@haposoft/cafekit 0.16.0-rc.2 → 0.16.0-rc.4

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

@@ -1,53 +1,44 @@
 ---
 name: hapo:develop
-description: "Code execution engine: Reads specs and implements code end-to-end with automatic code review, self-healing, and visual implementation notes."
+description: "Implement an explicitly invoked ready or low-risk change with policy-proportional evidence and one closeout owner."
 user-invocable: true
-when_to_use: "Invoke to implement specs and tasks end-to-end after scope is clear."
+when_to_use: "Use to implement a ready spec, a specific task, or a Direct low-risk change."
 category: utilities
-keywords: [implementation, specs, build, orchestration]
-argument-hint: "[feature-name|specs-directory-path] [task-file] [--flash] [--parallel [N]] [--no-notes]"
+keywords: [implementation, specs, verification]
+argument-hint: "[feature-name|specs-directory-path] [task-file] [--flash] [--parallel [N]] [--notes]"
 metadata:
   author: haposoft
   version: "1.0.0"
 ---
-# Develop — Feature Implementation (Task-Orchestrated Build)
+# Develop — implementation and closeout contract
 
-Reads the project specification (`hapo:specs`) and implements code through a disciplined task loop. In specific-task mode it behaves like a surgical executor. In full-spec mode it behaves like a sequential orchestrator, processing one unblocked task at a time and syncing state after every verified task.
+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`).
 
-**Principles:** YAGNI, KISS, DRY | Continuous execution | Smart self-healing
+## Usage and pre-state guard
 
-**Executable policy source:** `src/claude/scripts/workflow-policy.cjs` defines Direct/Standard/Critical lane classification, lane delegation, approval-state semantics, mode conflict fail-fast, legacy Light/Standard/Deep delegation, review verdict handling, and flash promotion. Installed Claude runtime uses `.claude/scripts/workflow-policy.cjs`; contracts below must match it.
-
-## Usage
-
-```bash
-/hapo:develop <feature name>
-/hapo:develop specs/<feature-name>
-/hapo:develop <feature name> <specific-task-file.md>
-/hapo:develop <feature name> --flash
-/hapo:develop <feature name> <specific-task-file.md> --flash
-/hapo:develop <feature name> --no-notes
+```text
+/hapo:develop <feature>
+/hapo:develop specs/<feature>
+/hapo:develop <feature> <specific-task-file.md>
+/hapo:develop <feature> --flash
+/hapo:develop <feature> --parallel [N]
+/hapo:develop <feature> --notes
 ```
 
-## Mode Matrix
+`--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.
 
-| Mode | Scout | Quality gate | Receipt | Notes |
-|---|---|---|---|---|
-| default (specific-task / full-spec) | per tier | full (Step 4) | verified | |
-| `--flash` | per tier | Flash Gate (4F) | `FLASH_UNVERIFIED` | |
-| `--parallel` | inspector per task (Critical) | full, inside each worktree | verified | implies Critical lane (legacy Deep) |
-| `--flash --parallel` | **flash+parallel fail-fast — no execution** | | | reject before state/worktree changes |
-| `--no-notes` | — | — | — | composable with all modes |
-
-## Argument validation
-
-Run policy pre-state guard before loading spec files or mutating state. For the incompatible flag pair, the command must exit nonzero and write no state, receipt, worktree, subagent, or commit:
+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.
 
 ```bash
 node .claude/scripts/workflow-policy.cjs --flash --parallel --json
 ```
 
-Expected JSON contract: `{"ok":false,"contract":"execution-policy","failFast":true,...}` with exit code `2`. If both `--flash` and `--parallel` are present, print:
+Expected message:
 
 ```text
 Unsupported flags: --flash and --parallel are incompatible.
@@ -55,278 +46,142 @@ Remediation: run `/hapo:develop <feature> --flash` or `/hapo:develop <feature> -
 No spec state, task receipt, worktree, subagent, or commit was created.
 ```
 
-Then STOP with no execution. Never silently drop `--flash`, prefer `--parallel`, or start a more expensive workflow.
+## 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.
 
