okstra 0.122.0 → 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,15 +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
@@ -1867,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
@@ -1903,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,
@@ -2927,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
     )
@@ -2994,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.
 """
 
@@ -658,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,
     )

package/src/cli-registry.mjs

@@ -187,6 +187,13 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Answer a task's open clarification questions in-session and write the response sidecar"],
   },
+  {
+    name: "design-prep",
+    module: "./commands/inspect/design-prep.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Review and record AI-prepared implementation design inputs"],
+  },
   {
     name: "rollup",
     module: "./commands/inspect/rollup.mjs",

package/src/commands/inspect/design-prep.mjs

@@ -0,0 +1,23 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra design-prep — review AI-prepared implementation design inputs
+
+Usage:
+  okstra design-prep list [--project-root <path>] [--report <path>]
+  okstra design-prep show --report <path> [--item PREP-001]
+  okstra design-prep write --report <path> --item PREP-001 \\
+    --decision <accept-draft|modify-draft|reject-draft|defer> \\
+    [--overrides <json-object>] [--notes <text>] --confirmed
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const { code } = await runPythonModule({
+    module: "okstra_ctl.design_prep",
+    args,
+  });
+  return code ?? 1;
+}

package/src/lib/skill-catalog.mjs

@@ -13,7 +13,7 @@ export const USER_SKILL_NAMES = Object.freeze([
   "okstra-inspect",
   "okstra-rollup",
   "okstra-usage",
-  "okstra-schedule",
+  "okstra-schedule-gen",
   "okstra-container-build",
   "okstra-graphify",
   "okstra-pr-gen",
@@ -33,6 +33,7 @@ export const OBSOLETE_SKILL_NAMES = Object.freeze([
   "okstra-coding-preflight",
   "okstra-container",
   "okstra-brief",
+  "okstra-schedule",
   // Pre-merge status/history/logs/report/time skills, since folded into
   // okstra-inspect. Absent here, upgrades left them stranded in agent skill
   // homes and their pre-.okstra-migration bodies kept triggering.