cclaw-cli 0.46.13 → 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;