cclaw-cli 0.51.28 → 0.51.29

package/dist/managed-resources.js

@@ -0,0 +1,289 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { CCLAW_VERSION, RUNTIME_ROOT } from "./constants.js";
+import { HARNESS_IDS } from "./types.js";
+export const MANAGED_RESOURCE_MANIFEST_REL_PATH = `${RUNTIME_ROOT}/state/managed-resources.json`;
+const MANAGED_RESOURCE_HARNESSES = new Set(["core", ...HARNESS_IDS]);
+const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/iu;
+let activeSession = null;
+function sha256(content) {
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+function normalizeRelPath(projectRoot, filePath) {
+    const rel = path.relative(projectRoot, filePath).replace(/\\/gu, "/");
+    if (rel.startsWith("../") || rel === ".." || path.isAbsolute(rel))
+        return null;
+    return rel;
+}
+async function exists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+}
+async function atomicWrite(filePath, content, options = {}) {
+    await ensureDir(path.dirname(filePath));
+    const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+    await fs.writeFile(tempPath, content, {
+        encoding: "utf8",
+        ...(options.mode !== undefined ? { mode: options.mode } : {})
+    });
+    await fs.rename(tempPath, filePath);
+    if (options.mode !== undefined) {
+        await fs.chmod(filePath, options.mode).catch(() => undefined);
+    }
+}
+function inferHarness(relPath) {
+    if (relPath.startsWith(".claude/"))
+        return "claude";
+    if (relPath.startsWith(".cursor/"))
+        return "cursor";
+    if (relPath.startsWith(".opencode/"))
+        return "opencode";
+    if (relPath.startsWith(".codex/") || relPath.startsWith(".agents/skills/"))
+        return "codex";
+    return "core";
+}
+export function isManagedGeneratedPath(relPath) {
+    if (relPath === MANAGED_RESOURCE_MANIFEST_REL_PATH)
+        return false;
+    if (relPath === `${RUNTIME_ROOT}/config.yaml`)
+        return false;
+    if (relPath === `${RUNTIME_ROOT}/knowledge.jsonl`)
+        return false;
+    if (relPath.startsWith(`${RUNTIME_ROOT}/artifacts/`))
+        return false;
+    if (relPath.startsWith(`${RUNTIME_ROOT}/runs/`))
+        return false;
+    if (relPath === `${RUNTIME_ROOT}/state/flow-state.json`)
+        return false;
+    if (relPath === `${RUNTIME_ROOT}/state/.init-in-progress`)
+        return false;
+    if (relPath.startsWith(`${RUNTIME_ROOT}/state/upgrade-backups/`))
+        return false;
+    if (relPath.startsWith(`${RUNTIME_ROOT}/state/sync-backups/`))
+        return false;
+    if (relPath === "AGENTS.md" || relPath === "CLAUDE.md")
+        return true;
+    if (relPath === `${RUNTIME_ROOT}/state/iron-laws.json`)
+        return true;
+    for (const prefix of [
+        `${RUNTIME_ROOT}/commands/`,
+        `${RUNTIME_ROOT}/skills/`,
+        `${RUNTIME_ROOT}/templates/`,
+        `${RUNTIME_ROOT}/rules/`,
+        `${RUNTIME_ROOT}/agents/`,
+        `${RUNTIME_ROOT}/hooks/`,
+        ".claude/commands/",
+        ".cursor/commands/",
+        ".opencode/commands/",
+        ".opencode/agents/",
+        ".codex/agents/",
+        ".agents/skills/"
+    ]) {
+        if (relPath.startsWith(prefix))
+            return true;
+    }
+    return relPath === ".claude/hooks/hooks.json" ||
+        relPath === ".cursor/hooks.json" ||
+        relPath === ".cursor/rules/cclaw-workflow.mdc" ||
+        relPath === ".codex/hooks.json" ||
+        relPath === ".opencode/plugins/cclaw-plugin.mjs";
+}
+function validationIssue(index, field, message, pathValue) {
+    return {
+        ...(index !== undefined ? { index } : {}),
+        ...(typeof pathValue === "string" ? { path: pathValue } : {}),
+        field,
+        message
+    };
+}
+function validateSha256(value) {
+    return typeof value === "string" && SHA256_HEX_PATTERN.test(value);
+}
+export function validateManagedResourceEntry(value, index) {
+    const issues = [];
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return [validationIssue(index, "entry", "entry must be an object")];
+    }
+    const entry = value;
+    if (typeof entry.path !== "string" || entry.path.trim().length === 0) {
+        issues.push(validationIssue(index, "path", "path must be a non-empty string", entry.path));
+    }
+    else if (entry.path.startsWith("../") || entry.path === ".." || path.isAbsolute(entry.path)) {
+        issues.push(validationIssue(index, "path", "path must be project-relative", entry.path));
+    }
+    else if (!isManagedGeneratedPath(entry.path)) {
+        issues.push(validationIssue(index, "path", "path must be a known generated cclaw surface", entry.path));
+    }
+    if (!validateSha256(entry.sha256)) {
+        issues.push(validationIssue(index, "sha256", "sha256 must be a 64-character hex digest", entry.path));
+    }
+    if (entry.owner !== "cclaw") {
+        issues.push(validationIssue(index, "owner", 'owner must be "cclaw"', entry.path));
+    }
+    if (typeof entry.harness !== "string" || !MANAGED_RESOURCE_HARNESSES.has(entry.harness)) {
+        issues.push(validationIssue(index, "harness", `harness must be one of: core, ${HARNESS_IDS.join(", ")}`, entry.path));
+    }
+    if (typeof entry.packageVersion !== "string" || entry.packageVersion.trim().length === 0) {
+        issues.push(validationIssue(index, "packageVersion", "packageVersion must be a non-empty string", entry.path));
+    }
+    if (typeof entry.prunable !== "boolean") {
+        issues.push(validationIssue(index, "prunable", "prunable must be a boolean", entry.path));
+    }
+    if (typeof entry.safeToOverwrite !== "boolean") {
+        issues.push(validationIssue(index, "safeToOverwrite", "safeToOverwrite must be a boolean", entry.path));
+    }
+    if (typeof entry.updatedAt !== "string" || entry.updatedAt.trim().length === 0) {
+        issues.push(validationIssue(index, "updatedAt", "updatedAt must be a non-empty string", entry.path));
+    }
+    if (entry.lastBackupPath !== undefined && (typeof entry.lastBackupPath !== "string" || entry.lastBackupPath.trim().length === 0)) {
+        issues.push(validationIssue(index, "lastBackupPath", "lastBackupPath must be a non-empty string when present", entry.path));
+    }
+    if (entry.previousSha256 !== undefined && !validateSha256(entry.previousSha256)) {
+        issues.push(validationIssue(index, "previousSha256", "previousSha256 must be a 64-character hex digest when present", entry.path));
+    }
+    return issues;
+}
+export function validateManagedResourceManifest(value) {
+    const issues = [];
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return [validationIssue(undefined, "manifest", "manifest must be an object")];
+    }
+    const manifest = value;
+    if (manifest.version !== 1) {
+        issues.push(validationIssue(undefined, "version", "version must be 1"));
+    }
+    if (typeof manifest.generatedAt !== "string" || manifest.generatedAt.trim().length === 0) {
+        issues.push(validationIssue(undefined, "generatedAt", "generatedAt must be a non-empty string"));
+    }
+    if (typeof manifest.packageVersion !== "string" || manifest.packageVersion.trim().length === 0) {
+        issues.push(validationIssue(undefined, "packageVersion", "packageVersion must be a non-empty string"));
+    }
+    if (!Array.isArray(manifest.resources)) {
+        issues.push(validationIssue(undefined, "resources", "resources must be an array"));
+        return issues;
+    }
+    manifest.resources.forEach((entry, index) => {
+        issues.push(...validateManagedResourceEntry(entry, index));
+    });
+    return issues;
+}
+export function isValidManagedResourceEntry(value) {
+    return validateManagedResourceEntry(value).length === 0;
+}
+export async function readManagedResourceManifest(projectRoot) {
+    const manifestPath = path.join(projectRoot, MANAGED_RESOURCE_MANIFEST_REL_PATH);
+    if (!(await exists(manifestPath)))
+        return null;
+    const parsed = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+    if (parsed.version !== 1 || !Array.isArray(parsed.resources))
+        return null;
+    const resources = parsed.resources.filter(isValidManagedResourceEntry);
+    return {
+        version: 1,
+        generatedAt: typeof parsed.generatedAt === "string" ? parsed.generatedAt : new Date(0).toISOString(),
+        packageVersion: typeof parsed.packageVersion === "string" ? parsed.packageVersion : "unknown",
+        resources
+    };
+}
+export class ManagedResourceSession {
+    projectRoot;
+    operation;
+    timestamp;
+    previous = new Map();
+    touched = new Map();
+    constructor(options, previous) {
+        this.projectRoot = options.projectRoot;
+        this.operation = options.operation;
+        this.timestamp = new Date().toISOString().replace(/[:.]/gu, "-");
+        for (const entry of previous?.resources ?? []) {
+            this.previous.set(entry.path, entry);
+        }
+    }
+    static async create(options) {
+        const previous = await readManagedResourceManifest(options.projectRoot).catch(() => null);
+        return new ManagedResourceSession(options, previous);
+    }
+    shouldManage(filePath) {
+        const rel = normalizeRelPath(this.projectRoot, filePath);
+        return rel !== null && isManagedGeneratedPath(rel);
+    }
+    async writeFileSafe(filePath, content, options = {}) {
+        const rel = normalizeRelPath(this.projectRoot, filePath);
+        if (rel === null || !isManagedGeneratedPath(rel)) {
+            await atomicWrite(filePath, content, options);
+            return;
+        }
+        const nextHash = sha256(content);
+        const previous = this.previous.get(rel);
+        let previousSha256;
+        let lastBackupPath;
+        if (await exists(filePath)) {
+            const current = await fs.readFile(filePath);
+            const currentHash = sha256(current);
+            previousSha256 = currentHash;
+            const knownPrevious = previous?.sha256;
+            if (currentHash !== nextHash && (knownPrevious === undefined || currentHash !== knownPrevious)) {
+                const backupRoot = path.join(this.projectRoot, RUNTIME_ROOT, "state", this.operation === "upgrade" ? "upgrade-backups" : "sync-backups", this.timestamp);
+                const backupPath = path.join(backupRoot, rel);
+                await ensureDir(path.dirname(backupPath));
+                await fs.copyFile(filePath, backupPath);
+                lastBackupPath = normalizeRelPath(this.projectRoot, backupPath) ?? undefined;
+            }
+        }
+        await atomicWrite(filePath, content, options);
+        this.touched.set(rel, {
+            path: rel,
+            sha256: nextHash,
+            owner: "cclaw",
+            harness: inferHarness(rel),
+            packageVersion: CCLAW_VERSION,
+            prunable: true,
+            safeToOverwrite: true,
+            updatedAt: new Date().toISOString(),
+            ...(lastBackupPath ? { lastBackupPath } : {}),
+            ...(previousSha256 && previousSha256 !== nextHash ? { previousSha256 } : {})
+        });
+    }
+    async commit() {
+        const resourcesByPath = new Map(this.previous);
+        for (const [rel, entry] of this.touched) {
+            resourcesByPath.set(rel, entry);
+        }
+        const resources = [];
+        for (const entry of resourcesByPath.values()) {
+            if (await exists(path.join(this.projectRoot, entry.path))) {
+                resources.push(entry);
+            }
+        }
+        const manifest = {
+            version: 1,
+            generatedAt: new Date().toISOString(),
+            packageVersion: CCLAW_VERSION,
+            resources: resources.sort((a, b) => a.path.localeCompare(b.path))
+        };
+        await atomicWrite(path.join(this.projectRoot, MANAGED_RESOURCE_MANIFEST_REL_PATH), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+        return manifest;
+    }
+}
+export function getActiveManagedResourceSession() {
+    return activeSession;
+}
+export function setActiveManagedResourceSession(session) {
+    activeSession = session;
+}
+export function isManagedResourcePath(projectRoot, filePath) {
+    const rel = normalizeRelPath(projectRoot, filePath);
+    return rel !== null && isManagedGeneratedPath(rel);
+}
+export function hashManagedResourceContent(content) {
+    return sha256(content);
+}

package/dist/run-archive.d.ts

@@ -1,5 +1,7 @@
 import { type FlowState } from "./flow-state.js";
 import type { FlowStage } from "./types.js";
+export declare const ARCHIVE_DISPOSITIONS: readonly ["completed", "cancelled", "abandoned"];
+export type ArchiveDisposition = (typeof ARCHIVE_DISPOSITIONS)[number];
 export interface CclawRunMeta {
     id: string;
     title: string;
@@ -12,6 +14,8 @@ export interface ArchiveRunResult {
     runName: string;
     resetState: FlowState;
     snapshottedStateFiles: string[];
+    disposition: ArchiveDisposition;
+    dispositionReason?: string;
     /** Knowledge curation hint: total active entries + soft threshold (50). */
     knowledge: {
         activeEntryCount: number;
@@ -36,11 +40,15 @@ export interface ArchiveManifest {
     sourceCurrentStage: FlowStage;
     sourceCompletedStages: FlowStage[];
     snapshottedStateFiles: string[];
+    disposition: ArchiveDisposition;
+    dispositionReason?: string;
     retro: ArchiveRunResult["retro"];
 }
 export interface ArchiveRunOptions {
     skipRetro?: boolean;
     skipRetroReason?: string;
+    disposition?: ArchiveDisposition;
+    dispositionReason?: string;
 }
 export declare function listRuns(projectRoot: string): Promise<CclawRunMeta[]>;
 export declare function archiveRun(projectRoot: string, runName?: string, options?: ArchiveRunOptions): Promise<ArchiveRunResult>;

package/dist/run-archive.js

@@ -6,6 +6,7 @@ import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.
 import { readKnowledgeSafely } from "./knowledge-store.js";
 import { evaluateRetroGate } from "./retro-gate.js";
 import { ensureRunSystem, flowStateLockPathFor, readFlowState, writeFlowState } from "./run-persistence.js";
+export const ARCHIVE_DISPOSITIONS = ["completed", "cancelled", "abandoned"];
 const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
 const ACTIVE_ARTIFACTS_REL_PATH = `${RUNTIME_ROOT}/artifacts`;
 const STATE_DIR_REL_PATH = `${RUNTIME_ROOT}/state`;
@@ -205,35 +206,44 @@ export async function archiveRun(projectRoot, runName, options = {}) {
             const archiveArtifactsPath = path.join(archivePath, "artifacts");
             let sourceState = await readFlowState(projectRoot);
             const retroGate = await evaluateRetroGate(projectRoot, sourceState);
+            const disposition = options.disposition ?? "completed";
+            const dispositionReason = options.dispositionReason?.trim();
+            const nonCompletedDisposition = disposition !== "completed";
+            if (nonCompletedDisposition && (!dispositionReason || dispositionReason.length === 0)) {
+                throw new Error("archive --disposition=cancelled|abandoned requires --reason=<text>.");
+            }
             const shipCompleted = sourceState.completedStages.includes("ship");
             const skipRetro = options.skipRetro === true;
             const skipRetroReason = options.skipRetroReason?.trim();
             if (skipRetro && (!skipRetroReason || skipRetroReason.length === 0)) {
                 throw new Error("archive --skip-retro requires --retro-reason=<text>.");
             }
+            if (nonCompletedDisposition && skipRetro) {
+                throw new Error("archive --skip-retro is only valid for completed archives; use --reason with cancelled/abandoned.");
+            }
             const retroSkippedInCloseout = sourceState.closeout.retroSkipped === true &&
                 typeof sourceState.closeout.retroSkipReason === "string" &&
                 sourceState.closeout.retroSkipReason.trim().length > 0;
             const readyForArchive = sourceState.closeout.shipSubstate === "ready_to_archive";
             const inShipCloseout = sourceState.currentStage === "ship";
-            if (readyForArchive && !compoundCloseoutComplete(sourceState)) {
+            if (!nonCompletedDisposition && 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) {
+            if (!nonCompletedDisposition && 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.");
             }
-            if (inShipCloseout && !readyForArchive) {
+            if (!nonCompletedDisposition && inShipCloseout && !readyForArchive) {
                 throw new Error("Archive blocked: closeout is not ready_to_archive. " +
                     "Resume /cc-next until closeout reaches ready_to_archive.");
             }
-            if (shipCompleted && !readyForArchive && !skipRetro) {
+            if (!nonCompletedDisposition && shipCompleted && !readyForArchive && !skipRetro) {
                 throw new Error("Archive blocked: closeout is not ready_to_archive. " +
                     "Resume /cc-next until closeout reaches ready_to_archive, " +
                     "or run `cclaw archive --skip-retro --retro-reason=<text>` for CLI-only flows.");
             }
-            if (retroGate.required && !retroGate.completed && !skipRetro && !retroSkippedInCloseout) {
+            if (!nonCompletedDisposition && retroGate.required && !retroGate.completed && !skipRetro && !retroSkippedInCloseout) {
                 throw new Error("Archive blocked: retro gate is required after ship completion. " +
                     "Run /cc-next (auto-runs retro) or, for CLI-only flows, re-run `cclaw archive --skip-retro --retro-reason=<text>`.");
             }
@@ -291,6 +301,8 @@ export async function archiveRun(projectRoot, runName, options = {}) {
                     sourceCurrentStage: sourceState.currentStage,
                     sourceCompletedStages: sourceState.completedStages,
                     snapshottedStateFiles,
+                    disposition,
+                    ...(dispositionReason ? { dispositionReason } : {}),
                     retro: retroSummary
                 };
                 await writeFileSafe(path.join(archivePath, "archive-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
@@ -304,6 +316,8 @@ export async function archiveRun(projectRoot, runName, options = {}) {
                     runName: archiveRunName,
                     resetState,
                     snapshottedStateFiles,
+                    disposition,
+                    ...(dispositionReason ? { dispositionReason } : {}),
                     knowledge: knowledgeStats,
                     retro: retroSummary
                 };

package/dist/runs.d.ts

@@ -1,2 +1,2 @@
 export { CorruptFlowStateError, InvalidStageTransitionError, type WriteFlowStateOptions, ensureRunSystem, readFlowState, writeFlowState } from "./run-persistence.js";
-export { archiveRun, countActiveKnowledgeEntries, listRuns, type ArchiveManifest, type ArchiveRunOptions, type ArchiveRunResult, type CclawRunMeta } from "./run-archive.js";
+export { ARCHIVE_DISPOSITIONS, archiveRun, countActiveKnowledgeEntries, listRuns, type ArchiveDisposition, type ArchiveManifest, type ArchiveRunOptions, type ArchiveRunResult, type CclawRunMeta } from "./run-archive.js";

package/dist/runs.js

@@ -1,2 +1,2 @@
 export { CorruptFlowStateError, InvalidStageTransitionError, ensureRunSystem, readFlowState, writeFlowState } from "./run-persistence.js";
-export { archiveRun, countActiveKnowledgeEntries, listRuns } from "./run-archive.js";
+export { ARCHIVE_DISPOSITIONS, archiveRun, countActiveKnowledgeEntries, listRuns } from "./run-archive.js";

package/dist/tdd-cycle.js

@@ -95,7 +95,7 @@ export function validateTddCycleOrder(entries, options = {}) {
     // 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)`);
+            issues.push(`slice "${slice}": id must match /^S-\\d+$/ (e.g. S-1); repair by re-logging RED/GREEN/REFACTOR with a stable slice id.`);
         }
     }
     for (const [slice, sliceEntries] of bySlice.entries()) {
@@ -103,15 +103,15 @@ export function validateTddCycleOrder(entries, options = {}) {
         for (const entry of sliceEntries) {
             if (entry.phase === "red") {
                 if (entry.exitCode === undefined) {
-                    issues.push(`slice ${slice}: red entry must record a non-zero exitCode`);
+                    issues.push(`slice ${slice}: RED repair needed: red entry must record a non-zero exitCode from a failing test.`);
                     continue;
                 }
                 if (entry.exitCode === 0) {
-                    issues.push(`slice ${slice}: red entry exitCode must be non-zero`);
+                    issues.push(`slice ${slice}: RED repair needed: red entry exitCode must be non-zero; passing output is not RED evidence.`);
                     continue;
                 }
                 if (state === "red_open") {
-                    issues.push(`slice ${slice}: duplicate red before green`);
+                    issues.push(`slice ${slice}: RED/GREEN repair needed: duplicate RED before GREEN; record the GREEN pass that closes the prior RED or split into a new slice.`);
                     continue;
                 }
                 state = "red_open";
@@ -119,15 +119,15 @@ export function validateTddCycleOrder(entries, options = {}) {
             }
             if (entry.phase === "green") {
                 if (entry.exitCode === undefined) {
-                    issues.push(`slice ${slice}: green entry must record exitCode 0`);
+                    issues.push(`slice ${slice}: GREEN repair needed: green entry must record exitCode 0 from the verification command.`);
                     continue;
                 }
                 if (entry.exitCode !== 0) {
-                    issues.push(`slice ${slice}: green entry exitCode must be 0`);
+                    issues.push(`slice ${slice}: GREEN repair needed: green entry exitCode must be 0; fix regressions before advancing.`);
                     continue;
                 }
                 if (state !== "red_open") {
-                    issues.push(`slice ${slice}: green logged before red`);
+                    issues.push(`slice ${slice}: GREEN repair needed: green logged before RED; add the failing RED test evidence first.`);
                     continue;
                 }
                 state = "green_done";
@@ -135,15 +135,15 @@ export function validateTddCycleOrder(entries, options = {}) {
             }
             // refactor — must preserve the passing state established by green.
             if (entry.exitCode === undefined) {
-                issues.push(`slice ${slice}: refactor entry must record exitCode 0`);
+                issues.push(`slice ${slice}: REFACTOR repair needed: refactor entry must record exitCode 0 proving behavior stayed green.`);
                 continue;
             }
             if (entry.exitCode !== 0) {
-                issues.push(`slice ${slice}: refactor entry exitCode must be 0 (tests must stay green)`);
+                issues.push(`slice ${slice}: REFACTOR repair needed: tests must stay green after cleanup; rerun/fix before closing the slice.`);
                 continue;
             }
             if (state !== "green_done") {
-                issues.push(`slice ${slice}: refactor logged before green`);
+                issues.push(`slice ${slice}: REFACTOR repair needed: refactor logged before GREEN; prove GREEN first, then cleanup.`);
                 continue;
             }
         }

package/dist/tdd-verification-evidence.js

@@ -14,20 +14,20 @@ export async function validateTddVerificationEvidence(projectRoot, evidence, opt
     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).");
+        issues.push("GREEN repair needed: 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`).");
+        issues.push("GREEN repair needed: 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`.");
+            issues.push("NO_VCS_MODE repair needed: 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>`).");
+            issues.push("NO_VCS_MODE repair needed: include a content/artifact hash for no-VCS TDD evidence (for example `artifact-hash: sha256:<hash>`).");
         }
     }
     else if (mode === "required" && !hasSha) {

package/dist/track-heuristics.d.ts

@@ -3,6 +3,8 @@ export interface TrackResolution {
     track: FlowTrack;
     reason: string;
     matchedTokens: string[];
+    confidence: "high" | "medium" | "low";
+    overrideGuidance: string;
 }
 /**
  * Reference implementation of the track classifier the /cc skill prose

package/dist/track-heuristics.js

@@ -111,15 +111,23 @@ export function resolveTrackFromPrompt(prompt, config) {
         if (matched.length > 0) {
             return {
                 track,
-                reason: `matched ${track} heuristic`,
-                matchedTokens: matched
+                reason: `matched ${track} heuristic (${matched.join(", ")})`,
+                matchedTokens: matched,
+                confidence: matched.length > 1 ? "high" : "medium",
+                overrideGuidance: track === "quick"
+                    ? "Use medium/standard instead when product framing, architecture, schema, migration, security, or unclear scope appears; quick skips ceremony, not safety."
+                    : track === "medium"
+                        ? "Use standard if architecture, data model, security boundary, or migration risk is uncertain."
+                        : "Use medium or quick only when the blast radius and architecture are already known."
             };
         }
     }
     return {
         track: fallback,
         reason: `no explicit match, fallback=${fallback}`,
-        matchedTokens: []
+        matchedTokens: [],
+        confidence: "low",
+        overrideGuidance: "Confirm or override before state is written; choose quick only for known low-blast-radius work, medium for known architecture with product framing, standard for uncertainty."
     };
 }
 export const TRACK_HEURISTICS_DEFAULTS = {

package/package.json

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