@haposoft/cafekit 0.16.0-rc.6 → 0.16.0-rc.8

package/src/claude/skills/develop/SKILL.md

@@ -1,187 +1,151 @@
 ---
 name: hapo:develop
-description: "Implement an explicitly invoked ready or low-risk change with policy-proportional evidence and one closeout owner."
+description: "Implement an explicitly requested process-first feature or task, run its real verification, and close it with one evidence owner. Also supports existing legacy Specs packets."
 user-invocable: true
-when_to_use: "Use to implement a ready spec, a specific task, or a Direct low-risk change."
+when_to_use: "Use to implement a ready feature packet, one named task, or a clear low-risk change."
 category: utilities
 keywords: [implementation, specs, verification]
 argument-hint: "[feature-name|specs-directory-path] [task-file] [--flash] [--parallel [N]] [--notes]"
 metadata:
   author: haposoft
-  version: "1.0.0"
+  version: "3.0.0"
 ---
-# Develop — implementation and closeout contract
+# Develop — implement, prove, synchronize
 
-Implement the requested scope, then close it with one canonical execution owner.
-For a durable spec, `spec.json` is machine authority and Markdown is a human
-projection. The v2.1 policy snapshot persists minimum input; lane, label,
-artifact profile, and ceremony are derived views. The executable policy source
-is `src/claude/scripts/workflow-policy.cjs` (installed as
-`.claude/scripts/workflow-policy.cjs`).
+Implement only the explicitly requested scope. For a process-first feature,
+`plan.md` and flat tasks are the durable packet; one closeout owner coordinates verification, review, sync, and docs impact without borrowing evidence.
+
+Develop never starts merely because Specs finished. The user invokes it.
 
 ## Usage and pre-state guard
 
 ```text
 /hapo:develop <feature>
 /hapo:develop specs/<feature>
-/hapo:develop <feature> <specific-task-file.md>
+/hapo:develop <feature> task-02-<slug>.md
 /hapo:develop <feature> --flash
 /hapo:develop <feature> --parallel [N]
 /hapo:develop <feature> --notes
 ```
 
-`--notes` is opt-in. Without it, do not create or update `implementation-notes.html`; there is no notes opt-out flag. When requested, load `references/implementation-notes-template.html` and record concrete decisions, gaps, scope-escape exceptions, risks, and verification caveats.
+`--notes` is opt-in. Only then load `references/implementation-notes-template.html`;
+record decisions, scope exceptions, risks, gaps, and verification limits. Never create it by default.
 
-Run the policy pre-state guard before loading a spec or mutating state. The incompatible pair must exit `2` and create no state, receipt, worktree, subagent, or commit: this is the `flash+parallel fail-fast` gate.
+Before any state mutation, reject `--flash` combined with `--parallel`:
 
 ```bash
 node .claude/scripts/workflow-policy.cjs --flash --parallel --json
 ```
 
-Expected message:
-
-```text
-Unsupported flags: --flash and --parallel are incompatible.
-Remediation: run `/hapo:develop <feature> --flash` or `/hapo:develop <feature> --parallel [N]`.
-No spec state, task receipt, worktree, subagent, or commit was created.
-```
-
-## Policy authority
-
-For durable specs, persisted `workflow_policy` authority is the v2.1 minimum.
-Canonical authoring supplies `planning_depth`, `assurance_level`,
-`classified_minimum`, and normalized `risks`; lane and ceremony remain derived
-views.
-
-Classify before spec/state mutation:
-
-```bash
-node .claude/scripts/workflow-policy.cjs --classify-lane --task-json '<task JSON>' --json
-```
-
-- **Direct**: clear, isolated, reversible, low-risk. Skip spec/state/registry ceremony and run targeted verification with proportional evidence.
-- **Standard**: use the bounded spec profile and focused inspection. A small feature needs no task registry/bundle and closes once at the feature boundary.
-- **Critical**: derived Strict view. Add durable task state, research, or review
-  only when actual topology, uncertainty, or assurance requires it.
+The pair exits `2` before a task edit, receipt, worktree, subagent, or commit. Do not reproduce it with a looser parser.
 
