cclaw-cli 0.51.23 → 0.51.25

package/dist/internal/advance-stage.js

@@ -4,6 +4,7 @@ import { spawn } from "node:child_process";
 import process from "node:process";
 import { resolveArtifactPath } from "../artifact-paths.js";
 import { RUNTIME_ROOT, SHIP_FINALIZATION_MODES } from "../constants.js";
+import { ensureDir } from "../fs-utils.js";
 import { stageAutoSubagentDispatch, stageSchema } from "../content/stage-schema.js";
 import { appendDelegation, checkMandatoryDelegations, readDelegationLedger } from "../delegation.js";
 import { verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "../gate-evidence.js";
@@ -18,6 +19,7 @@ import { runEnvelopeValidateCommand } from "./envelope-validate.js";
 import { runTddLoopStatusCommand } from "./tdd-loop-status.js";
 import { runTddRedEvidenceCommand } from "./tdd-red-evidence.js";
 import { extractReviewLoopEnvelopeFromArtifact } from "../content/review-loop.js";
+import { PASS_STATUS_PATTERN, TEST_COMMAND_HINT_PATTERN, validateTddVerificationEvidence } from "../tdd-verification-evidence.js";
 const AUTO_REVIEW_LOOP_GATE_BY_STAGE = {
     design: "design_architecture_locked"
 };
@@ -52,9 +54,6 @@ function resolveSuccessorTransition(stage, track, transitionTargets, satisfiedGu
     }
     return natural;
 }
-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;
 const SHIP_FINALIZATION_MODE_PATTERN = new RegExp(`\\b(?:${SHIP_FINALIZATION_MODES.join("|")})\\b`, "u");
 const SHIP_FINALIZATION_MODE_HINT = SHIP_FINALIZATION_MODES.join(", ");
 const REVIEW_LOOP_STOP_REASONS = new Set([
@@ -191,18 +190,6 @@ function validateUserApprovalEvidence(evidence) {
 // 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;
-    },
     "review:review_trace_matrix_clean": (evidence) => {
         if (!TEST_COMMAND_HINT_PATTERN.test(evidence)) {
             return "must include the fresh verification command that was run before ship handoff (for example `npm test`, `pytest`, `go test`, or equivalent).";
@@ -221,11 +208,16 @@ const GATE_EVIDENCE_VALIDATORS = {
     "scope:scope_user_approved": (evidence) => validateUserApprovalEvidence(evidence),
     "design:design_architecture_locked": (evidence) => validateReviewLoopGateEvidence("design", evidence)
 };
-function validateGateEvidenceShape(stage, gateId, evidence) {
+async function validateGateEvidenceShape(projectRoot, stage, gateId, evidence) {
+    const normalized = evidence.trim();
+    if (stage === "tdd" && gateId === "tdd_verified_before_complete") {
+        const result = await validateTddVerificationEvidence(projectRoot, normalized);
+        return result.ok ? null : result.issues.join(" ");
+    }
     const validator = GATE_EVIDENCE_VALIDATORS[`${stage}:${gateId}`];
     if (!validator)
         return null;
-    return validator(evidence.trim());
+    return validator(normalized);
 }
 function reviewLoopArtifactFixHint(stage, gateId) {
     if (AUTO_REVIEW_LOOP_GATE_BY_STAGE[stage] !== gateId)
@@ -540,6 +532,50 @@ function parseVerifyCurrentStateArgs(tokens) {
     }
     return { quiet };
 }
+function parseRewindArgs(tokens) {
+    let quiet = false;
+    let json = false;
+    const positional = [];
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        const nextToken = tokens[i + 1];
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        if (token === "--json") {
+            json = true;
+            continue;
+        }
+        if (token === "--ack") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--ack requires a stage value.");
+            }
+            if (!isFlowStageValue(nextToken)) {
+                throw new Error(`--ack stage must be one of: ${FLOW_STAGES.join(", ")}.`);
+            }
+            i += 1;
+            return { mode: "ack", targetStage: nextToken, quiet, json };
+        }
+        if (token.startsWith("--ack=")) {
+            const stage = token.slice("--ack=".length);
+            if (!isFlowStageValue(stage)) {
+                throw new Error(`--ack stage must be one of: ${FLOW_STAGES.join(", ")}.`);
+            }
+            return { mode: "ack", targetStage: stage, quiet, json };
+        }
+        positional.push(token);
+    }
+    const [targetStage, ...reasonParts] = positional;
+    if (!isFlowStageValue(targetStage)) {
+        throw new Error(`internal rewind requires a target stage (${FLOW_STAGES.join(", ")}) or --ack <stage>.`);
+    }
+    const reason = reasonParts.join(" ").trim();
+    if (reason.length === 0) {
+        throw new Error('internal rewind requires a reason, for example: cclaw internal rewind tdd "review_blocked_by_critical".');
+    }
+    return { mode: "rewind", targetStage, reason, quiet, json };
+}
 function parseHookArgs(tokens) {
     const [hookName, ...rest] = tokens;
     const normalizedHook = typeof hookName === "string" ? hookName.trim() : "";
@@ -633,6 +669,7 @@ async function buildValidationReport(projectRoot, flowState, options = {}) {
             missing: delegation.missing,
             waived: delegation.waived,
             missingEvidence: delegation.missingEvidence,
+            staleWorkers: delegation.staleWorkers,
             expectedMode: delegation.expectedMode
         },
         gates: {
@@ -773,9 +810,11 @@ async function runAdvanceStage(projectRoot, args, io) {
         }
     }
     if (args.waiveDelegations.length > 0) {
-        const waiverReason = args.waiverReason && args.waiverReason.length > 0
-            ? args.waiverReason
-            : "manual_waiver";
+        const waiverReason = args.waiverReason?.trim();
+        if (!waiverReason) {
+            io.stderr.write("cclaw internal advance-stage: --waive-delegation requires an explicit non-empty --waiver-reason.\n");
+            return 1;
+        }
         for (const agent of args.waiveDelegations) {
             await appendDelegation(projectRoot, {
                 stage: args.stage,
@@ -812,7 +851,8 @@ async function runAdvanceStage(projectRoot, args, io) {
         io.stderr.write(`cclaw internal advance-stage: missing --evidence-json entries for passed gates: ${missingGuardEvidence.join(", ")}.\n`);
         return 1;
     }
-    const malformedGateEvidence = nextPassed.flatMap((gateId) => {
+    const malformedGateEvidence = [];
+    for (const gateId of nextPassed) {
         const provided = args.evidenceByGate[gateId];
         const existing = flowState.guardEvidence[gateId];
         const effectiveEvidence = typeof provided === "string" && provided.trim().length > 0
@@ -820,9 +860,11 @@ async function runAdvanceStage(projectRoot, args, io) {
             : typeof existing === "string" && existing.trim().length > 0
                 ? existing
                 : "";
-        const issue = validateGateEvidenceShape(args.stage, gateId, effectiveEvidence);
-        return issue ? [`${gateId}: ${issue}${reviewLoopArtifactFixHint(args.stage, gateId)}`] : [];
-    });
+        const issue = await validateGateEvidenceShape(projectRoot, args.stage, gateId, effectiveEvidence);
+        if (issue) {
+            malformedGateEvidence.push(`${gateId}: ${issue}${reviewLoopArtifactFixHint(args.stage, gateId)}`);
+        }
+    }
     if (malformedGateEvidence.length > 0) {
         io.stderr.write(`cclaw internal advance-stage: gate evidence format check failed: ${malformedGateEvidence.join(" | ")}.\n`);
         return 1;
@@ -871,6 +913,9 @@ async function runAdvanceStage(projectRoot, args, io) {
                     ...(validation.delegation.missingEvidence.length > 0
                         ? ["Add evidenceRefs for role-switch delegation completion or use an explicit waiver reason."]
                         : []),
+                    ...(validation.delegation.staleWorkers.length > 0
+                        ? ["Resolve scheduled delegation span(s) without terminal lifecycle evidence before advancing."]
+                        : []),
                     ...(validation.gates.issues.length > 0
                         ? ["Fix the artifact/gate issue shown in gates.issues, then rerun stage-complete."]
                         : []),
@@ -888,6 +933,9 @@ async function runAdvanceStage(projectRoot, args, io) {
         if (validation.delegation.missingEvidence.length > 0) {
             io.stderr.write(`- role-switch evidence missing: ${validation.delegation.missingEvidence.join(", ")}\n`);
         }
+        if (validation.delegation.staleWorkers.length > 0) {
+            io.stderr.write(`- stale scheduled delegations: ${validation.delegation.staleWorkers.join(", ")}\n`);
+        }
         if (validation.gates.issues.length > 0) {
             io.stderr.write(`- gate issues: ${validation.gates.issues.join(" | ")}\n`);
         }
@@ -1231,6 +1279,108 @@ async function runStartFlow(projectRoot, args, io) {
     }
     return 0;
 }
+function rewindLogPath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state", "rewind-log.jsonl");
+}
+function rewindId(date = new Date()) {
+    return `rewind-${date.getTime().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function stagesInvalidatedByRewind(current, targetStage) {
+    const ordered = TRACK_STAGES[current.track];
+    const targetIndex = ordered.indexOf(targetStage);
+    const currentIndex = ordered.indexOf(current.currentStage);
+    if (targetIndex < 0 || currentIndex < 0 || targetIndex > currentIndex) {
+        return [];
+    }
+    return ordered.slice(targetIndex, currentIndex + 1);
+}
+async function appendRewindLog(projectRoot, payload) {
+    const logPath = rewindLogPath(projectRoot);
+    await ensureDir(path.dirname(logPath));
+    await fs.appendFile(logPath, `${JSON.stringify(payload)}\n`, "utf8");
+}
+async function runRewind(projectRoot, args, io) {
+    const current = await readFlowState(projectRoot);
+    const now = new Date().toISOString();
+    if (args.mode === "ack") {
+        const marker = current.staleStages[args.targetStage];
+        if (!marker) {
+            io.stderr.write(`cclaw internal rewind: no stale marker exists for "${args.targetStage}".\n`);
+            return 1;
+        }
+        if (current.currentStage !== args.targetStage) {
+            io.stderr.write(`cclaw internal rewind: cannot ack "${args.targetStage}" while currentStage is "${current.currentStage}". Re-run the stale stage before acknowledging it.\n`);
+            return 1;
+        }
+        const staleStages = { ...current.staleStages };
+        delete staleStages[args.targetStage];
+        const nextState = { ...current, staleStages };
+        await writeFlowState(projectRoot, nextState);
+        const payload = {
+            ok: true,
+            command: "rewind",
+            action: "ack",
+            stage: args.targetStage,
+            acknowledgedAt: now,
+            rewindId: marker.rewindId
+        };
+        await appendRewindLog(projectRoot, payload);
+        if (!args.quiet) {
+            io.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        }
+        return 0;
+    }
+    const invalidatedStages = stagesInvalidatedByRewind(current, args.targetStage);
+    if (invalidatedStages.length === 0) {
+        io.stderr.write(`cclaw internal rewind: target "${args.targetStage}" is not an earlier or current stage on track "${current.track}" from "${current.currentStage}".\n`);
+        return 1;
+    }
+    const id = rewindId();
+    const completedInvalidated = new Set(invalidatedStages);
+    const staleStages = { ...current.staleStages };
+    for (const stage of invalidatedStages) {
+        staleStages[stage] = {
+            rewindId: id,
+            reason: args.reason ?? "rewind",
+            markedAt: now
+        };
+    }
+    const record = {
+        id,
+        fromStage: current.currentStage,
+        toStage: args.targetStage,
+        reason: args.reason ?? "rewind",
+        timestamp: now,
+        invalidatedStages
+    };
+    const nextState = {
+        ...current,
+        currentStage: args.targetStage,
+        completedStages: current.completedStages.filter((stage) => !completedInvalidated.has(stage)),
+        staleStages,
+        rewinds: [...current.rewinds, record]
+    };
+    await writeFlowState(projectRoot, nextState);
+    const payload = {
+        ok: true,
+        command: "rewind",
+        action: "rewind",
+        rewind: record,
+        currentStage: nextState.currentStage,
+        completedStages: nextState.completedStages,
+        staleStages: Object.keys(nextState.staleStages),
+        nextActions: [
+            `Re-run ${args.targetStage} stage work and update its artifact evidence.`,
+            `Then run cclaw internal rewind --ack ${args.targetStage}.`,
+            "Continue with /cc-next after the stale marker is acknowledged."
+        ]
+    };
+    await appendRewindLog(projectRoot, payload);
+    if (!args.quiet) {
+        io.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    }
+    return 0;
+}
 async function runHookCommand(projectRoot, args, io) {
     const runHookPath = path.join(projectRoot, RUNTIME_ROOT, "hooks", "run-hook.mjs");
     try {
@@ -1269,7 +1419,7 @@ async function runHookCommand(projectRoot, args, io) {
 export async function runInternalCommand(projectRoot, argv, io) {
     const [subcommand, ...tokens] = argv;
     if (!subcommand) {
-        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook-manifest | hook\n");
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook-manifest | hook\n");
         return 1;
     }
     try {
@@ -1279,6 +1429,9 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "start-flow") {
             return await runStartFlow(projectRoot, parseStartFlowArgs(tokens), io);
         }
+        if (subcommand === "rewind") {
+            return await runRewind(projectRoot, parseRewindArgs(tokens), io);
+        }
         if (subcommand === "verify-flow-state-diff") {
             return await runVerifyFlowStateDiff(projectRoot, parseVerifyFlowStateDiffArgs(tokens), io);
         }
@@ -1303,7 +1456,7 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "hook") {
             return await runHookCommand(projectRoot, parseHookArgs(tokens), io);
         }
-        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook-manifest | hook\n`);
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook-manifest | hook\n`);
         return 1;
     }
     catch (err) {

package/dist/knowledge-store.js

@@ -505,18 +505,40 @@ export async function appendKnowledge(projectRoot, seeds, defaults = {}) {
         appendedEntries
     };
 }
+const SHORT_TECHNICAL_TOKEN_SET = new Set(["ci", "db", "ui", "qa", "ux"]);
 function tokenizeText(value) {
     if (!value)
         return [];
-    return value
-        .toLowerCase()
-        .split(/[^a-z0-9]+/u)
-        .map((token) => token.trim())
-        .filter((token) => token.length >= 3);
+    const tokens = [];
+    const matches = value.matchAll(/[A-Za-z0-9]+/gu);
+    for (const match of matches) {
+        const raw = match[0] ?? "";
+        const normalized = raw.toLowerCase();
+        if (normalized.length >= 3) {
+            tokens.push(normalized);
+            continue;
+        }
+        if (/^[A-Z]{2}$/u.test(raw) || SHORT_TECHNICAL_TOKEN_SET.has(normalized)) {
+            tokens.push(normalized);
+        }
+    }
+    return tokens;
 }
 function uniqueTokens(values) {
     return [...new Set(values)];
 }
+function supersededTriggerSet(entries) {
+    const superseded = new Set();
+    for (const entry of entries) {
+        for (const trigger of entry.supersedes ?? []) {
+            superseded.add(normalizeText(trigger));
+        }
+    }
+    return superseded;
+}
+function isSupersededLearning(entry, supersededTriggers) {
+    return entry.superseded_by !== undefined || supersededTriggers.has(normalizeText(entry.trigger));
+}
 function pathTokens(paths) {
     if (!Array.isArray(paths) || paths.length === 0)
         return [];
@@ -538,7 +560,9 @@ export async function selectRelevantLearnings(projectRoot, options = {}) {
     const limit = typeof options.limit === "number" && Number.isFinite(options.limit) && options.limit > 0
         ? Math.floor(options.limit)
         : 8;
-    const ranked = entries.map((entry, index) => {
+    const staleTriggers = supersededTriggerSet(entries);
+    const activeEntries = entries.filter((entry) => !isSupersededLearning(entry, staleTriggers));
+    const ranked = activeEntries.map((entry, index) => {
         let score = 0;
         let stageScore = 0;
         if (stage) {

package/dist/run-archive.js

@@ -35,6 +35,13 @@ function stateDirPath(projectRoot) {
 function archiveLockPath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "state", ".archive.lock");
 }
+function compoundCloseoutComplete(state) {
+    return (state.closeout.compoundCompletedAt !== undefined ||
+        state.closeout.compoundPromoted > 0 ||
+        (state.closeout.compoundSkipped === true &&
+            typeof state.closeout.compoundSkipReason === "string" &&
+            state.closeout.compoundSkipReason.trim().length > 0));
+}
 async function snapshotStateDirectory(projectRoot, destinationRoot) {
     const sourceDir = stateDirPath(projectRoot);
     if (!(await exists(sourceDir))) {
@@ -209,6 +216,10 @@ export async function archiveRun(projectRoot, runName, options = {}) {
                 sourceState.closeout.retroSkipReason.trim().length > 0;
             const readyForArchive = sourceState.closeout.shipSubstate === "ready_to_archive";
             const inShipCloseout = sourceState.currentStage === "ship";
+            if (readyForArchive && !compoundCloseoutComplete(sourceState)) {
+                throw new Error("Archive blocked: compound closeout is incomplete. " +
+                    "Promote compound guidance or skip compound review with an explicit reason before archiving.");
+            }
             if (inShipCloseout && skipRetro) {
                 throw new Error("Archive blocked: --skip-retro is not allowed while current stage is ship. " +
                     "Complete closeout to ready_to_archive via /cc-next.");

package/dist/run-persistence.js

@@ -30,10 +30,28 @@ function validateFlowTransition(prev, next) {
     if (prev.track !== next.track) {
         throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `cannot change track from "${prev.track}" to "${next.track}" mid-run (activeRunId="${prev.activeRunId}"). Archive the run and start a new one to switch tracks.`);
     }
-    for (const completed of prev.completedStages) {
-        if (!next.completedStages.includes(completed)) {
-            throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `completedStages must be monotonic: stage "${completed}" was previously completed but is missing from the new state.`);
+    const newRewind = next.rewinds.length === prev.rewinds.length + 1
+        ? next.rewinds[next.rewinds.length - 1]
+        : undefined;
+    const isManagedRewind = newRewind !== undefined
+        && newRewind.fromStage === prev.currentStage
+        && newRewind.toStage === next.currentStage
+        && newRewind.invalidatedStages.includes(next.currentStage);
+    const removedCompletedStages = prev.completedStages.filter((stage) => !next.completedStages.includes(stage));
+    if (removedCompletedStages.length > 0 && !isManagedRewind) {
+        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `completedStages must be monotonic: stage(s) ${removedCompletedStages.map((stage) => `"${stage}"`).join(", ")} were previously completed but are missing from the new state.`);
+    }
+    if (isManagedRewind) {
+        const invalidated = new Set(newRewind.invalidatedStages);
+        const unexpectedRemoved = removedCompletedStages.filter((stage) => !invalidated.has(stage));
+        const missingMarkers = newRewind.invalidatedStages.filter((stage) => {
+            const marker = next.staleStages[stage];
+            return !marker || marker.rewindId !== newRewind.id;
+        });
+        if (unexpectedRemoved.length > 0 || missingMarkers.length > 0) {
+            throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `managed rewind state is inconsistent: unexpectedRemoved=${unexpectedRemoved.join(",") || "none"}; missingMarkers=${missingMarkers.join(",") || "none"}.`);
         }
+        return;
     }
     if (prev.currentStage === next.currentStage) {
         return;
@@ -255,21 +273,27 @@ function sanitizeCloseoutState(value) {
         ? true
         : undefined;
     const compoundCompletedAt = typeof typed.compoundCompletedAt === "string" ? typed.compoundCompletedAt : undefined;
-    const compoundSkipped = typeof typed.compoundSkipped === "boolean" ? typed.compoundSkipped : undefined;
+    const compoundSkipReason = typeof typed.compoundSkipReason === "string"
+        ? typed.compoundSkipReason.trim() || undefined
+        : undefined;
+    const compoundSkipped = typed.compoundSkipped === true && compoundSkipReason !== undefined
+        ? true
+        : undefined;
     const promotedRaw = typed.compoundPromoted;
     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.
+    // Demote shipSubstate when its closeout invariants are violated on disk. A
+    // hand-edited flow-state could claim `ready_to_archive` without completing
+    // the compound leg, which would let `archive` skip durable closeout proof.
     const retroDone = retroAcceptedAt !== undefined || retroSkipped === true;
+    const compoundDone = compoundCompletedAt !== undefined || compoundPromoted > 0 || compoundSkipped === true;
     if (!retroDone && (shipSubstate === "ready_to_archive" || shipSubstate === "compound_review")) {
         shipSubstate = "retro_review";
     }
+    else if (shipSubstate === "ready_to_archive" && !compoundDone) {
+        shipSubstate = "compound_review";
+    }
     return {
         shipSubstate,
         retroDraftedAt,
@@ -278,6 +302,7 @@ function sanitizeCloseoutState(value) {
         retroSkipReason,
         compoundCompletedAt,
         compoundSkipped,
+        compoundSkipReason,
         compoundPromoted
     };
 }

package/dist/tdd-verification-evidence.d.ts

@@ -0,0 +1,17 @@
+export declare const TEST_COMMAND_HINT_PATTERN: RegExp;
+export declare const SHA_WITH_LABEL_PATTERN: RegExp;
+export declare const PASS_STATUS_PATTERN: RegExp;
+export declare const NO_VCS_ATTESTATION_PATTERN: RegExp;
+export declare const NO_VCS_HASH_PATTERN: RegExp;
+export type TddVerificationRefMode = "auto" | "required" | "disabled";
+export interface TddVerificationEvidenceOptions {
+    requireCommand?: boolean;
+    requirePassStatus?: boolean;
+}
+export interface TddVerificationEvidenceResult {
+    ok: boolean;
+    issues: string[];
+    mode: TddVerificationRefMode;
+    gitPresent: boolean;
+}
+export declare function validateTddVerificationEvidence(projectRoot: string, evidence: string, options?: TddVerificationEvidenceOptions): Promise<TddVerificationEvidenceResult>;

package/dist/tdd-verification-evidence.js

@@ -0,0 +1,43 @@
+import path from "node:path";
+import { readConfig } from "./config.js";
+import { exists } from "./fs-utils.js";
+export const TEST_COMMAND_HINT_PATTERN = /\b(?:npm test|npm run test(?::[\w:-]+)?|pnpm test|pnpm [\w:-]*test[\w:-]*|yarn test|yarn [\w:-]*test[\w:-]*|bun test|bun run test(?::[\w:-]+)?|vitest|jest|pytest|go test|cargo test|mvn test|gradle test|\.\/gradlew test|dotnet test)\b/iu;
+export const SHA_WITH_LABEL_PATTERN = /\b(?:sha|commit)(?:\s*[:=]|\s+)\s*[0-9a-f]{7,40}\b/iu;
+export const PASS_STATUS_PATTERN = /\b(?:pass|passed|green|ok)\b/iu;
+export const NO_VCS_ATTESTATION_PATTERN = /\b(?:no[-_ ]?vcs|no git|not a git repo|vcs\s*[:=]\s*none)\b/iu;
+export const NO_VCS_HASH_PATTERN = /\b(?:content|artifact)[-_ ]?hash\s*[:=]\s*(?:sha256:)?[0-9a-f]{16,64}\b|\bsha256\s*[:=]\s*[0-9a-f]{16,64}\b/iu;
+export async function validateTddVerificationEvidence(projectRoot, evidence, options = {}) {
+    const normalized = evidence.trim();
+    const config = await readConfig(projectRoot);
+    const mode = config.tdd?.verificationRef ?? "auto";
+    const configuredVcs = config.vcs ?? "git-local-only";
+    const gitPresent = configuredVcs !== "none" && await exists(path.join(projectRoot, ".git"));
+    const issues = [];
+    if (options.requireCommand !== false && !TEST_COMMAND_HINT_PATTERN.test(normalized)) {
+        issues.push("must include the fresh verification command that was run (for example `npm test`, `pytest`, `go test`, or equivalent).");
+    }
+    if (options.requirePassStatus !== false && !PASS_STATUS_PATTERN.test(normalized)) {
+        issues.push("must include explicit success status (for example `PASS` or `GREEN`).");
+    }
+    const hasSha = SHA_WITH_LABEL_PATTERN.test(normalized);
+    const hasNoVcs = NO_VCS_ATTESTATION_PATTERN.test(normalized);
+    const hasNoVcsHash = NO_VCS_HASH_PATTERN.test(normalized);
+    if (mode !== "disabled" && configuredVcs === "none") {
+        if (!hasNoVcs) {
+            issues.push("must include an explicit no-VCS reason because `vcs` is `none`.");
+        }
+        if (!hasNoVcsHash) {
+            issues.push("must include a content/artifact hash for no-VCS TDD evidence (for example `artifact-hash: sha256:<hash>`).");
+        }
+    }
+    else if (mode === "required" && !hasSha) {
+        issues.push("must include a commit SHA token prefixed with `sha` or `commit` because `tdd.verificationRef` is `required`.");
+    }
+    else if (mode === "auto" && gitPresent && !hasSha) {
+        issues.push("must include a commit SHA token prefixed with `sha` or `commit` (for example `sha: abc1234`).");
+    }
+    else if (mode === "auto" && !gitPresent && !hasSha && !hasNoVcs) {
+        issues.push("must include either a commit SHA or an explicit no-VCS attestation (for example `no-vcs: project has no .git directory`).");
+    }
+    return { ok: issues.length === 0, issues, mode, gitPresent };
+}

package/dist/types.d.ts

@@ -99,6 +99,13 @@ export interface SliceReviewConfig {
 export interface TddPathConfig {
     testPathPatterns?: string[];
     productionPathPatterns?: string[];
+    /**
+     * Verification reference policy for tdd_verified_before_complete evidence.
+     * - auto: require commit SHA when .git exists; with vcs:none require no-VCS reason plus content/artifact hash.
+     * - required: always require a commit SHA except explicit vcs:none still uses no-VCS hash evidence.
+     * - disabled: command + pass status are enough.
+     */
+    verificationRef?: "auto" | "required" | "disabled";
 }
 /**
  * Compound-stage clustering policy.
@@ -141,10 +148,13 @@ export interface ReviewLoopExternalSecondOpinionConfig {
 export interface ReviewLoopConfig {
     externalSecondOpinion?: ReviewLoopExternalSecondOpinionConfig;
 }
+export type VcsMode = "git-with-remote" | "git-local-only" | "none";
 export interface CclawConfig {
     version: string;
     flowVersion: string;
     harnesses: HarnessId[];
+    /** Repository evidence mode for stages that need durable verification refs. */
+    vcs?: VcsMode;
     /**
      * Single knob that controls enforcement behaviour of all hook-driven guards
      * (prompt guard, workflow guard, TDD enforcement, iron laws). Default:

package/package.json

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