Skip to content

Ticket #253: contract v7 terminal-turn workflow — verification ​

  • Date: 2026-11-12
  • Branch: ticket/253-agents-v7
  • Base: integration/native-ingestion-v7 at 9fc0fe8
  • 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-fake OpenAI-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 $Name is only a reference there;
  • ensemble_dispatch starts 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 $Name to 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 ​

BehaviorTest
v7 marker, native-first rules, terminal-turn workflow, root-only synthesis, dispatch continuation, worker routingsrc/v2/init-block.test.ts
Leader first and marked, memberIDs order, escaping, exact title/role, archived exclusionsrc/v2/init-block.test.ts
Same-version roster rewritesrc/v2/workspace-config.test.ts
Same-version contract-text rewrite and project-content preservationsrc/v2/workspace-config.test.ts
Prompt-size gate after the v7 contract growthsrc/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.

Released under the MIT License.