Ticket #253: contract v7 terminal-turn workflow — verification
- Date: 2026-11-12
- Branch:
ticket/253-agents-v7 - Base:
integration/native-ingestion-v7at9fc0fe8 - Spec: parent #245; ticket #253
- ADRs: 0012
- Unit gate:
npm run verify(strict typecheck + full test suite) - Live gate:
npm run test:live:vera— seed 2/2, run 54/54, flows 45/45, restart 39/39, exit 0 - Host matrix: OpenCode 2.2.7, Node 26.12.1, npm 12.2.1, tmux 3.5a
- Provider: isolated local
ensemble-fakeOpenAI-compatible provider; no model API, external network request, or user credential
Contract v7
ENSEMBLE_BLOCK_VERSION = 7. The workspace AGENTS.md block keeps the v6 native-first rules and adds the terminal-turn workflow in plain language:
- one synthesis per command, written by the command root; intermediate hops relay their child's result and do not wake the leader;
- synthesis, completion-review, and batch-review turns are terminal, and
$Nameis only a reference there; ensemble_dispatchstarts the next ticket as a new command root with a fresh group and command budget; one terminal turn starts at most one new command, and a retry returns the existing command and assignments;- normal worker, handoff, and peer turns are not terminal and still route
$Nameto a different teammate.
The generated roster table and leader-first ordering are unchanged.
Repository AGENTS.md
The repository block is generated, not hand-edited. A one-off script imported ensembleBlock() and writeAgentsBlock() from the worktree, captured the project-owned content with stripEnsembleBlock(), wrote the v7 block, and verified the project-owned content was unchanged. The committed file carries exactly one <!-- ensemble:start v7 --> block at the top; the project-owned guidance follows it.
Content-aware reconciliation
reconcileEnsembleInstructions still compares the desired block text as well as the marker version. The existing roster-change test covers a same-version roster rewrite; a new same-version contract-text test changes a v7 rule without changing the roster or version and asserts the block is rewritten while the project content outside the markers is preserved. A newer recorded version is still never downgraded.
Tests
| Behavior | Test |
|---|---|
| v7 marker, native-first rules, terminal-turn workflow, root-only synthesis, dispatch continuation, worker routing | src/v2/init-block.test.ts |
Leader first and marked, memberIDs order, escaping, exact title/role, archived exclusion | src/v2/init-block.test.ts |
| Same-version roster rewrite | src/v2/workspace-config.test.ts |
| Same-version contract-text rewrite and project-content preservation | src/v2/workspace-config.test.ts |
| Prompt-size gate after the v7 contract growth | src/v2/prompt-benchmark.test.ts |
Vera regression
scripts/lib/vera-regression-driver.mjs and scripts/live-vera-regression.sh now pin <!-- ensemble:start v7 --> and the v7 block. The seed still writes a pre-v7 stale block plus project-owned content; the run phase asserts the reconciled v7 block, the exact generated roster table, and leader-first order. The restart phase asserts one v7 block remains. The ticket #251 relay, fan-out, multi-ticket, refusal, and worker-route assertions are unchanged.
Measurements
The generic v7 block is 5,413 chars / 1,354 estimated tokens (chars/4); the v6 block it replaces was 4,548 / 1,137. The generated identity prompt is 5,965 chars / 1,492 tokens, still under the 6,200-char compactness gate. Total prompt size is 8,869 chars / 2,218 tokens versus the 3,347-token legacy baseline, a 33.7% reduction. The v7 contract adds 865 generic chars (~216 tokens) over v6, so the old 40% total-prompt gate is not reachable without deleting the terminal-turn rules; 33% is the recorded product floor with the measured 0.7pp margin. Because that margin is too tight to be the only guard, the test also ratchets the released v7 identity, turn-context, and total-prompt sizes (5,965 / 2,904 / 8,869 chars) with a 2% tolerance, and a unit test proves 500 chars of contract growth fails it. The native surface remains well below the legacy prompt and the tool-schema gate is unchanged.
The fixed 12-member filled v7 block is 6,532 chars / 1,633 estimated tokens: the #238 v6 measurement (5,667 / 1,417) plus the 865-char v7 contract delta. The Vera driver records the delta against that constant.
Privacy
The record contains fixture names, stored roster titles/roles, counts, lengths, versions, and token estimates only. It contains no prompt or answer text, conversation transcript, credentials, file bytes, or absolute private paths.
Conflict risk
- #231 native ingestion refactor: this ticket touches only the contract text, block version, tests, docs, and the Vera driver. It does not change the service maps, native queues, reconciliation, or turn state.
- #245/#251 terminal turns: the block and docs describe the delivered behavior; no runtime behavior changes.
- Live harness: the only driver changes are the v7 marker, v7 block label, and current block-version metric. The roster table, task graph, and budget assertions are unchanged.