okstra 0.172.0 → 0.174.0

package/docs/contributor-change-matrix.md

@@ -10,7 +10,7 @@ Use this matrix before changing high-risk repo contracts. Update the source file
 | Change manager contract | `scripts/okstra_ctl/manager_*.py`, `src/commands/manager.mjs`, `skills/okstra-manager/SKILL.md`, `docs/for-ai/skills/okstra-manager.md`, `docs/cli.md`, `docs/architecture/storage-model.md` | `tests-js/manager.test.mjs`, `tests/test_okstra_manager_*.py` |
 | Add phase | `scripts/okstra_ctl/workflow.py`, `prompts/profiles/`, `validators/`, `tests/` | workflow and validation contract tests |
 | Change worker roster | `prompts/profiles/*.md`, `scripts/okstra_ctl/workers.py`, `tests/contract/test_repo_contracts.py` | worker roster contract tests |
-| Change report section | `schemas/final-report-v1.0.schema.json`, `templates/reports/final-report.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |
+| Change report section | `schemas/final-report-v2.0.schema.json`, `templates/reports/final-report-v2.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |
 | Maintain Korean review mirrors | `config/korean-sources.json`, `tools/korean-sources/` (`lifecycle.mjs` plus its `lifecycle-*.mjs` support modules, CLI/hooks adapters, and shared workflow), `.agents/skills/sync-korean-sources/`, `.claude/skills/sync-korean-sources/` | `tests-js/korean-sources-*.test.mjs` (`lifecycle`, `cli`, `hooks`, and `skill`) |
 
 `runtime/` is build output. Never edit it directly; change source files and rebuild the runtime payload instead.

package/docs/performance-improvement-plan-v2.md

@@ -50,16 +50,17 @@ The current documentation and code contain two layers with similarly named phase
 
 #### Task-type lifecycle
 
-`PHASE_SEQUENCE` in `scripts/okstra_ctl/workflow.py` contains only the following six task types.
+`PHASE_SEQUENCE` in `scripts/okstra_ctl/workflow.py` contains the following task types in order.
 
 | Order | task-type | Responsibility |
 |---|---|---|
 | 1 | `requirements-discovery` | Classify the work category, route safely to the next phase, and identify missing inputs |
 | 2 | `error-analysis` | Analyze symptoms, root-cause hypotheses, reproduction gaps, and verification paths |
-| 3 | `implementation-planning` | Provide at least two implementation options, trade-offs, execution order, validation/rollback, and an approval request |
-| 4 | `implementation` | Execute the approved plan, commit, run verifier checks, and capture rollback evidence |
-| 5 | `final-verification` | Verify acceptability and residual risk, and decide whether to enter release handoff |
-| 6 | `release-handoff` | Perform the commit/push/PR handoff action selected by the user |
+| 3 | `implementation-option-selection` | Compare implementation directions, validate exact coverage, and record the user's selected direction |
+| 4 | `implementation-planning` | Expand the `selected-direction` contract into execution order, validation, rollback, and a separate plan approval request |
+| 5 | `implementation` | Execute the approved plan, commit, run verifier checks, and capture rollback evidence |
+| 6 | `final-verification` | Verify acceptability and residual risk, and decide whether to enter release handoff |
+| 7 | `release-handoff` | Perform the commit/push/PR handoff action selected by the user |
 
 Each okstra invocation performs exactly one task type. Moving to the next task type requires a new invocation.
 

package/docs/project-structure-overview.md

@@ -27,10 +27,10 @@ Current baseline:
 - package version: see `package.json`
 - Node CLI entrypoint: `bin/okstra`
 - Python orchestration authority: `scripts/okstra_ctl/run.py::prepare_task_bundle`
-- lifecycle: `requirements-discovery → error-analysis → implementation-planning → implementation → final-verification → release-handoff`
+- lifecycle: `requirements-discovery → error-analysis → implementation-option-selection → implementation-planning → implementation → final-verification → release-handoff`
 - installed skills: 13
 - provider workers: `claude`, `codex`, `antigravity`, `grok`, `kimi`; functional report writer: `report-writer`
-- final report SSOT: current `schemas/final-report-v2.0.schema.json` + `*.data.json`; schema v1 remains a compatibility contract
+- final report SSOT: `schemas/final-report-v2.0.schema.json` + `*.data.json`
 
 Design principles:
 
@@ -180,6 +180,7 @@ Runtime/install asset changes follow this checklist:
 | `worker-audit-check` | `src/commands/execute/worker-audit-check.mjs` | Apply the Phase 7 worker audit-sidecar rules while the worker session is still alive, so it can fix its own citations (Python: `okstra_ctl.worker_audit_check`, rules in `okstra_ctl.worker_audit_ledger`) |
 | `context-cost` | `src/commands/inspect/context-cost.mjs` | Estimate task bundle file/read context cost |
 | `worktree-lookup` | `src/commands/execute/worktree-lookup.mjs` | Look up a task-key's registered worktree |
+| `worktree-status` | `src/commands/execute/worktree-status.mjs` | Clean-worktree check over source paths only, excluding okstra's provisioned entries and nested stage worktrees (Python: `okstra_ctl.worktree.dirty_entries_excluding_okstra`) |
 | `plan-validate` | `src/commands/execute/plan-validate.mjs` | Check approved-plan approval marker |
 | `render-bundle` | `src/commands/execute/render-bundle.mjs` | Preview `prepare_task_bundle(render_only=True)` |
 | `profile` | `src/commands/inspect/profile-show.mjs` | Print a phase profile with `{{INCLUDE:}}` expanded and its lazy-read sidecars appended transitively, so one grep answers whether a task-type covers a rule — a top-level grep alone returns false negatives (Python: `okstra_ctl.profile_show`). Read-only, unlike `render-bundle` |
@@ -191,7 +192,7 @@ Runtime/install asset changes follow this checklist:
 | `plan-items` | `src/commands/execute/plan-items.mjs` | Internal admin CLI for deterministic plan-body item extraction and exact-match validation (`extract`/`validate`; Python: `okstra_ctl.plan_items_cli`) |
 | `agent-activity` | `src/commands/report/agent-activity.mjs` | Thin Node shim for `okstra_ctl.agent_activity`; `append` records one run-bound activity and `project` writes the validated event projection into final-report data |
 | `report-finalize` | `src/commands/report/finalize.mjs` | Run the whole Phase 7 post-report sequence in contractual order (Python: `okstra_ctl.report_finalize`) — the single reference point shared with the Codex lead adapter |
-| `render-views` | `src/commands/report/render-views.mjs` | Render schema v2 data with its task-specific human template, or use the schema v1 / quick-report compatibility view |
+| `render-views` | `src/commands/report/render-views.mjs` | Render schema v2 data with its task-specific human template, or use the quick-report compatibility view |
 | `render-final-report`, `inject-report-index` | `src/commands/report/*.mjs` | Render version-selected AI handoff Markdown from data.json; v1 index injection remains compatibility-only |
 | `wizard` | `src/commands/execute/wizard.mjs` | Drive the `okstra-run` interactive state machine, including the final outcome envelope |
 | `token-usage` | `src/commands/execute/token-usage.mjs` | Wrap installed Python token usage CLI |
@@ -225,11 +226,10 @@ Top-level scripts:
 | `okstra-wrapper-status.py` | Standalone writer for one worker status sidecar. No longer on the dispatch path — `worker_runner.py` writes the same document in-process |
 | `okstra-token-usage.py` | Token usage CLI entrypoint |
 | `okstra-render-final-report.py` | Render version-selected final-report Markdown from data.json |
-| `okstra-render-report-views.py` | Render schema v2 task-specific HTML directly from data.json, or a legacy view from schema v1 / quick Markdown |
+| `okstra-render-report-views.py` | Render schema v2 task-specific HTML directly from data.json, or a legacy view from quick Markdown |
 | `okstra-error-log.py` | Normalize worker/lead error sidecars |
 | `okstra-spawn-followups.py` | Follow-up spawning helper |
-| `okstra-trace-cleanup.sh` | tmux okstra pane cleanup (worker-agent + worker-compute, excluding the lead pane), called by the lead at every worker round boundary — not once per phase; `--keep <substr>` (repeatable) spares panes whose title contains the substring, which is how an in-flight `report-writer-worker` survives a boundary; `--list` prints what would be reclaimed without killing. Its `--reclaim-completed` mode keyed on trace panes tagged `@okstra_status`; **no code writes that tag any more**, so the mode is inert rather than wrong — the trace panes it reclaimed are no longer created |
-| `okstra-subagent-reclaim.sh` | entry that walks active runs and drives `--reclaim-completed` (wired to the `SubagentStop`/`TaskCompleted` hooks). **Inert for the same reason** — it still runs and matches nothing. Left installed rather than removed: the hooks are already seeded on user machines, so retiring this is a deliberate follow-up |
+| `okstra-trace-cleanup.sh` | Closes the harness-owned worker-agent panes of a run (excluding the lead pane), called by the lead at every worker round boundary — not once per phase; `--keep <substr>` (repeatable) spares panes whose title contains the substring, which is how an in-flight `report-writer-worker` survives a boundary; `--list` prints what would be reclaimed without killing. The tag-driven paths (`--reap`, `--reclaim-completed`, and the `@okstra_worker_run` / `@okstra_trace_run` / `@okstra_status` scan) were removed once nothing wrote those tags — a title scan scoped to the lead's window is all that remains |
 
 ### 4.3 `scripts/okstra_ctl/` — Python orchestration core
 
@@ -239,6 +239,9 @@ Important modules:
 |---|---|
 | `run.py` | `prepare_task_bundle()` single authority and CLI parser; for final-verification it adapts CLI stage input into `FinalVerificationTargetRequest`, maps the acquired target into render context, and owns `verification-target.md` snapshot/digest materialization before manifests and prompts are rendered |
 | `agent_activity.py` | Records activity rows against run-manifest identity, imports validated command evidence from worker audit sidecars, and deterministically projects the current run's `lead-events-*.jsonl` activity rows into `agentActivity[]`. Manifests without `activityContractVersion: 1` are left unchanged. |
+| `exact_coverage.py` | Shared pure calculator for requirement coverage and scope precision in option selection and selected-direction planning |
+| `implementation_options.py` | Option-selection criteria, weighting, candidate fingerprint convergence, ranking, and semantic validation |
+| `implementation_direction.py` | Selected report/response validation, direction snapshot materialization, and selected-direction reference validation |
 | `implementation_stage.py` | `implementation` single-stage run orchestration — read the Stage Lifecycle Snapshot → pick an available Stage Map entry → provision an isolated stage worktree → publish the selected stage as run context (extracted from `run.py`) |
 | `stage_targets.py` | Stage readiness/verification policy SSOT — from the Stage Lifecycle Snapshot (`consumers.jsonl` ledger + carry sidecar backfill + active registry reservation) it decides which stage is runnable, which commit it branches from, and what final-verification checks. `acquire_final_verification_target()` acquires the ledger, registry, worktree, Git, and optional whole-task integration facts behind one task-key mutex and returns a typed target without render-context coupling. `order_stage_closure` topologically sorts (Kahn) the dependency closure of the wizard's multi-selected stage set to produce the unattended `chain-stages` chaining order |
 | `stage_fix_carry.py` | fix-run carry derivation for a re-run on an `implementation` stage whose latest final-report data.json carries verifier `FAIL` verdicts — collects the previous report path, previous run HEAD, failed verifiers, carried blocking findings, and a routing recommendation, which `run.py` renders into the analysis profile through the `{{FIX_RUN_CONTEXT}}` token. A first run, or a re-run after `PASS`, yields no carry and renders the token empty |
@@ -265,9 +268,9 @@ Important modules:
 | `clarification_items.py` | Unified §5 clarification table parser and approval blockers |
 | `md_table.py` | Markdown pipe-table escape/split SSOT — the `mdcell` filter (`escape_pipes`) and the `\|`-aware `split_pipe_row`; shared by the renderer, HTML view, and validators |
 | `qa_commands.py` | QA command deny-list validation for plans |
-| `conformance.py` | validates task-level Tier 3 manifests, parses `QA-RESULT`, detects diff capability surfaces, and reduces results to PASS/ADVISORY/BLOCKING; DB/HTTP/external non-PASS is user-owned advisory while local IO and contract defects remain blocking, enforced by `scripts/okstra_ctl/conformance.py::decide_conformance_gate` and `validators/validate-run.py::_validate_conformance` |
+| `conformance.py` | validates task-level Tier 3 manifests, parses `QA-RESULT`, detects diff capability surfaces, and reduces results to PASS/ADVISORY/BLOCKING; DB/HTTP/external non-PASS is user-owned advisory while local IO and contract defects remain blocking, enforced by `scripts/okstra_ctl/conformance.py::decide_conformance_gate` and `validators/validate-run.py::_validate_conformance`. Also the single definition of the plan's `Conformance tests:` declaration format (`parse_conformance_tests`, `malformed_conformance_stages`), read both at the approval boundary (`run.py::_validate_approved_plan`) and at the end of an implementation run (`validators/validate-run.py`) so the two cannot disagree |
 | `pr_template.py` | PR body template resolution for release-handoff |
-| `report_views.py`, `render_final_report.py`, `final_report_schema.py` | Versioned final-report contract: schema v2 data independently produces AI handoff Markdown and human HTML; schema v1 keeps the legacy Markdown/view pipeline |
+| `report_views.py`, `render_final_report.py`, `final_report_schema.py` | Final-report contract: schema v2 data independently produces AI handoff Markdown and human HTML |
 | `report_markdown.py` | Schema-ordered Markdown serialisation of a data.json subtree for the AI handoff report — headings, tables for uniform row sets, prose for narrative fields; field order read from the schema, not from the mapping |
 | `final_report_paths.py`, `report_view_artifacts.py` | Path-helper SSOT for the final-report markdown/data.json pair and the generated view artifacts (HTML view, user-responses directory) |
 | `wizard.py` | `okstra-run` prompt state machine; user-facing Korean strings live in `prompts/wizard/prompts.ko.json` |
@@ -287,7 +290,7 @@ Important modules:
 | `code_review_paths.py` | filesystem-layout SSOT for code-review result files — `stage_review_dir` / `branch_review_dir` plus `next_stage_review` / `next_branch_review`, which read the existing files to derive the next round's name (`stage-<NN>.md`, then `-r2`, `-r3`, …) or the next same-day sequence (`<YYYY-MM-DD>-<NN>.md`), so skill markdown never re-derives a literal review path |
 | `code_review_target.py` | `okstra code-review target` backend — argument validation and JSON shaping only. Stage mode delegates whole to `okstra_project.state.code_review_target_snapshot`; branch mode is resolved here, defaulting the diff base to the merge-base with the default branch (`refs/remotes/origin/HEAD`, else `main`/`master`). Read-only: it never creates the review directory |
 | `session.py`, `tmux.py`, `seeding.py`, `locks.py`, `invocation.py`, `sequence.py`, `ids.py`, `material.py` | Supporting lifecycle helpers |
-| `pane_reclaim.py` | decides which completed trace panes are reclaim targets; imports the in-progress status set from the `reconcile.NON_TERMINAL_RECENT_STATUSES` SSOT. Inert alongside `--reclaim-completed` — no trace pane is created any more — but still the owner of that decision if the mechanism returns |
+| `pane_reclaim.py` | resolves which in-progress runs of the current project the `SessionStart(compact)` hook should re-inject the pane-cleanup obligation for; imports the in-progress status set from the `reconcile.NON_TERMINAL_RECENT_STATUSES` SSOT. The completed-pane decision it also used to own went away with `--reclaim-completed` |
 | `improvement_lenses.py` | lens enum SSOT + cap constants for the improvement-discovery phase (DEFAULT 8, ABSOLUTE 12, MIN/MAX PRIORITY 1/4, SOURCE_WORKERS) |
 | `improvement_assignment.py` | improvement-discovery primary-pass lens assignment — round-robins the resolved `requiredWorkerRoles` order over the resolved priority lenses (`assign_primary_lenses`) and validates the resulting map (`validate_primary_lens_assignments`). Only the primary pass rotates; every analyser still confirms the full lens set afterwards |
 | `container.py` | the `okstra container` convergence entrypoint of the okstra-container-build public skill — `provision_container_group` + `up`/`status`/`logs`/`stop-watcher`/`down` dispatch, env-override synthesis, compose argv assembly, and per-container watcher startup |
@@ -330,7 +333,7 @@ Important modules:
 | `plan_derivations.py` | the supersession sweep `_common-contract.md` requires an author to do by hand — extracts the symbols, paths, and ids an answered clarification names and reports every plan string that mentions one. Advisory: it locates candidates and never judges which are now false |
 | `scope_provenance.py` | single source of truth for the scope-provenance grammar every phase-emitted requirement must declare, shared by `validators/validate-run.py` and `validators/validate_fanout.py` so the planning report and fan-out packets cannot drift |
 | `worker_artifact_paths.py` | canonical worker artifact path derivation (e.g. `audit_sidecar_rel` inserts `-audit-` after the first `-worker-` token), so dispatch and validation agree on non-canonical-path rejection |
-| `report_finalize.py` | Phase 7 post-report sequence **SSOT** — runs `check-source` → `token-usage` → `render-views` → `spawn-followups` → `validate-run` in that load-bearing order, stops at the first non-zero exit and names the failing step. Both lead paths converge here: the Codex adapter calls it in-process (`codex_dispatch`), a Claude-led run reaches it through `okstra report-finalize`. Neither reimplements the sequence |
+| `report_finalize.py` | Phase 7 post-report sequence **SSOT** — runs `check-source` → `token-usage` → `render-views` → `spawn-followups` → `validate-run` in that load-bearing order, stops at the first non-zero exit and names the failing step — except `token-usage`, whose failure defers so the later steps still produce their artifacts. Both lead paths converge here: the Codex adapter calls it in-process (`codex_dispatch`), a Claude-led run reaches it through `okstra report-finalize`. Neither reimplements the sequence |
 | `wrapper_status.py` | worker wrapper status sidecar reader — the host-side reader of the sidecar `worker_runner.py` writes. `is_terminal` is the one question it answers for the dispatch record and the pane reclaim: does `stage` read `exited` |
 | `worker_runner.py` | runs one worker CLI and records what happened — shared by every provider entrypoint. Owns the `selectors` pump over the child's streams, the stream-arrival idle watchdog (`killpg` on breach), the run-wide progress cap on the log copy, and the status sidecar's whole life. A run that dies after launch still closes its sidecar, so `worker_liveness` never reads a dead worker as running |
 | `worker_request.py` | assembles the `WorkerExecRequest` every strategy then takes on trust: resolved paths, the write scope in the order the CLIs are told it (project root → stage tree → the tree's git-common-dir), the verifier's toolchain grants, and the role's idle budget |
@@ -365,9 +368,10 @@ Token/cost accounting:
 | Path | Role |
 |---|---|
 | `launch.template.md` | Lead prompt template rendered for each run |
-| `duties/common.md`, `duties/<audience>.md` | Canonical common and functional duty contracts composed into every Okstra-owned LLM invocation; provider/model identity does not select the duty |
+| `duties/common.md`, `duties/<audience>.md` | Canonical common and functional duty contracts composed into every Okstra-owned LLM invocation; `direction-selection-worker` owns direction comparison/validation while `planning-worker` realizes the selected direction; provider/model identity does not select the duty |
 | `profiles/_common-contract.md` | Shared phase contract |
 | `profiles/<task-type>.md` | Phase profiles (single language — runtime always loads from `profiles/`, never a translated mirror) |
+| `implementation-option-selection.md` | Read-only lifecycle profile for candidate comparison or preselected-direction validation before detailed planning |
 | `project-analysis.md`, `feature-analysis.md`, `change-impact-analysis.md` | Read-only sidetrack profiles for project mapping, one-feature behavior tracing, and proposed-change impact mapping |
 | `wizard/prompts.ko.json` | Korean wizard prompt single source of truth |
 
@@ -375,10 +379,10 @@ Token/cost accounting:
 
 | Path | Role |
 |---|---|
-| `templates/reports/final-report.template.md` | Schema v1 compatibility Markdown template |
+| `templates/reports/final-report-v2.template.md` | AI handoff Markdown spine |
 | `templates/reports/final-report-v2.template.md` | Schema v2 AI handoff Markdown spine |
-| `templates/reports/md/tasks/*.template.md`, `md/macros/sections.md` | Ten dedicated task bodies for the AI handoff Markdown, sibling of `html/tasks/`; shared section macro |
-| `templates/reports/html/base.template.html`, `html/tasks/*.template.html` | Shared HTML shell plus ten dedicated task templates for human reports; task bodies are not shared |
+| `templates/reports/md/tasks/*.template.md`, `md/macros/sections.md` | Eleven dedicated task bodies for the AI handoff Markdown, sibling of `html/tasks/`; shared section macro |
+| `templates/reports/html/base.template.html`, `html/tasks/*.template.html` | Shared HTML shell plus eleven dedicated task templates for human reports; task bodies are not shared |
 | `templates/reports/report.css`, `report.js` | Inline assets for self-contained HTML report views |
 | `templates/reports/*.template.md` | Inputs, schedule, user-response, settings templates |
 | `project-analysis-input.template.md`, `feature-analysis-input.template.md`, `change-impact-analysis-input.template.md` | Brief input templates for the three analysis sidetracks |
@@ -391,7 +395,7 @@ Token/cost accounting:
 
 ### 4.8 `schemas/`
 
-`schemas/final-report-v2.0.schema.json` is the current final-report data.json contract. The report-writer worker writes `final-report-<task-type>-<seq>.data.json`; independent renderers produce AI handoff Markdown and task-specific human HTML. `schemas/final-report-v1.0.schema.json` remains supported for existing reports and quick-report compatibility.
+`schemas/final-report-v2.0.schema.json` is the current final-report data.json contract. The report-writer worker writes `final-report-<task-type>-<seq>.data.json`; independent renderers produce AI handoff Markdown and task-specific human HTML.
 
 The deterministic convergence inputs are `schemas/convergence-groups-v1.0.schema.json`, `schemas/convergence-round-results-v1.0.schema.json`, and `schemas/convergence-critic-results-v1.0.schema.json`. `tools/build.mjs` syncs the entire source `schemas/` directory to `runtime/schemas/`; these JSON Schema files are runtime contracts, not Markdown publication-inventory entries.
 
@@ -404,7 +408,7 @@ Optional (v1.0 backward-compatible) top-level keys:
 
 | File | Role |
 |---|---|
-| `validate-run.py` | Version-aware run/final-report validation: schema v2 AI handoff order + structured data rules, with legacy schema v1 Markdown gates preserved |
+| `validate-run.py` | Run/final-report validation: schema v2 AI handoff order + structured data rules |
 | `validate-brief.py`, `validate-brief.sh` | Brief frontmatter/body contract validation |
 | `validate-report-views.py` | HTML view validation (form-control placement / no external URLs / stale source digest / Response ID parity) |
 | `validate_analysis_report.py` | Cross-field validation for the three read-only analysis reports: frozen target/evidence snapshots, current-code evidence, review-source identity, and exact affected-ID resolution coverage on revision reruns |
@@ -492,10 +496,11 @@ they are not published user skills.
 3. Resolve task identity segments, work category, and the run sequence input needed for path allocation.
 4. Provision or reuse the task-key worktree, or the selected implementation stage worktree for stage-isolated runs.
 5. For an analysis sidetrack, resolve the immutable source commit from the provisioned worktree's `HEAD`, then resolve evidence reports, freshness, and the feature target through `analysis_inputs.py`.
-6. Compute task/run paths and persist run context under `runs/<task-type>/manifests/`.
-7. Materialize `instruction-set/` files and lead prompt snapshot.
-8. Persist run inputs, team state, task manifest, task index, run manifest, timeline, discovery pointers.
-9. Record the run in `~/.okstra/{active,recent}.jsonl` and project index.
+6. For a new `implementation-planning` run, validate `--selected-direction` and materialize `instruction-set/selected-direction.json`; a same-task planning rerun validates its prior planning report instead.
+7. Compute task/run paths and persist run context under `runs/<task-type>/manifests/`.
+8. Materialize `instruction-set/` files and lead prompt snapshot.
+9. Persist run inputs, team state, task manifest, task index, run manifest, timeline, discovery pointers.
+10. Record the run in `~/.okstra/{active,recent}.jsonl` and project index.
 
 ### 5.2 Worktree model
 
@@ -532,7 +537,7 @@ Current report pipeline:
 4. For implementation-planning, `okstra plan-items extract` creates the complete `P-*` queue, `validate` proves it still matches data.json, and the analyser instances run the separate plan-body verification round.
 5. `scripts/okstra-render-final-report.py` renders compact AI handoff Markdown with `templates/reports/final-report-v2.template.md`.
 6. Token usage substitution fills usage/cost cells.
-7. `scripts/okstra-render-report-views.py` independently selects one of ten dedicated task templates and emits human-facing HTML directly from the same data.json; run validation checks both derived artifacts. Schema v1 and quick Markdown inputs retain their legacy conditional path.
+7. `scripts/okstra-render-report-views.py` independently selects one of eleven dedicated task templates and emits human-facing HTML directly from the same data.json; run validation checks both derived artifacts. A quick Markdown input retains its legacy conditional path.
 
 For the three analysis sidetracks, the HTML view also exports an immutable-source `## ANALYSIS REVIEW` sidecar. A revision rerun carries that sidecar, reanalyzes the whole confirmed scope, and records one `analysisReviewResolution` row for every affected ID before `validate_analysis_report.py` accepts the result.
 
@@ -612,9 +617,10 @@ Project-local `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a s
 
 | Phase | Purpose | Typical next step |
 |---|---|---|
-| `requirements-discovery` | Classify and route work | `error-analysis` or `implementation-planning` |
-| `error-analysis` | Reproduce and explain failure | `implementation-planning` |
-| `implementation-planning` | Compare options, produce approval-ready plan; the output is always the `## 5.5 Stage Map` + N `## 5.5.<i> Stage <i>` section structure. `implementation` can be split and run per stage | `implementation` after approval |
+| `requirements-discovery` | Classify and route work | `error-analysis` or `implementation-option-selection` |
+| `error-analysis` | Reproduce and explain failure | `implementation-option-selection` |
+| `implementation-option-selection` | Compare or validate directions; display at most three exact-coverage candidates | `implementation-planning` after direction confirmation |
+| `implementation-planning` | Realize one selected direction as an approval-ready Stage Map and exact-coverage plan | `implementation` after separate plan approval, or `implementation-option-selection` if invalidated |
 | `implementation` | Executor changes code, verifiers check independently | `final-verification` |
 | `final-verification` | Read-only acceptance verification | `release-handoff` if accepted |
 | `release-handoff` | User-selected commit/PR handoff | done or follow-up |
@@ -652,6 +658,8 @@ Edit English canonical Markdown sources directly. After changing a path register
 | `S-NNN` | Secondary evidence or alternate interpretation |
 | `R-NNN` | Missing information / risk |
 | `RR-NNN` | Residual risk |
+| `IO-NNN` | Ranked or audited implementation direction in option selection |
+| `P-Dir-1` | Selected direction realization item used by plan-body verification |
 | `P-Opt-*` | Plan option item used by plan-body verification |
 | `P-Step-*` | Plan execution step item |
 | `P-Dep-*` | Plan dependency / migration item |
@@ -660,7 +668,7 @@ Edit English canonical Markdown sources directly. After changing a path register
 | `FU-NNN` | Follow-up task |
 | `worker:item` | Source item pointer preserved from worker result into final report |
 | `Verdict Token` | `accepted`, `conditional-accept`, `blocked`, `not-applicable` |
-| `Direction` | `continue-investigation`, `begin-implementation`, `approve`, `reject`, `hold` |
+| `Direction` | `continue-investigation`, `begin-option-selection`, `begin-implementation`, `approve`, `reject`, `hold` |
 
 Clarifications now live in the unified `## 1. Clarification Items` table. Deprecated `5.1` / `5.2` split sections are no longer part of the schema.
 

package/docs/task-process/README.md

@@ -40,7 +40,8 @@ flowchart TD
 |---|---|---|
 | `requirements-discovery` | [requirements-discovery.md](requirements-discovery.md) | Classify the request and choose the next safe phase. |
 | `error-analysis` | [error-analysis.md](error-analysis.md) | Find cause candidates and validation paths from symptoms and evidence. |
-| `implementation-planning` | [implementation-planning.md](implementation-planning.md) | Produce a plan with implementation options, verification, rollback, and an approval gate. |
+| `implementation-option-selection` | [implementation-option-selection.md](implementation-option-selection.md) | Compare or validate exact-coverage directions before detailed planning. |
+| `implementation-planning` | [implementation-planning.md](implementation-planning.md) | Realize one selected direction as an exact-coverage plan with a separate approval gate. |
 | `implementation` | [implementation.md](implementation.md) | The executor implements the approved plan and the verifier verifies it independently. |
 | `final-verification` | [final-verification.md](final-verification.md) | Judge whole-task or single-stage acceptance of the implementation result. |
 | `release-handoff` | [release-handoff.md](release-handoff.md) | Perform the push/PR handoff lead-only after an accepted verdict. |
@@ -62,15 +63,16 @@ flowchart TD
 | worker roster parser | [`scripts/okstra_ctl/workers.py`](../../scripts/okstra_ctl/workers.py) |
 | lead operating contract | [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md) |
 | phase profiles | [`prompts/profiles/`](../../prompts/profiles/) |
-| final report shape / HTML view | [`templates/reports/final-report.template.md`](../../templates/reports/final-report.template.md), [`scripts/okstra_ctl/report_views.py`](../../scripts/okstra_ctl/report_views.py) |
+| final report shape / HTML view | [`templates/reports/final-report-v2.template.md`](../../templates/reports/final-report-v2.template.md), [`scripts/okstra_ctl/report_views.py`](../../scripts/okstra_ctl/report_views.py) |
 
 ## 5. Quick comparison table
 
 | task-type | wizard special question | runtime prepare gate | lead/worker mode | next phase default |
 |---|---|---|---|---|
 | `requirements-discovery` | common questions only | profile/brief/base-ref exist | multi-worker analysis, convergence 1 round default | `pending-routing-decision` |
-| `error-analysis` | common questions only | profile/brief/base-ref exist | multi-worker analysis, convergence 2 rounds default | `implementation-planning` |
-| `implementation-planning` | common questions only | profile/brief/base-ref exist | multi-worker analysis + Phase 6 plan-body verification | `implementation` |
+| `error-analysis` | common questions only | profile/brief/base-ref exist | multi-worker analysis, convergence 2 rounds default | `implementation-option-selection` |
+| `implementation-option-selection` | comparison or preselected-validation context | stable brief IDs and at least three analysers | read-only candidate validation, exact coverage, separate direction confirmation | `implementation-planning` or `blocked` |
+| `implementation-planning` | selected-direction report for a new plan | selection report/sidecar/digest or same-task planning rerun | one-direction realization + Phase 6 plan-body verification | `implementation` after plan approval |
 | `implementation` | approved plan, stage multi-pick, executor | approved marker, Stage Lifecycle Snapshot, stage-key reservation, QA command deny-list | one run = one stage; executor writes in isolated stage worktree, verifiers read-only | `final-verification` |
 | `final-verification` | approved plan, stage pick (whole-task or single-stage) | `VERIFICATION_TARGET` resolved; whole-task auto integration/teardown or single-stage worktree reuse | whole-task may integrate stages first; analyser verification itself is read-only | `pending-release-handoff` |
 | `release-handoff` | handoff scope (stage-group or whole-task), PR template override/scope | Stage Lifecycle Snapshot eligibility, generated `release-handoff-input.md`, empty worker roster | single-lead; whole-task PR or stage-group collector branch/PR | `done-or-follow-up` |

package/docs/task-process/error-analysis.md

@@ -57,7 +57,7 @@ sequenceDiagram
 
 For canonical briefs, preflight runs before worker resolution, worktree provisioning, or report creation. A brief whose `reporter-confirmations` status is `pending` stops at this point; legacy briefs keep the compatibility path.
 
-The final report records its next phase in `errorAnalysis.routing.nextTaskType`. After report validation passes, workflow metadata persists that route as `nextRecommendedPhase`. The static `error-analysis` → `implementation-planning` mapping is a fallback only when report data is missing, legacy, or not an error-analysis report.
+The final report records its next phase in `errorAnalysis.routing.nextTaskType`. After report validation passes, workflow metadata persists that route as `nextRecommendedPhase`. A credible cause uses `implementation-option-selection`; continued investigation uses `error-analysis`. The static fallback also routes a missing or legacy error-analysis report to option selection.
 
 ## 4. lead execution flow
 
@@ -92,7 +92,7 @@ The expected final-report content is:
 - practical next diagnostic steps
 - if there is blocking uncertainty, `## 1. Clarification Items`, usually `Blocks=next-phase`
 
-For `error-analysis`, the structured `errorAnalysis` object is the source of truth for the verbatim symptom, reproduction status, `EA-NNN` cause candidates and their counter-evidence, the next diagnostic, and routing. Its shape is enforced by `schemas/final-report-v1.0.schema.json` `$defs.ErrorAnalysis`; `validators/validate-run.py::_validate_error_analysis_consistency` enforces the cross-field semantics. A route to `implementation-planning` needs a credible referenced leading cause and `begin-planning`. A route back to `error-analysis` needs the sharp next diagnostic and `continue-investigation`.
+For `error-analysis`, the structured `errorAnalysis` object is the source of truth for the verbatim symptom, reproduction status, `EA-NNN` cause candidates and their counter-evidence, the next diagnostic, and routing. Its shape is enforced by the final-report schema; `validators/validate-run.py::_validate_error_analysis_consistency` enforces the cross-field semantics. A route to `implementation-option-selection` needs a credible referenced leading cause and `begin-option-selection`. A route back to `error-analysis` needs the sharp next diagnostic and `continue-investigation`.
 
 What is prohibited is source edit, refactor, fix attempt, implementation design artifact, and running build/migration/deploy. Deferring ambiguity that could be answered from code or logs to a user question is also a defect per the profile.
 

package/docs/task-process/final-verification.md

@@ -112,7 +112,7 @@ flowchart TD
     Verdict{Verdict Token}
     Verdict -->|accepted| Release[route to release-handoff or done]
     Verdict -->|conditional-accept| Conditions[conditions listed exhaustively]
-    Conditions --> Followup[route to error-analysis or implementation-planning]
+    Conditions --> Followup[route by cause, direction, or detailed-plan defect]
     Verdict -->|blocked| Blockers[acceptance blockers with evidence]
     Blockers --> Followup
 ```
@@ -165,7 +165,7 @@ flowchart TD
     FV -. forbidden .-> Hide[hide verifier dissent]
 ```
 
-The stage merge/teardown of whole-task mode is a runtime-owned integration step that prepare performs. After that, lead verification is read-only. Source edit, follow-up fix, and scope expansion are all forbidden. When a defect is found, it is not fixed within the current run; instead it is recorded as a blocker in the final report and handed off as new `error-analysis` or `implementation-planning` input.
+The stage merge/teardown of whole-task mode is a runtime-owned integration step that prepare performs. After that, lead verification is read-only. Source edit, follow-up fix, and scope expansion are all forbidden. When a defect is found, it is not fixed within the current run. Cause defects route to `error-analysis`, selected-direction defects route to `implementation-option-selection`, and detailed-plan defects route to `implementation-planning`.
 
 ## 8. Verified code
 

package/docs/task-process/implementation-option-selection.md

@@ -0,0 +1,70 @@
+# implementation-option-selection process
+
+## Index
+
+- [1. Purpose](#1-purpose)
+- [2. Execution modes](#2-execution-modes)
+- [3. Prepare gates](#3-prepare-gates)
+- [4. Candidate validation and ranking](#4-candidate-validation-and-ranking)
+- [5. Direction confirmation and planning handoff](#5-direction-confirmation-and-planning-handoff)
+- [6. Forbidden actions](#6-forbidden-actions)
+- [7. Verified code](#7-verified-code)
+
+## 1. Purpose
+
+`implementation-option-selection` is the read-only lifecycle phase between cause analysis and detailed planning. It decides which implementation mechanism and architecture boundary planning may realize. It does not name the exact file list, split stages, or prescribe test commands.
+
+Direction confirmation and detailed plan approval are independent user decisions. Confirming a direction permits planning to begin. It does not approve the plan or permit implementation.
+
+## 2. Execution modes
+
+| Mode | Input | Output |
+|---|---|---|
+| `candidate-comparison` | Requirement ledger, cause evidence, code evidence, independently proposed raw candidates | At most three ranked valid directions and a separate user selection |
+| `preselected-validation` | A direction already fixed by upstream evidence or an explicit user instruction | One normalized and validated direction, or `blocked`; no alternative is generated |
+
+The normal analyser roster contains at least three analyser workers plus the report writer. Each analyser may propose at most three raw candidates. All analysers reassess the merged candidate set before ranking.
+
+## 3. Prepare gates
+
+Prepare rejects the phase when the brief has no stable `EB-NNN`, `PB-NNN`, or `EO-NNN` requirement IDs. External Gates are not part of that denominator. Prepare also rejects a roster with fewer than three analysers.
+
+The phase reuses the task-key worktree and may inspect the code and prior task artifacts. It does not obtain a writable implementation-stage worktree.
+
+## 4. Candidate validation and ranking
+
+Every displayed candidate has all of the following properties:
+
+- `coveragePercent == 100`
+- `scopePrecisionPercent == 100`
+- `coverageVerdict == exact`
+- no `unmappedCommitments`
+- no `contradictedRequirements`
+- supporting code or upstream evidence
+- at least two feasibility votes
+- no safety blocker or unresolved implementation-critical external fact
+
+The final report can display one, two, or three valid candidates. Rejected candidates remain in `candidateAudit` with their rejection reasons and cannot be selected. If no candidate is valid, the report uses `blocked` and planning cannot start.
+
+Ranking uses eight fixed criteria with per-run weights: requirement fit, architecture fit, change locality, implementation complexity, correctness risk, reversibility, verification cost, and rollout cost. Safety and exact-coverage failures override the weighted score.
+
+## 5. Direction confirmation and planning handoff
+
+Comparison mode exports a `DIRECTION SELECTION` block in the user-response sidecar. Prepare validates the selected ID against the displayed candidates and binds the response to the report's sibling data JSON through its SHA-256 digest.
+
+A new planning run receives the selection report through `--selected-direction`. Prepare normalizes the validated choice into `instruction-set/selected-direction.json`. Planning cites that snapshot through `selectedDirectionRef` and writes `approved: false` until the user separately approves the detailed plan.
+
+If planning proves that the mechanism or architecture boundary cannot satisfy exact coverage, it emits `direction-invalidated` and routes back to `implementation-option-selection`. It never picks the next ranked direction automatically.
+
+## 6. Forbidden actions
+
+This phase does not edit source code, run builds or tests, execute migrations, deploy, or call a write API. Candidate details do not contain exact file lists, stage maps, or test commands. Those details belong to `implementation-planning` after direction confirmation.
+
+## 7. Verified code
+
+- [`prompts/profiles/implementation-option-selection.md`](../../prompts/profiles/implementation-option-selection.md)
+- [`prompts/duties/direction-selection-worker.md`](../../prompts/duties/direction-selection-worker.md)
+- [`scripts/okstra_ctl/implementation_options.py`](../../scripts/okstra_ctl/implementation_options.py)
+- [`scripts/okstra_ctl/implementation_direction.py`](../../scripts/okstra_ctl/implementation_direction.py)
+- [`scripts/okstra_ctl/exact_coverage.py`](../../scripts/okstra_ctl/exact_coverage.py)
+- [`validators/validate-run.py`](../../validators/validate-run.py)

package/docs/task-process/implementation-planning.md

@@ -12,7 +12,9 @@
 
 ## 1. Purpose
 
-`implementation-planning` is the phase that decides the implementation direction before coding. It produces at least two implementation options, trade-offs, a recommended option, a stepwise execution order, a validation checklist, and a rollback strategy, and it places a user approval gate.
+`implementation-planning` realizes one direction that was already confirmed by `implementation-option-selection`. It turns that mechanism and architecture boundary into a file-level Stage Map, validation checklist, rollback strategy, and exact requirement-coverage map. The resulting detailed plan has its own approval gate; direction confirmation does not approve it.
+
+An existing plan without `planningContract: selected-direction` remains on the legacy candidate-plan contract for compatibility. A new planning run uses the selected-direction contract and does not generate or rank alternatives.
 
 ## 2. okstra-run wizard flow
 
@@ -20,7 +22,11 @@
 flowchart TD
     Start[/okstra-run/] --> Common[common task identity flow]
     Common --> Type[task-type = implementation-planning]
-    Type --> Worktree{active task worktree?}
+    Type --> Input{new plan or planning rerun?}
+    Input -->|new| Direction[selected-direction report pick]
+    Input -->|rerun| Prior[prior planning report via clarification-response]
+    Direction --> Worktree{active task worktree?}
+    Prior --> Worktree
     Worktree -->|yes| Defaults[Use defaults / Customize]
     Worktree -->|no| BaseRef[base-ref pick/text]
     BaseRef --> Defaults
@@ -33,7 +39,7 @@ flowchart TD
     Confirm --> Render[render-bundle]
 ```
 
-The wizard currently does not ask about `--no-plan-verification`. On the okstra-run path, plan-body verification is prepared as enabled by default. The shell/CLI path has a `--no-plan-verification` flag.
+For a new plan, the wizard asks for a validated option-selection report and passes it as `--selected-direction`. A planning clarification rerun passes its own prior report through `--clarification-response`. The wizard currently does not ask about `--no-plan-verification`; on the okstra-run path, plan-body verification is prepared as enabled by default.
 
 ## 3. prepare_task_bundle handling
 
@@ -44,8 +50,10 @@ sequenceDiagram
     participant R as render.py
     participant M as manifests
 
-    W->>P: task-type=implementation-planning
+    W->>P: task-type=implementation-planning + selected-direction or prior planning report
     P->>P: validate profile/brief/base-ref
+    P->>P: validate selection report, data digest, response, and selected option
+    P->>M: write instruction-set/selected-direction.json
     P->>P: resolve profile workers + optional override
     P->>P: resolve model metadata
     P->>P: provision/reuse task worktree
@@ -55,7 +63,7 @@ sequenceDiagram
     P-->>W: prepared lead prompt
 ```
 
-The runtime prepare stage does not block source edits itself; instead it "bakes the current phase boundary into the lead prompt and manifest." The actual no-edit/no-build rules must be honored by the lead and workers reading the profile.
+Prepare rejects a new plan without a selected-direction report. Comparison mode requires a valid `DIRECTION SELECTION` sidecar, while preselected-validation mode uses the confirmed upstream direction without one. The normalized snapshot binds the source report, source-data digest, option ID, direction body, requirements, and invariants.
 
 ## 4. lead execution flow
 
@@ -72,8 +80,8 @@ flowchart TD
     RW --> Extract[Deterministic plan-item extraction]
     Extract --> PBV[Phase 6 sub-step<br/>Plan-body verifier round]
     PBV --> Gate{gate result}
-    Gate -->|passed / passed-with-dissent| Approval[render top Approval checkbox]
-    Gate -->|blocked-by-disagreement / aborted-non-result| NoApproval[render block without checkbox]
+    Gate -->|passed / passed-with-dissent| Approval[render plan decision approval control]
+    Gate -->|blocked-by-disagreement / aborted-non-result| NoApproval[render blocked plan decision]
     Approval --> P7[Phase 7 persistence/finalization<br/>canonical Markdown render<br/>HTML render + validate-run<br/>via okstra report-finalize]
     NoApproval --> P7
 ```
@@ -118,9 +126,8 @@ Plan approval and design-preparation status are independent gates. If plan-body
 
 ```mermaid
 flowchart LR
-    Options[Option Candidates] --> Matrix[Trade-off Matrix]
-    Matrix --> Rec[Recommended Option]
-    Rec --> Stages[Stage Map + Stage Exit/Validation]
+    Direction[Selected Direction Snapshot] --> Realize[Direction Realization]
+    Realize --> Stages[Stage Map + Stage Exit/Validation]
     Stages --> Prep[Implementation Design Preparation]
     Prep --> Dep[Dependency / Migration Risk]
     Dep --> Val[Validation Checklist]
@@ -130,11 +137,10 @@ flowchart LR
     Approval --> Impl[Next run: implementation]
 ```
 
-Because the validator searches for the English substring of the section heading, the following strings must remain verbatim on the heading line.
+The selected-direction branch verifies `P-Dir-1` before its stage, dependency, validation, rollback, requirement, preparation, and variation items. `P-Dir-1` proves that the plan preserves the selected mechanism, architecture boundary, invariants, and user constraints. The legacy branch continues to extract `P-Opt-*` from its option candidates.
+
+The detailed selected-direction plan retains these deliverable surfaces:
 
-- `Option Candidates`
-- `Trade-off`
-- `Recommended Option`
 - `Stage Map`
 - `Stage Exit Contract`
 - `Stage Validation`
@@ -146,7 +152,9 @@ Because the validator searches for the English substring of the section heading,
 - `Requirement Coverage`
 - `Implementation Design Preparation`
 
-Approval is recorded with `approved: true` in the YAML frontmatter and the chosen `implementation-option`. If a `Blocks=approval` clarification row is unresolved, the implementation prepare rejects it even when the frontmatter is in an approved state. The `blocked` status of design-preparation is not the same as `Blocks=approval`, and it operates only at that stage's implementation preflight.
+Approval is recorded with `approved: true` in YAML frontmatter. A selected-direction plan has no `implementation-option:` field and rejects `--implementation-option` before any approval-file mutation. If a `Blocks=approval` clarification row is unresolved, implementation prepare rejects the plan even when frontmatter is approved. Existing candidate plans keep their legacy option field and execution behavior.
+
+`plan-ready` requires 100% requirement coverage, 100% scope precision, and no unmapped stage or file change. If the selected mechanism or boundary cannot meet those conditions, planning emits `direction-invalidated` without an executable Stage Map and routes back to `implementation-option-selection`. It does not choose another direction automatically.
 
 ## 6. Forbidden actions
 
@@ -165,7 +173,7 @@ This phase only produces the plan document. Code-level micro-optimization, sourc
 
 - [`prompts/profiles/implementation-planning.md`](../../prompts/profiles/implementation-planning.md)
 - [`templates/reports/implementation-planning-input.template.md`](../../templates/reports/implementation-planning-input.template.md)
-- [`templates/reports/final-report.template.md`](../../templates/reports/final-report.template.md)
+- [`templates/reports/final-report-v2.template.md`](../../templates/reports/final-report-v2.template.md)
 - [`scripts/okstra_ctl/render.py`](../../scripts/okstra_ctl/render.py)
 - [`validators/validate-run.py`](../../validators/validate-run.py)
 - [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)

package/docs/task-process/requirements-discovery.md

@@ -11,7 +11,7 @@
 
 ## 1. Purpose
 
-`requirements-discovery` classifies the request before implementation. It determines which of bugfix, feature, improvement, refactor, or ops it is, and chooses whether the next safe phase is `error-analysis` or `implementation-planning`. Going directly to `implementation` is not valid per the profile. Implementation can only start once an approved `implementation-planning` report exists.
+`requirements-discovery` classifies the request before implementation. It determines which of bugfix, feature, improvement, refactor, or ops it is, and chooses whether the next safe phase is `error-analysis` or `implementation-option-selection`. Going directly to planning or implementation is not valid for a new direction. Implementation can only start once a selected direction has been expanded into a separately approved `implementation-planning` report.
 
 ## 2. okstra-run wizard flow
 
@@ -90,7 +90,7 @@ flowchart LR
     RD --> Domain[Domain Alignment<br/>terminology resolution]
     RD --> Route{next safe phase}
     Route --> EA[error-analysis]
-    Route --> IP[implementation-planning]
+    Route --> IOS[implementation-option-selection]
     Route -. invalid .-> Impl[implementation<br/>not allowed directly]
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.172.0",
+  "version": "0.174.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.172.0",
-  "builtAt": "2026-08-15T19:49:27.306Z",
+  "package": "0.174.0",
+  "builtAt": "2026-08-17T05:25:03.210Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/claude-worker.md

@@ -64,7 +64,7 @@ Before producing any output, you MUST:
 2. Read every primary input file the lead enumerated under `## Inputs` (or equivalent heading) end-to-end, following the selected preamble. Analysis workers normally receive `analysis-packet.md`; implementation workers receive their role sidecar and approved deliverable inputs.
 3. When the prompt carries `**Evidence ledger:** required-v1`, follow the selected preamble's `Evidence read ledger` procedure for every claim-evidence file you open. Do not invent a separate audit-row format here.
 
-**Heartbeat — write the audit sidecar EARLY and APPEND per stage (BLOCKING).** This worker runs as an in-process Agent or a fresh-session tmux pane, so the lead has no `BashOutput`-style liveness signal while it waits for your return — the audit sidecar is the only signal that survives a silent hang.
+**Heartbeat — write the audit sidecar EARLY and APPEND per stage (BLOCKING).** This worker runs as an in-process Agent, a cmux surface, or a CLI wrapper subprocess, so the lead has no `BashOutput`-style liveness signal while it waits for your return — the audit sidecar is the only signal that survives a silent hang.
 
 - **Where:** the absolute path in `**Audit sidecar path:**`.
 - **Start (before the per-file reads):** immediately after extracting `Project Root` and the assigned paths, `Write` just the heading line (`# Claude Worker Audit — <task-key>`) plus one `- PROGRESS: started <ISO-8601-UTC>` line.