cclaw-cli 0.51.6 → 0.51.8

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);
 }
@@ -355,6 +364,30 @@ function getMarkdownTableRows(sectionBody) {
     }
     return rows;
 }
+function getApproachRows(sectionBody) {
+    const tableRows = getMarkdownTableRows(sectionBody).map((row) => row.join(" "));
+    const bulletRows = sectionBody
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter((line) => /^(?:[-*]|\d+\.)\s+\S/u.test(line));
+    return [...tableRows, ...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 +1364,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 +1377,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 +1439,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 +1453,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 +1487,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 +1647,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,37 +45,35 @@ export const SCOPE = {
     },
     executionModel: {
         checklist: [
-            "**Default path first** — read brainstorm, challenge premise, recommend one mode, draft 3-5 key in/out boundaries plus deferred items, then seek approval.",
-            "**Optional audits by trigger** — run the pre-scope system audit only when configured; use deep-mode prime directives, dream-state mapping, and temporal interrogation only for complex/high-risk scope.",
-            "**Premise and leverage check** — test whether this is the right problem, what happens if nothing changes, and what existing code can be reused.",
-            "**Calibrate ambition** — for EXPAND/SELECTIVE candidates, do a brief landscape scan and align the quality bar to 2-3 strong in-repo modules.",
-            "**Compare implementation alternatives** — give 2-3 distinct options with effort, risk, pros/cons, and explicit reuse; include minimal viable and ideal architecture options.",
-            "**Select scope mode explicitly** — present expand/selective/hold/reduce with a recommendation and default heuristic justification.",
-            "**Run mode-specific analysis** — expand, selective, hold, or reduce according to the selected mode; do not silently add or trim scope.",
-            "**Handle deferred upside** — optionally park high-upside deferred/out-of-scope ideas in `.cclaw/seeds/`.",
-            `**Outside voice when warranted** — run/reconcile the loop for complex/high-risk or configured scope; otherwise do a concise adversarial self-check. ${reviewLoopPolicySummary("scope")} ${reviewLoopSecondOpinionSummary("scope")}`,
-            "**Write the scope contract** — include in-scope/out-of-scope, discretion areas, deferred items, locked decisions, error/rescue notes, completion dashboard, and explicit approval."
+            "**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** — SCOPE EXPANSION, SELECTIVE EXPANSION, HOLD SCOPE, or SCOPE REDUCTION. State why and what user signal would change the mode.",
+            "**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** — 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` before asking 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, next-stage handoff, and explicit approval."
         ],
         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 the default scope contract; ask only when the answer changes in/out/deferred boundaries.",
+            "Do not walk the full checklist by default. Lead with an opinionated scope contract and the one decision that matters most.",
+            "For simple web-app flows, default to HOLD SCOPE or SELECTIVE EXPANSION, show the exact in/out/deferred contract, and ask for one approval.",
             "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.",
-            "After acceptance/rejection, commit fully and do not re-argue.",
-            `Before final approval, reconcile outside-voice findings when the loop runs and bound retries with ${reviewLoopPolicySummary("scope")}`,
+            "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 via `node .cclaw/hooks/stage-complete.mjs scope`."
+            "**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\":\"<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`."
         ],
         process: [
             "Run configured pre-scope audit only when enabled.",
-            "Challenge premise, check existing-code leverage, and calibrate ambition/quality bar.",
-            "Compare structured scope alternatives with minimum viable and ideal architecture options.",
-            "Select scope mode with explicit user approval.",
-            "Run the selected mode analysis and park high-upside deferred ideas when useful.",
-            `Use outside-voice review only when complex/high-risk or configured; otherwise run a short adversarial self-check. If loop runs, enforce ${reviewLoopPolicySummary("scope")}`,
-            "Write explicit scope contract, discretion areas, deferred items, and D-XX locked decisions.",
-            "Produce scope summary and completion dashboard."
+            "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.",
+            "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, completion dashboard, and exact next-stage handoff before asking final approval."
         ],
         requiredGates: [
             { id: "scope_mode_selected", description: "One scope mode was explicitly selected." },
@@ -90,12 +88,13 @@ export const SCOPE = {
             "Selected mode and rationale are documented.",
             "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).",
-            `Spec review loop summary includes iteration count and quality score trajectory per ${reviewLoopPolicySummary("scope")}`,
+            "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")}`,
             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: [
@@ -147,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/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

@@ -195,6 +195,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 [];
@@ -359,9 +364,15 @@ async function hydrateReviewLoopEvidenceFromArtifact(projectRoot, stage, track,
         return;
     if (!selectedGateIds.includes(gateId))
         return;
-    const existing = evidenceByGate[gateId];
-    if (typeof existing === "string" && existing.trim().length > 0)
+    const reviewStage = stage === "scope" || stage === "design" ? stage : null;
+    if (!reviewStage)
         return;
+    const existing = evidenceByGate[gateId];
+    if (typeof existing === "string" && existing.trim().length > 0) {
+        const existingIssue = validateGateEvidenceShape(stage, gateId, existing);
+        if (!existingIssue)
+            return;
+    }
     const resolved = await resolveArtifactPath(stage, {
         projectRoot,
         track,
@@ -374,9 +385,6 @@ async function hydrateReviewLoopEvidenceFromArtifact(projectRoot, stage, track,
     catch {
         return;
     }
-    const reviewStage = stage === "scope" || stage === "design" ? stage : null;
-    if (!reviewStage)
-        return;
     const envelope = extractReviewLoopEnvelopeFromArtifact(raw, reviewStage, resolved.relPath);
     if (!envelope)
         return;
@@ -392,9 +400,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;
@@ -458,7 +471,8 @@ function parseAdvanceStageArgs(tokens) {
         evidenceByGate: parseEvidenceByGate(evidenceJson),
         waiveDelegations: unique(waiveDelegations),
         waiverReason,
-        quiet
+        quiet,
+        json
     };
 }
 function parseVerifyFlowStateDiffArgs(tokens) {
@@ -768,7 +782,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`);
@@ -799,9 +813,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.6",
+  "version": "0.51.8",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {