okstra 0.121.1 → 0.123.0

package/runtime/validators/validate-run.py

@@ -45,6 +45,18 @@ from okstra_ctl.md_table import (  # noqa: E402
     split_pipe_row as _split_pipe_row,
 )
 from okstra_ctl.final_report_paths import final_report_data_path as _data_path_for  # noqa: E402
+from okstra_ctl.design_prep import (  # noqa: E402
+    DesignPrepError,
+    _planning_seq as _design_prep_planning_seq,
+    _render_request as _render_design_prep_request,
+    _report_language as _design_prep_report_language,
+)
+from okstra_ctl.design_surfaces import (  # noqa: E402
+    RULES as DESIGN_SURFACE_RULES,
+    DesignSurfaceError,
+    detect_design_surfaces,
+    expected_prep_plan_item_id,
+)
 
 TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
@@ -1530,7 +1542,12 @@ def _load_final_report_data(report_path: Path) -> dict:
         return {}
 
 
-def validate_final_report_data(report_path: Path, failures: list[str]) -> None:
+def validate_final_report_data(
+    report_path: Path,
+    failures: list[str],
+    *,
+    report_contracts: set[str] | None = None,
+) -> None:
     """Validate the final-report data.json against the v1.0 schema.
 
     The data.json is the source-of-truth that the renderer reads to
@@ -1584,13 +1601,29 @@ def validate_final_report_data(report_path: Path, failures: list[str]) -> None:
     if task_type == "final-verification":
         _validate_final_verification_consistency(data, failures)
     elif task_type == "implementation-planning":
+        active_report_contracts = report_contracts or set()
+        enforce_design_prep = _DESIGN_PREP_CONTRACT in active_report_contracts
         _validate_implementation_planning_cross_project(data, failures)
         _validate_implementation_planning_decision_drafts(data, failures)
         _validate_plan_body_gate_recompute(data, failures)
-        _validate_plan_item_extraction_completeness(data, failures)
+        _validate_plan_item_extraction_completeness(
+            data,
+            failures,
+            enforce_design_prep=enforce_design_prep,
+        )
         _validate_plan_item_subject_substance(data, failures)
         _validate_plan_body_clarification_matching(data, failures)
+        _validate_disagree_has_fixability(data, failures)
+        _validate_self_fix_before_clarification(data, failures)
         _validate_requirement_coverage_covered_by(data, failures)
+        warnings = _validate_design_prep_contract(
+            data,
+            report_path,
+            active_report_contracts,
+            failures,
+        )
+        for warning in warnings:
+            print(f"validate-run: warning: {warning}", file=sys.stderr)
 
 
 # path:line (foo.service.ts:268), an in-report ID (C-001 / E-006 / P-004), a
@@ -1865,7 +1898,12 @@ _PLAN_ITEM_SOURCES = (
 )
 
 
-def _validate_plan_item_extraction_completeness(data: dict, failures: list[str]) -> None:
+def _validate_plan_item_extraction_completeness(
+    data: dict,
+    failures: list[str],
+    *,
+    enforce_design_prep: bool = False,
+) -> None:
     """H2 — when a verification round ran, every plan-body deliverable item must
     appear as a matching `P-*` verdict item. Closes the omission hole where the
     lead silently drops a weak item (e.g. an out-of-order rollback) from
@@ -1901,6 +1939,384 @@ def _validate_plan_item_extraction_completeness(data: dict, failures: list[str])
                 "extracted for cross-verification — a dropped item escapes the "
                 "gate (plan-body-verification.md Plan-item extraction)."
             )
+    if enforce_design_prep:
+        _validate_expected_prep_plan_items(ip, extracted_ids, failures)
+
+
+def _validate_expected_prep_plan_items(
+    planning: dict,
+    extracted_ids: list[str],
+    failures: list[str],
+) -> None:
+    try:
+        expected_prep_ids = {}
+        for trigger in detect_design_surfaces(planning):
+            item_id = expected_prep_plan_item_id(trigger.stage, trigger.kind)
+            expected_prep_ids[item_id.upper()] = item_id
+    except DesignSurfaceError as exc:
+        failures.append(
+            f"final-report data.json: design-surface detection failed: {exc}"
+        )
+        return
+    except Exception as exc:  # noqa: BLE001
+        failures.append(
+            "final-report data.json: design-surface detection failed on "
+            f"malformed input: {exc}"
+        )
+        return
+    actual_prep_ids = [
+        item_id for item_id in extracted_ids if item_id.startswith("P-PREP-")
+    ]
+    missing_prep_ids = [
+        expected_prep_ids[item_id]
+        for item_id in sorted(set(expected_prep_ids) - set(actual_prep_ids))
+    ]
+    if missing_prep_ids:
+        failures.append(
+            "final-report data.json: planBodyVerification.planItems is missing "
+            "detector-required design-prep verdict item(s): "
+            + ", ".join(missing_prep_ids)
+        )
+    unexpected_prep_ids = sorted(set(actual_prep_ids) - set(expected_prep_ids))
+    if unexpected_prep_ids:
+        failures.append(
+            "final-report data.json: planBodyVerification.planItems contains "
+            "unexpected design-prep verdict item(s) not produced by the "
+            "detector: "
+            + ", ".join(unexpected_prep_ids)
+        )
+    duplicate_prep_ids = sorted(
+        item_id
+        for item_id in set(actual_prep_ids)
+        if actual_prep_ids.count(item_id) > 1
+    )
+    if duplicate_prep_ids:
+        failures.append(
+            "final-report data.json: planBodyVerification.planItems contains "
+            "duplicate detector-required design-prep verdict item(s): "
+            + ", ".join(duplicate_prep_ids)
+        )
+
+
+_DESIGN_PREP_CONTRACT = "implementation-design-prep-v1"
+_DESIGN_PREP_REQUEST_STATUSES = {"provisional", "blocked"}
+_DESIGN_PREP_TERMINAL_STATUSES = {"ready", "not-applicable"}
+
+
+def _normalize_report_contracts(raw_contracts: object) -> set[str]:
+    if isinstance(raw_contracts, str):
+        candidates = [raw_contracts]
+    elif isinstance(raw_contracts, (list, tuple, set, frozenset)):
+        candidates = raw_contracts
+    else:
+        return set()
+    return {
+        value.strip()
+        for value in candidates
+        if isinstance(value, str) and value.strip()
+    }
+
+
+def _design_prep_rows(
+    planning: dict,
+    failures: list[str],
+) -> tuple[list[dict], dict[str, dict]] | None:
+    preparation = planning.get("designPreparation")
+    if not isinstance(preparation, dict):
+        failures.append(
+            "final-report data.json: implementationPlanning.designPreparation "
+            "is malformed; expected an object"
+        )
+        return None
+    raw_items = preparation.get("items")
+    if not isinstance(raw_items, list) or any(
+        not isinstance(item, dict) for item in raw_items
+    ):
+        failures.append(
+            "final-report data.json: implementationPlanning.designPreparation.items "
+            "is malformed; expected an array of objects"
+        )
+        return None
+    items = list(raw_items)
+    items_by_id: dict[str, dict] = {}
+    for item in items:
+        item_id = item.get("id")
+        if not isinstance(item_id, str) or not item_id:
+            failures.append(
+                "final-report data.json: designPreparation item has malformed id"
+            )
+            continue
+        if item_id in items_by_id:
+            failures.append(
+                f"final-report data.json: duplicate designPreparation item {item_id}"
+            )
+        items_by_id[item_id] = item
+    return items, items_by_id
+
+
+def _design_surface_coverage(
+    planning: dict,
+    failures: list[str],
+) -> dict[tuple[int, str], list[dict]] | None:
+    raw_stages = planning.get("stages")
+    if not isinstance(raw_stages, list):
+        failures.append(
+            "final-report data.json: implementationPlanning.stages is malformed"
+        )
+        return None
+    coverage_by_key: dict[tuple[int, str], list[dict]] = {}
+    for stage in raw_stages:
+        if not isinstance(stage, dict) or not isinstance(stage.get("stage"), int):
+            failures.append("final-report data.json: planning stage is malformed")
+            continue
+        rows = stage.get("designSurfaceCoverage", [])
+        if not isinstance(rows, list):
+            failures.append(
+                f"final-report data.json: Stage {stage['stage']} "
+                "designSurfaceCoverage is malformed"
+            )
+            continue
+        for row in rows:
+            if not isinstance(row, dict) or not isinstance(row.get("kind"), str):
+                failures.append(
+                    f"final-report data.json: Stage {stage['stage']} has malformed "
+                    "designSurfaceCoverage row"
+                )
+                continue
+            key = (stage["stage"], row["kind"])
+            coverage_by_key.setdefault(key, []).append(row)
+    return coverage_by_key
+
+
+def _trigger_evidence_identity(raw_evidence: object) -> set[tuple[object, object, object]]:
+    if not isinstance(raw_evidence, (list, tuple)):
+        return set()
+    return {
+        (row.get("step"), row.get("field"), row.get("match"))
+        for row in raw_evidence
+        if isinstance(row, dict)
+    }
+
+
+def _validate_detector_coverage(
+    planning: dict,
+    coverage_by_key: dict[tuple[int, str], list[dict]],
+    failures: list[str],
+) -> None:
+    triggers = detect_design_surfaces(planning)
+    expected_by_key = {(trigger.stage, trigger.kind): trigger for trigger in triggers}
+    detector_kinds = {rule.kind for rule in DESIGN_SURFACE_RULES}
+    for key, trigger in expected_by_key.items():
+        stage, kind = key
+        if kind == "manual-user-test":
+            failures.append(
+                "final-report data.json: detector must not generate "
+                f"manual-user-test for Stage {stage}"
+            )
+            continue
+        rows = coverage_by_key.get(key, [])
+        if len(rows) != 1:
+            failures.append(
+                f"final-report data.json: detector trigger Stage {stage} kind "
+                f"{kind} requires exactly one designSurfaceCoverage row; "
+                f"found {len(rows)}"
+            )
+            continue
+        expected_evidence = {
+            (evidence.step, evidence.field, evidence.match)
+            for evidence in trigger.evidence
+        }
+        actual_evidence = _trigger_evidence_identity(rows[0].get("triggerEvidence"))
+        if actual_evidence != expected_evidence:
+            failures.append(
+                f"final-report data.json: Stage {stage} {kind} triggerEvidence "
+                "does not match detector output"
+            )
+    for stage, kind in coverage_by_key:
+        if kind in detector_kinds and (stage, kind) not in expected_by_key:
+            failures.append(
+                f"final-report data.json: Stage {stage} {kind} coverage has no "
+                "matching detector trigger"
+            )
+
+
+def _coverage_prep_ids(row: dict) -> list[str]:
+    if isinstance(row.get("prepItemId"), str):
+        return [row["prepItemId"]]
+    raw_ids = row.get("prepItemIds")
+    if isinstance(raw_ids, list):
+        return [item_id for item_id in raw_ids if isinstance(item_id, str)]
+    return []
+
+
+def _validate_prep_references(
+    items: list[dict],
+    items_by_id: dict[str, dict],
+    coverage_by_key: dict[tuple[int, str], list[dict]],
+    failures: list[str],
+) -> None:
+    referenced: set[tuple[str, int, str]] = set()
+    for (stage, kind), rows in coverage_by_key.items():
+        for row in rows:
+            if row.get("disposition") != "prep-item":
+                continue
+            for item_id in _coverage_prep_ids(row):
+                item = items_by_id.get(item_id)
+                if item is None:
+                    failures.append(
+                        f"final-report data.json: coverage references missing {item_id}"
+                    )
+                    continue
+                if stage not in (item.get("stageRefs") or []):
+                    failures.append(
+                        f"final-report data.json: {item_id}.stageRefs does not "
+                        f"include coverage Stage {stage}"
+                    )
+                if item.get("kind") != kind:
+                    failures.append(
+                        f"final-report data.json: {item_id}.kind does not match "
+                        f"coverage kind {kind}"
+                    )
+                referenced.add((item_id, stage, kind))
+    for item in items:
+        item_id = item.get("id")
+        kind = item.get("kind")
+        stage_refs = item.get("stageRefs")
+        if not isinstance(item_id, str) or not isinstance(kind, str):
+            continue
+        if not isinstance(stage_refs, list):
+            failures.append(
+                f"final-report data.json: {item_id}.stageRefs is malformed"
+            )
+            continue
+        for stage in stage_refs:
+            if (item_id, stage, kind) not in referenced:
+                failures.append(
+                    f"final-report data.json: {item_id} Stage {stage} kind {kind} "
+                    "has no matching prep-item coverage reference"
+                )
+
+
+def _validate_design_prep_states(items: list[dict], failures: list[str]) -> None:
+    for item in items:
+        item_id = str(item.get("id") or "<missing>")
+        stage_refs = item.get("stageRefs") or []
+        review_at = item.get("reviewAt")
+        if isinstance(review_at, dict) and "stage" in review_at:
+            if review_at.get("stage") not in stage_refs:
+                failures.append(
+                    f"final-report data.json: {item_id}.reviewAt.stage must belong "
+                    "to stageRefs"
+                )
+        status = item.get("status")
+        if status == "blocked" and (
+            not isinstance(item.get("humanConfirmation"), dict)
+            or item["humanConfirmation"].get("required") is not True
+        ):
+            failures.append(
+                f"final-report data.json: blocked {item_id} requires "
+                "humanConfirmation.required=true"
+            )
+        if status in _DESIGN_PREP_REQUEST_STATUSES and not isinstance(
+            item.get("requestPath"), str
+        ):
+            failures.append(
+                f"final-report data.json: {status} {item_id} requires requestPath"
+            )
+        if status in _DESIGN_PREP_TERMINAL_STATUSES and "requestPath" in item:
+            failures.append(
+                f"final-report data.json: terminal {item_id} must not carry requestPath"
+            )
+
+
+def _validate_design_prep_requests(
+    data: dict,
+    report_path: Path,
+    items: list[dict],
+    failures: list[str],
+) -> None:
+    data_path = _data_path_for(report_path)
+    planning_seq = _design_prep_planning_seq(data_path)
+    report_language = _design_prep_report_language(data)
+    for item in items:
+        if item.get("status") not in _DESIGN_PREP_REQUEST_STATUSES:
+            continue
+        item_id = str(item.get("id") or "<missing>")
+        target, expected = _render_design_prep_request(
+            data_path=data_path,
+            planning_seq=planning_seq,
+            report_language=report_language,
+            item=item,
+        )
+        if not target.is_file():
+            failures.append(
+                f"final-report data.json: design-prep request is missing for {item_id}: "
+                f"{target}"
+            )
+            continue
+        try:
+            actual = target.read_bytes()
+        except OSError as exc:
+            failures.append(
+                f"final-report data.json: cannot read design-prep request for "
+                f"{item_id}: {exc}"
+            )
+            continue
+        if actual != expected:
+            failures.append(
+                f"final-report data.json: design-prep request content or "
+                f"fingerprint is stale for {item_id}: {target}"
+            )
+
+
+def _validate_design_prep_contract(
+    data: dict,
+    report_path: Path | None,
+    report_contracts: set[str],
+    failures: list[str],
+) -> list[str]:
+    warnings: list[str] = []
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        if _DESIGN_PREP_CONTRACT in report_contracts:
+            failures.append(
+                "final-report data.json: implementationPlanning is malformed"
+            )
+        return warnings
+    preparation = planning.get("designPreparation")
+    if not isinstance(preparation, dict):
+        if _DESIGN_PREP_CONTRACT in report_contracts:
+            failures.append(
+                "final-report data.json: marker implementation-design-prep-v1 "
+                "requires implementationPlanning.designPreparation"
+            )
+        else:
+            warnings.append("legacy-unassessed")
+        return warnings
+    if _DESIGN_PREP_CONTRACT not in report_contracts:
+        return warnings
+    try:
+        parsed = _design_prep_rows(planning, failures)
+        coverage_by_key = _design_surface_coverage(planning, failures)
+        if parsed is None or coverage_by_key is None:
+            return warnings
+        items, items_by_id = parsed
+        _validate_detector_coverage(planning, coverage_by_key, failures)
+        _validate_prep_references(items, items_by_id, coverage_by_key, failures)
+        _validate_design_prep_states(items, failures)
+        if report_path is not None:
+            _validate_design_prep_requests(data, report_path, items, failures)
+    except (DesignSurfaceError, DesignPrepError, KeyError, TypeError, ValueError) as exc:
+        failures.append(
+            "final-report data.json: design-preparation contract is malformed: "
+            f"{exc}"
+        )
+    except Exception as exc:  # noqa: BLE001
+        failures.append(
+            "final-report data.json: design-preparation validation failed closed "
+            f"on malformed input: {exc}"
+        )
+    return warnings
 
 
 # A `subject` this short or shaped like a bare `P-Opt-1` id is a placeholder,
@@ -1986,6 +2402,93 @@ def _validate_plan_body_clarification_matching(data: dict, failures: list[str])
             )
 
 
+def _validate_self_fix_before_clarification(data: dict, failures: list[str]) -> None:
+    """A planner-fixable defect MUST pass through a self-fix round before it is
+    promoted to a `## 1. Clarification Items` row. Closes the hole where the
+    lead dumps a fixable plan defect (abbreviated path, prose command,
+    placeholder, coverage remap) onto the user instead of having report-writer
+    correct it (plan-body-verification.md "Self-fix round").
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    pbv = ip.get("planBodyVerification")
+    if not isinstance(pbv, dict):
+        return
+    round_count = pbv.get("roundCount")
+    if not isinstance(round_count, int) or round_count < 1:
+        return
+    if pbv.get("selfFixRoundApplied") is True:
+        return
+    for item in pbv.get("planItems") or []:
+        if not isinstance(item, dict):
+            continue
+        if _classify_plan_item_gate(item) != "majority-disagree":
+            continue
+        disagrees = [
+            v for v in (item.get("verdicts") or [])
+            if isinstance(v, dict) and str(v.get("verdict") or "").upper() == "DISAGREE"
+        ]
+        fixable = [v for v in disagrees if v.get("fixability") == "planner-fixable"]
+        if disagrees and len(fixable) * 2 > len(disagrees):
+            failures.append(
+                "final-report data.json: plan item "
+                f"`{item.get('id') or '<unknown>'}` is majority-disagree with a "
+                "planner-fixable majority but `selfFixRoundApplied` is not true. A "
+                "planner-fixable defect MUST be corrected by a report-writer self-fix "
+                "round before it becomes a clarification row "
+                "(plan-body-verification.md Self-fix round)."
+            )
+
+
+# Allowed `fixability` values, mirroring the schema enum
+# (schemas/final-report-v1.0.schema.json planItems[].verdicts[].fixability).
+_FIXABILITY_VALUES = frozenset({"planner-fixable", "needs-user-input"})
+
+
+def _validate_disagree_has_fixability(data: dict, failures: list[str]) -> None:
+    """Every `DISAGREE` verdict MUST carry a valid `fixability`
+    (`planner-fixable` / `needs-user-input`). The schema enum only constrains a
+    *present* value; it does not require the field, so a DISAGREE with a missing
+    or mislabelled fixability is schema-valid. That silently degrades
+    `_validate_self_fix_before_clarification`, which counts a non-`planner-fixable`
+    DISAGREE as non-fixable and thus lets a genuinely planner-fixable defect
+    skip the self-fix round and land on the user. This is the enforcement point
+    for the "fixability is DISAGREE-only 필수" MUST in plan-body-verification.md.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    pbv = ip.get("planBodyVerification")
+    if not isinstance(pbv, dict):
+        return
+    round_count = pbv.get("roundCount")
+    if not isinstance(round_count, int) or round_count < 1:
+        return
+    for item in pbv.get("planItems") or []:
+        if not isinstance(item, dict):
+            continue
+        item_id = item.get("id") or "<unknown>"
+        for verdict in item.get("verdicts") or []:
+            if not isinstance(verdict, dict):
+                continue
+            if str(verdict.get("verdict") or "").upper() != "DISAGREE":
+                continue
+            fixability = verdict.get("fixability")
+            if fixability not in _FIXABILITY_VALUES:
+                worker = verdict.get("worker") or "<worker>"
+                allowed = " / ".join(sorted(_FIXABILITY_VALUES))
+                failures.append(
+                    f"final-report data.json: plan item `{item_id}` has a "
+                    f"`DISAGREE` verdict from `{worker}` with "
+                    f"fixability `{fixability}` — a DISAGREE MUST declare a "
+                    f"fixability of {allowed}. A missing/invalid value is "
+                    "counted as non-fixable and lets a planner-fixable defect "
+                    "skip the self-fix round (plan-body-verification.md "
+                    "\"fixability (DISAGREE 전용, 필수)\")."
+                )
+
+
 _COVERED_BY_ANCHOR_RE = re.compile(r"option|stage|step", re.IGNORECASE)
 _COVERED_BY_STAGE_REF_RE = re.compile(r"stage\s*(\d+)", re.IGNORECASE)
 _COVERED_BY_VAGUE = {"recommended option", "the recommended option", "recommended"}
@@ -2838,7 +3341,14 @@ def main() -> int:
     # contain every required section. Substring checks below are a
     # safety net for hand-edited or pre-v1.0 reports.
     task_type = effective_run_task_type(run_manifest, task_manifest)
-    validate_final_report_data(report_path, failures)
+    report_contracts = _normalize_report_contracts(
+        run_manifest.get("reportContracts")
+    )
+    validate_final_report_data(
+        report_path,
+        failures,
+        report_contracts=report_contracts,
+    )
     _validate_fix_cycle(
         run_manifest, _load_final_report_data(report_path), failures
     )
@@ -2905,7 +3415,7 @@ def main() -> int:
     write_json(task_manifest_path, task_manifest)
 
     # Best-effort: regenerate discovery/task-catalog.json so downstream
-    # tools (okstra-schedule, FleetView listings, etc.) don't read a stale
+    # tools (okstra-schedule-gen, FleetView listings, etc.) don't read a stale
     # snapshot frozen at instruction-set generation time.
     catalog_ok, catalog_msg = _refresh_task_catalog(project_root, task_manifest)
     if catalog_ok:

package/runtime/validators/validate-schedule.py

@@ -1,13 +1,13 @@
 #!/usr/bin/env python3
 """
 Validate that an okstra schedule Markdown file conforms to the Section Contract
-defined in skills/okstra-schedule/SKILL.md.
+defined in skills/okstra-schedule-gen/SKILL.md.
 
 Usage:
     python3 validators/validate-schedule.py <path-to-schedule.md>
 
 Exits 0 if compliant, 1 with a list of violations otherwise. Intended to be
-called by the okstra-schedule skill (self-validation step) and by humans /
+called by the okstra-schedule-gen skill (self-validation step) and by humans /
 hooks before committing a schedule.
 """
 
