okstra 0.171.0 → 0.173.0

package/docs/project-structure-overview.md

@@ -27,7 +27,7 @@ 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
@@ -189,6 +189,7 @@ Runtime/install asset changes follow this checklist:
 | `team` | `src/commands/execute/team.mjs` | External lead tmux-pane worker dispatch / await / teardown |
 | `convergence` | `src/commands/execute/convergence.mjs` | Internal admin CLI for the deterministic Phase 5.5 convergence engine (`seed`/`plan-round`/`apply-round`/`apply-critic-gaps`/`finalize`/`validate`/`example`; Python: `okstra_ctl.convergence`) |
 | `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-final-report`, `inject-report-index` | `src/commands/report/*.mjs` | Render version-selected AI handoff Markdown from data.json; v1 index injection remains compatibility-only |
@@ -237,6 +238,10 @@ Important modules:
 | Module | Role |
 |---|---|
 | `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 |
@@ -313,7 +318,7 @@ Important modules:
 | `domain/`, `application/`, `ports/` | Host-neutral values and errors, wizard/run use cases, and the interaction/session/dispatch/accounting port contracts |
 | `registry/host_registry.py`, `registry/provider_registry.py` | Discover bundled adapters plus explicit user installs under `~/.okstra/adapters/{hosts,providers}/<id>/`; project-local adapter code is outside the discovery roots |
 | `adapters/hosts/`, `adapters/providers/` | Six bundled host strategies and the independent provider catalogs; host manifests select a native provider without merging the two axes |
-| `lead_events.py` | structured JSONL events emitted by artifact-accounted lead runtimes |
+| `lead_events.py` | Structured JSONL events emitted by artifact-accounted lead runtimes. Its locked append path assigns monotonic `A-NNN` identifiers to activity events in the same canonical event file. |
 | `team_reconcile.py` | stale team-member reconciliation at run-end teardown |
 | `worker_prompt_headers.py` | shared rendering of phase-aware worker prompt anchors (`worker_prompt_headers`): coding-preflight only for implementation and compact target identity for final-verification |
 | `worker_prompt_body.py` | provider-neutral initial analysis body/input renderer shared by Codex and external/team dispatch paths |
@@ -363,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,8 +381,8 @@ Token/cost accounting:
 |---|---|
 | `templates/reports/final-report.template.md` | Schema v1 compatibility Markdown template |
 | `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 |
@@ -490,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
 
@@ -530,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. Schema v1 and quick Markdown inputs retain their 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.
 
@@ -610,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 |
@@ -650,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 |
@@ -658,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. |
@@ -69,8 +70,9 @@ flowchart TD
 | 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
 

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.171.0",
+  "version": "0.173.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.171.0",
-  "builtAt": "2026-08-15T08:20:00.683Z",
+  "package": "0.173.0",
+  "builtAt": "2026-08-16T04:09:59.317Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/report-writer-worker.md

@@ -102,12 +102,36 @@ You author the final-report data.json (the JSON SSOT). You author it against the
 
 The AI handoff Markdown is an agent-facing ledger: verdict, routing, clarification decisions, evidence, one structured task deliverable, and execution audits. The human HTML is the reader-facing explanation: `humanSummary` plus the selected task block's `userNarrative` and structured facts. Populate both human fields in data.json even though the Markdown intentionally omits their full prose. Worker discussion, convergence mechanics, and token usage belong to audit data and must not be copied into the HTML human main body.
 
