cclaw-cli 0.46.14 → 0.47.0

package/README.md

@@ -154,10 +154,11 @@ If cclaw detects a Node / Python / Go project at init time, a sixth
 default surface — a new user sees nothing they need to understand yet.
 
 Advanced knobs (`promptGuardMode` / `tddEnforcement` per-axis overrides,
-`tddTestGlobs`, `defaultTrack`, `trackHeuristics`, `sliceReview`) are
-**opt-in**: add them by hand when you need them. `cclaw upgrade`
-preserves exactly what you wrote — it never silently reintroduces
-defaults you removed.
+`tdd.testPathPatterns` / `tdd.productionPathPatterns`,
+`compound.recurrenceThreshold`, `defaultTrack`, `trackHeuristics`,
+`sliceReview`) are **opt-in**: add them by hand when you need them.
+`cclaw upgrade` preserves exactly what you wrote — it never silently
+reintroduces defaults you removed.
 
 Full key-by-key reference: [`docs/config.md`](./docs/config.md).
 
@@ -240,7 +241,7 @@ the flow matches the task.
 |---|---|---|
 | **quick** | `spec → tdd → review → ship` | `bug`, `hotfix`, `typo`, `rename`, `bump`, `docs only`, one-liners |
 | **medium** | `brainstorm → spec → plan → tdd → review → ship` | `add endpoint`, `add field`, `extend existing`, `wire integration` |
-| **standard** _(default)_ | all 8 stages | `new feature`, `refactor`, `migration`, `platform`, `schema`, `architecture` |
+| **standard** _(default)_ | all 8 stages (+ mandatory design-time parallel research fleet) | `new feature`, `refactor`, `migration`, `platform`, `schema`, `architecture` |
 
 **Every track ends with the same auto-closeout chain.** Once ship
 completes, `/cc-next` automatically drives
@@ -250,10 +251,11 @@ without re-drafting retros or re-asking structured questions. See
 [Ship and closeout](#ship-and-closeout--automatic-resumable).
 
 Each critical-path stage produces a dated artifact under
-`.cclaw/artifacts/`: `00-idea.md` (seed), `01-brainstorm.md` through
+`.cclaw/artifacts/`: `00-idea.md` (seed), `01-brainstorm.md`, `02-scope.md`,
+`02a-research.md` (design research fleet synthesis), `03-design.md` through
 `08-ship.md`. Closeout adds `09-retro.md`; archive then rolls the whole
-bundle into `.cclaw/runs/<YYYY-MM-DD-slug>/` and resets the active flow
-for the next feature.
+bundle into `.cclaw/runs/<YYYY-MM-DD-slug>/` and resets the active flow for
+the next feature.
 
 ### Track heuristics are configurable (advisory)
 
@@ -312,9 +314,12 @@ it into ceremony:
   protocol emits typed entries (`rule` / `pattern` / `lesson`) to
   `.cclaw/knowledge.jsonl` as the flow progresses — not only at retro.
   Retro itself adds a `compound` entry, and the automatic compound pass
-  after ship promotes recurring entries (≥ 3) into first-class
-  rules/protocols/skills so the **next** run is easier. Strict JSONL
-  schema keeps the whole thing machine-queryable.
+  after ship promotes recurring entries into first-class
+  rules/protocols/skills (base threshold from
+  `compound.recurrenceThreshold`, temporarily lowered to 2 for repositories
+  with <5 archived runs, plus a critical-severity single-hit override) so
+  the **next** run is easier. Strict JSONL schema keeps the whole thing
+  machine-queryable.
 - **Automatic integrity checks.** Runtime health is verified on every
   stage transition — no command you need to remember to run.
 

package/dist/artifact-linter.d.ts

@@ -15,6 +15,7 @@ export interface LintResult {
 export declare function extractMarkdownSectionBody(markdown: string, section: string): string | null;
 export type LearningEntryType = "rule" | "pattern" | "lesson" | "compound";
 export type LearningConfidence = "high" | "medium" | "low";
+export type LearningSeverity = "critical" | "important" | "suggestion";
 export type LearningUniversality = "project" | "personal" | "universal";
 export type LearningMaturity = "raw" | "lifted-to-rule" | "lifted-to-enforcement";
 export type LearningSource = "stage" | "retro" | "compound" | "ideate" | "manual";
@@ -23,6 +24,7 @@ export interface LearningSeedEntry {
     trigger: string;
     action: string;
     confidence: LearningConfidence;
+    severity?: LearningSeverity;
     domain?: string | null;
     stage?: FlowStage | null;
     origin_stage?: FlowStage | null;

package/dist/artifact-linter.js

@@ -12,25 +12,52 @@ async function resolveArtifactPath(projectRoot, fileName) {
 function normalizeHeadingTitle(title) {
     return title.trim().replace(/\s+/g, " ");
 }
-/** Collect H2 sections and body content (`## Section Name`). */
+/**
+ * Collect H2 sections and body content (`## Section Name`).
+ *
+ * - Ignores lines that live inside fenced code blocks (``` / ~~~) so a
+ *   commented `## Approaches` inside an example doesn't open a phantom
+ *   section and swallow real content.
+ * - When the same heading appears more than once at the top level we
+ *   concatenate the bodies rather than silently overwriting the earlier
+ *   occurrence. This keeps lint rules honest when authors split a section
+ *   into multiple passes.
+ */
 function extractH2Sections(markdown) {
     const sections = new Map();
     const lines = markdown.split(/\r?\n/);
     let currentHeading = null;
     let buffer = [];
+    let fenced = null;
     const flush = () => {
         if (currentHeading === null)
             return;
-        sections.set(currentHeading, buffer.join("\n"));
+        const existing = sections.get(currentHeading);
+        const body = buffer.join("\n");
+        sections.set(currentHeading, existing === undefined ? body : `${existing}\n${body}`);
     };
     for (const line of lines) {
-        const match = /^##\s+(.+)$/u.exec(line);
-        if (match) {
-            flush();
-            currentHeading = normalizeHeadingTitle(match[1] ?? "");
-            buffer = [];
+        const fenceMatch = /^(```|~~~)/u.exec(line);
+        if (fenceMatch) {
+            if (fenced === null) {
+                fenced = fenceMatch[1] ?? null;
+            }
+            else if (line.startsWith(fenced)) {
+                fenced = null;
+            }
+            if (currentHeading !== null)
+                buffer.push(line);
             continue;
         }
+        if (fenced === null) {
+            const match = /^##\s+(.+)$/u.exec(line);
+            if (match) {
+                flush();
+                currentHeading = normalizeHeadingTitle(match[1] ?? "");
+                buffer = [];
+                continue;
+            }
+        }
         if (currentHeading !== null) {
             buffer.push(line);
         }
@@ -299,6 +326,7 @@ function validateVerificationLadder(sectionBody) {
 }
 const LEARNING_TYPE_SET = new Set(["rule", "pattern", "lesson", "compound"]);
 const LEARNING_CONFIDENCE_SET = new Set(["high", "medium", "low"]);
+const LEARNING_SEVERITY_SET = new Set(["critical", "important", "suggestion"]);
 const LEARNING_UNIVERSALITY_SET = new Set(["project", "personal", "universal"]);
 const LEARNING_MATURITY_SET = new Set(["raw", "lifted-to-rule", "lifted-to-enforcement"]);
 const LEARNING_SOURCE_SET = new Set([
@@ -314,6 +342,7 @@ const LEARNING_ALLOWED_KEYS = new Set([
     "trigger",
     "action",
     "confidence",
+    "severity",
     "domain",
     "stage",
     "origin_stage",
@@ -377,6 +406,13 @@ function parseLearningSeedEntry(raw, index) {
             error: `Learnings bullet #${index} must set confidence to high|medium|low.`
         };
     }
+    const severity = typeof obj.severity === "string" ? obj.severity.toLowerCase() : undefined;
+    if (severity !== undefined && !LEARNING_SEVERITY_SET.has(severity)) {
+        return {
+            ok: false,
+            error: `Learnings bullet #${index} field "severity" must be critical|important|suggestion.`
+        };
+    }
     if (obj.domain !== undefined && !isNullableString(obj.domain)) {
         return { ok: false, error: `Learnings bullet #${index} field "domain" must be string or null.` };
     }
@@ -443,7 +479,8 @@ function parseLearningSeedEntry(raw, index) {
             type: type,
             trigger,
             action,
-            confidence: confidence
+            confidence: confidence,
+            ...(severity ? { severity: severity } : {})
         }
     };
 }
@@ -859,6 +896,49 @@ export async function lintArtifact(projectRoot, stage) {
             details: learnings.details
         });
     }
+    if (stage === "brainstorm") {
+        // Brainstorm Iron Law: "NO ARTIFACT IS COMPLETE WITHOUT AN EXPLICITLY
+        // APPROVED DIRECTION — SILENCE IS NOT APPROVAL." Previously this was
+        // prose-only — nothing failed when the Selected Direction section
+        // omitted an approval marker, or when the Approaches table collapsed
+        // to a single row (defeating the "2-3 distinct approaches" gate).
+        const approachesBody = sectionBodyByName(sections, "Approaches");
+        if (approachesBody !== null) {
+            const tableRows = approachesBody
+                .split(/\r?\n/u)
+                .map((line) => line.trim())
+                .filter((line) => line.startsWith("|"))
+                .filter((line) => !/^\|\s*[-: |]+\|\s*$/u.test(line))
+                .filter((line) => !/^\|\s*approach\b/iu.test(line));
+            const bulletRows = approachesBody
+                .split(/\r?\n/u)
+                .map((line) => line.trim())
+                .filter((line) => /^(?:[-*]|\d+\.)\s+\S/u.test(line));
+            const rowCount = Math.max(tableRows.length, bulletRows.length);
+            findings.push({
+                section: "Distinct Approaches Enforcement",
+                required: true,
+                rule: "Approaches section must document at least 2 distinct approaches so the Iron Law comparison is meaningful.",
+                found: rowCount >= 2,
+                details: rowCount >= 2
+                    ? `Detected ${rowCount} approach row(s).`
+                    : `Detected ${rowCount} approach row(s); at least 2 required.`
+            });
+        }
+        const directionBody = sectionBodyByName(sections, "Selected Direction");
+        if (directionBody !== null) {
+            const approvalMarker = /\bapprov(?:ed|al)\b/iu.test(directionBody);
+            findings.push({
+                section: "Direction Approval Marker",
+                required: true,
+                rule: "Selected Direction section must state an explicit approval marker (for example `Approval: approved` or `Approved by: user`).",
+                found: approvalMarker,
+                details: approvalMarker
+                    ? "Approval marker present in Selected Direction."
+                    : "No explicit `approved`/`approval` marker found in Selected Direction."
+            });
+        }
+    }
     if (stage === "plan") {
         const strictPlanGuards = parsedFrontmatter.hasFrontmatter ||
             headingPresent(sections, "No-Placeholder Scan") ||
@@ -904,12 +984,13 @@ export async function lintArtifact(projectRoot, stage) {
         });
     }
     if (stage === "scope") {
+        const lockedDecisionsBody = sectionBodyByName(sections, "Locked Decisions (D-XX)") ?? "";
         const strictScopeGuards = parsedFrontmatter.hasFrontmatter ||
             headingPresent(sections, "Locked Decisions (D-XX)");
         const scopeSections = [
             sectionBodyByName(sections, "In Scope / Out of Scope") ?? "",
             sectionBodyByName(sections, "Scope Summary") ?? "",
-            sectionBodyByName(sections, "Locked Decisions (D-XX)") ?? ""
+            lockedDecisionsBody
         ].join("\n");
         const reductionHits = collectPatternHits(scopeSections, SCOPE_REDUCTION_PATTERNS);
         findings.push({
@@ -921,6 +1002,45 @@ export async function lintArtifact(projectRoot, stage) {
                 ? "No scope-reduction phrases detected in scope boundary sections."
                 : `Detected scope-reduction phrase(s): ${reductionHits.join(", ")}.`
         });
+        // When the Locked Decisions section is present we must enforce the
+        // D-XX ID contract at runtime (previously this was prose-only in the
+        // artifactValidation rule). Empty body, missing IDs, and duplicate
+        // IDs all fail the lint; absence of the section remains advisory so
+        // scope stays optional for small/quick tracks.
+        if (headingPresent(sections, "Locked Decisions (D-XX)")) {
+            const decisionIds = extractDecisionIds(lockedDecisionsBody);
+            const bulletLines = lockedDecisionsBody
+                .split(/\r?\n/u)
+                .map((line) => line.trim())
+                .filter((line) => /^(?:[-*]|\|)\s+\S/u.test(line));
+            const orphanBullets = bulletLines.filter((line) => !/\bD-\d+\b/u.test(line));
+            const duplicateIds = (() => {
+                const all = lockedDecisionsBody.match(/\bD-\d+\b/gu) ?? [];
+                const counts = new Map();
+                for (const id of all)
+                    counts.set(id, (counts.get(id) ?? 0) + 1);
+                return [...counts.entries()].filter(([, n]) => n > 1).map(([id]) => id);
+            })();
+            const issues = [];
+            if (decisionIds.length === 0 && bulletLines.length === 0) {
+                issues.push("section is empty");
+            }
+            if (orphanBullets.length > 0) {
+                issues.push(`${orphanBullets.length} bullet(s) missing a D-XX ID`);
+            }
+            if (duplicateIds.length > 0) {
+                issues.push(`duplicate IDs: ${duplicateIds.join(", ")}`);
+            }
+            findings.push({
+                section: "Locked Decisions ID Integrity",
+                required: true,
+                rule: "Locked Decisions section must list each decision with a unique stable D-XX ID.",
+                found: issues.length === 0,
+                details: issues.length === 0
+                    ? `${decisionIds.length} decision ID(s) recorded with no duplicates.`
+                    : issues.join("; ")
+            });
+        }
     }
     const passed = findings.every((f) => !f.required || f.found);
     return { stage, file: relFile, passed, findings };
@@ -1188,6 +1308,14 @@ export async function checkReviewVerdictConsistency(projectRoot) {
     if (finalVerdict === "APPROVED" && (openCriticalCount > 0 || shipBlockerCount > 0)) {
         errors.push(`Final Verdict is APPROVED but review-army has ${openCriticalCount} open Critical finding(s) and ${shipBlockerCount} shipBlocker(s). Use BLOCKED or APPROVED_WITH_CONCERNS.`);
     }
+    // APPROVED_WITH_CONCERNS is intended for Important/Suggestion findings
+    // the author has accepted. An *open* Critical finding or an active
+    // shipBlocker must route through BLOCKED (review_verdict_blocked gate)
+    // rather than pass as a concession — previously this slipped through.
+    if (finalVerdict === "APPROVED_WITH_CONCERNS" &&
+        (openCriticalCount > 0 || shipBlockerCount > 0)) {
+        errors.push(`Final Verdict is APPROVED_WITH_CONCERNS but review-army has ${openCriticalCount} open Critical finding(s) and ${shipBlockerCount} shipBlocker(s). Resolve them or use BLOCKED.`);
+    }
     return {
         ok: errors.length === 0,
         errors,

package/dist/config.d.ts

@@ -1,14 +1,19 @@
 import type { FlowTrack, HarnessId, LanguageRulePack, VibyConfig } from "./types.js";
 export declare function configPath(projectRoot: string): string;
 /**
- * Default test-file globs used by workflow-guard.sh to detect when a write
- * targets a test file during TDD. Users rarely need to override this — the
- * defaults cover TypeScript / JavaScript / Python / Go / Rust / Java layouts.
- * Exposed so `install.ts` can reuse the same list when seeding the shell
- * guard script, even though the field is no longer written to the default
- * `config.yaml` template.
+ * Default test-path patterns used by workflow-guard.sh to classify TDD writes.
+ *
+ * Scope is intentionally narrow and language-agnostic; users can extend this
+ * list in config when their repository uses different conventions.
+ */
+export declare const DEFAULT_TDD_TEST_PATH_PATTERNS: readonly string[];
+/**
+ * Legacy alias kept for backwards compatibility with `tddTestGlobs`.
+ * Prefer `tdd.testPathPatterns` in new configurations.
  */
 export declare const DEFAULT_TDD_TEST_GLOBS: readonly string[];
+export declare const DEFAULT_TDD_PRODUCTION_PATH_PATTERNS: readonly string[];
+export declare const DEFAULT_COMPOUND_RECURRENCE_THRESHOLD = 3;
 /**
  * Populated runtime view of config values that downstream callers (install,
  * observe, doctor) consume. Always has the derived guard modes populated,
@@ -34,7 +39,7 @@ export declare function readConfig(projectRoot: string): Promise<VibyConfig>;
  * the user set them explicitly. Keeps the default template small and honest:
  * only knobs a new user would meaningfully flip show up.
  */
-type AdvancedConfigKey = "promptGuardMode" | "tddEnforcement" | "tddTestGlobs" | "defaultTrack" | "languageRulePacks" | "trackHeuristics" | "sliceReview";
+type AdvancedConfigKey = "promptGuardMode" | "tddEnforcement" | "tddTestGlobs" | "tdd" | "compound" | "defaultTrack" | "languageRulePacks" | "trackHeuristics" | "sliceReview";
 /**
  * Options controlling the serialisation shape of `config.yaml`.
  *

package/dist/config.js

@@ -19,6 +19,8 @@ const ALLOWED_CONFIG_KEYS = new Set([
     "promptGuardMode",
     "tddEnforcement",
     "tddTestGlobs",
+    "tdd",
+    "compound",
     "gitHookGuards",
     "defaultTrack",
     "languageRulePacks",
@@ -74,18 +76,23 @@ export function configPath(projectRoot) {
     return path.join(projectRoot, CONFIG_PATH);
 }
 /**
- * Default test-file globs used by workflow-guard.sh to detect when a write
- * targets a test file during TDD. Users rarely need to override this — the
- * defaults cover TypeScript / JavaScript / Python / Go / Rust / Java layouts.
- * Exposed so `install.ts` can reuse the same list when seeding the shell
- * guard script, even though the field is no longer written to the default
- * `config.yaml` template.
+ * Default test-path patterns used by workflow-guard.sh to classify TDD writes.
+ *
+ * Scope is intentionally narrow and language-agnostic; users can extend this
+ * list in config when their repository uses different conventions.
  */
-export const DEFAULT_TDD_TEST_GLOBS = [
+export const DEFAULT_TDD_TEST_PATH_PATTERNS = [
     "**/*.test.*",
-    "**/*.spec.*",
-    "**/test/**"
+    "**/tests/**",
+    "**/__tests__/**"
 ];
+/**
+ * Legacy alias kept for backwards compatibility with `tddTestGlobs`.
+ * Prefer `tdd.testPathPatterns` in new configurations.
+ */
+export const DEFAULT_TDD_TEST_GLOBS = [...DEFAULT_TDD_TEST_PATH_PATTERNS];
+export const DEFAULT_TDD_PRODUCTION_PATH_PATTERNS = [];
+export const DEFAULT_COMPOUND_RECURRENCE_THRESHOLD = 3;
 /**
  * Populated runtime view of config values that downstream callers (install,
  * observe, doctor) consume. Always has the derived guard modes populated,
@@ -93,6 +100,8 @@ export const DEFAULT_TDD_TEST_GLOBS = [
  * or neither.
  */
 export function createDefaultConfig(harnesses = DEFAULT_HARNESSES, defaultTrack = "standard") {
+    const tddTestPathPatterns = [...DEFAULT_TDD_TEST_PATH_PATTERNS];
+    const tddProductionPathPatterns = [...DEFAULT_TDD_PRODUCTION_PATH_PATTERNS];
     return {
         version: CCLAW_VERSION,
         flowVersion: FLOW_VERSION,
@@ -100,7 +109,14 @@ export function createDefaultConfig(harnesses = DEFAULT_HARNESSES, defaultTrack
         strictness: "advisory",
         promptGuardMode: "advisory",
         tddEnforcement: "advisory",
-        tddTestGlobs: [...DEFAULT_TDD_TEST_GLOBS],
+        tddTestGlobs: [...tddTestPathPatterns],
+        tdd: {
+            testPathPatterns: tddTestPathPatterns,
+            productionPathPatterns: tddProductionPathPatterns
+        },
+        compound: {
+            recurrenceThreshold: DEFAULT_COMPOUND_RECURRENCE_THRESHOLD
+        },
         gitHookGuards: false,
         defaultTrack,
         languageRulePacks: []
@@ -213,6 +229,48 @@ export async function readConfig(projectRoot) {
     const tddTestGlobsRaw = parsed.tddTestGlobs;
     const tddTestGlobs = validateStringArray(tddTestGlobsRaw, "tddTestGlobs", fullPath)
         ?? [...DEFAULT_TDD_TEST_GLOBS];
+    const hasTddField = Object.prototype.hasOwnProperty.call(parsed, "tdd");
+    const tddRaw = parsed.tdd;
+    let explicitTddTestPathPatterns;
+    let explicitTddProductionPathPatterns;
+    if (hasTddField) {
+        if (!isRecord(tddRaw)) {
+            throw configValidationError(fullPath, `"tdd" must be an object`);
+        }
+        const unknownTddKeys = Object.keys(tddRaw).filter((key) => key !== "testPathPatterns" && key !== "productionPathPatterns");
+        if (unknownTddKeys.length > 0) {
+            throw configValidationError(fullPath, `"tdd" has unknown key(s): ${unknownTddKeys.join(", ")}`);
+        }
+        explicitTddTestPathPatterns = validateStringArray(tddRaw.testPathPatterns, "tdd.testPathPatterns", fullPath);
+        explicitTddProductionPathPatterns = validateStringArray(tddRaw.productionPathPatterns, "tdd.productionPathPatterns", fullPath);
+    }
+    const resolvedTddTestPathPatterns = [
+        ...(explicitTddTestPathPatterns ?? tddTestGlobs ?? DEFAULT_TDD_TEST_PATH_PATTERNS)
+    ];
+    const resolvedTddProductionPathPatterns = [
+        ...(explicitTddProductionPathPatterns ?? DEFAULT_TDD_PRODUCTION_PATH_PATTERNS)
+    ];
+    const hasCompoundField = Object.prototype.hasOwnProperty.call(parsed, "compound");
+    const compoundRaw = parsed.compound;
+    let compoundRecurrenceThreshold = DEFAULT_COMPOUND_RECURRENCE_THRESHOLD;
+    if (hasCompoundField) {
+        if (!isRecord(compoundRaw)) {
+            throw configValidationError(fullPath, `"compound" must be an object`);
+        }
+        const unknownCompoundKeys = Object.keys(compoundRaw).filter((key) => key !== "recurrenceThreshold");
+        if (unknownCompoundKeys.length > 0) {
+            throw configValidationError(fullPath, `"compound" has unknown key(s): ${unknownCompoundKeys.join(", ")}`);
+        }
+        if (compoundRaw.recurrenceThreshold !== undefined &&
+            (typeof compoundRaw.recurrenceThreshold !== "number" ||
+                !Number.isInteger(compoundRaw.recurrenceThreshold) ||
+                compoundRaw.recurrenceThreshold < 1)) {
+            throw configValidationError(fullPath, `"compound.recurrenceThreshold" must be a positive integer`);
+        }
+        if (typeof compoundRaw.recurrenceThreshold === "number") {
+            compoundRecurrenceThreshold = compoundRaw.recurrenceThreshold;
+        }
+    }
     const gitHookGuardsRaw = parsed.gitHookGuards;
     if (Object.prototype.hasOwnProperty.call(parsed, "gitHookGuards") &&
         typeof gitHookGuardsRaw !== "boolean") {
@@ -327,6 +385,13 @@ export async function readConfig(projectRoot) {
         promptGuardMode,
         tddEnforcement,
         tddTestGlobs,
+        tdd: {
+            testPathPatterns: resolvedTddTestPathPatterns,
+            productionPathPatterns: resolvedTddProductionPathPatterns
+        },
+        compound: {
+            recurrenceThreshold: compoundRecurrenceThreshold
+        },
         gitHookGuards,
         defaultTrack,
         languageRulePacks,
@@ -349,6 +414,8 @@ function buildSerializableConfig(config, options = {}) {
         "promptGuardMode",
         "tddEnforcement",
         "tddTestGlobs",
+        "tdd",
+        "compound",
         "gitHookGuards",
         "defaultTrack",
         "languageRulePacks",
@@ -402,6 +469,8 @@ export async function detectAdvancedKeys(projectRoot) {
             "promptGuardMode",
             "tddEnforcement",
             "tddTestGlobs",
+            "tdd",
+            "compound",
             "defaultTrack",
             "languageRulePacks",
             "trackHeuristics",

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

@@ -1,2 +1,5 @@
-export declare function compoundCommandContract(): string;
-export declare function compoundCommandSkillMarkdown(): string;
+export interface CompoundCommandOptions {
+    recurrenceThreshold?: number;
+}
+export declare function compoundCommandContract(options?: CompoundCommandOptions): string;
+export declare function compoundCommandSkillMarkdown(options?: CompoundCommandOptions): string;

package/dist/content/compound-command.js

@@ -1,7 +1,18 @@
 import { RUNTIME_ROOT } from "../constants.js";
 const COMPOUND_SKILL_FOLDER = "flow-compound";
 const COMPOUND_SKILL_NAME = "flow-compound";
-export function compoundCommandContract() {
+const DEFAULT_RECURRENCE_THRESHOLD = 3;
+const SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD = 5;
+const SMALL_PROJECT_RECURRENCE_THRESHOLD = 2;
+function resolveRecurrenceThreshold(options) {
+    const threshold = options.recurrenceThreshold;
+    if (typeof threshold === "number" && Number.isInteger(threshold) && threshold >= 1) {
+        return threshold;
+    }
+    return DEFAULT_RECURRENCE_THRESHOLD;
+}
+export function compoundCommandContract(options = {}) {
+    const recurrenceThreshold = resolveRecurrenceThreshold(options);
     return `# /cc-ops compound
 
 ## Purpose
@@ -29,39 +40,48 @@ the user can approve individual lifts, accept-all, or skip.
 
 1. Read \`${RUNTIME_ROOT}/knowledge.jsonl\` (strict JSONL, one entry per line).
 2. Cluster entries by \`trigger\` + \`action\` similarity.
-3. Filter candidates whose recurrence count >= 3.
-4. If **no candidates** exist:
+3. Resolve recurrence policy:
+   - base threshold = \`${recurrenceThreshold}\` (from \`config.compound.recurrenceThreshold\`),
+   - count archived runs under \`${RUNTIME_ROOT}/runs/\`,
+   - if archived run count is < ${SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD}, use
+     effective threshold = \`min(base threshold, ${SMALL_PROJECT_RECURRENCE_THRESHOLD})\` for this pass.
+4. Filter candidates that satisfy at least one trigger:
+   - recurrence count >= effective threshold, or
+   - any knowledge entry in the cluster has \`severity: "critical"\`
+     (critical override, recurrence can be 1).
+5. If **no candidates** exist:
    - set \`closeout.compoundCompletedAt = <ISO>\`,
    - set \`closeout.compoundPromoted = 0\`,
    - set \`closeout.shipSubstate = "ready_to_archive"\`,
    - emit \`compound: no candidates | next: /cc-next\` and stop.
-5. **Drift check** each surviving candidate before presenting it (see
+6. **Drift check** each surviving candidate before presenting it (see
    "Drift check" section in the skill): confirm the lift target file is
    current, spot-check the repo for contradictions, demote stale clusters
    into a new superseding entry instead of a lift.
-6. Otherwise, present **one** structured ask via the harness's native ask
+7. Otherwise, present **one** structured ask via the harness's native ask
    tool (\`AskUserQuestion\` / \`AskQuestion\` / \`question\` /
    \`request_user_input\`; plain-text lettered list as fallback) summarising
    all candidates at once:
    - \`apply-all\` (default) — apply every listed lift,
    - \`apply-selected\` — prompt per-candidate,
    - \`skip\` — record a skip reason and advance without changes.
-7. Apply approved lifts to the target file(s). Each lift also appends a
+8. Apply approved lifts to the target file(s). Each lift also appends a
    \`type: "compound"\` entry back to \`${RUNTIME_ROOT}/knowledge.jsonl\`
    summarising what was lifted.
-8. Update flow-state:
+9. Update flow-state:
    - \`closeout.compoundCompletedAt = <ISO>\`,
    - \`closeout.compoundPromoted = <count>\`,
    - \`closeout.compoundSkipped = true\` if user picked skip,
    - \`closeout.shipSubstate = "ready_to_archive"\`.
-9. Emit one-line summary: \`compound: promoted=<N> skipped=<bool> | next: /cc-next\`.
+10. Emit one-line summary: \`compound: promoted=<N> skipped=<bool> | next: /cc-next\`.
 
 ## Primary skill
 
 **${RUNTIME_ROOT}/skills/${COMPOUND_SKILL_FOLDER}/SKILL.md**
 `;
 }
-export function compoundCommandSkillMarkdown() {
+export function compoundCommandSkillMarkdown(options = {}) {
+    const recurrenceThreshold = resolveRecurrenceThreshold(options);
     return `---
 name: ${COMPOUND_SKILL_NAME}
 description: "Lift repeated learnings into durable rules/protocols/skills. Auto-triggered after retro accept."
@@ -83,13 +103,20 @@ empty pass is allowed and must advance \`closeout.shipSubstate\` to
 
 1. Parse \`.cclaw/knowledge.jsonl\` and group repeated lessons by
    trigger+action similarity.
-2. Keep only candidates with recurrence >= 3 and an actionable lift path.
-3. If none qualify, record an empty pass:
+2. Resolve recurrence policy:
+   - base threshold = \`${recurrenceThreshold}\` from \`config.compound.recurrenceThreshold\`,
+   - count archived runs under \`.cclaw/runs/\`,
+   - if archived run count is < ${SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD}, use
+     effective threshold = \`min(base threshold, ${SMALL_PROJECT_RECURRENCE_THRESHOLD})\` for this pass.
+3. Keep only candidates that meet at least one trigger:
+   - recurrence >= effective threshold and actionable lift path, or
+   - a cluster entry with \`severity: critical\` (critical override, recurrence can be 1).
+4. If none qualify, record an empty pass:
    - \`closeout.compoundCompletedAt = <ISO>\`,
    - \`closeout.compoundPromoted = 0\`,
    - \`closeout.shipSubstate = "ready_to_archive"\`,
    - announce \`compound: no candidates\` and stop.
-4. **Drift check — run before presenting any candidate.** Knowledge lines
+5. **Drift check — run before presenting any candidate.** Knowledge lines
    are append-only, so textual repetition alone does not prove the rule is
    still true. For every cluster that survives the recurrence filter:
 
@@ -111,13 +138,17 @@ empty pass is allowed and must advance \`closeout.shipSubstate\` to
    - **Cite line IDs.** Every surviving candidate must list the concrete
      knowledge line indices (1-based) that back it, not just a
      summary string. This is what makes the lift auditable.
+   - **Include qualification reason.** Mark each candidate as
+     \`recurrence\` or \`critical_override\` so reviewers can see why it passed
+     the filter.
    - Optionally invoke the \`knowledge-curation\` utility skill's
      stale/duplicate/supersede heuristics if you want a second pass.
 
-5. Otherwise, render each candidate as:
+6. Otherwise, render each candidate as:
 
 \`\`\`
 Candidate: <short title>
+Qualification: <recurrence|critical_override>
 Evidence: <knowledge line-ids>
 Freshness: <newest last_seen_ts among evidence lines>
 Lift target: <rule/protocol/skill file>
@@ -125,17 +156,17 @@ Change type: <add/update/remove>
 Expected benefit: <what regressions this prevents>
 \`\`\`
 
-6. Present **one** structured question with three options:
+7. Present **one** structured question with three options:
    - \`apply-all\` (default) — apply every candidate,
    - \`apply-selected\` — prompt per-candidate approval next,
    - \`skip\` — record a skip reason and advance.
 
-7. For approved candidates:
+8. For approved candidates:
    - edit the target file(s) with the lift,
    - append a \`type: "compound"\` entry to \`.cclaw/knowledge.jsonl\`
      describing what was promoted, including the source line IDs.
 
-8. Update flow-state \`closeout\`:
+9. Update flow-state \`closeout\`:
    - \`compoundCompletedAt\`,
    - \`compoundPromoted\` (count),
    - \`compoundSkipped\` (boolean) + \`compoundSkipReason\` when applicable,

package/dist/content/contracts.js

@@ -34,7 +34,7 @@ ${schema.hardGate}
 2. Resolve active artifact root: \`.cclaw/artifacts/\`.
 3. Load required upstream artifacts for this stage:
 ${hydrationLines}
-4. Stream \`.cclaw/knowledge.jsonl\` and apply relevant JSON-line entries (strict schema: type, trigger, action, confidence, domain, stage, origin_stage, origin_feature, frequency, universality, maturity, created, first_seen_ts, last_seen_ts, project).
+4. Stream \`.cclaw/knowledge.jsonl\` and apply relevant JSON-line entries (strict schema: type, trigger, action, confidence, domain, stage, origin_stage, origin_feature, frequency, universality, maturity, created, first_seen_ts, last_seen_ts, project; optional: source, severity).
 5. Write stage output to ${writeStepPaths}.
 6. Do NOT copy artifacts into \`.cclaw/runs/\`; archival is handled by \`/cc-ops archive\` (agent-facing wrapper over archive runtime).
 

package/dist/content/examples.d.ts

@@ -16,4 +16,5 @@ export declare function stageExamplesReferenceMarkdown(stage: FlowStage): string
  */
 export declare function stageExamples(stage: FlowStage): string;
 export type ExampleDomain = "web" | "cli" | "library" | "data-pipeline";
+export declare const RESEARCH_FLEET_USAGE_EXAMPLE: string;
 export declare function stageDomainExamples(stage: FlowStage): string;