cclaw-cli 6.1.1 → 6.3.0

package/dist/internal/advance-stage/advance.js

@@ -11,7 +11,7 @@ import { stageSchema } from "../../content/stage-schema.js";
 import { extractReviewLoopEnvelopeFromArtifact } from "../../content/review-loop.js";
 import { unique } from "./helpers.js";
 import { AUTO_REVIEW_LOOP_GATE_BY_STAGE, reviewLoopArtifactFixHint, reviewLoopEnvelopeExample, validateGateEvidenceShape } from "./review-loop.js";
-import { ensureProactiveDelegationTrace } from "./verify.js";
+import { ensureProactiveDelegationTrace } from "./proactive-delegation-trace.js";
 function resolveSuccessorTransition(stage, track, transitionTargets, satisfiedGuards, selectedTransitionGuards) {
     const natural = transitionTargets[0] ?? null;
     const specialTargets = transitionTargets.filter((target) => target !== natural);
@@ -299,7 +299,7 @@ export async function runAdvanceStage(projectRoot, args, io) {
         io.stderr.write(`cclaw internal advance-stage: current stage is "${flowState.currentStage}", not "${args.stage}".\n`);
         return 1;
     }
-    const schema = stageSchema(args.stage, flowState.track);
+    const schema = stageSchema(args.stage, flowState.track, flowState.discoveryMode, flowState.taskClass ?? null);
     const requiredGateIds = schema.requiredGates
         .filter((gate) => gate.tier === "required")
         .map((gate) => gate.id);
@@ -434,6 +434,19 @@ export async function runAdvanceStage(projectRoot, args, io) {
         extraStageFlags: args.skipQuestions ? ["--skip-questions"] : undefined
     });
     if (!validation.ok) {
+        const delegationFailureCount = validation.delegation.missing.length +
+            validation.delegation.missingEvidence.length +
+            validation.delegation.missingDispatchProof.length +
+            validation.delegation.legacyInferredCompletions.length +
+            validation.delegation.corruptEventLines.length +
+            validation.delegation.staleWorkers.length;
+        const gatesFailureCount = validation.gates.issues.length;
+        const closureFailureCount = validation.completedStages.issues.length;
+        const failureCounts = {
+            delegation: delegationFailureCount,
+            gates: gatesFailureCount,
+            closure: closureFailureCount
+        };
         const ledgerForDiag = await readDelegationLedger(projectRoot).catch(() => ({ entries: [] }));
         const eventsForDiag = await readDelegationEvents(projectRoot).catch(() => ({ events: [], corruptLines: [] }));
         const ledgerEntriesText = await fs.readFile(path.join(projectRoot, ".cclaw/state/delegation-events.jsonl"), "utf8").catch(() => "");
@@ -482,6 +495,7 @@ export async function runAdvanceStage(projectRoot, args, io) {
                 command: "advance-stage",
                 stage: args.stage,
                 kind: "validation-failed",
+                failureCounts,
                 delegation: validation.delegation,
                 gates: validation.gates,
                 completedStages: validation.completedStages,
@@ -493,7 +507,7 @@ export async function runAdvanceStage(projectRoot, args, io) {
                 nextActions
             })}\n`);
         }
-        io.stderr.write(`cclaw internal advance-stage: validation failed for stage "${args.stage}".\n`);
+        io.stderr.write(`cclaw internal advance-stage: validation failed for stage "${args.stage}" (delegation=${failureCounts.delegation}, gates=${failureCounts.gates}, closure=${failureCounts.closure}).\n`);
         if (validation.delegation.missing.length > 0) {
             io.stderr.write(`- missing delegations: ${validation.delegation.missing.join(", ")}\n`);
             io.stderr.write(`  next action: run the named agent(s) for this stage, or rerun with --waive-delegation=${validation.delegation.missing.join(",")} --waiver-reason="<why safe>" only when the user accepts the safety trade-off.\n`);
@@ -530,7 +544,9 @@ export async function runAdvanceStage(projectRoot, args, io) {
     }
     const proactiveTrace = await ensureProactiveDelegationTrace(projectRoot, args.stage, {
         acceptWaiver: args.acceptProactiveWaiver,
-        waiverReason: args.acceptProactiveWaiverReason
+        waiverReason: args.acceptProactiveWaiverReason,
+        discoveryMode: flowState.discoveryMode,
+        repoSignals: flowState.repoSignals
     });
     if (proactiveTrace.missingRules.length > 0) {
         const missingSummary = proactiveTrace.missingRules

package/dist/internal/advance-stage/parsers.d.ts

@@ -1,4 +1,4 @@
-import { type FlowStage, type FlowTrack } from "../../types.js";
+import { type DiscoveryMode, type FlowStage, type FlowTrack } from "../../types.js";
 import type { ArchiveDisposition } from "../../runs.js";
 export interface AdvanceStageArgs {
     stage: FlowStage;
@@ -32,6 +32,7 @@ export interface RewindArgs {
 }
 export interface StartFlowArgs {
     track: FlowTrack;
+    discoveryMode: DiscoveryMode;
     className?: string;
     prompt?: string;
     reason?: string;

package/dist/internal/advance-stage/parsers.js

@@ -1,5 +1,5 @@
 import { FLOW_STAGES } from "../../types.js";
-import { isFlowTrack } from "../../flow-state.js";
+import { isDiscoveryMode, isFlowTrack } from "../../flow-state.js";
 import { isFlowStageValue, parseCsv, parseEvidenceByGate, unique } from "./helpers.js";
 export function parseAdvanceStageArgs(tokens) {
     const [stageRaw, ...flagTokens] = tokens;
@@ -204,6 +204,7 @@ export function parseHookArgs(tokens) {
 }
 export function parseStartFlowArgs(tokens) {
     let track;
+    let discoveryMode = "guided";
     let className;
     let prompt;
     let reason;
@@ -245,6 +246,15 @@ export function parseStartFlowArgs(tokens) {
             track = raw;
             continue;
         }
+        if (token === "--discovery-mode" || token.startsWith("--discovery-mode=")) {
+            const raw = readValue("--discovery-mode").trim();
+            const normalized = raw.toLowerCase();
+            if (!isDiscoveryMode(normalized)) {
+                throw new Error(`--discovery-mode must be one of: lean, guided, deep.`);
+            }
+            discoveryMode = normalized;
+            continue;
+        }
         if (token === "--class" || token.startsWith("--class=")) {
             className = readValue("--class").trim();
             continue;
@@ -281,6 +291,7 @@ export function parseStartFlowArgs(tokens) {
     }
     return {
         track,
+        discoveryMode,
         className,
         prompt,
         reason,

package/dist/internal/advance-stage/proactive-delegation-trace.d.ts

@@ -0,0 +1,21 @@
+import { type StageAutoSubagentDispatch } from "../../content/stage-schema.js";
+import type { DiscoveryMode, FlowStage } from "../../types.js";
+import type { RepoSignals } from "../../flow-state.js";
+export interface ProactiveDelegationTraceResult {
+    missingRules: StageAutoSubagentDispatch[];
+}
+/**
+ * Ensure every proactive dispatch rule for the stage has a ledger row for the
+ * active run, or an explicit user-flag waiver.
+ *
+ * Lean/guided discovery on early elicitation stages intentionally does not
+ * require a full proactive trace: specialists run only when triggers warrant
+ * them. Deep discovery keeps the blanket trace so mandatory + proactive
+ * coverage stays auditably complete before advance.
+ */
+export declare function ensureProactiveDelegationTrace(projectRoot: string, stage: FlowStage, options: {
+    acceptWaiver: boolean;
+    waiverReason?: string;
+    discoveryMode: DiscoveryMode;
+    repoSignals?: RepoSignals;
+}): Promise<ProactiveDelegationTraceResult>;

package/dist/internal/advance-stage/proactive-delegation-trace.js

@@ -0,0 +1,60 @@
+import { appendDelegation, readDelegationLedger } from "../../delegation.js";
+import { stageAutoSubagentDispatch } from "../../content/stage-schema.js";
+function isEarlyElicitationStage(stage) {
+    return stage === "brainstorm" || stage === "scope" || stage === "design";
+}
+function isSparseRepoForResearcherSkip(repoSignals) {
+    if (!repoSignals)
+        return false;
+    return repoSignals.fileCount < 5 && !repoSignals.hasReadme && !repoSignals.hasPackageManifest;
+}
+function skipRepoDependentProactiveRule(rule, stage, discoveryMode, repoSignals) {
+    if (discoveryMode !== "deep")
+        return false;
+    if (stage !== "brainstorm" && stage !== "scope")
+        return false;
+    if (!rule.dependsOnInternalRepoSignals)
+        return false;
+    return isSparseRepoForResearcherSkip(repoSignals);
+}
+/**
+ * Ensure every proactive dispatch rule for the stage has a ledger row for the
+ * active run, or an explicit user-flag waiver.
+ *
+ * Lean/guided discovery on early elicitation stages intentionally does not
+ * require a full proactive trace: specialists run only when triggers warrant
+ * them. Deep discovery keeps the blanket trace so mandatory + proactive
+ * coverage stays auditably complete before advance.
+ */
+export async function ensureProactiveDelegationTrace(projectRoot, stage, options) {
+    if (isEarlyElicitationStage(stage) && (options.discoveryMode === "lean" || options.discoveryMode === "guided")) {
+        return { missingRules: [] };
+    }
+    const proactiveRules = stageAutoSubagentDispatch(stage)
+        .filter((rule) => rule.mode === "proactive")
+        .filter((rule) => !skipRepoDependentProactiveRule(rule, stage, options.discoveryMode, options.repoSignals));
+    if (proactiveRules.length === 0)
+        return { missingRules: [] };
+    const ledger = await readDelegationLedger(projectRoot);
+    const currentRunEntries = ledger.entries.filter((entry) => entry.runId === ledger.runId);
+    const missingRules = proactiveRules.filter((rule) => !currentRunEntries.some((entry) => entry.stage === stage && entry.agent === rule.agent && entry.mode === "proactive"));
+    if (missingRules.length === 0)
+        return { missingRules: [] };
+    if (!options.acceptWaiver)
+        return { missingRules };
+    const waiverReason = options.waiverReason?.trim() || "accepted via --accept-proactive-waiver";
+    for (const rule of missingRules) {
+        await appendDelegation(projectRoot, {
+            stage,
+            agent: rule.agent,
+            mode: "proactive",
+            status: "waived",
+            waiverReason,
+            acceptedBy: "user-flag",
+            conditionTrigger: rule.when,
+            skill: rule.skill,
+            ts: new Date().toISOString()
+        });
+    }
+    return { missingRules: [] };
+}

package/dist/internal/advance-stage/start-flow.d.ts

@@ -1,10 +1,12 @@
-import { type FlowState } from "../../flow-state.js";
+import { type FlowState, type RepoSignals } from "../../flow-state.js";
 import type { StartFlowArgs } from "./parsers.js";
 import type { Writable } from "node:stream";
 interface InternalIo {
     stdout: Writable;
     stderr: Writable;
 }
+/** One-pass repo snapshot (max ~200 files, skips `node_modules`/`.git`). */
+export declare function collectRepoSignals(projectRoot: string): Promise<RepoSignals>;
 export declare function discoverStartFlowContext(projectRoot: string): Promise<string[]>;
 export declare function appendIdeaArtifact(projectRoot: string, args: StartFlowArgs, previous?: FlowState): Promise<void>;
 export declare function runStartFlow(projectRoot: string, args: StartFlowArgs, io: InternalIo): Promise<number>;

package/dist/internal/advance-stage/start-flow.js

@@ -7,6 +7,74 @@ import { listExistingFiles, listFilesUnder, pathExists } from "./helpers.js";
 import { TRACK_STAGES } from "../../types.js";
 import { buildValidationReport } from "./advance.js";
 import { carriedCompletedStageCatalog, completedStageClosureEvidenceIssues, firstIncompleteStageForTrack } from "./verify.js";
+function resolveTaskClass(className, fallback) {
+    if (className === "software-standard" || className === "software-trivial" || className === "software-bugfix") {
+        return className;
+    }
+    return fallback;
+}
+const REPO_SIGNAL_SKIP_DIRS = new Set(["node_modules", ".git"]);
+/** One-pass repo snapshot (max ~200 files, skips `node_modules`/`.git`). */
+export async function collectRepoSignals(projectRoot) {
+    const capturedAt = new Date().toISOString();
+    const cap = 200;
+    let fileCount = 0;
+    async function visit(absDir, depth) {
+        if (fileCount >= cap)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(absDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const ent of entries) {
+            if (fileCount >= cap)
+                return;
+            const name = ent.name;
+            if (REPO_SIGNAL_SKIP_DIRS.has(name))
+                continue;
+            const abs = path.join(absDir, name);
+            if (ent.isFile()) {
+                fileCount += 1;
+                continue;
+            }
+            if (ent.isDirectory() && depth < 1) {
+                await visit(abs, depth + 1);
+            }
+        }
+    }
+    let hasReadme = false;
+    let hasPackageManifest = false;
+    for (const fname of ["README.md", "readme.md", "Readme.md"]) {
+        try {
+            const st = await fs.stat(path.join(projectRoot, fname));
+            if (st.isFile())
+                hasReadme = true;
+        }
+        catch {
+            // ignore
+        }
+    }
+    for (const manifest of ["package.json", "pyproject.toml", "Cargo.toml"]) {
+        try {
+            const st = await fs.stat(path.join(projectRoot, manifest));
+            if (st.isFile())
+                hasPackageManifest = true;
+        }
+        catch {
+            // ignore
+        }
+    }
+    try {
+        await visit(projectRoot, 0);
+    }
+    catch {
+        fileCount = Math.min(fileCount, cap);
+    }
+    return { fileCount, hasReadme, hasPackageManifest, capturedAt };
+}
 export async function discoverStartFlowContext(projectRoot) {
     const lines = [];
     const seedFiles = (await listFilesUnder(projectRoot, path.join(RUNTIME_ROOT, "seeds"), 10))
@@ -58,6 +126,7 @@ export async function appendIdeaArtifact(projectRoot, args, previous) {
             `- From: ${previous?.track ?? "unknown"}`,
             `- To: ${args.track}`,
             `- Class: ${args.className || "unspecified"}`,
+            `- Discovery mode: ${args.discoveryMode}`,
             `- Reason: ${args.reason || "unspecified"}`
         ].join("\n") + "\n";
         await fs.appendFile(artifactPath, entry, "utf8");
@@ -68,6 +137,7 @@ export async function appendIdeaArtifact(projectRoot, args, previous) {
         "# Idea",
         `Class: ${args.className || "unspecified"}`,
         `Track: ${args.track}${args.reason ? ` (${args.reason})` : ""}`,
+        `Discovery mode: ${args.discoveryMode}`,
         `Stack: ${args.stack || "unknown"}`,
         "",
         "## User prompt",
@@ -85,10 +155,11 @@ export async function runStartFlow(projectRoot, args, io) {
         io.stderr.write("cclaw internal start-flow: refusing to reset an active flow with completed stages without --force-reset. Ask the user before resetting.\n");
         return 1;
     }
+    const nextTaskClass = resolveTaskClass(args.className, current.taskClass);
     let nextState;
     if (args.reclassify) {
         const completedInNewTrack = current.completedStages.filter((stage) => TRACK_STAGES[args.track].includes(stage));
-        const fresh = createInitialFlowState({ activeRunId: current.activeRunId, track: args.track });
+        const fresh = createInitialFlowState({ activeRunId: current.activeRunId, track: args.track, discoveryMode: args.discoveryMode });
         const stageGateCatalog = { ...fresh.stageGateCatalog };
         const guardEvidence = {};
         for (const stage of completedInNewTrack) {
@@ -98,6 +169,7 @@ export async function runStartFlow(projectRoot, args, io) {
         }
         nextState = {
             ...fresh,
+            ...(nextTaskClass !== undefined ? { taskClass: nextTaskClass } : {}),
             completedStages: completedInNewTrack,
             currentStage: firstIncompleteStageForTrack(args.track, completedInNewTrack),
             guardEvidence,
@@ -117,7 +189,10 @@ export async function runStartFlow(projectRoot, args, io) {
         }
     }
     else {
-        nextState = createInitialFlowState({ track: args.track });
+        nextState = createInitialFlowState({ track: args.track, discoveryMode: args.discoveryMode });
+        if (nextTaskClass !== undefined) {
+            nextState = { ...nextState, taskClass: nextTaskClass };
+        }
     }
     if (args.fromIdeaArtifact) {
         const existingHints = nextState.interactionHints ?? {};
@@ -132,6 +207,8 @@ export async function runStartFlow(projectRoot, args, io) {
             }
         };
     }
+    const repoSignals = await collectRepoSignals(projectRoot);
+    nextState = { ...nextState, repoSignals };
     await writeFlowState(projectRoot, nextState, { allowReset: true });
     await appendIdeaArtifact(projectRoot, args, current);
     if (!args.quiet) {
@@ -140,6 +217,8 @@ export async function runStartFlow(projectRoot, args, io) {
             command: "start-flow",
             reclassify: args.reclassify,
             track: nextState.track,
+            discoveryMode: nextState.discoveryMode,
+            taskClass: nextState.taskClass ?? null,
             currentStage: nextState.currentStage,
             skippedStages: nextState.skippedStages,
             activeRunId: nextState.activeRunId

package/dist/internal/advance-stage/verify.d.ts

@@ -1,4 +1,3 @@
-import { type StageAutoSubagentDispatch } from "../../content/stage-schema.js";
 import { type FlowState, type StageGateState } from "../../flow-state.js";
 import { type FlowStage, type FlowTrack } from "../../types.js";
 import type { VerifyCurrentStateArgs, VerifyFlowStateDiffArgs } from "./parsers.js";
@@ -7,9 +6,6 @@ interface InternalIo {
     stdout: Writable;
     stderr: Writable;
 }
-interface ProactiveDelegationTraceResult {
-    missingRules: StageAutoSubagentDispatch[];
-}
 export declare function runVerifyFlowStateDiff(projectRoot: string, args: VerifyFlowStateDiffArgs, io: InternalIo): Promise<number>;
 export declare function runVerifyCurrentState(projectRoot: string, args: VerifyCurrentStateArgs, io: InternalIo): Promise<number>;
 export declare function firstIncompleteStageForTrack(track: FlowTrack, completedStages: FlowStage[]): FlowStage;
@@ -18,10 +14,6 @@ export declare function carriedCompletedStageCatalog(current: FlowState, fresh:
     evidence: Record<string, string>;
 };
 export declare function completedStageClosureEvidenceIssues(flowState: FlowState): string[];
-export declare function ensureProactiveDelegationTrace(projectRoot: string, stage: FlowStage, options: {
-    acceptWaiver: boolean;
-    waiverReason?: string;
-}): Promise<ProactiveDelegationTraceResult>;
 export declare function pathExists(projectRoot: string, relPath: string): Promise<boolean>;
 export declare function listExistingFiles(projectRoot: string, relPaths: string[]): Promise<string[]>;
 export declare function listFilesUnder(projectRoot: string, relDir: string, limit?: number): Promise<string[]>;

package/dist/internal/advance-stage/verify.js

@@ -1,7 +1,6 @@
 import path from "node:path";
 import { RUNTIME_ROOT } from "../../constants.js";
-import { stageAutoSubagentDispatch, stageSchema } from "../../content/stage-schema.js";
-import { appendDelegation, readDelegationLedger } from "../../delegation.js";
+import { stageSchema } from "../../content/stage-schema.js";
 import { readFlowState } from "../../runs.js";
 import { TRACK_STAGES } from "../../types.js";
 import { coerceCandidateFlowState } from "./flow-state-coercion.js";
@@ -87,7 +86,7 @@ export function carriedCompletedStageCatalog(current, fresh, stage) {
 export function completedStageClosureEvidenceIssues(flowState) {
     const issues = [];
     for (const stage of flowState.completedStages) {
-        const schema = stageSchema(stage, flowState.track);
+        const schema = stageSchema(stage, flowState.track, flowState.discoveryMode, flowState.taskClass ?? null);
         const catalog = flowState.stageGateCatalog[stage];
         const required = schema.requiredGates
             .filter((gate) => gate.tier === "required")
@@ -103,33 +102,6 @@ export function completedStageClosureEvidenceIssues(flowState) {
     }
     return issues;
 }
-export async function ensureProactiveDelegationTrace(projectRoot, stage, options) {
-    const proactiveRules = stageAutoSubagentDispatch(stage).filter((rule) => rule.mode === "proactive");
-    if (proactiveRules.length === 0)
-        return { missingRules: [] };
-    const ledger = await readDelegationLedger(projectRoot);
-    const currentRunEntries = ledger.entries.filter((entry) => entry.runId === ledger.runId);
-    const missingRules = proactiveRules.filter((rule) => !currentRunEntries.some((entry) => entry.stage === stage && entry.agent === rule.agent && entry.mode === "proactive"));
-    if (missingRules.length === 0)
-        return { missingRules: [] };
-    if (!options.acceptWaiver)
-        return { missingRules };
-    const waiverReason = options.waiverReason?.trim() || "accepted via --accept-proactive-waiver";
-    for (const rule of missingRules) {
-        await appendDelegation(projectRoot, {
-            stage,
-            agent: rule.agent,
-            mode: "proactive",
-            status: "waived",
-            waiverReason,
-            acceptedBy: "user-flag",
-            conditionTrigger: rule.when,
-            skill: rule.skill,
-            ts: new Date().toISOString()
-        });
-    }
-    return { missingRules: [] };
-}
 export async function pathExists(projectRoot, relPath) {
     try {
         await fs.stat(path.join(projectRoot, relPath));

package/dist/run-persistence.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
-import { nextStage, createInitialCloseoutState, createInitialFlowState, FLOW_STATE_SCHEMA_VERSION, isFlowTrack, skippedStagesForTrack, SHIP_SUBSTATES } from "./flow-state.js";
+import { nextStage, createInitialCloseoutState, createInitialFlowState, FLOW_STATE_SCHEMA_VERSION, isDiscoveryMode, isFlowTrack, skippedStagesForTrack, SHIP_SUBSTATES } from "./flow-state.js";
 import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 import { FLOW_STAGES } from "./types.js";
 export class InvalidStageTransitionError extends Error {
@@ -30,6 +30,9 @@ function validateFlowTransition(prev, next) {
     if (prev.track !== next.track) {
         throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `cannot change track from "${prev.track}" to "${next.track}" mid-run (activeRunId="${prev.activeRunId}"). Archive the run and start a new one to switch tracks.`);
     }
+    if (prev.discoveryMode !== next.discoveryMode) {
+        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `cannot change discoveryMode from "${prev.discoveryMode}" to "${next.discoveryMode}" mid-run (activeRunId="${prev.activeRunId}"). Reclassify through start-flow or start a new run.`);
+    }
     const newRewind = next.rewinds.length === prev.rewinds.length + 1
         ? next.rewinds[next.rewinds.length - 1]
         : undefined;
@@ -159,6 +162,34 @@ function sanitizeStageGateCatalog(value, fallback) {
 function coerceTrack(value) {
     return isFlowTrack(value) ? value : "standard";
 }
+function coerceDiscoveryMode(value) {
+    if (typeof value === "string") {
+        const normalized = value.trim().toLowerCase();
+        if (isDiscoveryMode(normalized))
+            return normalized;
+    }
+    return "guided";
+}
+function coerceRepoSignals(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const typed = value;
+    const fileCountRaw = typed.fileCount;
+    const fileCount = typeof fileCountRaw === "number" && Number.isFinite(fileCountRaw) && fileCountRaw >= 0
+        ? Math.min(Math.floor(fileCountRaw), 1_000_000)
+        : undefined;
+    const capturedAt = typeof typed.capturedAt === "string" ? typed.capturedAt.trim() : "";
+    if (fileCount === undefined || !capturedAt) {
+        return undefined;
+    }
+    return {
+        fileCount,
+        hasReadme: typed.hasReadme === true,
+        hasPackageManifest: typed.hasPackageManifest === true,
+        capturedAt
+    };
+}
 /**
  * Wave 24 follow-up (v6.1.1) — preserve `flow-state.json#taskClass`
  * across read/write round-trips. Before this audit fix the persistence
