okstra 0.205.0 → 0.206.0

package/runtime/python/okstra_ctl/stage_targets.py

@@ -1,7 +1,11 @@
 """Stage readiness and verification target rules.
 
-This module owns the policy that decides which Stage Map stage can run, which
-commit it branches from, and what final-verification should inspect. It keeps
+This module owns the policy that decides which Stage Map stage can run and which
+commit it branches from, plus the Git and ledger facts final-verification builds
+its target from (whole-task integration, the stage that contains every other
+done stage, teardown after the verdict). Which of those facts a
+final-verification run uses is decided in
+``phases/final_verification/target.py``. It keeps
 the stage lifecycle rules behind one interface instead of leaking raw
 ``consumers.jsonl`` rows and git ancestry checks into prepare callers.
 """
@@ -10,13 +14,11 @@ from __future__ import annotations
 import heapq
 import subprocess
 import sys
-from dataclasses import dataclass, replace
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-from .plan_run_root import plan_run_root_from_approved_plan
 from .prepare_error import PrepareError  # noqa: F401 — 재노출(단일 참조점)
-from .stage_integrate import IntegrateResult
 from okstra_project.slug import slugify
 
 
@@ -37,32 +39,6 @@ class FinalVerificationTarget:
     reports: list[str]
 
 
-@dataclass(frozen=True)
-class FinalVerificationTargetRequest:
-    """Semantic inputs needed to acquire one final-verification target."""
-
-    project_root: Path
-    project_id: str
-    task_group: str
-    task_id: str
-    work_category: str
-    approved_plan_path: Path
-    stage: int | None
-    stage_map: tuple[dict[str, Any], ...]
-
-
-@dataclass(frozen=True)
-class FinalVerificationTargetAcquisition:
-    """Resolved target facts returned to the prepare adapter."""
-
-    target: FinalVerificationTarget
-    worktree_branch: str
-    integration_result: IntegrateResult | None
-    # whole-task 진입이 task worktree 안에서 꺼낸 중첩 stage worktree.
-    # `{"stage": N, "from": <old path>, "to": <new path>}` 행.
-    relocations: tuple[dict[str, Any], ...] = ()
-
-
 @dataclass(frozen=True)
 class StageLifecycle:
     stage: int
@@ -809,117 +785,6 @@ def resolve_and_integrate_whole_task(
         )
 
 
