okstra 0.154.2 → 0.156.0

package/runtime/validators/validate-run.py

@@ -109,6 +109,9 @@ from okstra_ctl.convergence_engine import (  # noqa: E402
     grouped_input_digest,
     validate_final_state,
 )
+from okstra_ctl.convergence_provenance import (  # noqa: E402
+    run_dir_provenance_errors,
+)
 
 TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
@@ -3241,17 +3244,7 @@ def validate_final_report_data(
         active_report_contracts = report_contracts or set()
         _validate_implementation_planning_cross_project(data, failures)
         _validate_implementation_planning_decision_drafts(data, failures)
-        _validate_plan_body_gate_recompute(data, failures)
-        _validate_gate_blocked_by(data, failures)
-        _validate_participating_analysers(data, failures)
-        _validate_self_fix_rewrite_scope(data, failures)
-        for warning in _detect_self_fix_recurrence(
-            (data.get("implementationPlanning") or {}).get("planBodyVerification") or {}
-        ):
-            print(f"validate-run: warning: {warning}", file=sys.stderr)
-        for warning in _detect_uniform_verifier(
-            (data.get("implementationPlanning") or {}).get("planBodyVerification") or {}
-        ):
+        for warning in validate_plan_body_section(data, report_path, failures):
             print(f"validate-run: warning: {warning}", file=sys.stderr)
         for warning in _detect_unmapped_incremental_fallback(data, report_path):
             print(f"validate-run: warning: {warning}", file=sys.stderr)
@@ -3260,23 +3253,12 @@ def validate_final_report_data(
         ):
             print(f"validate-run: warning: {warning}", file=sys.stderr)
         _validate_supersession_ledger(data, failures)
-        _validate_self_fix_grouping(data, failures)
         _validate_clarification_evidence_note(data, failures)
-        _validate_plan_body_verdict_provenance(data, report_path, failures)
-        _validate_reverify_result_addresses_prior_dissent(data, report_path, failures)
-        _validate_aborted_gate_has_clarification(data, failures)
-        _validate_round_recorded_verdicts(data, failures)
-        _validate_verdicts_match_current_subjects(data, failures)
-        _validate_plan_item_extraction_completeness(data, failures)
         _validate_variation_point_analysis(
             (data.get("implementationPlanning") or {}).get("variationPointAnalysis"),
             resolve_architecture(_project_root_from_report(report_path)),
             failures,
         )
-        _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_deviations(data, failures)
         _validate_requirement_coverage_covered_by(data, failures)
         warnings = _validate_design_prep_contract(
@@ -5838,6 +5820,86 @@ def _validate_disagree_has_fixability(data: dict, failures: list[str]) -> None:
                 )
 
 
+def validate_plan_body_section(
+    data: dict,
+    report_path: Path,
+    failures: list[str],
+) -> list[str]:
+    """Run every §5.5.9 plan-body check and return the advisory warnings.
+
+    Grouped into one callable so the round protocol can run the same checks at
+    each round boundary that the full run validation runs at the end. Before
+    this seam existed the only way to reach them was a finished report plus all
+    four manifests, so a lead computing the gate by hand mid-loop had nothing to
+    check itself against until Phase 7 — and a whole self-fix budget could be
+    spent against a mis-scored gate.
+    """
+    pbv = (data.get("implementationPlanning") or {}).get("planBodyVerification") or {}
+    _validate_plan_body_gate_recompute(data, failures)
+    _validate_gate_blocked_by(data, failures)
+    _validate_participating_analysers(data, failures)
+    _validate_self_fix_rewrite_scope(data, failures)
+    _validate_self_fix_grouping(data, failures)
+    _validate_plan_body_verdict_provenance(data, report_path, failures)
+    _validate_reverify_result_addresses_prior_dissent(data, report_path, failures)
+    _validate_aborted_gate_has_clarification(data, failures)
+    _validate_round_recorded_verdicts(data, failures)
+    _validate_verdicts_match_current_subjects(data, failures)
+    _validate_plan_item_extraction_completeness(data, failures)
+    _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)
+    return [*_detect_self_fix_recurrence(pbv), *_detect_uniform_verifier(pbv)]
+
+
+def plan_body_gate_summary(data: dict) -> dict | None:
+    """The §5.5.9 gate as the round protocol's step 5 needs it — per-item
+    classification, the whole-gate value, and the `gateBlockedBy` causes, all
+    recomputed from `planItems[].verdicts`. Returns ``None`` when the report
+    carries no plan items to judge.
+
+    This is what a lead records instead of tallying the verdicts by hand: the
+    single-vote-blocking kinds, the advisory-only kinds and the P-Var / P-Rb
+    exemptions are one implementation here, not a rule to be re-derived per
+    round from the prompt's prose.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return None
+    pbv = ip.get("planBodyVerification")
+    if not isinstance(pbv, dict):
+        return None
+    recomputed = _recompute_plan_body_gate(pbv)
+    if recomputed is None:
+        return None
+    items = [
+        {
+            "id": item.get("id"),
+            "classification": "has-dissent"
+            if _is_dissent_downgraded(item, pbv)
+            else _classify_plan_item_gate(item),
+            "correctnessCritical": _is_correctness_critical(item),
+        }
+        for item in (pbv.get("planItems") or [])
+        if isinstance(item, dict)
+    ]
+    coverage_blockers = _independent_coverage_blockers(ip, pbv)
+    return {
+        "declared": pbv.get("gateResult"),
+        "recomputed": recomputed,
+        "declaredBlockedBy": sorted(
+            str(c) for c in (pbv.get("gateBlockedBy") or []) if isinstance(c, str)
+        ),
+        "blockedBy": sorted(_gate_blocking_causes(pbv, coverage_blockers)),
+        "coverageBlockers": coverage_blockers,
+        "blockingItems": [
+            item["id"] for item in items if item["classification"] == "majority-disagree"
+        ],
+        "items": items,
+    }
+
+
 _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"}
@@ -6809,146 +6871,16 @@ def _nonempty_string(value) -> bool:
 # Round-0 grouping filename: `convergence-groups-<task-type>-<seq>.json`. The
 # `<task-type>-<seq>` suffix is shared verbatim with the worker-result and
 # working-state basenames, so capture it as one token to reconstruct both.
-_CONVERGENCE_GROUPS_BASENAME_RE = re.compile(
-    r"^convergence-groups-(?P<suffix>[a-z][a-z-]*?-\d{3})\.json$"
-)
-
-
-def _convergence_group_claims(document) -> list[tuple[str, str, str]] | None:
-    """Extract `(findingId, worker, itemId)` provenance claims from a grouping.
-
-    Returns ``None`` when the document does not match the convergence-groups
-    schema shape closely enough to read its provenance fields safely — the
-    caller refuses to judge such a file. Otherwise returns the deduplicated
-    claims drawn from every group's ``sourceItems[]`` and ``discoveredBy`` map.
-    """
-    if not isinstance(document, dict) or not isinstance(document.get("groups"), list):
-        return None
-    claims: list[tuple[str, str, str]] = []
-    seen: set[tuple[str, str, str]] = set()
-    for group in document["groups"]:
-        if not isinstance(group, dict):
-            return None
-        finding_id = group.get("findingId")
-        source_items = group.get("sourceItems")
-        discovered_by = group.get("discoveredBy")
-        if (
-            not _nonempty_string(finding_id)
-            or not isinstance(source_items, list)
-            or not isinstance(discovered_by, dict)
-        ):
-            return None
-        pairs: list[tuple[object, object]] = []
-        for item in source_items:
-            if not isinstance(item, dict):
-                return None
-            pairs.append((item.get("worker"), item.get("itemId")))
-        for worker, discovery in discovered_by.items():
-            if not isinstance(discovery, dict):
-                return None
-            pairs.append((worker, discovery.get("itemId")))
-        for worker, item_id in pairs:
-            if not _nonempty_string(worker) or not _nonempty_string(item_id):
-                return None
-            claim = (finding_id, worker, item_id)
-            if claim not in seen:
-                seen.add(claim)
-                claims.append(claim)
-    return claims
-
-
-def _convergence_groups_digest_ok(state_dir, suffix: str, document: dict) -> bool:
-    """False only when a recorded groupsDigest exists and no longer matches.
-
-    ``okstra convergence seed`` pins ``grouped_input_digest`` of the grouping
-    into the working state. When that record is present and disagrees with the
-    on-disk grouping, the file was tampered with or written out of band — not
-    evidence of fabrication — so the caller refuses to judge it. A missing
-    working state or missing digest means judge the file as parsed.
-    """
-    work_path = state_dir / f"convergence-work-{suffix}.json"
-    try:
-        work = json.loads(work_path.read_text(encoding="utf-8"))
-    except (OSError, ValueError):
-        return True
-    recorded = work.get("groupsDigest") if isinstance(work, dict) else None
-    if not _nonempty_string(recorded):
-        return True
-    return grouped_input_digest(document) == recorded
-
-
-def _read_canonical_worker_result(worker_results_dir, worker: str, suffix: str):
-    """Return the `<worker>-<suffix>.md` text, or ``None`` when it is not a
-    resolvable file directly inside ``worker-results/`` (missing, unreadable,
-    or a worker slug that is not a single path component)."""
-    candidate = worker_results_dir / f"{worker}-{suffix}.md"
-    try:
-        if candidate.resolve().parent != worker_results_dir.resolve():
-            return None
-        return candidate.read_text(encoding="utf-8")
-    except (OSError, ValueError):
-        return None
-
-
-def _id_occurs_wordbounded(text: str, item_id: str) -> bool:
-    """True when `item_id` occurs as a literal not flanked by another
-    identifier char, so `F-7` matches neither `F-70` nor `xF-7`."""
-    pattern = r"(?<![0-9A-Za-z_-])" + re.escape(item_id) + r"(?![0-9A-Za-z_-])"
-    return re.search(pattern, text) is not None
-
-
 def _validate_convergence_group_provenance(run_dir, failures) -> None:
     """Every source item a round-0 grouping cites must exist in the worker file.
 