-Risk can raise the classified minimum. Reclassify before persistence. After
-persistence, a per-feature baseline is monotonic and no downgrade is supported
-until a trusted issuer exists; the baseline applies only to that feature.
-Legacy approval fields and caller booleans have zero authority.
+## Resolve the work packet
 
-Develop starts only from the user's explicit Develop invocation. Technical
-`ready_for_implementation` never dispatches Develop, and Specs must never
-auto-chain into this workflow.
+1. Resolve one `specs/<feature>/plan.md` plus flat `task-NN-*.md`; an explicit task path wins.
+2. Read C1 scope, exclusions, acceptance mapping, ownership, and task order.
+3. A task is unblocked only when every named dependency is done with a valid inline Receipt.
+4. Full-feature mode selects one unblocked task at a time, in plan order.
+   Specific-task mode implements only that task and then stops.
+5. Without a packet, work directly only when the change is clear, isolated, reversible, and low-risk.
 
-`execution_tier` (`Light | Standard | Deep`) is a read-only legacy adapter (`Direct | Standard | Critical`). It cannot emit policy, create obligations, select a workflow, or override the lane. Do not branch on it for new behavior.
+Ambiguity, overlapping ownership, a dependency cycle, or a missing Verification Plan is a blocker. Do not guess.
 
 ## Modes
 
-### Specific task
+### Sequential feature or specific task
 
-Load exactly one task packet, implement only its scope, run its evidence, and stop after synchronization. Specific-task mode never selects or chains into another pending task.
+Set the selected task's single `Status:` field to `in_progress`. Implement its
+Outcome and Acceptance only. Do not start the next task until proof, review,
+and sync for the current task finish. A specific-task invocation never chains.
 
-### Full feature
+### Parallel (`--parallel [N]`)
 
-For a task-bearing policy, resolve one unblocked task at a time, complete its cycle, synchronize, and recompute the queue. A bounded Standard feature without tasks runs one feature-level cycle. Stop on the first unresolved block or missing proof; run final integration only after all pending tasks finish.
+Load `references/parallel-waves.md`. Require disjoint writes, satisfied dependencies,
+isolated worktrees, a bounded wave, and one controller writer; otherwise work sequentially.
 
-### Parallel (opt-in)
+### Flash (`--flash`)
 
-Load `references/parallel-waves.md` only with `--parallel`. It may use isolated worktrees and a bounded wave, but lane obligations, single-writer rules, immutable provenance, and final integration remain in force. Otherwise process one unblocked task at a time.
+Flash is an explicit speed trade-off, never completion:
 
-### 3. Flash Mode (`--flash`)
-Flash is an explicit speed trade-off, not a completion shortcut:
-
-- skip dedicated test suites, full task evidence execution, and extended manual
-  checks;
-- run only a cheap available syntax/typecheck/compile preflight;
-- never weaken or delete tests;
-- synchronize only as `in_progress` with `FLASH_UNVERIFIED`,
-  `dependencyBlocked: true`, `unblocks: false`, and blocker
+- run only an available cheap syntax, typecheck, or compile preflight;
+- skip dedicated tests, extended manual checks, and review retry loops;
+- keep `Status: in_progress` and record `FLASH_UNVERIFIED` plus blocker
   `awaiting /hapo:test <feature>`;
-- never claim `Test PASS`, `Evidence PASS`, `Auto-Approved`, or
-  `production-ready`.
+- do not unblock dependents or report Test PASS, Evidence PASS,
+  production-ready, or done;
+- promotion later requires a fresh canonical PASS receipt through the trusted
+  sync-finalize path.
 
-Only trusted sync-finalize may promote a current `FLASH_UNVERIFIED` task with explicit `--verdict PASS` and canonical proof; caller promotion fields are ignored/rejected, and marker-only proof never promotes. Stored state remains `in_progress`/`FLASH_UNVERIFIED`, dependency-blocked with a concrete blocker, omits promotion fields, and binds proof to expected Base/Head anchors.
-## Workflow
-`Classify lane → load lane artifacts → scout obligations → implement current
-scope → one closeout owner → test receipt → review → docs-impact sync.`
+Never weaken, delete, or rewrite tests to make Flash look complete.
 
-### Step 1 — Load and scope
+## Task cycle
 
