okstra 0.206.0 → 0.207.0

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

@@ -0,0 +1,26 @@
+# Change impact analysis phase
+
+## Purpose and boundaries
+
+This phase maps a proposed change's preserved behavior, affected and unaffected boundaries, dependency propagation, tests and operational impact. It records planning constraints and open decisions without producing an execution plan. `profile.md` owns these analysis instructions and the adversarial convergence setting.
+
+`entry.py` owns the feature-baseline selection and text-entry handlers. The common wizard registry preserves the existing question order: feature evidence before project evidence. Shared analysis-input code retains evidence ownership, review status, freshness, relation and path checks. The CLI evidence arguments and run artifacts are unchanged.
+
+## Result and validation
+
+`validation.py` owns the current-code evidence collection names and the rule limiting `planningInputs` to constraints and unknowns. `validators/validate_analysis_report.py` remains the common assembly point for phase semantics, current-code evidence, frozen input snapshots, worker completion and review-resolution checks. Evidence path predicates remain in `analysis_scope.py`.
+
+`report.py` builds the impact graph and human view from `changeImpactAnalysis`. The input, Markdown and HTML templates live in `report_assets/`. Common schemas, analysis-review controls and report routing remain shared. The common lead routing policy chooses the next phase; the profile describes facts and constraints for that decision.
+
+## Guarantees
+
+| ID | Guarantee | Enforcement |
+|---|---|---|
+| CI-1 | Planning inputs contain constraints and unknowns only. | `scripts/okstra_ctl/phases/change_impact_analysis/validation.py::validate_change_impact_semantics` |
+| CI-2 | Impact items require current-code evidence within the included scope. | `validators/validate_analysis_report.py::_validate_all_current_code_evidence`, `scripts/okstra_ctl/phases/change_impact_analysis/tests/test_change_impact_analysis_validation.py::test_change_impact_item_requires_current_code_evidence` |
+| CI-3 | The wizard collects feature evidence before project evidence. | `tests/domain/wizard/test_analysis_inputs.py::test_change_impact_collects_feature_then_project_evidence` |
+| CI-4 | Common validation checks the frozen analysis source, target and evidence snapshot. | `validators/validate_analysis_report.py::validate_analysis_snapshot` |
+
+## Tests
+
+The phase tests retain the existing impact-evidence and forbidden-planning-field assertions through the common report validator. Shared wizard tests cover selecting, skipping, reusing and editing evidence. Shared schema, report-assembly and rendering tests cover the existing report contract and views.

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

@@ -0,0 +1,23 @@
+"""Change impact content boundaries; analysis evidence stays shared."""
+from __future__ import annotations
+
+EVIDENCE_COLLECTIONS = (
+    "preservedBehaviors",
+    "impactItems",
+    "dependencyBlastRadius",
+    "testImpact",
+    "operationalImpact",
+)
+
+
+def validate_change_impact_semantics(data: dict, errors: list[str]) -> None:
+    analysis = data.get("changeImpactAnalysis") or {}
+    allowed = {"constraint", "unknown"}
+    for index, row in enumerate(analysis.get("planningInputs") or []):
+        if not isinstance(row, dict):
+            continue
+        for field in sorted(set(row) - allowed):
+            errors.append(
+                f"changeImpactAnalysis.planningInputs[{index}] forbids `{field}`; "
+                "planning inputs may contain constraints and unknowns only"
+            )

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

@@ -0,0 +1 @@
+"""오류 분석 단계의 진단 규칙과 자원."""

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

@@ -0,0 +1,9 @@
+{
+  "allowed": "  - symptom and trigger evidence\n  - root-cause hypotheses with supporting citations\n  - reproduction gaps and missing observability\n  - validation paths to confirm or refute hypotheses\n  - one endStateCoverage row per brief end-state id (this phase authors no goal of its own)",
+  "forbidden": [
+    "source code edits, refactors, or fix attempts",
+    "implementation design or planning artifacts",
+    "executing builds, migrations, deployments, or any state-mutating command",
+    "starting `implementation-planning` or `implementation` inside this run (each must be a separate run, and `implementation` additionally requires an approved `implementation-planning` deliverable)"
+  ]
+}