@@ -442,9 +442,13 @@ def validate(path: Path) -> list[str]:
         block = text[block_start:block_end]
         heading_line = text[block_start : text.find("\n", block_start)].strip()
 
-        # Skip blocks marked as NEEDS-OKSTRA-RUN or PARSE-ERROR — these are
-        # intentionally partial.
-        if "[NEEDS-OKSTRA-RUN]" in block or "[PARSE-ERROR" in block:
+        # Skip blocks marked as NEEDS-OKSTRA-RUN, PARSE-ERROR, or NEEDS-PLANNING
+        # — these are intentionally partial.
+        if (
+            "[NEEDS-OKSTRA-RUN]" in block
+            or "[PARSE-ERROR" in block
+            or "[NEEDS-PLANNING]" in block
+        ):
             continue
 
         last_pos = -1
@@ -654,13 +658,13 @@ def main(argv: list[str]) -> int:
     path = Path(argv[1])
     violations = validate(path)
     if not violations:
-        print(f"OK: {path} conforms to okstra-schedule Section Contract")
+        print(f"OK: {path} conforms to okstra-schedule-gen Section Contract")
         return 0
     print(f"FAIL: {path}", file=sys.stderr)
     for v in violations:
         print(f"  - {v}", file=sys.stderr)
     print(
-        "\nFix per skills/okstra-schedule/SKILL.md "
+        "\nFix per skills/okstra-schedule-gen/SKILL.md "
         "(Section Contract).",
         file=sys.stderr,
     )