cclaw-cli 0.51.19 → 0.51.22

package/dist/harness-adapters.js

@@ -134,11 +134,7 @@ export function harnessTier(harnessId) {
         capabilities.hookSurface === "full") {
         return "tier1";
     }
-    if (capabilities.hookSurface === "full" ||
-        capabilities.hookSurface === "plugin" ||
-        capabilities.hookSurface === "limited" ||
-        capabilities.nativeSubagentDispatch === "generic" ||
-        capabilities.nativeSubagentDispatch === "partial") {
+    if (capabilities.hookSurface !== "none" || capabilities.nativeSubagentDispatch !== "none") {
         return "tier2";
     }
     return "tier3";

package/dist/install.js

@@ -34,10 +34,17 @@ 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";
 const GIT_HOOK_RUNTIME_REL_DIR = `${RUNTIME_ROOT}/hooks/git`;
+const INIT_SENTINEL_FILE = ".init-in-progress";
 const execFileAsync = promisify(execFile);
 function runtimePath(projectRoot, ...segments) {
     return path.join(projectRoot, RUNTIME_ROOT, ...segments);
 }
+async function writeInitSentinel(projectRoot, operation) {
+    const sentinelPath = runtimePath(projectRoot, "state", INIT_SENTINEL_FILE);
+    await ensureDir(path.dirname(sentinelPath));
+    await writeFileSafe(sentinelPath, `${JSON.stringify({ operation, startedAt: new Date().toISOString() }, null, 2)}\n`);
+    return sentinelPath;
+}
 async function removeBestEffort(targetPath, recursive = false) {
     try {
         await fs.rm(targetPath, { recursive, force: true });
@@ -393,13 +400,37 @@ async function writeSkills(projectRoot, config) {
     // legacy per-language skill folders from v0.7.0 (.cclaw/skills/language-*)
     // are cleaned up below so the new rules/lang layout is the only truth.
     const enabledPacks = config?.languageRulePacks ?? [];
+    const enabledPackFileNames = new Set();
     for (const pack of enabledPacks) {
         const fileName = LANGUAGE_RULE_PACK_FILES[pack];
         const generator = LANGUAGE_RULE_PACK_GENERATORS[pack];
         if (!fileName || !generator)
             continue;
+        enabledPackFileNames.add(fileName);
         await writeFileSafe(runtimePath(projectRoot, ...LANGUAGE_RULE_PACK_DIR, fileName), generator());
     }
+    // Strict idempotence: once a pack is removed from config, its generated
+    // file under .cclaw/rules/lang/ must disappear on the next sync. Without
+    // this loop the directory accumulates a superset of every pack ever
+    // enabled, which silently keeps stale guidance alive.
+    const langDir = runtimePath(projectRoot, ...LANGUAGE_RULE_PACK_DIR);
+    if (await exists(langDir)) {
+        const knownPackFileNames = new Set(Object.values(LANGUAGE_RULE_PACK_FILES));
+        let entries = [];
+        try {
+            entries = await fs.readdir(langDir);
+        }
+        catch {
+            entries = [];
+        }
+        for (const entry of entries) {
+            if (!knownPackFileNames.has(entry))
+                continue;
+            if (enabledPackFileNames.has(entry))
+                continue;
+            await fs.rm(path.join(langDir, entry), { force: true });
+        }
+    }
     for (const legacyFolder of LEGACY_LANGUAGE_RULE_PACK_FOLDERS) {
         const legacyPath = runtimePath(projectRoot, "skills", legacyFolder);
         if (await exists(legacyPath)) {
@@ -629,6 +660,54 @@ async function backupHookFile(projectRoot, hookFilePath, rawContent) {
     await pruneOldHookBackups(backupsDir);
     return backupPath;
 }
+function normalizeHookCommandForDedupe(command) {
+    return command.trim().replace(/\s+/gu, " ").replace(/\\/gu, "/");
+}
+function dedupeHookEntryByCommand(entry, seenCommands) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return entry;
+    }
+    const obj = entry;
+    let changed = false;
+    if (typeof obj.command === "string") {
+        const normalized = normalizeHookCommandForDedupe(obj.command);
+        if (seenCommands.has(normalized)) {
+            return undefined;
+        }
+        seenCommands.add(normalized);
+    }
+    if (Array.isArray(obj.hooks)) {
+        const hooks = [];
+        for (const nested of obj.hooks) {
+            const deduped = dedupeHookEntryByCommand(nested, seenCommands);
+            if (deduped !== undefined) {
+                hooks.push(deduped);
+            }
+            else {
+                changed = true;
+            }
+        }
+        if (hooks.length !== obj.hooks.length) {
+            changed = true;
+        }
+        if (hooks.length === 0 && typeof obj.command !== "string") {
+            return undefined;
+        }
+        return changed ? { ...obj, hooks } : entry;
+    }
+    return entry;
+}
+function dedupeHookEntriesByCommand(entries) {
+    const seenCommands = new Set();
+    const deduped = [];
+    for (const entry of entries) {
+        const next = dedupeHookEntryByCommand(entry, seenCommands);
+        if (next !== undefined) {
+            deduped.push(next);
+        }
+    }
+    return deduped;
+}
 function mergeHookDocuments(existingDoc, generatedDoc) {
     const generatedRoot = toObject(generatedDoc) ?? {};
     const generatedHooks = toObject(generatedRoot.hooks) ?? {};
@@ -640,7 +719,7 @@ function mergeHookDocuments(existingDoc, generatedDoc) {
         const existingEntries = existingHooks[eventName];
         if (Array.isArray(generatedEntries)) {
             const preservedEntries = Array.isArray(existingEntries) ? existingEntries : [];
-            mergedHooks[eventName] = [...generatedEntries, ...preservedEntries];
+            mergedHooks[eventName] = dedupeHookEntriesByCommand([...generatedEntries, ...preservedEntries]);
             continue;
         }
         // Defensive: malformed generated event payload must not wipe user hooks.
@@ -920,26 +999,34 @@ async function cleanStaleFiles(projectRoot) {
     // Keep user-owned custom assets under .cclaw/agents and .cclaw/skills.
     // Legacy managed removals happen in cleanLegacyArtifacts() with explicit paths.
 }
-async function materializeRuntime(projectRoot, config, forceStateReset) {
-    const harnesses = config.harnesses;
-    await ensureStructure(projectRoot);
-    await cleanLegacyArtifacts(projectRoot);
-    await cleanStaleFiles(projectRoot);
-    await Promise.all([
-        writeEntryCommands(projectRoot),
-        writeSkills(projectRoot, config),
-        writeArtifactTemplates(projectRoot),
-        writeRulebook(projectRoot)
-    ]);
-    await writeState(projectRoot, config, forceStateReset);
-    await ensureRunSystem(projectRoot, { createIfMissing: false });
-    await ensureKnowledgeStore(projectRoot);
-    await writeHooks(projectRoot, config);
-    await syncDisabledHarnessArtifacts(projectRoot, harnesses);
-    await syncManagedGitHooks(projectRoot, config);
-    await syncHarnessShims(projectRoot, harnesses);
-    await writeCursorWorkflowRule(projectRoot, harnesses);
-    await ensureGitignore(projectRoot);
+async function materializeRuntime(projectRoot, config, forceStateReset, operation = "sync") {
+    const sentinelPath = await writeInitSentinel(projectRoot, operation);
+    try {
+        const harnesses = config.harnesses;
+        await ensureStructure(projectRoot);
+        await cleanLegacyArtifacts(projectRoot);
+        await cleanStaleFiles(projectRoot);
+        await Promise.all([
+            writeEntryCommands(projectRoot),
+            writeSkills(projectRoot, config),
+            writeArtifactTemplates(projectRoot),
+            writeRulebook(projectRoot)
+        ]);
+        await writeState(projectRoot, config, forceStateReset);
+        await ensureRunSystem(projectRoot, { createIfMissing: false });
+        await ensureKnowledgeStore(projectRoot);
+        await writeHooks(projectRoot, config);
+        await syncDisabledHarnessArtifacts(projectRoot, harnesses);
+        await syncManagedGitHooks(projectRoot, config);
+        await syncHarnessShims(projectRoot, harnesses);
+        await writeCursorWorkflowRule(projectRoot, harnesses);
+        await ensureGitignore(projectRoot);
+        await fs.unlink(sentinelPath).catch(() => undefined);
+    }
+    catch (error) {
+        // Leave the sentinel in place so doctor can surface the interrupted run.
+        throw error;
+    }
 }
 export async function initCclaw(options) {
     const baseConfig = createDefaultConfig(options.harnesses, options.track);
@@ -954,7 +1041,7 @@ export async function initCclaw(options) {
     // and only appear in the on-disk file when the user sets them explicitly
     // or a non-default value was detected (e.g. languageRulePacks).
     await writeConfig(options.projectRoot, config, { mode: "minimal" });
-    await materializeRuntime(options.projectRoot, config, true);
+    await materializeRuntime(options.projectRoot, config, true, "init");
 }
 export async function syncCclaw(projectRoot) {
     const configExists = await exists(configPath(projectRoot));
@@ -972,7 +1059,7 @@ export async function syncCclaw(projectRoot) {
         await writeConfig(projectRoot, defaultConfig);
         config = defaultConfig;
     }
-    await materializeRuntime(projectRoot, config, false);
+    await materializeRuntime(projectRoot, config, false, "sync");
 }
 /**
  * Refresh generated files in `.cclaw/` without touching user-authored
@@ -996,7 +1083,7 @@ export async function upgradeCclaw(projectRoot) {
         mode: "minimal",
         advancedKeysPresent
     });
-    await materializeRuntime(projectRoot, upgraded, false);
+    await materializeRuntime(projectRoot, upgraded, false, "upgrade");
 }
 function stripManagedHookCommands(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {

package/dist/internal/advance-stage.js

@@ -230,7 +230,7 @@ function validateGateEvidenceShape(stage, gateId, evidence) {
 function reviewLoopArtifactFixHint(stage, gateId) {
     if (AUTO_REVIEW_LOOP_GATE_BY_STAGE[stage] !== gateId)
         return "";
-    return " Add a `## Spec Review Loop` table to the artifact with rows like `| 1 | 0.80 | 0 |` plus `- Stop reason: quality_threshold_met`, `- Target score: 0.80`, and `- Max iterations: 3`; then omit this gate from manual evidence so stage-complete can auto-hydrate it.";
+    return ` Add a \`## ${stage === "scope" ? "Scope Outside Voice Loop" : "Design Outside Voice Loop"}\` table to the artifact with rows like \`| 1 | 0.80 | 0 |\` plus \`- Stop reason: quality_threshold_met\`, \`- Target score: 0.80\`, and \`- Max iterations: 3\`; then omit this gate from manual evidence so stage-complete can auto-hydrate it.`;
 }
 function parseStringList(raw) {
     if (!Array.isArray(raw))
@@ -401,9 +401,7 @@ async function hydrateReviewLoopEvidenceFromArtifact(projectRoot, stage, track,
         return;
     const existing = evidenceByGate[gateId];
     if (typeof existing === "string" && existing.trim().length > 0) {
-        const existingIssue = validateGateEvidenceShape(stage, gateId, existing);
-        if (!existingIssue)
-            return;
+        return;
     }
     const resolved = await resolveArtifactPath(stage, {
         projectRoot,
@@ -617,11 +615,16 @@ function parseStartFlowArgs(tokens) {
     }
     return { track, className, prompt, reason, stack, forceReset, reclassify, quiet };
 }
-async function buildValidationReport(projectRoot, flowState) {
+async function buildValidationReport(projectRoot, flowState, options = {}) {
     const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage);
     const gates = await verifyCurrentStageGateEvidence(projectRoot, flowState);
     const completedStages = verifyCompletedStagesGateClosure(flowState);
-    const ok = delegation.satisfied && gates.ok && gates.complete && completedStages.ok;
+    const blockedReviewRouteComplete = options.allowBlockedReviewRoute === true
+        && flowState.currentStage === "review"
+        && typeof flowState.guardEvidence.review_verdict_blocked === "string"
+        && flowState.guardEvidence.review_verdict_blocked.trim().length > 0
+        && !flowState.stageGateCatalog.review.passed.includes("review_criticals_resolved");
+    const ok = delegation.satisfied && gates.ok && (gates.complete || blockedReviewRouteComplete) && completedStages.ok;
     return {
         ok,
         stage: flowState.currentStage,
@@ -753,7 +756,11 @@ async function runAdvanceStage(projectRoot, args, io) {
         : requiredGateIds;
     const selectedGateIdSet = new Set(selectedGateIds);
     const selectedTransitionGuards = selectedGateIds.filter((gateId) => transitionGuardIds.has(gateId));
-    const missingRequired = requiredGateIds.filter((gateId) => !selectedGateIdSet.has(gateId));
+    const blockedReviewRoute = args.stage === "review" && selectedGateIdSet.has("review_verdict_blocked");
+    const requiredForSelectedRoute = blockedReviewRoute
+        ? requiredGateIds.filter((gateId) => gateId !== "review_criticals_resolved")
+        : requiredGateIds;
+    const missingRequired = requiredForSelectedRoute.filter((gateId) => !selectedGateIdSet.has(gateId));
     if (missingRequired.length > 0) {
         io.stderr.write(`cclaw internal advance-stage: required gates not selected as passed: ${missingRequired.join(", ")}.\n`);
         return 1;
@@ -844,7 +851,9 @@ async function runAdvanceStage(projectRoot, args, io) {
             [args.stage]: nextStageCatalog
         }
     };
-    const validation = await buildValidationReport(projectRoot, candidateState);
+    const validation = await buildValidationReport(projectRoot, candidateState, {
+        allowBlockedReviewRoute: blockedReviewRoute
+    });
     if (!validation.ok) {
         if (args.json) {
             io.stdout.write(`${JSON.stringify({
@@ -894,9 +903,11 @@ async function runAdvanceStage(projectRoot, args, io) {
     }
     const satisfiedGuards = new Set([...nextPassed, ...selectedTransitionGuards]);
     const successor = resolveSuccessorTransition(args.stage, flowState.track, transitionTargets, satisfiedGuards, new Set(selectedTransitionGuards));
-    const completedStages = flowState.completedStages.includes(args.stage)
-        ? [...flowState.completedStages]
-        : [...flowState.completedStages, args.stage];
+    const completedStages = blockedReviewRoute
+        ? flowState.completedStages.filter((stage) => stage !== args.stage)
+        : flowState.completedStages.includes(args.stage)
+            ? [...flowState.completedStages]
+            : [...flowState.completedStages, args.stage];
     const finalState = {
         ...candidateState,
         completedStages,
@@ -969,6 +980,55 @@ function firstIncompleteStageForTrack(track, completedStages) {
     const stages = TRACK_STAGES[track];
     return stages.find((stage) => !completed.has(stage)) ?? stages[stages.length - 1] ?? "brainstorm";
 }
+function carriedCompletedStageCatalog(current, fresh, stage) {
+    const previousCatalog = current.stageGateCatalog[stage];
+    const freshCatalog = fresh.stageGateCatalog[stage];
+    const allowed = new Set([...freshCatalog.required, ...freshCatalog.recommended]);
+    const previousPassed = new Set(previousCatalog.passed.filter((gateId) => allowed.has(gateId)));
+    const previousBlocked = new Set(previousCatalog.blocked.filter((gateId) => allowed.has(gateId)));
+    const orderedAllowed = [...freshCatalog.required, ...freshCatalog.recommended];
+    const evidence = {};
+    const passed = orderedAllowed.filter((gateId) => {
+        if (!previousPassed.has(gateId))
+            return false;
+        const note = current.guardEvidence[gateId];
+        if (typeof note !== "string" || note.trim().length === 0)
+            return false;
+        evidence[gateId] = note.trim();
+        return true;
+    });
+    const passedSet = new Set(passed);
+    return {
+        catalog: {
+            required: [...freshCatalog.required],
+            recommended: [...freshCatalog.recommended],
+            conditional: [],
+            triggered: [],
+            passed,
+            blocked: orderedAllowed.filter((gateId) => previousBlocked.has(gateId) && !passedSet.has(gateId))
+        },
+        evidence
+    };
+}
+function completedStageClosureEvidenceIssues(flowState) {
+    const issues = [];
+    for (const stage of flowState.completedStages) {
+        const schema = stageSchema(stage, flowState.track);
+        const catalog = flowState.stageGateCatalog[stage];
+        const required = schema.requiredGates
+            .filter((gate) => gate.tier === "required")
+            .map((gate) => gate.id);
+        for (const gateId of required) {
+            if (!catalog.passed.includes(gateId))
+                continue;
+            const note = flowState.guardEvidence[gateId];
+            if (typeof note !== "string" || note.trim().length === 0) {
+                issues.push(`completed stage "${stage}" passed gate "${gateId}" is missing guardEvidence.`);
+            }
+        }
+    }
+    return issues;
+}
 async function ensureProactiveDelegationTrace(projectRoot, stage) {
     const proactiveRules = stageAutoSubagentDispatch(stage).filter((rule) => rule.mode === "proactive");
     if (proactiveRules.length === 0)
@@ -1126,13 +1186,32 @@ async function runStartFlow(projectRoot, args, io) {
     if (args.reclassify) {
         const completedInNewTrack = current.completedStages.filter((stage) => TRACK_STAGES[args.track].includes(stage));
         const fresh = createInitialFlowState({ activeRunId: current.activeRunId, track: args.track });
+        const stageGateCatalog = { ...fresh.stageGateCatalog };
+        const guardEvidence = {};
+        for (const stage of completedInNewTrack) {
+            const carried = carriedCompletedStageCatalog(current, fresh, stage);
+            stageGateCatalog[stage] = carried.catalog;
+            Object.assign(guardEvidence, carried.evidence);
+        }
         nextState = {
             ...fresh,
             completedStages: completedInNewTrack,
             currentStage: firstIncompleteStageForTrack(args.track, completedInNewTrack),
+            guardEvidence,
+            stageGateCatalog,
             rewinds: current.rewinds,
             staleStages: current.staleStages
         };
+        const validation = await buildValidationReport(projectRoot, nextState);
+        const evidenceIssues = completedStageClosureEvidenceIssues(nextState);
+        if (!validation.completedStages.ok || evidenceIssues.length > 0) {
+            io.stderr.write("cclaw internal start-flow: reclassification would leave completed stages without valid gate closure.\n");
+            const issues = [...validation.completedStages.issues, ...evidenceIssues];
+            if (issues.length > 0) {
+                io.stderr.write(`- completed-stage closure issues: ${issues.join(" | ")}\n`);
+            }
+            return 1;
+        }
     }
     else {
         nextState = createInitialFlowState({ track: args.track });

package/dist/knowledge-store.d.ts

@@ -174,7 +174,10 @@ export declare function effectiveCompoundThreshold(baseThreshold: number, archiv
  * as ready.
  */
 export declare function computeCompoundReadiness(entries: KnowledgeEntry[], options?: ComputeCompoundReadinessOptions): CompoundReadiness;
-export declare function validateKnowledgeEntry(entry: unknown): {
+export interface ValidateKnowledgeEntryOptions {
+    allowLegacyOriginFeature?: boolean;
+}
+export declare function validateKnowledgeEntry(entry: unknown, options?: ValidateKnowledgeEntryOptions): {
     ok: boolean;
     errors: string[];
 };

package/dist/knowledge-store.js

@@ -171,11 +171,13 @@ const KNOWLEDGE_REQUIRED_KEYS = [
     "project"
 ];
 const KNOWLEDGE_ALLOWED_KEYS = new Set(KNOWLEDGE_REQUIRED_KEYS);
-KNOWLEDGE_ALLOWED_KEYS.add("origin_feature");
 KNOWLEDGE_ALLOWED_KEYS.add("source");
 KNOWLEDGE_ALLOWED_KEYS.add("severity");
 KNOWLEDGE_ALLOWED_KEYS.add("supersedes");
 KNOWLEDGE_ALLOWED_KEYS.add("superseded_by");
+function keyAllowedInKnowledgeEntry(key, options) {
+    return KNOWLEDGE_ALLOWED_KEYS.has(key) || (options.allowLegacyOriginFeature === true && key === "origin_feature");
+}
 function knowledgePath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
 }
@@ -236,7 +238,7 @@ function parseKnowledgeSnapshot(raw) {
             continue;
         try {
             const parsed = JSON.parse(trimmed);
-            const validated = validateKnowledgeEntry(parsed);
+            const validated = validateKnowledgeEntry(parsed, { allowLegacyOriginFeature: true });
             if (!validated.ok) {
                 malformedLines += 1;
                 continue;
@@ -294,20 +296,22 @@ function isNullableString(value) {
 function isNullableStage(value) {
     return value === null || (typeof value === "string" && FLOW_STAGE_SET.has(value));
 }
-export function validateKnowledgeEntry(entry) {
+export function validateKnowledgeEntry(entry, options = {}) {
     const errors = [];
     if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
         return { ok: false, errors: ["Knowledge entry must be a JSON object."] };
     }
     const obj = entry;
     for (const key of Object.keys(obj)) {
-        if (!KNOWLEDGE_ALLOWED_KEYS.has(key)) {
+        if (!keyAllowedInKnowledgeEntry(key, options)) {
             errors.push(`Unknown key "${key}" in knowledge entry.`);
         }
     }
     for (const key of KNOWLEDGE_REQUIRED_KEYS) {
         if (!Object.prototype.hasOwnProperty.call(obj, key)) {
-            if (key !== "origin_run" || !Object.prototype.hasOwnProperty.call(obj, "origin_feature")) {
+            if (key !== "origin_run" ||
+                options.allowLegacyOriginFeature !== true ||
+                !Object.prototype.hasOwnProperty.call(obj, "origin_feature")) {
                 errors.push(`Missing required key "${key}".`);
             }
         }
@@ -339,7 +343,9 @@ export function validateKnowledgeEntry(entry) {
     }
     const originRun = Object.prototype.hasOwnProperty.call(obj, "origin_run")
         ? obj.origin_run
-        : obj.origin_feature;
+        : options.allowLegacyOriginFeature === true
+            ? obj.origin_feature
+            : undefined;
     if (!isNullableString(originRun)) {
         errors.push("origin_run must be string or null.");
     }
@@ -534,16 +540,15 @@ export async function selectRelevantLearnings(projectRoot, options = {}) {
         : 8;
     const ranked = entries.map((entry, index) => {
         let score = 0;
+        let stageScore = 0;
         if (stage) {
             if (entry.stage === stage) {
-                score += 4;
+                stageScore = 4;
             }
             else if (entry.origin_stage === stage) {
-                score += 3;
-            }
-            else if (entry.stage === null) {
-                score += 1;
+                stageScore = 3;
             }
+            score += stageScore;
         }
         if (entry.confidence === "high")
             score += 2;
@@ -561,17 +566,22 @@ export async function selectRelevantLearnings(projectRoot, options = {}) {
             ...tokenizeText(entry.project)
         ];
         const searchSet = new Set(searchable);
+        let contextualScore = 0;
         for (const token of branchTokens) {
             if (searchSet.has(token))
-                score += 2;
+                contextualScore += 2;
         }
         for (const token of diffTokens) {
             if (searchSet.has(token))
-                score += 2;
+                contextualScore += 2;
         }
         for (const token of gateTokens) {
             if (searchSet.has(token))
-                score += 2;
+                contextualScore += 2;
+        }
+        score += contextualScore;
+        if (stage && entry.stage === null && stageScore === 0 && contextualScore < 4) {
+            score = 0;
         }
         return {
             index,

package/dist/retro-gate.d.ts

@@ -4,5 +4,6 @@ export interface RetroGateStatus {
     completed: boolean;
     compoundEntries: number;
     hasRetroArtifact: boolean;
+    skipped: boolean;
 }
 export declare function evaluateRetroGate(projectRoot: string, state: FlowState): Promise<RetroGateStatus>;

package/dist/retro-gate.js

@@ -42,11 +42,10 @@ export async function evaluateRetroGate(projectRoot, state) {
             hasRetroArtifact = false;
         }
     }
-    let compoundEntries = state.retro.compoundEntries;
+    let compoundEntries = 0;
     let windowStartMs = parseIsoTimestamp(state.closeout.retroDraftedAt);
     let windowEndMs = parseIsoTimestamp(state.closeout.retroAcceptedAt) ?? parseIsoTimestamp(state.retro.completedAt);
-    if (compoundEntries <= 0 &&
-        hasRetroArtifact &&
+    if (hasRetroArtifact &&
         windowStartMs === null &&
         windowEndMs === null) {
         try {
@@ -61,8 +60,8 @@ export async function evaluateRetroGate(projectRoot, state) {
             // fallback scan remains disabled when mtime cannot be read
         }
     }
-    const shouldFallbackScan = compoundEntries <= 0 && (windowStartMs !== null || windowEndMs !== null);
-    if (shouldFallbackScan) {
+    const shouldScanCompoundEvidence = windowStartMs !== null || windowEndMs !== null;
+    if (shouldScanCompoundEvidence) {
         const countIfEligible = (parsed) => {
             if (parsed.type !== "compound") {
                 return 0;
@@ -80,7 +79,6 @@ export async function evaluateRetroGate(projectRoot, state) {
         try {
             const knowledgeFile = path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
             const { entries } = await readKnowledgeSafely(projectRoot);
-            compoundEntries = 0;
             for (const parsed of entries) {
                 compoundEntries += countIfEligible(parsed);
             }
@@ -111,12 +109,13 @@ export async function evaluateRetroGate(projectRoot, state) {
     //     promoted during the retro window OR compound was explicitly skipped
     //     after reviewing the draft), or
     //   - the operator explicitly skipped the retro step itself
-    //     (`retroSkipped === true` with a reason). `retroSkipped` is an
+    //     (`retroSkipped === true` with a non-empty reason). `retroSkipped` is an
     //     operator-level override of the artifact requirement, so it must
     //     bypass `hasRetroArtifact` — otherwise a run that legitimately had
     //     nothing worth retro-ing dead-locks at closeout waiting for a
     //     file that will never exist.
-    const retroSkipped = state.closeout.retroSkipped === true;
+    const retroSkipReason = state.closeout.retroSkipReason?.trim() ?? "";
+    const retroSkipped = state.closeout.retroSkipped === true && retroSkipReason.length > 0;
     const compoundSkipped = state.closeout.compoundSkipped === true;
     const artifactPathComplete = hasRetroArtifact && (compoundEntries > 0 || compoundSkipped);
     const completed = required ? retroSkipped || artifactPathComplete : true;
@@ -124,6 +123,7 @@ export async function evaluateRetroGate(projectRoot, state) {
         required,
         completed,
         compoundEntries,
-        hasRetroArtifact
+        hasRetroArtifact,
+        skipped: retroSkipped
     };
 }

package/dist/run-archive.js

@@ -83,6 +83,24 @@ async function resetCarryoverStateFiles(projectRoot, activeRunId) {
     await writeFileSafe(path.join(stateDir, TDD_CYCLE_LOG_FILE), "", { mode: 0o600 });
     await writeFileSafe(path.join(stateDir, RECONCILIATION_NOTICES_FILE), `${JSON.stringify({ schemaVersion: 1, notices: [] }, null, 2)}\n`, { mode: 0o600 });
 }
+async function restoreStateSnapshot(projectRoot, archiveStatePath) {
+    if (!(await exists(archiveStatePath)))
+        return;
+    const stateDir = stateDirPath(projectRoot);
+    await ensureDir(stateDir);
+    const entries = await fs.readdir(archiveStatePath, { withFileTypes: true });
+    for (const entry of entries) {
+        const from = path.join(archiveStatePath, entry.name);
+        const to = path.join(stateDir, entry.name);
+        if (entry.isDirectory()) {
+            await fs.rm(to, { recursive: true, force: true });
+            await fs.cp(from, to, { recursive: true });
+        }
+        else if (entry.isFile()) {
+            await fs.copyFile(from, to);
+        }
+    }
+}
 function toArchiveDate(date = new Date()) {
     const yyyy = date.getFullYear().toString();
     const mm = (date.getMonth() + 1).toString().padStart(2, "0");
@@ -296,8 +314,8 @@ export async function archiveRun(projectRoot, runName, options = {}) {
                 }
                 if (stateReset) {
                     try {
+                        await restoreStateSnapshot(projectRoot, path.join(archivePath, "state"));
                         await writeFlowState(projectRoot, stateBeforeReset, { allowReset: true, skipLock: true });
-                        await resetCarryoverStateFiles(projectRoot, stateBeforeReset.activeRunId);
                     }
                     catch {
                         // If rollback of state fails, keep sentinel + archive remnants for

package/dist/run-persistence.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
-import { canTransition, createInitialCloseoutState, createInitialFlowState, FLOW_STATE_SCHEMA_VERSION, isFlowTrack, skippedStagesForTrack, SHIP_SUBSTATES } from "./flow-state.js";
+import { nextStage, createInitialCloseoutState, createInitialFlowState, FLOW_STATE_SCHEMA_VERSION, isFlowTrack, skippedStagesForTrack, SHIP_SUBSTATES } from "./flow-state.js";
 import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 import { FLOW_STAGES } from "./types.js";
 export class InvalidStageTransitionError extends Error {
@@ -38,8 +38,11 @@ function validateFlowTransition(prev, next) {
     if (prev.currentStage === next.currentStage) {
         return;
     }
-    if (!canTransition(prev.currentStage, next.currentStage)) {
-        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `no transition rule allows "${prev.currentStage}" -> "${next.currentStage}". Use /cc-next to advance stages or archive the run to reset.`);
+    const naturalForward = nextStage(prev.currentStage, prev.track);
+    const isNaturalForward = naturalForward === next.currentStage;
+    const isReviewRewind = prev.currentStage === "review" && next.currentStage === "tdd";
+    if (!isNaturalForward && !isReviewRewind) {
+        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `no transition rule allows "${prev.currentStage}" -> "${next.currentStage}" for track "${prev.track}". Use /cc-next to advance stages or archive the run to reset.`);
     }
 }
 function flowStatePath(projectRoot) {
@@ -245,8 +248,12 @@ function sanitizeCloseoutState(value) {
     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;
-    const retroSkipReason = typeof typed.retroSkipReason === "string" ? typed.retroSkipReason : undefined;
+    const retroSkipReason = typeof typed.retroSkipReason === "string"
+        ? typed.retroSkipReason.trim() || undefined
+        : undefined;
+    const retroSkipped = typed.retroSkipped === true && retroSkipReason !== undefined
+        ? true
+        : undefined;
     const compoundCompletedAt = typeof typed.compoundCompletedAt === "string" ? typed.compoundCompletedAt : undefined;
     const compoundSkipped = typeof typed.compoundSkipped === "boolean" ? typed.compoundSkipped : undefined;
     const promotedRaw = typed.compoundPromoted;

package/dist/tdd-cycle.js

@@ -146,7 +146,6 @@ export function validateTddCycleOrder(entries, options = {}) {
                 issues.push(`slice ${slice}: refactor logged before green`);
                 continue;
             }
-            state = "need_red";
         }
         if (state === "red_open") {
             openRedSlices.push(slice);
@@ -191,8 +190,12 @@ export function pathMatchesTarget(candidate, target) {
     if (normalizedCandidate.length === 0 || normalizedTarget.length === 0) {
         return false;
     }
-    return (normalizedCandidate === normalizedTarget ||
-        normalizedCandidate.endsWith(`/${normalizedTarget}`));
+    if (normalizedCandidate === normalizedTarget) {
+        return true;
+    }
+    // Only allow suffix matching for multi-segment targets. A bare basename
+    // like `app.ts` is too broad and can match unrelated files in any folder.
+    return normalizedTarget.includes("/") && normalizedCandidate.endsWith(`/${normalizedTarget}`);
 }
 /**
  * Derive a lightweight Ralph Loop summary from parsed tdd-cycle-log entries.