cclaw-cli 0.46.13 → 0.46.15

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/research-playbooks.js

@@ -102,6 +102,42 @@ Summarize citable domain practices for a narrow design decision.
 
 - Cite authoritative sources (official docs/standards).
 - State uncertainty explicitly when consensus is weak.
+`,
+    "research-fleet.md": `# Parallel Research Fleet Playbook
+
+## Purpose
+
+Run a four-lens investigation before design lock so architecture choices are grounded
+in current ecosystem data, not intuition.
+
+## Dispatch Lenses (fan-out)
+
+Launch four independent investigation threads in parallel when the harness supports it
+(or sequentially with explicit role-switch logs when it does not):
+
+1. **stack-researcher** — dependency compatibility, alternatives, deprecations.
+2. **features-researcher** — domain conventions and product/UX patterns.
+3. **architecture-researcher** — architecture options and trade-off matrix.
+4. **pitfalls-researcher** — known failure modes, CVEs, and operational traps.
+
+## Output Contract
+
+Write findings to \`.cclaw/artifacts/02a-research.md\` with these sections:
+
+- \`## Stack Analysis\`
+- \`## Features & Patterns\`
+- \`## Architecture Options\`
+- \`## Pitfalls & Risks\`
+- \`## Synthesis\`
+
+Each section must contain concrete notes and at least one evidence reference
+(source URL, file path, or command output anchor).
+
+## Guardrails
+
+- Investigate first; no production code edits in this playbook.
+- Keep lenses independent during fan-out; merge only in synthesis.
+- If any lens is incomplete, record it explicitly in \`## Synthesis\` as a blocker.
 `,
     "git-history.md": `# Git History Playbook
 

package/dist/content/stage-schema.js

@@ -13,6 +13,7 @@ const REQUIRED_GATE_IDS = {
         "scope_user_approved"
     ],
     design: [
+        "design_research_complete",
         "design_architecture_locked",
         "design_data_flow_mapped",
         "design_failure_modes_mapped",
@@ -53,7 +54,13 @@ const REQUIRED_GATE_IDS = {
 const REQUIRED_ARTIFACT_SECTIONS = {
     brainstorm: ["Context", "Problem", "Approaches", "Selected Direction"],
     scope: ["Scope Mode", "In Scope / Out of Scope", "Completion Dashboard", "Scope Summary"],
-    design: ["Architecture Boundaries", "Architecture Diagram", "Failure Mode Table", "Completion Dashboard"],
+    design: [
+        "Research Fleet Synthesis",
+        "Architecture Boundaries",
+        "Architecture Diagram",
+        "Failure Mode Table",
+        "Completion Dashboard"
+    ],
     spec: ["Acceptance Criteria", "Edge Cases", "Testability Map", "Approval"],
     plan: ["Task List", "Dependency Batches", "Acceptance Mapping", "WAIT_FOR_CONFIRM"],
     tdd: ["RED Evidence", "GREEN Evidence", "REFACTOR Notes", "Traceability", "Verification Ladder"],

package/dist/content/stages/design.js

@@ -21,6 +21,7 @@ export const DESIGN = {
     ],
     checklist: [
         "Trivial-Change Escape Hatch — If scope artifact shows ≤3 files, zero new interfaces, and no cross-module data flow, skip full review sections. Produce a mini-design: one paragraph of rationale, list of changed files, one risk to watch. Proceed to spec.",
+        "Parallel Research Fleet — run `research/research-fleet.md` before architecture lock. Record 4-lens findings in `.cclaw/artifacts/02a-research.md` and summarize resulting decisions in `## Research Fleet Synthesis`.",
         "Design Doc Check — read existing design docs, scope artifact, brainstorm artifact. If a design doc exists that covers this area, check for 'Supersedes:' and use the latest. Use upstream artifacts as source of truth.",
         "Codebase Investigation — Before any design decision, read the actual code in the blast radius. List every file that will be touched, its current responsibilities, and existing patterns (error handling, naming, test style). Design must conform to discovered patterns, not impose new ones without justification.",
         "Step 0: Scope Challenge — what existing code solves sub-problems? Minimum change set? Complexity check: 8+ files or 2+ new services = complexity smell → flag for possible scope reduction.",