+### Implementation-planning frontmatter contract
+
+#### Selected-direction
+
+Emit `frontmatter.approved` as `false` and copy `implementationPlanning.selectedDirectionRef.snapshotPath` into `frontmatter.selectedDirectionRef`. You MUST omit `frontmatter.implementationOption`; the direction was selected upstream and cannot be selected again in planning. `schemas/final-report-v2.0.schema.json` enforces the required selected-direction reference and rejects an `implementationOption` property for this branch.
+
+#### Legacy candidate-comparison
+
+Emit `frontmatter.approved` as `false` and `frontmatter.implementationOption` as the empty string `""`. The user later flips `approved` to `true` and fills `implementationOption` with the chosen Option Candidate name to authorise and scope the next `implementation` run. Every other report type follows the same empty `implementationOption` default; the schema's non-selected-direction branch requires that field and rejects a selected-direction reference.
+
+### General authoring rules
+
 Rules (the schema enforces most of these — they are listed here so you know *what* to populate, not *how* to validate):
 
 - Read the exact permitted header values from the task bundle schema excerpt. In the current v2 contract, `header.reportOwner` is `"Okstra lead"` and `header.reportAuthor` is `"Report writer worker"`. Set author to `"Okstra lead"` only for `release-handoff` runs (single-lead by design) or a recorded report-writer dispatch failure fallback. A legacy v1 excerpt may retain its historical compatibility values; follow that excerpt rather than inferring ownership from the provider.
 - **Source items (worker:item) preservation.** Every `consensus[].sourceItems`, `differences[].workersPosition[].itemId`, and `evidence.primary[].sourceItems` entry MUST carry the worker:item-id pair (e.g. `claude:F-001`, `codex:1.1`, `antigravity:F-3`, or `lead:mcp-1` for lead-only evidence). The schema enforces this via the `SourceItem` regex; bare worker-name lists no longer parse.
 - **Verdict Card consistency.** `verdictCard.verdictToken` and `verdictCard.direction` MUST byte-match `finalVerdict.verdictToken` / `.direction`; `validators/validate-run.py` diffs both and fails the run on divergence. `verdictCard.nextStep` names the same action as `finalVerdict.nextStep` and `recommendedNextSteps[0].text` but is written as the actionable command the reader runs (e.g. `/okstra-run task-key=… task-type=release-handoff`) where the other two are prose — it is deliberately not a byte copy. Duplicating the compared values across `verdictCard` and `finalVerdict` is intentional so the validator can diff them.
