okstra 0.25.1 → 0.27.0

package/runtime/validators/validate-run.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import argparse
 import json
 import os
+import re
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
@@ -527,6 +528,35 @@ PLANNING_REQUIRED_SECTIONS = (
     "Validation Checklist",
     "Rollback",
     "User Approval Request",
+    "Plan Body Verification",
+)
+
+PLAN_VERIFY_GATE_VALUES = (
+    "passed",
+    "passed-with-dissent",
+    "blocked-by-disagreement",
+    "aborted-non-result",
+)
+
+# `Gate result:` line in §4.5.9 of the final report — captures the value
+# token that follows. Tolerates arbitrary markdown formatting between the
+# label and the value (backticks for inline code, double-asterisks for
+# bold, colons, hyphens, whitespace). The captured value is then
+# validated against `PLAN_VERIFY_GATE_VALUES` below so typo'd or unknown
+# values surface as their own failure rather than silently no-matching.
+_GATE_RESULT_RE = re.compile(
+    r"Gate result[^A-Za-z\n]+(?P<value>[a-z][a-z\-]+)",
+    re.IGNORECASE,
+)
+
+# Approval marker line — the bullet that toggles to grant approval. Both
+# unchecked (`- [ ] Approved`) and checked (`- [x] Approved`) forms count
+# as "checkbox present" for this gate. Line-anchored to avoid false
+# positives from inline-code prose examples elsewhere in the template
+# (mirrors `APPROVED_PLAN_PATTERN` in scripts/okstra_ctl/run.py:79).
+_APPROVAL_CHECKBOX_RE = re.compile(
+    r"^[ \t]*(?:[-*+][ \t]+)?`?\[[ xX]\][ \t]*Approved`?[ \t]*$",
+    re.MULTILINE,
 )
 
 
