cclaw-cli 0.46.15 → 0.47.0

package/dist/artifact-linter.js

@@ -12,25 +12,52 @@ async function resolveArtifactPath(projectRoot, fileName) {
 function normalizeHeadingTitle(title) {
     return title.trim().replace(/\s+/g, " ");
 }
-/** Collect H2 sections and body content (`## Section Name`). */
+/**
+ * Collect H2 sections and body content (`## Section Name`).
+ *
+ * - Ignores lines that live inside fenced code blocks (``` / ~~~) so a
+ *   commented `## Approaches` inside an example doesn't open a phantom
+ *   section and swallow real content.
+ * - When the same heading appears more than once at the top level we
+ *   concatenate the bodies rather than silently overwriting the earlier
+ *   occurrence. This keeps lint rules honest when authors split a section
+ *   into multiple passes.
+ */
 function extractH2Sections(markdown) {
     const sections = new Map();
     const lines = markdown.split(/\r?\n/);
     let currentHeading = null;
     let buffer = [];
+    let fenced = null;
     const flush = () => {
         if (currentHeading === null)
             return;
-        sections.set(currentHeading, buffer.join("\n"));
+        const existing = sections.get(currentHeading);
+        const body = buffer.join("\n");
+        sections.set(currentHeading, existing === undefined ? body : `${existing}\n${body}`);
     };
     for (const line of lines) {
-        const match = /^##\s+(.+)$/u.exec(line);
-        if (match) {
-            flush();
-            currentHeading = normalizeHeadingTitle(match[1] ?? "");
-            buffer = [];
+        const fenceMatch = /^(```|~~~)/u.exec(line);
+        if (fenceMatch) {
+            if (fenced === null) {
+                fenced = fenceMatch[1] ?? null;
+            }
+            else if (line.startsWith(fenced)) {
+                fenced = null;
+            }
+            if (currentHeading !== null)
+                buffer.push(line);
             continue;
         }
+        if (fenced === null) {
+            const match = /^##\s+(.+)$/u.exec(line);
+            if (match) {
+                flush();
+                currentHeading = normalizeHeadingTitle(match[1] ?? "");
+                buffer = [];
+                continue;
+            }
+        }
         if (currentHeading !== null) {
             buffer.push(line);
         }
@@ -869,6 +896,49 @@ export async function lintArtifact(projectRoot, stage) {
             details: learnings.details
         });
     }
+    if (stage === "brainstorm") {
+        // Brainstorm Iron Law: "NO ARTIFACT IS COMPLETE WITHOUT AN EXPLICITLY
+        // APPROVED DIRECTION — SILENCE IS NOT APPROVAL." Previously this was
+        // prose-only — nothing failed when the Selected Direction section
+        // omitted an approval marker, or when the Approaches table collapsed
+        // to a single row (defeating the "2-3 distinct approaches" gate).
+        const approachesBody = sectionBodyByName(sections, "Approaches");
+        if (approachesBody !== null) {
+            const tableRows = approachesBody
+                .split(/\r?\n/u)
+                .map((line) => line.trim())
+                .filter((line) => line.startsWith("|"))
+                .filter((line) => !/^\|\s*[-: |]+\|\s*$/u.test(line))
+                .filter((line) => !/^\|\s*approach\b/iu.test(line));
+            const bulletRows = approachesBody
+                .split(/\r?\n/u)
+                .map((line) => line.trim())
+                .filter((line) => /^(?:[-*]|\d+\.)\s+\S/u.test(line));
+            const rowCount = Math.max(tableRows.length, bulletRows.length);
+            findings.push({
+                section: "Distinct Approaches Enforcement",
+                required: true,
+                rule: "Approaches section must document at least 2 distinct approaches so the Iron Law comparison is meaningful.",
+                found: rowCount >= 2,
+                details: rowCount >= 2
+                    ? `Detected ${rowCount} approach row(s).`
+                    : `Detected ${rowCount} approach row(s); at least 2 required.`
+            });
+        }
+        const directionBody = sectionBodyByName(sections, "Selected Direction");
+        if (directionBody !== null) {
+            const approvalMarker = /\bapprov(?:ed|al)\b/iu.test(directionBody);
+            findings.push({
+                section: "Direction Approval Marker",
+                required: true,
+                rule: "Selected Direction section must state an explicit approval marker (for example `Approval: approved` or `Approved by: user`).",
+                found: approvalMarker,
+                details: approvalMarker
+                    ? "Approval marker present in Selected Direction."
+                    : "No explicit `approved`/`approval` marker found in Selected Direction."
+            });
+        }
+    }
     if (stage === "plan") {
         const strictPlanGuards = parsedFrontmatter.hasFrontmatter ||
             headingPresent(sections, "No-Placeholder Scan") ||
@@ -914,12 +984,13 @@ export async function lintArtifact(projectRoot, stage) {
         });
     }
     if (stage === "scope") {
+        const lockedDecisionsBody = sectionBodyByName(sections, "Locked Decisions (D-XX)") ?? "";
         const strictScopeGuards = parsedFrontmatter.hasFrontmatter ||
             headingPresent(sections, "Locked Decisions (D-XX)");
         const scopeSections = [
             sectionBodyByName(sections, "In Scope / Out of Scope") ?? "",
             sectionBodyByName(sections, "Scope Summary") ?? "",
-            sectionBodyByName(sections, "Locked Decisions (D-XX)") ?? ""
+            lockedDecisionsBody
         ].join("\n");
         const reductionHits = collectPatternHits(scopeSections, SCOPE_REDUCTION_PATTERNS);
         findings.push({
@@ -931,6 +1002,45 @@ export async function lintArtifact(projectRoot, stage) {
                 ? "No scope-reduction phrases detected in scope boundary sections."
                 : `Detected scope-reduction phrase(s): ${reductionHits.join(", ")}.`
         });
+        // When the Locked Decisions section is present we must enforce the
+        // D-XX ID contract at runtime (previously this was prose-only in the
+        // artifactValidation rule). Empty body, missing IDs, and duplicate
+        // IDs all fail the lint; absence of the section remains advisory so
+        // scope stays optional for small/quick tracks.
+        if (headingPresent(sections, "Locked Decisions (D-XX)")) {
+            const decisionIds = extractDecisionIds(lockedDecisionsBody);
+            const bulletLines = lockedDecisionsBody
+                .split(/\r?\n/u)
+                .map((line) => line.trim())
+                .filter((line) => /^(?:[-*]|\|)\s+\S/u.test(line));
+            const orphanBullets = bulletLines.filter((line) => !/\bD-\d+\b/u.test(line));
+            const duplicateIds = (() => {
+                const all = lockedDecisionsBody.match(/\bD-\d+\b/gu) ?? [];
+                const counts = new Map();
+                for (const id of all)
+                    counts.set(id, (counts.get(id) ?? 0) + 1);
+                return [...counts.entries()].filter(([, n]) => n > 1).map(([id]) => id);
+            })();
+            const issues = [];
+            if (decisionIds.length === 0 && bulletLines.length === 0) {
+                issues.push("section is empty");
+            }
+            if (orphanBullets.length > 0) {
+                issues.push(`${orphanBullets.length} bullet(s) missing a D-XX ID`);
+            }
+            if (duplicateIds.length > 0) {
+                issues.push(`duplicate IDs: ${duplicateIds.join(", ")}`);
+            }
+            findings.push({
+                section: "Locked Decisions ID Integrity",
+                required: true,
+                rule: "Locked Decisions section must list each decision with a unique stable D-XX ID.",
+                found: issues.length === 0,
+                details: issues.length === 0
+                    ? `${decisionIds.length} decision ID(s) recorded with no duplicates.`
+                    : issues.join("; ")
+            });
+        }
     }
     const passed = findings.every((f) => !f.required || f.found);
     return { stage, file: relFile, passed, findings };
@@ -1198,6 +1308,14 @@ export async function checkReviewVerdictConsistency(projectRoot) {
     if (finalVerdict === "APPROVED" && (openCriticalCount > 0 || shipBlockerCount > 0)) {
         errors.push(`Final Verdict is APPROVED but review-army has ${openCriticalCount} open Critical finding(s) and ${shipBlockerCount} shipBlocker(s). Use BLOCKED or APPROVED_WITH_CONCERNS.`);
     }
+    // APPROVED_WITH_CONCERNS is intended for Important/Suggestion findings
+    // the author has accepted. An *open* Critical finding or an active
+    // shipBlocker must route through BLOCKED (review_verdict_blocked gate)
+    // rather than pass as a concession — previously this slipped through.
+    if (finalVerdict === "APPROVED_WITH_CONCERNS" &&
+        (openCriticalCount > 0 || shipBlockerCount > 0)) {
+        errors.push(`Final Verdict is APPROVED_WITH_CONCERNS but review-army has ${openCriticalCount} open Critical finding(s) and ${shipBlockerCount} shipBlocker(s). Resolve them or use BLOCKED.`);
+    }
     return {
         ok: errors.length === 0,
         errors,

package/dist/content/stage-schema.js

@@ -1,4 +1,5 @@
 import { COMMAND_FILE_ORDER } from "../constants.js";
+import { FLOW_TRACKS, TRACK_STAGES } from "../types.js";
 import { BRAINSTORM, SCOPE, DESIGN, SPEC, PLAN, TDD, REVIEW, SHIP } from "./stages/index.js";
 import { tddStageForTrack } from "./stages/tdd.js";
 const REQUIRED_GATE_IDS = {
@@ -266,15 +267,27 @@ export function nextCclawCommand(stage) {
 }
 export function buildTransitionRules() {
     const rules = [];
-    for (const schema of orderedStageSchemas()) {
-        if (schema.next === "done") {
-            continue;
+    const seen = new Set();
+    // Derive transitions from every track so medium/quick (which skip stages)
+    // get their neighbour edges registered alongside the standard chain.
+    // Previously only the standard track produced rules, so `canTransition`
+    // returned false for legitimate medium/quick transitions (e.g. brainstorm
+    // -> spec on medium) even though `nextStage` correctly advanced them.
+    for (const track of FLOW_TRACKS) {
+        const ordered = TRACK_STAGES[track];
+        for (let i = 0; i < ordered.length - 1; i += 1) {
+            const from = ordered[i];
+            const to = ordered[i + 1];
+            const key = `${from}->${to}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            rules.push({
+                from,
+                to,
+                guards: stageGateIds(from, track)
+            });
         }
-        rules.push({
-            from: schema.stage,
-            to: schema.next,
-            guards: stageGateIds(schema.stage)
-        });
     }
     // Review can explicitly route back to TDD when the verdict is BLOCKED.
     rules.push({

package/dist/delegation.js

@@ -126,6 +126,13 @@ export async function appendDelegation(projectRoot, entry) {
         if (!Array.isArray(stamped.evidenceRefs)) {
             stamped.evidenceRefs = [];
         }
+        // Idempotency: if a caller (or a retried hook) tries to append a row
+        // with a spanId that already exists in the ledger, treat it as a no-op
+        // instead of growing the log with duplicate entries that subsequent
+        // delegation checks would mis-count.
+        if (prior.entries.some((existing) => existing.spanId === stamped.spanId)) {
+            return;
+        }
         const ledger = {
             runId: activeRunId,
             entries: [...prior.entries, stamped]
@@ -201,11 +208,19 @@ export async function checkMandatoryDelegations(projectRoot, stage) {
         if (hasWaived) {
             waived.push(agent);
         }
-        // Under role-switch fallback, a `completed` row is only credible if it
-        // carries at least one evidenceRef — otherwise the agent might have
-        // claimed role-switch satisfaction without showing its work.
+        // Evidence gating for `completed` rows has two triggers:
+        //   1. The aggregate expected mode is role-switch (no isolated harness
+        //      available), so every completion implicitly ran as role-switch.
+        //   2. Any completed row is explicitly stamped `fulfillmentMode:
+        //      "role-switch"` — even in a mixed install. This closes the loop
+        //      where a Codex session logs a role-switch completion inside a
+        //      claude+codex project: the aggregate expectedMode is "isolated"
+        //      (claude wins), so the role-switch row would previously sail
+        //      through without evidenceRefs.
+        const hasExplicitRoleSwitchRow = completedRows.some((e) => e.fulfillmentMode === "role-switch");
+        const evidenceRequired = expectedMode === "role-switch" || hasExplicitRoleSwitchRow;
         if (hasCompleted &&
-            expectedMode === "role-switch" &&
+            evidenceRequired &&
             !completedRows.some((e) => Array.isArray(e.evidenceRefs) && e.evidenceRefs.length > 0)) {
             missingEvidence.push(agent);
         }

package/dist/gate-evidence.js

@@ -266,7 +266,12 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState) {
                             .map((line) => line.trim())
                             .filter((line) => line.length > 0)
                             .filter((line) => !/^\|?(?:[-:\s|])+$/u.test(line));
-                        const nonPlaceholder = meaningfulLines.filter((line) => !/\b(?:TODO|TBD|FIXME|pending|<fill-in>)\b/iu.test(line));
+                        // `<fill-in>` needs its own check because `\b` does not match
+                        // around `<`/`>` (non-word characters), so the previous combined
+                        // pattern `\b(?:...|<fill-in>)\b` silently never matched placeholder
+                        // templates that used angle-bracket form.
+                        const nonPlaceholder = meaningfulLines.filter((line) => !/\b(?:TODO|TBD|FIXME|pending)\b/iu.test(line) &&
+                            !/<fill-in>/iu.test(line));
                         if (nonPlaceholder.length === 0) {
                             missingSections.push(`${section} (empty or placeholder)`);
                         }

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/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/package.json

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