@@ -372,12 +403,14 @@ function sanitizeCloseoutState(value) {
 }
 function coerceFlowState(parsed) {
     const track = coerceTrack(parsed.track);
-    const next = createInitialFlowState({ track });
+    const discoveryMode = coerceDiscoveryMode(parsed.discoveryMode);
+    const next = createInitialFlowState({ track, discoveryMode });
     const activeRunIdRaw = parsed.activeRunId;
     const activeRunId = typeof activeRunIdRaw === "string" && activeRunIdRaw.trim().length > 0
         ? activeRunIdRaw.trim()
         : next.activeRunId;
     const taskClass = coerceTaskClass(parsed.taskClass);
+    const repoSignals = coerceRepoSignals(parsed.repoSignals);
     const state = {
         schemaVersion: FLOW_STATE_SCHEMA_VERSION,
         activeRunId,
@@ -386,7 +419,9 @@ function coerceFlowState(parsed) {
         guardEvidence: sanitizeGuardEvidence(parsed.guardEvidence),
         stageGateCatalog: sanitizeStageGateCatalog(parsed.stageGateCatalog, next.stageGateCatalog),
         track,
+        discoveryMode,
         ...(taskClass !== undefined ? { taskClass } : {}),
+        ...(repoSignals ? { repoSignals } : {}),
         skippedStages: sanitizeSkippedStages(parsed.skippedStages, track),
         staleStages: sanitizeStaleStages(parsed.staleStages),
         rewinds: sanitizeRewinds(parsed.rewinds),

package/dist/track-heuristics.d.ts

@@ -1,4 +1,4 @@
-import type { FlowStage, FlowTrack, TrackHeuristicRule, TrackHeuristicsConfig } from "./types.js";
+import type { DiscoveryMode, FlowStage, FlowTrack, TrackHeuristicRule, TrackHeuristicsConfig } from "./types.js";
 export interface TrackResolution {
     track: FlowTrack;
     reason: string;
@@ -19,7 +19,7 @@ export interface QuestionBudgetHint {
  * "advisory" language.
  */
 export declare function resolveTrackFromPrompt(prompt: string, config: TrackHeuristicsConfig | undefined): TrackResolution;
-export declare function questionBudgetHint(track: FlowTrack, stage: FlowStage): QuestionBudgetHint;
+export declare function questionBudgetHint(modeOrTrack: DiscoveryMode | FlowTrack, stage: FlowStage): QuestionBudgetHint;
 export declare const TRACK_HEURISTICS_DEFAULTS: {
     readonly fallback: "standard";
     readonly evaluationOrder: readonly ("quick" | "medium" | "standard")[];

package/dist/track-heuristics.js

@@ -55,10 +55,10 @@ const DEFAULT_RULES = {
 const EVALUATION_ORDER = ["standard", "medium", "quick"];
 const DEFAULT_FALLBACK = "standard";
 const ADAPTIVE_ELICITATION_STAGES = new Set(["brainstorm", "scope", "design"]);
-const QUESTION_BUDGET_HINTS_BY_TRACK = {
-    quick: { min: 2, recommended: 3, hardCapWarning: 4 },
-    medium: { min: 5, recommended: 6, hardCapWarning: 8 },
-    standard: { min: 10, recommended: 12, hardCapWarning: 14 }
+const QUESTION_BUDGET_HINTS_BY_DISCOVERY_MODE = {
+    lean: { min: 3, recommended: 4, hardCapWarning: 6 },
+    guided: { min: 5, recommended: 7, hardCapWarning: 10 },
+    deep: { min: 7, recommended: 10, hardCapWarning: 14 }
 };
 function hasToken(promptLower, token) {
     return promptLower.includes(token.toLowerCase());
@@ -136,11 +136,16 @@ export function resolveTrackFromPrompt(prompt, config) {
         overrideGuidance: "Confirm or override before state is written; choose quick only for known low-blast-radius work, medium for known architecture with product framing, standard for uncertainty."
     };
 }
-export function questionBudgetHint(track, stage) {
+export function questionBudgetHint(modeOrTrack, stage) {
     if (!ADAPTIVE_ELICITATION_STAGES.has(stage)) {
         return { min: 0, recommended: 0, hardCapWarning: 0 };
     }
-    return QUESTION_BUDGET_HINTS_BY_TRACK[track];
+    if (modeOrTrack === "lean" || modeOrTrack === "guided" || modeOrTrack === "deep") {
+        return QUESTION_BUDGET_HINTS_BY_DISCOVERY_MODE[modeOrTrack];
+    }
+    if (modeOrTrack === "quick")
+        return QUESTION_BUDGET_HINTS_BY_DISCOVERY_MODE.lean;
+    return QUESTION_BUDGET_HINTS_BY_DISCOVERY_MODE.guided;
 }
 export const TRACK_HEURISTICS_DEFAULTS = {
     fallback: DEFAULT_FALLBACK,

package/dist/types.d.ts

@@ -2,6 +2,8 @@ export declare const FLOW_STAGES: readonly ["brainstorm", "scope", "design", "sp
 export type FlowStage = (typeof FLOW_STAGES)[number];
 export declare const FLOW_TRACKS: readonly ["quick", "medium", "standard"];
 export type FlowTrack = (typeof FLOW_TRACKS)[number];
+export declare const DISCOVERY_MODES: readonly ["lean", "guided", "deep"];
+export type DiscoveryMode = (typeof DISCOVERY_MODES)[number];
 /**
  * Ordered stages that make up each flow track.
  *

package/dist/types.js

@@ -9,6 +9,7 @@ export const FLOW_STAGES = [
     "ship"
 ];
 export const FLOW_TRACKS = ["quick", "medium", "standard"];
+export const DISCOVERY_MODES = ["lean", "guided", "deep"];
 /**
  * Ordered stages that make up each flow track.
  *

package/package.json

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