cclaw-cli 0.11.0 → 0.12.0

package/dist/content/stage-schema.js

@@ -190,6 +190,10 @@ const BRAINSTORM = {
         "current behavior of affected area",
         "business and delivery constraints"
     ],
+    researchPlaybooks: [
+        "research/repo-scan.md",
+        "research/learnings-lookup.md"
+    ],
     outputs: [
         "approved design direction",
         "alternatives with trade-offs",
@@ -339,6 +343,9 @@ const SCOPE = {
         "existing capabilities and reusable components",
         "delivery deadlines and risk tolerance"
     ],
+    researchPlaybooks: [
+        "research/git-history.md"
+    ],
     outputs: ["scope mode decision", "scope contract", "discretion areas list", "deferred scope list", "scope summary", "scope completion dashboard"],
     blockers: [
         "scope mode not selected",
@@ -553,6 +560,10 @@ const DESIGN = {
         "operational constraints",
         "security and reliability expectations"
     ],
+    researchPlaybooks: [
+        "research/framework-docs-lookup.md",
+        "research/best-practices-lookup.md"
+    ],
     outputs: [
         "architecture lock",
         "risk and failure map",
@@ -1266,7 +1277,7 @@ const REVIEW = {
     checklist: [
         "Diff Scope — Run `git diff` against base branch. If no diff, exit early with APPROVED (no changes to review). Scope the review to changed files unless blast-radius analysis requires wider inspection.",
         "Change-Size Check — ~100 lines = normal. ~300 lines = consider splitting. ~1000+ lines = strongly recommend stacked PRs. Flag large diffs to the user.",
-        "Adversarial Trigger Check — compute changed-line count (`git diff --shortstat <base>..HEAD`), files-touched count, and whether trust boundaries changed (auth/secrets/external inputs/permissions). If `lines > 100` OR `files > 10` OR `trust boundary changed`, **dispatch a SECOND code-reviewer agent with the `adversarial-review` skill loaded** and reconcile its findings into the review army (treat the conditional dispatch as mandatory whenever the trigger holds; record the trigger that fired in the dashboard).",
+        "Adversarial Trigger Check — compute changed-line count (`git diff --shortstat <base>..HEAD`), files-touched count, and whether trust boundaries changed (auth/secrets/external inputs/permissions). If `lines > 100` OR `files > 10` OR `trust boundary changed`, **dispatch a SECOND reviewer agent with the `adversarial-review` skill loaded** and reconcile its findings into the review army (treat the conditional dispatch as mandatory whenever the trigger holds; record the trigger that fired in the dashboard).",
         "Load upstream evidence — read TDD artifact (RED + GREEN + REFACTOR), spec, and plan. Verify evidence chain is unbroken.",
         "Layer 1: Spec Compliance — check every acceptance criterion against implementation. Verdict: pass/fail per criterion.",
         "Layer 2a: Correctness — logic errors, race conditions, boundary violations, null handling.",
@@ -1642,20 +1653,6 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "When request is ambiguous, multi-surface, or spans multiple modules.",
             purpose: "Map scope and alternatives before direction lock.",
             requiresUserGate: false
-        },
-        {
-            agent: "repo-research-analyst",
-            mode: "proactive",
-            when: "When the user's idea touches an unfamiliar module, stack, or integration surface.",
-            purpose: "Parallel fan-out: summarise existing code paths, tech stack, and similar features already present — feeds the alternatives list.",
-            requiresUserGate: false
-        },
-        {
-            agent: "learnings-researcher",
-            mode: "proactive",
-            when: "On every non-trivial brainstorm where `.cclaw/knowledge.jsonl` has entries.",
-            purpose: "Surface prior learnings and anti-patterns that apply to the current task before direction lock.",
-            requiresUserGate: false
         }
     ],
     scope: [
@@ -1665,13 +1662,6 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "Always during scope shaping.",
             purpose: "Challenge premise, map alternatives, and produce explicit in/out contract.",
             requiresUserGate: false
-        },
-        {
-            agent: "git-history-analyzer",
-            mode: "proactive",
-            when: "When scope touches modules with churn, recent regressions, or unclear ownership.",
-            purpose: "Read recent commits, PRs, and issue references for the affected paths before scope lock.",
-            requiresUserGate: false
         }
     ],
     design: [
@@ -1688,20 +1678,6 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "When trust boundaries, auth, secrets, or external inputs are involved.",
             purpose: "Catch design-level security risks before implementation.",
             requiresUserGate: false
-        },
-        {
-            agent: "framework-docs-researcher",
-            mode: "proactive",
-            when: "When a specific framework/library version is detected and a non-trivial API is in play.",
-            purpose: "Retrieve version-specific docs + migration notes so the design does not rely on stale training priors.",
-            requiresUserGate: false
-        },
-        {
-            agent: "best-practices-researcher",
-            mode: "conditional",
-            when: "When the user flags a quality axis (performance, accessibility, reliability) as primary.",
-            purpose: "Pull domain best-practices and contrast them with the current design choice.",
-            requiresUserGate: false
         }
     ],
     spec: [
@@ -1713,7 +1689,7 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             requiresUserGate: false
         },
         {
-            agent: "spec-reviewer",
+            agent: "reviewer",
             mode: "proactive",
             when: "When acceptance criteria and edge cases are drafted and need independent validation before plan stage.",
             purpose: "Independent review of spec against measurability, testability, and completeness before locking the contract for plan.",
@@ -1747,17 +1723,10 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
     ],
     review: [
         {
-            agent: "spec-reviewer",
+            agent: "reviewer",
             mode: "mandatory",
             when: "Always in review stage.",
-            purpose: "Verify implementation against acceptance criteria with file evidence.",
-            requiresUserGate: false
-        },
-        {
-            agent: "code-reviewer",
-            mode: "mandatory",
-            when: "Always in review stage.",
-            purpose: "Assess correctness, maintainability, architecture, and ship risk.",
+            purpose: "Run spec compliance and code-quality passes with file evidence.",
             requiresUserGate: false
         },
         {
@@ -1769,10 +1738,10 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             skill: "security-audit"
         },
         {
-            agent: "code-reviewer",
+            agent: "reviewer",
             mode: "conditional",
             condition: "diff_lines_gt:100||files_touched_gt:10||trust_boundary_changed",
-            when: "When the diff exceeds 100 changed lines, touches more than 10 files, or modifies trust boundaries — dispatch a SECOND, independent code-reviewer with the adversarial-review skill loaded so the review army has at least two voices on a high-blast-radius change.",
+            when: "When the diff exceeds 100 changed lines, touches more than 10 files, or modifies trust boundaries — dispatch a SECOND, independent reviewer with the adversarial-review skill loaded so the review army has at least two voices on a high-blast-radius change.",
             purpose: "Adversarial second-opinion review on large or trust-sensitive diffs. The second reviewer treats the implementation as hostile and tries to break it (hostile-user, future-maintainer, competitor lenses) instead of sympathetically explaining it.",
             requiresUserGate: false,
             skill: "adversarial-review"
@@ -1787,10 +1756,10 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             requiresUserGate: false
         },
         {
-            agent: "code-reviewer",
+            agent: "security-reviewer",
             mode: "proactive",
-            when: "When release involves broad blast radius or unresolved concerns.",
-            purpose: "Provide final integration-scale quality pass.",
+            when: "When release involves broad blast radius, trust-boundary movement, or unresolved security concerns.",
+            purpose: "Provide final exploitability check before release finalization.",
             requiresUserGate: false
         }
     ]

package/dist/content/subagents.d.ts

@@ -7,7 +7,7 @@ export declare function subagentDrivenDevSkill(): string;
 export declare function parallelAgentsSkill(): string;
 /**
  * Returns markdown fragments augmenting each specialist persona with Task tool
- * delegation guidance. Combine with the existing `body` field from `agents.ts`.
+ * delegation guidance. Combine with the existing `body` field from `core-agents.ts`.
  */
 export declare function enhancedAgentBody(agentName: string): string;
 export declare function subagentsAgentsMdBlock(): string;

package/dist/content/subagents.js

@@ -5,16 +5,10 @@
  */
 const SUBAGENT_AGENT_NAMES = [
     "planner",
-    "spec-reviewer",
-    "code-reviewer",
+    "reviewer",
     "security-reviewer",
     "test-author",
-    "doc-updater",
-    "repo-research-analyst",
-    "learnings-researcher",
-    "framework-docs-researcher",
-    "best-practices-researcher",
-    "git-history-analyzer",
+    "doc-updater"
 ];
 export function subagentDrivenDevSkill() {
     return `---
@@ -40,7 +34,7 @@ For cclaw flow stages, machine-only specialist work should auto-dispatch without
 
 - **design/plan:** planner
 - **tdd:** test-author
-- **review:** spec-reviewer + code-reviewer + security-reviewer (security-reviewer is always mandatory; produce an explicit no-change attestation when no trust boundaries moved)
+- **review:** reviewer + security-reviewer (security-reviewer is always mandatory; produce an explicit no-change attestation when no trust boundaries moved)
 - **ship:** doc-updater
 
 Human input remains mandatory only at explicit approval gates (plan approval, user challenge resolution, release finalization mode).
@@ -69,8 +63,8 @@ If delegation tooling is unavailable in the active harness, run the same control
 | Tier | Use for | Example agents |
 |---|---|---|
 | \`deep\` | one heavy reasoning pass per stage (planner, final reconciliation) | planner |
-| \`balanced\` | spec compliance + code/security review with enough context | spec-reviewer, code-reviewer, security-reviewer, test-author |
-| \`fast\` | read-only research / narrow machine checks / docs updates — safe to fan out | repo-research-analyst, learnings-researcher, framework-docs-researcher, best-practices-researcher, git-history-analyzer, doc-updater |
+| \`balanced\` | spec compliance + code/security review with enough context | reviewer, security-reviewer, test-author |
+| \`fast\` | bounded maintenance updates and doc hygiene | doc-updater |
 
 **Routing rules:**
 - At most ONE \`deep\` agent per stage (planner OR final reconciliation, not both).
@@ -84,14 +78,14 @@ Concrete per-stage rules so the controller does not have to guess which tier fit
 
 | Stage | Deep slot | Balanced slot(s) | Fast fan-out | Trigger to escalate |
 |---|---|---|---|---|
-| brainstorm | planner (only if ambiguity spans >1 module) | — | repo-research-analyst · learnings-researcher (2 in parallel) | promote to \`balanced\` spec-reviewer once direction locks |
-| scope | planner (always) | — | git-history-analyzer (if churn / recent regression on the surface) | promote to \`balanced\` planner if scope touches external contracts |
-| design | planner (always) | security-reviewer (if trust boundary touched) | framework-docs-researcher · best-practices-researcher (up to 2 in parallel) | escalate one specialist to \`deep\` only if a failure mode is Critical-severity |
-| spec | — | spec-reviewer (if spec > 200 lines or multiple ACs) | — | escalate to \`deep\` only for spec ↔ design contradictions |
+| brainstorm | planner (only if ambiguity spans >1 module) | — | run in-thread research playbooks | promote to \`balanced\` reviewer once direction locks |
+| scope | planner (always) | — | run \`research/git-history.md\` in-thread when churn is high | promote to \`balanced\` planner if scope touches external contracts |
+| design | planner (always) | security-reviewer (if trust boundary touched) | run \`research/framework-docs-lookup.md\` + \`research/best-practices-lookup.md\` in-thread | escalate one specialist to \`deep\` only if a failure mode is Critical-severity |
+| spec | — | reviewer (if spec > 200 lines or multiple ACs) | — | escalate to \`deep\` only for spec ↔ design contradictions |
 | plan | planner (solo, always) | — | — | never fan out at plan stage; one owner for dependency graph |
-| tdd | — | test-author (each slice) · code-reviewer (slice-local) | doc-updater (API surface changes) | escalate to \`deep\` only when a RED test cannot be expressed (design leak) |
-| review | — | spec-reviewer · code-reviewer · security-reviewer (all mandatory) | doc-updater + framework-docs-researcher for narrow lookups | escalate a \`balanced\` reviewer to \`deep\` only when two reviewers disagree on severity |
-| ship | — | — | doc-updater (changelog/migration notes) | escalate to \`balanced\` code-reviewer only if preflight finds a regression |
+| tdd | — | test-author (each slice) · reviewer (slice-local) | doc-updater (API surface changes) | escalate to \`deep\` only when a RED test cannot be expressed (design leak) |
+| review | — | reviewer · security-reviewer (both mandatory) | doc-updater for release-note drift checks | escalate a \`balanced\` reviewer to \`deep\` only when two reviewers disagree on severity |
+| ship | — | security-reviewer (if blast radius is high) | doc-updater (changelog/migration notes) | escalate to \`balanced\` reviewer only if preflight finds a regression |
 
 **De-escalation rules (avoid over-spending):**
 - If a \`deep\` planner run returns low-uncertainty output (single unambiguous plan), do **not** add a second \`deep\` pass in the same stage.
@@ -121,7 +115,7 @@ If you catch yourself writing “read PLAN.md Task 3” or “implement the next
 2. **For each task sequentially (NEVER parallel implementation subagents — file conflicts):**
    1. **Dispatch implementer subagent** with the **full task text pasted in** (not a file reference).
    2. **Check return status:** \`DONE\` / \`DONE_WITH_CONCERNS\` / \`NEEDS_CONTEXT\` / \`BLOCKED\`
-   3. If \`DONE\`: dispatch **spec-reviewer** subagent to verify actual code matches spec.
+   3. If \`DONE\`: dispatch **reviewer** subagent to verify actual code matches spec and quality expectations.
    4. If spec review **FAIL**: dispatch **fixer subagent** (a **new** agent — not an inline patch from the parent — to avoid context pollution).
    5. Dispatch **code-quality reviewer** (maintainability/PR hygiene).
    6. **Mark task complete** only after concerns are triaged or explicitly accepted with rationale.
@@ -350,7 +344,7 @@ Write a structured reconciliation artifact at \`.cclaw/artifacts/07-review-army.
       "severity": "Critical|Important|Suggestion",
       "confidence": 1,
       "fingerprint": "hash-or-stable-key",
-      "reportedBy": ["spec-reviewer", "code-reviewer"],
+      "reportedBy": ["reviewer", "security-reviewer"],
       "status": "open|accepted|resolved",
       "location": { "file": "path", "line": 123 },
       "recommendation": "..."
@@ -501,7 +495,7 @@ function specReviewerEnhancedBody() {
 
 ## Task Tool Delegation
 
-For spec-compliance audits, use the Task tool with the following **spec-reviewer** payload (fill placeholders in the parent session).
+For review audits, use the Task tool with the following **reviewer** payload (fill placeholders in the parent session).
 
 \`\`\`
 You are a specification compliance reviewer (subagent).
@@ -544,6 +538,9 @@ Output format (mandatory):
 
 `;
 }
+function reviewerEnhancedBody() {
+    return `${specReviewerEnhancedBody()}${codeReviewerEnhancedBody()}`;
+}
 function securityReviewerEnhancedBody() {
     return `
 
@@ -603,7 +600,7 @@ function repoResearchAnalystEnhancedBody() {
 
 ## Task Tool Delegation
 
-Launch **read-only repo exploration** at the start of brainstorm/scope/design so the primary agent plans on a grounded map, not guesses. Run as a \`fast\` tier agent — cheap to fan out alongside learnings-researcher and best-practices-researcher.
+Launch **read-only repo exploration** at the start of brainstorm/scope/design so the primary agent plans on a grounded map, not guesses. Use this as an in-thread research procedure.
 
 \`\`\`
 You are a repo research analyst subagent.
@@ -761,32 +758,20 @@ Tasks:
 }
 /**
  * Returns markdown fragments augmenting each specialist persona with Task tool
- * delegation guidance. Combine with the existing `body` field from `agents.ts`.
+ * delegation guidance. Combine with the existing `body` field from `core-agents.ts`.
  */
 export function enhancedAgentBody(agentName) {
     switch (agentName) {
         case "planner":
             return plannerEnhancedBody();
-        case "spec-reviewer":
-            return specReviewerEnhancedBody();
-        case "code-reviewer":
-            return codeReviewerEnhancedBody();
+        case "reviewer":
+            return reviewerEnhancedBody();
         case "security-reviewer":
             return securityReviewerEnhancedBody();
         case "test-author":
             return testAuthorEnhancedBody();
         case "doc-updater":
             return docUpdaterEnhancedBody();
-        case "repo-research-analyst":
-            return repoResearchAnalystEnhancedBody();
-        case "learnings-researcher":
-            return learningsResearcherEnhancedBody();
-        case "framework-docs-researcher":
-            return frameworkDocsResearcherEnhancedBody();
-        case "best-practices-researcher":
-            return bestPracticesResearcherEnhancedBody();
-        case "git-history-analyzer":
-            return gitHistoryAnalyzerEnhancedBody();
         default:
             return `
 
@@ -809,7 +794,7 @@ Status contract: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED.
 
 - Controller sequentially dispatches **implementer → reviewer** loops per task.
 - HARD-GATE: paste **self-contained task text**; never point subagents at plan files to “discover” scope.
-- **Spec fixers** are **fresh agents** after failed spec reviews — avoids parent-context pollution.
+- **Review fixers** are **fresh agents** after failed review passes — avoids parent-context pollution.
 - **Machine-only flow checks auto-dispatch** by stage (design/plan/tdd/review/ship) without asking the user to trigger each specialist manually.
 
 ### Parallel Agents (\`dispatching-parallel-agents\` skill)

package/dist/content/templates.d.ts

@@ -1,4 +1,4 @@
 export declare const ARTIFACT_TEMPLATES: Record<string, string>;
 export declare const RULEBOOK_MARKDOWN = "# Cclaw Rulebook\n\n## MUST_ALWAYS\n- Follow flow order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship\n- Require explicit user confirmation after plan before TDD\n- Keep evidence artifacts in `.cclaw/artifacts/`\n- Enforce RED before GREEN in TDD\n- Run two-layer review (spec_compliance and code_quality) before ship\n- Validate all inputs before processing \u2014 never trust external data without sanitization\n- Prefer immutable data patterns and pure functions where the language supports them\n- Follow existing repo conventions, patterns, and directory structure \u2014 match the codebase\n- Verify claims with fresh evidence: \"tests pass\" requires running tests in this message\n- Use conventional commits: `type(scope): description` (feat, fix, refactor, test, docs, chore)\n\n## MUST_NEVER\n- Skip RED phase and jump directly to GREEN in TDD\n- Ship with critical review findings\n- Start implementation during /brainstorm\n- Modify generated cclaw files manually when CLI can regenerate them\n- Commit `.cclaw/` or generated shim files\n- Expose secrets, tokens, API keys, or absolute system paths in agent output\n- Duplicate existing functionality without explicit justification \u2014 search before building\n- Bypass security checks, linting hooks, or type checking to \"move faster\"\n- Claim success (\"Done,\" \"All good,\" \"Tests pass\") without running verification in this message\n- Make changes outside the blast radius of the current task without user consent\n\n## DELEGATION\nWhen a task requires specialist knowledge (security audit, performance profiling, database review),\ndelegate to a specialized agent or skill if the harness supports it. The primary agent should:\n1. Identify the specialist domain\n2. Provide focused context (relevant files, the specific concern)\n3. Evaluate the specialist output before acting on it \u2014 do not blindly apply recommendations\n";
-export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n- Follow stage order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship.\n- Read `.cclaw/state/flow-state.json` before acting; continue from current stage when active.\n- Use `/cc-next` only after required gates pass; never bypass explicit pause/approval rules.\n- Keep evidence in `.cclaw/artifacts/`; archive completed feature artifacts only via `cclaw archive`.\n- For machine-only checks in design/plan/tdd/review/ship, dispatch required specialists automatically when tooling supports it.\n- Ask for user input only at explicit approval gates (scope mode, plan approval, user challenge resolution, ship finalization).\n- Treat `.cclaw/skills/using-cclaw/SKILL.md` as routing source of truth; load contextual utility skills only when their triggers apply.\n";
+export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n## Activation Rule\n\nBefore responding to coding work:\n1. Read `.cclaw/state/flow-state.json`.\n2. Start with `/cc` or continue with `/cc-next`.\n3. If no software-stage flow applies, respond normally.\n\n## Stage Order\n\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nTrack-specific skips are allowed only when `flow-state.track` + `skippedStages` explicitly say so.\n\n## Task Classification\n\n| Class | Route |\n|---|---|\n| non-trivial software work | `/cc <idea>` |\n| trivial software fix | `/cc <idea>` (quick or medium track) |\n| bugfix with repro | `/cc <idea>` and enforce RED-first in tdd |\n| pure question / non-software | direct answer (no stage flow) |\n\n## Command Surface\n\n- `/cc` = entry and resume.\n- `/cc-next` = only progression path.\n- `/cc-learn` = knowledge capture and recall.\n\n## Verification Discipline\n\n- No completion claim without fresh command evidence in this turn.\n- Do not mark gates passed from memory.\n- Keep evidence in `.cclaw/artifacts/`; archive only via `cclaw archive`.\n\n## Delegation And Approvals\n\n- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.\n- Ask for user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization).\n- If harness capabilities are partial, record waiver reasons in delegation logs.\n\n## Routing Source Of Truth\n\n- Primary router: `.cclaw/skills/using-cclaw/SKILL.md`.\n- Protocols: `.cclaw/references/protocols/*.md`.\n- Preamble budget: `.cclaw/references/protocols/ethos.md`.\n";
 export declare function buildRulesJson(): Record<string, unknown>;

package/dist/content/templates.js

@@ -386,11 +386,11 @@ Execution rule: complete and verify each wave before starting the next wave.
 
 | Pass | Status | Completed at (UTC) | Reviewer / source | Commit at review | Drift vs HEAD |
 |---|---|---|---|---|---|
-| Layer 1 — spec compliance | pass / fail / pending | <ISO 8601> | spec-reviewer | <short sha> | <files changed since> |
-| Layer 2 — correctness | pass / fail / pending | <ISO 8601> | code-reviewer | <short sha> | <files changed since> |
+| Layer 1 — spec compliance | pass / fail / pending | <ISO 8601> | reviewer | <short sha> | <files changed since> |
+| Layer 2 — correctness | pass / fail / pending | <ISO 8601> | reviewer | <short sha> | <files changed since> |
 | Layer 2 — security | pass / fail / pending | <ISO 8601> | security-reviewer | <short sha> | <files changed since> |
-| Layer 2 — performance | pass / fail / pending | <ISO 8601> | code-reviewer | <short sha> | <files changed since> |
-| Layer 2 — architecture | pass / fail / pending | <ISO 8601> | code-reviewer | <short sha> | <files changed since> |
+| Layer 2 — performance | pass / fail / pending | <ISO 8601> | reviewer | <short sha> | <files changed since> |
+| Layer 2 — architecture | pass / fail / pending | <ISO 8601> | reviewer | <short sha> | <files changed since> |
 | Adversarial review | pass / fail / n/a | <ISO 8601 or —> | adversarial-review skill | <short sha or —> | <drift or —> |
 | Review army schema valid | pass / fail | <ISO 8601> | jsonschema | <short sha> | n/a |
 
@@ -531,13 +531,51 @@ alwaysApply: true
 
 # Cclaw Workflow Guardrails
 
-- Follow stage order: brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship.
-- Read \`.cclaw/state/flow-state.json\` before acting; continue from current stage when active.
-- Use \`/cc-next\` only after required gates pass; never bypass explicit pause/approval rules.
-- Keep evidence in \`.cclaw/artifacts/\`; archive completed feature artifacts only via \`cclaw archive\`.
-- For machine-only checks in design/plan/tdd/review/ship, dispatch required specialists automatically when tooling supports it.
-- Ask for user input only at explicit approval gates (scope mode, plan approval, user challenge resolution, ship finalization).
-- Treat \`.cclaw/skills/using-cclaw/SKILL.md\` as routing source of truth; load contextual utility skills only when their triggers apply.
+## Activation Rule
+
+Before responding to coding work:
+1. Read \`.cclaw/state/flow-state.json\`.
+2. Start with \`/cc\` or continue with \`/cc-next\`.
+3. If no software-stage flow applies, respond normally.
+
+## Stage Order
+
+\`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship\`
+
+Track-specific skips are allowed only when \`flow-state.track\` + \`skippedStages\` explicitly say so.
+
+## Task Classification
+
+| Class | Route |
+|---|---|
+| non-trivial software work | \`/cc <idea>\` |
+| trivial software fix | \`/cc <idea>\` (quick or medium track) |
+| bugfix with repro | \`/cc <idea>\` and enforce RED-first in tdd |
+| pure question / non-software | direct answer (no stage flow) |
+
+## Command Surface
+
+- \`/cc\` = entry and resume.
+- \`/cc-next\` = only progression path.
+- \`/cc-learn\` = knowledge capture and recall.
+
+## Verification Discipline
+
+- No completion claim without fresh command evidence in this turn.
+- Do not mark gates passed from memory.
+- Keep evidence in \`.cclaw/artifacts/\`; archive only via \`cclaw archive\`.
+
+## Delegation And Approvals
+
+- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.
+- Ask for user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization).
+- If harness capabilities are partial, record waiver reasons in delegation logs.
+
+## Routing Source Of Truth
+
+- Primary router: \`.cclaw/skills/using-cclaw/SKILL.md\`.
+- Protocols: \`.cclaw/references/protocols/*.md\`.
+- Preamble budget: \`.cclaw/references/protocols/ethos.md\`.
 `;
 export function buildRulesJson() {
     return {

package/dist/delegation.d.ts

@@ -28,5 +28,6 @@ export declare function checkMandatoryDelegations(projectRoot: string, stage: Fl
     satisfied: boolean;
     missing: string[];
     waived: string[];
+    autoWaived: string[];
     staleIgnored: string[];
 }>;

package/dist/delegation.js

@@ -1,7 +1,9 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
+import { readConfig } from "./config.js";
 import { exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
+import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 import { readFlowState } from "./runs.js";
 import { stageSchema } from "./content/stage-schema.js";
 function delegationLogPath(projectRoot) {
@@ -84,11 +86,34 @@ export async function checkMandatoryDelegations(projectRoot, stage) {
         .map((e) => `${e.agent}(runId=${e.runId ?? "unknown"})`);
     const missing = [];
     const waived = [];
+    const autoWaived = [];
+    const config = await readConfig(projectRoot).catch(() => null);
+    const harnesses = config?.harnesses ?? [];
+    const nativeDelegationUnavailable = harnesses.length > 0 &&
+        harnesses.every((harness) => HARNESS_ADAPTERS[harness].capabilities.nativeSubagentDispatch === "none");
     for (const agent of mandatory) {
         const rows = forRun.filter((e) => e.agent === agent);
         const ok = rows.some((e) => e.status === "completed" || e.status === "waived");
         if (!ok) {
-            missing.push(agent);
+            if (nativeDelegationUnavailable) {
+                const existingHarnessWaiver = rows.some((e) => e.status === "waived" && e.waiverReason === "harness_limitation");
+                if (!existingHarnessWaiver) {
+                    await appendDelegation(projectRoot, {
+                        stage,
+                        agent,
+                        mode: "mandatory",
+                        status: "waived",
+                        waiverReason: "harness_limitation",
+                        ts: new Date().toISOString(),
+                        runId: activeRunId
+                    });
+                }
+                waived.push(agent);
+                autoWaived.push(agent);
+            }
+            else {
+                missing.push(agent);
+            }
         }
         else if (rows.some((e) => e.status === "waived")) {
             waived.push(agent);
@@ -98,6 +123,7 @@ export async function checkMandatoryDelegations(projectRoot, stage) {
         satisfied: missing.length === 0,
         missing,
         waived,
+        autoWaived,
         staleIgnored
     };
 }

package/dist/doctor-registry.d.ts

@@ -0,0 +1,8 @@
+export type DoctorSeverity = "error" | "warning" | "info";
+export interface DoctorCheckMetadata {
+    severity: DoctorSeverity;
+    summary: string;
+    fix: string;
+    docRef?: string;
+}
+export declare function doctorCheckMetadata(checkName: string): DoctorCheckMetadata;

package/dist/doctor-registry.js

@@ -0,0 +1,127 @@
+import { DOCTOR_REFERENCE_DIR } from "./content/doctor-references.js";
+function ref(fileName) {
+    return `${DOCTOR_REFERENCE_DIR}/${fileName}`;
+}
+const RULES = [
+    {
+        test: /^gates:reconcile:writeback$/,
+        metadata: {
+            severity: "info",
+            summary: "Gate reconciliation status update.",
+            fix: "No action required unless subsequent gate checks fail.",
+            docRef: ref("state-and-gates.md")
+        }
+    },
+    {
+        test: /^warning:/,
+        metadata: {
+            severity: "warning",
+            summary: "Advisory signal; runtime can continue with caution.",
+            fix: "Address when possible to prevent future drift or degraded behavior.",
+            docRef: ref("README.md")
+        }
+    },
+    {
+        test: /^skill:.*:(max_lines|min_lines|canonical_sections)$/,
+        metadata: {
+            severity: "warning",
+            summary: "Stage skill quality guardrail check.",
+            fix: "Tune generated stage skill content and re-run `cclaw sync`.",
+            docRef: ref("runtime-layout.md")
+        }
+    },
+    {
+        test: /^capability:runtime:json_parser$/,
+        metadata: {
+            severity: "warning",
+            summary: "Optional JSON fallback parser availability.",
+            fix: "Install at least one of `python3` or `jq` for resilient fallback parsing.",
+            docRef: ref("tooling-capabilities.md")
+        }
+    },
+    {
+        test: /^capability:required:/,
+        metadata: {
+            severity: "error",
+            summary: "Required runtime tooling availability check.",
+            fix: "Install the missing required tool and re-run `cclaw doctor`.",
+            docRef: ref("tooling-capabilities.md")
+        }
+    },
+    {
+        test: /^(dir:|command:|utility_command:|skill:|utility_skill:|agent:|harness_tool_ref:|harness_ref:|stage_examples_ref:|doctor_ref:)/,
+        metadata: {
+            severity: "error",
+            summary: "Generated runtime surface presence check.",
+            fix: "Run `cclaw sync` to regenerate runtime files, then re-run doctor.",
+            docRef: ref("runtime-layout.md")
+        }
+    },
+    {
+        test: /^(hook:|lifecycle:|git_hooks:)/,
+        metadata: {
+            severity: "error",
+            summary: "Hook wiring and lifecycle integration check.",
+            fix: "Repair hook/plugin wiring (usually via `cclaw sync`) and validate harness config.",
+            docRef: ref("hooks-and-lifecycle.md")
+        }
+    },
+    {
+        test: /^(shim:|agents:cclaw_block|rules:cursor:workflow)/,
+        metadata: {
+            severity: "error",
+            summary: "Harness shim and routing file consistency check.",
+            fix: "Regenerate harness adapters via `cclaw sync`; confirm enabled harness list.",
+            docRef: ref("harness-and-routing.md")
+        }
+    },
+    {
+        test: /^(flow_state:|state:|contexts:|gates:)/,
+        metadata: {
+            severity: "error",
+            summary: "Flow state and gate evidence consistency check.",
+            fix: "Repair flow-state artifacts and gate evidence, then run `cclaw doctor --reconcile-gates`.",
+            docRef: ref("state-and-gates.md")
+        }
+    },
+    {
+        test: /^delegation:/,
+        metadata: {
+            severity: "error",
+            summary: "Mandatory delegation completion check.",
+            fix: "Complete or explicitly waive missing mandatory delegations in delegation log.",
+            docRef: ref("delegation-and-preamble.md")
+        }
+    },
+    {
+        test: /^trace:/,
+        metadata: {
+            severity: "error",
+            summary: "Cross-artifact traceability integrity check.",
+            fix: "Restore criterion/task/test ID mappings across spec, plan, and tdd artifacts.",
+            docRef: ref("traceability.md")
+        }
+    },
+    {
+        test: /^(config:|rules:policy_schema|language_rule_pack:|gitignore:|git:)/,
+        metadata: {
+            severity: "error",
+            summary: "Config or policy schema consistency check.",
+            fix: "Fix config/rules drift, then run `cclaw sync` and re-run doctor.",
+            docRef: ref("config-and-policy.md")
+        }
+    }
+];
+export function doctorCheckMetadata(checkName) {
+    for (const rule of RULES) {
+        if (rule.test.test(checkName)) {
+            return { ...rule.metadata };
+        }
+    }
+    return {
+        severity: "error",
+        summary: "Doctor runtime integrity check.",
+        fix: "Inspect check details, apply the suggested remediation, and re-run `cclaw doctor`.",
+        docRef: ref("README.md")
+    };
+}

package/dist/doctor.d.ts

@@ -1,7 +1,12 @@
+import type { DoctorSeverity } from "./doctor-registry.js";
 export interface DoctorCheck {
     name: string;
     ok: boolean;
     details: string;
+    severity: DoctorSeverity;
+    summary: string;
+    fix: string;
+    docRef?: string;
 }
 export interface DoctorOptions {
     /** When true, normalize current-stage gate catalog and persist reconciliation before checks. */