okstra 0.206.0 → 0.206.1

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` |

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

@@ -0,0 +1,27 @@
+"""기능 분석 결과의 대상 일치 정책."""
+
+from __future__ import annotations
+
+
+EVIDENCE_COLLECTIONS = ("flows", "domainRules", "stateChanges", "externalInteractions")
+
+
+def _validate_feature_semantics(data: dict, errors: list[str]) -> None:
+    analysis = data.get("featureAnalysis") or {}
+    common_target = ((data.get("analysisCommon") or {}).get("scope") or {}).get(
+        "resolvedTarget"
+    ) or {}
+    feature_target = analysis.get("target") or {}
+    for field in ("inputMode", "requestedValue"):
+        if feature_target.get(field) != common_target.get(field):
+            errors.append(
+                f"featureAnalysis.target.{field} must match "
+                f"analysisCommon.scope.resolvedTarget.{field}"
+            )
+    resolved_feature = common_target.get("feature") or {}
+    if common_target.get("inputMode") == "feature-index" and (
+        feature_target.get("featureId") != resolved_feature.get("id")
+    ):
+        errors.append(
+            "featureAnalysis.target.featureId must match the resolved feature id"
+        )