-def _resolve_single_stage_target(
-    *,
-    requested_stage: int,
-    done_rows: list[dict[str, Any]],
-    stage_base: str,
-    stage_worktree_path: str,
-    stage_head: str,
-    stage_dirty: bool,
-) -> FinalVerificationTarget:
-    """Resolve single-stage final-verification target, enforcing all gates."""
-    from .consumers import latest_done_by_stage
-
-    n = requested_stage
-    done_by_stage = latest_done_by_stage(done_rows)
-    if n not in done_by_stage:
-        raise StageTargetError(
-            f"final-verification(single-stage): stage {n} not done — "
-            f"run implementation --stage {n} first"
-        )
-    if not stage_worktree_path:
-        raise StageTargetError(
-            f"final-verification(single-stage): stage worktree not found for "
-            f"stage {n} (torn down?) — use whole-task mode (--stage auto)"
-        )
-    if stage_dirty:
-        raise StageTargetError(
-            "final-verification: worktree has uncommitted source changes "
-            "(outside .okstra/) — commit or stash before verifying"
-        )
-    return FinalVerificationTarget(
-        scope="single-stage",
-        base=stage_base,
-        head=stage_head,
-        worktree_path=stage_worktree_path,
-        stages=[n],
-        reports=[done_by_stage[n].get("report_path", "")],
-    )
-
-
-def _read_final_verification_done_rows(
-    request: FinalVerificationTargetRequest,
-    registry_coordinates: tuple[str, str, str],
-) -> list[dict[str, Any]]:
-    from .consumers import backfill_done_from_carry, read_stage_consumer_state
-    from .stage_reconcile import auto_reconcile_best_effort
-
-    plan_run_root = plan_run_root_from_approved_plan(request.approved_plan_path)
-    backfill_done_from_carry(plan_run_root)
-    project_id, task_group, task_id = registry_coordinates
-    auto_reconcile_best_effort(
-        replace(
-            request,
-            project_id=project_id,
-            task_group=task_group,
-            task_id=task_id,
-        ),
-        plan_run_root,
-    )
-    return read_stage_consumer_state(plan_run_root).done_rows
-
-
-def _final_verification_registry_coordinates(
-    request: FinalVerificationTargetRequest,
-) -> tuple[str, str, str]:
-
-    def segment(value: str) -> str:
-        return slugify(value) or "_"
-
-    return (
-        segment(request.project_id),
-        segment(request.task_group),
-        segment(request.task_id),
-    )
-
-
-def _acquire_single_stage_target(
-    request: FinalVerificationTargetRequest,
-    done_rows: list[dict[str, Any]],
-    registry_coordinates: tuple[str, str, str],
-) -> FinalVerificationTargetAcquisition:
-    from . import worktree_registry
-    from .worktree import _git, is_dirty_excluding_okstra
-
-    stage = request.stage
-    assert stage is not None
-    row = worktree_registry.get_stage_row(*registry_coordinates, stage)
-    worktree_path = (row or {}).get("worktree_path", "")
-    head = ""
-    if worktree_path and Path(worktree_path).is_dir():
-        head_result = _git(worktree_path, "rev-parse", "HEAD")
-        if head_result.returncode == 0:
-            head = head_result.stdout.strip()
-    if not head:
-        worktree_path = ""
-    target = _resolve_single_stage_target(
-        requested_stage=stage,
-        done_rows=done_rows,
-        stage_base=(row or {}).get("base_ref", ""),
-        stage_worktree_path=worktree_path,
-        stage_head=head,
-        stage_dirty=(
-            is_dirty_excluding_okstra(worktree_path) if worktree_path else False
-        ),
-    )
-    return FinalVerificationTargetAcquisition(
-        target=target,
-        worktree_branch=(row or {}).get("branch", ""),
-        integration_result=None,
-    )
-
-
 def single_containing_head(project_root: Path,
                            heads: dict[int, str]) -> int | None:
     """주어진 stage 들의 commit 을 혼자서 모두 담고 있는 stage. 없으면 None.
@@ -952,117 +817,12 @@ def containing_stage(project_root: Path,
     return single_containing_head(project_root, heads)
 
 
-def _acquire_tip_stage_target(
-    request: FinalVerificationTargetRequest,
-    done_rows: list[dict[str, Any]],
-    registry_coordinates: tuple[str, str, str],
-) -> FinalVerificationTargetAcquisition | None:
-    """전체를 담은 단일 stage 브랜치가 있으면 그것을 whole-task 검증 대상으로
-    삼는다 — 머지 없이. 없거나 그 워크트리가 쓸 수 없으면 None 을 돌려 기존
-    task 브랜치 통합 경로로 넘긴다."""
-    from . import worktree_registry
-    from .consumers import latest_done_by_stage
-    from .worktree import _git, is_dirty_excluding_okstra
-
-    done = latest_done_by_stage(done_rows)
-    planned = [int(s["stage_number"]) for s in request.stage_map]
-    if any(n not in done for n in planned):
-        return None  # 미완 stage 의 거부 메시지는 기존 경로가 낸다
-    tip = containing_stage(request.project_root,
-                          {n: done[n] for n in planned})
-    if tip is None:
-        return None
-    row = worktree_registry.get_stage_row(*registry_coordinates, tip) or {}
-    worktree_path = row.get("worktree_path", "")
-    if not worktree_path or not Path(worktree_path).is_dir():
-        return None
-    head_result = _git(worktree_path, "rev-parse", "HEAD")
-    if head_result.returncode != 0:
-        return None
-    head = head_result.stdout.strip()
-    if head != done[tip].get("head_commit", ""):
-        # 브랜치 tip 이 done 기록과 갈라져 있다. 검증 대상이 무엇인지 모호하므로
-        # 판정을 기존 경로로 넘긴다.
-        return None
-    if is_dirty_excluding_okstra(worktree_path):
-        raise StageTargetError(
-            "final-verification: worktree has uncommitted source changes "
-            "(outside .okstra/) — commit or stash before verifying"
-        )
-    anchor_base = worktree_registry.get_implementation_base(
-        *registry_coordinates) or ""
-    stages = sorted(planned)
-    return FinalVerificationTargetAcquisition(
-        target=FinalVerificationTarget(
-            scope="whole-task",
-            base=anchor_base,
-            head=head,
-            worktree_path=worktree_path,
-            stages=stages,
-            reports=[done[n].get("report_path", "") for n in stages],
-        ),
-        relocations=(),
-        worktree_branch=row.get("branch", ""),
-        integration_result=None,
-    )
-
-
-def _acquire_whole_task_target(
-    request: FinalVerificationTargetRequest,
-    done_rows: list[dict[str, Any]],
-    registry_coordinates: tuple[str, str, str],
-) -> FinalVerificationTargetAcquisition:
-    from . import worktree_registry
-
-    tip = _acquire_tip_stage_target(request, done_rows, registry_coordinates)
-    if tip is not None:
-        return tip
-
-    project_id, task_group, task_id = registry_coordinates
-    entry = worktree_registry.lookup(project_id, task_group, task_id)
-    worktree_path = (
-        entry.worktree_path if entry is not None else str(request.project_root)
-    )
-    relocations = (
-        relocate_nested_stage_worktrees(
-            project_id, task_group, task_id, worktree_path,
-            stages=[int(row["stage_number"]) for row in request.stage_map],
-        )
-        if entry is not None
-        else []
-    )
-    whole = _resolve_and_integrate_whole_task_unlocked(
-        project_id=project_id,
-        task_group=task_group,
-        task_id=task_id,
-        task_worktree_path=worktree_path,
-        stage_map=list(request.stage_map),
-        done_rows=done_rows,
-        anchor_base=(
-            worktree_registry.get_implementation_base(
-                project_id, task_group, task_id
-            )
-            or ""
-        ),
-        # 정리는 판정 뒤로 미룬다(Phase 7 `teardown-stages`). 되돌릴 수 없는 정리를
-        # 판정 앞에 두면, 재작업이 가장 필요한 blocked 판정에서 stage 작업물이 이미
-        # 사라져 있다. 여기서는 통합만 하고 worktree/registry 키는 남긴다.
-        teardown=False,
-    )
-    return FinalVerificationTargetAcquisition(
-        target=whole["target"],
-        relocations=tuple(relocations),
-        worktree_branch=entry.branch if entry is not None else "",
-        integration_result=whole["integrate_result"],
-    )
-
-
 def integrate_and_teardown_whole_task(
     *, project_root: Path, task_group: str, task_id: str,
 ) -> dict[str, Any]:
     """판정이 끝난 whole-task 검증의 stage worktree 와 registry 키를 회수한다.
 
