cclaw-cli 0.46.14 → 0.47.0

package/dist/internal/advance-stage.js

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

package/dist/knowledge-store.d.ts

@@ -1,6 +1,7 @@
 import { type FlowStage } from "./types.js";
 export type KnowledgeEntryType = "rule" | "pattern" | "lesson" | "compound";
 export type KnowledgeEntryConfidence = "high" | "medium" | "low";
+export type KnowledgeEntrySeverity = "critical" | "important" | "suggestion";
 export type KnowledgeEntryUniversality = "project" | "personal" | "universal";
 export type KnowledgeEntryMaturity = "raw" | "lifted-to-rule" | "lifted-to-enforcement";
 export type KnowledgeEntrySource = "stage" | "retro" | "compound" | "ideate" | "manual";
@@ -9,6 +10,7 @@ export interface KnowledgeEntry {
     trigger: string;
     action: string;
     confidence: KnowledgeEntryConfidence;
+    severity?: KnowledgeEntrySeverity;
     domain: string | null;
     stage: FlowStage | null;
     origin_stage: FlowStage | null;
@@ -27,6 +29,7 @@ export interface KnowledgeSeedEntry {
     trigger: string;
     action: string;
     confidence: KnowledgeEntryConfidence;
+    severity?: KnowledgeEntrySeverity;
     domain?: string | null;
     stage?: FlowStage | null;
     origin_stage?: FlowStage | null;

package/dist/knowledge-store.js

@@ -5,6 +5,7 @@ import { withDirectoryLock } from "./fs-utils.js";
 import { FLOW_STAGES } from "./types.js";
 const KNOWLEDGE_TYPE_SET = new Set(["rule", "pattern", "lesson", "compound"]);
 const KNOWLEDGE_CONFIDENCE_SET = new Set(["high", "medium", "low"]);
+const KNOWLEDGE_SEVERITY_SET = new Set(["critical", "important", "suggestion"]);
 const KNOWLEDGE_UNIVERSALITY_SET = new Set(["project", "personal", "universal"]);
 const KNOWLEDGE_MATURITY_SET = new Set(["raw", "lifted-to-rule", "lifted-to-enforcement"]);
 const KNOWLEDGE_SOURCE_SET = new Set([
@@ -34,6 +35,7 @@ const KNOWLEDGE_REQUIRED_KEYS = [
 ];
 const KNOWLEDGE_ALLOWED_KEYS = new Set(KNOWLEDGE_REQUIRED_KEYS);
 KNOWLEDGE_ALLOWED_KEYS.add("source");
+KNOWLEDGE_ALLOWED_KEYS.add("severity");
 function knowledgePath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
 }
@@ -60,7 +62,8 @@ function dedupeKey(entry) {
         entry.origin_feature === null ? "null" : normalizeText(entry.origin_feature),
         entry.universality,
         entry.project === null ? "null" : normalizeText(entry.project),
-        entry.source === undefined || entry.source === null ? "null" : entry.source
+        entry.source === undefined || entry.source === null ? "null" : entry.source,
+        entry.severity === undefined ? "none" : entry.severity
     ].join("|");
 }
 function isIsoUtcTimestamp(value) {
@@ -100,6 +103,10 @@ export function validateKnowledgeEntry(entry) {
     if (!KNOWLEDGE_CONFIDENCE_SET.has(obj.confidence)) {
         errors.push("confidence must be one of: high, medium, low.");
     }
+    if (obj.severity !== undefined &&
+        (typeof obj.severity !== "string" || !KNOWLEDGE_SEVERITY_SET.has(obj.severity))) {
+        errors.push("severity must be one of: critical, important, suggestion.");
+    }
     if (!isNullableString(obj.domain)) {
         errors.push("domain must be string or null.");
     }
@@ -161,6 +168,9 @@ export function materializeKnowledgeEntry(seed, defaults = {}) {
         last_seen_ts: normalizeUtcIso(seed.last_seen_ts ?? now),
         project: seed.project ?? defaults.project ?? null
     };
+    if (seed.severity !== undefined) {
+        entry.severity = seed.severity;
+    }
     if (source !== null) {
         entry.source = source;
     }

package/dist/retro-gate.js

@@ -73,7 +73,17 @@ export async function evaluateRetroGate(projectRoot, state) {
             compoundEntries = 0;
         }
     }
-    const completed = required ? (hasRetroArtifact && compoundEntries > 0) : true;
+    // A retro is considered complete when either:
+    //   - at least one compound learning was promoted during the retro window, or
+    //   - the operator explicitly skipped retro or compound (`retroSkipped` /
+    //     `compoundSkipped` recorded in the closeout substate) after reviewing
+    //     the draft. Previously the gate required `compoundEntries > 0`
+    //     unconditionally, which dead-locked ship closeout whenever the retro
+    //     yielded no new patterns worth promoting.
+    const explicitSkip = Boolean(state.closeout.retroSkipped || state.closeout.compoundSkipped);
+    const completed = required
+        ? hasRetroArtifact && (compoundEntries > 0 || explicitSkip)
+        : true;
     return {
         required,
         completed,

package/dist/run-persistence.js

@@ -235,7 +235,7 @@ function sanitizeCloseoutState(value) {
         return fallback;
     }
     const typed = value;
-    const shipSubstate = isShipSubstate(typed.shipSubstate) ? typed.shipSubstate : fallback.shipSubstate;
+    let shipSubstate = isShipSubstate(typed.shipSubstate) ? typed.shipSubstate : fallback.shipSubstate;
     const retroDraftedAt = typeof typed.retroDraftedAt === "string" ? typed.retroDraftedAt : undefined;
     const retroAcceptedAt = typeof typed.retroAcceptedAt === "string" ? typed.retroAcceptedAt : undefined;
     const retroSkipped = typeof typed.retroSkipped === "boolean" ? typed.retroSkipped : undefined;
@@ -246,6 +246,16 @@ function sanitizeCloseoutState(value) {
     const compoundPromoted = typeof promotedRaw === "number" && Number.isFinite(promotedRaw) && promotedRaw >= 0
         ? Math.floor(promotedRaw)
         : 0;
+    // Demote shipSubstate when its retro invariant is violated on disk. A
+    // hand-edited flow-state could claim `ready_to_archive` or `compound_review`
+    // without ever going through the retro step, which would let `archive`
+    // proceed and skip the gate. Compound completion is not independently
+    // tracked in all flows (some runs rely on knowledge.jsonl + the retro
+    // window), so we only demote when the retro leg is missing outright.
+    const retroDone = retroAcceptedAt !== undefined || retroSkipped === true;
+    if (!retroDone && (shipSubstate === "ready_to_archive" || shipSubstate === "compound_review")) {
+        shipSubstate = "retro_review";
+    }
     return {
         shipSubstate,
         retroDraftedAt,

package/dist/tdd-cycle.js

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

package/dist/types.d.ts

@@ -88,6 +88,27 @@ export interface SliceReviewConfig {
     /** Tracks on which missed reviews escalate to a doctor warning. */
     enforceOnTracks?: FlowTrack[];
 }
+/**
+ * File-path routing hints used by workflow-guard during `tdd` stage.
+ *
+ * - `testPathPatterns`: paths considered test-side changes (RED writes).
+ * - `productionPathPatterns`: optional allowlist for production paths that
+ *   participate in GREEN/REFACTOR checks. When omitted, workflow-guard treats
+ *   non-test code files as production writes.
+ */
+export interface TddPathConfig {
+    testPathPatterns?: string[];
+    productionPathPatterns?: string[];
+}
+/**
+ * Compound-stage clustering policy.
+ *
+ * `recurrenceThreshold` is the base minimum repeat count for a trigger/action
+ * cluster before it is eligible for promotion into durable rules/skills.
+ */
+export interface CompoundConfig {
+    recurrenceThreshold?: number;
+}
 export interface VibyConfig {
     version: string;
     flowVersion: string;
@@ -112,13 +133,20 @@ export interface VibyConfig {
      */
     promptGuardMode?: "advisory" | "strict";
     /**
-     * TDD red->green->refactor enforcement mode used by workflow guard hooks.
+     * TDD RED -> GREEN -> REFACTOR enforcement mode used by workflow guard hooks.
      *
      * Since v0.43.0 this is an advanced override — see `strictness`.
      */
     tddEnforcement?: "advisory" | "strict";
-    /** Optional test file globs used by guard guidance and /cc-ops tdd-log docs. */
+    /**
+     * Legacy alias for test-side path detection in workflow-guard.
+     * Prefer `tdd.testPathPatterns` in new configs.
+     */
     tddTestGlobs?: string[];
+    /** Path-pattern routing for TDD test/production write classification. */
+    tdd?: TddPathConfig;
+    /** Compound-stage recurrence policy overrides. */
+    compound?: CompoundConfig;
     /** When true, cclaw installs managed git pre-commit/pre-push wrappers. */
     gitHookGuards?: boolean;
     /** Default flow track for new runs (quick = shortened path, standard = full pipeline). */

package/package.json

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