@@ -541,6 +571,13 @@ def validate_phase_boundary(
     required deliverable sections; absence indicates a planning run that
     skipped its core outputs (or an implementation run that ran under the
     wrong task type).
+
+    Additionally enforces the Plan Body Verification gate (§4.5.9):
+    - gate ∈ {passed, passed-with-dissent} → top-level Approval checkbox
+      MUST be present.
+    - gate ∈ {blocked-by-disagreement, aborted-non-result} → checkbox
+      MUST be absent (lead converted findings into Clarification rows
+      instead of opening the gate).
     """
     if task_type != "implementation-planning":
         return
@@ -554,6 +591,40 @@ def validate_phase_boundary(
                 f"`{needle}`"
             )
 
+    gate_match = _GATE_RESULT_RE.search(content)
+    if gate_match is None:
+        # The `Plan Body Verification` heading check above already covers
+        # the wholly-missing case; a heading present without a `Gate result`
+        # line is its own contract violation.
+        if "Plan Body Verification" in content:
+            failures.append(
+                "implementation-planning report has `Plan Body Verification` "
+                "section but no `Gate result:` line — required by §4.5.9."
+            )
+        return
+    gate_value = gate_match.group("value").strip().lower()
+    if gate_value not in PLAN_VERIFY_GATE_VALUES:
+        failures.append(
+            "implementation-planning report `Gate result` value "
+            f"`{gate_value}` is not one of "
+            f"{', '.join(PLAN_VERIFY_GATE_VALUES)}."
+        )
+        return
+    checkbox_present = _APPROVAL_CHECKBOX_RE.search(content) is not None
+    if gate_value in ("passed", "passed-with-dissent") and not checkbox_present:
+        failures.append(
+            "implementation-planning report Gate result is "
+            f"`{gate_value}` but the top-level `User Approval Request` "
+            "checkbox line (`- [ ] Approved` / `- [x] Approved`) is missing."
+        )
+    if gate_value in ("blocked-by-disagreement", "aborted-non-result") and checkbox_present:
+        failures.append(
+            "implementation-planning report Gate result is "
+            f"`{gate_value}` but a top-level `User Approval Request` "
+            "checkbox line is present — gate must NOT render the checkbox "
+            "for this gate result."
+        )
+
 
 def _refresh_task_catalog(project_root: Path, task_manifest: dict) -> tuple[bool, str]:
     """Regenerate `discovery/task-catalog.json` so it stops trailing the

package/runtime/validators/validate-workflow.sh

@@ -18,7 +18,6 @@ OKSTRA_SCRIPT="$WORKSPACE_ROOT/scripts/okstra.sh"
 RUN_VALIDATOR_SCRIPT="$WORKSPACE_ROOT/validators/validate-run.py"
 SOURCE_ASSET_ROOT="$WORKSPACE_ROOT/agents"
 TASK_TYPE="final-verification"
-MARKER="MANUAL-VALIDATION-MARKER"
 PRIMARY_TASK_GROUP="validation"
 PRIMARY_TASK_ID="asset-refresh-and-reference-expectations"
 PRIMARY_BRIEF_FILENAME="validation-brief-primary.md"
@@ -56,7 +55,6 @@ PRIMARY_BRIEF_PATH="$PROJECT_ROOT/$PRIMARY_BRIEF_FILENAME"
 SECONDARY_BRIEF_PATH="$PROJECT_ROOT/$SECONDARY_BRIEF_FILENAME"
 DISCOVERY_FILE="$PROJECT_ROOT/$LATEST_TASK_RELATIVE_PATH"
 CATALOG_FILE="$PROJECT_ROOT/$TASK_CATALOG_RELATIVE_PATH"
-MARKER_FILE="$PROJECT_ROOT/.claude/agents/codex-worker.md"
 PRIMARY_TASK_KEY="$(task_key "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID")"
 SECONDARY_TASK_KEY="$(task_key "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID")"
 PRIMARY_REFERENCE_EXPECTATIONS_FILE="$(task_root "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID")/instruction-set/reference-expectations.md"
@@ -155,36 +153,12 @@ if ! validate_task_catalog "$SECONDARY_TASK_KEY" "$PRIMARY_TASK_KEY" "$SECONDARY
 fi
 pass "latest-task.json and task-catalog.json now reflect distinct primary and secondary tasks"
 
-step "Verifying that rerun without refresh preserves project-local assets"
-require_file "$MARKER_FILE"
-printf '\n%s\n' "$MARKER" >>"$MARKER_FILE"
-assert_contains "$MARKER_FILE" "$MARKER"
-if ! run_okstra "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID" "$SECONDARY_BRIEF_FILENAME"; then
-  fail "Secondary task rerun without refresh failed"
-fi
-assert_contains "$MARKER_FILE" "$MARKER"
-if ! validate_latest_task_pointer "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID"; then
-  fail "latest-task.json changed unexpectedly during secondary rerun without refresh"
-fi
-if ! validate_task_catalog "$SECONDARY_TASK_KEY" "$PRIMARY_TASK_KEY" "$SECONDARY_TASK_KEY"; then
-  fail "task-catalog.json changed unexpectedly during secondary rerun without refresh"
-fi
-pass "Rerun without refresh preserved the modified project-local asset and retained both catalog entries"
-
-step "Verifying that rerun with refresh regenerates project-local assets"
-if ! run_okstra "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID" "$SECONDARY_BRIEF_FILENAME" --refresh-assets; then
-  fail "Secondary task rerun with --refresh-assets failed"
-fi
-assert_not_contains "$MARKER_FILE" "$MARKER"
-if ! validate_seeded_assets match; then
-  fail "Refreshed project-local okstra assets do not match the source files"
-fi
-if ! validate_latest_task_pointer "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID"; then
-  fail "latest-task.json became invalid after refresh"
-fi
-if ! validate_task_catalog "$SECONDARY_TASK_KEY" "$PRIMARY_TASK_KEY" "$SECONDARY_TASK_KEY"; then
-  fail "task-catalog.json became invalid after refresh"
-fi
-pass "Refresh regenerated the mapped project-local okstra assets while preserving both catalog entries"
+# Removed: the historical "rerun without refresh preserves project-local
+# assets" and "rerun with refresh regenerates project-local assets" stanzas.
+# Those tested a contract from when `okstra install` seeded per-project
+# `.claude/` files; install now writes only to `$HOME/.claude` and
+# `$HOME/.okstra`, so the project-local sentinel is no longer a meaningful
+# contract. The `--refresh-assets` flag was removed entirely in a paired
+# commit; users with old scripts should switch to `okstra install --refresh`.
 
 print_summary

package/src/wizard.mjs

@@ -1,3 +1,7 @@
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
 import { runPythonModule } from "./_python-helper.mjs";
 import { resolvePaths } from "./paths.mjs";
 
@@ -7,12 +11,14 @@ Used by the okstra-run skill to drive the per-step prompt loop. Each
 subcommand round-trips a JSON state file held by the skill.
 
 Subcommands:
-  init         seed a fresh wizard state and emit the first prompt
-  step         submit an answer (or fetch the current prompt) and emit next
-  render-args  emit the final --flag/value map for 'okstra render-bundle'
-  confirmation emit the multi-line confirmation echo block
+  new-state-file  print a fresh absolute state-file path on stdout (no I/O on the file itself)
+  init            seed a fresh wizard state and emit the first prompt
+  step            submit an answer (or fetch the current prompt) and emit next
+  render-args     emit the final --flag/value map for 'okstra render-bundle'
+  confirmation    emit the multi-line confirmation echo block
 
 Usage:
+  okstra wizard new-state-file
   okstra wizard init --state-file <path> --project-root <p> --project-id <id>
   okstra wizard step --state-file <path> [--answer <value>]
   okstra wizard render-args --state-file <path>
@@ -50,11 +56,21 @@ export async function run(args) {
   }
 
   const [sub, ...rest] = args;
-  if (!["init", "step", "render-args", "confirmation"].includes(sub)) {
+  if (!["new-state-file", "init", "step", "render-args", "confirmation"].includes(sub)) {
     process.stderr.write(`error: unknown wizard subcommand '${sub}'\n\n${USAGE}`);
     return 2;
   }
 
+  if (sub === "new-state-file") {
+    if (rest.length > 0) {
+      process.stderr.write("error: new-state-file takes no arguments\n");
+      return 2;
+    }
+    const dir = mkdtempSync(join(tmpdir(), "okstra-wizard-"));
+    process.stdout.write(join(dir, "state.json") + "\n");
+    return 0;
+  }
+
   let flags;
   try {
     flags = parseFlags(rest);