[mfittko]

Closes #2955

Summary

A healthy coordinator now continues across phase transitions. The 150K peak-context figure is an advisory retrospective diagnostic, not a cap.

• unitBoundaries.handBackAfter is renamed reportAfter (same derivation, ordering and validation, same resume). At a report point the coordinator records status through existing evidence, re-resolves authoritative state and continues.
• A coordinator ends its run only at the run-ending cases in the canonical list in skills/docs/main-agent-contract.md (Unit coordinator boundaries). An issue-to-PR re-target caused by its own draft PR is a continuation.
• New rule COORDINATOR-CONTINUITY-SOFT-CAP in skills/docs/main-agent-contract.md (registered in required-rules.json). Crossing 150K never stops, relaunches or blocks gates, completion or merge. Reviewer/judge isolation stays fresh.
• Retrospective contract gains a coordinator context and traffic report: peak, input/cached/output traffic, launches and reasons, avoidable repeated work. Unavailable values are "unknown", never zero. Context size, token traffic and billing are kept separate.
• New ADR 0220 records the decision; ADR 0181 and ADR 0187 carry Status-only notes (superseded in part, amended). The one-report rule no longer says hand back at the first boundary. .claude mirrors regenerated.

Original repro

A coordinator was forced to hand back at a phase boundary (draft PR opened, gate verdict posted) or at the 150K cap, producing repeated bootstraps and replacement work (PR 2948 retrospective).

Regression evidence

Confirmed by a worker against a clean origin/main checkout (76cd5e5) with only the test files from this branch: the 2955: tests present when checked (7 then; later fixer passes only added or renamed tests) and the 3 changed older tests in unit-coordinator-handback-contract.test.mjs fail pre-fix, the one-report rule test fails pre-fix, and all 7 unitBoundaries: tests in handoff-envelope.test.mjs fail pre-fix. coordinator-work-order.test.mjs is unchanged and proves nothing about regression.

test/contracts/unit-coordinator-handback-contract.test.mjs has 14 top-level tests at the PR head, 10 of them new 2955: tests. No fresh run against origin/main was made for these counts, so no failure count is stated. They pin the reportAfter emission, the absence of "fresh unit coordinator per phase", "150K-token cap" and handBackAfter text, the advisory and unknown-not-zero text, mirror coverage and the retained reviewer/judge fresh-dispatch text.

AC2 note: no runtime code reads peak context, so AC2 is met by contract prose plus doc tests, not a behavioural fixture. The replacement reason is read from the predecessor's compact hand-back packet status, which names the run-ending case, reported as unknown when absent; no second telemetry store was added.

Size: 63 weighted logic LOC (budget 400). No scope split.

Follow-ups for the operator

• Epic Epic: Gate review token efficiency and coordinator context bounding #2268: the orchestrator already edited its policy row (superseded by issue 2955 and this PR); nothing deferred here.
• AC5 (representative supported-harness trace) is evidenced by this run's own coordinator, which continued across the draft PR and verdict boundaries.

Overlap

File-disjoint from PR 3003 (issue 2898) and issue 2884 as far as known; no shared files touched beyond the contract docs listed above.

Objective

Remove mandatory fresh-coordinator replacement and the hard 150K cap (issue 2955 spec of record below).

In scope

• Retain the current functioning coordinator across ordinary phase transitions, including draft PR creation and posted gate verdicts. A boundary may still delimit work, resolve current authoritative state, or report to the orchestrator; it must not require a fresh coordinator solely for context management.
• Treat 150K as a soft diagnostic threshold. Crossing it neither terminates/relaunches a coordinator nor blocks gates, completion or merge, and staying below it is not an acceptance prerequisite.
• Preserve fresh dispatch when independently required for reviewer/judge isolation or genuine recovery, unavailable actors, runtime constraints or explicit operator direction. Independent reviewers and judges remain independent; this issue concerns lifecycle coordinator continuity.
• Preserve orchestrator-owned operations, worker mutation boundaries, authoritative startup/resume and gate-state recovery, active joins, stop rules, permission boundaries and harness-specific safety behavior.
• Retrospectives report coordinator peak context, total input/cached input/output traffic when available, coordinator launches and their reasons, and avoidable repeated reads/bootstrap/review work. Unavailable measurements remain unknown. Distinguish context size, repeated token traffic and account allowance/billing.
• Reconcile canonical role/contract prose, emitted unit-boundary/handoff behavior and affected tests so no remaining mandatory fresh-per-phase rule or hard 150K criterion contradicts the new policy. Update the relevant efficiency epic's active policy references; preserve historical measurements. Follow the existing decision-record process if an ADR must be amended. Deferred to Epic: Gate review token efficiency and coordinator context bounding #2268 (follow-up, operator-owned): the epic active-policy edit is not delivered by this PR. (Epic edit: already done by the orchestrator, see Follow-ups.)

Known entry points: skills/docs/main-agent-contract.md (unit coordinator boundaries and budget), agents/dev-loop.agent.md, skills/docs/workflow-handoff-contract.md, and the existing handoff/startup producers identified by #2532. Verify callers and consumers before implementation; do not assume this is prose-only.

Acceptance criteria

• A functioning coordinator can continue after draft PR creation and draft/pre-approval verdict boundaries without mandatory fresh-coordinator replacement. Targeted fixtures cover those transitions and preserve authoritative gate evidence and state.
• A reported peak above 150K produces advisory retrospective information only; fixtures demonstrate no threshold-caused stop, relaunch or lifecycle failure. Unknown telemetry does not become a fabricated zero or a new blocker.
• Independent reviewer/judge dispatch and genuine recovery paths remain intact. The reason for a coordinator replacement is observable using existing records, without introducing a second telemetry store.
• Canonical docs, emitted instructions and affected tests agree on the soft limit and coordinator continuity; no hard peak-cap proof is required to accept this change.
• A representative supported-harness trace demonstrates continuity and reports available peak/total usage and dispatch reasons. Comparisons separate coordinator overhead from worker/reviewer cost; no fixed savings percentage or billing inference is required.
• Targeted cross-harness regression coverage preserves Codex, Claude Code and Pi behavior, required review angles, required reads, fail-closed evidence checks and human authority. Canonical validation passes at the PR head.

Definition of done

• Tests, docs, mirrors and ADR note per the AC / DoD matrix below.
• Canonical validation green at the PR head (CI).

Non-goals

Implementing this issue as part of filing; removing independent reviews; skipping gates or validation; forcing a coordinator to survive a genuine denial/runtime failure; exceeding the model's actual context window; changing model pricing; introducing a telemetry platform; claiming all observed token traffic was avoidable. Existing #2952 dispatch-authority and #2476 same-head review-reuse work retain their own scopes.

Milestone: v1.1.0. This is an efficiency/policy improvement, not a v1.0.8 release blocker.

AC / DoD matrix

Added 2026-11-01 by the orchestrator so the gate can verify the criteria above. The criteria text is unchanged.

Acceptance criterion	Required completion evidence
AC1. A functioning coordinator continues across draft PR creation and draft/pre-approval verdict boundaries without mandatory replacement.	Targeted fixtures for the draft-PR-created boundary and each verdict boundary show the emitted unit boundaries no longer require a fresh coordinator for context management, and authoritative gate evidence and state are preserved across the transition.
AC2. A peak above 150K is advisory only.	A fixture with a reported peak above 150K shows no stop, relaunch or lifecycle failure. A fixture with unknown telemetry shows it is reported as unknown, not zero and not a blocker.
AC3. Independent reviewer/judge dispatch and genuine recovery paths remain.	Existing reviewer/judge isolation and recovery tests pass unchanged. A coordinator replacement records its reason in the existing records, with no second telemetry store.
AC4. Docs, emitted instructions and tests agree on the soft limit.	main-agent-contract.md (Unit coordinator boundaries and the Budget paragraph), agents/dev-loop.agent.md (context budget), the emitted unitBoundaries and the .claude mirror are changed and consistent; test:docs and asset checks pass. No hard peak-cap proof is required.
AC5. A representative trace shows continuity and usage.	The PR body records one supported-harness trace with available peak and total usage and dispatch reasons, separating coordinator overhead from worker and reviewer cost, with no savings percentage claimed.
AC6. Cross-harness non-regression and canonical validation.	Targeted regression coverage for Codex, Claude Code and Pi (required angles, required reads, fail-closed evidence checks, human authority) passes, and canonical validation passes at the PR head.

Validation

• Commands: bun test test/contracts packages/core/test/handoff-envelope.test.mjs packages/core/test/coordinator-work-order.test.mjs, bun scripts/docs/validate-decision-records.mjs, bun scripts/docs/validate-links.mjs, node scripts/claude/generate-claude-assets.mjs --check, dev-loops-run scripts/loop/check-size-budget.mjs --base origin/main.
• CI (verify-suite) is the authority for the PR head; see the PR checks.

AC5 representative trace (Claude Code)

One dev-loop coordinator ran issue 2955 from loop startup through worktree, implementation, the pre-PR review, draft PR 3004 and the draft_gate verdict without replacement. It crossed both report points (draft PR opened, gate verdict posted) and continued. Dispatch reasons: developer x3 (implementation, review fixes, ADR fix), review x1 (fresh pre-PR review, independence), gate-coordinator x1 (round isolation), judge/reviewers inside the round (independence), fixer x1 (act list). Peak and total coordinator traffic are unknown: the harness exposes no per-coordinator usage to the coordinator, so they are reported as unknown, not zero. Coordinator overhead is separate from worker and reviewer cost.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R7yetT95WedZayUQMysoHv

[mfittko]

Gate review: draft_gate

Reviewed head SHA: a4a2576b6752403e4cfb49e5263ea0bda3af126f
Verdict: findings_present

Findings summary: Round 4: 0 high, 1 medium, 1 nit; judge within_scope: act 1 (AC3 replacement-reason record), reject 1

Inline findings: 1 (🟠 1 medium) — on the diff, see Files changed. Angles: contract-surface.

Details

Rejected (1)

• packages/core/test/handoff-envelope.test.mjs:1123 nit (holistic): The comment in the renamed test 'both gate verdict boundaries carry the same report point and resume target' still says 'Draft and pre-approval rounds are separate units; each resumes from the same authoritative PR target, so neither reads the other's conversation.' Under the amended contract one coordinator continues across both verdict report points, so the rounds are no longer separate units. The comment states the removed per-phase policy as a current invariant. — judge: reject - low_fix_until_cap (GATE-EXEC-LOW-FIX-UNTIL-CAP)

Next action: stay draft and fix

[Copilot]

🟡 Changes recommended

The coordinator’s continuation instructions conflict with its envelope authority rules, leaving no clearly defined and tested handoff refresh that preserves the dispatched file and permission scope.

1 open issue

• Pull coordinator cannot adopt refreshed handoff within envelope authority · New

What changed in this PR

This PR updates dev-loop coordinator policy for #2955: healthy coordinators continue across phase transitions, while the 150K peak-context threshold becomes advisory rather than a mandatory stopping point.

Changes:

• Renames unitBoundaries.handBackAfter to reportAfter, retaining boundary derivation, ordering and validation.
• Defines coordinator continuity, run-ending cases and retrospective usage reporting.
• Updates contract tests, decision records and generated Claude documentation.

File	Description
test/​contracts/​unit-coordinator-handback-contract.test.mjs	Adds continuity, advisory-threshold and mirrored-policy checks.
test/​contracts/​coordinator-handback-one-report-contract.test.mjs	Aligns final-report assertions with canonical run-ending cases.
skills/​docs/​workflow-handoff-contract.md	Documents report points and the renamed envelope field.
skills/​docs/​retrospective-checkpoint-contract.md	Adds coordinator context, traffic and launch-reason reporting.
skills/​docs/​required-rules.json	Registers the continuity and soft-cap rule.
skills/​docs/​main-agent-contract.md	Replaces forced hand-backs and the hard cap with continuity policy.
packages/​core/​test/​handoff-envelope.test.mjs	Updates boundary and validation tests for reportAfter.
packages/​core/​src/​loop/​handoff-envelope.mjs	Renames the emitted and validated boundary field.
docs/​decisions/​0220-coordinator-report-points-replace-per-phase-handback.md	Records the coordinator-continuity decision.
docs/​decisions/​0187-claude-code-coordinator-report-path.md	Adds a status note linking the final-report amendment.
docs/​decisions/​0181-unit-coordinator-handback-boundaries.md	Adds a status note marking partial supersession.
changes/​2955-coordinator-continuity.md	Summarizes the behavior change for release notes.
agents/​dev-loop.agent.md	Updates coordinator instructions for reporting and continuation.
.claude/​skills/​docs/​workflow-handoff-contract.md	Mirrors the updated handoff contract.
.claude/​skills/​docs/​retrospective-checkpoint-contract.md	Mirrors coordinator usage-reporting requirements.
.claude/​skills/​docs/​main-agent-contract.md	Mirrors continuity and advisory-threshold policy.
.claude/​agents/​dev-loop.md	Mirrors the revised coordinator instructions.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are reported for the coordinator continuity and report-point changes.

No open issues 🎉

1 resolved since last review

• Pull coordinator cannot adopt refreshed handoff within envelope authority

_{Review effort: Balanced}

[mfittko]

Gate review: pre_approval_gate

Reviewed head SHA: bf424c63141b8376a84e99ea0257d4beedca68f1
Verdict: clean
Size-budget outcome: pass
Size-budget T1 slice: not touched
Size-budget waiver: none

Findings summary: Round 2 clean: empty act list; 4 low/nit findings deferred or rejected (PR body edits applied, resume wording low)

Details

Deferred (4)

• low (contradiction-lens): The PR body contradicts itself on the epic 2268 policy edit. The In scope section says 'Deferred to 2268 (follow-up, operator-owned): the epic active-policy edit is not delivered by this PR.' The Follow-ups for the operator section says 'Epic 2268: the orchestrator already edited its policy row (superseded by issue 2955 and this PR); nothing deferred here.' One of the two statements is false, so a reader cannot tell whether the in-scope epic update is delivered. — judge: defer (follow-up 2955) - low_fix_until_cap (GATE-EXEC-LOW-FIX-UNTIL-CAP)

• skills/docs/workflow-handoff-contract.md:100 low (docs): The resume bullet in the schema-owning contract says it 'names the authoritative re-resolution a replacement coordinator runs'. The main-agent contract (Unit coordinator boundaries) and agents/dev-loop.agent.md now say the continuing coordinator re-resolves authoritative state with unitBoundaries.resume at each report point, and the handoff-envelope.mjs JSDoc says 'the re-resolution the unit runs at a report point, or a replacement runs after a real stop'. The field definition therefore narrows resume to replacements only and disagrees with the other surfaces. — judge: defer (follow-up 2955) - low_fix_until_cap (GATE-EXEC-LOW-FIX-UNTIL-CAP)

• test/contracts/unit-coordinator-handback-contract.test.mjs:156 low (holistic): The PR body Regression evidence says this file has '13 top-level tests at the PR head, 9 of them new 2955: tests'. At bf424c6 the file has 14 top-level tests and 10 2955: tests (lines 156 to 245). The same section also says 'all 7 2955: tests ... fail pre-fix', so the stated pre-fix evidence covers fewer tests than the head carries. — judge: defer (follow-up 2955) - low_fix_until_cap (GATE-EXEC-LOW-FIX-UNTIL-CAP)

• low (pr-checklist): The PR body contradicts itself on the epic 2268 policy edit. The 'In scope' copy of the issue's last scope bullet appends 'Deferred to 2268 (follow-up, operator-owned): the epic active-policy edit is not delivered by this PR.' The 'Follow-ups for the operator' section says the orchestrator already edited the epic policy row and 'nothing deferred here'. The issue scope row ('Update the relevant efficiency epic's active policy references') is therefore represented as both deferred and delivered. — judge: defer (follow-up 2955) - low_fix_until_cap (GATE-EXEC-LOW-FIX-UNTIL-CAP)

Rejected (2)

• test/contracts/unit-coordinator-handback-contract.test.mjs:262 nit (dry): The two AC2 fixtures at lines 262 and 276 are copies of one 13-line body. They differ only in the peakContextTokens value (200000 against null) and in the final assertion. One loop over the two values with the unknown-only peak assertion guarded by the null case would state the fixture once. — judge: reject - The duplication maps one test to each dod:1 case and folding it adds a conditional assertion.

• test/contracts/unit-coordinator-handback-contract.test.mjs:156 nit (dry): The test '2955: issue-intake and PR units emit reportAfter and no handBackAfter' is subsumed by the handoff-envelope.test.mjs unitBoundaries tests. Those tests deepEqual the whole unitBoundaries object for an issue unit and a PR unit, so they already fail on a missing reportAfter or a leftover handBackAfter key. The strategy difference (issue_intake) does not matter because deriveUnitBoundaries reads the strategy only for the stateless-route check. — judge: reject - low_fix_until_cap (GATE-EXEC-LOW-FIX-UNTIL-CAP)

Gate evidence note: Copilot review rounds exhausted (2/2); current head has zero unresolved threads and green CI, so pre_approval_gate fallback is allowed without another Copilot re-request.

Next action: Clean pre_approval_gate verdict at current head; ready for operator approval