cclaw-cli 0.55.2 → 1.0.0

package/dist/content/node-hooks.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import { DEFAULT_COMPOUND_RECURRENCE_THRESHOLD, DEFAULT_EARLY_LOOP_MAX_ITERATIONS } 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, EARLY_LOOP_INLINE_SOURCE } from "./hook-inline-snippets.js";
+import { SHARED_FLOW_AND_KNOWLEDGE_SNIPPETS, SHARED_STAGE_SUPPORT_SNIPPETS } from "./runtime-shared-snippets.js";
 function normalizePatterns(patterns, fallback) {
     if (!patterns || patterns.length === 0)
         return [...fallback];
@@ -84,6 +84,9 @@ const EARLY_LOOP_MAX_ITERATIONS = ${JSON.stringify(earlyLoopMaxIterations)};
 const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliRuntime.entrypoint)};
 const CCLAW_CLI_ARGS_PREFIX = ${JSON.stringify(cliRuntime.argsPrefix)};
 
+${SHARED_FLOW_AND_KNOWLEDGE_SNIPPETS}
+${SHARED_STAGE_SUPPORT_SNIPPETS}
+
 function resolveStrictness() {
   return process.env.CCLAW_STRICTNESS === "strict" ? "strict" : DEFAULT_STRICTNESS;
 }
@@ -427,6 +430,73 @@ async function runCclawInternal(root, args, options = {}) {
   });
 }
 
+function compactStderr(value) {
+  const raw = typeof value === "string" ? value : "";
+  return raw.replace(/\\s+/gu, " ").trim();
+}
+
+function summarizeInternalFailure(operation, result) {
+  const detail = compactStderr(result && typeof result === "object" ? result.stderr : "");
+  return detail.length > 0 ? operation + ": " + detail : operation + " failed";
+}
+
+function parseJsonStdoutObject(result) {
+  const raw = typeof (result && result.stdout) === "string" ? result.stdout.trim() : "";
+  if (raw.length === 0) return null;
+  try {
+    return toObject(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+function firstStdoutLine(value) {
+  const raw = typeof value === "string" ? value : "";
+  const lines = raw
+    .split(/\\r?\\n/gu)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  return lines[0] || "";
+}
+
+function formatRalphLoopStatusLineFromJson(status) {
+  const redOpenSlices = Array.isArray(status.redOpenSlices)
+    ? status.redOpenSlices.filter((value) => typeof value === "string")
+    : [];
+  const redOpen = redOpenSlices.length > 0 ? redOpenSlices.join(",") : "none";
+  const loopIteration =
+    typeof status.loopIteration === "number" && Number.isFinite(status.loopIteration)
+      ? Math.trunc(status.loopIteration)
+      : 0;
+  const sliceCount =
+    typeof status.sliceCount === "number" && Number.isFinite(status.sliceCount)
+      ? Math.trunc(status.sliceCount)
+      : 0;
+  const acClosed = Array.isArray(status.acClosed) ? status.acClosed.length : 0;
+  return "Ralph Loop: iter=" + String(loopIteration) +
+    ", slices=" + String(sliceCount) +
+    ", acClosed=" + String(acClosed) +
+    ", redOpen=" + redOpen;
+}
+
+function formatEarlyLoopStatusLineFromJson(status) {
+  const stage = typeof status.stage === "string" ? status.stage : "unknown";
+  const iteration =
+    typeof status.iteration === "number" && Number.isFinite(status.iteration)
+      ? Math.trunc(status.iteration)
+      : 0;
+  const maxIterations =
+    typeof status.maxIterations === "number" && Number.isFinite(status.maxIterations)
+      ? Math.trunc(status.maxIterations)
+      : EARLY_LOOP_MAX_ITERATIONS;
+  const openConcerns = Array.isArray(status.openConcerns) ? status.openConcerns.length : 0;
+  const convergence = status.convergenceTripped === true ? "tripped" : "clear";
+  return "Early Loop: stage=" + stage +
+    ", iter=" + String(iteration) + "/" + String(maxIterations) +
+    ", open=" + String(openConcerns) +
+    ", convergence=" + convergence;
+}
+
 function detectHarness(env) {
   if (env.CLAUDE_PROJECT_DIR) return "claude";
   if (env.CURSOR_PROJECT_DIR || env.CURSOR_PROJECT_ROOT) return "cursor";
@@ -839,12 +909,12 @@ async function readFlowState(root) {
   // empty object. Silent fallbacks used to mask stale CLI+hook drift.
   const parsed = await readJsonFile(statePath, {}, { root, stage: "read-flow-state" });
   const obj = toObject(parsed) || {};
-  const completed = Array.isArray(obj.completedStages) ? obj.completedStages : [];
+  const summary = summarizeFlowState(obj);
   return {
     filePath: statePath,
-    currentStage: typeof obj.currentStage === "string" ? obj.currentStage : "none",
-    activeRunId: typeof obj.activeRunId === "string" ? obj.activeRunId : "active",
-    completedCount: completed.length,
+    currentStage: summary.stage,
+    activeRunId: summary.activeRunId === "none" ? "active" : summary.activeRunId,
+    completedCount: summary.completed,
     raw: obj
   };
 }
@@ -857,44 +927,16 @@ async function buildKnowledgeDigest(root, currentStage, prereadRaw) {
   const raw = typeof prereadRaw === "string"
     ? prereadRaw
     : await readTextFile(knowledgeFile, "");
-  const lines = raw.split(/\\r?\\n/gu).map((line) => line.trim()).filter((line) => line.length > 0);
-  let learningsCount = 0;
-  const parsedRows = [];
-  for (const line of lines) {
-    if (line.startsWith("{")) learningsCount += 1;
-    try {
-      const parsed = JSON.parse(line);
-      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
-      parsedRows.push(parsed);
-    } catch {
-      // ignore malformed knowledge line in digest
-    }
-  }
-  const relevant = parsedRows
-    .filter((row) => {
-      const stage = typeof row.stage === "string" ? row.stage : null;
-      return stage === null || stage === currentStage;
-    })
-    .slice(-6)
-    .reverse()
-    .map((row) => {
-      const confidence = typeof row.confidence === "string" ? row.confidence : "unknown";
-      const stage = typeof row.stage === "string" ? row.stage : "global";
-      const domain = typeof row.domain === "string" ? row.domain : "general";
-      const trigger = typeof row.trigger === "string" ? row.trigger : "trigger";
-      const action = typeof row.action === "string" ? row.action : "action";
-      return "- [" + confidence + " • " + stage + " • " + domain + "] " + trigger + " -> " + action;
-    });
+  const digest = parseKnowledgeDigest(raw, currentStage, 6);
   return {
-    digestLines: relevant,
-    learningsCount
+    digestLines: digest.lines,
+    learningsCount: digest.learningsCount
   };
 }
 
 async function readStageSupportContext(root, currentStage) {
-  const stage = typeof currentStage === "string" ? currentStage : "";
-  const validStages = new Set(["brainstorm", "scope", "design", "spec", "plan", "tdd", "review", "ship"]);
-  if (!validStages.has(stage)) return [];
+  if (!isKnownStageId(currentStage)) return [];
+  const stage = currentStage;
 
   const parts = [];
   const contractPath = path.join(root, RUNTIME_ROOT, "templates", "state-contracts", stage + ".json");
@@ -906,12 +948,7 @@ async function readStageSupportContext(root, currentStage) {
     );
   }
 
-  const reviewPromptByStage = {
-    brainstorm: "brainstorm-self-review.md",
-    scope: "scope-ceo-review.md",
-    design: "design-eng-review.md"
-  };
-  const promptName = reviewPromptByStage[stage];
+  const promptName = reviewPromptFileName(stage);
   if (typeof promptName === "string") {
     const promptPath = path.join(root, RUNTIME_ROOT, "skills", "review-prompts", promptName);
     const prompt = (await readTextFile(promptPath, "")).trim();
@@ -952,15 +989,19 @@ async function handleSessionStart(runtime) {
   let earlyLoopLine = "";
   if (state.currentStage === "tdd") {
     try {
-      const ralphStatus = await computeRalphLoopStatusInline(stateDir, state.activeRunId);
-      await writeJsonFile(path.join(stateDir, "ralph-loop.json"), ralphStatus);
-      const redOpen = ralphStatus.redOpenSlices.length > 0
-        ? ralphStatus.redOpenSlices.join(",")
-        : "none";
-      ralphLoopLine = "Ralph Loop: iter=" + String(ralphStatus.loopIteration) +
-        ", slices=" + String(ralphStatus.sliceCount) +
-        ", acClosed=" + String(ralphStatus.acClosed.length) +
-        ", redOpen=" + redOpen;
+      const internalRalph = await runCclawInternal(
+        runtime.root,
+        ["tdd-loop-status", "--json", "--write"],
+        { captureStdout: true }
+      );
+      if (internalRalph.code !== 0) {
+        throw new Error(summarizeInternalFailure("tdd-loop-status", internalRalph));
+      }
+      const ralphStatus = parseJsonStdoutObject(internalRalph);
+      if (!ralphStatus) {
+        throw new Error("tdd-loop-status returned empty or malformed JSON");
+      }
+      ralphLoopLine = formatRalphLoopStatusLineFromJson(ralphStatus);
     } catch (err) {
       // Best-effort — a malformed cycle log should never break
       // session-start. But we DO leave a breadcrumb in
@@ -978,14 +1019,27 @@ async function handleSessionStart(runtime) {
     (state.currentStage === "brainstorm" || state.currentStage === "scope" || state.currentStage === "design")
   ) {
     try {
-      const earlyLoopStatus = await computeEarlyLoopStatusInline(
-        stateDir,
-        state.currentStage,
-        state.activeRunId,
-        EARLY_LOOP_MAX_ITERATIONS
+      const internalEarly = await runCclawInternal(
+        runtime.root,
+        [
+          "early-loop-status",
+          "--json",
+          "--write",
+          "--stage",
+          state.currentStage,
+          "--run-id",
+          state.activeRunId
+        ],
+        { captureStdout: true }
       );
-      await writeJsonFile(path.join(stateDir, "early-loop.json"), earlyLoopStatus);
-      earlyLoopLine = formatEarlyLoopStatusLineInline(earlyLoopStatus);
+      if (internalEarly.code !== 0) {
+        throw new Error(summarizeInternalFailure("early-loop-status", internalEarly));
+      }
+      const earlyLoopStatus = parseJsonStdoutObject(internalEarly);
+      if (!earlyLoopStatus) {
+        throw new Error("early-loop-status returned empty or malformed JSON");
+      }
+      earlyLoopLine = formatEarlyLoopStatusLineFromJson(earlyLoopStatus);
     } catch (err) {
       await recordHookError(
         runtime.root,
@@ -1000,32 +1054,17 @@ async function handleSessionStart(runtime) {
   // where lifting becomes relevant; earlier stages update the file silently.
   let compoundReadinessLine = "";
   try {
-    let readiness = null;
+    const shouldShowReadiness = state.currentStage === "review" || state.currentStage === "ship";
     const internalReadiness = await runCclawInternal(
       runtime.root,
-      ["compound-readiness", "--json"],
+      shouldShowReadiness ? ["compound-readiness"] : ["compound-readiness", "--quiet"],
       { captureStdout: true }
     );
-    if (internalReadiness.code === 0 && internalReadiness.stdout.trim().length > 0) {
-      try {
-        const parsed = JSON.parse(internalReadiness.stdout);
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-          readiness = parsed;
-        }
-      } catch {
-        readiness = null;
-      }
-    }
-    if (!readiness) {
-      const archivedRunsCount = await countArchivedRunsInline(runtime.root);
-      readiness = await computeCompoundReadinessInline(runtime.root, {
-        prereadRaw: knowledgeRaw,
-        ...(typeof archivedRunsCount === "number" ? { archivedRunsCount } : {})
-      });
-      await writeJsonFile(path.join(stateDir, "compound-readiness.json"), readiness);
+    if (internalReadiness.code !== 0) {
+      throw new Error(summarizeInternalFailure("compound-readiness", internalReadiness));
     }
-    if (state.currentStage === "review" || state.currentStage === "ship") {
-      compoundReadinessLine = formatCompoundReadinessLineInline(toObject(readiness) || {});
+    if (shouldShowReadiness) {
+      compoundReadinessLine = firstStdoutLine(internalReadiness.stdout);
     }
   } catch (err) {
     // Best-effort — a malformed knowledge.jsonl must never break
@@ -1063,8 +1102,8 @@ async function handleSessionStart(runtime) {
       "/8 completed, run=" +
       state.activeRunId +
       "). Active artifacts: " +
-      RUNTIME_ROOT +
-      "/artifacts/. Learnings: " +
+      activeArtifactsPathLabel(RUNTIME_ROOT) +
+      " Learnings: " +
       String(knowledge.learningsCount) +
       " entries."
   ];
@@ -1169,7 +1208,7 @@ async function handleStopHandoff(runtime) {
   const shipSubstate = typeof closeoutObj.shipSubstate === "string" ? closeoutObj.shipSubstate : "idle";
   const closeoutContext =
     state.currentStage === "ship" || shipSubstate !== "idle"
-      ? " closeout.shipSubstate=" + shipSubstate + "; closeout chain=retro -> compound -> archive; continue closeout with /cc."
+      ? " closeout.shipSubstate=" + shipSubstate + "; closeout chain=post_ship_review -> archive; continue closeout with /cc."
       : "";
 
   const message =
@@ -1246,17 +1285,6 @@ async function handlePromptGuard(runtime) {
   return 0;
 }
 
-// Inline mirrors of canonical CLI computations (compound-readiness,
-// ralph-loop, early-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}
-${EARLY_LOOP_INLINE_SOURCE}
-
 async function hasFailingRedEvidenceForPath(stateDir, runId, rawPath) {
   const cycleRaw = await readTextFile(path.join(stateDir, "tdd-cycle-log.jsonl"), "");
   for (const line of cycleRaw.split(/\\r?\\n/gu)) {
@@ -1468,8 +1496,14 @@ async function handleWorkflowGuard(runtime) {
       // writes that actually belonged to a new, not-yet-red S-2. Now
       // we reuse the canonical Ralph Loop status: if NO slice has an
       // open RED, we block.
-      const ralphStatus = await computeRalphLoopStatusInline(stateDir, currentRun);
-      if (!ralphStatus.redOpen) {
+      const internalRalph = await runCclawInternal(
+        runtime.root,
+        ["tdd-loop-status", "--json", "--no-write"],
+        { captureStdout: true }
+      );
+      const ralphStatus = parseJsonStdoutObject(internalRalph);
+      const redOpen = internalRalph.code === 0 && ralphStatus?.redOpen === true;
+      if (!redOpen) {
         reasons.push("tdd_write_without_open_red");
       }
     }

package/dist/content/opencode-plugin.js

@@ -1,5 +1,6 @@
 import { RUNTIME_ROOT } from "../constants.js";
 import { META_SKILL_NAME } from "./meta-skill.js";
+import { SHARED_FLOW_AND_KNOWLEDGE_SNIPPETS, SHARED_STAGE_SUPPORT_SNIPPETS } from "./runtime-shared-snippets.js";
 export function opencodePluginJs(_options = {}) {
     return `// cclaw OpenCode plugin — generated by npx cclaw-cli sync
 import { appendFileSync, existsSync, mkdirSync } from "node:fs";
@@ -16,13 +17,8 @@ export default function cclawPlugin(ctx) {
   const flowStatePath = join(stateDir, "flow-state.json");
   const knowledgePath = join(runtimeDir, "knowledge.jsonl");
   const metaSkillPath = join(runtimeDir, "skills/${META_SKILL_NAME}/SKILL.md");
-  const STAGE_IDS = ["brainstorm", "scope", "design", "spec", "plan", "tdd", "review", "ship"];
-  const REVIEW_PROMPT_BY_STAGE = {
-    brainstorm: "brainstorm-self-review.md",
-    scope: "scope-ceo-review.md",
-    design: "design-eng-review.md"
-  };
-  const REVIEW_PROMPT_FILES = Object.values(REVIEW_PROMPT_BY_STAGE);
+  ${SHARED_FLOW_AND_KNOWLEDGE_SNIPPETS}
+  ${SHARED_STAGE_SUPPORT_SNIPPETS}
 
   function ensureRuntimeDirs() {
     try {
@@ -61,14 +57,9 @@ export default function cclawPlugin(ctx) {
   async function readFlowState() {
     try {
       const raw = await readFile(flowStatePath, "utf8");
-      const state = JSON.parse(raw);
-      return {
-        stage: typeof state.currentStage === "string" ? state.currentStage : "none",
-        completed: Array.isArray(state.completedStages) ? state.completedStages.length : 0,
-        activeRunId: typeof state.activeRunId === "string" ? state.activeRunId : "none"
-      };
+      return summarizeFlowState(JSON.parse(raw));
     } catch {
-      return { stage: "none", completed: 0, activeRunId: "none" };
+      return summarizeFlowState({});
     }
   }
 
@@ -80,18 +71,13 @@ export default function cclawPlugin(ctx) {
     }
   }
 
-  async function readTailLines(filePath, maxLines) {
-    const text = (await readFileText(filePath)).trim();
-    if (!text) return [];
-    return text.split(/\\r?\\n/).slice(-maxLines);
-  }
-
-  async function readKnowledgeDigest() {
-    return readTailLines(knowledgePath, 12);
+  async function readKnowledgeDigest(stage) {
+    const raw = await readFileText(knowledgePath);
+    return parseKnowledgeDigest(raw, stage, 6).lines;
   }
 
   async function readStageSupportContext(stage) {
-    if (typeof stage !== "string" || !STAGE_IDS.includes(stage)) return [];
+    if (!isKnownStageId(stage)) return [];
     const parts = [];
     const contract = (await readFileText(join(runtimeDir, "templates/state-contracts", stage + ".json"))).trim();
     if (contract.length > 0) {
@@ -100,7 +86,7 @@ export default function cclawPlugin(ctx) {
           contract
       );
     }
-    const reviewPromptName = REVIEW_PROMPT_BY_STAGE[stage];
+    const reviewPromptName = reviewPromptFileName(stage);
     if (reviewPromptName) {
       const prompt = (await readFileText(join(runtimeDir, "skills/review-prompts", reviewPromptName))).trim();
       if (prompt.length > 0) {
@@ -119,12 +105,12 @@ export default function cclawPlugin(ctx) {
     const flow = await readFlowState();
     const parts = [
       BOOTSTRAP_MARKER,
-      \`cclaw loaded. Flow: stage=\${flow.stage} (\${flow.completed}/8 completed, run=\${flow.activeRunId}). Active artifacts: ${RUNTIME_ROOT}/artifacts/\`
+      \`cclaw loaded. Flow: stage=\${flow.stage} (\${flow.completed}/8 completed, run=\${flow.activeRunId}). Active artifacts: \${activeArtifactsPathLabel("${RUNTIME_ROOT}")}\`
     ];
 
 
 
-    const knowledge = await readKnowledgeDigest();
+    const knowledge = await readKnowledgeDigest(flow.stage);
     if (knowledge.length > 0) parts.push("Knowledge digest (top relevant entries):", ...knowledge);
 
     const stageSupport = await readStageSupportContext(flow.stage);

package/dist/content/reference-patterns.js

@@ -201,7 +201,7 @@ export const REFERENCE_PATTERNS = [
                     "Review source-item coverage by vertical slice, not by file count alone.",
                     "A slice is review-ready only when RED, GREEN, REFACTOR, and verification evidence all line up."
                 ],
-                artifactSections: ["Completeness Snapshot", "Trace Matrix Check"]
+                artifactSections: ["Completeness Snapshot", "Coverage Check"]
             }
         ]
     },
@@ -348,7 +348,7 @@ export const REFERENCE_PATTERNS = [
             {
                 stage: "review",
                 guidance: [
-                    "Victory Detector: Layer 1, Layer 2, security sweep, structured findings, and trace evidence are complete with no unresolved criticals unless verdict is BLOCKED.",
+                    "Victory Detector: Layer 1, Layer 2, security sweep, structured findings, and acceptance/reproduction coverage evidence are complete with no unresolved criticals unless verdict is BLOCKED.",
                     "If the detector fails, iterate findings or route back to TDD; do not say LGTM."
                 ],
                 artifactSections: ["Review Readiness Snapshot", "Final Verdict"]

package/dist/content/runtime-shared-snippets.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared runtime snippets interpolated into generated hook/plugin scripts.
+ *
+ * Keep these string helpers minimal and dependency-free so both runtimes
+ * (node hooks and OpenCode plugin) stay in sync without duplicating constants.
+ */
+export declare const SHARED_FLOW_AND_KNOWLEDGE_SNIPPETS = "\nfunction summarizeFlowState(rawState) {\n  const state =\n    rawState && typeof rawState === \"object\" && !Array.isArray(rawState)\n      ? rawState\n      : {};\n  return {\n    stage: typeof state.currentStage === \"string\" ? state.currentStage : \"none\",\n    completed: Array.isArray(state.completedStages) ? state.completedStages.length : 0,\n    activeRunId: typeof state.activeRunId === \"string\" ? state.activeRunId : \"none\"\n  };\n}\n\nfunction parseKnowledgeDigest(rawKnowledge, currentStage, maxRows = 6) {\n  const text = typeof rawKnowledge === \"string\" ? rawKnowledge : \"\";\n  if (text.trim().length === 0) {\n    return { learningsCount: 0, lines: [] };\n  }\n  const rows = text\n    .split(/\\r?\\n/gu)\n    .map((line) => line.trim())\n    .filter((line) => line.length > 0);\n  let learningsCount = 0;\n  const parsedRows = [];\n  for (const line of rows) {\n    if (line.startsWith(\"{\")) learningsCount += 1;\n    try {\n      const parsed = JSON.parse(line);\n      if (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) continue;\n      parsedRows.push(parsed);\n    } catch {\n      // ignore malformed knowledge line in digest\n    }\n  }\n  const lines = parsedRows\n    .filter((row) => {\n      const stage = typeof row.stage === \"string\" ? row.stage : null;\n      return stage === null || stage === currentStage;\n    })\n    .slice(-maxRows)\n    .reverse()\n    .map((row) => {\n      const confidence = typeof row.confidence === \"string\" ? row.confidence : \"unknown\";\n      const stage = typeof row.stage === \"string\" ? row.stage : \"global\";\n      const trigger = typeof row.trigger === \"string\" ? row.trigger : \"trigger\";\n      const action = typeof row.action === \"string\" ? row.action : \"action\";\n      return \"- [\" + confidence + \" \u2022 \" + stage + \"] \" + trigger + \" -> \" + action;\n    });\n  return { learningsCount, lines };\n}\n\nfunction activeArtifactsPathLabel(runtimeRoot) {\n  return String(runtimeRoot || \".cclaw\") + \"/artifacts/\";\n}\n";
+export declare const SHARED_STAGE_SUPPORT_SNIPPETS = "\nconst STAGE_IDS = [\"brainstorm\", \"scope\", \"design\", \"spec\", \"plan\", \"tdd\", \"review\", \"ship\"];\nconst REVIEW_PROMPT_BY_STAGE = {\n  brainstorm: \"brainstorm-self-review.md\",\n  scope: \"scope-ceo-review.md\",\n  design: \"design-eng-review.md\"\n};\nconst REVIEW_PROMPT_FILES = Object.values(REVIEW_PROMPT_BY_STAGE);\n\nfunction isKnownStageId(stage) {\n  return typeof stage === \"string\" && STAGE_IDS.includes(stage);\n}\n\nfunction reviewPromptFileName(stage) {\n  if (!isKnownStageId(stage)) return null;\n  const name = REVIEW_PROMPT_BY_STAGE[stage];\n  return typeof name === \"string\" ? name : null;\n}\n";

package/dist/content/runtime-shared-snippets.js

@@ -0,0 +1,80 @@
+/**
+ * Shared runtime snippets interpolated into generated hook/plugin scripts.
+ *
+ * Keep these string helpers minimal and dependency-free so both runtimes
+ * (node hooks and OpenCode plugin) stay in sync without duplicating constants.
+ */
+export const SHARED_FLOW_AND_KNOWLEDGE_SNIPPETS = `
+function summarizeFlowState(rawState) {
+  const state =
+    rawState && typeof rawState === "object" && !Array.isArray(rawState)
+      ? rawState
+      : {};
+  return {
+    stage: typeof state.currentStage === "string" ? state.currentStage : "none",
+    completed: Array.isArray(state.completedStages) ? state.completedStages.length : 0,
+    activeRunId: typeof state.activeRunId === "string" ? state.activeRunId : "none"
+  };
+}
+
+function parseKnowledgeDigest(rawKnowledge, currentStage, maxRows = 6) {
+  const text = typeof rawKnowledge === "string" ? rawKnowledge : "";
+  if (text.trim().length === 0) {
+    return { learningsCount: 0, lines: [] };
+  }
+  const rows = text
+    .split(/\\r?\\n/gu)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  let learningsCount = 0;
+  const parsedRows = [];
+  for (const line of rows) {
+    if (line.startsWith("{")) learningsCount += 1;
+    try {
+      const parsed = JSON.parse(line);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+      parsedRows.push(parsed);
+    } catch {
+      // ignore malformed knowledge line in digest
+    }
+  }
+  const lines = parsedRows
+    .filter((row) => {
+      const stage = typeof row.stage === "string" ? row.stage : null;
+      return stage === null || stage === currentStage;
+    })
+    .slice(-maxRows)
+    .reverse()
+    .map((row) => {
+      const confidence = typeof row.confidence === "string" ? row.confidence : "unknown";
+      const stage = typeof row.stage === "string" ? row.stage : "global";
+      const trigger = typeof row.trigger === "string" ? row.trigger : "trigger";
+      const action = typeof row.action === "string" ? row.action : "action";
+      return "- [" + confidence + " • " + stage + "] " + trigger + " -> " + action;
+    });
+  return { learningsCount, lines };
+}
+
+function activeArtifactsPathLabel(runtimeRoot) {
+  return String(runtimeRoot || ".cclaw") + "/artifacts/";
+}
+`;
+export const SHARED_STAGE_SUPPORT_SNIPPETS = `
+const STAGE_IDS = ["brainstorm", "scope", "design", "spec", "plan", "tdd", "review", "ship"];
+const REVIEW_PROMPT_BY_STAGE = {
+  brainstorm: "brainstorm-self-review.md",
+  scope: "scope-ceo-review.md",
+  design: "design-eng-review.md"
+};
+const REVIEW_PROMPT_FILES = Object.values(REVIEW_PROMPT_BY_STAGE);
+
+function isKnownStageId(stage) {
+  return typeof stage === "string" && STAGE_IDS.includes(stage);
+}
+
+function reviewPromptFileName(stage) {
+  if (!isKnownStageId(stage)) return null;
+  const name = REVIEW_PROMPT_BY_STAGE[stage];
+  return typeof name === "string" ? name : null;
+}
+`;

package/dist/content/session-hooks.js

@@ -66,7 +66,7 @@ When resuming work after a break:
 
 ### Optional session-history scan for compound
 
-During post-ship \`compound_review\`, ask before scanning external session history. If the user opts in, inspect only relevant Cursor/Claude/Codex transcripts for repeated failures or process lessons, summarize matches, and then apply the same overlap/refresh/supersede rules before touching \`.cclaw/knowledge.jsonl\`.
+During post-ship \`post_ship_review\`, ask before scanning external session history. If the user opts in, inspect only relevant Cursor/Claude/Codex transcripts for repeated failures or process lessons, summarize matches, and then apply the same overlap/refresh/supersede rules before touching \`.cclaw/knowledge.jsonl\`.
 
 ## Context Management
 

package/dist/content/skills.d.ts

@@ -10,3 +10,4 @@ export declare function noPlaceholdersBlock(): string;
 export declare function watchedFailProofBlock(): string;
 export declare function stageSkillFolder(stage: FlowStage): string;
 export declare function stageSkillMarkdown(stage: FlowStage, track?: FlowTrack): string;
+export declare function executingWavesSkillMarkdown(): string;

package/dist/content/skills.js

@@ -607,3 +607,53 @@ ${reviewSectionsBlock(reviewLens.reviewSections)}
 - Keep decisions explicit: context, options, chosen option, rationale, risk, and rollback.
 `;
 }
+export function executingWavesSkillMarkdown() {
+    return `---
+name: executing-waves
+description: "Execute multi-wave work using existing cclaw run resume + verify-current-state — no new CLI needed."
+---
+
+# Executing Waves (Persistent Multi-Wave Work)
+
+## Overview
+
+Long-form work (large refactors, multi-stage uplifts) often spans many waves.
+This skill documents how the controller persists work across waves WITHOUT new
+CLI commands, using existing \`cclaw run resume\` and \`internal verify-current-state\`.
+
+## When to Use
+
+- Work spans 2+ commits / waves with cohesion concerns between waves.
+- Each wave has its own stage cycle (brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship).
+- User wants explicit per-wave verification before the next wave starts.
+- Risk of cross-wave drift exists.
+
+## Anti-Pattern
+
+- Running many waves linearly without verification between them, accumulating drift.
+- Treating a wave as only a commit boundary without re-verifying upstream decisions.
+
+## Process
+
+1. **Wave Start**: author wave plan as \`.cclaw/wave-plans/<wave-n>.md\` referencing previous wave's ship artifact.
+2. **Carry-forward Audit**: at brainstorm of the next wave, re-read previous wave ship artifact and explicitly record:
+   - Carrying forward: <locked decisions still valid>
+   - Drift detected: <decisions no longer valid + reason>
+   - Re-scope needed: <yes/no>
+3. **Resume Path**: if a wave was interrupted mid-stage, \`cclaw run resume\` restores state. Run \`internal verify-current-state\` before continuing.
+4. **Wave End**: at ship, architect cross-stage verification runs from dispatch matrix. If \`DRIFT_DETECTED\`, fix before ship.
+5. **Next Wave Trigger**: launch new \`/cc <topic>\` for next wave and reference previous wave ship artifact in upstream handoff.
+
+## Status Markers
+
+- \`wave-status: in-progress\` — current stage incomplete.
+- \`wave-status: blocked-by-prev\` — waiting on previous wave verification.
+- \`wave-status: shipped\` — wave shipped, next wave can start.
+- \`wave-status: rolled-back\` — previous wave invalidated, current wave needs rebase.
+
+## Linter Hooks
+
+- If multi-wave work is detected (>1 wave-plan files in \`.cclaw/wave-plans/\`), current brainstorm artifact MUST contain \`## Wave Carry-forward\` section with drift audit.
+- If carry-forward drift is missing in multi-wave context, emit \`[P1] wave.drift_unaddressed\`.
+`;
+}