cclaw-cli 0.51.29 → 0.55.2

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

@@ -10,6 +10,8 @@
  *    `src/knowledge-store.ts::computeCompoundReadiness`.
  * 2. `computeRalphLoopStatusInline` mirrors
  *    `src/tdd-cycle.ts::computeRalphLoopStatus`.
+ * 3. `computeEarlyLoopStatusInline` mirrors
+ *    `src/early-loop.ts::computeEarlyLoopStatus`.
  *
  * Previously those bodies lived inline in `src/content/node-hooks.ts` — a
  * ~2000-line file — next to unrelated hook-handler code. Any silent drift
@@ -25,11 +27,12 @@
  *   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
+ * `tests/unit/ralph-loop-parity.test.ts` and
+ * `tests/unit/early-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`.
+ * 2. Re-run parity tests for the touched snippet.
  *
  * DO NOT inline tests here — keep the parity check in its dedicated test
  * file.
@@ -43,7 +46,7 @@
  *   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
+ *   `<root>/.cclaw/archive/` so both the hook and the CLI see the same
  *   `archivedRunsCount` for the small-project relaxation.
  * - `formatCompoundReadinessLineInline` mirrors the one-line summary shape
  *   used by `src/internal/compound-readiness.ts::formatCompoundReadinessLine`
@@ -54,11 +57,11 @@ function normalizeCompoundLastUpdatedAt(date) {
   return date.toISOString().replace(/\\.\\d{3}Z$/u, "Z");
 }
 
-// Count archived runs as sub-directories under \`.cclaw/runs/\`. Missing
+// Count archived runs as sub-directories under \`.cclaw/archive/\`. 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");
+  const dir = path.join(root, RUNTIME_ROOT, "archive");
   try {
     const entries = await fs.readdir(dir, { withFileTypes: true });
     return entries.filter((entry) => entry.isDirectory()).length;
@@ -300,3 +303,213 @@ async function computeRalphLoopStatusInline(stateDir, runId) {
   };
 }
 `;
+/**
+ * Inline mirror of `src/early-loop.ts::computeEarlyLoopStatus`.
+ *
+ * Parity enforced by
+ * `tests/unit/early-loop-parity.test.ts::early-loop parity`.
+ *
+ * Signature contract:
+ *   async function computeEarlyLoopStatusInline(stateDir, stageId, runId, maxIterations) -> EarlyLoopStatus
+ */
+export const EARLY_LOOP_INLINE_SOURCE = `
+function normalizeEarlyLoopSeverityInline(value) {
+  if (value === "critical" || value === "important" || value === "suggestion") {
+    return value;
+  }
+  return "important";
+}
+
+function normalizeEarlyLoopTextInline(value, fallback) {
+  if (typeof value !== "string") return fallback;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : fallback;
+}
+
+function stableConcernFallbackIdInline(locator, summary) {
+  const seed = (String(locator) + "::" + String(summary)).trim().toLowerCase();
+  let hash = 0;
+  for (let index = 0; index < seed.length; index += 1) {
+    hash = (Math.imul(31, hash) + seed.charCodeAt(index)) >>> 0;
+  }
+  return "C-" + hash.toString(16).padStart(8, "0");
+}
+
+function normalizeEarlyLoopConcernInline(row) {
+  if (!row || typeof row !== "object" || Array.isArray(row)) return null;
+  const locator = normalizeEarlyLoopTextInline(row.locator, "unknown-location");
+  const summary = normalizeEarlyLoopTextInline(row.summary, "missing-summary");
+  const id = typeof row.id === "string" && row.id.trim().length > 0
+    ? row.id.trim()
+    : stableConcernFallbackIdInline(locator, summary);
+  return {
+    id,
+    severity: normalizeEarlyLoopSeverityInline(row.severity),
+    locator,
+    summary
+  };
+}
+
+function normalizeEarlyLoopMaxIterationsInline(value) {
+  return Number.isInteger(value) && value >= 1 ? value : 3;
+}
+
+function earlyLoopSeverityWeightInline(value) {
+  if (value === "critical") return 3;
+  if (value === "important") return 2;
+  return 1;
+}
+
+function sortEarlyLoopConcernsInline(a, b) {
+  const severityDiff = earlyLoopSeverityWeightInline(b.severity) - earlyLoopSeverityWeightInline(a.severity);
+  if (severityDiff !== 0) return severityDiff;
+  if (a.firstSeenIteration !== b.firstSeenIteration) {
+    return a.firstSeenIteration - b.firstSeenIteration;
+  }
+  if (a.lastSeenIteration !== b.lastSeenIteration) {
+    return a.lastSeenIteration - b.lastSeenIteration;
+  }
+  return String(a.id).localeCompare(String(b.id), "en");
+}
+
+function formatEarlyLoopStatusLineInline(status) {
+  if (!status || typeof status !== "object") return "";
+  const convergence = status.convergenceTripped ? "tripped" : "clear";
+  return "Early Loop: stage=" + String(status.stage) +
+    ", iter=" + String(status.iteration) + "/" + String(status.maxIterations) +
+    ", open=" + String(Array.isArray(status.openConcerns) ? status.openConcerns.length : 0) +
+    ", convergence=" + convergence;
+}
+
+async function computeEarlyLoopStatusInline(stateDir, stageId, runId, maxIterations) {
+  const filePath = path.join(stateDir, "early-loop-log.jsonl");
+  const raw = await readTextFile(filePath, "");
+  const maxIters = normalizeEarlyLoopMaxIterationsInline(maxIterations);
+  const concernsMap = new Map();
+  let previousSnapshotKey = "";
+  let sameConcernStreak = 0;
+  let convergenceTripped = false;
+  let escalationReason = undefined;
+  let currentIteration = 0;
+  let lastSeenConcernIds = [];
+
+  for (const rawLine of raw.split(/\\r?\\n/gu)) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+    const rowRunId = typeof parsed.runId === "string" && parsed.runId.trim().length > 0
+      ? parsed.runId.trim()
+      : "active";
+    const rowStage = typeof parsed.stage === "string" && parsed.stage.trim().length > 0
+      ? parsed.stage.trim()
+      : "brainstorm";
+    if (rowRunId !== runId || rowStage !== stageId) continue;
+
+    currentIteration += 1;
+    const iteration = Number.isInteger(parsed.iteration) && parsed.iteration >= 1
+      ? parsed.iteration
+      : currentIteration;
+    const seenThisIteration = new Set();
+    const concerns = Array.isArray(parsed.concerns) ? parsed.concerns : [];
+    for (const rawConcern of concerns) {
+      const concern = normalizeEarlyLoopConcernInline(rawConcern);
+      if (!concern) continue;
+      seenThisIteration.add(concern.id);
+      const existing = concernsMap.get(concern.id);
+      if (!existing) {
+        concernsMap.set(concern.id, {
+          id: concern.id,
+          severity: concern.severity,
+          locator: concern.locator,
+          summary: concern.summary,
+          firstSeenIteration: iteration,
+          lastSeenIteration: iteration
+        });
+        continue;
+      }
+      existing.lastSeenIteration = iteration;
+      existing.locator = concern.locator;
+      existing.summary = concern.summary;
+      if (earlyLoopSeverityWeightInline(concern.severity) >= earlyLoopSeverityWeightInline(existing.severity)) {
+        existing.severity = concern.severity;
+      }
+      delete existing.resolvedAtIteration;
+    }
+
+    const resolvedConcernIds = Array.isArray(parsed.resolvedConcernIds)
+      ? parsed.resolvedConcernIds
+          .filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+          .map((entry) => entry.trim())
+      : [];
+    for (const concernId of resolvedConcernIds) {
+      const existing = concernsMap.get(concernId);
+      if (!existing) continue;
+      if (seenThisIteration.has(concernId)) continue;
+      if (existing.resolvedAtIteration === undefined) {
+        existing.resolvedAtIteration = iteration;
+      }
+    }
+
+    for (const concern of concernsMap.values()) {
+      if (concern.resolvedAtIteration !== undefined) continue;
+      if (seenThisIteration.has(concern.id)) continue;
+      concern.resolvedAtIteration = iteration;
+    }
+
+    const openConcernIds = Array.from(concernsMap.values())
+      .filter((concern) => concern.resolvedAtIteration === undefined)
+      .map((concern) => concern.id)
+      .sort((a, b) => String(a).localeCompare(String(b), "en"));
+    lastSeenConcernIds = openConcernIds;
+    const snapshotKey = openConcernIds.join("|");
+    if (snapshotKey.length > 0 && snapshotKey === previousSnapshotKey) {
+      sameConcernStreak += 1;
+      if (!convergenceTripped && sameConcernStreak >= 2) {
+        convergenceTripped = true;
+        escalationReason = "same concerns " + String(sameConcernStreak) + " iterations in a row";
+      }
+    } else {
+      sameConcernStreak = snapshotKey.length > 0 ? 1 : 0;
+    }
+    previousSnapshotKey = snapshotKey;
+  }
+
+  const openConcerns = Array.from(concernsMap.values())
+    .filter((concern) => concern.resolvedAtIteration === undefined)
+    .sort(sortEarlyLoopConcernsInline);
+  const resolvedConcerns = Array.from(concernsMap.values())
+    .filter((concern) => concern.resolvedAtIteration !== undefined)
+    .sort((a, b) => {
+      if (a.resolvedAtIteration !== b.resolvedAtIteration) {
+        return a.resolvedAtIteration - b.resolvedAtIteration;
+      }
+      return sortEarlyLoopConcernsInline(a, b);
+    });
+
+  if (!convergenceTripped && openConcerns.length > 0 && currentIteration >= maxIters) {
+    convergenceTripped = true;
+    escalationReason = "max iterations " + String(maxIters) +
+      " reached with " + String(openConcerns.length) + " open concern(s)";
+  }
+
+  return {
+    schemaVersion: 1,
+    stage: stageId,
+    runId,
+    iteration: currentIteration,
+    maxIterations: maxIters,
+    openConcerns,
+    resolvedConcerns,
+    lastSeenConcernIds,
+    convergenceTripped,
+    ...(escalationReason ? { escalationReason } : {}),
+    lastUpdatedAt: new Date().toISOString()
+  };
+}
+`;

package/dist/content/hook-manifest.d.ts

@@ -5,7 +5,7 @@
  *
  *  - the per-harness JSON generators in `./observe.ts`
  *    (claude/cursor/codex hook documents),
- *  - the semantic coverage map in `./hook-events.ts` (docs + doctor),
+ *  - the semantic coverage map in `./hook-events.ts` (docs + sync/runtime checks),
  *  - the `requiredEvents` list embedded in `src/hook-schemas/*.v1.json`
  *    (enforced by a parity test).
  *
@@ -74,6 +74,6 @@ export declare function groupBindingsByEvent(harness: HookManifestHarness): Even
 /** Distinct harness-native event names covered by the manifest. */
 export declare function requiredEventsFor(harness: HookManifestHarness): string[];
 /**
- * Human-readable per-harness semantic coverage used by docs and doctor output.
+ * Human-readable per-harness semantic coverage used by docs and sync/runtime diagnostics.
  */
 export declare function semanticEventCoverage(harness: HookManifestHarness): Partial<Record<HookSemanticEvent, string>>;

package/dist/content/hook-manifest.js

@@ -5,7 +5,7 @@
  *
  *  - the per-harness JSON generators in `./observe.ts`
  *    (claude/cursor/codex hook documents),
- *  - the semantic coverage map in `./hook-events.ts` (docs + doctor),
+ *  - the semantic coverage map in `./hook-events.ts` (docs + sync/runtime checks),
  *  - the `requiredEvents` list embedded in `src/hook-schemas/*.v1.json`
  *    (enforced by a parity test).
  *
@@ -177,7 +177,7 @@ export function requiredEventsFor(harness) {
     return ordered;
 }
 /**
- * Human-readable per-harness semantic coverage used by docs and doctor output.
+ * Human-readable per-harness semantic coverage used by docs and sync/runtime diagnostics.
  */
 export function semanticEventCoverage(harness) {
     const out = {};

package/dist/content/hooks.d.ts

@@ -1,4 +1,5 @@
 export declare function startFlowScript(): string;
+export declare function cancelRunScript(): string;
 export declare function stageCompleteScript(): string;
 export declare function delegationRecordScript(): string;
 export declare function runHookCmdScript(): string;

package/dist/content/hooks.js

@@ -26,7 +26,7 @@ function resolveCliRuntimeForGeneratedHook() {
     }
     return { entrypoint: null, argsPrefix: [] };
 }
