cclaw-cli 0.51.7 → 0.51.9

package/dist/artifact-linter.js

@@ -85,6 +85,15 @@ function sectionBodyByName(sections, section) {
     }
     return null;
 }
+function sectionBodyByAnyName(sections, sectionNames) {
+    const bodies = sectionNames.flatMap((section) => {
+        const body = sectionBodyByName(sections, section);
+        return body === null ? [] : [`### ${section}\n${body}`];
+    });
+    if (bodies.length === 0)
+        return null;
+    return bodies.join("\n");
+}
 export function extractMarkdownSectionBody(markdown, section) {
     return sectionBodyByName(extractH2Sections(markdown), section);
 }
@@ -243,7 +252,7 @@ function meaningfulLineCount(sectionBody) {
         .filter((line) => line.length > 0)
         .filter((line) => !line.startsWith("<!--"))
         .filter((line) => !/^[-:| ]+$/u.test(line))
-        .filter((line) => /[A-Za-z0-9]/u.test(line))
+        .filter((line) => /[\p{L}\p{N}]/u.test(line))
         .length;
 }
 function lineHasToken(line, token) {
@@ -355,6 +364,35 @@ function getMarkdownTableRows(sectionBody) {
     }
     return rows;
 }
+function getApproachRows(sectionBody) {
+    const tableRows = getMarkdownTableRows(sectionBody).map((row) => row.join(" "));
+    const headingRows = sectionBody
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter((line) => /^#{3,6}\s+\S/u.test(line))
+        .map((line) => line.replace(/^#{3,6}\s+/u, ""));
+    const bulletRows = sectionBody
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter((line) => /^(?:[-*]|\d+\.)\s+\S/u.test(line));
+    return [...tableRows, ...headingRows, ...bulletRows];
+}
+function hasSemanticChallenger(row) {
+    const normalized = row
+        .replace(/[_`*]/gu, " ")
+        .replace(/\s+/gu, " ")
+        .trim()
+        .toLowerCase();
+    const isChallenger = /\bchallenger\b/u.test(normalized);
+    if (!isChallenger)
+        return false;
+    return (/\bhigher[-\s]?upside\b/u.test(normalized) ||
+        /\bhigh[-\s]?upside\b/u.test(normalized) ||
+        /\bupside\s*:?\s*(?:high|higher|strong|large|meaningful)\b/u.test(normalized) ||
+        /\b(?:high|higher|strong|large|meaningful)\s+upside\b/u.test(normalized) ||
+        /\b(?:10-star|ten-star|ambitious|higher leverage|leverage)\b/u.test(normalized) ||
+        /\bhigh\b/u.test(normalized));
+}
 function parseBinaryFlag(value) {
     const normalized = value.trim().toLowerCase();
     if (/^(?:y|yes|true|1)$/u.test(normalized))
@@ -1331,7 +1369,11 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
         : null;
     for (const v of schema.artifactValidation) {
         const sectionKey = normalizeHeadingTitle(v.section).toLowerCase();
-        const hasHeading = headingPresent(sections, v.section);
+        const scopeBoundaryAlias = stage === "scope" && sectionKey === "in scope / out of scope";
+        const body = scopeBoundaryAlias
+            ? sectionBodyByAnyName(sections, ["In Scope / Out of Scope", "In Scope", "Out of Scope"])
+            : sectionBodyByName(sections, v.section);
+        const hasHeading = body !== null;
         const effectiveRequiredFromOverride = overrideSet
             ? overrideSet.has(sectionKey) ? true : false
             : v.required;
@@ -1340,7 +1382,6 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
             : stage === "scope" && sectionKey === "pre-scope system audit" && scopePreAuditEnabled
                 ? true
                 : effectiveRequiredFromOverride;
-        const body = hasHeading ? sectionBodyByName(sections, v.section) : null;
         const validation = body === null
             ? { ok: false, details: `No ## heading matching required section "${v.section}".` }
             : validateSectionBody(body, v.validationRule, v.section);
@@ -1403,12 +1444,8 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
                 .map((line) => line.trim())
                 .filter((line) => /^(?:[-*]|\d+\.)\s+\S/u.test(line));
             const rowCount = Math.max(tableRows.length, bulletRows.length);
-            const hasChallengerFromTable = tableRows.some((row) => {
-                const joined = row.join(" ");
-                return /\bchallenger\b/iu.test(joined) && /\bhigher[-\s]?upside\b/iu.test(joined);
-            });
-            const hasChallengerFromBullets = bulletRows.some((row) => /\bchallenger\b/iu.test(row) && /\bhigher[-\s]?upside\b/iu.test(row));
-            const hasChallenger = hasChallengerFromTable || hasChallengerFromBullets;
+            const approachRows = getApproachRows(approachesBody);
+            const hasChallenger = approachRows.some(hasSemanticChallenger);
             findings.push({
                 section: "Distinct Approaches Enforcement",
                 required: true,
@@ -1421,11 +1458,11 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
             findings.push({
                 section: "Challenger Alternative Enforcement",
                 required: true,
-                rule: "Approaches must include one option labeled `challenger: higher-upside`.",
+                rule: "Approaches must include one challenger option with explicit high/higher upside.",
                 found: hasChallenger,
                 details: hasChallenger
-                    ? "Challenger higher-upside alternative detected."
-                    : "Missing `challenger: higher-upside` alternative in Approaches."
+                    ? "Semantic challenger with high/higher upside detected."
+                    : "Missing a challenger option with explicit high/higher upside. Example: `| C | challenger | high upside | More ambitious path with clear trade-offs |`."
             });
         }
         const reactionIndex = headingLineIndex(raw, "Approach Reaction");
@@ -1455,15 +1492,17 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
                     : "No explicit `approved`/`approval` marker found in Selected Direction."
             });
             if (!brainstormShortCircuitActivated) {
-                const reactionTrace = /\b(?:reaction|feedback|concern(?:s)?)\b/iu.test(directionBody);
+                const reactionBody = sectionBodyByName(sections, "Approach Reaction");
+                const reactionTrace = /\b(?:reaction|feedback|concern(?:s)?)\b/iu.test(directionBody) ||
+                    (reactionIndex >= 0 && reactionIndex < directionIndex && meaningfulLineCount(reactionBody ?? "") > 0);
                 findings.push({
                     section: "Direction Reaction Trace",
                     required: true,
-                    rule: "Selected Direction rationale must reference user reaction/feedback before recommendation.",
+                    rule: "Selected Direction must be traceable to a prior Approach Reaction section or explicitly reference user reaction/feedback/concerns.",
                     found: reactionTrace,
                     details: reactionTrace
-                        ? "Selected Direction rationale references user reaction/feedback."
-                        : "Selected Direction rationale does not reference user reaction/feedback."
+                        ? "Selected Direction is traceable to prior user reaction."
+                        : "Selected Direction is not traceable to user reaction. Add `## Approach Reaction` before it, or mention the user's reaction/concerns in the rationale."
                 });
             }
         }
@@ -1613,7 +1652,7 @@ export async function lintArtifact(projectRoot, stage, track = "standard") {
         const strictScopeGuards = parsedFrontmatter.hasFrontmatter ||
             headingPresent(sections, "Locked Decisions (D-XX)");
         const scopeSections = [
-            sectionBodyByName(sections, "In Scope / Out of Scope") ?? "",
+            sectionBodyByAnyName(sections, ["In Scope / Out of Scope", "In Scope", "Out of Scope"]) ?? "",
             sectionBodyByName(sections, "Scope Summary") ?? "",
             lockedDecisionsBody
         ].join("\n");

package/dist/content/hooks.js

@@ -78,7 +78,7 @@ async function main() {
   const cliEntrypoint = process.env.CCLAW_CLI_JS || CCLAW_CLI_ENTRYPOINT;
   if (!cliEntrypoint || cliEntrypoint.trim().length === 0) {
     process.stderr.write(
-      "[cclaw] " + HELPER_NAME + ": local Node runtime entrypoint is missing. Re-run npx cclaw-cli sync or npx cclaw-cli upgrade to regenerate hooks.\\n"
+      "[cclaw] " + HELPER_NAME + ": local Node runtime entrypoint is missing. Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
     );
     process.exitCode = 1;
     return;
@@ -89,7 +89,7 @@ async function main() {
     if (!stat.isFile()) throw new Error("not-file");
   } catch {
     process.stderr.write(
-      "[cclaw] " + HELPER_NAME + ": local Node runtime entrypoint not found at " + cliEntrypoint + ". Re-run npx cclaw-cli sync or npx cclaw-cli upgrade to regenerate hooks.\\n"
+      "[cclaw] " + HELPER_NAME + ": local Node runtime entrypoint not found at " + cliEntrypoint + ". Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
     );
     process.exitCode = 1;
     return;
@@ -176,7 +176,7 @@ function printUsage() {
   process.stderr.write(
     "Usage: node " +
       RUNTIME_ROOT +
-      "/hooks/stage-complete.mjs <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...]\\n"
+      "/hooks/stage-complete.mjs <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...] [--json]\\n"
   );
 }
 
@@ -202,7 +202,7 @@ async function main() {
   const cliEntrypoint = process.env.CCLAW_CLI_JS || CCLAW_CLI_ENTRYPOINT;
   if (!cliEntrypoint || cliEntrypoint.trim().length === 0) {
     process.stderr.write(
-      "[cclaw] stage-complete: local Node runtime entrypoint is missing. Re-run npx cclaw-cli sync or npx cclaw-cli upgrade to regenerate hooks.\\n"
+      "[cclaw] stage-complete: local Node runtime entrypoint is missing. Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
     );
     process.exitCode = 1;
     return;
@@ -213,7 +213,7 @@ async function main() {
     if (!stat.isFile()) throw new Error("not-file");
   } catch {
     process.stderr.write(
-      "[cclaw] stage-complete: local Node runtime entrypoint not found at " + cliEntrypoint + ". Re-run npx cclaw-cli sync or npx cclaw-cli upgrade to regenerate hooks.\\n"
+      "[cclaw] stage-complete: local Node runtime entrypoint not found at " + cliEntrypoint + ". Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
     );
     process.exitCode = 1;
     return;

package/dist/content/next-command.js

@@ -1,4 +1,5 @@
 import { RUNTIME_ROOT } from "../constants.js";
+import { nextStage as nextStageForTrack } from "../flow-state.js";
 import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
 import { stageSchema } from "./stage-schema.js";
 import { closeoutChainInline, closeoutNextCommandGuidance, closeoutSubstateInline, closeoutSubstateProtocolBullets } from "./closeout-guidance.js";
@@ -152,6 +153,15 @@ export function nextCommandSkillMarkdown() {
     const delegationPath = delegationLogPathLine();
     const reconciliationNoticesPath = reconciliationNoticesPathLine();
     const stageRows = ["brainstorm", "scope", "design", "spec", "plan", "tdd", "review", "ship"]
+        .map((stage) => {
+        const skillMd = `${RUNTIME_ROOT}/skills/${stageSkillFolder(stage)}/SKILL.md`;
+        const standardNext = nextStageForTrack(stage, "standard") ?? "(terminal)";
+        const mediumNext = nextStageForTrack(stage, "medium") ?? "not in track";
+        const quickNext = nextStageForTrack(stage, "quick") ?? "not in track";
+        return `| \`${stage}\` | \`${standardNext}\` | \`${mediumNext}\` | \`${quickNext}\` | \`${skillMd}\` |`;
+    })
+        .join("\n");
+    const naturalStageRows = ["brainstorm", "scope", "design", "spec", "plan", "tdd", "review", "ship"]
         .map((stage) => {
         const schema = stageSchema(stage);
         const next = schema.next === "done" ? "(terminal)" : schema.next;
@@ -258,12 +268,18 @@ Otherwise (non-terminal \`next\`): load the next stage skill and begin execution
 
 ## Stage order
 
-This table is the critical path. After \`ship\`, \`/cc-next\` continues closeout via ${closeoutSubstateInline()}: ${closeoutChainInline()}.
+This table is the track-aware critical path. It must match \`flow-state.json.track\`; do not follow the natural schema edge when the active track skips a stage. After \`ship\`, \`/cc-next\` continues closeout via ${closeoutSubstateInline()}: ${closeoutChainInline()}.
 
-| Stage | Next | Skill path |
-|---|---|---|
+| Stage | Standard next | Medium next | Quick next | Skill path |
+|---|---|---|---|---|
 ${stageRows}
 
+Natural schema edge reference for diagnostics only:
+
+| Stage | Natural next | Skill path |
+|---|---|---|
+${naturalStageRows}
+
 ## Anti-patterns
 
 - Advancing when \`blocked\` is non-empty for the current stage.

package/dist/content/review-loop.js

@@ -535,6 +535,33 @@ function normalizeStopReason(value) {
         return "user_opt_out";
     return null;
 }
+function parseScoreCell(value) {
+    const percent = /([0-9]*\.?[0-9]+)\s*%/u.exec(value)?.[1];
+    if (percent !== undefined) {
+        const score = Number(percent) / 100;
+        return Number.isFinite(score) ? clampScore(score) : null;
+    }
+    const direct = Number(value.trim());
+    if (Number.isFinite(direct)) {
+        return clampScore(direct > 1 ? direct / 100 : direct);
+    }
+    const embedded = /([0-9]*\.?[0-9]+)/u.exec(value)?.[1];
+    if (embedded === undefined)
+        return null;
+    const score = Number(embedded);
+    if (!Number.isFinite(score))
+        return null;
+    return clampScore(score > 1 ? score / 100 : score);
+}
+function parseFindingsCountCell(value) {
+    if (/\b(?:none|zero|clear|no findings?|0)\b/iu.test(value))
+        return 0;
+    const match = /(\d+)/u.exec(value);
+    if (!match)
+        return null;
+    const count = Number(match[1]);
+    return Number.isInteger(count) && count >= 0 ? count : null;
+}
 function parseIterationsTable(sectionBody) {
     const rows = [];
     const lines = sectionBody.split(/\r?\n/gu);
@@ -548,22 +575,22 @@ function parseIterationsTable(sectionBody) {
             .map((cell) => cell.trim());
         if (cells.length < 3)
             continue;
-        if (/iteration/iu.test(cells[0] ?? ""))
+        if (/^iteration$/iu.test(cells[0] ?? ""))
             continue;
         if (/^-+$/u.test((cells[0] ?? "").replace(/:/gu, "")))
             continue;
-        const iteration = Number(cells[0]);
-        const qualityScore = Number(cells[1]);
-        const findingsCount = Number(cells[2]);
+        const iteration = Number(/(\d+)/u.exec(cells[0] ?? "")?.[1] ?? "");
+        const qualityScore = parseScoreCell(cells[1] ?? "");
+        const findingsCount = parseFindingsCountCell(cells[2] ?? "");
         if (!Number.isInteger(iteration) || iteration < 1)
             continue;
-        if (!Number.isFinite(qualityScore))
+        if (qualityScore === null)
             continue;
-        if (!Number.isInteger(findingsCount) || findingsCount < 0)
+        if (findingsCount === null)
             continue;
         rows.push({
             iteration,
-            qualityScore: clampScore(qualityScore),
+            qualityScore,
             findingsCount
         });
     }
@@ -593,11 +620,11 @@ export function extractReviewLoopEnvelopeFromArtifact(markdown, stage, artifactP
     if (iterations.length === 0)
         return null;
     const stopReasonFromSection = normalizeStopReason(/-\s*Stop reason:\s*([a-z_]+)/iu.exec(sectionBody)?.[1]);
-    const targetFromSection = Number(/-\s*Target score:\s*([0-9]*\.?[0-9]+)/iu.exec(sectionBody)?.[1] ?? "");
+    const targetFromSection = parseScoreCell(/-\s*Target score:\s*([^\n]+)/iu.exec(sectionBody)?.[1] ?? "");
     const maxFromSection = Number(/-\s*Max iterations:\s*(\d+)/iu.exec(sectionBody)?.[1] ?? "");
     const header = parseHeaderMeta(markdown);
-    const targetScore = Number.isFinite(targetFromSection)
-        ? clampScore(targetFromSection)
+    const targetScore = targetFromSection !== null
+        ? targetFromSection
         : REVIEW_LOOP_DEFAULT_TARGET_SCORE;
     const maxIterationsCandidate = Number.isInteger(maxFromSection) && maxFromSection > 0
         ? maxFromSection

package/dist/content/skills.js

@@ -1,4 +1,5 @@
 import { RUNTIME_ROOT, STAGE_TO_SKILL_FOLDER } from "../constants.js";
+import { nextStage as nextStageForTrack } from "../flow-state.js";
 import { stageExamples } from "./examples.js";
 import { reviewStackAwareRoutes, reviewStackAwareRoutingSummary, stageAutoSubagentDispatch, stageSchema, stageTrackRenderContext } from "./stage-schema.js";
 import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
@@ -201,13 +202,15 @@ function mergedAntiPatterns(philosophy, execution) {
 }
 function completionParametersBlock(schema, track) {
     const gateList = schema.executionModel.requiredGates.map((g) => `\`${g.id}\``).join(", ");
+    const mandatoryAgents = schema.reviewLens.mandatoryDelegations;
     const mandatory = schema.reviewLens.mandatoryDelegations.length > 0
         ? schema.reviewLens.mandatoryDelegations.map((a) => `\`${a}\``).join(", ")
         : "none";
-    const nextStage = schema.next === "done" ? "done" : schema.next;
-    const nextDescription = schema.next === "done"
+    const resolvedNextStage = nextStageForTrack(schema.stage, track);
+    const nextStage = resolvedNextStage ?? "done";
+    const nextDescription = nextStage === "done"
         ? "flow complete"
-        : stageSchema(schema.next, track).skillDescription;
+        : stageSchema(nextStage, track).skillDescription;
     return `## Completion Parameters
 
 - \`stage\`: \`${schema.stage}\`
@@ -217,8 +220,9 @@ function completionParametersBlock(schema, track) {
 - \`mandatory delegations\`: ${mandatory}
 - \`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.
 - Fill \`## Learnings\` before closeout: either \`- None this stage.\` or JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (knowledge-schema compatible).
-- Record mandatory delegation completion/waiver in \`${RUNTIME_ROOT}/state/delegation-log.json\` with rationale as needed.
+- Record mandatory delegation completion/waiver in \`${RUNTIME_ROOT}/state/delegation-log.json\` with rationale as needed.${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.` : ""}
 - 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.
 `;

package/dist/content/stages/brainstorm.js

@@ -38,11 +38,12 @@ export const BRAINSTORM = {
         checklist: [
             "**Explore project context** — inspect existing files/docs/recent activity before asking what to build.",
             "**Classify depth and scope** — pick Lightweight / Standard / Deep; decompose independent subsystems before deeper work.",
-            "**Short-circuit concrete asks** — for unambiguous requests, write a compact brainstorm stub (context, problem, approved intent, constraints, assumptions) and ask for one explicit approval.",
+            "**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.",
+            "**Short-circuit concrete asks** — for unambiguous implementation-only requests, write a compact brainstorm stub (context, problem, approved intent, constraints, assumptions) and ask for one explicit approval.",
             "**Ask only decision-changing questions** — one at a time; if answers would not change approach, state the assumption and continue.",
             "**Compare 2-3 distinct approaches** — include real trade-offs, withhold recommendation, and include one higher-upside challenger.",
             "**Collect reaction before recommending** — ask which option feels closest and what concern remains, then recommend based on that reaction.",
-            "**Write and tighten the artifact** — scale sections to complexity, optionally add a compact diagram, then patch contradictions, weak trade-offs, placeholders, and ambiguity.",
+            "**Write and tighten the artifact** — scale sections to complexity, optionally add a compact diagram, then patch contradictions, weak trade-offs, placeholders, ambiguity, and weak handoff language.",
             "**Request explicit approval** — state exactly what direction is being approved; do not advance without approval and artifact review.",
             "**Handoff** — only after approval, complete the stage and point to `/cc-next`."
         ],
@@ -50,12 +51,13 @@ export const BRAINSTORM = {
             "Start from observed project context; if the idea is vague, first narrow the project type.",
             "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.",
             "If likely answers do not change architecture or scope boundaries, choose the default and state the assumption.",
+            "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.",
             "Show approaches before the recommendation; include a higher-upside challenger and gather reaction first.",
             "State exactly what is being approved, then **STOP** until the user explicitly approves the artifact."
         ],
         process: [
             "Explore project context and classify depth/scope.",
-            "Short-circuit concrete asks or ask one decision-changing question at a time.",
+            "Use compact discovery for simple apps, short-circuit implementation-only asks, or ask one decision-changing question at a time.",
             "Compare 2-3 distinct approaches, including a higher-upside challenger.",
             "Collect reaction, then recommend with rationale tied to that reaction.",
             "Optionally park promising non-selected ideas in `.cclaw/seeds/`.",
@@ -74,6 +76,7 @@ export const BRAINSTORM = {
             "2-3 approaches with trade-offs are recorded, including one higher-upside challenger option.",
             "User reaction to approaches is captured before final recommendation.",
             "Final recommendation explicitly reflects user reaction.",
+            "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)."
@@ -119,9 +122,9 @@ export const BRAINSTORM = {
             { section: "Clarifying Questions", required: false, validationRule: "Must capture question, answer, and decision impact for each clarifying question." },
             { section: "Approach Tier", required: true, validationRule: "Must classify depth as Lightweight/Standard/Deep and explain why." },
             { section: "Short-Circuit Decision", required: false, validationRule: "Must include Status/Why/Scope handoff lines when short-circuit is discussed; compact stubs are valid for concrete asks." },
-            { section: "Approaches", required: true, validationRule: "Must compare 2-3 architecturally distinct options with real trade-offs; include at least one table/bullet row containing both `challenger` and `higher-upside`." },
+            { section: "Approaches", required: true, validationRule: "Must compare 2-3 distinct options with real trade-offs; include one option marked as a challenger with explicit high/higher upside." },
             { 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, an explicit approval marker, and rationale tied to user reaction/feedback/concerns so the recommendation traces to the user response." },
+            { section: "Selected Direction", required: true, validationRule: "Must include the selected approach, an explicit approval marker, rationale traceable to the prior Approach Reaction, and a track-aware next-stage handoff." },
             { 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: "Assumptions and Open Questions", required: false, validationRule: "Must capture unresolved assumptions/open questions, or explicitly state none." }

package/dist/content/stages/design.js

@@ -40,6 +40,7 @@ export const DESIGN = {
     },
     executionModel: {
         checklist: [
+            "Compact design lock — for simple greenfield/product slices, produce a tight but complete design spine: codebase investigation, architecture boundary, one labeled diagram, data flow, failure/rescue table, test/perf expectations, and handoff. Do not run a sprawling workshop when a strong engineering lock fits on one page.",
             "Trivial-Change Escape Hatch — for <=3 files, no new interfaces, and no cross-module data flow, produce a mini-design (rationale, changed files, one risk) and proceed to spec.",
             "Tiered Research Fleet — run `research/research-fleet.md` before lock; record `.cclaw/artifacts/02a-research.md` and summarize concrete decisions in `## Research Fleet Synthesis`.",
             "Design Doc Check — read upstream artifacts and current design docs; latest superseding doc wins.",
@@ -52,7 +53,7 @@ export const DESIGN = {
             "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: [
-            "Review section-by-section: investigator first, critic second, then reconcile.",
+            "Review section-by-section: investigator first, critic second, then reconcile. For simple apps, collapse this into one compact design lock with explicit risks and a single approval stop.",
             "Present each issue one at a time; do not batch issues or move sections until current issues are resolved.",
             decisionProtocolInstruction("each issue", "describe concretely with file/line references, present labeled options (A/B/C) with trade-offs, effort estimate (S/M/L/XL), risk level (Low/Med/High), and mark one as (recommended)", "recommend the option that closes the issue with the smallest blast radius and clearest verification path"),
             "If a section has no issues, say 'No issues found' and move on.",
@@ -60,7 +61,7 @@ export const DESIGN = {
             "Take a firm position, push back on weak framing, and call out suboptimal architecture with concrete alternatives.",
             "Classify ambiguity before acting: ask, enumerate-and-pick, or propose a hypothesis with validation path.",
             "Before final approval, run the critic pass, reconcile material findings, and bound retries with the review-loop policy.",
-            "For baseline approval, present the full design and **STOP** until explicit approval.",
+            "For baseline approval, present the full design plus exact spec handoff and **STOP** until explicit approval.",
             "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be completed or explicitly waived, then close via `node .cclaw/hooks/stage-complete.mjs design`."
         ],
         process: [

package/dist/content/stages/scope.js

@@ -45,34 +45,35 @@ export const SCOPE = {
     },
     executionModel: {
         checklist: [
-            "**CEO pass first** — read brainstorm, name the job-to-be-done, challenge whether this is the right product slice, and propose the highest-leverage scope in one pass.",
-            "**Pick one of four gstack modes** — SCOPE EXPANSION, SELECTIVE EXPANSION, HOLD SCOPE, or SCOPE REDUCTION. State why and what user signal would change the mode.",
-            "**Draft the 10-star vs v1 boundary** — show what would make the product meaningfully better, then explicitly choose what ships now, what is deferred, and what is excluded.",
+            "**Compact CEO pass first** — read brainstorm, name the job-to-be-done, challenge whether this is the right product slice, and propose the highest-leverage scope in one pass. For simple apps, keep this to a tight scope contract instead of a full strategy workshop.",
+            "**Pick one of four gstack modes with the user** — SCOPE EXPANSION, SELECTIVE EXPANSION, HOLD SCOPE, or SCOPE REDUCTION. Recommend one, state why and what signal would change it, then STOP for the user's mode/scope approval before writing the final artifact.",
+            "**Draft the 10-star vs current-slice boundary** — show what would make the product meaningfully better, then explicitly choose what ships now, what is deferred, and what is excluded without using vague `later/for now` placeholders.",
             "**Premise and leverage check** — test right problem, direct path, no-action outcome, existing-code leverage, and reversibility before asking the user anything.",
             "**Compare implementation alternatives** — include minimum viable, product-grade, and ideal architecture options with effort/risk/reuse, then recommend one.",
-            "**Run outside voice before final approval** — always do at least a concise adversarial self-check for scope; for complex/high-risk/configured scope, iterate until threshold. Record the loop summary in `## Spec Review Loop` before asking approval.",
+            "**Run outside voice before final approval** — for simple/low-risk scope, record one concise adversarial self-check row; for complex/high-risk/configured scope, iterate until threshold. Record the loop summary in `## Spec Review Loop`, but do not treat it as user approval.",
             "**Ask only one decision-changing question** — if the user rejects the contract but is unsure, offer 3-4 concrete scope moves instead of open-ended interrogation.",
-            "**Write the scope contract** — include in-scope/out-of-scope, discretion areas, deferred items, locked decisions, error/rescue notes, completion dashboard, scope summary, and explicit approval."
+            "**Write the scope contract after approval** — include in-scope/out-of-scope, discretion areas, deferred items, locked decisions, error/rescue notes, completion dashboard, scope summary, next-stage handoff, and explicit approval evidence."
         ],
         interactionProtocol: [
             decisionProtocolInstruction("scope mode selection", "present expand/selective/hold/reduce as labeled options with trade-offs and mark one as (recommended)", "recommend the option that best covers the prime-directive failure modes, four data-flow paths, observability, and deferred handling for the in-scope set with the smallest blast radius. Base your recommendation on default heuristics: greenfield -> expand, enhancement -> selective, bugfix/hotfix/refactor -> hold, broad blast radius -> reduce"),
-            "Do not walk the full checklist by default. Lead with an opinionated scope contract and the one decision that matters most.",
+            "Do not walk the full checklist by default. Lead with a proposed scope contract and the one decision that matters most; label the mode as recommended, not selected, until the user answers.",
+            "For simple web-app flows, default to HOLD SCOPE or SELECTIVE EXPANSION, show the exact in/out/deferred contract as a proposal, and STOP for one explicit approval before writing the final scope artifact or completing the stage.",
             "Challenge premise first, take a firm position, and name one concrete condition that would change it.",
             "Push back on weak framing: vague scope needs a specific user/problem, platform vision needs a narrow wedge, social proof needs behavioral evidence.",
             "Resolve one structural scope issue at a time; otherwise state the assumption and move on.",
             "If the user says no but cannot name the change, offer concrete moves: keep scope, add one obvious adjacent capability, reduce to wedge, or re-open stack/product direction.",
             `Before final approval, record outside-voice findings and a \`## Spec Review Loop\` table using ${reviewLoopPolicySummary("scope")}`,
-            "**STOP.** Wait for explicit approval of the scope contract before advancing.",
-            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be completed or explicitly waived. Then close with `node .cclaw/hooks/stage-complete.mjs scope --passed=scope_mode_selected,scope_contract_written,scope_user_approved --evidence-json '{\"scope_mode_selected\":\"<mode + rationale>\",\"scope_contract_written\":\"<artifact path + sections>\"}'`. Do not include `scope_user_approved` manually; stage-complete auto-hydrates its review-loop envelope from `## Spec Review Loop`."
+            "**STOP.** Wait for explicit user approval of the scope mode and scope contract before writing final approval language or advancing.",
+            "**STOP BEFORE ADVANCE.** Mandatory delegation `planner` must be completed or explicitly waived. If no isolated planner is available, use `--waive-delegation=planner --waiver-reason=\"role-switch scope self-review completed\"`. Then close with `node .cclaw/hooks/stage-complete.mjs scope --passed=scope_mode_selected,scope_contract_written,scope_user_approved --evidence-json '{\"scope_mode_selected\":\"<user-approved mode + rationale>\",\"scope_contract_written\":\"<artifact path + sections>\",\"scope_user_approved\":\"<explicit user approval quote or summary>\"}'`. `scope_user_approved` must cite the user's approval; review-loop evidence alone is not approval."
         ],
         process: [
             "Run configured pre-scope audit only when enabled.",
-            "Run the gstack-style CEO scope pass: job-to-be-done, premise challenge, 10-star upside, smallest useful wedge, and what would change the recommendation.",
+            "Run the gstack-style CEO scope pass scaled to risk: job-to-be-done, premise challenge, 10-star upside, smallest useful wedge, and what would change the recommendation.",
             "Compare minimum viable, product-grade, and ideal architecture scope alternatives with explicit reuse/effort/risk.",
-            "Select scope mode with explicit rationale; ask for user opt-in only when changing or expanding scope.",
+            "Recommend a scope mode with explicit rationale, then ask for user opt-in before treating it as selected.",
             "Run outside voice / adversarial self-check before final approval and record a valid `## Spec Review Loop` table.",
             "Write explicit scope contract, discretion areas, deferred items, error/rescue registry, and D-XX locked decisions.",
-            "Produce scope summary and completion dashboard before asking final approval."
+            "Produce scope summary, completion dashboard, and exact next-stage handoff before asking final approval."
         ],
         requiredGates: [
             { id: "scope_mode_selected", description: "One scope mode was explicitly selected." },
@@ -88,11 +89,12 @@ export const SCOPE = {
             "Locked Decisions section lists stable D-XX IDs for non-negotiable boundaries.",
             "Premise challenge findings documented.",
             "Outside Voice findings and dispositions are recorded (accept/reject/defer with rationale) before final approval.",
-            `Spec review loop summary includes a table with columns Iteration, Quality Score, Findings, plus Stop reason, Target score, and Max iterations. stage-complete auto-hydrates scope_user_approved evidence from this section. ${reviewLoopPolicySummary("scope")}`,
+            `Spec review loop summary includes a table with columns Iteration, Quality Score, Findings, plus Stop reason, Target score, and Max iterations. This is outside-voice evidence only; it does not satisfy user approval. ${reviewLoopPolicySummary("scope")}`,
             reviewLoopSecondOpinionSummary("scope"),
             "Deferred items list with one-line rationale for each.",
             "When an upside deferred idea is parked, a seed file is created under `.cclaw/seeds/` and referenced in the artifact.",
-            "Completion dashboard lists per-section status, critical/open gaps, decision count, and unresolved items (or `None`)."
+            "Completion dashboard lists per-section status, critical/open gaps, decision count, and unresolved items (or `None`).",
+            "Scope Summary includes a next-stage handoff naming the track-aware successor (`design` for standard, `spec` for medium) and the decisions/artifacts it must carry forward."
         ],
         inputs: ["brainstorm artifact", "timeline constraints", "product priorities"],
         requiredContext: [
@@ -144,14 +146,14 @@ export const SCOPE = {
             { section: "Implementation Alternatives", required: false, validationRule: "2-3 options with Name, Summary, Effort, Risk, Pros, Cons, and Reuses. Must include minimal viable and ideal architecture options." },
             { section: "Scope Mode", required: true, validationRule: "Must state selected mode and rationale with default heuristic justification." },
             { section: "Mode-Specific Analysis", required: false, validationRule: "Deep/complex scope only: document the analysis matching the selected mode. Default path may record a concise mode rationale instead." },
-            { section: "In Scope / Out of Scope", required: true, validationRule: "Two separate explicit lists. Out-of-scope must not be empty." },
+            { section: "In Scope / Out of Scope", required: true, validationRule: "Two separate explicit lists. Canonical form is one `## In Scope / Out of Scope` section with `### In Scope` and `### Out of Scope`; legacy split `## In Scope` and `## Out of Scope` headings are accepted. Out-of-scope must not be empty." },
             { section: "Discretion Areas", required: false, validationRule: "Explicit list of implementer decision zones, or 'None' if scope is fully locked." },
             { section: "Deferred Items", required: false, validationRule: "Each item has one-line rationale. If empty, state 'None' explicitly." },
             { section: "Error & Rescue Registry", required: false, validationRule: "Each scoped capability has: failure mode, detection method, fallback decision." },
             { section: "Outside Voice Findings", required: false, validationRule: "Must list external/adversarial findings and disposition (accept/reject/defer) with rationale." },
             { section: "Spec Review Loop", required: false, validationRule: `Must record iterations, quality score per iteration, stop reason, and unresolved concerns. Enforce ${reviewLoopPolicySummary("scope")}` },
             { section: "Completion Dashboard", required: true, validationRule: "Lists per-review-section status, count of critical/open gaps, resolved decisions, and unresolved decisions (or 'None')." },
-            { section: "Scope Summary", required: true, validationRule: "Clean summary: mode, strongest challenges, recommended path, accepted scope, deferred, excluded." },
+            { section: "Scope Summary", required: true, validationRule: "Clean summary: mode, strongest challenges, recommended path, accepted scope, deferred, excluded, and track-aware next-stage handoff." },
             { section: "Dream State Mapping", required: false, validationRule: "If present (complex projects): CURRENT STATE, THIS PLAN, 12-MONTH IDEAL, and alignment verdict." },
             { section: "Temporal Interrogation", required: false, validationRule: "If present (complex projects): timeline simulation table with decision pressures and lock-now vs defer verdicts." }
         ]

package/dist/content/start-command.js

@@ -70,7 +70,7 @@ ${conversationLanguagePolicyMarkdown()}
    Skip detection quietly if no markers are found — do NOT invent a stack.
 
 5. Read \`${flowPath}\`.
-6. If flow already has completed stages, warn the user that starting a new tracked flow will reset progress. Ask for confirmation before proceeding.
+6. If flow already has completed stages, warn the user that starting a new tracked flow will reset progress. Ask for confirmation before proceeding. A fresh init placeholder state with \`completedStages: []\`, no passed gates, and no \`00-idea.md\` is **not** an active flow; do not ask the user to resume it.
 7. **Track heuristic** — classify the idea text and **recommend** a track (the user can override before any state mutation):
    - First, load \`${RUNTIME_ROOT}/config.yaml\`. If \`trackHeuristics\` is defined, apply those per-track vocabulary hints (\`fallback\`, \`tracks.<id>.{triggers,veto}\`) on top of the built-in defaults. Evaluation order is always \`standard -> medium -> quick\` (narrow-to-broad).
    - **quick** (\`spec → tdd → review → ship\`) — single-purpose work where the spec is essentially already known.
@@ -152,7 +152,7 @@ description: "Unified entry point for the cclaw flow. No args = resume/next. Wit
 
 ## HARD-GATE
 
-Do **not** silently discard an existing flow when the user provides a prompt. If completed stages exist, inform and confirm before resetting.
+Do **not** silently discard an existing flow when the user provides a prompt. If completed stages exist, inform and confirm before resetting. A freshly initialized placeholder state with \`completedStages: []\`, no passed gates, and no \`${RUNTIME_ROOT}/artifacts/00-idea.md\` is not an active flow; classify the prompt and start normally.
 
 ${conversationLanguagePolicyMarkdown()}
 ## Protocol
@@ -168,6 +168,7 @@ ${conversationLanguagePolicyMarkdown()}
    - Inform: "You have an active flow at stage **{currentStage}** with {N} completed stages. Starting a new tracked flow will reset progress."
    - Ask: "Continue with reset? (A) Yes, start fresh (B) No, resume current flow"
    - If (B) → switch to Path B behavior.
+   If \`completedStages\` is empty, all gate \`passed\` arrays are empty, and \`${RUNTIME_ROOT}/artifacts/00-idea.md\` is missing, treat it as a fresh init placeholder — do **not** ask whether to continue the current flow.
 7. **Classify the idea** using the heuristic below and present one compact Start framing summary (class, track, stack, origin docs, seed recalls, next action). Wait for explicit confirmation or override before mutating any state only when reset/conflict/ambiguity makes it necessary.
    - If \`${RUNTIME_ROOT}/config.yaml\` defines \`trackHeuristics\`, apply those vocabulary hints (\`fallback\`, \`tracks.<id>.{triggers,veto}\`) on top of built-in defaults. Evaluation order is fixed: \`standard -> medium -> quick\`. (Honest note: this is advisory prose; the LLM applies it, not a Node-level router.)
 

package/dist/content/templates.js

@@ -46,10 +46,10 @@ export const ARTIFACT_TEMPLATES = {
 - Scope handoff:
 
 ## Approaches
-| Approach | Role | Architecture | Trade-offs | Recommendation |
-|---|---|---|---|---|
-| A | baseline |  |  |  |
-| B | challenger: higher-upside |  |  |  |
+| Approach | Role | Upside | Architecture | Trade-offs | Recommendation |
+|---|---|---|---|---|---|
+| A | baseline | modest |  |  |  |
+| B | challenger | high |  |  |  |
 
 ## Approach Reaction
 - Closest option:
@@ -58,8 +58,9 @@ export const ARTIFACT_TEMPLATES = {
 
 ## Selected Direction
 - **Approach:**
-- **Rationale:** Based on user reaction/feedback/concerns, ...
+- **Rationale:** Trace this to the prior Approach Reaction.
 - **Approval:** pending
+- **Next-stage handoff:** On standard track, hand this to \`scope\`; on medium track, hand this directly to \`spec\` with explicit requirements/constraints.
 
 ${SEED_SHELF_SECTION}
 
@@ -126,18 +127,18 @@ ${SEED_SHELF_SECTION}
 | HOUR 6+ (polish/tests) |  |  |  |
 
 ## Scope Mode
-- [ ] expand
-- [ ] selective
-- [ ] hold
-- [ ] reduce
+- [ ] SCOPE EXPANSION — dream bigger; user explicitly opts into the larger product slice.
+- [ ] SELECTIVE EXPANSION — hold baseline scope and cherry-pick one high-leverage addition.
+- [ ] HOLD SCOPE — preserve the approved brainstorm direction with maximum rigor.
+- [ ] SCOPE REDUCTION — strip to the smallest useful wedge when risk/blast radius is too high.
 
 ## Mode-Specific Analysis
 - **Selected mode:**
 - **Analysis:**
-  - (EXPAND: 10x opportunities, delight features)
-  - (SELECTIVE: hold-scope baseline, cherry-picked expansions)
-  - (HOLD: minimum-change-set hardening)
-  - (REDUCE: ruthless cuts, follow-up split)
+  - (SCOPE EXPANSION: 10-star opportunities, delight features)
+  - (SELECTIVE EXPANSION: hold-scope baseline, cherry-picked expansions)
+  - (HOLD SCOPE: approved slice with maximum rigor)
+  - (SCOPE REDUCTION: ruthless cuts, follow-up split)
 
 ## Requirements (stable IDs)
 | ID | Requirement (observable outcome) | Priority | Source (origin doc / prompt line) |
@@ -187,6 +188,8 @@ ${SEED_SHELF_SECTION}
 |---|---|---|---|
 | 1 | 0.00 | 0 | continue/stop |
 - Stop reason:
+- Target score: 0.800
+- Max iterations: 3
 - Unresolved concerns:
 
 ## Completion Dashboard
@@ -199,6 +202,7 @@ ${SEED_SHELF_SECTION}
 - Accepted scope:
 - Deferred:
 - Explicitly excluded:
+- Next-stage handoff: identify whether the next stage is \`design\` (standard track) or \`spec\` (medium track), and list the exact artifacts/decisions it must carry forward.
 
 ## Learnings
 - None this stage.
@@ -384,6 +388,8 @@ ${MARKDOWN_CODE_FENCE}
 |---|---|---|---|
 | 1 | 0.00 | 0 | continue/stop |
 - Stop reason:
+- Target score: 0.800
+- Max iterations: 3
 - Unresolved concerns:
 
 ## NOT in scope

package/dist/internal/advance-stage.js

@@ -19,7 +19,6 @@ import { runTddLoopStatusCommand } from "./tdd-loop-status.js";
 import { runTddRedEvidenceCommand } from "./tdd-red-evidence.js";
 import { extractReviewLoopEnvelopeFromArtifact } from "../content/review-loop.js";
 const AUTO_REVIEW_LOOP_GATE_BY_STAGE = {
-    scope: "scope_user_approved",
     design: "design_architecture_locked"
 };
 function unique(values) {
@@ -163,6 +162,30 @@ function validateReviewLoopGateEvidence(stage, evidence) {
     }
     return null;
 }
+function validateUserApprovalEvidence(evidence) {
+    const normalized = evidence.trim();
+    if (normalized.length === 0) {
+        return "must cite explicit user approval.";
+    }
+    const reviewLoopEnvelope = (() => {
+        try {
+            return pickReviewLoopEnvelope(JSON.parse(normalized));
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (reviewLoopEnvelope) {
+        return "must cite explicit user approval; review-loop evidence is outside-voice evidence, not user approval.";
+    }
+    if (/\b(?:approved|approval|user approved|confirmed|accepted|yes|ok)\b/iu.test(normalized)) {
+        return null;
+    }
+    if (/\b(?:утвержд(?:аю|ено|ен|ена)|подтвержд(?:аю|ено|ен|ена)|соглас(?:ен|на|овано)|да|ок|принято)\b/iu.test(normalized)) {
+        return null;
+    }
+    return "must cite explicit user approval (for example `user approved the scope contract` or `пользователь утвердил scope`).";
+}
 // Per-gate validators keyed by `${stage}:${gateId}`. Returning a non-null
 // string surfaces the reason as an `advance-stage` failure so evidence is
 // guaranteed to carry the structural breadcrumbs downstream tooling
@@ -186,7 +209,7 @@ const GATE_EVIDENCE_VALIDATORS = {
         }
         return null;
     },
-    "scope:scope_user_approved": (evidence) => validateReviewLoopGateEvidence("scope", evidence),
+    "scope:scope_user_approved": (evidence) => validateUserApprovalEvidence(evidence),
     "design:design_architecture_locked": (evidence) => validateReviewLoopGateEvidence("design", evidence)
 };
 function validateGateEvidenceShape(stage, gateId, evidence) {
@@ -195,6 +218,11 @@ function validateGateEvidenceShape(stage, gateId, evidence) {
         return null;
     return validator(evidence.trim());
 }
+function reviewLoopArtifactFixHint(stage, gateId) {
+    if (AUTO_REVIEW_LOOP_GATE_BY_STAGE[stage] !== gateId)
+        return "";
+    return " Add a `## Spec Review Loop` table to the artifact with rows like `| 1 | 0.80 | 0 |` plus `- Stop reason: quality_threshold_met`, `- Target score: 0.80`, and `- Max iterations: 3`; then omit this gate from manual evidence so stage-complete can auto-hydrate it.";
+}
 function parseStringList(raw) {
     if (!Array.isArray(raw))
         return [];
@@ -395,9 +423,14 @@ function parseAdvanceStageArgs(tokens) {
     let waiveDelegations = [];
     let waiverReason;
     let quiet = false;
+    let json = false;
     for (let i = 0; i < flagTokens.length; i += 1) {
         const token = flagTokens[i];
         const nextToken = flagTokens[i + 1];
+        if (token === "--json") {
+            json = true;
+            continue;
+        }
         if (token === "--quiet") {
             quiet = true;
             continue;
@@ -461,7 +494,8 @@ function parseAdvanceStageArgs(tokens) {
         evidenceByGate: parseEvidenceByGate(evidenceJson),
         waiveDelegations: unique(waiveDelegations),
         waiverReason,
-        quiet
+        quiet,
+        json
     };
 }
 function parseVerifyFlowStateDiffArgs(tokens) {
@@ -771,7 +805,7 @@ async function runAdvanceStage(projectRoot, args, io) {
                 ? existing
                 : "";
         const issue = validateGateEvidenceShape(args.stage, gateId, effectiveEvidence);
-        return issue ? [`${gateId}: ${issue}`] : [];
+        return issue ? [`${gateId}: ${issue}${reviewLoopArtifactFixHint(args.stage, gateId)}`] : [];
     });
     if (malformedGateEvidence.length > 0) {
         io.stderr.write(`cclaw internal advance-stage: gate evidence format check failed: ${malformedGateEvidence.join(" | ")}.\n`);
@@ -802,9 +836,35 @@ async function runAdvanceStage(projectRoot, args, io) {
     };
     const validation = await buildValidationReport(projectRoot, candidateState);
     if (!validation.ok) {
+        if (args.json) {
+            io.stdout.write(`${JSON.stringify({
+                ok: false,
+                command: "advance-stage",
+                stage: args.stage,
+                kind: "validation-failed",
+                delegation: validation.delegation,
+                gates: validation.gates,
+                completedStages: validation.completedStages,
+                nextActions: [
+                    ...(validation.delegation.missing.length > 0
+                        ? [`Complete or waive mandatory delegation(s): ${validation.delegation.missing.join(", ")}.`]
+                        : []),
+                    ...(validation.delegation.missingEvidence.length > 0
+                        ? ["Add evidenceRefs for role-switch delegation completion or use an explicit waiver reason."]
+                        : []),
+                    ...(validation.gates.issues.length > 0
+                        ? ["Fix the artifact/gate issue shown in gates.issues, then rerun stage-complete."]
+                        : []),
+                    ...(validation.completedStages.issues.length > 0
+                        ? ["Repair previously completed stage gate closure before advancing."]
+                        : [])
+                ]
+            })}\n`);
+        }
         io.stderr.write(`cclaw internal advance-stage: validation failed for stage "${args.stage}".\n`);
         if (validation.delegation.missing.length > 0) {
             io.stderr.write(`- missing delegations: ${validation.delegation.missing.join(", ")}\n`);
+            io.stderr.write(`  next action: complete the delegation, or rerun with --waive-delegation=${validation.delegation.missing.join(",")} --waiver-reason="<why safe>".\n`);
         }
         if (validation.delegation.missingEvidence.length > 0) {
             io.stderr.write(`- role-switch evidence missing: ${validation.delegation.missingEvidence.join(", ")}\n`);

package/package.json

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