cclaw-cli 6.1.1 → 6.3.0

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/skills.js

@@ -389,6 +389,7 @@ function completionParametersBlock(schema, track) {
 - Fill \`## Learnings\` before closeout: either \`- None this stage.\` or JSON bullets with required keys \`type\`, \`trigger\`, \`action\`, \`confidence\` (knowledge-schema compatible).
 - Record mandatory delegation lifecycle in \`${RUNTIME_ROOT}/state/delegation-log.json\` and append proof events to \`${RUNTIME_ROOT}/state/delegation-events.jsonl\`; the ledger is current state, the event log is audit proof.${mandatoryAgents.length > 0 ? ` If a mandatory delegation cannot run in this harness, use \`--waive-delegation=${mandatoryAgents.join(",")} --waiver-reason="<why safe>"\` on the completion helper.` : ""} If proactive delegations were intentionally skipped, rerun only with \`--accept-proactive-waiver\` (optionally \`--accept-proactive-waiver-reason="<why safe>"\`) after explicit user approval.
 - Never edit raw \`flow-state.json\` to complete a stage, even in advisory mode; that bypasses validation, gate evidence, and Learnings harvest. If a helper fails, report a one-line human-readable failure plus fenced JSON diagnostics; never echo the invoking command line or apply a manual state workaround.
+- Stage completion claim requires \`stage-complete\` exit 0 in the current turn. Quote the success line; do not paraphrase, do not infer success from skipped retries.
 - 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/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":
@@ -484,7 +498,8 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             runPhase: "post-elicitation",
             when: "When repository, market, docs, or prior-art context changes the approach set. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Provide search-before-read summaries and context-readiness evidence before large reads or decisions.",
-            requiresUserGate: false
+            requiresUserGate: false,
+            dependsOnInternalRepoSignals: true
         }
     ],
     scope: [
@@ -521,7 +536,8 @@ const STAGE_AUTO_SUBAGENT_DISPATCH = {
             runPhase: "post-elicitation",
             when: "When churn, prior attempts, reference patterns, or external constraints may change scope boundaries. Runs only after the adaptive elicitation Q&A loop converges.",
             purpose: "Summarize search/context findings before the scope contract locks accepted/rejected/deferred ideas.",
-            requiresUserGate: false
+            requiresUserGate: false,
+            dependsOnInternalRepoSignals: true
         },
         {
             agent: "product-discovery",
@@ -811,12 +827,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 +868,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 +877,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,

package/dist/content/stages/brainstorm.js

@@ -7,7 +7,7 @@ export const BRAINSTORM = {
     complexityTier: "standard",
     skillFolder: "brainstorm",
     skillName: "brainstorm",
-    skillDescription: "Problem-discovery stage. Build a concise Problem Decision Record, choose lite/standard/deep depth, compare distinct directions, and hand approved decisions to scope.",
+    skillDescription: "Problem-discovery stage. Build a concise Problem Decision Record, compare distinct directions under the run's discovery mode (lean / guided / deep), and hand approved decisions to scope.",
     philosophy: {
         hardGate: "Do NOT invoke implementation skills, write code, scaffold projects, or mutate product behavior until a concrete direction is approved by the user.",
         ironLaw: "NO ARTIFACT IS COMPLETE WITHOUT AN EXPLICITLY APPROVED DIRECTION — SILENCE IS NOT APPROVAL.",
@@ -39,7 +39,7 @@ export const BRAINSTORM = {
             "**ADAPTIVE ELICITATION COMES FIRST (no exceptions, no subagent dispatch before).** Load `.cclaw/skills/adaptive-elicitation/SKILL.md`. Walk the brainstorm forcing questions one-at-a-time via the harness-native question tool, append one row to `## Q&A Log` (`Turn | Question | User answer (1-line) | Decision impact`) after each user answer **and stamp the row's `Decision impact` cell with the matching `[topic:<id>]` tag** (e.g. `[topic:pain]`). Continue until every forcing-question topic id is tagged on a row OR Ralph-Loop convergence detector says no new decision-changing rows in last 2 iterations OR user records an explicit stop-signal row. Only then proceed to delegations, drafts, or analysis. The linter `qa_log_unconverged` rule will block `stage-complete` if convergence is not reached.",
             "**Explore project context** — after the elicitation loop converges, inspect existing files/docs/recent activity to refine the Discovered context section; capture matching files/patterns/seeds in `Context > Discovered context` so downstream stages don't redo discovery.",
             "**Brainstorm forcing questions (must be covered or explicitly waived)** — `pain: what pain are we solving`; `direct-path: what is the direct path`; `do-nothing: what happens if we do nothing`; `operator: who is the first operator/user affected`; `no-go: what no-go boundaries are non-negotiable`. Tag the matching `## Q&A Log` row's `Decision impact` cell with `[topic:<id>]` (e.g. `[topic:pain]`) so the linter can verify coverage in any natural language. Tags are MANDATORY for forcing-question rows; un-tagged rows do NOT count toward coverage.",
-            "**Classify stage depth** — choose `lite` for clear low-risk tasks, `standard` for normal engineering/product changes, or `deep` for ambiguity, architecture, external dependency, security/data risk, or explicit think-bigger requests.",
+            "**Discovery posture (flow-state `discoveryMode`)** — follow `lean` / `guided` / `deep` from the active run. Use lean for smallest safe discovery pass; guided as the default balanced pass; escalate to deep when ambiguity, architecture, external dependency, security/data risk, or explicit think-bigger requests warrant fuller option pressure and mandatory specialist coverage.",
             "**Write the Problem Decision Record** — pick a free-form `Frame type` label that names how this work is framed (examples: product, technical-maintenance, research-spike, ops-incident, infrastructure), then fill the universal Framing fields: affected user/role/operator, current state/failure mode/opportunity, desired observable outcome, evidence/signal, why now, do-nothing consequence, and non-goals.",
             "**Premise check (one pass)** — answer the three gstack-style questions in the artifact body: *Right problem? Direct path? What if we do nothing?* Take a position; do not hedge.",
             "**Reframe with How Might We** — write a single `How Might We …?` line that names the user/operator, the desired outcome, and the constraint. This is the altitude check before approaches.",
