cclaw-cli 0.48.32 → 0.48.34

package/dist/content/hook-inline-snippets.d.ts

@@ -0,0 +1,80 @@
+/**
+ * hook-inline-snippets.ts
+ *
+ * Runtime `.cclaw/hooks/run-hook.mjs` is a **standalone Node script** that
+ * cannot import from `cclaw-cli` — it must work inside the end-user's
+ * project even when the CLI is not installed. Two derived computations,
+ * though, must remain 1:1 with the canonical TS implementations:
+ *
+ * 1. `computeCompoundReadinessInline` mirrors
+ *    `src/knowledge-store.ts::computeCompoundReadiness`.
+ * 2. `computeRalphLoopStatusInline` mirrors
+ *    `src/tdd-cycle.ts::computeRalphLoopStatus`.
+ *
+ * Previously those bodies lived inline in `src/content/node-hooks.ts` — a
+ * ~2000-line file — next to unrelated hook-handler code. Any silent drift
+ * only surfaced when someone remembered to update both sides.
+ *
+ * This module centralizes the inline JavaScript snippets so:
+ *
+ * - There is exactly **one place** (this file) that holds each inline
+ *   JS body.
+ * - Each snippet carries an explicit "mirrors X, parity enforced by Y"
+ *   header comment and is emitted into `run-hook.mjs` verbatim.
+ * - `src/content/node-hooks.ts` only interpolates the snippets, it no
+ *   longer owns their source code.
+ *
+ * Parity with the TypeScript canonical implementations is enforced by
+ * `tests/unit/ralph-loop-parity.test.ts`. Any structural change to the
+ * canonical TS code MUST:
+ *
+ * 1. Update the matching snippet below.
+ * 2. Re-run `npm test tests/unit/ralph-loop-parity.test.ts`.
+ *
+ * DO NOT inline tests here — keep the parity check in its dedicated test
+ * file.
+ */
+/**
+ * Inline JS helpers used by both compound-readiness and ralph-loop
+ * snippets. Kept small and locked: they are shared across the two inline
+ * routines and must not grow into a hidden utility namespace.
+ *
+ * - `normalizeCompoundLastUpdatedAt` produces a stable ISO-8601 UTC
+ *   timestamp so the hook-written `compound-readiness.json` is byte-equal
+ *   to the CLI-written version for the same input.
+ * - `countArchivedRunsInline` counts immediate subdirectories of
+ *   `<root>/.cclaw/runs/` so both the hook and the CLI see the same
+ *   `archivedRunsCount` for the small-project relaxation.
+ */
+export declare const HOOK_INLINE_SHARED_HELPERS = "\nfunction normalizeCompoundLastUpdatedAt(date) {\n  return date.toISOString().replace(/\\.\\d{3}Z$/u, \"Z\");\n}\n\n// Count archived runs as sub-directories under `.cclaw/runs/`. Missing\n// dir returns 0; unexpected errors return undefined so the caller can\n// skip the small-project relaxation rather than guess.\nasync function countArchivedRunsInline(root) {\n  const dir = path.join(root, RUNTIME_ROOT, \"runs\");\n  try {\n    const entries = await fs.readdir(dir, { withFileTypes: true });\n    return entries.filter((entry) => entry.isDirectory()).length;\n  } catch (error) {\n    const code = error && typeof error === \"object\" && \"code\" in error ? error.code : null;\n    if (code === \"ENOENT\") return 0;\n    return undefined;\n  }\n}\n";
+/**
+ * Inline mirror of `src/knowledge-store.ts::computeCompoundReadiness`.
+ *
+ * Parity enforced by
+ * `tests/unit/ralph-loop-parity.test.ts::compound-readiness parity`.
+ *
+ * Signature contract:
+ *   async function computeCompoundReadinessInline(root, options) -> CompoundReadiness
+ *
+ * Accepted options (all optional):
+ * - prereadRaw: string | undefined — pre-read `knowledge.jsonl` contents.
+ * - threshold: integer >= 1 — default recurrence threshold.
+ * - archivedRunsCount: integer >= 0 — enables small-project relaxation.
+ * - maxReady: integer >= 1 — cap on returned `ready` cluster count
+ *   (default 10).
+ *
+ * Depends on: `SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD`,
+ * `SMALL_PROJECT_RECURRENCE_THRESHOLD`, `COMPOUND_RECURRENCE_THRESHOLD`,
+ * and `HOOK_INLINE_SHARED_HELPERS` being in the same runtime scope.
+ */
+export declare const COMPOUND_READINESS_INLINE_SOURCE = "\nasync function computeCompoundReadinessInline(root, options) {\n  const filePath = path.join(root, RUNTIME_ROOT, \"knowledge.jsonl\");\n  // Caller may supply pre-read raw to avoid double-reading knowledge.jsonl.\n  const raw = typeof (options && options.prereadRaw) === \"string\"\n    ? options.prereadRaw\n    : await readTextFile(filePath, \"\");\n  const baseThresholdRaw = options && options.threshold;\n  const baseThreshold = Number.isInteger(baseThresholdRaw) && baseThresholdRaw >= 1\n    ? baseThresholdRaw\n    : COMPOUND_RECURRENCE_THRESHOLD;\n  const archivedRunsCount =\n    typeof (options && options.archivedRunsCount) === \"number\" &&\n    Number.isFinite(options.archivedRunsCount) &&\n    options.archivedRunsCount >= 0\n      ? Math.floor(options.archivedRunsCount)\n      : undefined;\n  const smallProjectRelaxationApplied =\n    archivedRunsCount !== undefined &&\n    archivedRunsCount < SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD &&\n    baseThreshold > SMALL_PROJECT_RECURRENCE_THRESHOLD;\n  const threshold = smallProjectRelaxationApplied\n    ? SMALL_PROJECT_RECURRENCE_THRESHOLD\n    : baseThreshold;\n  const maxReady = Number.isInteger(options && options.maxReady) && options.maxReady >= 1\n    ? options.maxReady\n    : 10;\n  const normalize = (value) => String(value == null ? \"\" : value).trim().replace(/\\s+/gu, \" \").toLowerCase();\n  const severityWeight = (sev) => {\n    if (sev === \"critical\") return 3;\n    if (sev === \"important\") return 2;\n    if (sev === \"suggestion\") return 1;\n    return 0;\n  };\n  const buckets = new Map();\n  for (const rawLine of raw.split(/\\r?\\n/gu)) {\n    const line = rawLine.trim();\n    if (line.length === 0) continue;\n    let row;\n    try { row = JSON.parse(line); } catch { continue; }\n    if (!row || typeof row !== \"object\" || Array.isArray(row)) continue;\n    if (row.maturity === \"lifted-to-enforcement\") continue;\n    const type = typeof row.type === \"string\" ? row.type : \"\";\n    const trigger = typeof row.trigger === \"string\" ? row.trigger : \"\";\n    const action = typeof row.action === \"string\" ? row.action : \"\";\n    if (type.length === 0 || trigger.length === 0 || action.length === 0) continue;\n    const key = type + \"||\" + normalize(trigger) + \"||\" + normalize(action);\n    const frequency = Number.isInteger(row.frequency) && row.frequency > 0 ? Math.floor(row.frequency) : 1;\n    const lastSeen = typeof row.last_seen_ts === \"string\" ? row.last_seen_ts : \"\";\n    let bucket = buckets.get(key);\n    if (!bucket) {\n      bucket = {\n        trigger,\n        action,\n        recurrence: frequency,\n        entryCount: 1,\n        severity: typeof row.severity === \"string\" ? row.severity : undefined,\n        lastSeenTs: lastSeen,\n        types: new Set([type]),\n        maturity: new Set([typeof row.maturity === \"string\" ? row.maturity : \"raw\"])\n      };\n      buckets.set(key, bucket);\n      continue;\n    }\n    bucket.recurrence += frequency;\n    bucket.entryCount += 1;\n    bucket.types.add(type);\n    bucket.maturity.add(typeof row.maturity === \"string\" ? row.maturity : \"raw\");\n    if (row.severity === \"critical\") {\n      bucket.severity = \"critical\";\n    } else if (row.severity === \"important\" && bucket.severity !== \"critical\") {\n      bucket.severity = \"important\";\n    }\n    if (lastSeen && Date.parse(lastSeen) > Date.parse(bucket.lastSeenTs || \"0\")) {\n      bucket.lastSeenTs = lastSeen;\n    }\n  }\n  const ready = [];\n  for (const bucket of buckets.values()) {\n    const criticalOverride = bucket.severity === \"critical\";\n    const meetsRecurrence = bucket.recurrence >= threshold;\n    if (!criticalOverride && !meetsRecurrence) continue;\n    ready.push({\n      trigger: bucket.trigger,\n      action: bucket.action,\n      recurrence: bucket.recurrence,\n      entryCount: bucket.entryCount,\n      qualification: criticalOverride && !meetsRecurrence ? \"critical_override\" : \"recurrence\",\n      ...(bucket.severity ? { severity: bucket.severity } : {}),\n      lastSeenTs: bucket.lastSeenTs,\n      types: Array.from(bucket.types).sort(),\n      maturity: Array.from(bucket.maturity).sort()\n    });\n  }\n  ready.sort((a, b) => {\n    const sevDiff = severityWeight(b.severity) - severityWeight(a.severity);\n    if (sevDiff !== 0) return sevDiff;\n    if (b.recurrence !== a.recurrence) return b.recurrence - a.recurrence;\n    const recencyDiff = Date.parse(b.lastSeenTs || \"0\") - Date.parse(a.lastSeenTs || \"0\");\n    if (!Number.isNaN(recencyDiff) && recencyDiff !== 0) return recencyDiff;\n    return String(a.trigger).localeCompare(String(b.trigger));\n  });\n  return {\n    schemaVersion: 2,\n    threshold,\n    baseThreshold,\n    ...(archivedRunsCount !== undefined ? { archivedRunsCount } : {}),\n    smallProjectRelaxationApplied,\n    clusterCount: buckets.size,\n    readyCount: ready.length,\n    ready: ready.slice(0, maxReady),\n    lastUpdatedAt: normalizeCompoundLastUpdatedAt(new Date())\n  };\n}\n";
+/**
+ * Inline mirror of `src/tdd-cycle.ts::computeRalphLoopStatus`.
+ *
+ * Parity enforced by
+ * `tests/unit/ralph-loop-parity.test.ts::ralph-loop parity`.
+ *
+ * Signature contract:
+ *   async function computeRalphLoopStatusInline(stateDir, runId) -> RalphLoopStatus
+ */
+export declare const RALPH_LOOP_INLINE_SOURCE = "\nasync function computeRalphLoopStatusInline(stateDir, runId) {\n  const filePath = path.join(stateDir, \"tdd-cycle-log.jsonl\");\n  const raw = await readTextFile(filePath, \"\");\n  const sliceMap = new Map();\n  const acClosed = new Set();\n  const redOpenSlices = [];\n  let loopIteration = 0;\n  for (const rawLine of raw.split(/\\r?\\n/gu)) {\n    const line = rawLine.trim();\n    if (line.length === 0) continue;\n    let row;\n    try { row = JSON.parse(line); } catch { continue; }\n    if (!row || typeof row !== \"object\" || Array.isArray(row)) continue;\n    const rowRun = typeof row.runId === \"string\" && row.runId.length > 0 ? row.runId : runId;\n    if (rowRun !== runId) continue;\n    const slice = typeof row.slice === \"string\" && row.slice.length > 0 ? row.slice : \"S-unknown\";\n    let state = sliceMap.get(slice);\n    if (!state) {\n      state = { slice, redCount: 0, greenCount: 0, refactorCount: 0, redOpen: false, acIds: [] };\n      sliceMap.set(slice, state);\n    }\n    const exitCode = typeof row.exitCode === \"number\" ? row.exitCode : undefined;\n    if (row.phase === \"red\") {\n      state.redCount += 1;\n      if (exitCode !== undefined && exitCode !== 0) state.redOpen = true;\n    } else if (row.phase === \"green\") {\n      state.greenCount += 1;\n      state.redOpen = false;\n      loopIteration += 1;\n      if (Array.isArray(row.acIds)) {\n        for (const acId of row.acIds) {\n          if (typeof acId !== \"string\" || acId.length === 0) continue;\n          acClosed.add(acId);\n          if (!state.acIds.includes(acId)) state.acIds.push(acId);\n        }\n      }\n    } else if (row.phase === \"refactor\") {\n      state.refactorCount += 1;\n    }\n  }\n  for (const state of sliceMap.values()) {\n    if (state.redOpen) redOpenSlices.push(state.slice);\n  }\n  const slices = Array.from(sliceMap.values()).sort((a, b) => a.slice.localeCompare(b.slice, \"en\"));\n  return {\n    schemaVersion: 1,\n    runId,\n    loopIteration,\n    redOpen: redOpenSlices.length > 0,\n    redOpenSlices,\n    acClosed: Array.from(acClosed).sort(),\n    sliceCount: slices.length,\n    slices,\n    lastUpdatedAt: new Date().toISOString()\n  };\n}\n";

