cclaw-cli 0.48.31 → 0.48.33

package/dist/config.d.ts

@@ -42,7 +42,7 @@ export declare function readConfig(projectRoot: string): Promise<CclawConfig>;
  * the user set them explicitly. Keeps the default template small and honest:
  * only knobs a new user would meaningfully flip show up.
  */
-type AdvancedConfigKey = "tddTestGlobs" | "tdd" | "compound" | "defaultTrack" | "languageRulePacks" | "trackHeuristics" | "sliceReview" | "ironLaws";
+type AdvancedConfigKey = "tddTestGlobs" | "tdd" | "compound" | "defaultTrack" | "languageRulePacks" | "trackHeuristics" | "sliceReview" | "ironLaws" | "optInAudits" | "reviewLoop";
 /**
  * Options controlling the serialisation shape of `config.yaml`.
  *

package/dist/config.js

@@ -25,7 +25,9 @@ const ALLOWED_CONFIG_KEYS = new Set([
     "languageRulePacks",
     "trackHeuristics",
     "sliceReview",
-    "ironLaws"
+    "ironLaws",
+    "optInAudits",
+    "reviewLoop"
 ]);
 /**
  * Config keys removed in the advisory-by-default consolidation. Kept here so
@@ -429,6 +431,76 @@ export async function readConfig(projectRoot) {
     else {
         ironLaws = { strictLaws: [] };
     }
+    const optInAuditsRaw = parsed.optInAudits;
+    let optInAudits = undefined;
+    if (Object.prototype.hasOwnProperty.call(parsed, "optInAudits")) {
+        if (!isRecord(optInAuditsRaw)) {
+            throw configValidationError(fullPath, `"optInAudits" must be an object`);
+        }
+        const unknownOptInAuditKeys = Object.keys(optInAuditsRaw).filter((key) => key !== "scopePreAudit" && key !== "staleDiagramAudit");
+        if (unknownOptInAuditKeys.length > 0) {
+            throw configValidationError(fullPath, `"optInAudits" has unknown key(s): ${unknownOptInAuditKeys.join(", ")}`);
+        }
+        if (optInAuditsRaw.scopePreAudit !== undefined &&
+            typeof optInAuditsRaw.scopePreAudit !== "boolean") {
+            throw configValidationError(fullPath, `"optInAudits.scopePreAudit" must be a boolean`);
+        }
+        if (optInAuditsRaw.staleDiagramAudit !== undefined &&
+            typeof optInAuditsRaw.staleDiagramAudit !== "boolean") {
+            throw configValidationError(fullPath, `"optInAudits.staleDiagramAudit" must be a boolean`);
+        }
+        optInAudits = {
+            scopePreAudit: typeof optInAuditsRaw.scopePreAudit === "boolean"
+                ? optInAuditsRaw.scopePreAudit
+                : false,
+            staleDiagramAudit: typeof optInAuditsRaw.staleDiagramAudit === "boolean"
+                ? optInAuditsRaw.staleDiagramAudit
+                : false
+        };
+    }
+    const reviewLoopRaw = parsed.reviewLoop;
+    let reviewLoop = undefined;
+    if (Object.prototype.hasOwnProperty.call(parsed, "reviewLoop")) {
+        if (!isRecord(reviewLoopRaw)) {
+            throw configValidationError(fullPath, `"reviewLoop" must be an object`);
+        }
+        const unknownReviewLoopKeys = Object.keys(reviewLoopRaw).filter((key) => key !== "externalSecondOpinion");
+        if (unknownReviewLoopKeys.length > 0) {
+            throw configValidationError(fullPath, `"reviewLoop" has unknown key(s): ${unknownReviewLoopKeys.join(", ")}`);
+        }
+        const externalRaw = reviewLoopRaw.externalSecondOpinion;
+        let externalSecondOpinion = undefined;
+        if (externalRaw !== undefined) {
+            if (!isRecord(externalRaw)) {
+                throw configValidationError(fullPath, `"reviewLoop.externalSecondOpinion" must be an object`);
+            }
+            const unknownExternalKeys = Object.keys(externalRaw).filter((key) => key !== "enabled" && key !== "model" && key !== "scoreDeltaThreshold");
+            if (unknownExternalKeys.length > 0) {
+                throw configValidationError(fullPath, `"reviewLoop.externalSecondOpinion" has unknown key(s): ${unknownExternalKeys.join(", ")}`);
+            }
+            if (externalRaw.enabled !== undefined && typeof externalRaw.enabled !== "boolean") {
+                throw configValidationError(fullPath, `"reviewLoop.externalSecondOpinion.enabled" must be a boolean`);
+            }
+            if (externalRaw.model !== undefined && typeof externalRaw.model !== "string") {
+                throw configValidationError(fullPath, `"reviewLoop.externalSecondOpinion.model" must be a string`);
+            }
+            if (externalRaw.scoreDeltaThreshold !== undefined &&
+                (typeof externalRaw.scoreDeltaThreshold !== "number" ||
+                    Number.isNaN(externalRaw.scoreDeltaThreshold) ||
+                    externalRaw.scoreDeltaThreshold < 0 ||
+                    externalRaw.scoreDeltaThreshold > 1)) {
+                throw configValidationError(fullPath, `"reviewLoop.externalSecondOpinion.scoreDeltaThreshold" must be a number between 0 and 1`);
+            }
+            externalSecondOpinion = {
+                enabled: externalRaw.enabled === true,
+                model: typeof externalRaw.model === "string" ? externalRaw.model : undefined,
+                scoreDeltaThreshold: typeof externalRaw.scoreDeltaThreshold === "number"
+                    ? externalRaw.scoreDeltaThreshold
+                    : 0.2
+            };
+        }
+        reviewLoop = { externalSecondOpinion };
+    }
     return {
         version: parsed.version ?? CCLAW_VERSION,
         flowVersion: parsed.flowVersion ?? FLOW_VERSION,
@@ -447,7 +519,9 @@ export async function readConfig(projectRoot) {
         languageRulePacks,
         trackHeuristics,
         sliceReview,
-        ironLaws
+        ironLaws,
+        optInAudits,
+        reviewLoop
     };
 }
 function isMinimalKey(key) {
@@ -470,7 +544,9 @@ function buildSerializableConfig(config, options = {}) {
         "languageRulePacks",
         "trackHeuristics",
         "sliceReview",
-        "ironLaws"
+        "ironLaws",
+        "optInAudits",
+        "reviewLoop"
     ];
     for (const key of ordered) {
         const value = config[key];
@@ -523,7 +599,9 @@ export async function detectAdvancedKeys(projectRoot) {
             "languageRulePacks",
             "trackHeuristics",
             "sliceReview",
-            "ironLaws"
+            "ironLaws",
+            "optInAudits",
+            "reviewLoop"
         ];
         const present = new Set();
         for (const key of advancedCandidates) {

package/dist/content/examples.js

@@ -18,18 +18,35 @@ const STAGE_EXAMPLES = {
 | 2 | Should the validation logic live in a reusable module or stay as shell scripts? | Reusable module. | Architecture: shared TypeScript module imported by CI and local tooling, not duplicated shell scripts. |
 | 3 | For v1, prioritize rapid delivery or maximum configurability? | Rapid delivery. | Minimal deterministic validation surface; defer plugin/config system to v2. |
 
+## Approach Tier
+
+- **Tier:** Standard
+- **Why this tier:** Change spans CI + local release workflow and shared module boundaries, but remains bounded to one subsystem.
+
+## Short-Circuit Decision
+
+- **Status:** bypassed
+- **Why:** Core requirements were not concrete enough initially; we still needed options + trade-off conversation.
+- **Scope handoff:** Continue full brainstorm flow before scope.
+
 ## Approaches
 
-| Approach | Architecture | Trade-offs | Recommendation |
-| --- | --- | --- | --- |
-| A: Reusable validation module | Shared TS module with typed validators, imported by CI scripts and local CLI. Existing \`pre-publish.sh\` calls the module. | Medium upfront effort, high reuse. Requires test coverage for the module. | **Recommended** — best balance of reuse and delivery speed. |
-| B: Hardened shell scripts | Keep existing script approach, add stricter checks and error messages. | Lowest effort. Weak reuse, CI/local divergence risk grows over time. | Viable fallback if TS module is blocked. |
-| C: Full release framework | New release orchestrator with plugin system, config files, rollback commands. | Maximum flexibility. High risk, delivery delay, over-engineered for current needs. | Not recommended for v1. |
+| Approach | Role | Architecture | Trade-offs | Recommendation |
+| --- | --- | --- | --- | --- |
+| A: Reusable validation module | baseline | Shared TS module with typed validators, imported by CI scripts and local CLI. Existing \`pre-publish.sh\` calls the module. | Medium upfront effort, high reuse. Requires test coverage for the module. | **Recommended** — best balance of reuse and delivery speed. |
+| B: Hardened shell scripts | fallback | Keep existing script approach, add stricter checks and error messages. | Lowest effort. Weak reuse, CI/local divergence risk grows over time. | Viable fallback if TS module is blocked. |
+| C: Full release framework | challenger: higher-upside | New release orchestrator with plugin system, config files, rollback commands. | Maximum flexibility. High risk, delivery delay, over-engineered for current needs. | Not recommended for v1. |
+
+## Approach Reaction
+
+- **Closest option:** A (reusable validation module).
+- **Concerns:** User wanted to avoid framework-level overbuild and keep v1 delivery speed high.
+- **What changed after reaction:** Recommendation stayed on A, but added explicit fallback path via existing shell entrypoint to reduce migration risk.
 
 ## Selected Direction
 
 - **Approach:** A — Reusable validation module
-- **Rationale:** shared TS module gives consistent behavior in CI and local, avoids script duplication, and stays within the no-new-dependency constraint.
+- **Rationale:** based on user reaction favoring fast delivery and lower complexity, shared TS module gives consistent behavior in CI/local, avoids script duplication, and stays within the no-new-dependency constraint.
 - **Approval:** approved
 
 ## Design

package/dist/content/hook-inline-snippets.d.ts

@@ -0,0 +1,80 @@
+/**
+ * hook-inline-snippets.ts
+ *
+ * Runtime `.cclaw/hooks/run-hook.mjs` is a **standalone Node script** that
+ * cannot import from `cclaw-cli` — it must work inside the end-user's
+ * project even when the CLI is not installed. Two derived computations,
+ * though, must remain 1:1 with the canonical TS implementations:
+ *
+ * 1. `computeCompoundReadinessInline` mirrors
+ *    `src/knowledge-store.ts::computeCompoundReadiness`.
+ * 2. `computeRalphLoopStatusInline` mirrors
+ *    `src/tdd-cycle.ts::computeRalphLoopStatus`.
+ *
+ * Previously those bodies lived inline in `src/content/node-hooks.ts` — a
+ * ~2000-line file — next to unrelated hook-handler code. Any silent drift
+ * only surfaced when someone remembered to update both sides.
+ *
+ * This module centralizes the inline JavaScript snippets so:
+ *
+ * - There is exactly **one place** (this file) that holds each inline
+ *   JS body.
+ * - Each snippet carries an explicit "mirrors X, parity enforced by Y"
+ *   header comment and is emitted into `run-hook.mjs` verbatim.
+ * - `src/content/node-hooks.ts` only interpolates the snippets, it no
+ *   longer owns their source code.
+ *
+ * Parity with the TypeScript canonical implementations is enforced by
+ * `tests/unit/ralph-loop-parity.test.ts`. Any structural change to the
+ * canonical TS code MUST:
+ *
+ * 1. Update the matching snippet below.
+ * 2. Re-run `npm test tests/unit/ralph-loop-parity.test.ts`.
+ *
+ * DO NOT inline tests here — keep the parity check in its dedicated test
+ * file.
+ */
+/**
+ * Inline JS helpers used by both compound-readiness and ralph-loop
+ * snippets. Kept small and locked: they are shared across the two inline
+ * routines and must not grow into a hidden utility namespace.
+ *
+ * - `normalizeCompoundLastUpdatedAt` produces a stable ISO-8601 UTC
+ *   timestamp so the hook-written `compound-readiness.json` is byte-equal
+ *   to the CLI-written version for the same input.
+ * - `countArchivedRunsInline` counts immediate subdirectories of
+ *   `<root>/.cclaw/runs/` so both the hook and the CLI see the same
+ *   `archivedRunsCount` for the small-project relaxation.
+ */
+export declare const HOOK_INLINE_SHARED_HELPERS = "\nfunction normalizeCompoundLastUpdatedAt(date) {\n  return date.toISOString().replace(/\\.\\d{3}Z$/u, \"Z\");\n}\n\n// Count archived runs as sub-directories under `.cclaw/runs/`. Missing\n// dir returns 0; unexpected errors return undefined so the caller can\n// skip the small-project relaxation rather than guess.\nasync function countArchivedRunsInline(root) {\n  const dir = path.join(root, RUNTIME_ROOT, \"runs\");\n  try {\n    const entries = await fs.readdir(dir, { withFileTypes: true });\n    return entries.filter((entry) => entry.isDirectory()).length;\n  } catch (error) {\n    const code = error && typeof error === \"object\" && \"code\" in error ? error.code : null;\n    if (code === \"ENOENT\") return 0;\n    return undefined;\n  }\n}\n";
+/**
+ * Inline mirror of `src/knowledge-store.ts::computeCompoundReadiness`.
+ *
+ * Parity enforced by
+ * `tests/unit/ralph-loop-parity.test.ts::compound-readiness parity`.
+ *
+ * Signature contract:
+ *   async function computeCompoundReadinessInline(root, options) -> CompoundReadiness
+ *
+ * Accepted options (all optional):
+ * - prereadRaw: string | undefined — pre-read `knowledge.jsonl` contents.
+ * - threshold: integer >= 1 — default recurrence threshold.
+ * - archivedRunsCount: integer >= 0 — enables small-project relaxation.
+ * - maxReady: integer >= 1 — cap on returned `ready` cluster count
+ *   (default 10).
+ *
+ * Depends on: `SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD`,
+ * `SMALL_PROJECT_RECURRENCE_THRESHOLD`, `COMPOUND_RECURRENCE_THRESHOLD`,
+ * and `HOOK_INLINE_SHARED_HELPERS` being in the same runtime scope.
+ */
+export declare const COMPOUND_READINESS_INLINE_SOURCE = "\nasync function computeCompoundReadinessInline(root, options) {\n  const filePath = path.join(root, RUNTIME_ROOT, \"knowledge.jsonl\");\n  // Caller may supply pre-read raw to avoid double-reading knowledge.jsonl.\n  const raw = typeof (options && options.prereadRaw) === \"string\"\n    ? options.prereadRaw\n    : await readTextFile(filePath, \"\");\n  const baseThresholdRaw = options && options.threshold;\n  const baseThreshold = Number.isInteger(baseThresholdRaw) && baseThresholdRaw >= 1\n    ? baseThresholdRaw\n    : COMPOUND_RECURRENCE_THRESHOLD;\n  const archivedRunsCount =\n    typeof (options && options.archivedRunsCount) === \"number\" &&\n    Number.isFinite(options.archivedRunsCount) &&\n    options.archivedRunsCount >= 0\n      ? Math.floor(options.archivedRunsCount)\n      : undefined;\n  const smallProjectRelaxationApplied =\n    archivedRunsCount !== undefined &&\n    archivedRunsCount < SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD &&\n    baseThreshold > SMALL_PROJECT_RECURRENCE_THRESHOLD;\n  const threshold = smallProjectRelaxationApplied\n    ? SMALL_PROJECT_RECURRENCE_THRESHOLD\n    : baseThreshold;\n  const maxReady = Number.isInteger(options && options.maxReady) && options.maxReady >= 1\n    ? options.maxReady\n    : 10;\n  const normalize = (value) => String(value == null ? \"\" : value).trim().replace(/\\s+/gu, \" \").toLowerCase();\n  const severityWeight = (sev) => {\n    if (sev === \"critical\") return 3;\n    if (sev === \"important\") return 2;\n    if (sev === \"suggestion\") return 1;\n    return 0;\n  };\n  const buckets = new Map();\n  for (const rawLine of raw.split(/\\r?\\n/gu)) {\n    const line = rawLine.trim();\n    if (line.length === 0) continue;\n    let row;\n    try { row = JSON.parse(line); } catch { continue; }\n    if (!row || typeof row !== \"object\" || Array.isArray(row)) continue;\n    if (row.maturity === \"lifted-to-enforcement\") continue;\n    const type = typeof row.type === \"string\" ? row.type : \"\";\n    const trigger = typeof row.trigger === \"string\" ? row.trigger : \"\";\n    const action = typeof row.action === \"string\" ? row.action : \"\";\n    if (type.length === 0 || trigger.length === 0 || action.length === 0) continue;\n    const key = type + \"||\" + normalize(trigger) + \"||\" + normalize(action);\n    const frequency = Number.isInteger(row.frequency) && row.frequency > 0 ? Math.floor(row.frequency) : 1;\n    const lastSeen = typeof row.last_seen_ts === \"string\" ? row.last_seen_ts : \"\";\n    let bucket = buckets.get(key);\n    if (!bucket) {\n      bucket = {\n        trigger,\n        action,\n        recurrence: frequency,\n        entryCount: 1,\n        severity: typeof row.severity === \"string\" ? row.severity : undefined,\n        lastSeenTs: lastSeen,\n        types: new Set([type]),\n        maturity: new Set([typeof row.maturity === \"string\" ? row.maturity : \"raw\"])\n      };\n      buckets.set(key, bucket);\n      continue;\n    }\n    bucket.recurrence += frequency;\n    bucket.entryCount += 1;\n    bucket.types.add(type);\n    bucket.maturity.add(typeof row.maturity === \"string\" ? row.maturity : \"raw\");\n    if (row.severity === \"critical\") {\n      bucket.severity = \"critical\";\n    } else if (row.severity === \"important\" && bucket.severity !== \"critical\") {\n      bucket.severity = \"important\";\n    }\n    if (lastSeen && Date.parse(lastSeen) > Date.parse(bucket.lastSeenTs || \"0\")) {\n      bucket.lastSeenTs = lastSeen;\n    }\n  }\n  const ready = [];\n  for (const bucket of buckets.values()) {\n    const criticalOverride = bucket.severity === \"critical\";\n    const meetsRecurrence = bucket.recurrence >= threshold;\n    if (!criticalOverride && !meetsRecurrence) continue;\n    ready.push({\n      trigger: bucket.trigger,\n      action: bucket.action,\n      recurrence: bucket.recurrence,\n      entryCount: bucket.entryCount,\n      qualification: criticalOverride && !meetsRecurrence ? \"critical_override\" : \"recurrence\",\n      ...(bucket.severity ? { severity: bucket.severity } : {}),\n      lastSeenTs: bucket.lastSeenTs,\n      types: Array.from(bucket.types).sort(),\n      maturity: Array.from(bucket.maturity).sort()\n    });\n  }\n  ready.sort((a, b) => {\n    const sevDiff = severityWeight(b.severity) - severityWeight(a.severity);\n    if (sevDiff !== 0) return sevDiff;\n    if (b.recurrence !== a.recurrence) return b.recurrence - a.recurrence;\n    const recencyDiff = Date.parse(b.lastSeenTs || \"0\") - Date.parse(a.lastSeenTs || \"0\");\n    if (!Number.isNaN(recencyDiff) && recencyDiff !== 0) return recencyDiff;\n    return String(a.trigger).localeCompare(String(b.trigger));\n  });\n  return {\n    schemaVersion: 2,\n    threshold,\n    baseThreshold,\n    ...(archivedRunsCount !== undefined ? { archivedRunsCount } : {}),\n    smallProjectRelaxationApplied,\n    clusterCount: buckets.size,\n    readyCount: ready.length,\n    ready: ready.slice(0, maxReady),\n    lastUpdatedAt: normalizeCompoundLastUpdatedAt(new Date())\n  };\n}\n";
+/**
+ * Inline mirror of `src/tdd-cycle.ts::computeRalphLoopStatus`.
+ *
+ * Parity enforced by
+ * `tests/unit/ralph-loop-parity.test.ts::ralph-loop parity`.
+ *
+ * Signature contract:
+ *   async function computeRalphLoopStatusInline(stateDir, runId) -> RalphLoopStatus
+ */
+export declare const RALPH_LOOP_INLINE_SOURCE = "\nasync function computeRalphLoopStatusInline(stateDir, runId) {\n  const filePath = path.join(stateDir, \"tdd-cycle-log.jsonl\");\n  const raw = await readTextFile(filePath, \"\");\n  const sliceMap = new Map();\n  const acClosed = new Set();\n  const redOpenSlices = [];\n  let loopIteration = 0;\n  for (const rawLine of raw.split(/\\r?\\n/gu)) {\n    const line = rawLine.trim();\n    if (line.length === 0) continue;\n    let row;\n    try { row = JSON.parse(line); } catch { continue; }\n    if (!row || typeof row !== \"object\" || Array.isArray(row)) continue;\n    const rowRun = typeof row.runId === \"string\" && row.runId.length > 0 ? row.runId : runId;\n    if (rowRun !== runId) continue;\n    const slice = typeof row.slice === \"string\" && row.slice.length > 0 ? row.slice : \"S-unknown\";\n    let state = sliceMap.get(slice);\n    if (!state) {\n      state = { slice, redCount: 0, greenCount: 0, refactorCount: 0, redOpen: false, acIds: [] };\n      sliceMap.set(slice, state);\n    }\n    const exitCode = typeof row.exitCode === \"number\" ? row.exitCode : undefined;\n    if (row.phase === \"red\") {\n      state.redCount += 1;\n      if (exitCode !== undefined && exitCode !== 0) state.redOpen = true;\n    } else if (row.phase === \"green\") {\n      state.greenCount += 1;\n      state.redOpen = false;\n      loopIteration += 1;\n      if (Array.isArray(row.acIds)) {\n        for (const acId of row.acIds) {\n          if (typeof acId !== \"string\" || acId.length === 0) continue;\n          acClosed.add(acId);\n          if (!state.acIds.includes(acId)) state.acIds.push(acId);\n        }\n      }\n    } else if (row.phase === \"refactor\") {\n      state.refactorCount += 1;\n    }\n  }\n  for (const state of sliceMap.values()) {\n    if (state.redOpen) redOpenSlices.push(state.slice);\n  }\n  const slices = Array.from(sliceMap.values()).sort((a, b) => a.slice.localeCompare(b.slice, \"en\"));\n  return {\n    schemaVersion: 1,\n    runId,\n    loopIteration,\n    redOpen: redOpenSlices.length > 0,\n    redOpenSlices,\n    acClosed: Array.from(acClosed).sort(),\n    sliceCount: slices.length,\n    slices,\n    lastUpdatedAt: new Date().toISOString()\n  };\n}\n";

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

@@ -0,0 +1,270 @@
+/**
+ * hook-inline-snippets.ts
+ *
+ * Runtime `.cclaw/hooks/run-hook.mjs` is a **standalone Node script** that
+ * cannot import from `cclaw-cli` — it must work inside the end-user's
+ * project even when the CLI is not installed. Two derived computations,
+ * though, must remain 1:1 with the canonical TS implementations:
+ *
+ * 1. `computeCompoundReadinessInline` mirrors
+ *    `src/knowledge-store.ts::computeCompoundReadiness`.
+ * 2. `computeRalphLoopStatusInline` mirrors
+ *    `src/tdd-cycle.ts::computeRalphLoopStatus`.
+ *
+ * Previously those bodies lived inline in `src/content/node-hooks.ts` — a
+ * ~2000-line file — next to unrelated hook-handler code. Any silent drift
+ * only surfaced when someone remembered to update both sides.
+ *
+ * This module centralizes the inline JavaScript snippets so:
+ *
+ * - There is exactly **one place** (this file) that holds each inline
+ *   JS body.
+ * - Each snippet carries an explicit "mirrors X, parity enforced by Y"
+ *   header comment and is emitted into `run-hook.mjs` verbatim.
+ * - `src/content/node-hooks.ts` only interpolates the snippets, it no
+ *   longer owns their source code.
+ *
+ * Parity with the TypeScript canonical implementations is enforced by
+ * `tests/unit/ralph-loop-parity.test.ts`. Any structural change to the
+ * canonical TS code MUST:
+ *
+ * 1. Update the matching snippet below.
+ * 2. Re-run `npm test tests/unit/ralph-loop-parity.test.ts`.
+ *
+ * DO NOT inline tests here — keep the parity check in its dedicated test
+ * file.
+ */
+/**
+ * Inline JS helpers used by both compound-readiness and ralph-loop
+ * snippets. Kept small and locked: they are shared across the two inline
+ * routines and must not grow into a hidden utility namespace.
+ *
+ * - `normalizeCompoundLastUpdatedAt` produces a stable ISO-8601 UTC
+ *   timestamp so the hook-written `compound-readiness.json` is byte-equal
+ *   to the CLI-written version for the same input.
+ * - `countArchivedRunsInline` counts immediate subdirectories of
+ *   `<root>/.cclaw/runs/` so both the hook and the CLI see the same
+ *   `archivedRunsCount` for the small-project relaxation.
+ */
+export const HOOK_INLINE_SHARED_HELPERS = `
+function normalizeCompoundLastUpdatedAt(date) {
+  return date.toISOString().replace(/\\.\\d{3}Z$/u, "Z");
+}
+
+// Count archived runs as sub-directories under \`.cclaw/runs/\`. Missing
+// dir returns 0; unexpected errors return undefined so the caller can
+// skip the small-project relaxation rather than guess.
+async function countArchivedRunsInline(root) {
+  const dir = path.join(root, RUNTIME_ROOT, "runs");
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).length;
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? error.code : null;
+    if (code === "ENOENT") return 0;
+    return undefined;
+  }
+}
+`;
+/**
+ * Inline mirror of `src/knowledge-store.ts::computeCompoundReadiness`.
+ *
+ * Parity enforced by
+ * `tests/unit/ralph-loop-parity.test.ts::compound-readiness parity`.
+ *
+ * Signature contract:
+ *   async function computeCompoundReadinessInline(root, options) -> CompoundReadiness
+ *
+ * Accepted options (all optional):
+ * - prereadRaw: string | undefined — pre-read `knowledge.jsonl` contents.
+ * - threshold: integer >= 1 — default recurrence threshold.
+ * - archivedRunsCount: integer >= 0 — enables small-project relaxation.
+ * - maxReady: integer >= 1 — cap on returned `ready` cluster count
+ *   (default 10).
+ *
+ * Depends on: `SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD`,
+ * `SMALL_PROJECT_RECURRENCE_THRESHOLD`, `COMPOUND_RECURRENCE_THRESHOLD`,
+ * and `HOOK_INLINE_SHARED_HELPERS` being in the same runtime scope.
+ */
+export const COMPOUND_READINESS_INLINE_SOURCE = `
+async function computeCompoundReadinessInline(root, options) {
+  const filePath = path.join(root, RUNTIME_ROOT, "knowledge.jsonl");
+  // Caller may supply pre-read raw to avoid double-reading knowledge.jsonl.
+  const raw = typeof (options && options.prereadRaw) === "string"
+    ? options.prereadRaw
+    : await readTextFile(filePath, "");
+  const baseThresholdRaw = options && options.threshold;
+  const baseThreshold = Number.isInteger(baseThresholdRaw) && baseThresholdRaw >= 1
+    ? baseThresholdRaw
+    : COMPOUND_RECURRENCE_THRESHOLD;
+  const archivedRunsCount =
+    typeof (options && options.archivedRunsCount) === "number" &&
+    Number.isFinite(options.archivedRunsCount) &&
+    options.archivedRunsCount >= 0
+      ? Math.floor(options.archivedRunsCount)
+      : undefined;
+  const smallProjectRelaxationApplied =
+    archivedRunsCount !== undefined &&
+    archivedRunsCount < SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD &&
+    baseThreshold > SMALL_PROJECT_RECURRENCE_THRESHOLD;
+  const threshold = smallProjectRelaxationApplied
+    ? SMALL_PROJECT_RECURRENCE_THRESHOLD
+    : baseThreshold;
+  const maxReady = Number.isInteger(options && options.maxReady) && options.maxReady >= 1
+    ? options.maxReady
+    : 10;
+  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: 2,
+    threshold,
+    baseThreshold,
+    ...(archivedRunsCount !== undefined ? { archivedRunsCount } : {}),
+    smallProjectRelaxationApplied,
+    clusterCount: buckets.size,
+    readyCount: ready.length,
+    ready: ready.slice(0, maxReady),
+    lastUpdatedAt: normalizeCompoundLastUpdatedAt(new Date())
+  };
+}
+`;
+/**
+ * Inline mirror of `src/tdd-cycle.ts::computeRalphLoopStatus`.
+ *
+ * Parity enforced by
+ * `tests/unit/ralph-loop-parity.test.ts::ralph-loop parity`.
+ *
+ * Signature contract:
+ *   async function computeRalphLoopStatusInline(stateDir, runId) -> RalphLoopStatus
+ */
+export const RALPH_LOOP_INLINE_SOURCE = `
+async function computeRalphLoopStatusInline(stateDir, runId) {
+  const filePath = path.join(stateDir, "tdd-cycle-log.jsonl");
+  const raw = await readTextFile(filePath, "");
+  const sliceMap = new Map();
+  const acClosed = new Set();
+  const redOpenSlices = [];
+  let loopIteration = 0;
+  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;
+    const rowRun = typeof row.runId === "string" && row.runId.length > 0 ? row.runId : runId;
+    if (rowRun !== runId) continue;
+    const slice = typeof row.slice === "string" && row.slice.length > 0 ? row.slice : "S-unknown";
+    let state = sliceMap.get(slice);
+    if (!state) {
+      state = { slice, redCount: 0, greenCount: 0, refactorCount: 0, redOpen: false, acIds: [] };
+      sliceMap.set(slice, state);
+    }
+    const exitCode = typeof row.exitCode === "number" ? row.exitCode : undefined;
+    if (row.phase === "red") {
+      state.redCount += 1;
+      if (exitCode !== undefined && exitCode !== 0) state.redOpen = true;
+    } else if (row.phase === "green") {
+      state.greenCount += 1;
+      state.redOpen = false;
+      loopIteration += 1;
+      if (Array.isArray(row.acIds)) {
+        for (const acId of row.acIds) {
+          if (typeof acId !== "string" || acId.length === 0) continue;
+          acClosed.add(acId);
+          if (!state.acIds.includes(acId)) state.acIds.push(acId);
+        }
+      }
+    } else if (row.phase === "refactor") {
+      state.refactorCount += 1;
+    }
+  }
+  for (const state of sliceMap.values()) {
+    if (state.redOpen) redOpenSlices.push(state.slice);
+  }
+  const slices = Array.from(sliceMap.values()).sort((a, b) => a.slice.localeCompare(b.slice, "en"));
+  return {
+    schemaVersion: 1,
+    runId,
+    loopIteration,
+    redOpen: redOpenSlices.length > 0,
+    redOpenSlices,
+    acClosed: Array.from(acClosed).sort(),
+    sliceCount: slices.length,
+    slices,
+    lastUpdatedAt: new Date().toISOString()
+  };
+}
+`;

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

@@ -1,2 +1,6 @@
-export declare function ideateCommandContract(): string;
-export declare function ideateCommandSkillMarkdown(): string;
+import { type IdeateFrameId } from "./ideate-frames.js";
+export interface IdeateCommandOptions {
+    frameIds?: readonly IdeateFrameId[];
+}
+export declare function ideateCommandContract(options?: IdeateCommandOptions): string;
+export declare function ideateCommandSkillMarkdown(options?: IdeateCommandOptions): string;

package/dist/content/ideate-command.js

@@ -1,4 +1,5 @@
 import { RUNTIME_ROOT } from "../constants.js";
+import { resolveIdeateFrames } from "./ideate-frames.js";
 const IDEATE_SKILL_FOLDER = "flow-ideate";
 const IDEATE_SKILL_NAME = "flow-ideate";
 /**
@@ -18,7 +19,20 @@ const STRUCTURED_ASK_TOOLS = "`AskUserQuestion` on Claude, `AskQuestion` on Curs
     "`question` on OpenCode when `permission.question: \"allow\"` is set, " +
     "`request_user_input` on Codex in Plan / Collaboration mode; " +
     "fall back to a plain-text lettered list when the tool is hidden or errors";
-export function ideateCommandContract() {
+function renderFrameBullets(frameIds) {
+    return resolveIdeateFrames(frameIds)
+        .map((frame) => `   - ${frame.label} (\`${frame.id}\`)`)
+        .join("\n");
+}
+function renderFrameNames(frameIds) {
+    return resolveIdeateFrames(frameIds)
+        .map((frame) => frame.label)
+        .join(", ");
+}
+export function ideateCommandContract(options = {}) {
+    const frames = resolveIdeateFrames(options.frameIds);
+    const frameBullets = renderFrameBullets(options.frameIds);
+    const minimumDistinctFrames = Math.min(4, frames.length);
     return `# /cc-ideate
 
 ## Purpose
@@ -51,17 +65,24 @@ same session, or save/discard the backlog.
      repetition scan.
    - Elsewhere-software: docs-first grounding (Context7 and official docs).
    - Elsewhere-non-software: constraints and objective grounding.
-4. **Divergent ideation frames (parallel).** Generate candidates with at least
-   4 distinct frames: pain/friction, inversion, assumption-break, leverage,
-   cross-domain analogy, constraint-flip.
+4. **Divergent ideation frames (parallel).** Generate candidates with
+   configured frames (${frames.length} total):
+${frameBullets}
+   Keep at least ${minimumDistinctFrames} distinct frame outputs in every run.
 5. **Adversarial critique pass.** For each candidate, write the strongest
    counter-argument, kill weak ideas, and keep survivors only.
 6. **Produce 5-10 survivors** with impact (High/Medium/Low),
    effort (S/M/L), confidence (High/Medium/Low), and one evidence path per
    survivor.
-7. **Rank by impact/effort**, recommend the top survivor.
+7. **Rank by impact/effort/confidence** using
+   \`(impact points / effort cost) * confidence multiplier\` and recommend
+   the top survivor.
 8. **Write the artifact** at
    \`${IDEATE_ARTIFACT_PATTERN}\` using the schema in the skill.
+8.5 **Seed shelf (optional).** For critiqued-out or deferred ideas that still
+   show upside, write seed notes to
+   \`${RUNTIME_ROOT}/seeds/SEED-<YYYY-MM-DD>-<slug>.md\` with
+   \`trigger_when\`, hypothesis, and suggested action.
 9. **Present the handoff prompt** with four concrete options — not A/B/C
    letters. Default = "Start /cc on the top recommendation".
 
@@ -78,10 +99,14 @@ Validate envelopes with:
 
 ## Primary skill
 
-**${RUNTIME_ROOT}/skills/${IDEATE_SKILL_FOLDER}/SKILL.md**
+   **${RUNTIME_ROOT}/skills/${IDEATE_SKILL_FOLDER}/SKILL.md**
 `;
 }
-export function ideateCommandSkillMarkdown() {
+export function ideateCommandSkillMarkdown(options = {}) {
+    const frames = resolveIdeateFrames(options.frameIds);
+    const frameBullets = renderFrameBullets(options.frameIds);
+    const minimumDistinctFrames = Math.min(4, frames.length);
+    const frameNames = renderFrameNames(options.frameIds);
     return `---
 name: ${IDEATE_SKILL_NAME}
 description: "Repository ideate mode: detect and rank high-leverage improvements, persist a backlog artifact, and hand off to /cc or save/discard."
@@ -150,14 +175,9 @@ Record each finding with exact evidence (path, command, or doc source).
 
 Generate candidate ideas by frame, in parallel when possible:
 
-- pain/friction
-- inversion
-- assumption-break
-- leverage
-- cross-domain analogy
-- constraint-flip
+${frameBullets}
 
-Require at least 4 distinct frames in every run. Avoid frame-collapse
+Require at least ${minimumDistinctFrames} distinct frames in every run. Avoid frame-collapse
 (same idea rewritten 6 times). Keep raw outputs for auditability.
 
 ### Phase 3 — Critique all, keep survivors
@@ -182,7 +202,8 @@ Only survivors advance to ranking.
    - **Evidence** — path(s) or command output, inline if short
    - **Counter-argument** — strongest concern that survived
    - **Proposed handoff** — exact \`/cc <phrase>\`
-3. Sort by impact/effort ratio; break ties with confidence.
+3. Sort by score \`(impact points / effort cost) * confidence multiplier\`
+   and break ties with rationale strength.
 4. Compute the artifact filename:
    - \`slug\` = first 3–5 words of the top recommendation, lowercase,
      non-alphanumeric collapsed to \`-\`, trimmed. When ideate mode is
@@ -231,7 +252,11 @@ Only survivors advance to ranking.
    ### I-2 — …
    \`\`\`
 
-6. Confirm in chat: "Wrote <path>."
+6. Optional: for promising non-selected ideas, write
+   \`${RUNTIME_ROOT}/seeds/SEED-<YYYY-MM-DD>-<slug>.md\` entries with:
+   \`title\`, \`trigger_when\`, \`hypothesis\`, \`action\`, and
+   \`source_artifact\` = ideate artifact path.
+7. Confirm in chat: "Wrote <path>."
 
 ### Phase 5 — Handoff prompt
 
@@ -270,5 +295,7 @@ lettered list with the same four labels. Do not invent extra options.
 - Do not mutate \`.cclaw/state/flow-state.json\` at any phase.
 - Do not end the turn with an ungrounded "pick one" question — every
   option in the handoff prompt must reference a concrete command.
+- Do not collapse all ideas into one frame; distribute across:
+  ${frameNames}.
 `;
 }