cclaw-cli 0.48.21 → 0.48.22

package/dist/content/node-hooks.d.ts

@@ -8,6 +8,13 @@ export interface NodeHookRuntimeOptions {
     strictness?: "advisory" | "strict";
     tddTestPathPatterns?: string[];
     tddProductionPathPatterns?: string[];
+    /**
+     * Baked-in default recurrence threshold for compound-readiness computed
+     * by the session-start hook. Derived from
+     * `config.compound.recurrenceThreshold` at install time; re-run
+     * `cclaw sync` after changing the config value so hook and CLI agree.
+     */
+    compoundRecurrenceThreshold?: number;
 }
 /**
  * Node-only hook runtime (single entrypoint).

package/dist/content/node-hooks.js

@@ -1,4 +1,6 @@
+import { DEFAULT_COMPOUND_RECURRENCE_THRESHOLD } from "../config.js";
 import { RUNTIME_ROOT } from "../constants.js";
+import { SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD, SMALL_PROJECT_RECURRENCE_THRESHOLD } from "../knowledge-store.js";
 function normalizePatterns(patterns, fallback) {
     if (!patterns || patterns.length === 0)
         return [...fallback];
@@ -18,6 +20,11 @@ export function nodeHookRuntimeScript(options = {}) {
         "**/__tests__/**"
     ]);
     const tddProductionPathPatterns = normalizePatterns(options.tddProductionPathPatterns, []);
+    const compoundRecurrenceThreshold = typeof options.compoundRecurrenceThreshold === "number" &&
+        Number.isInteger(options.compoundRecurrenceThreshold) &&
+        options.compoundRecurrenceThreshold >= 1
+        ? options.compoundRecurrenceThreshold
+        : DEFAULT_COMPOUND_RECURRENCE_THRESHOLD;
     return `#!/usr/bin/env node
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -31,6 +38,14 @@ const RUNTIME_ROOT = ${JSON.stringify(RUNTIME_ROOT)};
 const DEFAULT_STRICTNESS = ${JSON.stringify(strictness)};
 const DEFAULT_TDD_TEST_PATH_PATTERNS = ${JSON.stringify(tddTestPathPatterns)};
 const DEFAULT_TDD_PRODUCTION_PATH_PATTERNS = ${JSON.stringify(tddProductionPathPatterns)};
+// Compound-readiness recurrence threshold. Baked from
+// \`config.compound.recurrenceThreshold\` at install time so the hook and
+// \`cclaw internal compound-readiness\` agree on the same number. The
+// small-project relaxation rule (<${SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD} archived runs
+// -> min(base, ${SMALL_PROJECT_RECURRENCE_THRESHOLD})) is applied at runtime.
+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)};
 
 function resolveStrictness() {
   return process.env.CCLAW_STRICTNESS === "strict" ? "strict" : DEFAULT_STRICTNESS;
@@ -752,10 +767,14 @@ function stageSuggestion(stage) {
   return map[stage] || "";
 }
 
-async function buildKnowledgeDigest(root, currentStage) {
+async function buildKnowledgeDigest(root, currentStage, prereadRaw) {
   const knowledgeFile = path.join(root, RUNTIME_ROOT, "knowledge.jsonl");
   const digestFile = path.join(root, RUNTIME_ROOT, "state", "knowledge-digest.md");
-  const raw = await readTextFile(knowledgeFile, "");
+  // Caller may supply pre-read raw bytes to avoid re-reading knowledge.jsonl.
+  // Falls back to a local read if nothing is passed in.
+  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 = [];
@@ -885,7 +904,11 @@ async function handleSessionStart(runtime) {
   const sessionDigest = (await readTextFile(sessionDigestFile, "")).trim();
   const activitySummary = await readRecentActivityLines(activityFile);
   const contextWarning = await readLatestContextWarningLine(contextWarningsFile);
-  const knowledge = await buildKnowledgeDigest(runtime.root, state.currentStage);
+  // Read knowledge.jsonl exactly once per session-start; both the digest
+  // and compound-readiness derive from the same snapshot.
+  const knowledgeFilePath = path.join(runtime.root, RUNTIME_ROOT, "knowledge.jsonl");
+  const knowledgeRaw = await readTextFile(knowledgeFilePath, "");
+  const knowledge = await buildKnowledgeDigest(runtime.root, state.currentStage, knowledgeRaw);
 
   // Refresh Ralph Loop status each session-start so /cc-next and the model
   // both read a consistent "iter=N, acClosed=[...]" snapshot. Runs only when
@@ -912,7 +935,11 @@ async function handleSessionStart(runtime) {
   // where lifting becomes relevant; earlier stages update the file silently.
   let compoundReadinessLine = "";
   try {
-    const readiness = await computeCompoundReadinessInline(runtime.root, {});
+    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);
     if (state.currentStage === "review" || state.currentStage === "ship") {
       if (readiness.readyCount === 0) {
@@ -1297,16 +1324,53 @@ async function handlePromptGuard(runtime) {
   return 0;
 }
 
+function normalizeCompoundLastUpdatedAt(date) {
+  return date.toISOString().replace(/\\.\\d{3}Z$/u, "Z");
+}
+
+// Count archived runs as sub-directories under \`.cclaw/runs/\`. Missing
+// dir returns 0; unexpected errors return undefined so the caller can
+// skip the small-project relaxation rather than guess.
+async function countArchivedRunsInline(root) {
+  const dir = path.join(root, RUNTIME_ROOT, "runs");
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).length;
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? error.code : null;
+    if (code === "ENOENT") return 0;
+    return undefined;
+  }
+}
+
 // Mirrors src/knowledge-store.ts::computeCompoundReadiness — kept inline so
 // SessionStart can refresh compound-readiness.json without the CLI binary.
 // Any schema change must update src/knowledge-store.ts::computeCompoundReadiness
-// and src/internal/compound-readiness.ts in lockstep.
+// and src/internal/compound-readiness.ts in lockstep. Parity is enforced by
+// tests/unit/ralph-loop-parity.test.ts.
 async function computeCompoundReadinessInline(root, options) {
   const filePath = path.join(root, RUNTIME_ROOT, "knowledge.jsonl");
-  const raw = await readTextFile(filePath, "");
-  const threshold = Number.isInteger(options && options.threshold) && options.threshold >= 1
-    ? options.threshold
-    : 3;
+  // Caller may supply pre-read raw to avoid double-reading knowledge.jsonl.
+  const raw = typeof (options && options.prereadRaw) === "string"
+    ? options.prereadRaw
+    : await readTextFile(filePath, "");
+  const baseThresholdRaw = options && options.threshold;
+  const baseThreshold = Number.isInteger(baseThresholdRaw) && baseThresholdRaw >= 1
+    ? baseThresholdRaw
+    : COMPOUND_RECURRENCE_THRESHOLD;
+  const archivedRunsCount =
+    typeof (options && options.archivedRunsCount) === "number" &&
+    Number.isFinite(options.archivedRunsCount) &&
+    options.archivedRunsCount >= 0
+      ? Math.floor(options.archivedRunsCount)
+      : undefined;
+  const smallProjectRelaxationApplied =
+    archivedRunsCount !== undefined &&
+    archivedRunsCount < SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD &&
+    baseThreshold > SMALL_PROJECT_RECURRENCE_THRESHOLD;
+  const threshold = smallProjectRelaxationApplied
+    ? SMALL_PROJECT_RECURRENCE_THRESHOLD
+    : baseThreshold;
   const maxReady = Number.isInteger(options && options.maxReady) && options.maxReady >= 1
     ? options.maxReady
     : 10;
@@ -1386,12 +1450,15 @@ async function computeCompoundReadinessInline(root, options) {
     return String(a.trigger).localeCompare(String(b.trigger));
   });
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     threshold,
+    baseThreshold,
+    ...(archivedRunsCount !== undefined ? { archivedRunsCount } : {}),
+    smallProjectRelaxationApplied,
     clusterCount: buckets.size,
     readyCount: ready.length,
     ready: ready.slice(0, maxReady),
-    lastUpdatedAt: new Date().toISOString()
+    lastUpdatedAt: normalizeCompoundLastUpdatedAt(new Date())
   };
 }
 

package/dist/install.js

@@ -731,7 +731,8 @@ async function writeHooks(projectRoot, config) {
     await writeFileSafe(path.join(hooksDir, "run-hook.mjs"), nodeHookRuntimeScript({
         strictness: effectiveStrictness,
         tddTestPathPatterns: config.tdd?.testPathPatterns ?? config.tddTestGlobs,
-        tddProductionPathPatterns: config.tdd?.productionPathPatterns
+        tddProductionPathPatterns: config.tdd?.productionPathPatterns,
+        compoundRecurrenceThreshold: config.compound?.recurrenceThreshold
     }));
     const opencodePluginSource = opencodePluginJs();
     await writeFileSafe(path.join(hooksDir, "opencode-plugin.mjs"), opencodePluginSource);

package/dist/internal/compound-readiness.d.ts

@@ -4,6 +4,14 @@ interface InternalIo {
     stdout: Writable;
     stderr: Writable;
 }
+/**
+ * Count archived runs as sub-directories under `.cclaw/runs/`. Missing
+ * dir / ENOENT is interpreted as zero — callers should NOT conflate
+ * that with "unknown" (undefined); we only return undefined on
+ * unexpected errors so the caller can choose to skip the relaxation
+ * rather than guess a number.
+ */
+export declare function countArchivedRunsSafely(projectRoot: string): Promise<number | undefined>;
 /**
  * Compact one-liner for session-digest / bootstrap surfaces.
  *

package/dist/internal/compound-readiness.js

@@ -1,3 +1,4 @@
+import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "../constants.js";
 import { readConfig } from "../config.js";
@@ -19,6 +20,11 @@ function parseArgs(tokens) {
             const value = tokens[i + 1];
             if (!value)
                 throw new Error("--threshold requires a numeric value");
+            // Strict: reject "2abc", "2.9", "-1", "" — parseInt would silently
+            // accept the first two and produce surprising behavior.
+            if (!/^\d+$/u.test(value)) {
+                throw new Error(`--threshold must be a positive integer, got ${value}`);
+            }
             const parsed = Number.parseInt(value, 10);
             if (!Number.isInteger(parsed) || parsed < 1) {
                 throw new Error(`--threshold must be a positive integer, got ${value}`);
@@ -35,6 +41,29 @@ function parseArgs(tokens) {
 function stateDir(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "state");
 }
+function archiveRunsDir(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "runs");
+}
+/**
+ * Count archived runs as sub-directories under `.cclaw/runs/`. Missing
+ * dir / ENOENT is interpreted as zero — callers should NOT conflate
+ * that with "unknown" (undefined); we only return undefined on
+ * unexpected errors so the caller can choose to skip the relaxation
+ * rather than guess a number.
+ */
+export async function countArchivedRunsSafely(projectRoot) {
+    const dir = archiveRunsDir(projectRoot);
+    try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).length;
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT")
+            return 0;
+        return undefined;
+    }
+}
 /**
  * Compact one-liner for session-digest / bootstrap surfaces.
  *
@@ -51,14 +80,26 @@ export function formatCompoundReadinessLine(status) {
 }
 export async function runCompoundReadinessCommand(projectRoot, argv, io) {
     const args = parseArgs(argv);
-    const config = await readConfig(projectRoot).catch(() => null);
+    // Reading config is best-effort — but DO surface a stderr warning so
+    // mis-wired / malformed config shows up in hook-errors / CI logs
+    // instead of silently degrading to default threshold.
+    let config = null;
+    try {
+        config = await readConfig(projectRoot);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        io.stderr.write(`[cclaw] compound-readiness: failed to read config (${detail}); falling back to default threshold\n`);
+    }
     const threshold = args.threshold ??
         (typeof config?.compound?.recurrenceThreshold === "number"
             ? config.compound.recurrenceThreshold
             : undefined);
-    const { entries } = await readKnowledgeSafely(projectRoot, { lockAware: false });
+    const archivedRunsCount = await countArchivedRunsSafely(projectRoot);
+    const { entries } = await readKnowledgeSafely(projectRoot, { lockAware: true });
     const status = computeCompoundReadiness(entries, {
-        ...(typeof threshold === "number" ? { threshold } : {})
+        ...(typeof threshold === "number" ? { threshold } : {}),
+        ...(typeof archivedRunsCount === "number" ? { archivedRunsCount } : {})
     });
     if (args.write) {
         const target = path.join(stateDir(projectRoot), "compound-readiness.json");

package/dist/knowledge-store.d.ts

@@ -98,9 +98,28 @@ export interface CompoundReadinessCluster {
     maturity: KnowledgeEntryMaturity[];
 }
 export interface CompoundReadiness {
-    schemaVersion: 1;
-    /** Effective recurrence threshold applied to this computation. */
+    schemaVersion: 2;
+    /**
+     * Effective recurrence threshold actually used. When
+     * `archivedRunsCount < SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD`, this is
+     * `min(baseThreshold, SMALL_PROJECT_RECURRENCE_THRESHOLD)` — otherwise
+     * it equals `baseThreshold`.
+     */
     threshold: number;