-    진입은 통합만 하고 정리를 남겨 두므로(`_resolve_whole_task_acquisition`), 정리는
+    진입은 통합만 하고 정리를 남겨 두므로(`phases/final_verification/target.py`), 정리는
     판정 뒤인 Phase 7 에서 여기로 들어온다. 통합은 이미 끝나 있어 Phase A 는 전부
     `already_merged` 로 지나가고 Phase B 만 실제 일을 한다. 두 번 불려도 결과는 같다 —
     사라진 worktree 는 건너뛰고, 미커밋 변경이 남은 stage 트리는 보존한다.
@@ -1117,7 +877,7 @@ def integrate_and_teardown_whole_task(
             done_rows=done_rows,
             teardown=True,
             # 한 stage 브랜치가 이미 전체를 담고 있으면 검증은 거기서 돌았다
-            # (`_acquire_tip_stage_target`). 그 경우 task 브랜치로의 머지는 아무도
+            # (`phases/final_verification/target.py`). 그 경우 task 브랜치로의 머지는 아무도
             # 읽지 않는 산출물이므로 정리만 한다.
             merge=tip is None,
             verified_head=(done_by_stage.get(tip) or {}).get("head_commit", ""),
@@ -1130,40 +890,3 @@ def integrate_and_teardown_whole_task(
         ],
         "warnings": result.warnings,
     }
-
-
-def acquire_final_verification_target(
-    request: FinalVerificationTargetRequest,
-) -> FinalVerificationTargetAcquisition:
-    """Acquire a stable final-verification target behind one task-key lock."""
-    from okstra_project.dirs import okstra_home
-
-    from .locks import worktree_provision_mutex
-
-    try:
-        with worktree_provision_mutex(
-            okstra_home(),
-            request.project_id,
-            slugify(request.task_group),
-            slugify(request.task_id),
-        ):
-            registry_coordinates = _final_verification_registry_coordinates(request)
-            done_rows = _read_final_verification_done_rows(
-                request,
-                registry_coordinates,
-            )
-            if request.stage is not None:
-                return _acquire_single_stage_target(
-                    request,
-                    done_rows,
-                    registry_coordinates,
-                )
-            return _acquire_whole_task_target(
-                request,
-                done_rows,
-                registry_coordinates,
-            )
-    except PrepareError:
-        raise
-    except (OSError, RuntimeError, StageTargetError, ValueError) as exc:
-        raise PrepareError(str(exc)) from exc

package/runtime/python/okstra_ctl/user_response.py

@@ -31,6 +31,7 @@ from okstra_ctl.report_views import (
     normalize_direction_selection_identity,
     serialize_user_response, UserResponseEntry, UserPlanDecision,
     UserReportAuthoring, UserResponseAnalysisReview, UserDirectionSelection,
+    direction_candidate_ineligibility,
     infer_run_meta,
     parse_expected_form_options,
     resolve_recommended_option,
@@ -712,6 +713,57 @@ def _plan_decision_required(context: ResponseReportContext) -> bool:
     return _existing_sidecar_state(context.sidecar_path).plan_decision is None
 
 
+_DIRECTION_TASK_TYPE = "implementation-option-selection"
+
+
+def _direction_candidates(
+    context: ResponseReportContext,
+) -> tuple[list[dict[str, str]], str]:
+    """Ranked candidates the user picks the planning direction from.
+
+    Only a finished candidate comparison that still awaits a direction
+    (`routing == pending-direction-selection`, the state `next_phase` reports as
+    "pick a direction") has any. Each row carries the report's id and name and,
+    when the planning gate would refuse it, the reason.
+    """
+    if context.task_type != _DIRECTION_TASK_TYPE:
+        return [], ""
+    record = _load_report_record(context.report_path) or {}
+    selection = record.get("implementationOptionSelection")
+    if (
+        not isinstance(selection, Mapping)
+        or selection.get("mode") != "candidate-comparison"
+        or selection.get("routing") != "pending-direction-selection"
+    ):
+        return [], ""
+    options = selection.get("rankedOptions")
+    candidates: list[dict[str, str]] = []
+    for option in options if isinstance(options, list) else []:
+        if not isinstance(option, Mapping):
+            continue
+        try:
+            option_id, option_name = normalize_direction_selection_identity(
+                str(option.get("id") or ""), str(option.get("name") or "")
+            )
+        except ValueError as exc:
+            raise UserResponseError(str(exc)) from exc
+        candidates.append({
+            "id": option_id,
+            "name": option_name,
+            "goal": str(option.get("goal") or ""),
+            "coreMechanism": str(option.get("coreMechanism") or ""),
+            "ineligibility": direction_candidate_ineligibility(option),
+        })
+    return candidates, str(selection.get("recommendedOptionId") or "")
+
+
+def _direction_selection_required(context: ResponseReportContext) -> bool:
+    candidates, _ = _direction_candidates(context)
+    if not candidates:
+        return False
+    return _existing_sidecar_state(context.sidecar_path).direction_selection is None
+
+
 def list_awaiting_tasks(home: Path, project_id: str, limit: int) -> list[dict]:
     """사용자 답변을 기다리는 clarification 이 있는 태스크를 최신 report mtime 순으로.
 
@@ -736,6 +788,7 @@ def list_awaiting_tasks(home: Path, project_id: str, limit: int) -> list[dict]:
             context = resolve_report_context(report)
             blockers = _open_blocker_rows(context.report_path)
             plan_required = _plan_decision_required(context)
+            direction_required = _direction_selection_required(context)
         except UserResponseError:
             base = {"taskKey": key, "taskType": row.get("taskType", ""),
                     "seq": _seq_from_report(report), "reportPath": str(report),
@@ -752,12 +805,13 @@ def list_awaiting_tasks(home: Path, project_id: str, limit: int) -> list[dict]:
             "normalizedReportPath": str(context.report_path),
             "reportMtime": context.report_path.stat().st_mtime,
         }
-        if not blockers and not plan_required:
+        if not blockers and not plan_required and not direction_required:
             continue
         approval_count = sum(1 for row in blockers if row["item"].blocks == "approval")
         out.append({**base, "openBlockerCount": len(blockers),
                     "openApprovalCount": approval_count,
                     "planDecisionRequired": plan_required,
+                    "directionSelectionRequired": direction_required,
                     "unreadable": False})
     out.sort(key=lambda t: t["reportMtime"], reverse=True)
     return out[:limit] if limit > 0 else out
@@ -1031,8 +1085,11 @@ def _transaction_errors(payload: dict[str, Any]) -> list[str]:
     if not isinstance(draft, Mapping):
         errors.append("draft must be an object")
     else:
+        # 방향 선택 도입 전의 2.0 초안에는 이 필드가 없다.
         errors.extend(_unexpected_keys(
-            draft, {"answers", "planDecision", "legacyReportAuthoring"}, "draft"
+            {"directionSelection": None, **draft},
+            {"answers", "planDecision", "legacyReportAuthoring", "directionSelection"},
+            "draft",
         ))
         answers = draft.get("answers")
         if not isinstance(answers, list):
@@ -1066,7 +1123,7 @@ def _transaction_errors(payload: dict[str, Any]) -> list[str]:
                         errors.append(f"{label}.rationale must be a string")
                     if answer.get("disposition") not in _DIRECT_ANSWER_DISPOSITIONS:
                         errors.append(f"{label}.disposition is invalid for a direct answer")
-        for field in ("planDecision", "legacyReportAuthoring"):
+        for field in ("planDecision", "legacyReportAuthoring", "directionSelection"):
             value = draft.get(field)
             if value is not None and not isinstance(value, Mapping):
                 errors.append(f"draft.{field} must be an object or null")
@@ -1083,6 +1140,21 @@ def _transaction_errors(payload: dict[str, Any]) -> list[str]:
                     errors.append(f"draft.planDecision.{field} must be a string")
             if decision.get("status") != "approved" and not decision.get("reason"):
                 errors.append("draft.planDecision.reason is required")
+        direction = draft.get("directionSelection")
+        if isinstance(direction, Mapping):
+            errors.extend(_unexpected_keys(
+                direction,
+                {"optionId", "optionName", "selectionNote", "constraints"},
+                "draft.directionSelection",
+            ))
+            for field in ("optionId", "optionName"):
+                if not isinstance(direction.get(field), str) or not direction[field]:
+                    errors.append(
+                        f"draft.directionSelection.{field} must be a non-empty string"
+                    )
+            for field in ("selectionNote", "constraints"):
+                if not isinstance(direction.get(field), str):
+                    errors.append(f"draft.directionSelection.{field} must be a string")
         authoring = draft.get("legacyReportAuthoring")
         if isinstance(authoring, Mapping):
             errors.extend(_unexpected_keys(
@@ -1171,6 +1243,7 @@ def _load_transaction(transaction_id: str) -> tuple[Path, dict[str, Any]]:
         raise UserResponseError("transaction anchor digest does not match its token")
     if payload["transactionId"] != transaction_id:
         raise UserResponseError("transaction id does not match its state")
+    payload["draft"].setdefault("directionSelection", None)
     return path, payload
 
 
@@ -1270,6 +1343,9 @@ def _validate_draft_against_context(
             raise UserResponseError(
                 f"implementation option is not a report candidate: {selected}"
             )
+    direction = draft.get("directionSelection")
+    if isinstance(direction, Mapping):
+        _eligible_direction(context, str(direction.get("optionId") or ""))
     authoring = draft.get("legacyReportAuthoring")
     if context.report_contract_version != "2.0" and authoring is not None:
         raise UserResponseError(
@@ -1342,6 +1418,7 @@ def begin_response(report_path: Path, task_key: str) -> str:
                 "answers": [],
                 "planDecision": None,
                 "legacyReportAuthoring": None,
+                "directionSelection": None,
             },
             "publication": {
                 "status": "draft",
@@ -1478,6 +1555,53 @@ def set_plan_decision(
         _write_transaction(path, payload)
 
 
+def _eligible_direction(
+    context: ResponseReportContext, option_id: str
+) -> dict[str, str]:
+    candidates, _ = _direction_candidates(context)
+    if not candidates:
+        raise UserResponseError(
+            "direction selection needs an implementation-option-selection report "
+            "that awaits a direction (candidate-comparison, pending-direction-selection)"
+        )
+    candidate = next((row for row in candidates if row["id"] == option_id), None)
+    if candidate is None:
+        raise UserResponseError(f"direction option is not a ranked candidate: {option_id}")
+    if candidate["ineligibility"]:
+        raise UserResponseError(f"{option_id}: {candidate['ineligibility']}")
+    return candidate
+
+
+def set_direction_selection(
+    transaction_id: str,
+    option_number: int,
+    note_file: Path | None,
+    constraints_file: Path | None,
+) -> None:
+    with _locked_transaction(transaction_id, mutable=True) as (path, payload, context):
+        candidates, _ = _direction_candidates(context)
+        if not candidates:
+            _eligible_direction(context, "")
+        if option_number < 1 or option_number > len(candidates):
+            raise UserResponseError(
+                f"direction option number does not exist: {option_number}"
+            )
+        candidate = _eligible_direction(context, candidates[option_number - 1]["id"])
+        payload["draft"]["directionSelection"] = {
+            "optionId": candidate["id"],
+            "optionName": candidate["name"],
+            "selectionNote": (
+                _read_body_file(note_file, "selection note", context)
+                if note_file else ""
+            ),
+            "constraints": (
+                _read_body_file(constraints_file, "constraints", context)
+                if constraints_file else ""
+            ),
+        }
+        _write_transaction(path, payload)
+
+
 def set_legacy_report_authoring(
     transaction_id: str, status: str, reason_file: Path
 ) -> None:
@@ -1653,6 +1777,19 @@ def _transaction_authoring(payload: Mapping[str, Any]) -> UserReportAuthoring |
     )
 
 
+def _transaction_direction(payload: Mapping[str, Any]) -> UserDirectionSelection | None:
+    direction = payload.get("directionSelection")
+    if not isinstance(direction, Mapping):
+        return None
+    return UserDirectionSelection(
+        option_id=str(direction.get("optionId") or ""),
+        option_name=str(direction.get("optionName") or ""),
+        confirmed=True,
+        selection_note=str(direction.get("selectionNote") or ""),
+        constraints=str(direction.get("constraints") or ""),
+    )
+
+
 def _render_transaction_sidecar(
     payload: Mapping[str, Any], context: ResponseReportContext
 ) -> str:
@@ -1669,6 +1806,7 @@ def _render_transaction_sidecar(
         and not draft["answers"]
         and draft["planDecision"] is None
         and draft["legacyReportAuthoring"] is None
+        and draft["directionSelection"] is None
     ):
         return existing_text
     merged = {entry.response_id: entry for entry in existing_state.entries}
@@ -1712,7 +1850,9 @@ def _render_transaction_sidecar(
             _transaction_decision(draft) or existing_state.plan_decision
         ),
         analysis_review=existing_state.analysis_review,
-        direction_selection=existing_state.direction_selection,
+        direction_selection=(
+            _transaction_direction(draft) or existing_state.direction_selection
+        ),
         report_authoring=(
             _transaction_authoring(draft) or existing_state.report_authoring
         ),
@@ -1791,6 +1931,8 @@ def format_list_view(rows: list[dict[str, Any]]) -> str:
             f"Open items: {open_items}",
             f"Open approval items: {row.get('openApprovalCount', 0)}",
             f"Plan decision required: {'yes' if row.get('planDecisionRequired') else 'no'}",
+            "Direction selection required: "
+            f"{'yes' if row.get('directionSelectionRequired') else 'no'}",
             f"Status: {status}",
         ])
         picker.extend([
@@ -2007,6 +2149,43 @@ def _format_open_row_view(
     return lines
 
 
+def _format_direction_view(
+    context: ResponseReportContext, state: ExistingSidecarState
+) -> list[str]:
+    candidates, recommended = _direction_candidates(context)
+    if not candidates:
+        return []
+    current = state.direction_selection
+    lines = [
+        "Current direction selection: "
+        f"{f'{current.option_id} {current.option_name}' if current else 'none'}",
+        "Direction candidates:",
+    ]
+    ordered = sorted(
+        enumerate(candidates, start=1),
+        key=lambda pair: pair[1]["id"] != recommended,
+    )
+    for index, candidate in enumerate(candidates, start=1):
+        lines.extend([
+            f"Direction option {index}: {candidate['id']} {candidate['name']}",
+            f"  Recommended: {'yes' if candidate['id'] == recommended else 'no'}",
+            f"  Goal: {candidate['goal'] or 'not stated in the report'}",
+            f"  Core mechanism: {candidate['coreMechanism'] or 'not stated in the report'}",
+            f"  Selectable: {'no - ' + candidate['ineligibility'] if candidate['ineligibility'] else 'yes'}",
+        ])
+    lines.append("Direction picker:")
+    for index, candidate in ordered:
+        if candidate["ineligibility"]:
+            continue
+        suffix = " (Recommended)" if candidate["id"] == recommended else ""
+        lines.extend([
+            f"- Label: {candidate['id']} {candidate['name']}{suffix}",
+            f"  Description: {candidate['goal'] or 'not stated in the report'}",
+            f"  Option number: {index}",
+        ])
+    return lines
+
+
 def format_show_view(report_path: Path, project_root: Path) -> str:
     context = _validate_owned_report_context(
         report_path, expected_project_root=project_root
@@ -2043,6 +2222,7 @@ def format_show_view(report_path: Path, project_root: Path) -> str:
                 f"  Recommended: {'yes' if candidate == recommended_name else 'no'}",
                 f"  Current decision: {'yes' if current_pick else 'no'}",
             ])
+    lines.extend(_format_direction_view(context, state))
     for row in rows:
         item = row["item"]
         if item.status not in {"open", "answered"} or item.row_id in current:
@@ -2108,6 +2288,8 @@ _CLI_EPILOG = r"""Usage:
     --kind <kind> --disposition <value> --value-file <md> [--rationale-file <md>]
   okstra user-response plan-decision --transaction <id> --status <value> \
     [--implementation-option <name>] [--reason-file <md>]
+  okstra user-response direction --transaction <id> --option-number <N> \
+    [--note-file <md>] [--constraints-file <md>]
   okstra user-response legacy-report-authoring --transaction <id> \
     --status <approved|denied> --reason-file <md>
   okstra user-response finalize --transaction <id>
@@ -2147,6 +2329,11 @@ def _build_parser() -> argparse.ArgumentParser:
     decision.add_argument("--status", choices=sorted(_PLAN_DECISION_STATUSES), required=True)
     decision.add_argument("--implementation-option", default="")
     decision.add_argument("--reason-file")
+    direction = sub.add_parser("direction")
+    direction.add_argument("--transaction", required=True)
+    direction.add_argument("--option-number", type=int, required=True)
+    direction.add_argument("--note-file")
+    direction.add_argument("--constraints-file")
     authoring = sub.add_parser("legacy-report-authoring")
     authoring.add_argument("--transaction", required=True)
     authoring.add_argument("--status", choices=("approved", "denied"), required=True)
@@ -2191,6 +2378,14 @@ def _dispatch_command(ns: argparse.Namespace) -> None:
             Path(ns.reason_file) if ns.reason_file else None,
         )
         _write_json({"transaction": ns.transaction, "status": "draft"})
+    elif ns.cmd == "direction":
+        set_direction_selection(
+            ns.transaction,
+            ns.option_number,
+            Path(ns.note_file) if ns.note_file else None,
+            Path(ns.constraints_file) if ns.constraints_file else None,
+        )
+        _write_json({"transaction": ns.transaction, "status": "draft"})
     elif ns.cmd == "legacy-report-authoring":
         set_legacy_report_authoring(
             ns.transaction, ns.status, Path(ns.reason_file)