cclaw-cli 0.48.13 → 0.48.15

package/dist/content/flow-map.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Relative path used by skills/commands to cite the consolidated flow map.
+ * Stable contract — changing this value is a breaking change for doctor
+ * policies and meta-skill links.
+ */
+export declare const FLOW_MAP_REL_PATH = ".cclaw/references/flow-map.md";
+/**
+ * Canonical one-page overview of cclaw's user-facing surface.
+ *
+ * Purpose: give the model (and any curious human) a single file that
+ * answers "what does cclaw expose, where does my current stage fit, and
+ * which files drive progress?" without forcing a walk of the 8 stage
+ * skills plus the 4 router skills plus the meta-skill.
+ *
+ * Design rules:
+ * - Keep it under ~150 lines; it is a map, not a manual.
+ * - Only cite files that already exist under `.cclaw/`.
+ * - Do not duplicate protocol text (decision/completion/ethos live in
+ *   `.cclaw/references/protocols/`). Link, don't inline.
+ * - Do not introduce new gates or hard rules here — flow-map is
+ *   descriptive, not prescriptive.
+ */
+export declare function flowMapMarkdown(): string;

package/dist/content/flow-map.js

@@ -0,0 +1,129 @@
+import { RUNTIME_ROOT } from "../constants.js";
+/**
+ * Relative path used by skills/commands to cite the consolidated flow map.
+ * Stable contract — changing this value is a breaking change for doctor
+ * policies and meta-skill links.
+ */
+export const FLOW_MAP_REL_PATH = `${RUNTIME_ROOT}/references/flow-map.md`;
+/**
+ * Canonical one-page overview of cclaw's user-facing surface.
+ *
+ * Purpose: give the model (and any curious human) a single file that
+ * answers "what does cclaw expose, where does my current stage fit, and
+ * which files drive progress?" without forcing a walk of the 8 stage
+ * skills plus the 4 router skills plus the meta-skill.
+ *
+ * Design rules:
+ * - Keep it under ~150 lines; it is a map, not a manual.
+ * - Only cite files that already exist under `.cclaw/`.
+ * - Do not duplicate protocol text (decision/completion/ethos live in
+ *   `.cclaw/references/protocols/`). Link, don't inline.
+ * - Do not introduce new gates or hard rules here — flow-map is
+ *   descriptive, not prescriptive.
+ */
+export function flowMapMarkdown() {
+    return `# cclaw Flow Map
+
+One-page surface reference. Use this when you need the shape of cclaw
+without reading every skill — the stage quick-map, the user-facing
+slash commands, the Ralph Loop signal, and the key state files.
+
+For enforcement details, load the matching stage skill or command
+contract. For protocols (decision/completion/ethos) see
+\`${RUNTIME_ROOT}/references/protocols/\`.
+
+## Stages (8)
+
+| # | Stage | Goal | Primary artifact |
+|---|---|---|---|
+| 1 | brainstorm | Explore options and constraints | \`.cclaw/artifacts/00-idea.md\` (+ \`01-brainstorm.md\`) |
+| 2 | scope | Freeze scope (in/out, assumptions) | \`.cclaw/artifacts/02-scope.md\` |
+| 3 | design | Pick the shape of the change | \`.cclaw/artifacts/03-design.md\` |
+| 4 | spec | Turn design into testable acceptance criteria | \`.cclaw/artifacts/04-spec.md\` |
+| 5 | plan | Decompose spec into executable slices | \`.cclaw/artifacts/05-plan.md\` |
+| 6 | tdd | Drive each slice through RED → GREEN → REFACTOR (Ralph Loop) | \`.cclaw/artifacts/06-tdd.md\` + \`.cclaw/state/tdd-cycle-log.jsonl\` |
+| 7 | review | Cross-check correctness, spec coverage, and ethos | \`.cclaw/artifacts/07-review.md\` |
+| 8 | ship | Close out: retro, compound, archive | \`.cclaw/artifacts/08-ship.md\` (+ \`09-retro.md\`) |
+
+Track shortcuts (set in \`.cclaw/state/flow-state.json\`):
+
+- \`quick\` — spec → tdd → review → ship
+- \`medium\` — brainstorm → spec → plan → tdd → review → ship
+- \`standard\` — all 8 stages (default)
+
+## User-facing slash commands
+
+| Command | Role | Notes |
+|---|---|---|
+| \`/cc\` | Entry point. No args = resume. With prompt = classify + start. | Writes \`00-idea.md\` and picks the track. |
+| \`/cc-next\` | Advance or resume the current stage based on gates. | Soft nudge from Ralph Loop during \`tdd\`. |
+| \`/cc-ideate\` | Repo-improvement discovery, separate from product flow. | Produces ideas, not stage artifacts. |
+| \`/cc-view [status\\|tree\\|diff]\` | Read-only router. Never mutates flow state. | \`diff\` refreshes the snapshot baseline by design. |
+| \`/cc-ops [feature\\|tdd-log\\|retro\\|compound\\|archive\\|rewind]\` | Operations router for post-flow and side-channel actions. | Mutations are scoped to each subcommand. |
+
+Subcommand dispatch lives in \`${RUNTIME_ROOT}/commands/\` and the
+matching \`${RUNTIME_ROOT}/skills/flow-*/SKILL.md\`. The meta-skill
+(\`${RUNTIME_ROOT}/skills/using-cclaw/SKILL.md\`) decides which router to
+use before any substantive work.
+
+## Ralph Loop (TDD progress signal)
+
+When \`currentStage === "tdd"\`, SessionStart writes
+\`${RUNTIME_ROOT}/state/ralph-loop.json\` from the TDD cycle log. Fields
+worth acting on:
+
+- \`loopIteration\` — how many RED → GREEN cycles already landed.
+- \`redOpenSlices\` — slices with an unsatisfied RED. Non-empty means do
+  **not** advance to review.
+- \`acClosed\` — distinct acceptance-criterion IDs closed by a GREEN row
+  (requires \`acIds\` on the green log entry via \`/cc-ops tdd-log\`).
+- \`sliceCount\` — total distinct plan slices ever touched.
+
+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 |
+|---|---|
+| \`${RUNTIME_ROOT}/state/flow-state.json\` | Track, currentStage, completedStages, gate catalog, closeout substate. |
+| \`${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\`, ...). |
+| \`${RUNTIME_ROOT}/state/harness-gaps.json\` | Per-harness tier, subagent fallback, playbook path (schemaVersion 2). |
+| \`${RUNTIME_ROOT}/knowledge.jsonl\` | Append-only learnings; surfaced to sessions via digest. |
+
+## Strictness and hooks
+
+Hook-driven guards respect the \`strictness\` field in
+\`${RUNTIME_ROOT}/config.yaml\`:
+
+- \`advisory\` (default) — hooks warn but never block tool calls.
+- \`strict\` — hooks block tool calls that violate their scope.
+
+Override per-session with \`CCLAW_STRICTNESS=advisory|strict\`.
+
+## When in doubt
+
+1. Read \`${RUNTIME_ROOT}/state/flow-state.json\` to know where you are.
+2. Load the matching stage skill only if you are about to do
+   substantive work (see \`using-cclaw\` meta-skill).
+3. Prefer \`/cc-next\` for progression. \`/cc-view\` for visibility.
+   \`/cc-ops\` for side-channel operations.
+`;
+}

package/dist/content/meta-skill.js

@@ -1,3 +1,4 @@
+import { FLOW_MAP_REL_PATH } from "./flow-map.js";
 import { COMPLETION_PROTOCOL_REL_PATH, DECISION_PROTOCOL_REL_PATH, ETHOS_PROTOCOL_REL_PATH } from "./protocols.js";
 export const META_SKILL_NAME = "using-cclaw";
 export function usingCclawSkillMarkdown() {
@@ -76,6 +77,8 @@ Before stage work:
 brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship
 
 Tracks may skip stages via \`flow-state.track\` + \`skippedStages\`.
+For the full surface (stages, routers, Ralph Loop, state files) load
+\`${FLOW_MAP_REL_PATH}\` — it is the single-page overview of cclaw.
 
 ## Contextual skill activation
 

package/dist/content/next-command.js

@@ -1,4 +1,5 @@
 import { RUNTIME_ROOT } from "../constants.js";
+import { FLOW_MAP_REL_PATH } from "./flow-map.js";
 import { stageSchema } from "./stage-schema.js";
 import { stageSkillFolder } from "./skills.js";
 const NEXT_SKILL_FOLDER = "flow-next-step";
@@ -128,6 +129,12 @@ Validate envelopes with:
 ## Primary skill
 
 **${skillRel}** — full protocol and stage table.
+
+## Surface reference
+
+When you need the full shape of cclaw (stages, routers, Ralph Loop,
+state files) load \`${FLOW_MAP_REL_PATH}\`. It is the single-page
+overview and is safe to read at any time.
 `;
 }
 /**

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/content/start-command.js

@@ -1,4 +1,5 @@
 import { RUNTIME_ROOT } from "../constants.js";
+import { FLOW_MAP_REL_PATH } from "./flow-map.js";
 const START_SKILL_FOLDER = "flow-start";
 const START_SKILL_NAME = "flow-start";
 function flowStatePath() {
@@ -115,6 +116,12 @@ Validate envelopes with:
 ## Primary skill
 
 **${RUNTIME_ROOT}/skills/${START_SKILL_FOLDER}/SKILL.md**
+
+## Surface reference
+
+For the 1-page overview of cclaw (stages, routers, Ralph Loop, state
+files) load \`${FLOW_MAP_REL_PATH}\` — useful when a fresh session
+needs orientation before \`/cc <prompt>\` runs.
 `;
 }
 /**

package/dist/doctor-registry.js

@@ -85,7 +85,7 @@ const RULES = [
         }
     },
     {
-        test: /^(meta_skill:|protocol:|stage_skill:|context_mode:)/,
+        test: /^(meta_skill:|protocol:|stage_skill:|context_mode:|reference:)/,
         metadata: {
             severity: "error",
             summary: "Routing skill and protocol integrity check.",

package/dist/install.js

@@ -28,6 +28,7 @@ import { stageCompleteScript, opencodePluginJs, claudeHooksJson, codexHooksJson,
 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";
+import { flowMapMarkdown } from "./content/flow-map.js";
 import { ARTIFACT_TEMPLATES, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildRulesJson } from "./content/templates.js";
 import { EVAL_BASELINES_README, EVAL_CONFIG_YAML, EVAL_CORPUS_README, EVAL_REPORTS_README, EVAL_RUBRIC_FILES, EVAL_RUBRICS_README } from "./content/eval-scaffold.js";
 import { TDD_BATCH_WALKTHROUGH_MARKDOWN, stageSkillFolder, stageSkillMarkdown } from "./content/skills.js";
@@ -355,6 +356,7 @@ async function writeSkills(projectRoot, config) {
     await writeFileSafe(runtimePath(projectRoot, "references", "protocols", "decision.md"), decisionProtocolMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "references", "protocols", "completion.md"), completionProtocolMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "references", "protocols", "ethos.md"), ethosProtocolMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "references", "flow-map.md"), flowMapMarkdown());
     for (const folder of UTILITY_SKILL_FOLDERS) {
         const generator = UTILITY_SKILL_MAP[folder];
         await writeFileSafe(runtimePath(projectRoot, "skills", folder, "SKILL.md"), generator());

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

@@ -142,6 +142,11 @@ export async function policyChecks(projectRoot, options = {}) {
         { file: runtimeFile("references/protocols/decision.md"), needle: "# Decision Protocol", name: "protocol:decision" },
         { file: runtimeFile("references/protocols/completion.md"), needle: "# Stage Completion Protocol", name: "protocol:completion" },
         { file: runtimeFile("references/protocols/ethos.md"), needle: "# Engineering Ethos", name: "protocol:ethos" },
+        { file: runtimeFile("references/flow-map.md"), needle: "# cclaw Flow Map", name: "reference:flow_map:header" },
+        { 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.13",
+  "version": "0.48.15",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {