cclaw-cli 0.7.1 → 0.9.0

package/dist/content/subagents.js

@@ -10,6 +10,11 @@ const SUBAGENT_AGENT_NAMES = [
     "security-reviewer",
     "test-author",
     "doc-updater",
+    "repo-research-analyst",
+    "learnings-researcher",
+    "framework-docs-researcher",
+    "best-practices-researcher",
+    "git-history-analyzer",
 ];
 export function subagentDrivenDevSkill() {
     return `---
@@ -59,6 +64,20 @@ If delegation tooling is unavailable in the active harness, run the same control
 - **Use a more capable model** for high-ambiguity or high-risk analysis (security review, architecture conflicts, spec contradiction resolution).
 - During review-heavy stages, prefer **mixed routing**: faster first-pass triage + escalate only high-severity/low-confidence findings.
 
+### Cost-aware routing (tier table)
+
+| 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 |
+
+**Routing rules:**
+- At most ONE \`deep\` agent per stage (planner OR final reconciliation, not both).
+- \`balanced\` agents are default for review-stage specialists.
+- \`fast\` agents are the only tier you should fan out in parallel (3-5 at a time is fine).
+- Never escalate a \`fast\` agent's output directly to ship decisions — always have a \`balanced\` reviewer consume the evidence first.
+
 ## HARD-GATE
 
 **Never dispatch a subagent without a concrete, self-contained task description pasted into the prompt. Do not pass file references the subagent must read to understand its task.**
@@ -556,6 +575,146 @@ Process (mandatory):
    - Report: FILES_EDITED, GREEN_COMMAND_RUN, REFACTOR_NOTES, STATUS: DONE|BLOCKED.
 \`\`\`
 
+`;
+}
+function repoResearchAnalystEnhancedBody() {
+    return `
+
+## 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.
+
+\`\`\`
+You are a repo research analyst subagent.
+
+TASK DOMAIN: {1-sentence description of the feature/fix/refactor being planned}
+REPO HINTS: {known directories, module names, patterns the primary agent already knows}
+OUT OF SCOPE: {paths not to read (large vendor dirs, generated code)}
+
+Deliverables:
+- Relevant modules: list of \`path — purpose\` (cite file:line on ambiguous claims).
+- Reuse candidates: list of \`file:line — why this absorbs the change\`.
+- Ownership hints: CODEOWNERS / README / comment signals.
+- Gaps: capabilities NOT yet present that the task would need.
+
+Rules:
+- Read-only. Do NOT edit files.
+- Cite file:line for every claim; never invent paths.
+- If the scope is too large to fully explore, say so and bound your search.
+\`\`\`
+
+`;
+}
+function learningsResearcherEnhancedBody() {
+    return `
+
+## Task Tool Delegation
+
+Dispatch before any non-trivial stage to stream \`.cclaw/knowledge.jsonl\` and surface prior learnings. Cheap \`fast\` tier — fan out with other research agents.
+
+\`\`\`
+You are a learnings researcher subagent.
+
+TASK DESCRIPTION: {verbatim prompt + current stage}
+DOMAIN HINTS: {keywords from Task Classification / Origin Docs}
+
+Deliverables:
+- Matched rules: list of \`trigger → action (confidence)\`.
+- Matched patterns: list of \`trigger → action (confidence)\`.
+- Matched lessons: list of \`trigger → action (confidence)\`.
+- Matched compounds: list of \`trigger → action (confidence)\`.
+- No-match note (if nothing relevant exists).
+
+Rules:
+- Read-only; NEVER rewrite or delete entries.
+- Return at most 10 entries, ranked by confidence then recency.
+- Quote the entries verbatim — do NOT paraphrase.
+\`\`\`
+
+`;
+}
+function frameworkDocsResearcherEnhancedBody() {
+    return `
+
+## Task Tool Delegation
+
+Use for any task that depends on a specific framework/library/SDK/CLI. Prefer context7 MCP when available for version-accurate docs; otherwise WebSearch/WebFetch official sources.
+
+\`\`\`
+You are a framework documentation researcher subagent.
+
+LIBRARY + VERSION: {name + resolved version from lockfile / pyproject / go.mod / Cargo.toml / pom.xml / build.gradle}
+TASK USAGE: {which APIs the task will actually call}
+CONTEXT7: {"available" | "not available"}
+
+Deliverables:
+- Key APIs: list of signatures the task will touch.
+- Breaking changes since the last major release relevant to the task.
+- Gotchas: deprecated paths, version-gated flags, platform caveats.
+- Source: URL(s) or MCP reference used.
+
+Rules:
+- Never invent APIs. Prefer silence + UNKNOWN over speculation.
+- Tie every statement to an authoritative source; avoid blog posts when official docs exist.
+\`\`\`
+
+`;
+}
+function bestPracticesResearcherEnhancedBody() {
+    return `
+
+## Task Tool Delegation
+
+Use when the task touches a well-known domain (auth, caching, rate limiting, observability, accessibility, etc.) and the primary agent needs a short, citable best-practice summary.
+
+\`\`\`
+You are a best-practices researcher subagent.
+
+DOMAIN: {one word, e.g. auth, caching, rate-limiting, a11y, observability, retries}
+SUB-PROBLEM: {narrow one-sentence statement of what the task is actually deciding}
+
+Deliverables:
+- Recommended practices: 5-8 entries of \`practice — rationale — source\`.
+- Common traps / anti-patterns: list of \`trap — why it fails — source\`.
+- Decision hooks: 1-3 explicit questions the primary agent must answer.
+
+Rules:
+- Cite 3-5 authoritative sources (official docs, IETF/W3C/OWASP, well-known standards).
+- If the domain has no authoritative answer, say so; do NOT substitute opinion.
+\`\`\`
+
+`;
+}
+function gitHistoryAnalyzerEnhancedBody() {
+    return `
+
+## Task Tool Delegation
+
+Use when the task touches existing code, so the primary agent can see prior attempts, reverts, and owners before proposing changes.
+
+\`\`\`
+You are a git history analyzer subagent.
+
+IMPACTED PATHS: {list of files/directories the task plans to touch}
+WINDOW: {default 90 days; adjust only if explicitly needed}
+
+Commands to run (read-only):
+- git log --follow -n 20 -- <path>
+- git blame <path>
+- git log --since="<window>" --grep="revert|regression" -- <path>
+- git log --since="<window>" --format="%an" -- <path> | sort | uniq -c | sort -nr
+
+Deliverables:
+- Recent themes: 3-5 bullets on what changed lately per path.
+- Revert/regression signals: list with commit SHAs.
+- Owners: best-guess from blame + committer frequency.
+- Collision risks: in-flight refactors/migrations visible in log.
+
+Rules:
+- Read-only. Never amend history, never git push.
+- If a path is new (no history), say so explicitly rather than fabricating context.
+\`\`\`
+
 `;
 }
 function docUpdaterEnhancedBody() {
@@ -597,6 +756,16 @@ export function enhancedAgentBody(agentName) {
             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 `
 

package/dist/content/templates.js

@@ -84,6 +84,16 @@ export const ARTIFACT_TEMPLATES = {
   - (HOLD: minimum-change-set hardening)
   - (REDUCE: ruthless cuts, follow-up split)
 
+## Requirements (stable IDs)
+| ID | Requirement (observable outcome) | Priority | Source (origin doc / prompt line) |
+|---|---|---|---|
+| R1 |  | P0 |  |
+
+> Assign \`R1\`, \`R2\`, \`R3\`… once and never renumber. Downstream artifacts
+> (design, spec, plan, review) reference these IDs verbatim. If a requirement
+> is later dropped, keep the row and mark Priority \`DROPPED\`; if a new one is
+> added mid-flow, append with the next free R-number — do NOT reuse numbers.
+
 ## In Scope / Out of Scope
 
 ### In Scope
@@ -203,9 +213,13 @@ export const ARTIFACT_TEMPLATES = {
     "04-spec.md": `# Specification Artifact
 
 ## Acceptance Criteria
-| ID | Criterion (observable/measurable/falsifiable) | Design Decision Ref |
-|---|---|---|
-| AC-1 |  |  |
+| ID | Requirement Ref (R#) | Criterion (observable/measurable/falsifiable) | Design Decision Ref |
+|---|---|---|---|
+| AC-1 | R1 |  |  |
+
+> Every AC must reference at least one \`R#\` from \`02-scope.md\`. ACs are
+> stable (never renumber): dropped ACs stay with Priority \`DROPPED\`; new
+> ones append with the next free \`AC-#\`.
 
 ## Edge Cases
 | Criterion ID | Boundary case | Error case |
@@ -264,9 +278,15 @@ export const ARTIFACT_TEMPLATES = {
 Execution rule: complete and verify each wave before starting the next wave.
 
 ## Task List
-| Task ID | Description | Acceptance criterion | Verification command | Effort |
-|---|---|---|---|---|
-| T-1 |  |  |  |  |
+
+**Rules (apply before writing rows):**
+- Every task fits the **2-5 minute budget**. If \`[~Nm]\` is >5, split the task.
+- **No placeholders.** Forbidden tokens anywhere in this table: \`TODO\`, \`TBD\`, \`FIXME\`, \`<fill-in>\`, \`<your-*-here>\`, \`xxx\`, bare ellipsis. Every file path, test, and verification command must be copy-pasteable as written.
+- If an estimate is genuinely uncertain (new library, unfamiliar subsystem), add a **spike task in wave 0** to de-risk — do NOT hide the uncertainty inside a large estimate.
+
+| Task ID | Description | Acceptance criterion | Verification command | Effort (S/M/L) | Minutes |
+|---|---|---|---|---|---|
+| T-1 |  |  |  |  | [~3m] |
 
 ## Acceptance Mapping
 | Criterion ID | Task IDs |
@@ -283,6 +303,10 @@ Execution rule: complete and verify each wave before starting the next wave.
 |---|---|---|
 |  |  |  |
 
+## No-Placeholder Scan
+- Scanned tokens: \`TODO\`, \`TBD\`, \`FIXME\`, \`<fill-in>\`, \`<your-*-here>\`, \`xxx\`, bare ellipsis in task rows.
+- Hits: 0 (required for WAIT_FOR_CONFIRM to resolve).
+
 ## WAIT_FOR_CONFIRM
 - Status: pending
 - Confirmed by:
@@ -327,6 +351,20 @@ Execution rule: complete and verify each wave before starting the next wave.
 | Code type | Target | Current | Command |
 |---|---|---|---|
 |  |  |  |  |
+
+## Test Pyramid Shape
+> Fill in per slice. Size classes: **Small** = pure logic, no I/O, <50ms; **Medium** = single process boundary (fs, in-memory DB, in-process service); **Large** = multi-process / network / real external service. Default to Small; escalate only when a real boundary must be exercised.
+
+| Slice | # Small | # Medium | # Large | Justification for any Medium/Large |
+|---|---|---|---|---|
+| S-1 |  |  |  |  |
+
+## Prove-It Reproduction (bug-fix slices only)
+> Required whenever the slice is classified as a **bug fix** (task class = \`software-bugfix\`). Must demonstrate the test fails without the fix, passes with the fix, and would fail again if the fix were reverted. Skip this table entirely for non-bugfix slices.
+
+| Slice | Reproduction test | RED-without-fix evidence | GREEN-with-fix evidence | Revert-guard note |
+|---|---|---|---|---|
+| S-1 |  |  |  |  |
 `,
     "07-review.md": `# Review Artifact
 

package/dist/content/utility-skills.d.ts

@@ -16,6 +16,7 @@ export declare function landscapeCheckSkill(): string;
 export declare function knowledgeCurationSkill(): string;
 export declare function securityAuditSkill(): string;
 export declare function adversarialReviewSkill(): string;
+export declare function documentReviewSkill(): string;
 export declare function retrospectiveSkill(): string;
 export declare function languageTypescriptSkill(): string;
 export declare function languagePythonSkill(): string;
@@ -43,5 +44,5 @@ export declare const LANGUAGE_RULE_PACK_GENERATORS: Record<string, () => string>
  * clean them up after the move to `.cclaw/rules/lang/`.
  */
 export declare const LEGACY_LANGUAGE_RULE_PACK_FOLDERS: readonly ["language-typescript", "language-python", "language-go"];
-export declare const UTILITY_SKILL_FOLDERS: readonly ["security", "debugging", "performance", "ci-cd", "docs", "executing-plans", "context-engineering", "source-driven-development", "frontend-accessibility", "landscape-check", "adversarial-review", "security-audit", "knowledge-curation", "retrospective"];
+export declare const UTILITY_SKILL_FOLDERS: readonly ["security", "debugging", "performance", "ci-cd", "docs", "executing-plans", "context-engineering", "source-driven-development", "frontend-accessibility", "landscape-check", "adversarial-review", "security-audit", "knowledge-curation", "retrospective", "document-review"];
 export declare const UTILITY_SKILL_MAP: Record<string, () => string>;

package/dist/content/utility-skills.js

@@ -1069,6 +1069,143 @@ Escalate to the main review-army under the matching severity (Critical / Importa
 - Only playing the hostile-user role and skipping operator + maintainer.
 `;
 }
+export function documentReviewSkill() {
+    return `---
+name: document-review
+description: "Post-artifact scrub pass. Use after writing any cclaw artifact (brainstorm, scope, design, spec, plan, review, ship) and before asking the user for approval — catches placeholders, internal inconsistencies, dangling references, and vague language."
+---
+
+# Document Review
+
+## Quick Start
+
+> 1. Run against the **just-written artifact** before you ask the user to approve it.
+> 2. Walk the five lenses below. For each, produce either a concrete fix or the explicit string "no issues".
+> 3. Apply all fixes yourself in the same artifact — this skill is a scrub, not a checklist for the user.
+
+## HARD-GATE
+
+Do NOT surface an artifact to the user for approval while **any** of the
+following are still present:
+
+- Unresolved placeholders (\`TBD\`, \`TODO\`, \`<fill me>\`, empty table rows
+  that the schema requires).
+- Broken cross-references (e.g. \`AC-12\` in spec when spec table only goes
+  up to \`AC-8\`; \`R3\` referenced in a design decision when scope stops at \`R2\`).
+- Contradictions between sections of the same artifact (e.g. \`In Scope\`
+  says X but \`Acceptance Criteria\` never mentions X).
+- Vague language where the stage requires observable / measurable
+  statements (e.g. "fast", "simple", "seamless", "robust" without a metric).
+- Missing required sections declared by the stage's \`artifactValidation\`.
+
+If any of these remain, fix them first, then re-run this skill; only then
+ask for approval.
+
+## When to Use
+
+- Immediately after writing \`.cclaw/artifacts/01-brainstorm.md\`
+- Immediately after writing \`.cclaw/artifacts/02-scope.md\`
+- Immediately after writing \`.cclaw/artifacts/03-design.md\`
+- Immediately after writing \`.cclaw/artifacts/04-spec.md\`
+- Immediately after writing \`.cclaw/artifacts/05-plan.md\`
+- Immediately after writing \`.cclaw/artifacts/07-review.md\`
+- Immediately after writing \`.cclaw/artifacts/08-ship.md\`
+- Whenever you regenerate an artifact after a Reclassification pass
+
+Do NOT run during \`06-tdd.md\` — the TDD artifact is append-only evidence;
+scrubbing risks destroying RED/GREEN history. Use \`Verification Before
+Completion\` in the TDD skill instead.
+
+## Five Lenses
+
+### 1. Placeholder Scrub
+
+Grep the artifact for: \`TBD\`, \`TODO\`, \`FIXME\`, \`<fill me>\`,
+\`<describe>\`, \`<owner>\`, \`N/A\` inside cells the schema marks as required,
+and empty first-row table cells that the template left blank.
+
+**Output:** each placeholder replaced with real content, or a line added
+explicitly stating "None — <reason>". Never leave a placeholder in a
+required section.
+
+### 2. Cross-Reference Integrity
+
+- Every \`R#\` referenced in this artifact must exist in \`02-scope.md\`.
+- Every \`AC-#\` referenced must exist in \`04-spec.md\`.
+- Every task ID referenced must exist in \`05-plan.md\`.
+- Every file path cited must be the canonical casing used elsewhere.
+- Every ADR / decision reference must resolve to an existing record.
+
+**Output:** broken refs fixed, or flagged with the exact upstream artifact
+that needs updating first.
+
+### 3. Internal Consistency
+
+- \`In Scope\` / \`Out of Scope\` lists do not overlap.
+- Acceptance Criteria match the requirements they claim to verify.
+- Plan tasks cover every AC (no AC left without at least one task).
+- Failure modes listed in design appear in the spec's edge cases.
+- Review verdict matches the evidence (no "Ship" with open Criticals).
+
+**Output:** contradictions resolved by amending whichever side is wrong,
+with a one-line rationale.
+
+### 4. Ambiguity Scan
+
+Flag words that masquerade as decisions:
+
+- "fast", "simple", "robust", "intuitive", "seamless", "scalable",
+  "production-ready", "high quality" — each must be replaced with an
+  observable metric or dropped.
+- "etc.", "and so on", "similar to X" in requirements — enumerate or drop.
+- Passive voice that hides the actor ("will be validated") — name the
+  actor ("the API gateway validates the payload").
+
+**Output:** every flagged term rewritten as observable, or escalated as a
+Decision Protocol question before approval.
+
+### 5. Schema Conformance
+
+Re-verify the artifact against the stage's \`artifactValidation\`:
+
+- Every required section is present with a non-empty body.
+- Tables have the columns the template specifies (no dropped columns).
+- Any "N/A" in a required section carries an inline reason.
+- Required evidence links (test output, diff excerpts) resolve.
+
+**Output:** missing sections added, or escalated as a BLOCKED signal if
+the artifact cannot honestly be completed without more work.
+
+## Output Protocol
+
+After running all five lenses, emit a single one-line summary **before
+asking the user for approval**:
+
+> Document review: 5/5 lenses clean; <N> fixes applied.
+
+If fixes were blocked (e.g. upstream artifact drift), do NOT claim
+"clean" — surface the blocker explicitly and stop.
+
+## Anti-Patterns
+
+- Running this skill as a "polish pass" after the user already approved
+  the artifact — by then it is too late.
+- Treating placeholders as "documentation" ("TBD on rollback — we'll
+  figure it out"). Either decide now or mark it as an explicit BLOCKED.
+- Silently rewriting user-approved content under the guise of "scrubbing".
+- Using this skill as a substitute for the stage's own review sections —
+  it is a **last-mile check**, not a replacement for the stage review.
+
+## Red Flags
+
+- "No issues" on an artifact that still has empty table rows.
+- Cross-reference lens passes but the artifact cites IDs from a stage
+  that has not yet been written.
+- Ambiguity scan finds nothing in a brainstorm / scope artifact (this is
+  implausible — those stages produce narrative by design, and narrative
+  always contains at least one vague phrase worth tightening).
+`;
+}
 export function retrospectiveSkill() {
     return `---
 name: retrospective
@@ -1394,7 +1531,8 @@ export const UTILITY_SKILL_FOLDERS = [
     "adversarial-review",
     "security-audit",
     "knowledge-curation",
-    "retrospective"
+    "retrospective",
+    "document-review"
 ];
 export const UTILITY_SKILL_MAP = {
     security: securityReviewSkill,
@@ -1410,5 +1548,6 @@ export const UTILITY_SKILL_MAP = {
     "adversarial-review": adversarialReviewSkill,
     "security-audit": securityAuditSkill,
     "knowledge-curation": knowledgeCurationSkill,
-    retrospective: retrospectiveSkill
+    retrospective: retrospectiveSkill,
+    "document-review": documentReviewSkill
 };

package/dist/doctor.js

@@ -258,13 +258,90 @@ export async function doctorChecks(projectRoot, options = {}) {
             const skillContent = await fs.readFile(skillPath, "utf8");
             const lineCount = skillContent.split("\n").length;
             const MIN_SKILL_LINES = 110;
+            const MAX_SKILL_LINES = 650;
             checks.push({
                 name: `skill:${stage}:min_lines`,
                 ok: lineCount >= MIN_SKILL_LINES,
                 details: `${skillPath} has ${lineCount} lines (minimum ${MIN_SKILL_LINES})`
             });
+            checks.push({
+                name: `skill:${stage}:max_lines`,
+                ok: lineCount <= MAX_SKILL_LINES,
+                details: `${skillPath} has ${lineCount} lines (soft max ${MAX_SKILL_LINES}; stage skills beyond this drift into unread bloat)`
+            });
+            const canonicalSections = [
+                { id: "frontmatter", pattern: /^---\nname: [\w-]+\ndescription: /m, label: "YAML frontmatter (name + description)" },
+                { id: "hard_gate", pattern: /^## HARD-GATE$/m, label: "## HARD-GATE" },
+                { id: "checklist", pattern: /^## Checklist$/m, label: "## Checklist" },
+                { id: "completion_protocol", pattern: /^## Stage Completion Protocol$/m, label: "## Stage Completion Protocol" },
+                { id: "handoff_menu", pattern: /^### Handoff Menu$/m, label: "### Handoff Menu" },
+                { id: "good_vs_bad", pattern: /Good vs Bad/i, label: "Good vs Bad examples" },
+                { id: "anti_patterns", pattern: /^## Anti-Patterns$/m, label: "## Anti-Patterns" }
+            ];
+            const missingSections = canonicalSections
+                .filter((section) => !section.pattern.test(skillContent))
+                .map((section) => section.label);
+            checks.push({
+                name: `skill:${stage}:canonical_sections`,
+                ok: missingSections.length === 0,
+                details: missingSections.length === 0
+                    ? `${skillPath} contains all canonical sections`
+                    : `${skillPath} missing sections: ${missingSections.join(", ")}`
+            });
         }
     }
+    // Meta-skill health — the using-cclaw routing brain must always contain the
+    // signals that stage skills reference. When one of these drifts, every stage
+    // citation breaks silently.
+    const metaSkillPath = path.join(projectRoot, RUNTIME_ROOT, "skills", "using-cclaw", "SKILL.md");
+    if (await exists(metaSkillPath)) {
+        const metaContent = await fs.readFile(metaSkillPath, "utf8");
+        const requiredSignals = [
+            { id: "instruction_priority", pattern: /Instruction Priority/i, label: "Instruction Priority" },
+            { id: "spawned_detection", pattern: /Spawned Subagent Detection/i, label: "Spawned Subagent Detection" },
+            { id: "shared_decision", pattern: /Shared Decision \+ Tool-Use Protocol/i, label: "Shared Decision + Tool-Use Protocol" },
+            { id: "shared_completion", pattern: /Shared Stage Completion Protocol/i, label: "Shared Stage Completion Protocol" },
+            { id: "escalation_rule", pattern: /Escalation Rule \(3 attempts\)/i, label: "Escalation Rule (3 attempts)" },
+            { id: "invocation_preamble", pattern: /Invocation Preamble/i, label: "Invocation Preamble" },
+            { id: "operational_self_improvement", pattern: /Operational Self-Improvement/i, label: "Operational Self-Improvement" },
+            { id: "engineering_ethos", pattern: /Engineering Ethos/i, label: "Engineering Ethos" },
+            { id: "task_classification", pattern: /Task Classification/i, label: "Task Classification" }
+        ];
+        const missingMeta = requiredSignals
+            .filter((signal) => !signal.pattern.test(metaContent))
+            .map((signal) => signal.label);
+        checks.push({
+            name: "skill:meta:signals",
+            ok: missingMeta.length === 0,
+            details: missingMeta.length === 0
+                ? `${metaSkillPath} contains all required routing signals`
+                : `${metaSkillPath} missing signals: ${missingMeta.join(", ")}`
+        });
+    }
+    // Harness tool-map references (A.1#4) must always be present — stage skills
+    // cite the paths by name.
+    const harnessRefDir = path.join(projectRoot, RUNTIME_ROOT, "references", "harness-tools");
+    const harnessRefFiles = ["README.md", "claude.md", "cursor.md", "opencode.md", "codex.md"];
+    for (const fileName of harnessRefFiles) {
+        const refPath = path.join(harnessRefDir, fileName);
+        checks.push({
+            name: `harness_tool_ref:${fileName.replace(/\.md$/, "")}`,
+            ok: await exists(refPath),
+            details: refPath
+        });
+    }
+    // Per-stage example references (A.2#8, progressive disclosure). Each stage
+    // skill's Examples section points here; the file MUST exist or the pointer
+    // is a dangling link.
+    const stageRefDir = path.join(projectRoot, RUNTIME_ROOT, "references", "stages");
+    for (const stage of COMMAND_FILE_ORDER) {
+        const refPath = path.join(stageRefDir, `${stage}-examples.md`);
+        checks.push({
+            name: `stage_examples_ref:${stage}`,
+            ok: await exists(refPath),
+            details: refPath
+        });
+    }
     checks.push({
         name: "gitignore:required_patterns",
         ok: await gitignoreHasRequiredPatterns(projectRoot),

package/dist/harness-adapters.js

@@ -31,25 +31,55 @@ Before responding to a coding request:
 2. Use \`/cc\` to start or \`/cc-next\` to continue the flow.
 3. If no stage applies, respond normally.
 
+### Task Classification (before \`/cc\`)
+
+| Class | Examples | Route |
+|---|---|---|
+| Software — non-trivial | feature, refactor, migration, integration | \`/cc <idea>\` → stage flow (standard track) |
+| Software — trivial | typo, one-liner, rename, config tweak | \`/cc <idea>\` → quick track |
+| Software — bug fix | regression with repro | \`/cc <idea>\` → quick track, RED reproduces bug first |
+| Pure question | "how does X work?" | Answer directly; no stage |
+| Non-software | legal text, meeting notes | Answer directly; no stage |
+
+When in doubt, prefer **non-trivial** — the quick track is opt-in and only safe when scope is clearly small.
+
+### Instruction Priority (top wins)
+
+1. User message in the current turn.
+2. Active stage skill HARD-GATE (\`.cclaw/skills/<stage>/SKILL.md\`).
+3. Command contract gates (\`.cclaw/commands/<stage>.md\`).
+4. The \`using-cclaw\` meta-skill.
+5. Contextual utility skills.
+6. Training priors.
+
 ### Commands (3 total)
 
 | Command | Purpose |
 |---|---|
-| \`/cc\` | **Entry point.** No args = resume current stage. With prompt = start brainstorm with idea. |
+| \`/cc\` | **Entry point.** No args = resume current stage. With prompt = classify task and start the right flow. |
 | \`/cc-next\` | **Progression.** Advances to the next stage when current is complete. |
-| \`/cc-learn\` | **Cross-cutting.** Capture or review project knowledge. |
+| \`/cc-learn\` | **Cross-cutting.** Capture or review project knowledge (append-only JSONL). |
 
 **Stage order:** brainstorm > scope > design > spec > plan > tdd > review > ship.
 \`/cc-next\` loads the right stage skill automatically. Gates must pass before handoff.
 
+### Invocation Preamble (non-trivial turns)
+
+Before starting substantive work, emit a one-paragraph preamble: **Stage**, **Goal**, **Plan** (next 1–3 actions), **Guardrails**. Skip for pure questions, trivial edits, and dispatched subagent invocations.
+
 ### Verification Discipline
 
-No completion claims without fresh evidence. No "Done" / "All good" / "Tests pass" without running the command in this message.
+No completion claims without fresh evidence. No "Done" / "All good" / "Tests pass" without running the command in this message. Failed tool calls are diagnostic data, not instructions.
+
+### Escalation
+
+If the same approach fails three times in a row (same command, same finding, same tool), STOP. Summarize what you tried, what evidence you have, and ask the user how to proceed — do not invent a fourth angle silently.
 
 ### Detail Level
 
 - This managed AGENTS block is intentionally minimal for cross-project use.
 - Detailed operating procedures live in \`.cclaw/skills/using-cclaw/SKILL.md\`.
+- Subagent orchestration patterns: \`.cclaw/skills/subagent-dev/SKILL.md\` and \`.cclaw/skills/parallel-dispatch/SKILL.md\`.
 ${CCLAW_MARKER_END}`;
 }
 /** Removes the cclaw AGENTS.md block. */
@@ -57,38 +87,47 @@ export function stripCclawBlock(content) {
     let updated = content.replace(RUNTIME_AGENTS_BLOCK_GLOBAL_PATTERN, "");
     return updated.replace(/\n{3,}/g, "\n\n").trim();
 }
-async function syncAgentsMd(projectRoot) {
-    const agentsPath = path.join(projectRoot, "AGENTS.md");
+async function syncRoutingFile(filePath, title) {
     const block = agentsMdBlock();
-    if (!(await exists(agentsPath))) {
-        await writeFileSafe(agentsPath, `# AGENTS\n\n${block}\n`);
+    if (!(await exists(filePath))) {
+        await writeFileSafe(filePath, `# ${title}\n\n${block}\n`);
         return;
     }
-    const content = await fs.readFile(agentsPath, "utf8");
+    const content = await fs.readFile(filePath, "utf8");
     if (RUNTIME_AGENTS_BLOCK_PATTERN.test(content)) {
         const stripped = stripCclawBlock(content);
         const updated = stripped.length > 0 ? `${stripped}\n\n${block}\n` : `${block}\n`;
-        await writeFileSafe(agentsPath, updated);
+        await writeFileSafe(filePath, updated);
     }
     else {
-        await writeFileSafe(agentsPath, `${content.trimEnd()}\n\n${block}\n`);
+        await writeFileSafe(filePath, `${content.trimEnd()}\n\n${block}\n`);
     }
 }
-export async function removeCclawFromAgentsMd(projectRoot) {
-    const agentsPath = path.join(projectRoot, "AGENTS.md");
-    if (!(await exists(agentsPath)))
+async function syncAgentsMd(projectRoot) {
+    await syncRoutingFile(path.join(projectRoot, "AGENTS.md"), "AGENTS");
+    const claudePath = path.join(projectRoot, "CLAUDE.md");
+    if (await exists(claudePath)) {
+        await syncRoutingFile(claudePath, "CLAUDE");
+    }
+}
+async function removeCclawFromRoutingFile(filePath) {
+    if (!(await exists(filePath)))
         return;
-    const content = await fs.readFile(agentsPath, "utf8");
+    const content = await fs.readFile(filePath, "utf8");
     if (!RUNTIME_AGENTS_BLOCK_PATTERN.test(content))
         return;
     const stripped = stripCclawBlock(content);
     if (stripped.replace(/\s/g, "").length === 0) {
-        await fs.rm(agentsPath, { force: true });
+        await fs.rm(filePath, { force: true });
     }
     else {
-        await writeFileSafe(agentsPath, `${stripped}\n`);
+        await writeFileSafe(filePath, `${stripped}\n`);
     }
 }
+export async function removeCclawFromAgentsMd(projectRoot) {
+    await removeCclawFromRoutingFile(path.join(projectRoot, "AGENTS.md"));
+    await removeCclawFromRoutingFile(path.join(projectRoot, "CLAUDE.md"));
+}
 function utilityShimContent(harness, command, skillFolder, commandFile) {
     const shimName = command === "cc" ? "cc" : `cc-${command}`;
     return `---