Ticket #238: contract v6 and team roster — verification
- Date: 2026-11-11
- Branch:
ticket/238-agents-roster - Base:
integration/native-first-defaultsat53c5aac - Spec: parent #235; ticket #238
- ADRs: 0011 (contract v6 and roster), 0004
- Unit gate:
npm run verify(strict typecheck + full test suite)
Contract v6
ENSEMBLE_BLOCK_VERSION = 6. The workspace AGENTS.md block now states the native-first rules:
- the final native text is the group message;
$Nameroutes work, a bare name is only a reference, and@pathis file-only;- code spans, URLs, and paths never route;
- direct conversations are one-to-one;
- the server owns routing, budgets, and completion;
- do not claim a teammate replied until their turn is visible, and do not open a second completion loop for a teammate you asked;
- explicit
ensemble_delegateandensemble_handoffare migration and rollback tools, not the normal chat path.
The old “every non-leader turn ends with a handoff” rule is removed. The repository handoff contract and root agent instructions were updated to match.
Roster table
The block carries one generated Team roster table:
| Member | Title | Role |
|---|---|---|
| Ada (leader) | Lead Engineer | Own architecture and release. |
| Bo | Researcher | Own evidence. |
| Cy | Analyst | Own metrics. |
- Active members only; archived members are excluded.
- The leader is first and marked
**Name** (leader). - Remaining members follow
memberIDsorder. TitleandRoleare the stored strings exactly as authored.- Only table syntax is escaped:
|becomes\|and a newline becomes<br>. No other rewriting, truncation, or summarization. - The generic identity block and every
ensemble_turnblock stay unchanged; the table is written once to the workspace file, not per turn. - Rows contain names, titles, and roles only: no credentials, conversation content, or private paths.
Refresh and reconciliation
reconcileEnsembleInstructions compares the desired block text as well as the version marker, so a roster change rewrites the block at the same version. Project-owned content outside the Ensemble markers is preserved, and a newer recorded version is never downgraded. Refresh triggers:
| Change | Service path |
|---|---|
| Workspace membership or leader | workspace.update and config/discovery reconciliation |
| Workspace creation | workspace.create and discovery |
| Agent name, title, or role | agent.update |
| Agent archive | agent.archive |
| Agent delete | agent.delete |
| Version or content drift | Maintenance and start reconciliation |
Prompt delta
Fixed 12-member fixture, chars/4 estimate. “Filled” gives every member a one-line title and one-line role.
| Measurement | Chars | Est. tokens | Delta vs v5 |
|---|---|---|---|
| v5 block | 4,248 | 1,062 | — |
| v6 generic text (no roster) | 4,058 | 1,015 | −190 chars / −47 tokens |
| v6 + empty 12-member table | 4,373 | 1,094 | +125 chars / +31 tokens |
| v6 + filled 12-member table | 5,667 | 1,417 | +1,419 chars / +355 tokens |
Per-turn ensemble_turn context | 2,904 | 726 | 0 (unchanged by v6) |
The generated table is 231 chars when empty and 1,525 chars when filled.
Tests
| Behavior | Test |
|---|---|
| v6 rules, retired handoff rule, generic block has no table | src/v2/init-block.test.ts |
Leader first and marked, memberIDs order, escaping, exact title/role, archived exclusion | src/v2/init-block.test.ts |
| Content-aware reconciliation, preservation outside the markers, stability, newer version guard | src/v2/workspace-config.test.ts |
| Membership and leader refresh, agent name/title/role refresh, archive/delete removal, project content preserved | src/v2/service.test.ts |
| Table stays out of the per-turn context | existing src/v2/turn-context.test.ts, src/v2/prompt-benchmark.test.ts |