-function internalHelperScript(helperName, internalSubcommand, usage) {
+function internalHelperScript(helperName, internalSubcommand, usage, options) {
     const cliRuntime = resolveCliRuntimeForGeneratedHook();
     return `#!/usr/bin/env node
 import fs from "node:fs/promises";
@@ -40,6 +40,8 @@ const CCLAW_CLI_ARGS_PREFIX = ${JSON.stringify(cliRuntime.argsPrefix)};
 const HELPER_NAME = ${JSON.stringify(helperName)};
 const INTERNAL_SUBCOMMAND = ${JSON.stringify(internalSubcommand)};
 const USAGE = ${JSON.stringify(usage)};
+const POSITIONAL_ARG_NAME = ${JSON.stringify(options?.positionalArgName ?? null)};
+const POSITIONAL_ARG_REQUIRED = ${JSON.stringify(options?.positionalArgRequired === true)};
 
 async function detectRoot() {
   const candidates = [
@@ -69,11 +71,22 @@ function printUsage() {
 }
 
 async function main() {
-  const [, , ...flags] = process.argv;
-  if (flags.includes("--help") || flags.includes("-h")) {
+  const [, , ...argvTokens] = process.argv;
+  if (argvTokens.includes("--help") || argvTokens.includes("-h")) {
     printUsage();
     return;
   }
+  let positionalArg = "";
+  let flags = argvTokens;
+  if (POSITIONAL_ARG_NAME !== null) {
+    positionalArg = (argvTokens[0] ?? "").trim();
+    flags = argvTokens.slice(1);
+    if (POSITIONAL_ARG_REQUIRED && positionalArg.length === 0) {
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+  }
 
   const root = await detectRoot();
   const runtimePath = path.join(root, RUNTIME_ROOT);
@@ -112,7 +125,12 @@ async function main() {
     return;
   }
 
-  const child = spawn(process.execPath, [cliEntrypoint, ...cliArgsPrefix, "internal", INTERNAL_SUBCOMMAND, ...flags], {
+  const internalArgs =
+    POSITIONAL_ARG_NAME !== null
+      ? [INTERNAL_SUBCOMMAND, positionalArg, ...flags]
+      : [INTERNAL_SUBCOMMAND, ...flags];
+
+  const child = spawn(process.execPath, [cliEntrypoint, ...cliArgsPrefix, "internal", ...internalArgs], {
     cwd: root,
     env: process.env,
     stdio: "inherit"
@@ -124,7 +142,7 @@ async function main() {
     const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
     if (code === "ENOENT") {
       process.stderr.write(
-        "[cclaw] " + HELPER_NAME + ": node executable not found while invoking local runtime. Re-run npx cclaw-cli doctor.\\n"
+        "[cclaw] " + HELPER_NAME + ": node executable not found while invoking local runtime. Re-run npx cclaw-cli sync.\\n"
       );
     } else {
       process.stderr.write(
@@ -155,137 +173,14 @@ void main();
 export function startFlowScript() {
     return internalHelperScript("start-flow", "start-flow", "Usage: node " + RUNTIME_ROOT + "/hooks/start-flow.mjs --track=<standard|medium|quick> [--class=...] [--prompt=...] [--stack=...] [--reason=...] [--reclassify] [--force-reset]");
 }
-export function stageCompleteScript() {
-    const cliRuntime = resolveCliRuntimeForGeneratedHook();
-    return `#!/usr/bin/env node
-import fs from "node:fs/promises";
-import path from "node:path";
-import process from "node:process";
-import { spawn } from "node:child_process";
-
-const RUNTIME_ROOT = ${JSON.stringify(RUNTIME_ROOT)};
-const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliRuntime.entrypoint)};
-const CCLAW_CLI_ARGS_PREFIX = ${JSON.stringify(cliRuntime.argsPrefix)};
-
-async function detectRoot() {
-  const candidates = [
-    process.env.CCLAW_PROJECT_ROOT,
-    process.env.CLAUDE_PROJECT_DIR,
-    process.env.CURSOR_PROJECT_DIR,
-    process.env.CURSOR_PROJECT_ROOT,
-    process.env.OPENCODE_PROJECT_DIR,
-    process.env.OPENCODE_PROJECT_ROOT,
-    process.cwd()
-  ].filter((value) => typeof value === "string" && value.length > 0);
-
-  for (const candidate of candidates) {
-    try {
-      const runtimePath = path.join(candidate, RUNTIME_ROOT);
-      const stat = await fs.stat(runtimePath);
-      if (stat.isDirectory()) return candidate;
-    } catch {
-      // continue
-    }
-  }
-  return candidates[0] || process.cwd();
+export function cancelRunScript() {
+    return internalHelperScript("cancel-run", "cancel-run", "Usage: node " + RUNTIME_ROOT + "/hooks/cancel-run.mjs --reason=<text> [--disposition=<cancelled|abandoned>] [--name=<slug>]");
 }
-
-function printUsage() {
-  process.stderr.write(
-    "Usage: node " +
-      RUNTIME_ROOT +
-      "/hooks/stage-complete.mjs <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...] [--json]\\n"
-  );
-}
-
-async function main() {
-  const [, , stage, ...flags] = process.argv;
-  if (!stage || stage.trim().length === 0) {
-    printUsage();
-    process.exitCode = 1;
-    return;
-  }
-
-  const root = await detectRoot();
-  const runtimePath = path.join(root, RUNTIME_ROOT);
-  try {
-    const stat = await fs.stat(runtimePath);
-    if (!stat.isDirectory()) throw new Error("not-dir");
-  } catch {
-    process.stderr.write("[cclaw] stage-complete: runtime root not found at " + runtimePath + "\\n");
-    process.exitCode = 1;
-    return;
-  }
-
-  const cliEntrypoint = process.env.CCLAW_CLI_JS || CCLAW_CLI_ENTRYPOINT;
-  const cliArgsPrefix = process.env.CCLAW_CLI_JS ? [] : CCLAW_CLI_ARGS_PREFIX;
-  if (!cliEntrypoint || cliEntrypoint.trim().length === 0) {
-    process.stderr.write(
-      "[cclaw] stage-complete: local Node runtime entrypoint is missing. Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
-    );
-    process.exitCode = 1;
-    return;
-  }
-
-  try {
-    const stat = await fs.stat(cliEntrypoint);
-    if (!stat.isFile()) throw new Error("not-file");
-    for (const argPath of cliArgsPrefix) {
-      if (typeof argPath !== "string" || argPath.startsWith("-")) continue;
-      const argStat = await fs.stat(argPath);
-      if (!argStat.isFile()) throw new Error("arg-not-file");
-    }
-  } catch {
-    process.stderr.write(
-      "[cclaw] stage-complete: local Node runtime entrypoint not found at " + cliEntrypoint + ". Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
-    );
-    process.exitCode = 1;
-    return;
-  }
-
-  const child = spawn(
-    process.execPath,
-    [cliEntrypoint, ...cliArgsPrefix, "internal", "advance-stage", stage, ...flags],
-    {
-    cwd: root,
-    env: process.env,
-    stdio: "inherit"
-  }
-  );
-  let spawnErrored = false;
-
-  child.on("error", (error) => {
-    spawnErrored = true;
-    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "";
-    if (code === "ENOENT") {
-      process.stderr.write(
-        "[cclaw] stage-complete: node executable not found while invoking local runtime. Re-run npx cclaw-cli doctor.\\n"
-      );
-    } else {
-      process.stderr.write(
-        "[cclaw] stage-complete: failed to invoke local Node advance-stage runtime (" +
-          (error instanceof Error ? error.message : String(error)) +
-          ").\\n"
-      );
-    }
-    process.exitCode = 1;
-  });
-
-  child.on("close", (code, signal) => {
-    if (spawnErrored) {
-      process.exitCode = 1;
-      return;
-    }
-    if (signal) {
-      process.exitCode = 1;
-      return;
-    }
-    process.exitCode = typeof code === "number" && code >= 0 ? code : 1;
-  });
-}
-
-void main();
-`;
+export function stageCompleteScript() {
+    return internalHelperScript("stage-complete", "advance-stage", "Usage: node " + RUNTIME_ROOT + "/hooks/stage-complete.mjs <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...] [--accept-proactive-waiver] [--accept-proactive-waiver-reason=...] [--json]", {
+        positionalArgName: "stage",
+        positionalArgRequired: true
+    });
 }
 export function delegationRecordScript() {
     return `#!/usr/bin/env node
@@ -669,7 +564,7 @@ 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.
-  echo [cclaw] run-hook.cmd: node not found; cclaw hook skipped. Run npx cclaw-cli doctor. >&2
+  echo [cclaw] run-hook.cmd: node not found; cclaw hook skipped. Run npx cclaw-cli sync. >&2
   exit /b 0
 )
 node "%RUNTIME%" %*
@@ -681,7 +576,7 @@ if [ "$#" -lt 1 ]; then
   exit 1
 fi
 if ! command -v node >/dev/null 2>&1; then
-  echo "[cclaw] run-hook.cmd: node not found; cclaw hook skipped. Run npx cclaw-cli doctor." >&2
+  echo "[cclaw] run-hook.cmd: node not found; cclaw hook skipped. Run npx cclaw-cli sync." >&2
   exit 0
 fi
 exec node "\${SCRIPT_DIR}/run-hook.mjs" "$@"

package/dist/content/idea-command.d.ts

@@ -0,0 +1,8 @@
+import { type IdeaFrameId } from "./idea-frames.js";
+export interface IdeaCommandOptions {
+    frameIds?: readonly IdeaFrameId[];
+    mode?: "repo-grounded" | "elsewhere-software" | "elsewhere-non-software" | "narrow";
+}
+export declare function minimumDistinctIdeaFrames(frameCount: number, mode?: IdeaCommandOptions["mode"]): number;
+export declare function ideaCommandContract(options?: IdeaCommandOptions): string;
+export declare function ideaCommandSkillMarkdown(options?: IdeaCommandOptions): string;