cclaw-cli 0.47.0 → 0.48.0

package/dist/content/templates.js

@@ -1,5 +1,5 @@
-import { COMMAND_FILE_ORDER } from "../constants.js";
 import { orderedStageSchemas } from "./stage-schema.js";
+import { FLOW_STAGES } from "../types.js";
 export const ARTIFACT_TEMPLATES = {
     "01-brainstorm.md": `---
 stage: brainstorm
@@ -522,6 +522,7 @@ inputs_hash: sha256:pending
 | ID | Severity | Category | Description | Status |
 |---|---|---|---|---|
 | R-1 | Critical/Important/Suggestion | correctness/security/performance/architecture |  | open/resolved |
+- NO_CHANGE_ATTESTATION: <required when Category=security has no entries; explain why no security-relevant changes were detected>
 
 ## Incoming Feedback Queue
 | ID | Source | Severity | File:line | Request | Status | Evidence |
@@ -802,7 +803,7 @@ Track-specific skips are allowed only when \`flow-state.track\` + \`skippedStage
 export function buildRulesJson() {
     return {
         version: 1,
-        stage_order: COMMAND_FILE_ORDER,
+        stage_order: FLOW_STAGES,
         stage_gates: Object.fromEntries(orderedStageSchemas().map((schema) => [
             schema.stage,
             schema.requiredGates.map((gate) => gate.id)
@@ -820,7 +821,7 @@ export function buildRulesJson() {
             "conventional_commits"
         ],
         MUST_NEVER: [
-            "skip_test_stage",
+            "skip_tdd_stage",
             "ship_with_critical_findings",
             "implement_in_brainstorm",
             "manual_edit_generated",

package/dist/delegation.js

@@ -1,11 +1,14 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 import { RUNTIME_ROOT } from "./constants.js";
 import { readConfig } from "./config.js";
 import { exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 import { readFlowState } from "./runs.js";
 import { stageSchema } from "./content/stage-schema.js";
+const execFileAsync = promisify(execFile);
 function delegationLogPath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "state", "delegation-log.json");
 }
@@ -15,6 +18,82 @@ function delegationLockPath(projectRoot) {
 function createSpanId() {
     return `dspan-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
+async function resolveReviewDiffBase(projectRoot) {
+    let head = "";
+    try {
+        head = (await execFileAsync("git", ["rev-parse", "HEAD"], { cwd: projectRoot })).stdout.trim();
+    }
+    catch {
+        return null;
+    }
+    const candidates = ["origin/main", "origin/master", "main", "master"];
+    for (const candidate of candidates) {
+        try {
+            await execFileAsync("git", ["rev-parse", "--verify", candidate], { cwd: projectRoot });
+            const { stdout } = await execFileAsync("git", ["merge-base", "HEAD", candidate], {
+                cwd: projectRoot
+            });
+            const base = stdout.trim();
+            if (base.length > 0 && base !== head) {
+                return base;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD~1"], {
+            cwd: projectRoot
+        });
+        const base = stdout.trim();
+        return base.length > 0 ? base : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function detectReviewTriggers(projectRoot) {
+    const empty = {
+        changedFiles: 0,
+        changedLines: 0,
+        trustBoundaryChanged: false,
+        requireAdversarialReviewer: false
+    };
+    const base = await resolveReviewDiffBase(projectRoot);
+    if (!base) {
+        return empty;
+    }
+    try {
+        const range = `${base}..HEAD`;
+        const shortstat = await execFileAsync("git", ["diff", "--shortstat", range], {
+            cwd: projectRoot
+        });
+        const short = shortstat.stdout.trim();
+        const changedFiles = Number((/(\d+)\s+files?\s+changed/u.exec(short)?.[1] ?? "0"));
+        const insertions = Number((/(\d+)\s+insertions?\(\+\)/u.exec(short)?.[1] ?? "0"));
+        const deletions = Number((/(\d+)\s+deletions?\(-\)/u.exec(short)?.[1] ?? "0"));
+        const changedLines = insertions + deletions;
+        const names = await execFileAsync("git", ["diff", "--name-only", range], {
+            cwd: projectRoot
+        });
+        const changedPaths = names.stdout
+            .split(/\r?\n/gu)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        const trustBoundaryChanged = changedPaths.some((filePath) => /(auth|security|secret|token|credential|permission|acl|policy|oauth|session|encrypt|decrypt|input|validation)/iu.test(filePath));
+        const requireAdversarialReviewer = changedLines > 100 || changedFiles > 10 || trustBoundaryChanged;
+        return {
+            changedFiles,
+            changedLines,
+            trustBoundaryChanged,
+            requireAdversarialReviewer
+        };
+    }
+    catch {
+        return empty;
+    }
+}
 function isDelegationTokenUsage(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -76,6 +155,8 @@ function parseLedger(raw, runId) {
         for (const item of entriesRaw) {
             if (isDelegationEntry(item)) {
                 const ts = item.startTs ?? item.ts ?? new Date().toISOString();
+                const inferredFulfillmentMode = item.fulfillmentMode
+                    ?? (item.status === "completed" ? "isolated" : undefined);
                 entries.push({
                     ...item,
                     spanId: item.spanId ?? createSpanId(),
@@ -85,6 +166,7 @@ function parseLedger(raw, runId) {
                         ? item.retryCount
                         : 0,
                     evidenceRefs: Array.isArray(item.evidenceRefs) ? item.evidenceRefs : [],
+                    fulfillmentMode: inferredFulfillmentMode,
                     schemaVersion: 1
                 });
             }
@@ -126,6 +208,12 @@ export async function appendDelegation(projectRoot, entry) {
         if (!Array.isArray(stamped.evidenceRefs)) {
             stamped.evidenceRefs = [];
         }
+        if (stamped.status === "completed" && stamped.fulfillmentMode === undefined) {
+            const config = await readConfig(projectRoot).catch(() => null);
+            const harnesses = config?.harnesses ?? [];
+            const fallbacks = harnesses.map((h) => HARNESS_ADAPTERS[h].capabilities.subagentFallback);
+            stamped.fulfillmentMode = expectedFulfillmentMode(fallbacks);
+        }
         // Idempotency: if a caller (or a retried hook) tries to append a row
         // with a spanId that already exists in the ledger, treat it as a no-op
         // instead of growing the log with duplicate entries that subsequent
@@ -174,51 +262,29 @@ export async function checkMandatoryDelegations(projectRoot, stage) {
     const harnesses = config?.harnesses ?? [];
     const fallbacks = harnesses.map((h) => HARNESS_ADAPTERS[h].capabilities.subagentFallback);
     const expectedMode = expectedFulfillmentMode(fallbacks);
-    const onlyWaiverFallback = harnesses.length > 0 && fallbacks.every((f) => f === "waiver");
+    const reviewTriggers = stage === "review" ? await detectReviewTriggers(projectRoot) : null;
     for (const agent of mandatory) {
         const rows = forRun.filter((e) => e.agent === agent);
         const completedRows = rows.filter((e) => e.status === "completed");
         const waivedRows = rows.filter((e) => e.status === "waived");
-        const hasCompleted = completedRows.length > 0;
+        const requiredCompletedCount = stage === "review" &&
+            agent === "reviewer" &&
+            reviewTriggers?.requireAdversarialReviewer
+            ? 2
+            : 1;
+        const hasCompleted = completedRows.length >= requiredCompletedCount;
         const hasWaived = waivedRows.length > 0;
         const ok = hasCompleted || hasWaived;
         if (!ok) {
-            if (onlyWaiverFallback) {
-                const existingHarnessWaiver = rows.some((e) => e.status === "waived" && e.waiverReason === "harness_limitation");
-                if (!existingHarnessWaiver) {
-                    await appendDelegation(projectRoot, {
-                        stage,
-                        agent,
-                        mode: "mandatory",
-                        status: "waived",
-                        waiverReason: "harness_limitation",
-                        fulfillmentMode: "harness-waiver",
-                        ts: new Date().toISOString(),
-                        runId: activeRunId
-                    });
-                }
-                waived.push(agent);
-                autoWaived.push(agent);
-            }
-            else {
-                missing.push(agent);
-            }
+            missing.push(agent);
             continue;
         }
         if (hasWaived) {
             waived.push(agent);
         }
-        // Evidence gating for `completed` rows has two triggers:
-        //   1. The aggregate expected mode is role-switch (no isolated harness
-        //      available), so every completion implicitly ran as role-switch.
-        //   2. Any completed row is explicitly stamped `fulfillmentMode:
-        //      "role-switch"` — even in a mixed install. This closes the loop
-        //      where a Codex session logs a role-switch completion inside a
-        //      claude+codex project: the aggregate expectedMode is "isolated"
-        //      (claude wins), so the role-switch row would previously sail
-        //      through without evidenceRefs.
-        const hasExplicitRoleSwitchRow = completedRows.some((e) => e.fulfillmentMode === "role-switch");
-        const evidenceRequired = expectedMode === "role-switch" || hasExplicitRoleSwitchRow;
+        // Evidence is required for any non-isolated completion mode. Legacy rows
+        // without fulfillmentMode are inferred to `isolated` during parse.
+        const evidenceRequired = completedRows.some((e) => (e.fulfillmentMode ?? "isolated") !== "isolated");
         if (hasCompleted &&
             evidenceRequired &&
             !completedRows.some((e) => Array.isArray(e.evidenceRefs) && e.evidenceRefs.length > 0)) {

package/dist/doctor.js

@@ -3,16 +3,16 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
-import { COMMAND_FILE_ORDER, REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
+import { REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
 import { CCLAW_AGENTS } from "./content/core-agents.js";
-import { readConfig } from "./config.js";
+import { detectAdvancedKeys, readConfig } from "./config.js";
 import { exists } from "./fs-utils.js";
 import { gitignoreHasRequiredPatterns } from "./gitignore.js";
 import { HARNESS_ADAPTERS, CCLAW_MARKER_START, CCLAW_MARKER_END, harnessShimFileNames, harnessShimSkillNames } from "./harness-adapters.js";
 import { policyChecks } from "./policy.js";
 import { readFlowState } from "./runs.js";
 import { skippedStagesForTrack } from "./flow-state.js";
-import { TRACK_STAGES } from "./types.js";
+import { FLOW_STAGES, TRACK_STAGES } from "./types.js";
 import { checkMandatoryDelegations } from "./delegation.js";
 import { ensureFeatureSystem, listFeatures, readActiveFeature, readFeatureWorktreeRegistry, resolveFeatureWorkspacePath, worktreeRegistryPath } from "./feature-system.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
@@ -280,7 +280,7 @@ export async function doctorChecks(projectRoot, options = {}) {
             details: fullPath
         });
     }
-    for (const stage of COMMAND_FILE_ORDER) {
+    for (const stage of FLOW_STAGES) {
         const commandPath = path.join(projectRoot, RUNTIME_ROOT, "commands", `${stage}.md`);
         checks.push({
             name: `command:${stage}`,
@@ -377,7 +377,7 @@ export async function doctorChecks(projectRoot, options = {}) {
     // skill's Examples section points here; the file MUST exist or the pointer
     // is a dangling link.
     const stageRefDir = path.join(projectRoot, RUNTIME_ROOT, "references", "stages");
-    for (const stage of COMMAND_FILE_ORDER) {
+    for (const stage of FLOW_STAGES) {
         const refPath = path.join(stageRefDir, `${stage}-examples.md`);
         checks.push({
             name: `stage_examples_ref:${stage}`,
@@ -430,6 +430,18 @@ export async function doctorChecks(projectRoot, options = {}) {
         });
     }
     if (parsedConfig) {
+        const advancedKeys = await detectAdvancedKeys(projectRoot).catch(() => new Set());
+        const hasLegacyTddTestGlobs = advancedKeys.has("tddTestGlobs");
+        const hasModernTddConfig = advancedKeys.has("tdd");
+        checks.push({
+            name: "warning:config:deprecated_tdd_test_globs",
+            ok: !hasLegacyTddTestGlobs,
+            details: hasLegacyTddTestGlobs
+                ? hasModernTddConfig
+                    ? `warning: ${RUNTIME_ROOT}/config.yaml sets deprecated "tddTestGlobs" alongside "tdd.*"; "tdd.testPathPatterns" takes precedence. Remove legacy key.`
+                    : `warning: ${RUNTIME_ROOT}/config.yaml uses deprecated "tddTestGlobs". Migrate to "tdd.testPathPatterns".`
+                : `no deprecated "tddTestGlobs" key detected in ${RUNTIME_ROOT}/config.yaml`
+        });
         const expectedMode = parsedConfig.promptGuardMode === "strict" ? "strict" : "advisory";
         const promptGuardPath = path.join(projectRoot, RUNTIME_ROOT, "hooks", "prompt-guard.sh");
         let promptGuardModeOk = false;
@@ -1191,6 +1203,62 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "state", "harness-gaps.json")),
         details: `${RUNTIME_ROOT}/state/harness-gaps.json must exist for tiered harness capability tracking`
     });
+    const adapterManifestPath = path.join(projectRoot, RUNTIME_ROOT, "adapters", "manifest.json");
+    const adapterManifestExists = await exists(adapterManifestPath);
+    checks.push({
+        name: "state:adapter_manifest_exists",
+        ok: adapterManifestExists,
+        details: `${RUNTIME_ROOT}/adapters/manifest.json must exist for harness adapter provenance`
+    });
+    if (adapterManifestExists) {
+        let harnessesOk = false;
+        let harnessesDetails = "";
+        let sourcesOk = false;
+        let sourcesDetails = "";
+        try {
+            const parsed = JSON.parse(await fs.readFile(adapterManifestPath, "utf8"));
+            const manifestHarnesses = Array.isArray(parsed.harnesses)
+                ? parsed.harnesses.filter((entry) => typeof entry === "string")
+                : [];
+            const expectedHarnesses = configuredHarnesses.length > 0
+                ? [...new Set(configuredHarnesses)].sort()
+                : null;
+            const actualHarnesses = [...new Set(manifestHarnesses)].sort();
+            harnessesOk = expectedHarnesses
+                ? actualHarnesses.length === expectedHarnesses.length &&
+                    actualHarnesses.every((harness, index) => harness === expectedHarnesses[index])
+                : actualHarnesses.length > 0;
+            harnessesDetails = expectedHarnesses
+                ? harnessesOk
+                    ? `adapter manifest harnesses match config.yaml: ${actualHarnesses.join(", ")}`
+                    : `adapter manifest harnesses [${actualHarnesses.join(", ")}] do not match config.yaml [${expectedHarnesses.join(", ")}]`
+                : harnessesOk
+                    ? `adapter manifest declares harnesses: ${actualHarnesses.join(", ")}`
+                    : "adapter manifest must declare at least one harness";
+            const commandSource = typeof parsed.commandSource === "string" ? parsed.commandSource.trim() : "";
+            const skillSource = typeof parsed.skillSource === "string" ? parsed.skillSource.trim() : "";
+            sourcesOk = commandSource.length > 0 && skillSource.length > 0;
+            sourcesDetails = sourcesOk
+                ? `adapter manifest source globs are set (commandSource=${commandSource}; skillSource=${skillSource})`
+                : "adapter manifest must include non-empty commandSource and skillSource";
+        }
+        catch {
+            harnessesOk = false;
+            harnessesDetails = "adapter manifest must be valid JSON with a harnesses array";
+            sourcesOk = false;
+            sourcesDetails = "adapter manifest must be valid JSON with source globs";
+        }
+        checks.push({
+            name: "state:adapter_manifest_harnesses",
+            ok: harnessesOk,
+            details: harnessesDetails
+        });
+        checks.push({
+            name: "state:adapter_manifest_sources",
+            ok: sourcesOk,
+            details: sourcesDetails
+        });
+    }
     const contextModeStatePath = path.join(projectRoot, RUNTIME_ROOT, "state", "context-mode.json");
     checks.push({
         name: "state:context_mode_exists",
@@ -1276,7 +1344,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         name: "flow_state:track",
         ok: skippedConsistent,
         details: skippedConsistent
-            ? `active track "${activeTrack}" (${trackStageList.length}/${COMMAND_FILE_ORDER.length} stages: ${trackStageList.join(" → ")})${expectedSkipped.length > 0 ? `; skippedStages=${expectedSkipped.join(", ")}` : ""}`
+            ? `active track "${activeTrack}" (${trackStageList.length}/${FLOW_STAGES.length} stages: ${trackStageList.join(" → ")})${expectedSkipped.length > 0 ? `; skippedStages=${expectedSkipped.join(", ")}` : ""}`
             : `track "${activeTrack}" expects skippedStages=[${expectedSkipped.join(", ")}] but flow-state has [${skippedFromState.join(", ")}] — run \`cclaw sync\` to repair`
     });
     if (parsedConfig?.trackHeuristics) {
@@ -1441,7 +1509,7 @@ export async function doctorChecks(projectRoot, options = {}) {
             ? "no legacy .cclaw/features snapshot entries remain"
             : `legacy snapshot entries still present (read-only): ${legacyWorkspaceEntries.join(", ")}`
     });
-    const staleStages = Object.keys(flowState.staleStages).filter((value) => COMMAND_FILE_ORDER.includes(value));
+    const staleStages = Object.keys(flowState.staleStages).filter((value) => FLOW_STAGES.includes(value));
     checks.push({
         name: "state:stale_stages_resolved",
         ok: staleStages.length === 0,
@@ -1667,10 +1735,10 @@ export async function doctorChecks(projectRoot, options = {}) {
             const stageOrder = parsed.stage_order;
             const stageGates = parsed.stage_gates;
             const hasStageOrder = Array.isArray(stageOrder) &&
-                COMMAND_FILE_ORDER.every((stage) => stageOrder.includes(stage));
+                FLOW_STAGES.every((stage) => stageOrder.includes(stage));
             const hasStageGates = typeof stageGates === "object" &&
                 stageGates !== null &&
-                COMMAND_FILE_ORDER.every((stage) => Array.isArray(stageGates[stage]));
+                FLOW_STAGES.every((stage) => Array.isArray(stageGates[stage]));
             hasRules = hasCoreLists && hasStageOrder && hasStageGates;
         }
         catch {

package/dist/flow-state.d.ts

@@ -43,6 +43,14 @@ export interface RetroState {
  *   automatic step.
  * - `archived` — archive completed in this session (transient — archive
  *   resets flow-state so this value does not persist between runs).
+ *
+ * Layer separation (intentional):
+ * - `next: "done"` in stage schema means "the flow stage chain ended".
+ * - `shipSubstate: "archived"` is closeout-machine progress after ship.
+ * - `shipSubstate: "idle"` is the default closeout value before ship.
+ *
+ * These are not duplicates: `done` lives in stage transitions; `archived` /
+ * `idle` live in closeout lifecycle state.
  */
 export declare const SHIP_SUBSTATES: readonly ["idle", "retro_review", "compound_review", "ready_to_archive", "archived"];
 export type ShipSubstate = (typeof SHIP_SUBSTATES)[number];

package/dist/flow-state.js

@@ -1,4 +1,3 @@
-import { COMMAND_FILE_ORDER } from "./constants.js";
 import { buildTransitionRules, orderedStageSchemas, stageGateIds, stageRecommendedGateIds } from "./content/stage-schema.js";
 import { FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "./types.js";
 export const TRANSITION_RULES = buildTransitionRules();
@@ -17,6 +16,14 @@ export const TRANSITION_RULES = buildTransitionRules();
  *   automatic step.
  * - `archived` — archive completed in this session (transient — archive
  *   resets flow-state so this value does not persist between runs).
+ *
+ * Layer separation (intentional):
+ * - `next: "done"` in stage schema means "the flow stage chain ended".
+ * - `shipSubstate: "archived"` is closeout-machine progress after ship.
+ * - `shipSubstate: "idle"` is the default closeout value before ship.
+ *
+ * These are not duplicates: `done` lives in stage transitions; `archived` /
+ * `idle` live in closeout lifecycle state.
  */
 export const SHIP_SUBSTATES = [
     "idle",
@@ -98,11 +105,7 @@ export function nextStage(stage, track = "standard") {
     const ordered = TRACK_STAGES[track];
     const index = ordered.indexOf(stage);
     if (index < 0) {
-        const fallback = COMMAND_FILE_ORDER.indexOf(stage);
-        if (fallback < 0 || fallback === COMMAND_FILE_ORDER.length - 1) {
-            return null;
-        }
-        return COMMAND_FILE_ORDER[fallback + 1];
+        return null;
     }
     if (index === ordered.length - 1) {
         return null;
@@ -116,11 +119,11 @@ export function previousStage(stage, track = "standard") {
         return null;
     }
     if (index < 0) {
-        const fallback = COMMAND_FILE_ORDER.indexOf(stage);
+        const fallback = FLOW_STAGES.indexOf(stage);
         if (fallback <= 0) {
             return null;
         }
-        return COMMAND_FILE_ORDER[fallback - 1];
+        return FLOW_STAGES[fallback - 1];
     }
     return ordered[index - 1];
 }

package/dist/gate-evidence.js

@@ -1,9 +1,11 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { checkReviewVerdictConsistency, extractMarkdownSectionBody, lintArtifact, validateReviewArmy } from "./artifact-linter.js";
+import { checkReviewSecurityNoChangeAttestation, checkReviewVerdictConsistency, extractMarkdownSectionBody, lintArtifact, validateReviewArmy } from "./artifact-linter.js";
 import { RUNTIME_ROOT } from "./constants.js";
 import { stageSchema } from "./content/stage-schema.js";
+import { readDelegationLedger } from "./delegation.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
+import { detectPublicApiChanges } from "./internal/detect-public-api-changes.js";
 import { readFlowState, writeFlowState } from "./runs.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
 import { FLOW_STAGES } from "./types.js";
@@ -228,6 +230,10 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
             if (!verdictConsistency.ok) {
                 issues.push(`review verdict inconsistency: ${verdictConsistency.errors.join("; ")}`);
             }
+            const securityAttestation = await checkReviewSecurityNoChangeAttestation(projectRoot);
+            if (!securityAttestation.ok) {
+                issues.push(`review security attestation failed: ${securityAttestation.errors.join("; ")}`);
+            }
             const traceGateRequired = schema.requiredGates.some((gate) => gate.id === "review_trace_matrix_clean" && gate.tier === "required");
             if (traceGateRequired) {
                 const trace = await buildTraceMatrix(projectRoot);
@@ -282,6 +288,19 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
                 }
             }
         }
+        if (stage === "tdd") {
+            const docsDriftDetection = await detectPublicApiChanges(projectRoot);
+            if (docsDriftDetection.triggered) {
+                const ledger = await readDelegationLedger(projectRoot);
+                const hasDocUpdaterCompletion = ledger.entries.some((entry) => entry.runId === flowState.activeRunId &&
+                    entry.stage === "tdd" &&
+                    entry.agent === "doc-updater" &&
+                    entry.status === "completed");
+                if (!hasDocUpdaterCompletion) {
+                    issues.push(`tdd docs drift gate blocked (tdd_docs_drift_check): public surface changes detected (${docsDriftDetection.changedFiles.join(", ")}) but no completed doc-updater delegation exists for the active run.`);
+                }
+            }
+        }
     }
     const passedSet = new Set(catalog.passed);
     const missingRequired = required.filter((gateId) => !passedSet.has(gateId));

package/dist/harness-adapters.d.ts

@@ -17,8 +17,8 @@ export type SubagentFallback =
  */
  | "role-switch"
 /**
- * No meaningful fallback — mandatory delegations can only be waived
- * under `waiverReason: "harness_limitation"`.
+ * Reserved escape hatch for future harnesses with no parity path.
+ * Current shipped harnesses do not use this fallback.
  */
  | "waiver";
 /**

package/dist/harness-adapters.js

@@ -222,7 +222,7 @@ When in doubt, prefer **non-trivial** — the quick track is opt-in and only saf
 |---|---|
 | \`/cc\` | **Entry point.** No args = resume current stage. With prompt = classify task and start the right flow. |
 | \`/cc-next\` | **Progression.** Advances to the next stage when current is complete. |
-| \`/cc-ideate\` | **Discovery mode.** Generates a ranked repo-improvement backlog before implementation. |
+| \`/cc-ideate\` | **Ideate mode.** Generates a ranked repo-improvement backlog before implementation. |
 | \`/cc-view\` | **Read-only router.** Unified entry for status/tree/diff views. |
 | \`/cc-ops\` | **Operations router.** Unified entry for feature/tdd-log/retro/compound/archive/rewind actions. |
 
@@ -356,7 +356,7 @@ function codexSkillDescription(command) {
         case "next":
             return `Advance the cclaw flow to the next stage. Use when the user types \`/cc-next\` or asks to "move to the next stage", "continue the flow", "advance cclaw", "progress the workflow", or when the current stage skill reports completion and gates have passed.`;
         case "ideate":
-            return `Read-only repo-improvement discovery for cclaw. Use when the user types \`/cc-ideate\` or asks to "ideate", "brainstorm improvements", "scan the repo for TODOs/tech debt", "generate a backlog", or wants a ranked list of candidate ideas before committing to a single flow. Does not mutate \`.cclaw/state/flow-state.json\`.`;
+            return `Read-only repo-improvement ideate mode for cclaw. Use when the user types \`/cc-ideate\` or asks to "ideate", "scan the repo for TODOs/tech debt", "generate a backlog", or wants a ranked list of candidate ideas before committing to a single flow. Does not mutate \`.cclaw/state/flow-state.json\`.`;
         case "view":
             return `Read-only router for cclaw flow views. Use when the user types \`/cc-view\`, \`/cc-view status\`, \`/cc-view tree\`, \`/cc-view diff\`, or asks to "show cclaw status", "show the flow tree", "diff flow state", or wants a snapshot without mutation.`;
         case "ops":

package/dist/install.js

@@ -2,9 +2,9 @@ import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
-import { CCLAW_VERSION, COMMAND_FILE_ORDER, FLOW_VERSION, REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
+import { CCLAW_VERSION, FLOW_VERSION, REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
 import { writeConfig, createDefaultConfig, readConfig, configPath, detectLanguageRulePacks, detectAdvancedKeys } from "./config.js";
-import { commandContract } from "./content/contracts.js";
+import { stageCommandContract } from "./content/contracts.js";
 import { contextModeFiles, createInitialContextModeState } from "./content/contexts.js";
 import { learnSkillMarkdown, learnCommandContract } from "./content/learnings.js";
 import { nextCommandContract, nextCommandSkillMarkdown } from "./content/next-command.js";
@@ -36,7 +36,7 @@ import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LANGUAGE_RULE_PACK_GE
 import { RESEARCH_PLAYBOOKS } from "./content/research-playbooks.js";
 import { HARNESS_TOOL_REFS_DIR, HARNESS_TOOL_REFS_INDEX_MD, harnessToolRefMarkdown } from "./content/harness-tool-refs.js";
 import { DOCTOR_REFERENCE_MARKDOWN } from "./content/doctor-references.js";
-import { harnessDocsOverviewMarkdown, harnessIntegrationDocMarkdown } from "./content/harnesses-doc.js";
+import { harnessDocsOverviewMarkdown, harnessIntegrationDocMarkdown } from "./content/harness-doc.js";
 import { HARNESS_PLAYBOOKS_DIR, harnessPlaybookFileName, harnessPlaybookMarkdown, harnessPlaybooksIndexMarkdown } from "./content/harness-playbooks.js";
 import { HOOK_EVENTS_BY_HARNESS, HOOK_SEMANTIC_EVENTS } from "./content/hook-events.js";
 import { createInitialFlowState } from "./flow-state.js";
@@ -45,6 +45,7 @@ import { ensureGitignore, removeGitignorePatterns } from "./gitignore.js";
 import { HARNESS_ADAPTERS, harnessShimFileNames, harnessTier, syncHarnessShims, removeCclawFromAgentsMd } from "./harness-adapters.js";
 import { validateHookDocument } from "./hook-schema.js";
 import { ensureRunSystem, readFlowState } from "./runs.js";
+import { FLOW_STAGES } from "./types.js";
 const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
 const CURSOR_RULE_REL_PATH = ".cursor/rules/cclaw-workflow.mdc";
 const GIT_HOOK_MANAGED_MARKER = "cclaw-managed-git-hook";
@@ -177,8 +178,8 @@ async function ensureStructure(projectRoot) {
     }
 }
 async function writeCommandContracts(projectRoot) {
-    for (const stage of COMMAND_FILE_ORDER) {
-        await writeFileSafe(runtimePath(projectRoot, "commands", `${stage}.md`), commandContract(stage));
+    for (const stage of FLOW_STAGES) {
+        await writeFileSafe(runtimePath(projectRoot, "commands", `${stage}.md`), stageCommandContract(stage));
     }
 }
 async function writeArtifactTemplates(projectRoot) {
@@ -214,7 +215,7 @@ async function writeEvalScaffold(projectRoot) {
 }
 async function writeSkills(projectRoot, config) {
     const skillTrack = config?.defaultTrack ?? "standard";
-    for (const stage of COMMAND_FILE_ORDER) {
+    for (const stage of FLOW_STAGES) {
         const folder = stageSkillFolder(stage);
         await writeFileSafe(runtimePath(projectRoot, "skills", folder, "SKILL.md"), stageSkillMarkdown(stage, skillTrack));
         // Progressive disclosure (A.2#8): materialize the full example artifact as
@@ -1114,6 +1115,27 @@ async function cleanLegacyArtifacts(projectRoot) {
             // best-effort cleanup
         }
     }
+    // D-4 terminology migration: rename historical ideation artifacts to the
+    // canonical ideate-* naming without deleting user-authored content.
+    const artifactsDir = runtimePath(projectRoot, "artifacts");
+    try {
+        const entries = await fs.readdir(artifactsDir);
+        for (const entry of entries) {
+            const match = /^ideation-(.+\.md)$/u.exec(entry);
+            if (!match)
+                continue;
+            const nextName = `ideate-${match[1]}`;
+            const from = path.join(artifactsDir, entry);
+            const to = path.join(artifactsDir, nextName);
+            if (await exists(to)) {
+                continue;
+            }
+            await fs.rename(from, to);
+        }
+    }
+    catch {
+        // no artifacts directory yet (fresh init) or read-only FS
+    }
 }
 async function cleanStaleFiles(projectRoot) {
     const expectedShimFiles = new Set(harnessShimFileNames());

package/dist/internal/detect-public-api-changes.d.ts

@@ -0,0 +1,5 @@
+export interface PublicApiChangeDetection {
+    triggered: boolean;
+    changedFiles: string[];
+}
+export declare function detectPublicApiChanges(projectRoot: string): Promise<PublicApiChangeDetection>;

package/dist/internal/detect-public-api-changes.js

@@ -0,0 +1,45 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const PUBLIC_SURFACE_PATH_PATTERNS = [
+    /(^|\/)(cli|types?|config)\.[cm]?[jt]s$/iu,
+    /(^|\/)(openapi|swagger|schema)(\/|[-_.])/iu,
+    /(^|\/)(api|commands?|flags?)(\/|[-_.])/iu,
+    /(^|\/)(package|tsconfig)\.json$/iu
+];
+async function resolveDiffBase(projectRoot) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD~1"], {
+            cwd: projectRoot
+        });
+        const base = stdout.trim();
+        return base.length > 0 ? base : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function detectPublicApiChanges(projectRoot) {
+    const base = await resolveDiffBase(projectRoot);
+    if (!base) {
+        return { triggered: false, changedFiles: [] };
+    }
+    try {
+        const range = `${base}..HEAD`;
+        const { stdout } = await execFileAsync("git", ["diff", "--name-only", range], {
+            cwd: projectRoot
+        });
+        const changedFiles = stdout
+            .split(/\r?\n/gu)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .filter((filePath) => PUBLIC_SURFACE_PATH_PATTERNS.some((pattern) => pattern.test(filePath)));
+        return {
+            triggered: changedFiles.length > 0,
+            changedFiles
+        };
+    }
+    catch {
+        return { triggered: false, changedFiles: [] };
+    }
+}