cclaw-cli 0.48.14 → 0.48.16

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\`, ...). |
@@ -106,6 +118,11 @@ Hook-driven guards respect the \`strictness\` field in
 
 Override per-session with \`CCLAW_STRICTNESS=advisory|strict\`.
 
+Hook wiring itself comes from a **single manifest** (\`src/content/hook-manifest.ts\`):
+the per-harness documents at \`.claude/hooks/hooks.json\`, \`.cursor/hooks.json\`,
+\`.codex/hooks.json\` are all derived from it. Inspect the live bindings with
+\`cclaw internal hook-manifest\` (add \`--json\` for machine-readable output).
+
 ## When in doubt
 
 1. Read \`${RUNTIME_ROOT}/state/flow-state.json\` to know where you are.

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

@@ -1,4 +1,9 @@
 import type { HarnessId } from "../types.js";
-export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "pre_tool_prompt_guard", "pre_tool_workflow_guard", "post_tool_context_monitor", "stop_checkpoint", "precompact_digest"];
-export type HookSemanticEvent = (typeof HOOK_SEMANTIC_EVENTS)[number];
+import { type HookSemanticEvent } from "./hook-manifest.js";
+export { HOOK_SEMANTIC_EVENTS, type HookSemanticEvent } from "./hook-manifest.js";
+/**
+ * Public semantic coverage map derived from `HOOK_MANIFEST` for
+ * claude/cursor/codex, plus the static OpenCode descriptor. Consumers
+ * should treat this as read-only.
+ */
 export declare const HOOK_EVENTS_BY_HARNESS: Record<HarnessId, Partial<Record<HookSemanticEvent, string>>>;

package/dist/content/hook-events.js

@@ -1,47 +1,31 @@
-export const HOOK_SEMANTIC_EVENTS = [
-    "session_rehydrate",
-    "pre_tool_prompt_guard",
-    "pre_tool_workflow_guard",
-    "post_tool_context_monitor",
-    "stop_checkpoint",
-    "precompact_digest"
-];
-export const HOOK_EVENTS_BY_HARNESS = {
-    claude: {
-        session_rehydrate: "SessionStart matcher startup|resume|clear|compact",
-        pre_tool_prompt_guard: "PreToolUse -> prompt-guard",
-        pre_tool_workflow_guard: "PreToolUse -> workflow-guard",
-        post_tool_context_monitor: "PostToolUse -> context-monitor",
-        stop_checkpoint: "Stop -> stop-checkpoint",
-        precompact_digest: "PreCompact -> pre-compact"
-    },
-    cursor: {
-        session_rehydrate: "sessionStart/sessionResume/sessionClear/sessionCompact",
-        pre_tool_prompt_guard: "preToolUse -> prompt-guard",
-        pre_tool_workflow_guard: "preToolUse -> workflow-guard",
-        post_tool_context_monitor: "postToolUse -> context-monitor",
-        stop_checkpoint: "stop -> stop-checkpoint",
-        precompact_digest: "sessionCompact -> pre-compact"
-    },
-    opencode: {
-        session_rehydrate: "plugin event handlers + transform rehydration",
-        pre_tool_prompt_guard: "plugin tool.execute.before -> prompt-guard",
-        pre_tool_workflow_guard: "plugin tool.execute.before -> workflow-guard",
-        post_tool_context_monitor: "plugin tool.execute.after -> context-monitor",
-        stop_checkpoint: "plugin session.idle -> stop-checkpoint",
-        precompact_digest: "plugin session.compacted -> pre-compact"
-    },
-    codex: {
-        // Codex CLI v0.114+ exposes lifecycle hooks via `.codex/hooks.json`,
-        // gated by `[features] codex_hooks = true` in `~/.codex/config.toml`.
-        // SessionStart, Stop, and UserPromptSubmit fire for every turn;
-        // PreToolUse/PostToolUse are **Bash-only** (Write/Edit/WebSearch/MCP
-        // calls do not trigger them). `precompact_digest` is unmapped —
-        // Codex has no PreCompact event; cclaw covers it via `/cc-ops retro`.
-        session_rehydrate: "SessionStart matcher startup|resume",
-        pre_tool_prompt_guard: "PreToolUse matcher Bash -> prompt-guard (plus UserPromptSubmit for non-Bash prompts)",
-        pre_tool_workflow_guard: "PreToolUse matcher Bash -> workflow-guard (Bash-only)",
-        post_tool_context_monitor: "PostToolUse matcher Bash -> context-monitor (Bash-only)",
-        stop_checkpoint: "Stop -> stop-checkpoint"
-    }
+import { HOOK_MANIFEST_HARNESSES, semanticEventCoverage } from "./hook-manifest.js";
+export { HOOK_SEMANTIC_EVENTS } from "./hook-manifest.js";
+function isManifestHarness(value) {
+    return HOOK_MANIFEST_HARNESSES.includes(value);
+}
+/**
+ * OpenCode is covered by the inline plugin (`opencode-plugin.ts`), not
+ * by the generated `run-hook.mjs` dispatcher. We keep its semantic
+ * coverage table here as an explicit descriptor, since it does not
+ * flow through the hook manifest.
+ */
+const OPENCODE_SEMANTIC_COVERAGE = {
+    session_rehydrate: "plugin event handlers + transform rehydration",
+    pre_tool_prompt_guard: "plugin tool.execute.before -> prompt-guard",
+    pre_tool_workflow_guard: "plugin tool.execute.before -> workflow-guard",
+    post_tool_context_monitor: "plugin tool.execute.after -> context-monitor",
+    stop_checkpoint: "plugin session.idle -> stop-checkpoint",
+    precompact_digest: "plugin session.compacted -> pre-compact"
 };
+/**
+ * Public semantic coverage map derived from `HOOK_MANIFEST` for
+ * claude/cursor/codex, plus the static OpenCode descriptor. Consumers
+ * should treat this as read-only.
+ */
+export const HOOK_EVENTS_BY_HARNESS = Object.freeze({
+    claude: semanticEventCoverage("claude"),
+    cursor: semanticEventCoverage("cursor"),
+    codex: semanticEventCoverage("codex"),
+    opencode: OPENCODE_SEMANTIC_COVERAGE
+});
+void isManifestHarness;

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

@@ -0,0 +1,82 @@
+/**
+ * Canonical operational manifest for cclaw hooks.
+ *
+ * This is the **single source of truth** for:
+ *
+ *  - the per-harness JSON generators in `./observe.ts`
+ *    (claude/cursor/codex hook documents),
+ *  - the semantic coverage map in `./hook-events.ts` (docs + doctor),
+ *  - the `requiredEvents` list embedded in `src/hook-schemas/*.v1.json`
+ *    (enforced by a parity test).
+ *
+ * When adding a new hook handler or rerouting an existing one, edit
+ * this file and let the downstream modules rebuild from it. Never
+ * hard-code a `SessionStart`, `PreToolUse`, etc. mapping outside of
+ * this manifest.
+ *
+ * OpenCode is deliberately out of scope here: its plugin
+ * (`opencode-plugin.ts`) implements the handlers inline rather than
+ * dispatching through `run-hook.mjs`, so its coverage is tracked
+ * separately in `HOOK_EVENTS_BY_HARNESS`.
+ */
+export declare const HOOK_MANIFEST_HARNESSES: readonly ["claude", "cursor", "codex"];
+export type HookManifestHarness = (typeof HOOK_MANIFEST_HARNESSES)[number];
+export declare const HOOK_HANDLERS: readonly ["session-start", "prompt-guard", "workflow-guard", "context-monitor", "stop-checkpoint", "pre-compact", "verify-current-state"];
+export type HookHandlerId = (typeof HOOK_HANDLERS)[number];
+export interface HookBinding {
+    /**
+     * Harness-native event name (exact string; PascalCase for
+     * claude/codex, camelCase for cursor). Do not normalize casing.
+     */
+    event: string;
+    matcher?: string;
+    timeout?: number;
+    /**
+     * Within a single (harness, event) group, entries are sorted by
+     * `priority` ASC, ties broken by manifest-declaration order. Use
+     * this to express "this handler must run BEFORE/AFTER that handler
+     * on the same event" (e.g. pre-compact must run before session-start
+     * on cursor `sessionCompact`). Default `0`.
+     */
+    priority?: number;
+}
+export interface HookHandlerSpec {
+    handler: HookHandlerId;
+    description: string;
+    /**
+     * Semantic event id used by `HOOK_EVENTS_BY_HARNESS` / docs.
+     * `null` means this handler contributes no semantic coverage row
+     * (e.g. `verify-current-state` on codex is a supplementary guard,
+     * not a top-level semantic event).
+     */
+    semantic: HookSemanticEvent | null;
+    bindings: Partial<Record<HookManifestHarness, HookBinding[]>>;
+}
+export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "pre_tool_prompt_guard", "pre_tool_workflow_guard", "post_tool_context_monitor", "stop_checkpoint", "precompact_digest"];
+export type HookSemanticEvent = (typeof HOOK_SEMANTIC_EVENTS)[number];
+export declare const HOOK_MANIFEST: readonly HookHandlerSpec[];
+export interface EventGroup {
+    event: string;
+    /**
+     * Entries sorted by (priority ASC, declaration order). Default
+     * priority is 0. Stable — ties preserve manifest order.
+     */
+    entries: Array<{
+        handler: HookHandlerId;
+        matcher?: string;
+        timeout?: number;
+    }>;
+}
+/**
+ * Group manifest bindings by harness-native event name. This is the
+ * core projection that observe.ts generators consume to emit the
+ * harness-specific JSON document.
+ */
+export declare function groupBindingsByEvent(harness: HookManifestHarness): EventGroup[];
+/** 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 by
+ * the doctor's `harness-gaps.json` synthesis.
+ */
+export declare function semanticEventCoverage(harness: HookManifestHarness): Partial<Record<HookSemanticEvent, string>>;

package/dist/content/hook-manifest.js

@@ -0,0 +1,208 @@
+/**
+ * Canonical operational manifest for cclaw hooks.
+ *
+ * This is the **single source of truth** for:
+ *
+ *  - the per-harness JSON generators in `./observe.ts`
+ *    (claude/cursor/codex hook documents),
+ *  - the semantic coverage map in `./hook-events.ts` (docs + doctor),
+ *  - the `requiredEvents` list embedded in `src/hook-schemas/*.v1.json`
+ *    (enforced by a parity test).
+ *
+ * When adding a new hook handler or rerouting an existing one, edit
+ * this file and let the downstream modules rebuild from it. Never
+ * hard-code a `SessionStart`, `PreToolUse`, etc. mapping outside of
+ * this manifest.
+ *
+ * OpenCode is deliberately out of scope here: its plugin
+ * (`opencode-plugin.ts`) implements the handlers inline rather than
+ * dispatching through `run-hook.mjs`, so its coverage is tracked
+ * separately in `HOOK_EVENTS_BY_HARNESS`.
+ */
+export const HOOK_MANIFEST_HARNESSES = ["claude", "cursor", "codex"];
+export const HOOK_HANDLERS = [
+    "session-start",
+    "prompt-guard",
+    "workflow-guard",
+    "context-monitor",
+    "stop-checkpoint",
+    "pre-compact",
+    "verify-current-state"
+];
+export const HOOK_SEMANTIC_EVENTS = [
+    "session_rehydrate",
+    "pre_tool_prompt_guard",
+    "pre_tool_workflow_guard",
+    "post_tool_context_monitor",
+    "stop_checkpoint",
+    "precompact_digest"
+];
+export const HOOK_MANIFEST = [
+    {
+        handler: "session-start",
+        description: "Rehydrate flow state, refresh Ralph Loop + compound readiness, emit bootstrap digest.",
+        semantic: "session_rehydrate",
+        bindings: {
+            claude: [{ event: "SessionStart", matcher: "startup|resume|clear|compact" }],
+            cursor: [
+                { event: "sessionStart" },
+                { event: "sessionResume" },
+                { event: "sessionClear" },
+                { event: "sessionCompact" }
+            ],
+            codex: [{ event: "SessionStart", matcher: "startup|resume" }]
+        }
+    },
+    {
+        handler: "prompt-guard",
+        description: "Stage-aware prompt gate (iron-laws + strictness).",
+        semantic: "pre_tool_prompt_guard",
+        bindings: {
+            claude: [{ event: "PreToolUse", matcher: "*" }],
+            cursor: [{ event: "preToolUse", matcher: "*" }],
+            codex: [
+                { event: "UserPromptSubmit" },
+                { event: "PreToolUse", matcher: "Bash|bash" }
+            ]
+        }
+    },
+    {
+        handler: "workflow-guard",
+        description: "TDD and workflow gate on Write/Edit/Bash style tool invocations.",
+        semantic: "pre_tool_workflow_guard",
+        bindings: {
+            claude: [{ event: "PreToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash" }],
+            cursor: [{ event: "preToolUse", matcher: "*" }],
+            codex: [
+                { event: "UserPromptSubmit" },
+                { event: "PreToolUse", matcher: "Bash|bash" }
+            ]
+        }
+    },
+    {
+        handler: "context-monitor",
+        description: "Post-tool context usage + stage signal monitor.",
+        semantic: "post_tool_context_monitor",
+        bindings: {
+            claude: [{ event: "PostToolUse", matcher: "*" }],
+            cursor: [{ event: "postToolUse", matcher: "*" }],
+            codex: [{ event: "PostToolUse", matcher: "Bash|bash" }]
+        }
+    },
+    {
+        handler: "stop-checkpoint",
+        description: "Persist checkpoint with stage + run context on session stop.",
+        semantic: "stop_checkpoint",
+        bindings: {
+            claude: [{ event: "Stop", timeout: 10 }],
+            cursor: [{ event: "stop", timeout: 10 }],
+            codex: [{ event: "Stop", timeout: 10 }]
+        }
+    },
+    {
+        handler: "pre-compact",
+        description: "Write pre-compact digest (Claude+Cursor have a native event; Codex has no PreCompact — covered by `/cc-ops retro`).",
+        semantic: "precompact_digest",
+        bindings: {
+            claude: [{ event: "PreCompact", matcher: "manual|auto", timeout: 10 }],
+            // pre-compact must capture the digest BEFORE session-start
+            // rehydrates on cursor `sessionCompact`.
+            cursor: [{ event: "sessionCompact", priority: -10 }]
+        }
+    },
+    {
+        handler: "verify-current-state",
+        description: "Supplementary codex guard that runs on UserPromptSubmit to assert the live state matches the flow.",
+        semantic: null,
+        bindings: {
+            codex: [{ event: "UserPromptSubmit" }]
+        }
+    }
+];
+/** Sanity: every harness in HOOK_MANIFEST_HARNESSES must be a HarnessId. */
+const _harnessIdCheck = HOOK_MANIFEST_HARNESSES;
+void _harnessIdCheck;
+/**
+ * Group manifest bindings by harness-native event name. This is the
+ * core projection that observe.ts generators consume to emit the
+ * harness-specific JSON document.
+ */
+export function groupBindingsByEvent(harness) {
+    const order = [];
+    const byEvent = new Map();
+    let seq = 0;
+    for (const spec of HOOK_MANIFEST) {
+        const bindings = spec.bindings[harness];
+        if (!bindings)
+            continue;
+        for (const binding of bindings) {
+            let group = byEvent.get(binding.event);
+            if (!group) {
+                group = { event: binding.event, entries: [] };
+                byEvent.set(binding.event, group);
+                order.push(binding.event);
+            }
+            group.entries.push({
+                handler: spec.handler,
+                ...(binding.matcher !== undefined ? { matcher: binding.matcher } : {}),
+                ...(binding.timeout !== undefined ? { timeout: binding.timeout } : {}),
+                priority: binding.priority ?? 0,
+                seq: seq++
+            });
+        }
+    }
+    return order.map((event) => {
+        const group = byEvent.get(event);
+        const sorted = [...group.entries].sort((a, b) => {
+            if (a.priority !== b.priority)
+                return a.priority - b.priority;
+            return a.seq - b.seq;
+        });
+        return {
+            event: group.event,
+            entries: sorted.map(({ priority: _p, seq: _s, ...entry }) => entry)
+        };
+    });
+}
+/** Distinct harness-native event names covered by the manifest. */
+export function requiredEventsFor(harness) {
+    const seen = new Set();
+    const ordered = [];
+    for (const spec of HOOK_MANIFEST) {
+        for (const binding of spec.bindings[harness] ?? []) {
+            if (seen.has(binding.event))
+                continue;
+            seen.add(binding.event);
+            ordered.push(binding.event);
+        }
+    }
+    return ordered;
+}
+/**
+ * Human-readable per-harness semantic coverage used by docs and by
+ * the doctor's `harness-gaps.json` synthesis.
+ */
+export function semanticEventCoverage(harness) {
+    const out = {};
+    for (const spec of HOOK_MANIFEST) {
+        if (spec.semantic === null)
+            continue;
+        const bindings = spec.bindings[harness];
+        if (!bindings || bindings.length === 0)
+            continue;
+        out[spec.semantic] = describeBindings(bindings);
+    }
+    return out;
+}
+function describeBindings(bindings) {
+    return bindings
+        .map((binding) => {
+        const pieces = [binding.event];
+        if (binding.matcher)
+            pieces.push(`matcher=${binding.matcher}`);
+        if (binding.timeout)
+            pieces.push(`timeout=${binding.timeout}s`);
+        return pieces.join(" ");
+    })
+        .join(" | ");
+}

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/observe.d.ts

@@ -1,3 +1,19 @@
+import { type HookHandlerId, type HookManifestHarness } from "./hook-manifest.js";
 export declare function claudeHooksJsonWithObservation(): string;
 export declare function cursorHooksJsonWithObservation(): string;
 export declare function codexHooksJsonWithObservation(): string;
+/**
+ * Public accessor so diagnostic CLIs and tests can inspect the
+ * manifest without importing the private generator helpers.
+ */
+export declare function hookManifestSnapshot(): Array<{
+    harness: HookManifestHarness;
+    events: Array<{
+        event: string;
+        entries: Array<{
+            handler: HookHandlerId;
+            matcher?: string;
+            timeout?: number;
+        }>;
+    }>;
+}>;

package/dist/content/observe.js

@@ -1,4 +1,5 @@
 import { RUNTIME_ROOT } from "../constants.js";
+import { HOOK_MANIFEST, groupBindingsByEvent } from "./hook-manifest.js";
 function hookDispatcherCommand(hookName) {
     // RUNTIME_ROOT is a relative path (".cclaw") that currently contains no
     // whitespace, so quoting is unnecessary inside the JSON-encoded command
@@ -6,139 +7,83 @@ function hookDispatcherCommand(hookName) {
     // JSON.stringify to survive spaces.
     return `node ${RUNTIME_ROOT}/hooks/run-hook.mjs ${hookName}`;
 }
+/**
+ * Claude / Codex share the same outer envelope: each event is an
+ * array of `{matcher?, hooks: [{type: "command", command, timeout?}]}`
+ * objects. Entries with the same `matcher` are merged into a single
+ * outer entry so we emit one `{matcher: "..."}` block with multiple
+ * inner hook commands.
+ */
+function buildClaudeLikeEvents(harness) {
+    const out = {};
+    for (const group of groupBindingsByEvent(harness)) {
+        const mergedByMatcher = new Map();
+        const order = [];
+        for (const entry of group.entries) {
+            const matcherKey = entry.matcher ?? "__no_matcher__";
+            let bucket = mergedByMatcher.get(matcherKey);
+            if (!bucket) {
+                bucket = {
+                    ...(entry.matcher !== undefined ? { matcher: entry.matcher } : {}),
+                    hooks: []
+                };
+                mergedByMatcher.set(matcherKey, bucket);
+                order.push(matcherKey);
+            }
+            const hookEntry = {
+                type: "command",
+                command: hookDispatcherCommand(entry.handler),
+                ...(entry.timeout !== undefined ? { timeout: entry.timeout } : {})
+            };
+            bucket.hooks.push(hookEntry);
+        }
+        out[group.event] = order.map((key) => mergedByMatcher.get(key));
+    }
+    return out;
+}
+/**
+ * Cursor uses a flat shape: each event maps directly to an array of
+ * `{command, matcher?, timeout?}` entries — no inner `hooks` array.
+ */
+function buildCursorEvents() {
+    const out = {};
+    for (const group of groupBindingsByEvent("cursor")) {
+        out[group.event] = group.entries.map((entry) => ({
+            command: hookDispatcherCommand(entry.handler),
+            ...(entry.matcher !== undefined ? { matcher: entry.matcher } : {}),
+            ...(entry.timeout !== undefined ? { timeout: entry.timeout } : {})
+        }));
+    }
+    return out;
+}
 export function claudeHooksJsonWithObservation() {
     return JSON.stringify({
         cclawHookSchemaVersion: 1,
-        hooks: {
-            SessionStart: [{
-                    matcher: "startup|resume|clear|compact",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("session-start")
-                        }]
-                }],
-            PreToolUse: [{
-                    matcher: "*",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("prompt-guard")
-                        }]
-                }, {
-                    matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("workflow-guard")
-                        }]
-                }],
-            PostToolUse: [{
-                    matcher: "*",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("context-monitor")
-                        }]
-                }],
-            Stop: [{
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("stop-checkpoint"),
-                            timeout: 10
-                        }]
-                }],
-            PreCompact: [{
-                    matcher: "manual|auto",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("pre-compact"),
-                            timeout: 10
-                        }]
-                }]
-        }
+        hooks: buildClaudeLikeEvents("claude")
     }, null, 2);
 }
 export function cursorHooksJsonWithObservation() {
     return JSON.stringify({
         cclawHookSchemaVersion: 1,
         version: 1,
-        hooks: {
-            sessionStart: [{
-                    command: hookDispatcherCommand("session-start")
-                }],
-            sessionResume: [{
-                    command: hookDispatcherCommand("session-start")
-                }],
-            sessionClear: [{
-                    command: hookDispatcherCommand("session-start")
-                }],
-            sessionCompact: [{
-                    command: hookDispatcherCommand("pre-compact")
-                }, {
-                    command: hookDispatcherCommand("session-start")
-                }],
-            preToolUse: [{
-                    matcher: "*",
-                    command: hookDispatcherCommand("prompt-guard")
-                }, {
-                    matcher: "*",
-                    command: hookDispatcherCommand("workflow-guard")
-                }],
-            postToolUse: [{
-                    matcher: "*",
-                    command: hookDispatcherCommand("context-monitor")
-                }],
-            stop: [{
-                    command: hookDispatcherCommand("stop-checkpoint"),
-                    timeout: 10
-                }]
-        }
+        hooks: buildCursorEvents()
     }, null, 2);
 }
 export function codexHooksJsonWithObservation() {
     return JSON.stringify({
         cclawHookSchemaVersion: 1,
-        hooks: {
-            SessionStart: [{
-                    matcher: "startup|resume",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("session-start")
-                        }]
-                }],
-            UserPromptSubmit: [{
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("prompt-guard")
-                        }, {
-                            type: "command",
-                            command: hookDispatcherCommand("workflow-guard")
-                        }, {
-                            type: "command",
-                            command: hookDispatcherCommand("verify-current-state")
-                        }]
-                }],
-            PreToolUse: [{
-                    matcher: "Bash|bash",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("prompt-guard")
-                        }, {
-                            type: "command",
-                            command: hookDispatcherCommand("workflow-guard")
-                        }]
-                }],
-            PostToolUse: [{
-                    matcher: "Bash|bash",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("context-monitor")
-                        }]
-                }],
-            Stop: [{
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("stop-checkpoint"),
-                            timeout: 10
-                        }]
-                }]
-        }
+        hooks: buildClaudeLikeEvents("codex")
     }, null, 2);
 }
+/**
+ * Public accessor so diagnostic CLIs and tests can inspect the
+ * manifest without importing the private generator helpers.
+ */
+export function hookManifestSnapshot() {
+    return (HOOK_MANIFEST.length === 0
+        ? ["claude", "cursor", "codex"]
+        : ["claude", "cursor", "codex"]).map((harness) => ({
+        harness,
+        events: groupBindingsByEvent(harness)
+    }));
+}

package/dist/internal/advance-stage.js

@@ -12,6 +12,8 @@ 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 { runHookManifestCommand } from "./hook-manifest.js";
 import { runEnvelopeValidateCommand } from "./envelope-validate.js";
 import { runKnowledgeDigestCommand } from "./knowledge-digest.js";
 import { runTddLoopStatusCommand } from "./tdd-loop-status.js";
@@ -673,7 +675,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-manifest | hook\n");
         return 1;
     }
     try {
@@ -698,10 +700,16 @@ 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-manifest") {
+            return await runHookManifestCommand(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-manifest | 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/internal/hook-manifest.d.ts

@@ -0,0 +1,16 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+/**
+ * `cclaw internal hook-manifest` — diagnostic command that prints
+ * the resolved manifest. Primary use cases:
+ *
+ *  - debugging "which handler fires for event X on harness Y",
+ *  - migration tooling that needs a machine-readable view,
+ *  - parity verification between the source-of-truth manifest and
+ *    per-harness generated documents.
+ */
+export declare function runHookManifestCommand(_projectRoot: string, argv: string[], io: InternalIo): Promise<number>;
+export {};

package/dist/internal/hook-manifest.js

@@ -0,0 +1,77 @@
+import { HOOK_MANIFEST, HOOK_MANIFEST_HARNESSES, groupBindingsByEvent, requiredEventsFor } from "../content/hook-manifest.js";
+function parseArgs(tokens) {
+    const args = { json: false };
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token === "--json")
+            args.json = true;
+        else if (token === "--harness") {
+            const value = tokens[i + 1];
+            if (value !== "claude" && value !== "cursor" && value !== "codex") {
+                throw new Error(`--harness must be one of claude|cursor|codex, got ${String(value)}`);
+            }
+            args.harness = value;
+            i += 1;
+        }
+        else {
+            throw new Error(`Unknown hook-manifest flag: ${token}`);
+        }
+    }
+    return args;
+}
+/**
+ * `cclaw internal hook-manifest` — diagnostic command that prints
+ * the resolved manifest. Primary use cases:
+ *
+ *  - debugging "which handler fires for event X on harness Y",
+ *  - migration tooling that needs a machine-readable view,
+ *  - parity verification between the source-of-truth manifest and
+ *    per-harness generated documents.
+ */
+export async function runHookManifestCommand(_projectRoot, argv, io) {
+    const args = parseArgs(argv);
+    const harnesses = args.harness ? [args.harness] : [...HOOK_MANIFEST_HARNESSES];
+    if (args.json) {
+        const payload = {
+            handlers: HOOK_MANIFEST.map((spec) => ({
+                handler: spec.handler,
+                description: spec.description,
+                semantic: spec.semantic,
+                bindings: spec.bindings
+            })),
+            byHarness: Object.fromEntries(harnesses.map((harness) => [
+                harness,
+                {
+                    requiredEvents: requiredEventsFor(harness),
+                    events: groupBindingsByEvent(harness)
+                }
+            ]))
+        };
+        io.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return 0;
+    }
+    const lines = [];
+    lines.push("cclaw hook manifest");
+    for (const harness of harnesses) {
+        lines.push("");
+        lines.push(`## ${harness}`);
+        const groups = groupBindingsByEvent(harness);
+        if (groups.length === 0) {
+            lines.push("  (no bindings)");
+            continue;
+        }
+        for (const group of groups) {
+            lines.push(`  ${group.event}:`);
+            for (const entry of group.entries) {
+                const parts = [entry.handler];
+                if (entry.matcher)
+                    parts.push(`matcher=${entry.matcher}`);
+                if (entry.timeout)
+                    parts.push(`timeout=${entry.timeout}s`);
+                lines.push(`    - ${parts.join(" ")}`);
+            }
+        }
+    }
+    io.stdout.write(`${lines.join("\n")}\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.16",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {