okstra 0.172.0 → 0.173.0

package/runtime/python/okstra_ctl/run.py

@@ -26,6 +26,7 @@ import tempfile
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
+from typing import Sequence
 
 from okstra_project import project_json_path, upsert_project_json
 from okstra_project.state import slugify
@@ -48,6 +49,15 @@ from .clarification_items import (
 )
 from .error_report import prior_run_error_digest
 from .incremental_scope import ReverifyScopeError, parse_user_reverify_scope
+from .implementation_direction import (
+    DirectionSelectionError,
+    SelectedDirection,
+    lexical_absolute_path,
+    resolve_selected_direction,
+    validate_selected_direction_plan,
+    validate_task_artifact_path,
+    write_selected_direction_snapshot,
+)
 from .qa_commands import format_errors as _format_qa_errors, validate_qa_commands
 from .material import (
     build_analysis_material,
@@ -154,6 +164,7 @@ from .brief_frontmatter import (
     has_reporter_confirmation_contract,
     read_brief_frontmatter,
 )
+from .scope_provenance import brief_end_state_id_sequence
 
 # Frontmatter approval-flag matcher.
 #
@@ -183,6 +194,10 @@ IMPLEMENTATION_OPTION_FRONTMATTER_PATTERN = re.compile(
     r"^implementation-option:[ \t]*(.*)$",
     re.MULTILINE,
 )
+SELECTED_DIRECTION_FRONTMATTER_PATTERN = re.compile(
+    r"^selected-direction-ref:[ \t]*(.*)$",
+    re.MULTILINE,
+)
 
 # validators/validate-run.py:_FRONTMATTER_BLOCK_RE 의 미러 — 선행 BOM/빈 줄을
 # 허용해 두 모듈이 같은 리포트의 frontmatter 게이트를 동일하게 판정하게 한다.
@@ -393,6 +408,8 @@ class PrepareInputs:
     # 별개 채널이다.
     stages: str = ""
     clarification_response_path: str = ""  # absolute or empty
+    # implementation-planning 신규 실행 전용: 검증된 방향 선택 최종 보고서.
+    selected_direction_path: str = ""
     # implementation-planning 전용: 사용자가 고른 이번 재실행의 재검증 범위.
     # "" / "auto" = 리드의 `okstra incremental-scope` 판정에 맡김, "full" =
     # 전체 재검증 강제, "<stage csv>" = 그 stage 들을 impacted 로 지정.
@@ -781,6 +798,7 @@ def _canonical_argv(inp: PrepareInputs, ctx: dict) -> list[str]:
         ("--approved-plan", inp.approved_plan_path),
         ("--implementation-option", inp.implementation_option),
         ("--clarification-response", inp.clarification_response_path),
+        ("--selected-direction", inp.selected_direction_path),
         ("--workers", workers),
         ("--lead-provider", inp.lead_provider or ctx.get("LEAD_PROVIDER", "")),
         ("--lead-model", inp.lead_model or ctx.get("LEAD_MODEL", "")),
@@ -992,6 +1010,13 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
         pass
     elif not inp.brief_path.is_file():
         raise PrepareError(f"task brief not found: {inp.brief_path}")
+    elif inp.task_type == "implementation-option-selection" and not brief_end_state_id_sequence(
+        inp.brief_path
+    ):
+        raise PrepareError(
+            "regenerate the brief with stable end-state IDs before starting "
+            "implementation-option-selection"
+        )
     ctx_stage_map: list = []
     # implementation 과 final-verification 은 둘 다 승인된 plan 의 Stage Map 을
     # 입력으로 받는다(전자는 실행 scope, 후자는 검증 scope).
@@ -1041,10 +1066,123 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
         raise PrepareError(
             f"clarification response file not found: {inp.clarification_response_path}"
         )
+    _validate_planning_entry_inputs(project_root, inp)
     _validate_reverify_scope(inp)
     return ctx_stage_map
 
 
+_PLANNING_REPORT_RE = re.compile(
+    r"^final-report-implementation-planning-\d{3,}\.md$"
+)
+
+
+def _resolve_planning_input_path(
+    path_value: str, project_root: Path
+) -> Path | None:
+    """Resolve cwd-first planning inputs without following symbolic links."""
+    raw_path = Path(path_value).expanduser()
+    cwd_candidate = lexical_absolute_path(raw_path)
+    if cwd_candidate.is_file():
+        return cwd_candidate
+    if not raw_path.is_absolute():
+        project_candidate = lexical_absolute_path(project_root / raw_path)
+        if project_candidate.is_file():
+            return project_candidate
+    return None
+
+
+def _is_existing_planning_report(
+    path_value: str, project_root: Path, inp: PrepareInputs
+) -> bool:
+    from .paths import task_dir
+
+    try:
+        report = lexical_absolute_path(Path(path_value))
+        task_root = lexical_absolute_path(
+            task_dir(project_root, inp.task_group, inp.task_id)
+        )
+        relative = report.relative_to(task_root)
+    except ValueError:
+        return False
+    has_planning_layout = (
+        _PLANNING_REPORT_RE.fullmatch(report.name) is not None
+        and relative.parts[:3] == (
+            "runs",
+            "implementation-planning",
+            "reports",
+        )
+        and len(relative.parts) == 4
+    )
+    if not has_planning_layout:
+        return False
+    try:
+        validate_task_artifact_path(report, task_root, "planning report")
+    except DirectionSelectionError:
+        return False
+    return True
+
+
+def _validate_planning_entry_inputs(
+    project_root: Path, inp: PrepareInputs
+) -> None:
+    if inp.task_type != "implementation-planning":
+        if inp.selected_direction_path:
+            raise PrepareError(
+                "--selected-direction is only meaningful with --task-type "
+                f"implementation-planning; got {inp.task_type}"
+            )
+        return
+    if inp.selected_direction_path and inp.clarification_response_path:
+        raise PrepareError(
+            "implementation-planning accepts either --selected-direction for a "
+            "new plan or --clarification-response for a rerun, not both"
+        )
+    if inp.selected_direction_path:
+        return
+    if inp.clarification_response_path:
+        if not _is_existing_planning_report(
+            inp.clarification_response_path, project_root, inp
+        ):
+            raise PrepareError(
+                "implementation-planning rerun --clarification-response must point "
+                "to an existing implementation-planning report for the same task"
+            )
+        return
+    raise PrepareError(
+        "implementation-planning requires --selected-direction for a new plan or "
+        "--clarification-response to an existing implementation-planning report"
+    )
+
+
+def _resolve_planning_direction(inp: PrepareInputs) -> SelectedDirection | None:
+    if inp.task_type != "implementation-planning" or not inp.selected_direction_path:
+        return None
+    from .paths import task_dir
+
+    try:
+        report = lexical_absolute_path(Path(inp.selected_direction_path))
+        expected_task_root = lexical_absolute_path(
+            task_dir(Path(inp.project_root), inp.task_group, inp.task_id)
+        )
+        report.relative_to(expected_task_root)
+    except ValueError as exc:
+        raise PrepareError(
+            "selected direction report must belong to the same task"
+        ) from exc
+    try:
+        validate_task_artifact_path(
+            report, expected_task_root, "selected direction report"
+        )
+        return resolve_selected_direction(
+            report,
+            expected_task_key=(
+                f"{inp.project_id}:{inp.task_group}:{inp.task_id}"
+            ),
+        )
+    except DirectionSelectionError as exc:
+        raise PrepareError(str(exc)) from exc
+
+
 def _validate_reverify_scope(inp: PrepareInputs) -> None:
     """A pinned re-verification scope is only actionable on a planning re-run.
 
@@ -1070,8 +1208,165 @@ def _validate_reverify_scope(inp: PrepareInputs) -> None:
         raise PrepareError(str(exc)) from exc
 
 
+def _implementation_plan_contract(
+    inp: PrepareInputs,
+) -> tuple[str, Path, dict | None]:
+    """Classify an implementation plan from its sibling data.json contract."""
+    plan_path = Path(inp.approved_plan_path)
+    body = plan_path.read_text(encoding="utf-8", errors="replace")
+    frontmatter = _extract_frontmatter_block(body) or ""
+    markdown_ref_match = SELECTED_DIRECTION_FRONTMATTER_PATTERN.search(frontmatter)
+    markdown_ref: str | None = None
+    if markdown_ref_match is not None:
+        markdown_ref = markdown_ref_match.group(1).strip()
+        if markdown_ref.startswith('"'):
+            try:
+                markdown_ref = json.loads(markdown_ref)
+            except json.JSONDecodeError as exc:
+                raise PrepareError(
+                    "selected-direction plan markdown `selected-direction-ref` is "
+                    "not a valid quoted string"
+                ) from exc
+        elif len(markdown_ref) >= 2 and markdown_ref[0] == markdown_ref[-1] == "'":
+            markdown_ref = markdown_ref[1:-1].replace("''", "'")
+        if not isinstance(markdown_ref, str) or not markdown_ref.strip():
+            raise PrepareError(
+                "selected-direction plan markdown `selected-direction-ref` must "
+                "be a non-empty string"
+            )
+    loaded = _load_final_report_data_if_present(plan_path)
+    if loaded is None:
+        if markdown_ref_match is not None:
+            raise PrepareError(
+                "selected-direction plan requires its sibling data.json before "
+                f"implementation entry: {_final_report_data_path(plan_path)}"
+            )
+        return "legacy", plan_path, None
+    _, data = loaded
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        raise PrepareError(
+            "approved plan sibling data.json must contain an "
+            "implementationPlanning object"
+        )
+    contract = planning.get("planningContract")
+    selected_payload = any(
+        field in planning
+        for field in (
+            "selectedDirectionRef",
+            "directionRealization",
+            "directionInvalidation",
+            "outcome",
+        )
+    )
+    if contract is None:
+        if markdown_ref_match is not None or selected_payload:
+            raise PrepareError(
+                "selected-direction markers require "
+                "implementationPlanning.planningContract=`selected-direction`; "
+                "the markdown `selected-direction-ref` and data contract disagree"
+            )
+        return "legacy", plan_path, data
+    if contract != "selected-direction":
+        raise PrepareError(
+            "approved plan sibling data.json has unsupported planningContract "
+            f"{contract!r}"
+        )
+    if markdown_ref_match is None:
+        raise PrepareError(
+            "selected-direction plan markdown frontmatter must contain "
+            "`selected-direction-ref:`"
+        )
+    selected_ref = planning.get("selectedDirectionRef")
+    snapshot_ref = (
+        selected_ref.get("snapshotPath")
+        if isinstance(selected_ref, dict)
+        else None
+    )
+    if not isinstance(markdown_ref, str) or markdown_ref != snapshot_ref:
+        raise PrepareError(
+            "selected-direction plan markdown `selected-direction-ref` must "
+            "exactly match implementationPlanning.selectedDirectionRef.snapshotPath"
+        )
+    if IMPLEMENTATION_OPTION_FRONTMATTER_PATTERN.search(frontmatter):
+        raise PrepareError(
+            "selected-direction plan must not contain an `implementation-option:` "
+            "frontmatter field"
+        )
+    return "selected-direction", plan_path, data
+
+
+def _validate_selected_implementation_plan(
+    inp: PrepareInputs,
+    plan_path: Path,
+    data: dict,
+) -> None:
+    """Apply the Task 8 selected-direction semantics at implementation entry."""
+    planning = data.get("implementationPlanning") or {}
+    if planning.get("outcome") != "plan-ready":
+        raise PrepareError(
+            "selected-direction plan is not implementation-ready: "
+            f"outcome={planning.get('outcome')!r}; direction-invalidated plans "
+            "must re-enter implementation-option-selection"
+        )
+    summary = planning.get("coverageSummary") or {}
+    if summary.get("coverageVerdict") != "exact":
+        raise PrepareError(
+            "selected-direction plan requires exact coverage before implementation"
+        )
+
+    from .paths import task_dir
+
+    expected_task_root = lexical_absolute_path(
+        task_dir(Path(inp.project_root), inp.task_group, inp.task_id)
+    )
+    try:
+        validate_task_artifact_path(plan_path, expected_task_root, "approved plan")
+        data_path = validate_task_artifact_path(
+            _final_report_data_path(plan_path),
+            expected_task_root,
+            "approved plan data.json",
+        )
+        if data_path != _final_report_data_path(plan_path):
+            raise DirectionSelectionError("approved plan data.json must be a sibling")
+        snapshot_path = validate_task_artifact_path(
+            expected_task_root / "instruction-set" / "selected-direction.json",
+            expected_task_root,
+            "selected direction snapshot",
+        )
+        brief_path = validate_task_artifact_path(
+            expected_task_root / "instruction-set" / "task-brief.md",
+            expected_task_root,
+            "selected direction task brief",
+        )
+    except DirectionSelectionError as exc:
+        raise PrepareError(f"selected-direction plan input is invalid: {exc}") from exc
+
+    expected_task_key = f"{inp.project_id}:{inp.task_group}:{inp.task_id}"
+    actual_task_key = (data.get("header") or {}).get("taskKey")
+    if actual_task_key != expected_task_key:
+        raise PrepareError(
+            "selected-direction plan header.taskKey must match the implementation "
+            f"task: expected {expected_task_key!r}, got {actual_task_key!r}"
+        )
+    failures = validate_selected_direction_plan(data, brief_path, snapshot_path)
+    if failures:
+        raise PrepareError(
+            "selected-direction plan failed implementation entry validation:\n  - "
+            + "\n  - ".join(failures)
+        )
+
+
 def _prepare_implementation_approved_plan(inp: PrepareInputs) -> list:
     """Apply approved-plan inputs only after canonical brief preflight succeeds."""
+    contract, plan_path, data = _implementation_plan_contract(inp)
+    if contract == "selected-direction":
+        assert data is not None
+        _validate_selected_implementation_plan(inp, plan_path, data)
+        if inp.implementation_option:
+            raise PrepareError(
+                "--implementation-option is not accepted for a selected-direction plan"
+            )
     if inp.approve_plan_ack or inp.implementation_option:
         with worktree_provision_mutex(
             okstra_home(), inp.project_id,
@@ -1083,7 +1378,11 @@ def _prepare_implementation_approved_plan(inp: PrepareInputs) -> list:
                 _apply_cli_implementation_option(
                     inp.approved_plan_path, inp.implementation_option
                 )
+    contract, plan_path, data = _implementation_plan_contract(inp)
     _validate_approved_plan(inp.approved_plan_path)
+    if contract == "selected-direction":
+        assert data is not None
+        _validate_selected_implementation_plan(inp, plan_path, data)
     _validate_stage_structure(inp.approved_plan_path)
     return _parse_stage_map_into_ctx(inp.approved_plan_path)
 
@@ -1348,9 +1647,23 @@ def _resolve_roster(inp: PrepareInputs, profile_file: Path) -> tuple[list[str],
         validate_workers_against_profile(workers, profile_workers, optional_workers)
     if not workers:
         raise PrepareError(f"no workers resolved for profile: {inp.task_type}")
+    _validate_option_selection_roster(inp.task_type, workers)
     return workers, ",".join(workers)
 
 
+def _validate_option_selection_roster(
+    task_type: str, workers: Sequence[str]
+) -> None:
+    """Require independent analysis from three workers before option selection."""
+    if task_type != "implementation-option-selection":
+        return
+    analyser_count = sum(worker != "report-writer" for worker in workers)
+    if analyser_count < 3:
+        raise PrepareError(
+            "implementation-option-selection requires at least 3 analyser workers"
+        )
+
+
 def _resolve_pr_template(inp: PrepareInputs) -> tuple[str, str]:
     """release-handoff 전용 PR 본문 템플릿 경로 + 출처를 해소한다 (그 외엔 빈 값)."""
     if inp.task_type != "release-handoff":
@@ -1987,11 +2300,17 @@ def _write_instruction_set_sources(
     profile_content: str,
     review_material: str,
     host_rules_file: Path | None,
+    selected_direction: SelectedDirection | None,
 ) -> Path:
     """instruction-set 디렉터리에 profile/material/brief/clarification/directive 와
     reference-expectations 를 기록하고 디렉터리 경로를 돌려준다."""
     instruction_set = Path(ctx["INSTRUCTION_SET_PATH"])
     instruction_set.mkdir(parents=True, exist_ok=True)
+    if selected_direction is not None:
+        write_selected_direction_snapshot(
+            selected_direction,
+            instruction_set / "selected-direction.json",
+        )
     _write_analysis_evidence_artifact(ctx, instruction_set)
     _write_verification_target_artifact(inp, ctx, instruction_set)
     _write_prior_run_error_digest(ctx, instruction_set)
@@ -2252,6 +2571,7 @@ def _persist_run_inputs(
             "relatedTasks": inp.related_tasks_raw,
             "approvedPlanPath": approved_plan_path,
             "clarificationResponsePath": inp.clarification_response_path,
+            "selectedDirectionPath": inp.selected_direction_path,
             "analysisTarget": json.loads(ctx.get("ANALYSIS_TARGET_JSON", "{}")).get(
                 "requestedValue", ""
             ),
@@ -2796,6 +3116,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             inp.brief_path,
             assets.brief_validator,
         )
+    selected_direction = _resolve_planning_direction(inp)
     if inp.task_type == "implementation":
         ctx_stage_map = _prepare_implementation_approved_plan(inp)
 
@@ -2929,6 +3250,10 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         relative_to_project_root(Path(inp.clarification_response_path), project_root)
         if inp.clarification_response_path else ""
     )
+    selected_direction_relative = (
+        relative_to_project_root(Path(inp.selected_direction_path), project_root)
+        if inp.selected_direction_path else ""
+    )
 
     forbidden_by_phase = load_phase_forbidden(workspace_root)
 
@@ -2946,6 +3271,8 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "CLAUDE_SESSION_ID": claude_session_id,
         "CLARIFICATION_RESPONSE_PATH": inp.clarification_response_path,
         "CLARIFICATION_RESPONSE_RELATIVE_PATH": clarification_relative,
+        "SELECTED_DIRECTION_PATH": inp.selected_direction_path,
+        "SELECTED_DIRECTION_RELATIVE_PATH": selected_direction_relative,
         **_reverify_scope_ctx(inp.reverify_scope),
         "BRIEF_FILE_PATH": str(inp.brief_path),
         "BRIEF_RELATIVE_PATH": brief_relative,
@@ -2978,7 +3305,12 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
 
     # ---- write instruction-set scaffolding ----
     instruction_set = _write_instruction_set_sources(
-        inp, ctx, profile_content, review_material, assets.host_rules_file
+        inp,
+        ctx,
+        profile_content,
+        review_material,
+        assets.host_rules_file,
+        selected_direction,
     )
     # ---- run-inputs persistence ----
     _persist_run_inputs(inp, ctx, models, selected_reviewers, brief_relative)
@@ -3134,6 +3466,7 @@ def main(argv: list[str]) -> int:
         ),
     )
     p.add_argument("--clarification-response", default="", dest="clarification_response_path")
+    p.add_argument("--selected-direction", default="", dest="selected_direction_path")
     p.add_argument(
         "--reverify-scope",
         default="",
@@ -3212,7 +3545,9 @@ def main(argv: list[str]) -> int:
             return 1
     clarification_abs = ""
     if args.clarification_response_path:
-        cr = resolve_user_file(args.clarification_response_path, project_root)
+        cr = _resolve_planning_input_path(
+            args.clarification_response_path, project_root
+        )
         if cr is None:
             print(
                 f"clarification response file not found: {args.clarification_response_path}",
@@ -3220,6 +3555,18 @@ def main(argv: list[str]) -> int:
             )
             return 1
         clarification_abs = str(cr)
+    selected_direction_abs = ""
+    if args.selected_direction_path:
+        selected = _resolve_planning_input_path(
+            args.selected_direction_path, project_root
+        )
+        if selected is None:
+            print(
+                f"selected direction report not found: {args.selected_direction_path}",
+                file=__import__("sys").stderr,
+            )
+            return 1
+        selected_direction_abs = str(selected)
 
     inputs = PrepareInputs(
         workspace_root=Path(args.workspace_root).resolve(),
@@ -3254,6 +3601,7 @@ def main(argv: list[str]) -> int:
         stage=args.stage,
         stages=args.stages,
         clarification_response_path=clarification_abs,
+        selected_direction_path=selected_direction_abs,
         reverify_scope=args.reverify_scope,
         pr_template_path=args.pr_template_path,
         render_only=args.render_only,

package/runtime/python/okstra_ctl/scope_provenance.py

@@ -89,8 +89,8 @@ def brief_headings(brief_path: Path) -> set[str]:
     return headings
 
 
-def brief_end_state_ids(brief_path: Path) -> set[str]:
-    """End-state ids the brief declares, across all three sections.
+def brief_end_state_id_sequence(brief_path: Path) -> tuple[str, ...]:
+    """End-state ids the brief declares, preserving section and item order.
 
     The reading rules mirror validators/validate-brief.py exactly, because that
     file checks the very same lines for their format and the two readers must
@@ -106,16 +106,17 @@ def brief_end_state_ids(brief_path: Path) -> set[str]:
     accepted — is the worse failure: the brief passes, the id is absent from the
     declared set, and no phase is ever asked to account for it.
 
-    An empty set means the brief predates the end-state sections, which is what
-    the downstream conditional gate keys on: a legacy brief keeps the legacy
-    path instead of being wedged by a contract it was never written against.
+    An empty sequence means the brief predates the end-state sections, which is
+    what the downstream conditional gate keys on: a legacy brief keeps the
+    legacy path instead of being wedged by a contract it was never written
+    against.
     """
     try:
         text = _HTML_COMMENT_RE.sub("", Path(brief_path).read_text(encoding="utf-8"))
     except OSError:
-        return set()
+        return ()
 
-    ids: set[str] = set()
+    ids: list[str] = []
     section = ""
     for line in text.splitlines():
         if m := _SECTION_HEADING_RE.match(line):
@@ -125,8 +126,13 @@ def brief_end_state_ids(brief_path: Path) -> set[str]:
         if not section:
             continue
         if m := _END_STATE_BULLET_RE.match(line.strip()):
-            ids.add(m.group("id"))
-    return ids
+            ids.append(m.group("id"))
+    return tuple(ids)
+
+
+def brief_end_state_ids(brief_path: Path) -> set[str]:
+    """End-state ids the brief declares, across all three sections."""
+    return set(brief_end_state_id_sequence(brief_path))
 
 
 @dataclass(frozen=True)

package/runtime/python/okstra_ctl/user_response.py

@@ -20,6 +20,7 @@ from typing import Optional
 
 from okstra_ctl.report_views import (
     PLAN_DECISION_APPROVED,
+    normalize_direction_selection_identity,
     serialize_user_response, UserResponseEntry, UserPlanDecision, infer_run_meta,
     parse_expected_form_options,
 )
@@ -36,6 +37,9 @@ from okstra_ctl.clarification_items import (
 _PLAN_DECISION_HEADING_RE = re.compile(r"^## PLAN DECISION\s*$", re.MULTILINE)
 _NEXT_RESPONSE_HEADING_RE = re.compile(r"^## ", re.MULTILINE)
 _ANALYSIS_REVIEW_HEADING_RE = re.compile(r"^## ANALYSIS REVIEW\s*$", re.MULTILINE)
+_DIRECTION_SELECTION_HEADING_RE = re.compile(
+    r"^## DIRECTION SELECTION\s*$", re.MULTILINE
+)
 _ANALYSIS_SIDECAR_HEADING_RE = re.compile(
     r"^## (?P<filename>user-response-[^\n]+\.md)\s*$", re.MULTILINE
 )
@@ -79,6 +83,20 @@ class AnalysisReviewRecord:
     seq: str
 
 
+@dataclass(frozen=True)
+class DirectionSelectionRecord:
+    status: str
+    option_id: str
+    option_name: str
+    confirmed: bool
+    selection_note: str
+    constraints: str
+    source_report: str
+    source_data: str
+    source_data_sha256: str
+    seq: str
+
+
 _ANALYSIS_REVIEW_STATUSES = frozenset({
     "accepted",
     "revision-requested",
@@ -405,6 +423,19 @@ def _field(block: str, key: str) -> Optional[str]:
     return m.group(1) if m else None
 
 
+def _direction_identity_fields(block: str) -> tuple[str, str]:
+    match = re.search(
+        r"^- Option-ID:[ \t]*(?P<option_id>[^\r\n]*)\r?\n"
+        r"- Option-Name:[ \t]*(?P<option_name>[^\r\n]*)\r?\n"
+        r"- Confirmed:",
+        block,
+        re.MULTILINE,
+    )
+    if match is None:
+        return "", ""
+    return match.group("option_id"), match.group("option_name")
+
+
 def _value(block: str) -> str:
     # Value 는 "- Value:" 다음 줄들의 "  > " 인용 블록.
     m = re.search(r"^- Value:\s*\n((?:\s*>.*\n?)+)", block, re.MULTILINE)
@@ -414,6 +445,50 @@ def _value(block: str) -> str:
     return "\n".join(lines).strip()
 
 
+def parse_direction_selection(
+    sidecar_text: str,
+) -> DirectionSelectionRecord | None:
+    matches = list(_DIRECTION_SELECTION_HEADING_RE.finditer(sidecar_text))
+    if not matches:
+        return None
+    if len(matches) != 1:
+        raise UserResponseError(
+            "DIRECTION SELECTION requires exactly one block"
+        )
+    block = sidecar_text[matches[0].end():]
+    next_heading = _NEXT_RESPONSE_HEADING_RE.search(block)
+    if next_heading:
+        block = block[:next_heading.start()]
+    status = _field(block, "Status")
+    if status != "selected":
+        raise UserResponseError("DIRECTION SELECTION Status must be selected")
+    confirmed = _field(block, "Confirmed")
+    if confirmed != "true":
+        raise UserResponseError("DIRECTION SELECTION Confirmed must be true")
+    raw_option_id, raw_option_name = _direction_identity_fields(block)
+    try:
+        option_id, option_name = normalize_direction_selection_identity(
+            raw_option_id,
+            raw_option_name,
+        )
+    except ValueError as error:
+        raise UserResponseError(str(error)) from error
+    return DirectionSelectionRecord(
+        status=status,
+        option_id=option_id,
+        option_name=option_name,
+        confirmed=True,
+        selection_note=_quoted_review_value(block, "Selection-Note"),
+        constraints=_quoted_review_value(block, "Constraints"),
+        source_report=_sidecar_metadata_value(sidecar_text, "source-report"),
+        source_data=_sidecar_metadata_value(sidecar_text, "source-data"),
+        source_data_sha256=_sidecar_metadata_value(
+            sidecar_text, "source-data-sha256"
+        ),
+        seq=_sidecar_metadata_value(sidecar_text, "seq"),
+    )
+
+
 def parse_user_response_entries(sidecar_text: str) -> list[UserResponseEntry]:
     """Reverse of ``serialize_user_response`` for the per-response ``## C-*``
     blocks. The ``## PLAN DECISION`` block is skipped (read separately by