cclaw-cli 6.1.0 → 6.2.0

package/README.md

@@ -68,7 +68,7 @@ Legacy `.cclaw/runs/` directories are only auto-removed when empty. If the direc
 
 That gives you:
 
-- **One path** from idea to ship, with `quick`, `medium`, and `standard` tracks.
+- **One path** from idea to ship, with one user-chosen discovery mode (`lean`, `guided`, `deep`) and internal `quick` / `medium` / `standard` tracks.
 - **Real gates** for evidence, tests, review, delegation, stale-stage recovery, and closeout.
 - **Subagents with accountability**: controller owns state, workers do bounded tasks, overseers validate, evidence lands in `delegation-log.json`.
 - **Recovery instead of confusion**: `npx cclaw-cli sync` tells you blockers and next fixes.
@@ -101,7 +101,7 @@ medium    brainstorm -> spec -> plan -> tdd -> review -> ship
 standard  brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship
 ```
 
-Track selection is **model-guided and advisory** during `/cc`. Runtime enforcement begins after state is written: subsequent `/cc` turns follow the selected track, required gates, delegation rules, stale-stage markers, and `closeout.shipSubstate`.
+At `/cc <idea>`, the user picks **one discovery mode** (`lean`, `guided`, `deep`) for upstream shaping. Track selection remains **model-guided and advisory** during start-up; runtime enforcement begins after state is written: subsequent `/cc` turns follow the selected internal track, persisted `discoveryMode`, required gates, delegation rules, stale-stage markers, and `closeout.shipSubstate`.
 
 ## When Blocked
 

package/dist/artifact-linter/brainstorm.js

@@ -20,7 +20,7 @@ export async function lintBrainstormStage(ctx) {
     });
     if (!brainstormShortCircuitActivated) {
         const skipQuestions = ctx.activeStageFlags.includes("--skip-questions");
-        const floor = evaluateQaLogFloor(qaLogBody, track, "brainstorm", { skipQuestions });
+        const floor = evaluateQaLogFloor(qaLogBody, track, "brainstorm", { discoveryMode: ctx.discoveryMode, skipQuestions });
         findings.push({
             section: "qa_log_unconverged",
             required: !floor.skipQuestionsAdvisory,
@@ -53,7 +53,7 @@ export async function lintBrainstormStage(ctx) {
         const ok = hasDecisionLine;
         findings.push({
             section: "Approach Tier Classification",
-            required: true,
+            required: false,
             rule: "Approach Tier must explicitly classify depth as one of `lite` (a.k.a. `Lightweight`), `Standard`, or `Deep`.",
             found: ok,
             details: ok
@@ -77,14 +77,14 @@ export async function lintBrainstormStage(ctx) {
         });
         findings.push({
             section: "Approaches Role/Upside Taxonomy",
-            required: true,
+            required: false,
             rule: "Approaches table must use canonical Role and Upside enum values.",
             found: approachesTaxonomy.roleUpsideOk,
             details: approachesTaxonomy.details
         });
         findings.push({
             section: "Challenger Alternative Enforcement",
-            required: true,
+            required: false,
             rule: "Approaches must include one challenger option with explicit high/higher upside.",
             found: approachesTaxonomy.challengerOk,
             details: approachesTaxonomy.details
@@ -96,7 +96,7 @@ export async function lintBrainstormStage(ctx) {
         const orderOk = reactionIndex >= 0 && reactionIndex < directionIndex;
         findings.push({
             section: "Approach Reaction Ordering",
-            required: true,
+            required: false,
             rule: "Approach Reaction must appear before Selected Direction (propose -> react -> recommend).",
             found: orderOk,
             details: orderOk
@@ -151,7 +151,7 @@ export async function lintBrainstormStage(ctx) {
         const hasStatus = statusValue.length > 0;
         findings.push({
             section: "Short-Circuit Status",
-            required: true,
+            required: false,
             rule: "Short-Circuit Decision must include a `Status:` line (`activated` or `bypassed`).",
             found: hasStatus,
             details: hasStatus
@@ -187,7 +187,7 @@ export async function lintBrainstormStage(ctx) {
         const selfReview = validateCalibratedSelfReview(selfReviewBody);
         findings.push({
             section: "Calibrated Self-Review Format",
-            required: true,
+            required: false,
             rule: "When Self-Review Notes are present, they must use the calibrated review prompt output shape.",
             found: selfReview.ok,
             details: selfReview.details
@@ -197,7 +197,7 @@ export async function lintBrainstormStage(ctx) {
     if (criticPredictions !== null) {
         findings.push({
             section: "critic.predictions_missing",
-            required: true,
+            required: false,
             rule: "[P2] critic.predictions_missing — pre-commitment predictions block missing or empty",
             found: criticPredictions.found,
             details: criticPredictions.details
@@ -227,7 +227,7 @@ export async function lintBrainstormStage(ctx) {
         const ok = tokenMatches.size === 1 && !isPlaceholder;
         findings.push({
             section: "Mode Block Token",
-            required: true,
+            required: false,
             rule: "Mode Block must declare exactly one mode token: STARTUP, BUILDER, ENGINEERING, OPS, or RESEARCH.",
             found: ok,
             details: ok
@@ -246,7 +246,7 @@ export async function lintBrainstormStage(ctx) {
         /^RECOMMENDATION:/imu.test(raw)) {
         findings.push({
             section: "Approach Detail Cards",
-            required: true,
+            required: false,
             rule: "Approach Detail Cards must include ≥2 `#### APPROACH <letter>` blocks each with Summary/Effort/Risk/Pros/Cons/Reuses.",
             found: cardCount >= 2,
             details: cardCount >= 2
@@ -257,7 +257,7 @@ export async function lintBrainstormStage(ctx) {
         const hasRecommendation = recommendationLine !== null && recommendationLine[1] !== undefined && recommendationLine[1].trim().length > 0;
         findings.push({
             section: "Approach Recommendation Marker",
-            required: true,
+            required: false,
             rule: "Approach Detail Cards must conclude with a single `RECOMMENDATION:` line citing the chosen letter and rationale.",
             found: hasRecommendation,
             details: hasRecommendation
@@ -272,7 +272,7 @@ export async function lintBrainstormStage(ctx) {
         const optedOut = /\bnot used\b|\bn\/a\b|\bnone\b/iu.test(outsideVoiceBody);
         findings.push({
             section: "Outside Voice Slot Shape",
-            required: true,
+            required: false,
             rule: "Outside Voice section must either declare opt-out (`not used`/`none`) or include `source:`, `prompt:`, `tension:`, `resolution:`.",
             found: optedOut || missing.length === 0,
             details: optedOut || missing.length === 0
@@ -337,7 +337,7 @@ export async function lintBrainstormStage(ctx) {
         const waveDriftAddressed = hasCarryForwardSection && hasCarryForwardContent && hasDriftAuditMarkers;
         findings.push({
             section: "wave.drift_unaddressed",
-            required: true,
+            required: false,
             rule: "[P1] wave.drift_unaddressed — when `.cclaw/wave-plans/` has >=2 entries, brainstorm must include `## Wave Carry-forward` with carry-forward and drift audit markers.",
             found: waveDriftAddressed,
             details: waveDriftAddressed

package/dist/artifact-linter/design.js

@@ -284,7 +284,7 @@ export async function lintDesignStage(ctx) {
     });
     {
         const skipQuestions = activeStageFlags.includes("--skip-questions");
-        const floor = evaluateQaLogFloor(qaLogBody, track, "design", { skipQuestions });
+        const floor = evaluateQaLogFloor(qaLogBody, track, "design", { discoveryMode: ctx.discoveryMode, skipQuestions });
         findings.push({
             section: "qa_log_unconverged",
             required: !floor.skipQuestionsAdvisory,
@@ -297,7 +297,7 @@ export async function lintDesignStage(ctx) {
     if (criticPredictions !== null) {
         findings.push({
             section: "critic.predictions_missing",
-            required: true,
+            required: false,
             rule: "[P2] critic.predictions_missing — pre-commitment predictions block missing or empty",
             found: criticPredictions.found,
             details: criticPredictions.details
@@ -390,7 +390,7 @@ export async function lintDesignStage(ctx) {
         const ack = markdownFieldRegex("Iron rule acknowledged", "yes|true|y").test(regressionBody);
         findings.push({
             section: "Regression Iron Rule Acknowledgement",
-            required: true,
+            required: false,
             rule: "Regression Iron Rule section must affirm `Iron rule acknowledged: yes`.",
             found: ack,
             details: ack
@@ -409,7 +409,7 @@ export async function lintDesignStage(ctx) {
         const ok = isEmpty || validRows.length >= 1;
         findings.push({
             section: "Calibrated Finding Format",
-            required: true,
+            required: false,
             rule: "Calibrated Findings must either declare `None this stage` or contain at least one finding in the form `[P1|P2|P3] (confidence: <n>/10) <path>[:<line>] — <description>`.",
             found: ok,
             details: isEmpty
@@ -423,7 +423,7 @@ export async function lintDesignStage(ctx) {
     if (layeredDocumentReview !== null) {
         findings.push({
             section: "Document Reviewer Structured Findings",
-            required: true,
+            required: false,
             rule: "When Layered review references coherence-reviewer/scope-guardian-reviewer/feasibility-reviewer, include explicit reviewer status plus calibrated finding lines.",
             found: layeredDocumentReview.missingStructured.length === 0,
             details: layeredDocumentReview.missingStructured.length === 0

package/dist/artifact-linter/scope.js

@@ -23,7 +23,7 @@ export async function lintScopeStage(ctx) {
     });
     {
         const skipQuestions = activeStageFlags.includes("--skip-questions");
-        const floor = evaluateQaLogFloor(qaLogBody, track, "scope", { skipQuestions });
+        const floor = evaluateQaLogFloor(qaLogBody, track, "scope", { discoveryMode: ctx.discoveryMode, skipQuestions });
         findings.push({
             section: "qa_log_unconverged",
             required: !floor.skipQuestionsAdvisory,
@@ -94,7 +94,7 @@ export async function lintScopeStage(ctx) {
     if (criticPredictions !== null) {
         findings.push({
             section: "critic.predictions_missing",
-            required: true,
+            required: false,
             rule: "[P2] critic.predictions_missing — pre-commitment predictions block missing or empty",
             found: criticPredictions.found,
             details: criticPredictions.details
@@ -139,7 +139,7 @@ export async function lintScopeStage(ctx) {
         }
         findings.push({
             section: "Locked Decisions ID Integrity",
-            required: true,
+            required: false,
             rule: "Locked Decisions section must list each decision with a unique stable D-XX ID. (D-XX IDs replaced the legacy LD#<sha8> hash anchors in Wave 22.)",
             found: issues.length === 0,
             details: issues.length === 0

package/dist/artifact-linter/shared.d.ts

@@ -1,4 +1,4 @@
-import { type FlowStage, type FlowTrack } from "../types.js";
+import { type DiscoveryMode, type FlowStage, type FlowTrack } from "../types.js";
 /**
  * Stages that run adaptive elicitation. The `qa_log_unconverged` rule
  * only fires for these. Other stages may still record a Q&A Log but no
@@ -20,6 +20,7 @@ export interface ForcingQuestionTopic {
     topic: string;
 }
 export interface QaLogFloorOptions {
+    discoveryMode?: DiscoveryMode;
     /**
      * When true, downgrades the finding to advisory (`required: false`).
      * Set when `--skip-questions` was persisted to the active stage flags.
@@ -97,25 +98,22 @@ export declare function extractForcingQuestions(stage: FlowStage): ForcingQuesti
  * design artifact. Returns ok=true when convergence is reached or any
  * escape hatch fires.
  *
- * Convergence sources (any one is sufficient):
- * - All forcing-question topics from the stage checklist appear addressed
- *   in `## Q&A Log` (substring keyword match in question/answer columns).
- * - The Ralph-Loop convergence detector reports the last 2 substantive
- *   rows have decision_impact marking `skip`/`continue`/`no-change`/`done`
- *   (i.e. the dialogue is no longer producing decision-changing rows).
- * - Q&A Log contains a stop-signal row (existing
- *   `QA_LOG_STOP_SIGNAL_PATTERNS` keep working).
- * - `--skip-questions` flag was persisted to the active stage flags
- *   (`options.skipQuestions=true`); finding downgrades to advisory.
- * - The stage checklist exposes no forcing-questions row (e.g. simple
- *   refactor) AND the artifact has at least one substantive row — treat
- *   as converged because there is nothing left to force.
+ * Convergence sources (any one can set ok=true — see also
+ * `adaptiveElicitationSkillMarkdown`):
+ * - Every forcing-question topic id from the stage checklist is tagged
+ *   `[topic:<id>]` on at least one `## Q&A Log` row.
+ * - Ralph-Loop path: last 2 substantive rows read as no-new-decisions,
+ *   substantive count ≥ max(2, questionBudgetHint(discoveryMode, stage).min),
+ *   and not (guided/deep discovery with pending forcing-topic ids).
+ * - Stop-signal row (`QA_LOG_STOP_SIGNAL_PATTERNS`).
+ * - `--skip-questions` (`options.skipQuestions`): ok remains false but
+ *   `skipQuestionsAdvisory` is true (linter treats as non-blocking).
+ * - No forcing-questions row in the checklist and ≥1 substantive row.
  *
- * Wave 23 (v5.0.0) replaces the count-based `qa_log_below_min` rule with
- * `qa_log_unconverged`. The fixed count constant (10 for standard) and
- * the `CCLAW_ELICITATION_FLOOR=advisory` env override were removed. The
- * `min` and `liteShortCircuit` fields on the result are retained for
- * harness UI compatibility but are always 0/false.
+ * Wave 23 retired the fixed English-only count floor; Wave 24 made
+ * `[topic:<id>]` mandatory for topic coverage. The `min` and
+ * `liteShortCircuit` fields stay for harness compatibility (min is always 0;
+ * liteShortCircuit false).
  */
 export declare function evaluateQaLogFloor(qaLogBody: string | null, track: FlowTrack, stage: FlowStage, options?: QaLogFloorOptions): QaLogFloorResult;
 export interface LintFinding {
@@ -448,6 +446,7 @@ export interface StageLintContext {
     projectRoot: string;
     stage: FlowStage;
     track: FlowTrack;
+    discoveryMode: DiscoveryMode;
     raw: string;
     absFile: string;
     sections: H2SectionMap;

package/dist/artifact-linter/shared.js

@@ -207,25 +207,22 @@ function lastTwoRowsAllNoDecision(substantiveRows) {
  * design artifact. Returns ok=true when convergence is reached or any
  * escape hatch fires.
  *
- * Convergence sources (any one is sufficient):
- * - All forcing-question topics from the stage checklist appear addressed
- *   in `## Q&A Log` (substring keyword match in question/answer columns).
- * - The Ralph-Loop convergence detector reports the last 2 substantive
- *   rows have decision_impact marking `skip`/`continue`/`no-change`/`done`
- *   (i.e. the dialogue is no longer producing decision-changing rows).
- * - Q&A Log contains a stop-signal row (existing
- *   `QA_LOG_STOP_SIGNAL_PATTERNS` keep working).
- * - `--skip-questions` flag was persisted to the active stage flags
- *   (`options.skipQuestions=true`); finding downgrades to advisory.
- * - The stage checklist exposes no forcing-questions row (e.g. simple
- *   refactor) AND the artifact has at least one substantive row — treat
- *   as converged because there is nothing left to force.
+ * Convergence sources (any one can set ok=true — see also
+ * `adaptiveElicitationSkillMarkdown`):
+ * - Every forcing-question topic id from the stage checklist is tagged
+ *   `[topic:<id>]` on at least one `## Q&A Log` row.
+ * - Ralph-Loop path: last 2 substantive rows read as no-new-decisions,
+ *   substantive count ≥ max(2, questionBudgetHint(discoveryMode, stage).min),
+ *   and not (guided/deep discovery with pending forcing-topic ids).
+ * - Stop-signal row (`QA_LOG_STOP_SIGNAL_PATTERNS`).
+ * - `--skip-questions` (`options.skipQuestions`): ok remains false but
+ *   `skipQuestionsAdvisory` is true (linter treats as non-blocking).
+ * - No forcing-questions row in the checklist and ≥1 substantive row.
  *
- * Wave 23 (v5.0.0) replaces the count-based `qa_log_below_min` rule with
- * `qa_log_unconverged`. The fixed count constant (10 for standard) and
- * the `CCLAW_ELICITATION_FLOOR=advisory` env override were removed. The
- * `min` and `liteShortCircuit` fields on the result are retained for
- * harness UI compatibility but are always 0/false.
+ * Wave 23 retired the fixed English-only count floor; Wave 24 made
+ * `[topic:<id>]` mandatory for topic coverage. The `min` and
+ * `liteShortCircuit` fields stay for harness compatibility (min is always 0;
+ * liteShortCircuit false).
  */
 export function evaluateQaLogFloor(qaLogBody, track, stage, options = {}) {
     const rows = qaLogBody !== null ? getMarkdownTableRows(qaLogBody) : [];
@@ -233,6 +230,7 @@ export function evaluateQaLogFloor(qaLogBody, track, stage, options = {}) {
     const count = substantiveRows.length;
     const hasStopSignal = detectStopSignal(rows);
     const skipQuestionsAdvisory = options.skipQuestions === true;
+    const discoveryMode = options.discoveryMode ?? (track === "quick" ? "lean" : "guided");
     const forcingTopics = (options.forcingQuestions ?? extractForcingQuestions(stage)).map((entry) => (typeof entry === "string" ? { id: entry, topic: entry } : entry));
     const forcingCovered = [];
     const forcingPending = [];
@@ -242,9 +240,13 @@ export function evaluateQaLogFloor(qaLogBody, track, stage, options = {}) {
         else
             forcingPending.push(topic.id);
     }
+    const budget = questionBudgetHint(discoveryMode, stage);
     const noNewDecisions = lastTwoRowsAllNoDecision(substantiveRows);
     const allForcingCovered = forcingTopics.length > 0 ? forcingPending.length === 0 : count >= 1;
-    const ok = allForcingCovered || noNewDecisions || hasStopSignal;
+    const minimumRowsReached = count >= Math.max(2, budget.min);
+    const riskEscalationNeeded = forcingPending.length > 0 && /^(guided|deep)$/u.test(discoveryMode);
+    const noNewDecisionConverged = noNewDecisions && minimumRowsReached && !riskEscalationNeeded;
+    const ok = allForcingCovered || noNewDecisionConverged || hasStopSignal;
     const pendingIdsBracket = forcingPending.length > 0
         ? `[${forcingPending.join(", ")}]`
         : "[none]";
@@ -256,10 +258,10 @@ export function evaluateQaLogFloor(qaLogBody, track, stage, options = {}) {
         else if (allForcingCovered) {
             details = `Q&A Log converged: stage exposes no forcing-questions row and ${count} substantive entry recorded.`;
         }
-        else if (noNewDecisions) {
+        else if (noNewDecisionConverged) {
             const remaining = forcingPending.length > 0
-                ? ` ${forcingPending.length} forcing topic IDs still pending: ${pendingIdsBracket} (Ralph-Loop convergence overrode coverage).`
-                : " Ralph-Loop convergence detector says no new decision-changing rows in the last 2 turns.";
+                ? ` ${forcingPending.length} forcing topic IDs still pending: ${pendingIdsBracket} after the minimum ${budget.min}-row discovery pass.`
+                : ` Ralph-Loop convergence detector says no new decision-changing rows in the last 2 turns after the minimum ${budget.min}-row discovery pass.`;
             details = `Q&A Log converged via no-new-decisions detector at ${count} row(s).${remaining}`;
         }
         else {
@@ -269,27 +271,28 @@ export function evaluateQaLogFloor(qaLogBody, track, stage, options = {}) {
     else if (skipQuestionsAdvisory) {
         details = `Q&A Log unconverged at ${count} row(s); --skip-questions flag downgraded the finding to advisory. Forcing topic IDs pending: ${pendingIdsBracket}.`;
     }
+    else if (noNewDecisions && !minimumRowsReached) {
+        details = `Q&A Log still below the minimum ${budget.min}-row ${discoveryMode} discovery pass (${count} substantive row(s)). Forcing topic IDs pending: ${pendingIdsBracket}. Continue asking decision-changing questions before drafting.`;
+    }
+    else if (riskEscalationNeeded && noNewDecisions) {
+        details = `Q&A Log cannot converge via Ralph-Loop yet because ${discoveryMode} mode keeps pending forcing topic IDs blocking: ${pendingIdsBracket}. Cover the remaining topics or record an explicit stop-signal row.`;
+    }
     else {
-        details = `Q&A Log unconverged at ${count} row(s). Forcing topic IDs pending: ${pendingIdsBracket}. Tag each Q&A row with \`[topic:<id>]\` to mark coverage, append a no-new-decisions pair, or record an explicit user stop-signal row.`;
+        details = `Q&A Log unconverged at ${count} row(s). Forcing topic IDs pending: ${pendingIdsBracket}. Tag each Q&A row with \`[topic:<id>]\` to mark coverage, complete the minimum ${budget.min}-row ${discoveryMode} discovery pass, or record an explicit user stop-signal row.`;
     }
-    // Surface advisory budget hint for harness UI without re-introducing a
-    // blocking count. `recommended` is the soft budget per track/stage.
-    const advisoryBudget = questionBudgetHint(track, stage).recommended;
+    const advisoryBudget = budget.recommended;
     return {
         ok,
         count,
-        // Wave 23: floor no longer enforces a count. Surfacing 0 keeps the
-        // QaLogFloorSignal shape stable for harness consumers; harness UIs
-        // may show `recommended` from `questionBudgetHint` separately.
         min: 0,
         hasStopSignal,
         liteShortCircuit: false,
         skipQuestionsAdvisory,
         forcingCovered,
         forcingPending,
-        noNewDecisions,
+        noNewDecisions: noNewDecisionConverged,
         details: advisoryBudget > 0
-            ? `${details} (advisory budget for ${track}/${stage}: ~${advisoryBudget} Q&A turns)`
+            ? `${details} (advisory budget for ${discoveryMode}/${stage}: ~${advisoryBudget} Q&A turns)`
             : details
     };
 }

package/dist/artifact-linter.js

@@ -114,6 +114,7 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
     // Same flow-state read powers the post-loop demotion + audit log
     // below; we cache the result here to avoid two disk reads.
     let activeStageFlags = [];
+    let discoveryMode = "guided";
     let taskClass = null;
     let activeRunId = null;
     try {
@@ -121,11 +122,13 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
         const hint = flowState.interactionHints?.[stage];
         if (hint?.skipQuestions === true)
             activeStageFlags.push("--skip-questions");
+        discoveryMode = flowState.discoveryMode ?? "guided";
         taskClass = flowState.taskClass ?? null;
         activeRunId = flowState.activeRunId ?? null;
     }
     catch {
         activeStageFlags = [];
+        discoveryMode = "guided";
         taskClass = null;
         activeRunId = null;
     }
@@ -195,6 +198,7 @@ export async function lintArtifact(projectRoot, stage, track = "standard", optio
         projectRoot,
         stage,
         track,
+        discoveryMode,
         raw,
         absFile,
         sections,

package/dist/content/hooks.js

@@ -185,13 +185,13 @@ void main();
 `;
 }
 export function startFlowScript() {
-    return internalHelperScript("start-flow", "start-flow", "Usage: node " + RUNTIME_ROOT + "/hooks/start-flow.mjs --track=<standard|medium|quick> [--class=...] [--prompt=...] [--stack=...] [--reason=...] [--reclassify] [--force-reset]", { defaultQuietEnvVar: "CCLAW_START_FLOW_QUIET" });
+    return internalHelperScript("start-flow", "start-flow", "Usage: node " + RUNTIME_ROOT + "/hooks/start-flow.mjs --track=<standard|medium|quick> [--discovery-mode=<lean|guided|deep>] [--class=...] [--prompt=...] [--stack=...] [--reason=...] [--reclassify] [--force-reset]", { defaultQuietEnvVar: "CCLAW_START_FLOW_QUIET" });
 }
 export function cancelRunScript() {
     return internalHelperScript("cancel-run", "cancel-run", "Usage: node " + RUNTIME_ROOT + "/hooks/cancel-run.mjs --reason=<text> [--disposition=<cancelled|abandoned>] [--name=<slug>]");
 }
 export function stageCompleteScript() {
-    return internalHelperScript("stage-complete", "advance-stage", "Usage: node " + RUNTIME_ROOT + "/hooks/stage-complete.mjs <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...] [--accept-proactive-waiver] [--accept-proactive-waiver-reason=...] [--skip-questions] [--json]", {
+    return internalHelperScript("stage-complete", "advance-stage", "Usage: node " + RUNTIME_ROOT + "/hooks/stage-complete.mjs <stage> [--passed=...] [--evidence-json=...] [--waive-delegation=...] [--waiver-reason=...] [--skip-questions] [--json]", {
         positionalArgName: "stage",
         positionalArgRequired: true,
         defaultQuietEnvVar: "CCLAW_STAGE_COMPLETE_QUIET"

package/dist/content/skills-elicitation.js

@@ -1,16 +1,15 @@
 import { RUNTIME_ROOT } from "../constants.js";
 import { questionBudgetHint } from "../track-heuristics.js";
-import { FLOW_TRACKS } from "../types.js";
 const ELICITATION_STAGES = ["brainstorm", "scope", "design"];
 function renderQuestionBudgetHintTable() {
     const rows = [];
-    for (const track of FLOW_TRACKS) {
+    for (const mode of ["lean", "guided", "deep"]) {
         for (const stage of ELICITATION_STAGES) {
-            const hint = questionBudgetHint(track, stage);
-            rows.push(`| \`${track}\` | \`${stage}\` | ${hint.min} | ${hint.recommended} | ${hint.hardCapWarning} |`);
+            const hint = questionBudgetHint(mode, stage);
+            rows.push(`| \`${mode}\` | \`${stage}\` | ${hint.min} | ${hint.recommended} | ${hint.hardCapWarning} |`);
         }
     }
-    return `| Track | Stage | Min | Recommended | Hard cap warning |
+    return `| Discovery mode | Stage | Min | Recommended | Hard cap warning |
 |---|---|---|---|---|
 ${rows.join("\n")}`;
 }
@@ -47,7 +46,7 @@ These behaviors are the exact reason this skill exists. The linter will block yo
 - Ask exactly one question per turn and wait for the answer before asking the next one.
 - Use harness-native question tools first; prose fallback is allowed only when the tool is unavailable.
 - Keep a running Q&A trace in the active artifact under \`## Q&A Log\` in \`${RUNTIME_ROOT}/artifacts/\` as append-only rows.
-- **Convergence floor**: do NOT advance the stage (do NOT call \`stage-complete.mjs\`) until Q&A converges. Convergence is reached when ANY of: (a) every forcing-question topic id is tagged \`[topic:<id>]\` on at least one \`## Q&A Log\` row, (b) the last 2 substantive rows produce no decision-changing impact (\`skip\`/\`continue\`/\`no-change\`/\`done\`), or (c) an explicit user stop-signal row is recorded. The linter rule \`qa_log_unconverged\` enforces this; \`stage-complete\` will fail otherwise. Wave 24 (v6.0.0) made the topic tag MANDATORY (no English keyword fallback) so the gate works in any natural language.
+- **Convergence floor**: do NOT advance the stage (do NOT call \`stage-complete.mjs\`) until Q&A converges. The machine contract matches \`evaluateQaLogFloor\` in \`src/artifact-linter/shared.ts\` (rule \`qa_log_unconverged\`). Pass when ANY holds: (a) every forcing-question topic id is tagged \`[topic:<id>]\` on at least one \`## Q&A Log\` row; (b) the Ralph-Loop detector fires (last 2 substantive rows are non-decision-changing: \`skip\`/\`continue\`/\`no-change\`/\`done\`/etc.) **and** the log has at least \`max(2, questionBudgetHint(discoveryMode, stage).min)\` substantive rows — **unless** \`discoveryMode\` is \`guided\` or \`deep\` with pending forcing-topic ids (then Ralph-Loop alone cannot pass until topics are tagged, a stop-signal is recorded, or \`--skip-questions\` downgrades the finding to advisory); (c) an explicit user stop-signal row; or (d) \`--skip-questions\` was persisted (unconverged is advisory only). Wave 24 (v6.0.0) made \`[topic:<id>]\` mandatory (no English keyword fallback).
 - **NEVER run shell hash commands** (\`shasum\`, \`sha256sum\`, \`md5sum\`, \`Get-FileHash\`, \`certutil\`, etc.) to compute artifact hashes. If a linter ever asks you for a hash, that is a linter bug — report failure and stop, do not auto-fix in bash.
 - **NEVER paste cclaw command lines into chat** (e.g. \`node .cclaw/hooks/stage-complete.mjs ... --evidence-json '{...}'\`). Run them via the tool layer; report only the resulting summary. The user does not run cclaw manually and seeing the command line is noise.
 
@@ -103,23 +102,13 @@ Each grill question follows the same Core Protocol: ask one, wait, log, self-eva
 
 Do not ask extra questions "for theater" on simple low-risk work.
 
-## Question Budget Hint (advisory only — Wave 23 dropped the count floor)
+## Question Budget Hint (\`questionBudgetHint\` — min rows feed the convergence floor)
 
-Source of truth: \`questionBudgetHint(track, stage)\`. The numbers below are
-**soft hints** for harness UI and elicitation pacing; gate blocking is done
-by the \`qa_log_unconverged\` rule (Ralph-Loop convergence detector), NOT by
-a fixed count.
+Source of truth: \`questionBudgetHint(discoveryMode, stage)\`. The \`Min\` column is **not advisory** for the Ralph-Loop exit: \`evaluateQaLogFloor\` requires at least \`max(2, Min)\` substantive rows before the no-new-decisions path can converge (other exits — full topic coverage, stop-signal, \`--skip-questions\` advisory — ignore that minimum). \`Recommended\` and \`Hard cap warning\` remain pacing hints for the harness.
 
 ${budgetTable}
 
-Track mapping note: \`quick\` ~= lightweight, \`medium\` ~= standard, \`standard\` ~= deep.
-
-How to use the columns:
-- \`Min\` — soft minimum to surface forcing questions; not a blocking gate.
-- \`Recommended\` — target for normal flows.
-- \`Hard cap warning\` — point at which to stop or compress remaining forcing questions into one final batched ask. Not skip.
-
-## Stage Forcing Questions (walk in order, one per turn)
+Default mapping note: \`lean\` maps to a lightweight specialist tier on early stages, \`guided\` to standard, \`deep\` to deep; risk signals can escalate further.
 
 **Walk the forcing questions list one-by-one in order, asking each as a separate turn.** Do NOT batch. Do NOT pick favorites — go in order. For each question record one of:
 - \`asked\` — question was asked and answered.

package/dist/content/stage-schema.d.ts

@@ -1,4 +1,4 @@
-import type { FlowStage, FlowTrack, TransitionRule } from "../types.js";
+import type { DiscoveryMode, FlowStage, FlowTrack, TransitionRule } from "../types.js";
 import type { StageComplexityTier, StageAutoSubagentDispatch, StageSchema } from "./stages/schema-types.js";
 export type { ArtifactValidation, CrossStageTrace, ReviewSection, StageComplexityTier, StageExecutionModel, StagePhilosophy, StageArtifactRules, StageReviewLoop, StageReviewLens, StageAutoSubagentDispatch, StageGate, StageSchemaLegacyInput, StageSchema, StageSchemaInput, StageSchemaV2Input } from "./stages/schema-types.js";
 export declare const SKILL_ENVELOPE_KINDS: readonly ["stage-output", "gate-result", "delegation-record"];
@@ -83,7 +83,7 @@ export declare function mandatoryDelegationsForStage(stage: FlowStage, complexit
  * boundary.
  */
 export type MandatoryDelegationTaskClass = "software-standard" | "software-trivial" | "software-bugfix";
-export declare function mandatoryAgentsFor(stage: FlowStage, track: FlowTrack, taskClass?: MandatoryDelegationTaskClass | null, complexityTier?: StageComplexityTier): string[];
+export declare function mandatoryAgentsFor(stage: FlowStage, track: FlowTrack, taskClass?: MandatoryDelegationTaskClass | null, complexityTier?: StageComplexityTier, discoveryMode?: DiscoveryMode): string[];
 /**
  * Wave 25 (v6.1.0) — track-aware artifact validation demotion.
  *
@@ -107,7 +107,7 @@ export declare function mandatoryAgentsFor(stage: FlowStage, track: FlowTrack, t
  * `delegation-events.jsonl` once per stage advance for traceability.
  */
 export declare function shouldDemoteArtifactValidationByTrack(track: FlowTrack, taskClass?: MandatoryDelegationTaskClass | null): boolean;
-export declare function stageSchema(stage: FlowStage, track?: FlowTrack): StageSchema;
+export declare function stageSchema(stage: FlowStage, track?: FlowTrack, discoveryMode?: DiscoveryMode, taskClass?: MandatoryDelegationTaskClass | null): StageSchema;
 export declare function orderedStageSchemas(track?: FlowTrack): StageSchema[];
 export declare function stageGateIds(stage: FlowStage, track?: FlowTrack): string[];
 export declare function stageRecommendedGateIds(stage: FlowStage, track?: FlowTrack): string[];

package/dist/content/stage-schema.js

@@ -81,6 +81,20 @@ function dedupeAgentsInOrder(agents) {
     }
     return out;
 }
+function discoveryModeTier(mode) {
+    if (mode === "lean")
+        return "lightweight";
+    if (mode === "deep")
+        return "deep";
+    return "standard";
+}
+function resolvedStageComplexityTier(params) {
+    const base = params.defaultTier ?? "standard";
+    const earlyStage = params.stage === "brainstorm" || params.stage === "scope" || params.stage === "design";
+    if (!earlyStage || params.discoveryMode === undefined)
+        return base;
+    return discoveryModeTier(params.discoveryMode);
+}
 function defaultReturnSchemaForAgent(agent) {
     switch (agent) {
         case "researcher":
@@ -811,12 +825,17 @@ export function mandatoryDelegationsForStage(stage, complexityTier = "standard")
         .find((row) => row.stage === stage);
     return summary ? summary.mandatoryAgents : [];
 }
-export function mandatoryAgentsFor(stage, track, taskClass, complexityTier = "standard") {
+export function mandatoryAgentsFor(stage, track, taskClass, complexityTier = "standard", discoveryMode) {
     if (track === "quick")
         return [];
     if (taskClass === "software-bugfix")
         return [];
-    return mandatoryDelegationsForStage(stage, complexityTier);
+    const effectiveTier = resolvedStageComplexityTier({
+        stage,
+        defaultTier: complexityTier,
+        discoveryMode
+    });
+    return mandatoryDelegationsForStage(stage, effectiveTier);
 }
 /**
  * Wave 25 (v6.1.0) — track-aware artifact validation demotion.
@@ -847,7 +866,7 @@ export function shouldDemoteArtifactValidationByTrack(track, taskClass) {
         return true;
     return false;
 }
-export function stageSchema(stage, track = "standard") {
+export function stageSchema(stage, track = "standard", discoveryMode, taskClass) {
     const rawInput = stage === "tdd" ? tddStageForTrack(track) : STAGE_SCHEMA_MAP[stage];
     const base = normalizeStageSchemaInput(rawInput);
     const tieredGates = tieredStageGates(stage, base.requiredGates, track);
@@ -856,7 +875,11 @@ export function stageSchema(stage, track = "standard") {
         ...base.crossStageTrace,
         readsFrom: readsFromForTrack(base.crossStageTrace.readsFrom, track)
     };
-    const complexityTier = base.complexityTier ?? "standard";
+    const complexityTier = resolvedStageComplexityTier({
+        stage,
+        defaultTier: base.complexityTier ?? "standard",
+        discoveryMode
+    });
     const mandatoryDelegations = mandatoryDelegationsForStage(stage, complexityTier);
     const philosophy = {
         hardGate: base.hardGate,