-- Direct does not create a spec, state, registry, task bundle, or notes file.
-- Standard requires its bounded validated artifacts, but not a
-  registry when the scope is small and no task obligation is persisted.
-- Critical requires only the artifacts named by its snapshot obligations.
-- For task-bearing work, load one requested task or one unblocked task and
-  extract the exact seven v2.1 sections: `Outcome`, `Scope`, `Anchors and Ownership`,
-  `Changes`, `Acceptance`, `Dependencies`, and `Verification Plan`.
-  Use typed `coordination.boundaries` for ownership/DAG/proof/parallel authority.
-- Before implementation, transition `pending` to `in_progress` in task Markdown `**Status:**` and `spec.json.task_registry[path]` with synchronized timestamps. Never write execution proof into the task plan.
-- A spec-ready execution-evidence or independent-audit slot may be `PENDING`
-  before implementation; pending is not proof and cannot close the feature.
+### 1. Scout
 
-### Step 2 — Scout
+Trace entrypoints, callers, dependents, registration, errors, and owned files.
+Compilation does not prove an unmounted UI, unregistered route, uncalled service, or missing consumer.
 
-Scout depth follows assurance, risk, and blast radius. Identify real
-entrypoints/callers, integration points, dependents, reachability risks, and
-safe scope. File count is not review depth; stop if a runtime entrypoint cannot
-be grounded.
+### 2. Implement
 
-### Step 3 — Implement
+Honor Scope, Ownership, Acceptance, and Dependencies. Do not silently replace named contracts;
+scope expansion requires evidence and a return to C1, not implementation convenience.
 
-Implement only the scoped behavior and named contracts. Do not silently replace
-frameworks, auth, transport, storage, or runtime boundaries. Do not mark a
-runtime-facing file complete while it is orphaned, unmounted, unregistered, or
-uncalled. A specific-task request ends after that task; no automatic chain.
+### 3. Verify and review once
 
-<SCOPE-FIDELITY>
-The `scope_lock`, requirements, design contracts, and active task are
-the implementation contract. Scope escape requires a concrete reachability or
-compile reason and must not deliver a later task early.
-</SCOPE-FIDELITY>
+The test owner executes the exact Verification Plan and records real output.
+The review owner, when risk or repository policy requires review, evaluates
+correctness, security, scope, and reachability but does not manufacture proof.
+Use `PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED`; only literal PASS can close.
 
-### Step 4 — Closeout owner
+Load `references/quality-gate.md` for the closeout contract. Remediate an
+observed failure, then rerun only affected proof and review. Do not blind-retry
+a blocked environment. After three failed repair rounds, stop and ask the user.
 
-The controller assigns exactly one closeout owner for the current task or feature. It invokes testing once, then review once when required; no phase re-runs either as a hidden gate.
+### 4. Write the inline Receipt and sync
 
-- For task-bearing work, the test owner executes the Verification Plan and writes the canonical execution receipt to `receipts/<task-basename>.md` only after real execution.
-- The review owner evaluates correctness, security, and spec compliance; it
-  consumes existing proof but never creates or claims execution proof.
-- Review depth follows `assurance_level`, risk, and blast radius. Lane is only
-  a derived view, and depth does not follow the
-  number of files changed.
-- Finding count never selects review depth or overrides missing execution proof.
-- Use the shared adapter surface: `PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED`.
-  Warnings do not waive missing proof; `FAIL` is remediable and `BLOCKED` stops.
+After a real pass, append or replace the task's final `## Receipt` with:
 
-Load `references/quality-gate.md` for the exact closeout contract. It has no
-fixed Light/Standard/Deep agent sequence.
+- `Verification: PASS`;
+- the exact `Command:` and `Exit: 0`;
+- runtime-derived `Base:` and `Head:`;
+- a non-empty fenced block containing current command output;
+- required negative, reachability, and artifact proof from the task.
 
-### Step 5 — Sync and docs checkpoint
+Then set `Status: done`, update only implemented checkboxes, and recompute the
+queue. Missing, stale, contradictory, zero-test, placeholder, or marker-only
+proof leaves the task unfinished.
 
