Skip to content

Ticket #238: contract v6 and team roster — verification ​

  • Date: 2026-11-11
  • Branch: ticket/238-agents-roster
  • Base: integration/native-first-defaults at 53c5aac
  • 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;
  • $Name routes work, a bare name is only a reference, and @path is 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_delegate and ensemble_handoff are 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:

MemberTitleRole
Ada (leader)Lead EngineerOwn architecture and release.
BoResearcherOwn evidence.
CyAnalystOwn metrics.
  • Active members only; archived members are excluded.
  • The leader is first and marked **Name** (leader).
  • Remaining members follow memberIDs order.
  • Title and Role are 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_turn block 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:

ChangeService path
Workspace membership or leaderworkspace.update and config/discovery reconciliation
Workspace creationworkspace.create and discovery
Agent name, title, or roleagent.update
Agent archiveagent.archive
Agent deleteagent.delete
Version or content driftMaintenance and start reconciliation

Prompt delta ​

Fixed 12-member fixture, chars/4 estimate. “Filled” gives every member a one-line title and one-line role.

MeasurementCharsEst. tokensDelta vs v5
v5 block4,2481,062—
v6 generic text (no roster)4,0581,015−190 chars / −47 tokens
v6 + empty 12-member table4,3731,094+125 chars / +31 tokens
v6 + filled 12-member table5,6671,417+1,419 chars / +355 tokens
Per-turn ensemble_turn context2,9047260 (unchanged by v6)

The generated table is 231 chars when empty and 1,525 chars when filled.

Tests ​

BehaviorTest
v6 rules, retired handoff rule, generic block has no tablesrc/v2/init-block.test.ts
Leader first and marked, memberIDs order, escaping, exact title/role, archived exclusionsrc/v2/init-block.test.ts
Content-aware reconciliation, preservation outside the markers, stability, newer version guardsrc/v2/workspace-config.test.ts
Membership and leader refresh, agent name/title/role refresh, archive/delete removal, project content preservedsrc/v2/service.test.ts
Table stays out of the per-turn contextexisting src/v2/turn-context.test.ts, src/v2/prompt-benchmark.test.ts

Released under the MIT License.