okstra 0.172.0 → 0.173.0

package/runtime/templates/reports/task-brief.template.md

@@ -60,9 +60,14 @@ taskType: "{{FM_TASK_TYPE}}"
   - What is the visible symptom?
   - What are the expected vs actual results?
   - What are the current hypotheses and missing evidence?
+- If `Task Type` is `implementation-option-selection`:
+  - Is this a comparison among possible directions or validation of one preselected direction?
+  - Which stable `EB-NNN`, `PB-NNN`, and `EO-NNN` requirements form the coverage denominator?
+  - Which mechanism, architecture boundary, preservation rule, or implementation constraint must each direction address?
 - If `Task Type` is `implementation-planning`:
-  - What implementation options are under consideration?
-  - What trade-offs, dependencies, or migrations matter?
+  - Which validated selection report and `selectedDirectionRef` authorise this new plan?
+  - Which mechanism, architecture boundary, invariants, and user constraints must the plan preserve?
+  - Which dependencies or migrations matter while realizing that one direction?
   - What validation and rollback approach is expected?
 - If `Task Type` is `implementation`:
   - Which approved `implementation-planning` final report authorises this run, and is its frontmatter `approved: true` cited verbatim?
@@ -141,6 +146,7 @@ taskType: "{{FM_TASK_TYPE}}"
 - Allowed and forbidden actions for each task type are listed in `Lifecycle Phase Boundaries` of the okstra skill (`prompts/lead/okstra-lead-contract.md`). The lead and every worker stay inside that boundary.
 - "proceed to the next step" or any equivalent user phrase is interpreted as "complete the remaining outputs of the current phase," never as "start the next lifecycle phase." The next phase begins only via a fresh okstra invocation with the new `--task-type`.
 - For `implementation-planning` specifically: produce a plan document with the sections listed in `okstra-implementation-planning-input.template.md` `## Required Plan Deliverable`. Do not edit project source code, run builds/migrations/deployments, or write artifacts outside the run's own directories.
+- For `implementation-option-selection` specifically: compare or validate implementation directions without editing source, running tests/builds, or writing exact file lists, stage maps, and test commands. Only directions with 100% requirement coverage and 100% scope precision may be displayed.
 - For `implementation` specifically: edits are bounded by the approved plan's file list (the `--approved-plan` reference). The run MUST refuse to start if the approved plan path is missing or its frontmatter `approved` field is not `true`. `git push`, publish, deploy, real migrations, and any third-party write API call remain forbidden; only local `git add`/`git commit` are allowed. Verifier roles stay read-only — they record fix recommendations rather than applying edits — and acceptance verdicts belong to `final-verification`, not this phase.
 
 ## Available MCP Servers
@@ -157,7 +163,7 @@ How to invoke (worker-by-worker):
 
 Usage policy:
 
-- **Allowed phases**: `requirements-discovery`, `error-analysis`, `implementation-planning`, `final-verification`. Use only when local schema/data evidence improves the answer. Always cite the server, table, and the SELECT used as evidence in worker output.
+- **Allowed phases**: `requirements-discovery`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `final-verification`. Use only when local schema/data evidence improves the answer. Always cite the server, table, and the SELECT used as evidence in worker output.
 - **`implementation` phase**: read-only MCP queries are permitted as cross-checks; MCP MUST NOT be used as a write path even if a write tool becomes available — schema/data mutations belong in the codebase migration files reviewed by humans.
 - **CLI-wrapper workers**: can use these MCP servers only if their provider CLI configuration mirrors the same servers. If not configured, the worker should record `MCP not available in this CLI` in `Missing Information or Assumptions` rather than guessing.
 - **Forbidden**: connecting to non-listed databases, running anything that mutates state (server is read-only — flagged write attempts are a contract violation), persisting query results outside the run's own artifact directories.

package/runtime/templates/reports/user-response.template.md