-## Lane selection before spec gate
-
-Run lane classification at the runtime boundary before loading spec files or mutating state. Decisions are executable, not advisory prose:
+Classify before spec/state mutation:
 
 ```bash
 node .claude/scripts/workflow-policy.cjs --classify-lane --task-json '<task JSON>' --json
-# Downgrade requires explicit user authorization - model-supplied downgrade is blocked
-node .claude/scripts/workflow-policy.cjs --classify-lane --task-json '{"riskSignals":{"auth":true},"override":"Direct","userAuthorized":true}' --json
 ```
 
-- **Direct** — clear, isolated, reversible, low-risk work. May skip spec/state/subagents and full task/spec/registry ceremony; execute targeted test, diff self-check, and proportional evidence only.
-- **Standard** — default. Use one bounded spec artifact (`requirements.md` + `design.md` in current layout), one canonical receipt, and exactly one combined `code-auditor` review at feature ship point (not per-task).
-- **Critical** — destructive/irreversible, auth/payment/privacy/data, schema/migration, public contract, cross-runtime coupling, outcome-changing ambiguity, or difficult rollback. Use strict durable state and evidence with risk-driven delegation (inspector/test-runner/code-auditor enabled per risk lens), not a fixed four-agent chain.
+- **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.
 
-Explicit overrides are enforced at the runtime boundary. A model-supplied lane or downgrade must not bypass risk signals. Downgrading from Critical requires explicit user-originated authorization (`userAuthorized:true` or `origin:user`) and must surface the trade-off (reduced review/evidence coverage). Keep `generated`, `agent_validated`, and `user_approved` independent; agent validation or --auto never fabricates `user_approved`.
+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.
 
-Direct may bypass the approved-spec hard gate only for low-risk reversible work. Standard and Critical still require their lane-appropriate spec/state gate.
+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. Specific-Task Mode
-Triggered by `/hapo:develop <feature> <task-file>`.
+`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.
 
-- Load exactly one task file.
-- Implement only that task packet.
-- STOP immediately after the task is verified and synchronized, or flash-synchronized when `--flash` is active.
-- Never auto-chain into the next task.
+## Modes
 
-### 2. Full-Spec Mode
-Triggered by `/hapo:develop <feature>` or `/hapo:develop specs/<feature>`.
+### Specific task
 
-- Build a queue from `spec.json.task_registry`.
-- Select the next `pending` + unblocked task only.
-- Run the full implementation cycle for that single task.
-- Sync state.
-- Recompute the queue and continue.
-- STOP the overall run on the first blocked task, unresolved gate failure, or missing proof.
-- In `--flash` mode, missing full test proof stores the task as `status: "in_progress"` with receipt `FLASH_UNVERIFIED` and blocker `awaiting /hapo:test <feature>`. It does not unblock dependencies or mark the task done.
+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.
 
-### 2b. Parallel Wave Mode (opt-in)
-Triggered by adding `--parallel [N]` to Full-Spec mode. Load `references/parallel-waves.md` and follow it exactly — it is the operating procedure (wave planning, dispatch, merge, cleanup).
+### Full feature
 
-Contracts: WAVE_CONFIG
+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.
 
-<!-- contract:WAVE_CONFIG -->
-```jsonc
-// .claude/runtime.json — develop parallel toggle (missing key = allowed)
-"develop": {
-  "parallel": true   // false = --parallel refused, sequential run + notice
-}
-// Flag: /hapo:develop <feature> --parallel [N]   (N = wave cap, 1..5, default 3)
-```
+### Parallel (opt-in)
+
+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.
+
+### 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
+  `awaiting /hapo:test <feature>`;
+- never claim `Test PASS`, `Evidence PASS`, `Auto-Approved`, or
+  `production-ready`.
+
+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.`
+
+### Step 1 — Load and scope
+
+- 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.
+
+### Step 2 — Scout
 
