cclaw-cli 0.6.0 → 0.7.0

package/dist/cli.d.ts

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-import type { FlowTrack, HarnessId } from "./types.js";
+import type { FlowTrack, HarnessId, InitProfile } from "./types.js";
 type CommandName = "init" | "sync" | "doctor" | "upgrade" | "uninstall" | "archive";
 interface ParsedArgs {
     command?: CommandName;
     harnesses?: HarnessId[];
     track?: FlowTrack;
+    profile?: InitProfile;
     reconcileGates?: boolean;
     archiveName?: string;
     showHelp?: boolean;
@@ -13,5 +14,6 @@ interface ParsedArgs {
 export declare function usage(): string;
 declare function parseHarnesses(raw: string): HarnessId[];
 declare function parseTrack(raw: string): FlowTrack;
+declare function parseProfile(raw: string): InitProfile;
 declare function parseArgs(argv: string[]): ParsedArgs;
-export { parseArgs, parseHarnesses, parseTrack };
+export { parseArgs, parseHarnesses, parseTrack, parseProfile };

package/dist/cli.js

@@ -3,11 +3,12 @@ import { readFileSync, realpathSync } from "node:fs";
 import process from "node:process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { FLOW_TRACKS, HARNESS_IDS } from "./types.js";
+import { FLOW_TRACKS, HARNESS_IDS, INIT_PROFILES } from "./types.js";
 import { doctorChecks, doctorSucceeded } from "./doctor.js";
 import { initCclaw, syncCclaw, uninstallCclaw, upgradeCclaw } from "./install.js";
 import { error, info } from "./logger.js";
 import { archiveRun } from "./runs.js";
+import { RUNTIME_ROOT } from "./constants.js";
 const INSTALLER_COMMANDS = ["init", "sync", "doctor", "upgrade", "uninstall", "archive"];
 export function usage() {
     return `cclaw - installer-first flow toolkit
@@ -19,8 +20,9 @@ Usage:
 
 Commands:
   init       Bootstrap .cclaw runtime, state, and harness shims in this project.
-             Flags: --harnesses=<list>  Comma list of harnesses (claude,cursor,opencode,codex).
-                    --track=<id>        Flow track for new runs (standard | quick). Default: standard.
+             Flags: --profile=<id>      Pre-fill defaults. One of: minimal | standard | full. Default: standard.
+                    --harnesses=<list>  Comma list of harnesses (claude,cursor,opencode,codex). Overrides the profile default.
+                    --track=<id>        Flow track for new runs (standard | quick). Overrides the profile default.
   sync       Regenerate harness shim files from the current .cclaw config (non-destructive).
   doctor     Run health checks against the local .cclaw runtime. Exit code 2 on failure.
              Flags: --reconcile-gates   Recompute current-stage gate evidence before checks.
@@ -85,6 +87,13 @@ function parseTrack(raw) {
     }
     return trimmed;
 }
+function parseProfile(raw) {
+    const trimmed = raw.trim();
+    if (!INIT_PROFILES.includes(trimmed)) {
+        throw new Error(`Unknown profile: ${trimmed}. Supported: ${INIT_PROFILES.join(", ")}`);
+    }
+    return trimmed;
+}
 function parseArgs(argv) {
     const parsed = {};
     const helpFlag = argv.find((arg) => arg === "--help" || arg === "-h");
@@ -108,6 +117,10 @@ function parseArgs(argv) {
             parsed.track = parseTrack(flag.replace("--track=", ""));
             continue;
         }
+        if (flag.startsWith("--profile=")) {
+            parsed.profile = parseProfile(flag.replace("--profile=", ""));
+            continue;
+        }
         if (flag === "--reconcile-gates") {
             parsed.reconcileGates = true;
             continue;
@@ -136,10 +149,13 @@ async function runCommand(parsed, ctx) {
         await initCclaw({
             projectRoot: ctx.cwd,
             harnesses: parsed.harnesses,
-            track: parsed.track
+            track: parsed.track,
+            profile: parsed.profile
         });
-        const trackNote = parsed.track ? ` (track: ${parsed.track})` : "";
-        info(ctx, `Initialized .cclaw runtime and generated harness shims${trackNote}`);
+        const profileNote = parsed.profile ? ` profile=${parsed.profile}` : "";
+        const trackNote = parsed.track ? ` track=${parsed.track}` : "";
+        const suffix = profileNote || trackNote ? ` (${(profileNote + trackNote).trim()})` : "";
+        info(ctx, `Initialized .cclaw runtime and generated harness shims${suffix}`);
         return 0;
     }
     if (command === "sync") {
@@ -167,6 +183,16 @@ async function runCommand(parsed, ctx) {
             ? ` Snapshotted ${archived.snapshottedStateFiles.length} state file(s) under ${archived.archivePath}/state and wrote archive-manifest.json.`
             : "";
         info(ctx, `Archived active artifacts to ${archived.archivePath}. Flow state reset to brainstorm.${snapshotSummary}`);
+        const k = archived.knowledge;
+        if (k.overThreshold) {
+            info(ctx, `Knowledge curation recommended: ${k.knowledgePath} now has ${k.activeEntryCount} active entries (soft threshold ${k.softThreshold}). Run \`/cc-learn curate\` to plan a soft-archive of stale/duplicate entries to ${RUNTIME_ROOT}/knowledge.archive.md.`);
+        }
+        else if (k.activeEntryCount > 0) {
+            info(ctx, `Knowledge: ${k.activeEntryCount}/${k.softThreshold} active entries. Run \`/cc-learn curate\` if you want a sweep before the next run.`);
+        }
+        else {
+            info(ctx, `Knowledge: 0 active entries in ${k.knowledgePath}. Capture lessons from this run with \`/cc-learn add\` before they fade.`);
+        }
         return 0;
     }
     await uninstallCclaw(ctx.cwd);
