cclaw-cli 0.51.21 → 0.51.22

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

@@ -248,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.51.21",
+  "version": "0.51.22",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {