okstra 0.128.0 → 0.129.1

package/runtime/validators/validate-run.py

@@ -46,6 +46,9 @@ 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.improvement_assignment import (  # noqa: E402
+    validate_primary_lens_assignments,
+)
 from okstra_ctl.design_prep import (  # noqa: E402
     DesignPrepError,
     _planning_seq as _design_prep_planning_seq,
@@ -59,8 +62,10 @@ from okstra_ctl.design_surfaces import (  # noqa: E402
     expected_prep_plan_item_id,
 )
 from okstra_ctl.worker_prompt_contract import (  # noqa: E402
-    validate_final_verification_prompt_paths,
+    PromptRecord,
+    validate_initial_prompt_records,
 )
+from okstra_ctl.convergence_engine import validate_final_state  # noqa: E402
 
 TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
@@ -370,45 +375,198 @@ def effective_run_task_type(run_manifest: dict, task_manifest: dict) -> str:
     ).strip()
 
 
-def _validate_final_verification_initial_prompts(
+def _resolve_prompt_record_path(project_root: Path, prompt_value: str) -> Path:
+    prompt_path = Path(prompt_value)
+    return prompt_path if prompt_path.is_absolute() else project_root / prompt_path
+
+
+def _fallback_dispatch_kind(prompt_value: str) -> str:
+    match = re.search(r"-reverify-(r\d+)", Path(prompt_value).name)
+    return f"reverify-{match.group(1)}" if match else "initial"
+
+
+def _persisted_prompt_records(
+    *,
+    project_root: Path,
+    selected_ids: set[str],
+    team_state: dict,
+) -> list[PromptRecord]:
+    dispatches = team_state.get("workerDispatches")
+    source = dispatches if isinstance(dispatches, list) and dispatches else (
+        team_state.get("workers") or []
+    )
+    records: list[PromptRecord] = []
+    seen: set[tuple[str, str, str]] = set()
+    for worker in source:
+        if not isinstance(worker, dict):
+            continue
+        worker_id = str(worker.get("workerId") or "").strip()
+        prompt_value = str(worker.get("promptPath") or "").strip()
+        if worker_id not in selected_ids or not prompt_value:
+            continue
+        dispatch_kind = str(worker.get("kind") or "").strip()
+        if not dispatch_kind:
+            dispatch_kind = _fallback_dispatch_kind(prompt_value)
+        identity = (worker_id, dispatch_kind, prompt_value)
+        if identity in seen:
+            continue
+        seen.add(identity)
+        records.append(
+            PromptRecord(
+                worker_id=worker_id,
+                dispatch_kind=dispatch_kind,
+                path=_resolve_prompt_record_path(project_root, prompt_value),
+            )
+        )
+    return records
+
+
+def _markdown_section(text: str, heading: str) -> str:
+    pattern = rf"(?ms)^##\s+{re.escape(heading)}\s*$\n(.*?)(?=^##\s|\Z)"
+    match = re.search(pattern, text)
+    return match.group(1) if match else ""
+
+
+def _parse_resolved_lenses(grilling_text: str) -> list[str]:
+    section = _markdown_section(grilling_text, "Resolved lenses")
+    return [
+        match.group(1).strip().strip("`")
+        for line in section.splitlines()
+        if (match := re.match(r"^\s*-\s+(.+?)\s*$", line))
+    ]
+
+
+def _parse_primary_assignments(
+    grilling_text: str,
+) -> tuple[dict[str, str], list[str]]:
+    section = _markdown_section(grilling_text, "Primary Pass Assignments")
+    rows = [
+        (line.strip(), _split_pipe_row(line.strip()))
+        for line in section.splitlines()
+        if line.strip().startswith("|") and line.strip().endswith("|")
+    ]
+    errors: list[str] = []
+    if not rows or rows[0][1] != ["Worker ID", "Primary lens"]:
+        return {}, [
+            "Primary Pass Assignments table must start with "
+            "`| Worker ID | Primary lens |`"
+        ]
+    assignments: dict[str, str] = {}
+    for raw_line, row in rows[1:]:
+        if _is_markdown_separator(raw_line):
+            continue
+        if len(row) != 2 or not all(cell.strip() for cell in row):
+            errors.append("Primary Pass Assignments rows must contain two values")
+            continue
+        worker_id, lens = (cell.strip().strip("`") for cell in row)
+        if worker_id in assignments:
+            errors.append(f"duplicate worker assignment row: {worker_id}")
+            continue
+        assignments[worker_id] = lens
+    return assignments, errors
+
+
+def _grilling_log_path_from_prompts(
+    *,
+    project_root: Path,
+    worker_ids: list[str],
+    records: list[PromptRecord],
+) -> tuple[Path | None, list[str]]:
+    header = "**Phase 1.5 Grilling Log:**"
+    values: set[str] = set()
+    errors: list[str] = []
+    for record in records:
+        if record.worker_id not in worker_ids or record.dispatch_kind != "initial":
+            continue
+        try:
+            text = record.path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        matches = [
+            line.strip()[len(header):].strip().strip("`")
+            for line in text.splitlines()
+            if line.strip().startswith(header)
+        ]
+        if len(matches) == 1 and matches[0]:
+            values.add(matches[0])
+    if not values:
+        return None, ["initial analyser prompts have no grilling-log path"]
+    if len(values) != 1:
+        return None, ["initial analyser prompts reference different grilling logs"]
+    return _resolve_prompt_record_path(project_root, values.pop()), errors
+
+
+def _validate_improvement_primary_assignments(
+    *,
+    project_root: Path,
+    worker_ids: list[str],
+    records: list[PromptRecord],
+) -> list[str]:
+    grilling_path, errors = _grilling_log_path_from_prompts(
+        project_root=project_root,
+        worker_ids=worker_ids,
+        records=records,
+    )
+    if grilling_path is None:
+        return errors
+    try:
+        grilling_text = grilling_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return [*errors, f"cannot read grilling log {grilling_path}: {exc}"]
+    lenses = _parse_resolved_lenses(grilling_text)
+    assignments, parse_errors = _parse_primary_assignments(grilling_text)
+    return [
+        *errors,
+        *parse_errors,
+        *validate_primary_lens_assignments(assignments, worker_ids, lenses),
+    ]
+
+
+def _validate_initial_analysis_prompts(
     data: dict,
     failures: list[str],
 ) -> None:
-    """Validate the selected initial analysis prompts persisted for the run."""
-    if data.get("taskType") != "final-verification":
+    """Validate persisted prompts using their functional audience contract."""
+    task_type = str(data.get("taskType") or "").strip()
+    if not task_type:
         return
-
     run_manifest = data.get("runManifest") or {}
     team_contract = run_manifest.get("teamContract") or {}
     selected_workers = team_contract.get("requiredWorkerRoles") or []
-    selected_ids = {
+    selected_worker_ids = [
         str(worker.get("workerId") or "").strip()
         for worker in selected_workers
         if isinstance(worker, dict)
-    }
+        and str(worker.get("workerId") or "").strip()
+    ]
+    selected_ids = set(selected_worker_ids)
     project_root = Path(data["projectRoot"])
     team_state = data.get("teamState") or {}
-    prompt_paths: dict[str, Path] = {}
-    for worker in team_state.get("workers") or []:
-        if not isinstance(worker, dict):
-            continue
-        worker_id = str(worker.get("workerId") or "").strip()
-        prompt_value = str(worker.get("promptPath") or "").strip()
-        if (
-            worker_id not in selected_ids
-            or worker_id == "report-writer"
-            or not prompt_value
-            or "-reverify-r" in Path(prompt_value).name
-        ):
-            continue
-        prompt_path = Path(prompt_value)
-        prompt_paths[worker_id] = (
-            prompt_path if prompt_path.is_absolute() else project_root / prompt_path
+    manifest = dict(run_manifest)
+    manifest["taskType"] = task_type
+    records = _persisted_prompt_records(
+        project_root=project_root,
+        selected_ids=selected_ids,
+        team_state=team_state,
+    )
+    errors = validate_initial_prompt_records(
+        manifest=manifest,
+        records=records,
+    )
+    if task_type == "improvement-discovery":
+        errors.extend(
+            _validate_improvement_primary_assignments(
+                project_root=project_root,
+                worker_ids=[
+                    worker_id
+                    for worker_id in selected_worker_ids
+                    if worker_id != "report-writer"
+                ],
+                records=records,
+            )
         )
-
-    errors = validate_final_verification_prompt_paths(prompt_paths)
     failures.extend(
-        f"final-verification prompt contract: {error}" for error in errors
+        f"{task_type} prompt contract: {error}" for error in errors
     )
 
 
@@ -3135,63 +3293,34 @@ def _validate_forbidden_actions(
     failures.extend(f"forbidden-action: {v}" for v in violations)
 
 
-CLASSIFICATION_COUNT_KEYS = {
-    "full-consensus": "fullConsensus",
-    "partial-consensus": "partialConsensus",
-    "contested": "contested",
-    "worker-unique": "workerUnique",
-}
-
-
-def classification_counts_from_findings(findings) -> dict:
-    """Recompute `finalClassificationCounts` from `findings[].classification`.
-
-    Shared with `tests/contract/test_convergence_state_contract.py` so the
-    invariant has one definition — it used to live only in that test, which
-    meant it was checked against four hand-written fixtures and never against
-    the state a lead actually writes.
-    """
-    counts = {value: 0 for value in CLASSIFICATION_COUNT_KEYS.values()}
-    for finding in findings or []:
-        if not isinstance(finding, dict):
-            continue
-        key = CLASSIFICATION_COUNT_KEYS.get(finding.get("classification"))
-        if key:
-            counts[key] += 1
-    return counts
-
+_CONVERGENCE_INTERMEDIATE_PREFIXES = (
+    "convergence-groups-",
+    "convergence-work-",
+    "convergence-round-",
+)
 
-def _validate_convergence_state_counts(run_dir, failures) -> None:
-    """A run's convergence state must agree with its own findings list.
 
-    `finalClassificationCounts` is a lead-authored summary of
-    `findings[].classification`. Nothing recomputed it against the real
-    artifact, so a miscount survived into the report as two different truths
-    (observed on dev-6901 planning 009: declared partial 6 / worker-unique 4
-    against an actual 5 / 5). Downstream readers pick one arbitrarily.
-    """
+def _validate_convergence_states(run_dir, failures) -> None:
+    """Replay shared engine invariants for every public final state artifact."""
     from pathlib import Path as _Path
 
     state_dir = _Path(run_dir) / "state"
     if not state_dir.is_dir():
         return
     for state_path in sorted(state_dir.glob("convergence-*.json")):
+        if state_path.name.startswith(_CONVERGENCE_INTERMEDIATE_PREFIXES):
+            continue
         try:
             state = json.loads(state_path.read_text(encoding="utf-8"))
         except (OSError, json.JSONDecodeError) as exc:
-            failures.append(f"convergence state {state_path.name} unreadable: {exc}")
-            continue
-        declared = state.get("finalClassificationCounts")
-        if not isinstance(declared, dict):
-            continue
-        actual = classification_counts_from_findings(state.get("findings"))
-        if declared != actual:
             failures.append(
-                f"convergence state {state_path.name}: finalClassificationCounts "
-                f"{declared} does not match findings[].classification {actual}. "
-                "The counts are a summary of the findings list — a mismatch means "
-                "the run reports two different classifications for the same work."
+                f"convergence state {state_path.name}: unreadable JSON: {exc}"
             )
+            continue
+        failures.extend(
+            f"convergence state {state_path.name}: {error}"
+            for error in validate_final_state(state)
+        )
 
 
 def _validate_requirements_discovery_fanout(run_dir, failures) -> None:
@@ -3569,7 +3698,7 @@ 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_verification_initial_prompts(
+    _validate_initial_analysis_prompts(
         {
             "taskType": task_type,
             "projectRoot": project_root,
@@ -3641,7 +3770,7 @@ def main() -> int:
         run_dir = report_path.parent.parent
         _validate_requirements_discovery_fanout(run_dir, failures)
     # Phase-agnostic: convergence runs in every finding-producing phase.
-    _validate_convergence_state_counts(report_path.parent.parent, failures)
+    _validate_convergence_states(report_path.parent.parent, failures)
     validate_report_views(report_path, failures)
 
     validation_status = "passed" if not failures else "failed"

package/src/cli-registry.mjs

@@ -66,6 +66,13 @@ export const COMMAND_REGISTRY = [
     category: "admin",
     summary: ["Move legacy .project-docs/okstra/ to .okstra/ (one-shot)"],
   },
+  {
+    name: "convergence",
+    module: "./commands/execute/convergence.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Advance and validate deterministic re-verification state"],
+  },
   {
     name: "git-reconcile",
     module: "./commands/execute/git-reconcile.mjs",
@@ -312,6 +319,17 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Render slim AI + self-contained HTML views of a final report"],
   },
+  {
+    name: "report-finalize",
+    module: "./commands/report/finalize.mjs",
+    export: "run",
+    category: "introspection",
+    summary: [
+      "Run the Phase 7 post-report sequence (token-usage,",
+      "render-views, spawn-followups, validate-run) in its",
+      "contractual order against one final report.",
+    ],
+  },
   {
     name: "render-final-report",
     module: "./commands/report/render-final-report.mjs",

package/src/commands/execute/convergence.mjs

@@ -0,0 +1,34 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra convergence — advance deterministic re-verification state
+
+Usage:
+  okstra convergence seed --groups <path> --work-state <path> \\
+    --final-state <path> --migration-dir <path> [--restart-from-round0]
+  okstra convergence plan-round --work-state <path> --plan <path>
+  okstra convergence apply-round --work-state <path> --plan <path> \\
+    --results <path>
+  okstra convergence finalize --work-state <path> --output <path>
+  okstra convergence validate --state <path> --kind <working|final>
+
+This internal admin command is consumed by the Phase 5.5 lead contract. It
+does not install or revive the obsolete okstra-convergence skill.
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (args.length === 0) {
+    process.stdout.write(USAGE);
+    return 2;
+  }
+  const result = await runPythonModule({
+    module: "okstra_ctl.convergence",
+    args,
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}
+

package/src/commands/report/finalize.mjs

@@ -0,0 +1,65 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
+
+const USAGE = `okstra report-finalize — run the Phase 7 post-report sequence
+
+Usage:
+  okstra report-finalize --project-root <dir> --run-manifest <path> \\
+    --report <final-report-<task-type>-<seq>.md> [--team-state <path>]
+
+Runs the four Phase 7 steps in their contractual order against one final-report:
+
+  1. token-usage       substitute real token/cost numbers into the data.json
+  2. render-views      write the self-contained *.html sibling (skipped when the
+                       report has no C-* clarification rows and is not a plan
+                       approval target)
+  3. spawn-followups   turn section 4 rows into task stubs
+  4. validate-run      validate the finished run artifacts
+
+Every step is idempotent, so re-running after a fixed failure is safe. The
+sequence stops at the first non-zero exit and reports which step failed.
+
+This is the same code path the Codex lead adapter runs automatically after its
+report-writer completes, so a Claude-led and a Codex-led run finalize
+identically.
+
+  --workspace-root is owned by this command.
+`;
+
+const OWNED_FLAGS = new Set(["--workspace-root"]);
+
+function isOwnedFlag(arg) {
+  if (OWNED_FLAGS.has(arg)) return true;
+  return [...OWNED_FLAGS].some((flag) => arg.startsWith(`${flag}=`));
+}
+
+export function buildReportFinalizeArgs(args, paths) {
+  return ["--workspace-root", paths.workspace, ...args];
+}
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (args.length === 0) {
+    process.stdout.write(USAGE);
+    return 2;
+  }
+
+  const forbidden = args.find(isOwnedFlag);
+  if (forbidden) {
+    process.stderr.write(
+      `error: ${forbidden} is set by 'okstra report-finalize' itself — remove it from your args\n`,
+    );
+    return 2;
+  }
+
+  const paths = await resolvePaths();
+  const result = await runPythonModule({
+    module: "okstra_ctl.report_finalize",
+    args: buildReportFinalizeArgs(args, paths),
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}