cclaw-cli 0.48.23 → 0.48.25

package/dist/content/doctor-references.js

@@ -124,7 +124,8 @@ Reference docs for \`cclaw doctor\` checks.
 
 Earlier releases relied on \`bash\` to execute generated shell hooks and on
 \`python3\`/\`jq\` as JSON fallback parsers. Node-only mode removes both: hooks
-dispatch through \`node .cclaw/hooks/run-hook.mjs <hook-name>\`, so these tools
+dispatch through \`.cclaw/hooks/run-hook.cmd <hook-name>\` (which forwards to
+Node), so these tools
 are no longer part of the supported runtime contract.
 
 ## Typical fixes

package/dist/content/hooks.d.ts

@@ -1,4 +1,5 @@
 export declare function stageCompleteScript(): string;
+export declare function runHookCmdScript(): string;
 export { claudeHooksJsonWithObservation as claudeHooksJson } from "./observe.js";
 export { cursorHooksJsonWithObservation as cursorHooksJson } from "./observe.js";
 export { codexHooksJsonWithObservation as codexHooksJson } from "./observe.js";

package/dist/content/hooks.js

@@ -120,6 +120,36 @@ async function main() {
 void main();
 `;
 }
+export function runHookCmdScript() {
+    return `: << 'CMDBLOCK'
+@echo off
+REM Cross-platform wrapper for cclaw Node hook runtime.
+REM Windows executes this batch block; Unix shells treat it as a heredoc comment.
+if "%~1"=="" (
+  echo [cclaw] run-hook.cmd: missing hook name >&2
+  exit /b 1
+)
+set "HOOK_DIR=%~dp0"
+set "RUNTIME=%HOOK_DIR%run-hook.mjs"
+where node >nul 2>nul
+if %ERRORLEVEL% neq 0 (
+  REM Best-effort: missing node should not block harness execution loops.
+  exit /b 0
+)
+node "%RUNTIME%" %*
+exit /b %ERRORLEVEL%
+CMDBLOCK
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+if [ "$#" -lt 1 ]; then
+  echo "[cclaw] run-hook.cmd: missing hook name" >&2
+  exit 1
+fi
+if ! command -v node >/dev/null 2>&1; then
+  exit 0
+fi
+exec node "\${SCRIPT_DIR}/run-hook.mjs" "$@"
+`;
+}
 export { claudeHooksJsonWithObservation as claudeHooksJson } from "./observe.js";
 export { cursorHooksJsonWithObservation as cursorHooksJson } from "./observe.js";
 export { codexHooksJsonWithObservation as codexHooksJson } from "./observe.js";

package/dist/content/meta-skill.js

