cclaw-cli 0.48.19 → 0.48.21

package/dist/content/next-command.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Single source of truth for how /cc-next should treat Ralph Loop status.
+ *
+ * IMPORTANT: Ralph Loop is a **progress indicator + soft pre-advance nudge**,
+ * not a hard gate. Hard enforcement always flows through flow-state.json
+ * gates via `stage-complete.mjs`. Both the command contract and the skill
+ * document render this same paragraph to prevent drift — see
+ * `tests/e2e/next-command-ralph-loop-contract.test.ts`.
+ */
+export declare const RALPH_LOOP_CONTRACT_MARKER = "ralph-loop-contract:v1";
+export declare function ralphLoopContractSnippet(): string;
 /**
  * Command contract for /cc-next — the primary progression command.
  * Reads flow-state, starts the current stage if unfinished, or advances if all gates pass.

package/dist/content/next-command.js

@@ -13,6 +13,34 @@ function delegationLogPathLine() {
 function reconciliationNoticesPathLine() {
     return `${RUNTIME_ROOT}/state/reconciliation-notices.json`;
 }
+/**
+ * Single source of truth for how /cc-next should treat Ralph Loop status.
+ *
+ * IMPORTANT: Ralph Loop is a **progress indicator + soft pre-advance nudge**,
+ * not a hard gate. Hard enforcement always flows through flow-state.json
+ * gates via `stage-complete.mjs`. Both the command contract and the skill
+ * document render this same paragraph to prevent drift — see
+ * `tests/e2e/next-command-ralph-loop-contract.test.ts`.
+ */
+export const RALPH_LOOP_CONTRACT_MARKER = "ralph-loop-contract:v1";
+export function ralphLoopContractSnippet() {
+    return `**Ralph Loop (tdd only).** When \`currentStage === "tdd"\`, read
+\`${RUNTIME_ROOT}/state/ralph-loop.json\` (refreshed on every session-start
+while the flow is in tdd) as a **progress indicator**:
+
+- \`loopIteration\` — running count of RED → GREEN cycles already landed.
+- \`acClosed\` — distinct acceptance-criterion IDs closed by GREEN rows
+  (populated from \`acIds\` in \`tdd-cycle-log.jsonl\`).
+- \`redOpenSlices\` — slices with an unsatisfied RED.
+
+Ralph Loop is a **soft pre-advance nudge**, not a gate: do not advance
+toward review while \`redOpenSlices\` is non-empty unless the user
+explicitly defers a slice. Hard gate enforcement always flows through
+\`flow-state.json\` gates via \`node .cclaw/hooks/stage-complete.mjs <stage>\`;
+Ralph Loop fields never gate-check on their own.
+
+<!-- ${RALPH_LOOP_CONTRACT_MARKER} -->`;
+}
 /**
  * Command contract for /cc-next — the primary progression command.
  * Reads flow-state, starts the current stage if unfinished, or advances if all gates pass.
@@ -60,17 +88,8 @@ This is the only progression command the user needs to drive the entire flow. St
 → Load **\`${RUNTIME_ROOT}/skills/<skillFolder>/SKILL.md\`** and **\`${RUNTIME_ROOT}/commands/<currentStage>.md\`** for the current stage.
 → Execute that stage's protocol. The stage skill handles the full interaction including STOP points and gate tracking.
 → Stage completion must use \`node .cclaw/hooks/stage-complete.mjs <currentStage>\` (canonical), which validates delegations + gate evidence before mutating \`flow-state.json\`.
-→ **Ralph Loop (tdd only).** When \`currentStage === "tdd"\`, also read
-  \`${RUNTIME_ROOT}/state/ralph-loop.json\` (refreshed on every session-start
-  while the flow is in tdd). Use it as a ground-truth progress indicator:
-  - \`loopIteration\` tells you how many RED → GREEN cycles already landed.
-  - \`acClosed\` lists the distinct acceptance-criterion IDs a GREEN row has
-    closed so far — if your plan tasks map to ACs, this is the "tasks
-    remaining" signal without needing a separate counter.
-  - \`redOpenSlices\` is the set of slices with an unsatisfied RED. Do not
-    advance to review while this is non-empty.
-  - Stage advancement to \`review\` still requires the normal gates in
-    \`flow-state.json\`; Ralph Loop status is a soft nudge, not a gate.
+
+${ralphLoopContractSnippet()}
 
 ### Path B: Current stage IS complete (all gates passed, all delegations satisfied)
 
@@ -208,14 +227,7 @@ Load the current stage's skill and command contract:
 
 Execute the stage protocol. The stage skill handles interaction, STOP points, gate tracking, and stage completion via \`node .cclaw/hooks/stage-complete.mjs <stage>\` (canonical flow-state mutation path).
 
-**Ralph Loop (tdd only).** When the current stage is \`tdd\`, pair the
-normal gate-evidence view with \`${RUNTIME_ROOT}/state/ralph-loop.json\`:
-\`loopIteration\` is the running count of RED → GREEN cycles,
-\`acClosed\` lists distinct acceptance-criterion IDs already closed by
-GREEN rows (populated from \`acIds\` in \`tdd-cycle-log.jsonl\`), and
-\`redOpenSlices\` is the "tasks remaining" indicator. Advance only when
-every planned slice is in \`acClosed\` (or explicitly deferred) and
-\`redOpenSlices\` is empty.
+${ralphLoopContractSnippet()}
 
 Special-case for review: if \`review_criticals_resolved\` is in \`blocked\`, route to rework instead of looping review forever — recommend \`/cc-ops rewind tdd "review_blocked_by_critical"\`.
 

package/dist/content/node-hooks.js

@@ -368,13 +368,31 @@ function normalizeText(value) {
   return String(value || "").replace(/\\s+/gu, " ").trim();
 }
 
+// Mirrors \`src/tdd-cycle.ts::normalizeTddPath\`. Any change to
+// canonical normalization must be updated in BOTH places; the
+// tdd-parity test asserts matcher behavior agrees end-to-end.
 function normalizePathForMatch(rawPath) {
-  return normalizeText(rawPath)
+  return String(rawPath == null ? "" : rawPath)
+    .trim()
     .replace(/\\\\/gu, "/")
     .replace(/^\\.\\//u, "")
     .toLowerCase();
 }
 
+// Mirrors \`src/tdd-cycle.ts::pathMatchesTarget\`. Use instead of raw
+// \`===\` when checking recorded files against a target path.
+function pathMatchesTargetInline(candidate, target) {
+  const normalizedCandidate = normalizePathForMatch(candidate);
+  const normalizedTarget = normalizePathForMatch(target);
+  if (normalizedCandidate.length === 0 || normalizedTarget.length === 0) {
+    return false;
+  }
+  return (
+    normalizedCandidate === normalizedTarget ||
+    normalizedCandidate.endsWith("/" + normalizedTarget)
+  );
+}
+
 function normalizeToolName(value) {
   if (typeof value === "string" && value.trim().length > 0) return value.trim();
   if (value && typeof value === "object") {
@@ -1279,27 +1297,6 @@ async function handlePromptGuard(runtime) {
   return 0;
 }
 
-async function tddCycleCounts(stateDir, runId) {
-  const filePath = path.join(stateDir, "tdd-cycle-log.jsonl");
-  const raw = await readTextFile(filePath, "");
-  const lines = raw.split(/\\r?\\n/gu).map((line) => line.trim()).filter((line) => line.length > 0);
-  let red = 0;
-  let green = 0;
-  for (const line of lines) {
-    try {
-      const row = JSON.parse(line);
-      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
-      const rowRun = typeof row.runId === "string" && row.runId.length > 0 ? row.runId : runId;
-      if (rowRun !== runId) continue;
-      if (row.phase === "red") red += 1;
-      if (row.phase === "green") green += 1;
-    } catch {
-      // ignore malformed rows
-    }
-  }
-  return { red, green };
-}
-
 // Mirrors src/knowledge-store.ts::computeCompoundReadiness — kept inline so
 // SessionStart can refresh compound-readiness.json without the CLI binary.
 // Any schema change must update src/knowledge-store.ts::computeCompoundReadiness
@@ -1458,14 +1455,7 @@ async function computeRalphLoopStatusInline(stateDir, runId) {
   };
 }
 
-function tddCycleStateFromCounts(counts) {
-  if (counts.red <= 0) return "need_red";
-  if (counts.red > counts.green) return "red_open";
-  return "green_done";
-}
-
 async function hasFailingRedEvidenceForPath(stateDir, runId, rawPath) {
-  const normalizedTarget = normalizePathForMatch(rawPath);
   const cycleRaw = await readTextFile(path.join(stateDir, "tdd-cycle-log.jsonl"), "");
   for (const line of cycleRaw.split(/\\r?\\n/gu)) {
     const trimmed = line.trim();
@@ -1484,7 +1474,10 @@ async function hasFailingRedEvidenceForPath(stateDir, runId, rawPath) {
       const files = Array.isArray(row.files) ? row.files : [];
       for (const filePath of files) {
         if (typeof filePath !== "string") continue;
-        if (normalizePathForMatch(filePath) === normalizedTarget) return true;
+        // endsWith-aware match (mirrors tdd-cycle.ts::pathMatchesTarget)
+        // — previously the inline impl used strict === which disagreed
+        // with the CLI/internal path and produced guard blind spots.
+        if (pathMatchesTargetInline(filePath, rawPath)) return true;
       }
     } catch {
       // ignore malformed line
@@ -1508,7 +1501,7 @@ async function hasFailingRedEvidenceForPath(stateDir, runId, rawPath) {
       const paths = Array.isArray(row.paths) ? row.paths : [];
       for (const filePath of paths) {
         if (typeof filePath !== "string") continue;
-        if (normalizePathForMatch(filePath) === normalizedTarget) return true;
+        if (pathMatchesTargetInline(filePath, rawPath)) return true;
       }
     } catch {
       // ignore malformed line
@@ -1667,9 +1660,14 @@ async function handleWorkflowGuard(runtime) {
         reasons.push("tdd_write_without_red_for_path");
       }
     } else if (productionPatterns.length === 0 && !isTestPayload(payloadLower, payloadPaths, testPatterns)) {
-      const counts = await tddCycleCounts(stateDir, currentRun);
-      const cycleState = tddCycleStateFromCounts(counts);
-      if (cycleState === "need_red") {
+      // Slice-aware fallback: the previous implementation used a flat
+      // red/green count which said "ok" as long as the totals balanced
+      // across ALL slices, so a closed S-1 could unlock production
+      // writes that actually belonged to a new, not-yet-red S-2. Now
+      // we reuse the canonical Ralph Loop status: if NO slice has an
+      // open RED, we block.
+      const ralphStatus = await computeRalphLoopStatusInline(stateDir, currentRun);
+      if (!ralphStatus.redOpen) {
         reasons.push("tdd_write_without_open_red");
       }
     }

package/dist/internal/tdd-red-evidence.js

@@ -2,10 +2,10 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "../constants.js";
 import { readFlowState } from "../runs.js";
-import { hasFailingTestForPath, parseTddCycleLog } from "../tdd-cycle.js";
-function normalizePath(value) {
-    return value.replace(/\\/gu, "/").toLowerCase();
-}
+import { hasFailingTestForPath, parseTddCycleLog, pathMatchesTarget } from "../tdd-cycle.js";
+// normalizePath and the path matcher live in src/tdd-cycle.ts so all
+// TDD-related guards (internal CLI, runtime hook, unit tests) agree on
+// what "path X matches recorded file Y" means.
 function parseArgs(tokens) {
     const args = { quiet: false };
     for (const token of tokens) {
@@ -73,15 +73,12 @@ function parseAutoEvidence(text) {
     return out;
 }
 function hasFailingAutoEvidenceForPath(entries, targetPath, options = {}) {
-    const normalizedTarget = normalizePath(targetPath);
     for (const entry of entries) {
         if (options.runId && entry.runId !== options.runId)
             continue;
         for (const filePath of entry.paths) {
-            const normalized = normalizePath(filePath);
-            if (normalized === normalizedTarget || normalized.endsWith(`/${normalizedTarget}`)) {
+            if (pathMatchesTarget(filePath, targetPath))
                 return true;
-            }
         }
     }
     return false;

package/dist/tdd-cycle.d.ts

@@ -47,6 +47,23 @@ export declare function parseTddCycleLog(text: string, options?: ParseTddCycleLo
 export declare function validateTddCycleOrder(entries: TddCycleEntry[], options?: {
     runId?: string;
 }): TddCycleValidation;
+/**
+ * Canonical path normalization used by ALL TDD path-matching layers
+ * (cycle-log analysis, internal CLI `tdd-red-evidence`, and the
+ * inline runtime hook). Previously each layer had its own near-copy,
+ * which produced subtle drift (e.g. `./src/app.ts` vs `src/app.ts`
+ * differing between hook and CLI). Keep this function in one place
+ * so all callers agree.
+ */
+export declare function normalizeTddPath(value: string): string;
+/**
+ * Shared "does the recorded file path refer to the target" matcher.
+ * Uses canonical normalization plus the traditional `endsWith('/'+x)`
+ * rule so a recorded `src/app.ts` matches either `src/app.ts` or
+ * `subdir/src/app.ts` but NOT `src/app.test.ts`. All TDD path checks
+ * MUST go through this helper.
+ */
+export declare function pathMatchesTarget(candidate: string, target: string): boolean;
 export interface RalphLoopSliceState {
     slice: string;
     redCount: number;

package/dist/tdd-cycle.js

@@ -159,8 +159,40 @@ export function validateTddCycleOrder(entries, options = {}) {
         sliceCount: bySlice.size
     };
 }
+/**
+ * Canonical path normalization used by ALL TDD path-matching layers
+ * (cycle-log analysis, internal CLI `tdd-red-evidence`, and the
+ * inline runtime hook). Previously each layer had its own near-copy,
+ * which produced subtle drift (e.g. `./src/app.ts` vs `src/app.ts`
+ * differing between hook and CLI). Keep this function in one place
+ * so all callers agree.
+ */
+export function normalizeTddPath(value) {
+    const trimmed = String(value ?? "").trim();
+    return trimmed
+        .replace(/\\/gu, "/")
+        .replace(/^\.\//u, "")
+        .toLowerCase();
+}
+// Legacy alias kept for local callers below.
 function normalizePath(value) {
-    return value.replace(/\\/gu, "/").toLowerCase();
+    return normalizeTddPath(value);
+}
+/**
+ * Shared "does the recorded file path refer to the target" matcher.
+ * Uses canonical normalization plus the traditional `endsWith('/'+x)`
+ * rule so a recorded `src/app.ts` matches either `src/app.ts` or
+ * `subdir/src/app.ts` but NOT `src/app.test.ts`. All TDD path checks
+ * MUST go through this helper.
+ */
+export function pathMatchesTarget(candidate, target) {
+    const normalizedCandidate = normalizeTddPath(candidate);
+    const normalizedTarget = normalizeTddPath(target);
+    if (normalizedCandidate.length === 0 || normalizedTarget.length === 0) {
+        return false;
+    }
+    return (normalizedCandidate === normalizedTarget ||
+        normalizedCandidate.endsWith(`/${normalizedTarget}`));
 }
 /**
  * Derive a lightweight Ralph Loop summary from parsed tdd-cycle-log entries.
@@ -233,7 +265,6 @@ export function computeRalphLoopStatus(entries, options = {}) {
  * `productionPath` for the active run.
  */
 export function hasFailingTestForPath(entries, productionPath, options = {}) {
-    const normalizedTarget = normalizePath(productionPath);
     const filtered = options.runId
         ? entries.filter((entry) => entry.runId === options.runId)
         : entries;
@@ -244,10 +275,7 @@ export function hasFailingTestForPath(entries, productionPath, options = {}) {
             continue;
         if (!Array.isArray(entry.files) || entry.files.length === 0)
             continue;
-        const hasMatch = entry.files.some((filePath) => {
-            const normalized = normalizePath(filePath);
-            return normalized === normalizedTarget || normalized.endsWith(`/${normalizedTarget}`);
-        });
+        const hasMatch = entry.files.some((filePath) => pathMatchesTarget(filePath, productionPath));
         if (hasMatch) {
             return true;
         }

package/package.json

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