# Code and Organization Workspace Contract

## Goal

Make AGS repository and organization pages truthful for people who are moving
their daily work from GitHub. The backend must never advertise a private
repository that the current principal cannot subsequently open. It must also
return the bounded metadata that a code browser and an organization workspace
need, without forcing gh-web to make one request per file or repository.

## Scope

This change provides four contracts.

1. **Discoverable repository scope.** Repository, Issue, pull-request,
   commit, and code search only return public repositories or repositories
   readable by the current principal. A direct request for an inaccessible
   private resource continues to return `404`, matching GitHub's
   non-disclosure behavior.
2. **Directory commit metadata.** `GET /api/v3/repos/{owner}/{repo}/contents`
   accepts `include=last_commit`. For a directory response only, every entry
   can include a `last_commit` object with its SHA, subject, and authored time.
   AGS resolves all visible entries in one Git history walk; it does not launch
   one `git log` process per row.
3. **Organization profile and policy updates.** Organization owners can
   `PATCH /api/v3/orgs/{org}` with display metadata and the default repository
   permission. Public organization reads continue to hide the contact email.
4. **Organization work.** Issue and pull-request search honors `org:` and a
   read-scoped extension endpoint lists workflow runs across the organization:
   `GET /api/ext/v1/orgs/{org}/actions/runs`.

`GET /api/v3/orgs/{org}/members?user_kind=human|agent` is added so the web UI
does not filter one page of a larger membership list and present it as an
organization-wide result.

## Discoverability Rules

For an HTTP request, a repository is discoverable when it is public, or the
authenticated user is its owner, site administrator, direct collaborator,
member of a team with a repository grant, or an organization member with a
non-`none` base permission. Internal service calls without an HTTP principal
retain their existing unrestricted behavior for jobs and tests.

The same predicate is injected into all search surfaces. This is important:
filtering only the frontend would still leak private names, titles, commit
messages, or workflow history through REST and GraphQL APIs.

## Directory Metadata Contract

The normal GitHub-compatible contents response is unchanged. With
`include=last_commit`, an entry may additionally contain:

```json
{
  "last_commit": {
    "sha": "abc123...",
    "message": "feat: add workspace",
    "authored_at": "2026-08-20T08:00:00Z"
  }
}
```

The field is absent when no history can be resolved. A transient history
lookup failure degrades to the normal directory list rather than making code
browsing unavailable. Directory paths are mapped from changed descendant
files, so a directory shows the latest commit that touched anything within it.

## Organization Update Contract

`PATCH /api/v3/orgs/{org}` is owner-only and accepts optional `name`,
`description`, `company`, `blog`, `location`, `email`, and
`default_repository_permission` fields. Omitted fields are unchanged and an
empty string clears an optional text field. The permission is normalized to
`none`, `read`, `write`, or `admin`; invalid values are rejected.

The write response is owner-private and includes the contact email. `GET`
responses remain public-safe.

## Non-goals

- This does not implement package hosting, a dependency/security alert
  aggregator, organization activity feeds, nested or secret teams, or pinned
  repository persistence. Each needs its own data model and API contract.
- This does not add Git blame or an unbounded repository history endpoint.
- Workflow runs are listed as historical AGS executions; this does not turn
  GitHub Actions YAML into a compatible CI runner.

## Verification

- Anonymous and unauthorized users cannot discover private repositories through
  repository, Issue, PR, commit, or code search; an owner, collaborator,
  eligible team member, and eligible organization member can.
- Directory metadata returns correct subject/time for files and directories,
  including a nested directory, in one batch call.
- Organization owners can update profile and policy fields; non-owners cannot;
  public reads do not expose email.
- Human/agent member filters page independently, and organization Work returns
  only runs from repositories the viewer may read.