+    /** Base threshold from config/CLI before small-project relaxation. */
+    baseThreshold: number;
+    /**
+     * Archived-run count observed at compute time (used to gate the
+     * small-project relaxation). Optional — the computation can run
+     * without knowing this and then no relaxation is applied.
+     */
+    archivedRunsCount?: number;
+    /**
+     * True iff the effective threshold was lowered by the small-project
+     * relaxation rule. Always false when `archivedRunsCount` is not
+     * supplied.
+     */
+    smallProjectRelaxationApplied: boolean;
     /** Total number of (trigger, action) clusters seen, regardless of threshold. */
     clusterCount: number;
     /** Number of clusters that passed the threshold or critical override. */
@@ -117,7 +136,27 @@ export interface ComputeCompoundReadinessOptions {
     /** Hard cap on `ready[]` to keep the surface digest concise. Default 10. */
     maxReady?: number;
     now?: Date;
+    /**
+     * Count of archived runs under `.cclaw/runs/`. When supplied and
+     * `< SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD`, the effective threshold
+     * is lowered to `min(threshold, SMALL_PROJECT_RECURRENCE_THRESHOLD)`.
+     * Matches the rule documented in `src/content/compound-command.ts`
+     * and `docs/config.md`.
+     */
+    archivedRunsCount?: number;
 }
+/**
+ * Single source of truth for the small-project relaxation rule.
+ *
+ * Kept exported so the inline hook mirror, the CLI command, and
+ * the `/cc-ops compound` skill all agree on the same numbers.
+ */
+export declare const SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD = 5;
+export declare const SMALL_PROJECT_RECURRENCE_THRESHOLD = 2;
+export declare function effectiveCompoundThreshold(baseThreshold: number, archivedRunsCount: number | undefined): {
+    threshold: number;
+    relaxationApplied: boolean;
+};
 /**
  * Pure function — no filesystem side effects. Callers pass entries from
  * `readKnowledgeSafely` and get a derived readiness snapshot suitable

package/dist/knowledge-store.js

@@ -5,6 +5,26 @@ import { RUNTIME_ROOT } from "./constants.js";
 import { stripBom, withDirectoryLock } from "./fs-utils.js";
 import { FLOW_STAGES } from "./types.js";
 const DEFAULT_COMPOUND_READINESS_MAX_READY = 10;
+/**
+ * Single source of truth for the small-project relaxation rule.
+ *
+ * Kept exported so the inline hook mirror, the CLI command, and
+ * the `/cc-ops compound` skill all agree on the same numbers.
+ */
+export const SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD = 5;
+export const SMALL_PROJECT_RECURRENCE_THRESHOLD = 2;
+export function effectiveCompoundThreshold(baseThreshold, archivedRunsCount) {
+    if (typeof archivedRunsCount === "number" &&
+        Number.isFinite(archivedRunsCount) &&
+        archivedRunsCount < SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD &&
+        baseThreshold > SMALL_PROJECT_RECURRENCE_THRESHOLD) {
+        return {
+            threshold: SMALL_PROJECT_RECURRENCE_THRESHOLD,
+            relaxationApplied: true
+        };
+    }
+    return { threshold: baseThreshold, relaxationApplied: false };
+}
 /**
  * Pure function — no filesystem side effects. Callers pass entries from
  * `readKnowledgeSafely` and get a derived readiness snapshot suitable
@@ -17,7 +37,7 @@ const DEFAULT_COMPOUND_READINESS_MAX_READY = 10;
  */
 export function computeCompoundReadiness(entries, options = {}) {
     const thresholdRaw = options.threshold ?? DEFAULT_COMPOUND_RECURRENCE_THRESHOLD;
-    const threshold = Number.isInteger(thresholdRaw) && thresholdRaw >= 1
+    const baseThreshold = Number.isInteger(thresholdRaw) && thresholdRaw >= 1
         ? thresholdRaw
         : DEFAULT_COMPOUND_RECURRENCE_THRESHOLD;
     const maxReadyRaw = options.maxReady ?? DEFAULT_COMPOUND_READINESS_MAX_READY;
@@ -25,6 +45,12 @@ export function computeCompoundReadiness(entries, options = {}) {
         ? maxReadyRaw
         : DEFAULT_COMPOUND_READINESS_MAX_READY;
     const now = options.now ?? new Date();
+    const archivedRunsCount = typeof options.archivedRunsCount === "number" &&
+        Number.isFinite(options.archivedRunsCount) &&
+        options.archivedRunsCount >= 0
+        ? Math.floor(options.archivedRunsCount)
+        : undefined;
+    const { threshold, relaxationApplied } = effectiveCompoundThreshold(baseThreshold, archivedRunsCount);
     const buckets = new Map();
     for (const entry of entries) {
         if (entry.maturity === "lifted-to-enforcement")
@@ -102,8 +128,11 @@ export function computeCompoundReadiness(entries, options = {}) {
         return a.trigger.localeCompare(b.trigger);
     });
     return {
-        schemaVersion: 1,
+        schemaVersion: 2,
         threshold,
+        baseThreshold,
+        ...(archivedRunsCount !== undefined ? { archivedRunsCount } : {}),
+        smallProjectRelaxationApplied: relaxationApplied,
         clusterCount: buckets.size,
         readyCount: ready.length,
         ready: ready.slice(0, maxReady),

package/package.json

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