cclaw-cli 0.11.0 → 0.13.0

package/dist/content/harnesses-doc.js

@@ -0,0 +1,103 @@
+import { HARNESS_ADAPTERS, harnessTier } from "../harness-adapters.js";
+import { HOOK_EVENTS_BY_HARNESS, HOOK_SEMANTIC_EVENTS } from "./hook-events.js";
+function harnessTitle(harness) {
+    switch (harness) {
+        case "claude":
+            return "Claude Code";
+        case "cursor":
+            return "Cursor";
+        case "opencode":
+            return "OpenCode";
+        case "codex":
+            return "OpenAI Codex";
+    }
+}
+function tierDescription(tier) {
+    if (tier === "tier1")
+        return "full native automation";
+    if (tier === "tier2")
+        return "partial automation with waivers";
+    return "manual fallback only";
+}
+export function harnessIntegrationDocMarkdown() {
+    const harnesses = Object.keys(HARNESS_ADAPTERS);
+    const capabilityRows = harnesses
+        .map((harness) => {
+        const adapter = HARNESS_ADAPTERS[harness];
+        const tier = harnessTier(harness);
+        return `| ${harnessTitle(harness)} | \`${harness}\` | \`${tier}\` (${tierDescription(tier)}) | ${adapter.capabilities.nativeSubagentDispatch} | ${adapter.capabilities.hookSurface} | ${adapter.capabilities.structuredAsk} |`;
+    })
+        .join("\n");
+    const hookRows = HOOK_SEMANTIC_EVENTS.map((eventName) => {
+        const columns = harnesses
+            .map((harness) => {
+            const mapping = HOOK_EVENTS_BY_HARNESS[harness][eventName];
+            return mapping ?? "missing";
+        })
+            .join(" | ");
+        return `| \`${eventName}\` | ${columns} |`;
+    }).join("\n");
+    return `# Harness Integration Matrix
+
+Generated from \`src/harness-adapters.ts\` capabilities and hook event mappings.
+
+## Capability tiers
+
+| Harness | ID | Tier | Native subagent dispatch | Hook surface | Structured ask |
+|---|---|---|---|---|---|
+${capabilityRows}
+
+## Semantic hook event coverage
+
+| Event | Claude | Cursor | OpenCode | Codex |
+|---|---|---|---|---|
+${hookRows}
+
+## Interpretation
+
+- \`tier1\`: full native delegation + structured asks + full hook surface.
+- \`tier2\`: usable flow with capability gaps; mandatory delegation can require waivers.
+- \`tier3\`: manual-only fallback; no native automation guarantees.
+
+## Shared command contract
+
+All harnesses receive the same utility commands:
+
+- \`/cc\` - flow entry and resume
+- \`/cc-next\` - stage progression
+- \`/cc-learn\` - knowledge capture/lookup
+- \`/cc-status\` - read-only visual flow snapshot
+- \`/cc-tree\` - deep flow tree (stages, artifacts, stale markers)
+- \`/cc-diff\` - before/after flow-state diff map
+- \`/cc-feature\` - multi-feature workspace management
+- \`/cc-tdd-log\` - explicit RED/GREEN/REFACTOR evidence log
+- \`/cc-retro\` - mandatory retrospective gate before archive
+- \`/cc-rewind\` - rewind flow and invalidate downstream stages
+- \`/cc-rewind-ack\` - clear stale stage markers after redo
+
+Stage order remains canonical:
+\`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship\`
+
+## Install surfaces
+
+Always generated:
+
+- \`.cclaw/commands/*.md\`
+- \`.cclaw/skills/*/SKILL.md\`
+- \`.cclaw/references/**\`
+- \`.cclaw/state/*.json|*.jsonl\`
+- \`AGENTS.md\` managed block
+
+Harness-specific additions:
+
+- \`claude\`: \`.claude/commands/cc*.md\`, \`.claude/hooks/hooks.json\`
+- \`cursor\`: \`.cursor/commands/cc*.md\`, \`.cursor/hooks.json\`, \`.cursor/rules/cclaw-workflow.mdc\`
+- \`opencode\`: \`.opencode/commands/cc*.md\`, \`.opencode/plugins/cclaw-plugin.mjs\`, opencode plugin registration
+- \`codex\`: \`.codex/commands/cc*.md\`, \`.codex/hooks.json\`
+
+## Runtime observability
+
+- \`.cclaw/state/harness-gaps.json\` captures per-harness capability gaps for the active config.
+- \`cclaw doctor\` validates shim, hook, and lifecycle surfaces against this capability model.
+`;
+}

package/dist/content/hook-events.d.ts

@@ -0,0 +1,4 @@
+import type { HarnessId } from "../types.js";
+export declare const HOOK_SEMANTIC_EVENTS: readonly ["session_rehydrate", "pre_tool_prompt_guard", "pre_tool_workflow_guard", "post_tool_context_monitor", "stop_checkpoint", "precompact_digest"];
+export type HookSemanticEvent = (typeof HOOK_SEMANTIC_EVENTS)[number];
+export declare const HOOK_EVENTS_BY_HARNESS: Record<HarnessId, Partial<Record<HookSemanticEvent, string>>>;

package/dist/content/hook-events.js

@@ -0,0 +1,42 @@
+export const HOOK_SEMANTIC_EVENTS = [
+    "session_rehydrate",
+    "pre_tool_prompt_guard",
+    "pre_tool_workflow_guard",
+    "post_tool_context_monitor",
+    "stop_checkpoint",
+    "precompact_digest"
+];
+export const HOOK_EVENTS_BY_HARNESS = {
+    claude: {
+        session_rehydrate: "SessionStart matcher startup|resume|clear|compact",
+        pre_tool_prompt_guard: "PreToolUse -> prompt-guard.sh",
+        pre_tool_workflow_guard: "PreToolUse -> workflow-guard.sh",
+        post_tool_context_monitor: "PostToolUse -> context-monitor.sh",
+        stop_checkpoint: "Stop -> stop-checkpoint.sh",
+        precompact_digest: "PreCompact -> pre-compact.sh"
+    },
+    cursor: {
+        session_rehydrate: "sessionStart/sessionResume/sessionClear/sessionCompact",
+        pre_tool_prompt_guard: "preToolUse -> prompt-guard.sh",
+        pre_tool_workflow_guard: "preToolUse -> workflow-guard.sh",
+        post_tool_context_monitor: "postToolUse -> context-monitor.sh",
+        stop_checkpoint: "stop -> stop-checkpoint.sh",
+        precompact_digest: "sessionCompact -> pre-compact.sh"
+    },
+    opencode: {
+        session_rehydrate: "plugin event handlers + transform rehydration",
+        pre_tool_prompt_guard: "plugin tool.execute.before -> prompt-guard.sh",
+        pre_tool_workflow_guard: "plugin tool.execute.before -> workflow-guard.sh",
+        post_tool_context_monitor: "plugin tool.execute.after -> context-monitor.sh",
+        stop_checkpoint: "plugin session.idle -> stop-checkpoint.sh",
+        precompact_digest: "plugin session.cleared/session.resumed hooks"
+    },
+    codex: {
+        session_rehydrate: "SessionStart matcher startup|resume|clear|compact",
+        pre_tool_prompt_guard: "PreToolUse -> prompt-guard.sh",
+        pre_tool_workflow_guard: "PreToolUse -> workflow-guard.sh",
+        post_tool_context_monitor: "PostToolUse -> context-monitor.sh",
+        stop_checkpoint: "Stop -> stop-checkpoint.sh",
+        precompact_digest: "PreCompact -> pre-compact.sh"
+    }
+};

package/dist/content/hooks.js

@@ -45,6 +45,7 @@ set -euo pipefail
 ${DETECT_ROOT}
 
 STATE_FILE="$ROOT/${RUNTIME_ROOT}/state/flow-state.json"