@@ -61,7 +61,7 @@ export const BRAINSTORM = {
         interactionProtocol: [
             "\"If something is unclear, stop. Name what's confusing. Ask.\"",
             "Start from observed project context; if the idea is vague, first narrow the project type with **one** structured question, then keep going.",
-            "Select depth explicitly: `lite`, `standard`, or `deep`; keep lite concise, but escalate when risk/ambiguity changes decisions.",
+            "Honor the run's `discoveryMode` (`lean` | `guided` | `deep`) from flow-state: lean stays fastest, guided is the default breadth, deep pulls in fuller critique and mandatory delegations when the run is classified that way.",
             "Lead with the premise check (right problem / direct path / what if nothing) and the `How Might We` reframing before approaches; both go in the artifact, not just the chat.",
             "Ask at most one question per turn, only when decision-changing; if using a structured question tool, send exactly one question object, not a multi-question form.",
             "Run the shared adaptive elicitation cycle from `.cclaw/skills/adaptive-elicitation/SKILL.md`, including stop-signal handling (RU/EN/UA), smart-skip, conditional grilling triggers, and append-only `## Q&A Log` updates.",
@@ -72,7 +72,7 @@ export const BRAINSTORM = {
             "State exactly what is being approved, then **STOP** until the user explicitly approves the artifact."
         ],
         process: [
-            "Explore project context and classify depth/scope.",
+            "Explore project context and align work to the run's discovery mode (lean / guided / deep).",
             "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.",
@@ -145,7 +145,7 @@ export const BRAINSTORM = {
             { section: "Clarity Gate", required: false, validationRule: "Recommended before recommendation lock: include ambiguity score (0.00-1.00), decision boundaries, reaffirmed non-goals, and residual-risk handoff for scope." },
             { section: "Sharpening Questions", required: false, validationRule: "Recommended only when needed: one decision-changing question per turn with explicit `Decision impact`; compact tasks may record `None - early exit` with rationale." },
             { 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 lite/standard/deep and explain the risk/uncertainty signal." },
+            { section: "Approach Tier", required: true, validationRule: "Must record how much discovery/evidence breadth is warranted in discoveryMode terms (`lean`, `guided`, or `deep`) relative to flow-state—and explain what risk or uncertainty drives that calibration (not merely the label)." },
             { 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: "Reference Pattern Candidates", required: false, validationRule: "Recommended when examples influence direction: list pattern/source, reusable invariant, accept/reject/defer disposition, and reason before approaches are finalized." },
             { section: "Idea Evidence Carry-forward", required: false, validationRule: "Wave 23 (v5.0.0): when `flow-state.interactionHints.brainstorm.fromIdeaArtifact` is set, this section MUST cite the idea artifact path and the chosen `I-#`, list reused fields (Title, Why-now, Expected impact, Risk, Counter-argument), and explicitly state that only challenger row(s) were newly generated. Honors `/cc-ideate` handoff so divergent + critique + rank work is reused, not redone." },

package/dist/content/stages/design.js

@@ -78,7 +78,7 @@ export const DESIGN = {
             "Run compact research by default; write `.cclaw/artifacts/02a-research.md` only when deep/high-risk uncertainty requires a separate research artifact.",
             "Run investigator pass plus scope challenge/search-before-building.",
             "Walk review sections interactively and lock boundaries, data flow, state transitions, edge cases, and failure modes.",
-            "Cover security, observability, deployment, tests, and performance for Standard+ changes.",
+            "Cover security, observability, deployment, tests, and performance for guided/deep-shaped design work; lean slices may omit heavy add-ons only when scope and risk justify the compact path.",
             "Run stale-diagram audit (enabled by default unless explicitly disabled).",
             "Produce required outputs: blast-radius diff (scope owns full repo audit), tier diagrams, failure table, completion dashboard. Out-of-scope is carried from scope via Upstream Handoff — do NOT re-author it.",
             "Plant high-upside deferred ideas when useful and reconcile critic/outside-voice findings.",

package/dist/content/stages/schema-types.d.ts

@@ -53,6 +53,12 @@ export interface StageAutoSubagentDispatch {
     returnSchema?: StageSubagentReturnSchema;
     /** Optional skill folder the dispatched agent should load as additional context. */
     skill?: string;
+    /**
+     * When true, proactive trace requirements for this row may be skipped on an
+     * empty/sparse repo (see `ensureProactiveDelegationTrace`). Used for
+     * `researcher` on early elicitation stages in deep discovery mode.
+     */
+    dependsOnInternalRepoSignals?: boolean;
 }
 export type StageComplexityTier = "lightweight" | "standard" | "deep";
 export interface StagePhilosophy {

package/dist/content/stages/scope.js

@@ -52,7 +52,7 @@ export const SCOPE = {
             "**Premise carry-forward (do NOT re-author)** — brainstorm OWNS the premise check (right problem / direct path / what if nothing). Cite brainstorm's `## Premise Check` section in `## Upstream Handoff > Decisions carried forward`. Add a row to `## Premise Drift` only when the scope-stage Q&A surfaced NEW evidence that materially changes the brainstorm answer (e.g. new constraint, new user signal). Otherwise mark `Premise Drift: None` — do not duplicate the brainstorm premise table.",
             "**Conditional 10-star boundary** — for deep/high-risk/product-strategy work, show what would make the product meaningfully better, then explicitly choose what ships now, what is deferred, and what is excluded without vague `later/for now` placeholders. Skip this for straightforward repair work and record `not needed: compact scope`.",
             "**Pick one operational mode with the user** — HOLD SCOPE preserves focus; SELECTIVE EXPANSION cherry-picks high-leverage reference ideas; SCOPE EXPANSION explores ambitious alternatives; SCOPE REDUCTION cuts to the essential wedge. Recommend one, state why and what signal would change it, then keep elicitation focused until the user either approves or asks to proceed with draft boundaries.",
-            "**Run mode-specific analysis only to needed depth** — lite keeps the selected-mode row compact; standard adds requirements/locked decisions/discretion; deep may add Landscape Check, Taste Calibration, Reference Pattern Registry, Reference Pull, Ambitious Alternatives, and Ruthless Minimum Slice evidence when mode/risk warrants it.",
+            "**Run mode-specific analysis only to needed depth** — lean discovery keeps the selected-mode row compact; guided adds the standard contract rows; deep may add Landscape Check, Taste Calibration, Reference Pattern Registry, Reference Pull, Ambitious Alternatives, and Ruthless Minimum Slice evidence when mode/risk warrants it.",
             "**Decision-driver contract** — list weighted decision drivers (value, risk, reversibility, effort, timeline) and score candidate scope moves so the selected mode and boundaries are evidence-backed, not preference-led.",
             "**Architecture handoff (do NOT pick architecture tier here)** — design OWNS architecture choice (minimum-viable / product-grade / ideal). Scope only picks the SCOPE MODE (HOLD/SELECTIVE/EXPAND/REDUCE) and boundary; record in `## Scope Contract > Design handoff` what design must decide (e.g. `architecture-tier`, `framework`, `data-model`). Do NOT enumerate Implementation Alternatives in scope.",
             "**Constraints (carry-forward from brainstorm/external sources)** — record explicit external/regulatory/system/integration constraints in `## Scope Contract > Constraints`. Spec OWNS testable assumptions (`## Assumptions Before Finalization`); do NOT duplicate constraint material as assumption material.",
@@ -65,7 +65,7 @@ export const SCOPE = {
             "\"Strong success criteria let you loop independently. Weak criteria require constant clarification.\"",
             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"),
             "Run the shared adaptive elicitation cycle from `.cclaw/skills/adaptive-elicitation/SKILL.md`, including stop-signal handling (RU/EN/UA), smart-skip, conditional grilling triggers, and append-only `## Q&A Log` updates.",
-            "**Lead with adaptive elicitation, not with a proposed contract.** First walk scope forcing questions one-at-a-time per `adaptive-elicitation` skill. Only AFTER the Q&A loop converges (forcing-Qs answered/waived OR user stop-signal row recorded) propose the scope contract draft for approval. Lite-tier may compress: ask the smallest forcing-Q set (>= linter floor for `lightweight`/`scope`), then propose contract.",
+            "**Lead with adaptive elicitation, not with a proposed contract.** First walk scope forcing questions one-at-a-time per `adaptive-elicitation` skill. Only AFTER the Q&A loop converges (forcing-Qs answered/waived OR user stop-signal row recorded) propose the scope contract draft for approval. Lean discovery may compress: ask the smallest forcing-Q set that satisfies the convergence floor, then propose contract.",
             "For low-risk concrete asks, keep the proposal compact but still explicit: recommend (do not auto-select) one mode, show exact in/out/deferred boundaries, and request explicit approval before finalizing the artifact or completing the stage.",
             "Cite brainstorm's premise via `## Upstream Handoff` and take a firm position on whether scope-stage Q&A surfaced any premise drift; do NOT re-author the brainstorm Premise Check table.",
             "Push back on weak framing: vague scope needs a specific user/problem, platform vision needs a narrow wedge, social proof needs behavioral evidence.",

package/dist/content/start-command.d.ts

@@ -2,8 +2,8 @@
  * Command contract for /cc — the unified entry point.
  * No args → reads existing flow state and progresses it when a tracked flow
  * already exists; missing state/fresh placeholder state blocks with
- * init/start guidance. With prompt → classifies the idea, selects a track, and
- * starts the first stage of that track (brainstorm for medium/standard, spec for quick).
+ * init/start guidance. With prompt → classifies the idea, asks for one discovery mode,
+ * resolves the internal track, and starts the first stage of that track (brainstorm for medium/standard, spec for quick).
  */
 export declare function startCommandContract(): string;
 /**

package/dist/content/start-command.js

@@ -9,8 +9,8 @@ function flowStatePath() {
  * Command contract for /cc — the unified entry point.
  * No args → reads existing flow state and progresses it when a tracked flow
  * already exists; missing state/fresh placeholder state blocks with
- * init/start guidance. With prompt → classifies the idea, selects a track, and
- * starts the first stage of that track (brainstorm for medium/standard, spec for quick).
+ * init/start guidance. With prompt → classifies the idea, asks for one discovery mode,
+ * resolves the internal track, and starts the first stage of that track (brainstorm for medium/standard, spec for quick).
  */
 export function startCommandContract() {
     const flowPath = flowStatePath();
@@ -21,7 +21,7 @@ export function startCommandContract() {
 **The unified entry point for the cclaw flow.**
 
 - \`/cc\` (no arguments) → reads existing flow state and resumes/progresses the active flow. If flow state is missing or still a fresh init placeholder, stop and guide the user to run \`/cc <prompt>\` or \`npx cclaw-cli init\`; do not silently create a brainstorm run.
-- \`/cc <prompt>\` (with an idea/description) → saves the prompt as idea context and starts the first stage of the resolved track.
+- \`/cc <prompt>\` (with an idea/description) → saves the prompt as idea context, asks for one discovery mode, and starts the first stage of the resolved internal track.
 
 This is the **recommended way to start, resume, and continue** working with cclaw.
 
@@ -72,7 +72,7 @@ ${conversationLanguagePolicyMarkdown()}
 
 5. Read \`${flowPath}\`.
 6. If flow already has completed stages, warn the user that starting a new tracked flow will reset progress. Ask for confirmation before proceeding. A fresh init placeholder state with \`completedStages: []\`, no passed gates, and no \`00-idea.md\` is **not** an active flow; do not ask the user to resume it.
-7. **Track heuristic** — classify the idea text and **recommend** a track (the user can override before any state mutation):
+7. **Internal track heuristic** — classify the idea text and compute an internal track recommendation before any state mutation:
    - First, load \`${RUNTIME_ROOT}/config.yaml\`. If \`trackHeuristics\` is defined, apply those per-track vocabulary hints (\`fallback\`, \`tracks.<id>.{triggers,veto}\`) on top of the built-in defaults. Evaluation order is always \`standard -> medium -> quick\` (narrow-to-broad).
    - **quick** (\`spec → tdd → review → ship\`) — single-purpose work where the spec is essentially already known. Quick skips ceremony, not safety: spec approval, TDD evidence, review, and ship gates remain mandatory.
      Triggers (case-insensitive substring or close variant): \`bug\`, \`bugfix\`, \`fix\`, \`hotfix\`, \`patch\`, \`typo\`, \`regression\`, \`copy change\`, \`rename\`, \`bump\`, \`upgrade dep\`, \`config tweak\`, \`docs only\`, \`comment\`, \`lint\`, \`format\`, \`small\`, \`tiny\`, \`one-liner\`, \`revert\`.
@@ -82,14 +82,16 @@ ${conversationLanguagePolicyMarkdown()}
      Triggers: \`new feature\`, \`refactor\`, \`migration\`, \`platform\`, \`architecture\`, \`schema\`, \`integrate\`, \`workflow\`, \`onboarding\`, or any prompt that does not match quick/medium confidently.
    - When triggers conflict, prefer **standard** over **medium**, and **medium** over **quick**.
    - Report **track selection confidence** as high/medium/low with the matched trigger or fallback reason, plus one sentence explaining what the selected track skips and what safety gates remain. Be explicit that this recommendation is advisory until the user accepts and the managed helper writes state; after that, \`/cc\` follows the configured track.
-8. Present one compact **Start framing** summary: class, recommended track, track selection confidence, stack, origin docs, seed recalls, and the recommended next action. Ask a single confirmation question only when there is a destructive reset, a real contradiction, or ambiguous software/non-software classification.
-9. Present the recommendation as a single decision with explicit options:
-   > \`Recommended track: <quick|medium|standard>\` because \`<one-line reason citing matched triggers>\`.
-   > \`Safety retained: <spec/TDD/review/ship gates that still apply>\`.
-   > Override? (A) keep \`<recommended>\`  (B) switch track with reason  (C) cancel.
+8. Present one compact **Start framing** summary: class, internal track recommendation, track selection confidence, stack, origin docs, seed recalls, and the recommended next action. Ask a single confirmation question only when there is a destructive reset, a real contradiction, or ambiguous software/non-software classification.
+9. Ask one explicit **discovery mode** question and make it the only normal start-of-run user choice:
+   > \`Choose discovery mode: Lean / Guided / Deep\`.
+   > \`Lean\` = compact shaping, \`Guided\` = recommended default with enough questions and key specialists before drafting, \`Deep\` = stronger probing and broader specialist/research passes.
+   > Mention the internal track recommendation only as context, not as the primary decision. Offer track override only when reset, contradiction, or reclassification evidence makes the internal recommendation suspect.
+   Normalize the user's answer before calling the start helper: \`trim\`, lower-case, map UI labels to \`lean\` / \`guided\` / \`deep\` only; if the answer is not one of those three, re-ask the same question once with the compact definitions. In \`flow-state.json\`, persist only the canonical lowercase token (never \`Deep\`/\`Guided\` casing).
+   If the user prompt is one short line (at most 12 words) and the workspace matches an empty-repo signal set — either \`flow-state.repoSignals\` from the last successful \`start-flow\` shows \`fileCount < 5\` with \`hasReadme\` and \`hasPackageManifest\` both false, OR (before any \`start-flow\` yet) a shallow scan finds no root \`README.md\`, no root \`package.json\`/\`pyproject.toml\`/\`Cargo.toml\`, and fewer than five relevant files excluding \`node_modules\`/\`.git\` — recommend \`guided\` and ask for explicit confirmation before defaulting to \`deep\`.
    If the harness's native ask tool is available (\`AskUserQuestion\` / \`AskQuestion\` / \`question\` / \`request_user_input\`), send exactly ONE question; on schema error, fall back to a plain-text lettered list.
 10. Start the tracked flow only through the managed helper:
-   \`node .cclaw/hooks/start-flow.mjs --track=<quick|medium|standard> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`
+   \`node .cclaw/hooks/start-flow.mjs --track=<quick|medium|standard> --discovery-mode=<lean|guided|deep> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`
    If this helper fails, STOP. Report one human-readable failure line from the JSON \`error\` field, include the helper JSON payload in a fenced \`json\` block, and never echo the invoking command line. Do **not** manually edit \`${flowPath}\`.
 11. The helper persists \`${flowPath}\`, computes \`skippedStages\`, sets the first stage for the track, resets the gate catalog, and writes \`.cclaw/artifacts/00-idea.md\`.
 12. Load the **first-stage skill for the chosen track** and its command file:
@@ -103,9 +105,9 @@ ${conversationLanguagePolicyMarkdown()}
 If during any stage the agent discovers evidence that contradicts the initial Phase 0 / track decision (e.g. a supposedly \`trivial\` change turns out to require schema migration, a \`quick\` bug fix turns out to need design discussion, an origin doc reveals scope 3× larger than the prompt), STOP and re-classify:
 
 1. Surface the new evidence in plain text.
-2. Propose the updated \`Class\` + \`Track\` with a one-line reason.
+2. Propose the updated \`Class\`, internal \`Track\`, and (when discovery posture should change) \`Discovery mode\` with a one-line reason.
 3. Use the Decision Protocol to let the user accept, override, or cancel.
-4. On acceptance: run \`node .cclaw/hooks/start-flow.mjs --reclassify --track=<new-track> --class=<new-class> --reason=<why>\`. The helper appends a \`Reclassification:\` entry to \`00-idea.md\` and updates flow state atomically. If it fails, STOP and report one human-readable line plus the helper JSON payload in a fenced \`json\` block; never echo the invoking command line. Do NOT manually edit \`flow-state.json\`.
+4. On acceptance: run \`node .cclaw/hooks/start-flow.mjs --reclassify --track=<new-track> --discovery-mode=<lean|guided|deep> --class=<new-class> --reason=<why>\`. The helper appends a \`Reclassification:\` entry to \`00-idea.md\` and updates flow state atomically. If it fails, STOP and report one human-readable line plus the helper JSON payload in a fenced \`json\` block; never echo the invoking command line. Do NOT manually edit \`flow-state.json\`.
 
 ### Without prompt (\`/cc\`)
 
@@ -153,7 +155,7 @@ description: "Unified entry point for the cclaw flow. No args = resume/next. Wit
 \`/cc\` is the **starting command** for cclaw. It intelligently routes:
 
 - **No arguments** → resumes or progresses an existing tracked flow; missing/fresh placeholder state blocks with start guidance
-- **With a prompt** → classifies the task, picks a track (quick/medium/standard), and starts the **first stage of that track** (not always brainstorm — e.g. the \`quick\` track starts at \`spec\`)
+- **With a prompt** → classifies the task, asks for one discovery mode (lean/guided/deep), resolves an internal track (quick/medium/standard), and starts the **first stage of that track** (not always brainstorm — e.g. the \`quick\` track starts at \`spec\`)
 
 ## HARD-GATE
 
@@ -174,7 +176,7 @@ ${conversationLanguagePolicyMarkdown()}
    - Ask: "Continue with reset? (A) Yes, start fresh (B) No, resume current flow"
    - If (B) → switch to Path B behavior.
    If \`completedStages\` is empty, all gate \`passed\` arrays are empty, and \`${RUNTIME_ROOT}/artifacts/00-idea.md\` is missing, treat it as a fresh init placeholder — do **not** ask whether to continue the current flow.
-7. **Classify the idea** using the heuristic below and present one compact Start framing summary (class, track, stack, origin docs, seed recalls, next action). Wait for explicit confirmation or override before mutating any state only when reset/conflict/ambiguity makes it necessary.
+7. **Classify the idea** using the heuristic below and present one compact Start framing summary (class, internal track recommendation, stack, origin docs, seed recalls, next action). Wait for explicit confirmation or override before mutating any state only when reset/conflict/ambiguity makes it necessary.
    - If \`${RUNTIME_ROOT}/config.yaml\` defines \`trackHeuristics\`, apply those vocabulary hints (\`fallback\`, \`tracks.<id>.{triggers,veto}\`) on top of built-in defaults. Evaluation order is fixed: \`standard -> medium -> quick\`. (Honest note: this is advisory prose; the LLM applies it, not a Node-level router.)
 
    **Track heuristic** (lowercase substring match against the user prompt):
@@ -187,12 +189,15 @@ ${conversationLanguagePolicyMarkdown()}
 
    - On conflict, prefer \`standard\` over \`medium\`, and \`medium\` over \`quick\`.
    - Always state the recommendation as a one-line reason citing matched triggers and a high/medium/low track selection confidence. Clarify that the heuristic is advisory until the managed helper writes state; after that, \`/cc\` follows the selected track. Include override guidance: switch to standard when architecture, schema, migration, security, or unclear scope appears; switch to medium when product framing is needed but architecture is known.
-8. Run the managed start helper: \`node .cclaw/hooks/start-flow.mjs --track=<quick|medium|standard> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`. The helper writes \`${flowPath}\`, computes \`skippedStages\`, resets the gate catalog, and writes \`${RUNTIME_ROOT}/artifacts/00-idea.md\`. If it fails, STOP, report one human-readable failure line from the JSON \`error\` field, and include the helper JSON payload in a fenced \`json\` block; do not echo the invoking command line, and do not manually edit flow state.
-9. Load and execute the **first stage skill of the chosen track** (\`brainstorm\` for medium/standard, \`spec\` for quick) plus its matching command file.
+8. Ask for the single explicit start choice: \`Lean / Guided / Deep\`. Use \`Guided\` as the recommended default unless the user clearly wants compact shaping or unusually deep probing. Keep track internal unless contradiction/reset/reclassification requires surfacing an override.
+   Normalize the answer (\`trim\`, lower-case) to exactly \`lean\` / \`guided\` / \`deep\` before invoking the start helper; re-ask once if the reply is not one of those. Pass only canonical lowercase tokens to \`--discovery-mode\`.
+   If the prompt is one short line (at most 12 words) and the workspace matches an empty-repo signal set — either persisted \`repoSignals\` has \`fileCount < 5\` with \`hasReadme\` and \`hasPackageManifest\` false, OR a shallow scan before the first \`start-flow\` shows the same — recommend \`guided\` and confirm before defaulting to \`deep\`.
+9. Run the managed start helper: \`node .cclaw/hooks/start-flow.mjs --track=<quick|medium|standard> --discovery-mode=<lean|guided|deep> --class=<class> --prompt=<prompt> --stack=<stack> --reason=<matched heuristic>\`. The helper writes \`${flowPath}\`, including \`discoveryMode\`, computes \`skippedStages\`, resets the gate catalog, and writes \`${RUNTIME_ROOT}/artifacts/00-idea.md\`. If it fails, STOP, report one human-readable failure line from the JSON \`error\` field, and include the helper JSON payload in a fenced \`json\` block; do not echo the invoking command line, and do not manually edit flow state.
+10. Load and execute the **first stage skill of the chosen track** (\`brainstorm\` for medium/standard, \`spec\` for quick) plus its matching command file.
 
 ### Reclassification on discovery
 
-If mid-stage evidence contradicts the initial Class/Track decision (the "trivial" change needs a migration, the "quick" bug fix needs architecture work, an origin doc multiplies scope), STOP and re-classify using the Decision Protocol. On acceptance, run \`node .cclaw/hooks/start-flow.mjs --reclassify --track=<new-track> --class=<new-class> --reason=<why>\`; the helper records \`Reclassification:\` in \`00-idea.md\` and updates state atomically. If it fails, report one human-readable line plus the helper JSON payload in a fenced \`json\` block, never echo the invoking command line, and do not rewrite prior artifacts or manually edit flow-state.
+If mid-stage evidence contradicts the initial Class/Track/Discovery decision (the "trivial" change needs a migration, the "quick" bug fix needs architecture work, an origin doc multiplies scope), STOP and re-classify using the Decision Protocol. On acceptance, run \`node .cclaw/hooks/start-flow.mjs --reclassify --track=<new-track> --discovery-mode=<lean|guided|deep> --class=<new-class> --reason=<why>\`; the helper records \`Reclassification:\` in \`00-idea.md\` and updates state atomically. If it fails, report one human-readable line plus the helper JSON payload in a fenced \`json\` block, never echo the invoking command line, and do not rewrite prior artifacts or manually edit flow-state.
 
 ### Path B: \`/cc\` (no arguments)
 
@@ -217,6 +222,6 @@ Use \`/cc\` for the happy path:
 | Progressing after completing a stage | \`/cc\` |
 | Starting with a specific idea | \`/cc <idea>\` |
 
-\`/cc <prompt>\` resolves class + track and starts that track's first stage; \`/cc\` without a prompt follows the current \`flow-state.json\`.
+\`/cc <prompt>\` resolves class + internal track, asks for one discovery mode, and starts the selected track's first stage; \`/cc\` without a prompt follows the current \`flow-state.json\`.
 `;
 }

package/dist/content/subagents.js

@@ -18,7 +18,7 @@ function automaticStageDelegationTable() {
 |---|---|---|
 ${rows}
 
-> **Track-aware skip (Wave 24, v6.0.0):** mandatory agents are skipped entirely when \`track === "quick"\` OR \`taskClass === "software-bugfix"\`. Use \`mandatoryAgentsFor(stage, track, taskClass)\` from \`src/content/stage-schema.ts\` for the authoritative list at runtime. Proactive agents stay enforced because they fire only on triggers (high blast radius, security-sensitive paths, etc.), not on every run.`;
+> **Track-aware skip (Wave 24, v6.0.0):** mandatory agents are skipped entirely when \`track === "quick"\` OR \`taskClass === "software-bugfix"\`. Use \`mandatoryAgentsFor(stage, track, taskClass)\` from \`src/content/stage-schema.ts\` for the authoritative list at runtime. Proactive agents are trigger-driven opportunities, not a blanket completion gate, and lean/lightweight early-stage runs may intentionally record none.`;
 }
 function stageSummary(stage) {
     return stageDelegationSummary("standard").find((row) => row.stage === stage)

package/dist/content/templates.d.ts

@@ -7,5 +7,5 @@ export declare const RULEBOOK_MARKDOWN = "# Cclaw Rulebook\n\n## MUST_ALWAYS\n-
  * (premature draft, premature subagent dispatch, command-line echo to chat).
  */
 export declare const CURSOR_GUIDELINES_RULE_MDC = "---\ndescription: cclaw zero-install behavior baseline (always-on)\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-guidelines-rule -->\n\n# Cclaw Baseline Guidelines\n\nThese three rules apply to every Cursor agent session in this project,\nregardless of whether stage skills loaded.\n\n## 1. Q&A floor before drafting (brainstorm/scope/design)\n\nBefore drafting any `.cclaw/artifacts/01-brainstorm-*.md`,\n`02-scope-*.md`, or `03-design-*.md`, verify that the artifact's\n`## Q&A Log` table demonstrates Ralph-Loop convergence: every\nforcing-question topic id is tagged `[topic:<id>]` on at least one row\n(see the stage's forcing-questions checklist for the id list), the last\n2 turns produce no new decision-changing impact, OR an explicit user\nstop-signal row is recorded. Walk the stage forcing questions one at a\ntime via the `AskQuestion` tool. If you find yourself proposing a\ndraft after 1-2 questions while forcing topic ids remain untagged, STOP\nand continue the loop.\n\nThe `qa_log_unconverged` linter rule will block `stage-complete` when\nconvergence has not been reached. Wave 24 (v6.0.0) made `[topic:<id>]`\ntagging mandatory; the English keyword fallback was removed because it\nmis-reported convergence on RU/UA Q&A logs.\n\n## 2. Mandatory subagents run after Q&A approval\n\nFor brainstorm / scope / design, mandatory subagents (\n`product-discovery`, `critic`, `planner`, `architect`,\n`test-author`) run **only AFTER the user approves the elicitation\noutcome**, never before the Q&A loop converges. Dispatching them early\npreempts the user dialogue and violates the elicitation contract \u2014 the\nlinter will block stage-complete.\n\nSee each stage's \"Run Phase: post-elicitation\" rows in the materialized\nAutomatic Subagent Dispatch table.\n\n## 3. Never echo cclaw command lines to chat\n\nThe user does not run cclaw helpers (`node .cclaw/hooks/...`) manually.\nNEVER paste full command lines, `--evidence-json '{...}'` payloads,\n`--waive-delegation=...`, or shell hash commands (`shasum`,\n`sha256sum`, `Get-FileHash`, `certutil`, etc.) into chat. Run the\nhelper via the tool layer and report only the resulting summary. On\nfailure, report a compact human-readable summary plus the helper JSON in\na single fenced `json` block.\n";
-export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n## Activation Rule\n\nBefore responding to coding work:\n1. Read `.cclaw/state/flow-state.json`.\n2. Start with `/cc` or continue with `/cc`.\n3. If no software-stage flow applies, respond normally.\n\n## Stage Order\n\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nTrack-specific skips are allowed only when `flow-state.track` + `skippedStages` explicitly say so.\n\n## Task Classification\n\n| Class | Route |\n|---|---|\n| non-trivial software work | `/cc <idea>` |\n| trivial software fix | `/cc <idea>` (quick track) |\n| bugfix with repro | `/cc <idea>` and enforce RED-first in tdd |\n| pure question / non-software | direct answer (no stage flow) |\n\n## Command Surface\n\n- `/cc` = entry and resume.\n- `/cc` = only progression path.\n- Knowledge capture and recall use the `learnings` skill when requested.\n\n## Verification Discipline\n\n- No completion claim without fresh command evidence in this turn.\n- Do not mark gates passed from memory.\n- Keep evidence in `.cclaw/artifacts/`; archive through closeout via `/cc` or cancel early via `node .cclaw/hooks/cancel-run.mjs`.\n\n## Delegation And Approvals\n\n- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.\n- **For brainstorm / scope / design stages**: ask user input continuously via adaptive elicitation (one question per turn through the harness-native question tool \u2014 `AskQuestion` in Cursor). Walk the stage forcing-questions list one-by-one. **Tag each Q&A Log row's `Decision impact` cell with `[topic:<id>]`** (the id is given in the stage's forcing-questions checklist) so the linter can verify coverage in any natural language. Do NOT batch and do NOT defer to a single approval gate at the end. The `qa_log_unconverged` linter rule will block `stage-complete` when convergence is not reached (forcing topic ids untagged AND last 2 turns still produce decision-changing rows AND no stop-signal).\n- **For other stages** (spec/plan/tdd/build/review/ship): ask user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization), not for routine progress updates.\n- If you find yourself proposing a draft after 1-2 questions in brainstorm/scope/design, STOP \u2014 go back to the forcing-questions list and continue.\n- Mandatory subagents in brainstorm/scope/design run only AFTER the user approves the elicitation outcome (see each stage's \"Run Phase: post-elicitation\" rows). Dispatching them before the Q&A loop converges violates the contract.\n- Never echo cclaw command lines (`node .cclaw/hooks/...`, `--evidence-json '{...}'`) to chat \u2014 the user does not run cclaw manually. Run helpers via the tool layer; report only the resulting summary.\n- If harness capabilities are partial, record waiver reasons in delegation logs.\n\n## Routing Source Of Truth\n\n- Primary router: `.cclaw/skills/using-cclaw/SKILL.md`.\n- Stage behavior: current stage skill plus `.cclaw/state/flow-state.json`.\n- Preamble budget: keep role/status announcements brief and avoid repeating\n  them unless the stage or role changes.\n";
+export declare const CURSOR_WORKFLOW_RULE_MDC = "---\ndescription: cclaw workflow guardrails for Cursor agent sessions\nglobs:\n  - \"**/*\"\nalwaysApply: true\n---\n\n<!-- cclaw-managed-cursor-workflow-rule -->\n\n# Cclaw Workflow Guardrails\n\n## Activation Rule\n\nBefore responding to coding work:\n1. Read `.cclaw/state/flow-state.json`.\n2. Start with `/cc` or continue with `/cc`.\n3. If no software-stage flow applies, respond normally.\n\n## Stage Order\n\n`brainstorm -> scope -> design -> spec -> plan -> tdd -> review -> ship`\n\nTrack-specific skips are allowed only when `flow-state.track` + `skippedStages` explicitly say so.\n\n## Task Classification\n\n| Class | Route |\n|---|---|\n| non-trivial software work | `/cc <idea>` |\n| trivial software fix | `/cc <idea>` (quick track) |\n| bugfix with repro | `/cc <idea>` and enforce RED-first in tdd |\n| pure question / non-software | direct answer (no stage flow) |\n\n## Command Surface\n\n- `/cc` = entry and resume.\n- `/cc` = only progression path.\n- Knowledge capture and recall use the `learnings` skill when requested.\n\n## Verification Discipline\n\n- No completion claim without fresh command evidence in this turn.\n- Stage completion claim requires `stage-complete` exit 0 in the current turn. Quote the success line; do not paraphrase, do not infer success from skipped retries.\n- Do not mark gates passed from memory.\n- Keep evidence in `.cclaw/artifacts/`; archive through closeout via `/cc` or cancel early via `node .cclaw/hooks/cancel-run.mjs`.\n\n## Delegation And Approvals\n\n- Machine-only checks in design/plan/tdd/review/ship should auto-dispatch when tooling supports it.\n- **For brainstorm / scope / design stages**: ask user input continuously via adaptive elicitation (one question per turn through the harness-native question tool \u2014 `AskQuestion` in Cursor). Walk the stage forcing-questions list one-by-one. **Tag each Q&A Log row's `Decision impact` cell with `[topic:<id>]`** (the id is given in the stage's forcing-questions checklist) so the linter can verify coverage in any natural language. Do NOT batch and do NOT defer to a single approval gate at the end. The `qa_log_unconverged` linter rule will block `stage-complete` when convergence is not reached (forcing topic ids untagged AND last 2 turns still produce decision-changing rows AND no stop-signal).\n- **For other stages** (spec/plan/tdd/build/review/ship): ask user input only at explicit approval gates (scope mode, plan approval, challenge resolution, ship finalization), not for routine progress updates.\n- If you find yourself proposing a draft after 1-2 questions in brainstorm/scope/design, STOP \u2014 go back to the forcing-questions list and continue.\n- Mandatory subagents in brainstorm/scope/design run only AFTER the user approves the elicitation outcome (see each stage's \"Run Phase: post-elicitation\" rows). Dispatching them before the Q&A loop converges violates the contract.\n- Never echo cclaw command lines (`node .cclaw/hooks/...`, `--evidence-json '{...}'`) to chat \u2014 the user does not run cclaw manually. Run helpers via the tool layer; report only the resulting summary.\n- If harness capabilities are partial, record waiver reasons in delegation logs.\n\n## Routing Source Of Truth\n\n- Primary router: `.cclaw/skills/using-cclaw/SKILL.md`.\n- Stage behavior: current stage skill plus `.cclaw/state/flow-state.json`.\n- Preamble budget: keep role/status announcements brief and avoid repeating\n  them unless the stage or role changes.\n";
 export declare function buildRulesJson(): Record<string, unknown>;

package/dist/content/templates.js

@@ -1565,6 +1565,7 @@ Track-specific skips are allowed only when \`flow-state.track\` + \`skippedStage
 ## Verification Discipline
 
 - No completion claim without fresh command evidence in this turn.
+- Stage completion claim requires \`stage-complete\` exit 0 in the current turn. Quote the success line; do not paraphrase, do not infer success from skipped retries.
 - Do not mark gates passed from memory.
 - Keep evidence in \`.cclaw/artifacts/\`; archive through closeout via \`/cc\` or cancel early via \`node .cclaw/hooks/cancel-run.mjs\`.
 

package/dist/delegation.js

@@ -481,9 +481,9 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
     // via `flow-state.json`. Forward-typed `null` callers still suppress
     // the lookup explicitly; only `undefined` triggers the fallback.
     const resolvedTaskClass = options.taskClass !== undefined ? options.taskClass : flowState.taskClass ?? null;
-    const mandatory = mandatoryAgentsFor(stage, flowState.track, resolvedTaskClass);
+    const mandatory = mandatoryAgentsFor(stage, flowState.track, resolvedTaskClass, "standard", flowState.discoveryMode);
     const skippedByTrack = mandatory.length === 0 &&
-        stageSchema(stage, flowState.track).mandatoryDelegations.length > 0;
+        stageSchema(stage, flowState.track, flowState.discoveryMode, resolvedTaskClass).mandatoryDelegations.length > 0;
     if (skippedByTrack) {
         await recordMandatorySkippedByTrack(projectRoot, {
             stage,

package/dist/flow-state.d.ts

@@ -1,6 +1,13 @@
-import type { FlowStage, FlowTrack, TransitionRule } from "./types.js";
+import type { DiscoveryMode, FlowStage, FlowTrack, TransitionRule } from "./types.js";
 export declare const TRANSITION_RULES: TransitionRule[];
 export declare const FLOW_STATE_SCHEMA_VERSION = 1;
+/** Snapshot from `collectRepoSignals` at last successful `start-flow` (optional on older states). */
+export interface RepoSignals {
+    fileCount: number;
+    hasReadme: boolean;
+    hasPackageManifest: boolean;
+    capturedAt: string;
+}
 export interface StageGateState {
     required: string[];
     recommended: string[];
@@ -76,6 +83,8 @@ export interface FlowState {
     stageGateCatalog: Record<FlowStage, StageGateState>;
     /** Active flow track (determines which stages are in the critical path for this run). */
     track: FlowTrack;
+    /** Run-level upstream shaping mode chosen once at start (`lean` / `guided` / `deep`). */
+    discoveryMode: DiscoveryMode;
     /**
      * Wave 25 (v6.1.0) — optional task class for the active run.
      *
@@ -102,6 +111,8 @@ export interface FlowState {
     retro: RetroState;
     /** Ship → post_ship_review → archive substate for resumable closeout. */
     closeout: CloseoutState;
+    /** Repo shape signals captured at last successful start-flow (omit on legacy files). */
+    repoSignals?: RepoSignals;
 }
 export interface StageInteractionHint {
     skipQuestions?: boolean;
@@ -123,8 +134,10 @@ export interface StageInteractionHint {
 export interface InitialFlowStateOptions {
     activeRunId?: string;
     track?: FlowTrack;
+    discoveryMode?: DiscoveryMode;
 }
 export declare function isFlowTrack(value: unknown): value is FlowTrack;
+export declare function isDiscoveryMode(value: unknown): value is DiscoveryMode;
 export declare function trackStages(track: FlowTrack): FlowStage[];
 export declare function skippedStagesForTrack(track: FlowTrack): FlowStage[];
 export declare function firstStageForTrack(track: FlowTrack): FlowStage;

package/dist/flow-state.js

@@ -1,5 +1,5 @@
 import { buildTransitionRules, orderedStageSchemas, stageGateIds, stageRecommendedGateIds } from "./content/stage-schema.js";
-import { FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "./types.js";
+import { DISCOVERY_MODES, FLOW_STAGES, FLOW_TRACKS, TRACK_STAGES } from "./types.js";
 export const TRANSITION_RULES = buildTransitionRules();
 export const FLOW_STATE_SCHEMA_VERSION = 1;
 /**
@@ -47,6 +47,9 @@ export function createInitialCloseoutState() {
 export function isFlowTrack(value) {
     return typeof value === "string" && FLOW_TRACKS.includes(value);
 }
+export function isDiscoveryMode(value) {
+    return typeof value === "string" && DISCOVERY_MODES.includes(value);
+}
 export function trackStages(track) {
     return [...TRACK_STAGES[track]];
 }
@@ -67,6 +70,7 @@ export function createInitialFlowState(activeRunIdOrOptions = {}, maybeTrack) {
         : activeRunIdOrOptions;
     const activeRunId = options.activeRunId ?? createRunId();
     const track = options.track ?? "standard";
+    const discoveryMode = options.discoveryMode ?? "guided";
     const skippedStages = skippedStagesForTrack(track);
     const stageGateCatalog = {};
     for (const schema of orderedStageSchemas(track)) {
@@ -87,6 +91,7 @@ export function createInitialFlowState(activeRunIdOrOptions = {}, maybeTrack) {
         guardEvidence: {},
         stageGateCatalog,
         track,
+        discoveryMode,
         skippedStages,
         staleStages: {},
         rewinds: [],

package/dist/gate-evidence.js

@@ -210,7 +210,7 @@ const DESIGN_RESEARCH_REQUIRED_SECTIONS = [
 ];
 export async function verifyCurrentStageGateEvidence(projectRoot, flowState, options = {}) {
     const stage = flowState.currentStage;
-    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")
@@ -462,6 +462,7 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState, opt
         const skipQuestionsHint = flowState.interactionHints?.[stage]?.skipQuestions === true ||
             (options.extraStageFlags ?? []).includes("--skip-questions");
         const floor = evaluateQaLogFloor(qaLogBody, flowState.track, stage, {
+            discoveryMode: flowState.discoveryMode,
             skipQuestions: skipQuestionsHint
         });
         qaLogFloor = {
@@ -498,7 +499,7 @@ export function verifyCompletedStagesGateClosure(flowState) {
     const issues = [];
     const openStages = [];
     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")
@@ -526,7 +527,7 @@ export function verifyCompletedStagesGateClosure(flowState) {
 }
 export function reconcileCurrentStageGateCatalog(flowState) {
     const stage = flowState.currentStage;
-    const schema = stageSchema(stage, flowState.track);
+    const schema = stageSchema(stage, flowState.track, flowState.discoveryMode, flowState.taskClass ?? null);
     const required = schema.requiredGates
         .filter((gate) => gate.tier === "required")
         .map((gate) => gate.id);