cclaw-cli 0.46.15 → 0.48.0

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);
@@ -266,7 +272,12 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
                             .map((line) => line.trim())
                             .filter((line) => line.length > 0)
                             .filter((line) => !/^\|?(?:[-:\s|])+$/u.test(line));
-                        const nonPlaceholder = meaningfulLines.filter((line) => !/\b(?:TODO|TBD|FIXME|pending|<fill-in>)\b/iu.test(line));
+                        // `<fill-in>` needs its own check because `\b` does not match
+                        // around `<`/`>` (non-word characters), so the previous combined
+                        // pattern `\b(?:...|<fill-in>)\b` silently never matched placeholder
+                        // templates that used angle-bracket form.
+                        const nonPlaceholder = meaningfulLines.filter((line) => !/\b(?:TODO|TBD|FIXME|pending)\b/iu.test(line) &&
+                            !/<fill-in>/iu.test(line));
                         if (nonPlaceholder.length === 0) {
                             missingSections.push(`${section} (empty or placeholder)`);
                         }
@@ -277,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/advance-stage.js

@@ -16,21 +16,36 @@ function unique(values) {
 const TEST_COMMAND_HINT_PATTERN = /\b(?:npm test|pnpm test|yarn test|bun test|vitest|jest|pytest|go test|cargo test|mvn test|gradle test|dotnet test)\b/iu;
 const SHA_WITH_LABEL_PATTERN = /\b(?:sha|commit)(?:\s*[:=]|\s+)\s*[0-9a-f]{7,40}\b/iu;
 const PASS_STATUS_PATTERN = /\b(?:pass|passed|green|ok)\b/iu;
-function validateGateEvidenceShape(stage, gateId, evidence) {
-    if (stage !== "tdd" || gateId !== "tdd_verified_before_complete") {
+const SHIP_FINALIZATION_MODE_PATTERN = /\bFINALIZE_(?:MERGE_LOCAL|OPEN_PR|QUEUE|HANDOFF|SKIP)\b/u;
+// Per-gate validators keyed by `${stage}:${gateId}`. Returning a non-null
+// string surfaces the reason as an `advance-stage` failure so evidence is
+// guaranteed to carry the structural breadcrumbs downstream tooling
+// expects. Previously only `tdd:tdd_verified_before_complete` was checked.
+const GATE_EVIDENCE_VALIDATORS = {
+    "tdd:tdd_verified_before_complete": (evidence) => {
+        if (!TEST_COMMAND_HINT_PATTERN.test(evidence)) {
+            return "must include the fresh verification command that was run (for example `npm test`, `pytest`, `go test`, or equivalent).";
+        }
+        if (!SHA_WITH_LABEL_PATTERN.test(evidence)) {
+            return "must include a commit SHA token prefixed with `sha` or `commit` (for example `sha: abc1234`).";
+        }
+        if (!PASS_STATUS_PATTERN.test(evidence)) {
+            return "must include explicit success status (for example `PASS` or `GREEN`).";
+        }
+        return null;
+    },
+    "ship:ship_finalization_executed": (evidence) => {
+        if (!SHIP_FINALIZATION_MODE_PATTERN.test(evidence)) {
+            return "must name the finalization mode that ran (for example `FINALIZE_MERGE_LOCAL`, `FINALIZE_OPEN_PR`, `FINALIZE_HANDOFF`, `FINALIZE_QUEUE`, or `FINALIZE_SKIP`).";
+        }
         return null;
     }
-    const trimmed = evidence.trim();
-    if (!TEST_COMMAND_HINT_PATTERN.test(trimmed)) {
-        return "must include the fresh verification command that was run (for example `npm test`, `pytest`, `go test`, or equivalent).";
-    }
-    if (!SHA_WITH_LABEL_PATTERN.test(trimmed)) {
-        return "must include a commit SHA token prefixed with `sha` or `commit` (for example `sha: abc1234`).";
-    }
-    if (!PASS_STATUS_PATTERN.test(trimmed)) {
-        return "must include explicit success status (for example `PASS` or `GREEN`).";
-    }
-    return null;
+};
+function validateGateEvidenceShape(stage, gateId, evidence) {
+    const validator = GATE_EVIDENCE_VALIDATORS[`${stage}:${gateId}`];
+    if (!validator)
+        return null;
+    return validator(evidence.trim());
 }
 function parseStringList(raw) {
     if (!Array.isArray(raw))
@@ -58,10 +73,23 @@ function parseGuardEvidence(value) {
     }
     return next;
 }
+function emptyGateState() {
+    return {
+        required: [],
+        recommended: [],
+        conditional: [],
+        triggered: [],
+        passed: [],
+        blocked: []
+    };
+}
 function parseCandidateGateCatalog(value, fallback) {
     const next = {};
     for (const stage of FLOW_STAGES) {
-        const base = fallback[stage];
+        // Guard against stale on-disk flow-state files that persisted a partial
+        // stageGateCatalog (missing a stage key). Previously `fallback[stage]`
+        // could be undefined and the spread below would throw at runtime.
+        const base = fallback[stage] ?? emptyGateState();
         next[stage] = {
             required: [...base.required],
             recommended: [...base.recommended],
@@ -81,7 +109,7 @@ function parseCandidateGateCatalog(value, fallback) {
             continue;
         }
         const typed = rawStage;
-        const base = fallback[stage];
+        const base = fallback[stage] ?? emptyGateState();
         const allowed = new Set([...base.required, ...base.recommended, ...base.conditional]);
         const conditional = new Set(base.conditional);
         const passed = unique(parseStringList(typed.passed)).filter((gateId) => allowed.has(gateId));
@@ -114,13 +142,22 @@ function coerceCandidateFlowState(raw, fallback) {
     const completedStages = unique(parseStringList(typed.completedStages).filter((stage) => isFlowStageValue(stage)));
     const skippedStagesRaw = parseStringList(typed.skippedStages).filter((stage) => isFlowStageValue(stage));
     const skippedStages = skippedStagesRaw.length > 0 ? skippedStagesRaw : fallback.skippedStages;
+    // When the candidate payload omits `guardEvidence` entirely we must keep
+    // the on-disk fallback — otherwise a partial update (e.g. a tooling call
+    // that only passes stage + passedGateIds) would silently wipe every
+    // previously recorded evidence string and fail the next
+    // `verifyCurrentStageGateEvidence` check.
+    const candidateEvidence = parseGuardEvidence(typed.guardEvidence);
+    const guardEvidence = typed.guardEvidence === undefined
+        ? { ...fallback.guardEvidence }
+        : candidateEvidence;
     return {
         ...fallback,
         currentStage,
         completedStages,
         track,
         skippedStages,
-        guardEvidence: parseGuardEvidence(typed.guardEvidence),
+        guardEvidence,
         stageGateCatalog: parseCandidateGateCatalog(typed.stageGateCatalog, fallback.stageGateCatalog)
     };
 }

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: [] };
+    }
+}

package/dist/policy.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
+import { RUNTIME_ROOT } from "./constants.js";
+import { FLOW_STAGES } from "./types.js";
 import { stageSchema, stagePolicyNeedles } from "./content/stage-schema.js";
 import { stageSkillFolder } from "./content/skills.js";
 import { exists } from "./fs-utils.js";
@@ -10,7 +11,7 @@ export async function policyChecks(projectRoot, options = {}) {
     const checks = [];
     const rules = [...POLICY_RULES];
     const activeHarnesses = new Set(options.harnesses && options.harnesses.length > 0 ? options.harnesses : ALL_HARNESSES);
-    for (const stage of COMMAND_FILE_ORDER) {
+    for (const stage of FLOW_STAGES) {
         const folder = stageSkillFolder(stage);
         const schema = stageSchema(stage);
         const commandFile = `${RUNTIME_ROOT}/commands/${stage}.md`;

package/dist/retro-gate.js

@@ -8,6 +8,7 @@ function activeArtifactsPath(projectRoot) {
 function retroArtifactPath(projectRoot) {
     return path.join(activeArtifactsPath(projectRoot), "09-retro.md");
 }
+const RETRO_ARTIFACT_MTIME_FALLBACK_WINDOW_MS = 24 * 60 * 60 * 1000;
 function parseIsoTimestamp(value) {
     if (!value || value.trim().length === 0)
         return null;
@@ -35,8 +36,24 @@ export async function evaluateRetroGate(projectRoot, state) {
         }
     }
     let compoundEntries = state.retro.compoundEntries;
-    const windowStartMs = parseIsoTimestamp(state.closeout.retroDraftedAt);
-    const windowEndMs = parseIsoTimestamp(state.closeout.retroAcceptedAt) ?? parseIsoTimestamp(state.retro.completedAt);
+    let windowStartMs = parseIsoTimestamp(state.closeout.retroDraftedAt);
+    let windowEndMs = parseIsoTimestamp(state.closeout.retroAcceptedAt) ?? parseIsoTimestamp(state.retro.completedAt);
+    if (compoundEntries <= 0 &&
+        hasRetroArtifact &&
+        windowStartMs === null &&
+        windowEndMs === null) {
+        try {
+            const stats = await fs.stat(artifactFile);
+            const anchor = stats.mtimeMs;
+            if (Number.isFinite(anchor) && anchor > 0) {
+                windowStartMs = anchor - RETRO_ARTIFACT_MTIME_FALLBACK_WINDOW_MS;
+                windowEndMs = anchor + RETRO_ARTIFACT_MTIME_FALLBACK_WINDOW_MS;
+            }
+        }
+        catch {
+            // fallback scan remains disabled when mtime cannot be read
+        }
+    }
     const shouldFallbackScan = compoundEntries <= 0 && (windowStartMs !== null || windowEndMs !== null);
     const knowledgeFile = path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
     if (shouldFallbackScan && (await exists(knowledgeFile))) {
@@ -73,7 +90,17 @@ export async function evaluateRetroGate(projectRoot, state) {
             compoundEntries = 0;
         }
     }
-    const completed = required ? (hasRetroArtifact && compoundEntries > 0) : true;
+    // A retro is considered complete when either:
+    //   - at least one compound learning was promoted during the retro window, or
+    //   - the operator explicitly skipped retro or compound (`retroSkipped` /
+    //     `compoundSkipped` recorded in the closeout substate) after reviewing
+    //     the draft. Previously the gate required `compoundEntries > 0`
+    //     unconditionally, which dead-locked ship closeout whenever the retro
+    //     yielded no new patterns worth promoting.
+    const explicitSkip = Boolean(state.closeout.retroSkipped || state.closeout.compoundSkipped);
+    const completed = required
+        ? hasRetroArtifact && (compoundEntries > 0 || explicitSkip)
+        : true;
     return {
         required,
         completed,

package/dist/run-persistence.js

@@ -1,9 +1,10 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { COMMAND_FILE_ORDER, RUNTIME_ROOT } from "./constants.js";
+import { RUNTIME_ROOT } from "./constants.js";
 import { canTransition, createInitialCloseoutState, createInitialFlowState, isFlowTrack, skippedStagesForTrack, SHIP_SUBSTATES } from "./flow-state.js";
 import { ensureFeatureSystem, syncActiveFeatureSnapshot } from "./feature-system.js";
 import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
+import { FLOW_STAGES } from "./types.js";
 export class InvalidStageTransitionError extends Error {
     from;
     to;
@@ -17,7 +18,7 @@ export class InvalidStageTransitionError extends Error {
 const FLOW_STATE_REL_PATH = `${RUNTIME_ROOT}/state/flow-state.json`;
 const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
 const ACTIVE_ARTIFACTS_REL_PATH = `${RUNTIME_ROOT}/artifacts`;
-const FLOW_STAGE_SET = new Set(COMMAND_FILE_ORDER);
+const FLOW_STAGE_SET = new Set(FLOW_STAGES);
 function validateFlowTransition(prev, next) {
     if (prev.activeRunId !== next.activeRunId) {
         // New run — only reset paths may change the runId, but those set allowReset.
@@ -85,7 +86,7 @@ function sanitizeGuardEvidence(value) {
 function sanitizeStageGateCatalog(value, fallback) {
     const uniqueStrings = (items) => [...new Set(items)];
     const next = {};
-    for (const stage of COMMAND_FILE_ORDER) {
+    for (const stage of FLOW_STAGES) {
         const base = fallback[stage];
         next[stage] = {
             required: [...base.required],
@@ -100,7 +101,7 @@ function sanitizeStageGateCatalog(value, fallback) {
         return next;
     }
     const rawCatalog = value;
-    for (const stage of COMMAND_FILE_ORDER) {
+    for (const stage of FLOW_STAGES) {
         const rawStage = rawCatalog[stage];
         if (!rawStage || typeof rawStage !== "object" || Array.isArray(rawStage)) {
             continue;
@@ -235,7 +236,7 @@ function sanitizeCloseoutState(value) {
         return fallback;
     }
     const typed = value;
-    const shipSubstate = isShipSubstate(typed.shipSubstate) ? typed.shipSubstate : fallback.shipSubstate;
+    let shipSubstate = isShipSubstate(typed.shipSubstate) ? typed.shipSubstate : fallback.shipSubstate;
     const retroDraftedAt = typeof typed.retroDraftedAt === "string" ? typed.retroDraftedAt : undefined;
     const retroAcceptedAt = typeof typed.retroAcceptedAt === "string" ? typed.retroAcceptedAt : undefined;
     const retroSkipped = typeof typed.retroSkipped === "boolean" ? typed.retroSkipped : undefined;
@@ -246,6 +247,16 @@ function sanitizeCloseoutState(value) {
     const compoundPromoted = typeof promotedRaw === "number" && Number.isFinite(promotedRaw) && promotedRaw >= 0
         ? Math.floor(promotedRaw)
         : 0;
+    // Demote shipSubstate when its retro invariant is violated on disk. A
+    // hand-edited flow-state could claim `ready_to_archive` or `compound_review`
+    // without ever going through the retro step, which would let `archive`
+    // proceed and skip the gate. Compound completion is not independently
+    // tracked in all flows (some runs rely on knowledge.jsonl + the retro
+    // window), so we only demote when the retro leg is missing outright.
+    const retroDone = retroAcceptedAt !== undefined || retroSkipped === true;
+    if (!retroDone && (shipSubstate === "ready_to_archive" || shipSubstate === "compound_review")) {
+        shipSubstate = "retro_review";
+    }
     return {
         shipSubstate,
         retroDraftedAt,

package/dist/tdd-cycle.js

@@ -31,6 +31,7 @@ export function parseTddCycleLog(text) {
     }
     return out;
 }
+const SLICE_ID_PATTERN = /^S-\d+$/u;
 export function validateTddCycleOrder(entries, options = {}) {
     const targetRun = options.runId;
     const filtered = targetRun
@@ -44,6 +45,15 @@ export function validateTddCycleOrder(entries, options = {}) {
     }
     const issues = [];
     const openRedSlices = [];
+    // Reject slices whose ID does not match the stable `S-<number>` contract.
+    // Entries that drop the slice field entirely were previously coerced to
+    // `S-unknown` and silently bucketed together, which means multiple distinct
+    // cycles could appear to share a RED/GREEN pair.
+    for (const slice of bySlice.keys()) {
+        if (!SLICE_ID_PATTERN.test(slice)) {
+            issues.push(`slice "${slice}": id must match /^S-\\d+$/ (e.g. S-1)`);
+        }
+    }
     for (const [slice, sliceEntries] of bySlice.entries()) {
         let state = "need_red";
         for (const entry of sliceEntries) {
@@ -79,7 +89,15 @@ export function validateTddCycleOrder(entries, options = {}) {
                 state = "green_done";
                 continue;
             }
-            // refactor
+            // refactor — must preserve the passing state established by green.
+            if (entry.exitCode === undefined) {
+                issues.push(`slice ${slice}: refactor entry must record exitCode 0`);
+                continue;
+            }
+            if (entry.exitCode !== 0) {
+                issues.push(`slice ${slice}: refactor entry exitCode must be 0 (tests must stay green)`);
+                continue;
+            }
             if (state !== "green_done") {
                 issues.push(`slice ${slice}: refactor logged before green`);
             }

package/dist/types.d.ts

@@ -109,7 +109,7 @@ export interface TddPathConfig {
 export interface CompoundConfig {
     recurrenceThreshold?: number;
 }
-export interface VibyConfig {
+export interface CclawConfig {
     version: string;
     flowVersion: string;
     harnesses: HarnessId[];
@@ -141,6 +141,7 @@ export interface VibyConfig {
     /**
      * Legacy alias for test-side path detection in workflow-guard.
      * Prefer `tdd.testPathPatterns` in new configs.
+     * @deprecated Use `tdd.testPathPatterns` instead.
      */
     tddTestGlobs?: string[];
     /** Path-pattern routing for TDD test/production write classification. */
@@ -173,6 +174,10 @@ export interface VibyConfig {
      */
     sliceReview?: SliceReviewConfig;
 }
+/**
+ * @deprecated Use `CclawConfig` instead.
+ */
+export type VibyConfig = CclawConfig;
 export interface TransitionRule {
     from: FlowStage;
     to: FlowStage;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.46.15",
+  "version": "0.48.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "test:mutation": "stryker run",
     "smoke:runtime": "npm run build && node scripts/smoke-init.mjs",
     "lint:hooks": "npm run build && node scripts/lint-generated-hooks.mjs",
     "build:harness-docs": "npm run build && node scripts/build-harness-docs.mjs",
@@ -44,6 +45,8 @@
     "yaml": "^2.8.1"
   },
   "devDependencies": {
+    "@stryker-mutator/core": "^9.6.1",
+    "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/node": "^24.7.2",
     "@vitest/coverage-v8": "^3.2.4",
     "typescript": "^5.9.3",