Teams drive the crew: a membership carries a role, and a repository's crew is the members of the teams that can write it #10088

A team membership now carries a role, and on an org's repository the crew comes from the org's teams. Where no team gives an agent a role, the repository keeps its own roster unchanged.

What changed

• Migration 20261109130000-team-member-role (pinned) adds team_member.role: planner | builder | reviewer | member. It defaults to member and the column refuses any other value. It is one additive column, run once like every migration.
• crewSeats(db, repoIds) in src/core/agents.ts is now the one function the routing reads. For an org-owned repository, the crew is the agents the org's write and admin teams give a named role, each in that role. If a team gives an agent a role it doesn't declare, it sits in its first declared role. A repository can narrow what an agent declares but never widen it. When no team gives any agent a role, the crew is the repository's repo_crew roster, read exactly as before. listCrewRoles, crewWithRole (and so reviewersOf/pickReviewer) and reposWithBuilder all read it. All repositories are read in batches, not one query per repository.
• One decision to check: member holds no crew seat; it gives the team's access only. Every existing membership becomes member, so routing on every repository is unchanged on deploy, including juniper and sentinel. A team only takes over a repository's crew once someone gives an agent a role.
• API: POST /api/v1/orgs/:org/teams/:team/members accepts an optional role and refuses a bad one with 422 bad_role. Posting someone already on the team with a role sets their role, and the answer is { added, role }. DELETE …/members/:username?role=reviewer takes just that role off and leaves them on the team as member (404 if they don't hold it, 422 for a bad role). Without role, DELETE removes the member as before. GET …/members now includes each member's role.
• Org page: each team row lists its members with their roles, server-rendered and escaped ("2 members: juniper, reviewer; mason, builder"). The team's Manage page shows each member's role and adds a Role select to "Add member".
• docs/ARCHITECTURE.md has a paragraph on where the crew comes from.

Not done

• isCrew, listCrew and crewForRepos (permissions and plain name lists) still read the roster only. A team's own permission already covers access.
• MCP org_teams and the terminal's team screen don't take a role yet.

Tests

• test/teams-crew.test.ts (8 tests, all passing) covers:

- the migration's default and its refusal of other values - the roster still answering when no team gives an agent a role, on org and personal repositories - a write team with a reviewer: the routing picks that reviewer - a write team without one: no reviewer, and no fallback to the roster's - an org whose write teams hold only plain members keeping its roster - the API taking, checking and removing a role - the escaped roles on the org page

• One existing test changed because it was out of date, not because the code was wrong: test/actions.test.ts:284 expected the add answer to be exactly { added: true }, and it now also carries role: "member".
• bun scripts/gate.ts, bun x tsc --noEmit and bun scripts/design-lint.ts pass. So do the tests covering orgs, reviews, crew routing, parity, MCP, the terminal and migrations (about 320 tests, no failures). scripts/fast.ts said the change was too broad to pick tests, so I chose these files myself.
• The issue asks for a short plan kept with a keep_plan tool; that tool wasn't available in this run, so no plan was posted on the issue.

Try it on the preview: add an agent to a write team with {"user":"<agent>","role":"reviewer"} through the members API, or the Role select on the team's Manage page. Then open /<org>: the team row reads "<agent>, reviewer", and that agent reviews the org's pulls.

🤖 Generated with Claude Code

Closes #571

A team membership now carries a role, and on an org's repository the crew comes from the org's teams. Where no team gives an agent a role, the repository keeps its own roster unchanged.

What changed

• Migration 20261109130000-team-member-role (pinned) adds team_member.role: planner | builder | reviewer | member. It defaults to member and the column refuses any other value. It is one additive column, run once like every migration.
• crewSeats(db, repoIds) in src/core/agents.ts is now the one function the routing reads. For an org-owned repository, the crew is the agents the org's write and admin teams give a named role, each in that role. If a team gives an agent a role it doesn't declare, it sits in its first declared role. A repository can narrow what an agent declares but never widen it. When no team gives any agent a role, the crew is the repository's repo_crew roster, read exactly as before. listCrewRoles, crewWithRole (and so reviewersOf/pickReviewer) and reposWithBuilder all read it. All repositories are read in batches, not one query per repository.
• One decision to check: member holds no crew seat; it gives the team's access only. Every existing membership becomes member, so routing on every repository is unchanged on deploy, including juniper and sentinel. A team only takes over a repository's crew once someone gives an agent a role.
• API: POST /api/v1/orgs/:org/teams/:team/members accepts an optional role and refuses a bad one with 422 bad_role. Posting someone already on the team with a role sets their role, and the answer is { added, role }. DELETE …/members/:username?role=reviewer takes just that role off and leaves them on the team as member (404 if they don't hold it, 422 for a bad role). Without role, DELETE removes the member as before. GET …/members now includes each member's role.
• Org page: each team row lists its members with their roles, server-rendered and escaped ("2 members: juniper, reviewer; mason, builder"). The team's Manage page shows each member's role and adds a Role select to "Add member".
• docs/ARCHITECTURE.md has a paragraph on where the crew comes from.

Not done

• isCrew, listCrew and crewForRepos (permissions and plain name lists) still read the roster only. A team's own permission already covers access.
• MCP org_teams and the terminal's team screen don't take a role yet.

Tests

• test/teams-crew.test.ts (8 tests, all passing) covers:

- the migration's default and its refusal of other values - the roster still answering when no team gives an agent a role, on org and personal repositories - a write team with a reviewer: the routing picks that reviewer - a write team without one: no reviewer, and no fallback to the roster's - an org whose write teams hold only plain members keeping its roster - the API taking, checking and removing a role - the escaped roles on the org page

• One existing test changed because it was out of date, not because the code was wrong: test/actions.test.ts:284 expected the add answer to be exactly { added: true }, and it now also carries role: "member".
• bun scripts/gate.ts, bun x tsc --noEmit and bun scripts/design-lint.ts pass. So do the tests covering orgs, reviews, crew routing, parity, MCP, the terminal and migrations (about 320 tests, no failures). scripts/fast.ts said the change was too broad to pick tests, so I chose these files myself.
• The issue asks for a short plan kept with a keep_plan tool; that tool wasn't available in this run, so no plan was posted on the issue.

Try it on the preview: add an agent to a write team with {"user":"<agent>","role":"reviewer"} through the members API, or the Role select on the team's Manage page. Then open /<org>: the team row reads "<agent>, reviewer", and that agent reviews the org's pulls.

🤖 Generated with Claude Code

A team membership now carries a role, and on an org's repository the crew comes from the org's teams. Where no team gives an agent a role, the repository keeps its own roster unchanged.

What changed

• Migration 20261109130000-team-member-role (pinned) adds team_member.role: planner | builder | reviewer | member. It defaults to member and the column refuses any other value. It is one additive column, run once like every migration.
• crewSeats(db, repoIds) in src/core/agents.ts is now the one function the routing reads. For an org-owned repository, the crew is the agents the org's write and admin teams give a named role, each in that role. If a team gives an agent a role it doesn't declare, it sits in its first declared role. A repository can narrow what an agent declares but never widen it. When no team gives any agent a role, the crew is the repository's repo_crew roster, read exactly as before. listCrewRoles, crewWithRole (and so reviewersOf/pickReviewer) and reposWithBuilder all read it. It is one UNION ALL query per chunk of 400 repositories, covering both team seats and the roster, never one query per repository.
• One decision to check: member holds no crew seat; it gives the team's access only. Every existing membership becomes member, so routing on every repository is unchanged on deploy, including juniper and sentinel. A team only takes over a repository's crew once someone gives an agent a role.
• API: POST /api/v1/orgs/:org/teams/:team/members accepts an optional role and refuses a bad one with 422 bad_role. Posting someone already on the team with a role sets their role, and the answer is { added, role }. DELETE …/members/:username?role=reviewer takes just that role off and leaves them on the team as member (404 if they don't hold it, 422 for a bad role). Without role, DELETE removes the member as before. GET …/members now includes each member's role.
• Org page: each team row lists its members with their roles, server-rendered and escaped ("2 members: juniper, reviewer; mason, builder"). The team's Manage page shows each member's role and adds a Role select to "Add member".
• docs/ARCHITECTURE.md has a paragraph on where the crew comes from.

Not done

• isCrew, listCrew and crewForRepos (permissions and plain name lists) still read the roster only. A team's own permission already covers access.
• MCP org_teams and the terminal's team screen don't take a role yet.

Tests

• test/teams-crew.test.ts (8 tests, all passing) covers:

- the migration's default and its refusal of other values - the roster still answering when no team gives an agent a role, on org and personal repositories - a write team with a reviewer: the routing picks that reviewer - a write team without one: no reviewer, and no fallback to the roster's - an org whose write teams hold only plain members keeping its roster - the API taking, checking and removing a role - the escaped roles on the org page

• Two existing tests changed because they were out of date, not because the code was wrong:

- test/actions.test.ts:284 expected the add answer to be exactly { added: true }; it now also carries role: "member". - test/asks-counts.test.ts:259 found the reviewer read by its old SQL text, so it now matches the new query. It still checks the same thing: one request reads the reviewers once.

• Earlier failure: the previous push's check failed that asks-counts test, while the preview itself was serving fine. The home page read the reviewers in two queries, team and then roster. That is now one query, and the test passes.
• bun scripts/gate.ts and bun x tsc --noEmit pass, and bun scripts/design-lint.ts passed on the previous push. So do the tests covering asks, shelf, home, query counts, orgs, reviews, crew routing, parity, MCP, the terminal and migrations (about 800 tests across both pushes, no failures). scripts/fast.ts said the change was too broad to pick tests, so I chose these files myself.
• The issue asks for a short plan kept with a keep_plan tool; that tool wasn't available in this run, so no plan was posted on the issue.

Try it on the preview: add an agent to a write team with {"user":"<agent>","role":"reviewer"} through the members API, or the Role select on the team's Manage page. Then open /<org>: the team row reads "<agent>, reviewer", and that agent reviews the org's pulls.

🤖 Generated with Claude Code

A team membership now carries a role, and on an org's repository the crew comes from the org's teams. The role can be set from the page, the API, MCP and the terminal, and every change is recorded on the outbox. Where no team gives an agent a role, the repository keeps its own roster unchanged.

What changed

• Migration 20261109130000-team-member-role (pinned) adds team_member.role: planner | builder | reviewer | member. It defaults to member, and the column refuses any other value. It is one additive column.
• crewSeats(db, repoIds) in src/core/agents.ts is the one function the routing reads. For an org-owned repository, the crew is the agents the org's write and admin teams give a named role, each in that role. When no team gives any agent a role, the crew is the repository's repo_crew roster, read as before. listCrewRoles, crewWithRole (and so reviewersOf/pickReviewer) and reposWithBuilder all read it. It is one UNION ALL query per chunk of repositories.
• One decision to check: member holds no crew seat; it gives the team's access only. Every existing membership becomes member, so nothing reroutes on deploy, including juniper and sentinel. A team only takes over a repository's crew once someone gives an agent a role.
• Outbox: every role change appends team.member_role_set with who made it, the member, and the role before and after. That covers adding someone already on the team with a new role, and DELETE ?role=. It is classified for the same readers as team.member_added.
• API: POST /api/v1/orgs/:org/teams/:team/members takes an optional role and refuses a bad one with 422 bad_role. DELETE …/members/:username?role=X takes only that role off and leaves them a member. GET …/members lists each member's role.
• MCP: org_teams add_member takes a validated role. A new action, members, lists a team's members with their roles, for org admins only, the same gate as the page.
• Terminal: the team screen shows each member's role, and an org admin presses r on a member to pick one. It goes through the same addTeamMember action as the page.
• Org page: each team row shows "N members" plus a <dl> (the existing row facts component) pairing each name with its role. The Role hint on the team's Manage page is one sentence: "An agent's role is its seat on the org's repositories."
• Cleanup: removeTeamMember's role path is now plain statements, teamRoleOf has no nested ternary, and the long lines are wrapped.
• Docs: docs/features/team-roles.md covers the page, API, MCP and terminal, and docs/ARCHITECTURE.md says where the crew comes from.

Where I differ from the review: a role set in the terminal is not pushed live to web pages that are already open. A reload shows it, and the test checks that the next page request has the new role. The web's live stream is per repository, and team events carry no repository, so no org page is live today, not even for adding or removing a member. Pushing org events to open pages needs an org-level stream with its own access rule. That deserves its own issue rather than a corner of this pull.

Not done: isCrew, listCrew and crewForRepos (permissions and plain name lists) still read the roster only. A team's own permission already covers access.

Tests

• test/teams-crew.test.ts (11 tests, all passing) covers:

- the migration's default and its refusal of other values - the roster still answering when no team gives an agent a role - a write team with a reviewer, and one without - plain members holding no seat - the API taking, refusing and removing a role - the role-change event, including that no-op and refused changes record nothing - MCP adding with a role, refusing a bad one, listing, and hiding the team from non-admins - a terminal r change showing on the org page - the escaped <dl> on the page

• Two existing tests changed because they were out of date, not because the code was wrong:

- test/actions.test.ts:284 expected the add answer to be exactly { added: true }; it now also carries role: "member". - test/asks-counts.test.ts:259 found the reviewer read by its old SQL text, so it now matches the new query. It still checks that one request reads the reviewers once.

• bun scripts/gate.ts, bun x tsc --noEmit and bun scripts/design-lint.ts pass. So do the tests for the terminal, MCP, parity, orgs, asks, event audience and tool docs that cover this change (715 tests, no failures). scripts/fast.ts said the change was too broad to pick tests, so I chose these files myself.

Try it on the preview: open /<org>, choose Manage on a write team, pick Role "reviewer" beside an agent's username and press Add member. The team row then shows that agent with "reviewer", and that agent reviews the org's pulls.

🤖 Generated with Claude Code