package/runtime/{prompts/profiles/error-analysis.md → python/okstra_ctl/phases/error_analysis/profile.md}

@@ -25,10 +25,10 @@
   - **Falsifiable cause candidates:** every root-cause candidate must include supporting evidence, the strongest falsifying evidence checked, confidence, and the next diagnostic action that would disprove it. A candidate that cannot be falsified is too vague for this phase.
   - **Graph-aware scope:** a graph edge can explain ordering or duplication, but it is not proof of cause by itself. Cite code/log evidence before claiming an upstream related task caused the current symptom.
   - **Sharp next diagnostic:** end with the single highest-value diagnostic command, log capture, or file inspection that should happen next, plus the expected signal that would confirm or reject the leading cause.
-  - **Fix-design boundary:** do not design the implementation fix beyond what is necessary to validate the cause. If the cause is credible, recommend `implementation-option-selection` with the verified evidence; if the cause is still unclear, recommend another `error-analysis` run with the next diagnostic. The lead's Phase Routing settles the next phase.
+  - **Fix-design boundary:** do not design the implementation fix beyond what is necessary to validate the cause. Record whether the cause is credible and the next diagnostic. The common Phase Routing settles the next phase.
 - Structured diagnosis and routing contract:
   - `errorAnalysis` is the source of truth for reproduction status, `EA-NNN` cause candidates, the sharp next diagnostic, and the next route.
-  - A route to `implementation-option-selection` requires a credible leading cause referenced by `routing.leadingCauseId` and `begin-option-selection` as the direction. A route back to `error-analysis` requires the sharp next diagnostic and `continue-investigation` as the direction.
+  - Record the route selected by the lead through the common Phase Routing rules, its `routing.leadingCauseId`, and the matching direction.
   - Structure is enforced by `schemas/final-report-v2.0.schema.json` `$defs.ErrorAnalysis`. `validators/validate-run.py::_validate_error_analysis_consistency` enforces the cross-field values: the routing target, a `routing.leadingCauseId` that names an actual `EA-NNN` candidate, the `verdictCard.direction` / `finalVerdict.direction` pair matching that target, and exactly one `phase-continuation` row in `followUpTasks` pointing at it. The prose of `direction` and `nextStep` is not scanned for routing wording.
 - Primary focus areas:
   - symptom and trigger clarification

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

@@ -1,17 +1,16 @@
 """Human-first error-analysis view model."""
+
 from __future__ import annotations
 
 import re
 
-from ..common import evidence_index
-from ..models import HumanReportView, VisualEdge, VisualNode
-from ..visualizations import cause_graph_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 cause_graph_figure
 
 # Record fields this template anchors as `id-<row id>` (see
 # `HumanReportView.anchored_fields`); ids elsewhere land in the ledger.
-ANCHORED_FIELDS = (
-    "errorAnalysis.causeCandidates",
-)
+ANCHORED_FIELDS = ("errorAnalysis.causeCandidates",)
 
 
 _LEAD_CLAUSE = re.compile(r"\s[—–-]\s|(?<=[.。!?])\s")
@@ -43,7 +42,7 @@ def _cause_node(row: dict, leading_cause_id: str) -> VisualNode:
         "candidate",
         "leading" if leading else row["confidence"],
         "",
-        note="Leading cause" if leading else f'Confidence {row["confidence"]}',
+        note="Leading cause" if leading else f"Confidence {row['confidence']}",
     )
 
 
@@ -79,7 +78,9 @@ def _cause_edges(rows: list[dict], symptom_id: str) -> tuple[VisualEdge, ...]:
 
 
 def _cause_figure(error: dict):
-    symptom = VisualNode("symptom", "Observed failure", "effect", "risk", "", note="Symptom")
+    symptom = VisualNode(
+        "symptom", "Observed failure", "effect", "risk", "", note="Symptom"
+    )
     rows = error.get("causeCandidates", [])
     leading_cause_id = (error.get("routing") or {}).get("leadingCauseId") or ""
     causes = tuple(_cause_node(row, leading_cause_id) for row in rows)

