okstra 0.174.0 → 0.176.0

package/runtime/validators/validate_session_conformance.py

@@ -146,6 +146,14 @@ _TRACKED_READ_BASENAMES = (
 @dataclass
 class SessionConformanceResult:
     errors: list[str] = field(default_factory=list)
+    # Conformance findings that are reported without failing the run: the
+    # PROGRESS narration lines. A missing checkpoint line means the run is
+    # harder to follow after the fact, not that any of its work is wrong, and
+    # by the time this validator runs the line can no longer be emitted — the
+    # session that would have written it has ended. Checks that verify a
+    # *claim* (a user confirmation the report says it obtained) stay in
+    # `errors`.
+    advisories: list[str] = field(default_factory=list)
 
     @property
     def ok(self) -> bool:
@@ -1089,26 +1097,30 @@ def _check_progress_checkpoints(
     suffix: str | None,
     report_path: Path,
     errors: list[str],
+    advisories: list[str] | None = None,
 ) -> None:
+    # The narration lines are advisory (see `SessionConformanceResult`); the
+    # user-confirmation cross-check below stays in `errors`.
+    narration = advisories if advisories is not None else errors
     by_phase: dict[str, list[tuple[str, str]]] = {}
     for ts, phase, line in evidence.progress:
         by_phase.setdefault(phase, []).append((ts, line))
 
     def require(phase: str, condition: bool, detail: str) -> None:
         if condition and phase not in by_phase:
-            errors.append(
+            narration.append(
                 f"PROGRESS checkpoint missing: `{phase}` ({detail}) — "
                 "prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
             )
 
     intake = by_phase.get("phase-1-intake", [])
     if not any("complete" not in line.lower() for _ts, line in intake):
-        errors.append(
+        narration.append(
             "PROGRESS checkpoint missing: `phase-1-intake reading task bundle` "
             "(start-of-Phase-1 line) — prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
         )
     if not any("complete" in line.lower() for _ts, line in intake):
-        errors.append(
+        narration.append(
             "PROGRESS checkpoint missing: `phase-1-intake complete` "
             "(after all intake reads) — prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
         )
@@ -1126,7 +1138,7 @@ def _check_progress_checkpoints(
         "`using implicit team (split-pane=<on|off>)` line, or the "
         "`skipped (concurrent-run)` variant in the concurrent-run path",
     )
-    _check_worker_checkpoint_lines(by_phase, analysis_workers, errors)
+    _check_worker_checkpoint_lines(by_phase, analysis_workers, narration)
     convergence_ran = _convergence_rounds_ran(run_dir, suffix)
     require(
         "phase-5.5-convergence",
@@ -1145,10 +1157,10 @@ def _check_progress_checkpoints(
     )
     require("phase-7-persist", True, "at the start of Phase 7")
     _check_batch_cleanup_checkpoints(
-        by_phase, convergence_ran, report_writer_dispatched, errors
+        by_phase, convergence_ran, report_writer_dispatched, narration
     )
     _check_plan_verify_cleanup_checkpoints(
-        by_phase, _plan_body_rounds_ran(run_dir, suffix), errors
+        by_phase, _plan_body_rounds_ran(run_dir, suffix), narration
     )
     _check_user_confirm_checkpoints(
         by_phase, _ids_reported_as_asked(report_path), errors
@@ -1413,7 +1425,13 @@ def validate_session_conformance(
         result.errors.append(error)
         return result
     _check_progress_checkpoints(
-        evidence, team_state, run_dir, suffix, report_path, result.errors
+        evidence,
+        team_state,
+        run_dir,
+        suffix,
+        report_path,
+        result.errors,
+        result.advisories,
     )
     _check_activity_contract(
         evidence,

package/src/cli-registry.mjs

@@ -1,539 +0,0 @@
-const SUMMARY_COLUMN = 25;
-
-export const COMMAND_REGISTRY = [
-  {
-    name: "install",
-    module: "./commands/lifecycle/install.mjs",
-    export: "runInstall",
-    category: "admin",
-    summary: ["Install runtime; seed skills into Agent and Claude homes"],
-  },
-  {
-    name: "ensure-installed",
-    module: "./commands/lifecycle/install.mjs",
-    export: "runEnsureInstalled",
-    category: "admin",
-    summary: ["Verify install is fresh; reinstall if stale (idempotent)"],
-  },
-  {
-    name: "uninstall",
-    module: "./commands/lifecycle/uninstall.mjs",
-    export: "runUninstall",
-    category: "admin",
-    summary: ["Remove runtime + skills (user data preserved by default)"],
-  },
-  {
-    name: "setup",
-    module: "./commands/lifecycle/setup.mjs",
-    export: "run",
-    category: "admin",
-    summary: ["Register the current project (.okstra/project.json)"],
-  },
-  {
-    name: "doctor",
-    module: "./commands/lifecycle/doctor.mjs",
-    export: "run",
-    category: "admin",
-    summary: [
-      "Diagnostic check; --runtime selects assets, --phase checks readiness",
-    ],
-  },
-  {
-    name: "check-project",
-    module: "./commands/lifecycle/check-project.mjs",
-    export: "run",
-    category: "admin",
-    summary: ["Verify the current project has been registered with setup"],
-  },
-  {
-    name: "preflight",
-    module: "./commands/lifecycle/preflight.mjs",
-    export: "run",
-    category: "admin",
-    summary: ["One-call skill preflight: ensure-installed + check-project (JSON)"],
-  },
-  {
-    name: "config",
-    module: "./commands/lifecycle/config.mjs",
-    export: "run",
-    category: "admin",
-    summary: ["Read / write okstra settings (e.g. PR template path)"],
-  },
-  {
-    name: "migrate",
-    module: "./commands/lifecycle/migrate.mjs",
-    export: "run",
-    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: "plan-items",
-    module: "./commands/execute/plan-items.mjs",
-    export: "run",
-    category: "admin",
-    summary: ["Extract and validate deterministic plan-body items"],
-  },
-  {
-    name: "agent-prompt",
-    module: "./commands/execute/agent-prompt.mjs",
-    export: "run",
-    category: "admin",
-    summary: ["Materialize and verify auditable agent invocations"],
-  },
-  {
-    name: "worker-dispatch",
-    module: "./commands/execute/worker-dispatch.mjs",
-    export: "run",
-    category: "admin",
-    summary: ["Dispatch verified CLI-backed worker assignments"],
-  },
-  {
-    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: "worker-audit-check",
-    module: "./commands/execute/worker-audit-check.mjs",
-    export: "run",
-    category: "admin",
-    summary: [
-      "Check a run's worker audit sidecars while the workers",
-      "are still alive (the Phase 7 rules, run early)",
-    ],
-  },
-  {
-    name: "git-reconcile",
-    module: "./commands/execute/git-reconcile.mjs",
-    export: "run",
-    category: "admin",
-    summary: ["Reconcile stale stage SHAs after external git history changes"],
-  },
-  {
-    name: "handoff",
-    module: "./commands/execute/handoff.mjs",
-    export: "run",
-    category: "admin",
-    summary: ["Stage-group release-handoff helpers (eligible/assemble/record)"],
-  },
-  {
-    name: "integrate-stages",
-    module: "./commands/execute/integrate-stages.mjs",
-    export: "run",
-    category: "admin",
-    summary: ["stage 들을 task 브랜치에 통합 머지하고 stage worktree 를 정리"],
-  },
-  {
-    name: "paths",
-    module: "./commands/lifecycle/paths.mjs",
-    export: "run",
-    category: "admin",
-    summary: [
-      "Print runtime paths (workspace/agents/pythonpath/bin/home/version)",
-    ],
-  },
-  {
-    name: "task-list",
-    module: "./commands/inspect/task-list.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["List tasks registered in the current project"],
-  },
-  {
-    name: "task-show",
-    module: "./commands/inspect/task-show.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Summarize a task's manifest + workflow phase state"],
-  },
-  {
-    name: "stage-map",
-    module: "./commands/inspect/stage-map.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Dump a task's implementation-planning Stage Map + done stages"],
-  },
-  {
-    name: "context-cost",
-    module: "./commands/inspect/context-cost.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Estimate file/read context cost for a task bundle"],
-  },
-  {
-    name: "resolve-task-key",
-    module: "./commands/inspect/resolve-task-key.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Resolve a bare task-id to candidate task-keys from the catalog"],
-  },
-  {
-    name: "code-review",
-    module: "./commands/inspect/code-review.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Resolve a code review's diff range and result file path"],
-  },
-  {
-    name: "set-work-status",
-    module: "./commands/inspect/set-work-status.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Set a task's user-managed workStatus in task-manifest.json"],
-  },
-  {
-    name: "time-report",
-    module: "./commands/inspect/time-report.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Aggregate elapsed work time across a task's runs (raw ms)"],
-  },
-  {
-    name: "usage-report",
-    module: "./commands/inspect/usage-report.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Aggregate recent token, cost, and time usage by task type"],
-  },
-  {
-    name: "log-report",
-    module: "./commands/inspect/log-report.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Inventory wrapper sidecar logs by size and task (read-only)"],
-  },
-  {
-    name: "worker-liveness",
-    module: "./commands/inspect/worker-liveness.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Report whether pending workers are still alive (read-only)"],
-  },
-  {
-    name: "error-report",
-    module: "./commands/inspect/error-report.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Aggregate okstra-run error logs into a task-level report"],
-  },
-  {
-    name: "error-zip",
-    module: "./commands/inspect/error-zip.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Bundle cross-project okstra error logs into a zip"],
-  },
-  {
-    name: "run-audit",
-    module: "./commands/inspect/run-audit.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Check okstra run artifacts against progress invariants"],
-  },
-  {
-    name: "recap",
-    module: "./commands/inspect/recap.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Assemble a task's run-to-run phase recap or append a recap log entry"],
-  },
-  {
-    name: "user-response",
-    module: "./commands/inspect/user-response.mjs",
-    export: "run",
-    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",
-    export: "run",
-    category: "introspection",
-    summary: ["Roll up run results across a task-group's tasks (raw ms + tallies)"],
-  },
-  {
-    name: "container",
-    module: "./commands/inspect/container.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Manage the okstra container runtime (up/status/logs/stop-watcher/down)"],
-  },
-  {
-    name: "manager",
-    module: "./commands/manager.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Manage cross-project okstra tasks"],
-  },
-  {
-    name: "worktree-lookup",
-    module: "./commands/execute/worktree-lookup.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Look up registered worktree for a task-key"],
-  },
-  {
-    name: "worktree-status",
-    module: "./commands/execute/worktree-status.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Clean-worktree check that ignores okstra's own scaffolding"],
-  },
-  {
-    name: "plan-validate",
-    module: "./commands/execute/plan-validate.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Check an approved-plan file for the approval marker"],
-  },
-  {
-    name: "render-bundle",
-    module: "./commands/execute/render-bundle.mjs",
-    export: "run",
-    category: "introspection",
-    summary: [
-      "Preview prepare_task_bundle() output (forwards to",
-      "python3 -m okstra_ctl.run --render-only)",
-    ],
-  },
-  {
-    name: "profile",
-    module: "./commands/inspect/profile-show.mjs",
-    export: "run",
-    category: "introspection",
-    summary: [
-      "Print a phase profile with {{INCLUDE:}} expanded and its",
-      "lazy-read sidecars appended (read-only)",
-    ],
-  },
-  {
-    name: "run",
-    module: "./commands/execute/run.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Host-aware auto execution front door"],
-  },
-  {
-    name: "codex-run",
-    module: "./commands/execute/codex-run.mjs",
-    export: "run",
-    category: "introspection",
-    summary: [
-      "Prepare a render-only Codex lead task bundle",
-      "(--lead-runtime codex, no worker dispatch)",
-    ],
-  },
-  {
-    name: "codex-dispatch",
-    module: "./commands/execute/codex-dispatch.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Dispatch CLI-backed workers for a prepared Codex run"],
-  },
-  {
-    name: "worker-state",
-    module: "./commands/execute/worker-state.mjs",
-    export: "run",
-    category: "admin",
-    summary: ["Atomically transition persisted worker status"],
-  },
-  {
-    name: "team",
-    module: "./commands/execute/team.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Dispatch and await pane-backed workers for external leads"],
-  },
-  {
-    name: "wizard",
-    module: "./commands/execute/wizard.mjs",
-    export: "run",
-    category: "introspection",
-    summary: [
-      "Drive the okstra-run interactive input state machine",
-      "(init / step / render-args / confirmation)",
-    ],
-  },
-  {
-    name: "token-usage",
-    module: "./commands/execute/token-usage.mjs",
-    export: "run",
-    category: "introspection",
-    summary: [
-      "Collect token usage for a run (wraps the installed",
-      "okstra-token-usage.py so skills avoid emitting",
-      'python3 "$HOME/..." invocations).',
-    ],
-  },
-  {
-    name: "render-views",
-    module: "./commands/report/render-views.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Render slim AI + self-contained HTML views of a final report"],
-  },
-  {
-    name: "report-translate",
-    module: "./commands/report/translate.mjs",
-    export: "run",
-    category: "introspection",
-    summary: [
-      "Build and verify the translation sidecar the HTML",
-      "renderer overlays when the report language is not",
-      "English (extract | check).",
-    ],
-  },
-  {
-    name: "agent-activity",
-    module: "./commands/report/agent-activity.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Record and project structured lead activity into report data"],
-  },
-  {
-    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",
-    export: "run",
-    category: "introspection",
-    summary: ["Render the markdown sibling of a final-report data.json"],
-  },
-  {
-    name: "inject-report-index",
-    module: "./commands/report/inject-report-index.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Add the top-of-report Index + scroll anchors to a report"],
-  },
-  {
-    name: "spawn-followups",
-    module: "./commands/execute/spawn-followups.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Create follow-up task bundles from a final report"],
-  },
-  {
-    name: "error-log",
-    module: "./commands/execute/error-log.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Append run error events to the run error log"],
-  },
-  {
-    name: "incremental-scope",
-    module: "./commands/execute/incremental-scope.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Decide re-verify vs carry-forward scope for a clarification re-run"],
-  },
-  {
-    name: "incremental-carry",
-    module: "./commands/execute/incremental-carry.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Merge carried-forward plan-item verdicts into an incremental re-run"],
-  },
-  {
-    name: "memory",
-    module: "./commands/memory/memory.mjs",
-    export: "run",
-    category: "introspection",
-    summary: [
-      "Store and find user-home conversation memory under",
-      "~/.okstra/memory-book.",
-    ],
-  },
-  {
-    name: "pr",
-    module: "./commands/pr/pr.mjs",
-    export: "run",
-    category: "introspection",
-    summary: [
-      "Manage PR body templates and prepare PR generation",
-      "bundles under ~/.okstra/template/pr.",
-    ],
-  },
-];
-
-export const COMMANDS = new Map(
-  COMMAND_REGISTRY.map((c) => [
-    c.name,
-    () => import(c.module).then((m) => m[c.export]),
-  ]),
-);
-
-const PREAMBLE = `okstra — host-aware multi-provider cross-verification orchestrator
-
-This CLI is the installer/admin tool. Day-to-day usage happens inside a
-supported agent host through installed skills (okstra-setup, okstra-run, ...).
-
-Quick start (CLI):
-  1. npx -y okstra@latest install                       # one-time, this machine
-  2. cd <your project>
-  3. npx -y okstra@latest setup --project-id <id>       # one-time, this project
-  4. open Claude Code, Codex, or Antigravity and run okstra-run  # start a task
-
-Inside a supported agent host you can replace step 3 with okstra-setup —
-both write the same <PROJECT_ROOT>/.okstra/project.json.
-
-Usage:
-  okstra <command> [options]
-`;
-
-const GLOBAL_OPTIONS = `  --version              Print okstra version and exit
-  --help                 Print this help`;
-
-const FOOTER = `
-
-Run 'okstra <command> --help' for command-specific options.
-Docs: https://github.com/Devonshin/okstra#readme
-`;
-
-function renderRow(command) {
-  const [first, ...rest] = command.summary;
-  const head = "  " + command.name.padEnd(SUMMARY_COLUMN - 2) + first;
-  const continuations = rest.map((line) => " ".repeat(SUMMARY_COLUMN) + line);
-  return [head, ...continuations].join("\n");
-}
-
-function renderRows(category) {
-  return COMMAND_REGISTRY.filter((c) => c.category === category)
-    .map(renderRow)
-    .join("\n");
-}
-
-export const USAGE =
-  PREAMBLE +
-  "\nAdmin commands:\n" +
-  renderRows("admin") +
-  "\n\nIntrospection commands (JSON output, used by skills to avoid python heredocs):\n" +
-  renderRows("introspection") +
-  "\n\nGlobal options:\n" +
-  GLOBAL_OPTIONS +
-  FOOTER;

package/src/commands/execute/codex-dispatch.mjs

@@ -1,10 +0,0 @@
-import {
-  buildWorkerDispatchArgs,
-  runWorkerDispatch,
-} from "./worker-dispatch.mjs";
-
-export const buildCodexDispatchArgs = buildWorkerDispatchArgs;
-
-export async function run(args) {
-  return runWorkerDispatch(args, { commandName: "codex-dispatch" });
-}

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

@@ -1,9 +0,0 @@
-import { runPythonModule } from "../../lib/python-helper.mjs";
-
-export async function run(args) {
-  const { code } = await runPythonModule({
-    module: "okstra_ctl.plan_items_cli",
-    args,
-  });
-  return code ?? 1;
-}