-- **Error-analysis diagnosis and routing.** When `header.taskType` is `error-analysis`, populate the required `errorAnalysis` object. Copy `errorAnalysis.symptomVerbatim` byte-for-byte from the symptom stated in the brief's `Source Material`; do not paraphrase it. Every `causeCandidates[]` row includes the full `supportingEvidence`, `falsifyingEvidenceChecked`, `confidence`, and `disproveWith` fields. When a candidate is a step in a propagation chain rather than a competing explanation — the analysis calls it a downstream step, a second stage, or a consequence of another candidate — set its `downstreamOf` to the ids of the candidates immediately upstream of it; leave the field absent for a candidate that stands on its own. Every id listed MUST be another candidate in the same report, no row may name itself, and the links MUST NOT form a cycle; `validators/validate-run.py::_validate_cause_chain` rejects all three. This is the only place the chain is machine-readable — prose calling a candidate "the second step of the chain" while `downstreamOf` is absent leaves the report's figure claiming the candidates are alternatives. Route `errorAnalysis.routing.nextTaskType=implementation-planning` with `direction=begin-planning`, or route `errorAnalysis.routing.nextTaskType=error-analysis` with `direction=continue-investigation`; no other pairing is valid. `verdictCard.nextStep`, `finalVerdict.nextStep`, the first `recommendedNextSteps` action and command, and the unique `followUpTasks` row whose `origin` is `phase-continuation` MUST all point to the same `errorAnalysis.routing.nextTaskType` target. The schema enforces only the presence of a `phase-continuation` row. Phase validation MUST enforce exact target agreement and uniqueness through `validators/validate-run.py::_validate_error_analysis_consistency`; until that check is implemented and executed, those semantics are contract requirements rather than enforced guarantees.
+- **Error-analysis diagnosis and routing.** When `header.taskType` is `error-analysis`, populate the required `errorAnalysis` object. Copy `errorAnalysis.symptomVerbatim` byte-for-byte from the symptom stated in the brief's `Source Material`; do not paraphrase it. Every `causeCandidates[]` row includes the full `supportingEvidence`, `falsifyingEvidenceChecked`, `confidence`, and `disproveWith` fields. When a candidate is a step in a propagation chain rather than a competing explanation — the analysis calls it a downstream step, a second stage, or a consequence of another candidate — set its `downstreamOf` to the ids of the candidates immediately upstream of it; leave the field absent for a candidate that stands on its own. Every id listed MUST be another candidate in the same report, no row may name itself, and the links MUST NOT form a cycle; `validators/validate-run.py::_validate_cause_chain` rejects all three. This is the only place the chain is machine-readable — prose calling a candidate "the second step of the chain" while `downstreamOf` is absent leaves the report's figure claiming the candidates are alternatives. Route `errorAnalysis.routing.nextTaskType=implementation-option-selection` with `direction=begin-option-selection`, or route `errorAnalysis.routing.nextTaskType=error-analysis` with `direction=continue-investigation`; no other pairing is valid. `verdictCard.nextStep`, `finalVerdict.nextStep`, the first `recommendedNextSteps` action and command, and the unique `followUpTasks` row whose `origin` is `phase-continuation` MUST all point to the same `errorAnalysis.routing.nextTaskType` target. The schema enforces only the presence of a `phase-continuation` row; `validators/validate-run.py::_validate_error_analysis_consistency` enforces exact target agreement and uniqueness.
+- **Implementation-option-selection comparison.** When `header.taskType` is `implementation-option-selection`, populate `implementationOptionSelection` from the converged direction-selection findings. Preserve every merged or rejected raw candidate in `candidateAudit`, and put at most three selectable candidates in `rankedOptions`. Each displayed candidate carries its requirement coverage, scope commitments, criterion scores, feasibility votes, safety blockers, unresolved feasibility facts, planning invariants, and exact coverage summary. In each displayed candidate, `expectedChangeAreas` names direction-level change surfaces, never exact file paths or an exact file list. `expectedVerification` names direction-level verification signals, never a stage list or executable test commands. `schemas/final-report-v2.0.schema.json` enforces the displayed-summary constants and the three-option cap; semantic recalculation belongs to `validators/validate-run.py`.
+- **Implementation-planning direction branch.** For `planningContract: selected-direction`, read `selectedDirectionRef` and its snapshot, then preserve their core mechanism, architecture boundaries, and planning invariants in `directionRealization`. Materialize files, interfaces, stages, validation, rollback, and bidirectional original-requirement links without candidate generation, scoring, recommendation, or user candidate selection. Author exactly one `P-Dir-1` whose payload is the complete `directionRealization`; its verifier checks those preserved properties and any hidden direction change. If the direction must change, author `direction-invalidated` and no execution queue. Legacy candidate-comparison reruns retain Option Candidates, trade-offs, Recommended Option, and `P-Opt-*` semantics.
+
+```json
+{
+  "candidateDetailBoundary": {
+    "expectedChangeAreas": "direction-level-only",
+    "expectedVerification": "direction-level-signals-only",
+    "forbidden": ["exact-file-lists", "stage-lists", "test-commands"]
+  }
+}
+```
 - **Human narrative.** Populate required `humanSummary` and the selected task block's `userNarrative`. Human-visible analysis facts must not exist only in Markdown; HTML is derived independently and can use only data.json. Keep worker discussion and audit details in `crossVerification`, `executionStatus`, and `tokenUsage`, outside the human narrative fields.
 - **External QA advisory.** A Tier 3 entry requiring `db`, `http`, or
   `external` may be non-PASS without changing approval or final verdict. Render
