okstra 0.172.0 → 0.173.0

package/runtime/python/okstra_ctl/wizard.py

@@ -82,6 +82,11 @@ from okstra_ctl.design_prep import (
     resolve_design_prep,
     write_design_prep_input,
 )
+from okstra_ctl.implementation_direction import (
+    DirectionSelectionError,
+    lexical_absolute_path,
+    validate_task_artifact_path,
+)
 from okstra_ctl.final_report_paths import final_report_data_path
 from okstra_ctl.plan_run_root import list_implementation_planning_reports
 from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
@@ -154,6 +159,7 @@ TASK_TYPES: list[tuple[str, str]] = [
     ("improvement-discovery", "Find improvement candidates within a codebase scope and lens whitelist"),
     *zip(ANALYSIS_TASK_TYPES, _ANALYSIS_TASK_TYPE_DESCRIPTIONS),
     ("error-analysis", "Evidence-based root-cause analysis (no code changes)"),
+    ("implementation-option-selection", "Compare implementation options (read-only)"),
     ("implementation-planning", "Plan options + request user approval"),
     ("implementation", "Execute approved plan (requires approved final-report)"),
     ("final-verification", "Acceptance + residual-risk review"),
@@ -331,6 +337,7 @@ S_ANALYSIS_TARGET_PICK = "analysis_target_pick"
 S_ANALYSIS_TARGET = "analysis_target"
 S_BASE_REF_PICK = "base_ref_pick"
 S_BASE_REF_TEXT = "base_ref_text"
+S_SELECTED_DIRECTION_PICK = "selected_direction_pick"
 S_APPROVED_PLAN_PICK = "approved_plan_pick"
 S_APPROVED_PLAN = "approved_plan"
 S_APPROVE_PLAN_CONFIRM = "approve_plan_confirm"
@@ -495,6 +502,7 @@ class WizardState:
     clarification_response_path: str = ""
     clarification_pending_text: bool = False
     last_final_report_cached: str = ""
+    selected_direction_path: str = ""
     # "" | "auto" | "full" | "<stage csv>" — 사용자가 고른 이번 재실행의 재검증
     # 범위. implementation-planning 재실행에서 좁힐 여지가 있을 때만 채워진다.
     reverify_scope: str = ""
@@ -595,6 +603,105 @@ def _require_file(path_str: str, project_root: Path, label: str) -> Path:
     return p
 
 
+_SELECTION_REPORT_RE = re.compile(
+    r"^final-report-implementation-option-selection-(?P<seq>\d{3,})\.md$"
+)
+
+
+def _selected_direction_candidates(state: WizardState) -> list[str]:
+    if not state.project_root or not state.task_group or not state.task_id:
+        return []
+    project_root = Path(state.project_root).resolve()
+    task_root = lexical_absolute_path(
+        task_dir(project_root, state.task_group, state.task_id)
+    )
+    reports = (
+        task_runs_dir(project_root, state.task_group, state.task_id)
+        / "implementation-option-selection"
+        / "reports"
+    )
+    candidates: list[tuple[int, Path]] = []
+    for report in reports.glob("final-report-implementation-option-selection-*.md"):
+        match = _SELECTION_REPORT_RE.fullmatch(report.name)
+        if match is None:
+            continue
+        try:
+            validated = validate_task_artifact_path(
+                report, task_root, "selection report"
+            )
+        except DirectionSelectionError:
+            continue
+        candidates.append((int(match.group("seq")), validated))
+    return [
+        _project_relative_path(path, project_root)
+        for _, path in sorted(candidates, reverse=True)[:3]
+    ]
+
+
+def _planning_rerun_selected(state: WizardState) -> bool:
+    if (
+        not state.clarification_response_path
+        or not state.project_root
+        or not state.task_group
+        or not state.task_id
+    ):
+        return False
+    project_root = Path(state.project_root).resolve()
+    raw_path = Path(state.clarification_response_path).expanduser()
+    path = lexical_absolute_path(
+        raw_path if raw_path.is_absolute() else project_root / raw_path
+    )
+    task_root = lexical_absolute_path(
+        task_dir(project_root, state.task_group, state.task_id)
+    )
+    reports = lexical_absolute_path(
+        task_runs_dir(project_root, state.task_group, state.task_id)
+        / "implementation-planning"
+        / "reports"
+    )
+    try:
+        validate_task_artifact_path(path, task_root, "planning report")
+    except DirectionSelectionError:
+        return False
+    return (
+        path.is_file()
+        and not path.is_symlink()
+        and re.fullmatch(
+            r"final-report-implementation-planning-\d{3,}\.md", path.name
+        )
+        is not None
+        and path.parent == reports
+    )
+
+
+def _build_selected_direction_pick(state: WizardState) -> Prompt:
+    candidates = _selected_direction_candidates(state)
+    t = _p(state.workspace_root, S_SELECTED_DIRECTION_PICK)
+    if not candidates:
+        raise WizardError(t["errors"]["none"])
+    return Prompt(
+        step=S_SELECTED_DIRECTION_PICK,
+        kind="pick",
+        label=t["label"],
+        options=[_opt(path, path) for path in candidates],
+        echo_template=t["echo_template"],
+    )
+
+
+def _submit_selected_direction_pick(
+    state: WizardState, value: str
+) -> Optional[str]:
+    candidates = _selected_direction_candidates(state)
+    if value not in candidates:
+        raise WizardError(
+            _p(state.workspace_root, S_SELECTED_DIRECTION_PICK)["errors"][
+                "unknown"
+            ].format(value=value)
+        )
+    state.selected_direction_path = value
+    return f"selected-direction: {value}"
+
+
 def _data_json_approved_state(plan_path: Path) -> Optional[bool]:
     """`approved` flag of the sibling final-report data.json (the SSOT).
 
@@ -621,6 +728,18 @@ def _classify_approved_plan(path_str: str, project_root: Path) -> tuple[Path, bo
     ``already_fully_approved=False`` — the approve-confirm step offers to flip it.
     """
     p = _require_file(path_str, project_root, "approved plan")
+    loaded = _load_final_report_data_if_present(p)
+    if loaded is not None:
+        planning = loaded[1].get("implementationPlanning")
+        if (
+            isinstance(planning, dict)
+            and planning.get("planningContract") == "selected-direction"
+            and planning.get("outcome") == "direction-invalidated"
+        ):
+            raise WizardError(
+                "direction-invalidated planning reports are not approvable; "
+                "re-enter implementation-option-selection"
+            )
     body = p.read_text(encoding="utf-8", errors="replace")
     frontmatter = _extract_frontmatter_block(body)
     if frontmatter is None:
@@ -690,6 +809,14 @@ def _find_html_approval_sidecar(
     승인이 아닌 판정(반려·재작업 요청)은 여기서 걸러진다 — 이 단계가 묻는 것은
     "사용자가 이 plan 을 승인해 두었는가" 뿐이고, 반려 사유는 다음 planning
     run 이 sidecar 를 통째로 읽어 처리한다."""
+    loaded = _load_final_report_data_if_present(plan_path)
+    if loaded is not None:
+        planning = loaded[1].get("implementationPlanning")
+        if (
+            isinstance(planning, dict)
+            and planning.get("planningContract") == "selected-direction"
+        ):
+            return None
     responses_dir = plan_path.parent.parent / "user-responses"
     if not responses_dir.is_dir():
         return None
@@ -4175,6 +4302,19 @@ STEPS: list[Step] = [
          applies=lambda s: s.base_ref_pending_text,
          build=_build_base_ref_text, submit=_submit_base_ref_text,
          owns=("base_ref", "base_ref_pending_text")),
+    Step(S_SELECTED_DIRECTION_PICK,
+         applies=lambda s: (
+             s.task_type == "implementation-planning"
+             and not s.selected_direction_path
+             and not _planning_rerun_selected(s)
+             and _brief_resolved(s)
+             and _base_ref_ready(s)
+             and not s.base_ref_pending_text
+             and S_SELECTED_DIRECTION_PICK not in s.answered
+         ),
+         build=_build_selected_direction_pick,
+         submit=_submit_selected_direction_pick,
+         owns=("selected_direction_path",)),
     Step(S_APPROVED_PLAN_PICK,
          applies=lambda s: (s.task_type in _STAGE_SCOPED_TASK_TYPES
                             and not s.approved_plan_path
@@ -4556,6 +4696,7 @@ _FIELD_DEFAULTS: dict[str, Any] = {
     "directive_pending_text": False,
     "related_tasks_raw": "", "related_tasks_pending_text": False,
     "clarification_response_path": "", "clarification_pending_text": False,
+    "selected_direction_path": "",
     "reverify_scope": "", "reverify_scope_pending_text": False,
     "pr_template_path": "", "pr_template_pending_text": False,
     "pr_template_scope": "",
@@ -4924,6 +5065,7 @@ def render_args(state: WizardState) -> dict[str, str]:
         "report-writer-model": state.report_writer_model,
         "related-tasks": state.related_tasks_raw,
         "clarification-response": state.clarification_response_path,
+        "selected-direction": state.selected_direction_path,
         "reverify-scope": (
             state.reverify_scope
             if state.task_type == "implementation-planning" else ""
@@ -5080,6 +5222,8 @@ def confirmation_block(state: WizardState) -> str:
         reverify_line = _reverify_scope_line(state)
         if reverify_line is not None:
             lines.append(reverify_line)
+    if state.selected_direction_path:
+        lines.append(f"  selected-direction: {state.selected_direction_path}")
     if state.task_type == "release-handoff" and state.handoff_mode:
         scope = (
             _msg(state.workspace_root, "confirmation",

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -51,6 +51,7 @@ FINAL_VERIFICATION_HEADERS = (
 SUPPORTED_TASK_TYPES = frozenset({
     "requirements-discovery",
     "error-analysis",
+    "implementation-option-selection",
     "implementation-planning",
     "improvement-discovery",
     "implementation",
@@ -67,6 +68,7 @@ ANALYSIS_DUTY_BY_TASK_TYPE: dict[str, AgentAudience] = {
     "requirements-discovery": "discovery-worker",
     "improvement-discovery": "discovery-worker",
     "error-analysis": "diagnosis-worker",
+    "implementation-option-selection": "direction-selection-worker",
     "implementation-planning": "planning-worker",
 }
 WORKER_PREAMBLE_FILENAME_BY_AUDIENCE = {

package/runtime/python/okstra_ctl/workflow.py

@@ -17,22 +17,34 @@ from okstra_ctl.analysis_inputs import ANALYSIS_TASK_TYPES
 PHASE_SEQUENCE = [
     "requirements-discovery",
     "error-analysis",
+    "implementation-option-selection",
     "implementation-planning",
     "implementation",
     "final-verification",
     "release-handoff",
 ]
 
+REQUIREMENTS_DISCOVERY_ROUTING_TARGETS = frozenset(
+    {"error-analysis", "implementation-option-selection"}
+)
+
+ERROR_ANALYSIS_ROUTING_DIRECTIONS = {
+    "error-analysis": "continue-investigation",
+    "implementation-option-selection": "begin-option-selection",
+}
+
 DEFAULT_NEXT_PHASE = {
-    "requirements-discovery": "pending-routing-decision",
+    "requirements-discovery": "implementation-option-selection",
     "improvement-discovery": "pending-routing-decision",
     **{task_type: "pending-routing-decision" for task_type in ANALYSIS_TASK_TYPES},
-    "error-analysis": "implementation-planning",
+    "error-analysis": "implementation-option-selection",
+    "implementation-option-selection": "implementation-planning",
     "implementation-planning": "implementation",
     "implementation": "final-verification",
     # final-verification 의 다음 단계는 verdict 에 따라 갈리므로 정적 매핑은
     # `pending-release-handoff` 로 둔다 (accepted 일 때만 release-handoff 로
-    # 진입; 그 외에는 error-analysis / implementation-planning 으로 리라우팅).
+    # 진입; 그 외에는 error-analysis / implementation-option-selection /
+    # implementation-planning 으로 리라우팅).
     "final-verification": "pending-release-handoff",
     "release-handoff": "done-or-follow-up",
 }
@@ -87,12 +99,22 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)"
         ),
     },
+    "implementation-option-selection": {
+        "allowed": (
+            "  - candidate-comparison evidence for up to three options per worker\n"
+            "  - preselected-validation that re-evaluates the merged candidate set\n"
+            "  - a ranked display of at most three options with requirement mappings\n"
+            "  - an audit record for every rejected candidate\n"
+            "  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)"
+        ),
+    },
     "implementation-planning": {
         "allowed": (
             "  - pre-planning context exploration notes (files/interfaces inspected, recent commits scanned, ambiguities flagged)\n"
-            "  - at least two implementation option candidates, each with a File Structure list (Create/Modify/Delete with one-line responsibility per file), affected interfaces, and blast-radius estimate\n"
-            "  - trade-off matrix across options (complexity, risk, reversibility, test cost, rollout cost) and recommended option with rationale tied to isolation / single-responsibility / YAGNI principles\n"
-            "  - bite-sized stepwise execution order for the recommended option (each step ~2-5 min, exact file paths and commands, TDD ordering when applicable, no placeholders)\n"
+            "  - selected-direction planning: realize the one validated selected direction without reopening candidate comparison, with a File Structure list (Create/Modify/Delete with one-line responsibility per file), affected interfaces, and blast-radius estimate\n"
+            "  - legacy candidate-comparison planning only: at least two implementation option candidates, each with a File Structure list (Create/Modify/Delete with one-line responsibility per file), affected interfaces, and blast-radius estimate\n"
+            "  - legacy candidate-comparison planning only: a trade-off matrix across options (complexity, risk, reversibility, test cost, rollout cost) and recommended option with rationale tied to isolation / single-responsibility / YAGNI principles\n"
+            "  - bite-sized stepwise execution order for the selected direction or legacy recommended option (each step ~2-5 min, exact file paths and commands, TDD ordering when applicable, no placeholders)\n"
             "  - dependency / migration risk assessment, validation checklist (pre / mid / post with exact commands), rollback strategy with revert path and trigger signal\n"
             "  - every unresolved ambiguity registered as a `Blocks=approval` row in the `## 1. Clarification Items` table (do NOT create a separate `Open Questions` block under `5.5.x` — the unified table is the single home)\n"
             "  - YAML frontmatter line `approved: false` awaiting human flip to `true`\n"
@@ -117,7 +139,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
         "allowed": (
             "  - acceptance verdict with requirement coverage assessment\n"
             "  - residual risk and regression notes\n"
-            "  - recommended follow-up routing (`error-analysis` / `implementation-planning` / `release-handoff`) for any defects detected"
+            "  - recommended follow-up routing (`error-analysis` / `implementation-option-selection` / `implementation-planning` / `release-handoff`) for any defects detected"
         ),
     },
     "release-handoff": {