cclaw-cli 0.51.30 → 0.55.2

package/dist/content/iron-laws.js

@@ -146,31 +146,37 @@ export function ironLawRuntimeDocument(options = {}) {
         laws
     };
 }
-export function ironLawsAgentsMdBlock() {
-    const rows = IRON_LAWS.map((law) => {
-        return `| \`${law.id}\` | ${law.rule} | ${law.enforcement} | ${law.severity} |`;
-    }).join("\n");
-    return `### Iron Laws
-
-These rules are always-on. Hook-enforced laws can block actions in strict mode.
-
-| ID | Rule | Enforced by | Level |
-|---|---|---|---|
-${rows}
-`;
+function appliesToLabel(law) {
+    return law.appliesTo === "all" ? "all stages" : law.appliesTo.join(", ");
+}
+function hardGateReference(law) {
+    if (law.appliesTo === "all") {
+        return "the active stage `HARD-GATE` block in `.cclaw/skills/<stage>/SKILL.md`";
+    }
+    return law.appliesTo
+        .map((stage) => `\`${RUNTIME_ROOT}/skills/${stage}/SKILL.md\` (${stage} HARD-GATE)`)
+        .join(", ");
 }
 export function ironLawsSkillMarkdown() {
-    const list = IRON_LAWS.map((law, index) => {
-        const applies = law.appliesTo === "all" ? "all stages" : law.appliesTo.join(", ");
+    const enforcedLawIds = new Set([
+        "stop-clean-or-handoff",
+        "review-coverage-complete-before-ship"
+    ]);
+    const enforced = IRON_LAWS.filter((law) => enforcedLawIds.has(law.id));
+    const advisory = IRON_LAWS.filter((law) => !enforcedLawIds.has(law.id));
+    const enforcedSections = enforced.map((law, index) => {
         return `### ${index + 1}. ${law.title}
 
 - **ID:** \`${law.id}\`
 - **Rule:** ${law.rule}
 - **Why:** ${law.rationale}
-- **Applies to:** ${applies}
+- **Applies to:** ${appliesToLabel(law)}
 - **Enforced by:** ${law.enforcement} (${law.severity})
 `;
     }).join("\n");
+    const advisoryList = advisory
+        .map((law) => `- \`${law.id}\` — applies to ${appliesToLabel(law)}; see ${hardGateReference(law)}.`)
+        .join("\n");
     return `---
 name: iron-laws
 description: "Non-negotiable workflow constraints enforced by cclaw hooks and routing."
@@ -181,7 +187,16 @@ description: "Non-negotiable workflow constraints enforced by cclaw hooks and ro
 These are cclaw's non-negotiable constraints for harness sessions.  
 Use them as the final arbitration layer when local instructions conflict.
 
-${list}
+## Hook-Enforced Runtime Laws
+
+${enforcedSections}
+
+## Advisory Laws (Stage-Owned)
+
+The following laws remain active guidance, but their canonical enforcement surface
+is each stage's \`HARD-GATE\` contract:
+
+${advisoryList}
 
 ## Practical rule
 

package/dist/content/learnings.js

@@ -101,7 +101,7 @@ Optional fields \`source\`, \`severity\`, \`supersedes\`, and \`superseded_by\`
 | \`first_seen_ts\` | ISO 8601 UTC string | yes | First observed timestamp (usually equals \`created\`). |
 | \`last_seen_ts\` | ISO 8601 UTC string | yes | Last re-confirmed timestamp. |
 | \`project\` | string \\| null | yes | Repo or scope name. Use \`null\` when the entry crosses projects. |
-| \`source\` | \`"stage" \\| "retro" \\| "compound" \\| "ideate" \\| "manual" \\| null\` | no | Origin channel for the entry when known. |
+| \`source\` | \`"stage" \\| "retro" \\| "compound" \\| "idea" \\| "manual" \\| null\` | no | Origin channel for the entry when known. |
 | \`severity\` | \`"critical" \\| "important" \\| "suggestion"\` | no | Priority signal for compound lifts; \`critical\` enables single-hit override in compound readiness analysis. |
 | \`supersedes\` | string[] | no | Non-empty IDs/slugs of older entries this entry refreshes. Use only for clear replacements discovered during compound closeout or curation. |
 | \`superseded_by\` | string | no | Non-empty ID/slug of the newer entry that refreshes this one. Use only when marking stale guidance as replaced. |

package/dist/content/meta-skill.js

@@ -13,7 +13,7 @@ function generatedHelperSkillList() {
 export function usingCclawSkillMarkdown() {
     return `---
 name: using-cclaw
-description: "Routing brain for cclaw. Decide whether to start/resume a stage, answer directly, or use visible commands like /cc, /cc-ideate, and /cc-cancel."
+description: "Routing brain for cclaw. Decide whether to start/resume a stage, answer directly, or use visible commands like /cc, /cc-idea, and /cc-cancel."
 ---
 
 # Using Cclaw
@@ -64,7 +64,7 @@ Task arrives
   ├─ Running as spawned subagent? -> obey parent prompt only; do not run cclaw routing
   ├─ Pure question / non-software ask? -> answer directly (no stage)
   ├─ New software work? -> /cc <idea>
-  ├─ Repo-improvement discovery? -> /cc-ideate
+  ├─ Repo-improvement discovery? -> /cc-idea
   ├─ Resume existing flow? -> /cc
   ├─ Knowledge operation? -> load the learnings skill
   ├─ Normal post-ship closeout? -> /cc drives ${closeoutChainInline()}
@@ -92,18 +92,18 @@ Before stage work:
 ## Platform reliability notes
 
 - Managed hook dispatch uses \`.cclaw/hooks/run-hook.cmd\` (cross-platform wrapper).
-- If hooks fail due missing runtime deps (for example \`node\` not on \`PATH\`), run \`npx cclaw-cli doctor\` before continuing.
+- If hooks fail due missing runtime deps (for example \`node\` not on \`PATH\`), run \`npx cclaw-cli sync\` before continuing.
 - Prefer cross-platform commands in artifacts/examples (\`npm test\`, \`pnpm test\`, \`python -m pytest\`, etc.) over shell-specific aliases whenever possible.
 
 ## Stage quick map
 
-Use \`/cc <idea>\` for new work, \`/cc\` for progression and closeout, \`/cc-ideate\` for backlog discovery, and \`/cc-cancel\` for cancellation/abandonment.
+Use \`/cc <idea>\` for new work, \`/cc\` for progression and closeout, \`/cc-idea\` for backlog discovery, and \`/cc-cancel\` for cancellation/abandonment.
 
 ## Main vs Operator Surfaces
 
-- **Main workflow:** \`/cc\`, \`/cc-ideate\`, and \`/cc-cancel\` inside the installed harness runtime.
-- **Installer/support surface:** \`npx cclaw-cli init\`, \`npx cclaw-cli sync\`, \`npx cclaw-cli upgrade\`, \`npx cclaw-cli doctor\`, and explicit support/archive actions. Do not ask users to install or run a \`cclaw\` binary during normal stage flow.
-- Use operator/support surfaces only for install/runtime diagnosis, explicit archival, or deeper inspection. Do not make them part of the happy path.
+- **Main workflow:** \`/cc\`, \`/cc-idea\`, and \`/cc-cancel\` inside the installed harness runtime.
+- **Installer/support surface:** \`npx cclaw-cli init\`, \`npx cclaw-cli sync\`, \`npx cclaw-cli upgrade\`, \`npx cclaw-cli sync\`, and \`npx cclaw-cli uninstall\`.
+- Use operator/support surfaces only for install/runtime diagnosis or lifecycle maintenance. Do not make them part of the happy path.
 
 ## Whole flow map
 

package/dist/content/node-hooks.d.ts

@@ -15,6 +15,16 @@ export interface NodeHookRuntimeOptions {
      * `cclaw sync` after changing the config value so hook and CLI agree.
      */
     compoundRecurrenceThreshold?: number;
+    /**
+     * Enables early-stage producer/critic loop diagnostics in session-start.
+     * Defaults to true.
+     */
+    earlyLoopEnabled?: boolean;
+    /**
+     * Baked-in max iterations for brainstorm/scope/design early-loop status.
+     * Derived from `config.earlyLoop.maxIterations`.
+     */
+    earlyLoopMaxIterations?: number;
 }
 /**
  * Node-only hook runtime (single entrypoint).

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);
 }
 
@@ -942,6 +949,7 @@ async function handleSessionStart(runtime) {
   // 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) {
@@ -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/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-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." }
         ],