Skip to content

Ticket #73 verification — tailored handoff instructions, system ack, review framing — 2026-11-03 ​

Parent spec #66, child ticket #73 (handoff content: tailored recipient-facing instructions, concise system ack, review framing). Worktree: /tmp/opencode/ensemble-worktrees/55-73-handoff, branch feat/v55-73, base a15ff07 (= local integration/ensemble-v5.5 tip). Merged the moved tip twice before reporting: 640dc7e (ticket #72) as ee0225f, then 5e6207d (tip owner's #72 live determinism fix) as 8e263e7; reran check (exit 0) + test (361 passed) after each.

Environment ​

sh
export PATH=/home/tristan/.nvm/versions/node/v26.12.1/bin:/home/tristan/.local/bin

node --version: v26.12.1. The worktree ships no node_modules (gitignored); typechecking ran via the parent repo's node_modules/.bin/tsc symlinked into the worktree (removed before commit — git status clean). Unit tests need no installed deps (node --test --experimental-strip-types).

Command results ​

Exact commandResult
npm run check (tsc --noEmit)Exit 0.
npm testExit 0; 359 passed, 0 failed, 0 skipped (361 after merging the moved integration tip 640dc7e, which adds 2 ticket-#72 tests).
npm run test:live:fakeExit 0; fake live-check passed. History: pre-merge rerun green (first run hit the known transient link text rich-fixture timing flake, also recorded under #71); post-640dc7e-merge run red at the #67 bubble assert — proven a #72 tip regression via a clean-tip baseline run (same failure, scratch worktree removed), not #73; post-5e6207d-merge run green, including the new #73 asserts (concise handoff ack without policy text, no policy text in the transcript, both non-leader turns handed to the leader, ticket #71 completion handoff and batch review verified live).
npm run test:live:fake:emptyExit 0; fake empty-catalog live-check passed; no skips.
npm run test:liveExit 0; live-check passed; no skips.

Unit and live checks ran separately (unit first, then live); live results reported here, not folded into the unit count. No skips anywhere.

Reproduction evidence (red → green) ​

src/v2/handoff.test.ts was extended first against the old code and failed as required (completionReviewInstruction / handoffGroupAckText not exported). After the fix the same file passes: frontmatter parses instruction: distinct from the task title (legacy files without one still parse), distinct briefs hash to distinct idempotency keys (legacy key shape stable without one), the group ack is exactly Handed to $Name · <label> with no @Name, no handoff_ ref, no policy sentence, and the completion review instruction frames sender / title / outcome / path with Review and $Name/@file grammar.

src/v2/handoff-service.test.ts gained handoff carries a tailored instruction distinct from the user text: the hop's title stays the short label, its instruction carries the sender's self-authored brief (plus path ref) and tool-passed constraints/expected, the user's verbatim message never appears in it, a second hop with the same title but a distinct brief queues (not dedupes), and resubmission with the same brief still dedupes (Already handed). Red state was proven by the Cannot access 'path' before initialization failure the first implementation hit (declaration-order bug, fixed by moving hopInstruction below the relative() call) — the test caught it.

Behavior notes ​

  • Instruction contract: ensemble_handoff accepts optional instruction/constraints/expected (tool args are fallbacks; file frontmatter wins, matching task/summary). Resolution: file.instruction ?? tool.instruction ?? (summary ? task+\n\n+summary : task). Hop sets title = task, instruction = brief + (path); the recipient prompt (promptForTask) renders it verbatim. Legacy callers without an instruction keep the exact old brief.
  • Idempotency: handoffWorkKey now hashes recipient + task + instruction + constraints + expected (plus actor/workspace/run-prefix scope); the approval-path hop key includes the payload instruction too. Correlation still derives from the key.
  • Group ack: all four handoff ack sites (explicit hop, single completion, approved cross-boundary hop, batch-review follow-up) post author: "system", kind: "system" with Handed to $Name · <label> (label = summary || task for explicit hops, title otherwise). The policy sentence + (ref …) stays only in the explicit tool result for the calling model. Duplicate/failure legs unchanged.
  • Completion: single hops carry $Finisher finished "title" (@path?). Review the finished turn and decide what happens next:\n\n<content>; batch keeps its consolidated batchReviewText instruction. title stays the finished title.
  • Prompts/copy: ensemble_handoff tool description, identityForAgent, init-block.ts Handoffs section (frontmatter instruction:, ## Instruction, call signature, delegation framing), and AGENTS.md end-of-turn section all require a self-authored instruction, never a copy of the user's message, with task as the short display title and handoff-as-delegation (no delegate-after-handoff).
  • Compatibility: waiting semantics (#70), leader-only delegate rule, loop guards, approvals, $Name/!Name, @ file-only, and all live assertions preserved. Existing tests were updated intentionally, never silently weakened: relay/waiting/completion-batch/service tests now pin author === "system" + exact concise ack text + absence of policy/ref in the transcript, and the tool-result policy assertions stay.

Files changed ​

  • src/v2/handoff.ts — instruction?: on HandoffFileData, parser, key input, handoffGroupAckText, completionReviewInstruction.
  • src/v2/service.ts — tool schema + description, resolution, hop + approval payload, key call sites, four system ack posts, completion review brief, identity copy.
  • src/v2/init-block.ts, AGENTS.md — tailored-instruction contract.
  • Tests: handoff.test.ts (4 new), handoff-service.test.ts (1 new + relay ack rewrite), handoff-waiting.test.ts (+2 transcript asserts), completion-batch-service.test.ts (review framing + 3 ack asserts), service.test.ts (exact system ack).
  • scripts/live-check-fake.sh — ticket-#73 block: concise ack present, policy text absent.

Acceptance mapping ​

  • [x] Schema accepts a tailored instruction; recipient prompt uses it, short display title kept (handoff-service.test.ts tailored test).
  • [x] Leader/peer instruction distinct from user text; recipient never gets verbatim user words as its instruction (asserted negative).
  • [x] Group ack is a system line without policy text/ref; no agent-bubble leakage (unit + live fake asserts).
  • [x] Completion/batch instructions framed as review work (completion-handoff/completion-batch-service asserts).
  • [x] Prompts/AGENTS copy updated; existing handoff/batch/waiting tests and live scenarios green (359 unit + 3 live).
  • [x] check, test, three live scenarios; dated record (this file).

Uncertainty ​

  • No live macOS run; native permission round-trip covered by fake-ctx tests (fake provider emits text only).
  • Post-merge live:fake initially failed at the ticket-#67 bubble assert (user bubble not right-aligned): ticket #72's padded-bubble restyle broke the old {15,} space-run proxy deterministically. Proven not #73 (zero src/v2/tui/ diff vs the tip; a baseline run at 640dc7e without #73 fails identically; scratch worktree removed afterwards). The tip owner fixed the assert at the source in 5e6207d (column- position awk proxy); this branch merged it and reran green — no #73 drive-by to another ticket's assert was needed.
  • summary || task ack labels can be long when senders write long summaries; the contract keeps the sender's words out of the policy line but does not truncate. No truncation was added (minimal change).

Released under the MIT License.