cclaw-cli 0.11.0 → 0.12.0

package/dist/content/doctor-references.js

@@ -0,0 +1,144 @@
+import { RUNTIME_ROOT } from "../constants.js";
+export const DOCTOR_REFERENCE_DIR = `${RUNTIME_ROOT}/references/doctor`;
+export const DOCTOR_REFERENCE_MARKDOWN = {
+    "README.md": `# Doctor Reference Index
+
+Reference docs for \`cclaw doctor\` checks.
+
+## Categories
+
+- \`runtime-layout.md\` - runtime directories, generated commands, and skill files
+- \`hooks-and-lifecycle.md\` - hook wiring and harness lifecycle integration
+- \`harness-and-routing.md\` - harness shims, AGENTS/CLAUDE routing blocks, cursor rule
+- \`state-and-gates.md\` - flow-state integrity and gate evidence contracts
+- \`delegation-and-preamble.md\` - mandatory delegations and preamble budget controls
+- \`traceability.md\` - spec/plan/tdd trace matrix expectations
+- \`tooling-capabilities.md\` - local runtime prerequisites (bash/node/python/jq)
+- \`config-and-policy.md\` - config schema, rules policy, and validation references
+`,
+    "runtime-layout.md": `# Runtime Layout
+
+## Expected surfaces
+
+- \`.cclaw/\` root and generated subdirectories
+- stage command contracts under \`.cclaw/commands/\`
+- stage skills under \`.cclaw/skills/\`
+- utility command contracts (\`start\`, \`next\`, \`learn\`, \`status\`)
+- state files under \`.cclaw/state/\`
+
+## Typical fixes
+
+1. Run \`cclaw sync\` to re-materialize generated assets.
+2. If runtime is severely drifted, run \`cclaw upgrade\`.
+3. Avoid manual edits under generated runtime paths unless explicitly supported.
+`,
+    "hooks-and-lifecycle.md": `# Hooks And Lifecycle
+
+## Expected behavior
+
+- session start rehydrates flow + knowledge digest
+- pre-tool hooks run prompt/workflow guards
+- post-tool hooks run context monitor
+- stop hooks checkpoint progress
+- OpenCode uses plugin-based lifecycle integration
+
+## Typical fixes
+
+1. Re-run \`cclaw sync\` after harness config changes.
+2. Ensure harness is enabled in \`.cclaw/config.yaml\`.
+3. Validate hook JSON shape and remove malformed manual edits.
+`,
+    "harness-and-routing.md": `# Harness And Routing
+
+## Expected behavior
+
+- command shims exist for every enabled harness
+- managed routing block is present in \`AGENTS.md\` (and \`CLAUDE.md\` when applicable)
+- cursor rule mirrors workflow activation guidance
+- opencode plugin path is registered in opencode config
+
+## Typical fixes
+
+1. Confirm \`harnesses\` list in \`.cclaw/config.yaml\`.
+2. Run \`cclaw sync\` to re-generate shims/routing files.
+3. Remove stale harness artifacts for disabled harnesses via \`cclaw sync\`.
+`,
+    "state-and-gates.md": `# State And Gates
+
+## Expected behavior
+
+- \`flow-state.json\` has activeRunId, current stage, and consistent track/skippedStages
+- current-stage gate evidence is internally consistent
+- completed stages only include passed required gates
+
+## Typical fixes
+
+1. Run \`cclaw doctor --reconcile-gates\` to refresh current-stage gate catalog.
+2. Repair inconsistent stage artifacts, then re-run doctor.
+3. Do not manually mutate gate arrays without matching artifact evidence.
+`,
+    "delegation-and-preamble.md": `# Delegation And Preamble
+
+## Delegation contract
+
+- mandatory delegations for the current stage must be completed or waived
+- waivers should include an explicit reason
+- stale entries from previous runs are ignored by current-run checks
+
+## Preamble budget contract
+
+- preamble events are logged to \`.cclaw/state/preamble-log.jsonl\`
+- repeated entries inside cooldown windows indicate noisy preamble behavior
+- in TDD wave mode, emit once per wave unless plan materially changes
+
+## Typical fixes
+
+1. Append missing delegation records with \`completed\` or \`waived\` status.
+2. Record harness-limitation waivers when native delegation is unavailable.
+3. Reduce repeated preamble emissions and keep logs structured (\`ts/stage/trigger/hash\`).
+`,
+    "traceability.md": `# Traceability
+
+## Expected behavior
+
+- spec criteria map to plan tasks
+- plan tasks map to tdd slices/tests
+- no orphaned criteria/tasks/tests when downstream artifacts exist
+
+## Typical fixes
+
+1. Add stable IDs to spec/plan/tdd sections.
+2. Ensure mapping tables include every active criterion/task/slice.
+3. Re-run \`cclaw doctor\` after artifact updates.
+`,
+    "tooling-capabilities.md": `# Tooling Capabilities
+
+## Required
+
+- \`bash\` for runtime hook scripts
+- \`node\` for generated runtime scripts/plugins
+
+## Optional fallback
+
+- at least one of \`python3\` or \`jq\` for JSON parsing fallback paths
+
+## Typical fixes
+
+1. Install missing runtime tools.
+2. Keep at least one JSON fallback parser available (\`python3\` or \`jq\`).
+`,
+    "config-and-policy.md": `# Config And Policy
+
+## Expected behavior
+
+- \`.cclaw/config.yaml\` parses and uses supported keys/values
+- \`.cclaw/rules/rules.json\` matches generated policy schema
+- policy needles and required sections remain present in generated contracts
+
+## Typical fixes
+
+1. Repair invalid config values and run \`cclaw sync\`.
+2. Re-generate policy files via \`cclaw sync\` if drift is detected.
+3. Keep generated contracts aligned with stage schemas and policy needles.
+`
+};

package/dist/content/examples.js

@@ -379,7 +379,7 @@ Execution rule: complete and verify each wave before starting the next wave.
 ## Review Army Contract
 
 - See \`07-review-army.json\`
-- Reconciliation summary: 1 duplicate collapsed (R-1 reported by spec-reviewer and code-reviewer), 0 conflicts
+- Reconciliation summary: 1 duplicate collapsed (R-1 reported by reviewer and security-reviewer), 0 conflicts
 
 ## Review Readiness Dashboard
 

package/dist/content/harnesses-doc.d.ts

@@ -0,0 +1 @@
+export declare function harnessIntegrationDocMarkdown(): string;

package/dist/content/harnesses-doc.js

@@ -0,0 +1,95 @@
+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
+
+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/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[];

package/dist/content/research-playbooks.js

@@ -0,0 +1,135 @@
+/**
+ * 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 const RESEARCH_PLAYBOOKS = {
+    "repo-scan.md": `# Repo Scan Playbook
+
+## Purpose
+
+Build a grounded map of existing modules and reuse candidates before design lock.
+
+## Steps
+
+1. Identify 3-8 task keywords (feature nouns + action verbs).
+2. Search for likely modules with \`rg\` and \`Glob\` patterns.
+3. List existing implementations or close analogs with file citations.
+4. Flag duplication risk and obvious extension points.
+
+## Output Contract
+
+- Relevant modules: \`path - purpose\`
+- Reuse candidates: \`file:line - why reusable\`
+- Gaps: capabilities not currently present
+
+## Guardrails
+
+- Read-only procedure.
+- Never invent paths or ownership.
+- If scope is too broad, return bounded partial coverage explicitly.
+`,
+    "learnings-lookup.md": `# Learnings Lookup Playbook
+
+## Purpose
+
+Reuse prior project knowledge before choosing a direction.
+
+## Steps
+
+1. Read \`.cclaw/knowledge.jsonl\`.
+2. Match by stage/domain keywords from the current task.
+3. Rank matches by confidence and recency.
+4. Return the top entries verbatim.
+
+## Output Contract
+
+- Matched rules
+- Matched patterns
+- Matched lessons
+- Matched compounds
+- Explicit no-match note when empty
+
+## Guardrails
+
+- Append-only store: do not rewrite history entries.
+- Prefer exact quote over paraphrase.
+`,
+    "framework-docs-lookup.md": `# Framework Docs Lookup Playbook
+
+## Purpose
+
+Anchor design decisions to version-accurate framework/library docs.
+
+## Steps
+
+1. Resolve the actual dependency version from lockfiles/manifests.
+2. Fetch official docs for that version (context7 when available).
+3. Extract APIs used by the task and any migration or deprecation notes.
+
+## Output Contract
+
+- Library + version
+- APIs/signatures touched
+- Relevant breaking changes or gotchas
+- Source links/references
+
+## Guardrails
+
+- No speculative APIs.
+- If docs conflict or are unclear, mark UNKNOWN and escalate.
+`,
+    "best-practices-lookup.md": `# Best Practices Lookup Playbook
+
+## Purpose
+
+Summarize citable domain practices for a narrow design decision.
+
+## Steps
+
+1. Narrow the domain to one concrete sub-problem.
+2. Gather 3-5 authoritative sources.
+3. Produce short practice and anti-pattern lists tied to sources.
+
+## Output Contract
+
+- Recommended practices (\`practice - rationale - source\`)
+- Common traps (\`trap - why it fails - source\`)
+- Decision hooks (1-3 questions to resolve before proceeding)
+
+## Guardrails
+
+- Cite authoritative sources (official docs/standards).
+- State uncertainty explicitly when consensus is weak.
+`,
+    "git-history.md": `# Git History Playbook
+
+## Purpose
+
+Detect churn, regressions, and ownership signals before locking scope/design.
+
+## Steps
+
+1. For impacted paths, inspect recent history and themes:
+   - \`git log --follow -n 20 -- <path>\`
+2. Check ownership hotspots:
+   - \`git blame <path>\`
+   - \`git log --since="<window>" --format="%an" -- <path>\`
+3. Search for regression signals:
+   - \`git log --since="<window>" --grep="revert|regression" -- <path>\`
+
+## Output Contract
+
+- Recent themes
+- Revert/regression signals (with SHAs)
+- Ownership hints
+- Collision risks with ongoing refactors
+
+## Guardrails
+
+- Read-only git usage.
+- If there is no history, say so explicitly.
+`
+};
+export const RESEARCH_PLAYBOOK_FILES = Object.keys(RESEARCH_PLAYBOOKS).sort();

package/dist/content/skills.js

@@ -54,6 +54,22 @@ Mandatory delegations for this stage: ${mandatoryList}.
 Record completion/waiver in \`${delegationLogRel}\` before stage completion.
 `;
 }
+function researchPlaybooksBlock(stage) {
+    const playbooks = stageSchema(stage).researchPlaybooks ?? [];
+    if (playbooks.length === 0)
+        return "";
+    const rows = playbooks
+        .map((playbook) => `- \`${RUNTIME_ROOT}/skills/${playbook}\``)
+        .join("\n");
+    return `## Research Playbooks
+
+Use these in-thread research procedures before locking this stage. They are
+playbooks (not delegated personas), so execute them in the primary agent context
+and record outcomes in the stage artifact when relevant.
+
+${rows}
+`;
+}
 function reviewSectionsBlock(stage) {
     const schema = stageSchema(stage);
     if (schema.reviewSections.length === 0)
@@ -92,6 +108,9 @@ function waveExecutionModeBlock(stage) {
 
 Execute the current dependency wave task-by-task (RED -> GREEN -> REFACTOR).
 Stop on BLOCKED status or when user input is required.
+Apply preamble budget discipline: one preamble per wave, then continue without
+repeating it for each task. Re-emit only when the wave boundary changes or the
+plan changes materially.
 
 Detailed walkthrough:
 \`.cclaw/${STAGE_EXAMPLES_REFERENCE_DIR}/tdd-wave-walkthrough.md\`
@@ -313,6 +332,7 @@ ${schema.requiredContext.length > 0 ? schema.requiredContext.map((item) => `- ${
 
 ${contextLoadingBlock(stage)}
 ${autoSubagentDispatchBlock(stage)}
+${researchPlaybooksBlock(stage)}
 
 ## Outputs
 ${schema.outputs.map((item) => `- ${item}`).join("\n")}

package/dist/content/stage-schema.d.ts

@@ -33,7 +33,7 @@ export interface ArtifactValidation {
     validationRule: string;
 }
 export interface StageAutoSubagentDispatch {
-    agent: "planner" | "spec-reviewer" | "code-reviewer" | "security-reviewer" | "test-author" | "doc-updater" | "repo-research-analyst" | "learnings-researcher" | "framework-docs-researcher" | "best-practices-researcher" | "git-history-analyzer";
+    agent: "planner" | "reviewer" | "security-reviewer" | "test-author" | "doc-updater";
     /**
      * - `mandatory` — must be dispatched (or explicitly waived) before stage transition.
      * - `proactive` — should be dispatched automatically when context matches `when`.
@@ -81,6 +81,8 @@ export interface StageSchema {
     requiredEvidence: string[];
     inputs: string[];
     requiredContext: string[];
+    /** In-thread research procedures for this stage (`.cclaw/skills/research/*.md`). */
+    researchPlaybooks?: string[];
     outputs: string[];
     blockers: string[];
     exitCriteria: string[];