cclaw-cli 0.51.29 → 0.55.2

package/dist/content/node-hooks.js

@@ -1,10 +1,10 @@
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { DEFAULT_COMPOUND_RECURRENCE_THRESHOLD } from "../config.js";
+import { DEFAULT_COMPOUND_RECURRENCE_THRESHOLD, DEFAULT_EARLY_LOOP_MAX_ITERATIONS } from "../config.js";
 import { RUNTIME_ROOT } from "../constants.js";
 import { SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD, SMALL_PROJECT_RECURRENCE_THRESHOLD } from "../knowledge-store.js";
-import { HOOK_INLINE_SHARED_HELPERS, COMPOUND_READINESS_INLINE_SOURCE, RALPH_LOOP_INLINE_SOURCE } from "./hook-inline-snippets.js";
+import { HOOK_INLINE_SHARED_HELPERS, COMPOUND_READINESS_INLINE_SOURCE, RALPH_LOOP_INLINE_SOURCE, EARLY_LOOP_INLINE_SOURCE } from "./hook-inline-snippets.js";
 function normalizePatterns(patterns, fallback) {
     if (!patterns || patterns.length === 0)
         return [...fallback];
@@ -51,6 +51,12 @@ export function nodeHookRuntimeScript(options = {}) {
         options.compoundRecurrenceThreshold >= 1
         ? options.compoundRecurrenceThreshold
         : DEFAULT_COMPOUND_RECURRENCE_THRESHOLD;
+    const earlyLoopEnabled = options.earlyLoopEnabled !== false;
+    const earlyLoopMaxIterations = typeof options.earlyLoopMaxIterations === "number" &&
+        Number.isInteger(options.earlyLoopMaxIterations) &&
+        options.earlyLoopMaxIterations >= 1
+        ? options.earlyLoopMaxIterations
+        : DEFAULT_EARLY_LOOP_MAX_ITERATIONS;
     const cliRuntime = resolveCliRuntimeForGeneratedHook();
     return `#!/usr/bin/env node
 import fs from "node:fs/promises";
@@ -73,6 +79,8 @@ const DEFAULT_TDD_PRODUCTION_PATH_PATTERNS = ${JSON.stringify(tddProductionPathP
 const COMPOUND_RECURRENCE_THRESHOLD = ${JSON.stringify(compoundRecurrenceThreshold)};
 const SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD = ${JSON.stringify(SMALL_PROJECT_ARCHIVE_RUNS_THRESHOLD)};
 const SMALL_PROJECT_RECURRENCE_THRESHOLD = ${JSON.stringify(SMALL_PROJECT_RECURRENCE_THRESHOLD)};
+const EARLY_LOOP_ENABLED = ${JSON.stringify(earlyLoopEnabled)};
+const EARLY_LOOP_MAX_ITERATIONS = ${JSON.stringify(earlyLoopMaxIterations)};
 const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliRuntime.entrypoint)};
 const CCLAW_CLI_ARGS_PREFIX = ${JSON.stringify(cliRuntime.argsPrefix)};
 
@@ -253,7 +261,7 @@ async function readJsonFile(filePath, fallback = {}, options = {}) {
     } catch (parseErr) {
       // Emit a diagnostic breadcrumb instead of silently returning fallback.
       // The hook must still continue (soft-fail), but the corruption is
-      // now visible in \`state/hook-errors.jsonl\` and to \`cclaw doctor\`.
+      // now visible in \`state/hook-errors.jsonl\` and to \`npx cclaw-cli sync\`.
       if (options.root) {
         await recordHookError(
           options.root,
@@ -684,7 +692,6 @@ function detectTargetStage(payloadLower) {
 }
 
 function isFlowProgressionCommand(payloadLower) {
-  if (/(\\/cc-next|cc-next)([^a-z0-9_-]|$)/u.test(payloadLower)) return true;
   return /\\/cc([^a-z0-9_-]|$)/u.test(payloadLower);
 }
 
@@ -938,10 +945,11 @@ async function handleSessionStart(runtime) {
   );
   const knowledge = await buildKnowledgeDigest(runtime.root, state.currentStage, knowledgeRaw);
 
-  // Refresh Ralph Loop status each session-start so /cc-next and the model
+  // Refresh Ralph Loop status each session-start so /cc 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 = "";
+  let earlyLoopLine = "";
   if (state.currentStage === "tdd") {
     try {
       const ralphStatus = await computeRalphLoopStatusInline(stateDir, state.activeRunId);
@@ -956,7 +964,7 @@ async function handleSessionStart(runtime) {
     } catch (err) {
       // Best-effort — a malformed cycle log should never break
       // session-start. But we DO leave a breadcrumb in
-      // hook-errors.jsonl so \`cclaw doctor\` can surface chronic
+      // hook-errors.jsonl so \`npx cclaw-cli sync\` can surface chronic
       // failures (previously this was a silent swallow).
       await recordHookError(
         runtime.root,
@@ -965,6 +973,27 @@ async function handleSessionStart(runtime) {
       );
     }
   }
+  if (
+    EARLY_LOOP_ENABLED &&
+    (state.currentStage === "brainstorm" || state.currentStage === "scope" || state.currentStage === "design")
+  ) {
+    try {
+      const earlyLoopStatus = await computeEarlyLoopStatusInline(
+        stateDir,
+        state.currentStage,
+        state.activeRunId,
+        EARLY_LOOP_MAX_ITERATIONS
+      );
+      await writeJsonFile(path.join(stateDir, "early-loop.json"), earlyLoopStatus);
+      earlyLoopLine = formatEarlyLoopStatusLineInline(earlyLoopStatus);
+    } catch (err) {
+      await recordHookError(
+        runtime.root,
+        "session-start:early-loop",
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+  }
 
   // Keep compound-readiness.json fresh on every session-start (cheap derived
   // summary). Surface a one-line nudge only from review and ship stages
@@ -1002,7 +1031,7 @@ async function handleSessionStart(runtime) {
     // Best-effort — a malformed knowledge.jsonl must never break
     // session-start. But we DO leave a breadcrumb in
     // hook-errors.jsonl so config/IO problems become visible in
-    // \`cclaw doctor\` instead of silently degrading readiness output.
+    // \`npx cclaw-cli sync\` instead of silently degrading readiness output.
     await recordHookError(
       runtime.root,
       "session-start:compound-readiness",
@@ -1042,6 +1071,9 @@ async function handleSessionStart(runtime) {
   if (ralphLoopLine.length > 0) {
     parts.push(ralphLoopLine);
   }
+  if (earlyLoopLine.length > 0) {
+    parts.push(earlyLoopLine);
+  }
   if (compoundReadinessLine.length > 0) {
     parts.push(compoundReadinessLine);
   }
@@ -1049,7 +1081,7 @@ async function handleSessionStart(runtime) {
     parts.push(
       "Stale stages pending acknowledgement: " +
         staleStageNames.join(", ") +
-        " (use cclaw internal rewind --ack <stage> after redo)."
+        " (use npx cclaw-cli internal rewind --ack <stage> after redo)."
     );
   }
   if (knowledge.digestLines.length > 0) {
@@ -1137,7 +1169,7 @@ async function handleStopHandoff(runtime) {
   const shipSubstate = typeof closeoutObj.shipSubstate === "string" ? closeoutObj.shipSubstate : "idle";
   const closeoutContext =
     state.currentStage === "ship" || shipSubstate !== "idle"
-      ? " closeout.shipSubstate=" + shipSubstate + "; closeout chain=retro -> compound -> archive; continue closeout with /cc-next."
+      ? " closeout.shipSubstate=" + shipSubstate + "; closeout chain=retro -> compound -> archive; continue closeout with /cc."
       : "";
 
   const message =
@@ -1215,13 +1247,15 @@ async function handlePromptGuard(runtime) {
 }
 
 // Inline mirrors of canonical CLI computations (compound-readiness,
-// ralph-loop) are factored into src/content/hook-inline-snippets.ts so
+// ralph-loop, early-loop) are factored into
+// src/content/hook-inline-snippets.ts so
 // this 2000+-line file no longer owns their bodies. Each snippet carries
 // an explicit "mirrors X, parity enforced by Y" comment in the snippets
 // module. Parity is enforced by tests/unit/ralph-loop-parity.test.ts.
 ${HOOK_INLINE_SHARED_HELPERS}
 ${COMPOUND_READINESS_INLINE_SOURCE}
 ${RALPH_LOOP_INLINE_SOURCE}
+${EARLY_LOOP_INLINE_SOURCE}
 
 async function hasFailingRedEvidenceForPath(stateDir, runId, rawPath) {
   const cycleRaw = await readTextFile(path.join(stateDir, "tdd-cycle-log.jsonl"), "");
@@ -1401,7 +1435,7 @@ async function handleWorkflowGuard(runtime) {
     /^(read|readfile|open|view|cat|shell|runcommand|run_command|execcommand|exec_command|terminal)$/u.test(
       toolLower
     ) &&
-    /(\\.cclaw\\/state\\/flow-state\\.json|cclaw doctor|cclaw sync)/u.test(payloadLower);
+    /(\\.cclaw\\/state\\/flow-state\\.json|npx cclaw-cli sync|npx cclaw-cli sync|npx cclaw-cli sync|cclaw sync)/u.test(payloadLower);
   if (shouldRecordFlowRead) {
     await writeJsonFile(guardStateFile, {
       ...guardState,

package/dist/content/opencode-plugin.js

@@ -131,7 +131,7 @@ export default function cclawPlugin(ctx) {
     if (stageSupport.length > 0) parts.push(...stageSupport);
 
     parts.push(
-      "If you discover a non-obvious rule or pattern during stage work, add it to the current artifact ## Learnings section; stage-complete harvests it into .cclaw/knowledge.jsonl. If this plugin does not load, run \`cclaw sync\`, verify opencode.json(.c) includes the cclaw plugin registration, then run \`cclaw doctor --explain\`. Direct JSONL append is only for explicit manual learnings operations."
+      "If you discover a non-obvious rule or pattern during stage work, add it to the current artifact ## Learnings section; stage-complete harvests it into .cclaw/knowledge.jsonl. If this plugin does not load, run \`npx cclaw-cli sync\`, verify opencode.json(.c) includes the cclaw plugin registration, then run \`npx cclaw-cli sync\`. Direct JSONL append is only for explicit manual learnings operations."
     );
 
     const meta = (await readFileText(metaSkillPath)).trim();
@@ -510,7 +510,7 @@ export default function cclawPlugin(ctx) {
     notInitializedAdvised = true;
     logToFile(
       "guards skipped: cclaw is not initialized in this project. " +
-      "Run \`cclaw init\` in " + root + " to activate flow enforcement."
+      "Run \`npx cclaw-cli init\` in " + root + " to activate flow enforcement."
     );
   }
 
@@ -697,7 +697,7 @@ export default function cclawPlugin(ctx) {
         throw new Error(
           "cclaw " + failed + " blocked tool.execute.before.\\n" +
           "Reason: " + detail + "\\n" +
-          "Diagnose: run \`npx cclaw-cli doctor\` in project root.\\n" +
+          "Diagnose: run \`npx cclaw-cli sync\` in project root.\\n" +
           "Bypass (temporary): export CCLAW_DISABLE=1 before starting OpenCode,\\n" +
           "or set \`strictness: advisory\` in .cclaw/config.yaml."
         );

package/dist/content/session-hooks.js

@@ -36,7 +36,7 @@ When a new session begins in any harness:
 \`\`\`
 Cclaw flow state: [current stage] ([N] of 8 stages completed)
 Knowledge highlights: [rule/pattern 1], [rule/pattern 2], [rule/pattern 3]
-Next action: /cc-next to continue, /cc to start new work, or describe what you'd like to do.
+Next action: /cc to continue or start work, /cc-cancel to cancel, or describe what you'd like to do.
 \`\`\`
 
 ## Session Stop Protocol

package/dist/content/skills.js

@@ -3,10 +3,10 @@ import { nextStage as nextStageForTrack } from "../flow-state.js";
 import { FLOW_STAGES } from "../types.js";
 import { stageExamples } from "./examples.js";
 import { reviewStackAwareRoutes, reviewStackAwareRoutingSummary, stageAutoSubagentDispatch, stageSchema, stageTrackRenderContext } from "./stage-schema.js";
-import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
 import { referencePatternsForStage } from "./reference-patterns.js";
 import { harnessDelegationRecipes } from "../harness-adapters.js";
 const VERIFICATION_STAGES = ["tdd", "review", "ship"];
+const STAGE_LANGUAGE_POLICY_POINTER = "> Language policy: see `using-cclaw` section `Conversation Language Policy`.";
 // ---------- Cross-cutting universal mechanics (Layer 2 building blocks) ----------
 //
 // These are shared, structural blocks that get injected into every stage skill.
@@ -363,7 +363,7 @@ function completionParametersBlock(schema, track) {
     const nextDescription = nextStage === "done"
         ? "flow complete"
         : stageSchema(nextStage, track).skillDescription;
-    return `## Completion Parameters
+    return `### Completion Parameters
 
 - \`stage\`: \`${schema.stage}\`
 - \`next\`: \`${nextStage}\` (${nextDescription})
@@ -373,13 +373,26 @@ function completionParametersBlock(schema, track) {
 - \`completion helper\`: \`node .cclaw/hooks/stage-complete.mjs ${schema.stage}\`
 - \`completion helper with evidence\`: \`node .cclaw/hooks/stage-complete.mjs ${schema.stage} --evidence-json '{"<gate_id>":"<evidence note>"}' --passed=<gate_id>[,<gate_id>]\`
 - \`completion helper JSON diagnostics\`: append \`--json\` to receive a machine-readable validation failure summary.
-- \`delegation record helper\`: \`node .cclaw/hooks/delegation-record.mjs --stage=${schema.stage} --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|failed|waived|stale> --span-id=<spanId> --dispatch-id=<dispatchId> --dispatch-surface=<surface> --agent-definition-path=<path> --json\`. \`delegation helper recipe\`: call \`--status=scheduled\`, then \`--status=launched\`, then \`--status=acknowledged\`, then \`--status=completed\` with the same \`--span-id\`, \`--dispatch-id\`, \`--dispatch-surface\`, and \`--agent-definition-path\`; completed isolated/generic rows fail unless that same span already has an acknowledged event or the completed call includes \`--ack-ts=<iso>\`. For role-switch fallback, use \`--dispatch-surface=role-switch --evidence-ref=<artifact#anchor>\` instead of pretending isolated completion.
+- \`delegation lifecycle proof\`: use the delegation helper recipe in this section with explicit lifecycle rows: \`--status=scheduled\` -> \`--status=launched\` -> \`--status=acknowledged\` -> \`--status=completed\` (completed isolated/generic requires prior ACK for the same span or \`--ack-ts=<iso>\`).
 - Fill \`## Learnings\` before closeout: either \`- None this stage.\` or JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (knowledge-schema compatible).
-- Record mandatory delegation lifecycle in \`${RUNTIME_ROOT}/state/delegation-log.json\` and append proof events to \`${RUNTIME_ROOT}/state/delegation-events.jsonl\`; the ledger is current state, the event log is audit proof.${mandatoryAgents.length > 0 ? ` If a mandatory delegation cannot run in this harness, use \`--waive-delegation=${mandatoryAgents.join(",")} --waiver-reason="<why safe>"\` on the completion helper.` : ""}
+- Record mandatory delegation lifecycle in \`${RUNTIME_ROOT}/state/delegation-log.json\` and append proof events to \`${RUNTIME_ROOT}/state/delegation-events.jsonl\`; the ledger is current state, the event log is audit proof.${mandatoryAgents.length > 0 ? ` If a mandatory delegation cannot run in this harness, use \`--waive-delegation=${mandatoryAgents.join(",")} --waiver-reason="<why safe>"\` on the completion helper.` : ""} If proactive delegations were intentionally skipped, rerun only with \`--accept-proactive-waiver\` (optionally \`--accept-proactive-waiver-reason="<why safe>"\`) after explicit user approval.
 - Never edit raw \`flow-state.json\` to complete a stage, even in advisory mode; that bypasses validation, gate evidence, and Learnings harvest. If the helper fails, stop and report the exact command/output instead of applying a manual state workaround.
 - Completion protocol: verify required gates, update the artifact, then use the completion helper with \`--evidence-json\` and \`--passed\` for every satisfied gate.
 `;
 }
