cclaw-cli 6.1.1 → 6.2.0

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/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,14 @@ ${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.
    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 +103,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 +153,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 +174,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 +187,13 @@ ${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.
+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.
+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.
 9. 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 +218,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/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,4 +1,4 @@
-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;
 export interface StageGateState {
@@ -76,6 +76,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.
      *
@@ -123,8 +125,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);

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);
@@ -530,7 +530,8 @@ 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
     });
     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,14 @@ export function parseStartFlowArgs(tokens) {
             track = raw;
             continue;
         }
+        if (token === "--discovery-mode" || token.startsWith("--discovery-mode=")) {
+            const raw = readValue("--discovery-mode").trim();
+            if (!isDiscoveryMode(raw)) {
+                throw new Error(`--discovery-mode must be one of: lean, guided, deep.`);
+            }
+            discoveryMode = raw;
+            continue;
+        }
         if (token === "--class" || token.startsWith("--class=")) {
             className = readValue("--class").trim();
             continue;
@@ -281,6 +290,7 @@ export function parseStartFlowArgs(tokens) {
     }
     return {
         track,
+        discoveryMode,
         className,
         prompt,
         reason,

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

@@ -0,0 +1,19 @@
+import { type StageAutoSubagentDispatch } from "../../content/stage-schema.js";
+import type { DiscoveryMode, FlowStage } from "../../types.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;
+}): Promise<ProactiveDelegationTraceResult>;

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

@@ -0,0 +1,44 @@
+import { appendDelegation, readDelegationLedger } from "../../delegation.js";
+import { stageAutoSubagentDispatch } from "../../content/stage-schema.js";
+function isEarlyElicitationStage(stage) {
+    return stage === "brainstorm" || stage === "scope" || stage === "design";
+}
+/**
+ * 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");
+    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.js

@@ -7,6 +7,12 @@ 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;
+}
 export async function discoverStartFlowContext(projectRoot) {
     const lines = [];
     const seedFiles = (await listFilesUnder(projectRoot, path.join(RUNTIME_ROOT, "seeds"), 10))
@@ -58,6 +64,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 +75,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 +93,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 +107,7 @@ export async function runStartFlow(projectRoot, args, io) {
         }
         nextState = {
             ...fresh,
+            ...(nextTaskClass !== undefined ? { taskClass: nextTaskClass } : {}),
             completedStages: completedInNewTrack,
             currentStage: firstIncompleteStageForTrack(args.track, completedInNewTrack),
             guardEvidence,
@@ -117,7 +127,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 ?? {};
@@ -140,6 +153,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[]>;