package/runtime/{templates/reports → python/okstra_ctl/phases/error_analysis/report_assets}/error-analysis-input.template.md

@@ -80,7 +80,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 > Analysers MUST NOT expand the hypothesis space or evidence collection into items listed here. If an analyser believes an excluded item is causally linked to the symptom, it is reported as a recommended follow-up analysis task in the final report — never silently merged into the current root-cause narrative. If this section is left empty, analysers treat any cause beyond what `Symptom Summary` and `Reproduction Context` describe as out of scope by default.
 
-**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `validators/validate_improvement_report.py` checks that one.
+**Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
 
 ## Questions for Analysers
 

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

@@ -0,0 +1,118 @@
+# error-analysis process
+
+## Guarantees
+
+| ID | Guarantee | Enforcement |
+|---|---|---|
+| EA-1 | A blocked reproduction names its blocking reason; other statuses carry an empty reason | `scripts/okstra_ctl/phases/error_analysis/validation.py::_validate_reproduction` |
+| EA-2 | Cause-chain links reference sibling candidates and reject self-links and cycles | `scripts/okstra_ctl/phases/error_analysis/tests/test_diagnosis.py::test_cause_chain_rejects_unresolvable_links` |
+| EA-3 | A selected destination agrees with the cause reference, verdict directions, and continuation row | `scripts/okstra_ctl/phases/error_analysis/validation.py::_validate_error_analysis_consistency` |
+| EA-4 | Common routing destinations match both supported report schemas | `scripts/okstra_ctl/phases/error_analysis/tests/test_diagnosis.py::test_error_routing_policy_matches_schema` |
+
+## Index
+
+- [1. Purpose](#1-purpose)
+- [2. okstra-run wizard flow](#2-okstra-run-wizard-flow)
+- [3. prepare_task_bundle handling](#3-prepare_task_bundle-handling)
+- [4. lead execution flow](#4-lead-execution-flow)
+- [5. Deliverables and prohibitions](#5-deliverables-and-prohibitions)
+- [6. Code reviewed](#6-code-reviewed)
+
+## 1. Purpose
+
+`error-analysis` analyzes a reported error or incident to organize the symptom, trigger, root-cause candidate, reproduction gap, and validation path. It is not the phase that produces the fix itself or an implementation design.
+
+## 2. okstra-run wizard flow
+
+```mermaid
+flowchart TD
+    Start[/okstra-run/] --> Common[common task identity flow]
+    Common --> Type[task-type = error-analysis]
+    Type --> Worktree{active worktree exists?}
+    Worktree -->|yes| RoleCount[role-count min..max<br/>omit uses recommended; skip if min==max]
+    Worktree -->|no| BaseRef[base-ref pick/text<br/>main recommended]
+    BaseRef --> RoleCount
+    RoleCount --> RoleModel[role-model provider/model per slot]
+    RoleModel --> RoleAdd[min=0 roles via role-add only<br/>default skip]
+    RoleAdd --> Extras[directive, related tasks, clarification]
+    Extras --> Confirm
+    Confirm --> Render[render-bundle --render-only]
+```
+
+Launch selection uses role slots and model refs only: current-session lead is this session (listed on the confirmation summary), then each static role's count in `min..max` (default **recommended**; the count step is skipped when `min == max`), then one `provider/model` per slot. Roles with `min = 0` stay closed unless the user opens them with role-add (default skip). Duplicate model refs in the same role are rejected. There is no provider roster multi-pick and no `Use defaults / Customize` fork. Dynamic verifiers are not chosen at launch. `--workers` is a CLI compatibility input only, not a launch picker.
+
+## 3. prepare_task_bundle handling
+
+```mermaid
+sequenceDiagram
+    participant Skill as okstra-run
+    participant Wizard as okstra_ctl.wizard
+    participant Run as prepare_task_bundle
+    participant WT as worktree/provision.py
+    participant Art as artifacts
+
+    Skill->>Wizard: task-type error-analysis selected
+    Wizard-->>Skill: workers/base-ref/model args
+    Skill->>Run: render-bundle --render-only
+    Run->>Run: canonical brief preflight
+    Run->>Run: validate brief/profile
+    Run->>Run: resolve worker roster
+    Run->>WT: provision/reuse worktree
+    Run->>Art: analysis-profile.md includes common contract
+    Run->>Art: task-manifest workflow next=validated report route
+```
+
+For canonical briefs, preflight runs before worker resolution, worktree provisioning, or report creation. A brief whose `reporter-confirmations` status is `pending` stops at this point; legacy briefs keep the compatibility path.
+
+The final report records its next phase in `errorAnalysis.routing.nextTaskType`. The common Phase Routing guide selects the destination from the recorded cause evidence. When report validation passes, Phase 7 projects `workflow.nextRecommendedPhase` from that one field (`scripts/okstra_ctl/next_phase.py::project`) — a `ready` pointer naming it. A report that leaves the field empty leaves the pointer `pending`; there is no static fallback that supplies a phase the report did not author.
+
+## 4. lead execution flow
+
+```mermaid
+flowchart TD
+    Intake[Phase 1 intake] --> Prompts[Phase 2 worker prompts]
+    Prompts --> Team[Phase 3 TeamCreate]
+    Team --> Dispatch[Phase 4/5 dispatch analysers]
+    Dispatch --> Evidence[worker outputs<br/>root-cause hypotheses]
+    Evidence --> Conv[Phase 5.5 convergence<br/>default maxRounds = 2]
+    Conv --> Report[Phase 6 report-writer final report]
+    Report --> Persist[Phase 7 persist + validate]
+```
+
+The workers analyze the symptom and evidence independently. A finding two distinct role executions derived on their own is recorded as full consensus at Round 0 in both modes — independent co-derivation is already cross-verification, so the adversarial burden of proof applies to single-source claims. Evidence-backed counter-evidence classifies a finding `contested` in the round it lands and takes it out of the verification queue; later agreement can neither erase it nor cost another round. The report-writer does not analyze during Phase 4/5 but writes the final report in Phase 6.
+
+## 5. Deliverables and prohibitions
+
+```mermaid
+flowchart LR
+    Symptom[Symptom] --> Hyp[Root-cause candidates]
+    Hyp --> Gap[Reproduction gaps]
+    Gap --> Validate[Validation path]
+    Validate --> Next[Recommended next diagnostic/planning step]
+    Hyp -. forbidden .-> Fix[Code fix in this run]
+```
+
+The expected final-report content is:
+
+- evidence-backed cause analysis
+- uncertainty boundary
+- practical next diagnostic steps
+- if there is blocking uncertainty, `## 1. Clarification Items`, usually `Blocks=next-phase`
+
+For `error-analysis`, the structured `errorAnalysis` object is the source of truth for the verbatim symptom, reproduction status, `EA-NNN` cause candidates and their counter-evidence, the next diagnostic, and routing. Its shape is enforced by the final-report schema; `validators/validate-run.py::_validate_error_analysis_consistency` enforces the cross-field values — the routing target, a `leadingCauseId` naming a real cause candidate, the two `direction` fields agreeing with that target, and the single matching `phase-continuation` follow-up row. The common Phase Routing guide owns the conditions for selecting the next phase.
+
+What is prohibited is source edit, refactor, fix attempt, implementation design artifact, and running build/migration/deploy. Deferring ambiguity that could be answered from code or logs to a user question is also a defect per the profile.
+
+## 6. Code reviewed
+
+- [`prompts/profiles/error-analysis.md`](profile.md)
+- [`templates/reports/error-analysis-input.template.md`](report_assets/error-analysis-input.template.md)
+- [`scripts/okstra_ctl/workflow.py`](../../workflow.py)
+- [`scripts/okstra_ctl/wizard/`](../../wizard)
+- [`prompts/lead/okstra-lead-contract.md`](../../../../prompts/lead/okstra-lead-contract.md)
+
+## Phase ownership
+
+`profile.md` and `profile.json` own the diagnostic procedure and worker requirements. `validation.py` owns reproduction, cause-chain, and authored routing consistency checks. `report.py` and `report_assets/` own the diagnosis display and input template. The common lead guide `prompts/lead/phase-routing.md` owns destination selection; common evidence reading, clarification contracts, and lifecycle projection remain outside this phase. The shared 2.0 and 3.0 final-report schemas retain `$defs.ErrorAnalysis`.
+
+`tests/test_diagnosis.py` exercises diagnosis rules. The common contract suite retains workflow projection and final-report assembly tests. No additional entry or wizard module is needed: this phase uses the common brief preflight and worker-selection flow.

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

@@ -0,0 +1,241 @@
+"""오류 분석의 재현·원인 연결·선택된 이동 결과를 검증한다."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+from okstra_ctl.workflow import ERROR_ANALYSIS_ROUTING_DIRECTIONS
+
+
+def _upstream_by_candidate(candidates: list[Any]) -> dict[str, list[str]]:
+    upstream: dict[str, list[str]] = {}
+    for candidate in candidates:
+        if not isinstance(candidate, Mapping):
+            continue
+        candidate_id = candidate.get("id")
+        declared = candidate.get("downstreamOf")
+        if isinstance(candidate_id, str) and isinstance(declared, list):
+            upstream[candidate_id] = [row for row in declared if isinstance(row, str)]
+    return upstream
+
+
+def _chain_cycle(upstream: dict[str, list[str]]) -> list[str]:
+    """The first cycle reachable through `downstreamOf`, as the ids that form it.
+
+    A cycle is a diagnosis that says each step is caused by the next, so it
+    names no first cause. It also hangs the figure's layering, which relaxes
+    until depths settle.
+    """
+    settled: set[str] = set()
+    for start in sorted(upstream):
+        stack = [(start, False)]
+        on_path: list[str] = []
+        active: dict[str, int] = {}
+        while stack:
+            current, exiting = stack.pop()
+            if exiting:
+                active.pop(current)
+                on_path.pop()
+                settled.add(current)
+                continue
+            if current in active:
+                return on_path[active[current] :] + [current]
+            if current in settled or current not in upstream:
+                continue
+            active[current] = len(on_path)
+            on_path.append(current)
+            stack.append((current, True))
+            stack.extend((parent, False) for parent in upstream[current])
+    return []
+
+
+def _validate_cause_chain(
+    candidates: list[Any], candidate_ids: set[str], failures: list[str]
+) -> None:
+    """`downstreamOf` must name a sibling candidate, and never itself."""
+    upstream = _upstream_by_candidate(candidates)
+    for candidate_id in sorted(upstream):
+        unknown = sorted(set(upstream[candidate_id]) - candidate_ids)
+        if unknown:
+            failures.append(
+                f"final-report data.json: {candidate_id}.downstreamOf names "
+                "unknown cause candidate(s): " + ", ".join(unknown) + "."
+            )
+        if candidate_id in upstream[candidate_id]:
+            failures.append(
+                f"final-report data.json: {candidate_id}.downstreamOf names itself."
+            )
+    cycle = _chain_cycle(
+        {
+            key: [row for row in value if row in candidate_ids]
+            for key, value in upstream.items()
+        }
+    )
+    if cycle:
+        failures.append(
+            "final-report data.json: cause candidates form a downstreamOf cycle: "
+            + " -> ".join(cycle)
+            + "."
+        )
+
+
+def _validate_reproduction(
+    error_analysis: Mapping[str, Any], failures: list[str]
+) -> None:
+    reproduction_value = error_analysis.get("reproduction")
+    reproduction = reproduction_value if isinstance(reproduction_value, Mapping) else {}
+    reproduction_status = reproduction.get("status")
+    blocked_reason = reproduction.get("blockedReason")
+    if reproduction_status == "blocked-before-repro":
+        if not isinstance(blocked_reason, str) or not blocked_reason.strip():
+            failures.append(
+                "final-report data.json: blocked-before-repro requires a non-empty "
+                "errorAnalysis.reproduction.blockedReason."
+            )
+    elif blocked_reason != "":
+        failures.append(
+            "final-report data.json: errorAnalysis.reproduction.blockedReason "
+            "must be exactly empty unless status is blocked-before-repro."
+        )
+
+
+def _validate_cause_candidates(candidates: list[Any], failures: list[str]) -> set[str]:
+    candidate_ids: list[str] = []
+    for candidate in candidates:
+        if not isinstance(candidate, Mapping):
+            continue
+        candidate_id = candidate.get("id")
+        if isinstance(candidate_id, str):
+            candidate_ids.append(candidate_id)
+    duplicate_ids = sorted(
+        candidate_id
+        for candidate_id in set(candidate_ids)
+        if candidate_ids.count(candidate_id) > 1
+    )
+    if duplicate_ids:
+        failures.append(
+            "final-report data.json: duplicate cause candidate id(s): "
+            + ", ".join(duplicate_ids)
+            + "."
+        )
+
+    _validate_cause_chain(candidates, set(candidate_ids), failures)
+
+    return set(candidate_ids)
+
+
+def _validate_routing_cause(
+    error_analysis: Mapping[str, Any],
+    candidates: list[Any],
+    candidate_id_set: set[str],
+    failures: list[str],
+) -> Any:
+    routing_value = error_analysis.get("routing")
+    routing = routing_value if isinstance(routing_value, Mapping) else {}
+    target = routing.get("nextTaskType")
+    leading_cause_id = routing.get("leadingCauseId")
+    if isinstance(target, str) and target not in ERROR_ANALYSIS_ROUTING_DIRECTIONS:
+        failures.append(
+            "final-report data.json: errorAnalysis.routing has unsupported "
+            f"routing target `{target}`."
+        )
+    if target == "implementation-option-selection":
+        if not candidates:
+            failures.append(
+                "final-report data.json: implementation-option-selection routing requires "
+                "at least one cause candidate."
+            )
+        if (
+            not isinstance(leading_cause_id, str)
+            or leading_cause_id not in candidate_id_set
+        ):
+            failures.append(
+                "final-report data.json: implementation-option-selection routing "
+                "leadingCauseId must reference a cause candidate."
+            )
+    elif target == "error-analysis" and (
+        not isinstance(leading_cause_id, str)
+        or (leading_cause_id != "" and leading_cause_id not in candidate_id_set)
+    ):
+        failures.append(
+            "final-report data.json: error-analysis routing leadingCauseId must be "
+            "empty or reference a cause candidate."
+        )
+
+    return target
+
+
+def _validate_verdict_directions(
+    data: Mapping[str, Any], target: Any, failures: list[str]
+) -> None:
+    expected_direction = ERROR_ANALYSIS_ROUTING_DIRECTIONS.get(target)
+    verdict_card_value = data.get("verdictCard")
+    verdict_card = verdict_card_value if isinstance(verdict_card_value, Mapping) else {}
+    final_verdict_value = data.get("finalVerdict")
+    final_verdict = (
+        final_verdict_value if isinstance(final_verdict_value, Mapping) else {}
+    )
+    if expected_direction:
+        for field_name, verdict in (
+            ("verdictCard", verdict_card),
+            ("finalVerdict", final_verdict),
+        ):
+            if verdict.get("direction") != expected_direction:
+                failures.append(
+                    f"final-report data.json: {field_name}.direction must be "
+                    f"`{expected_direction}` for `{target}` routing."
+                )
+
+
+def _validate_phase_continuation(
+    data: Mapping[str, Any], target: Any, failures: list[str]
+) -> None:
+    follow_up_tasks_value = data.get("followUpTasks")
+    follow_up_tasks = (
+        follow_up_tasks_value if isinstance(follow_up_tasks_value, list) else []
+    )
+    continuations = [
+        row
+        for row in follow_up_tasks
+        if isinstance(row, Mapping) and row.get("origin") == "phase-continuation"
+    ]
+    if len(continuations) != 1:
+        failures.append(
+            "final-report data.json: followUpTasks must contain exactly one "
+            "phase-continuation row."
+        )
+    else:
+        continuation = continuations[0]
+        if continuation.get("suggestedTaskType") != target:
+            failures.append(
+                "final-report data.json: phase-continuation suggestedTaskType "
+                "must match the routing target."
+            )
+        # `newTaskId` 의 형식과 `priority` 값은 여기서 보지 않는다. 이 행은
+        # `okstra-spawn-followups.py` 의 `NON_SPAWNING_ORIGINS` 에 들어 있어
+        # 아무것도 스폰하지 않는 표식이고, 그래서 두 필드에는 소비자가 없다.
+        # 게다가 그 스크립트의 priority 기본값은 `P1` 인데 여기서는 `P0` 를
+        # 요구해 두 값이 정면으로 어긋났고, 두 규칙 중 어느 쪽도 report-writer
+        # 가 읽는 스키마·프로필·템플릿 어디에도 적혀 있지 않았다 — 작성자가
+        # 알 수 없는 규칙을 소비자 없는 필드에 걸어 두고 있었다.
+        if continuation.get("autoSpawn") != "no":
+            failures.append(
+                "final-report data.json: phase-continuation autoSpawn must be no."
+            )
+
+
+def _validate_error_analysis_consistency(
+    data: Mapping[str, Any], failures: list[str]
+) -> None:
+    error_analysis_value = data.get("errorAnalysis")
+    error_analysis = (
+        error_analysis_value if isinstance(error_analysis_value, Mapping) else {}
+    )
+    _validate_reproduction(error_analysis, failures)
+    candidates_value = error_analysis.get("causeCandidates")
+    candidates = candidates_value if isinstance(candidates_value, list) else []
+    candidate_ids = _validate_cause_candidates(candidates, failures)
+    target = _validate_routing_cause(
+        error_analysis, candidates, candidate_ids, failures
+    )
+    _validate_verdict_directions(data, target, failures)
+    _validate_phase_continuation(data, target, failures)

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

@@ -0,0 +1 @@
+"""기능 분석 단계의 대상 해석과 보고서 정책."""

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

@@ -0,0 +1,8 @@
+{
+  "allowed": "  - confirmed target and normal, alternate, and failure flows\n  - rules, state transitions, external calls, and test coverage 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/feature_analysis/entry.py

@@ -0,0 +1,63 @@
+"""선택한 프로젝트 증거에서 기능 분석 대상을 해석한다."""
+
+from __future__ import annotations
+import re
+from pathlib import Path
+from typing import Mapping, Sequence
+from okstra_ctl.prepare_error import PrepareError
+from okstra_ctl.analysis_inputs import (
+    AnalysisInputError,
+    AnalysisReportCandidate,
+    ResolvedEvidenceInput,
+)
+
+_FEATURE_ID_RE = re.compile(r"PF-\d{3}")
+
+
+def resolve_analysis_target(
+    raw_target: str,
+    evidence_inputs: Sequence[ResolvedEvidenceInput],
+    candidates: Mapping[Path, AnalysisReportCandidate],
+) -> dict[str, object]:
+    """Normalize a feature-index identifier or a non-empty free-text target."""
+    target = raw_target.strip()
+    if not target:
+        raise AnalysisInputError("analysis target must not be empty")
+    if not _FEATURE_ID_RE.fullmatch(target):
+        return {"inputMode": "free-text", "requestedValue": target}
+    matches: list[dict[object, object]] = []
+    for evidence in evidence_inputs:
+        if evidence.relation != "project-context":
+            continue
+        candidate = candidates.get(evidence.report_path)
+        if candidate is None:
+            candidate = next(
+                (
+                    value
+                    for path, value in candidates.items()
+                    if path.resolve() == evidence.report_path
+                ),
+                None,
+            )
+        if candidate is None:
+            continue
+        matches.extend(
+            feature
+            for feature in candidate.feature_index
+            if isinstance(feature, dict) and feature.get("id") == target
+        )
+    if len(matches) != 1:
+        raise AnalysisInputError(
+            f"exactly one project-context feature must match {target}"
+        )
+    return {
+        "inputMode": "feature-index",
+        "requestedValue": target,
+        "feature": dict(matches[0]),
+    }
+
+
+def validate_feature_target_input(raw_target: str) -> None:
+    """실행 생성 전에 필수 대상 입력을 확인한다."""
+    if not raw_target.strip():
+        raise PrepareError("feature-analysis requires --analysis-target")

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

@@ -1,9 +1,10 @@
 """Human-first feature-analysis view model."""
+
 from __future__ import annotations
 
-from ..common import analysis_review_ids, evidence_index
-from ..models import HumanReportView, VisualNode
-from ..visualizations import flow_figure
+from okstra_ctl.report_html.common import analysis_review_ids, evidence_index
+from okstra_ctl.report_html.models import HumanReportView, VisualNode
+from okstra_ctl.report_html.visualizations import flow_figure
 
 # Record fields this template anchors as `id-<row id>` (see
 # `HumanReportView.anchored_fields`); ids elsewhere land in the ledger.
@@ -15,7 +16,11 @@ ANCHORED_FIELDS = (
 )
 
 
-_FLOW_KINDS = {"normal": "Normal path", "alternative": "Alternative path", "failure": "Failure path"}
+_FLOW_KINDS = {
+    "normal": "Normal path",
+    "alternative": "Alternative path",
+    "failure": "Failure path",
+}
 
 
 def _flow_nodes(feature: dict) -> tuple[VisualNode, ...]:
@@ -33,7 +38,9 @@ def _flow_nodes(feature: dict) -> tuple[VisualNode, ...]:
 
 def build_feature_analysis_view(data: dict) -> HumanReportView:
     feature = data["featureAnalysis"]
-    figure = flow_figure(nodes=_flow_nodes(feature), edges=(), title="Feature behavior paths")
+    figure = flow_figure(
+        nodes=_flow_nodes(feature), edges=(), title="Feature behavior paths"
+    )
     context = {
         "humanSummary": data["humanSummary"],
         "feature": feature,

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

@@ -0,0 +1,22 @@
+# Feature analysis phase
+
+## Purpose and boundaries
+
+This phase describes a confirmed feature's normal, alternate and failure flows, domain rules, state changes, external interactions and test coverage. The profile guides read-only analysis without implementation alternatives or execution plans. Evidence report loading, user review authority, source snapshots and report publication remain common contracts.
+
+## Inputs and questions
+
+`entry.resolve_analysis_target` trims free-text targets and resolves `PF-` identifiers against exactly one feature in the selected project-context evidence. `entry.validate_feature_target_input` rejects a missing target before provisioning. The wizard preserves project-evidence selection before feature-index selection or direct target text, including reuse and rewind behavior. `wizard.py` owns target questions; shared evidence questions stay in `wizard/steps_analysis.py`.
+
+## Reports and validation
+
+`profile.md` and `profile.json` own instructions and worker roles. `report.py` and `report_assets/` own feature report content. `validation._validate_feature_semantics` checks that report target fields match the resolved target. The common analysis validator continues to enforce current-code evidence, included paths, worker completion and scope confirmation. Shared schemas retain the same versions and artifact names. The profile does not choose a next lifecycle phase; orchestration remains common.
+
+## Guarantees
+
+| ID | Guarantee | Enforcement |
+|---|---|---|
+| FA-1 | A feature-index target resolves to exactly one selected project-context feature; free text cannot be empty. | `scripts/okstra_ctl/phases/feature_analysis/entry.py::resolve_analysis_target` |
+| FA-2 | Report target identity matches the resolved analysis target. | `scripts/okstra_ctl/phases/feature_analysis/validation.py::_validate_feature_semantics` |
+| FA-3 | Current-code evidence remains within the declared analysis scope. | `validators/validate_analysis_report.py::_validate_all_current_code_evidence` |
+| FA-4 | Feature target selection preserves the wizard's rendered arguments. | `tests/domain/wizard/test_analysis_inputs.py::test_feature_target_from_index_reaches_render_args` |