-    The lead mints its own finding IDs, but each ``sourceItems[].itemId`` and
-    ``discoveredBy.<worker>.itemId`` is copied verbatim from a worker's own
-    result. A grouping that cites ``codex-worker:F-007`` when codex never wrote
-    F-007 is a fabricated provenance link the final report cannot expose. This
-    replays that one claim: the cited item ID must occur, word-boundary
-    anchored, in the worker's canonical result file.
-
-    A validator failure blocks user approval, so unjudgeable input is skipped
-    silently: no groups file, unreadable/malformed JSON, a groups file that
-    fails the schema shape, a missing worker result file (provider-unavailable
-    substitution is legitimate), or a recorded groupsDigest that no longer
-    matches.
+    Shared with `okstra convergence seed`, which runs the same check when the
+    grouping is handed over — this pass re-runs it over the finished run so a
+    grouping written out of band is still caught. A validator failure blocks
+    user approval, so unjudgeable input is skipped silently
+    (`okstra_ctl.convergence_provenance.run_dir_provenance_errors`).
     """
-    from pathlib import Path as _Path
-
-    state_dir = _Path(run_dir) / "state"
-    worker_results_dir = _Path(run_dir) / "worker-results"
-    if not state_dir.is_dir() or not worker_results_dir.is_dir():
-        return
-    for groups_path in sorted(state_dir.glob("convergence-groups-*.json")):
-        match = _CONVERGENCE_GROUPS_BASENAME_RE.match(groups_path.name)
-        if match is None:
-            continue
-        suffix = match.group("suffix")
-        try:
-            document = json.loads(groups_path.read_text(encoding="utf-8"))
-        except (OSError, ValueError):
-            continue
-        claims = _convergence_group_claims(document)
-        if claims is None:
-            continue
-        if not _convergence_groups_digest_ok(state_dir, suffix, document):
-            continue
-        contents: dict[str, str | None] = {}
-        for finding_id, worker, item_id in claims:
-            if worker not in contents:
-                contents[worker] = _read_canonical_worker_result(
-                    worker_results_dir, worker, suffix
-                )
-            text = contents[worker]
-            if text is None or _id_occurs_wordbounded(text, item_id):
-                continue
-            failures.append(
-                f"convergence groups `{groups_path.name}` group {finding_id} "
-                f"cites source item `{worker}:{item_id}`, but that ID does not "
-                f"occur in the worker's result file `{worker}-{suffix}.md` — a "
-                "grouping may not invent a provenance link to an item the "
-                "worker never reported."
-            )
+    failures.extend(run_dir_provenance_errors(Path(run_dir)))
 
 
 # Reverify-prompt basename: `<role-slug>-reverify-r<N>-<task-type>-<seq>.md`.
@@ -7371,13 +7303,92 @@ def _rerender_report_views_after_autofix(report_path: Path) -> str:
     return "report-views re-rendered"
 
 
+SECTION_FULL = "full"
+SECTION_PLAN_BODY = "plan-body"
+
+# `full` needs the whole run assembled; the round-boundary section reads only
+# the report and its data.json sibling, which is what exists mid-loop.
+_FULL_ONLY_REQUIRED_FLAGS = ("team_state", "run_manifest", "task_manifest")
+
+
+def run_plan_body_section(report_path: Path) -> int:
+    """`--section plan-body` — the §5.5.9 checks a self-fix round can run on
+    its own, plus the recomputed gate the lead records for that round.
+
+    Emits one JSON object on stdout so the caller reads the gate instead of
+    re-deriving it: exit 0 when the section is clean, 2 when it is not.
+    """
+    data_path = _data_path_for(report_path)
+    if not data_path.is_file():
+        print(
+            f"validate-run: --section plan-body needs {data_path}, which does "
+            "not exist yet — render the round's data.json first.",
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except ValueError as exc:
+        print(
+            f"validate-run: {data_path} is not parseable JSON ({exc}). "
+            "Restore it from the sibling `.data.json.last-valid` snapshot the "
+            "renderer writes after each successful render.",
+            file=sys.stderr,
+        )
+        return 2
+    failures = _data_schema_failures(data)
+    warnings = validate_plan_body_section(data, report_path, failures)
+    _validate_plan_body_state_file(data, report_path, failures)
+    payload = {
+        "ok": not failures,
+        "section": SECTION_PLAN_BODY,
+        "gate": plan_body_gate_summary(data),
+        "failures": failures,
+        "warnings": warnings,
+    }
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0 if not failures else 2
+
+
+def _data_schema_failures(data: dict) -> list[str]:
+    """Schema errors in the round's data.json, as failures.
+
+    The gate block is hand-edited between rounds, so a structure written in the
+    lead's own internal shape is schema-invalid while still being readable
+    JSON. Nothing caught that until the renderer ran, which is one round too
+    late — by then the previous verdicts have already been overwritten.
+    """
+    if schema_validate is None or load_schema_for_data is None:
+        return []
+    try:
+        schema = load_schema_for_data(data)
+    except SchemaError as exc:
+        return [f"final-report data.json: schema not locatable ({exc})"]
+    return [
+        f"final-report data.json: schema violation — {error}"
+        for error in schema_validate(data, schema)
+    ]
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(
         description="Validate okstra run contract artifacts."
     )
+    parser.add_argument(
+        "--section",
+        choices=(SECTION_FULL, SECTION_PLAN_BODY),
+        default=SECTION_FULL,
+        help=(
+            "Which contract surface to validate. `full` (default) validates the "
+            "finished run. `plan-body` validates only the §5.5.9 plan-body "
+            "verification surface from the report and its data.json, and prints "
+            "the recomputed gate — the round-boundary check a self-fix loop runs "
+            "before it records a round."
+        ),
+    )
     parser.add_argument(
         "--team-state",
-        required=True,
+        required=False,
         help="Project-relative or absolute path to the team state JSON.",
     )
     parser.add_argument(
@@ -7387,12 +7398,12 @@ def main() -> int:
     )
     parser.add_argument(
         "--run-manifest",
-        required=True,
+        required=False,
         help="Project-relative or absolute path to the run manifest JSON.",
     )
     parser.add_argument(
         "--task-manifest",
-        required=True,
+        required=False,
         help="Project-relative or absolute path to the task manifest JSON.",
     )
     parser.add_argument(
@@ -7409,6 +7420,19 @@ def main() -> int:
     )
     args = parser.parse_args()
 
+    if args.section == SECTION_PLAN_BODY:
+        return run_plan_body_section(Path(args.report).resolve())
+
+    missing = [
+        f"--{flag.replace('_', '-')}"
+        for flag in _FULL_ONLY_REQUIRED_FLAGS
+        if not getattr(args, flag)
+    ]
+    if missing:
+        parser.error(
+            f"--section {SECTION_FULL} requires {', '.join(missing)}"
+        )
+
     run_manifest_path = Path(args.run_manifest).resolve()
     run_manifest = load_json(run_manifest_path)
     task_manifest_path = Path(args.task_manifest).resolve()

package/runtime/validators/validate_session_conformance.py

@@ -385,6 +385,26 @@ def _convergence_rounds_ran(run_dir: Path, suffix: str | None) -> bool:
     return isinstance(doc, dict) and (doc.get("totalRounds") or 0) >= 1
 
 
+def _plan_body_rounds_ran(run_dir: Path, suffix: str | None) -> int:
+    """이 run 의 plan-body 검증이 실제로 돈 라운드 수.
+
+    각 라운드는 새 워커 배치를 띄우므로 라운드마다 배치 경계가 하나씩 생긴다.
+    Phase 6 이후에 도는 구간이라 기존 배치-정리 강제(수렴 라운드 1 직전 /
+    report-writer 디스패치 직전)의 바깥이었고, 그래서 self-fix 를 여러 라운드
+    돈 run 은 매 라운드의 완료 워커가 그대로 남았다."""
+    if not suffix:
+        return 0
+    path = run_dir / "state" / f"plan-body-verification-{suffix}.json"
+    try:
+        doc = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return 0
+    if not isinstance(doc, dict):
+        return 0
+    rounds = doc.get("roundCount")
+    return rounds if isinstance(rounds, int) and rounds > 0 else 0
+
+
 def _phase_mentions_worker(lines: list[tuple[str, str]], needles: list[str]) -> bool:
     return any(needle in _norm(line) for _ts, line in lines for needle in needles)
 
@@ -449,6 +469,40 @@ def _check_batch_cleanup_checkpoints(
             )
 
 
+def _check_plan_verify_cleanup_checkpoints(
+    by_phase: dict[str, list[tuple[str, str]]],
+    plan_body_rounds: int,
+    errors: list[str],
+) -> None:
+    """plan-body 라운드도 배치 경계다 — 라운드마다 새 검증 워커를 띄운다.
+
+    Phase 6 뒤에 도는 구간이라 위 두 지점의 바깥이었고, self-fix 를 다섯 라운드
+    돈 run 은 라운드마다 완료 워커를 남겨 유휴 세션이 쌓였다. 라운드 2 이상은
+    직전 라운드의 워커가 반드시 존재하므로, 각 라운드 직전에 정리가 있어야
+    한다(라운드 1의 앞 경계는 report-writer 디스패치 정리가 이미 덮는다)."""
+    if plan_body_rounds < 2:
+        return
+    detail = "prompts/lead/plan-body-verification.md §\"Round protocol\" step 7"
+    round_ts = sorted(ts for ts, _line in by_phase.get("phase-5.5.9-plan-verify", []))
+    if not round_ts:
+        errors.append(
+            "PROGRESS checkpoint missing: `phase-5.5.9-plan-verify` — the state "
+            f"file records {plan_body_rounds} plan-body rounds, each of which "
+            f"dispatches a worker batch and must announce itself ({detail})."
+        )
+        return
+    cleanup_ts = sorted(ts for ts, _line in by_phase.get("phase-batch-cleanup", []))
+    for index, dispatched_at in enumerate(round_ts[1:], start=1):
+        previous = round_ts[index - 1]
+        if not any(previous <= ts <= dispatched_at for ts in cleanup_ts):
+            errors.append(
+                "PROGRESS checkpoint missing: no `phase-batch-cleanup` line "
+                f"between plan-body rounds ({previous} → {dispatched_at}) — the "
+                f"previous round's completed verifiers must be cleared before "
+                f"the next round dispatches ({detail})."
+            )
+
+
 def _check_progress_checkpoints(
     evidence: _LeadEvidence,
     team_state: dict,
@@ -513,6 +567,9 @@ def _check_progress_checkpoints(
     _check_batch_cleanup_checkpoints(
         by_phase, convergence_ran, report_writer_dispatched, errors
     )
+    _check_plan_verify_cleanup_checkpoints(
+        by_phase, _plan_body_rounds_ran(run_dir, suffix), errors
+    )
 
 
 def _parse_iso(ts: str) -> datetime | None:

package/src/cli-registry.mjs

@@ -80,6 +80,13 @@ export const COMMAND_REGISTRY = [
     category: "admin",
     summary: ["Extract and validate deterministic plan-body items"],
   },
+  {
+    name: "plan-verify",
+    module: "./commands/execute/plan-verify.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Score the §5.5.9 plan-body gate for one self-fix round"],
+  },
   {
     name: "git-reconcile",
     module: "./commands/execute/git-reconcile.mjs",

package/src/commands/execute/plan-verify.mjs

@@ -0,0 +1,44 @@
+import { runInstalledValidator } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra plan-verify — score the §5.5.9 plan-body gate for one self-fix round
+
+Usage:
+  okstra plan-verify --report <final-report-implementation-planning-<seq>.md>
+
+Recomputes the gate from the report data.json's \`planItems[].verdicts\` and runs
+every plan-body contract check that a round can be judged on its own — verdict
+provenance, fixability, subject substance, self-fix grouping, round recording,
+clarification matching, and the state-file round history.
+
+Emits one JSON object:
+
+  gate.recomputed      the gate value this round's votes actually support
+  gate.blockedBy       the \`gateBlockedBy\` causes, recomputed
+  gate.blockingItems   the plan items classified \`majority-disagree\`
+  gate.items[]         per-item classification
+  failures[]           contract violations — exit code 2 when non-empty
+  warnings[]           advisory signals (self-fix recurrence, uniform verifier)
+
+Run this at every round boundary and record what it returns. The single-vote
+blocking kinds, the advisory-only kinds and the P-Var / P-Rb exemptions live in
+this one implementation — a lead that tallies the verdicts by hand instead is
+re-deriving them per round, and a round scored wrong spends its self-fix budget
+on the wrong items.
+`;
+
+export async function run(args) {
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return args.length === 0 ? 2 : 0;
+  }
+  if (args.includes("--section")) {
+    process.stderr.write(
+      "error: --section is set by 'okstra plan-verify' itself — remove it from your args\n",
+    );
+    return 2;
+  }
+  return await runInstalledValidator({
+    validatorName: "validate-run.py",
+    args: ["--section", "plan-body", ...args],
+  });
+}

package/src/lib/python-helper.mjs

@@ -15,6 +15,30 @@ export function resolveInstalledScript(paths, scriptName) {
   return existsSync(dev) ? dev : null;
 }
 
+export function resolveInstalledValidator(paths, validatorName) {
+  // `okstra install` lands the validators tree at ~/.okstra/lib/validators;
+  // a checkout that has not been installed still has the in-repo source.
+  const installed = join(paths.home, "lib", "validators", validatorName);
+  if (existsSync(installed)) return installed;
+  const repoRoot = fileURLToPath(new URL("../..", import.meta.url));
+  const dev = resolvePath(repoRoot, "validators", validatorName);
+  return existsSync(dev) ? dev : null;
+}
+
+async function spawnPythonEntry(entry, args, paths) {
+  return await new Promise((resolve) => {
+    const child = spawn("python3", [entry, ...args], {
+      stdio: "inherit",
+      env: { ...process.env, PYTHONPATH: buildPythonpath(paths) },
+    });
+    child.on("error", (err) => {
+      process.stderr.write(`error: failed to spawn python3: ${err.message}\n`);
+      resolve(1);
+    });
+    child.on("close", (code) => resolve(typeof code === "number" ? code : 1));
+  });
+}
+
 // Thin spawn shim shared by every `okstra <cmd>` subcommand that fronts a
 // `scripts/okstra-*.py` entry point. Centralizing it keeps PYTHONPATH wiring
 // and installed/dev resolution in one place so skills call `okstra <cmd>`
@@ -40,17 +64,19 @@ export async function runInstalledScript({ scriptName, args, usage, emptyArgsCod
     );
     return 1;
   }
-  return await new Promise((resolve) => {
-    const child = spawn("python3", [entry, ...args], {
-      stdio: "inherit",
-      env: { ...process.env, PYTHONPATH: buildPythonpath(paths) },
-    });
-    child.on("error", (err) => {
-      process.stderr.write(`error: failed to spawn python3: ${err.message}\n`);
-      resolve(1);
-    });
-    child.on("close", (code) => resolve(typeof code === "number" ? code : 1));
-  });
+  return await spawnPythonEntry(entry, args, paths);
+}
+
+export async function runInstalledValidator({ validatorName, args }) {
+  const paths = await resolvePaths();
+  const entry = resolveInstalledValidator(paths, validatorName);
+  if (!entry) {
+    process.stderr.write(
+      `error: ${validatorName} not found — run 'okstra install' (or 'okstra ensure-installed') first\n`,
+    );
+    return 1;
+  }
+  return await spawnPythonEntry(entry, args, paths);
 }
 
 export async function runPythonSnippet({ script, args = [], extraEnv = {} }) {