-- Preconditions first: if `runtime.json` sets `develop.parallel: false`, refuse `--parallel`, name the key, and run the sequential loop. If the work context is not a git repository or worktree isolation is unavailable, state the reason and fall back sequential (see parallel-waves.md §1).
-- Waves are computed from `task_registry.dependencies` with the single-writer-per-file rule; wave cap = N (1..5, default 3).
-- Dispatch one `implementer` per wave task — worktree isolation, background, self-contained prompt per `rules/orchestrator.md`, plus the mandatory lines in parallel-waves.md §3 (commit mandate; never edit `spec.json`/`tasks/*.md`; never touch files outside the task's `Related Files`).
-- Quality gate (Stage A+B, unchanged) runs inside each task's worktree BEFORE merge; merge = sequential `git cherry-pick` of agent commits with explicit worktree/branch cleanup (spike-verified — see parallel-waves.md §5); post-merge integration check gates the next wave.
-- The orchestrator is the single writer of spec state: registry/task-md/receipts update after each cherry-pick, exactly as in sequential mode.
-- Without `--parallel`, nothing in this section applies — the sequential Full-Spec loop below is unchanged.
-
-### 3. Flash Mode
-Triggered by adding `--flash` to either specific-task or full-spec mode.
-
-- Optimize for fast implementation, not full verification.
-- Still load the approved spec, scout every task, obey scope, and implement real code.
-- Skip dedicated test suites, E2E/browser/manual QA loops, full task evidence execution, and code-review retry loops.
-- Run only cheap preflight checks when available and fast: syntax, typecheck, or build commands that do not require installing dependencies or starting external services.
-- Never weaken, delete, or rewrite tests to avoid running them.
-- Sync the implementation as `status: "in_progress"` with receipt `FLASH_UNVERIFIED`, blocker `awaiting /hapo:test <feature>`, and no dependency unblocking. Do not claim task or feature completion.
-- Final output MUST recommend `/hapo:test <feature>` before merge, release, or publish.
-
-### 4. Implementation Notes
-Implementation notes apply to Standard/Critical modes by default; Direct stays artifact-free unless user explicitly requests a receipt. Disable notes with `--no-notes`.
-
-- **Standard/Critical**: maintain `specs/<feature-name>/implementation-notes.html`.
-- **Standard/Critical**: use `references/implementation-notes-template.html` when the file does not exist.
-- Keep the file self-contained: inline CSS, no JS, no external fonts, no network assets.
-- Style notes as readable Claude Code-like blocks: compact cards, left accent bars, category badges, monospace file paths, and a task timeline.
-- Record decisions and caveats while implementing, not only at the end.
-- Do not use notes to justify scope changes that alter the approved contract. If the contract changes, stop and route back to `/hapo:specs update`.
-
-## Delegation policy (single source for this skill)
-
-Implement in the main session by default. Do not spawn a subagent because a step
-mentions an agent name — spawn only per this table:
-
-| Lane | Delegation (risk-driven) | Quality gate |
-|---|---|---|
-| Direct | None | Main-session targeted verification and diff self-check |
-| Standard | Exactly one combined `code-auditor` at feature ship point (not per-task) | Feature-level ship point |
-| Critical | Risk-driven: `inspector` when discovery needed, `test-runner` when code changes, `code-auditor` at feature closeout (not fixed four-agent per task) | Strict evidence gate |
-
-Legacy `execution_tier` (`Light | Standard | Deep`) is retained only as backward-compatible metadata (tier = Light → Direct, Standard → Standard, Deep → Critical). When both exist, lane policy controls ceremony/delegation and tier is metadata only. Do not treat tier as authoritative.
-
-<LANE-GATE>
-Do not write implementation code until lane classification runs at the runtime boundary.
-- **Direct** may bypass spec/state/registry and full task ceremony only when classifier confirms clear, isolated, reversible, low-risk work; targeted verification and evidence remain mandatory.
-- **Standard** requires one bounded approved spec artifact (`requirements.md` + `design.md` in current layout) and canonical receipt before implementation; exactly one feature-level closeout review.
-- **Critical** requires approved lane-appropriate spec/state plus strict evidence before implementation; delegation is risk-driven, not a fixed chain.
-Never treat a Direct override as automatic low risk; preserve its warning, risk signals, and user authorization requirement. Model-supplied downgrades without user authorization are blocked.
-</LANE-GATE>
-
-<DEFINITION-OF-DONE>
-A task is NOT done because code compiles or a placeholder renders.
-A task is done only when the task file's Completion Criteria AND `## Evidence` (legacy heading aliases still parse) are satisfied with real execution proof.
-`--flash` is the only exception: it records fast implementation closeout with `FLASH_UNVERIFIED`, not full Definition of Done.
-</DEFINITION-OF-DONE>
-
-<CONTRACT-FIDELITY>
-If the spec/task explicitly names a framework, auth system, datastore, transport path, or runtime boundary, that named choice is contractual.
-You MUST NOT silently replace it with a simpler custom substitute ("for MVP", "placeholder", "temporary auth", "in-memory until later") unless the spec itself is updated first.
-</CONTRACT-FIDELITY>
+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.
+
+### Step 3 — Implement
+
+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.
 
 <SCOPE-FIDELITY>
-The approved `scope_lock`, requirements, design contracts, and active task packet are the implementation contract.
-You MUST implement all scoped behavior for the active task, MUST NOT add out-of-scope behavior, and MUST NOT mark work done while required surfaces exist only as orphaned files, unmounted UI, unregistered routes, uncalled loaders, or placeholder wiring.
+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>
 
-## Absolute Workflow
-
-```mermaid
-flowchart TD
-    A["/hapo:develop \u003cfeature\u003e"] --> L[Classify lane]
-    L -->|Direct| D[Step 3: Implement (targeted or lane-scoped)]
-    L -->|Standard/Critical| B[Step 1: Load lane spec/state]
-    B -->|Missing or not approved| Z[Stop: Run lane-appropriate /hapo:specs]
-    B -->|Ready| C[Step 2: Task-Aware Scout (per lane policy)]
-    C --> D
-    D --> E{Flash Mode?}
-    E -->|No| Q[Step 4: Quality Gate: Test + Spec Review + Code Review + Evidence]
-    E -->|Yes| R[Step 4F: Flash Gate: Minimal Preflight + Scope Sanity]
-    Q -->|Fail| D
-    Q -->|Pass| F[Step 5: State Sync + Incremental Docs Sync]
-    R -->|Syntax/compile fail| D
-    R -->|Flash closeout| F
-    F --> H{More tasks?}
-    H -->|Yes| B
-    H -->|No| G[Final Integration Scout + Report Completion]
-```
+### Step 4 — Closeout owner
 
-### Step 1: Initialize & Load Spec
-- **Direct**: after classifier confirms low-risk reversible work, skip spec/state/registry initialization and continue with targeted implementation/evidence.
-- **Standard/Critical**: identify input and open the lane-appropriate `spec.json` plus bounded spec artifacts; require approved state before implementation.
-- Check `ready_for_implementation` only for Standard/Critical specs. If not ready, notify user.
-- **Standard/Critical only**: load `task_registry` and verify it matches the requested task file(s). If registry is missing or stale, route to `/hapo:sync audit <feature>` before coding.
-- **Standard/Critical only**: unless `--no-notes` is present, initialize or update `specs/<feature-name>/implementation-notes.html`:
-  - If missing, create it from `references/implementation-notes-template.html`.
-  - Replace template placeholders for feature name, spec path, creation timestamp, and current mode.
-  - If present, preserve existing note cards and update the summary/timeline/status fields.
-- **Direct** does not create or update spec implementation notes unless user explicitly asks for a receipt.
-- **Standard/Critical only**: load exactly one task packet for specific-task mode, or resolve one unblocked task from `task_registry` for full-spec mode.
-- **Standard/Critical only**: extract Objective + Constraints, Related Files, Completion Criteria, Evidence commands, requirement IDs, named technologies, and canonical contracts before coding.
-- If a Standard/Critical task file lacks actionable completion or verification detail, stop and route back to spec correction. Direct does not use this packet gate.
-- **Standard/Critical only**: set the active task to `in_progress` in markdown and `spec.json.task_registry` before coding. Direct has no registry mutation.
-
-### Step 2: Scout (Codebase Inspection)
-- **Scout per Delegation policy** — Critical may delegate to `inspector` when risk lens requires discovery; Direct/Standard scout in the main session with the same required outputs (legacy Light/Standard/Deep tier is metadata only):
-- The scout prompt MUST include:
-  - Active task file path and extracted task packet
-  - Requirement IDs and `scope_lock`
-  - Relevant `design.md` contracts/invariants
-  - Prior completed task outputs from `spec.json.task_registry`
-  - Related Files from the active task
-- The scout MUST report:
-  - Real runtime entrypoints/callers affected by the task (`App.tsx`, routes, CLI command, worker registration, manifest, API consumer, etc.)
-  - Existing integration points and adjacent code patterns to follow
-  - Prior task outputs this task must consume or preserve
-  - Blast-radius touchpoints and dependent files that can regress
-  - Reachability risks: orphan components, unmounted UI, unregistered routes, uncalled services/loaders, unused providers, disconnected reducers/actions
-  - Exact files likely safe to modify and any files outside `Related Files` that require a justified scope escape
-- If the inspector cannot identify the entrypoint/caller for a runtime-facing task, STOP and route back to spec correction or ask the user. Do not guess.
-
-### Step 3: Implement Code
-- Act as the `implementer` per the Delegation policy (default: the main session), executing tasks specified in the loaded Markdown file(s) sequentially.
-- **Important:** You may create and modify files directly, but must faithfully follow the design from the Spec.
-- You MUST use the Step 2 scout report as implementation context. If code reality contradicts the task packet, stop and reconcile the spec before coding.
-- **Standard/Critical only**: unless `--no-notes` is present, append a note card to `implementation-notes.html` whenever any of these occurs:
-  - `decision`: a necessary implementation choice not specified by the spec
-  - `spec-gap`: missing or ambiguous spec detail discovered during implementation
-  - `codebase-reality`: existing code requires a different integration path than the task implied
-  - `tradeoff`: a conscious simplicity, performance, UX, or maintainability tradeoff
-  - `scope-escape`: a file or behavior outside Related Files must be touched for reachability/compile/integration
-  - `risk`: known residual risk, edge case, or deferred follow-up
-  - `verification`: command result, skipped check, manual proof, or evidence caveat
-- Progress tracking: Temporarily change `[ ]` to `[/]` in Spec files while coding is in progress. Do NOT mark `[x]` before Step 4 passes.
-- **Task Boundary Protocol (CRITICAL):**
-  - Default editable scope is `Related Files` from the task packet.
-  - You may additionally touch direct test files plus minimal support files required to make the current task executable (shared types, exports, config glue, generated migration wiring).
-  - If you must edit a file outside this scope, explicitly treat it as a `scope escape` and justify why it is required for the current task.
-  - If the out-of-scope change would deliver functionality clearly assigned to a later task, STOP instead of implementing it early.
-- **Hard Stop Protocol:** If you were asked to implement a specific task file, you MUST STOP completely after that task is verified. DO NOT auto-chain or jump to "Next Task" simply because you see it in the spec. Wait for the user's next command.
-- **Full-Spec Loop Protocol:** If you were asked to implement the whole feature, you MUST still work one task at a time. Finish Step 4 and Step 5 for the current task before selecting the next unblocked task from `task_registry`.
-- **Test Integrity Protocol:** You MUST NOT delete, replace, or reduce the scope of existing test cases to make tests pass. If a test fails, you must fix the **implementation code** or fix the **test setup/mock**, NOT remove the assertion. Reducing test count or weakening assertions (e.g., removing `toHaveBeenCalledWith` and replacing with `toEqual(expect.any(...))`) is a Critical violation.
-- **Contract Integrity Protocol:** If implementation appears to require changing auth/session, transport, persistence, entrypoint wiring, or generated artifact behavior beyond what `design.md` states, STOP and route back to spec correction instead of inventing a new contract in code.
-- **Named Technology Rule:** If the task/spec explicitly requires a named dependency or runtime choice (for example Better Auth, Hono, Next.js proxy routes, Redis, Drizzle, S3), you MUST implement that choice or stop. Do not swap it for a custom/in-memory/local substitute and still call the task complete.
-- **Cross-Service Reality Rule:** If a task spans multiple processes or runtimes (web ↔ API, worker ↔ DB, extension ↔ backend), you MUST prove the integration uses shared real state or a real contract boundary. Process-local placeholders on both sides do not count as completion.
-- **Placeholder Completion Rule:** You MAY scaffold future files only when the active task truly needs them to compile, but placeholder route handlers, in-memory stores, or fake adapters MUST NOT be used as evidence that the current task's behavior works end-to-end.
-- **Reachability Rule:** Runtime-facing work is incomplete until it is reachable from the real entrypoint/caller named in the task evidence or Step 2 scout report. Creating a component/service/route/provider/reducer without importing, mounting, registering, or invoking it is not implementation.
-- **Prior Output Consumption Rule:** If this task depends on previous task outputs, verify those outputs are consumed through real code paths. If a prior output is unused and this task is responsible for wiring it, wire it now; if a later task owns the wiring, keep the current task pending unless that deferral is named in the active task evidence.
-
-### Step 4: Self-Healing (Quality Gate Auto-Fix)
-The moment you finish coding, DO NOT proceed further. Switch to `references/quality-gate.md` and run the automatic review loop.
-**Mantra:** Scope/spec compliance first, code quality second. All feedback from code-auditor must be addressed thoroughly: PASS requires no Critical findings, no High findings, and at most one Medium.
-
-If `--flash` is active, use **Step 4F: Flash Gate** instead of the full automatic review loop.
-
-- Passing Step 4 requires ALL of the following:
-  1. Automated verification passes, including preflight compile/typecheck/build health and every exact command named in the task's `## Evidence` (legacy heading aliases still parse)
-  2. Spec compliance review passes: every scoped requirement and active task criterion is implemented, with no extras and no omissions
-  3. Code quality review passes
-  4. Task evidence passes (artifacts/runtime surfaces/reachability/negative-path checks from the task file are proven)
-- Violating any Step 3 rule = FAIL.
-- `PRECHECK_FAIL` outranks `NO_TESTS`. If compile/typecheck/build fails, the task is FAIL even when no test suite exists yet.
-- If build/test passes but task evidence is missing, the task is still FAIL.
-- Only escalate to the user after 3 consecutive failed review rounds.
-
-### Step 4F: Flash Gate (`--flash` only)
-Flash mode is an explicit speed trade-off requested by the user.
-
-- Skip:
-  - dedicated test commands from task Evidence
-  - full test-runner delegation
-  - E2E/browser/manual QA loops
-  - full code-auditor retry loop
-  - screenshot, accessibility, performance, and visual verification unless the active task is purely visual and can be checked cheaply
-- Still perform:
-  - task-aware scout from Step 2
-  - active task scope sanity check against Completion Criteria
-  - reachability sanity check for runtime-facing files: imported, mounted, registered, routed, or invoked where applicable
-  - cheap compile/syntax/typecheck/build command when it is already available and expected to run quickly
-- If the cheap preflight fails, return to Step 3 and fix before syncing.
-- If no cheap preflight exists or it would require slow setup/external services, record `Preflight: skipped in --flash mode`.
-- Flash output MUST log: `⚡ Step 4 Flash Gate: tests skipped by --flash; preflight=<pass|skipped>; evidence=FLASH_UNVERIFIED`.
-- Flash output MUST NOT say `Test PASS`, `Evidence PASS`, `Auto-Approved`, or `production-ready`.
-
-### Step 5: State Sync + Task-Level Docs Sync
-- Only after Step 4 passes may you mark task checkboxes completed and sync `spec.json` progress/timestamps/task_registry.
-- In `--flash`, Step 4F may record implementation closeout only as `status: "in_progress"` with `FLASH_UNVERIFIED` and blocker `awaiting /hapo:test <feature>`; it never syncs `done` or unblocks dependencies.
-- If verification is partial or blocked by environment, keep the task in `pending` or `in_progress` and record the blocker instead of pretending completion.
-- A completed task MUST leave behind:
-  - markdown `**Status:** done`
-  - `spec.json.task_registry[path].status = "done"`
-  - `completed_at` + `last_updated_at`
-  - synchronized top-level `updated_at`
-  - a human-readable verification receipt inside the task's `Evidence` section showing which commands ran, their outcomes, and what proof was observed
-- In `--flash`, the receipt MUST include `Mode: --flash`, `Tests: skipped by user request`, `Evidence: FLASH_UNVERIFIED`, `Status: in_progress`, `Blocker: awaiting /hapo:test <feature>`, and `Next verification: /hapo:test <feature>`.
-- Verification receipts with `PRECHECK_FAIL`, `FAIL`, `UNVERIFIED`, or an explicit note that the implementation intentionally simplified a named contract MUST NOT be synchronized as `done`.
-- Exception: `FLASH_UNVERIFIED` is allowed only when `--flash` is explicitly present. It records fast implementation completion, not full verification completion.
-- Unless `--no-notes` is present, update `implementation-notes.html` before reporting the task:
-  - Mark the task block as `done`, `blocked`, or `flash_unverified`.
-  - Add a `verification` note with exact commands run or `Tests skipped by --flash`.
-  - If no implementation note was needed for the task, add a compact `decision` note: `No spec gaps, tradeoffs, scope escapes, or deferred risks recorded for this task.`
-  - Add `Next verification: /hapo:test <feature>` when any evidence is skipped, partial, or `FLASH_UNVERIFIED`.
-- After syncing the active task, run a **Task Closeout Docs Checkpoint**
-- Task Closeout Docs Checkpoint:
-  - Evaluate `Docs impact: none | minor | major` based on real behavior changes from the just-completed task
-  - If `none`: record that explicitly in the completion report and stop
-  - If `minor` or `major`: trigger `docs-keeper` to surgically update affected existing docs under `./docs`
-  - Default to **lightweight docs sync**: update only the docs touched by this task and its verified behavior; do NOT run `repomix` unless `docs-keeper` truly cannot verify the required architecture/context from the code, spec, and current docs
-- **CWD Protocol (CRITICAL):** When spawning `docs-keeper`, set its Current Working Directory (CWD context) to the **Workspace Root**, not the inner package directory.
-- Task-level docs sync happens after every verified completed task, but actual edits still depend on `Docs impact`.
-- In **Specific-Task Mode**, STOP after sync and report the result.
-- In **Full-Spec Mode**, only after sync may you re-read `task_registry`, pick the next unblocked pending task, and repeat from Step 1 for that task.
-- When no pending tasks remain, run a **Final Integration Scout** before reporting completion:
-  - Trace runtime entrypoints from `main`/route/CLI/worker/manifest/API consumer through the scoped feature surfaces.
-  - Compare reachable behavior against `scope_lock`, `requirements.md`, `design.md`, and all task Completion Criteria.
-  - FAIL completion if any scoped surface is missing, any created runtime-facing artifact is orphaned, or spec progress/registry says done while evidence is missing.
-  - Only then set top-level progress to `code_done` / next phase.
+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.
 
----
-## Attached References
-- `references/quality-gate.md` - Rules for the Code Review loop.
-- `references/subagent-patterns.md` - Standard prompts for calling subagents.
-- `references/implementation-notes-template.html` - Self-contained visual implementation notes template.
+- 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.
+
+Load `references/quality-gate.md` for the exact closeout contract. It has no
+fixed Light/Standard/Deep agent sequence.
+
+### Step 5 — Sync and docs checkpoint
+
+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:
+
+- `none`: record it and stop;
+- `minor`/`major`: update only affected existing docs through the normal docs
+  workflow, with no broad refresh.
+
+Do not run a docs checkpoint merely because a task finished.
+
+## Definition of done and handoff
+
+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.
+
+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.
+
+## 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`.

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

@@ -86,7 +86,8 @@ these mandatory lines:
 
 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. "Do NOT touch files outside this task's `Related Files`."
+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
@@ -150,14 +151,15 @@ 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 `## Evidence` and repository contract (build or affected test
+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 Evidence suite
+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. Classify every failure before acting as exactly one of:
+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;
@@ -172,8 +174,9 @@ sequential fallback according to the task contract.
 
 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 verification receipt citing the worktree gate evidence plus
-the post-merge check result. The Stop completion gate (`spec-gate.cjs`) applies
+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.