cclaw-cli 0.46.14 → 0.46.15

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

@@ -299,6 +299,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 +315,7 @@ const LEARNING_ALLOWED_KEYS = new Set([
     "trigger",
     "action",
     "confidence",
+    "severity",
     "domain",
     "stage",
     "origin_stage",
@@ -377,6 +379,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 +452,8 @@ function parseLearningSeedEntry(raw, index) {
             type: type,
             trigger,
             action,
-            confidence: confidence
+            confidence: confidence,
+            ...(severity ? { severity: severity } : {})
         }
     };
 }

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;

package/dist/content/examples.js

@@ -713,6 +713,14 @@ const DOMAIN_LABELS = {
     library: "Library / SDK",
     "data-pipeline": "Data pipeline / ETL"
 };
+export const RESEARCH_FLEET_USAGE_EXAMPLE = [
+    "Before drafting `03-design.md`, run `research/research-fleet.md` once and",
+    "capture all four lenses in `.cclaw/artifacts/02a-research.md`.",
+    "Dispatch semantics by harness: Claude/Cursor = parallel subagents in one turn;",
+    "OpenCode/Codex = sequential role-switch with explicit announcements.",
+    "Design must include a `Research Fleet Synthesis` section that maps each",
+    "lens to concrete architecture decisions and risks."
+].join(" ");
 const STAGE_DOMAIN_SAMPLES = {
     brainstorm: [
         {
@@ -759,6 +767,11 @@ const STAGE_DOMAIN_SAMPLES = {
         }
     ],
     design: [
+        {
+            domain: "web",
+            label: "Parallel research fleet handoff",
+            body: RESEARCH_FLEET_USAGE_EXAMPLE
+        },
         {
             domain: "web",
             label: "Architecture note",

package/dist/content/harnesses-doc.js

@@ -58,6 +58,17 @@ Fallback legend:
 - \`role-switch\` — in-session role announce + delegation-log entry with evidenceRefs (OpenCode, Codex).
 - \`waiver\` — no parity path; reserved for harnesses that cannot role-switch (none shipped).
 
+## Parallel research dispatch semantics
+
+Design-stage research fleet uses the same parity model:
+
+- **Claude / Cursor**: dispatch all four research lenses in one turn
+  (stack, features, architecture, pitfalls) and synthesize into
+  \`.cclaw/artifacts/02a-research.md\`.
+- **OpenCode / Codex**: execute the same four lenses via sequential
+  role-switch, each with explicit announce -> execute -> evidence trail.
+  This preserves auditability when native parallel dispatch is unavailable.
+
 ## Semantic hook event coverage
 
 | Event | Claude | Cursor | OpenCode | Codex |

package/dist/content/learnings.d.ts

@@ -1,6 +1,7 @@
 /**
  * Canonical required JSONL field order (matches strict validator keys).
- * Optional keys (for now: `source`) may be appended after these required fields.
+ * Optional keys (for now: `source`, `severity`) may be appended after these
+ * required fields.
  * Exported for tests and any programmatic writer that wants a stable base shape.
  */
 export declare const KNOWLEDGE_JSONL_FIELDS: readonly ["type", "trigger", "action", "confidence", "domain", "stage", "origin_stage", "origin_feature", "frequency", "universality", "maturity", "created", "first_seen_ts", "last_seen_ts", "project"];

package/dist/content/learnings.js

@@ -11,7 +11,8 @@ const LEARN_SKILL_NAME = "learnings";
 const LEARN_SKILL_DESCRIPTION = "Project-scoped knowledge store: append and query rule/pattern/lesson/compound entries in the canonical JSONL file at .cclaw/knowledge.jsonl. Strict schema, append-only, machine-queryable.";
 /**
  * Canonical required JSONL field order (matches strict validator keys).
- * Optional keys (for now: `source`) may be appended after these required fields.
+ * Optional keys (for now: `source`, `severity`) may be appended after these
+ * required fields.
  * Exported for tests and any programmatic writer that wants a stable base shape.
  */
 export const KNOWLEDGE_JSONL_FIELDS = [
@@ -74,7 +75,7 @@ Do not invent alternate stores (no markdown mirror, no SQLite, no per-stage file
 
 Exactly one JSON object per line. Required fields must appear in the order:
 \`type, trigger, action, confidence, domain, stage, origin_stage, origin_feature, frequency, universality, maturity, created, first_seen_ts, last_seen_ts, project\`.
-Optional field \`source\` may be appended after \`project\`.
+Optional fields \`source\` and \`severity\` may be appended after \`project\`.
 
 \`\`\`json
 {"type":"pattern","trigger":"when reviewing external payloads","action":"parse through zod before touching service layer","confidence":"high","domain":"api","stage":"review","origin_stage":"review","origin_feature":"payload-hardening","frequency":1,"universality":"project","maturity":"raw","created":"2026-04-14T12:00:00Z","first_seen_ts":"2026-04-14T12:00:00Z","last_seen_ts":"2026-04-14T12:00:00Z","project":"cclaw"}
@@ -98,6 +99,7 @@ Optional field \`source\` may be appended after \`project\`.
 | \`last_seen_ts\` | ISO 8601 UTC string | yes | Last re-confirmed timestamp. |
 | \`project\` | string \\| null | yes | Repo or scope name. Use \`null\` when the entry crosses projects. |
 | \`source\` | \`"stage" \\| "retro" \\| "compound" \\| "ideate" \\| "manual" \\| null\` | no | Origin channel for the entry when known. |
+| \`severity\` | \`"critical" \\| "important" \\| "suggestion"\` | no | Priority signal for compound lifts; \`critical\` enables single-hit override in \`/cc-ops compound\`. |
 
 Rules:
 - No other fields beyond the table above. Extra keys are forbidden and MUST be rejected by any writer.
@@ -170,7 +172,7 @@ Do not edit source code from this command. Only operate on \`${KNOWLEDGE_PATH}\`
 |---|---|---|
 | (default) | — | Show recent knowledge entries (tail of JSONL, pretty-printed). |
 | \`search\` | \`<query>\` | Stream-filter the JSONL for matching \`trigger\`, \`action\`, \`domain\`, \`project\`. |
-| \`add\` | — | Append one JSON line (\`rule\` / \`pattern\` / \`lesson\` / \`compound\`) with the strict JSONL schema (15 required fields + optional \`source\`). |
+| \`add\` | — | Append one JSON line (\`rule\` / \`pattern\` / \`lesson\` / \`compound\`) with the strict JSONL schema (15 required fields + optional \`source\` / \`severity\`). |
 | \`curate\` | — | Hand off to the **knowledge-curation** skill: read-only audit + soft-archive plan when the file exceeds the curation threshold. |
 `;
 }

package/dist/content/observe.d.ts

@@ -12,7 +12,8 @@ export declare function promptGuardScript(options?: PromptGuardOptions): string;
 export interface WorkflowGuardOptions {
     workflowGuardMode?: "advisory" | "strict";
     tddEnforcementMode?: "advisory" | "strict";
-    tddTestGlobs?: string[];
+    tddTestPathPatterns?: string[];
+    tddProductionPathPatterns?: string[];
 }
 export declare function workflowGuardScript(options?: WorkflowGuardOptions): string;
 export declare function contextMonitorScript(): string;

package/dist/content/observe.js

@@ -156,9 +156,12 @@ exit 0
 export function workflowGuardScript(options = {}) {
     const workflowGuardMode = options.workflowGuardMode === "strict" ? "strict" : "advisory";
     const tddEnforcementMode = options.tddEnforcementMode === "strict" ? "strict" : "advisory";
-    const tddTestGlobs = options.tddTestGlobs && options.tddTestGlobs.length > 0
-        ? options.tddTestGlobs.join(",")
-        : "**/*.test.*,**/*.spec.*,**/test/**";
+    const tddTestPathPatterns = options.tddTestPathPatterns && options.tddTestPathPatterns.length > 0
+        ? options.tddTestPathPatterns.join(",")
+        : "**/*.test.*,**/tests/**,**/__tests__/**";
+    const tddProductionPathPatterns = options.tddProductionPathPatterns && options.tddProductionPathPatterns.length > 0
+        ? options.tddProductionPathPatterns.join(",")
+        : "";
     return `#!/usr/bin/env bash
 # cclaw workflow guard hook — generated by cclaw sync
 # Enforces stage-aware command discipline and recent flow-state read hygiene.
@@ -166,7 +169,8 @@ set -uo pipefail
 WORKFLOW_GUARD_MODE="\${CCLAW_WORKFLOW_GUARD_MODE:-${workflowGuardMode}}"
 MAX_FLOW_READ_AGE_SEC="\${CCLAW_WORKFLOW_GUARD_MAX_AGE_SEC:-1800}"
 TDD_ENFORCEMENT_MODE="${tddEnforcementMode}"
-TDD_TEST_GLOBS="${tddTestGlobs}"
+TDD_TEST_PATH_PATTERNS="${tddTestPathPatterns}"
+TDD_PRODUCTION_PATH_PATTERNS="${tddProductionPathPatterns}"
 
 ${RUNTIME_SHELL_DETECT_ROOT}
 
@@ -425,34 +429,153 @@ is_preimplementation_stage() {
   esac
 }
 
+normalize_payload_path() {
+  local raw="$1"
+  local normalized="$raw"
+  normalized=$(printf '%s' "$normalized" | tr '\\\\' '/')
+  normalized=$(printf '%s' "$normalized" | tr '[:upper:]' '[:lower:]')
+  normalized="\${normalized#./}"
+  printf '%s' "$normalized"
+}
+
+extract_payload_paths() {
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$INPUT" | jq -r '
+      [.. | objects | (.path?, .file_path?, .filepath?) | select(type == "string" and length > 0)]
+      | unique
+      | .[]
+    ' 2>/dev/null || printf ''
+    return 0
+  fi
+  if command -v python3 >/dev/null 2>&1; then
+    INPUT_JSON="$INPUT" python3 - <<'PY'
+import json
+import os
+
+def visit(node, acc):
+    if isinstance(node, dict):
+        for key in ("path", "file_path", "filepath"):
+            value = node.get(key)
+            if isinstance(value, str) and value.strip():
+                acc.add(value.strip())
+        for value in node.values():
+            visit(value, acc)
+    elif isinstance(node, list):
+        for value in node:
+            visit(value, acc)
+
+try:
+    payload = json.loads(os.environ.get("INPUT_JSON", "{}"))
+except Exception:
+    payload = {}
+
+items = set()
+visit(payload, items)
+for value in sorted(items):
+    print(value)
+PY
+    return 0
+  fi
+  printf ''
+  return 0
+}
+
+matches_path_patterns() {
+  local candidate="$1"
+  local patterns_csv="$2"
+  [ -n "$candidate" ] || return 1
+  [ -n "$patterns_csv" ] || return 1
+  local old_ifs="$IFS"
+  IFS=','
+  for pattern in $patterns_csv; do
+    local normalized_pattern
+    normalized_pattern=$(normalize_payload_path "$pattern")
+    [ -n "$normalized_pattern" ] || continue
+    case "$candidate" in
+      $normalized_pattern)
+        IFS="$old_ifs"
+        return 0
+        ;;
+    esac
+  done
+  IFS="$old_ifs"
+  return 1
+}
+
+is_code_like_path() {
+  local candidate="$1"
+  printf '%s' "$candidate" | grep -Eq '\\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift)$'
+}
+
 is_tdd_test_payload() {
   local text="$1"
-  if printf '%s' "$text" | grep -Eq '/tests?/|\\.test\\.|\\.spec\\.'; then
-    return 0
+  local payload_paths="$2"
+  if [ -n "$payload_paths" ]; then
+    while IFS= read -r raw_path; do
+      [ -n "$raw_path" ] || continue
+      local normalized
+      normalized=$(normalize_payload_path "$raw_path")
+      if matches_path_patterns "$normalized" "$TDD_TEST_PATH_PATTERNS"; then
+        return 0
+      fi
+    done <<< "$payload_paths"
   fi
-  if printf '%s' "$TDD_TEST_GLOBS" | grep -Eq '.' && printf '%s' "$text" | grep -Eq '(test|spec)'; then
+  if printf '%s' "$text" | grep -Eq '/tests?/|/__tests__/|\\.test\\.'; then
     return 0
   fi
   return 1
 }
 
-is_tdd_runtime_write_payload() {
+is_tdd_production_path() {
+  local normalized="$1"
+  [ -n "$normalized" ] || return 1
+  if printf '%s' "$normalized" | grep -Eq '(^|/)\\.cclaw/'; then
+    return 1
+  fi
+  if matches_path_patterns "$normalized" "$TDD_TEST_PATH_PATTERNS"; then
+    return 1
+  fi
+  if [ -n "$TDD_PRODUCTION_PATH_PATTERNS" ]; then
+    matches_path_patterns "$normalized" "$TDD_PRODUCTION_PATH_PATTERNS"
+    return $?
+  fi
+  is_code_like_path "$normalized"
+  return $?
+}
+
+is_tdd_production_write_payload() {
   local text="$1"
+  local payload_paths="$2"
+  if [ -n "$payload_paths" ]; then
+    while IFS= read -r raw_path; do
+      [ -n "$raw_path" ] || continue
+      local normalized
+      normalized=$(normalize_payload_path "$raw_path")
+      if is_tdd_production_path "$normalized"; then
+        return 0
+      fi
+    done <<< "$payload_paths"
+    return 1
+  fi
+  if [ -n "$TDD_PRODUCTION_PATH_PATTERNS" ]; then
+    return 1
+  fi
   if printf '%s' "$text" | grep -Eq '\\.cclaw/'; then
     return 1
   fi
   if ! printf '%s' "$text" | grep -Eq '\\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift)'; then
     return 1
   fi
-  if is_tdd_test_payload "$text"; then
+  if is_tdd_test_payload "$text" ""; then
     return 1
   fi
   return 0
 }
 
-has_open_red_cycle() {
+tdd_cycle_counts() {
   if [ ! -f "$TDD_LOG_FILE" ] || [ ! -s "$TDD_LOG_FILE" ]; then
-    return 1
+    printf '0:0'
+    return 0
   fi
   local red_count="0"
   local green_count="0"
@@ -512,12 +635,37 @@ PY
   fi
   [ -n "$red_count" ] || red_count="0"
   [ -n "$green_count" ] || green_count="0"
+  printf '%s:%s' "$red_count" "$green_count"
+}
+
+has_open_red_cycle() {
+  local counts
+  counts=$(tdd_cycle_counts)
+  local red_count="\${counts%%:*}"
+  local green_count="\${counts##*:}"
   if [ "$red_count" -gt "$green_count" ]; then
     return 0
   fi
   return 1
 }
 
+tdd_cycle_state() {
+  local counts
+  counts=$(tdd_cycle_counts)
+  local red_count="\${counts%%:*}"
+  local green_count="\${counts##*:}"
+  if [ "$red_count" -le 0 ]; then
+    printf 'need_red'
+    return 0
+  fi
+  if [ "$red_count" -gt "$green_count" ]; then
+    printf 'red_open'
+    return 0
+  fi
+  printf 'green_done'
+  return 0
+}
+
 detect_target_stage() {
   local text="$1"
   for stage in brainstorm scope design spec plan tdd review ship; do
@@ -546,6 +694,11 @@ FLOW_COMMAND_INVOKED=0
 if is_flow_progression_command "$PAYLOAD_LOWER"; then
   FLOW_COMMAND_INVOKED=1
 fi
+MUTATION_PATHS=""
+if is_mutating_tool "$TOOL_LOWER"; then
+  MUTATION_PATHS=$(extract_payload_paths)
+fi
+TDD_CYCLE_STATE="unknown"
 if [ -n "$TARGET_STAGE" ] && [ "$CURRENT_STAGE" != "none" ]; then
   CURRENT_IDX=$(stage_index "$CURRENT_STAGE")
   TARGET_IDX=$(stage_index "$TARGET_STAGE")
@@ -583,8 +736,13 @@ if is_preimplementation_stage "$CURRENT_STAGE" && is_mutating_tool "$TOOL_LOWER"
 fi
 
 if [ "$CURRENT_STAGE" = "tdd" ] && is_mutating_tool "$TOOL_LOWER"; then
-  if is_tdd_runtime_write_payload "$PAYLOAD_LOWER"; then
-    if ! has_open_red_cycle; then
+  if is_tdd_production_write_payload "$PAYLOAD_LOWER" "$MUTATION_PATHS"; then
+    if has_open_red_cycle; then
+      TDD_CYCLE_STATE="red_open"
+    else
+      TDD_CYCLE_STATE=$(tdd_cycle_state)
+    fi
+    if [ "$TDD_CYCLE_STATE" = "need_red" ]; then
       if [ -n "$REASONS" ]; then
         REASONS="$REASONS,tdd_write_without_open_red"
       else
@@ -659,7 +817,9 @@ PY
 fi
 
 if [ -n "$REASONS" ]; then
-  if printf '%s' "$REASONS" | grep -Eq 'direct_flow_state_edit'; then
+  if printf '%s' "$REASONS" | grep -Eq 'tdd_write_without_open_red'; then
+    NOTE="Cclaw workflow guard: Write a failing test first before editing production files during tdd stage (state=\${TDD_CYCLE_STATE})."
+  elif printf '%s' "$REASONS" | grep -Eq 'direct_flow_state_edit'; then
     NOTE="Cclaw workflow guard: direct flow-state edit bypasses the canonical stage-complete helper (\${REASONS}). Prefer: bash ${RUNTIME_ROOT}/hooks/stage-complete.sh <stage>. In strict mode this is blocked."
   else
     NOTE="Cclaw workflow guard: detected potential flow violation (\${REASONS}). Re-read ${RUNTIME_ROOT}/state/flow-state.json, avoid source edits before tdd stage, and enforce RED -> GREEN -> REFACTOR discipline inside tdd."

package/dist/content/stages/design.js

@@ -118,9 +118,7 @@ export const DESIGN = {
         "No performance budget for critical path",
         "Batching multiple design issues into one question",
         "Agreeing with user's architecture choice without evaluating alternatives",
-        "Hedging every recommendation with 'it depends' instead of taking a position",
         "No NOT-in-scope output section",
-        "No What-already-exists output section",
         "Design decisions made without reading the actual code first"
     ],
     policyNeedles: [

package/dist/content/utility-skills.js

@@ -1469,7 +1469,7 @@ For each lens, write either a knowledge entry **or** the explicit string
 ## Output protocol
 
 For every harvested insight, append one strict-schema JSON line to
-\`.cclaw/knowledge.jsonl\` (fields: \`type, trigger, action, confidence, domain, stage, origin_stage, origin_feature, frequency, universality, maturity, created, first_seen_ts, last_seen_ts, project\`).
+\`.cclaw/knowledge.jsonl\` (fields: \`type, trigger, action, confidence, domain, stage, origin_stage, origin_feature, frequency, universality, maturity, created, first_seen_ts, last_seen_ts, project\`; optional: \`source\`, \`severity\`).
 See the \`learnings\` skill for the canonical shape. Choose \`type\`:
 
 - \`compound\` for process/speed accelerators.

package/dist/install.d.ts

@@ -12,9 +12,9 @@ export declare function syncCclaw(projectRoot: string): Promise<void>;
  * stamps are rewritten so the on-disk config reflects the installed CLI.
  *
  * Shape preservation: if the user previously hand-authored advanced keys
- * (e.g. `tddTestGlobs`, `trackHeuristics`, `sliceReview`), those stay in the
- * yaml. If their existing config is minimal, the upgrade keeps it minimal —
- * advanced knobs are never silently added.
+ * (e.g. `tdd`, `compound`, `trackHeuristics`, `sliceReview`), those stay in
+ * the yaml. If their existing config is minimal, the upgrade keeps it
+ * minimal — advanced knobs are never silently added.
  */
 export declare function upgradeCclaw(projectRoot: string): Promise<void>;
 export declare function uninstallCclaw(projectRoot: string): Promise<void>;

package/dist/install.js

@@ -245,7 +245,9 @@ async function writeSkills(projectRoot, config) {
     await writeFileSafe(runtimePath(projectRoot, "skills", "using-git-worktrees", "SKILL.md"), featureCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "tdd-cycle-log", "SKILL.md"), tddLogCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-retro", "SKILL.md"), retroCommandSkillMarkdown());
-    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-compound", "SKILL.md"), compoundCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-compound", "SKILL.md"), compoundCommandSkillMarkdown({
+        recurrenceThreshold: config?.compound?.recurrenceThreshold
+    }));
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-rewind", "SKILL.md"), rewindCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-archive", "SKILL.md"), archiveCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "subagent-dev", "SKILL.md"), subagentDrivenDevSkill());
@@ -306,7 +308,7 @@ async function writeSkills(projectRoot, config) {
         await writeFileSafe(runtimePath(projectRoot, ...playbookDirSegments, harnessPlaybookFileName(harness)), harnessPlaybookMarkdown(harness));
     }
 }
-async function writeUtilityCommands(projectRoot) {
+async function writeUtilityCommands(projectRoot, config) {
     await writeFileSafe(runtimePath(projectRoot, "commands", "learn.md"), learnCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "next.md"), nextCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "ideate.md"), ideateCommandContract());
@@ -319,7 +321,9 @@ async function writeUtilityCommands(projectRoot) {
     await writeFileSafe(runtimePath(projectRoot, "commands", "feature.md"), featureCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "tdd-log.md"), tddLogCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "retro.md"), retroCommandContract());
-    await writeFileSafe(runtimePath(projectRoot, "commands", "compound.md"), compoundCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "compound.md"), compoundCommandContract({
+        recurrenceThreshold: config.compound?.recurrenceThreshold
+    }));
     await writeFileSafe(runtimePath(projectRoot, "commands", "archive.md"), archiveCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "rewind.md"), rewindCommandContract());
 }
@@ -627,7 +631,8 @@ async function writeHooks(projectRoot, config) {
     await writeFileSafe(path.join(hooksDir, "workflow-guard.sh"), workflowGuardScript({
         workflowGuardMode: config.strictness ?? "advisory",
         tddEnforcementMode: config.tddEnforcement ?? "advisory",
-        tddTestGlobs: config.tddTestGlobs
+        tddTestPathPatterns: config.tdd?.testPathPatterns ?? config.tddTestGlobs,
+        tddProductionPathPatterns: config.tdd?.productionPathPatterns
     }));
     await writeFileSafe(path.join(hooksDir, "context-monitor.sh"), contextMonitorScript());
     const opencodePluginSource = opencodePluginJs();
@@ -1146,7 +1151,7 @@ async function materializeRuntime(projectRoot, config, forceStateReset) {
     await cleanLegacyArtifacts(projectRoot);
     await cleanStaleFiles(projectRoot);
     await writeCommandContracts(projectRoot);
-    await writeUtilityCommands(projectRoot);
+    await writeUtilityCommands(projectRoot, config);
     await writeSkills(projectRoot, config);
     await writeContextModes(projectRoot);
     await writeArtifactTemplates(projectRoot);
@@ -1195,9 +1200,9 @@ export async function syncCclaw(projectRoot) {
  * stamps are rewritten so the on-disk config reflects the installed CLI.
  *
  * Shape preservation: if the user previously hand-authored advanced keys
- * (e.g. `tddTestGlobs`, `trackHeuristics`, `sliceReview`), those stay in the
- * yaml. If their existing config is minimal, the upgrade keeps it minimal —
- * advanced knobs are never silently added.
+ * (e.g. `tdd`, `compound`, `trackHeuristics`, `sliceReview`), those stay in
+ * the yaml. If their existing config is minimal, the upgrade keeps it
+ * minimal — advanced knobs are never silently added.
  */
 export async function upgradeCclaw(projectRoot) {
     const advancedKeysPresent = await detectAdvancedKeys(projectRoot);

package/dist/knowledge-store.d.ts

@@ -1,6 +1,7 @@
 import { type FlowStage } from "./types.js";
 export type KnowledgeEntryType = "rule" | "pattern" | "lesson" | "compound";
 export type KnowledgeEntryConfidence = "high" | "medium" | "low";
+export type KnowledgeEntrySeverity = "critical" | "important" | "suggestion";
 export type KnowledgeEntryUniversality = "project" | "personal" | "universal";
 export type KnowledgeEntryMaturity = "raw" | "lifted-to-rule" | "lifted-to-enforcement";
 export type KnowledgeEntrySource = "stage" | "retro" | "compound" | "ideate" | "manual";
@@ -9,6 +10,7 @@ export interface KnowledgeEntry {
     trigger: string;
     action: string;
     confidence: KnowledgeEntryConfidence;
+    severity?: KnowledgeEntrySeverity;
     domain: string | null;
     stage: FlowStage | null;
     origin_stage: FlowStage | null;
@@ -27,6 +29,7 @@ export interface KnowledgeSeedEntry {
     trigger: string;
     action: string;
     confidence: KnowledgeEntryConfidence;
+    severity?: KnowledgeEntrySeverity;
     domain?: string | null;
     stage?: FlowStage | null;
     origin_stage?: FlowStage | null;

package/dist/knowledge-store.js

@@ -5,6 +5,7 @@ import { withDirectoryLock } from "./fs-utils.js";
 import { FLOW_STAGES } from "./types.js";
 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"]);
 const KNOWLEDGE_UNIVERSALITY_SET = new Set(["project", "personal", "universal"]);
 const KNOWLEDGE_MATURITY_SET = new Set(["raw", "lifted-to-rule", "lifted-to-enforcement"]);
 const KNOWLEDGE_SOURCE_SET = new Set([
@@ -34,6 +35,7 @@ const KNOWLEDGE_REQUIRED_KEYS = [
 ];
 const KNOWLEDGE_ALLOWED_KEYS = new Set(KNOWLEDGE_REQUIRED_KEYS);
 KNOWLEDGE_ALLOWED_KEYS.add("source");
+KNOWLEDGE_ALLOWED_KEYS.add("severity");
 function knowledgePath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
 }
@@ -60,7 +62,8 @@ function dedupeKey(entry) {
         entry.origin_feature === null ? "null" : normalizeText(entry.origin_feature),
         entry.universality,
         entry.project === null ? "null" : normalizeText(entry.project),
-        entry.source === undefined || entry.source === null ? "null" : entry.source
+        entry.source === undefined || entry.source === null ? "null" : entry.source,
+        entry.severity === undefined ? "none" : entry.severity
     ].join("|");
 }
 function isIsoUtcTimestamp(value) {
@@ -100,6 +103,10 @@ export function validateKnowledgeEntry(entry) {
     if (!KNOWLEDGE_CONFIDENCE_SET.has(obj.confidence)) {
         errors.push("confidence must be one of: high, medium, low.");
     }
+    if (obj.severity !== undefined &&
+        (typeof obj.severity !== "string" || !KNOWLEDGE_SEVERITY_SET.has(obj.severity))) {
+        errors.push("severity must be one of: critical, important, suggestion.");
+    }
     if (!isNullableString(obj.domain)) {
         errors.push("domain must be string or null.");
     }
@@ -161,6 +168,9 @@ export function materializeKnowledgeEntry(seed, defaults = {}) {
         last_seen_ts: normalizeUtcIso(seed.last_seen_ts ?? now),
         project: seed.project ?? defaults.project ?? null
     };
+    if (seed.severity !== undefined) {
+        entry.severity = seed.severity;
+    }
     if (source !== null) {
         entry.source = source;
     }

package/dist/types.d.ts

@@ -88,6 +88,27 @@ export interface SliceReviewConfig {
     /** Tracks on which missed reviews escalate to a doctor warning. */
     enforceOnTracks?: FlowTrack[];
 }
+/**
+ * File-path routing hints used by workflow-guard during `tdd` stage.
+ *
+ * - `testPathPatterns`: paths considered test-side changes (RED writes).
+ * - `productionPathPatterns`: optional allowlist for production paths that
+ *   participate in GREEN/REFACTOR checks. When omitted, workflow-guard treats
+ *   non-test code files as production writes.
+ */
+export interface TddPathConfig {
+    testPathPatterns?: string[];
+    productionPathPatterns?: string[];
+}
+/**
+ * Compound-stage clustering policy.
+ *
+ * `recurrenceThreshold` is the base minimum repeat count for a trigger/action
+ * cluster before it is eligible for promotion into durable rules/skills.
+ */
+export interface CompoundConfig {
+    recurrenceThreshold?: number;
+}
 export interface VibyConfig {
     version: string;
     flowVersion: string;
@@ -112,13 +133,20 @@ export interface VibyConfig {
      */
     promptGuardMode?: "advisory" | "strict";
     /**
-     * TDD red->green->refactor enforcement mode used by workflow guard hooks.
+     * TDD RED -> GREEN -> REFACTOR enforcement mode used by workflow guard hooks.
      *
      * Since v0.43.0 this is an advanced override — see `strictness`.
      */
     tddEnforcement?: "advisory" | "strict";
-    /** Optional test file globs used by guard guidance and /cc-ops tdd-log docs. */
+    /**
+     * Legacy alias for test-side path detection in workflow-guard.
+     * Prefer `tdd.testPathPatterns` in new configs.
+     */
     tddTestGlobs?: string[];
+    /** Path-pattern routing for TDD test/production write classification. */
+    tdd?: TddPathConfig;
+    /** Compound-stage recurrence policy overrides. */
+    compound?: CompoundConfig;
     /** When true, cclaw installs managed git pre-commit/pre-push wrappers. */
     gitHookGuards?: boolean;
     /** Default flow track for new runs (quick = shortened path, standard = full pipeline). */

package/package.json

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