cclaw-cli 0.47.0 → 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

@@ -1324,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);

package/dist/content/stage-schema.js

@@ -1,7 +1,17 @@
-import { COMMAND_FILE_ORDER } from "../constants.js";
-import { FLOW_TRACKS, TRACK_STAGES } from "../types.js";
+import { FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "../types.js";
+import { STAGE_TO_SKILL_FOLDER } from "../constants.js";
 import { BRAINSTORM, SCOPE, DESIGN, SPEC, PLAN, TDD, REVIEW, SHIP } from "./stages/index.js";
 import { tddStageForTrack } from "./stages/tdd.js";
+const ARTIFACT_STAGE_BY_PATH = {
+    ".cclaw/artifacts/01-brainstorm.md": "brainstorm",
+    ".cclaw/artifacts/02-scope.md": "scope",
+    ".cclaw/artifacts/03-design.md": "design",
+    ".cclaw/artifacts/04-spec.md": "spec",
+    ".cclaw/artifacts/05-plan.md": "plan",
+    ".cclaw/artifacts/06-tdd.md": "tdd",
+    ".cclaw/artifacts/07-review.md": "review",
+    ".cclaw/artifacts/08-ship.md": "ship"
+};
 const REQUIRED_GATE_IDS = {
     brainstorm: [
         "brainstorm_approaches_compared",
@@ -92,6 +102,16 @@ function tieredArtifactValidation(stage, rows) {
         };
     });
 }
+function readsFromForTrack(readsFrom, track) {
+    const stageSet = new Set(TRACK_STAGES[track]);
+    return readsFrom.filter((artifactPath) => {
+        const stage = ARTIFACT_STAGE_BY_PATH[artifactPath];
+        if (!stage) {
+            return true;
+        }
+        return stageSet.has(stage);
+    });
+}
 // ---------------------------------------------------------------------------
 // Stage map and accessors
 // ---------------------------------------------------------------------------
@@ -199,8 +219,8 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
         },
         {
             agent: "reviewer",
-            mode: "proactive",
-            when: "When the diff exceeds 100 changed lines, touches more than 10 files, or modifies trust boundaries — dispatch a SECOND, independent reviewer with the adversarial-review skill loaded so the review army has at least two voices on a high-blast-radius change.",
+            mode: "mandatory",
+            when: "Mandatory when the diff exceeds 100 changed lines, touches more than 10 files, or modifies trust boundaries — dispatch a SECOND, independent 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"
@@ -233,23 +253,29 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
 };
 /** Transition guard: agents with `mode: "mandatory"` in auto-subagent dispatch for this stage. */
 export function mandatoryDelegationsForStage(stage) {
-    return STAGE_AUTO_SUBAGENT_DISPATCH[stage]
-        .filter((d) => d.mode === "mandatory")
-        .map((d) => d.agent);
+    return [...new Set(STAGE_AUTO_SUBAGENT_DISPATCH[stage]
+            .filter((d) => d.mode === "mandatory")
+            .map((d) => d.agent))];
 }
 export function stageSchema(stage, track = "standard") {
     const base = stage === "tdd" ? tddStageForTrack(track) : STAGE_SCHEMA_MAP[stage];
     const tieredGates = tieredStageGates(stage, base.requiredGates, track);
     const tieredValidation = tieredArtifactValidation(stage, base.artifactValidation);
+    const crossStageTrace = {
+        ...base.crossStageTrace,
+        readsFrom: readsFromForTrack(base.crossStageTrace.readsFrom, track)
+    };
     return {
         ...base,
+        skillFolder: STAGE_TO_SKILL_FOLDER[stage],
+        crossStageTrace,
         requiredGates: tieredGates,
         artifactValidation: tieredValidation,
         mandatoryDelegations: mandatoryDelegationsForStage(stage)
     };
 }
 export function orderedStageSchemas(track = "standard") {
-    return COMMAND_FILE_ORDER.map((stage) => stageSchema(stage, track));
+    return FLOW_STAGES.map((stage) => stageSchema(stage, track));
 }
 export function stageGateIds(stage, track = "standard") {
     return stageSchema(stage, track).requiredGates

package/dist/content/stages/design.js

@@ -10,7 +10,7 @@ export const DESIGN = {
     ironLaw: "NO DESIGN DECISION WITHOUT A LABELED DIAGRAM, A REJECTED ALTERNATIVE, AND A NAMED FAILURE MODE.",
     purpose: "Lock architecture, data flow, failure modes, and test/performance expectations through rigorous interactive review.",
     whenToUse: [
-        "After scope contract approval",
+        "After scope agreement approval",
         "Before writing final spec and execution plan",
         "When architecture risks need explicit treatment"
     ],
@@ -79,7 +79,7 @@ export const DESIGN = {
         "What-already-exists section produced.",
         "Completion dashboard lists every review section status, decision count, and unresolved items (or 'None')."
     ],
-    inputs: ["scope contract", "system constraints", "non-functional requirements"],
+    inputs: ["scope agreement artifact", "system constraints", "non-functional requirements"],
     requiredContext: [
         "parallel research synthesis from `.cclaw/artifacts/02a-research.md`",
         "existing architecture and boundaries",

package/dist/content/stages/review.js

@@ -201,7 +201,7 @@ export const REVIEW = {
     },
     artifactValidation: [
         { section: "Layer 1 Verdict", required: true, validationRule: "Per-criterion pass/fail with references." },
-        { section: "Layer 2 Findings", required: false, validationRule: "Each finding has severity, description, and resolution status." },
+        { section: "Layer 2 Findings", required: false, validationRule: "Each finding has severity, description, and resolution status. Security coverage must include either explicit security findings or `NO_CHANGE_ATTESTATION: <reason>` when no security-relevant changes were found." },
         { 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: false, 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: false, 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%'." },

package/dist/content/stages/ship.js

@@ -100,6 +100,8 @@ export const SHIP = {
         "FINALIZE_NO_VCS"
     ],
     artifactFile: "08-ship.md",
+    // `done` exits the stage pipeline. Archive semantics are handled by the
+    // closeout substate machine (`idle` -> ... -> `archived`) in flow-state.
     next: "done",
     reviewSections: [
         {

package/dist/content/stages/tdd.js

@@ -63,7 +63,8 @@ export const TDD = {
         { id: "tdd_green_full_suite", description: "Full relevant suite passes in GREEN state." },
         { id: "tdd_refactor_completed", description: "Refactor pass completed with behavior preservation verified." },
         { id: "tdd_verified_before_complete", description: "Fresh verification evidence includes test command, commit SHA, and explicit pass/fail status." },
-        { id: "tdd_traceable_to_plan", description: "Change traceability to plan slice is explicit." }
+        { id: "tdd_traceable_to_plan", description: "Change traceability to plan slice is explicit." },
+        { id: "tdd_docs_drift_check", description: "When public API/config/CLI surfaces change, docs drift is addressed via a completed doc-updater pass." }
     ],
     requiredEvidence: [
         "Artifact updated at `.cclaw/artifacts/06-tdd.md` with RED, GREEN, and REFACTOR sections.",
@@ -206,9 +207,12 @@ function tddQuickTrackVariant() {
         checklist: TDD.checklist.map(quickTrackText),
         interactionProtocol: TDD.interactionProtocol.map(quickTrackText),
         process: TDD.process.map(quickTrackText),
-        requiredGates: TDD.requiredGates.map((gate) => gate.id === "tdd_traceable_to_plan"
-            ? { ...gate, description: "Change traceability to acceptance criterion is explicit." }
-            : gate),
+        requiredGates: TDD.requiredGates
+            .filter((gate) => gate.id !== "tdd_traceable_to_plan")
+            .map((gate) => ({
+            ...gate,
+            description: quickTrackText(gate.description)
+        })),
         requiredEvidence: TDD.requiredEvidence.map(quickTrackText),
         inputs: TDD.inputs.map(quickTrackText),
         requiredContext: ["spec artifact", "existing test patterns"],