-Only a canonical receipt with task identity/path, exact command/result, expected versus observed behavior, bound provenance, applicable negative/reachability proof, and required artifact hashes can close a task. Prefer `receipts/<task-basename>.md`; legacy task `## Evidence` is read-compatible, but conflicting proof identities fail closed. Missing, pending, marker-only, or contradictory evidence stays unfinished. Critical audits need distinct session IDs, expected Base/Head binding, concrete evidence, and literal `verdict: "PASS"`; `Audit: PASS` is not evidence.
-After verification, synchronize status/timestamps/task state. Then evaluate
-actual docs impact:
+### 5. Finish the requested boundary
 
-- `none`: record it and stop;
-- `minor`/`major`: update only affected existing docs through the normal docs
-  workflow, with no broad refresh.
+Specific-task mode stops after its sync. Full-feature mode continues one task
+at a time, then runs the feature-level integration command and reachability
+check named by the repository or plan. Show current evidence and limitations at
+C3; the user decides completion.
 
-Do not run a docs checkpoint merely because a task finished.
+Evaluate docs impact from the behavior actually changed:
 
-## Definition of done and handoff
+- `none`: report it and make no docs edit;
+- `minor` or `major`: update only affected existing docs through the docs flow.
 
-Done requires active criteria, all required evidence, reachable runtime behavior,
-a receipt bound to expected Base/Head, and every lane obligation. Only literal
-`PASS` can complete; `PASS_WITH_WARNINGS` remains unfinished.
-`--flash` records only `FLASH_UNVERIFIED` and never done.
+## Definition of done
 
-For a full feature, after the last task run the **Final Integration Scout** for runtime-facing surfaces and compare reachability/scope before completion. The same test owner creates `feature-receipt.md` exactly once from final integration proof. Task-bearing closeout requires every task receipt plus that feature receipt; taskless Compact/Full creates only the feature receipt at closeout. Its earlier absence is normal. A specific task stops after synchronization and creates no feature receipt unless it also completes the full integration boundary.
+Done requires satisfied acceptance, reachable behavior, current executable
+proof, correct Base/Head binding, resolved blocking review findings, and no
+scope substitution. `PASS_WITH_WARNINGS`, `NO_TESTS`, `FLASH_UNVERIFIED`, or a
+review-only pass cannot close work.
 
 ## Attached references
 
-- `references/quality-gate.md` — closeout ownership, verdict normalization, and
-  evidence checks.
-- `references/parallel-waves.md` — opt-in worktree waves.
-- `references/implementation-notes-template.html` — loaded only with `--notes`.
+- `references/quality-gate.md` — proof and review ownership.
+- `references/parallel-waves.md` — opt-in isolated worktree waves.
+- `references/implementation-notes-template.html` — only with `--notes`.
+
+## Legacy workflow compatibility
+
+If the selected feature contains `spec.json`, use its persisted
+`workflow_policy`, `task_registry`, nested task paths, typed boundaries,
+separate task receipts, and feature closeout receipt exactly as the legacy
+adapters require. Preserve `planning_depth`, `assurance_level`, derived lane,
+and read-only `execution_tier`; do not project these fields into a new v3
+packet. Keep JSON and Markdown status synchronized, and use the existing
+completion-authority path for final closeout.

package/src/claude/skills/develop/references/parallel-waves.md