package/dist/content/hook-inline-snippets.js

@@ -0,0 +1,270 @@
+/**
+ * hook-inline-snippets.ts
+ *
+ * Runtime `.cclaw/hooks/run-hook.mjs` is a **standalone Node script** that
+ * cannot import from `cclaw-cli` — it must work inside the end-user's
+ * project even when the CLI is not installed. Two derived computations,
+ * though, must remain 1:1 with the canonical TS implementations:
+ *
+ * 1. `computeCompoundReadinessInline` mirrors
+ *    `src/knowledge-store.ts::computeCompoundReadiness`.
+ * 2. `computeRalphLoopStatusInline` mirrors
+ *    `src/tdd-cycle.ts::computeRalphLoopStatus`.
+ *
+ * Previously those bodies lived inline in `src/content/node-hooks.ts` — a
+ * ~2000-line file — next to unrelated hook-handler code. Any silent drift
+ * only surfaced when someone remembered to update both sides.
+ *
+ * This module centralizes the inline JavaScript snippets so:
+ *
+ * - There is exactly **one place** (this file) that holds each inline
+ *   JS body.
+ * - Each snippet carries an explicit "mirrors X, parity enforced by Y"
+ *   header comment and is emitted into `run-hook.mjs` verbatim.
+ * - `src/content/node-hooks.ts` only interpolates the snippets, it no
+ *   longer owns their source code.
+ *
+ * Parity with the TypeScript canonical implementations is enforced by
+ * `tests/unit/ralph-loop-parity.test.ts`. Any structural change to the
+ * canonical TS code MUST:
+ *
+ * 1. Update the matching snippet below.
+ * 2. Re-run `npm test tests/unit/ralph-loop-parity.test.ts`.
+ *
+ * DO NOT inline tests here — keep the parity check in its dedicated test
+ * file.
+ */
+/**
+ * Inline JS helpers used by both compound-readiness and ralph-loop
+ * snippets. Kept small and locked: they are shared across the two inline
+ * routines and must not grow into a hidden utility namespace.
+ *
+ * - `normalizeCompoundLastUpdatedAt` produces a stable ISO-8601 UTC
+ *   timestamp so the hook-written `compound-readiness.json` is byte-equal
+ *   to the CLI-written version for the same input.
+ * - `countArchivedRunsInline` counts immediate subdirectories of
+ *   `<root>/.cclaw/runs/` so both the hook and the CLI see the same
+ *   `archivedRunsCount` for the small-project relaxation.
+ */
+export const HOOK_INLINE_SHARED_HELPERS = `
+function normalizeCompoundLastUpdatedAt(date) {
+  return date.toISOString().replace(/\\.\\d{3}Z$/u, "Z");
+}
+
+// Count archived runs as sub-directories under \`.cclaw/runs/\`. Missing
+// dir returns 0; unexpected errors return undefined so the caller can
+// skip the small-project relaxation rather than guess.
+async function countArchivedRunsInline(root) {
+  const dir = path.join(root, RUNTIME_ROOT, "runs");
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).length;
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? error.code : null;
+    if (code === "ENOENT") return 0;
+    return undefined;
+  }
+}
+`;
+/**
+ * Inline mirror of `src/knowledge-store.ts::computeCompoundReadiness`.
+ *
+ * Parity enforced by
+ * `tests/unit/ralph-loop-parity.test.ts::compound-readiness parity`.
+ *
+ * Signature contract:
+ *   async function computeCompoundReadinessInline(root, options) -> CompoundReadiness
+ *
+ * Accepted options (all optional):
+ * - prereadRaw: string | undefined — pre-read `knowledge.jsonl` contents.
+ * - threshold: integer >= 1 — default recurrence threshold.
+ * - archivedRunsCount: integer >= 0 — enables small-project relaxation.
+ * - maxReady: integer >= 1 — cap on returned `ready` cluster count
+ *   (default 10).
+ *
+ * Depends on: `SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD`,
+ * `SMALL_PROJECT_RECURRENCE_THRESHOLD`, `COMPOUND_RECURRENCE_THRESHOLD`,
+ * and `HOOK_INLINE_SHARED_HELPERS` being in the same runtime scope.
+ */
+export const COMPOUND_READINESS_INLINE_SOURCE = `
+async function computeCompoundReadinessInline(root, options) {
+  const filePath = path.join(root, RUNTIME_ROOT, "knowledge.jsonl");
+  // Caller may supply pre-read raw to avoid double-reading knowledge.jsonl.
+  const raw = typeof (options && options.prereadRaw) === "string"
+    ? options.prereadRaw
+    : await readTextFile(filePath, "");
+  const baseThresholdRaw = options && options.threshold;
+  const baseThreshold = Number.isInteger(baseThresholdRaw) && baseThresholdRaw >= 1
+    ? baseThresholdRaw
+    : COMPOUND_RECURRENCE_THRESHOLD;
+  const archivedRunsCount =
+    typeof (options && options.archivedRunsCount) === "number" &&
+    Number.isFinite(options.archivedRunsCount) &&
+    options.archivedRunsCount >= 0
+      ? Math.floor(options.archivedRunsCount)
+      : undefined;
+  const smallProjectRelaxationApplied =
+    archivedRunsCount !== undefined &&
+    archivedRunsCount < SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD &&
+    baseThreshold > SMALL_PROJECT_RECURRENCE_THRESHOLD;
+  const threshold = smallProjectRelaxationApplied
+    ? SMALL_PROJECT_RECURRENCE_THRESHOLD
+    : baseThreshold;
+  const maxReady = Number.isInteger(options && options.maxReady) && options.maxReady >= 1
+    ? options.maxReady
+    : 10;
+  const normalize = (value) => String(value == null ? "" : value).trim().replace(/\\s+/gu, " ").toLowerCase();
+  const severityWeight = (sev) => {
+    if (sev === "critical") return 3;
+    if (sev === "important") return 2;
+    if (sev === "suggestion") return 1;
+    return 0;
+  };
+  const buckets = new Map();
+  for (const rawLine of raw.split(/\\r?\\n/gu)) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }
+    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+    if (row.maturity === "lifted-to-enforcement") continue;
+    const type = typeof row.type === "string" ? row.type : "";
+    const trigger = typeof row.trigger === "string" ? row.trigger : "";
+    const action = typeof row.action === "string" ? row.action : "";
+    if (type.length === 0 || trigger.length === 0 || action.length === 0) continue;
+    const key = type + "||" + normalize(trigger) + "||" + normalize(action);
+    const frequency = Number.isInteger(row.frequency) && row.frequency > 0 ? Math.floor(row.frequency) : 1;
+    const lastSeen = typeof row.last_seen_ts === "string" ? row.last_seen_ts : "";
+    let bucket = buckets.get(key);
+    if (!bucket) {
+      bucket = {
+        trigger,
+        action,
+        recurrence: frequency,
+        entryCount: 1,
+        severity: typeof row.severity === "string" ? row.severity : undefined,
+        lastSeenTs: lastSeen,
+        types: new Set([type]),
+        maturity: new Set([typeof row.maturity === "string" ? row.maturity : "raw"])
+      };
+      buckets.set(key, bucket);
+      continue;
+    }
+    bucket.recurrence += frequency;
+    bucket.entryCount += 1;
+    bucket.types.add(type);
+    bucket.maturity.add(typeof row.maturity === "string" ? row.maturity : "raw");
+    if (row.severity === "critical") {
+      bucket.severity = "critical";
+    } else if (row.severity === "important" && bucket.severity !== "critical") {
+      bucket.severity = "important";
+    }
+    if (lastSeen && Date.parse(lastSeen) > Date.parse(bucket.lastSeenTs || "0")) {
+      bucket.lastSeenTs = lastSeen;
+    }
+  }
+  const ready = [];
+  for (const bucket of buckets.values()) {
+    const criticalOverride = bucket.severity === "critical";
+    const meetsRecurrence = bucket.recurrence >= threshold;
+    if (!criticalOverride && !meetsRecurrence) continue;
+    ready.push({
+      trigger: bucket.trigger,
+      action: bucket.action,
+      recurrence: bucket.recurrence,
+      entryCount: bucket.entryCount,
+      qualification: criticalOverride && !meetsRecurrence ? "critical_override" : "recurrence",
+      ...(bucket.severity ? { severity: bucket.severity } : {}),
+      lastSeenTs: bucket.lastSeenTs,
+      types: Array.from(bucket.types).sort(),
+      maturity: Array.from(bucket.maturity).sort()
+    });
+  }
+  ready.sort((a, b) => {
+    const sevDiff = severityWeight(b.severity) - severityWeight(a.severity);
+    if (sevDiff !== 0) return sevDiff;
+    if (b.recurrence !== a.recurrence) return b.recurrence - a.recurrence;
+    const recencyDiff = Date.parse(b.lastSeenTs || "0") - Date.parse(a.lastSeenTs || "0");
+    if (!Number.isNaN(recencyDiff) && recencyDiff !== 0) return recencyDiff;
+    return String(a.trigger).localeCompare(String(b.trigger));
+  });
+  return {
+    schemaVersion: 2,
+    threshold,
+    baseThreshold,
+    ...(archivedRunsCount !== undefined ? { archivedRunsCount } : {}),
+    smallProjectRelaxationApplied,
+    clusterCount: buckets.size,
+    readyCount: ready.length,
+    ready: ready.slice(0, maxReady),
+    lastUpdatedAt: normalizeCompoundLastUpdatedAt(new Date())
+  };
+}
+`;
+/**
+ * Inline mirror of `src/tdd-cycle.ts::computeRalphLoopStatus`.
+ *
+ * Parity enforced by
+ * `tests/unit/ralph-loop-parity.test.ts::ralph-loop parity`.
+ *
+ * Signature contract:
+ *   async function computeRalphLoopStatusInline(stateDir, runId) -> RalphLoopStatus
+ */
+export const RALPH_LOOP_INLINE_SOURCE = `
+async function computeRalphLoopStatusInline(stateDir, runId) {
+  const filePath = path.join(stateDir, "tdd-cycle-log.jsonl");
+  const raw = await readTextFile(filePath, "");
+  const sliceMap = new Map();
+  const acClosed = new Set();
+  const redOpenSlices = [];
+  let loopIteration = 0;
+  for (const rawLine of raw.split(/\\r?\\n/gu)) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }
+    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+    const rowRun = typeof row.runId === "string" && row.runId.length > 0 ? row.runId : runId;
+    if (rowRun !== runId) continue;
+    const slice = typeof row.slice === "string" && row.slice.length > 0 ? row.slice : "S-unknown";
+    let state = sliceMap.get(slice);
+    if (!state) {
+      state = { slice, redCount: 0, greenCount: 0, refactorCount: 0, redOpen: false, acIds: [] };
+      sliceMap.set(slice, state);
+    }
+    const exitCode = typeof row.exitCode === "number" ? row.exitCode : undefined;
+    if (row.phase === "red") {
+      state.redCount += 1;
+      if (exitCode !== undefined && exitCode !== 0) state.redOpen = true;
+    } else if (row.phase === "green") {
+      state.greenCount += 1;
+      state.redOpen = false;
+      loopIteration += 1;
+      if (Array.isArray(row.acIds)) {
+        for (const acId of row.acIds) {
+          if (typeof acId !== "string" || acId.length === 0) continue;
+          acClosed.add(acId);
+          if (!state.acIds.includes(acId)) state.acIds.push(acId);
+        }
+      }
+    } else if (row.phase === "refactor") {
+      state.refactorCount += 1;
+    }
+  }
+  for (const state of sliceMap.values()) {
+    if (state.redOpen) redOpenSlices.push(state.slice);
+  }
+  const slices = Array.from(sliceMap.values()).sort((a, b) => a.slice.localeCompare(b.slice, "en"));
+  return {
+    schemaVersion: 1,
+    runId,
+    loopIteration,
+    redOpen: redOpenSlices.length > 0,
+    redOpenSlices,
+    acClosed: Array.from(acClosed).sort(),
+    sliceCount: slices.length,
+    slices,
+    lastUpdatedAt: new Date().toISOString()
+  };
+}
+`;

package/dist/content/node-hooks.js

@@ -1,6 +1,7 @@
 import { DEFAULT_COMPOUND_RECURRENCE_THRESHOLD } from "../config.js";
 import { RUNTIME_ROOT } from "../constants.js";
 import { SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD, SMALL_PROJECT_RECURRENCE_THRESHOLD } from "../knowledge-store.js";
+import { HOOK_INLINE_SHARED_HELPERS, COMPOUND_READINESS_INLINE_SOURCE, RALPH_LOOP_INLINE_SOURCE } from "./hook-inline-snippets.js";
 function normalizePatterns(patterns, fallback) {
     if (!patterns || patterns.length === 0)
         return [...fallback];
@@ -1451,203 +1452,14 @@ async function handlePromptGuard(runtime) {
   return 0;
 }
 
-function normalizeCompoundLastUpdatedAt(date) {
-  return date.toISOString().replace(/\\.\\d{3}Z$/u, "Z");
-}
-
-// Count archived runs as sub-directories under \`.cclaw/runs/\`. Missing
-// dir returns 0; unexpected errors return undefined so the caller can
-// skip the small-project relaxation rather than guess.
-async function countArchivedRunsInline(root) {
-  const dir = path.join(root, RUNTIME_ROOT, "runs");
-  try {
-    const entries = await fs.readdir(dir, { withFileTypes: true });
-    return entries.filter((entry) => entry.isDirectory()).length;
-  } catch (error) {
-    const code = error && typeof error === "object" && "code" in error ? error.code : null;
-    if (code === "ENOENT") return 0;
-    return undefined;
-  }
-}
-
-// Mirrors src/knowledge-store.ts::computeCompoundReadiness — kept inline so
-// SessionStart can refresh compound-readiness.json without the CLI binary.
-// Any schema change must update src/knowledge-store.ts::computeCompoundReadiness
-// and src/internal/compound-readiness.ts in lockstep. Parity is enforced by
-// tests/unit/ralph-loop-parity.test.ts.
-async function computeCompoundReadinessInline(root, options) {
-  const filePath = path.join(root, RUNTIME_ROOT, "knowledge.jsonl");
-  // Caller may supply pre-read raw to avoid double-reading knowledge.jsonl.
-  const raw = typeof (options && options.prereadRaw) === "string"
-    ? options.prereadRaw
-    : await readTextFile(filePath, "");
-  const baseThresholdRaw = options && options.threshold;
-  const baseThreshold = Number.isInteger(baseThresholdRaw) && baseThresholdRaw >= 1
-    ? baseThresholdRaw
-    : COMPOUND_RECURRENCE_THRESHOLD;
-  const archivedRunsCount =
-    typeof (options && options.archivedRunsCount) === "number" &&
-    Number.isFinite(options.archivedRunsCount) &&
-    options.archivedRunsCount >= 0
-      ? Math.floor(options.archivedRunsCount)
-      : undefined;
-  const smallProjectRelaxationApplied =
-    archivedRunsCount !== undefined &&
-    archivedRunsCount < SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD &&
-    baseThreshold > SMALL_PROJECT_RECURRENCE_THRESHOLD;
-  const threshold = smallProjectRelaxationApplied
-    ? SMALL_PROJECT_RECURRENCE_THRESHOLD
-    : baseThreshold;
-  const maxReady = Number.isInteger(options && options.maxReady) && options.maxReady >= 1
-    ? options.maxReady
-    : 10;
-  const normalize = (value) => String(value == null ? "" : value).trim().replace(/\\s+/gu, " ").toLowerCase();
-  const severityWeight = (sev) => {
-    if (sev === "critical") return 3;
-    if (sev === "important") return 2;
-    if (sev === "suggestion") return 1;
-    return 0;
-  };
-  const buckets = new Map();
-  for (const rawLine of raw.split(/\\r?\\n/gu)) {
-    const line = rawLine.trim();
-    if (line.length === 0) continue;
-    let row;
-    try { row = JSON.parse(line); } catch { continue; }
-    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
-    if (row.maturity === "lifted-to-enforcement") continue;
-    const type = typeof row.type === "string" ? row.type : "";
-    const trigger = typeof row.trigger === "string" ? row.trigger : "";
-    const action = typeof row.action === "string" ? row.action : "";
-    if (type.length === 0 || trigger.length === 0 || action.length === 0) continue;
-    const key = type + "||" + normalize(trigger) + "||" + normalize(action);
-    const frequency = Number.isInteger(row.frequency) && row.frequency > 0 ? Math.floor(row.frequency) : 1;
-    const lastSeen = typeof row.last_seen_ts === "string" ? row.last_seen_ts : "";
-    let bucket = buckets.get(key);
-    if (!bucket) {
-      bucket = {
-        trigger,
-        action,
-        recurrence: frequency,
-        entryCount: 1,
-        severity: typeof row.severity === "string" ? row.severity : undefined,
-        lastSeenTs: lastSeen,
-        types: new Set([type]),
-        maturity: new Set([typeof row.maturity === "string" ? row.maturity : "raw"])
-      };
-      buckets.set(key, bucket);
-      continue;
-    }
-    bucket.recurrence += frequency;
-    bucket.entryCount += 1;
-    bucket.types.add(type);
-    bucket.maturity.add(typeof row.maturity === "string" ? row.maturity : "raw");
-    if (row.severity === "critical") {
-      bucket.severity = "critical";
-    } else if (row.severity === "important" && bucket.severity !== "critical") {
-      bucket.severity = "important";
-    }
-    if (lastSeen && Date.parse(lastSeen) > Date.parse(bucket.lastSeenTs || "0")) {
-      bucket.lastSeenTs = lastSeen;
-    }
-  }
-  const ready = [];
-  for (const bucket of buckets.values()) {
-    const criticalOverride = bucket.severity === "critical";
-    const meetsRecurrence = bucket.recurrence >= threshold;
-    if (!criticalOverride && !meetsRecurrence) continue;
-    ready.push({
-      trigger: bucket.trigger,
-      action: bucket.action,
-      recurrence: bucket.recurrence,
-      entryCount: bucket.entryCount,
-      qualification: criticalOverride && !meetsRecurrence ? "critical_override" : "recurrence",
-      ...(bucket.severity ? { severity: bucket.severity } : {}),
-      lastSeenTs: bucket.lastSeenTs,
-      types: Array.from(bucket.types).sort(),
-      maturity: Array.from(bucket.maturity).sort()
-    });
-  }
-  ready.sort((a, b) => {
-    const sevDiff = severityWeight(b.severity) - severityWeight(a.severity);
-    if (sevDiff !== 0) return sevDiff;
-    if (b.recurrence !== a.recurrence) return b.recurrence - a.recurrence;
-    const recencyDiff = Date.parse(b.lastSeenTs || "0") - Date.parse(a.lastSeenTs || "0");
-    if (!Number.isNaN(recencyDiff) && recencyDiff !== 0) return recencyDiff;
-    return String(a.trigger).localeCompare(String(b.trigger));
-  });
-  return {
-    schemaVersion: 2,
-    threshold,
-    baseThreshold,
-    ...(archivedRunsCount !== undefined ? { archivedRunsCount } : {}),
-    smallProjectRelaxationApplied,
-    clusterCount: buckets.size,
-    readyCount: ready.length,
-    ready: ready.slice(0, maxReady),
-    lastUpdatedAt: normalizeCompoundLastUpdatedAt(new Date())
-  };
-}
-
-// Mirrors src/tdd-cycle.ts::computeRalphLoopStatus — kept inline so the
-// SessionStart hook can write ralph-loop.json without depending on the CLI
-// binary being installed globally. Any schema change must update both copies.
-async function computeRalphLoopStatusInline(stateDir, runId) {
-  const filePath = path.join(stateDir, "tdd-cycle-log.jsonl");
-  const raw = await readTextFile(filePath, "");
-  const sliceMap = new Map();
-  const acClosed = new Set();
-  const redOpenSlices = [];
-  let loopIteration = 0;
-  for (const rawLine of raw.split(/\\r?\\n/gu)) {
-    const line = rawLine.trim();
-    if (line.length === 0) continue;
-    let row;
-    try { row = JSON.parse(line); } catch { continue; }
-    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
-    const rowRun = typeof row.runId === "string" && row.runId.length > 0 ? row.runId : runId;
-    if (rowRun !== runId) continue;
-    const slice = typeof row.slice === "string" && row.slice.length > 0 ? row.slice : "S-unknown";
-    let state = sliceMap.get(slice);
-    if (!state) {
-      state = { slice, redCount: 0, greenCount: 0, refactorCount: 0, redOpen: false, acIds: [] };
-      sliceMap.set(slice, state);
-    }
-    const exitCode = typeof row.exitCode === "number" ? row.exitCode : undefined;
-    if (row.phase === "red") {
-      state.redCount += 1;
-      if (exitCode !== undefined && exitCode !== 0) state.redOpen = true;
-    } else if (row.phase === "green") {
-      state.greenCount += 1;
-      state.redOpen = false;
-      loopIteration += 1;
-      if (Array.isArray(row.acIds)) {
-        for (const acId of row.acIds) {
-          if (typeof acId !== "string" || acId.length === 0) continue;
-          acClosed.add(acId);
-          if (!state.acIds.includes(acId)) state.acIds.push(acId);
-        }
-      }
-    } else if (row.phase === "refactor") {
-      state.refactorCount += 1;
-    }
-  }
-  for (const state of sliceMap.values()) {
-    if (state.redOpen) redOpenSlices.push(state.slice);
-  }
-  const slices = Array.from(sliceMap.values()).sort((a, b) => a.slice.localeCompare(b.slice, "en"));
-  return {
-    schemaVersion: 1,
-    runId,
-    loopIteration,
-    redOpen: redOpenSlices.length > 0,
-    redOpenSlices,
-    acClosed: Array.from(acClosed).sort(),
-    sliceCount: slices.length,
-    slices,
-    lastUpdatedAt: new Date().toISOString()
-  };
-}
+// Inline mirrors of canonical CLI computations (compound-readiness,
+// ralph-loop) are factored into src/content/hook-inline-snippets.ts so
+// this 2000+-line file no longer owns their bodies. Each snippet carries
+// an explicit "mirrors X, parity enforced by Y" comment in the snippets
+// module. Parity is enforced by tests/unit/ralph-loop-parity.test.ts.
+${HOOK_INLINE_SHARED_HELPERS}
+${COMPOUND_READINESS_INLINE_SOURCE}
+${RALPH_LOOP_INLINE_SOURCE}
 
 async function hasFailingRedEvidenceForPath(stateDir, runId, rawPath) {
   const cycleRaw = await readTextFile(path.join(stateDir, "tdd-cycle-log.jsonl"), "");

package/dist/content/opencode-plugin.js

@@ -2,7 +2,7 @@ import { RUNTIME_ROOT } from "../constants.js";
 import { META_SKILL_NAME } from "./meta-skill.js";
 export function opencodePluginJs(_options = {}) {
     return `// cclaw OpenCode plugin — generated by cclaw sync
-import { existsSync, mkdirSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 
@@ -10,6 +10,8 @@ export default function cclawPlugin(ctx) {
   const root = ctx.directory || process.cwd();
   const runtimeDir = join(root, "${RUNTIME_ROOT}");
   const stateDir = join(runtimeDir, "state");
+  const logsDir = join(runtimeDir, "logs");
+  const pluginLogPath = join(logsDir, "opencode-plugin.log");
   const flowStatePath = join(stateDir, "flow-state.json");
   const checkpointPath = join(stateDir, "checkpoint.json");
   const activityPath = join(stateDir, "stage-activity.jsonl");
@@ -34,6 +36,27 @@ export default function cclawPlugin(ctx) {
     }
   }
 
+  /**
+   * Diagnostic log used instead of console.error on the hot path.
+   * Writing to a file keeps hook failures and unknown events from
+   * racing OpenCode's TUI renderer (which causes the overlapping-text
+   * artifact users have reported). Best-effort: any I/O failure is
+   * swallowed so logging never itself blocks or throws.
+   */
+  function logToFile(line) {
+    try {
+      mkdirSync(logsDir, { recursive: true });
+    } catch {
+      return;
+    }
+    const timestamp = new Date().toISOString();
+    try {
+      appendFileSync(pluginLogPath, timestamp + " " + line + "\\n", "utf8");
+    } catch {
+      // ignore — never let logging fail the hook
+    }
+  }
+
   async function readFlowState() {
     try {
       const raw = await readFile(flowStatePath, "utf8");
@@ -272,6 +295,17 @@ export default function cclawPlugin(ctx) {
     });
   }
 
+  const lastHookStderr = new Map();
+  function recordHookStderr(hookName, stderr) {
+    if (typeof hookName !== "string" || hookName.length === 0) return;
+    const trimmed = typeof stderr === "string" ? stderr.trim() : "";
+    if (trimmed.length === 0) {
+      lastHookStderr.delete(hookName);
+      return;
+    }
+    lastHookStderr.set(hookName, trimmed);
+  }
+
   async function runHookScript(hookName, payload = {}) {
     const { spawn } = await import("node:child_process");
     const hookRuntimePath = join(root, "${RUNTIME_ROOT}/hooks/run-hook.mjs");
@@ -282,6 +316,7 @@ export default function cclawPlugin(ctx) {
       const finish = (ok) => {
         if (settled) return;
         settled = true;
+        recordHookStderr(hookName, stderr);
         resolve(ok);
       };
 
@@ -296,13 +331,19 @@ export default function cclawPlugin(ctx) {
         return;
       }
 
+      // Tool.execute.before is a user-facing hot path: 20s is far too
+      // long to wait on a guard. 5s gives the hook real breathing room
+      // (typical runtime is well under 500ms) while capping the worst-
+      // case stall at a number the user will still tolerate.
       const timer = setTimeout(() => {
         child.kill("SIGKILL");
         if (stderr.length > 0) {
-          console.error("[cclaw] opencode hook timeout: " + hookName + " stderr=" + stderr.slice(-1200));
+          logToFile("hook timeout: " + hookName + " stderr=" + stderr.slice(-1200));
+        } else {
+          logToFile("hook timeout: " + hookName + " (no stderr)");
         }
         finish(false);
-      }, 20_000);
+      }, 5_000);
 
       child.stderr?.on("data", (chunk) => {
         stderr += String(chunk ?? "");
@@ -318,7 +359,7 @@ export default function cclawPlugin(ctx) {
         clearTimeout(timer);
         const ok = code === 0;
         if (!ok && stderr.length > 0) {
-          console.error("[cclaw] opencode hook failed: " + hookName + " stderr=" + stderr.slice(-1200));
+          logToFile("hook failed: " + hookName + " exit=" + code + " stderr=" + stderr.slice(-1200));
         }
         finish(ok);
       });
@@ -355,6 +396,118 @@ export default function cclawPlugin(ctx) {
     return { input: input ?? {}, output: output ?? {} };
   }
 
+  /**
+   * Read-only tools cannot mutate state or execute arbitrary code, so
+   * running prompt/workflow guards on them is pure overhead and — worse —
+   * surfaces a hard block when guards are misconfigured. OpenCode tool
+   * names vary (Claude/Codex use PascalCase; opencode-native often uses
+   * lowercase), so we normalize and match against a tight allow-list.
+   * Anything not in this list (bash, edit, write, patch, task, run, …)
+   * still runs through guards.
+   */
+  const SAFE_READONLY_TOOLS = new Set([
+    "read",
+    "glob",
+    "grep",
+    "list",
+    "ls",
+    "view",
+    "webfetch",
+    "websearch"
+  ]);
+
+  function isSafeReadOnlyTool(payload) {
+    if (!payload || typeof payload !== "object") return false;
+    const candidates = [
+      payload.tool,
+      payload.name,
+      payload.tool_name,
+      payload.toolName
+    ];
+    const inner = payload.input;
+    if (inner && typeof inner === "object") {
+      candidates.push(inner.tool, inner.name, inner.tool_name, inner.toolName);
+    }
+    for (const candidate of candidates) {
+      if (typeof candidate !== "string" || candidate.length === 0) continue;
+      if (SAFE_READONLY_TOOLS.has(candidate.toLowerCase())) return true;
+    }
+    return false;
+  }
+
+  /**
+   * cclaw considers itself "active" in a project when both the state
+   * file and the hook runtime script exist. If either is missing the
+   * plugin behaves as a no-op for guards — this project hasn't been
+   * initialized (or the install is corrupt) and blocking every tool
+   * call would strand the user.
+   */
+  function isCclawInitialized() {
+    try {
+      const hookRuntimePath = join(runtimeDir, "hooks/run-hook.mjs");
+      return existsSync(flowStatePath) && existsSync(hookRuntimePath);
+    } catch {
+      return false;
+    }
+  }
+
+  let notInitializedAdvised = false;
+  function noteNotInitialized() {
+    if (notInitializedAdvised) return;
+    notInitializedAdvised = true;
+    logToFile(
+      "guards skipped: cclaw is not initialized in this project. " +
+      "Run \`cclaw init\` in " + root + " to activate flow enforcement."
+    );
+  }
+
+  /**
+   * Escape hatch for a user stuck behind a misbehaving guard chain.
+   * Reads a small set of env vars that all mean "turn cclaw off for this
+   * session": CCLAW_DISABLE=1 (primary), CCLAW_STRICTNESS=off, or
+   * CCLAW_GUARDS=off. Anything truthy disables both guards and the
+   * advisory path. Logged once so users can confirm the bypass is in
+   * effect without cluttering the TUI.
+   */
+  const DISABLE_ENV_KEYS = ["CCLAW_DISABLE", "CCLAW_GUARDS", "CCLAW_STRICTNESS"];
+  let disabledAdvised = false;
+  function isCclawDisabled() {
+    for (const key of DISABLE_ENV_KEYS) {
+      const raw = process.env[key];
+      if (typeof raw !== "string") continue;
+      const value = raw.trim().toLowerCase();
+      if (value.length === 0) continue;
+      if (key === "CCLAW_STRICTNESS") {
+        if (value === "off" || value === "disabled" || value === "none") {
+          return { disabled: true, key, value };
+        }
+        continue;
+      }
+      if (
+        value === "1" ||
+        value === "true" ||
+        value === "yes" ||
+        value === "on" ||
+        value === "off" ||
+        value === "disabled"
+      ) {
+        if (key === "CCLAW_GUARDS" && (value === "on" || value === "true" || value === "yes" || value === "1")) {
+          continue;
+        }
+        return { disabled: true, key, value };
+      }
+    }
+    return { disabled: false, key: "", value: "" };
+  }
+  function noteDisabled(reason) {
+    if (disabledAdvised) return;
+    disabledAdvised = true;
+    logToFile(
+      "guards disabled by env " + reason.key + "=" + reason.value + ". " +
+      "All tool calls will pass through without prompt/workflow checks."
+    );
+  }
+
   function resolveEventType(payload) {
     if (typeof payload === "string") return payload;
     if (payload && typeof payload === "object") {
@@ -407,7 +560,7 @@ export default function cclawPlugin(ctx) {
           payload && typeof payload === "object"
             ? Object.keys(payload).slice(0, 10).join(", ")
             : typeof payload;
-        console.error("[cclaw] opencode unknown event payload keys: " + keys);
+        logToFile("unknown event payload keys: " + keys);
       }
       // session.compacted must run pre-compact BEFORE refreshing the bootstrap
       // cache, otherwise the injected system prompt still shows the pre-compact
@@ -435,12 +588,41 @@ export default function cclawPlugin(ctx) {
       }
     },
     "tool.execute.before": async (input, output) => {
+      const disabled = isCclawDisabled();
+      if (disabled.disabled) {
+        // Explicit user override (CCLAW_DISABLE=1 et al): stay fully out
+        // of the way. Any real problem with the guard chain should not
+        // prevent the user from unblocking themselves.
+        noteDisabled(disabled);
+        return;
+      }
       const payload = normalizeToolPayload(input, output);
-      const promptOk = await runHookScript("prompt-guard", payload);
-      const workflowOk = await runHookScript("workflow-guard", payload);
+      if (isSafeReadOnlyTool(payload)) {
+        // Read-only tools bypass guards — they cannot mutate state and
+        // blocking them gives users an unusable session when guards are
+        // misconfigured or cclaw isn't fully initialized.
+        return;
+      }
+      if (!isCclawInitialized()) {
+        // Project has no flow-state or hook runtime: cclaw isn't in use
+        // here. Never block the user's tools because of setup they didn't
+        // ask for. Surface a single advisory so they can notice.
+        noteNotInitialized();
+        return;
+      }
+      const [promptOk, workflowOk] = await Promise.all([
+        runHookScript("prompt-guard", payload),
+        runHookScript("workflow-guard", payload)
+      ]);
       if (!promptOk || !workflowOk) {
+        const failed = !promptOk ? "prompt-guard" : "workflow-guard";
+        const rawDetail = lastHookStderr.get(failed) || "";
+        const detail = rawDetail.length > 0 ? rawDetail.slice(-400) : "(no stderr captured)";
         throw new Error(
-          "cclaw OpenCode guard blocked tool.execute.before (prompt/workflow guard non-zero exit)."
+          "cclaw " + failed + " blocked tool.execute.before.\\n" +
+          "Reason: " + detail + "\\n" +
+          "Diagnose: run \`cclaw doctor\` in project root.\\n" +
+          "Bypass (temporary): export CCLAW_DISABLE=1 before starting OpenCode."
         );
       }
     },

package/dist/content/skills.js

@@ -309,6 +309,59 @@ function normalizedGuidanceKey(value) {
         .trim()
         .toLowerCase();
 }
+function mermaidNodeLabel(raw, index) {
+    const stripped = raw
+        .replace(/`[^`]+`/gu, "")
+        .replace(/\*\*/gu, "")
+        .replace(/[*_]/gu, "")
+        .replace(/\[[^\]]*\]\([^)]*\)/gu, "")
+        .split(/[—:.;]/u)[0]
+        ?.trim() ?? "";
+    const words = stripped.split(/\s+/u).filter((word) => word.length > 0);
+    const short = words.slice(0, 4).join(" ");
+    const label = short.length === 0
+        ? `Step ${index + 1}`
+        : short.replace(/["`]/gu, "");
+    return label.length > 48 ? `${label.slice(0, 45)}...` : label;
+}
+const MERMAID_PROCESS_MAX_NODES = 10;
+function renderProcessFlowMermaid(executionModel) {
+    if (executionModel.processFlow && executionModel.processFlow.trim().length > 0) {
+        return `\`\`\`mermaid\n${executionModel.processFlow.trim()}\n\`\`\``;
+    }
+    const source = executionModel.process.length > 0
+        ? executionModel.process
+        : executionModel.checklist;
+    if (source.length === 0) {
+        return "";
+    }
+    const limited = source.slice(0, MERMAID_PROCESS_MAX_NODES);
+    const nodes = limited.map((item, index) => ({
+        id: `S${index + 1}`,
+        label: mermaidNodeLabel(item, index)
+    }));
+    const lines = ["flowchart TD"];
+    for (const node of nodes) {
+        lines.push(`  ${node.id}["${node.label}"]`);
+    }
+    for (let i = 0; i < nodes.length - 1; i += 1) {
+        lines.push(`  ${nodes[i].id} --> ${nodes[i + 1].id}`);
+    }
+    if (source.length > MERMAID_PROCESS_MAX_NODES) {
+        lines.push(`  S${nodes.length} --> More["...see full Checklist"]`);
+    }
+    return `\`\`\`mermaid\n${lines.join("\n")}\n\`\`\``;
+}
+function renderPlatformNotesBlock(notes) {
+    if (!notes || notes.length === 0) {
+        return "";
+    }
+    const body = notes.map((item) => `- ${item}`).join("\n");
+    return `## Platform Notes
+${body}
+
+`;
+}
 function dedupeGuidance(items, blockedBy) {
     const blocked = new Set(blockedBy
         .map((item) => normalizedGuidanceKey(item))
@@ -345,7 +398,8 @@ export function stageSkillMarkdown(stage, track = "standard") {
         .map((item, i) => `${i + 1}. ${item}`)
         .join("\n");
     const interactionFocus = dedupeGuidance(executionModel.interactionProtocol, [...executionModel.checklist, ...executionModel.process]).slice(0, 5);
-    const processSummary = dedupeGuidance(executionModel.process, executionModel.checklist).slice(0, 5);
+    const processFlowMermaid = renderProcessFlowMermaid(executionModel);
+    const platformNotesBlock = renderPlatformNotesBlock(executionModel.platformNotes);
     const stageRefs = stageSpecificSeeAlso(stage);
     const reviewLoopSection = reviewLoopBlock(reviewLens.reviewLoop);
     const mandatoryDelegationSummary = mandatoryDelegations.length > 0
@@ -386,7 +440,10 @@ ${philosophy.hardGate}
 ${mergedAntiPatterns(philosophy, executionModel)}
 
 ## Process
-${processSummary.length > 0 ? processSummary.map((item, i) => `${i + 1}. ${item}`).join("\n") : "1. Execute the Checklist in order.\n2. Satisfy every required gate.\n3. Complete verification before stage closeout."}
+
+This is the stage **state machine** — the canonical ordered flow. For every detailed step, gate, and wording, follow the Checklist below; this diagram is the map, not the territory.
+
+${processFlowMermaid.length > 0 ? processFlowMermaid : "```mermaid\nflowchart TD\n  S1[\"Execute Checklist\"] --> S2[\"Satisfy required gates\"] --> S3[\"Verify before closeout\"]\n```"}
 
 ## Inputs
 ${executionModel.inputs.length > 0 ? executionModel.inputs.map((item) => `- ${item}`).join("\n") : "- (first stage — no required inputs)"}
@@ -394,7 +451,7 @@ ${executionModel.inputs.length > 0 ? executionModel.inputs.map((item) => `- ${it
 ## Required Context
 ${executionModel.requiredContext.length > 0 ? executionModel.requiredContext.map((item) => `- ${item}`).join("\n") : "- None beyond this skill"}
 
-${contextLoadingBlock(artifactRules.crossStageTrace)}
+${platformNotesBlock}${contextLoadingBlock(artifactRules.crossStageTrace)}
 ${autoSubagentDispatchBlock(stage, track)}
 ${researchPlaybooksBlock(executionModel.researchPlaybooks ?? [])}
 
@@ -407,6 +464,9 @@ ${checklistItems}
 ${stageExamples(stage)}
 
 ## Interaction Protocol
+
+These are **rules for HOW you interact with the user** during this stage — tone, question shape, decision gating. Ordered steps of *what to do* live in the Checklist; do not treat these as an alternative sequence.
+
 ${interactionFocus.length > 0 ? interactionFocus.map((item, i) => `${i + 1}. ${item}`).join("\n") : "- Keep communication concise and decision-focused; rely on the Checklist for execution order."}
 
 Decision protocol reference: \`${DECISION_PROTOCOL_PATH}\`

package/dist/content/stage-schema.js

@@ -224,6 +224,8 @@ function normalizeStageSchemaInput(value) {
         whenNotToUse: value.philosophy.whenNotToUse,
         interactionProtocol: value.executionModel.interactionProtocol,
         process: value.executionModel.process,
+        processFlow: value.executionModel.processFlow,
+        platformNotes: value.executionModel.platformNotes,
         requiredGates: value.executionModel.requiredGates,
         requiredEvidence: value.executionModel.requiredEvidence,
         inputs: value.executionModel.inputs,
@@ -445,6 +447,8 @@ export function stageSchema(stage, track = "standard") {
     const executionModel = {
         interactionProtocol: base.interactionProtocol,
         process: base.process,
+        processFlow: base.processFlow,
+        platformNotes: base.platformNotes,
         checklist: base.checklist,
         requiredGates: tieredGates,
         requiredEvidence: base.requiredEvidence,

package/dist/content/stages/brainstorm.js

@@ -119,6 +119,11 @@ export const BRAINSTORM = {
             "required gates marked satisfied",
             "no implementation action taken",
             "artifact reviewed by user"
+        ],
+        platformNotes: [
+            "Write artifact paths in POSIX form (`.cclaw/artifacts/01-brainstorm-<slug>.md`) even on Windows — the runtime normalizes separators. Do NOT commit Windows-style backslashes into the artifact or flow-state.",
+            "Slugify titles with lowercase ASCII letters, digits, and single dashes only — avoid spaces and case-sensitive names so the file resolves identically on case-insensitive filesystems (macOS/Windows default).",
+            "When linking to files inside the artifact, use repo-relative forward-slash paths (`src/foo/bar.ts`) so reviewers on any OS can click through."
         ]
     },
     artifactRules: {

package/dist/content/stages/design.js

@@ -142,6 +142,11 @@ export const DESIGN = {
             "required gates marked satisfied",
             "completion dashboard present with all review-section statuses",
             "artifact complete for spec handoff"
+        ],
+        platformNotes: [
+            "Architecture diagrams (ASCII, Mermaid) must use plain ASCII punctuation — avoid smart quotes and em-dashes that render differently across Windows CMD (cp1252), macOS Terminal (UTF-8), and Linux consoles.",
+            "When referencing build or runtime tools in the design, name them by binary (`node`, `python`, `go`) rather than by IDE-specific run configurations (`npm: start (WebStorm)`, `launch.json:Debug`) so the design stays OS-agnostic.",
+            "File system layouts drawn in the artifact use forward slashes; explicitly note when a platform-specific path style is required (e.g. Windows long-path `\\\\?\\` prefix, macOS bundle `.app/Contents/MacOS/`)."
         ]
     },
     artifactRules: {

package/dist/content/stages/plan.js

@@ -100,6 +100,11 @@ export const PLAN = {
             "WAIT_FOR_CONFIRM present and unresolved until user approves",
             "artifact ready for TDD execution",
             "acceptance mapping complete"
+        ],
+        platformNotes: [
+            "Per-task verification commands must be runnable on Windows PowerShell, macOS bash/zsh, and Linux bash. Prefer `npm run <script>` / `pnpm <script>` / `pytest -k <name>` over raw shell one-liners so the command portability is handled by the script runner.",
+            "If a task command needs globbing, wrap the glob in single quotes on POSIX and escape as needed on PowerShell (`'src/**/*.ts'` vs `\"src/**/*.ts\"`). Note the quoting variant when the task is expected to run in mixed-OS CI.",
+            "Environment variables referenced from tasks must be named in uppercase with underscores (`CCLAW_PROJECT_ROOT`) and set via a cross-shell wrapper (e.g. `cross-env` for Node tasks) — do not inline `KEY=value cmd` style that fails in PowerShell/cmd.exe."
         ]
     },
     artifactRules: {

package/dist/content/stages/review.js

@@ -100,6 +100,11 @@ export const REVIEW = {
             "all review sections evaluated",
             "critical blockers resolved",
             "ship readiness explicitly stated"
+        ],
+        platformNotes: [
+            "When citing file locations in findings, use repo-relative forward-slash paths with a line number (`src/foo/bar.ts:42`). Avoid IDE-generated hyperlinks that embed absolute machine-specific paths.",
+            "Line-range or diff-range references must match `git diff --unified=0` output format so reviewers on any OS can reproduce the range locally without GUI tooling.",
+            "Commands in remediation suggestions must be portable (`npm run lint`, `pytest -x path/to/test`) — if a platform-specific command is required, tag the note explicitly (`# PowerShell only`, `# macOS only`)."
         ]
     },
     artifactRules: {

package/dist/content/stages/schema-types.d.ts

@@ -50,6 +50,14 @@ export interface StagePhilosophy {
 export interface StageExecutionModel {
     interactionProtocol: string[];
     process: string[];
+    /**
+     * Optional custom mermaid `flowchart` body (without the fenced `mermaid`
+     * code block) that overrides the auto-generated linear flowchart in the
+     * rendered `## Process` section. Use for stages whose state machine is
+     * non-linear (loops, conditional branches) — otherwise leave unset and
+     * let the renderer derive a simple `A --> B --> C` chart from `process`.
+     */
+    processFlow?: string;
     checklist: string[];
     requiredGates: StageGate[];
     requiredEvidence: string[];
@@ -58,6 +66,13 @@ export interface StageExecutionModel {
     researchPlaybooks?: string[];
     blockers: string[];
     exitCriteria: string[];
+    /**
+     * Optional platform-specific notes (Windows/macOS/Linux path separators,
+     * PowerShell vs cmd, harness-specific tool names). Rendered under
+     * "## Platform Notes" when present. Omit when the stage is
+     * platform-agnostic.
+     */
+    platformNotes?: string[];
 }
 export interface StageArtifactRules {
     artifactFile: string;
@@ -108,6 +123,10 @@ export interface StageSchema {
     whenNotToUse: string[];
     interactionProtocol: string[];
     process: string[];
+    /** See {@link StageExecutionModel.processFlow}. */
+    processFlow?: string;
+    /** See {@link StageExecutionModel.platformNotes}. */
+    platformNotes?: string[];
     requiredGates: StageGate[];
     requiredEvidence: string[];
     inputs: string[];

package/dist/content/stages/scope.js

@@ -133,6 +133,11 @@ export const SCOPE = {
             "locked decisions captured with stable D-XX IDs",
             "completion dashboard produced",
             "scope summary produced"
+        ],
+        platformNotes: [
+            "Scope contract paths must be repo-relative with forward slashes so they resolve identically on Windows, macOS, and Linux (`src/pkg/mod.ts`, NOT `src\\pkg\\mod.ts`).",
+            "When invoking `git log`/`git diff` for the Pre-Scope audit, wrap glob patterns in single quotes on POSIX shells and double quotes on PowerShell (`git log -- 'src/**/*.ts'` vs `git log -- \"src/**/*.ts\"`). Document the command with the quoting style you actually ran.",
+            "Do not hard-code machine-specific absolute paths (home dirs, drive letters) into the scope contract — keep boundaries repo-relative."
         ]
     },
     artifactRules: {

package/dist/content/stages/ship.js

@@ -92,6 +92,12 @@ export const SHIP = {
             "preflight completed",
             "rollback and release notes complete",
             "finalization action explicitly chosen and executed"
+        ],
+        platformNotes: [
+            "Release commands (`npm publish`, `git tag -s`, `gh release create`, `cargo publish`, `goreleaser`) behave the same across OSes, but signing keys differ: macOS Keychain, Windows credential store, Linux GPG agent. Verify the signing flow on the actual release machine before running the real publish.",
+            "Version tags must be pure ASCII and lowercase after an optional `v` prefix (`v1.2.3`, `v1.2.3-rc.1`). Avoid Unicode dashes and non-breaking spaces that sneak in via copy-paste from docs.",
+            "When the rollback plan references timestamps (CI run windows, DB snapshot IDs), pin them to UTC ISO-8601 so the plan reads identically across CI runners in different regions.",
+            "`gh release create` requires a repo-level `GH_TOKEN`/`GITHUB_TOKEN`; document whether it is sourced from the shell env, `.env`, or the OS keychain so another operator on a different OS can reproduce the release."
         ]
     },
     artifactRules: {

package/dist/content/stages/spec.js

@@ -40,6 +40,7 @@ export const SPEC = {
             "Capture edge cases — for each criterion, define at least one boundary condition and one error condition.",
             "Document constraints and assumptions — regulatory, system, integration, and performance boundaries. Surface implicit assumptions explicitly.",
             "Confirm testability — for each acceptance criterion, describe the test that would prove it. If untestable, rewrite the criterion.",
+            "Present acceptance criteria to the user in 3-5-item batches, pausing for explicit ACK between batches (see Interaction Protocol).",
             "Write spec artifact and request user approval — wait for explicit confirmation before proceeding."
         ],
         interactionProtocol: [
@@ -86,6 +87,11 @@ export const SPEC = {
             "required gates marked satisfied",
             "plan-ready acceptance mapping exists",
             "testability confirmed for all criteria"
+        ],
+        platformNotes: [
+            "Acceptance criteria that reference CLI commands must name the executable portably (`node`, `npm`, `pytest`) and avoid OS-specific shell features (`&&` is safe, `||` differs subtly between cmd.exe and POSIX — prefer explicit multi-step descriptions).",
+            "When a criterion specifies file-content expectations, use `LF` as the canonical newline and state any CRLF-on-Windows tolerance explicitly (most git-managed repos normalize via `.gitattributes`; the criterion should not implicitly depend on autocrlf).",
+            "Timezone-sensitive criteria (timestamps, retention windows) must pin UTC or note the source of truth — clocks differ across CI runners (GitHub macOS vs Linux image vs Windows image)."
         ]
     },
     artifactRules: {

package/dist/content/stages/tdd.js

@@ -103,6 +103,12 @@ export const TDD = {
             "REFACTOR evidence captured",
             "required gates marked satisfied",
             "traceability annotated"
+        ],
+        platformNotes: [
+            "Record the **exact** test command run (`npm test -- path/to/file`, `pytest path/to/file`, `go test ./...`) so RED/GREEN evidence is reproducible on any OS. Do not paraphrase to a shorter alias.",
+            "Line-ending drift (CRLF vs LF) can turn a passing test red on Windows if the repo mixes styles. When a GREEN flip happens only after whitespace normalization, record it as a refactor note, not a hidden fix.",
+            "When invoking a test file path from Windows PowerShell, use forward slashes (`npm test -- tests/foo.test.ts`) — backslashes trip globbing on `cross-env` and similar wrappers.",
+            "Flaky tests that only fail on one OS must be marked as such in the TDD artifact (OS + runner + one failing output snippet) — do not retry until green without evidence."
         ]
     },
     artifactRules: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.48.32",
+  "version": "0.48.34",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {