cclaw-cli 0.51.30 → 1.0.0

package/dist/content/node-hooks.js

@@ -1,10 +1,10 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { DEFAULT_COMPOUND_RECURRENCE_THRESHOLD } from "../config.js";
+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 } 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];
@@ -51,6 +51,12 @@ export function nodeHookRuntimeScript(options = {}) {
         options.compoundRecurrenceThreshold >= 1
         ? options.compoundRecurrenceThreshold
         : DEFAULT_COMPOUND_RECURRENCE_THRESHOLD;
+    const earlyLoopEnabled = options.earlyLoopEnabled !== false;
+    const earlyLoopMaxIterations = typeof options.earlyLoopMaxIterations === "number" &&
+        Number.isInteger(options.earlyLoopMaxIterations) &&
+        options.earlyLoopMaxIterations >= 1
+        ? options.earlyLoopMaxIterations
+        : DEFAULT_EARLY_LOOP_MAX_ITERATIONS;
     const cliRuntime = resolveCliRuntimeForGeneratedHook();
     return `#!/usr/bin/env node
 import fs from "node:fs/promises";
@@ -73,9 +79,14 @@ const DEFAULT_TDD_PRODUCTION_PATH_PATTERNS = ${JSON.stringify(tddProductionPathP
 const COMPOUND_RECURRENCE_THRESHOLD = ${JSON.stringify(compoundRecurrenceThreshold)};
 const SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD = ${JSON.stringify(SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD)};
 const SMALL_PROJECT_RECURRENCE_THRESHOLD = ${JSON.stringify(SMALL_PROJECT_RECURRENCE_THRESHOLD)};
+const EARLY_LOOP_ENABLED = ${JSON.stringify(earlyLoopEnabled)};
+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;
 }
@@ -253,7 +264,7 @@ async function readJsonFile(filePath, fallback = {}, options = {}) {
     } catch (parseErr) {
       // Emit a diagnostic breadcrumb instead of silently returning fallback.
       // The hook must still continue (soft-fail), but the corruption is
-      // now visible in \`state/hook-errors.jsonl\` and to \`cclaw doctor\`.
+      // now visible in \`state/hook-errors.jsonl\` and to \`npx cclaw-cli sync\`.
       if (options.root) {
         await recordHookError(
           options.root,
@@ -419,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";
@@ -684,7 +762,6 @@ function detectTargetStage(payloadLower) {
 }
 
 function isFlowProgressionCommand(payloadLower) {
-  if (/(\\/cc-next|cc-next)([^a-z0-9_-]|$)/u.test(payloadLower)) return true;
   return /\\/cc([^a-z0-9_-]|$)/u.test(payloadLower);
 }
 
@@ -832,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
   };
 }
@@ -850,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");
@@ -899,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();
@@ -942,21 +986,26 @@ async function handleSessionStart(runtime) {
   // both read a consistent "iter=N, acClosed=[...]" snapshot. Runs only when
   // we are in tdd — other stages skip the write to keep the file stable.
   let ralphLoopLine = "";
+  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
-      // hook-errors.jsonl so \`cclaw doctor\` can surface chronic
+      // hook-errors.jsonl so \`npx cclaw-cli sync\` can surface chronic
       // failures (previously this was a silent swallow).
       await recordHookError(
         runtime.root,
@@ -965,44 +1014,63 @@ async function handleSessionStart(runtime) {
       );
     }
   }
+  if (
+    EARLY_LOOP_ENABLED &&
+    (state.currentStage === "brainstorm" || state.currentStage === "scope" || state.currentStage === "design")
+  ) {
+    try {
+      const internalEarly = await runCclawInternal(
+        runtime.root,
+        [
+          "early-loop-status",
+          "--json",
+          "--write",
+          "--stage",
+          state.currentStage,
+          "--run-id",
+          state.activeRunId
+        ],
+        { captureStdout: true }
+      );
+      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,
+        "session-start:early-loop",
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+  }
 
   // Keep compound-readiness.json fresh on every session-start (cheap derived
   // summary). Surface a one-line nudge only from review and ship stages
   // 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 (internalReadiness.code !== 0) {
+      throw new Error(summarizeInternalFailure("compound-readiness", internalReadiness));
     }
-    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 (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
     // session-start. But we DO leave a breadcrumb in
     // hook-errors.jsonl so config/IO problems become visible in
-    // \`cclaw doctor\` instead of silently degrading readiness output.
+    // \`npx cclaw-cli sync\` instead of silently degrading readiness output.
     await recordHookError(
       runtime.root,
       "session-start:compound-readiness",
@@ -1034,14 +1102,17 @@ async function handleSessionStart(runtime) {
       "/8 completed, run=" +
       state.activeRunId +
       "). Active artifacts: " +
-      RUNTIME_ROOT +
-      "/artifacts/. Learnings: " +
+      activeArtifactsPathLabel(RUNTIME_ROOT) +
+      " Learnings: " +
       String(knowledge.learningsCount) +
       " entries."
   ];
   if (ralphLoopLine.length > 0) {
     parts.push(ralphLoopLine);
   }
+  if (earlyLoopLine.length > 0) {
+    parts.push(earlyLoopLine);
+  }
   if (compoundReadinessLine.length > 0) {
     parts.push(compoundReadinessLine);
   }
@@ -1049,7 +1120,7 @@ async function handleSessionStart(runtime) {
     parts.push(
       "Stale stages pending acknowledgement: " +
         staleStageNames.join(", ") +
-        " (use cclaw internal rewind --ack <stage> after redo)."
+        " (use npx cclaw-cli internal rewind --ack <stage> after redo)."
     );
   }
   if (knowledge.digestLines.length > 0) {
@@ -1137,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 =
@@ -1214,15 +1285,6 @@ async function handlePromptGuard(runtime) {
   return 0;
 }
 
-// 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"), "");
   for (const line of cycleRaw.split(/\\r?\\n/gu)) {
@@ -1401,7 +1463,7 @@ async function handleWorkflowGuard(runtime) {
     /^(read|readfile|open|view|cat|shell|runcommand|run_command|execcommand|exec_command|terminal)$/u.test(
       toolLower
     ) &&
-    /(\\.cclaw\\/state\\/flow-state\\.json|cclaw doctor|cclaw sync)/u.test(payloadLower);
+    /(\\.cclaw\\/state\\/flow-state\\.json|npx cclaw-cli sync|npx cclaw-cli sync|npx cclaw-cli sync|cclaw sync)/u.test(payloadLower);
   if (shouldRecordFlowRead) {
     await writeJsonFile(guardStateFile, {
       ...guardState,
@@ -1434,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,19 +105,19 @@ 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);
     if (stageSupport.length > 0) parts.push(...stageSupport);
 
     parts.push(
-      "If you discover a non-obvious rule or pattern during stage work, add it to the current artifact ## Learnings section; stage-complete harvests it into .cclaw/knowledge.jsonl. If this plugin does not load, run \`cclaw sync\`, verify opencode.json(.c) includes the cclaw plugin registration, then run \`cclaw doctor --explain\`. Direct JSONL append is only for explicit manual learnings operations."
+      "If you discover a non-obvious rule or pattern during stage work, add it to the current artifact ## Learnings section; stage-complete harvests it into .cclaw/knowledge.jsonl. If this plugin does not load, run \`npx cclaw-cli sync\`, verify opencode.json(.c) includes the cclaw plugin registration, then run \`npx cclaw-cli sync\`. Direct JSONL append is only for explicit manual learnings operations."
     );
 
     const meta = (await readFileText(metaSkillPath)).trim();
@@ -510,7 +496,7 @@ export default function cclawPlugin(ctx) {
     notInitializedAdvised = true;
     logToFile(
       "guards skipped: cclaw is not initialized in this project. " +
-      "Run \`cclaw init\` in " + root + " to activate flow enforcement."
+      "Run \`npx cclaw-cli init\` in " + root + " to activate flow enforcement."
     );
   }
 
@@ -697,7 +683,7 @@ export default function cclawPlugin(ctx) {
         throw new Error(
           "cclaw " + failed + " blocked tool.execute.before.\\n" +
           "Reason: " + detail + "\\n" +
-          "Diagnose: run \`npx cclaw-cli doctor\` in project root.\\n" +
+          "Diagnose: run \`npx cclaw-cli sync\` in project root.\\n" +
           "Bypass (temporary): export CCLAW_DISABLE=1 before starting OpenCode,\\n" +
           "or set \`strictness: advisory\` in .cclaw/config.yaml."
         );

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;