okstra 0.206.0 → 0.207.0

package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py

@@ -0,0 +1,166 @@
+"""구현 계획 진입에서 방향 선택과 기존 계획 재실행을 구분한다."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from collections.abc import Mapping
+from typing import Optional
+
+from okstra_ctl.implementation_direction import (
+    DirectionSelectionError,
+    lexical_absolute_path,
+    resolve_selected_direction,
+    validate_task_artifact_path,
+)
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
+from okstra_ctl.paths import task_dir, task_runs_dir
+from okstra_ctl.wizard.ids import S_SELECTED_DIRECTION_PICK
+from okstra_ctl.wizard.state import Prompt, WizardError, WizardState
+from okstra_ctl.wizard.prompts import _opt, _p
+from okstra_ctl.wizard.sources import _project_relative_path
+
+
+# 후보는 리포트 **기록**으로 찾는다. 전체 열람본(`.md`)은 `2bcd575` 이후 완료
+# 산출물이 아니라 요청 시 렌더라, `.md` 를 글롭하는 동안 이 목록은 항상 비었고
+# 방향 선택 단계 자체가 뜨지 않았다 — 비교가 끝나도 계획으로 갈 길이 없었다.
+_SELECTION_REPORT_RE = re.compile(
+    r"^final-report-implementation-option-selection-(?P<seq>\d{3,})\.data\.json$"
+)
+
+
+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-*.data.json"
+    ):
+        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|data\.json)", 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, _selection_option_label(state, path, t)) for path in candidates
+        ],
+        echo_template=t["echo_template"],
+    )
+
+
+def _selection_option_label(state: WizardState, rel_path: str, t: dict) -> str:
+    """후보 경로에 그 리포트가 실제로 무엇을 담았는지 붙인다.
+
+    목록은 최신순이라 후보가 0건인 최근 재실행이 맨 위에 온다. 경로만 보이면
+    사용자가 그것을 고르고, 방향 없는 리포트로 계획을 열려다 막힌다.
+    """
+    record = Path(state.project_root) / rel_path
+    try:
+        data = load_owned_object(record, artifact="implementation option data")
+    except (OSError, JsonBoundaryError):
+        return rel_path
+    selection = data.get("implementationOptionSelection")
+    if not isinstance(selection, Mapping):
+        return rel_path
+    rows = selection.get("rankedOptions")
+    ids = (
+        [
+            str(row.get("id"))
+            for row in rows
+            if isinstance(row, Mapping) and row.get("id")
+        ]
+        if isinstance(rows, list)
+        else []
+    )
+    if not ids:
+        return t["labels"]["no_options"].format(path=rel_path)
+    return t["labels"]["options"].format(path=rel_path, ids=", ".join(ids))
+
+
+def _submit_selected_direction_pick(state: WizardState, value: str) -> Optional[str]:
+    t = _p(state.workspace_root, S_SELECTED_DIRECTION_PICK)
+    candidates = _selected_direction_candidates(state)
+    if value not in candidates:
+        raise WizardError(t["errors"]["unknown"].format(value=value))
+    try:
+        resolve_selected_direction(
+            Path(state.project_root) / value,
+            expected_task_key=f"{state.project_id}:{state.task_group}:{state.task_id}",
+        )
+    except DirectionSelectionError as exc:
+        raise WizardError(str(exc)) from exc
+    state.selected_direction_path = value
+    # 두 입력은 상호 배타다 — 방향이 정해진 순간 이 런은 새 계획이고,
+    # clarification 자리에 남은 값은 render-bundle 이 거절할 이유일 뿐이다.
+    # 거절을 여기서 앞당기는 대신 값을 비우고, 무엇이 비워졌는지 echo 로
+    # 알린다. 사용자 답변은 손실되지 않는다: 그 사이드카는
+    # `--selected-direction` 경로로 계획 런에 첨부된다(`run.py` 참조).
+    if state.clarification_response_path:
+        state.clarification_response_path = ""
+        return t["echo_variants"]["cleared_clarification"].format(value=value)
+    return f"selected-direction: {value}"

package/runtime/python/okstra_ctl/phases/improvement_discovery/boundary.json

@@ -0,0 +1,12 @@
+{
+  "allowed": "  - improvement candidate discovery within the lens whitelist defined in `scripts/okstra_ctl/phases/improvement_discovery/lenses.py`\n  - top-N ranking (default 8, brief `candidate-cap` overrides within 1..12)\n  - per-candidate columns Lens / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Expected behavior after / Evidence (path:line)\n  - Phase 1.5 reflect-back grilling log at `runs/improvement-discovery/<seq>/state/phase-1.5-grilling.md`\n  - Phase 5.5 consensus classification (full / partial / contested / worker-unique / unverified)",
+  "forbidden": [
+    "source code edits of any kind",
+    "implementation planning, root-cause analysis, builds, migrations, or deployments",
+    "starting `implementation-planning`, `implementation`, `error-analysis`, or any other lifecycle phase inside this run",
+    "generating candidates outside the lens whitelist (Lens enum violation rejects the report)",
+    "exceeding the candidate cap (absolute cap 12)",
+    "free external data fetch beyond the brief's Source Material or Phase 1.5 resolved scope",
+    "interpreting user phrases like `다음 단계 진행해` as authorisation to enter another phase"
+  ]
+}

package/runtime/python/okstra_ctl/{improvement_lenses.py → phases/improvement_discovery/lenses.py}

@@ -1,9 +1,4 @@
-"""Improvement-discovery phase SSOT: lens enum and cap constants.
-
-profile / brief skill / validator / wizard MUST import from this module.
-Re-defining the enum anywhere else violates the single-reference-point rule
-and is rejected by tests/test_okstra_improvement_lenses.py.
-"""
+"""Improvement discovery lens vocabulary and candidate bounds."""
 from __future__ import annotations
 
 LENSES: tuple[str, ...] = (

package/runtime/{prompts/profiles/improvement-discovery.md → python/okstra_ctl/phases/improvement_discovery/profile.md}

@@ -13,7 +13,7 @@
 {{INCLUDE:_common-contract.md}}
 - Brief consumption (phase-specific addendum — shared rules live in `_common-contract.md` under "Brief handoff contract"):
   - this phase REQUIRES a codebase-scan brief whose frontmatter contains `scope: codebase`. A brief without that marker is rejected before worker dispatch.
-  - the brief's `priority-lenses` MUST be a non-empty subset (size 1..4) of the lens whitelist defined in `scripts/okstra_ctl/improvement_lenses.py`. Lenses outside the whitelist are rejected.
+  - the brief's `priority-lenses` MUST be a non-empty subset (size 1..4) of the lens whitelist defined in `scripts/okstra_ctl/phases/improvement_discovery/lenses.py`. Lenses outside the whitelist are rejected.
   - the brief's `scan-scope` defines the only paths workers may read for candidate evidence. `out-of-scope` paths MUST be ignored even when the codebase is otherwise reachable.
   - the brief's `candidate-cap` (default 8 if absent, absolute cap 12) bounds the number of rows in `## 5.9 Improvement Candidates`.
   - Apply the shared reporter-confirmation precondition as written. For this phase any unresolved `intent-check:` / `conversion-block:` row uses `Blocks=next-phase`.
@@ -52,11 +52,11 @@
 - Report assembly instructions:
   - current branch — `schemaVersion: 2.0`: author the structured data contract below and let the independent renderers produce the full reading copy and task-specific human HTML.
   - v1 legacy branch: when validating or rerendering an existing schema-v1 report, preserve its `## 5.9 Improvement Candidates` table and legacy Markdown contract; do not rewrite that historical data into v2 implicitly.
-  - the `## 5.9 Improvement Candidates` table populated with rows that obey the 11-column schema from `validators/validate_improvement_report.py` (Cand ID `I-NNN`, Lens from whitelist, Title, Scope ⊆ scan-scope, Severity, Effort, Consensus, Source workers `<worker>:<id>` from {claude, codex, antigravity}, Recommended next-phase ∈ {requirements-discovery, implementation-option-selection, error-analysis}, Expected behavior after, Evidence as path:line list). `Expected behavior after` states, in one observable sentence, what becomes different once the candidate is applied — it is the seed of the downstream brief's `EB-NNN` / `EO-NNN`. A candidate you cannot write this cell for is a preference, not a finding: drop it rather than filling the cell with a restatement of the title.
+  - the `## 5.9 Improvement Candidates` table populated with rows that obey the 11-column schema from `scripts/okstra_ctl/phases/improvement_discovery/validation.py` (Cand ID `I-NNN`, Lens from whitelist, Title, Scope ⊆ scan-scope, Severity, Effort, Consensus, Source workers `<worker>:<id>` from {claude, codex, antigravity}, Recommended next-phase ∈ {requirements-discovery, implementation-option-selection, error-analysis}, Expected behavior after, Evidence as path:line list). `Expected behavior after` states, in one observable sentence, what becomes different once the candidate is applied — it is the seed of the downstream brief's `EB-NNN` / `EO-NNN`. A candidate you cannot write this cell for is a preference, not a finding: drop it rather than filling the cell with a restatement of the title.
   - `Consensus` cells in `## 5.9 Improvement Candidates` use the table enum exactly: `full`, `partial`, `contested`, `worker-unique`. Map convergence's `full-consensus` / `partial-consensus` labels to `full` / `partial` before writing the table.
-  - Verdict Token — **branch-specific, and the two branches do not share a vocabulary.** On the current v2 branch use the shared analysis enum: `analysis-complete` when every resolved lens was examined, `analysis-partial` when one could not be, `blocked` when the scan itself could not run. `schemas/final-report-v2.0.schema.json` admits only those three for `finalVerdict.verdictToken` — the report's single verdict-token home — so a v2 report carrying `candidates-ready` fails Phase 7. **Finding no candidates is not a verdict**: it is an empty `candidates[]` plus a `lensCoverage[]` row per lens with `status: no-candidate` and its evidence-backed rationale — the verdict stays `analysis-complete`. `candidates-ready` / `no-candidates` belong to the v1 legacy `## 7. Final Verdict` Markdown alone, where `validators/validate_improvement_report.py` enforces them. Both branches: Direction `routing`; Next Step "ask the user to select K candidates (see the ## 5.9 table)".
-  - `## 3. Recommended Next Steps` first entry summarises per-candidate routing and proposes new task-key names of the form `<task-group>/imp-<Cand-ID>`
-  - author the shared narrative fields plus `improvementDiscovery.candidates[]`, `improvementDiscovery.lensCoverage[]`, `improvementDiscovery.selectionLimit`, and `improvementDiscovery.userNarrative` in the report narrative. `candidates[]` carries the same 11 logical fields described above; `lensCoverage[]` records either candidate IDs or an evidence-backed no-candidate rationale for every resolved lens. `schemas/final-report-v3.0.schema.json`, `schemas/report-narrative-v3.0.schema.json`, and `validators/validate_improvement_report.py` enforce this contract. Phase 7 assembles the final record and derives the reading copy and human HTML.
+  - Verdict Token — **branch-specific, and the two branches do not share a vocabulary.** On the current v2 branch use the shared analysis enum: `analysis-complete` when every resolved lens was examined, `analysis-partial` when one could not be, `blocked` when the scan itself could not run. `schemas/final-report-v2.0.schema.json` admits only those three for `finalVerdict.verdictToken` — the report's single verdict-token home — so a v2 report carrying `candidates-ready` fails Phase 7. **Finding no candidates is not a verdict**: it is an empty `candidates[]` plus a `lensCoverage[]` row per lens with `status: no-candidate` and its evidence-backed rationale — the verdict stays `analysis-complete`. `candidates-ready` / `no-candidates` belong to the v1 legacy `## 7. Final Verdict` Markdown alone, where `scripts/okstra_ctl/phases/improvement_discovery/validation.py` enforces them. Continuation guidance is owned by `prompts/lead/phase-routing.md`.
+  - Record each candidate's recommended next phase and scope as facts for the common lead routing policy.
+  - author the shared narrative fields plus `improvementDiscovery.candidates[]`, `improvementDiscovery.lensCoverage[]`, `improvementDiscovery.selectionLimit`, and `improvementDiscovery.userNarrative` in the report narrative. `candidates[]` carries the same 11 logical fields described above; `lensCoverage[]` records either candidate IDs or an evidence-backed no-candidate rationale for every resolved lens. `schemas/final-report-v3.0.schema.json`, `schemas/report-narrative-v3.0.schema.json`, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` enforce this contract. Phase 7 assembles the final record and derives the reading copy and human HTML.
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
   - if scan-scope or priority-lenses cannot be made concrete during Phase 1.5, end the run with Verdict Token `blocked`, populate `## 1. Clarification Items` with `Blocks=next-phase` rows, and do not run worker dispatch
 {{INCLUDE:_clarification-recommendation.md}}

package/runtime/python/okstra_ctl/{report_html/view_models/improvement_discovery.py → phases/improvement_discovery/report.py}

@@ -1,9 +1,9 @@
 """Human-first improvement-discovery view model."""
 from __future__ import annotations
 
-from ..common import evidence_index
-from ..models import HumanReportView, VisualNode
-from ..visualizations import matrix_figure
+from okstra_ctl.report_html.common import evidence_index
+from okstra_ctl.report_html.models import HumanReportView, VisualNode
+from okstra_ctl.report_html.visualizations import matrix_figure
 
 # Record fields this template anchors as `id-<row id>` (see
 # `HumanReportView.anchored_fields`); ids elsewhere land in the ledger.

package/runtime/{templates/reports → python/okstra_ctl/phases/improvement_discovery/report_assets}/improvement-discovery-input.template.md

@@ -78,5 +78,4 @@ being reconstructed.
 
 ## Conversion Note
 
-- Each candidate the user picks becomes a new okstra task. Suggested task-key: `<task-group>/imp-<Cand-ID>`.
-- The candidate row's Recommended next-phase determines which `--task-type` to launch with.
+Use `prompts/lead/phase-routing.md` for user selection and candidate continuation.

package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md

@@ -0,0 +1,29 @@
+# Improvement discovery phase
+
+## Purpose and ownership
+
+This phase discovers evidence-backed improvement candidates within a codebase scan's scope and resolved lenses. `lenses.py` owns the lens vocabulary and candidate bounds. `validation.py` owns candidate scope, identity, source-worker, consensus and report checks. `report.py` and `report_assets/` own the human view and dedicated input and report templates.
+
+Common analysis dispatch, convergence, clarification handling, report schemas and artifact paths remain shared. The brief validator imports the phase lens vocabulary for codebase briefs. The doctor uses the same vocabulary for its lens check. The lead chooses candidate continuation using `prompts/lead/phase-routing.md`; candidate validation checks the declared target vocabulary without choosing a target.
+
+## Execution and output
+
+`profile.md` directs the lead's bounded scope-and-lens discussion and records its resolved scope, lenses and primary-pass assignments in `state/phase-1.5-grilling.md`. The common worker-prompt policy supplies the explicit log anchor. Every analyser inspects every resolved lens. Candidate rows retain their scope, expected observable change, evidence and source-worker identities.
+
+The run validator calls `validate_improvement_report` with the existing report path, run directory and parsed brief frontmatter. Schema-v2 data uses the shared schema validator followed by candidate checks. Existing schema-v1 Markdown uses the eleven-column candidate table and the matching Verdict Card and Final Verdict rows. The migration preserves these version branches and error messages; it does not add a new schema branch.
+
+The validator requires the resolved-log headings, but does not prove that each declared inspection or user conversation occurred. Primary-pass rotation and preserved-behavior reconciliation remain profile instructions reviewed during convergence.
+
+## Guarantees
+
+| ID | Guarantee | Enforcement |
+|---|---|---|
+| ID-1 | Candidate IDs, lens count and vocabulary, scan scope, source workers, consensus, continuation vocabulary and observable-change cells are checked. | `scripts/okstra_ctl/phases/improvement_discovery/validation.py::_check_candidate_row` |
+| ID-2 | Candidate caps remain in 1..12 and bound the candidate count. | `scripts/okstra_ctl/phases/improvement_discovery/validation.py::_check_candidates_cap` |
+| ID-3 | The run log contains resolved scope and lens blocks. | `scripts/okstra_ctl/phases/improvement_discovery/validation.py::_check_grilling_log` |
+| ID-4 | Legacy verdict rows use the legacy vocabulary and match the Verdict Card. | `scripts/okstra_ctl/phases/improvement_discovery/validation.py::_check_final_verdict`, `scripts/okstra_ctl/phases/improvement_discovery/validation.py::_check_verdict_card` |
+| ID-5 | Codebase briefs use one to four priority lenses from the phase vocabulary. | `validators/validate-brief.py::check_codebase_scope` |
+
+## Tests
+
+`tests/test_improvement_discovery_validation.py` exercises both existing report branches with real report files and candidate mutations. The shared brief, rendering, doctor, prompt-anchor and catalog tests continue exercising the common callers.

package/runtime/{validators/validate_improvement_report.py → python/okstra_ctl/phases/improvement_discovery/validation.py}

@@ -1,26 +1,16 @@
 """Validator for final-report.md produced by the improvement-discovery phase.
 
-Enforces the 11-item contract in
-docs/superpowers/specs/2026-05-21-improvement-discovery-task-type-design.md §6.5.
+Validates candidate rows and the legacy/current report branches described in spec.md.
 
 Called by validators/validate-run.py when task_type == "improvement-discovery".
 """
 from __future__ import annotations
 
-import json
 import re
-import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 
-# scripts/ (repo) and python/ (installed under ~/.okstra/lib) are not packages;
-# insert whichever exists so okstra_ctl is importable directly.
-_VALIDATORS_DIR = Path(__file__).resolve().parent
-for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
-    if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
-        sys.path.insert(0, str(_ssot_dir))
-
-from okstra_ctl.improvement_lenses import (
+from .lenses import (
     LENSES,
     DEFAULT_CANDIDATE_CAP,
     ABSOLUTE_CANDIDATE_CAP,
@@ -32,6 +22,7 @@ from okstra_ctl.final_report_schema import (
     validate as validate_final_report_data,
 )
 from okstra_ctl.md_table import split_pipe_row
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
 
 
 _VERDICT_TOKENS = ("candidates-ready", "no-candidates", "blocked")
@@ -353,8 +344,8 @@ def validate_improvement_report(
     data_path = final_report_data_path(report_path)
     if data_path.exists():
         try:
-            data = json.loads(data_path.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError) as exc:
+            data = load_owned_object(data_path, artifact="improvement report data")
+        except JsonBoundaryError as exc:
             return ValidationResult(ok=False, errors=[f"invalid report data: {exc}"])
         if data.get("schemaVersion") == "2.0":
             return _validate_v2_report(data, run_dir, brief_frontmatter)

package/runtime/python/okstra_ctl/phases/project_analysis/__init__.py

@@ -0,0 +1 @@
+"""프로젝트 구조 분석 단계의 입력과 보고서 정책."""

package/runtime/python/okstra_ctl/phases/project_analysis/boundary.json

@@ -0,0 +1,8 @@
+{
+  "allowed": "  - components, dependency directions, entry points, repositories, and external integrations\n  - shallow feature index and scan scope\n",
+  "forbidden": [
+    "source or configuration edits",
+    "tests, builds, migrations, or deployments",
+    "starting any other lifecycle phase inside this run"
+  ]
+}

package/runtime/python/okstra_ctl/phases/project_analysis/entry.py

@@ -0,0 +1,11 @@
+"""프로젝트 분석 단계가 받지 않는 상류 입력을 거부한다."""
+from __future__ import annotations
+
+from okstra_ctl.prepare_error import PrepareError
+
+
+def validate_project_analysis_inputs(analysis_target: str, evidence_inputs_raw: str) -> None:
+    if analysis_target:
+        raise PrepareError("project-analysis does not accept an analysis target")
+    if evidence_inputs_raw:
+        raise PrepareError("project-analysis does not accept evidence inputs")

package/runtime/python/okstra_ctl/{report_html/view_models/project_analysis.py → phases/project_analysis/report.py}

@@ -1,9 +1,9 @@
 """Human-first project-analysis view model."""
 from __future__ import annotations
 
-from ..common import evidence_index
-from ..models import HumanReportView, VisualEdge, VisualNode
-from ..visualizations import dependency_figure, infrastructure_figure, workflow_figure
+from okstra_ctl.report_html.common import evidence_index
+from okstra_ctl.report_html.models import HumanReportView, VisualEdge, VisualNode
+from okstra_ctl.report_html.visualizations import dependency_figure, infrastructure_figure, workflow_figure
 
 # Record fields this template anchors as `id-<row id>` (see
 # `HumanReportView.anchored_fields`); ids elsewhere land in the ledger. The

package/runtime/python/okstra_ctl/phases/project_analysis/spec.md

@@ -0,0 +1,33 @@
+# Project analysis phase
+
+## Guarantees
+
+| ID | Guarantee | Enforcement |
+|---|---|---|
+| PA-1 | Project analysis rejects analysis-target and evidence-input arguments before run artifacts are written | `scripts/okstra_ctl/phases/project_analysis/entry.py::validate_project_analysis_inputs`; `tests/run/test_analysis_prepare_inputs.py::test_project_analysis_rejects_target_and_evidence_before_context` |
+| PA-2 | Feature-index entry points stay inside the declared analysis scope | `scripts/okstra_ctl/phases/project_analysis/validation.py::validate_project_semantics` |
+| PA-3 | Interface and workflow component references name declared components when components are present | `scripts/okstra_ctl/phases/project_analysis/validation.py::_validate_component_references` |
+| PA-4 | Source-commit and evidence-input snapshots remain common analysis contracts | `validators/validate_analysis_report.py::validate_analysis_snapshot` |
+| PA-5 | Scope, architecture and terminology conclusions reflect inspected code | unenforced — phase instructions and independent worker review; no generic validator proves free-form conclusions |
+
+## Scope and input
+
+The phase maps a bounded project area: repositories, directories, components, dependency directions, entry points and external systems. The brief defines scope and preserved boundaries. The common wizard collects identity, scope and model choices; this phase adds no separate wizard flow.
+
+`entry.py` rejects analysis-target and upstream evidence-input arguments. Common preparation retains the source commit and analysis scope. Shared `analysis_inputs.py` reads previously published project feature indexes for downstream feature and impact analysis; it remains a consumer contract rather than phase execution code.
+
+## Procedure and outputs
+
+`profile.md` owns the scope questions, evidence expectations, shallow feature index and optional technology, internal-interface and workflow descriptions. `profile.json` retains the worker roster and roles. The common read-only execution, clarification and analysis-review contracts still apply.
+
+The output remains `projectAnalysis` plus `analysisCommon` in the common v2/v3 report schemas. `report.py` renders architecture, infrastructure and workflow figures with the existing HTML and Markdown body templates. Source changes, builds, migrations, deployments and implementation plans remain outside this phase's scope.
+
+## Validation and continuation
+
+`validation.py` checks representative entry-point inclusion and declared component references. `analysis_scope.py` provides the same lexical path rules to phase and common evidence validation. Common validation retains evidence-row checks, worker outcomes, scope confirmation and accepted analysis lineage.
+
+The profile supplies no lifecycle destination selection rule. Common `next_phase.py` retains project analysis as a pending side-track result. This migration does not add an automatic continuation or invent a routing field.
+
+## Tests
+
+`tests/test_project_analysis_validation.py` checks declared and unknown interface/workflow component references, empty-component behavior and scoped feature entry points. Existing `tests/contract/test_validate_run_analysis.py` exercises the full common analysis validator, and `tests/run/test_analysis_prepare_inputs.py` checks rejection before preparation writes a run context. Common report rendering tests cover the phase body through the public router.

package/runtime/python/okstra_ctl/phases/project_analysis/validation.py

@@ -0,0 +1,55 @@
+"""프로젝트 지도 안의 진입점 범위와 구성요소 참조 검증."""
+from __future__ import annotations
+
+from okstra_ctl.analysis_scope import _path_is_included
+
+
+def validate_project_semantics(data: dict, errors: list[str]) -> None:
+    common = data.get("analysisCommon") or {}
+    included = ((common.get("scope") or {}).get("includedPaths") or [])
+    analysis = data.get("projectAnalysis") or {}
+    for row in analysis.get("featureIndex") or []:
+        if not isinstance(row, dict):
+            continue
+        entry = row.get("representativeEntryPoint") or {}
+        if not _path_is_included(entry.get("path"), included):
+            errors.append(
+                f"projectAnalysis.featureIndex `{row.get('id') or '?'}` representative "
+                "entry point must be inside analysisCommon.scope.includedPaths"
+            )
+    _validate_component_references(analysis, errors)
+
+
+def _validate_component_references(analysis: dict, errors: list[str]) -> None:
+    """Every componentId a row names has to be a component this report declares.
+
+    The reader clicks these — they render as links to the component's row — so
+    a reference to a component that was never listed is a dead anchor, and one
+    to a component that exists under a different id is worse: it reads as a
+    relationship the analysis never found.
+    """
+    declared = {
+        row.get("id")
+        for row in analysis.get("components") or []
+        if isinstance(row, dict) and row.get("id")
+    }
+    if not declared:
+        return
+
+    def check(component_id: object, where: str) -> None:
+        if isinstance(component_id, str) and component_id and component_id not in declared:
+            errors.append(f"{where} names component `{component_id}`, which is not declared")
+
+    for row in analysis.get("internalInterfaces") or []:
+        if not isinstance(row, dict):
+            continue
+        where = f"projectAnalysis.internalInterfaces `{row.get('id') or '?'}`"
+        check(row.get("ownerComponentId"), where)
+        for consumer in row.get("consumers") or []:
+            check(consumer, where)
+    for row in analysis.get("workflows") or []:
+        if not isinstance(row, dict):
+            continue
+        for step in row.get("steps") or []:
+            if isinstance(step, dict):
+                check(step.get("componentId"), f"projectAnalysis.workflows `{row.get('id') or '?'}`")

package/runtime/python/okstra_ctl/phases/release_handoff/__init__.py

@@ -0,0 +1 @@
+"""release-handoff 단계의 전용 정책과 실행 자원."""

package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json

@@ -0,0 +1,17 @@
+{
+  "allowed": "  - entering this phase only when the cited final-verification report's verdict is release-ready — `Verdict Token` exactly `accepted`, or exactly `conditional-accept` with every Conditional Acceptance Condition row declaring `blocksReleaseHandoff: false` (`okstra_ctl.release_gate.release_handoff_allowed`)\n  - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `local checkout`, `push + PR`, or `skip` (end the run)\n  - asking the user to pick a PR base branch from `staging` | `preprod` | `prod` | `main` | `dev` | a user-supplied branch name\n  - drafting PR title and PR body **inline as the Okstra lead** (no drafter worker and no delegated dispatch); the lead reviews its own draft with the user before any mutating git / gh command runs\n  - read-only git inspection: `git status`, `git diff`, `git log`, `git rev-parse`\n  - pushing the current feature branch to its origin remote via `git push -u origin <current-branch>` (the feature branch only — NEVER the base branch)\n  - creating a pull request via `gh pr create --base <chosen-base> --head <current-branch>`; if a PR with the same head already exists, surface its URL and skip creation\n  - the lead writes the final report directly (no `Report writer worker` dispatch); the report still conforms to the standard final-report template",
+  "forbidden": [
+    "entering this phase when the cited final-verification `Verdict Token` is `conditional-accept` or `blocked`, or when no final-verification report is cited",
+    "local commit commands of any kind (`git add`, `git commit`, `git restore --staged`, `git stash`), and any direct `git merge` / `git rebase` / `git rebase --onto` / `git cherry-pick` / `git commit --amend` run by the lead. The single exception is the merge commits `okstra handoff pr-plan` itself creates on a `merge-base` branch — the lead never merges by hand. Rewriting a stage branch breaks the PR stack that sits on it.",
+    "any git push variant that rewrites remote history, regardless of intent or whether the user said \"force it\": `git push --force`, `git push --force-with-lease`, `git push -f`, `git push +<refspec>`, or any other history-rewriting invocation",
+    "pushing directly to a release base branch — i.e. `git push origin <branch>` where `<branch>` is `main`, `master`, `prod`, `preprod`, `staging`, `dev`, or the branch the user chose as the release base in this run. The only permitted push targets are the branches `okstra handoff pr-plan` listed for this run (each stage `head_branch`, and any `merge-base` branch).",
+    "bypassing repo safeguards: `--no-verify` / `-n` on `git push`, bypassing GPG signing, disabling safeguards via equivalent flags, or any hook bypass.",
+    "release-publishing commands: `gh release create`, `gh release edit`, `npm publish`, `cargo publish`, `pip publish`, `twine upload`, `docker push`, `terraform apply`, `kubectl apply` against any non-local cluster.",
+    "source-code edits, refactors, or any modification to files outside the run's own artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`). The diff being shipped MUST be exactly what the prior `implementation` run produced; release-handoff packages it, it does not re-author it.",
+    "executing any mutating command the user did NOT select. Examples: opening a PR when the user picked `local checkout`; pushing when the user picked `skip`; switching the release base branch silently after the user already chose one; opening a PR for a stage outside `HANDOFF_STAGES`.",
+    "squash-merging, or instructing anyone to squash-merge, a stage PR — and `gh pr merge` in any form. A squash replaces the commits the next stage's PR base points at, so the stack breaks; the PR body states merge-commit-or-rebase and the lead never merges.",
+    "retrying a failed git / gh command with weaker safety flags. If `git push` fails with non-fast-forward, the lead MUST stop, explain the failure to the user, and ask for instructions — it MUST NOT add `--force`.",
+    "worker dispatch of any kind, or any other parallel sub-agent fan-out. This phase runs entirely under the Okstra lead.",
+    "silently treating an unrecognised user reply as one of the menu options. If the user's answer does not match a presented choice, re-ask the question verbatim."
+  ]
+}

package/runtime/python/okstra_ctl/phases/release_handoff/entry.py

@@ -0,0 +1,147 @@
+"""검증 보고서를 인계 입력으로 고정하고 PR 템플릿을 해석한다."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from okstra_ctl.json_boundary import load_owned_object
+from okstra_ctl.path_resolve import relative_to_project_root
+from okstra_ctl.plan_run_root import plan_run_root_from_approved_plan
+from okstra_ctl.prepare_error import PrepareError
+from okstra_ctl.pr_template import PrTemplateError, resolve_pr_template_path
+from okstra_ctl.stage_map import parse_stage_map_for_prepare
+from okstra_ctl.phases.catalog import migrated_report_template
+from okstra_ctl.handoff_error import HandoffError
+from .operations import _require_eligible, compute_eligibility, _parse_stages_csv
+
+
+def _collect_handoff_source_report_rows(
+    rows: list, nums: list,
+) -> list:
+    """선택 stage 들의 마지막 verified 행에서 인용 표 행을 만든다 (last-wins)."""
+    last_verified: dict = {}
+    for r in rows:
+        if r.get("status") == "verified" and isinstance(r.get("stage"), int):
+            last_verified[r["stage"]] = r
+    return [(str(n), Path(last_verified[n]["report_path"])) for n in nums]
+
+
+def _render_handoff_sources(sources: list, project_root: Path) -> tuple[str, str]:
+    """인용 표와 미해결 조건은 같은 원본 판정에서 렌더한다."""
+    from okstra_ctl.release_gate import release_handoff_allowed, verdict_token
+
+    rows, conditions = [], []
+    for stage, report in sources:
+        data = load_owned_object(report, artifact="handoff verification report")
+        if not release_handoff_allowed(data):
+            raise PrepareError(f"verification no longer release-ready: {report}")
+        relative = relative_to_project_root(report, project_root) or str(report)
+        rows.append(f"| {stage} | {relative} | `{verdict_token(data)}` |")
+        if verdict_token(data) == "conditional-accept":
+            for condition in data["finalVerdict"]["conditionalAcceptanceConditions"]:
+                conditions.append(
+                    f"- Stage {stage}, `{condition.get('id', '')}`\n"
+                    f"  - Condition: {condition.get('condition', '')}\n"
+                    f"  - Evidence required: {condition.get('evidenceRequired', '')}\n"
+                    f"  - blocksReleaseHandoff: {json.dumps(condition['blocksReleaseHandoff'])}"
+                )
+    section = "## Unresolved Conditional Acceptance Conditions\n\n" + "\n".join(conditions) if conditions else ""
+    return "\n".join(rows), section
+
+
+def _select_handoff_stages(stage_map: list, rows: list, selection: str) -> list[int]:
+    if selection:
+        try:
+            nums = _parse_stages_csv(selection)
+        except HandoffError as exc:
+            raise PrepareError(str(exc)) from exc
+        try:
+            _require_eligible(stage_map, rows, nums)
+        except HandoffError as exc:
+            raise PrepareError(str(exc)) from exc
+    else:
+        eligibility = compute_eligibility(stage_map, rows)
+        nums = [e["stage"] for e in eligibility if e["eligible"]]
+        if not nums:
+            blocked = "; ".join(
+                f"stage {e['stage']}: {', '.join(e['reasons'])}"
+                for e in eligibility) or "(no stage in the Stage Map)"
+            raise PrepareError(
+                "release-handoff has no eligible stage — every stage must "
+                "carry a release-ready single-stage final-verification of its "
+                f"recorded implementation commit. {blocked}"
+            )
+    return nums
+
+
+def materialize_handoff_input(
+    workspace_root: Path, project_root: Path, inp, *, install_hint: str,
+) -> dict:
+    """release-handoff 의 입력 문서를 검증 보고서 인용으로 자동 생성한다.
+
+    brief 는 entry phase 의 입력물이라 release-handoff 에는 없다 — 이 run 의
+    `--task-brief` 자리는 여기서 생성된 input 문서가 채운다. stage 자격은
+    okstra_ctl.handoff 의 SSOT 판정을 prepare 에서도 그대로 강제한다.
+    반환: ctx 에 올릴 {"HANDOFF_STAGES": ...}."""
+    from okstra_ctl.consumers import read_consumers
+    from okstra_ctl.paths import task_dir
+    from okstra_ctl.render import render_template_with_ctx
+    from okstra_ctl.run_context import _now_task_date
+
+    # Path("") 는 "." 로 정규화된다 — 빈 brief 센티널은 둘 다로 들어올 수 있다.
+    if str(inp.brief_path).strip() not in ("", "."):
+        raise PrepareError(
+            "--task-brief is not accepted for --task-type release-handoff — "
+            "the input document is generated from the cited final-verification "
+            "reports (pick stages via --stages, or leave it empty to take "
+            "every eligible stage)"
+        )
+    if not inp.approved_plan_path:
+        raise PrepareError(
+            "release-handoff requires --approved-plan "
+            "<implementation-planning final-report> — the Stage Map and the "
+            "consumers ledger drive stage eligibility"
+        )
+    plan = Path(inp.approved_plan_path)
+    if not plan.is_file():
+        raise PrepareError(f"approved plan not found: {plan}")
+    stage_map = parse_stage_map_for_prepare(str(plan))
+    rows = read_consumers(plan_run_root_from_approved_plan(plan))
+
+    nums = _select_handoff_stages(stage_map, rows, inp.stages)
+    stages_csv = ",".join(str(n) for n in nums)
+    report_rows = _collect_handoff_source_report_rows(rows, nums)
+
+    source_rows, source_conditions = _render_handoff_sources(report_rows, project_root)
+
+    template = (migrated_report_template(workspace_root, "release-handoff-input.template.md")
+                or workspace_root / "templates" / "reports" / "release-handoff-input.template.md")
+    if not template.is_file():
+        raise PrepareError(
+            f"release-handoff input template missing: {template}.{install_hint}"
+        )
+    out = (task_dir(project_root, inp.task_group, inp.task_id)
+           / "release-handoff-input.md")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    render_template_with_ctx(str(template), str(out), {
+        "TASK_KEY": f"{inp.project_id}:{inp.task_group}:{inp.task_id}",
+        "TASK_ID": inp.task_id,
+        "TASK_GROUP": inp.task_group,
+        "PROJECT_ID": inp.project_id,
+        "TASK_TYPE": inp.task_type,
+        "TASK_DATE": _now_task_date(),
+        "HANDOFF_STAGES": stages_csv,
+        "HANDOFF_SOURCE_REPORTS": source_rows,
+        "HANDOFF_CONDITIONS": source_conditions,
+    })
+    inp.brief_path = out
+    return {"HANDOFF_STAGES": stages_csv}
+
+
+def resolve_pr_template(inp) -> tuple[str, str]:
+    """release-handoff 전용 PR 본문 템플릿 경로와 출처를 해소한다."""
+    try:
+        resolved_tpl = resolve_pr_template_path(Path(inp.project_root), inp.pr_template_path)
+    except PrTemplateError as exc:
+        raise PrepareError(f"PR template resolution failed: {exc}") from exc
+    return str(resolved_tpl.path), resolved_tpl.source