cclaw-cli 0.7.0 → 0.8.0

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 |
@@ -327,6 +341,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
 
@@ -446,7 +474,7 @@ Execution rule: complete and verify each wave before starting the next wave.
 _Optional retrospective. The goal is to make the **next** feature faster, not to evaluate this one._
 _If you have nothing to add, write the explicit line: \`No compound insight this run.\`_
 - Insight: <one short line about what should accelerate the next run>
-- Action: append \`[compound]\` entry to \`.cclaw/knowledge.md\` capturing the insight
+- Action: append one strict-schema JSON line with \`"type":"compound"\` to \`.cclaw/knowledge.jsonl\` capturing the insight (fields: type, trigger, action, confidence, domain, stage, created, project)
 `
 };
 export const RULEBOOK_MARKDOWN = `# Cclaw Rulebook

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

@@ -16,15 +16,33 @@ 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;
 export declare function languageGoSkill(): string;
-export declare const LANGUAGE_RULE_PACK_FOLDERS: {
-    readonly typescript: "language-typescript";
-    readonly python: "language-python";
-    readonly go: "language-go";
+/**
+ * Language rule packs live under `.cclaw/rules/lang/<pack>.md`. They are NOT
+ * skills (no folder, no `SKILL.md`) — they are opt-in **rule files** that the
+ * meta-skill router and stage hooks consult when the corresponding language
+ * appears in a diff. The pack id doubles as the on-disk filename stem.
+ */
+export declare const LANGUAGE_RULE_PACK_FILES: {
+    readonly typescript: "typescript.md";
+    readonly python: "python.md";
+    readonly go: "go.md";
 };
+/**
+ * Folder (relative to runtime root) that holds every enabled language rule
+ * pack. A single folder keeps discovery trivial for hooks and for `doctor`.
+ */
+export declare const LANGUAGE_RULE_PACK_DIR: readonly ["rules", "lang"];
 export declare const LANGUAGE_RULE_PACK_GENERATORS: Record<string, () => string>;
-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"];
+/**
+ * Legacy per-language folders under `.cclaw/skills/` used in v0.7.0. Listed
+ * here so `cclaw sync` and `doctor` can surface drift and the installer can
+ * 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", "document-review"];
 export declare const UTILITY_SKILL_MAP: Record<string, () => string>;

package/dist/content/utility-skills.js

@@ -751,22 +751,22 @@ candidates exist).
 export function knowledgeCurationSkill() {
     return `---
 name: knowledge-curation
-description: "Read-only curation pass over .cclaw/knowledge.md and .cclaw/knowledge.jsonl. Surfaces stale, duplicate, or low-confidence entries and proposes a soft-archive plan; never deletes without explicit user approval."
+description: "Read-only curation pass over the canonical strict-JSONL knowledge store at .cclaw/knowledge.jsonl. Surfaces stale, duplicate, or low-confidence entries and proposes a soft-archive plan that moves approved lines to .cclaw/knowledge.archive.jsonl. Never deletes without explicit user approval."
 ---
 
 # Knowledge Curation
 
 ## Quick Start
 
-> 1. This is a **read-only audit** of \`.cclaw/knowledge.md\` and, when present, \`.cclaw/knowledge.jsonl\`. Never delete or rewrite entries here.
+> 1. This is a **read-only audit** of \`.cclaw/knowledge.jsonl\`. Never delete or rewrite entries here.
 > 2. Surface candidates for soft-archive when the active file > 50 entries OR contains stale/duplicate/superseded entries.
 > 3. Propose a single archive plan and require explicit user approval before any move.
 
 ## HARD-GATE
 
-- Do not modify \`.cclaw/knowledge.md\` or \`.cclaw/knowledge.jsonl\` from this skill except via an explicit user-approved archive plan that **moves** markdown entries to \`.cclaw/knowledge.archive.md\` and appends soft-archive lines (same title, \`archived: true\`) to the JSONL. Never physically removes entries.
-- Do not silently rewrite or summarize entries — preserve original wording.
-- Prefer the JSONL store for queries when present (faster, structured); use the markdown mirror as the human-readable source of truth for final user approval.
+- Do not modify \`.cclaw/knowledge.jsonl\` from this skill except via an explicit user-approved archive plan that **moves** full JSON lines verbatim to \`.cclaw/knowledge.archive.jsonl\`. Never physically delete history that is already archived — the archive file is append-only too.
+- Do not silently rewrite or summarize entries — preserve the original JSON line byte-for-byte.
+- Operate only on the canonical JSONL store. If you see a stray \`.cclaw/knowledge.md\`, report it as a drift signal; do **not** read or rewrite it.
 
 ## When to run
 
@@ -776,28 +776,28 @@ description: "Read-only curation pass over .cclaw/knowledge.md and .cclaw/knowle
 
 ## Audit dimensions
 
-For each entry in \`.cclaw/knowledge.md\` produce a row with:
+For each JSON line in \`.cclaw/knowledge.jsonl\` produce a row with:
 
 | Field | Source |
 |---|---|
-| Title | \`### <ts> [type] <title>\` heading |
-| Type | \`rule\` / \`pattern\` / \`lesson\` / \`compound\` |
-| Stage | \`Stage:\` field (or \`unknown\`) |
-| Age | days since timestamp |
-| Confidence | \`Confidence:\` field if present, else \`unstated\` |
-| Domain | \`Domain:\` field if present |
-| Supersedes | \`Supersedes:\` field if present |
+| # | 1-based line number in the JSONL file |
+| Type | \`type\` field (\`rule\` / \`pattern\` / \`lesson\` / \`compound\`) |
+| Stage | \`stage\` field (or \`null\`) |
+| Age | days since \`created\` |
+| Confidence | \`confidence\` field |
+| Domain | \`domain\` field (or \`null\`) |
+| Trigger | \`trigger\` field, truncated to 60 chars |
 | Status hint | one of: keep / supersede-candidate / archive-candidate / duplicate |
 
 ### Status rules
 
-- **supersede-candidate**: another entry has \`Supersedes: <this-title>\`.
-- **duplicate**: title or insight ≈ another entry's (caller's judgment, not regex).
+- **supersede-candidate**: a newer line shares the same \`trigger\` (case-insensitive) and a different \`action\`.
+- **duplicate**: \`trigger\` ≈ another line's AND \`action\` ≈ the same (caller's judgment).
 - **archive-candidate**:
-  - Type \`lesson\` AND age > 180 days AND no \`Supersedes\` chain points to it; OR
-  - Stage = \`brainstorm\` AND age > 90 days; OR
-  - Confidence = \`low\` AND age > 60 days; OR
-  - Total active entries > 50 and entry has lowest reuse signal.
+  - \`type=lesson\` AND age > 180 days AND no newer line references the same \`trigger\`; OR
+  - \`stage=brainstorm\` AND age > 90 days; OR
+  - \`confidence=low\` AND age > 60 days; OR
+  - Total active entries > 50 and entry has the lowest estimated reuse signal.
 - **keep**: everything else.
 
 ## Output format
@@ -807,7 +807,7 @@ Produce two artifacts as **chat output only** (do not write files):
 ### 1. Audit table
 
 \`\`\`markdown
-| # | Title | Type | Stage | Age | Confidence | Status hint |
+| # | Type | Stage | Age | Confidence | Trigger | Status hint |
 |---|---|---|---|---|---|---|
 | 1 | … | … | … | … | … | … |
 \`\`\`
@@ -820,14 +820,15 @@ Produce two artifacts as **chat output only** (do not write files):
 Threshold reasoning: <why entries below were selected>
 
 Entries to archive:
-1. <title> — reason
-2. <title> — reason
+1. line #<N> — <trigger> — reason
+2. line #<N> — <trigger> — reason
 
 Action plan if approved:
-1. Append a header to \`.cclaw/knowledge.archive.md\` with today's UTC date.
-2. Move (cut/paste) selected entries verbatim from \`.cclaw/knowledge.md\` into the archive file.
-3. Append a single supersession line to \`.cclaw/knowledge.md\`:
-   \\\`### <ts> [pattern] knowledge-curation-<date> — archived <N> entries, see knowledge.archive.md\\\`
+1. Ensure \`.cclaw/knowledge.archive.jsonl\` exists (create empty if missing).
+2. Move (cut/paste) the selected JSON lines verbatim from
+   \`.cclaw/knowledge.jsonl\` into \`.cclaw/knowledge.archive.jsonl\`,
+   preserving byte order within each file.
+3. Do not rewrite, re-order, or pretty-print any remaining line in the active file.
 
 After approval: ask the user to run the move themselves, or — if they explicitly grant write access — perform the move atomically and report the new active count.
 \`\`\`
@@ -1068,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
@@ -1079,7 +1217,7 @@ description: "Post-ship retrospective lens. Use after a ship to extract durable
 ## Quick Start
 
 > 1. Run **after** the ship stage closes (PR merged or release tagged), while the run is still loaded in memory.
-> 2. Walk the four lenses below; harvest concrete entries for \`.cclaw/knowledge.md\`.
+> 2. Walk the four lenses below; harvest concrete entries for \`.cclaw/knowledge.jsonl\`.
 > 3. Stop when you have at least one durable entry **or** an explicit "no new lesson this run".
 
 ## HARD-GATE
@@ -1132,13 +1270,14 @@ For each lens, write either a knowledge entry **or** the explicit string
 
 ## Output protocol
 
-For every harvested insight, append one entry to \`.cclaw/knowledge.md\` using
-the standard format (see \`learnings\` skill). Prefer:
+For every harvested insight, append one strict-schema JSON line to
+\`.cclaw/knowledge.jsonl\` (fields: \`type, trigger, action, confidence, domain, stage, created, project\`).
+See the \`learnings\` skill for the canonical shape. Choose \`type\`:
 
-- \`[compound]\` for process/speed accelerators.
-- \`[lesson]\` for "we learned this the hard way".
-- \`[pattern]\` for repeatable shapes that worked.
-- \`[rule]\` only for hard constraints that must always hold.
+- \`compound\` for process/speed accelerators.
+- \`lesson\` for "we learned this the hard way".
+- \`pattern\` for repeatable shapes that worked.
+- \`rule\` only for hard constraints that must always hold.
 
 Then write a one-paragraph **Run Summary** at the top of the next
 \`/cc <idea>\` brainstorm context citing the lessons in scope.
@@ -1347,16 +1486,37 @@ irrelevant. Discarded errors are Go's #1 source of silent data loss.
 \`\`\`
 `;
 }
-export const LANGUAGE_RULE_PACK_FOLDERS = {
-    typescript: "language-typescript",
-    python: "language-python",
-    go: "language-go"
+/**
+ * Language rule packs live under `.cclaw/rules/lang/<pack>.md`. They are NOT
+ * skills (no folder, no `SKILL.md`) — they are opt-in **rule files** that the
+ * meta-skill router and stage hooks consult when the corresponding language
+ * appears in a diff. The pack id doubles as the on-disk filename stem.
+ */
+export const LANGUAGE_RULE_PACK_FILES = {
+    typescript: "typescript.md",
+    python: "python.md",
+    go: "go.md"
 };
+/**
+ * Folder (relative to runtime root) that holds every enabled language rule
+ * pack. A single folder keeps discovery trivial for hooks and for `doctor`.
+ */
+export const LANGUAGE_RULE_PACK_DIR = ["rules", "lang"];
 export const LANGUAGE_RULE_PACK_GENERATORS = {
-    "language-typescript": languageTypescriptSkill,
-    "language-python": languagePythonSkill,
-    "language-go": languageGoSkill
+    typescript: languageTypescriptSkill,
+    python: languagePythonSkill,
+    go: languageGoSkill
 };
+/**
+ * Legacy per-language folders under `.cclaw/skills/` used in v0.7.0. Listed
+ * here so `cclaw sync` and `doctor` can surface drift and the installer can
+ * clean them up after the move to `.cclaw/rules/lang/`.
+ */
+export const LEGACY_LANGUAGE_RULE_PACK_FOLDERS = [
+    "language-typescript",
+    "language-python",
+    "language-go"
+];
 export const UTILITY_SKILL_FOLDERS = [
     "security",
     "debugging",
@@ -1371,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,
@@ -1387,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

@@ -17,7 +17,7 @@ import { checkMandatoryDelegations } from "./delegation.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
 import { reconcileAndWriteCurrentStageGateCatalog, verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
 import { stageSkillFolder } from "./content/skills.js";
-import { LANGUAGE_RULE_PACK_FOLDERS, UTILITY_SKILL_FOLDERS } from "./content/utility-skills.js";
+import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LEGACY_LANGUAGE_RULE_PACK_FOLDERS, UTILITY_SKILL_FOLDERS } from "./content/utility-skills.js";
 import { CONTEXT_MODES, DEFAULT_CONTEXT_MODE } from "./content/contexts.js";
 import { validateHookDocument } from "./hook-schema.js";
 const execFileAsync = promisify(execFile);
@@ -409,15 +409,29 @@ export async function doctorChecks(projectRoot, options = {}) {
         });
     }
     // Opt-in language rule packs: only check presence for packs the user enabled.
+    // Canonical location is .cclaw/rules/lang/<pack>.md.
     for (const pack of parsedConfig?.languageRulePacks ?? []) {
-        const folder = LANGUAGE_RULE_PACK_FOLDERS[pack];
-        if (!folder)
+        const fileName = LANGUAGE_RULE_PACK_FILES[pack];
+        if (!fileName)
             continue;
-        const skillPath = path.join(projectRoot, RUNTIME_ROOT, "skills", folder, "SKILL.md");
+        const packPath = path.join(projectRoot, RUNTIME_ROOT, ...LANGUAGE_RULE_PACK_DIR, fileName);
         checks.push({
             name: `language_rule_pack:${pack}`,
-            ok: await exists(skillPath),
-            details: skillPath
+            ok: await exists(packPath),
+            details: packPath
+        });
+    }
+    // Drift: legacy per-language skill folders from v0.7.0 must not coexist with
+    // the new rules/lang/ layout. `cclaw sync` removes them on the next run.
+    for (const legacyFolder of LEGACY_LANGUAGE_RULE_PACK_FOLDERS) {
+        const legacyPath = path.join(projectRoot, RUNTIME_ROOT, "skills", legacyFolder);
+        const legacyPresent = await exists(legacyPath);
+        checks.push({
+            name: `language_rule_pack:no_legacy:${legacyFolder}`,
+            ok: !legacyPresent,
+            details: legacyPresent
+                ? `legacy ${legacyPath} must be removed — language packs moved to ${RUNTIME_ROOT}/${LANGUAGE_RULE_PACK_DIR.join("/")}/. Run \`cclaw sync\`.`
+                : `no legacy ${legacyFolder} skill folder`
         });
     }
     // Agent definition files
@@ -680,11 +694,21 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: true,
         details: hasPython ? "python3 available" : "warning: python3 not found, jq/node paths must stay healthy"
     });
-    // Knowledge store exists
+    // Knowledge store exists (canonical JSONL, no markdown mirror)
     checks.push({
         name: "knowledge:store_exists",
-        ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "knowledge.md")),
-        details: `${RUNTIME_ROOT}/knowledge.md must exist`
+        ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl")),
+        details: `${RUNTIME_ROOT}/knowledge.jsonl must exist`
+    });
+    // There must be NO legacy markdown knowledge store — JSONL is the only store.
+    const legacyKnowledgeMdPath = path.join(projectRoot, RUNTIME_ROOT, "knowledge.md");
+    const legacyExists = await exists(legacyKnowledgeMdPath);
+    checks.push({
+        name: "knowledge:no_legacy_markdown",
+        ok: !legacyExists,
+        details: legacyExists
+            ? `legacy ${RUNTIME_ROOT}/knowledge.md must be removed — cclaw is JSONL-native`
+            : `no legacy markdown store present`
     });
     checks.push({
         name: "state:checkpoint_exists",

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 `---