@@ -116,7 +140,7 @@ Rules (the schema enforces most of these — they are listed here so you know *w
   and add the exact rerun command to `recommendedNextSteps`. Never turn this
   advisory alone into a clarification, Acceptance Blocker, conditional
   acceptance condition, or blocked routing.
-- **§7 phase-continuation row (mandatory for non-terminal task-types).** When `header.taskType` is one of `requirements-discovery` / `implementation-planning` / `error-analysis` / `implementation` / `final-verification`, `followUpTasks` MUST contain at least one row whose `origin` is `phase-continuation`, `newTaskId` reuses the current task-id, `autoSpawn` is `"no"`, and `priority` is `"P0"`. For `release-handoff` runs, omit the phase-continuation row. The schema `allOf` / `contains` clause enforces row presence, not exact route-target agreement or uniqueness; phase validation must enforce those error-analysis semantics as specified above.
+- **§7 phase-continuation row (mandatory for non-terminal task-types).** When `header.taskType` is one of `requirements-discovery` / `implementation-option-selection` / `implementation-planning` / `error-analysis` / `implementation` / `final-verification`, `followUpTasks` MUST contain at least one row whose `origin` is `phase-continuation`, `newTaskId` reuses the current task-id, `autoSpawn` is `"no"`, and `priority` is `"P0"`. For `release-handoff` runs, omit the phase-continuation row. The schema `allOf` / `contains` clause enforces row presence, not exact route-target agreement or uniqueness; phase validation must enforce those error-analysis semantics as specified above.
 - **No deprecated sections.** The schema has no `4.5.8 User Approval Request` body field, no `4.5.9 Open Questions`, no `5.1 Additional Material Request`, no `5.2 User Confirmation Questions` — clarifications go under the unified `clarificationItems[]` array.
 - **Optional Section 0.** Include `clarificationCarryIn` ONLY when the lead's prompt provides a non-empty carry-in path. Omit the key entirely otherwise (do NOT set it to `null` or an empty object).
 - **Reading Confirmation** goes at `**Audit sidecar path:**` per the selected report-writer preamble's `Required reading` section — never in the data.json or the main worker-results file.
@@ -129,10 +153,10 @@ Rules (the schema enforces most of these — they are listed here so you know *w
 - Cite file paths and line numbers in every `evidence.primary[].source` / `consensus[].evidence` cell.
 - Preserve every analysis worker's ticket tagging — every row's `ticketId` field carries the ticket key or the task-fallback. For single-ticket runs, set `ticketCoverage` to `{"singleTicket": "<ticket>"}`. For runs that do not require ticket tagging (`release-handoff`, `final-verification`), set `ticketCoverage` to `{"omit": true}`.
 - For `requirements-discovery`, `error-analysis`, and `implementation-planning`, populate the top-level `endStateCoverage` with exactly one row per end-state id the brief declares — no more, no fewer. `disposition` is one of `addressed` / `deferred` / `not-applicable` / `blocked`. `addressed` requires a `coveredBy` anchor in THIS phase's own deliverable (requirements-discovery: the routing decision, the fan-out unit id, or the `C-NNN` clarification; error-analysis: the root-cause candidate or the next diagnostic; implementation-planning: the `R-NNN` row); every other disposition requires a `rationale`. Do not author a goal of your own here and do not restate the brief — this table records only how this phase accounted for what the reporter already pinned. When the brief declares no end-state ids (a brief authored before those sections existed), omit the field entirely. **Enforced:** `validators/validate-run.py` `_validate_end_state_coverage`.
-- For `implementation-planning`, populate `implementationPlanning.requirementCoverage` with one row per concrete requirement from the brief / packet, using IDs `R-001`, `R-002`, ... in source order. A `covered` row's `coveredBy` MUST name the specific Option Candidate plus Stage/Step that satisfies the requirement. Use `status: "covered"` only when the report's plan actually covers it; use `documented-deviation` only when `coveredBy` states the concrete alternative and the row records non-empty unique `decisionRefs` plus `approvalDisposition`. Each `C-NNN` ref must name a clarification in this report; each `D-NNNN` ref must name a `decisionDrafts[].number`. `approvalDisposition: "accepted"` requires a referenced clarification with `status: answered|resolved` and non-empty `userInput`; `approvalDisposition: "blocked C-NNN"` requires that same-report clarification to be `status: open, blocks: approval`. Otherwise use `gap` or `blocked C-NNN` and ensure the corresponding `Clarification Items` row blocks approval. Do not collapse this into `ticketCoverage`; ticket coverage is not requirement coverage. **Enforced:** `schemas/final-report-v2.0.schema.json` `$defs.ImplementationRequirementCoverageRow` and `validators/validate-run.py` `_validate_requirement_deviations`.
-- For `implementation-planning`, each `requirementCoverage` row's `source` is a graded cell, not prose — free text like `"carry-in from requirements-discovery C-001"` is rejected. Write exactly one of: `brief:EB-001` / `brief:PB-001` / `brief:EO-001`, an end-state id the brief declares — when the brief pins ids, citing a heading instead is rejected, because every brief carries the same generic headings and a heading cannot say WHICH reporter line the requirement came from (only a brief authored before the end-state sections existed still takes the older `brief:<heading>` form, and there the heading must literally exist in it); `derived:R-NNN — <one-line reason>`, whose chain must terminate at a `brief:` or `contract:` row of the same table without cycling; or `contract:<rule>`, for artifacts okstra's own phase contract mandates, whose allowlist is exactly the two tokens `decision-record-step` (the §5.4 Decision Drafts materialization step) and `glossary-step` (the glossary proposal step) — any other rule name is rejected, so never invent one. (Maintainer SSOT for that allowlist: `scripts/okstra_ctl/scope_provenance.py` in the okstra repo.) A requirement you cannot source this way does not belong in the table: put it in `clarificationItems[]` with `Blocks=approval`. **Enforced:** `validators/validate-run.py` `_validate_requirement_provenance`. In the same table, anchor every stage number in `coveredBy` to a `Stage` / `Stages` word (`Stage 2`, `Stages 1-3`) — `_validate_stage_has_requirement` reads that cell as prose and fails the plan when a Stage Map stage is cited by no row.
-- For `implementation-planning`, also populate `implementationPlanning.decisionDrafts` (one row per decision meeting all three decision-record criteria; `[]` otherwise) and `implementationPlanning.skippedAdrCandidates` (evaluated-but-dropped adr-candidates; `[]` otherwise). The schema excerpt enumerates the row shape; the renderer emits §5.4 `### Decision Drafts`. When `decisionDrafts` is non-empty, the plan's stages MUST carry a stepwise step that creates `.okstra/decisions/<NNNN>-<slug>.md` (validate-run gates this).
-- For `implementation-planning`, populate `implementationPlanning.variationPointAnalysis` — a `hasMultipleImplementations` judgement synthesized from the analysis workers' output, not a field filled in last. When it is `true`, write one `points[]` row per varying behavior carrying `behavior`, the two or more `implementations` that serve it, `evidence` (a `path:line`, or the sibling task / stage that already implements that behavior), and an `extractionDecision` of `extract` / `interfaceKind` / `coveredBy` (the Stage Map stage that builds the interface) / `rationale`; when it is `false`, write a non-empty `noVariationRationale` and leave `points` empty (the two branches are mutually exclusive). Do NOT pass a boilerplate rationale — `false` is the cheaper field to fill, and a `false` declaration the brief or the sibling code in the workers' evidence contradicts is a `P-Var` DISAGREE, not a saving. Also populate `implementationPlanning.recommendedOption.testSeams`: one row per boundary a test injects at and replaces, each carrying `boundary` / `injectedAs` / `replacedInTest`. An empty list is a conscious "no seam needed" claim, never a default for a field nobody filled. The schema excerpt enumerates both row shapes — author against it. (Maintainer SSOT for these two rules: the `Required deliverable shape` bullet in `prompts/profiles/implementation-planning.md` in the okstra repo; that path is not resolvable here, so it is provenance, not a file to open.) **Enforced:** `schemas/final-report-v2.0.schema.json` `$defs.VariationPointAnalysis` / `$defs.VariationPoint` (the block is in `implementationPlanning.required`) plus `testSeams` in `$defs.RecommendedOption`'s `required`; `validators/validate-run.py` `_validate_variation_point_analysis` rejects a rationale-less `false`, a `false` carrying points, a `true` with no point, an `extract: true` decision leaving `interfaceKind` or `coveredBy` empty, and a hexagonal project extracting as anything but a port; and every point becomes a `P-Var-*` plan item judged in §5.5.9.
+- For selected-direction `implementation-planning`, preserve each original requirement ID and populate its `stageRefs`, `stepRefs`, `validationRefs`, and `fileRefs`; `validate_selected_direction_plan` enforces forward and reverse exact coverage. For legacy candidate-comparison `implementation-planning`, populate `implementationPlanning.requirementCoverage` with one row per concrete requirement from the brief / packet, using IDs `R-001`, `R-002`, ... in source order. A `covered` row's `coveredBy` MUST name the specific Option Candidate plus Stage/Step that satisfies the requirement. Use `status: "covered"` only when the report's plan actually covers it; use `documented-deviation` only when `coveredBy` states the concrete alternative and the row records non-empty unique `decisionRefs` plus `approvalDisposition`. Each `C-NNN` ref must name a clarification in this report; each `D-NNNN` ref must name a `decisionDrafts[].number`. `approvalDisposition: "accepted"` requires a referenced clarification with `status: answered|resolved` and non-empty `userInput`; `approvalDisposition: "blocked C-NNN"` requires that same-report clarification to be `status: open, blocks: approval`. Otherwise use `gap` or `blocked C-NNN` and ensure the corresponding `Clarification Items` row blocks approval. Do not collapse this into `ticketCoverage`; ticket coverage is not requirement coverage. **Enforced:** `schemas/final-report-v2.0.schema.json` `$defs.ImplementationRequirementCoverageRow` and `validators/validate-run.py` `_validate_requirement_deviations`.
+- For legacy candidate-comparison `implementation-planning`, each `requirementCoverage` row's `source` is a graded cell, not prose — free text like `"carry-in from requirements-discovery C-001"` is rejected. Write exactly one of: `brief:EB-001` / `brief:PB-001` / `brief:EO-001`, an end-state id the brief declares — when the brief pins ids, citing a heading instead is rejected, because every brief carries the same generic headings and a heading cannot say WHICH reporter line the requirement came from (only a brief authored before the end-state sections existed still takes the older `brief:<heading>` form, and there the heading must literally exist in it); `derived:R-NNN — <one-line reason>`, whose chain must terminate at a `brief:` or `contract:` row of the same table without cycling; or `contract:<rule>`, for artifacts okstra's own phase contract mandates, whose allowlist is exactly the two tokens `decision-record-step` (the §5.4 Decision Drafts materialization step) and `glossary-step` (the glossary proposal step) — any other rule name is rejected, so never invent one. (Maintainer SSOT for that allowlist: `scripts/okstra_ctl/scope_provenance.py` in the okstra repo.) A requirement you cannot source this way does not belong in the table: put it in `clarificationItems[]` with `Blocks=approval`. **Enforced:** `validators/validate-run.py` `_validate_requirement_provenance`. In the same table, anchor every stage number in `coveredBy` to a `Stage` / `Stages` word (`Stage 2`, `Stages 1-3`) — `_validate_stage_has_requirement` reads that cell as prose and fails the plan when a Stage Map stage is cited by no row.
+- For legacy candidate-comparison `implementation-planning`, also populate `implementationPlanning.decisionDrafts` (one row per decision meeting all three decision-record criteria; `[]` otherwise) and `implementationPlanning.skippedAdrCandidates` (evaluated-but-dropped adr-candidates; `[]` otherwise). The schema excerpt enumerates the row shape; the renderer emits §5.4 `### Decision Drafts`. When `decisionDrafts` is non-empty, the plan's stages MUST carry a stepwise step that creates `.okstra/decisions/<NNNN>-<slug>.md` (validate-run gates this).
+- For `implementation-planning`, populate `implementationPlanning.variationPointAnalysis` — a `hasMultipleImplementations` judgement synthesized from the analysis workers' output, not a field filled in last. When it is `true`, write one `points[]` row per varying behavior carrying `behavior`, the two or more `implementations` that serve it, `evidence` (a `path:line`, or the sibling task / stage that already implements that behavior), and an `extractionDecision` of `extract` / `interfaceKind` / `coveredBy` (the Stage Map stage that builds the interface) / `rationale`; when it is `false`, write a non-empty `noVariationRationale` and leave `points` empty (the two branches are mutually exclusive). Do NOT pass a boilerplate rationale. Populate test seams under `implementationPlanning.directionRealization.testSeams` for selected-direction plans and under `implementationPlanning.recommendedOption.testSeams` for legacy candidate-comparison plans. An empty list is a conscious "no seam needed" claim, never a default for a field nobody filled. Every point becomes a `P-Var-*` plan item judged in §5.5.9.
 - When the `Task Type` is `improvement-discovery`, populate `improvementDiscovery.candidates[]`, `improvementDiscovery.lensCoverage[]`, `improvementDiscovery.selectionLimit`, and `improvementDiscovery.userNarrative`. Each candidate carries the 11 logical fields enforced by `validators/validate_improvement_report.py`; each lens-coverage row records candidate IDs or an evidence-backed no-candidate rationale. Source IDs, lens names, and worker prefixes from `scripts/okstra_ctl/improvement_lenses.py`. The standard renderer derives the AI handoff Markdown; never author a free-form improvement report.
 
 Write the three completion artifacts and the separate audit sidecar with your `Write` tool — that is the canonical authoring path, and okstra ships no hook that blocks `.md` writes (its seeded settings carry no `PreToolUse` entry at all — only the session/subagent lifecycle hooks `SessionStart` compact-reminder, `SessionEnd` trace-cleanup, and `SubagentStop` / `TaskCompleted` pane reclaim, none of which can intercept a tool call). A Bash heredoc is acceptable ONLY when a specific `Write` call is genuinely rejected by the host environment, and it MUST produce byte-identical content — do not reach for it pre-emptively. After writing data.json, invoke the renderer (`Bash`): `okstra render-final-report <data.json path>`, then write the Worker Result Path pointer. Confirm data.json, rendered Markdown, the pointer, and the audit sidecar exist before responding with a short status line prefixed by your model identity, per the preamble §"Return message to the lead". **Enforced:** dispatch `completionPaths` requires the first three files and `validators/validate_session_conformance.py` validates the audit sidecar.

package/runtime/bin/lib/okstra/cli.sh

@@ -175,6 +175,10 @@ while [[ $# -gt 0 ]]; do
       CLARIFICATION_RESPONSE_PATH="$(require_option_value --clarification-response "${2-}")"
       shift 2
       ;;
+    --selected-direction)
+      SELECTED_DIRECTION_PATH="$(require_option_value --selected-direction "${2-}")"
+      shift 2
+      ;;
     --task-key)
       TASK_KEY_INPUT="$(require_option_value --task-key "${2-}")"
       shift 2
@@ -233,7 +237,7 @@ while [[ $# -gt 0 ]]; do
           printf '  hint: did you mean --task-id?\n' >&2
           ;;
       esac
-      printf '  valid options: --render-only --resume-clarification --yes --workers --lead-provider --lead-model --claude-model --codex-model --antigravity-model --worker-model --report-writer-provider --report-writer-model --lead-runtime --executor --critic --related-tasks --work-category --task-type --project-id --project-root --task-group --task-id --task-brief --directive --base-ref --fix-cycle --clarification-response --task-key --approved-plan --approve --implementation-option --stage --stages --qa-waiver --no-plan-verification -h|--help\n' >&2
+      printf '  valid options: --render-only --resume-clarification --yes --workers --lead-provider --lead-model --claude-model --codex-model --antigravity-model --worker-model --report-writer-provider --report-writer-model --lead-runtime --executor --critic --related-tasks --work-category --task-type --project-id --project-root --task-group --task-id --task-brief --directive --base-ref --fix-cycle --clarification-response --selected-direction --task-key --approved-plan --approve --implementation-option --stage --stages --qa-waiver --no-plan-verification -h|--help\n' >&2
       usage
       exit 1
       ;;

package/runtime/bin/lib/okstra/globals.sh

@@ -44,6 +44,7 @@ ANALYSIS_PROFILE=""
 DIRECTIVE=""
 FIX_CYCLE=""
 CLARIFICATION_RESPONSE_PATH=""
+SELECTED_DIRECTION_PATH=""
 APPROVED_PLAN_PATH=""
 APPROVE_PLAN_ACK="false"
 # implementation 전용: 유저가 고른 Option Candidate 이름. 빈 값이면 implementation

package/runtime/bin/lib/okstra/usage.sh

@@ -43,6 +43,9 @@ optional arguments:
                        input so the lead can reconcile each prior Q*. Use this for scripted or
                        CI runs where the answer file is already prepared. Interactive users
                        should prefer --resume-clarification, which wraps this flag.
+  --selected-direction Path to a validated implementation-option-selection final report.
+                       Required for a new implementation-planning run. Existing planning
+                       reruns continue to use --clarification-response with their prior report.
   --approved-plan      Path to the approved final-report.md from a prior implementation-planning run.
                        Required when --task-type=implementation; the file MUST contain a recorded user approval marker.
   --approve            Treat the user's CLI invocation itself as the plan-approval signal. Only meaningful

package/runtime/bin/okstra.sh

@@ -187,6 +187,7 @@ okstra execution summary:
   task brief: ${BRIEF_PATH}
   directive: ${DIRECTIVE:-None}
   clarification response: ${CLARIFICATION_RESPONSE_PATH:-None}
+  selected direction: ${SELECTED_DIRECTION_PATH:-None}
   workers override: ${WORKERS_OVERRIDE:-None}
   executor (implementation only): ${EXECUTOR_OVERRIDE:-default(claude)}
   approved plan: ${APPROVED_PLAN_PATH:-None}
@@ -237,6 +238,7 @@ PY_ARGS=(
 [[ "$APPROVE_PLAN_ACK" == "true" ]] && PY_ARGS+=(--approve)
 [[ -n "${IMPLEMENTATION_OPTION-}" ]] && PY_ARGS+=(--implementation-option "$IMPLEMENTATION_OPTION")
 [[ -n "${CLARIFICATION_RESPONSE_PATH-}" ]] && PY_ARGS+=(--clarification-response "$CLARIFICATION_RESPONSE_PATH")
+[[ -n "${SELECTED_DIRECTION_PATH-}" ]] && PY_ARGS+=(--selected-direction "$SELECTED_DIRECTION_PATH")
 [[ -n "${WORK_CATEGORY-}" ]] && PY_ARGS+=(--work-category "$WORK_CATEGORY")
 [[ -n "${BASE_REF-}" ]] && PY_ARGS+=(--base-ref "$BASE_REF")
 [[ -n "${STAGE-}" ]] && PY_ARGS+=(--stage "$STAGE")