okstra 0.172.0 → 0.174.0

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

@@ -3,7 +3,7 @@
 PROFILE_DIR="$WORKSPACE_ROOT/prompts/profiles"
 PROMPT_TEMPLATE="$WORKSPACE_ROOT/prompts/launch.template.md"
 TASK_INDEX_TEMPLATE="$WORKSPACE_ROOT/templates/project-docs/task-index.template.md"
-FINAL_REPORT_TEMPLATE_SOURCE="$WORKSPACE_ROOT/templates/reports/final-report.template.md"
+FINAL_REPORT_TEMPLATE_SOURCE="$WORKSPACE_ROOT/templates/reports/final-report-v2.template.md"
 RUN_VALIDATOR_PATH="$WORKSPACE_ROOT/validators/validate-run.py"
 OKSTRA_ROOT=""
 OKSTRA_TASKS_ROOT=""
@@ -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-provider-exec.py

@@ -40,10 +40,11 @@ from okstra_ctl.worker_runner import LIVE, QUIET, run_worker  # noqa: E402
 _USAGE = (
     "usage: okstra-provider-exec.py <provider> <project-root> "
     "<model-execution-value> <prompt-path> [worktree-path] [role] "
-    "[idle-timeout-seconds] [--presentation live|quiet]"
+    "[idle-timeout-seconds] [--presentation live|quiet] [--session-id <uuid>]"
 )
 
 _PRESENTATION_FLAG = "--presentation"
+_SESSION_ID_FLAG = "--session-id"
 _PRESENTATIONS = (LIVE, QUIET)
 
 
@@ -66,6 +67,9 @@ class Invocation:
 def parse_invocation(argv: list[str]) -> Invocation:
     """Resolve the wrapper's positional contract into one runnable dispatch."""
     positional, presentation = _take_presentation(argv)
+    # Empty unless the dispatcher issued one. Without it the CLI picks its own
+    # id and nothing downstream can map that session back to this worker.
+    positional, session_id = _take_flag(positional, _SESSION_ID_FLAG, "")
     if not 4 <= len(positional) <= 7:
         raise PreflightError(64, _USAGE)
     provider_id, project_root_raw, model, prompt_raw = positional[:4]
@@ -90,6 +94,7 @@ def parse_invocation(argv: list[str]) -> Invocation:
         worktree_path=worktree,
         role=role,
         idle_timeout_seconds=idle_timeout_seconds,
+        session_id=session_id,
     )
     strategy = spec.exec_strategy
     _check_command(strategy, request)
@@ -103,27 +108,39 @@ def parse_invocation(argv: list[str]) -> Invocation:
     )
 
 
-def _take_presentation(argv: list[str]) -> tuple[list[str], str]:
-    """Split the one flag out of an otherwise positional argv.
+def _take_flag(argv: list[str], flag: str, default: str) -> tuple[list[str], str]:
+    """Split one value-carrying flag out of an otherwise positional argv.
 
-    Defaults to ``quiet``. ``live`` is only ever right where a screen was
-    declared, and the only callers that can declare one are the pane backends —
-    which pass the flag explicitly. Defaulting the other way assumed a screen
-    that a subagent dispatch does not have, and sent every worker's progress
-    into its caller's context window instead.
+    The wrapper's contract is positional, so every flag it grows has to be
+    lifted out before the positions are counted. Written once because the flags
+    differ only in the value they carry: a second copy of this loop is where
+    their refusals of a flag with no value would drift apart.
     """
     positional: list[str] = []
-    presentation = QUIET
+    value = default
     index = 0
     while index < len(argv):
-        if argv[index] != _PRESENTATION_FLAG:
+        if argv[index] != flag:
             positional.append(argv[index])
             index += 1
             continue
         if index + 1 >= len(argv):
-            raise PreflightError(64, f"{_PRESENTATION_FLAG} needs a value: {_USAGE}")
-        presentation = argv[index + 1]
+            raise PreflightError(64, f"{flag} needs a value: {_USAGE}")
+        value = argv[index + 1]
         index += 2
+    return positional, value
+
+
+def _take_presentation(argv: list[str]) -> tuple[list[str], str]:
+    """``_take_flag`` plus the allowlist only this flag has.
+
+    Defaults to ``quiet``. ``live`` is only ever right where a screen was
+    declared, and the only callers that can declare one are the pane backends —
+    which pass the flag explicitly. Defaulting the other way assumed a screen
+    that a subagent dispatch does not have, and sent every worker's progress
+    into its caller's context window instead.
+    """
+    positional, presentation = _take_flag(argv, _PRESENTATION_FLAG, QUIET)
     if presentation not in _PRESENTATIONS:
         allowed = " | ".join(_PRESENTATIONS)
         raise PreflightError(

package/runtime/bin/okstra-trace-cleanup.sh

@@ -1,45 +1,45 @@
 #!/usr/bin/env bash
 #
-# okstra-trace-cleanup.sh — close tmux panes created during okstra runs.
+# okstra-trace-cleanup.sh — close the harness-owned worker panes of an okstra run.
 #
-# Worker-compute panes are tmux-pane backend siblings. Their dispatcher tags
-# each pane it owns with a pane-level user option (`@okstra_worker_run=<RUN_DIR>`),
-# so panes are found server-wide by tag — no tmux env var or pane-id registry is
-# needed, and the run-scoped tag keeps concurrent okstra runs from closing each
-# other's panes.
+# The panes this closes are the teammate panes the HARNESS splits for dispatched
+# worker agents. okstra does not create them and cannot tag them, so they are
+# found by a title allowlist scoped to the lead's window. They accumulate until
+# the pane budget runs out, and `shutdown_request` only idles the agent without
+# freeing its pane — this script is the only thing that closes them, which is why
+# the lead calls it at every round boundary and before every user gate.
 #
-# Trace panes were `tail -F` siblings the provider wrappers split, tagged
-# `@okstra_trace_run` / `@okstra_status`. Those wrappers are now four-line
-# entrypoints and worker progress renders into the worker's own pane, so
-# NOTHING SPAWNS A TRACE PANE and neither tag has a writer left. The trace
-# paths below still run and simply match nothing; `--reclaim-completed`, which
-# keys on `@okstra_status`, is inert for the same reason. Kept rather than
-# deleted because the hooks that call this script are already seeded on user
-# machines — retiring the trace machinery is a deliberate follow-up.
+# Two tag-driven paths used to live here and both are gone:
 #
-# Two invocation shapes:
+#   - Worker-compute panes of the `tmux-pane` dispatch backend, tagged
+#     `@okstra_worker_run`. That backend was removed — a worker now gets a cmux
+#     surface or a cli-wrapper subprocess, and neither is a tmux pane okstra owns.
+#   - Trace panes, tagged `@okstra_trace_run` / `@okstra_status`, which the
+#     provider wrappers used to split as `tail -F` siblings. The wrappers became
+#     four-line entrypoints and worker progress renders into the worker's own
+#     pane, so nothing had spawned a trace pane for some time.
 #
-#   --run-dir <RUN_DIR>   Used by the LEAD between phases and at wrap-up. Closes
-#                         (a) trace panes tagged with this run's dir and
-#                         (b) worker-agent panes the harness gives to dispatched
-#                         subagents (`claude-worker` / `codex-worker` /
-#                         `antigravity-worker` / `report-writer-worker`), identified
-#                         by a title allowlist scoped to the LEAD's WINDOW. The
-#                         lead pane is read from `<RUN_DIR>/state/lead-pane.id`
-#                         (recorded once by the lead in its own foreground pane —
-#                         reliable even though Claude Code's Bash tool strips
-#                         `$TMUX`/`$TMUX_PANE`); it scopes the title scan and is
-#                         NEVER killed. Window scope keeps a second lead running
-#                         in another window of the same session out of range.
+# With both writers gone the tag scan matched nothing, so it was removed along
+# with the two modes that existed only to drive it (`--reap`, which the SessionEnd
+# hook called, and `--reclaim-completed`, which `okstra-subagent-reclaim.sh` drove
+# from SubagentStop / TaskCompleted). Those hooks are gone from the seeded
+# settings too.
 #
-#   --reap                Used by the `SessionEnd` hook, where no single run-dir
-#                         applies. Closes every trace pane whose tag points under
-#                         `$CLAUDE_PROJECT_DIR/.okstra/` (or every tagged trace
-#                         pane if that env var is unset). Harness-owned
-#                         worker-agent panes are left to the harness.
+# Invocation:
+#
+#   --run-dir <RUN_DIR>   Closes the run's worker-agent panes (`claude-worker` /
+#                         `codex-worker` / `antigravity-worker` /
+#                         `report-writer-worker` and the FleetView teammate
+#                         prefixes), scoped to the LEAD's WINDOW. The lead pane is
+#                         read from `<RUN_DIR>/state/lead-pane.id` (recorded once
+#                         by the lead in its own foreground pane — reliable even
+#                         though Claude Code's Bash tool strips `$TMUX` /
+#                         `$TMUX_PANE`); it scopes the scan and is NEVER killed.
+#                         Window scope keeps a second lead running in another
+#                         window of the same session out of range.
 #
 # `--list` (alias `--dry-run`) prints `<pane_id>\t<pane_title>` per pane instead
-# of killing — only meaningful with `--run-dir`.
+# of killing.
 #
 # `--keep <substr>` (repeatable) spares any pane whose current title contains
 # <substr>, in both the kill and the list set. Used to preserve an in-flight
@@ -50,7 +50,7 @@
 
 set -u
 
-# Trace-pane caller resolution helper (okstra_resolve_caller_pane) — see
+# Caller-pane resolution helper (okstra_resolve_caller_pane) — see
 # lib/okstra/tmux-pane.sh. Used as the lead-pane fallback below so a missing /
 # stale lead-pane.id resolves to the pane THIS process actually runs in (via
 # ancestor-PID ↔ tmux pane_pid matching), never a foreign active-client pane.
@@ -58,43 +58,26 @@ set -u
 _clean_script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
 [ -r "$_clean_script_dir/lib/okstra/tmux-pane.sh" ] && . "$_clean_script_dir/lib/okstra/tmux-pane.sh"
 
-# --reclaim-completed shells out to `python3 -m okstra_ctl.pane_reclaim`. The
-# package is a bin-sibling in the repo layout (scripts/okstra_ctl) and under
-# $OKSTRA_HOME/lib/python in the installed layout. Put both on PYTHONPATH so the
-# import resolves regardless of where this script runs from.
-_okstra_home="${OKSTRA_HOME:-$HOME/.okstra}"
-export PYTHONPATH="${_clean_script_dir}:${_okstra_home}/lib/python${PYTHONPATH:+:$PYTHONPATH}"
-
 MODE="kill"   # kill | list
-RECLAIM=0     # 1: trace pane 은 @okstra_status 가 완료(exited)일 때만 회수 (--reclaim-completed)
-REAP=0
 run_dir=""
 KEEP_PATTERNS=()   # --keep <substr>: panes whose title contains substr are spared from kill/list
 while [[ $# -gt 0 ]]; do
   case "$1" in
-    --list|--dry-run)    MODE="list" ;;
-    --reclaim-completed) RECLAIM=1 ;;
-    --reap)              REAP=1 ;;
+    --list|--dry-run) MODE="list" ;;
     --run-dir)        shift; run_dir="${1-}" ;;
     --run-dir=*)      run_dir="${1#--run-dir=}" ;;
     --keep)           shift; KEEP_PATTERNS+=("${1-}") ;;
     --keep=*)         KEEP_PATTERNS+=("${1#--keep=}") ;;
     -h|--help)
       cat <<'USAGE'
-usage: okstra-trace-cleanup.sh (--run-dir <RUN_DIR> [--list] [--reclaim-completed] [--keep <substr>]... | --reap)
+usage: okstra-trace-cleanup.sh --run-dir <RUN_DIR> [--list] [--keep <substr>]...
 
-  --run-dir            okstra run directory; closes that run's trace + worker-agent panes.
-  --list               with --run-dir: print "<pane_id>\t<pane_title>" per pane; no kill.
+  --run-dir            okstra run directory; closes that run's worker-agent panes.
+  --list               print "<pane_id>\t<pane_title>" per pane; no kill.
   --dry-run            alias for --list.
   --keep <substr>      exclude any pane whose title contains <substr> from the
                        kill/list set (repeatable). Used to spare an in-flight
                        report-writer at a round boundary.
-  --reclaim-completed  with --run-dir: restrict trace panes to those whose
-                       @okstra_status sidecar is terminal (stage=exited); in-flight
-                       and teammate panes are preserved. Skips the title-allowlist
-                       teammate scan. Combinable with --list.
-  --reap               close every okstra trace pane under $CLAUDE_PROJECT_DIR/.okstra
-                       (SessionEnd hook; no single run-dir applies).
 USAGE
       exit 0 ;;
     *)
@@ -104,29 +87,16 @@ USAGE
   shift
 done
 
-if [[ "$REAP" -eq 0 && -z "$run_dir" ]]; then
-  printf 'okstra-trace-cleanup.sh: --run-dir <RUN_DIR> (or --reap) is required\n' >&2
+if [[ -z "$run_dir" ]]; then
+  printf 'okstra-trace-cleanup.sh: --run-dir <RUN_DIR> is required\n' >&2
   exit 2
 fi
 
-# Canonicalize paths used in tag string-compares. The wrappers tag panes with
-# `pwd -P` (symlink-resolved), so the scope paths must be resolved the same way
-# — else a symlinked component (e.g. macOS /tmp -> /private/tmp) makes the
-# compare miss. Fall back to the literal value if the dir does not resolve.
-_resolve() { (cd "$1" 2>/dev/null && pwd -P) || printf '%s' "$1"; }
-[[ -n "$run_dir" ]] && run_dir="$(_resolve "$run_dir")"
-project_dir=""
-[[ -n "${CLAUDE_PROJECT_DIR:-}" ]] && project_dir="$(_resolve "$CLAUDE_PROJECT_DIR")"
-
-# Lead pane. For a run, prefer the value the lead recorded in its own foreground
-# pane; fall back to the active-pane probe. Rejected if the recorded pane is
-# gone. For --reap there is no run state — probe the active pane, used only to
-# avoid killing whatever pane the reap runs from.
+# Lead pane. Prefer the value the lead recorded in its own foreground pane; fall
+# back to the active-pane probe. Rejected if the recorded pane is gone.
 lead_pane=""
-if [[ "$REAP" -eq 0 ]]; then
-  lead_pane_file="$run_dir/state/lead-pane.id"
-  [[ -r "$lead_pane_file" ]] && lead_pane="$(head -n1 "$lead_pane_file" 2>/dev/null || true)"
-fi
+lead_pane_file="$run_dir/state/lead-pane.id"
+[[ -r "$lead_pane_file" ]] && lead_pane="$(head -n1 "$lead_pane_file" 2>/dev/null || true)"
 if [[ -z "$lead_pane" ]] || ! tmux display-message -p -t "$lead_pane" '#{pane_id}' >/dev/null 2>&1; then
   if type okstra_resolve_caller_pane >/dev/null 2>&1; then
     lead_pane="$(okstra_resolve_caller_pane 2>/dev/null || true)"
@@ -135,17 +105,6 @@ if [[ -z "$lead_pane" ]] || ! tmux display-message -p -t "$lead_pane" '#{pane_id
   fi
 fi
 
-# Does a trace pane's tag belong to the set we are closing?
-_tag_in_scope() {
-  local tag="$1"
-  if [[ "$REAP" -eq 1 ]]; then
-    [[ -z "$tag" ]] && return 1
-    [[ -n "$project_dir" ]] && { [[ "$tag" == "$project_dir/"* ]]; return; }
-    return 0   # no project scope available → reap every tagged trace pane
-  fi
-  [[ "$tag" == "$run_dir" ]]
-}
-
 _title_in_okstra_scope() {
   local title="$1"
   case "$title" in
@@ -168,7 +127,6 @@ _title_in_okstra_scope() {
 }
 
 # A collected pane whose current title contains any --keep substring is spared.
-# Applied at the final emit so both the tag scan and the title scan honour it.
 _keep_excluded() {
   local pid="$1" title pat
   (( ${#KEEP_PATTERNS[@]} )) || return 1
@@ -181,54 +139,25 @@ _keep_excluded() {
 
 collect_okstra_panes() {
   local -a panes=()
-  local pid trace_tag worker_tag status_tag title
-
-  # (1) Trace and worker-compute panes tagged in scope — found server-wide by
-  # tag, so no tmux env var or pane-id registry is needed. Each `@okstra_*`
-  # column carries a leading `x` sentinel (stripped after read): tmux's `-F`
-  # drops an UNSET user option AND its adjacent tab, which would otherwise
-  # shift later columns left (e.g. an empty worker tag stealing the status
-  # value). The sentinel keeps every column present so positional parsing holds.
-  # `#x` strip 은 실제 태그 값을 깎지 않는다: 모든 태그 값(trace_run/worker_run/
-  # status)은 절대경로라 `/` 로 시작 → `x` 로 시작하는 일이 없어 sentinel 만 벗겨진다.
-  while IFS=$'\t' read -r pid trace_tag worker_tag status_tag; do
-    trace_tag="${trace_tag#x}"; worker_tag="${worker_tag#x}"; status_tag="${status_tag#x}"
+  local pid title
+
+  # Title-allowlisted worker-agent panes in the lead's WINDOW. `list-panes -t
+  # <pane>` (no `-s`, no `-a`) resolves the window containing that pane and lists
+  # only that window's panes. Split-pane teammates always land in the lead's
+  # window, so this catches all of THIS run's worker panes while a second okstra
+  # lead in another window of the same tmux session is left untouched. Skipped
+  # when the lead pane is unknown.
+  [[ -n "$lead_pane" ]] || return 0
+  while IFS=$'\t' read -r pid title; do
     [[ -n "$pid" ]] || continue
     [[ "$pid" == "$lead_pane" ]] && continue
-    if _tag_in_scope "$trace_tag" || _tag_in_scope "$worker_tag"; then
-      if [[ "$RECLAIM" -eq 1 ]]; then
-        # reclaim 모드: 완료(stage=exited)된 worker 의 pane 만. status 태그가
-        # 없거나(teammate/비-wrapper pane) 미완료면 보존.
-        [[ -n "$status_tag" ]] || continue
-        python3 -m okstra_ctl.pane_reclaim "$status_tag" || continue
-      fi
+    if _title_in_okstra_scope "$title"; then
       panes+=("$pid")
     fi
-  done < <(tmux list-panes -a \
-             -F '#{pane_id}'$'\t''x#{@okstra_trace_run}'$'\t''x#{@okstra_worker_run}'$'\t''x#{@okstra_status}' \
-             2>/dev/null || true)
-  # (2) Title-allowlisted worker-agent panes in the lead's WINDOW. Only for a
-  # run (reap leaves these harness-owned panes to the harness). `list-panes -t
-  # <pane>` (no `-s`, no `-a`) resolves the window containing that pane and
-  # lists only that window's panes. Split-pane teammates always land in the
-  # lead's window, so this catches all of THIS run's worker panes while a second
-  # okstra lead in another window of the same tmux session — whose in-flight
-  # worker panes are untagged and title-only — is left untouched. Skipped when
-  # the lead pane is unknown. reclaim 모드는 teammate pane 을 회수하지 않으므로
-  # (완료 판정 불가, trace-only) 이 스캔을 건너뛴다.
-  if [[ "$REAP" -eq 0 && "$RECLAIM" -eq 0 && -n "$lead_pane" ]]; then
-    while IFS=$'\t' read -r pid title; do
-      [[ -n "$pid" ]] || continue
-      [[ "$pid" == "$lead_pane" ]] && continue
-      if _title_in_okstra_scope "$title"; then
-        panes+=("$pid")
-      fi
-    done < <(tmux list-panes -t "$lead_pane" \
-               -F '#{pane_id}'$'\t''#{pane_title}' 2>/dev/null || true)
-  fi
+  done < <(tmux list-panes -t "$lead_pane" \
+             -F '#{pane_id}'$'\t''#{pane_title}' 2>/dev/null || true)
 
-  # Dedupe — a live trace pane can match both the tag scan and the title scan.
-  # Then drop any pane a --keep pattern spares (in-flight report-writer).
+  # Drop any pane a --keep pattern spares (in-flight report-writer).
   if (( ${#panes[@]} )); then
     printf '%s\n' "${panes[@]}" | awk 'NF && !seen[$0]++' | while IFS= read -r _pid; do
       _keep_excluded "$_pid" && continue

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")

package/runtime/prompts/duties/direction-selection-worker.md

@@ -0,0 +1,44 @@
+---
+id: direction-selection-worker
+version: 1
+kind: role
+appliesTo: direction-selection-worker
+---
+
+# Direction Selection Worker Duty Contract
+
+## Responsibility
+
+Compare feasible directions before planning in `candidate-comparison` mode, or validate one preselected direction in `preselected-validation` mode.
+
+## Required conduct
+
+In `candidate-comparison` mode, inspect the evidence needed to distinguish candidates, submit no more than three candidates, state the strongest counterevidence for each one, and map every candidate to the stable brief end-state IDs it satisfies, preserves, or leaves unresolved. In `preselected-validation` mode, validate the one preselected direction against that evidence and mapping; the worker must not generate new candidates.
+
+## Decision principles
+
+Score candidates against the same stated criteria. Prefer evidence-backed feasibility over familiarity, and preserve a rejected candidate when its evidence or trade-off could affect the later planning decision.
+
+## Authority and boundaries
+
+Select directions only. Do not edit project state, author detailed file lists, create stage maps, prescribe execution commands, or approve an implementation plan.
+
+## Evidence standard
+
+Each candidate, score, counterexample, and requirement mapping cites inspected evidence. State uncertainty when the code or brief cannot establish a criterion.
+
+## Collaboration contract
+
+Reason independently from other workers. Do not collapse overlapping candidates or seek agreement before convergence; provide the evidence that lets the lead merge and re-evaluate them.
+
+## Completion criteria
+
+In `candidate-comparison` mode, every submitted candidate has a criterion score, counterevidence, and stable requirement mapping. In `preselected-validation` mode, the one preselected direction has a validation result, counterevidence, and stable requirement mapping. Rejected candidates retain their audit reason and evidence.
+
+## Forbidden conduct
+
+Do not turn a candidate into a detailed implementation plan, invent a requirement ID, omit contrary evidence, present a selection as user approval, or generate a new candidate in `preselected-validation` mode.
+
+## Blocked-state reporting
+
+Name the missing evidence or unresolved requirement that prevents a candidate comparison, the inspection attempted, and the criterion it leaves unscored.

package/runtime/prompts/duties/planning-worker.md

@@ -9,11 +9,19 @@ appliesTo: planning-worker
 
 ## Responsibility
 
-Produce an implementation direction a person can approve: feasible options with their trade-offs, one recommendation, and stages that carry the requirement to a verifiable end — all without writing the implementation.
+Produce an executable implementation plan without writing the implementation.
+
+### Selected-direction responsibility
+
+When `selected-direction.json` is present, read it and the requirements ledger first. Preserve the selected direction's core mechanism, architecture boundaries, user constraints, and planning invariants. Concretize only its files, interfaces, stages, validation, and rollback. Link every file and stage back to original requirements, and link every original requirement forward to its files, stages, and checks. If current code evidence requires changing the direction, return `direction-invalidated` with evidence and stop. Direction selection remains upstream of this branch.
+
+### Legacy candidate-comparison compatibility
+
+For a legacy rerun without `selected-direction.json`, retain Option Candidates, trade-offs, the Recommended Option, and `P-Opt-*` verification semantics. Only this compatibility branch compares alternatives or chooses a recommendation.
 
 ## Required conduct
 
-Read the current state of the code the work touches before drafting options; compare at least two feasible options on evidence from that code unless the decision is already settled upstream; tie the recommendation to the trade-off that decides it; split the work into stages along real dependencies with each stage's validation signal and rollback; and connect every requirement to the stage that satisfies it.
+Read the current state of the code the work touches before planning. Split work into stages along real dependencies with each stage's validation signal and rollback. Connect every requirement to the stage that satisfies it. In the selected-direction branch, verify direction preservation before adding plan detail. In the legacy branch, compare options on current-code evidence.
 
 ## Decision principles
 
@@ -29,11 +37,11 @@ Every cited path, symbol, and command must exist as written and be executable in
 
 ## Collaboration contract
 
-Draft independently of the other planners rather than converging on the first option proposed. Leave the choice between competing plans and the resolution of contested items to convergence and the lead, and hand the executor a plan complete enough to follow without re-deriving the decisions behind it.
+Draft independently of the other planners. Leave contested plan details to convergence and the lead, and hand the executor a plan complete enough to follow without re-deriving the selected direction.
 
 ## Completion criteria
 
-Options, trade-offs, the recommendation, the stages with their dependencies, validation and rollback, and requirement coverage are all present and mutually consistent; every unresolved decision is recorded as such rather than assumed; and no stage depends on work the plan never places.
+For selected-direction planning, the snapshot and requirements ledger are preserved; files, interfaces, stages, validation, rollback, and requirements links are mutually consistent; planning invariants have evidence; and no hidden direction change is present. For legacy candidate-comparison compatibility, Option Candidates, trade-offs, the Recommended Option, and `P-Opt-*` semantics remain present. Every unresolved decision is recorded rather than assumed, and no stage depends on work the plan never places.
 
 ## Forbidden conduct