Teams (S31)

Teams are sub-groups within an organization. They're the canonical way to grant repo access to a set of users without per-user collab rows. The S15 policy aggregator unions team-granted permissions with direct collaborator permissions and the org-owner implicit-admin rule.

Schema (migration 0035)

teams              — (org_id, slug, parent_team_id, privacy, …)
team_members       — (team_id, user_id, role enum('member','maintainer'))
team_repo_access   — (team_id, repo_id, role enum('read'..'admin'))

One-level nesting is structurally enforced by a BEFORE INSERT OR UPDATE trigger that checks the parent team's parent_team_id IS NULL. Two-level deep nesting raises SQLSTATE 23514, which the orchestrator translates to ErrTeamNestingTooDeep.

Permission resolution

The S15 policy contract gets one new source. For an org-owned repo, policy.effectiveRole returns:

max(
  org_role == owner   → admin,         (S30)
  direct collab role,                  (S15: repo_collaborators)
  team grant role over team-set,       (S31: team_repo_access)
)

Where the team-set for a user in an org is:

• every team they're a direct member of, plus
• the parent team of each (one hop, per nesting cap).

The aggregator resolves team-set + grants in two indexed queries (team_members JOIN teams + team_repo_access WHERE team_id = ANY(...)) and stores the winning role in the per-request policy.WithCache memo so subsequent Can() calls in the same request reuse it.

team_role = maintainer is about managing the team (adding members); it does not elevate repo perms beyond the team's team_repo_access.role. Confusion with the repo maintain role is flagged in the team-management UI.

Visibility

• privacy='visible': team metadata visible to all org members; basic info (name + description) visible to anyone who can see the org.
• privacy='secret': team metadata, members, and repo grants visible only to (team members ∪ org owners).

The list page filters secret teams the viewer can't see; the team view page 404s for the same reason. The markdown @org/team resolver must return ok=false for secret teams the viewer can't see — it falls back to plain text rather than leaking existence via a 404.

Cross-repo refs + mentions

• owner/repo#N: now dispatches via principals.Resolve so org-owned repos resolve. internal/issues/references.go was the S21 deferral; cleared this sprint.
• @org/team: a new alternation in internal/markdown/extensions/extensions.go::reCombined matches the slash form before the bare @user branch, so the trailing /team doesn't get split off. Routes to /{org}/teams/{team} via the Team resolver. S25 deferral cleared.

Routes

GET  /{org}/teams                         list (secret teams filtered)
POST /{org}/teams                         create  (owner-only)
GET  /{org}/teams/{slug}                  view: members + repo grants
POST /{org}/teams/{slug}/members          add (form + role) / remove (action=remove)
POST /{org}/teams/{slug}/repos            grant (repo_id + role) / revoke (action=remove)

What we deferred from the spec

• Set-parent UI: orchestrator (SetTeamParent) + the trigger validation are in place; the form to retarget a parent in the UI lands in a follow-up.
• Repo-settings team-grant UI: the team-side grant form on /{org}/teams/{slug} works today; mirroring it on /{owner}/{repo}/settings/access is S32 territory.
• Team rename + redirects: team_redirects table from the spec isn't shipped; defer to the same follow-up that does the username_redirects → principal_redirects rename.
• Notifications for "added to team" / "team granted access": routing matrix in S29 is wired for arbitrary kinds; emit-side hook lands when these surfaces next get touched.
• API endpoints GET /api/v1/orgs/{org}/teams etc.: same posture as S30 — defer to S33/S34 API consolidation.
• CODEOWNERS / SCIM team provisioning are post-MVP per spec.

Pitfalls noted in code

• Permission caching staleness: the per-request memo is invalidated by policy.InvalidateRepo; cross-request changes are picked up on the next request.
• Cycle prevention: parent_team_id != id row CHECK + the one-level trigger together prevent every cycle shape.
• Deleting the parent team flips children to top-level via ON DELETE SET NULL on parent_team_id (the spec's lean).
• Outside collaborator on a member's account: removing the user from the org clears team memberships but NOT direct collab rows — this matches GitHub. Implementation note: today the org member removal in orgs.RemoveMember doesn't delete team rows explicitly; the org_members row removal cascades through team_members only via shared users FK. Follow-up: when orgs.RemoveMember lands its policy-driven cleanup pass, it should also DELETE FROM team_members WHERE user_id = $1 AND team_id IN (SELECT id FROM teams WHERE org_id = $2). Tracked.
• Secret-team metadata leak via repo-settings page: the /{owner}/{repo}/settings/access extension ships in S32; the visibility filter must match the team-list page's logic.