cclaw-cli 0.48.14 → 0.48.15

package/dist/content/flow-map.js

@@ -82,6 +82,17 @@ worth acting on:
 Ralph Loop is a signal, not a gate. Stage advancement still runs
 through the normal \`flow-state.json\` gate catalog.
 
+## Compound readiness (auto-promotion signal)
+
+SessionStart also refreshes
+\`${RUNTIME_ROOT}/state/compound-readiness.json\` from \`knowledge.jsonl\`.
+The file lists clusters whose summed \`frequency\` reaches
+\`compound.recurrenceThreshold\` (default 3) or whose severity is
+\`critical\` (override). It surfaces a one-line nudge in the session
+digest only during \`review\` and \`ship\`, where lift-to-rule is in
+scope; earlier stages refresh the file silently. Promotion itself stays
+manual via \`/cc-ops compound\` so the signal never blocks flow.
+
 ## Key state files
 
 | Path | What it holds |
@@ -90,6 +101,7 @@ through the normal \`flow-state.json\` gate catalog.
 | \`${RUNTIME_ROOT}/state/delegation-log.json\` | Per-stage mandatory agent status + fulfillmentMode + evidenceRefs. |
 | \`${RUNTIME_ROOT}/state/tdd-cycle-log.jsonl\` | Append-only RED/GREEN/REFACTOR entries (source of Ralph Loop). |
 | \`${RUNTIME_ROOT}/state/ralph-loop.json\` | Derived Ralph Loop status (TDD-only). |
+| \`${RUNTIME_ROOT}/state/compound-readiness.json\` | Derived compound-promotion readiness (refreshed each SessionStart). |
 | \`${RUNTIME_ROOT}/state/stage-activity.jsonl\` | Append-only stage-enter/exit and gate-pass signals. |
 | \`${RUNTIME_ROOT}/state/checkpoint.json\` | Latest session checkpoint (stage + timestamp). |
 | \`${RUNTIME_ROOT}/state/context-mode.json\` | Active context mode (\`default\`, \`headless\`, ...). |

package/dist/content/node-hooks.js

@@ -725,6 +725,28 @@ async function handleSessionStart(runtime) {
     }
   }
 
+  // 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 {
+    const readiness = await computeCompoundReadinessInline(runtime.root, {});
+    await writeJsonFile(path.join(stateDir, "compound-readiness.json"), readiness);
+    if (state.currentStage === "review" || state.currentStage === "ship") {
+      if (readiness.readyCount === 0) {
+        compoundReadinessLine = "Compound readiness: no candidates (clusters=" +
+          String(readiness.clusterCount) + ", threshold=" + String(readiness.threshold) + ")";
+      } else {
+        const critical = readiness.ready.filter((entry) => entry.severity === "critical").length;
+        const criticalSuffix = critical > 0 ? " (critical=" + String(critical) + ")" : "";
+        compoundReadinessLine = "Compound readiness: clusters=" + String(readiness.clusterCount) +
+          ", ready=" + String(readiness.readyCount) + criticalSuffix;
+      }
+    }
+  } catch (_err) {
+    // best-effort — a malformed knowledge.jsonl must never break session-start.
+  }
+
   const suggestionMemory = toObject(await readJsonFile(suggestionMemoryFile, {})) || {};
   const suggestionsEnabled = suggestionMemory.enabled !== false;
   const mutedStages = Array.isArray(suggestionMemory.mutedStages)
@@ -792,6 +814,9 @@ async function handleSessionStart(runtime) {
   if (ralphLoopLine.length > 0) {
     parts.push(ralphLoopLine);
   }
+  if (compoundReadinessLine.length > 0) {
+    parts.push(compoundReadinessLine);
+  }
   if (contextWarning.length > 0) {
     parts.push("Latest context warning:\\n" + contextWarning);
   }
@@ -1112,6 +1137,104 @@ async function tddCycleCounts(stateDir, runId) {
   return { red, green };
 }
 
+// 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.
+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;
+  const maxReady = Number.isInteger(options && options.maxReady) && options.maxReady >= 1
+    ? options.maxReady
+    : 10;
+  const normalize = (value) => String(value == null ? "" : value).trim().replace(/\\s+/gu, " ").toLowerCase();
+  const severityWeight = (sev) => {
+    if (sev === "critical") return 3;
+    if (sev === "important") return 2;
+    if (sev === "suggestion") return 1;
+    return 0;
+  };
+  const buckets = new Map();
+  for (const rawLine of raw.split(/\\r?\\n/gu)) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }
+    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+    if (row.maturity === "lifted-to-enforcement") continue;
+    const type = typeof row.type === "string" ? row.type : "";
+    const trigger = typeof row.trigger === "string" ? row.trigger : "";
+    const action = typeof row.action === "string" ? row.action : "";
+    if (type.length === 0 || trigger.length === 0 || action.length === 0) continue;
+    const key = type + "||" + normalize(trigger) + "||" + normalize(action);
+    const frequency = Number.isInteger(row.frequency) && row.frequency > 0 ? Math.floor(row.frequency) : 1;
+    const lastSeen = typeof row.last_seen_ts === "string" ? row.last_seen_ts : "";
+    let bucket = buckets.get(key);
+    if (!bucket) {
+      bucket = {
+        trigger,
+        action,
+        recurrence: frequency,
+        entryCount: 1,
+        severity: typeof row.severity === "string" ? row.severity : undefined,
+        lastSeenTs: lastSeen,
+        types: new Set([type]),
+        maturity: new Set([typeof row.maturity === "string" ? row.maturity : "raw"])
+      };
+      buckets.set(key, bucket);
+      continue;
+    }
+    bucket.recurrence += frequency;
+    bucket.entryCount += 1;
+    bucket.types.add(type);
+    bucket.maturity.add(typeof row.maturity === "string" ? row.maturity : "raw");
+    if (row.severity === "critical") {
+      bucket.severity = "critical";
+    } else if (row.severity === "important" && bucket.severity !== "critical") {
+      bucket.severity = "important";
+    }
+    if (lastSeen && Date.parse(lastSeen) > Date.parse(bucket.lastSeenTs || "0")) {
+      bucket.lastSeenTs = lastSeen;
+    }
+  }
+  const ready = [];
+  for (const bucket of buckets.values()) {
+    const criticalOverride = bucket.severity === "critical";
+    const meetsRecurrence = bucket.recurrence >= threshold;
+    if (!criticalOverride && !meetsRecurrence) continue;
+    ready.push({
+      trigger: bucket.trigger,
+      action: bucket.action,
+      recurrence: bucket.recurrence,
+      entryCount: bucket.entryCount,
+      qualification: criticalOverride && !meetsRecurrence ? "critical_override" : "recurrence",
+      ...(bucket.severity ? { severity: bucket.severity } : {}),
+      lastSeenTs: bucket.lastSeenTs,
+      types: Array.from(bucket.types).sort(),
+      maturity: Array.from(bucket.maturity).sort()
+    });
+  }
+  ready.sort((a, b) => {
+    const sevDiff = severityWeight(b.severity) - severityWeight(a.severity);
+    if (sevDiff !== 0) return sevDiff;
+    if (b.recurrence !== a.recurrence) return b.recurrence - a.recurrence;
+    const recencyDiff = Date.parse(b.lastSeenTs || "0") - Date.parse(a.lastSeenTs || "0");
+    if (!Number.isNaN(recencyDiff) && recencyDiff !== 0) return recencyDiff;
+    return String(a.trigger).localeCompare(String(b.trigger));
+  });
+  return {
+    schemaVersion: 1,
+    threshold,
+    clusterCount: buckets.size,
+    readyCount: ready.length,
+    ready: ready.slice(0, maxReady),
+    lastUpdatedAt: new Date().toISOString()
+  };
+}
+
 // Mirrors src/tdd-cycle.ts::computeRalphLoopStatus — kept inline so the
 // SessionStart hook can write ralph-loop.json without depending on the CLI
 // binary being installed globally. Any schema change must update both copies.

package/dist/internal/advance-stage.js

@@ -12,6 +12,7 @@ import { getAvailableTransitions, getTransitionGuards, isFlowTrack } from "../fl
 import { appendKnowledge } from "../knowledge-store.js";
 import { readFlowState, writeFlowState } from "../runs.js";
 import { FLOW_STAGES } from "../types.js";
+import { runCompoundReadinessCommand } from "./compound-readiness.js";
 import { runEnvelopeValidateCommand } from "./envelope-validate.js";
 import { runKnowledgeDigestCommand } from "./knowledge-digest.js";
 import { runTddLoopStatusCommand } from "./tdd-loop-status.js";
@@ -673,7 +674,7 @@ async function runHookCommand(projectRoot, args, io) {
 export async function runInternalCommand(projectRoot, argv, io) {
     const [subcommand, ...tokens] = argv;
     if (!subcommand) {
-        io.stderr.write("cclaw internal requires a subcommand: advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | tdd-loop-status | hook\n");
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook\n");
         return 1;
     }
     try {
@@ -698,10 +699,13 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "tdd-loop-status") {
             return await runTddLoopStatusCommand(projectRoot, tokens, io);
         }
+        if (subcommand === "compound-readiness") {
+            return await runCompoundReadinessCommand(projectRoot, tokens, io);
+        }
         if (subcommand === "hook") {
             return await runHookCommand(projectRoot, parseHookArgs(tokens), io);
         }
-        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | tdd-loop-status | hook\n`);
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook\n`);
         return 1;
     }
     catch (err) {

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

@@ -0,0 +1,15 @@
+import type { Writable } from "node:stream";
+import { type CompoundReadiness } from "../knowledge-store.js";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+/**
+ * Compact one-liner for session-digest / bootstrap surfaces.
+ *
+ * Example: `Compound readiness: clusters=12, ready=2 (critical=1)`.
+ * When `ready === 0`, emit `Compound readiness: no candidates`.
+ */
+export declare function formatCompoundReadinessLine(status: CompoundReadiness): string;
+export declare function runCompoundReadinessCommand(projectRoot: string, argv: string[], io: InternalIo): Promise<number>;
+export {};

package/dist/internal/compound-readiness.js

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { RUNTIME_ROOT } from "../constants.js";
+import { readConfig } from "../config.js";
+import { writeFileSafe } from "../fs-utils.js";
+import { computeCompoundReadiness, readKnowledgeSafely } from "../knowledge-store.js";
+function parseArgs(tokens) {
+    const args = { json: false, quiet: false, write: true };
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token === "--json")
+            args.json = true;
+        else if (token === "--quiet")
+            args.quiet = true;
+        else if (token === "--no-write")
+            args.write = false;
+        else if (token === "--write")
+            args.write = true;
+        else if (token === "--threshold") {
+            const value = tokens[i + 1];
+            if (!value)
+                throw new Error("--threshold requires a numeric value");
+            const parsed = Number.parseInt(value, 10);
+            if (!Number.isInteger(parsed) || parsed < 1) {
+                throw new Error(`--threshold must be a positive integer, got ${value}`);
+            }
+            args.threshold = parsed;
+            i += 1;
+        }
+        else {
+            throw new Error(`Unknown compound-readiness flag: ${token}`);
+        }
+    }
+    return args;
+}
+function stateDir(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state");
+}
+/**
+ * Compact one-liner for session-digest / bootstrap surfaces.
+ *
+ * Example: `Compound readiness: clusters=12, ready=2 (critical=1)`.
+ * When `ready === 0`, emit `Compound readiness: no candidates`.
+ */
+export function formatCompoundReadinessLine(status) {
+    if (status.readyCount === 0) {
+        return `Compound readiness: no candidates (clusters=${status.clusterCount}, threshold=${status.threshold})`;
+    }
+    const critical = status.ready.filter((cluster) => cluster.severity === "critical").length;
+    const criticalSuffix = critical > 0 ? ` (critical=${critical})` : "";
+    return `Compound readiness: clusters=${status.clusterCount}, ready=${status.readyCount}${criticalSuffix}`;
+}
+export async function runCompoundReadinessCommand(projectRoot, argv, io) {
+    const args = parseArgs(argv);
+    const config = await readConfig(projectRoot).catch(() => null);
+    const threshold = args.threshold ??
+        (typeof config?.compound?.recurrenceThreshold === "number"
+            ? config.compound.recurrenceThreshold
+            : undefined);
+    const { entries } = await readKnowledgeSafely(projectRoot, { lockAware: false });
+    const status = computeCompoundReadiness(entries, {
+        ...(typeof threshold === "number" ? { threshold } : {})
+    });
+    if (args.write) {
+        const target = path.join(stateDir(projectRoot), "compound-readiness.json");
+        await writeFileSafe(target, `${JSON.stringify(status, null, 2)}\n`);
+    }
+    if (!args.quiet) {
+        if (args.json) {
+            io.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
+        }
+        else {
+            io.stdout.write(`${formatCompoundReadinessLine(status)}\n`);
+        }
+    }
+    return 0;
+}

package/dist/knowledge-store.d.ts

@@ -72,6 +72,63 @@ export interface SelectRelevantLearningsOptions {
     openGates?: string[];
     limit?: number;
 }
+/**
+ * One clustered (trigger, action) group ready for compound lift.
+ *
+ * A cluster "qualifies" when its recurrence count meets the configured
+ * threshold **or** any contributing entry is marked `severity: "critical"`.
+ * The skill surface exposes this for nudging — it is not a gate.
+ */
+export interface CompoundReadinessCluster {
+    trigger: string;
+    action: string;
+    /**
+     * Sum of `frequency` across entries in the cluster — matches the
+     * recurrence count used by `/cc-ops compound`.
+     */
+    recurrence: number;
+    /** Distinct entry lines contributing to this cluster. */
+    entryCount: number;
+    qualification: "recurrence" | "critical_override";
+    severity?: KnowledgeEntrySeverity;
+    lastSeenTs: string;
+    /** Entry types observed (rule/pattern/lesson/compound). */
+    types: KnowledgeEntryType[];
+    /** Distinct maturity values observed across the cluster. */
+    maturity: KnowledgeEntryMaturity[];
+}
+export interface CompoundReadiness {
+    schemaVersion: 1;
+    /** Effective recurrence threshold applied to this computation. */
+    threshold: number;
+    /** Total number of (trigger, action) clusters seen, regardless of threshold. */
+    clusterCount: number;
+    /** Number of clusters that passed the threshold or critical override. */
+    readyCount: number;
+    /**
+     * Top ready clusters (sorted by qualification severity / recurrence /
+     * recency). Capped by `maxReady` to keep the artifact small.
+     */
+    ready: CompoundReadinessCluster[];
+    lastUpdatedAt: string;
+}
+export interface ComputeCompoundReadinessOptions {
+    threshold?: number;
+    /** Hard cap on `ready[]` to keep the surface digest concise. Default 10. */
+    maxReady?: number;
+    now?: Date;
+}
+/**
+ * Pure function — no filesystem side effects. Callers pass entries from
+ * `readKnowledgeSafely` and get a derived readiness snapshot suitable
+ * for persisting to `.cclaw/state/compound-readiness.json`.
+ *
+ * Clustering key: `(type, normalizeText(trigger), normalizeText(action))`
+ * which mirrors the clustering used by the `/cc-ops compound` skill.
+ * Entries with `maturity === "lifted-to-enforcement"` are excluded —
+ * they were already promoted and should not re-appear as ready.
+ */
+export declare function computeCompoundReadiness(entries: KnowledgeEntry[], options?: ComputeCompoundReadinessOptions): CompoundReadiness;
 export declare function validateKnowledgeEntry(entry: unknown): {
     ok: boolean;
     errors: string[];

package/dist/knowledge-store.js

@@ -1,8 +1,115 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { DEFAULT_COMPOUND_RECURRENCE_THRESHOLD } from "./config.js";
 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;
+/**
+ * Pure function — no filesystem side effects. Callers pass entries from
+ * `readKnowledgeSafely` and get a derived readiness snapshot suitable
+ * for persisting to `.cclaw/state/compound-readiness.json`.
+ *
+ * Clustering key: `(type, normalizeText(trigger), normalizeText(action))`
+ * which mirrors the clustering used by the `/cc-ops compound` skill.
+ * Entries with `maturity === "lifted-to-enforcement"` are excluded —
+ * they were already promoted and should not re-appear as ready.
+ */
+export function computeCompoundReadiness(entries, options = {}) {
+    const thresholdRaw = options.threshold ?? DEFAULT_COMPOUND_RECURRENCE_THRESHOLD;
+    const threshold = Number.isInteger(thresholdRaw) && thresholdRaw >= 1
+        ? thresholdRaw
+        : DEFAULT_COMPOUND_RECURRENCE_THRESHOLD;
+    const maxReadyRaw = options.maxReady ?? DEFAULT_COMPOUND_READINESS_MAX_READY;
+    const maxReady = Number.isInteger(maxReadyRaw) && maxReadyRaw >= 1
+        ? maxReadyRaw
+        : DEFAULT_COMPOUND_READINESS_MAX_READY;
+    const now = options.now ?? new Date();
+    const buckets = new Map();
+    for (const entry of entries) {
+        if (entry.maturity === "lifted-to-enforcement")
+            continue;
+        const key = [
+            entry.type,
+            normalizeText(entry.trigger),
+            normalizeText(entry.action)
+        ].join("||");
+        const frequency = Math.max(1, Math.floor(entry.frequency));
+        const bucket = buckets.get(key);
+        if (!bucket) {
+            buckets.set(key, {
+                trigger: entry.trigger,
+                action: entry.action,
+                recurrence: frequency,
+                entryCount: 1,
+                severity: entry.severity,
+                lastSeenTs: entry.last_seen_ts,
+                types: new Set([entry.type]),
+                maturity: new Set([entry.maturity])
+            });
+            continue;
+        }
+        bucket.recurrence += frequency;
+        bucket.entryCount += 1;
+        bucket.types.add(entry.type);
+        bucket.maturity.add(entry.maturity);
+        if (entry.severity === "critical") {
+            bucket.severity = "critical";
+        }
+        else if (entry.severity === "important" && bucket.severity !== "critical") {
+            bucket.severity = "important";
+        }
+        if (Date.parse(entry.last_seen_ts) > Date.parse(bucket.lastSeenTs)) {
+            bucket.lastSeenTs = entry.last_seen_ts;
+        }
+    }
+    const ready = [];
+    for (const bucket of buckets.values()) {
+        const criticalOverride = bucket.severity === "critical";
+        const meetsRecurrence = bucket.recurrence >= threshold;
+        if (!criticalOverride && !meetsRecurrence)
+            continue;
+        ready.push({
+            trigger: bucket.trigger,
+            action: bucket.action,
+            recurrence: bucket.recurrence,
+            entryCount: bucket.entryCount,
+            qualification: criticalOverride && !meetsRecurrence ? "critical_override" : "recurrence",
+            ...(bucket.severity ? { severity: bucket.severity } : {}),
+            lastSeenTs: bucket.lastSeenTs,
+            types: Array.from(bucket.types).sort(),
+            maturity: Array.from(bucket.maturity).sort()
+        });
+    }
+    ready.sort((a, b) => {
+        const severityWeight = (sev) => {
+            if (sev === "critical")
+                return 3;
+            if (sev === "important")
+                return 2;
+            if (sev === "suggestion")
+                return 1;
+            return 0;
+        };
+        const severityDiff = severityWeight(b.severity) - severityWeight(a.severity);
+        if (severityDiff !== 0)
+            return severityDiff;
+        if (b.recurrence !== a.recurrence)
+            return b.recurrence - a.recurrence;
+        const recencyDiff = Date.parse(b.lastSeenTs) - Date.parse(a.lastSeenTs);
+        if (!Number.isNaN(recencyDiff) && recencyDiff !== 0)
+            return recencyDiff;
+        return a.trigger.localeCompare(b.trigger);
+    });
+    return {
+        schemaVersion: 1,
+        threshold,
+        clusterCount: buckets.size,
+        readyCount: ready.length,
+        ready: ready.slice(0, maxReady),
+        lastUpdatedAt: normalizeUtcIso(now.toISOString())
+    };
+}
 const KNOWLEDGE_TYPE_SET = new Set(["rule", "pattern", "lesson", "compound"]);
 const KNOWLEDGE_CONFIDENCE_SET = new Set(["high", "medium", "low"]);
 const KNOWLEDGE_SEVERITY_SET = new Set(["critical", "important", "suggestion"]);

package/dist/policy.js

@@ -146,6 +146,7 @@ export async function policyChecks(projectRoot, options = {}) {
         { file: runtimeFile("references/flow-map.md"), needle: "## Stages (8)", name: "reference:flow_map:stages" },
         { file: runtimeFile("references/flow-map.md"), needle: "## Ralph Loop", name: "reference:flow_map:ralph_loop" },
         { file: runtimeFile("references/flow-map.md"), needle: "## Key state files", name: "reference:flow_map:state_files" },
+        { file: runtimeFile("references/flow-map.md"), needle: "## Compound readiness", name: "reference:flow_map:compound_readiness" },
         { file: runtimeFile("skills/session/SKILL.md"), needle: "## Session Resume Protocol", name: "utility_skill:session:resume" },
         { file: runtimeFile("skills/brainstorming/SKILL.md"), needle: "common-guidance.md", name: "stage_skill:shared_guidance_reference" },
         { file: runtimeFile("skills/security/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:security:hard_gate" },

package/package.json

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