@@ -40,6 +40,15 @@ If the current stage is ambiguous because \`flow-state.json\` is missing
 or corrupt, stop and route through \`/cc\` before any substantive
 response.
 
+## Red Flags (stop and re-route)
+
+If you think any of these, stop and follow the routing flow:
+
+- "This looks simple, I can skip the stage." -> No. Route through \`/cc\`.
+- "I can answer from memory without loading the active stage skill." -> No. Load the skill first.
+- "Hook guard warned, but I can ignore it." -> No. Resolve the warning before continuing.
+- "I'll edit \`.cclaw/state\` directly to move faster." -> No. Use managed commands only.
+
 ## Routing flow
 
 \`\`\`
@@ -72,6 +81,12 @@ Before stage work:
 2. If active stage exists, continue with \`/cc\` or \`/cc-next\`.
 3. Do not jump directly to stage-specific commands.
 
+## Platform reliability notes
+
+- Managed hook dispatch uses \`.cclaw/hooks/run-hook.cmd\` (cross-platform wrapper).
+- If hooks fail due missing runtime deps (for example \`node\` not on \`PATH\`), run \`cclaw doctor\` before continuing.
+- Prefer cross-platform commands in artifacts/examples (\`npm test\`, \`pnpm test\`, \`python -m pytest\`, etc.) over shell-specific aliases whenever possible.
+
 ## Stage quick map
 
 brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship

package/dist/content/node-hooks.js

@@ -307,10 +307,12 @@ async function readStdin() {
   });
 }
 
-async function runCclawInternal(root, args) {
+async function runCclawInternal(root, args, options = {}) {
   return await new Promise((resolve) => {
     const isWindows = process.platform === "win32";
+    const captureStdout = options && options.captureStdout === true;
     let settled = false;
+    let stdout = "";
     let stderr = "";
     const finalize = (value) => {
       if (settled) return;
@@ -325,18 +327,27 @@ async function runCclawInternal(root, args) {
         {
         cwd: root,
         env: process.env,
-        stdio: ["ignore", "ignore", "pipe"]
+        stdio: ["ignore", captureStdout ? "pipe" : "ignore", "pipe"]
       }
       );
     } catch (error) {
       const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
       finalize({
         code: 1,
+        stdout,
         stderr,
         missingBinary: code === "ENOENT" || (isWindows && code === "EINVAL")
       });
       return;
     }
+    if (captureStdout) {
+      child.stdout?.on("data", (chunk) => {
+        stdout += String(chunk ?? "");
+        if (stdout.length > 16000) {
+          stdout = stdout.slice(-16000);
+        }
+      });
+    }
     child.stderr?.on("data", (chunk) => {
       stderr += String(chunk ?? "");
       if (stderr.length > 8000) {
@@ -347,6 +358,7 @@ async function runCclawInternal(root, args) {
       const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
       finalize({
         code: 1,
+        stdout,
         stderr,
         missingBinary: code === "ENOENT" || (isWindows && code === "EINVAL")
       });
@@ -355,6 +367,7 @@ async function runCclawInternal(root, args) {
       if (signal) {
         finalize({
           code: 1,
+          stdout,
           stderr,
           missingBinary: false
         });
@@ -366,6 +379,7 @@ async function runCclawInternal(root, args) {
         : false;
       finalize({
         code: typeof code === "number" ? code : 1,
+        stdout,
         stderr,
         missingBinary
       });
@@ -380,6 +394,32 @@ function detectHarness(env) {
   return "codex";
 }
 
+function hookEventNameForOutput(hookName) {
+  if (hookName === "session-start") return "SessionStart";
+  if (hookName === "prompt-guard") return "PreToolUse";
+  if (hookName === "workflow-guard") return "PreToolUse";
+  if (hookName === "context-monitor") return "PostToolUse";
+  if (hookName === "stop-checkpoint") return "Stop";
+  if (hookName === "pre-compact") return "PreCompact";
+  if (hookName === "verify-current-state") return "UserPromptSubmit";
+  return "SessionStart";
+}
+
+function emitAdvisoryContext(runtime, hookName, note) {
+  const normalized = normalizeText(note);
+  if (normalized.length === 0) return;
+  if (runtime.harness === "claude" || runtime.harness === "codex") {
+    runtime.writeJson({
+      hookSpecificOutput: {
+        hookEventName: hookEventNameForOutput(hookName),
+        additionalContext: normalized
+      }
+    });
+    return;
+  }
+  runtime.writeJson({ additional_context: normalized });
+}
+
 async function detectRoot(env) {
   const candidates = [
     env.CCLAW_PROJECT_ROOT,
@@ -976,21 +1016,55 @@ async function handleSessionStart(runtime) {
   // where lifting becomes relevant; earlier stages update the file silently.
   let compoundReadinessLine = "";
   try {
-    const archivedRunsCount = await countArchivedRunsInline(runtime.root);
-    const readiness = await computeCompoundReadinessInline(runtime.root, {
-      prereadRaw: knowledgeRaw,
-      ...(typeof archivedRunsCount === "number" ? { archivedRunsCount } : {})
-    });
-    await writeJsonFile(path.join(stateDir, "compound-readiness.json"), readiness);
+    let readiness = null;
+    const internalReadiness = await runCclawInternal(
+      runtime.root,
+      ["compound-readiness", "--json"],
+      { 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);
+    }
+    const readinessObj = toObject(readiness) || {};
+    const ready = Array.isArray(readinessObj.ready) ? readinessObj.ready : [];
+    const readyCount =
+      typeof readinessObj.readyCount === "number" && Number.isFinite(readinessObj.readyCount)
+        ? Math.trunc(readinessObj.readyCount)
+        : ready.length;
+    const clusterCount =
+      typeof readinessObj.clusterCount === "number" && Number.isFinite(readinessObj.clusterCount)
+        ? Math.trunc(readinessObj.clusterCount)
+        : 0;
+    const threshold =
+      typeof readinessObj.threshold === "number" && Number.isFinite(readinessObj.threshold)
+        ? Math.trunc(readinessObj.threshold)
+        : COMPOUND_RECURRENCE_THRESHOLD;
     if (state.currentStage === "review" || state.currentStage === "ship") {
-      if (readiness.readyCount === 0) {
+      if (readyCount === 0) {
         compoundReadinessLine = "Compound readiness: no candidates (clusters=" +
-          String(readiness.clusterCount) + ", threshold=" + String(readiness.threshold) + ")";
+          String(clusterCount) + ", threshold=" + String(threshold) + ")";
       } else {
-        const critical = readiness.ready.filter((entry) => entry.severity === "critical").length;
+        const critical = ready.filter(
+          (entry) => entry && typeof entry === "object" && entry.severity === "critical"
+        ).length;
         const criticalSuffix = critical > 0 ? " (critical=" + String(critical) + ")" : "";
-        compoundReadinessLine = "Compound readiness: clusters=" + String(readiness.clusterCount) +
-          ", ready=" + String(readiness.readyCount) + criticalSuffix;
+        compoundReadinessLine = "Compound readiness: clusters=" + String(clusterCount) +
+          ", ready=" + String(readyCount) + criticalSuffix;
       }
     }
   } catch (err) {
@@ -1342,7 +1416,9 @@ async function handlePromptGuard(runtime) {
   const reasons = [];
 
   if (/^(write|edit|multiedit|multi_edit|delete|applypatch|runcommand|shell|terminal|execcommand)$/u.test(toolLower)) {
-    if (/\\.cclaw\\/(state|artifacts|hooks|skills|commands|agents|runs|knowledge)/u.test(payloadLower)) {
+    // Artifacts, runs, and knowledge writes are part of normal stage flow.
+    // Guard only managed internals that should be mutated via installer/CLI.
+    if (/\\.cclaw\\/(state|hooks|skills|commands|agents)/u.test(payloadLower)) {
       reasons.push("write_to_cclaw_runtime");
     }
   }
@@ -1356,7 +1432,7 @@ async function handlePromptGuard(runtime) {
       RUNTIME_ROOT +
       " runtime (" +
       reasons.join(",") +
-      "). Prefer installer commands or explicit confirmation before mutating runtime internals.";
+      "). Prefer installer commands before mutating managed runtime internals (.cclaw/state|hooks|skills|commands|agents).";
     await appendJsonLine(guardLog, {
       ts: new Date().toISOString(),
       harness: runtime.harness,
@@ -1364,6 +1440,8 @@ async function handlePromptGuard(runtime) {
       reasons,
       note
     });
+    const advisoryNote = mode === "strict" ? note + " Blocked by strict mode." : note;
+    emitAdvisoryContext(runtime, "prompt-guard", advisoryNote);
     if (mode === "strict") {
       process.stderr.write("[cclaw] " + note + " (blocked by strict mode)\\n");
       return 1;
@@ -1877,9 +1955,11 @@ async function handleWorkflowGuard(runtime) {
     }
 
     if (shouldBlock) {
+      emitAdvisoryContext(runtime, "workflow-guard", note + " Blocked by workflow guard.");
       process.stderr.write("[cclaw] " + note + " (blocked by workflow guard)\\n");
       return 1;
     }
+    emitAdvisoryContext(runtime, "workflow-guard", note);
     process.stderr.write("[cclaw] " + note + "\\n");
   }
 
@@ -1978,6 +2058,7 @@ async function handleContextMonitor(runtime) {
       remainingPercent,
       note
     });
+    emitAdvisoryContext(runtime, "context-monitor", note);
     process.stderr.write("[cclaw] " + note + "\\n");
     nextAdvisoryBand = band;
     nextAdvisoryAt = now.toISOString();
@@ -1998,10 +2079,24 @@ async function handleVerifyCurrentState(runtime) {
   const mode = resolveStrictness();
   const result = await runCclawInternal(runtime.root, ["verify-current-state", "--quiet"]);
   if (result.missingBinary) {
+    emitAdvisoryContext(
+      runtime,
+      "verify-current-state",
+      "Cclaw verify-current-state requires cclaw binary on PATH."
+    );
     process.stderr.write("[cclaw] hook: cclaw binary is required for verify-current-state\\n");
     return 1;
   }
   if (mode === "strict") {
+    if (result.code !== 0) {
+      emitAdvisoryContext(
+        runtime,
+        "verify-current-state",
+        result.stderr.trim().length > 0
+          ? result.stderr.trim()
+          : "Cclaw verify-current-state failed in strict mode."
+      );
+    }
     if (result.code !== 0 && result.stderr.trim().length > 0) {
       process.stderr.write(result.stderr);
     }

package/dist/content/observe.js

@@ -1,11 +1,9 @@
 import { RUNTIME_ROOT } from "../constants.js";
 import { HOOK_MANIFEST, groupBindingsByEvent } from "./hook-manifest.js";
 function hookDispatcherCommand(hookName) {
-    // RUNTIME_ROOT is a relative path (".cclaw") that currently contains no
-    // whitespace, so quoting is unnecessary inside the JSON-encoded command
-    // string. If RUNTIME_ROOT ever becomes configurable, wrap the path with
-    // JSON.stringify to survive spaces.
-    return `node ${RUNTIME_ROOT}/hooks/run-hook.mjs ${hookName}`;
+    // Dispatch through the polyglot .cmd wrapper so Windows harnesses can run
+    // hooks even when command execution happens under CMD-style shells.
+    return `${RUNTIME_ROOT}/hooks/run-hook.cmd ${hookName}`;
 }
 /**
  * Claude / Codex share the same outer envelope: each event is an

package/dist/content/skills.js

@@ -297,6 +297,34 @@ After T-3 REFACTOR, before declaring Batch 1 done:
 export function stageSkillFolder(stage) {
     return STAGE_TO_SKILL_FOLDER[stage];
 }
+function normalizedGuidanceKey(value) {
+    return value
+        .replace(/`[^`]+`/gu, " ")
+        .replace(/[*_]/gu, " ")
+        .replace(/[^a-z0-9]+/giu, " ")
+        .replace(/\s+/gu, " ")
+        .trim()
+        .toLowerCase();
+}
+function dedupeGuidance(items, blockedBy) {
+    const blocked = new Set(blockedBy
+        .map((item) => normalizedGuidanceKey(item))
+        .filter((item) => item.length > 0));
+    const seen = new Set();
+    const result = [];
+    for (const item of items) {
+        const key = normalizedGuidanceKey(item);
+        if (key.length === 0)
+            continue;
+        if (blocked.has(key))
+            continue;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(item);
+    }
+    return result;
+}
 export function stageSkillMarkdown(stage, track = "standard") {
     const schema = stageSchema(stage, track);
     const gateList = schema.requiredGates
@@ -308,6 +336,11 @@ export function stageSkillMarkdown(stage, track = "standard") {
     const checklistItems = schema.checklist
         .map((item, i) => `${i + 1}. ${item}`)
         .join("\n");
+    const interactionFocus = dedupeGuidance(schema.interactionProtocol, [...schema.checklist, ...schema.process]).slice(0, 5);
+    const processSummary = dedupeGuidance(schema.process, schema.checklist).slice(0, 5);
+    const processNote = schema.process.length > processSummary.length
+        ? `- Follow the Checklist above for remaining execution detail (+${schema.process.length - processSummary.length} condensed step${schema.process.length - processSummary.length === 1 ? "" : "s"}).`
+        : "";
     const stageRefs = stageSpecificSeeAlso(stage);
     return `---
 name: ${schema.skillName}
@@ -360,7 +393,7 @@ ${stageDomainExamples(stage)}
 ${stageExamples(stage)}
 
 ## Interaction Protocol
-${schema.interactionProtocol.map((item, i) => `${i + 1}. ${item}`).join("\n")}
+${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."}
 
 Shared decision/ask-user protocol:
 \`${DECISION_PROTOCOL_PATH}\`
@@ -373,7 +406,8 @@ ${gateList}
 ${evidenceList}
 
 ## Process
-${schema.process.map((item, i) => `${i + 1}. ${item}`).join("\n")}
+${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."}
+${processNote.length > 0 ? `\n${processNote}` : ""}
 
 ${reviewSectionsBlock(stage, track)}
 ${verificationBlock(stage)}

package/dist/doctor-registry.js

@@ -85,7 +85,7 @@ const RULES = [
         }
     },
     {
-        test: /^(meta_skill:|protocol:|stage_skill:|context_mode:|reference:)/,
+        test: /^(meta_skill:|protocol:|stage_skill:|context_mode:)/,
         metadata: {
             severity: "error",
             summary: "Routing skill and protocol integrity check.",
@@ -93,6 +93,21 @@ const RULES = [
             docRef: ref("harness-and-routing.md")
         }
     },
+    {
+        // `reference:*` checks (flow-map.md and similar overview documents)
+        // are useful to detect drift from the generated baseline, but they
+        // document the surface rather than gate it. A missing section here
+        // means the map is out of date, not that a runtime contract is
+        // broken — so they report as a warning instead of hard-failing
+        // doctor / CI. `cclaw sync` rewrites the file.
+        test: /^reference:/,
+        metadata: {
+            severity: "warning",
+            summary: "Reference/overview doc integrity (non-blocking).",
+            fix: "Run `cclaw sync` to regenerate the reference doc from the canonical source.",
+            docRef: ref("harness-and-routing.md")
+        }
+    },
     {
         test: /^delegation:/,
         metadata: {

package/dist/doctor.js

@@ -674,6 +674,7 @@ export async function doctorChecks(projectRoot, options = {}) {
     // Hook scripts
     for (const script of [
         "run-hook.mjs",
+        "run-hook.cmd",
         "stage-complete.mjs",
         "opencode-plugin.mjs"
     ]) {
@@ -1021,7 +1022,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         if (!(await exists(candidate)))
             continue;
         const content = await fs.readFile(candidate, "utf8");
-        if (/run-hook\.cmd|bash\s+\.cclaw\/hooks\//u.test(content)) {
+        if (/bash\s+\.cclaw\/hooks\/|\.cclaw\/hooks\/(?:session-start|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor)\.sh/u.test(content)) {
             legacyDispatchFiles.push(path.relative(projectRoot, candidate));
         }
     }
@@ -1029,7 +1030,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         name: "warning:windows:hook_dispatch_node_only",
         ok: legacyDispatchFiles.length === 0,
         details: legacyDispatchFiles.length === 0
-            ? "hook configs use node-dispatched .cclaw/hooks/run-hook.mjs commands"
+            ? "hook configs use managed .cclaw/hooks/run-hook.cmd dispatch commands"
             : `warning: legacy shell hook dispatch remains in ${legacyDispatchFiles.join(", ")}`
     });
     // Knowledge store exists (canonical JSONL, no markdown mirror)

package/dist/install.js

@@ -24,7 +24,7 @@ import { rewindCommandContract, rewindCommandSkillMarkdown } from "./content/rew
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
 import { ironLawRuntimeDocument, ironLawsSkillMarkdown } from "./content/iron-laws.js";
-import { stageCompleteScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
+import { stageCompleteScript, runHookCmdScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
 import { nodeHookRuntimeScript } from "./content/node-hooks.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { decisionProtocolMarkdown, completionProtocolMarkdown, ethosProtocolMarkdown } from "./content/protocols.js";
@@ -734,12 +734,14 @@ async function writeHooks(projectRoot, config) {
         tddProductionPathPatterns: config.tdd?.productionPathPatterns,
         compoundRecurrenceThreshold: config.compound?.recurrenceThreshold
     }));
+    await writeFileSafe(path.join(hooksDir, "run-hook.cmd"), runHookCmdScript());
     const opencodePluginSource = opencodePluginJs();
     await writeFileSafe(path.join(hooksDir, "opencode-plugin.mjs"), opencodePluginSource);
     try {
         for (const script of [
             "stage-complete.mjs",
             "run-hook.mjs",
+            "run-hook.cmd",
             "opencode-plugin.mjs"
         ]) {
             await fs.chmod(path.join(hooksDir, script), 0o755);
@@ -1440,7 +1442,7 @@ function isManagedRuntimeHookCommand(command) {
     // (e.g. `node .cclaw\hooks\run-hook.mjs ...`) still round-trip through
     // sync without being duplicated alongside freshly generated entries.
     const normalized = command.trim().replace(/\s+/gu, " ").replace(/\\/gu, "/");
-    if (/(^|\s)(?:node\s+)?(?:"|')?(?:\.\/)?\.cclaw\/hooks\/run-hook\.mjs(?:"|')?\s+(?:session-start|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor|verify-current-state)(?:\s|$)/u.test(normalized)) {
+    if (/(^|\s)(?:node\s+)?(?:"|')?(?:\.\/)?\.cclaw\/hooks\/run-hook\.(?:mjs|cmd)(?:"|')?\s+(?:session-start|stop-checkpoint|pre-compact|prompt-guard|workflow-guard|context-monitor|verify-current-state)(?:\s|$)/u.test(normalized)) {
         return true;
     }
     // Codex UserPromptSubmit non-blocking state nudge.

package/package.json

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