+ACTIVE_FEATURE_FILE="$ROOT/${RUNTIME_ROOT}/state/active-feature.json"
 CHECKPOINT_FILE="$ROOT/${RUNTIME_ROOT}/state/checkpoint.json"
 ACTIVITY_FILE="$ROOT/${RUNTIME_ROOT}/state/stage-activity.jsonl"
 SUGGESTION_MEMORY_FILE="$ROOT/${RUNTIME_ROOT}/state/suggestion-memory.json"
@@ -59,13 +60,16 @@ META_SKILL="$ROOT/${RUNTIME_ROOT}/skills/${META_SKILL_NAME}/SKILL.md"
 STAGE="none"
 COMPLETED="0"
 ACTIVE_RUN="none"
+ACTIVE_FEATURE="default"
 ACTIVE_CONTEXT_MODE="default"
+STALE_STAGES=""
 CONTEXT_MODE_NOTE=""
 if [ -f "$STATE_FILE" ]; then
   if command -v jq >/dev/null 2>&1; then
     STAGE=$(jq -r '.currentStage // "none"' "$STATE_FILE" 2>/dev/null || echo "none")
     COMPLETED=$(jq -r '(.completedStages | length) // 0' "$STATE_FILE" 2>/dev/null || echo "0")
     ACTIVE_RUN=$(jq -r '.activeRunId // "none"' "$STATE_FILE" 2>/dev/null || echo "none")
+    STALE_STAGES=$(jq -r '(.staleStages // {} | keys | join(", "))' "$STATE_FILE" 2>/dev/null || echo "")
   else
     if command -v python3 >/dev/null 2>&1; then
       STAGE=$(python3 - "$STATE_FILE" <<'PY'
@@ -115,6 +119,22 @@ except Exception:
     pass
 print(run)
 PY
+)
+      STALE_STAGES=$(python3 - "$STATE_FILE" <<'PY'
+import json
+import sys
+value = ""
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    stale = data.get("staleStages", {})
+    if isinstance(stale, dict):
+        keys = [k for k, v in stale.items() if isinstance(v, dict)]
+        value = ", ".join(keys)
+except Exception:
+    pass
+print(value)
+PY
 )
     else
       STAGE=$(grep -o '"currentStage"[[:space:]]*:[[:space:]]*"[^"]*"' "$STATE_FILE" 2>/dev/null | head -1 | sed 's/.*"\\([^"]*\\)"$/\\1/' || echo "none")
@@ -129,6 +149,28 @@ PY
   fi
 fi
 
+if [ -f "$ACTIVE_FEATURE_FILE" ]; then
+  if command -v jq >/dev/null 2>&1; then
+    ACTIVE_FEATURE=$(jq -r '.activeFeature // "default"' "$ACTIVE_FEATURE_FILE" 2>/dev/null || echo "default")
+  elif command -v python3 >/dev/null 2>&1; then
+    ACTIVE_FEATURE=$(python3 - "$ACTIVE_FEATURE_FILE" <<'PY'
+import json
+import sys
+feature = "default"
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        data = json.load(fh)
+    value = data.get("activeFeature")
+    if isinstance(value, str) and value:
+        feature = value
+except Exception:
+    pass
+print(feature)
+PY
+)
+  fi
+fi
+
 if [ -f "$CONTEXT_MODE_FILE" ]; then
   if command -v jq >/dev/null 2>&1; then
     ACTIVE_CONTEXT_MODE=$(jq -r '.activeMode // "default"' "$CONTEXT_MODE_FILE" 2>/dev/null || echo "default")
@@ -415,7 +457,7 @@ if [ -n "$ROUTING_MISSING" ]; then
 fi
 
 # --- Build context message ---
-CTX="cclaw loaded. Flow: stage=$STAGE ($COMPLETED/8 completed, run=$ACTIVE_RUN). Active artifacts: ${RUNTIME_ROOT}/artifacts/. Learnings: $LEARNINGS_COUNT entries."
+CTX="cclaw loaded. Flow: stage=$STAGE ($COMPLETED/8 completed, run=$ACTIVE_RUN, feature=$ACTIVE_FEATURE). Active artifacts: ${RUNTIME_ROOT}/artifacts/. Feature snapshots: ${RUNTIME_ROOT}/features/$ACTIVE_FEATURE/. Learnings: $LEARNINGS_COUNT entries."
 if [ -n "$VERSION_NOTE" ]; then
   CTX="$CTX
 $VERSION_NOTE"
@@ -452,6 +494,10 @@ if [ -n "$STAGE_SUGGESTION" ]; then
 $STAGE_SUGGESTION
 To disable suggestions persistently set ${RUNTIME_ROOT}/state/suggestion-memory.json -> enabled=false."
 fi
+if [ -n "$STALE_STAGES" ]; then
+  CTX="$CTX
+Stale stages pending acknowledgement: $STALE_STAGES (use /cc-rewind-ack <stage> after redo)."
+fi
 if [ -n "$KNOWLEDGE_DIGEST" ]; then
   CTX="$CTX
 Knowledge digest (top relevant entries):

package/dist/content/meta-skill.js

@@ -3,7 +3,7 @@ export const META_SKILL_NAME = "using-cclaw";
 export function usingCclawSkillMarkdown() {
     return `---
 name: using-cclaw
-description: "Routing brain for cclaw. Decide whether to start/resume a stage, answer directly, or use /cc-learn."
+description: "Routing brain for cclaw. Decide whether to start/resume a stage, answer directly, or use utility commands like /cc-learn, /cc-status, /cc-tree, and /cc-diff."
 ---
 
 # Using Cclaw
@@ -26,7 +26,8 @@ Task arrives
   ├─ Pure question / non-software ask? -> answer directly (no stage)
   ├─ New software work? -> /cc <idea>
   ├─ Resume existing flow? -> /cc or /cc-next
-  └─ Knowledge operation? -> /cc-learn
+  ├─ Knowledge operation? -> /cc-learn
+  └─ Workspace operation? -> /cc-status, /cc-tree, /cc-diff, /cc-feature, /cc-tdd-log, /cc-retro, /cc-rewind
 \`\`\`
 
 ## Task classification

package/dist/content/next-command.js

@@ -39,11 +39,12 @@ This is the only progression command the user needs to drive the entire flow. St
 
 1. Read **\`${flowPath}\`**. If missing → **BLOCKED** (state missing).
 2. Parse JSON. Capture \`currentStage\` and \`stageGateCatalog[currentStage]\`.
-3. Let \`G\` = \`requiredGates\` for **\`currentStage\`** from the stage schema.
-4. Let \`catalog\` = \`stageGateCatalog[currentStage]\` from flow state.
-5. **Satisfied** for gate id \`g\`: \`g\` in \`catalog.passed\` and \`g\` not in \`catalog.blocked\`.
-6. Let \`M\` = \`mandatoryDelegations\` for \`currentStage\`.
-7. If \`M\` is non-empty, inspect **\`${delegationPath}\`**. Treat as satisfied only if the agent is **completed** or **waived**.
+3. If \`staleStages[currentStage]\` exists, do not advance automatically. Re-run the stage artifact work, then clear the marker with \`/cc-rewind-ack <currentStage>\`.
+4. Let \`G\` = \`requiredGates\` for **\`currentStage\`** from the stage schema.
+5. Let \`catalog\` = \`stageGateCatalog[currentStage]\` from flow state.
+6. **Satisfied** for gate id \`g\`: \`g\` in \`catalog.passed\` and \`g\` not in \`catalog.blocked\`.
+7. Let \`M\` = \`mandatoryDelegations\` for \`currentStage\`.
+8. If \`M\` is non-empty, inspect **\`${delegationPath}\`**. Treat as satisfied only if the agent is **completed** or **waived**.
 
 ### Path A: Current stage is NOT complete (any gate unmet or delegation missing)
 
@@ -120,7 +121,8 @@ Do **not** mark gates satisfied from memory alone. Cite **artifact evidence** (p
 
 1. Open **\`${flowPath}\`**.
 2. Record \`currentStage\` and \`stageGateCatalog[currentStage]\`.
-3. If the file is missing or invalid JSON → **BLOCKED** (report and stop).
+3. If \`staleStages[currentStage]\` exists, re-run the stage and clear marker via \`/cc-rewind-ack <currentStage>\` before advancing.
+4. If the file is missing or invalid JSON → **BLOCKED** (report and stop).
 
 ### Step 2: Evaluate gates
 

package/dist/content/observe.d.ts

@@ -9,7 +9,11 @@ export interface PromptGuardOptions {
     strictMode?: boolean;
 }
 export declare function promptGuardScript(options?: PromptGuardOptions): string;
-export declare function workflowGuardScript(): string;
+export interface WorkflowGuardOptions {
+    tddEnforcementMode?: "advisory" | "strict";
+    tddTestGlobs?: string[];
+}
+export declare function workflowGuardScript(options?: WorkflowGuardOptions): string;
 export declare function observeScript(): string;
 export declare function contextMonitorScript(): string;
 export declare function summarizeObservationsRuntimeModule(): string;

package/dist/content/observe.js

@@ -153,18 +153,25 @@ fi
 exit 0
 `;
 }
-export function workflowGuardScript() {
+export function workflowGuardScript(options = {}) {
+    const tddEnforcementMode = options.tddEnforcementMode === "strict" ? "strict" : "advisory";
+    const tddTestGlobs = options.tddTestGlobs && options.tddTestGlobs.length > 0
+        ? options.tddTestGlobs.join(",")
+        : "**/*.test.*,**/*.spec.*,**/test/**";
     return `#!/usr/bin/env bash
 # cclaw workflow guard hook — generated by cclaw sync
 # Enforces stage-aware command discipline and recent flow-state read hygiene.
 set -uo pipefail
 WORKFLOW_GUARD_MODE="\${CCLAW_WORKFLOW_GUARD_MODE:-advisory}"
 MAX_FLOW_READ_AGE_SEC="\${CCLAW_WORKFLOW_GUARD_MAX_AGE_SEC:-1800}"
+TDD_ENFORCEMENT_MODE="${tddEnforcementMode}"
+TDD_TEST_GLOBS="${tddTestGlobs}"
 
 ${RUNTIME_SHELL_DETECT_ROOT}
 
 STATE_DIR="$ROOT/${RUNTIME_ROOT}/state"
 FLOW_STATE_FILE="$STATE_DIR/flow-state.json"
+TDD_LOG_FILE="$STATE_DIR/tdd-cycle-log.jsonl"
 GUARD_STATE_FILE="$STATE_DIR/workflow-guard.json"
 GUARD_LOG="$STATE_DIR/workflow-guard.jsonl"
 mkdir -p "$STATE_DIR" 2>/dev/null || true
@@ -234,9 +241,11 @@ NOW_EPOCH=$(date +%s 2>/dev/null || echo "0")
 REASONS=""
 
 CURRENT_STAGE="none"
+CURRENT_RUN="active"
 if [ -f "$FLOW_STATE_FILE" ]; then
   if command -v jq >/dev/null 2>&1; then
     CURRENT_STAGE=$(jq -r '.currentStage // "none"' "$FLOW_STATE_FILE" 2>/dev/null || echo "none")
+    CURRENT_RUN=$(jq -r '.activeRunId // "active"' "$FLOW_STATE_FILE" 2>/dev/null || echo "active")
   elif command -v python3 >/dev/null 2>&1; then
     CURRENT_STAGE=$(python3 - "$FLOW_STATE_FILE" <<'PY'
 import json
@@ -252,6 +261,21 @@ except Exception:
     pass
 print(stage)
 PY
+)
+    CURRENT_RUN=$(python3 - "$FLOW_STATE_FILE" <<'PY'
+import json
+import sys
+run_id = "active"
+try:
+    with open(sys.argv[1], "r", encoding="utf-8") as fh:
+        parsed = json.load(fh)
+    value = parsed.get("activeRunId")
+    if isinstance(value, str) and value:
+        run_id = value
+except Exception:
+    pass
+print(run_id)
+PY
 )
   fi
 fi
@@ -325,6 +349,99 @@ is_preimplementation_stage() {
   esac
 }
 
+is_tdd_test_payload() {
+  local text="$1"
+  if printf '%s' "$text" | grep -Eq '/tests?/|\\.test\\.|\\.spec\\.'; then
+    return 0
+  fi
+  if printf '%s' "$TDD_TEST_GLOBS" | grep -Eq '.' && printf '%s' "$text" | grep -Eq '(test|spec)'; then
+    return 0
+  fi
+  return 1
+}
+
+is_tdd_runtime_write_payload() {
+  local text="$1"
+  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
+    return 1
+  fi
+  return 0
+}
+
+has_open_red_cycle() {
+  if [ ! -f "$TDD_LOG_FILE" ] || [ ! -s "$TDD_LOG_FILE" ]; then
+    return 1
+  fi
+  local red_count="0"
+  local green_count="0"
+  if command -v jq >/dev/null 2>&1; then
+    red_count=$(jq -r --arg run "$CURRENT_RUN" 'select((.runId // $run) == $run and .phase == "red") | .phase' "$TDD_LOG_FILE" 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+    green_count=$(jq -r --arg run "$CURRENT_RUN" 'select((.runId // $run) == $run and .phase == "green") | .phase' "$TDD_LOG_FILE" 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+  elif command -v python3 >/dev/null 2>&1; then
+    red_count=$(python3 - "$TDD_LOG_FILE" "$CURRENT_RUN" <<'PY'
+import json
+import sys
+count = 0
+run_id = sys.argv[2]
+with open(sys.argv[1], "r", encoding="utf-8") as fh:
+    for raw in fh:
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            parsed = json.loads(raw)
+        except Exception:
+            continue
+        if not isinstance(parsed, dict):
+            continue
+        if str(parsed.get("runId", run_id)) != run_id:
+            continue
+        if parsed.get("phase") == "red":
+            count += 1
+print(count)
+PY
+)
+    green_count=$(python3 - "$TDD_LOG_FILE" "$CURRENT_RUN" <<'PY'
+import json
+import sys
+count = 0
+run_id = sys.argv[2]
+with open(sys.argv[1], "r", encoding="utf-8") as fh:
+    for raw in fh:
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            parsed = json.loads(raw)
+        except Exception:
+            continue
+        if not isinstance(parsed, dict):
+            continue
+        if str(parsed.get("runId", run_id)) != run_id:
+            continue
+        if parsed.get("phase") == "green":
+            count += 1
+print(count)
+PY
+)
+  else
+    red_count=$(grep -ci '"phase"[[:space:]]*:[[:space:]]*"red"' "$TDD_LOG_FILE" 2>/dev/null || echo "0")
+    green_count=$(grep -ci '"phase"[[:space:]]*:[[:space:]]*"green"' "$TDD_LOG_FILE" 2>/dev/null || echo "0")
+  fi
+  [ -n "$red_count" ] || red_count="0"
+  [ -n "$green_count" ] || green_count="0"
+  if [ "$red_count" -gt "$green_count" ]; then
+    return 0
+  fi
+  return 1
+}
+
 detect_target_stage() {
   local text="$1"
   for stage in brainstorm scope design spec plan tdd review ship; do
@@ -373,6 +490,18 @@ if is_preimplementation_stage "$CURRENT_STAGE" && is_mutating_tool "$TOOL_LOWER"
   fi
 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 [ -n "$REASONS" ]; then
+        REASONS="$REASONS,tdd_write_without_open_red"
+      else
+        REASONS="tdd_write_without_open_red"
+      fi
+    fi
+  fi
+fi
+
 if is_preimplementation_stage "$CURRENT_STAGE" && ! is_plan_mode_safe_tool "$TOOL_LOWER"; then
   if ! is_mutating_tool "$TOOL_LOWER"; then
     if ! printf '%s' "$PAYLOAD_LOWER" | grep -Eq '\.cclaw/' && ! is_cclaw_cli_payload "$PAYLOAD_LOWER"; then
@@ -438,7 +567,7 @@ PY
 fi
 
 if [ -n "$REASONS" ]; then
-  NOTE="Cclaw workflow guard: detected potential flow violation (\${REASONS}). Re-read ${RUNTIME_ROOT}/state/flow-state.json, avoid source edits before tdd stage, and continue from current stage ordering."
+  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."
   if command -v jq >/dev/null 2>&1; then
     ENTRY=$(jq -n -c \
       --arg ts "$TS" \
@@ -458,6 +587,9 @@ if [ -n "$REASONS" ]; then
   if printf '%s' "$REASONS" | grep -Eq 'implementation_write_before_'; then
     SHOULD_BLOCK="true"
   fi
+  if printf '%s' "$REASONS" | grep -Eq 'tdd_write_without_open_red' && [ "$TDD_ENFORCEMENT_MODE" = "strict" ]; then
+    SHOULD_BLOCK="true"
+  fi
   if [ "$WORKFLOW_GUARD_MODE" = "strict" ] || [ "$SHOULD_BLOCK" = "true" ]; then
     printf '[cclaw] %s (blocked by workflow guard)\n' "$NOTE" >&2
     exit 1

package/dist/content/protocols.js

@@ -78,14 +78,42 @@ Before adding new code/templates/rules:
 - Evidence beats volume.
 - Keep stage output concrete and testable.
 
-## Preamble rule
+## Preamble budget
 
-Use a turn preamble only for non-trivial execution turns:
-- a file-editing implementation step,
-- stage transition,
-- or multi-step operation where drift risk is real.
+This section is the single source of truth for preamble behavior.
+Do not duplicate preamble rules in AGENTS.md, harness adapters, or stage-local docs.
 
-Skip preamble for pure Q&A or tiny edits.
+### Emit when
+
+| Trigger | Machine-verifiable condition |
+|---|---|
+| Stage transition | \`flow-state.currentStage\` changes in this turn |
+| Non-trivial implementation turn | agent is about to run source-editing tools outside \`.cclaw/\` |
+| Multi-step risky operation | planned sequence contains 2+ commands with rollback/risk potential |
+
+### Skip when
+
+| Skip reason | Condition |
+|---|---|
+| Pure Q&A | no filesystem or runtime mutation planned |
+| Trivial change | single low-risk edit with no stage or plan drift |
+| Subagent dispatch payload | prompt is for spawned agent/tool call only |
+| Cooldown hit | same stage + same trigger emitted within cooldown window |
+
+### Form contract (max 4 lines)
+
+1. \`Stage:\` current stage id  
+2. \`Goal:\` concrete objective for this turn  
+3. \`Plan:\` next 1-3 actions  
+4. \`Guardrails:\` key constraints / non-goals
+
+### Cooldown
+
+- Record each emitted preamble in \`.cclaw/state/preamble-log.jsonl\` as JSON line:
+  \`{"ts","stage","runId","trigger","hash"}\`.
+- Default cooldown: 15 minutes for identical \`stage + trigger + hash\`.
+- TDD wave mode uses stricter dedupe: one preamble per wave unless scope changes.
+- If the plan changes materially, a new preamble is allowed inside cooldown.
 
 ## Operational learning
 

package/dist/content/research-playbooks.d.ts

@@ -0,0 +1,8 @@
+/**
+ * In-thread research playbooks.
+ *
+ * These files intentionally have no YAML frontmatter and are not standalone
+ * delegated personas. The primary agent loads and executes them directly.
+ */
+export declare const RESEARCH_PLAYBOOKS: Record<string, string>;
+export declare const RESEARCH_PLAYBOOK_FILES: string[];