cclaw-cli 0.48.12 → 0.48.14

package/dist/content/flow-map.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Relative path used by skills/commands to cite the consolidated flow map.
+ * Stable contract — changing this value is a breaking change for doctor
+ * policies and meta-skill links.
+ */
+export declare const FLOW_MAP_REL_PATH = ".cclaw/references/flow-map.md";
+/**
+ * Canonical one-page overview of cclaw's user-facing surface.
+ *
+ * Purpose: give the model (and any curious human) a single file that
+ * answers "what does cclaw expose, where does my current stage fit, and
+ * which files drive progress?" without forcing a walk of the 8 stage
+ * skills plus the 4 router skills plus the meta-skill.
+ *
+ * Design rules:
+ * - Keep it under ~150 lines; it is a map, not a manual.
+ * - Only cite files that already exist under `.cclaw/`.
+ * - Do not duplicate protocol text (decision/completion/ethos live in
+ *   `.cclaw/references/protocols/`). Link, don't inline.
+ * - Do not introduce new gates or hard rules here — flow-map is
+ *   descriptive, not prescriptive.
+ */
+export declare function flowMapMarkdown(): string;

package/dist/content/flow-map.js

@@ -0,0 +1,117 @@
+import { RUNTIME_ROOT } from "../constants.js";
+/**
+ * Relative path used by skills/commands to cite the consolidated flow map.
+ * Stable contract — changing this value is a breaking change for doctor
+ * policies and meta-skill links.
+ */
+export const FLOW_MAP_REL_PATH = `${RUNTIME_ROOT}/references/flow-map.md`;
+/**
+ * Canonical one-page overview of cclaw's user-facing surface.
+ *
+ * Purpose: give the model (and any curious human) a single file that
+ * answers "what does cclaw expose, where does my current stage fit, and
+ * which files drive progress?" without forcing a walk of the 8 stage
+ * skills plus the 4 router skills plus the meta-skill.
+ *
+ * Design rules:
+ * - Keep it under ~150 lines; it is a map, not a manual.
+ * - Only cite files that already exist under `.cclaw/`.
+ * - Do not duplicate protocol text (decision/completion/ethos live in
+ *   `.cclaw/references/protocols/`). Link, don't inline.
+ * - Do not introduce new gates or hard rules here — flow-map is
+ *   descriptive, not prescriptive.
+ */
+export function flowMapMarkdown() {
+    return `# cclaw Flow Map
+
+One-page surface reference. Use this when you need the shape of cclaw
+without reading every skill — the stage quick-map, the user-facing
+slash commands, the Ralph Loop signal, and the key state files.
+
+For enforcement details, load the matching stage skill or command
+contract. For protocols (decision/completion/ethos) see
+\`${RUNTIME_ROOT}/references/protocols/\`.
+
+## Stages (8)
+
+| # | Stage | Goal | Primary artifact |
+|---|---|---|---|
+| 1 | brainstorm | Explore options and constraints | \`.cclaw/artifacts/00-idea.md\` (+ \`01-brainstorm.md\`) |
+| 2 | scope | Freeze scope (in/out, assumptions) | \`.cclaw/artifacts/02-scope.md\` |
+| 3 | design | Pick the shape of the change | \`.cclaw/artifacts/03-design.md\` |
+| 4 | spec | Turn design into testable acceptance criteria | \`.cclaw/artifacts/04-spec.md\` |
+| 5 | plan | Decompose spec into executable slices | \`.cclaw/artifacts/05-plan.md\` |
+| 6 | tdd | Drive each slice through RED → GREEN → REFACTOR (Ralph Loop) | \`.cclaw/artifacts/06-tdd.md\` + \`.cclaw/state/tdd-cycle-log.jsonl\` |
+| 7 | review | Cross-check correctness, spec coverage, and ethos | \`.cclaw/artifacts/07-review.md\` |
+| 8 | ship | Close out: retro, compound, archive | \`.cclaw/artifacts/08-ship.md\` (+ \`09-retro.md\`) |
+
+Track shortcuts (set in \`.cclaw/state/flow-state.json\`):
+
+- \`quick\` — spec → tdd → review → ship
+- \`medium\` — brainstorm → spec → plan → tdd → review → ship
+- \`standard\` — all 8 stages (default)
+
+## User-facing slash commands
+
+| Command | Role | Notes |
+|---|---|---|
+| \`/cc\` | Entry point. No args = resume. With prompt = classify + start. | Writes \`00-idea.md\` and picks the track. |
+| \`/cc-next\` | Advance or resume the current stage based on gates. | Soft nudge from Ralph Loop during \`tdd\`. |
+| \`/cc-ideate\` | Repo-improvement discovery, separate from product flow. | Produces ideas, not stage artifacts. |
+| \`/cc-view [status\\|tree\\|diff]\` | Read-only router. Never mutates flow state. | \`diff\` refreshes the snapshot baseline by design. |
+| \`/cc-ops [feature\\|tdd-log\\|retro\\|compound\\|archive\\|rewind]\` | Operations router for post-flow and side-channel actions. | Mutations are scoped to each subcommand. |
+
+Subcommand dispatch lives in \`${RUNTIME_ROOT}/commands/\` and the
+matching \`${RUNTIME_ROOT}/skills/flow-*/SKILL.md\`. The meta-skill
+(\`${RUNTIME_ROOT}/skills/using-cclaw/SKILL.md\`) decides which router to
+use before any substantive work.
+
+## Ralph Loop (TDD progress signal)
+
+When \`currentStage === "tdd"\`, SessionStart writes
+\`${RUNTIME_ROOT}/state/ralph-loop.json\` from the TDD cycle log. Fields
+worth acting on:
+
+- \`loopIteration\` — how many RED → GREEN cycles already landed.
+- \`redOpenSlices\` — slices with an unsatisfied RED. Non-empty means do
+  **not** advance to review.
+- \`acClosed\` — distinct acceptance-criterion IDs closed by a GREEN row
+  (requires \`acIds\` on the green log entry via \`/cc-ops tdd-log\`).
+- \`sliceCount\` — total distinct plan slices ever touched.
+
+Ralph Loop is a signal, not a gate. Stage advancement still runs
+through the normal \`flow-state.json\` gate catalog.
+
+## Key state files
+
+| Path | What it holds |
+|---|---|
+| \`${RUNTIME_ROOT}/state/flow-state.json\` | Track, currentStage, completedStages, gate catalog, closeout substate. |
+| \`${RUNTIME_ROOT}/state/delegation-log.json\` | Per-stage mandatory agent status + fulfillmentMode + evidenceRefs. |
+| \`${RUNTIME_ROOT}/state/tdd-cycle-log.jsonl\` | Append-only RED/GREEN/REFACTOR entries (source of Ralph Loop). |
+| \`${RUNTIME_ROOT}/state/ralph-loop.json\` | Derived Ralph Loop status (TDD-only). |
+| \`${RUNTIME_ROOT}/state/stage-activity.jsonl\` | Append-only stage-enter/exit and gate-pass signals. |
+| \`${RUNTIME_ROOT}/state/checkpoint.json\` | Latest session checkpoint (stage + timestamp). |
+| \`${RUNTIME_ROOT}/state/context-mode.json\` | Active context mode (\`default\`, \`headless\`, ...). |
+| \`${RUNTIME_ROOT}/state/harness-gaps.json\` | Per-harness tier, subagent fallback, playbook path (schemaVersion 2). |
+| \`${RUNTIME_ROOT}/knowledge.jsonl\` | Append-only learnings; surfaced to sessions via digest. |
+
+## Strictness and hooks
+
+Hook-driven guards respect the \`strictness\` field in
+\`${RUNTIME_ROOT}/config.yaml\`:
+
+- \`advisory\` (default) — hooks warn but never block tool calls.
+- \`strict\` — hooks block tool calls that violate their scope.
+
+Override per-session with \`CCLAW_STRICTNESS=advisory|strict\`.
+
+## When in doubt
+
+1. Read \`${RUNTIME_ROOT}/state/flow-state.json\` to know where you are.
+2. Load the matching stage skill only if you are about to do
+   substantive work (see \`using-cclaw\` meta-skill).
+3. Prefer \`/cc-next\` for progression. \`/cc-view\` for visibility.
+   \`/cc-ops\` for side-channel operations.
+`;
+}

package/dist/content/meta-skill.js

@@ -1,3 +1,4 @@
+import { FLOW_MAP_REL_PATH } from "./flow-map.js";
 import { COMPLETION_PROTOCOL_REL_PATH, DECISION_PROTOCOL_REL_PATH, ETHOS_PROTOCOL_REL_PATH } from "./protocols.js";
 export const META_SKILL_NAME = "using-cclaw";
 export function usingCclawSkillMarkdown() {
@@ -76,6 +77,8 @@ Before stage work:
 brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship
 
 Tracks may skip stages via \`flow-state.track\` + \`skippedStages\`.
+For the full surface (stages, routers, Ralph Loop, state files) load
+\`${FLOW_MAP_REL_PATH}\` — it is the single-page overview of cclaw.
 
 ## Contextual skill activation
 

package/dist/content/next-command.js

@@ -1,4 +1,5 @@
 import { RUNTIME_ROOT } from "../constants.js";
+import { FLOW_MAP_REL_PATH } from "./flow-map.js";
 import { stageSchema } from "./stage-schema.js";
 import { stageSkillFolder } from "./skills.js";
 const NEXT_SKILL_FOLDER = "flow-next-step";
@@ -59,6 +60,17 @@ 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.
 
 ### Path B: Current stage IS complete (all gates passed, all delegations satisfied)
 
@@ -117,6 +129,12 @@ Validate envelopes with:
 ## Primary skill
 
 **${skillRel}** — full protocol and stage table.
+
+## Surface reference
+
+When you need the full shape of cclaw (stages, routers, Ralph Loop,
+state files) load \`${FLOW_MAP_REL_PATH}\`. It is the single-page
+overview and is safe to read at any time.
 `;
 }
 /**
@@ -190,6 +208,15 @@ 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.
+
 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"\`.
 
 **Path B — stage IS complete (all gates met, all delegations done):**

package/dist/content/node-hooks.js

@@ -705,6 +705,26 @@ async function handleSessionStart(runtime) {
   const contextWarning = await readLatestContextWarningLine(contextWarningsFile);
   const knowledge = await buildKnowledgeDigest(runtime.root, state.currentStage);
 
+  // Refresh Ralph Loop status each session-start so /cc-next and the model
+  // both read a consistent "iter=N, acClosed=[...]" snapshot. Runs only when
+  // we are in tdd — other stages skip the write to keep the file stable.
+  let ralphLoopLine = "";
+  if (state.currentStage === "tdd") {
+    try {
+      const ralphStatus = await computeRalphLoopStatusInline(stateDir, state.activeRunId);
+      await writeJsonFile(path.join(stateDir, "ralph-loop.json"), ralphStatus);
+      const redOpen = ralphStatus.redOpenSlices.length > 0
+        ? ralphStatus.redOpenSlices.join(",")
+        : "none";
+      ralphLoopLine = "Ralph Loop: iter=" + String(ralphStatus.loopIteration) +
+        ", slices=" + String(ralphStatus.sliceCount) +
+        ", acClosed=" + String(ralphStatus.acClosed.length) +
+        ", redOpen=" + redOpen;
+    } catch (_err) {
+      // best-effort — a malformed cycle log should never break session-start.
+    }
+  }
+
   const suggestionMemory = toObject(await readJsonFile(suggestionMemoryFile, {})) || {};
   const suggestionsEnabled = suggestionMemory.enabled !== false;
   const mutedStages = Array.isArray(suggestionMemory.mutedStages)
@@ -769,6 +789,9 @@ async function handleSessionStart(runtime) {
   if (activitySummary.length > 0) {
     parts.push("Recent stage activity:\\n" + activitySummary.join("\\n"));
   }
+  if (ralphLoopLine.length > 0) {
+    parts.push(ralphLoopLine);
+  }
   if (contextWarning.length > 0) {
     parts.push("Latest context warning:\\n" + contextWarning);
   }
@@ -1089,6 +1112,66 @@ async function tddCycleCounts(stateDir, runId) {
   return { red, green };
 }
 
+// Mirrors src/tdd-cycle.ts::computeRalphLoopStatus — kept inline so the
+// SessionStart hook can write ralph-loop.json without depending on the CLI
+// binary being installed globally. Any schema change must update both copies.
+async function computeRalphLoopStatusInline(stateDir, runId) {
+  const filePath = path.join(stateDir, "tdd-cycle-log.jsonl");
+  const raw = await readTextFile(filePath, "");
+  const sliceMap = new Map();
+  const acClosed = new Set();
+  const redOpenSlices = [];
+  let loopIteration = 0;
+  for (const rawLine of raw.split(/\\r?\\n/gu)) {
+    const line = rawLine.trim();
+    if (line.length === 0) continue;
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }
+    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;
+    const slice = typeof row.slice === "string" && row.slice.length > 0 ? row.slice : "S-unknown";
+    let state = sliceMap.get(slice);
+    if (!state) {
+      state = { slice, redCount: 0, greenCount: 0, refactorCount: 0, redOpen: false, acIds: [] };
+      sliceMap.set(slice, state);
+    }
+    const exitCode = typeof row.exitCode === "number" ? row.exitCode : undefined;
+    if (row.phase === "red") {
+      state.redCount += 1;
+      if (exitCode !== undefined && exitCode !== 0) state.redOpen = true;
+    } else if (row.phase === "green") {
+      state.greenCount += 1;
+      state.redOpen = false;
+      loopIteration += 1;
+      if (Array.isArray(row.acIds)) {
+        for (const acId of row.acIds) {
+          if (typeof acId !== "string" || acId.length === 0) continue;
+          acClosed.add(acId);
+          if (!state.acIds.includes(acId)) state.acIds.push(acId);
+        }
+      }
+    } else if (row.phase === "refactor") {
+      state.refactorCount += 1;
+    }
+  }
+  for (const state of sliceMap.values()) {
+    if (state.redOpen) redOpenSlices.push(state.slice);
+  }
+  const slices = Array.from(sliceMap.values()).sort((a, b) => a.slice.localeCompare(b.slice, "en"));
+  return {
+    schemaVersion: 1,
+    runId,
+    loopIteration,
+    redOpen: redOpenSlices.length > 0,
+    redOpenSlices,
+    acClosed: Array.from(acClosed).sort(),
+    sliceCount: slices.length,
+    slices,
+    lastUpdatedAt: new Date().toISOString()
+  };
+}
+
 function tddCycleStateFromCounts(counts) {
   if (counts.red <= 0) return "need_red";
   if (counts.red > counts.green) return "red_open";

package/dist/content/stages/tdd.js

@@ -20,7 +20,7 @@ export const TDD = {
         "The stage intent is review/ship sign-off rather than implementation"
     ],
     checklist: [
-        "Select plan slice — pick one task from the plan. Do not batch multiple tasks.",
+        "Select plan slice — pick one task from the plan. Do not batch multiple tasks. Before starting, read `.cclaw/state/ralph-loop.json` (`loopIteration`, `acClosed[]`, `redOpenSlices[]`) so you skip cycles already closed.",
         "Map to acceptance criterion — identify the specific spec criterion this test proves.",
         "Dispatch mandatory `tdd-red` execution (or `test-author` in TEST_RED_ONLY mode) — produce failing behavior tests and RED evidence only (no production edits). Set `CCLAW_ACTIVE_AGENT=tdd-red` when supported.",
         "RED: Capture failure output — copy the exact failure output as RED evidence. Record in artifact.",
@@ -29,7 +29,7 @@ export const TDD = {
         "GREEN: Verify no regressions — if any existing test breaks, fix the regression before proceeding.",
         "Run verification-before-completion discipline for the slice — capture a fresh test command, commit SHA, and explicit PASS/FAIL status before completion claims.",
         "REFACTOR: Dispatch `tdd-refactor` execution (or dedicated refactor mode) to improve code quality without behavior changes. Set `CCLAW_ACTIVE_AGENT=tdd-refactor` when supported.",
-        "Record evidence — capture RED failure, GREEN output, and REFACTOR notes in the TDD artifact.",
+        "Record evidence — capture RED failure, GREEN output, and REFACTOR notes in the TDD artifact. When logging the `green` row via `/cc-ops tdd-log green`, attach the closed acceptance-criterion IDs in `acIds` so Ralph Loop status counts them.",
         "Annotate traceability — link to plan task ID and spec criterion.",
         "Per-Slice Review (conditional) — if `.cclaw/config.yaml::sliceReview.enabled` is true and the slice meets any trigger (touchCount >= filesChangedThreshold, touchPaths match touchTriggers, or highRisk=true), append a `## Per-Slice Review` entry for this slice before moving on (see the dedicated section below).",
         "Repeat for each slice — return to step 1 for the next plan slice."

package/dist/content/start-command.js

@@ -1,4 +1,5 @@
 import { RUNTIME_ROOT } from "../constants.js";
+import { FLOW_MAP_REL_PATH } from "./flow-map.js";
 const START_SKILL_FOLDER = "flow-start";
 const START_SKILL_NAME = "flow-start";
 function flowStatePath() {
@@ -115,6 +116,12 @@ Validate envelopes with:
 ## Primary skill
 
 **${RUNTIME_ROOT}/skills/${START_SKILL_FOLDER}/SKILL.md**
+
+## Surface reference
+
+For the 1-page overview of cclaw (stages, routers, Ralph Loop, state
+files) load \`${FLOW_MAP_REL_PATH}\` — useful when a fresh session
+needs orientation before \`/cc <prompt>\` runs.
 `;
 }
 /**

package/dist/content/tdd-log-command.js

@@ -35,7 +35,9 @@ Each JSON line must include:
 - \`slice\` (e.g. \`S-1\`)
 - \`phase\` (\`red\` | \`green\` | \`refactor\`)
 - \`command\`
-- optional: \`files\`, \`exitCode\`, \`note\`
+- optional: \`files\`, \`exitCode\`, \`note\`, \`acIds\` (array of acceptance
+  criterion IDs like \`["AC-1"]\` — GREEN rows use this to drive the Ralph
+  Loop status summary at \`.cclaw/state/ralph-loop.json\`).
 
 ## Primary skill
 
@@ -64,8 +66,16 @@ Do not fake RED evidence. A \`red\` entry must correspond to a failing test comm
    - \`slice\`: user-provided slice id
    - \`phase\`: red|green|refactor
    - \`command\`: test command or refactor verification command
+   - \`acIds\` (optional, recommended on \`green\`): the acceptance-criterion
+     IDs this GREEN row closes (e.g. \`["AC-1","AC-3"]\`). The SessionStart
+     hook aggregates distinct \`acIds\` from green rows into \`acClosed\`
+     inside \`.cclaw/state/ralph-loop.json\` so \`/cc-next\` can answer
+     "is the Ralph Loop done?" without parsing the artifact.
 3. Append one line to \`${logPath()}\`.
-4. \`show\`: print the last 20 lines grouped by slice.
+4. After append, refresh Ralph Loop status with
+   \`cclaw internal tdd-loop-status --quiet\` (the SessionStart hook also
+   refreshes it, but a manual refresh is safe and idempotent).
+5. \`show\`: print the last 20 lines grouped by slice.
 
 ## Validation
 

package/dist/doctor-registry.js

@@ -85,7 +85,7 @@ const RULES = [
         }
     },
     {
-        test: /^(meta_skill:|protocol:|stage_skill:|context_mode:)/,
+        test: /^(meta_skill:|protocol:|stage_skill:|context_mode:|reference:)/,
         metadata: {
             severity: "error",
             summary: "Routing skill and protocol integrity check.",

package/dist/install.js

@@ -28,6 +28,7 @@ import { stageCompleteScript, opencodePluginJs, claudeHooksJson, codexHooksJson,
 import { nodeHookRuntimeScript } from "./content/node-hooks.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { decisionProtocolMarkdown, completionProtocolMarkdown, ethosProtocolMarkdown } from "./content/protocols.js";
+import { flowMapMarkdown } from "./content/flow-map.js";
 import { ARTIFACT_TEMPLATES, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildRulesJson } from "./content/templates.js";
 import { EVAL_BASELINES_README, EVAL_CONFIG_YAML, EVAL_CORPUS_README, EVAL_REPORTS_README, EVAL_RUBRIC_FILES, EVAL_RUBRICS_README } from "./content/eval-scaffold.js";
 import { TDD_BATCH_WALKTHROUGH_MARKDOWN, stageSkillFolder, stageSkillMarkdown } from "./content/skills.js";
@@ -355,6 +356,7 @@ async function writeSkills(projectRoot, config) {
     await writeFileSafe(runtimePath(projectRoot, "references", "protocols", "decision.md"), decisionProtocolMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "references", "protocols", "completion.md"), completionProtocolMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "references", "protocols", "ethos.md"), ethosProtocolMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "references", "flow-map.md"), flowMapMarkdown());
     for (const folder of UTILITY_SKILL_FOLDERS) {
         const generator = UTILITY_SKILL_MAP[folder];
         await writeFileSafe(runtimePath(projectRoot, "skills", folder, "SKILL.md"), generator());

package/dist/internal/advance-stage.js

@@ -14,6 +14,7 @@ import { readFlowState, writeFlowState } from "../runs.js";
 import { FLOW_STAGES } from "../types.js";
 import { runEnvelopeValidateCommand } from "./envelope-validate.js";
 import { runKnowledgeDigestCommand } from "./knowledge-digest.js";
+import { runTddLoopStatusCommand } from "./tdd-loop-status.js";
 import { runTddRedEvidenceCommand } from "./tdd-red-evidence.js";
 function unique(values) {
     return [...new Set(values)];
@@ -672,7 +673,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 | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | hook\n");
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | tdd-loop-status | hook\n");
         return 1;
     }
     try {
@@ -694,10 +695,13 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "tdd-red-evidence") {
             return await runTddRedEvidenceCommand(projectRoot, tokens, io);
         }
+        if (subcommand === "tdd-loop-status") {
+            return await runTddLoopStatusCommand(projectRoot, tokens, io);
+        }
         if (subcommand === "hook") {
             return await runHookCommand(projectRoot, parseHookArgs(tokens), io);
         }
-        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | hook\n`);
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | tdd-loop-status | hook\n`);
         return 1;
     }
     catch (err) {

package/dist/internal/tdd-loop-status.d.ts

@@ -0,0 +1,14 @@
+import type { Writable } from "node:stream";
+import { type RalphLoopStatus } from "../tdd-cycle.js";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+/**
+ * Produces a one-line "Ralph Loop: iter=X, slices=Y, acClosed=Z, redOpen=..."
+ * summary — suitable for session-digest / bootstrap surfaces where the user
+ * just needs a progress indicator, not the full slice breakdown.
+ */
+export declare function formatRalphLoopStatusLine(status: RalphLoopStatus): string;
+export declare function runTddLoopStatusCommand(projectRoot: string, argv: string[], io: InternalIo): Promise<number>;
+export {};

package/dist/internal/tdd-loop-status.js

@@ -0,0 +1,68 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RUNTIME_ROOT } from "../constants.js";
+import { writeFileSafe } from "../fs-utils.js";
+import { readFlowState } from "../runs.js";
+import { computeRalphLoopStatus, parseTddCycleLog } from "../tdd-cycle.js";
+function parseArgs(tokens) {
+    const args = { json: false, quiet: false, write: true };
+    for (const token of tokens) {
+        if (token === "--json")
+            args.json = true;
+        else if (token === "--quiet")
+            args.quiet = true;
+        else if (token === "--no-write")
+            args.write = false;
+        else if (token === "--write")
+            args.write = true;
+        else
+            throw new Error(`Unknown tdd-loop-status flag: ${token}`);
+    }
+    return args;
+}
+function stateDir(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state");
+}
+async function readCycleLog(projectRoot) {
+    const filePath = path.join(stateDir(projectRoot), "tdd-cycle-log.jsonl");
+    try {
+        return await fs.readFile(filePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return "";
+        throw err;
+    }
+}
+/**
+ * Produces a one-line "Ralph Loop: iter=X, slices=Y, acClosed=Z, redOpen=..."
+ * summary — suitable for session-digest / bootstrap surfaces where the user
+ * just needs a progress indicator, not the full slice breakdown.
+ */
+export function formatRalphLoopStatusLine(status) {
+    const redOpen = status.redOpenSlices.length > 0
+        ? status.redOpenSlices.join(",")
+        : "none";
+    return `Ralph Loop: iter=${status.loopIteration}, slices=${status.sliceCount}, acClosed=${status.acClosed.length}, redOpen=${redOpen}`;
+}
+export async function runTddLoopStatusCommand(projectRoot, argv, io) {
+    const args = parseArgs(argv);
+    const flow = await readFlowState(projectRoot).catch(() => null);
+    const runId = flow?.activeRunId ?? "active";
+    const text = await readCycleLog(projectRoot);
+    const entries = parseTddCycleLog(text);
+    const status = computeRalphLoopStatus(entries, { runId });
+    if (args.write) {
+        const target = path.join(stateDir(projectRoot), "ralph-loop.json");
+        await writeFileSafe(target, `${JSON.stringify(status, null, 2)}\n`);
+    }
+    if (!args.quiet) {
+        if (args.json) {
+            io.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
+        }
+        else {
+            io.stdout.write(`${formatRalphLoopStatusLine(status)}\n`);
+        }
+    }
+    return 0;
+}

package/dist/policy.js

@@ -142,6 +142,10 @@ export async function policyChecks(projectRoot, options = {}) {
         { file: runtimeFile("references/protocols/decision.md"), needle: "# Decision Protocol", name: "protocol:decision" },
         { file: runtimeFile("references/protocols/completion.md"), needle: "# Stage Completion Protocol", name: "protocol:completion" },
         { file: runtimeFile("references/protocols/ethos.md"), needle: "# Engineering Ethos", name: "protocol:ethos" },
+        { file: runtimeFile("references/flow-map.md"), needle: "# cclaw Flow Map", name: "reference:flow_map:header" },
+        { file: runtimeFile("references/flow-map.md"), needle: "## Stages (8)", name: "reference:flow_map:stages" },
+        { file: runtimeFile("references/flow-map.md"), needle: "## Ralph Loop", name: "reference:flow_map:ralph_loop" },
+        { file: runtimeFile("references/flow-map.md"), needle: "## Key state files", name: "reference:flow_map:state_files" },
         { file: runtimeFile("skills/session/SKILL.md"), needle: "## Session Resume Protocol", name: "utility_skill:session:resume" },
         { file: runtimeFile("skills/brainstorming/SKILL.md"), needle: "common-guidance.md", name: "stage_skill:shared_guidance_reference" },
         { file: runtimeFile("skills/security/SKILL.md"), needle: "## HARD-GATE", name: "utility_skill:security:hard_gate" },

package/dist/tdd-cycle.d.ts

@@ -9,6 +9,12 @@ export interface TddCycleEntry {
     files?: string[];
     exitCode?: number;
     note?: string;
+    /**
+     * Optional acceptance-criterion IDs this log line relates to (e.g. `["AC-1"]`).
+     * Used by the Ralph Loop status summary to surface how many ACs have been
+     * closed by a GREEN cycle without forcing the user to track them manually.
+     */
+    acIds?: string[];
 }
 export interface TddCycleValidation {
     ok: boolean;
@@ -20,6 +26,40 @@ export declare function parseTddCycleLog(text: string): TddCycleEntry[];
 export declare function validateTddCycleOrder(entries: TddCycleEntry[], options?: {
     runId?: string;
 }): TddCycleValidation;
+export interface RalphLoopSliceState {
+    slice: string;
+    redCount: number;
+    greenCount: number;
+    refactorCount: number;
+    redOpen: boolean;
+    acIds: string[];
+}
+export interface RalphLoopStatus {
+    schemaVersion: 1;
+    runId: string;
+    /**
+     * Number of RED -> GREEN cycles observed for the run — a rough "Ralph Loop"
+     * iteration counter that mirrors how many passing tests the loop has
+     * delivered so far.
+     */
+    loopIteration: number;
+    redOpen: boolean;
+    redOpenSlices: string[];
+    acClosed: string[];
+    sliceCount: number;
+    slices: RalphLoopSliceState[];
+    lastUpdatedAt: string;
+}
+/**
+ * Derive a lightweight Ralph Loop summary from parsed tdd-cycle-log entries.
+ * The goal is to give the model a single source of truth for "am I done
+ * iterating?" — it collapses per-slice progress and distinct closed AC IDs
+ * (from GREEN rows) into a single artifact the next-command contract reads.
+ */
+export declare function computeRalphLoopStatus(entries: TddCycleEntry[], options?: {
+    runId?: string;
+    now?: Date;
+}): RalphLoopStatus;
 /**
  * Checks whether the log contains a failing RED record associated with
  * `productionPath` for the active run.

package/dist/tdd-cycle.js

@@ -25,7 +25,11 @@ export function parseTddCycleLog(text) {
                     ? parsed.files.filter((item) => typeof item === "string")
                     : undefined,
                 exitCode: typeof parsed.exitCode === "number" ? parsed.exitCode : undefined,
-                note: typeof parsed.note === "string" ? parsed.note : undefined
+                note: typeof parsed.note === "string" ? parsed.note : undefined,
+                acIds: Array.isArray(parsed.acIds)
+                    ? parsed.acIds
+                        .filter((item) => typeof item === "string" && item.length > 0)
+                    : undefined
             };
             out.push(entry);
         }
@@ -122,6 +126,72 @@ export function validateTddCycleOrder(entries, options = {}) {
 function normalizePath(value) {
     return value.replace(/\\/gu, "/").toLowerCase();
 }
+/**
+ * Derive a lightweight Ralph Loop summary from parsed tdd-cycle-log entries.
+ * The goal is to give the model a single source of truth for "am I done
+ * iterating?" — it collapses per-slice progress and distinct closed AC IDs
+ * (from GREEN rows) into a single artifact the next-command contract reads.
+ */
+export function computeRalphLoopStatus(entries, options = {}) {
+    const runId = options.runId ?? "active";
+    const filtered = entries.filter((entry) => options.runId ? entry.runId === options.runId : true);
+    const slicesMap = new Map();
+    const acClosedSet = new Set();
+    let loopIteration = 0;
+    const redOpenSlices = [];
+    for (const slice of Array.from(new Set(filtered.map((entry) => entry.slice)))) {
+        slicesMap.set(slice, {
+            slice,
+            redCount: 0,
+            greenCount: 0,
+            refactorCount: 0,
+            redOpen: false,
+            acIds: []
+        });
+    }
+    for (const entry of filtered) {
+        const state = slicesMap.get(entry.slice);
+        if (!state)
+            continue;
+        if (entry.phase === "red") {
+            state.redCount += 1;
+            if (entry.exitCode !== undefined && entry.exitCode !== 0) {
+                state.redOpen = true;
+            }
+            continue;
+        }
+        if (entry.phase === "green") {
+            state.greenCount += 1;
+            state.redOpen = false;
+            loopIteration += 1;
+            if (Array.isArray(entry.acIds)) {
+                for (const acId of entry.acIds) {
+                    acClosedSet.add(acId);
+                    if (!state.acIds.includes(acId))
+                        state.acIds.push(acId);
+                }
+            }
+            continue;
+        }
+        state.refactorCount += 1;
+    }
+    for (const state of slicesMap.values()) {
+        if (state.redOpen)
+            redOpenSlices.push(state.slice);
+    }
+    const slices = Array.from(slicesMap.values()).sort((a, b) => a.slice.localeCompare(b.slice, "en"));
+    return {
+        schemaVersion: 1,
+        runId,
+        loopIteration,
+        redOpen: redOpenSlices.length > 0,
+        redOpenSlices,
+        acClosed: Array.from(acClosedSet).sort(),
+        sliceCount: slices.length,
+        slices,
+        lastUpdatedAt: (options.now ?? new Date()).toISOString()
+    };
+}
 /**
  * Checks whether the log contains a failing RED record associated with
  * `productionPath` for the active run.

package/package.json

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