cclaw-cli 0.48.13 → 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";
@@ -128,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.
 `;
 }
 /**

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

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