+function delegationAndCompletionBlock(schema, track) {
+    const dispatchBlock = autoSubagentDispatchBlock(schema.stage, track).trim();
+    const completionBlock = completionParametersBlock(schema, track).trim();
+    const normalizedDispatch = dispatchBlock.length > 0
+        ? dispatchBlock.replace(/^## Automatic Subagent Dispatch/mu, "### Automatic Subagent Dispatch")
+        : "### Automatic Subagent Dispatch\nNo automatic subagent dispatch rules for this stage.";
+    return `## Delegation & Completion
+
+${normalizedDispatch}
+
+${completionBlock}
+`;
+}
 function quickStartBlock(stage, track) {
     const schema = stageSchema(stage, track);
     const gatePreview = schema.executionModel.requiredGates.slice(0, 3).map((g) => `\`${g.id}\``).join(", ");
@@ -516,7 +529,7 @@ If you are about to violate the Iron Law, STOP. No amount of urgency, partial pr
 
 ${quickStartBlock(stage, track)}
 
-${conversationLanguagePolicyMarkdown()}
+${STAGE_LANGUAGE_POLICY_POINTER}
 ## Philosophy
 ${philosophy.purpose}
 
@@ -541,7 +554,7 @@ Stage state machine (map only; Checklist is authoritative):
 ${processFlowMermaid.length > 0 ? processFlowMermaid : "```mermaid\nflowchart TD\n  S1[\"Execute Checklist\"] --> S2[\"Satisfy required gates\"] --> S3[\"Verify before closeout\"]\n```"}
 
 ${platformNotesBlock}${contextLoadingBlock(stage, artifactRules.crossStageTrace, executionModel)}
-${autoSubagentDispatchBlock(stage, track)}
+${delegationAndCompletionBlock(schema, track)}
 ${stackAwareReviewRoutingBlock(stage)}
 ${researchPlaybooksBlock(executionModel.researchPlaybooks ?? [])}
 ${referencePatternsBlock(stage)}
@@ -575,7 +588,6 @@ ${verificationBlock(stage)}
 ## Exit Criteria
 ${executionModel.exitCriteria.map((item) => `- [ ] ${item}`).join("\n")}
 
-${completionParametersBlock(schema, track)}
 ## Artifact Rules
 - Artifact target: \`${RUNTIME_ROOT}/artifacts/${artifactRules.artifactFile}\`
 

package/dist/content/stage-command.js

@@ -10,7 +10,7 @@ Load and follow the authoritative stage skill:
 
 - \`${skillPath}\`
 
-Normal stage resume and advancement uses \`/cc-next\`. Use \`/cc-next\` to read
+Normal stage resume and advancement uses \`/cc\`. Use \`/cc\` to read
 \`.cclaw/state/flow-state.json\`, select the active stage, and advance only after
 that stage's gates pass. Do not duplicate the stage protocol here.
 `;

package/dist/content/stage-schema.js

@@ -89,6 +89,8 @@ function defaultReturnSchemaForAgent(agent) {
             return "architecture-return";
         case "spec-validator":
             return "spec-validation-return";
+        case "spec-document-reviewer":
+            return "review-return";
         case "slice-implementer":
             return "worker-return";
         case "performance-reviewer":
@@ -102,6 +104,7 @@ function defaultReturnSchemaForAgent(agent) {
         case "planner":
             return "planning-return";
         case "product-manager":
+        case "product-strategist":
             return "product-return";
         case "critic":
             return "critic-return";
@@ -258,6 +261,7 @@ const REQUIRED_GATE_IDS = {
     design: [
         "design_research_complete",
         "design_architecture_locked",
+        "design_diagram_freshness",
         "design_data_flow_mapped",
         "design_failure_modes_mapped",
         "design_test_and_perf_defined"
@@ -266,6 +270,7 @@ const REQUIRED_GATE_IDS = {
         "spec_acceptance_measurable",
         "spec_testability_confirmed",
         "spec_assumptions_surfaced",
+        "spec_self_review_complete",
         "spec_user_approved"
     ],
     plan: [
@@ -282,6 +287,9 @@ const REQUIRED_GATE_IDS = {
         "tdd_green_full_suite",
         "tdd_refactor_completed",
         "tdd_verified_before_complete",
+        "tdd_iron_law_acknowledged",
+        "tdd_watched_red_observed",
+        "tdd_slice_cycle_complete",
         "tdd_docs_drift_check",
         ...(track === "quick" ? [] : ["tdd_traceable_to_plan"])
     ],
@@ -322,9 +330,27 @@ const REQUIRED_ARTIFACT_SECTIONS = {
         "Spec Handoff",
         "Completion Dashboard"
     ],
-    spec: ["Acceptance Criteria", "Edge Cases", "Assumptions Before Finalization", "Acceptance Mapping", "Approval"],
+    spec: [
+        "Acceptance Criteria",
+        "Edge Cases",
+        "Assumptions Before Finalization",
+        "Acceptance Mapping",
+        "Spec Self-Review",
+        "Approval"
+    ],
     plan: ["Task List", "Dependency Batches", "Acceptance Mapping", "Execution Posture", "WAIT_FOR_CONFIRM"],
-    tdd: ["Test Discovery", "System-Wide Impact Check", "RED Evidence", "GREEN Evidence", "REFACTOR Notes", "Traceability", "Verification Ladder"],
+    tdd: [
+        "Test Discovery",
+        "System-Wide Impact Check",
+        "RED Evidence",
+        "GREEN Evidence",
+        "REFACTOR Notes",
+        "Traceability",
+        "Iron Law Acknowledgement",
+        "Watched-RED Proof",
+        "Vertical Slice Cycle",
+        "Verification Ladder"
+    ],
     review: ["Review Evidence Scope", "Changed-File Coverage", "Layer 1 Verdict", "Review Findings Contract", "Severity Summary", "Final Verdict"],
     ship: ["Preflight Results", "Release Notes", "Rollback Plan", "Finalization"]
 };
@@ -474,6 +500,14 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "When scope choices change user value, success metrics, or product positioning.",
             purpose: "Keep accepted/deferred reference ideas tied to user value and measurable success.",
             requiresUserGate: false
+        },
+        {
+            agent: "product-strategist",
+            mode: "proactive",
+            requiredAtTier: "standard",
+            when: "When scope mode resolves to SCOPE EXPANSION or SELECTIVE EXPANSION.",
+            purpose: "Drive 10x vision and concrete expansion proposals before locking the scope contract.",
+            requiresUserGate: false
         }
     ],
     design: [
@@ -546,6 +580,14 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             when: "When acceptance criteria need testability review or RED expressibility is uncertain.",
             purpose: "Confirm likely test levels, commands/manual evidence, and assertion surfaces are concrete.",
             requiresUserGate: false
+        },
+        {
+            agent: "spec-document-reviewer",
+            mode: "proactive",
+            requiredAtTier: "standard",
+            when: "When Spec Self-Review reports gaps (Status: Issues Found) or subsystem boundaries drift beyond one coherent plan slice.",
+            purpose: "Run a final document-level quality pass for completeness, consistency, clarity, and scope fit before handoff to plan.",
+            requiresUserGate: false
         }
     ],
     plan: [

package/dist/content/stages/_lint-metadata/index.js

@@ -6,6 +6,9 @@ const STAGE_POLICY_NEEDLES = {
         "Explore project context",
         "One question at a time",
         "2-3 architecturally distinct approaches",
+        "Embedded Grill",
+        "Victory Detector",
+        "Critic Pass",
         "State what is being approved",
         "Self-review before handoff",
         "Do NOT implement, scaffold, or modify behavior"
@@ -17,7 +20,9 @@ const STAGE_POLICY_NEEDLES = {
         "Discretion Areas",
         "NOT in scope",
         "Premise Challenge",
-        "Locked Decisions"
+        "Locked Decisions",
+        "Victory Detector",
+        "Critic Pass"
     ],
     design: [
         "Parallel Research Fleet",
@@ -25,9 +30,21 @@ const STAGE_POLICY_NEEDLES = {
         "Data Flow",
         "Failure Modes and Mitigation",
         "Performance Budget",
+        "Long-Term Trajectory",
+        "Victory Detector",
+        "Critic Pass",
         "One issue at a time"
     ],
-    spec: ["Acceptance Criteria", "Constraints", "Assumptions Before Finalization", "Testability", "approved spec", "Edge Cases"],
+    spec: [
+        "Acceptance Criteria",
+        "Constraints",
+        "Assumptions Before Finalization",
+        "Testability",
+        "Spec Self-Review",
+        "single subsystem",
+        "approved spec",
+        "Edge Cases"
+    ],
     plan: [
         "WAIT_FOR_CONFIRM",
         "Task Graph",
@@ -35,6 +52,8 @@ const STAGE_POLICY_NEEDLES = {
         "Acceptance Mapping",
         "verification steps",
         "Execution Posture",
+        "Calibrated Findings",
+        "Regression Iron Rule",
         "Locked Decision Coverage"
     ],
     tdd: [
@@ -42,8 +61,13 @@ const STAGE_POLICY_NEEDLES = {
         "GREEN",
         "REFACTOR",
         "failing test",
+        "Iron Law Acknowledgement",
+        "Watched-RED Proof",
+        "Vertical Slice Cycle",
         "Test Discovery",
         "System-Wide Impact Check",
+        "TDD Blocker Taxonomy",
+        "Per-Slice Review",
         "full test suite",
         "acceptance criteria",
         "traceable to plan slice"

package/dist/content/stages/brainstorm.js

@@ -5,8 +5,8 @@ export const BRAINSTORM = {
     schemaShape: "v2",
     stage: "brainstorm",
     complexityTier: "standard",
-    skillFolder: "brainstorming",
-    skillName: "brainstorming",
+    skillFolder: "brainstorm",
+    skillName: "brainstorm",
     skillDescription: "Problem-discovery stage. Build a concise Problem Decision Record, choose lite/standard/deep depth, compare distinct directions, and hand approved decisions to scope.",
     philosophy: {
         hardGate: "Do NOT invoke implementation skills, write code, scaffold projects, or mutate product behavior until a concrete direction is approved by the user.",
@@ -43,15 +43,17 @@ export const BRAINSTORM = {
             "**Reframe with How Might We** — write a single `How Might We …?` line that names the user/operator, the desired outcome, and the constraint. This is the altitude check before approaches.",
             "**Run Clarity Gate** — record ambiguity score (0.00-1.00), decision boundaries, reaffirmed non-goals, and residual-risk handoff before locking recommendations. If ambiguity remains high (>0.40), ask one decision-changing question before recommending.",
             "**Sharpening question discipline** — ask one decision-changing question at a time. Do not default to 3-5 batched questions; record only questions that changed the direction or a critical stop decision.",
-            "**Use compact discovery for simple apps** — for concrete low-risk asks (todo app, landing page, local widget), do one context pass, compare one baseline and one challenger, then ask for one explicit approval; do not drag the user through a full workshop.",
+            "**Use compact discovery for low-risk asks** — for concrete bounded requests, do one context pass, compare one baseline and one challenger, then ask for one explicit approval; do not drag the user through a full workshop.",
             "**Early-exit concrete asks** — for unambiguous implementation-only requests, write a compact Problem Decision Record plus short-circuit handoff (context, approved intent, constraints, assumptions, next-stage risks) and ask for one explicit approval.",
             "**Ask only decision-changing questions** — one at a time; if answers would not change approach and are non-critical preference/default assumptions, state the assumption and continue; STOP on scope, architecture, security, data loss, public API, migration, auth/pricing, or user approval uncertainty.",
             "**Compare 2-3 distinct approaches with stable Role/Upside columns** — Role values are `baseline` | `challenger` | `wild-card`; Upside is `low` | `modest` | `high` | `higher`; include real trade-offs, reuse notes, and reference-pattern source/disposition when a known pattern influenced the option; include exactly one challenger with explicit `high` or `higher` upside.",
             "**Collect reaction before recommending** — ask which option feels closest and what concern remains, then recommend based on that reaction.",
             "**Write the `Not Doing` list** — name 3-5 things this brainstorm explicitly is not committing to (vs. deferred). This protects scope from silent enlargement and the next stage from rework.",
+            "**Run early Ralph loop discipline** — after each producer iteration, append a `Critic Pass` JSONL row to `.cclaw/state/early-loop-log.jsonl`, refresh `.cclaw/state/early-loop.json`, and iterate until open concerns clear or convergence guard escalates.",
+            "**Embedded Grill (post-pick)** — after `Selected Direction` is named, run 3-5 sharp checks on hidden constraints, reversibility/rollback, scope boundaries, existing-pattern conformance, and domain-language fit; record each question with recommended answer and disposition (accept/refine/reject).",
             "**Self-review before user approval** — re-read the artifact and patch contradictions, weak trade-offs, placeholders, ambiguity, and weak handoff language. Record the result in `Self-Review Notes` using the calibrated review format: `- Status: Approved` (or `Issues Found`), `- Patches applied:` with inline note or sub-bullets, `- Remaining concerns:` with inline note or sub-bullets. Use `Patches applied: None` and `Remaining concerns: None` when there is nothing to record.",
             "**Request explicit approval** — state exactly what direction is being approved; do not advance without approval and artifact review.",
-            "**Handoff** — only after approval, hand scope: upstream decisions used, explicit drift, confidence level, unresolved questions, next-stage risk hints, and non-goals."
+            "**Handoff packet** — only after approval, produce a scope handoff packet with selected direction, why rejected options were rejected, explicit non-goals, unresolved questions, risk hints, and explicit drift from the initial ask so scope starts from locked upstream decisions instead of rediscovering intent."
         ],
         interactionProtocol: [
             "Start from observed project context; if the idea is vague, first narrow the project type with **one** structured question, then keep going.",
@@ -59,7 +61,7 @@ export const BRAINSTORM = {
             "Lead with the premise check (right problem / direct path / what if nothing) and the `How Might We` reframing before approaches; both go in the artifact, not just the chat.",
             "Ask at most one question per turn, only when decision-changing; if using a structured question tool, send exactly one question object, not a multi-question form.",
             "Only non-critical preference/default assumptions may continue inline. STOP and ask when uncertainty affects scope, architecture, security, data loss, public API, migration, auth/pricing, or user approval.",
-            "For simple greenfield web apps, present a compact A/B choice with one recommended path and one higher-upside challenger; keep the artifact concise but structurally complete (Context, Premise, How Might We, Sharpening Questions, Approaches, Reaction, Selected Direction, Not Doing).",
+            "For simple low-risk greenfield work, present a compact A/B choice with one recommended path and one higher-upside challenger; keep the artifact concise but structurally complete (Context, Premise, How Might We, Sharpening Questions, Approaches, Reaction, Selected Direction, Not Doing).",
             "Show approaches before the recommendation; include a higher-upside challenger and gather reaction first.",
             "Self-review before approval: re-read the artifact, fix contradictions/placeholders/weak trade-offs, then ask for approval. Do not ask for approval on a draft you have not re-read.",
             "State exactly what is being approved, then **STOP** until the user explicitly approves the artifact."
@@ -87,11 +89,12 @@ export const BRAINSTORM = {
             "2-3 approaches with trade-offs are recorded, including one higher-upside challenger option and reference-pattern source/disposition when applicable.",
             "User reaction to approaches is captured before final recommendation.",
             "Final recommendation explicitly reflects user reaction.",
+            "Early-loop status is reflected via `Victory Detector` / `Critic Pass` sections and `.cclaw/state/early-loop.json` when concerns remain.",
             "Selected Direction includes the handoff to the track-aware next stage: scope on standard, spec on medium when scope/design are skipped.",
             "When a promising option is parked, a seed file is created under `.cclaw/seeds/` and referenced in the artifact.",
             "Approved direction and approval marker are present.",
             "Assumptions and open questions are captured (or explicitly marked as none).",
-            "Scope handoff includes upstream decisions used, explicit drift, confidence, unresolved questions, next-stage risk hints, and non-goals."
+            "Scope handoff packet includes selected direction, upstream decisions used, explicit drift, confidence, unresolved questions, next-stage risk hints, and non-goals."
         ],
         inputs: ["problem statement", "constraints", "success criteria"],
         requiredContext: [
@@ -141,10 +144,13 @@ export const BRAINSTORM = {
             { section: "Reference Pattern Candidates", required: false, validationRule: "Recommended when examples influence direction: list pattern/source, reusable invariant, accept/reject/defer disposition, and reason before approaches are finalized." },
             { section: "Approaches", required: true, validationRule: "Must compare 2-3 distinct options with real trade-offs. Use the canonical `Role` column with `baseline` | `challenger` | `wild-card` and the `Upside` column with `low` | `modest` | `high` | `higher`; include exactly one challenger row with `high` or `higher` upside, and cite reference-pattern source/disposition when applicable." },
             { section: "Approach Reaction", required: true, validationRule: "Must appear before Selected Direction and summarize user reaction before recommendation, including `Closest option`, `Concerns`, and what changed after reaction." },
-            { section: "Selected Direction", required: true, validationRule: "Must include the selected approach, explicit approval marker, rationale traceable to Approach Reaction, and scope handoff with decisions, drift, confidence, unresolved questions, risk hints, and non-goals." },
+            { section: "Selected Direction", required: true, validationRule: "Must include the selected approach, explicit approval marker, rationale traceable to Approach Reaction, and a scope handoff packet with selected direction, decisions, drift, confidence, unresolved questions, risk hints, and non-goals." },
+            { section: "Embedded Grill", required: false, validationRule: "Recommended after Selected Direction: 3-5 rows covering hidden constraints, reversibility/rollback, scope boundaries, existing-pattern fit, and domain-language alignment. Each row records question, recommended answer, and disposition (accept/refine/reject)." },
             { section: "Not Doing", required: false, validationRule: "Recommended: 3-5 explicitly non-committed items (distinct from deferred). Protects scope from silent enlargement and the next stage from rework." },
             { section: "Design", required: false, validationRule: "Must cover architecture, key components, and data flow scaled to complexity." },
             { section: "Visual Companion", required: false, validationRule: "If architecture/data-flow complexity is medium+, include compact ASCII/Mermaid diagram or explicitly justify omission." },
+            { section: "Victory Detector", required: false, validationRule: "Recommended early-loop checkpoint: cite `.cclaw/state/early-loop.json`, current iteration/maxIterations, open concern count, convergence status, and iterate/ready/escalate decision." },
+            { section: "Critic Pass", required: false, validationRule: "Recommended producer/critic log contract: each iteration appends one JSONL row to `.cclaw/state/early-loop-log.jsonl` with runId, stage, iteration, and open concerns." },
             { section: "Self-Review Notes", required: false, validationRule: "Recommended: use the calibrated review format — `- Status: Approved` (or `Issues Found`), `- Patches applied:` (inline note or sub-bullets, use `None` if nothing changed), `- Remaining concerns:` (inline note or sub-bullets, use `None` if nothing remains). Done before requesting user approval." },
             { section: "Assumptions and Open Questions", required: false, validationRule: "Must capture unresolved assumptions/open questions, or explicitly state none." }
         ],

package/dist/content/stages/design.js

@@ -1,4 +1,4 @@
-import { REVIEW_LOOP_CHECKLISTS, reviewLoopPolicySummary, reviewLoopSecondOpinionSummary } from "../review-loop.js";
+import { REVIEW_LOOP_CHECKLISTS, reviewLoopPolicySummary } from "../review-loop.js";
 import { decisionProtocolInstruction } from "../decision-protocol.js";
 // ---------------------------------------------------------------------------
 // DESIGN — reference: gstack Eng review
@@ -7,8 +7,8 @@ export const DESIGN = {
     schemaShape: "v2",
     stage: "design",
     complexityTier: "standard",
-    skillFolder: "engineering-design-lock",
-    skillName: "engineering-design-lock",
+    skillFolder: "design",
+    skillName: "design",
     skillDescription: "Engineering lock stage. Convert the approved scope contract into a buildable architecture with adversarial alternatives, failure/rescue paths, and spec handoff.",
     philosophy: {
         hardGate: "Do NOT write implementation code. This stage produces design decisions and architecture documents only. No code changes, no scaffolding, no test files.",
@@ -49,8 +49,9 @@ export const DESIGN = {
             "Architecture Review — lock boundaries, chosen path, shadow alternative, switch trigger, failure/rescue/degraded behavior, and verification evidence for every high-risk choice; include tier-required diagrams.",
             "Review core risk areas — existing system fit, data/state flow, critical path, security/trust boundaries, tests, performance budget, observability/debuggability, rollout/rollback, rejected alternatives, and spec handoff.",
             "**ADR + pre-mortem contract** — capture ADR-style decision rows (context, decision, alternatives, consequences), run a pre-mortem on likely failures, and map each critical flow to a validating test and diagram anchor before lock.",
-            `Critic pass — run/reconcile adversarial second opinion on architecture, coupling, failure modes, and cheaper alternatives. ${reviewLoopPolicySummary("design")} ${reviewLoopSecondOpinionSummary("design")}`,
-            "Run optional stale-diagram audit only when configured.",
+            "Critic pass — run/reconcile adversarial second opinion on architecture, coupling, failure modes, and cheaper alternatives; record outcomes per the Design Outside Voice Loop policy.",
+            "**Run early Ralph loop discipline** — after each producer iteration, append a `Critic Pass` JSONL row to `.cclaw/state/early-loop-log.jsonl`, refresh `.cclaw/state/early-loop.json`, and iterate until open concerns clear or convergence guard escalates.",
+            "Run stale-diagram audit as a design freshness gate (default-on; explicit config opt-out allowed).",
             "Capture leftovers — seed high-upside deferred ideas, list unresolved decisions with defaults, document distribution for new artifact types, and cross-reference deferred items to scope or unresolved decisions."
         ],
         interactionProtocol: [
@@ -71,7 +72,7 @@ export const DESIGN = {
             "Run investigator pass plus scope challenge/search-before-building.",
             "Walk review sections interactively and lock boundaries, data flow, state transitions, edge cases, and failure modes.",
             "Cover security, observability, deployment, tests, and performance for Standard+ changes.",
-            "Run configured stale-diagram audit when enabled.",
+            "Run stale-diagram audit (enabled by default unless explicitly disabled).",
             "Produce required outputs: NOT-in-scope, What-already-exists, tier diagrams, failure table, completion dashboard.",
             "Plant high-upside deferred ideas when useful and reconcile critic/outside-voice findings.",
             "Write design lock artifact for downstream spec/plan with design decisions, rejected alternatives, verification evidence, and exact spec handoff."
@@ -79,6 +80,7 @@ export const DESIGN = {
         requiredGates: [
             { id: "design_research_complete", description: "Research is complete: compact inline synthesis by default, or a separate research artifact for deep/high-risk work, and findings are mapped to design decisions." },
             { id: "design_architecture_locked", description: "Architecture boundaries are explicit and approved." },
+            { id: "design_diagram_freshness", description: "Stale Diagram Audit is clear, or explicitly skipped for compact trivial-override slices without diagram markers." },
             { id: "design_data_flow_mapped", description: "Data/state flow includes edge-case paths." },
             { id: "design_failure_modes_mapped", description: "Failure modes and mitigations are documented." },
             { id: "design_test_and_perf_defined", description: "Test strategy and performance budget are defined." }
@@ -88,12 +90,13 @@ export const DESIGN = {
             "Artifact written to `.cclaw/artifacts/03-design-<slug>.md`.",
             "Failure-mode table exists in Method/Exception/Rescue/UserSees format.",
             "Tier-required diagram markers are present: architecture (all tiers). Standard/Deep add-ons (shadow/error) and Deep add-ons (state-machine/rollback/deployment-sequence) are included only when risk warrants them.",
-            "When `.cclaw/config.yaml::optInAudits.staleDiagramAudit` is true, stale diagram audit finding is clear (no blast-radius file newer than diagram markers without explicit update).",
+            "Stale diagram audit finding is clear by default (unless `.cclaw/config.yaml::optInAudits.staleDiagramAudit` is explicitly false): no blast-radius file newer than diagram markers without explicit update.",
             "Security & threat model findings are documented with mitigations.",
             "Observability and deployment plans are explicit for critical flows.",
             "Outside-voice findings and dispositions are recorded (accept/reject/defer).",
-            `Spec review loop summary includes iteration count and quality score trajectory per ${reviewLoopPolicySummary("design")}`,
-            reviewLoopSecondOpinionSummary("design"),
+            "Design outside-voice loop summary includes iteration count and quality-score trajectory with explicit stop reason and unresolved concerns.",
+            "Early-loop status is reflected via `Victory Detector` / `Critic Pass` sections and `.cclaw/state/early-loop.json` when concerns remain.",
+            "When a second opinion is used, record source, critique frame, and disposition (accept/reject/defer) with rationale.",
             "Adversarial lock table includes chosen path, shadow alternative, switch trigger, failure/rescue/degraded behavior, and verification evidence, with reference-grade contracts for mirrored patterns when applicable.",
             "Architecture Decision Record (ADR) section captures context, decision, alternatives, consequences, and reversal trigger for major choices.",
             "Pre-mortem section lists top failure scenarios, early signals, mitigations, and owner before implementation begins.",
@@ -158,13 +161,12 @@ export const DESIGN = {
             { section: "Data-Flow Shadow Paths", required: false, validationRule: "Standard/Deep add-on: include `<!-- diagram: data-flow-shadow-paths -->` marker plus a table for high-risk choices: chosen path, shadow alternative, switch trigger, failure/rescue/degraded behavior, and verification evidence." },
             { section: "Error Flow Diagram", required: false, validationRule: "Standard/Deep add-on: include `<!-- diagram: error-flow -->` marker and failure-detection -> rescue -> user-visible outcome flow." },
             { section: "Data Flow", required: false, validationRule: "Must include data/state flow, happy path, nil input, empty input, upstream error paths, plus Interaction Edge Case matrix rows for double-click, nav-away-mid-request, 10K-result dataset, background-job abandonment, zombie connection. Each row declares handled yes/no and deferred item when not handled." },
-            { section: "Stale Diagram Audit", required: false, validationRule: "When `.cclaw/config.yaml::optInAudits.staleDiagramAudit` is true: blast-radius files from Codebase Investigation must not be newer than the current design diagram-marker baseline unless explicitly refreshed." },
+            { section: "Stale Diagram Audit", required: false, validationRule: "Default-on audit (unless `.cclaw/config.yaml::optInAudits.staleDiagramAudit` is false): blast-radius files from Codebase Investigation must not be newer than the current design diagram-marker baseline unless explicitly refreshed." },
             { section: "Failure Mode Table", required: true, validationRule: "Use Method/Exception/Rescue/UserSees columns and treat silent user impact without rescue as critical." },
             { section: "Pre-mortem", required: false, validationRule: "Recommended: list top failure scenarios, early warning signal, mitigation owner, and containment action before implementation." },
             { section: "Security & Threat Model", required: true, validationRule: "Must list trust boundaries, abuse/failure scenarios, mitigations, and residual risks." },
             { section: "Test Strategy", required: false, validationRule: "Must define unit/integration/e2e expectations with coverage targets." },
             { section: "Test-Diagram Mapping", required: false, validationRule: "Recommended: map each critical flow to at least one validating test ID and one diagram marker/anchor." },
-            { section: "Test Strategy", required: false, validationRule: "Must define unit/integration/e2e expectations with coverage targets." },
             { section: "Performance Budget", required: false, validationRule: "For each critical path: metric name, target threshold, and measurement method." },
             { section: "Observability & Debuggability", required: true, validationRule: "Must define logs/metrics/traces plus alerting/debug path for critical failure modes." },
             { section: "Deployment & Rollout", required: true, validationRule: "Must define migration/flag strategy, rollout/rollback plan, switch trigger, and post-deploy verification steps." },
@@ -173,8 +175,11 @@ export const DESIGN = {
             { section: "Rejected Alternatives", required: false, validationRule: "List alternatives considered, why rejected, and what signal would revive them." },
             { section: "Design Decisions", required: false, validationRule: "Stable design decisions with requirement/locked-decision refs and downstream spec impact." },
             { section: "Spec Handoff", required: true, validationRule: "Exact requirements, design decisions, risks, test/perf expectations, and unresolved questions that spec must carry forward." },
+            { section: "Long-Term Trajectory", required: false, validationRule: "Recommended (1-3 lines, present-only): name what comes after this ships (Phase 2 / Phase 3 / platform promotion) and whether the locked architecture can absorb that path without major rework. Use `None - tactical change only` for compact slices." },
             { section: "Outside Voice Findings", required: false, validationRule: "Critic pass: list adversarial findings and disposition (accept/reject/defer) with rationale per material finding." },
             { section: "Design Outside Voice Loop", required: false, validationRule: `Record iteration table with quality score per iteration, stop reason, and unresolved concerns. Enforce ${reviewLoopPolicySummary("design")}` },
+            { section: "Victory Detector", required: false, validationRule: "Recommended early-loop checkpoint: cite `.cclaw/state/early-loop.json`, current iteration/maxIterations, open concern count, convergence status, and iterate/ready/escalate decision." },
+            { section: "Critic Pass", required: false, validationRule: "Recommended producer/critic log contract: each iteration appends one JSONL row to `.cclaw/state/early-loop-log.jsonl` with runId, stage, iteration, and open concerns." },
             { section: "NOT in scope", required: false, validationRule: "Work considered and explicitly deferred with one-line rationale." },
             { section: "Completion Dashboard", required: true, validationRule: "Lists every review section with status (clear / issues-found-resolved / issues-open), critical/open gap counts, decision count, and unresolved items (or 'None')." }
         ],