@@ -9,9 +9,11 @@ This file defines the standard format of the markdown produced by the **Export u
 
 ```yaml
 task-key: <task-group>/<task-id>
-task-type: <requirements-discovery | error-analysis | implementation-planning | implementation | final-verification | release-handoff | project-analysis | feature-analysis | change-impact-analysis>
+task-type: <requirements-discovery | error-analysis | implementation-option-selection | implementation-planning | implementation | final-verification | release-handoff | improvement-discovery | project-analysis | feature-analysis | change-impact-analysis>
 seq: <3-digit zero-padded run sequence>
 source-report: <project-relative path to the final-report .md the HTML was derived from>
+source-data: <project-relative path to the final-report data.json; omit for legacy reports without one>
+source-data-sha256: <SHA-256 of the exact source-data bytes; omit when source-data is omitted>
 created-by: user
 created-at: <ISO 8601 UTC timestamp>
 ```
@@ -72,15 +74,16 @@ When you pick a verdict in the Plan Decision widget and Export, the following bl
 ```markdown
 ## PLAN DECISION
 - Status: <approved | revision-requested | rejected>
-- Implementation-Option: <the name exactly as in Option Candidates>
+- Implementation-Option: <legacy plans only: the name exactly as in Option Candidates>
 - Reason:
   > <one quoted line per input line>
 ```
 
 - `revision-requested` and `rejected` require a reason: a plan sent back without one leaves the next run guessing at what to change, so Export refuses to serialise it.
-- `Implementation-Option:` is emitted only for `approved`, and only when you moved off the recommended default — otherwise implementation falls back to the plan's Recommended Option.
+- A `planningContract: selected-direction` plan never emits `Implementation-Option:`. The direction was confirmed before planning, and this block decides only whether the detailed plan is approved, revised, or rejected.
+- A legacy candidate plan emits `Implementation-Option:` only for `approved`, and only when you moved off the recommended default. Otherwise implementation falls back to the legacy plan's Recommended Option.
 - `Reason:` is optional for `approved`, and the line is omitted when empty.
-- The consumer of an `approved` block is the approve-confirm step of the implementation start wizard (`scripts/okstra_ctl/wizard.py`). After user confirmation the wizard applies it through the existing `--approve` / `--implementation-option` path; the sidecar itself does not bypass approval-gate validation. A non-approved status is ignored there — that step only ever looks for an approval.
+- The consumer of an `approved` block is the approve-confirm step of the implementation start wizard (`scripts/okstra_ctl/wizard.py`). After user confirmation the wizard applies `--approve`; it applies `--implementation-option` only for a legacy plan. The sidecar itself does not bypass approval-gate validation. A non-approved status is ignored there — that step only ever looks for an approval.
 - The parser is `parse_plan_decision` in `scripts/okstra_ctl/user_response.py`, and it accepts only the lowercase statuses that are byte-identical to the producer output (hand-edited values such as `Approved` are rejected fail-closed).
 - `--resume-clarification` attaches the sidecar verbatim, so the PLAN DECISION block reaches the next planning run — which is how a rejection and its reason get acted on.
 
@@ -102,6 +105,24 @@ The Analysis Review control appends one decision block. `revision-requested` and
 
 The block is the review decision's sole storage location. Export never changes the source final-report markdown. A later analysis rerun receives the sidecar through `--clarification-response` and records one `analysisReviewResolution` row for each imported affected ID.
 
+## DIRECTION SELECTION block (implementation-option-selection comparison only)
+
+Selecting one ranked direction and checking `Confirmed` appends this block. `Selection-Note` and `Constraints` keep their field lines when empty, but do not emit empty quote lines.
+
+```markdown
+## DIRECTION SELECTION
+- Status: selected
+- Option-ID: IO-002
+- Option-Name: Adapter boundary
+- Confirmed: true
+- Selection-Note:
+  > Use the existing port.
+- Constraints:
+  > Keep PB-001 unchanged.
+```
+
+The parser accepts exactly one block, lowercase `selected`, and lowercase `true`. A `preselected-validation` report displays its confirmed upstream direction read-only and does not export a new selection block.
+
 ## Compatibility Rules
 
 - If `Kind` has an unknown value, the form renders with a `<textarea>` fallback, and the received `Kind` string is preserved as-is during serialization.

package/runtime/templates/worker-prompt-preamble.md

