okstra 0.206.0 → 0.207.0

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

@@ -0,0 +1,597 @@
+"""선택된 방향을 구현 계획으로 구체화한 결과의 전용 검증."""
+
+from __future__ import annotations
+
+import posixpath
+import re
+from collections import Counter
+from pathlib import Path
+from typing import Any, Mapping
+
+from okstra_ctl.exact_coverage import ExactCoverageError, calculate_plan_exact_coverage
+from okstra_ctl.implementation_direction import (
+    SelectedDirectionSnapshot,
+    load_selected_direction_snapshot,
+    validate_selected_direction_ref,
+    stage_validation_executability_errors,
+)
+from okstra_ctl.stage_citations import enumerated_stage_numbers
+from okstra_ctl.scope_provenance import (
+    brief_end_state_id_sequence,
+    brief_citation_problem,
+    parse_source,
+    resolve_chain,
+)
+
+
+_PLAN_EXECUTION_FIELDS = (
+    "directionRealization",
+    "stageMap",
+    "stages",
+    "designPreparation",
+    "dependencyMigrationRisk",
+    "validationChecklist",
+    "rollbackStrategy",
+    "requirementCoverage",
+    "coverageSummary",
+    "variationPointAnalysis",
+    "planBodyVerification",
+    "stepwiseExecution",
+    "supersessionLedger",
+    "crossProjectDependencies",
+    "decisionDrafts",
+    "skippedAdrCandidates",
+    "incrementalDecision",
+    "userNarrative",
+)
+
+
+def _direction_realization_errors(
+    realization: object, snapshot: SelectedDirectionSnapshot
+) -> list[str]:
+    if not isinstance(realization, Mapping):
+        return ["directionRealization is missing from a plan-ready result"]
+    direction = snapshot.data.get("direction")
+    if not isinstance(direction, Mapping):
+        return ["selected direction snapshot is missing its direction object"]
+    comparisons = {
+        "coreMechanism": direction.get("coreMechanism"),
+        "architectureBoundaries": direction.get("architectureBoundaries"),
+        "planningInvariants": snapshot.data.get("planningInvariants"),
+        "userConstraints": snapshot.data.get("userConstraints"),
+    }
+    return [
+        f"directionRealization.{field} must exactly preserve the selected-direction snapshot"
+        for field, expected in comparisons.items()
+        if realization.get(field) != expected
+    ]
+
+
+def _plan_reference_sets(
+    planning: Mapping[str, Any],
+) -> tuple[set[int], set[str], set[str], tuple[str, ...]]:
+    stages = [row for row in planning.get("stages") or () if isinstance(row, Mapping)]
+    stage_ids = {row["stage"] for row in stages if isinstance(row.get("stage"), int)}
+    step_ids = {
+        f"{stage['stage']}.{step['step']}"
+        for stage in stages
+        if isinstance(stage.get("stage"), int)
+        for step in stage.get("stepwiseExecution") or ()
+        if isinstance(step, Mapping) and isinstance(step.get("step"), int)
+    }
+    validation_ids = {
+        str(row.get("id"))
+        for row in planning.get("validationChecklist") or ()
+        if isinstance(row, Mapping) and row.get("id")
+    }
+    realization = planning.get("directionRealization")
+    file_rows = (
+        realization.get("fileStructure") or ()
+        if isinstance(realization, Mapping)
+        else ()
+    )
+    file_paths = tuple(
+        str(row.get("path"))
+        for row in file_rows
+        if isinstance(row, Mapping) and row.get("path")
+    )
+    return stage_ids, step_ids, validation_ids, file_paths
+
+
+def _duplicate_values(values: list[object]) -> tuple[object, ...]:
+    return tuple(value for value, count in Counter(values).items() if count > 1)
+
+
+def _normalized_plan_file_path(value: object) -> str:
+    return posixpath.normpath(str(value).replace("\\", "/"))
+
+
+def _plan_structure_errors(planning: Mapping[str, Any]) -> list[str]:
+    failures: list[str] = []
+    stage_map = [
+        row for row in planning.get("stageMap") or () if isinstance(row, Mapping)
+    ]
+    stages = [row for row in planning.get("stages") or () if isinstance(row, Mapping)]
+    stage_map_numbers = [
+        row["stage"] for row in stage_map if isinstance(row.get("stage"), int)
+    ]
+    stage_numbers = [
+        row["stage"] for row in stages if isinstance(row.get("stage"), int)
+    ]
+    duplicate_stage_map = set(_duplicate_values(stage_map_numbers))
+    duplicate_stages = set(_duplicate_values(stage_numbers))
+    failures.extend(
+        f"stageMap contains duplicate stage {number}"
+        for number in sorted(duplicate_stage_map)
+    )
+    failures.extend(
+        f"stages contains duplicate stage {number}"
+        for number in sorted(duplicate_stages)
+    )
+
+    stage_map_set = set(stage_map_numbers)
+    stage_set = set(stage_numbers)
+    failures.extend(
+        f"stageMap is missing stages stage {number}"
+        for number in sorted(stage_set - stage_map_set)
+    )
+    failures.extend(
+        f"stages is missing stageMap stage {number}"
+        for number in sorted(stage_map_set - stage_set)
+    )
+    unique_stage_map = {
+        row["stage"]: row
+        for row in stage_map
+        if isinstance(row.get("stage"), int) and row["stage"] not in duplicate_stage_map
+    }
+    unique_stages = {
+        row["stage"]: row
+        for row in stages
+        if isinstance(row.get("stage"), int) and row["stage"] not in duplicate_stages
+    }
+    failures.extend(
+        f"stageMap and stages stage {number} title must match"
+        for number in sorted(unique_stage_map.keys() & unique_stages.keys())
+        if unique_stage_map[number].get("title") != unique_stages[number].get("title")
+    )
+
+    for stage in stages:
+        stage_number = stage.get("stage")
+        step_numbers = [
+            step["step"]
+            for step in stage.get("stepwiseExecution") or ()
+            if isinstance(step, Mapping) and isinstance(step.get("step"), int)
+        ]
+        failures.extend(
+            f"stages stage {stage_number} step {step_number} is duplicate"
+            for step_number in sorted(_duplicate_values(step_numbers))
+        )
+
+    validation_ids = [
+        str(row["id"])
+        for row in planning.get("validationChecklist") or ()
+        if isinstance(row, Mapping) and row.get("id")
+    ]
+    failures.extend(
+        f"validationChecklist id {validation_id} is duplicate"
+        for validation_id in sorted(_duplicate_values(validation_ids))
+    )
+
+    realization = planning.get("directionRealization")
+    file_rows = (
+        [
+            row
+            for row in realization.get("fileStructure") or ()
+            if isinstance(row, Mapping)
+        ]
+        if isinstance(realization, Mapping)
+        else []
+    )
+    file_ids = [str(row["id"]) for row in file_rows if row.get("id")]
+    failures.extend(
+        f"directionRealization.fileStructure id {file_id} is duplicate"
+        for file_id in sorted(_duplicate_values(file_ids))
+    )
+    normalized_paths = [
+        _normalized_plan_file_path(row["path"]) for row in file_rows if row.get("path")
+    ]
+    failures.extend(
+        f"directionRealization.fileStructure path {path} is duplicate after normalization"
+        for path in sorted(_duplicate_values(normalized_paths))
+    )
+    return failures
+
+
+def _coverage_reference_errors(
+    rows: list[Mapping[str, Any]],
+    stage_ids: set[int],
+    step_ids: set[str],
+    validation_ids: set[str],
+    file_paths: tuple[str, ...],
+    dependencies: list[Mapping[str, Any]],
+) -> list[str]:
+    failures: list[str] = []
+    reference_sets = {
+        "stageRefs": stage_ids,
+        "stepRefs": step_ids,
+        "validationRefs": validation_ids,
+        "fileRefs": set(file_paths),
+        "crossProjectDependencyRefs": {row.get("id") for row in dependencies},
+    }
+    for row in rows:
+        requirement_id = str(row.get("originalRequirementId") or "<missing>")
+        external_refs = row.get("crossProjectDependencyRefs") or ()
+        if row.get("status") == "externally-tracked":
+            if not external_refs:
+                failures.append(
+                    f"requirementCoverage {requirement_id} requires crossProjectDependencyRefs"
+                )
+            for ref in external_refs:
+                matches = [item for item in dependencies if item.get("id") == ref]
+                if (
+                    len(matches) != 1
+                    or any(
+                        not isinstance(matches[0].get(field), str)
+                        or not matches[0][field].strip()
+                        for field in (
+                            "project",
+                            "requiredWork",
+                            "verificationSignal",
+                            "linkedWork",
+                            "howToStart",
+                        )
+                    )
+                    or matches[0].get("direction")
+                    not in {"upstream-precondition", "downstream-carry"}
+                ):
+                    failures.append(
+                        f"requirementCoverage {requirement_id} crossProjectDependencyRefs must resolve to one complete dependency: {ref}"
+                    )
+        elif external_refs:
+            failures.append(
+                f"requirementCoverage {requirement_id} external references require externally-tracked status"
+            )
+        elif any(
+            not row.get(field)
+            for field in ("stageRefs", "stepRefs", "validationRefs", "fileRefs")
+        ):
+            failures.append(
+                f"requirementCoverage {requirement_id} requires local stage, step, validation and file references"
+            )
+        for field, valid_values in reference_sets.items():
+            dangling = [
+                value for value in row.get(field) or () if value not in valid_values
+            ]
+            if dangling:
+                failures.append(
+                    f"requirementCoverage {requirement_id} {field} contains "
+                    f"dangling reference(s): {dangling}"
+                )
+    return failures
+
+
+def _requirement_ids_for_scope(
+    rows: list[Mapping[str, Any]], field: str, value: object
+) -> tuple[str, ...]:
+    return tuple(
+        str(row.get("originalRequirementId"))
+        for row in rows
+        if value in (row.get(field) or ()) and row.get("originalRequirementId")
+    )
+
+
+def _coverage_summary_errors(
+    planning: Mapping[str, Any], original_ids: tuple[str, ...]
+) -> list[str]:
+    rows = [
+        row
+        for row in planning.get("requirementCoverage") or ()
+        if isinstance(row, Mapping)
+    ]
+    row_ids = tuple(str(row.get("originalRequirementId") or "") for row in rows)
+    failures: list[str] = []
+    if not original_ids:
+        return ["original requirement denominator from taskBriefPath is empty"]
+    if row_ids != original_ids:
+        failures.append(
+            "original requirement rows must match the taskBriefPath requirement "
+            "sequence exactly once"
+        )
+        return failures
+    structure_failures = _plan_structure_errors(planning)
+    failures.extend(structure_failures)
+    stage_ids, step_ids, validation_ids, file_paths = _plan_reference_sets(planning)
+    failures.extend(
+        _coverage_reference_errors(
+            rows,
+            stage_ids,
+            step_ids,
+            validation_ids,
+            file_paths,
+            [
+                row
+                for row in planning.get("crossProjectDependencies") or ()
+                if isinstance(row, Mapping)
+            ],
+        )
+    )
+    if failures:
+        return failures
+    # 검증된 외부 작업 연결은 계획 범위에만 포함하며 실제 완료 상태는 바꾸지 않는다.
+    statuses = {
+        row_id: "covered"
+        if row.get("status") == "externally-tracked"
+        else str(row.get("status") or "")
+        for row_id, row in zip(row_ids, rows)
+    }
+    stage_requirements = {
+        stage: _requirement_ids_for_scope(rows, "stageRefs", stage)
+        for stage in sorted(stage_ids)
+    }
+    file_requirements = {
+        path: _requirement_ids_for_scope(rows, "fileRefs", path) for path in file_paths
+    }
+    try:
+        result, unmapped_stages, unmapped_files = calculate_plan_exact_coverage(
+            original_ids, statuses, stage_requirements, file_requirements
+        )
+    except ExactCoverageError as exc:
+        return [*failures, f"plan-ready requires exact 100% coverage: {exc}"]
+    failures.extend(
+        f"unmapped stage {stage} has no original requirement"
+        for stage in unmapped_stages
+    )
+    failures.extend(
+        f"unmapped file change {path} has no original requirement"
+        for path in unmapped_files
+    )
+    failures.extend(
+        _declared_coverage_summary_errors(
+            planning.get("coverageSummary"), result, unmapped_stages, unmapped_files
+        )
+    )
+    if result.verdict != "exact":
+        failures.append("plan-ready requires exact 100% coverage")
+    return failures
+
+
+def _declared_coverage_summary_errors(
+    summary: object,
+    result: Any,
+    unmapped_stages: tuple[int, ...],
+    unmapped_files: tuple[str, ...],
+) -> list[str]:
+    if not isinstance(summary, Mapping):
+        return ["coverageSummary is missing from a plan-ready result"]
+    expected = {
+        "coveragePercent": result.coverage_percent,
+        "scopePrecisionPercent": result.scope_precision_percent,
+        "coverageVerdict": result.verdict,
+        "unmappedStages": list(unmapped_stages),
+        "unmappedFileChanges": list(unmapped_files),
+    }
+    return [
+        f"coverageSummary.{field} does not match recalculated plan coverage"
+        for field, value in expected.items()
+        if summary.get(field) != value
+    ]
+
+
+def _is_config_only_path(path: str) -> bool:
+    name = posixpath.basename(posixpath.normpath(str(path).replace("\\", "/")))
+    if name == "Dockerfile" or name.startswith("Dockerfile."):
+        return True
+    if name.startswith("docker-compose") or name.startswith(".env"):
+        return True
+    return name.endswith((".yml", ".yaml"))
+
+
+def _micro_stage_fold_errors(planning: Mapping[str, Any]) -> list[str]:
+    """설정 파일 전용 종속 stage 는 독립 stage 가 아니다 — 커밋으로만 나눈다.
+
+    실측(dev-10341): 다른 stage 가 도입한 플래그를 Dockerfile/compose 2줄,
+    workflow 2줄로 전파하는 작업이 stage 2·3 을 각각 차지해 run 2회(회당
+    30분+)와 검증 차단 1회를 낳았다. 값 전파는 도입 stage 의 스텝이고,
+    분리가 필요하면 커밋을 나눈다. 첫 stage(의존 없음)는 예외다 — 설정만
+    바꾸는 태스크 자체는 정당하다.
+    """
+    dependent: dict[int, bool] = {}
+    for row in planning.get("stageMap") or ():
+        if isinstance(row, Mapping) and isinstance(row.get("stage"), int):
+            raw = str(row.get("dependsOn") or "").strip().lower()
+            dependent[row["stage"]] = raw not in ("", "(none)", "none")
+    failures: list[str] = []
+    for stage in planning.get("stages") or ():
+        if not isinstance(stage, Mapping):
+            continue
+        number = stage.get("stage")
+        if not isinstance(number, int) or not dependent.get(number):
+            continue
+        paths = [
+            str(path)
+            for step in stage.get("stepwiseExecution") or ()
+            if isinstance(step, Mapping)
+            for path in step.get("plannedPaths") or ()
+        ]
+        if paths and all(_is_config_only_path(path) for path in paths):
+            failures.append(
+                f"stage {number} is a config-only propagation stage "
+                f"({sorted(set(paths))}); fold it into the stage that introduces "
+                "the value and split the work by commits, not stages"
+            )
+    return failures
+
+
+def _direction_invalidation_errors(planning: Mapping[str, Any]) -> list[str]:
+    failures: list[str] = []
+    invalidation = planning.get("directionInvalidation")
+    if not isinstance(invalidation, Mapping):
+        failures.append("direction-invalidated requires directionInvalidation evidence")
+    else:
+        for field in ("reasons", "codeEvidence"):
+            values = invalidation.get(field)
+            if (
+                not isinstance(values, list)
+                or not values
+                or any(
+                    not isinstance(value, str) or not value.strip() for value in values
+                )
+            ):
+                failures.append(f"directionInvalidation.{field} must contain evidence")
+    if planning.get("routing") != "implementation-option-selection":
+        failures.append(
+            "direction-invalidated routing must be implementation-option-selection"
+        )
+    for field in _PLAN_EXECUTION_FIELDS:
+        if field in planning:
+            failures.append(
+                f"direction-invalidated must not contain execution field {field}"
+            )
+    return failures
+
+
+def validate_selected_direction_plan(
+    data: Mapping[str, Any], brief_path: Path, snapshot_path: Path
+) -> list[str]:
+    """Validate selected-direction planning semantics against independent inputs."""
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, Mapping):
+        return ["implementationPlanning is missing"]
+    if planning.get("planningContract") != "selected-direction":
+        return ["implementationPlanning.planningContract must be selected-direction"]
+    snapshot, failures = load_selected_direction_snapshot(snapshot_path)
+    if snapshot is None:
+        return failures
+    header = data.get("header")
+    plan_task_key = header.get("taskKey") if isinstance(header, Mapping) else None
+    snapshot_task_key = snapshot.data.get("taskKey")
+    if not isinstance(plan_task_key, str) or not plan_task_key:
+        failures.append("plan header.taskKey must be a non-empty string")
+    if not isinstance(snapshot_task_key, str) or not snapshot_task_key:
+        failures.append(
+            "selected direction snapshot taskKey must be a non-empty string"
+        )
+    elif isinstance(plan_task_key, str) and snapshot_task_key != plan_task_key:
+        failures.append(
+            "selected direction snapshot taskKey must exactly match plan header.taskKey"
+        )
+    ref = planning.get("selectedDirectionRef")
+    if not isinstance(ref, Mapping):
+        failures.append("selectedDirectionRef is missing")
+    else:
+        failures.extend(validate_selected_direction_ref(ref, snapshot))
+    outcome = planning.get("outcome")
+    if outcome == "direction-invalidated":
+        failures.extend(_direction_invalidation_errors(planning))
+        return failures
+    if outcome != "plan-ready":
+        return [*failures, f"selected-direction outcome is invalid: {outcome!r}"]
+    failures.extend(
+        _direction_realization_errors(planning.get("directionRealization"), snapshot)
+    )
+    failures.extend(
+        _coverage_summary_errors(
+            planning, brief_end_state_id_sequence(Path(brief_path))
+        )
+    )
+    failures.extend(stage_validation_executability_errors(planning))
+    failures.extend(_micro_stage_fold_errors(planning))
+    return failures
+
+
+# Deliberately not `_COVERED_BY_STAGE_REF_RE`: the two directions disagree on
+# what "no match" means — forward treats it as nothing to verify and passes,
+# reverse treats it as nothing cited and orphans every stage — so the reverse
+# reader must cover `Stages 1, 2` and `Stage 1 and 2` too.
+#
+# It reads hand-enumerated numbers only. A range's interior is deliberately NOT
+# coverage evidence: one `Stages 1-64` cell would otherwise stamp every stage in
+# the map while the planner confirmed none of them. The incremental-scope
+# back-trace keeps the widening reader (`cited_stage_numbers`) because "could
+# this answer reach stage 5" is the opposite question and must over-approximate.
+
+
+# Statuses under which a row asserts the plan does work for the requirement.
+# `gap` is excluded: it states the plan does NOT cover the requirement, so it
+# can justify no stage. `blocked C-NNN` and `documented-deviation` are included:
+# each records a real requirement with a planned treatment, even when the
+# treatment awaits approval or deliberately differs from the original request.
+_COVERAGE_CLAIMING_STATUS_RE = re.compile(
+    r"^(covered|blocked C-\d{3,}|documented-deviation)$"
+)
+
+
+def _validate_requirement_provenance(
+    data: dict, headings: set[str], end_state: set[str], failures: list[str]
+) -> None:
+    """Every requirement must declare where it came from.
+
+    The planning input template already states that any change beyond what
+    `Requirement Summary` demands is out of scope by default; without this
+    check that sentence has no enforcement point and a phase can invent
+    requirements freely.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    rows = [r for r in (ip.get("requirementCoverage") or []) if isinstance(r, dict)]
+    if not rows:
+        return
+
+    refs = {
+        str(r.get("id") or "").strip(): parse_source(str(r.get("source") or ""))
+        for r in rows
+    }
+
+    for rid, ref in refs.items():
+        problem = brief_citation_problem(ref, headings, end_state)
+        if problem:
+            failures.append(
+                f"final-report data.json: requirementCoverage `{rid}` {problem}. A "
+                "requirement must trace to a line the reporter actually wrote."
+            )
+
+    for rid, verdict in resolve_chain(refs).items():
+        if verdict != "ok":
+            failures.append(
+                f"final-report data.json: requirementCoverage `{rid}` provenance "
+                f"failed — {verdict}. An item with no admissible source is not a "
+                "requirement: raise it as a `Blocks=approval` clarification instead."
+            )
+
+
+def _validate_stage_has_requirement(data: dict, failures: list[str]) -> None:
+    """Reverse of `_validate_requirement_coverage_covered_by`.
+
+    That check proves every requirement reaches a stage; this one proves every
+    stage traces back to a requirement. Without it a plan can carry stages no
+    one asked for and still pass every gate.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    stage_numbers = {
+        s.get("stage")
+        for s in (ip.get("stages") or [])
+        if isinstance(s, dict) and isinstance(s.get("stage"), int)
+    }
+    if not stage_numbers:
+        return
+
+    cited: set[int] = set()
+    for row in ip.get("requirementCoverage") or []:
+        if not isinstance(row, dict):
+            continue
+        if not _COVERAGE_CLAIMING_STATUS_RE.match(str(row.get("status") or "").strip()):
+            continue
+        cited |= enumerated_stage_numbers(str(row.get("coveredBy") or ""))
+
+    for orphan in sorted(stage_numbers - cited):
+        failures.append(
+            f"final-report data.json: Stage {orphan} is cited by no requirementCoverage "
+            "row — it traces back to nothing the brief asked for. Either cite the "
+            "requirement it serves, or drop it and raise it as a `Blocks=approval` "
+            "clarification (profile: scope provenance). A range cites only its "
+            "endpoints here: write `Stages 1, 2, 3` rather than `Stages 1-3`, so each "
+            "stage this requirement covers is one the planner named."
+        )