@@ -204,4 +230,4 @@ function isDirectExecution() {
 if (isDirectExecution()) {
     void main();
 }
-export { parseArgs, parseHarnesses, parseTrack };
+export { parseArgs, parseHarnesses, parseTrack, parseProfile };

package/dist/config.d.ts

@@ -1,5 +1,15 @@
-import type { FlowTrack, HarnessId, VibyConfig } from "./types.js";
+import type { FlowTrack, HarnessId, InitProfile, LanguageRulePack, VibyConfig } from "./types.js";
 export declare function configPath(projectRoot: string): string;
 export declare function createDefaultConfig(harnesses?: HarnessId[], defaultTrack?: FlowTrack): VibyConfig;
+/**
+ * Build a VibyConfig for a named init profile. Profile defaults are applied
+ * first, then any explicit overrides (CLI flags) win. This keeps the profile
+ * contract deterministic and testable.
+ */
+export declare function createProfileConfig(profile: InitProfile, overrides?: {
+    harnesses?: HarnessId[];
+    defaultTrack?: FlowTrack;
+    languageRulePacks?: LanguageRulePack[];
+}): VibyConfig;
 export declare function readConfig(projectRoot: string): Promise<VibyConfig>;
 export declare function writeConfig(projectRoot: string, config: VibyConfig): Promise<void>;

package/dist/config.js

@@ -3,12 +3,14 @@ import path from "node:path";
 import { parse, stringify } from "yaml";
 import { CCLAW_VERSION, DEFAULT_HARNESSES, FLOW_VERSION, RUNTIME_ROOT } from "./constants.js";
 import { exists, writeFileSafe } from "./fs-utils.js";
-import { FLOW_TRACKS, HARNESS_IDS } from "./types.js";
+import { FLOW_TRACKS, HARNESS_IDS, LANGUAGE_RULE_PACKS } from "./types.js";
 const CONFIG_PATH = `${RUNTIME_ROOT}/config.yaml`;
 const HARNESS_ID_SET = new Set(HARNESS_IDS);
 const FLOW_TRACK_SET = new Set(FLOW_TRACKS);
+const LANGUAGE_RULE_PACK_SET = new Set(LANGUAGE_RULE_PACKS);
 const SUPPORTED_HARNESSES_TEXT = HARNESS_IDS.join(", ");
 const SUPPORTED_TRACKS_TEXT = FLOW_TRACKS.join(", ");
+const SUPPORTED_LANGUAGE_RULE_PACKS_TEXT = LANGUAGE_RULE_PACKS.join(", ");
 const ALLOWED_CONFIG_KEYS = new Set([
     "version",
     "flowVersion",
@@ -16,7 +18,8 @@ const ALLOWED_CONFIG_KEYS = new Set([
     "autoAdvance",
     "promptGuardMode",
     "gitHookGuards",
-    "defaultTrack"
+    "defaultTrack",
+    "languageRulePacks"
 ]);
 function configFixExample() {
     return `harnesses:
@@ -27,6 +30,7 @@ function configValidationError(configFilePath, reason) {
     return new Error(`Invalid cclaw config at ${configFilePath}: ${reason}\n` +
         `Supported harnesses: ${SUPPORTED_HARNESSES_TEXT}\n` +
         `Supported tracks: ${SUPPORTED_TRACKS_TEXT}\n` +
+        `Supported languageRulePacks: ${SUPPORTED_LANGUAGE_RULE_PACKS_TEXT}\n` +
         `Example config:\n${configFixExample()}\n` +
         `After fixing, run: cclaw sync`);
 }
@@ -41,9 +45,50 @@ export function createDefaultConfig(harnesses = DEFAULT_HARNESSES, defaultTrack
         autoAdvance: false,
         promptGuardMode: "advisory",
         gitHookGuards: false,
-        defaultTrack
+        defaultTrack,
+        languageRulePacks: []
     };
 }
+/**
+ * Build a VibyConfig for a named init profile. Profile defaults are applied
+ * first, then any explicit overrides (CLI flags) win. This keeps the profile
+ * contract deterministic and testable.
+ */
+export function createProfileConfig(profile, overrides = {}) {
+    const base = createDefaultConfig();
+    switch (profile) {
+        case "minimal":
+            return {
+                ...base,
+                harnesses: overrides.harnesses ?? ["claude"],
+                autoAdvance: false,
+                promptGuardMode: "advisory",
+                gitHookGuards: false,
+                defaultTrack: overrides.defaultTrack ?? "quick",
+                languageRulePacks: overrides.languageRulePacks ?? []
+            };
+        case "standard":
+            return {
+                ...base,
+                harnesses: overrides.harnesses ?? DEFAULT_HARNESSES,
+                autoAdvance: false,
+                promptGuardMode: "advisory",
+                gitHookGuards: false,
+                defaultTrack: overrides.defaultTrack ?? "standard",
+                languageRulePacks: overrides.languageRulePacks ?? []
+            };
+        case "full":
+            return {
+                ...base,
+                harnesses: overrides.harnesses ?? DEFAULT_HARNESSES,
+                autoAdvance: false,
+                promptGuardMode: "strict",
+                gitHookGuards: true,
+                defaultTrack: overrides.defaultTrack ?? "standard",
+                languageRulePacks: overrides.languageRulePacks ?? [...LANGUAGE_RULE_PACKS]
+            };
+    }
+}
 export async function readConfig(projectRoot) {
     const fullPath = configPath(projectRoot);
     if (!(await exists(fullPath))) {
@@ -102,6 +147,20 @@ export async function readConfig(projectRoot) {
     const defaultTrack = typeof defaultTrackRaw === "string" && FLOW_TRACK_SET.has(defaultTrackRaw)
         ? defaultTrackRaw
         : "standard";
+    const languageRulePacksRaw = parsed.languageRulePacks;
+    const hasLanguageRulePacksField = Object.prototype.hasOwnProperty.call(parsed, "languageRulePacks");
+    if (hasLanguageRulePacksField && !Array.isArray(languageRulePacksRaw)) {
+        throw configValidationError(fullPath, `"languageRulePacks" must be an array`);
+    }
+    const rawPacks = (languageRulePacksRaw ?? []);
+    const invalidPacks = rawPacks.filter((pack) => typeof pack !== "string" || !LANGUAGE_RULE_PACK_SET.has(pack));
+    if (invalidPacks.length > 0) {
+        const formatted = invalidPacks
+            .map((item) => (typeof item === "string" ? item : JSON.stringify(item)))
+            .join(", ");
+        throw configValidationError(fullPath, `unknown languageRulePacks id(s): ${formatted}`);
+    }
+    const languageRulePacks = [...new Set(rawPacks)];
     return {
         version: parsed.version ?? CCLAW_VERSION,
         flowVersion: parsed.flowVersion ?? FLOW_VERSION,
@@ -109,7 +168,8 @@ export async function readConfig(projectRoot) {
         autoAdvance,
         promptGuardMode,
         gitHookGuards,
-        defaultTrack
+        defaultTrack,
+        languageRulePacks
     };
 }
 export async function writeConfig(projectRoot, config) {

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,9 +15,14 @@ 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
@@ -24,9 +30,9 @@ Use it to keep durable knowledge that should survive sessions:
 
 ## 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
@@ -39,12 +45,49 @@ Under \`/cc-learn\`, only modify the knowledge store (\`${KNOWLEDGE_PATH}\`) or
 - 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\`, \`compound\` (lowercase).
-- Never rewrite history silently; append a newer correction entry instead. To replace, prefix the new entry with \`Supersedes: <old-title>\`.
+- 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:
@@ -61,18 +104,24 @@ See the **knowledge-curation** utility skill for the full curation protocol.
 - 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\`.
-- Optionally ask for: \`confidence\`, \`domain\`, \`project\`.
-- 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}\` without an explicit user-approved 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() {
@@ -80,19 +129,22 @@ 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\` / \`compound\`. |
+| (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. |
 `;
 }
@@ -103,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)"
@@ -114,6 +166,7 @@ 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\`, \`compound\`.

package/dist/content/meta-skill.js

@@ -89,14 +89,37 @@ 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\` with the same frontmatter format as managed skills (\`name\` + \`description\` triggering routing).
-- Activate by mentioning the skill name explicitly, or rely on semantic routing from the description.
+- 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.
@@ -129,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/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."
@@ -1148,7 +1149,8 @@ const REVIEW = {
         { 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_completeness_scored", description: "Completeness score is computed and recorded (AC coverage, task coverage, slice coverage, adversarial pass)." }
+        { 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`.",
@@ -1289,7 +1291,7 @@ 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." }
@@ -1334,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."
     ],
@@ -1568,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: [
@@ -1595,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 {