@@ -50,6 +51,7 @@ export const DESIGN = {
     ],
     process: [
         "Read upstream artifacts (brainstorm, scope).",
+        "Run the research fleet playbook and write `.cclaw/artifacts/02a-research.md` before locking architecture choices.",
         "Investigate codebase: read files in blast radius, catalogue current patterns and responsibilities.",
         "Run Step 0 scope challenge: existing code leverage, minimum change set, complexity check.",
         "Walk through each review section interactively.",
@@ -62,12 +64,14 @@ export const DESIGN = {
         "Write design lock artifact for downstream spec/plan."
     ],
     requiredGates: [
+        { id: "design_research_complete", description: "Parallel research artifact is complete and synthesized into design decisions." },
         { id: "design_architecture_locked", description: "Architecture boundaries are explicit and approved." },
         { id: "design_data_flow_mapped", description: "Data/state flow includes edge-case paths." },
         { id: "design_failure_modes_mapped", description: "Failure modes and mitigations are documented." },
         { id: "design_test_and_perf_defined", description: "Test strategy and performance budget are defined." }
     ],
     requiredEvidence: [
+        "Research artifact written to `.cclaw/artifacts/02a-research.md` with stack/features/architecture/pitfalls sections plus synthesis.",
         "Artifact written to `.cclaw/artifacts/03-design.md`.",
         "Failure-mode table exists with mitigations.",
         "Test strategy includes unit/integration/e2e expectations.",
@@ -77,15 +81,18 @@ export const DESIGN = {
     ],
     inputs: ["scope contract", "system constraints", "non-functional requirements"],
     requiredContext: [
+        "parallel research synthesis from `.cclaw/artifacts/02a-research.md`",
         "existing architecture and boundaries",
         "operational constraints",
         "security and reliability expectations"
     ],
     researchPlaybooks: [
+        "research/research-fleet.md",
         "research/framework-docs-lookup.md",
         "research/best-practices-lookup.md"
     ],
     outputs: [
+        "parallel research synthesis artifact",
         "architecture lock",
         "risk and failure map",
         "test and performance baseline",
@@ -110,17 +117,12 @@ export const DESIGN = {
         "Missing data-flow edge cases",
         "No performance budget for critical path",
         "Batching multiple design issues into one question",
-        "Skipping review sections because plan seems simple",
         "Agreeing with user's architecture choice without evaluating alternatives",
-        "Hedging every recommendation with 'it depends' instead of taking a position",
-        "No explicit architecture boundary section",
-        "No failure recovery strategy",
-        "No defined test/perf baseline",
         "No NOT-in-scope output section",
-        "No What-already-exists output section",
         "Design decisions made without reading the actual code first"
     ],
     policyNeedles: [
+        "Parallel Research Fleet",
         "Architecture",
         "Data Flow",
         "Failure Modes and Mitigation",
@@ -186,11 +188,16 @@ export const DESIGN = {
     ],
     completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
     crossStageTrace: {
-        readsFrom: [".cclaw/artifacts/01-brainstorm.md", ".cclaw/artifacts/02-scope.md"],
+        readsFrom: [
+            ".cclaw/artifacts/01-brainstorm.md",
+            ".cclaw/artifacts/02-scope.md",
+            ".cclaw/artifacts/02a-research.md"
+        ],
         writesTo: [".cclaw/artifacts/03-design.md"],
         traceabilityRule: "Every architecture decision must trace to a scope boundary. Every downstream spec requirement must trace to a design decision."
     },
     artifactValidation: [
+        { section: "Research Fleet Synthesis", required: true, validationRule: "Must summarize all four lenses (stack/features/architecture/pitfalls) and map findings to concrete design decisions." },
         { section: "Codebase Investigation", required: false, validationRule: "Must list blast-radius files with current responsibilities and discovered patterns." },
         { section: "Search Before Building", required: false, validationRule: "For each technical choice: Layer 1 (exact match), Layer 2 (partial match), Layer 3 (inspiration), EUREKA labels with reuse-first default." },
         { section: "Architecture Boundaries", required: true, validationRule: "Must list component boundaries with ownership." },

package/dist/content/templates.js

@@ -152,6 +152,47 @@ inputs_hash: sha256:pending
 - Deferred:
 - Explicitly excluded:
 
+## Learnings
+- None this stage.
+`,
+    "02a-research.md": `---
+stage: design
+schema_version: 1
+version: 0.18.0
+feature: <feature-id>
+locked_decisions: []
+inputs_hash: sha256:pending
+---
+
+# Research Report
+
+## Stack Analysis
+| Topic | Finding | Evidence |
+|---|---|---|
+| Dependency compatibility |  |  |
+| Alternatives/deprecations |  |  |
+
+## Features & Patterns
+| Topic | Finding | Evidence |
+|---|---|---|
+| Domain conventions |  |  |
+| UX/product patterns |  |  |
+
+## Architecture Options
+| Option | Trade-offs | Recommendation | Evidence |
+|---|---|---|---|
+| A |  |  |  |
+| B |  |  |  |
+
+## Pitfalls & Risks
+| Risk | Impact | Mitigation | Evidence |
+|---|---|---|---|
+|  |  |  |  |
+
+## Synthesis
+- Key decisions informed by research:
+- Open questions:
+
 ## Learnings
 - None this stage.
 `,
@@ -178,6 +219,14 @@ inputs_hash: sha256:pending
 | Layer 2 |  |  |
 | Layer 3 |  |  |
 
+## Research Fleet Synthesis
+| Lens | Key findings | Design impact | Evidence |
+|---|---|---|---|
+| stack-researcher |  |  |  |
+| features-researcher |  |  |  |
+| architecture-researcher |  |  |  |
+| pitfalls-researcher |  |  |  |
+
 ## Architecture Boundaries
 | Component | Responsibility | Owner |
 |---|---|---|

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/gate-evidence.js

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { checkReviewVerdictConsistency, lintArtifact, validateReviewArmy } from "./artifact-linter.js";
+import { checkReviewVerdictConsistency, extractMarkdownSectionBody, lintArtifact, validateReviewArmy } from "./artifact-linter.js";
 import { RUNTIME_ROOT } from "./constants.js";
 import { stageSchema } from "./content/stage-schema.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
@@ -26,6 +26,23 @@ async function currentStageArtifactExists(projectRoot, stage, track) {
         return false;
     }
 }
+async function readArtifactMarkdown(projectRoot, artifactFile) {
+    const candidates = [
+        path.join(projectRoot, RUNTIME_ROOT, "artifacts", artifactFile),
+        path.join(projectRoot, artifactFile)
+    ];
+    for (const candidate of candidates) {
+        if (!(await exists(candidate)))
+            continue;
+        try {
+            return await fs.readFile(candidate, "utf8");
+        }
+        catch {
+            // Try next location.
+        }
+    }
+    return null;
+}
 function unique(values) {
     return [...new Set(values)];
 }
@@ -36,6 +53,13 @@ function sameStringArray(a, b) {
 }
 const RECONCILIATION_NOTICES_FILE = "reconciliation-notices.json";
 const RECONCILIATION_NOTICES_SCHEMA_VERSION = 1;
+const DESIGN_RESEARCH_REQUIRED_SECTIONS = [
+    "Stack Analysis",
+    "Features & Patterns",
+    "Architecture Options",
+    "Pitfalls & Risks",
+    "Synthesis"
+];
 export const RECONCILIATION_NOTICES_REL_PATH = `${RUNTIME_ROOT}/state/${RECONCILIATION_NOTICES_FILE}`;
 function isFlowStageValue(value) {
     return typeof value === "string" && FLOW_STAGES.includes(value);
@@ -222,6 +246,37 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
                 }
             }
         }
+        if (stage === "design") {
+            const researchGateRequired = schema.requiredGates.some((gate) => gate.id === "design_research_complete" && gate.tier === "required");
+            if (researchGateRequired) {
+                const researchMarkdown = await readArtifactMarkdown(projectRoot, "02a-research.md");
+                if (!researchMarkdown) {
+                    issues.push("design research gate blocked (design_research_complete): missing `.cclaw/artifacts/02a-research.md`.");
+                }
+                else {
+                    const missingSections = [];
+                    for (const section of DESIGN_RESEARCH_REQUIRED_SECTIONS) {
+                        const body = extractMarkdownSectionBody(researchMarkdown, section);
+                        if (body === null) {
+                            missingSections.push(section);
+                            continue;
+                        }
+                        const meaningfulLines = body
+                            .split(/\r?\n/gu)
+                            .map((line) => line.trim())
+                            .filter((line) => line.length > 0)
+                            .filter((line) => !/^\|?(?:[-:\s|])+$/u.test(line));
+                        const nonPlaceholder = meaningfulLines.filter((line) => !/\b(?:TODO|TBD|FIXME|pending|<fill-in>)\b/iu.test(line));
+                        if (nonPlaceholder.length === 0) {
+                            missingSections.push(`${section} (empty or placeholder)`);
+                        }
+                    }
+                    if (missingSections.length > 0) {
+                        issues.push(`design research gate blocked (design_research_complete): ${missingSections.join(", ")}.`);
+                    }
+                }
+            }
+        }
     }
     const passedSet = new Set(catalog.passed);
     const missingRequired = required.filter((gateId) => !passedSet.has(gateId));

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;