@@ -61,6 +61,14 @@ Every analysis result starts with YAML frontmatter containing the task identity
 
 Every item has a worker-local ID and file:line evidence where code evidence exists. Sections 1–5 are the common core: feasibility, requirement interpretation, hidden assumptions, alternatives, and execution risk. Section 6 is the only legal home for specialization and is not consensus input.
 
+### Selected-direction planning ownership
+
+For `implementation-planning` with `selected-direction.json`, sections 1–5 read that snapshot and the original requirements, then assess only its realization into files, interfaces, stages, validation, rollback, bidirectional requirement links, and `direction-invalidated` evidence. Direction selection remains upstream of this prompt.
+
+### Legacy candidate-comparison ownership
+
+For an implementation-planning compatibility rerun without the snapshot, sections 1–5 retain candidate comparison, trade-off, recommendation, and `P-Opt-*` evidence.
+
 ### Ticket Tagging
 
 For `requirements-discovery`, `error-analysis`, and `implementation-planning`, tag every section 1–5 item with its related ticket. Use `Issue / Ticket`, fall back to Task ID, then `unknown`; comma-separate multiple tickets.

package/runtime/validators/validate-implementation-plan-stages.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 import argparse
 import re
 import sys
+from collections import Counter
 from dataclasses import dataclass
 from pathlib import Path
 from typing import List, Tuple
@@ -472,6 +473,99 @@ def _check_data_step_counts(
     return errs
 
 
+def _check_data_stage_identities(
+    raw_stage_map: List[dict], stages: List[dict]
+) -> List[ValidationError]:
+    """Reject ambiguous schema-v2 identities before building stage indexes."""
+    errs: List[ValidationError] = []
+    stage_map_numbers = [
+        row["stage"]
+        for row in raw_stage_map
+        if isinstance(row, dict) and isinstance(row.get("stage"), int)
+    ]
+    stage_numbers = [
+        row["stage"]
+        for row in stages
+        if isinstance(row, dict) and isinstance(row.get("stage"), int)
+    ]
+    duplicate_stage_map = {
+        number for number, count in Counter(stage_map_numbers).items() if count > 1
+    }
+    duplicate_stages = {
+        number for number, count in Counter(stage_numbers).items() if count > 1
+    }
+    errs.extend(
+        ValidationError("S3", number, f"stageMap duplicate stage {number}")
+        for number in sorted(duplicate_stage_map)
+    )
+    errs.extend(
+        ValidationError("S3", number, f"stages[] duplicate stage {number}")
+        for number in sorted(duplicate_stages)
+    )
+
+    stage_map_set = set(stage_map_numbers)
+    stage_set = set(stage_numbers)
+    errs.extend(
+        ValidationError(
+            "S3",
+            number,
+            f"stageMap is missing stages[] stage {number}",
+        )
+        for number in sorted(stage_set - stage_map_set)
+    )
+    errs.extend(
+        ValidationError(
+            "S3",
+            number,
+            f"stages[] is missing stageMap stage {number}",
+        )
+        for number in sorted(stage_map_set - stage_set)
+    )
+
+    stage_map_by_number = {
+        row["stage"]: row
+        for row in raw_stage_map
+        if isinstance(row, dict)
+        and isinstance(row.get("stage"), int)
+        and row["stage"] not in duplicate_stage_map
+    }
+    stages_by_number = {
+        row["stage"]: row
+        for row in stages
+        if isinstance(row, dict)
+        and isinstance(row.get("stage"), int)
+        and row["stage"] not in duplicate_stages
+    }
+    errs.extend(
+        ValidationError(
+            "S3",
+            number,
+            f"stageMap and stages[] stage {number} title must match",
+        )
+        for number in sorted(stage_map_by_number.keys() & stages_by_number.keys())
+        if stage_map_by_number[number].get("title")
+        != stages_by_number[number].get("title")
+    )
+
+    for stage in stages:
+        number = stage.get("stage")
+        step_numbers = [
+            step["step"]
+            for step in stage.get("stepwiseExecution") or []
+            if isinstance(step, dict) and isinstance(step.get("step"), int)
+        ]
+        errs.extend(
+            ValidationError(
+                "S4",
+                number if isinstance(number, int) else 0,
+                f"stages[] stage {number} step {step} is duplicate",
+            )
+            for step, count in sorted(Counter(step_numbers).items())
+            if count > 1
+        )
+    return errs
+
+
 def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
     """The S-checks that schema v2 cannot express, over `implementationPlanning`.
 
@@ -482,11 +576,22 @@ def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
     covers presence and cardinality; this covers the relationships between
     fields, which is what a JSON Schema has no way to say.
     """
-    stage_map, errors = _data_stage_metas(planning.get("stageMap") or [])
+    if (
+        planning.get("planningContract") == "selected-direction"
+        and planning.get("outcome") == "direction-invalidated"
+    ):
+        return []
+
+    raw_stage_map = planning.get("stageMap") or []
+    stage_map, errors = _data_stage_metas(raw_stage_map)
     stages = [s for s in (planning.get("stages") or []) if isinstance(s, dict)]
     if not stage_map and not stages:
         return errors
 
+    identity_errors = _check_data_stage_identities(raw_stage_map, stages)
+    errors.extend(identity_errors)
+    if identity_errors:
+        return errors
     errors.extend(_check_data_step_counts(stage_map, stages))
     errors.extend(_check_depends_on(stage_map))
     errors.extend(_report_shared_parallel_files({

package/runtime/validators/validate-report-views.py

@@ -43,7 +43,7 @@ from okstra_ctl.report_views import (  # noqa: E402
 )
 from okstra_ctl.report_view_artifacts import html_view_path  # noqa: E402
 from okstra_ctl.final_report_paths import final_report_data_path  # noqa: E402
-from okstra_ctl.report_contract import TASK_TYPE_REQUIRED_HUMAN_FIELDS  # noqa: E402
+from okstra_ctl.report_contract import required_human_fields_for_report  # noqa: E402
 
 
 _EXTERNAL_URL_RE = re.compile(
@@ -98,7 +98,7 @@ def _validate_v2(report_path: Path, data_path: Path, data: dict) -> list[str]:
     if f'data-task-template="{task_type}"' not in html_text:
         failures.append(f"v2 html task template mismatch for {task_type}")
     actual_fields = set(re.findall(r'data-report-field="([^"]+)"', main_body))
-    for field in TASK_TYPE_REQUIRED_HUMAN_FIELDS.get(task_type, ()):
+    for field in required_human_fields_for_report(task_type, data):
         if field not in actual_fields:
             failures.append(f"missing human field: {field}")
 

package/runtime/validators/validate-run.py

@@ -71,7 +71,12 @@ from okstra_ctl.incremental_scope import (  # noqa: E402
     coverage_row_blocked_on,
     stages_for_clarification,
 )
-from okstra_ctl.workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE  # noqa: E402
+from okstra_ctl.workflow import (  # noqa: E402
+    DEFAULT_NEXT_PHASE,
+    ERROR_ANALYSIS_ROUTING_DIRECTIONS,
+    PHASE_SEQUENCE,
+    REQUIREMENTS_DISCOVERY_ROUTING_TARGETS,
+)
 from okstra_ctl.md_table import (  # noqa: E402
     is_separator_row as _is_markdown_separator,
     split_pipe_row as _split_pipe_row,
@@ -80,9 +85,16 @@ from okstra_ctl.final_report_paths import final_report_data_path as _data_path_f
 from okstra_ctl.improvement_assignment import (  # noqa: E402
     validate_primary_lens_assignments,
 )
+from okstra_ctl.implementation_options import (  # noqa: E402
+    validate_implementation_option_selection,
+)
+from okstra_ctl.implementation_direction import (  # noqa: E402
+    validate_selected_direction_plan,
+)
 from okstra_ctl.worker_prompt_policy import GRILLING_LOG_HEADER  # noqa: E402
 from okstra_ctl.scope_provenance import (  # noqa: E402
     brief_citation_problem,
+    brief_end_state_id_sequence,
     brief_end_state_ids,
     brief_headings,
     parse_source,
@@ -406,7 +418,28 @@ def _error_analysis_next_phase(data: Mapping[str, Any]) -> str | None:
     if not isinstance(routing, Mapping):
         return None
     target = routing.get("nextTaskType")
-    if target in {"error-analysis", "implementation-planning"}:
+    if target in ERROR_ANALYSIS_ROUTING_DIRECTIONS:
+        return str(target)
+    return None
+
+
+def _requirements_discovery_next_phase(data: Mapping[str, Any]) -> str | None:
+    if not isinstance(data, Mapping):
+        return None
+    header = data.get("header")
+    if (
+        not isinstance(header, Mapping)
+        or header.get("taskType") != "requirements-discovery"
+    ):
+        return None
+    requirements = data.get("requirementsDiscovery")
+    if not isinstance(requirements, Mapping):
+        return None
+    routing = requirements.get("routing")
+    if not isinstance(routing, Mapping):
+        return None
+    target = routing.get("nextTaskType")
+    if target in REQUIREMENTS_DISCOVERY_ROUTING_TARGETS:
         return str(target)
     return None
 
@@ -445,11 +478,12 @@ def update_workflow_metadata(
         # Validation just passed → actively advance to the next phase in
         # the sequence rather than preserving a stale value that may equal
         # current_phase (which would cause the lifecycle pointer to stall).
-        report_next_phase = (
-            _error_analysis_next_phase(report_data or {})
-            if current_phase == "error-analysis"
-            else None
-        )
+        if current_phase == "requirements-discovery":
+            report_next_phase = _requirements_discovery_next_phase(report_data or {})
+        elif current_phase == "error-analysis":
+            report_next_phase = _error_analysis_next_phase(report_data or {})
+        else:
+            report_next_phase = None
         next_recommended_phase = report_next_phase or advance_next_phase(
             current_phase, phase_sequence
         )
@@ -3142,10 +3176,15 @@ def _validate_error_analysis_consistency(
     target = routing.get("nextTaskType")
     leading_cause_id = routing.get("leadingCauseId")
     candidate_id_set = set(candidate_ids)
-    if target == "implementation-planning":
+    if isinstance(target, str) and target not in ERROR_ANALYSIS_ROUTING_DIRECTIONS:
+        failures.append(
+            "final-report data.json: errorAnalysis.routing has unsupported "
+            f"routing target `{target}`."
+        )
+    if target == "implementation-option-selection":
         if not candidates:
             failures.append(
-                "final-report data.json: implementation-planning routing requires "
+                "final-report data.json: implementation-option-selection routing requires "
                 "at least one cause candidate."
             )
         if (
@@ -3153,7 +3192,7 @@ def _validate_error_analysis_consistency(
             or leading_cause_id not in candidate_id_set
         ):
             failures.append(
-                "final-report data.json: implementation-planning routing "
+                "final-report data.json: implementation-option-selection routing "
                 "leadingCauseId must reference a cause candidate."
             )
     elif target == "error-analysis" and (
@@ -3165,10 +3204,7 @@ def _validate_error_analysis_consistency(
             "empty or reference a cause candidate."
         )
 
-    expected_direction = {
-        "implementation-planning": "begin-planning",
-        "error-analysis": "continue-investigation",
-    }.get(target)
+    expected_direction = ERROR_ANALYSIS_ROUTING_DIRECTIONS.get(target)
     verdict_card_value = data.get("verdictCard")
     verdict_card = (
         verdict_card_value if isinstance(verdict_card_value, Mapping) else {}
@@ -3230,7 +3266,7 @@ def _validate_error_analysis_consistency(
 
     if isinstance(target, str) and target in {
         "error-analysis",
-        "implementation-planning",
+        "implementation-option-selection",
     }:
         for field_name, value in (
             ("verdictCard.nextStep", verdict_card.get("nextStep")),
@@ -3373,7 +3409,25 @@ def validate_final_report_data(
 
     task_type = (data.get("header") or {}).get("taskType")
     _validate_verifier_fail_blocks_verdict(data, failures)
-    if task_type == "implementation":
+    if task_type == "implementation-option-selection":
+        selection = data.get("implementationOptionSelection") or {}
+        validation_root = project_root or report_path.parent
+        original_ids = brief_end_state_id_sequence(
+            _brief_path_from_manifest(manifest, validation_root)
+        )
+        roster = manifest.get("recommendedWorkers") or ()
+        participating_analysers = tuple(
+            worker for worker in roster if worker != "report-writer"
+        )
+        failures.extend(
+            f"implementation-option-selection: {error}"
+            for error in validate_implementation_option_selection(
+                selection,
+                original_ids,
+                participating_analysers,
+            )
+        )
+    elif task_type == "implementation":
         _validate_stage_carry_sidecar_exists(data, report_path, failures)
     if task_type == "error-analysis":
         _validate_error_analysis_consistency(data, failures)
@@ -3382,6 +3436,31 @@ def validate_final_report_data(
         _validate_verified_row_recorded(data, report_path, failures)
     elif task_type == "implementation-planning":
         active_report_contracts = report_contracts or set()
+        planning = data.get("implementationPlanning") or {}
+        selected_direction_contract = (
+            isinstance(planning, Mapping)
+            and planning.get("planningContract") == "selected-direction"
+        )
+        if selected_direction_contract:
+            validation_root = project_root or report_path.parent
+            try:
+                brief_path = _brief_path_from_manifest(manifest, validation_root)
+            except (OSError, ValueError) as exc:
+                failures.append(
+                    "implementation-planning selected-direction: run manifest "
+                    f"taskBriefPath is malformed: {exc}"
+                )
+                brief_path = validation_root / "__invalid-brief__"
+            task_root = _task_root_from_run_dir(report_path.parent.parent)
+            snapshot_path = task_root / "instruction-set" / "selected-direction.json"
+            failures.extend(
+                f"implementation-planning selected-direction: {error}"
+                for error in validate_selected_direction_plan(
+                    data, brief_path, snapshot_path
+                )
+            )
+            if planning.get("outcome") == "direction-invalidated":
+                return data
         _validate_implementation_planning_cross_project(data, failures)
         _validate_implementation_planning_decision_drafts(data, failures)
         for warning in validate_plan_body_section(data, report_path, failures):
@@ -3401,8 +3480,9 @@ def validate_final_report_data(
             resolve_architecture(_project_root_from_report(report_path)),
             failures,
         )
-        _validate_requirement_deviations(data, failures)
-        _validate_requirement_coverage_covered_by(data, failures)
+        if not selected_direction_contract:
+            _validate_requirement_deviations(data, failures)
+            _validate_requirement_coverage_covered_by(data, failures)
         warnings = _validate_design_prep_contract(
             data,
             report_path,
@@ -7803,6 +7883,13 @@ def _validate_stage_has_requirement(data: dict, failures: list[str]) -> None:
         )
 
 
+_FINAL_VERIFICATION_ROUTING_TOKEN_RE = re.compile(
+    r"(?<![A-Za-z-])(?:release-handoff\(stage-group\)|release-handoff|done|"
+    r"implementation|error-analysis|implementation-option-selection|"
+    r"implementation-planning)(?![A-Za-z-])"
+)
+
+
 def _validate_final_verification_consistency(data: dict, failures: list[str]) -> None:
     """Enforce verdict ↔ blocker/condition/routing consistency on the
     final-verification data.json (SSOT). The schema guarantees field SHAPE;
@@ -7817,7 +7904,16 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
     fv = data.get("finalVerification") or {}
     blockers = fv.get("acceptanceBlockers") or []
     conditions = verdict.get("conditionalAcceptanceConditions") or []
-    routing = fv.get("routingRecommendation") or ""
+    routing_value = fv.get("routingRecommendation")
+    routing = routing_value if isinstance(routing_value, str) else ""
+    routing_tokens = _FINAL_VERIFICATION_ROUTING_TOKEN_RE.findall(routing)
+    routing_token = routing_tokens[0] if len(routing_tokens) == 1 else None
+
+    if routing_token is None:
+        failures.append(
+            "final-verification: routingRecommendation must contain exactly one "
+            "supported routing token."
+        )
 
     if token == "accepted" and blockers:
         failures.append(
@@ -7834,7 +7930,10 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
             "final-verification: verdict `conditional-accept` but "
             "conditionalAcceptanceConditions is empty — list every condition."
         )
-    if "release-handoff" in routing and token != "accepted":
+    if (
+        routing_token in {"release-handoff", "release-handoff(stage-group)"}
+        and token != "accepted"
+    ):
         failures.append(
             f"final-verification: routingRecommendation cites `release-handoff` "
             f"but verdict is `{token}` — release-handoff routing is allowed only "
@@ -7847,8 +7946,7 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
             f"final-verification: verificationScope must be `whole-task` or "
             f"`single-stage`, got {scope!r}."
         )
-    if (scope == "single-stage" and "release-handoff" in routing
-            and "release-handoff(stage-group)" not in routing):
+    if scope == "single-stage" and routing_token == "release-handoff":
         failures.append(
             "final-verification: verificationScope `single-stage` cannot recommend "
             "plain release-handoff routing — a single-stage accepted verdict may "
@@ -9144,16 +9242,28 @@ def main() -> int:
         for warning in conformance_warnings:
             print(f"validate-run: warning: {warning}", file=sys.stderr)
     if task_type in _BRIEF_DERIVED_PHASES:
-        brief_path = _brief_path_from_manifest(task_manifest, project_root)
+        planning = validation_data.get("implementationPlanning")
+        selected_direction_plan = (
+            task_type == "implementation-planning"
+            and isinstance(planning, Mapping)
+            and planning.get("planningContract") == "selected-direction"
+        )
+        brief_path = (
+            project_root / "__selected-direction-brief-validated-from-run-manifest__"
+            if selected_direction_plan
+            else _brief_path_from_manifest(task_manifest, project_root)
+        )
         if task_type in _END_STATE_PHASES:
             if task_type == "implementation-planning":
                 _validate_planning_conformance_declared(report_path, failures)
-            _validate_end_state_coverage(validation_data, brief_path, failures)
-            if task_type == "implementation-planning":
+            if not selected_direction_plan:
+                _validate_end_state_coverage(validation_data, brief_path, failures)
+            if task_type == "implementation-planning" and not selected_direction_plan:
                 _validate_requirement_provenance(
                     validation_data, brief_path, failures
                 )
                 _validate_stage_has_requirement(validation_data, failures)
+            if task_type == "implementation-planning":
                 _append_stage_data_failures(validation_data, failures)
         if task_type == "improvement-discovery":
             run_dir = report_path.parent.parent

package/runtime/validators/validate_improvement_report.py

@@ -34,7 +34,11 @@ from okstra_ctl.md_table import split_pipe_row
 
 
 _VERDICT_TOKENS = ("candidates-ready", "no-candidates", "blocked")
-_NEXT_PHASES = ("requirements-discovery", "implementation-planning", "error-analysis")
+_NEXT_PHASES = (
+    "requirements-discovery",
+    "implementation-option-selection",
+    "error-analysis",
+)
 _CAND_ID_RE = re.compile(r"^I-\d{3}$")
 _SOURCE_WORKER_RE = re.compile(r"^([a-z-]+):([A-Za-z0-9._-]+)$")
 _CONSENSUS_VALUES = ("full", "partial", "contested", "worker-unique")

package/src/commands/execute/codex-run.mjs

@@ -16,6 +16,7 @@ Usage:
     [--antigravity-model <m>] [--report-writer-model <m>] \\
     [--related-tasks <list>] [--base-ref <ref>] \\
     [--clarification-response <path>] [--work-category <cat>] \\
+    [--selected-direction <selection-final-report.md>] \\
     [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>] \\
     [--fix-cycle <yes|no>]
 

package/src/commands/execute/render-bundle.mjs

@@ -21,6 +21,7 @@ Usage:
     [--lead-runtime auto|<host-id-or-alias>] \\
     [--related-tasks <list>] [--base-ref <ref>] \\
     [--clarification-response <path>] [--work-category <cat>] \\
+    [--selected-direction <selection-final-report.md>] \\
     [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>] \\
     [--fix-cycle <yes|no>]