@kontextmind/kxm 0.6.0 → 0.7.10

package/scripts/kxm-hub.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 
 import { spawn, spawnSync } from "node:child_process";
-import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -15,6 +17,19 @@ const startedAt = new Date().toISOString();
 const controlFile = "hub.stop";
 const controlPath = join(stateDir, controlFile);
 
+// --- Persistent hub credentials (kxm.hub-env.v1) -------------------------
+// Precedence: KXM_AUTH_TOKEN/KXM_PROJECT_TOKENS env, then the persisted
+// user-state file, then a generated admin token that is persisted so later
+// restarts, workers, and dashboards reuse the same credential.
+function resolveUserStateRoot() {
+  const explicit = process.env.KXM_STATE_HOME?.trim();
+  if (explicit) return resolve(explicit);
+  const home = homedir();
+  if (process.platform === "win32") return resolve(process.env.LOCALAPPDATA?.trim() || join(home, "AppData", "Local"), "KXM");
+  if (process.platform === "darwin") return resolve(home, "Library", "Application Support", "KXM");
+  return resolve(process.env.XDG_STATE_HOME?.trim() || join(home, ".local", "state"), "kxm");
+}
+
 function processExists(pid) {
   try {
     process.kill(pid, 0);
@@ -24,6 +39,119 @@ function processExists(pid) {
   }
 }
 
+function parseHubEnvFile() {
+  const file = join(resolveUserStateRoot(), "hub-env.json");
+  let raw;
+  try {
+    raw = readFileSync(file, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return { file, record: undefined };
+    throw new Error(`KXM hub could not read the persisted hub env at ${file}: ${error.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`KXM hub env file is malformed at ${file}; fix or remove it (it holds only KXM_AUTH_TOKEN/KXM_PROJECT_TOKENS values): ${error.message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || parsed.schema !== "kxm.hub-env.v1") {
+    throw new Error(`KXM hub env file at ${file} does not use schema kxm.hub-env.v1`);
+  }
+  return { file, record: parsed };
+}
+
+function generateAdminToken() {
+  return `kxm_admin_${randomBytes(24).toString("base64url")}`;
+}
+
+function persistHubEnv(file, record) {
+  mkdirSync(resolve(file, ".."), { recursive: true });
+  const temporary = join(resolve(file, ".."), `.hub-env-${process.pid}.tmp`);
+  writeFileSync(temporary, `${JSON.stringify(record, undefined, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  try {
+    renameSync(temporary, file);
+  } catch (error) {
+    rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+
+function parseProjectTokensEnv(raw) {
+  const trimmed = raw?.trim();
+  if (!trimmed) return undefined;
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    throw new Error("KXM_PROJECT_TOKENS must be a JSON object of project names to tokens");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("KXM_PROJECT_TOKENS must be a JSON object of project names to tokens");
+  }
+  for (const [project, token] of Object.entries(parsed)) {
+    if (!project.trim() || typeof token !== "string" || !token.trim()) {
+      throw new Error("KXM_PROJECT_TOKENS must contain non-empty project names and token strings");
+    }
+  }
+  return parsed;
+}
+
+/** Resolve credentials, persisting generated/env values into the user-state file. */
+function resolveCredentials() {
+  const { file, record } = parseHubEnvFile();
+  const envToken = process.env.KXM_AUTH_TOKEN?.trim();
+  const envProjectTokens = parseProjectTokensEnv(process.env.KXM_PROJECT_TOKENS);
+  let authToken = envToken || record?.authToken;
+  let authTokenSource = envToken ? "env" : record?.authToken ? "file" : "none";
+  if (!authToken) {
+    authToken = generateAdminToken();
+    authTokenSource = "generated";
+  }
+  const projectTokens = envProjectTokens || record?.projectTokens;
+  const projectTokensSource = envProjectTokens ? "env" : record?.projectTokens ? "file" : "none";
+  const envChanged = (authTokenSource === "env" && record?.authToken !== authToken)
+    || (projectTokensSource === "env" && JSON.stringify(record?.projectTokens ?? undefined) !== JSON.stringify(projectTokens ?? undefined));
+  if (authTokenSource === "generated" || envChanged) {
+    persistHubEnv(file, {
+      schema: "kxm.hub-env.v1",
+      createdAt: record?.createdAt || new Date().toISOString(),
+      ...(authToken ? { authToken } : {}),
+      ...(projectTokens ? { projectTokens } : {}),
+    });
+  }
+  return { authToken, authTokenSource, projectTokens, projectTokensSource, file };
+}
+
+let credentials;
+try {
+  credentials = resolveCredentials();
+} catch (error) {
+  process.stderr.write(`kxm hub: ${error.message}\n`);
+  process.exit(1);
+}
+const launchEnv = { ...process.env };
+if (credentials.authToken) launchEnv.KXM_AUTH_TOKEN = credentials.authToken;
+if (credentials.projectTokens) launchEnv.KXM_PROJECT_TOKENS = JSON.stringify(credentials.projectTokens);
+if (credentials.authTokenSource !== "env") {
+  process.stdout.write(`kxm hub: using ${credentials.authTokenSource === "generated" ? "newly generated" : "persisted"} KXM_AUTH_TOKEN from ${credentials.file}\n`);
+}
+
+function terminateTree(pid) {
+  // Best-effort cleanup of an orphaned hub server whose wrapper died
+  // without reclaiming (e.g. SIGKILL). The wrapper could not be stopped
+  // gracefully in that state, so the server is asked to shut down first and
+  // forced after a short grace period.
+  if (!Number.isInteger(pid) || pid <= 0) return;
+  try { process.kill(pid, "SIGTERM"); } catch { /* already gone */ }
+  const deadline = Date.now() + 3000;
+  while (Date.now() < deadline) {
+    if (!processExists(pid)) return;
+    const wait = Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+    if (wait !== "timed-out") return;
+  }
+  try { process.kill(pid, "SIGKILL"); } catch { /* already gone */ }
+}
+
 function claimPidFile() {
   const record = { version: 1, pid: process.pid, role: "hub", startedAt, controlFile };
   for (let attempt = 0; attempt < 3; attempt += 1) {
@@ -50,6 +178,19 @@ function claimPidFile() {
       if (existing?.version === 1 && existing.role === "hub" && Number.isInteger(existing.pid) && processExists(existing.pid)) {
         throw new Error(`KXM hub is already managed by PID ${existing.pid}`);
       }
+      // A well-formed claim whose wrapper is dead is safe to reclaim. Keep
+      // malformed claims fail-closed because they may belong to another tool.
+      if (existing?.version === 1 && existing.role === "hub" && Number.isInteger(existing.pid) && !processExists(existing.pid)) {
+        // The wrapper is gone. An orphaned server child recorded by the dead
+        // wrapper is cleaned up before reclaiming so a SIGKILLed wrapper does
+        // not leave a port-holding server behind.
+        if (Number.isInteger(existing.serverPid) && existing.serverPid !== existing.pid && processExists(existing.serverPid)) {
+          process.stderr.write(`kxm hub: cleaning up orphaned hub server PID ${existing.serverPid} from a dead wrapper\n`);
+          terminateTree(existing.serverPid);
+        }
+        rmSync(pidPath, { force: true });
+        continue;
+      }
       throw new Error(
         `KXM hub PID claim is stale at ${pidPath}; remove it only after verifying no hub process is running`,
       );
@@ -73,8 +214,15 @@ const child = spawn(process.execPath, [
   ...process.argv.slice(2),
 ], {
   stdio: ["inherit", "inherit", "inherit", "ipc"],
-  env: process.env,
+  env: launchEnv,
 });
+// Record the server child PID inside the claim so a later wrapper can clean
+// up an orphaned server if this wrapper is killed without running cleanupPid.
+if (child.pid) {
+  try {
+    writeFileSync(pidPath, `${JSON.stringify({ version: 1, pid: process.pid, serverPid: child.pid, role: "hub", startedAt, controlFile })}\n`, "utf8");
+  } catch { /* claim already written; serverPid tracking is best-effort */ }
+}
 let stopping = false;
 
 child.once("error", (error) => {

package/scripts/kxm-publish-npm.mjs

@@ -275,7 +275,9 @@ export async function main(env = process.env, stdout = process.stdout, stderr =
   const token = env.GITHUB_TOKEN || env.GH_TOKEN;
   const npmToken = env.NODE_AUTH_TOKEN || env.NPM_TOKEN;
   const repo = env.GITHUB_REPOSITORY;
-  const tag = env.GITHUB_REF_NAME || env.TAG;
+  // KXM_RELEASE_TAG is explicit for workflow_dispatch runs; GITHUB_REF_NAME
+  // is the branch name for that event, not the requested release tag.
+  const tag = env.KXM_RELEASE_TAG || env.TAG || env.GITHUB_REF_NAME;
   const assetName = env.KXM_ASSET;
   const assetPath = env.KXM_ASSET_PATH;
   const declaredSha256 = env.KXM_ASSET_SHA256;

package/scripts/kxm-release-github.mjs

@@ -427,7 +427,9 @@ export function fileSha256(path) {
 export async function main(env = process.env, stdout = process.stdout, stderr = process.stderr) {
   const token = env.GITHUB_TOKEN || env.GH_TOKEN;
   const repo = env.GITHUB_REPOSITORY;
-  const tag = env.GITHUB_REF_NAME;
+  // KXM_RELEASE_TAG is explicit for workflow_dispatch runs; GITHUB_REF_NAME
+  // is the branch name for that event, not the requested release tag.
+  const tag = env.KXM_RELEASE_TAG || env.TAG || env.GITHUB_REF_NAME;
   const assetName = env.KXM_ASSET;
   const assetPath = env.KXM_ASSET_PATH;
   const declared = env.KXM_ASSET_SHA256;

package/scripts/native-critic.d.mts

@@ -0,0 +1,5 @@
+export function nativeCriticLaunch(harness: string): {
+  model: string;
+  command: string;
+  args: string[];
+};

package/scripts/native-critic.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { HubClient } from "../plugins/kxm/dist/client.js";
+import { buildArgv } from "./harness-run.mjs";
+
+// Launch intent only: these labels are not observed model identity or admission.
+export function nativeCriticLaunch(harness) {
+  if (!["fable", "astra"].includes(harness)) {
+    throw new Error("usage: native-critic.mjs <fable|astra> <prompt>");
+  }
+  const model = harness === "fable" ? "fable" : "gpt-6-astra";
+  const command = harness === "fable" ? "claude" : "codex";
+  const args = harness === "fable"
+    ? ["-p", "--model", model, "--output-format", "json", "--no-session-persistence", "--tools", "Read,Glob,Grep", "--setting-sources", "user"]
+    : buildArgv({ harness: "codex", model, effort: "low", permission: "read-only", prompt_file: "-" });
+  return { model, command, args };
+}
+
+async function main() {
+  const [harness, ...promptParts] = process.argv.slice(2);
+  let launch;
+  try {
+    launch = nativeCriticLaunch(harness);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 2;
+    return;
+  }
+  const { model, command, args } = launch;
+  const env = process.env;
+  const serverUrl = env.KXM_SERVER_URL || "http://127.0.0.1:7331";
+  const outDir = env.KXM_CRITIC_DIR || join(process.cwd(), ".kxm", "assets", "critic-reviews");
+  mkdirSync(outDir, { recursive: true });
+  const client = new HubClient({ serverUrl, authToken: env.KXM_AUTH_TOKEN, name: `${harness}-critic`, purpose: "independent CLI critic", project: env.KXM_PROJECT || ".kxm", model });
+  const prompt = promptParts.join(" ");
+  const agent = await client.start(() => {});
+  const result = await new Promise((resolve) => {
+    const child = spawn(command, args, { env, stdio: ["pipe", "pipe", "pipe"], shell: false });
+    let stdout = "", stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.on("error", (error) => resolve({ code: null, stdout, stderr: String(error) }));
+    child.on("close", (code, signal) => resolve({ code, signal, stdout, stderr }));
+    child.stdin.end(prompt);
+  });
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const path = join(outDir, `${harness}-${stamp}.json`);
+  writeFileSync(path, JSON.stringify({ schema: "kxm.native-critic-review.v1", harness, model, agentId: agent.id, completedAt: new Date().toISOString(), ...result }, null, 2) + "\n", { mode: 0o600 });
+  try { await client.send({ target: env.KXM_REVIEW_TARGET || agent.id, content: `${harness} review completed; artifact=${path}; exit=${String(result.code)}`, delivery: "followUp", idempotencyKey: `critic:${harness}:${stamp}` }); } catch { /* Transport artifact remains, not approval or hub peer-reply evidence. */ }
+  await client.stop();
+  if (result.code !== 0) process.exit(result.code ?? 1);
+  console.log(path);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  await main();
+}

package/.kxm/config/README.md

@@ -1,5 +0,0 @@
-# Workspace configuration
-
-Store reviewable, repository-specific harness and workflow configuration here. `env.example` documents supported environment settings. `workflows/` contains the complete Jira development lifecycle, the v0.4 dogfood workflow, and the provenance/quorum workflow used by parser and evidence-policy tests.
-
-Configuration files may reference secret environment-variable names such as `JIRA_WEBHOOK_SECRET`; they must never contain the secret values. Set `KXM_WEBHOOK_WORKFLOWS_FILE` to the chosen workflow file.

package/.kxm/config/agents.json

@@ -1,43 +0,0 @@
-{
-  "schema": "kxm.agents.v1",
-  "project": "kxm",
-  "host": "local",
-  "agents": [
-    {
-      "name": "grok",
-      "kind": "agent",
-      "driver": "ai",
-      "model": "xai/grok-4.6",
-      "thinking": "xhigh",
-      "purpose": "Sole writer; independent critic of kxm CLI and envelopes"
-    },
-    {
-      "name": "fable",
-      "kind": "agent",
-      "driver": "ai",
-      "model": "anthropic/claude-fable-5-1",
-      "thinking": "xhigh",
-      "purpose": "Independent critic: architecture and permissions"
-    },
-    {
-      "name": "gpt-sol",
-      "kind": "agent",
-      "driver": "ai",
-      "model": "openai-codex/gpt-5.6-sol",
-      "thinking": "xhigh",
-      "purpose": "Independent critic: CLI contracts and documentation"
-    },
-    {
-      "name": "kimi",
-      "kind": "agent",
-      "driver": "ai",
-      "model": "kimi-coding/kimi-for-coding",
-      "thinking": "max",
-      "purpose": "Independent critic: mapping gaps and portability"
-    }
-  ],
-  "ownership": {
-    "writeAgent": "grok",
-    "peerAgents": ["fable", "gpt-sol", "kimi"]
-  }
-}

package/.kxm/config/env.example

@@ -1,56 +0,0 @@
-KXM_HOST=127.0.0.1
-KXM_PORT=7331
-KXM_AUTH_TOKEN=replace-with-a-long-random-token
-KXM_WORKSPACE_DIR=.kxm
-# KXM_CONFIG_DIR=.kxm/config
-# KXM_LOGS_DIR=.kxm/logs
-# KXM_ASSETS_DIR=.kxm/assets
-# KXM_STATE_DIR=.kxm/state
-# KXM_DATA_PATH=.kxm/state/kxm.db
-# KXM_LOG_PATH=.kxm/logs/kxm-hub.jsonl
-KXM_PROJECT_TOKENS={"my-project":"replace-with-a-project-token"}
-KXM_MESSAGE_TTL_MS=86400000
-KXM_MESSAGE_RETENTION_MS=604800000
-KXM_RATE_LIMIT_MAX=600
-KXM_RATE_LIMIT_WINDOW_MS=60000
-KXM_WEBHOOK_WORKFLOWS_FILE=.kxm/config/workflows/jira-development.json
-JIRA_WEBHOOK_SECRET=replace-with-a-high-entropy-webhook-secret
-WORKFLOW_SIGNAL_SECRET=replace-with-a-separate-callback-secret
-
-# Client / Pi extension settings
-KXM_SERVER_URL=http://127.0.0.1:7331
-KXM_PROJECT=my-project
-KXM_AGENT_NAME=planner
-KXM_AGENT_PURPOSE=Plans work and reviews architecture
-
-# Long-lived headless Pi worker
-KXM_WORKDIR=C:\path\to\project
-KXM_WORKER_CONTINUE=true
-# Opt in after reviewing the fresh scoped-history upgrade behavior:
-# workflow = stable default Pi session plus one session per durable workflow run
-# KXM_WORKER_SESSION_ISOLATION=workflow
-# KXM_WORKER_MAX_RUN_SESSIONS=128
-# KXM_WORKER_INITIAL_CONTINUE=false
-# KXM_WORKER_LOG_PATH=.kxm/logs/kxm-worker-planner.jsonl
-# KXM_AGENT_LOG_PATH=.kxm/logs/pi-agent-planner.log
-# KXM_WORKER_MAX_RESTARTS=20
-# KXM_WORKER_MODEL=provider/model
-# KXM_WORKER_FALLBACK_MODELS=provider/fallback-one,provider/fallback-two
-# KXM_WORKER_PROVIDER_RETRY_MS=60000
-# KXM_WORKER_TOOL_TIMEOUT_MS=1860000
-# KXM_WORKER_ACTIVATION_TIMEOUT_MS=60000
-# KXM_WORKER_TOOLS=read,grep,find,ls,kxm_fanout,kxm_workflow_get
-# KXM_WORKER_EXTENSION_PATHS=plugins/kxm/src/extension.ts;C:\path\to\provider\extension.ts
-# KXM_WORKER_SKILL_PATHS=plugins/kxm/skills/kxm
-
-# Optional proposed-improvement telemetry classification override: cli or project
-# KXM_IMPROVE_TARGET=project
-
-# Opt-in Nous Pi providers (unset = no fetch, no registration)
-# KXM_NOUS_PROVIDERS=direct
-# KXM_NOUS_PROVIDERS=proxy
-# KXM_NOUS_PROVIDERS=direct,proxy
-# NOUS_API_KEY=
-# KXM_NOUS_PROXY_URL=http://127.0.0.1:8645/v1
-# KXM_NOUS_DISCOVERY_TIMEOUT_MS=5000
-# KXM_NOUS_CATALOG_FILE=

package/.kxm/config/update.example.yaml

@@ -1,9 +0,0 @@
-# Copy this file to the per-user state root. kxm never reads a project
-# .kxm/update.yaml (it prints a warning and continues). Locations:
-#   Windows: %LOCALAPPDATA%\KXM\update.yaml
-#   macOS:   ~/Library/Application Support/KXM/update.yaml
-#   Linux:   ${XDG_STATE_HOME:-~/.local/state}/kxm/update.yaml
-# Override the state root with an absolute KXM_STATE_HOME for tests.
-schema: kxm.update.v1
-auto: false
-source: github

package/.kxm/config/workflows/fix.json

@@ -1,160 +0,0 @@
-[
-  {
-    "id": "fix",
-    "source": "generic",
-    "project": "kxm",
-    "target": "coordinator",
-    "secretEnv": "FIX_WEBHOOK_SECRET",
-    "signalSecretEnv": "WORKFLOW_SIGNAL_SECRET",
-    "delivery": "followUp",
-    "maxTransitions": 28,
-    "reproOracle": { "stageId": "repro-review", "evidenceKey": "repro" },
-    "planHash": { "stageId": "final-plan", "evidenceKey": "plan" },
-    "requirePlanHash": ["implement", "local-verify", "delivery"],
-    "promptTemplate": "Bug report: {{task}}\n\nRun the /fix workflow: two-phase reproduction before any production edit, approved plan before implementation, bounded rework on failure. The confirmed reproduction is an immutable oracle.\n\nHard rules: (1) The oracle must invoke the diagnosis-named production callables on the reporter path — a sibling API or newer stack is invalid even if it fails. (2) After repro_invalidated, rewrite the draft against that named seam; never checkpoint blocked because the previous seam was wrong or because a method news its own DbContext. (3) Search existing test hosts (controller fixtures, HttpContext helpers, TransactionScope, read-only call against existing data) before declaring a seam untestable.",
-    "stages": [
-      {
-        "id": "intake",
-        "label": "Intake",
-        "area": "workflow",
-        "instructions": "Classify the bug report: expected vs actual behavior, affected surface, severity, and reproduction hints. Record a journal 'plan' entry with the classification. If the report is not actionable, checkpoint with outcome 'blocked'.",
-        "requiredEvidence": ["classification"],
-        "maxAttempts": 2,
-        "on": { "passed": "repro-explore", "blocked": "$terminal" }
-      },
-      {
-        "id": "repro-explore",
-        "label": "Repro explore (read-only)",
-        "area": "implementation",
-        "instructions": "Read and search only: locate the bug, note prior reproductions, test conventions, and similar incidents via kxm context. No source or test edits. Produce a diagnosis that names the exact production callables on the reporter path (handler, data method, or rendered component), root-cause hypothesis, expected/actual behavior, reproduction strategy, reference tests in existing area folders, and target assertions. Secondary surfaces (other API versions, other tabs) are notes only — they are not substitute oracles. Record the diagnosis with journal category 'hypothesis'.",
-        "requiredEvidence": ["diagnosis"],
-        "maxAttempts": 3,
-        "on": { "passed": "repro-write", "blocked": "$terminal" }
-      },
-      {
-        "id": "repro-write",
-        "label": "Repro write (tests only)",
-        "area": "implementation",
-        "instructions": "Write and execute the failing reproduction. Tests and test helpers only — production and configuration stay byte-for-byte unchanged. Every target assertion must call the diagnosis-named production handler, production seam, or rendered production component and fail for the reported reason rather than compilation/setup. A sibling API, newer stack, or 'also used by some admins' handler is invalid even if it fails. A method that news its own DbContext is not grounds for blocked: use existing test hosts (controller fixtures, HttpContext helpers, TransactionScope so a new context still rolls back) or a read-only call against existing data with no seed. After repro_invalidated, write a new draft against the named seam; do not checkpoint outcome blocked because the previous draft was the wrong seam. Checkpoint failed (outcome failed) to consume an attempt and rewrite. blocked is only when the ticket is not a code defect. Cite evidence key 'repro' with every test path, sha256, exact command, and failed/passed counts. This is a reviewable draft; it is not immutable until independent repro-review passes.",
-        "requiredEvidence": ["repro"],
-        "maxAttempts": 3,
-        "on": { "passed": "repro-review", "failed": "repro-write", "blocked": "$terminal" }
-      },
-      {
-        "id": "repro-review",
-        "label": "Independent reproduction review",
-        "area": "gates",
-        "instructions": "Before the oracle is captured, send the diagnosis, test files/hashes, exact failing results, and production/config git status to both independent critics. They must verify production coupling to the diagnosis-named reporter-path seam (a sibling API is invalid), full expected-behavior coverage, failure causality, immutability feasibility, and absence of production/config edits. Caller-authored evidence cannot satisfy peer review. If either critic finds an omission or invalid test, checkpoint status 'failed' with outcome 'repro_invalidated' and return to repro-write. Only unanimous validation may pass; cite the unchanged draft under evidence key 'repro'. Passing this stage captures the immutable oracle.",
-        "requiredEvidence": ["repro", "review"],
-        "maxAttempts": 3,
-        "evidencePolicies": {
-          "review": {
-            "kind": "peer-reply",
-            "minProducers": 2,
-            "eligibleAgents": ["critic-1", "critic-2"],
-            "acceptedStatuses": ["replied"]
-          }
-        },
-        "on": { "passed": "plan", "repro_invalidated": "repro-write", "blocked": "$terminal" }
-      },
-      {
-        "id": "plan",
-        "label": "Plan",
-        "area": "workflow",
-        "instructions": "Using the diagnosis and the confirmed reproduction, write the implementation plan: changed files, approach, risks, and how the reproduction proves the fix. Cite evidence key 'plan' with the plan artifact path and content hash.",
-        "requiredEvidence": ["plan"],
-        "maxAttempts": 3,
-        "on": { "passed": "critics", "blocked": "$terminal" }
-      },
-      {
-        "id": "critics",
-        "label": "Independent critics",
-        "area": "gates",
-        "instructions": "Two independent critics review the plan for correctness, scope creep, and risk. Both must reply through the mesh; caller-authored evidence cannot satisfy this policy. If the plan is invalidated, checkpoint with outcome 'plan_invalidated'.",
-        "requiredEvidence": ["critique"],
-        "maxAttempts": 3,
-        "evidencePolicies": {
-          "critique": {
-            "kind": "peer-reply",
-            "minProducers": 2,
-            "eligibleAgents": ["critic-1", "critic-2"],
-            "acceptedStatuses": ["replied"]
-          }
-        },
-        "on": { "passed": "final-plan", "plan_invalidated": "plan", "blocked": "$terminal" }
-      },
-      {
-        "id": "final-plan",
-        "label": "Final plan",
-        "area": "workflow",
-        "instructions": "Fold critic feedback into the final plan. Re-cite evidence key 'plan' with the final artifact path and content hash. The hash of this stage's plan evidence becomes the approved plan hash required by implementation.",
-        "requiredEvidence": ["plan"],
-        "maxAttempts": 2,
-        "on": { "passed": "approval", "plan_invalidated": "plan", "blocked": "$terminal" }
-      },
-      {
-        "id": "approval",
-        "label": "Human approval",
-        "area": "security",
-        "instructions": "Human operator approves the plan. Cite evidence key 'signoff' with the approver identity and approval reference. A 'rejected' outcome routes back to planning; this stage cannot be bypassed by any transition.",
-        "requiredEvidence": ["signoff"],
-        "maxAttempts": 8,
-        "on": { "passed": "implement", "rejected": "plan", "blocked": "$terminal" }
-      },
-      {
-        "id": "implement",
-        "label": "Implement",
-        "area": "implementation",
-        "instructions": "Implement the approved plan. The reproduction oracle is immutable: local verification must fail before the fix and pass after it. Cite evidence keys 'diff' and 'repro' (same value as the oracle).",
-        "requiredEvidence": ["diff"],
-        "maxAttempts": 4,
-        "on": { "passed": "local-verify", "blocked": "$terminal" }
-      },
-      {
-        "id": "local-verify",
-        "label": "Local verify",
-        "area": "gates",
-        "instructions": "Run the repo-defined gates: unit, lint, typecheck, build, and the confirmed reproduction test. Cite evidence key 'gates' with per-gate results. 'implementation_failure' reworks implementation; 'plan_invalidated' routes back to planning rather than expanding scope.",
-        "requiredEvidence": ["gates"],
-        "maxAttempts": 4,
-        "on": {
-          "passed": "delivery",
-          "implementation_failure": "implement",
-          "plan_invalidated": "plan",
-          "blocked": "$terminal"
-        }
-      },
-      {
-        "id": "delivery",
-        "label": "Delivery",
-        "area": "workflow",
-        "instructions": "Create and push the branch and merge request with the reproduction, plan, and diff references. Delivery never auto-merges: CI and review outcomes are watched in the next stage.",
-        "requiredEvidence": ["mr"],
-        "maxAttempts": 2,
-        "on": { "passed": "ci-watch", "blocked": "$terminal" }
-      },
-      {
-        "id": "ci-watch",
-        "label": "CI and review watch",
-        "area": "gates",
-        "instructions": "Watch required CI checks and review status. On failure, checkpoint with outcome 'failure' to rework through bounded transitions. On success, continue to human acceptance.",
-        "requiredEvidence": ["ci"],
-        "maxAttempts": 6,
-        "on": {
-          "passed": "ready-for-human-acceptance",
-          "failure": "implement",
-          "blocked": "$terminal"
-        }
-      },
-      {
-        "id": "ready-for-human-acceptance",
-        "label": "Ready for human acceptance",
-        "area": "workflow",
-        "instructions": "Summarize the fix: reproduction (immutable oracle), approved plan hash, diff, gate results, CI outcome, and the full claim-to-evidence trail from the run journal. Checkpoint 'passed' to complete the run; a human performs final acceptance outside the workflow.",
-        "requiredEvidence": ["summary"],
-        "maxAttempts": 2,
-        "on": { "passed": "$terminal", "blocked": "$terminal" }
-      }
-    ]
-  }
-]