@@ -1,194 +1,107 @@
-# Parallel Waves — hapo:develop `--parallel` operating procedure
-
-Normative protocol for executing independent spec tasks concurrently. Loaded by
-`develop/SKILL.md` when Full-Spec mode runs with `--parallel [N]`. Verified against
-live worktree-subagent behavior (spec `develop-parallel-wave`,
-`reports/worktree-spike.md`, 2026-07-19).
-
-## 1. Preconditions (check before anything else)
-
-1. `.claude/runtime.json` → `develop.parallel` is not `false` (escape hatch; missing
-   key = allowed). If `false`: refuse `--parallel`, tell the user the hatch is active
-   and which key controls it, then run the standard sequential loop.
-2. The work context is a git repository and worktree isolation is available.
-   Otherwise: state the reason ("not a git repo" / "isolation unavailable") and run
-   the standard **sequential fallback**.
-3. `--parallel N`: **wave cap** = N clamped to 1..5; default 3. Never exceed 5 —
-   each subagent carries a ~200K context budget (orchestrator.md resource rule).
-4. The destination tree must be clean (`git status --porcelain` is empty) and
-   compatible with the selected base before dispatch. Record the destination
-   `base_sha` and stop without mutation when cleanliness, repository, or base
-   compatibility checks fail.
-5. Before dispatch, state whether `--parallel` consent authorizes worker commits
-   and orchestrator cherry-picks. If that consent is not explicit, obtain the
-   separate confirmation before creating worktrees or asking workers to commit.
-
-### Receipt contract (required per wave/task)
-
-Every task and wave receipt records these exact fields:
+# Parallel waves — `hapo:develop --parallel`
+
+Load this reference only for explicit parallel execution. The goal is bounded
+concurrency with immutable provenance and one state writer.
+
+## Preconditions
+
+1. Confirm the work context is a Git repository and worktree isolation is
+   available. Otherwise state why and fall back to the sequential loop.
+2. Respect `.claude/runtime.json` `develop.parallel: false` when present.
+3. Clamp `--parallel N` to 1..5; default to 3.
+4. Require a clean destination and record its exact `base_sha`. Stop without
+   mutation if cleanliness or base compatibility fails.
+5. Confirm whether the user's parallel consent also authorizes worker commits
+   and controller cherry-picks before creating worktrees.
+
+Every task receipt for a wave records:
 
 ```text
 base_sha: <destination commit before dispatch>
-head_sha: <latest worker/integration commit>
+head_sha: <worker or integrated commit>
 branch: <worker branch>
-worktree_path: <retained or merged worktree path>
+worktree_path: <path>
 commit_range: <base_sha>..<head_sha>
 retention: retained|released
 cleanup_authorization: pending|explicit-discard|merged-release
 ```
 
-Reviewer and tester commands MUST inspect `git diff <base_sha>..<head_sha>` (or
-`git diff --stat <base_sha>..<head_sha>`), never an ambient working-tree diff.
-Every fix is a new commit: advance `head_sha`, replace `commit_range`, and rerun
-only affected gates plus the wave integration check. A receipt without these
-fields is incomplete.
+Test and review commands inspect `git diff <base_sha>..<head_sha>`, never an
+ambient working-tree diff. A fix creates a new commit and advances Head.
 
-## 2. Wave planning (normative)
-
-```
-ready(t) = t.status == "pending" AND every dep in task_registry[t].dependencies
-           has status == "done"
-candidates = ready tasks in task_registry order
-wave = first ≤cap candidates, EXCLUDING any task that conflicts with an
-       earlier task already in the wave under the conflict graph below
-```
+## Build a wave
 
-**Conflict graph.** A pair conflicts when either task writes the same exact file,
-one writes a directory another writes, or either touches a shared mutable surface:
-lockfiles, manifests/export barrels, migrations/registries, generated artifacts,
-or shared state writers. `Create`/`Modify`/`Delete` rows are writers; `Read` rows
-are still conflicts when they consume a mutable generated or registry surface.
-Normalize paths before comparison. If overlap is uncertain, classify it as a
-conflict and defer the task to the sequential fallback; never guess that two
-writers are independent.
+Read dependencies from the plan task table and each flat task's
+`## Dependencies`. A candidate is ready only when all named dependencies are
+done with valid Receipts.
 
-**Single writer per file per wave** remains absolute. Read-only tasks can still
-be deferred when they inspect a directory or shared generated state that a sibling
-writes.
+Add ready tasks in plan order up to the cap, excluding a task when it shares a
+write target with an earlier task or touches the same mutable registry,
+lockfile, manifest, generated output, migration, or export barrel. Normalize
+paths. Uncertain overlap is a conflict, not an invitation to guess.
 
-If the wave is empty but pending tasks remain, dependencies or conflicts are
-unsatisfiable in parallel — finish them with the sequential loop and say so.
+One file has one writer per wave. If no safe wave remains, use the sequential
+loop and state the dependency or ownership conflict.
 
-### Worked example
+## Dispatch
 
-Registry: A (deps: –), B (deps: –), C (deps: A), D (deps: – but shares
-`src/api/users.ts` Modify with B). Cap 3.
+Each worker receives the complete task packet, work context, exact owned paths,
+acceptance, Verification Plan, dependencies, and these constraints:
 
