cclaw-cli 0.5.17 → 0.7.0

package/dist/content/learnings.js

@@ -2,8 +2,9 @@
 // Knowledge store content for /cc-learn and stage self-improvement prompts.
 // ---------------------------------------------------------------------------
 const KNOWLEDGE_PATH = ".cclaw/knowledge.md";
+const KNOWLEDGE_JSONL_PATH = ".cclaw/knowledge.jsonl";
 const LEARN_SKILL_NAME = "learnings";
-const LEARN_SKILL_DESCRIPTION = "Project-scoped knowledge store: review and append rule/pattern/lesson entries in .cclaw/knowledge.md.";
+const LEARN_SKILL_DESCRIPTION = "Project-scoped knowledge store: review and append rule/pattern/lesson/compound entries. Maintains a human-readable markdown mirror at .cclaw/knowledge.md and a canonical JSONL store at .cclaw/knowledge.jsonl.";
 export function learnSkillMarkdown() {
     return `---
 name: ${LEARN_SKILL_NAME}
@@ -14,18 +15,24 @@ description: "${LEARN_SKILL_DESCRIPTION}"
 
 ## Overview
 
-This skill manages the append-only project knowledge file at \`${KNOWLEDGE_PATH}\`.
+This skill manages the project knowledge store. The store has **two mirrored formats**:
 
-Use it to keep durable knowledge that should survive sessions:
+- \`${KNOWLEDGE_PATH}\` — human-readable, append-only markdown (the reading view).
+- \`${KNOWLEDGE_JSONL_PATH}\` — canonical, machine-queryable JSONL (one JSON object per line). Used by the curator, /cc-status, and future analytics.
+
+Every \`/cc-learn add\` appends to **both** files. \`/cc-learn search\` prefers the JSONL store if it exists; otherwise it falls back to the markdown file.
+
+Use the store to keep durable knowledge that should survive sessions:
 - **rule**: hard constraint to follow every time
 - **pattern**: repeatable way that works well in this project
 - **lesson**: non-obvious outcome from a failure or trade-off
+- **compound**: post-ship insight about how to make the *next* feature faster (process accelerator, not domain rule)
 
 ## HARD-GATE
 
-Under \`/cc-learn\`, only modify the knowledge store (\`${KNOWLEDGE_PATH}\`) or an explicitly user-approved summary file. Do not modify application code here.
+Under \`/cc-learn\`, only modify the knowledge store files (\`${KNOWLEDGE_PATH}\` and \`${KNOWLEDGE_JSONL_PATH}\`) or an explicitly user-approved summary file. Do not modify application code here.
 
-## Entry format (append-only)
+## Entry format — markdown mirror (append-only)
 
 \`\`\`markdown
 ### 2026-04-14T12:00:00Z [pattern] short-title
@@ -33,12 +40,62 @@ Under \`/cc-learn\`, only modify the knowledge store (\`${KNOWLEDGE_PATH}\`) or
 - Context: one short line
 - Insight: one short line
 - Reuse: one short line
+- Confidence: high | medium | low      (optional)
+- Domain: api | infra | ui | testing | …  (optional)
+- Project: <repo or scope name>        (optional)
 \`\`\`
 
+## Entry format — canonical JSONL (one entry per line)
+
+\`\`\`json
+{"type":"pattern","title":"short-title","stage":"design","context":"one short line","insight":"one short line","reuse":"one short line","created":"2026-04-14T12:00:00Z","confidence":"high","domain":"api","project":"cclaw","supersedes":null,"superseded":false,"archived":false}
+\`\`\`
+
+Schema:
+
+| field | type | required | notes |
+|---|---|---|---|
+| \`type\` | \`"rule" \\| "pattern" \\| "lesson" \\| "compound"\` | yes | Lowercase. |
+| \`title\` | string | yes | Short title, used as a human-readable identifier. |
+| \`stage\` | \`FlowStage\` | yes | One of brainstorm / scope / design / spec / plan / tdd / review / ship. |
+| \`context\` | string | yes | What situation triggered this. |
+| \`insight\` | string | yes | What must be remembered. |
+| \`reuse\` | string | yes | How to apply this next time — concrete trigger/action. |
+| \`created\` | ISO 8601 UTC string | yes | When the entry was written. |
+| \`confidence\` | \`"high" \\| "medium" \\| "low"\` | optional | Default \`medium\` if omitted. |
+| \`domain\` | string | optional | Free-form taxonomy (\`api\`, \`infra\`, \`ui\`, …). |
+| \`project\` | string | optional | Repo or scope name when the entry crosses features. |
+| \`supersedes\` | string \\| null | optional | Title of the entry this one replaces. |
+| \`superseded\` | boolean | optional | \`true\` when a newer entry replaces this one. |
+| \`archived\` | boolean | optional | \`true\` once the curator soft-archives the entry. |
+
 Rules:
-- Type must be exactly one of \`rule\`, \`pattern\`, \`lesson\` (lowercase).
-- Never rewrite history silently; append a newer correction entry instead.
+- Type must be exactly one of \`rule\`, \`pattern\`, \`lesson\`, \`compound\` (lowercase).
+- Never rewrite history silently; append a newer correction entry instead. To replace, set \`supersedes\` to the old title in the new JSONL entry and in the new markdown entry prefix with \`Supersedes: <old-title>\`. Flip \`superseded: true\` on the old JSONL entry via a new JSONL line (the file is append-only; use a \`replace\` line by convention — see Curation policy).
 - Keep entries concise and actionable.
+- Optional fields (\`Confidence\`, \`Domain\`, \`Project\`) are forward-compatible and used by the **knowledge-curation** skill — fill them when known.
+
+## Backward-compat migration (markdown → JSONL)
+
+Run \`/cc-learn migrate\` once per repo when \`${KNOWLEDGE_JSONL_PATH}\` is missing:
+
+1. Parse \`${KNOWLEDGE_PATH}\`. Each entry starts with \`### <ISO8601> [<type>] <title>\` and is followed by \`- <Field>: <value>\` lines until the next \`###\` or EOF.
+2. Map fields to JSONL schema:
+   - Heading timestamp → \`created\`; heading \`[type]\` → \`type\`; heading title → \`title\`.
+   - Bullet \`Stage:\`, \`Context:\`, \`Insight:\`, \`Reuse:\`, \`Confidence:\`, \`Domain:\`, \`Project:\` → matching fields.
+   - A \`Supersedes:\` prefix line becomes \`"supersedes": "<old-title>"\`.
+3. Emit one JSON object per line to \`${KNOWLEDGE_JSONL_PATH}\` preserving the original order. Set defaults: \`confidence = "medium"\`, \`superseded = false\`, \`archived = false\`, missing optional fields = \`null\`.
+4. Do **not** rewrite \`${KNOWLEDGE_PATH}\`. The markdown stays as the human-readable mirror; new additions continue to write both files.
+5. After migration, \`/cc-learn search\` reads the JSONL store first; if absent, it continues to parse the markdown file (so users who never migrate still work).
+
+## Curation policy (target: ≤ 50 active entries)
+
+The knowledge file is append-only, but entries can be **superseded** rather than deleted:
+
+- When you discover a more correct rule, append a new entry with \`Supersedes: <old-title>\`.
+- During \`/cc-learn curate\`, the assistant surfaces candidates for soft-archive (move to \`.cclaw/knowledge.archive.md\`) when the active file exceeds 50 entries or contains stale/duplicate entries.
+
+See the **knowledge-curation** utility skill for the full curation protocol.
 
 ## Subcommands
 
@@ -47,13 +104,24 @@ Rules:
 - If file is missing or empty, report that clearly.
 
 ### \`/cc-learn search <query>\`
-- Perform case-insensitive text search in \`${KNOWLEDGE_PATH}\`.
+- If \`${KNOWLEDGE_JSONL_PATH}\` exists: stream it, JSON.parse each line, filter where any of \`title\`, \`context\`, \`insight\`, \`reuse\`, \`domain\` contains \`<query>\` (case-insensitive). Skip \`archived: true\` unless \`--include-archived\` is passed.
+- Otherwise: case-insensitive text search in \`${KNOWLEDGE_PATH}\`.
 - Return matched headings and nearby lines.
 
 ### \`/cc-learn add\`
 - Ask for: \`type\`, \`short title\`, \`context\`, \`insight\`, \`reuse\`.
-- Append one entry using current UTC timestamp.
-- Re-read the file tail and confirm the entry was written.
+- Optionally ask for: \`confidence\`, \`domain\`, \`project\`, \`supersedes\`.
+- Append one markdown entry to \`${KNOWLEDGE_PATH}\` (human mirror).
+- Append one JSON line to \`${KNOWLEDGE_JSONL_PATH}\` (canonical store) using the same UTC timestamp as the markdown entry's heading.
+- Re-read both tails to confirm both writes.
+
+### \`/cc-learn migrate\`
+- Parse \`${KNOWLEDGE_PATH}\` and emit \`${KNOWLEDGE_JSONL_PATH}\` per the Backward-compat migration protocol above.
+- Safe to re-run: if JSONL already exists, report the current entry count and exit (no destructive rewrite).
+
+### \`/cc-learn curate\`
+- Hand off to the **knowledge-curation** skill (read-only audit + soft-archive plan).
+- Never deletes from \`${KNOWLEDGE_PATH}\` or \`${KNOWLEDGE_JSONL_PATH}\` without an explicit user-approved archive plan. Soft-archive in JSONL means appending a new line with the same \`title\` and \`archived: true\` (entries are never physically removed).
 `;
 }
 export function learnCommandContract() {
@@ -61,19 +129,23 @@ export function learnCommandContract() {
 
 ## Purpose
 
-Manage the project knowledge store at \`${KNOWLEDGE_PATH}\` (append-only markdown).
+Manage the project knowledge store. Two mirrored formats:
+- \`${KNOWLEDGE_PATH}\` — human-readable markdown (append-only, tail view).
+- \`${KNOWLEDGE_JSONL_PATH}\` — canonical JSONL (one entry per line) used by the curator and machine consumers.
 
 ## HARD-GATE
 
-Do not edit source code from this command. Only operate on \`${KNOWLEDGE_PATH}\` (or user-approved summary output).
+Do not edit source code from this command. Only operate on \`${KNOWLEDGE_PATH}\`, \`${KNOWLEDGE_JSONL_PATH}\`, or user-approved summary output.
 
 ## Subcommands
 
 | subcommand | args | description |
 |---|---|---|
-| (default) | — | Show recent knowledge entries (tail view). |
-| \`search\` | \`<query>\` | Search knowledge text for relevant prior rules/patterns/lessons. |
-| \`add\` | — | Append a new entry with type \`rule\` / \`pattern\` / \`lesson\`. |
+| (default) | — | Show recent knowledge entries (tail view from markdown mirror). |
+| \`search\` | \`<query>\` | Search knowledge for relevant prior rules/patterns/lessons. Prefers JSONL when present. |
+| \`add\` | — | Append a new entry (\`rule\` / \`pattern\` / \`lesson\` / \`compound\`) to **both** markdown and JSONL. |
+| \`migrate\` | — | Emit the canonical JSONL mirror from the markdown file (idempotent). |
+| \`curate\` | — | Hand off to the **knowledge-curation** skill: read-only audit + soft-archive plan when the active file exceeds the curation threshold. |
 `;
 }
 export function selfImprovementBlock(stageName) {
@@ -83,7 +155,7 @@ After this stage, ask:
 - Did I discover a non-obvious reusable **rule** or **pattern**?
 - Did a failure reveal a reusable **lesson**?
 
-If yes, append one concise entry to \`${KNOWLEDGE_PATH}\`:
+If yes, append one concise entry to **both** the markdown mirror (\`${KNOWLEDGE_PATH}\`) and the canonical JSONL store (\`${KNOWLEDGE_JSONL_PATH}\`) with the same timestamp:
 
 \`\`\`bash
 TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
@@ -94,9 +166,10 @@ cat >> ${KNOWLEDGE_PATH} <<EOF
 - Insight: what should be remembered
 - Reuse: how to apply this next time
 EOF
+printf '%s\\n' '{"type":"pattern","title":"short-title","stage":"${stageName}","context":"what situation triggered this","insight":"what should be remembered","reuse":"how to apply this next time","created":"'"$TS"'","confidence":"medium","domain":null,"project":null,"supersedes":null,"superseded":false,"archived":false}' >> ${KNOWLEDGE_JSONL_PATH}
 \`\`\`
 
-Type must be exactly one of: \`rule\`, \`pattern\`, \`lesson\`.
+Type must be exactly one of: \`rule\`, \`pattern\`, \`lesson\`, \`compound\`.
 `;
 }
 export function learningsSearchPreamble(stage) {
@@ -110,7 +183,7 @@ If the file is empty, continue normally.
 export function learningsAgentsMdBlock() {
     return `### Knowledge Store
 
-\`${KNOWLEDGE_PATH}\` — append-only markdown memory with entry types \`rule\`, \`pattern\`, \`lesson\`.
+\`${KNOWLEDGE_PATH}\` — append-only markdown memory with entry types \`rule\`, \`pattern\`, \`lesson\`, \`compound\`.
 At session start and stage transitions, load recent entries and apply relevant ones.
 If a non-obvious reusable rule/pattern/lesson is discovered, append a new entry.
 `;

package/dist/content/meta-skill.js

@@ -89,6 +89,41 @@ These skills live in \`.cclaw/skills/\` but have no slash commands. They activat
 
 **Activation rule:** When a contextual skill applies, read its SKILL.md and follow it as a supplementary lens alongside the current stage. Do not skip the stage workflow — the contextual skill adds depth, not a detour.
 
+### Opt-in language rule packs
+
+cclaw stays language-agnostic by default. Projects that want language-specific
+review lenses can enable opt-in rule packs in \`.cclaw/config.yaml\`:
+
+\`\`\`yaml
+languageRulePacks:
+  - typescript   # → skills/language-typescript/SKILL.md
+  - python       # → skills/language-python/SKILL.md
+  - go           # → skills/language-go/SKILL.md
+\`\`\`
+
+After editing the list, run \`cclaw sync\` to materialize the enabled pack SKILL.md
+files. Packs activate during \`tdd\` and \`review\` when the diff touches files in
+their language. They are additive lenses — Tier-1 rules block merge, Tier-2 rules
+require a named follow-up. Never silently override them.
+
+## Custom Skills (project-owned, sync-safe)
+
+\`.cclaw/custom-skills/\` is a sync-safe directory. \`cclaw sync\` and \`cclaw upgrade\` **never overwrite** files there.
+
+Use it to add **project-specific** skills that complement the managed library:
+
+- Each skill: \`.cclaw/custom-skills/<folder>/SKILL.md\` following the public-API frontmatter schema documented in \`.cclaw/custom-skills/README.md\`.
+- The frontmatter public API is stable across cclaw releases: \`name\`, \`description\` (required), plus optional \`stages\`, \`triggers\`, \`hardGate\`, \`owners\`, \`version\`.
+- Routing precedence when loading a stage:
+  1. Active stage skill under \`.cclaw/skills/<stage>/\`.
+  2. Managed utility skills whose trigger matches (\`landscape-check\`, \`security-audit\`, \`adversarial-review\`, etc.).
+  3. **Custom skills** whose \`stages\` array includes the active stage (or is missing) AND whose \`description\` / \`triggers\` match the prompt.
+- Custom skills are **never mandatory delegations** — they are opt-in lenses. If you need a mandatory dispatch, promote the skill upstream or add a managed specialist instead.
+- Activate by mentioning the skill name explicitly, or rely on semantic routing from the description + triggers.
+- See \`.cclaw/custom-skills/README.md\` for the full convention and a starter template under \`.cclaw/custom-skills/example/\`.
+
+If a custom skill turns out to generalize (e.g. another project would want the same lens), promote it to a managed skill via a contribution to the cclaw repo — managed skills get versioning and maintenance.
+
 ## Progressive Disclosure (Depth / See Also)
 
 Use this loading order to keep context lean while preserving depth:
@@ -117,13 +152,27 @@ When a stage requires user input (approval, choice, direction), use this structu
 2. **Present options** as labeled choices (A, B, C...) with:
    - One-line description of each option
    - Trade-off or consequence
+   - **\`Completeness: X/10\`** — how thoroughly does this option cover the dimensions the stage cares about (failure modes, data flow, blast radius, observability, rollback, etc. — pick the dimensions that matter for *this* decision and subtract for each gap). Force a numeric score; vague text scores ≤ 5.
    - Mark one as **(recommended)** with brief why
-3. **Use the harness ask-user tool** when available:
+3. **Pick the highest-scoring option as the recommendation.** If scores tie, prefer the option with the smallest blast radius (review/ship), the lowest risk (design/spec), or the most reversible outcome (ship finalization).
+4. **Use the harness ask-user tool** when available:
    - Claude Code: \`AskUserQuestion\` tool
    - Cursor: \`AskQuestion\` tool with options array
    - Codex/OpenCode: numbered list in message (no native ask tool)
-4. **Wait for response.** Do not proceed until the user picks.
-5. **Commit to the choice.** Once decided, do not re-argue.
+5. **Wait for response.** Do not proceed until the user picks.
+6. **Commit to the choice.** Once decided, do not re-argue.
+
+### Completeness scoring rubric (apply per option)
+
+| Score | Meaning |
+|---|---|
+| 9-10 | Closes the decision with no carry-over risk; covers every dimension stage cares about. |
+| 7-8 | Closes the decision with a small named follow-up; one dimension partially covered. |
+| 5-6 | Plausible but leaves at least one dimension visibly open; needs follow-up before next stage. |
+| 3-4 | Workaround, not a solution; defers the real problem. |
+| 0-2 | Wishful thinking; do not recommend. |
+
+Always show the score next to the option label, e.g. \`(B) [Completeness: 8/10]\`.
 
 ### When to use structured asks vs conversational
 - **Structured (tool):** Architecture choices, scope decisions, approval gates, mode selection, scope boundary issues

package/dist/content/next-command.js

@@ -56,6 +56,14 @@ This is the only progression command the user needs to drive the entire flow. St
 → If current stage's \`next\` is **\`done\`**: report **"Flow complete. All stages finished."** and stop.
 → Otherwise: load **\`${RUNTIME_ROOT}/skills/<skillFolder>/SKILL.md\`** and **\`${RUNTIME_ROOT}/commands/<nextStage>.md\`** for the successor stage. Execute that stage's protocol.
 
+### Track-aware successor resolution
+
+\`flow-state.json\` carries a \`track\` field (\`"quick"\` or \`"standard"\`) and a \`skippedStages\` array.
+
+- If \`track === "quick"\`, the critical path is **spec → tdd → review → ship**. When advancing, skip any stage listed in \`skippedStages\` — i.e. after the current stage completes, pick the next stage that is NOT in \`skippedStages\`.
+- If \`track === "standard"\`, advance through all 8 stages in their natural order.
+- Never reintroduce a skipped stage mid-run. If the user wants upstream scoping work, they must archive the run and start a new one with \`track: "standard"\`.
+
 ## Resume Semantics
 
 \`/cc-next\` in a **new session** = resume from where you left off:

package/dist/content/observe.js

@@ -1613,6 +1613,14 @@ export function claudeHooksJsonWithObservation() {
                             command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`,
                             timeout: 10
                         }]
+                }],
+            PreCompact: [{
+                    matcher: "manual|auto",
+                    hooks: [{
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/pre-compact.sh`,
+                            timeout: 10
+                        }]
                 }]
         }
     }, null, 2);
@@ -1632,6 +1640,8 @@ export function cursorHooksJsonWithObservation() {
                     command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`
                 }],
             sessionCompact: [{
+                    command: `bash ${RUNTIME_ROOT}/hooks/pre-compact.sh`
+                }, {
                     command: `bash ${RUNTIME_ROOT}/hooks/session-start.sh`
                 }],
             preToolUse: [{
@@ -1684,6 +1694,14 @@ export function codexHooksJsonWithObservation() {
                             command: `bash ${RUNTIME_ROOT}/hooks/stop-checkpoint.sh`,
                             timeout: 10
                         }]
+                }],
+            PreCompact: [{
+                    matcher: "manual|auto",
+                    hooks: [{
+                            type: "command",
+                            command: `bash ${RUNTIME_ROOT}/hooks/pre-compact.sh`,
+                            timeout: 10
+                        }]
                 }]
         }
     }, null, 2);

package/dist/content/session-hooks.js

@@ -34,7 +34,7 @@ When a new session begins in any harness:
 ### What to show the user at session start
 
 \`\`\`
-Cclaw flow state: [current stage] ([N] of 9 stages completed)
+Cclaw flow state: [current stage] ([N] of 8 stages completed)
 Knowledge highlights: [rule/pattern 1], [rule/pattern 2], [rule/pattern 3]
 Next action: /cc-[stage] to continue, or describe what you'd like to do.
 \`\`\`

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

@@ -28,10 +28,25 @@ export interface ArtifactValidation {
 }
 export interface StageAutoSubagentDispatch {
     agent: "planner" | "spec-reviewer" | "code-reviewer" | "security-reviewer" | "test-author" | "doc-updater";
-    mode: "mandatory" | "proactive";
+    /**
+     * - `mandatory` — must be dispatched (or explicitly waived) before stage transition.
+     * - `proactive` — should be dispatched automatically when context matches `when`.
+     * - `conditional` — dispatched only when `condition` evaluates true at runtime; counted as
+     *   mandatory **only when the condition holds**.
+     */
+    mode: "mandatory" | "proactive" | "conditional";
     when: string;
     purpose: string;
     requiresUserGate: boolean;
+    /**
+     * Optional machine-friendly trigger expression for `conditional` rows.
+     * Supported predicates: `diff_lines_gt:<N>`, `files_touched_gt:<N>`,
+     * `trust_boundary_changed`, `release_blast_radius_high`.
+     * Multiple predicates joined by `||` mean ANY trigger satisfies the condition.
+     */
+    condition?: string;
+    /** Optional skill folder the dispatched agent should load as additional context. */
+    skill?: string;
 }
 export interface NamedAntiPattern {
     title: string;
@@ -80,6 +95,8 @@ export declare const QUESTION_FORMAT_SPEC: string;
 export declare const ERROR_BUDGET_SPEC: string;
 /** Transition guard: agents with `mode: "mandatory"` in auto-subagent dispatch for this stage. */
 export declare function mandatoryDelegationsForStage(stage: FlowStage): string[];
+/** Conditional dispatches that become mandatory only when their `condition` predicate evaluates true. */
+export declare function conditionalDispatchesForStage(stage: FlowStage): StageAutoSubagentDispatch[];
 export declare function stageSchema(stage: FlowStage): StageSchema;
 export declare function orderedStageSchemas(): StageSchema[];
 export declare function stageGateIds(stage: FlowStage): string[];

package/dist/content/stage-schema.js

@@ -195,7 +195,7 @@ const SCOPE = {
         "**Error and Rescue Registry** — For each capability: what breaks, how detected, what fallback."
     ],
     interactionProtocol: [
-        "For scope mode selection: use the Decision Protocol — present expand/selective/hold/reduce as labeled options with trade-offs and mark one as (recommended). Base your recommendation on default heuristics: greenfield -> expand, enhancement -> selective, bugfix/hotfix/refactor -> hold, broad blast radius -> reduce. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
+        "For scope mode selection: use the Decision Protocol — present expand/selective/hold/reduce as labeled options with trade-offs and mark one as (recommended). **Score each option `Completeness: X/10`** (10 = covers every prime-directive failure mode, four data-flow paths, observability, and deferred handling for the in-scope set; subtract for each gap). Recommend the highest-scoring option; if scores tie, pick the lowest blast radius. Base your recommendation on default heuristics: greenfield -> expand, enhancement -> selective, bugfix/hotfix/refactor -> hold, broad blast radius -> reduce. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
         "Walk through the scope checklist interactively. Each checklist item that surfaces a decision should be presented to the user as a question, not as a monologue. Do not dump all items at once.",
         "Challenge premise and verify the problem framing before anything else.",
         "Take a position on every scope decision. Avoid hedging phrases like 'this could work' or 'there are many ways'; state your recommendation and one concrete condition that would change it.",
@@ -405,7 +405,7 @@ const DESIGN = {
     interactionProtocol: [
         "Review architecture decisions section-by-section.",
         "For EACH issue found in a review section, present it ONE AT A TIME. Do NOT batch multiple issues.",
-        "For each issue: use the Decision Protocol — describe concretely with file/line references, present labeled options (A/B/C) with trade-offs, effort estimate (S/M/L/XL), risk level (Low/Med/High), and mark one as (recommended). If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
+        "For each issue: use the Decision Protocol — describe concretely with file/line references, present labeled options (A/B/C) with trade-offs, effort estimate (S/M/L/XL), risk level (Low/Med/High), **`Completeness: X/10` per option** (10 = fully addresses architecture/data-flow/failure-modes/test+perf review concerns for the issue, subtract for each unaddressed dimension), and mark one as (recommended). Prefer the highest-scoring option; if scores tie, prefer the lower-risk one. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
         "Only proceed to the next review section after ALL issues in the current section are resolved.",
         "If a section has no issues, say 'No issues found' and move on.",
         "Do not skip failure-mode mapping.",
@@ -1108,10 +1108,11 @@ 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).",
         "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.",
-        "Layer 2b: Security — input validation, auth boundaries, secrets exposure, injection vectors.",
+        "Layer 2b: Security — input validation, auth boundaries, secrets exposure, injection vectors. **Mandatory:** also load and execute the `.cclaw/skills/security-audit/SKILL.md` utility skill (proactive pattern sweep across diff + touched modules, not just the diff itself) and merge findings into the review army. The Layer 2 security pass is not complete until the audit sweep records a finding count (0 acceptable) with file:line evidence for every Critical.",
         "Layer 2c: Performance — N+1 queries, memory leaks, missing caching, hot paths.",
         "Layer 2d: Architecture Fit — does the implementation match the locked design? Coupling, cohesion, interface contracts.",
         "Layer 2e: External Safety — SQL safety, concurrency, secrets in logs, enum completeness (grep outside diff), LLM trust boundaries.",
@@ -1124,7 +1125,7 @@ const REVIEW = {
         "Run Layer 1 (spec compliance) completely before starting Layer 2.",
         "In each review section, present findings ONE AT A TIME. Do NOT batch.",
         "Classify every finding as Critical, Important, or Suggestion.",
-        "For each Critical finding: use the Decision Protocol — present resolution options (A/B/C) with trade-offs and mark one as (recommended). If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
+        "For each Critical finding: use the Decision Protocol — present resolution options (A/B/C) with trade-offs, **score each option `Completeness: X/10`** (10 = fully closes the finding with no carry-over risk; subtract for partial fixes, deferred follow-ups, or new risk introduced), and mark one as (recommended). Prefer the highest-scoring option; if scores tie, prefer the option with the smallest blast radius. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
         "Resolve all critical blockers before ship.",
         "For final verdict: use AskQuestion/AskUserQuestion only if runtime schema is confirmed; otherwise collect verdict with a plain-text single-choice prompt (APPROVED / APPROVED_WITH_CONCERNS / BLOCKED).",
         "**STOP.** Do NOT proceed to ship until the user provides an explicit verdict."
@@ -1147,7 +1148,9 @@ const REVIEW = {
         { id: "review_layer2_architecture", description: "Architecture fit review completed." },
         { id: "review_severity_classified", description: "All findings are severity-tagged." },
         { id: "review_criticals_resolved", description: "No unresolved critical blockers remain." },
-        { id: "review_army_json_valid", description: "07-review-army.json passes schema validation (validateReviewArmy)." }
+        { id: "review_army_json_valid", description: "07-review-army.json passes schema validation (validateReviewArmy)." },
+        { id: "review_completeness_scored", description: "Completeness score is computed and recorded (AC coverage, task coverage, slice coverage, adversarial pass)." },
+        { id: "review_security_audit_swept", description: "The security-audit utility skill was run against the diff scope and the modules it touches. Finding count (0 if clean) recorded in the review army with file:line evidence for every Critical." }
     ],
     requiredEvidence: [
         "Artifact written to `.cclaw/artifacts/07-review.md`.",
@@ -1288,7 +1291,8 @@ const REVIEW = {
         { section: "Layer 1 Verdict", required: true, validationRule: "Per-criterion pass/fail with references." },
         { section: "Layer 2 Findings", required: true, validationRule: "Each finding has severity, description, and resolution status." },
         { section: "Review Army Contract", required: true, validationRule: "Structured findings include id/severity/confidence/fingerprint/reportedBy/status with dedup reconciliation summary." },
-        { section: "Review Readiness Dashboard", required: true, validationRule: "At least 4 readiness checklist lines including blocker and recommendation status." },
+        { section: "Review Readiness Dashboard", required: true, validationRule: "Includes a per-pass table (Layer 1 / Layer 2 / Adversarial / Schema) with a 'Completed at' column, a Delegation log snapshot block (path .cclaw/state/delegation-log.json with required/completed/waived/pending), a Staleness signal block (commit at last review pass and current commit), and a Headline with open critical blockers + ship recommendation. At minimum, the section text must contain the substrings 'Completed at', 'delegation-log.json', 'commit at last review pass', and 'Ship recommendation'." },
+        { section: "Completeness Score", required: true, validationRule: "Records AC coverage, task coverage, test-slice coverage, and adversarial-review pass status as numeric or boolean values. At minimum, a line like 'AC coverage: N/M' or 'AC coverage: 100%'." },
         { section: "Severity Summary", required: true, validationRule: "Per-severity count lines for critical, important, and suggestion buckets." },
         { section: "Final Verdict", required: true, validationRule: "Exactly one of: APPROVED, APPROVED_WITH_CONCERNS, BLOCKED." }
     ],
@@ -1332,7 +1336,7 @@ const SHIP = {
     interactionProtocol: [
         "Run preflight checks before any release action.",
         "Document release notes and rollback plan explicitly.",
-        "For finalization mode: use the Decision Protocol — present modes as labeled options (A/B/C/D) with consequences and mark one as (recommended). If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
+        "For finalization mode: use the Decision Protocol — present modes as labeled options (A/B/C/D) with consequences, **score each option `Completeness: X/10`** (10 = fully addresses release blast-radius, rollback readiness, observability, and stakeholder communication), and mark one as (recommended). Prefer the highest-scoring option; if scores tie, prefer the most reversible one. If AskQuestion/AskUserQuestion is available, send exactly ONE question per call, validate fields against runtime schema, and on schema error immediately fall back to plain-text question instead of retrying guessed payloads.",
         "Do not proceed if critical blockers remain from review.",
         "**STOP.** Present finalization options and wait for user selection before executing any finalization action."
     ],
@@ -1450,7 +1454,8 @@ const SHIP = {
         { section: "Rollback Plan", required: true, validationRule: "Trigger conditions, rollback steps (exact commands), verification steps." },
         { section: "Monitoring", required: false, validationRule: "If applicable: what metrics/logs to watch post-deploy. Risk note if no monitoring." },
         { section: "Finalization", required: true, validationRule: "Exactly one finalization enum token selected. Execution result documented. Worktree cleaned if applicable." },
-        { section: "Completion Status", required: false, validationRule: "If present: exactly one of SHIPPED, SHIPPED_WITH_EXCEPTIONS, BLOCKED. Exceptions documented when applicable." }
+        { section: "Completion Status", required: false, validationRule: "If present: exactly one of SHIPPED, SHIPPED_WITH_EXCEPTIONS, BLOCKED. Exceptions documented when applicable." },
+        { section: "Compound Step", required: false, validationRule: "Optional retrospective: at least one bullet of the form 'Insight: ... | Action: append [compound] entry to .cclaw/knowledge.md', or an explicit 'No compound insight this run.' line." }
     ],
     namedAntiPattern: {
         title: "Green CI Means Safe to Merge",
@@ -1512,6 +1517,13 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "When acceptance criteria are unclear or constraints conflict.",
             purpose: "Normalize measurable criteria and testability mapping.",
             requiresUserGate: false
+        },
+        {
+            agent: "spec-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.",
+            requiresUserGate: false
         }
     ],
     plan: [
@@ -1558,8 +1570,18 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             agent: "security-reviewer",
             mode: "mandatory",
             when: "Always in review stage. Even when no trust boundaries changed, produce an explicit 'no-change' security attestation.",
-            purpose: "Guarantee a dedicated security pass on every diff: auth, input validation, secrets, injection, privilege, and blast-radius review are never opt-in.",
-            requiresUserGate: false
+            purpose: "Guarantee a dedicated security pass on every diff: auth, input validation, secrets, injection, privilege, and blast-radius review are never opt-in. MUST load the `security-audit` skill and run a pattern-based sweep across the diff scope and touched modules in addition to the per-diff Layer 2 security checklist.",
+            requiresUserGate: false,
+            skill: "security-audit"
+        },
+        {
+            agent: "code-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.",
+            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"
         }
     ],
     ship: [
@@ -1585,6 +1607,10 @@ export function mandatoryDelegationsForStage(stage) {
         .filter((d) => d.mode === "mandatory")
         .map((d) => d.agent);
 }
+/** Conditional dispatches that become mandatory only when their `condition` predicate evaluates true. */
+export function conditionalDispatchesForStage(stage) {
+    return STAGE_AUTO_SUBAGENT_DISPATCH[stage].filter((d) => d.mode === "conditional");
+}
 export function stageSchema(stage) {
     const base = STAGE_SCHEMA_MAP[stage];
     return {

package/dist/content/start-command.js

@@ -33,10 +33,22 @@ This is the **recommended way to start** working with cclaw. Use \`/cc-next\` fo
 
 1. Read \`${flowPath}\`.
 2. If flow already has completed stages beyond brainstorm, warn the user that starting a new brainstorm will reset progress. Ask for confirmation before proceeding.
-3. Write the prompt to \`.cclaw/artifacts/00-idea.md\` as the raw idea capture.
-4. Set \`currentStage: "brainstorm"\` in flow state (reset if needed).
-5. Load \`.cclaw/skills/brainstorming/SKILL.md\` and \`.cclaw/commands/brainstorm.md\`.
-6. Execute brainstorm with the prompt as initial context.
+3. **Track heuristic** — classify the idea text and **recommend** a track (the user can override before any state mutation):
+   - **quick** (\`spec → tdd → review → ship\`) — single-purpose work where the spec is essentially already known.
+     Triggers (case-insensitive substring or close variant): \`bug\`, \`bugfix\`, \`fix\`, \`hotfix\`, \`patch\`, \`typo\`, \`regression\`, \`copy change\`, \`rename\`, \`bump\`, \`upgrade dep\`, \`config tweak\`, \`docs only\`, \`comment\`, \`lint\`, \`format\`, \`small\`, \`tiny\`, \`one-liner\`, \`revert\`.
+   - **standard** (full 8 stages — default) — anything that introduces a new capability, touches multiple modules, or has unclear scope.
+     Triggers: \`new feature\`, \`add\`, \`build\`, \`design\`, \`refactor\`, \`migration\`, \`platform\`, \`architecture\`, \`endpoint\`, \`schema\`, \`api\`, \`integrate\`, \`workflow\`, \`onboarding\`, or any prompt that does not match quick triggers.
+   - When triggers conflict (e.g. "small refactor that touches 5 modules") prefer **standard** — quick is opt-in and only safe when scope is genuinely tiny.
+4. Present the recommendation as a single decision with explicit options:
+   > \`Recommended track: <quick|standard>\` because \`<one-line reason citing matched triggers>\`.
+   > Override? (A) keep \`<recommended>\`  (B) switch to \`<other>\`  (C) cancel.
+   If \`AskQuestion\`/\`AskUserQuestion\` is available, send exactly ONE question; on schema error, fall back to plain text.
+5. Persist the chosen track to \`${flowPath}\` (\`track\` field). Compute \`skippedStages\` from the track and write that too. Use the **first stage of the chosen track** as \`currentStage\` (quick → \`spec\`, standard → \`brainstorm\`).
+6. Write the prompt to \`.cclaw/artifacts/00-idea.md\` as the raw idea capture, and append a \`Track:\` line referencing the chosen track and the matched heuristic.
+7. Load the **first-stage skill for the chosen track** and its command file:
+   - quick → \`.cclaw/skills/specification-authoring/SKILL.md\` + \`.cclaw/commands/spec.md\`
+   - standard → \`.cclaw/skills/brainstorming/SKILL.md\` + \`.cclaw/commands/brainstorm.md\`
+8. Execute that stage with the prompt as initial context.
 
 ### Without prompt (\`/cc\`)
 
@@ -81,9 +93,20 @@ Do **not** silently discard an existing flow when the user provides a prompt. If
    - Inform: "You have an active flow at stage **{currentStage}** with {N} completed stages. Starting a new brainstorm will reset progress."
    - Ask: "Continue with reset? (A) Yes, start fresh (B) No, resume current flow"
    - If (B) → switch to Path B behavior.
-3. Write \`${RUNTIME_ROOT}/artifacts/00-idea.md\` with the user's prompt.
-4. Update \`${flowPath}\`: set \`currentStage: "brainstorm"\`, clear \`completedStages\`, reset gate catalog.
-5. Load and execute: \`${RUNTIME_ROOT}/skills/brainstorming/SKILL.md\` + \`${RUNTIME_ROOT}/commands/brainstorm.md\`.
+3. **Classify the idea** using the heuristic below and present a single track recommendation. Wait for explicit confirmation or override before mutating any state.
+
+   **Track heuristic** (lowercase substring match against the user prompt):
+
+   | Track | Triggers | Use when |
+   |---|---|---|
+   | \`quick\` | \`bug\`, \`bugfix\`, \`fix\`, \`hotfix\`, \`patch\`, \`typo\`, \`regression\`, \`rename\`, \`bump\`, \`upgrade dep\`, \`docs only\`, \`comment\`, \`lint\`, \`format\`, \`small\`, \`tiny\`, \`one-liner\`, \`revert\`, \`copy change\` | Single-purpose, spec is essentially known, low blast radius |
+   | \`standard\` | \`new feature\`, \`add\`, \`build\`, \`design\`, \`refactor\`, \`migration\`, \`platform\`, \`architecture\`, \`endpoint\`, \`schema\`, \`api\`, \`integrate\`, \`workflow\`, \`onboarding\` (or no quick trigger matched) | Anything new, multi-module, or unclear scope |
+
+   - On conflict, prefer \`standard\` (quick is opt-in for genuinely tiny work).
+   - Always state the recommendation as a one-line reason citing the matched trigger.
+4. Persist the chosen track in \`${flowPath}\` (\`track\` + \`skippedStages\`). Set \`currentStage\` to the first stage of the chosen track (\`quick\` → \`spec\`, \`standard\` → \`brainstorm\`). Reset gate catalog.
+5. Write \`${RUNTIME_ROOT}/artifacts/00-idea.md\` with the user's prompt and an explicit \`Track:\` line capturing the heuristic decision.
+6. Load and execute the **first stage skill of the chosen track** (\`brainstorming\` for standard, \`specification-authoring\` for quick) plus its matching command file.
 
 ### Path B: \`/cc\` (no arguments)
 

package/dist/content/status-command.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Command contract for /cc-status — a read-only snapshot command.
+ * Does not mutate state. Always safe to run.
+ */
+export declare function statusCommandContract(): string;
+/**
+ * Skill body for /cc-status — read-only status snapshot.
+ */
+export declare function statusCommandSkillMarkdown(): string;