cclaw-cli 0.46.15 → 0.48.0

package/README.md

@@ -174,7 +174,7 @@ inside `/cc-ops` subcommands.
 |---|---|
 | **`/cc <idea>`** | Classify the task, discover origin docs (`docs/prd/**`, ADRs, root `PRD.md`, …), sniff the stack, recommend a track, then start the first stage of that track. `/cc` without arguments resumes the current flow. |
 | **`/cc-next`** | The one progression primitive. Reads `flow-state.json`, checks gates + mandatory subagent delegations, and either resumes the current stage or advances to the next. `/cc-next` in a new session is how you **resume**. |
-| **`/cc-ideate`** | Repository improvement discovery. Scans for TODOs, flaky tests, oversized modules, docs drift, and recurring knowledge-store lessons, **persists the ranked backlog** to `.cclaw/artifacts/ideation-<date>-<slug>.md`, and ends with a concrete handoff: launch `/cc` on the selected candidate in the same session, save-and-close, or discard. Resume check on next run reuses any ideation artifact younger than 30 days. Never mutates `flow-state.json`. |
+| **`/cc-ideate`** | Repository improvement ideate mode. Scans for TODOs, flaky tests, oversized modules, docs drift, and recurring knowledge-store lessons, **persists the ranked backlog** to `.cclaw/artifacts/ideate-<date>-<slug>.md`, and ends with a concrete handoff: launch `/cc` on the selected candidate in the same session, save-and-close, or discard. Resume check on next run reuses any ideate artifact younger than 30 days. Never mutates `flow-state.json`. |
 | **`/cc-view`** | Read-only flow visibility. `/cc-view status` (default) shows stage progress, mandatory delegations with their fulfillment mode (isolated / generic-dispatch / role-switch), the ship closeout substate (retro → compound → archive), and the active harness parity row. `/cc-view tree` renders the same picture as a tree with a closeout sub-branch under ship and a per-harness playbook summary. `/cc-view diff` shows stage/gate/closeout/delegation deltas since the last run. Never mutates state (except diff's snapshot baseline). |
 
 > Power-user surface: `/cc-ops` is an operational router for manual
@@ -458,6 +458,8 @@ CCLAW_EVAL_MODEL=glm-5.1                                  # default
 
 Full details, corpus format, and the eval contract live in
 [`docs/evals.md`](./docs/evals.md).
+Mutation-testing setup lives in `stryker.config.mjs` and
+`.github/workflows/mutation.yml` (manual + weekly run).
 
 ---
 

package/dist/artifact-linter.d.ts

@@ -58,9 +58,16 @@ export interface ReviewVerdictConsistencyResult {
     openCriticalCount: number;
     shipBlockerCount: number;
 }
+export interface ReviewSecurityNoChangeAttestationResult {
+    ok: boolean;
+    errors: string[];
+    hasSecurityFinding: boolean;
+    hasNoChangeAttestation: boolean;
+}
 /**
  * Ensure the narrative verdict in 07-review.md is consistent with the
  * structured review-army reconciliation. A review cannot declare
  * APPROVED while open Critical findings or shipBlockers remain.
  */
 export declare function checkReviewVerdictConsistency(projectRoot: string): Promise<ReviewVerdictConsistencyResult>;
+export declare function checkReviewSecurityNoChangeAttestation(projectRoot: string): Promise<ReviewSecurityNoChangeAttestationResult>;

package/dist/artifact-linter.js

@@ -12,25 +12,52 @@ async function resolveArtifactPath(projectRoot, fileName) {
 function normalizeHeadingTitle(title) {
     return title.trim().replace(/\s+/g, " ");
 }
-/** Collect H2 sections and body content (`## Section Name`). */
+/**
+ * Collect H2 sections and body content (`## Section Name`).
+ *
+ * - Ignores lines that live inside fenced code blocks (``` / ~~~) so a
+ *   commented `## Approaches` inside an example doesn't open a phantom
+ *   section and swallow real content.
+ * - When the same heading appears more than once at the top level we
+ *   concatenate the bodies rather than silently overwriting the earlier
+ *   occurrence. This keeps lint rules honest when authors split a section
+ *   into multiple passes.
+ */
 function extractH2Sections(markdown) {
     const sections = new Map();
     const lines = markdown.split(/\r?\n/);
     let currentHeading = null;
     let buffer = [];
+    let fenced = null;
     const flush = () => {
         if (currentHeading === null)
             return;
-        sections.set(currentHeading, buffer.join("\n"));
+        const existing = sections.get(currentHeading);
+        const body = buffer.join("\n");
+        sections.set(currentHeading, existing === undefined ? body : `${existing}\n${body}`);
     };
     for (const line of lines) {
-        const match = /^##\s+(.+)$/u.exec(line);
-        if (match) {
-            flush();
-            currentHeading = normalizeHeadingTitle(match[1] ?? "");
-            buffer = [];
+        const fenceMatch = /^(```|~~~)/u.exec(line);
+        if (fenceMatch) {
+            if (fenced === null) {
+                fenced = fenceMatch[1] ?? null;
+            }
+            else if (line.startsWith(fenced)) {
+                fenced = null;
+            }
+            if (currentHeading !== null)
+                buffer.push(line);
             continue;
         }
+        if (fenced === null) {
+            const match = /^##\s+(.+)$/u.exec(line);
+            if (match) {
+                flush();
+                currentHeading = normalizeHeadingTitle(match[1] ?? "");
+                buffer = [];
+                continue;
+            }
+        }
         if (currentHeading !== null) {
             buffer.push(line);
         }
@@ -869,6 +896,49 @@ export async function lintArtifact(projectRoot, stage) {
             details: learnings.details
         });
     }
+    if (stage === "brainstorm") {
+        // Brainstorm Iron Law: "NO ARTIFACT IS COMPLETE WITHOUT AN EXPLICITLY
+        // APPROVED DIRECTION — SILENCE IS NOT APPROVAL." Previously this was
+        // prose-only — nothing failed when the Selected Direction section
+        // omitted an approval marker, or when the Approaches table collapsed
+        // to a single row (defeating the "2-3 distinct approaches" gate).
+        const approachesBody = sectionBodyByName(sections, "Approaches");
+        if (approachesBody !== null) {
+            const tableRows = approachesBody
+                .split(/\r?\n/u)
+                .map((line) => line.trim())
+                .filter((line) => line.startsWith("|"))
+                .filter((line) => !/^\|\s*[-: |]+\|\s*$/u.test(line))
+                .filter((line) => !/^\|\s*approach\b/iu.test(line));
+            const bulletRows = approachesBody
+                .split(/\r?\n/u)
+                .map((line) => line.trim())
+                .filter((line) => /^(?:[-*]|\d+\.)\s+\S/u.test(line));
+            const rowCount = Math.max(tableRows.length, bulletRows.length);
+            findings.push({
+                section: "Distinct Approaches Enforcement",
+                required: true,
+                rule: "Approaches section must document at least 2 distinct approaches so the Iron Law comparison is meaningful.",
+                found: rowCount >= 2,
+                details: rowCount >= 2
+                    ? `Detected ${rowCount} approach row(s).`
+                    : `Detected ${rowCount} approach row(s); at least 2 required.`
+            });
+        }
+        const directionBody = sectionBodyByName(sections, "Selected Direction");
+        if (directionBody !== null) {
+            const approvalMarker = /\bapprov(?:ed|al)\b/iu.test(directionBody);
+            findings.push({
+                section: "Direction Approval Marker",
+                required: true,
+                rule: "Selected Direction section must state an explicit approval marker (for example `Approval: approved` or `Approved by: user`).",
+                found: approvalMarker,
+                details: approvalMarker
+                    ? "Approval marker present in Selected Direction."
+                    : "No explicit `approved`/`approval` marker found in Selected Direction."
+            });
+        }
+    }
     if (stage === "plan") {
         const strictPlanGuards = parsedFrontmatter.hasFrontmatter ||
             headingPresent(sections, "No-Placeholder Scan") ||
@@ -914,12 +984,13 @@ export async function lintArtifact(projectRoot, stage) {
         });
     }
     if (stage === "scope") {
+        const lockedDecisionsBody = sectionBodyByName(sections, "Locked Decisions (D-XX)") ?? "";
         const strictScopeGuards = parsedFrontmatter.hasFrontmatter ||
             headingPresent(sections, "Locked Decisions (D-XX)");
         const scopeSections = [
             sectionBodyByName(sections, "In Scope / Out of Scope") ?? "",
             sectionBodyByName(sections, "Scope Summary") ?? "",
-            sectionBodyByName(sections, "Locked Decisions (D-XX)") ?? ""
+            lockedDecisionsBody
         ].join("\n");
         const reductionHits = collectPatternHits(scopeSections, SCOPE_REDUCTION_PATTERNS);
         findings.push({
@@ -931,6 +1002,45 @@ export async function lintArtifact(projectRoot, stage) {
                 ? "No scope-reduction phrases detected in scope boundary sections."
                 : `Detected scope-reduction phrase(s): ${reductionHits.join(", ")}.`
         });
+        // When the Locked Decisions section is present we must enforce the
+        // D-XX ID contract at runtime (previously this was prose-only in the
+        // artifactValidation rule). Empty body, missing IDs, and duplicate
+        // IDs all fail the lint; absence of the section remains advisory so
+        // scope stays optional for small/quick tracks.
+        if (headingPresent(sections, "Locked Decisions (D-XX)")) {
+            const decisionIds = extractDecisionIds(lockedDecisionsBody);
+            const bulletLines = lockedDecisionsBody
+                .split(/\r?\n/u)
+                .map((line) => line.trim())
+                .filter((line) => /^(?:[-*]|\|)\s+\S/u.test(line));
+            const orphanBullets = bulletLines.filter((line) => !/\bD-\d+\b/u.test(line));
+            const duplicateIds = (() => {
+                const all = lockedDecisionsBody.match(/\bD-\d+\b/gu) ?? [];
+                const counts = new Map();
+                for (const id of all)
+                    counts.set(id, (counts.get(id) ?? 0) + 1);
+                return [...counts.entries()].filter(([, n]) => n > 1).map(([id]) => id);
+            })();
+            const issues = [];
+            if (decisionIds.length === 0 && bulletLines.length === 0) {
+                issues.push("section is empty");
+            }
+            if (orphanBullets.length > 0) {
+                issues.push(`${orphanBullets.length} bullet(s) missing a D-XX ID`);
+            }
+            if (duplicateIds.length > 0) {
+                issues.push(`duplicate IDs: ${duplicateIds.join(", ")}`);
+            }
+            findings.push({
+                section: "Locked Decisions ID Integrity",
+                required: true,
+                rule: "Locked Decisions section must list each decision with a unique stable D-XX ID.",
+                found: issues.length === 0,
+                details: issues.length === 0
+                    ? `${decisionIds.length} decision ID(s) recorded with no duplicates.`
+                    : issues.join("; ")
+            });
+        }
     }
     const passed = findings.every((f) => !f.required || f.found);
     return { stage, file: relFile, passed, findings };
@@ -1198,6 +1308,14 @@ export async function checkReviewVerdictConsistency(projectRoot) {
     if (finalVerdict === "APPROVED" && (openCriticalCount > 0 || shipBlockerCount > 0)) {
         errors.push(`Final Verdict is APPROVED but review-army has ${openCriticalCount} open Critical finding(s) and ${shipBlockerCount} shipBlocker(s). Use BLOCKED or APPROVED_WITH_CONCERNS.`);
     }
+    // APPROVED_WITH_CONCERNS is intended for Important/Suggestion findings
+    // the author has accepted. An *open* Critical finding or an active
+    // shipBlocker must route through BLOCKED (review_verdict_blocked gate)
+    // rather than pass as a concession — previously this slipped through.
+    if (finalVerdict === "APPROVED_WITH_CONCERNS" &&
+        (openCriticalCount > 0 || shipBlockerCount > 0)) {
+        errors.push(`Final Verdict is APPROVED_WITH_CONCERNS but review-army has ${openCriticalCount} open Critical finding(s) and ${shipBlockerCount} shipBlocker(s). Resolve them or use BLOCKED.`);
+    }
     return {
         ok: errors.length === 0,
         errors,
@@ -1206,3 +1324,46 @@ export async function checkReviewVerdictConsistency(projectRoot) {
         shipBlockerCount
     };
 }
+export async function checkReviewSecurityNoChangeAttestation(projectRoot) {
+    const reviewMdPath = path.join(projectRoot, RUNTIME_ROOT, "artifacts", "07-review.md");
+    if (!(await exists(reviewMdPath))) {
+        return {
+            ok: true,
+            errors: [],
+            hasSecurityFinding: false,
+            hasNoChangeAttestation: false
+        };
+    }
+    const errors = [];
+    const raw = await fs.readFile(reviewMdPath, "utf8");
+    const sections = extractH2Sections(raw);
+    const securityBody = sectionBodyByName(sections, "Layer 2 Security")
+        ?? sectionBodyByName(sections, "Layer 2b: Security")
+        ?? sectionBodyByName(sections, "Layer 2 Findings");
+    if (!securityBody) {
+        errors.push('07-review.md is missing a Layer 2 security section.');
+        return {
+            ok: false,
+            errors,
+            hasSecurityFinding: false,
+            hasNoChangeAttestation: false
+        };
+    }
+    const securityTableRowPattern = /^\|\s*[^|\n]+\|\s*[^|\n]+\|\s*security\s*\|\s*[^|\n]+\|\s*[^|\n]+\|/imu;
+    const securityBulletPattern = /^[*-]\s+.*\b(?:security|auth|injection|secret|credential|permission)\b/imu;
+    const hasSecurityFinding = securityTableRowPattern.test(securityBody) || securityBulletPattern.test(securityBody);
+    const attestationMatch = /NO_CHANGE_ATTESTATION\s*:\s*(.*)/iu.exec(securityBody);
+    const hasNoChangeAttestation = Boolean(attestationMatch && attestationMatch[1]?.trim().length > 0);
+    if (attestationMatch && attestationMatch[1]?.trim().length === 0) {
+        errors.push("NO_CHANGE_ATTESTATION must include a non-empty rationale.");
+    }
+    if (!hasSecurityFinding && !hasNoChangeAttestation) {
+        errors.push("Layer 2 security evidence missing: include at least one security finding or `NO_CHANGE_ATTESTATION: <reason>`.");
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+        hasSecurityFinding,
+        hasNoChangeAttestation
+    };
+}

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import type { FlowTrack, HarnessId, LanguageRulePack, VibyConfig } from "./types.js";
+import type { CclawConfig, FlowTrack, HarnessId, LanguageRulePack } from "./types.js";
 export declare function configPath(projectRoot: string): string;
 /**
  * Default test-path patterns used by workflow-guard.sh to classify TDD writes.
@@ -20,7 +20,7 @@ export declare const DEFAULT_COMPOUND_RECURRENCE_THRESHOLD = 3;
  * regardless of whether the user wrote `strictness`, the legacy keys, both,
  * or neither.
  */
-export declare function createDefaultConfig(harnesses?: HarnessId[], defaultTrack?: FlowTrack): VibyConfig;
+export declare function createDefaultConfig(harnesses?: HarnessId[], defaultTrack?: FlowTrack): CclawConfig;
 /**
  * Probe common project-root manifests to infer which language rule packs the
  * user would reasonably want. Pure-functional best-effort: any filesystem
@@ -31,9 +31,9 @@ export declare function createDefaultConfig(harnesses?: HarnessId[], defaultTrac
  * never surprise a user who intentionally cleared the list.
  */
 export declare function detectLanguageRulePacks(projectRoot: string): Promise<LanguageRulePack[]>;
-export declare function readConfig(projectRoot: string): Promise<VibyConfig>;
+export declare function readConfig(projectRoot: string): Promise<CclawConfig>;
 /**
- * Fields that live on the populated runtime `VibyConfig` but are considered
+ * Fields that live on the populated runtime `CclawConfig` but are considered
  * "advanced" — we keep them in the in-memory object so downstream callers
  * don't have to branch, but we do **not** write them to `config.yaml` unless
  * the user set them explicitly. Keeps the default template small and honest:
@@ -43,7 +43,7 @@ type AdvancedConfigKey = "promptGuardMode" | "tddEnforcement" | "tddTestGlobs" |
 /**
  * Options controlling the serialisation shape of `config.yaml`.
  *
- * - `"full"` (default): write every field on the `VibyConfig` object that
+ * - `"full"` (default): write every field on the `CclawConfig` object that
  *   isn't `undefined`. Preserves existing shapes and keeps legacy callers
  *   working without migration.
  * - `"minimal"`: write only the user-facing knobs (`MINIMAL_CONFIG_KEYS`)
@@ -60,7 +60,7 @@ export interface WriteConfigOptions {
     mode?: "full" | "minimal";
     advancedKeysPresent?: ReadonlySet<AdvancedConfigKey>;
 }
-export declare function writeConfig(projectRoot: string, config: VibyConfig, options?: WriteConfigOptions): Promise<void>;
+export declare function writeConfig(projectRoot: string, config: CclawConfig, options?: WriteConfigOptions): Promise<void>;
 /**
  * Enumerate which advanced keys are currently set in the on-disk config.
  * Used by `cclaw upgrade` to preserve the user's existing shape — if they

package/dist/config.js

@@ -44,6 +44,22 @@ const MINIMAL_CONFIG_KEYS = [
 ];
 const DEFAULT_SLICE_REVIEW_THRESHOLD = 5;
 const DEFAULT_SLICE_REVIEW_TRACKS = ["standard"];
+const emittedConfigWarnings = new Set();
+function emitConfigWarningOnce(code, message) {
+    const key = `${code}:${message}`;
+    if (emittedConfigWarnings.has(key)) {
+        return;
+    }
+    emittedConfigWarnings.add(key);
+    process.emitWarning(message, { code });
+}
+function sameStringArray(a, b) {
+    if (!a || !b)
+        return false;
+    if (a.length !== b.length)
+        return false;
+    return a.every((value, index) => value === b[index]);
+}
 function configFixExample() {
     return `harnesses:
   - claude
@@ -244,6 +260,12 @@ export async function readConfig(projectRoot) {
         explicitTddTestPathPatterns = validateStringArray(tddRaw.testPathPatterns, "tdd.testPathPatterns", fullPath);
         explicitTddProductionPathPatterns = validateStringArray(tddRaw.productionPathPatterns, "tdd.productionPathPatterns", fullPath);
     }
+    if (tddTestGlobsRaw !== undefined &&
+        explicitTddTestPathPatterns !== undefined &&
+        !sameStringArray(tddTestGlobs, explicitTddTestPathPatterns)) {
+        emitConfigWarningOnce("CCLAW_CONFIG_DEPRECATED_TDD_TEST_GLOBS", `[cclaw] Both "tddTestGlobs" (deprecated) and "tdd.testPathPatterns" are set in ${fullPath}. ` +
+            `Using "tdd.testPathPatterns".`);
+    }
     const resolvedTddTestPathPatterns = [
         ...(explicitTddTestPathPatterns ?? tddTestGlobs ?? DEFAULT_TDD_TEST_PATH_PATTERNS)
     ];

package/dist/constants.d.ts

@@ -15,7 +15,16 @@ export declare const EVALS_CONFIG_PATH = ".cclaw/evals/config.yaml";
 export declare const EVALS_DIRS: readonly [".cclaw/evals", ".cclaw/evals/corpus", ".cclaw/evals/rubrics", ".cclaw/evals/baselines", ".cclaw/evals/reports"];
 export declare const REQUIRED_DIRS: readonly [".cclaw", ".cclaw/commands", ".cclaw/skills", ".cclaw/contexts", ".cclaw/templates", ".cclaw/artifacts", ".cclaw/worktrees", ".cclaw/state", ".cclaw/runs", ".cclaw/rules", ".cclaw/adapters", ".cclaw/agents", ".cclaw/hooks", ".cclaw/custom-skills", ".cclaw/evals", ".cclaw/evals/corpus", ".cclaw/evals/rubrics", ".cclaw/evals/baselines", ".cclaw/evals/reports"];
 export declare const REQUIRED_GITIGNORE_PATTERNS: readonly ["# cclaw generated artifacts", ".cclaw/", "# cclaw evals: user-owned, track in git", "!.cclaw/evals/", "!.cclaw/evals/config.yaml", "!.cclaw/evals/corpus/", "!.cclaw/evals/corpus/**", "!.cclaw/evals/rubrics/", "!.cclaw/evals/rubrics/**", "!.cclaw/evals/baselines/", "!.cclaw/evals/baselines/**", ".claude/commands/cc-*.md", ".claude/commands/cc.md", ".cursor/commands/cc-*.md", ".cursor/commands/cc.md", ".opencode/commands/cc-*.md", ".opencode/commands/cc.md", ".agents/skills/cc/SKILL.md", ".agents/skills/cc-*/SKILL.md", ".claude/hooks/hooks.json", ".cursor/hooks.json", ".codex/hooks.json", ".opencode/plugins/cclaw-plugin.mjs", ".cursor/rules/cclaw-workflow.mdc"];
-export declare const COMMAND_FILE_ORDER: FlowStage[];
+/**
+ * Canonical stage -> skill folder mapping.
+ *
+ * Intentional divergence from stage ids:
+ * - stage ids stay short and flow-oriented (`spec`, `tdd`, `ship`)
+ * - skill folders stay descriptive and user-facing for `.cclaw/skills/*`.
+ *
+ * Keep this map as the single source of truth for generated skill paths.
+ */
+export declare const STAGE_TO_SKILL_FOLDER: Record<FlowStage, string>;
 export declare const UTILITY_COMMANDS: readonly ["learn", "next", "ideate", "view", "status", "tree", "diff", "ops", "feature", "tdd-log", "retro", "compound", "archive", "rewind"];
 export declare const SUBAGENT_SKILL_FOLDERS: readonly ["subagent-dev", "parallel-dispatch"];
 export type UtilityCommand = (typeof UTILITY_COMMANDS)[number];

package/dist/constants.js

@@ -103,16 +103,25 @@ export const REQUIRED_GITIGNORE_PATTERNS = [
     ".opencode/plugins/cclaw-plugin.mjs",
     ".cursor/rules/cclaw-workflow.mdc"
 ];
-export const COMMAND_FILE_ORDER = [
-    "brainstorm",
-    "scope",
-    "design",
-    "spec",
-    "plan",
-    "tdd",
-    "review",
-    "ship"
-];
+/**
+ * Canonical stage -> skill folder mapping.
+ *
+ * Intentional divergence from stage ids:
+ * - stage ids stay short and flow-oriented (`spec`, `tdd`, `ship`)
+ * - skill folders stay descriptive and user-facing for `.cclaw/skills/*`.
+ *
+ * Keep this map as the single source of truth for generated skill paths.
+ */
+export const STAGE_TO_SKILL_FOLDER = {
+    brainstorm: "brainstorming",
+    scope: "scope-shaping",
+    design: "engineering-design-lock",
+    spec: "specification-authoring",
+    plan: "planning-and-task-breakdown",
+    tdd: "test-driven-development",
+    review: "two-layer-review",
+    ship: "shipping-and-handoff"
+};
 export const UTILITY_COMMANDS = [
     "learn",
     "next",

package/dist/content/contracts.d.ts

@@ -1,2 +1,2 @@
 import type { FlowStage } from "../types.js";
-export declare function commandContract(stage: FlowStage): string;
+export declare function stageCommandContract(stage: FlowStage): string;

package/dist/content/contracts.js

@@ -1,6 +1,6 @@
 import { stageSchema } from "./stage-schema.js";
 import { stageSkillFolder } from "./skills.js";
-export function commandContract(stage) {
+export function stageCommandContract(stage) {
     const schema = stageSchema(stage);
     const skillPath = `.cclaw/skills/${stageSkillFolder(stage)}/SKILL.md`;
     const reads = schema.crossStageTrace.readsFrom;

package/dist/content/{harnesses-doc.js → harness-doc.js}

@@ -1,4 +1,5 @@
 import { HARNESS_ADAPTERS, harnessTier } from "../harness-adapters.js";
+import { STAGE_TO_SKILL_FOLDER } from "../constants.js";
 import { HOOK_EVENTS_BY_HARNESS, HOOK_SEMANTIC_EVENTS } from "./hook-events.js";
 import { HARNESS_PLAYBOOKS_DIR, harnessPlaybookFileName } from "./harness-playbooks.js";
 import { HARNESS_TOOL_REFS_DIR } from "./harness-tool-refs.js";
@@ -23,6 +24,15 @@ function tierDescription(tier) {
 }
 export function harnessIntegrationDocMarkdown() {
     const harnesses = Object.keys(HARNESS_ADAPTERS);
+    const stageSkillRows = Object.entries(STAGE_TO_SKILL_FOLDER)
+        .map(([stage, skillFolder]) => `| \`${stage}\` | \`${skillFolder}\` |`)
+        .join("\n");
+    const hookCasingRows = [
+        "| Claude Code | `claude` | PascalCase (`SessionStart`, `PreToolUse`) |",
+        "| Cursor | `cursor` | camelCase (`sessionStart`, `preToolUse`) |",
+        "| OpenCode | `opencode` | camelCase (`sessionStart`, `preToolUse`) |",
+        "| OpenAI Codex | `codex` | PascalCase (`SessionStart`, `PreToolUse`) |"
+    ].join("\n");
     const capabilityRows = harnesses
         .map((harness) => {
         const adapter = HARNESS_ADAPTERS[harness];
@@ -75,6 +85,17 @@ Design-stage research fleet uses the same parity model:
 |---|---|---|---|---|
 ${hookRows}
 
+## Hook event casing
+
+Hook keys are intentionally harness-native and must not be normalized:
+
+| Harness | ID | Event key casing |
+|---|---|---|
+${hookCasingRows}
+
+Use the exact event names from each harness schema. Treating all hooks as one
+shared casing silently breaks generated wiring.
+
 ## Interpretation
 
 - \`tier1\`: full native delegation + structured asks + full hook surface.
@@ -91,7 +112,7 @@ All harnesses receive the same utility commands:
 
 - \`/cc\` - flow entry and resume
 - \`/cc-next\` - stage progression
-- \`/cc-ideate\` - discovery mode for ranked repo-improvement backlog
+- \`/cc-ideate\` - ideate mode for ranked repo-improvement backlog
 - \`/cc-view\` - read-only router for status/tree/diff
 - \`/cc-ops\` - operations router for feature/tdd-log/retro/compound/archive/rewind
 
@@ -112,6 +133,16 @@ Operations subcommands:
 Stage order remains canonical:
 \`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship\`
 
+## Stage -> skill folder mapping
+
+| Stage | Skill folder |
+|---|---|
+${stageSkillRows}
+
+This map is generated from \`src/constants.ts::STAGE_TO_SKILL_FOLDER\` so
+skill-path naming stays explicit and stable even when stage ids differ from
+folder names.
+
 ## Install surfaces
 
 Always generated:

package/dist/content/harness-playbooks.js

@@ -95,9 +95,9 @@ generic dispatcher with a strict role prompt.
 ## Dispatch pattern
 
 1. Pick the mapped \`subagent_type\` from the table above.
-2. Build the \`prompt\` from the cclaw agent contract in
+2. Build the \`prompt\` from the cclaw agent role brief in
    \`.cclaw/agents/<agent>.md\`, prefaced with a single line naming the
-   cclaw role (\`You are the cclaw <agent>. Follow the contract below.\`).
+   cclaw role (\`You are the cclaw <agent>. Follow the role brief below.\`).
 3. Set \`readonly: true\` when the table says yes — Cursor enforces it.
 4. Before dispatch, append a delegation row:
 
@@ -142,7 +142,7 @@ description: "OpenCode has plugin-based dispatch hooks and a native structured-a
 **Fallback: role-switch.** OpenCode exposes tool/session event hooks via a
 plugin but does not provide an isolated subagent worker. cclaw closes the
 delegation gate by role-switching inside the same session: the agent
-announces the role, performs the work against the contract, and records
+announces the role, performs the work against the role brief, and records
 evidence.
 
 **Structured ask: native \`question\` tool.** OpenCode ships a first-class
@@ -168,7 +168,7 @@ artifact decision log. Full mapping:
    > Acting as cclaw **<agent>** per \`.cclaw/agents/<agent>.md\`. No other
    > role may be assumed until the delegation row is closed.
 
-2. Execute the role's contract. Do NOT interleave other roles' work.
+2. Execute the role's brief. Do NOT interleave other roles' work.
 3. Write the result into the stage artifact (e.g. TDD work lands in
    \`.cclaw/artifacts/06-tdd.md\`).
 4. Append a delegation row:

package/dist/content/ideate-command.js

@@ -2,13 +2,13 @@ import { RUNTIME_ROOT } from "../constants.js";
 const IDEATE_SKILL_FOLDER = "flow-ideate";
 const IDEATE_SKILL_NAME = "flow-ideate";
 /**
- * Directory + filename convention for ideation artifacts. These are separate
+ * Directory + filename convention for ideate artifacts. These are separate
  * from stage artifacts (00-..08-*.md) because `/cc-ideate` runs outside the
  * critical-path flow state machine and must not collide with stage numbering.
  */
-const IDEATION_ARTIFACT_GLOB = ".cclaw/artifacts/ideation-*.md";
-const IDEATION_ARTIFACT_PATTERN = ".cclaw/artifacts/ideation-<YYYY-MM-DD-slug>.md";
-const IDEATION_RESUME_WINDOW_DAYS = 30;
+const IDEATE_ARTIFACT_GLOB = ".cclaw/artifacts/ideate-*.md";
+const IDEATE_ARTIFACT_PATTERN = ".cclaw/artifacts/ideate-<YYYY-MM-DD-slug>.md";
+const IDEATE_RESUME_WINDOW_DAYS = 30;
 /**
  * Structured-ask tool list reused across cclaw skills. Kept inline here (small
  * enough) to avoid cross-module coupling; larger stage skills cite the shared
@@ -23,25 +23,25 @@ export function ideateCommandContract() {
 
 ## Purpose
 
-Repository-improvement discovery mode. Generate a ranked backlog of
+Repository-improvement ideate mode. Generate a ranked backlog of
 high-value improvements, persist it as an artifact on disk, and end with
 an explicit handoff — either launch \`/cc\` on a chosen candidate in the
 same session, or save/discard the backlog.
 
 ## HARD-GATE
 
-- Discovery mode only. Never mutate \`.cclaw/state/flow-state.json\`.
+- Ideate mode only. Never mutate \`.cclaw/state/flow-state.json\`.
 - Every recommendation cites evidence from the current repository
   (file path, command output, or knowledge-store entry id).
 - Always write a persisted artifact to
-  \`${IDEATION_ARTIFACT_PATTERN}\`. Chat-only output is not acceptable —
+  \`${IDEATE_ARTIFACT_PATTERN}\`. Chat-only output is not acceptable —
   the next session must be able to resume.
 - Always end with a structured handoff prompt, not an open question.
 
 ## Algorithm
 
-1. **Resume check.** Glob \`${IDEATION_ARTIFACT_GLOB}\`. If any artifact
-   has been modified within the last ${IDEATION_RESUME_WINDOW_DAYS} days,
+1. **Resume check.** Glob \`${IDEATE_ARTIFACT_GLOB}\`. If any artifact
+   has been modified within the last ${IDEATE_RESUME_WINDOW_DAYS} days,
    offer the user: continue that backlog, start fresh, or cancel.
 2. **Scan repo signals:**
    - open TODO/FIXME/XXX/HACK notes,
@@ -54,7 +54,7 @@ same session, or save/discard the backlog.
    per candidate.
 4. **Rank by impact/effort**, recommend the top item.
 5. **Write the artifact** at
-   \`${IDEATION_ARTIFACT_PATTERN}\` using the schema in the skill.
+   \`${IDEATE_ARTIFACT_PATTERN}\` using the schema in the skill.
 6. **Present the handoff prompt** with four concrete options — not A/B/C
    letters. Default = "Start /cc on the top recommendation".
 
@@ -66,7 +66,7 @@ same session, or save/discard the backlog.
 export function ideateCommandSkillMarkdown() {
     return `---
 name: ${IDEATE_SKILL_NAME}
-description: "Repository ideation mode: detect and rank high-leverage improvements, persist a backlog artifact, and hand off to /cc or save/discard."
+description: "Repository ideate mode: detect and rank high-leverage improvements, persist a backlog artifact, and hand off to /cc or save/discard."
 ---
 
 # /cc-ideate
@@ -75,12 +75,12 @@ description: "Repository ideation mode: detect and rank high-leverage improvemen
 
 "Using flow-ideate to identify highest-leverage improvements in this
 repository. Will persist a ranked backlog to
-\`${IDEATION_ARTIFACT_PATTERN}\` and end with an explicit handoff."
+\`${IDEATE_ARTIFACT_PATTERN}\` and end with an explicit handoff."
 
 ## HARD-GATE
 
 - Do not start coding in ideate mode.
-- Do not mutate \`.cclaw/state/flow-state.json\` — ideation sits outside
+- Do not mutate \`.cclaw/state/flow-state.json\` — ideate mode sits outside
   the critical-path flow.
 - Always produce the artifact file on disk before presenting the handoff.
 - Always end with a structured handoff that names the concrete follow-up
@@ -91,12 +91,12 @@ repository. Will persist a ranked backlog to
 ### Phase 0 — Resume check
 
 1. Use the harness's file-glob tool (\`Glob\` pattern
-   \`${IDEATION_ARTIFACT_GLOB}\` or equivalent \`ls\`/\`find\`).
-2. Filter to files modified within the last ${IDEATION_RESUME_WINDOW_DAYS} days.
+   \`${IDEATE_ARTIFACT_GLOB}\` or equivalent \`ls\`/\`find\`).
+2. Filter to files modified within the last ${IDEATE_RESUME_WINDOW_DAYS} days.
 3. If one or more match, present **one** structured ask using the
    harness's native tool (${STRUCTURED_ASK_TOOLS}) with options:
    - **Continue the existing backlog** — read the most-recent
-     ideation-*.md and work from its candidate list; skip re-scanning.
+     ideate-*.md and work from its candidate list; skip re-scanning.
    - **Start a fresh scan** — proceed to Phase 1; the old artifact stays
      on disk for history.
    - **Cancel** — stop; do not scan or write anything.
@@ -137,10 +137,10 @@ Aim for 5–10 candidates. Do not invent candidates without evidence.
 1. Sort by impact/effort ratio; break ties with confidence.
 2. Compute the artifact filename:
    - \`slug\` = first 3–5 words of the top recommendation, lowercase,
-     non-alphanumeric collapsed to \`-\`, trimmed. When ideation is
+     non-alphanumeric collapsed to \`-\`, trimmed. When ideate mode is
      focus-hinted (user passed an argument), use the focus hint instead.
    - \`date\` = today in \`YYYY-MM-DD\` (local time).
-   - Path = \`.cclaw/artifacts/ideation-<date>-<slug>.md\`.
+   - Path = \`.cclaw/artifacts/ideate-<date>-<slug>.md\`.
 3. Use the harness's write-file tool (\`Write\`, \`apply_patch\`, or shell
    \`cat <<EOF > path\`) to create the artifact with this schema:
 
@@ -195,7 +195,7 @@ lettered list with the same four labels. Do not invent extra options.
 - **Start /cc on I-1** or **different candidate:** announce
   "Handing off to /cc <phrase>" and load the \`using-cclaw\` router
   skill. From there, the normal \`/cc\` classification and stage flow
-  takes over. Do not produce a second artifact; the ideation file is
+  takes over. Do not produce a second artifact; the ideate file is
   preserved as the origin document for this run.
 - **Save and close:** reply with the artifact path and stop.
 - **Discard:** delete the artifact file, confirm deletion, stop.

package/dist/content/skills.js

@@ -1,4 +1,4 @@
-import { RUNTIME_ROOT } from "../constants.js";
+import { RUNTIME_ROOT, STAGE_TO_SKILL_FOLDER } from "../constants.js";
 import { STAGE_EXAMPLES_REFERENCE_DIR, stageDomainExamples, stageExamples, stageGoodBadExamples } from "./examples.js";
 import { STAGE_COMMON_GUIDANCE_REL_PATH } from "./stage-common-guidance.js";
 import { stageAutoSubagentDispatch, stageSchema } from "./stage-schema.js";
@@ -295,7 +295,7 @@ After T-3 REFACTOR, before declaring Batch 1 done:
 - The same RED failure reappears after a GREEN change → **escalate** per the 3-attempts rule; do not keep patching.
 `;
 export function stageSkillFolder(stage) {
-    return stageSchema(stage).skillFolder;
+    return STAGE_TO_SKILL_FOLDER[stage];
 }
 export function stageSkillMarkdown(stage, track = "standard") {
     const schema = stageSchema(stage, track);