-- Wave 1 = A, B (D excluded: path collision with B; C excluded: dep on A)
-- Wave 2 = C, D (A done unblocks C; B done releases D's path)
+1. Work only in the assigned isolated worktree.
+2. Do not edit `plan.md`, task Status, or `## Receipt`; the controller owns
+   state and evidence synchronization.
+3. Do not touch a path outside granted ownership or undo another worker's edit.
+4. Run task-local prechecks and report exact commands and exits.
+5. Commit only when the user's authorization covers worker commits.
+6. Return status plus branch, worktree, Base, Head, range, and retention.
 
-## 3. Dispatch (one implementer per wave task)
+A blocked or failed worker keeps its identifiable worktree and branch. Never
+force-delete it without merge success or explicit discard authorization.
 
-Every dispatch uses worktree isolation + background execution and a
-self-contained prompt per `rules/orchestrator.md` (task file content, design and
-requirements excerpts, work-context/specs/docs paths, acceptance criteria) plus
-these mandatory lines:
+## Verify before integration
 
-1. "You are in an isolated git worktree. Implement ONLY this task."
-2. "Do NOT edit `spec.json` or any `tasks/*.md` — the orchestrator owns spec state."
-3. "Write only exact targets granted by this task's `Anchors and Ownership`
-   table and typed ownership/parallel boundaries."
-4. "When done, `git add` your changes and `git commit -m \"task(<id>): <title>\"` —
-   an uncommitted worktree cannot be merged."
-5. End with the standard `Status: DONE|CONCERNS|BLOCKED|NEEDS_INFO` block, plus
-   the receipt fields from §1, including worktree path, branch, and commit range.
-6. If a worker fails or blocks, do not remove its worktree or delete its branch.
-   Mark `retention: retained` and `cleanup_authorization: pending` until merge
-   succeeds or the user gives explicit discard authorization.
+Inside each worktree, run the task's proof through `quality-gate.md` against the
+immutable commit range. A task with missing proof, overlap, or unresolved High
+or Critical finding is not eligible to integrate. Three failed repair rounds
+collapse only that task; siblings may finish but do not erase its blocker.
 
-The orchestrator records `base_sha` immediately before dispatch. The worker's
-first accepted commit becomes `head_sha`; no receipt may use a moving ambient
-HEAD as a substitute. The Agent result returns `worktreePath` and
-`worktreeBranch`; record both in the receipt.
+## Integrate sequentially
 
-## 4. Quality gate — inside the worktree, before merge
-
-Run the unchanged Stage A + Stage B gate (`references/quality-gate.md`) per task
-**with the task's worktree as working directory**. Before reviewing, tester and
-reviewer commands must inspect the receipt's immutable range:
+Apply accepted worker commits one at a time in plan order:
 
 ```bash
-git diff --stat "$BASE_SHA..$HEAD_SHA"
-git diff "$BASE_SHA..$HEAD_SHA"
+git cherry-pick <worker-commit>
 ```
 
-Do not replace this range with `git diff`, `git status`, or another ambient
-working-tree view. Gate evidence from that run feeds the task receipt. Three
-failed rounds → COLLAPSE protocol for that task only; sibling tasks in the wave
-keep running. Any fix creates a new commit and updates `head_sha`/`commit_range`
-before affected gates rerun.
+On conflict, abort the cherry-pick, mark the task blocked, and retain its
+worktree/branch. After success, update the receipt range to the integrated Head.
+Release a worktree only after recording `cleanup_authorization: merged-release`.
 
-## 5. Merge protocol (spike-verified — do not improvise)
+## Post-merge proof
 
-⚠️ Spike finding: worktree branches are based on **`origin/<default-branch>`**
-(`worktree.baseRef: "fresh"` default), NOT the session HEAD. On repos whose origin
-default diverges, `git merge <agent-branch>` explodes into unrelated conflicts.
+After the wave's last integration, run an affected integration command derived
+from the tasks and repository contract. Record command, exit, Base, Head,
+range, and output. Failure blocks the next wave.
 
-Therefore, for each gate-passed task, sequentially (one at a time, registry order):
+Classify a failure before acting:
 
-```bash
-git cherry-pick <agent-commit>       # base-agnostic: applies only the agent's diff
-# conflict? → git cherry-pick --abort
-#   → task_registry[task].status = "blocked", blocker = one-line conflict summary
-#   → retain the worktree/branch; receipt says retention=retained
-```
+- `baseline`: reproduces from the recorded Base;
+- `environment`: required tool, service, permission, or dependency unavailable;
+- `spec`: acceptance or evidence contract is wrong or incomplete;
+- `code`: implementation or integration regression.
 
-A successful merge may release the worktree and branch only after the receipt
-records `head_sha` at the merge result, the new `commit_range`, and
-`cleanup_authorization: merged-release`:
+Do not blind-retry. Fix code/spec with a new commit and rerun affected proof;
+record baseline/environment as blockers.
 
-```bash
-git worktree remove .claude/worktrees/agent-<id>
-git branch -d worktree-agent-<id>
-```
+After the final wave, run the feature-level integration and reachability proof.
+The controller then writes inline Receipts and Status updates one task at a
+time. Worker reports are evidence inputs, not permission to claim done.
+
+## Legacy workflow compatibility
 
-Never use `--force` cleanup for failed or blocked work. Retain its identifiable
-worktree and branch for inspect/resume until the merge succeeds or the user
-explicitly authorizes discard; record `cleanup_authorization: explicit-discard`
-when that happens. Optionally set `worktree.baseRef: "head"` in settings;
-cherry-pick remains the recipe regardless.
-
-## 6. Post-merge integration check (per wave)
-
-After the wave's last cherry-pick, run an affected integration command derived
-from the task's `Verification Plan` and repository contract (build or affected test
-subset; never the full suite mid-flight). Record command, `base_sha`, `head_sha`,
-range, and result in the wave receipt. Failure blocks the next wave.
-
-After the final wave, run an explicit feature/full integration command derived
-from the repository contract — for example the feature's exact verification suite
-or the repository's documented full test/build command. A final scout is not a
-substitute. On PASS, the test owner creates `feature-receipt.md` once; task
-receipts alone cannot close the feature. Classify every failure before acting as exactly one of:
-
-- `baseline` — reproduces from the recorded destination `base_sha`;
-- `environment` — tool, dependency, permission, or service unavailable;
-- `spec` — requirement, acceptance, or evidence contract mismatch;
-- `code` — implementation or integration regression.
-
-Do not blind-retry. Fix `code`/`spec` failures with a new commit and affected
-gates; record `baseline`/`environment` blockers and escalate or use the
-sequential fallback according to the task contract.
-
-## 7. State sync — orchestrator is the single writer
-
-Only the orchestrator writes `spec.json` and task markdown, after each task's
-cherry-pick: registry `status`/`completed_at`/`last_updated_at`, task-md `Status`,
-checkbox ticks, and a canonical `receipts/<task-basename>.md` citing the
-worktree gate evidence plus the post-merge check result. Never append execution
-proof to task Markdown. The Stop completion gate (`spec-gate.cjs`) applies
-unchanged — a receipt-less done blocks the turn. After syncing the wave, recompute
-§2 and continue until no pending tasks remain.
-
-## 8. Failure summary
-
-| Event | Action |
-|---|---|
-| Escape hatch on / not a git repo / no isolation | Sequential fallback + stated reason |
-| Same-wave path collision | Defer the later task to next wave (§2) |
-| Gate fails 3× for a task | COLLAPSE for that task; retain worktree/branch and receipt; wave continues |
-| Worker failure or blocked task | Retain identifiable worktree/branch; no force-remove; classify and await resume or explicit discard |
-| Cherry-pick conflict | Abort pick; task `blocked` + conflict blocker; retain worktree/branch; wave continues |
-| Post-merge check fails | Classify baseline/environment/spec/code; no next wave until resolved or explicitly blocked |
-| Final integration fails | Record failure class and stop; do not claim completion from a final scout |
-| Empty wave, tasks pending | Sequential loop for the remainder + notice |
+For an existing `spec.json` feature, readiness and dependencies come from the
+persisted `task_registry` and typed `coordination.boundaries`. Workers still do
+not edit that state. The controller writes the legacy separate task receipt,
+synchronizes registry plus nested task Markdown, and creates the required final
+feature receipt only after integrated proof.