okstra 0.205.1 → 0.206.1

package/runtime/python/okstra_ctl/implementation_direction.py

@@ -5,10 +5,8 @@ from __future__ import annotations
 import hashlib
 import json
 import os
-import posixpath
 import re
 import stat
-from collections import Counter
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Mapping
@@ -19,7 +17,6 @@ from .final_report_paths import (
     final_report_markdown_path,
     is_full_reading_copy_path,
 )
-from .exact_coverage import ExactCoverageError, calculate_plan_exact_coverage
 from .final_report_schema import (
     SchemaError,
     load_schema_for_data,
@@ -30,9 +27,11 @@ from .json_boundary import (
     load_owned_object_snapshot,
     write_owned_object_atomic,
 )
-from .report_views import normalize_direction_selection_identity
+from .report_views import (
+    direction_candidate_ineligibility,
+    normalize_direction_selection_identity,
+)
 from .qa_commands import find_denied_tokens
-from .scope_provenance import brief_end_state_id_sequence
 from .user_response import UserResponseError, parse_direction_selection
 
 
@@ -309,15 +308,13 @@ def _selected_option(
         raise DirectionSelectionError(str(exc)) from exc
     if report_option_id != option_id:
         raise DirectionSelectionError("selected candidate id does not match report")
-    coverage = option.get("coverageSummary")
-    if not isinstance(coverage, Mapping) or coverage.get("coverageVerdict") != "exact":
-        raise DirectionSelectionError("selected candidate must have exact coverage")
+    ineligibility = direction_candidate_ineligibility(option)
+    if ineligibility:
+        raise DirectionSelectionError(ineligibility)
     return option, report_option_name
 
 
-def _validate_no_blockers(data: Mapping[str, Any], option: Mapping[str, Any]) -> None:
-    if option.get("safetyBlockers") or option.get("unresolvedFeasibilityFacts"):
-        raise DirectionSelectionError("selected candidate has a safety blocker")
+def _validate_no_blockers(data: Mapping[str, Any]) -> None:
     blockers = progress_blocking_ids(
         data.get("clarificationItems"), USER_INPUT_BLOCKS
     )
@@ -389,7 +386,7 @@ def resolve_selected_direction(
     else:
         raise DirectionSelectionError(f"unsupported selection mode: {mode}")
     option, normalized_option_name = _selected_option(selection, option_id)
-    _validate_no_blockers(data, option)
+    _validate_no_blockers(data)
     return SelectedDirection(
         mode=mode,
         task_key=expected_task_key,
@@ -435,28 +432,6 @@ def write_selected_direction_snapshot(
     return destination
 
 
-_PLAN_EXECUTION_FIELDS = (
-    "directionRealization",
-    "stageMap",
-    "stages",
-    "designPreparation",
-    "dependencyMigrationRisk",
-    "validationChecklist",
-    "rollbackStrategy",
-    "requirementCoverage",
-    "coverageSummary",
-    "variationPointAnalysis",
-    "planBodyVerification",
-    "stepwiseExecution",
-    "supersessionLedger",
-    "crossProjectDependencies",
-    "decisionDrafts",
-    "skippedAdrCandidates",
-    "incrementalDecision",
-    "userNarrative",
-)
-
-
 def load_selected_direction_snapshot(
     snapshot_path: Path,
 ) -> tuple[SelectedDirectionSnapshot | None, list[str]]:
@@ -521,341 +496,6 @@ def validate_selected_direction_ref(
     return failures
 
 
-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
-    ]
-
-
 # stage 를 게이트하는 검증 행이 implementation run 안에서 실행 가능함을 강제하는
 # 마커. 실측 실패값(dev-10341 VC-013/VC-014)에서 왔다: 수동 워크스루·배포 전제
 # 문구가 stageRefs 를 단 채 실리면, implementation run 은 배포 금지·자격증명
@@ -909,119 +549,3 @@ def stage_validation_executability_errors(
                 "or final-verification's user-owned external QA"
             )
     return failures
-
-
-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

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -958,7 +958,14 @@ def _required_resource_path_candidates(
         paths = (profiles / "_implementation-verifier.md",)
     else:
         return ()
-    return paths
+    from .phases.catalog import profile_sidecar
+
+    root = context.request.runtime_root.resolve()
+    return tuple(
+        profile_sidecar(root, str(path.relative_to(root)))
+        if path.is_relative_to(root) else path
+        for path in paths
+    )
 
 
 def _executor_profile_path(context: _MaterializationContext) -> Path:

package/runtime/python/okstra_ctl/next_phase.py

@@ -283,8 +283,8 @@ def _direction_selection_reason(selection: Mapping[str, Any]) -> str:
     # (`implementation_direction.py` `_comparison_selection`). 종전 문장은
     # "위저드에 후보가 선택지로 나온다" 고 해서 사이드카 없이 계획을 열게 했다.
     return (
-        f"{head} 고르는 자리는 이 리포트의 HTML 열람본입니다 — 방향 선택 칸에서 "
-        "후보를 고르고 Export 한 파일을 "
+        f"{head} `/okstra-user-response` 에서 이 리포트를 골라 채팅으로 고르거나, "
+        "이 리포트의 HTML 열람본 방향 선택 칸에서 고르고 Export 한 파일을 "
         "`runs/implementation-option-selection/user-responses/"
         "user-response-implementation-option-selection-<이 리포트 번호>.md` 로 "
         "저장하세요. 그다음 `/okstra-run` 으로 `implementation-planning` 을 "