okstra 0.206.0 → 0.207.0

package/runtime/validators/validate_analysis_report.py

@@ -15,6 +15,16 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
         sys.path.insert(0, str(_ssot_dir))
 
 from okstra_ctl.analysis_inputs import ANALYSIS_TASK_TYPES
+from okstra_ctl.phases.change_impact_analysis.validation import (
+    EVIDENCE_COLLECTIONS as CHANGE_IMPACT_EVIDENCE_COLLECTIONS,
+    validate_change_impact_semantics,
+)
+from okstra_ctl.phases.feature_analysis.validation import (
+    EVIDENCE_COLLECTIONS as FEATURE_EVIDENCE_COLLECTIONS,
+    _validate_feature_semantics,
+)
+from okstra_ctl.analysis_scope import _normalized_project_path, _path_is_included
+from okstra_ctl.phases.project_analysis.validation import validate_project_semantics
 from okstra_ctl.final_report_paths import final_report_data_path
 from okstra_ctl.paths import RunRef
 from okstra_ctl.report_views import analysis_review_context
@@ -35,19 +45,8 @@ _EVIDENCE_COLLECTIONS = {
         "externalSystems",
         "featureIndex",
     ),
-    "feature-analysis": (
-        "flows",
-        "domainRules",
-        "stateChanges",
-        "externalInteractions",
-    ),
-    "change-impact-analysis": (
-        "preservedBehaviors",
-        "impactItems",
-        "dependencyBlastRadius",
-        "testImpact",
-        "operationalImpact",
-    ),
+    "feature-analysis": FEATURE_EVIDENCE_COLLECTIONS,
+    "change-impact-analysis": CHANGE_IMPACT_EVIDENCE_COLLECTIONS,
 }
 _ANALYSIS_PARENT_KEYS = {
     "project-analysis": "projectAnalysis",
@@ -111,33 +110,6 @@ def validate_analysis_snapshot(
         )
 
 
-def _normalized_project_path(path: object) -> PurePosixPath | None:
-    if not isinstance(path, str):
-        return None
-    raw = path.strip().rstrip("/")
-    if not raw or raw == "." or raw.startswith("/"):
-        return None
-    if any(part in {"", ".", ".."} for part in raw.split("/")):
-        return None
-    normalized = PurePosixPath(raw)
-    if normalized.is_absolute():
-        return None
-    return normalized
-
-
-def _path_is_included(path: object, included_paths: list[object]) -> bool:
-    candidate = _normalized_project_path(path)
-    if candidate is None:
-        return False
-    for raw in included_paths:
-        included = _normalized_project_path(raw)
-        if included is not None and (
-            candidate == included or included in candidate.parents
-        ):
-            return True
-    return False
-
-
 def _validate_included_paths(included_paths: list[object], errors: list[str]) -> None:
     for index, path in enumerate(included_paths):
         if _normalized_project_path(path) is None:
@@ -201,90 +173,6 @@ def _validate_all_current_code_evidence(
         )
 
 
-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 '?'}`")
-
-
-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"
-        )
-
-
-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"
-            )
-
 
 def _required_worker_roles(
     run_manifest: dict, errors: list[str]
@@ -475,11 +363,11 @@ def validate_analysis_semantics(
     )
     _validate_all_current_code_evidence(task_type, data, errors)
     if task_type == "project-analysis":
-        _validate_project_semantics(data, errors)
+        validate_project_semantics(data, errors)
     elif task_type == "feature-analysis":
         _validate_feature_semantics(data, errors)
     elif task_type == "change-impact-analysis":
-        _validate_change_impact_semantics(data, errors)
+        validate_change_impact_semantics(data, errors)
     _validate_scope_before_dispatch(
         data, analysis_worker_roles, reporter_confirmation, errors
     )

package/runtime/python/okstra_ctl/report_html/view_models/implementation_planning.py

@@ -1,147 +0,0 @@
-"""Human-first implementation-planning view and approval state."""
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-
-from ..common import evidence_index
-from ..models import HumanReportView, VisualEdge, VisualNode
-from ..visualizations import stage_map_figure
-
-
-@dataclass(frozen=True)
-class PlanApprovalState:
-    option_names: tuple[str, ...]
-    recommended_option: str
-    disabled_reason: str
-    blocker_ids: tuple[str, ...]
-    show_option_selector: bool = True
-    reentry_command: str = ""
-
-
-def resolve_recommended_option(rec_name: str, names: tuple[str, ...]) -> str:
-    if rec_name in names:
-        return rec_name
-    matches = [
-        name
-        for name in names
-        if rec_name and (name.startswith(rec_name) or rec_name.startswith(name))
-    ]
-    return matches[0] if len(matches) == 1 else names[0]
-
-
-def plan_approval_state(data: dict) -> PlanApprovalState | None:
-    planning = data.get("implementationPlanning")
-    if not isinstance(planning, dict):
-        return None
-    blockers = tuple(
-        row["id"]
-        for row in data.get("clarificationItems", [])
-        if row.get("blocks") == "approval"
-        and row.get("status") in {"open", "answered"}
-    )
-    reason = f"{len(blockers)} approval blocker(s) unresolved" if blockers else ""
-    if planning.get("planningContract") == "selected-direction":
-        if planning.get("outcome") == "direction-invalidated" and not reason:
-            reason = "selected direction invalidated"
-        task_key = (data.get("header") or {}).get("taskKey", "")
-        reentry_command = (
-            f"/okstra-run task-key={task_key} "
-            "task-type=implementation-option-selection"
-            if planning.get("outcome") == "direction-invalidated" and task_key
-            else ""
-        )
-        return PlanApprovalState(
-            (), "", reason, blockers, False, reentry_command
-        )
-    names = tuple(
-        row["name"]
-        for row in planning.get("optionCandidates", [])
-        if isinstance(row, dict) and row.get("name")
-    )
-    if not names:
-        return None
-    recommended = planning.get("recommendedOption", {}).get("name", "")
-    return PlanApprovalState(
-        names,
-        resolve_recommended_option(recommended, names),
-        reason,
-        blockers,
-    )
-
-
-def _stage_figure(planning: dict):
-    nodes = tuple(
-        VisualNode(
-            f"stage-{row['stage']}",
-            f"Stage {row['stage']} · {row['title']}",
-            "stage",
-            "planned",
-            row["exitContractSummary"],
-        )
-        for row in planning["stageMap"]
-    )
-    edges = tuple(
-        VisualEdge(f"stage-{dependency}", f"stage-{row['stage']}", "precedes", "dependency")
-        for row in planning["stageMap"]
-        for dependency in re.findall(r"\d+", row["dependsOn"])
-    )
-    return stage_map_figure(nodes=nodes, edges=edges, title="Implementation stage dependencies")
-
-
-# Record fields this template anchors as `id-<row id>` (see
-# `HumanReportView.anchored_fields`). The implementer-facing tables the
-# approver does not read — validation checklist, cross-project dependencies,
-# migration risk, rollback — are not drawn, so their rows land in the ledger.
-ANCHORED_FIELDS = (
-    "implementationPlanning.directionRealization.fileStructure",
-    "implementationPlanning.directionRealization.planningInvariants",
-    "implementationPlanning.optionCandidates.fileStructure",
-    "implementationPlanning.designPreparation.items",
-    "implementationPlanning.requirementCoverage",
-    "implementationPlanning.planBodyVerification.planItems",
-    "implementationPlanning.supersessionLedger",
-)
-
-
-def build_implementation_planning_view(data: dict) -> HumanReportView:
-    planning = data["implementationPlanning"]
-    figure = _stage_figure(planning) if planning.get("stageMap") else None
-    approval = plan_approval_state(data)
-    activities = tuple(
-        row for row in data.get("agentActivity", []) if isinstance(row, dict)
-    )
-    decision_cards = tuple(
-        row
-        for row in data.get("clarificationItems", [])
-        if isinstance(row, dict)
-        and row.get("blocks") == "approval"
-        and isinstance(row.get("approvalContext"), dict)
-    )
-    context = {
-        "humanSummary": data["humanSummary"],
-        "planning": planning,
-        "narrative": planning.get("userNarrative", {}),
-        "stageFigure": figure,
-        "approval": approval,
-        "openDecisions": [
-            row
-            for row in data.get("clarificationItems", [])
-            if isinstance(row, dict)
-            and row.get("blocks") == "approval"
-            and row.get("status") in {"open", "answered"}
-        ],
-        "agentActivities": activities,
-        "activityById": {
-            row["activityId"]: row for row in activities if row.get("activityId")
-        },
-        "decisionCards": decision_cards,
-        "evidenceIndex": evidence_index(data, ANCHORED_FIELDS),
-    }
-    return HumanReportView(
-        "implementation-planning",
-        "html/tasks/implementation-planning.template.html",
-        context,
-        (figure,) if figure is not None else (),
-        anchored_fields=ANCHORED_FIELDS,
-    )

package/runtime/python/okstra_ctl/technical_verification.py

@@ -1,195 +0,0 @@
-"""미확정 사실의 시험 입력과 관측 결과를 연결하며 도입 승인은 만들지 않는다."""
-
-from __future__ import annotations
-
-import hashlib
-import re
-from collections.abc import Mapping
-from pathlib import Path
-from typing import Any, TypedDict
-
-from .clarification_items import USER_INPUT_BLOCKS, progress_blocking_ids
-from .final_report_schema import load_schema_for_data, validate
-from .implementation_direction import validate_task_artifact_path
-from .json_boundary import load_owned_object_snapshot, serialize_owned_object
-
-
-class VerificationFact(TypedDict):
-    id: str
-    candidateId: str
-    factIndex: int
-    fact: str
-    whyItMatters: str
-    evidence: list[str]
-
-
-class VerificationInput(TypedDict):
-    sourceReport: str
-    sourceDataSha256: str
-    scope: str
-    facts: list[VerificationFact]
-
-
-class TechnicalVerificationError(ValueError):
-    """시험 입력 또는 관측 결과가 원본 사실과 일치하지 않는다."""
-
-
-def technical_verification_facts(data: Mapping[str, Any]) -> list[VerificationFact]:
-    """안전 차단이 없는 후보의 명시적인 기술 검증 사실만 추출한다."""
-    blockers = progress_blocking_ids(
-        data.get("clarificationItems"), USER_INPUT_BLOCKS, report_data=data
-    )
-    if blockers:
-        raise TechnicalVerificationError(
-            "unresolved user decisions: " + ", ".join(blockers)
-        )
-    selection = data.get("implementationOptionSelection") or {}
-    facts: list[VerificationFact] = []
-    for candidate in selection.get("candidateAudit") or []:
-        if candidate.get("safetyBlockers"):
-            continue
-        for index, fact in enumerate(candidate.get("unresolvedFeasibilityFacts") or []):
-            if fact.get("resolutionKind") != "technical-verification":
-                continue
-            facts.append(
-                {
-                    "id": f"TV-{len(facts) + 1:03d}",
-                    "candidateId": candidate["id"],
-                    "factIndex": index,
-                    "fact": fact["fact"],
-                    "whyItMatters": fact["whyItMatters"],
-                    "evidence": fact["evidence"],
-                }
-            )
-    if not facts:
-        raise TechnicalVerificationError("no eligible technical-verification facts")
-    return facts
-
-
-def resolve_technical_verification_input(
-    report: Path, project_root: Path, task_root: Path, task_key: str
-) -> VerificationInput:
-    """같은 작업의 후보 비교 기록을 시험 입력으로 고정한다."""
-    report = report if report.is_absolute() else project_root / report
-    validate_task_artifact_path(report, task_root, "technical verification source")
-    expected_parent = task_root / "runs/implementation-option-selection/reports"
-    if report.parent != expected_parent or not re.fullmatch(
-        r"final-report-implementation-option-selection-\d{3,}\.data\.json", report.name
-    ):
-        raise TechnicalVerificationError(
-            "source must be this task's option-selection record"
-        )
-    snapshot = load_owned_object_snapshot(
-        report, artifact="technical verification source"
-    )
-    data = snapshot.value
-    errors = validate(data, load_schema_for_data(data))
-    if errors:
-        raise TechnicalVerificationError("invalid source report: " + "; ".join(errors))
-    if data["header"]["taskKey"] != task_key:
-        raise TechnicalVerificationError(
-            "source taskKey does not match verification task"
-        )
-    return {
-        "sourceReport": report.relative_to(project_root).as_posix(),
-        "sourceDataSha256": hashlib.sha256(snapshot.raw_bytes).hexdigest(),
-        "scope": "technical-evidence-only",
-        "facts": technical_verification_facts(data),
-    }
-
-
-def write_technical_verification_input(
-    payload: VerificationInput, run_root: Path, seq: str
-) -> Path:
-    """실행 순번별 입력을 저장해 후속 실행이 이전 시험 범위를 덮지 않게 한다."""
-    path = run_root / "state" / f"technical-verification-input-{seq}.json"
-    serialized = serialize_owned_object(path, payload, artifact="technical verification input")
-    path.parent.mkdir(parents=True, exist_ok=True)
-    with path.open("x", encoding="utf-8") as output:
-        output.write(serialized)
-    return path
-
-
-def _check_execution_evidence(
-    check: Mapping[str, Any], project_root: Path, run_root: Path, seq: str
-) -> list[str]:
-    """관측 판정은 실행 기록과 실행별 시험 디렉터리를 요구한다."""
-    errors = []
-    commands = check.get("commands") or []
-    if check.get("status") != "not-run" and not commands:
-        errors.append(f"{check['id']}: an observed result requires command evidence")
-    for command in commands:
-        try:
-            log = project_root / command["logPath"]
-            experiment_root = run_root / "experiments" / seq
-            validate_task_artifact_path(log, experiment_root, "verification log")
-            if not log.read_text(encoding="utf-8").strip():
-                errors.append(f"{check['id']}: verification log is empty")
-            cwd = project_root / command["cwd"]
-            cwd.resolve(strict=True).relative_to(experiment_root.resolve(strict=True))
-            relative = cwd.relative_to(experiment_root)
-            current = run_root
-            for part in ("experiments", seq, *relative.parts):
-                current = current / part
-                if current.is_symlink():
-                    raise TechnicalVerificationError(
-                        "experiment cwd contains a symlink"
-                    )
-            if not cwd.is_dir() or cwd.is_symlink():
-                errors.append(f"{check['id']}: experiment cwd must be a directory")
-        except (OSError, ValueError) as exc:
-            errors.append(f"{check['id']}: invalid execution evidence: {exc}")
-        if check.get("status") == "supported" and command.get("exitCode") != 0:
-            errors.append(f"{check['id']}: a supported result has a failed command")
-    return errors
-
-
-def validate_technical_verification_report(
-    data: Mapping[str, Any], report_path: Path, project_root: Path
-) -> list[str]:
-    """발행·최종 검증에서 같은 사실 집합과 실제 시험 산출물을 대조한다."""
-    if (data.get("header") or {}).get("taskType") != "technical-verification":
-        return []
-    match = re.fullmatch(
-        r"final-report-technical-verification-(\d{3,})\.data\.json", report_path.name
-    )
-    if match is None:
-        return ["technical verification report must use its canonical record path"]
-    run_root = report_path.parent.parent
-    path = run_root / "state" / f"technical-verification-input-{match[1]}.json"
-    try:
-        validate_task_artifact_path(path, run_root, "technical verification input")
-        source = load_owned_object_snapshot(
-            path, artifact="technical verification input"
-        ).value
-    except (OSError, ValueError) as exc:
-        return [str(exc)]
-    block = data.get("technicalVerification") or {}
-    errors = []
-    for key in ("sourceReport", "sourceDataSha256", "scope"):
-        if block.get(key) != source.get(key):
-            errors.append(f"technicalVerification.{key} must match the run input")
-    expected = {fact["id"]: fact for fact in source["facts"]}
-    checks = block.get("checks") or []
-    ids = [check.get("id") for check in checks]
-    if len(ids) != len(set(ids)) or set(ids) != set(expected):
-        errors.append(
-            "technicalVerification.checks must cover each input fact exactly once"
-        )
-    for check in checks:
-        fact = expected.get(check.get("id"))
-        if fact is None:
-            continue
-        for key in ("candidateId", "factIndex", "fact"):
-            if check.get(key) != fact[key]:
-                errors.append(f"{check['id']}: {key} must preserve the input fact")
-        errors.extend(
-            _check_execution_evidence(check, project_root, run_root, match[1])
-        )
-    if (block.get("routing") or {}).get(
-        "nextTaskType"
-    ) != "implementation-option-selection":
-        errors.append(
-            "technical verification returns only to implementation-option-selection"
-        )
-    return errors