okstra 0.127.0 → 0.129.0

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,
@@ -58,6 +61,11 @@ from okstra_ctl.design_surfaces import (  # noqa: E402
     detect_design_surfaces,
     expected_prep_plan_item_id,
 )
+from okstra_ctl.worker_prompt_contract import (  # noqa: E402
+    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"}
@@ -367,6 +375,201 @@ def effective_run_task_type(run_manifest: dict, task_manifest: dict) -> str:
     ).strip()
 
 
+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 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_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 {}
+    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,
+            )
+        )
+    failures.extend(
+        f"{task_type} prompt contract: {error}" for error in errors
+    )
+
+
 def _is_legal_concurrent_run_skip(
     team_create: object, concurrent_run_authorized: bool
 ) -> bool:
@@ -3090,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:
@@ -3524,6 +3698,15 @@ 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_initial_analysis_prompts(
+        {
+            "taskType": task_type,
+            "projectRoot": project_root,
+            "runManifest": run_manifest,
+            "teamState": team_state,
+        },
+        failures,
+    )
     report_contracts = _normalize_report_contracts(
         run_manifest.get("reportContracts")
     )
@@ -3587,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",

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/inspect/log-report.mjs

@@ -6,9 +6,11 @@ Usage:
   okstra log-report [--project-root <dir>] [--cwd <dir>] [--top <N>] [--json]
 
 Output: JSON { ok, projectRoot, logsRoot, topLargest[], perTask[], totals }.
-Scans <project-root>/.okstra/tasks/**/runs/*/prompts/*.log. Sizes are raw bytes
-and mtimes are epoch seconds — the caller formats KB/MB and ages. Read-only: it
-never deletes logs (cleanup commands stay in the skill).
+Scans <project-root>/.okstra/tasks/**/runs/*/prompts/*.log. Each entry reports
+the wrapper transcript as transcriptBytes and its sibling prompt Markdown as
+promptBytes; sizeBytes remains the transcript-size compatibility field. Sizes
+are raw bytes and mtimes are epoch seconds — the caller formats KB/MB and ages.
+Read-only: it never deletes logs (cleanup commands stay in the skill).
 `;
 
 export async function run(args) {