okstra 0.205.1 → 0.206.1

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"
+        )

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

@@ -0,0 +1,95 @@
+"""기능 분석 대상 선택·직접 입력 질문."""
+
+from __future__ import annotations
+from pathlib import Path
+from typing import Optional
+from okstra_ctl.analysis_inputs import (
+    AnalysisInputError,
+    AnalysisReportCandidate,
+    load_analysis_report_candidate,
+)
+from okstra_ctl.wizard.ids import (
+    PICK_TYPE_CUSTOM,
+    S_ANALYSIS_TARGET,
+    S_ANALYSIS_TARGET_PICK,
+)
+from okstra_ctl.wizard.state import Prompt, WizardError, WizardState
+from okstra_ctl.wizard.prompts import _opt, _p
+from okstra_ctl.wizard.steps_analysis import (
+    _analysis_evidence_paths,
+    _resolve_analysis_evidence,
+)
+from .entry import resolve_analysis_target
+
+
+def _feature_description(feature: dict[object, object]) -> str:
+    name = str(feature.get("name") or "")
+    summary = str(feature.get("summary") or "")
+    entry_point = str(feature.get("entryPoint") or feature.get("entrypoint") or "")
+    return " · ".join(value for value in (name, summary, entry_point) if value)
+
+
+def _build_analysis_target_pick(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, S_ANALYSIS_TARGET_PICK)
+    try:
+        candidate = load_analysis_report_candidate(
+            Path(state.project_root), Path(state.project_evidence_path)
+        )
+    except AnalysisInputError as exc:
+        raise WizardError(str(exc)) from exc
+    options = [
+        _opt(str(feature["id"]), str(feature["id"]), _feature_description(feature))
+        for feature in candidate.feature_index
+        if isinstance(feature, dict) and isinstance(feature.get("id"), str)
+    ][:3]
+    options.append(_opt(PICK_TYPE_CUSTOM, t["options"][PICK_TYPE_CUSTOM]))
+    return Prompt(
+        step=S_ANALYSIS_TARGET_PICK,
+        kind="pick",
+        label=t["label"],
+        options=options,
+        echo_template=t["echo_template"],
+    )
+
+
+def _accept_analysis_target(state: WizardState, value: str) -> str:
+    candidates: dict[Path, AnalysisReportCandidate] = {}
+    for path in _analysis_evidence_paths(state):
+        try:
+            candidate = load_analysis_report_candidate(Path(state.project_root), path)
+        except AnalysisInputError as exc:
+            raise WizardError(str(exc)) from exc
+        candidates[candidate.report_path] = candidate
+    try:
+        target = resolve_analysis_target(
+            value, _resolve_analysis_evidence(state), candidates
+        )
+    except AnalysisInputError as exc:
+        raise WizardError(str(exc)) from exc
+    requested_value = target["requestedValue"]
+    if not isinstance(requested_value, str):
+        raise WizardError("analysis target resolver returned an invalid requestedValue")
+    state.analysis_target = requested_value
+    state.analysis_target_pending_text = False
+    return requested_value
+
+
+def _submit_analysis_target_pick(state: WizardState, value: str) -> Optional[str]:
+    if value == PICK_TYPE_CUSTOM:
+        state.analysis_target_pending_text = True
+        return None
+    return f"analysis-target: {_accept_analysis_target(state, value)}"
+
+
+def _build_analysis_target(state: WizardState) -> Prompt:
+    t = _p(state.workspace_root, S_ANALYSIS_TARGET)
+    return Prompt(
+        step=S_ANALYSIS_TARGET,
+        kind="text",
+        label=t["label"],
+        echo_template=t["echo_template"],
+    )
+
+
+def _submit_analysis_target(state: WizardState, value: str) -> Optional[str]:
+    return f"analysis-target: {_accept_analysis_target(state, value)}"

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

@@ -0,0 +1,4 @@
+"""final-verification 단계 패키지.
+
+공통 실행 조립부와 다른 단계 패키지를 여기서 가져오지 않는다.
+"""

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

@@ -0,0 +1,8 @@
+{
+  "allowed": "  - acceptance verdict with requirement coverage assessment\n  - residual risk and regression notes\n  - routing recommendation as the `routingRecommendation` object `{target, rationale}`: `target` is one of `release-handoff`, `release-handoff(stage-group)`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `implementation`, `done`, and `rationale` ties that choice to the verdict and the blocker list. Both `release-handoff` forms require a release-ready verdict — `accepted`, or `conditional-accept` with every condition declaring `blocksReleaseHandoff: false` (`okstra_ctl.release_gate.release_handoff_allowed`); either verification scope may route there, because release-handoff opens one PR per stage. Prose alone does not route the task — Phase 7 projects `workflow.nextRecommendedPhase` from `target`",
+  "forbidden": [
+    "source code edits, follow-up bug fixes, or scope expansion",
+    "state-mutating commands against the project or shared environments; permitted mutations are limited to the run's own `.okstra` artifacts (reports, state, `<task_root>/qa/result-*.json` sidecars, `okstra handoff record-verified` on acceptance) and Tier3 conformance scripts that mutate only their qaEnv replica datastore — everything else is read-only execution of pre-existing test or validation commands",
+    "starting any follow-up phase inside this run; record findings and end the run"
+  ]
+}