muonroi-cli 1.8.3 → 1.8.5

package/dist/src/playbook/directives.js

@@ -17,6 +17,12 @@
  * All directive text is English. The agent is responsible for translating
  * user-facing prompts into the user's language at render time.
  */
+/** When true and tier is standard/heavy, CHECK-PLAN points to gsd_plan_review tool. */
+export function buildNativeCheckPlanHint() {
+    return ("  4. CHECK-PLAN — call gsd_plan_review (native council) BEFORE executing. " +
+        "Multi-perspective review spawns research/skeptic/architect sub-agents; leader synthesizes PLAN-VERIFY.md. " +
+        "gsd_execute is blocked until verdict: pass.");
+}
 const HEADER = "[playbook]";
 /**
  * High-precision predicate: is this turn about the Muonroi ECOSYSTEM (where the
@@ -60,12 +66,15 @@ export function buildLanguageNudge(lang) {
 // senior-engineer reasoning over labeled scaffolds — feedback 12eceab7).
 function buildHeavy(input) {
     const phaseHint = input.phase ? ` (hint: this reads like a "${input.phase}" task)` : "";
+    const checkPlan = input.nativeGsd
+        ? buildNativeCheckPlanHint()
+        : "  4. CHECK-PLAN — review your own plan BEFORE executing: does it cover the acceptance criteria, handle the edge cases, and match what the user actually asked? Revise until it does (update the todo_write list if steps change). Confirm with the user only if the plan diverges from their intent.";
     return [
         `${HEADER} This reads like a HEAVY task${phaseHint} — architectural, cross-cutting, multi-file, or with real unresolved design choices. Don't start editing yet; work through these phases:`,
         "  1. DISCUSS — surface the decisions/ambiguities that actually change the design. For the ones the prompt doesn't already answer, ask up front with AskUserQuestion (put your recommended option first; write the question text in the user's language). Skip questions the prompt already settles — don't interrogate.",
-        "  2. RESEARCH — gather the codebase facts the task depends on: read/grep the relevant modules, and dispatch parallel research Agents when the areas are independent. When you delegate, give each sub-agent a NON-overlapping scope and tell it the exact return shape you need (findings as file:line + a one-line conclusion) — only the sub's final synthesis re-enters your context. Ground every later decision in what you actually found, not assumptions.",
-        "  3. PLAN — write a concrete, numbered plan: the change per file, the order, and the acceptance criteria (how you'll know it's done). Then record the plan as a todo_write checklist (one item per step) so the user sees a live progress list.",
-        "  4. CHECK-PLAN — review your own plan BEFORE executing: does it cover the acceptance criteria, handle the edge cases, and match what the user actually asked? Revise until it does (update the todo_write list if steps change). Confirm with the user only if the plan diverges from their intent.",
+        "  2. RESEARCH — gather the codebase facts the task depends on: read/grep the relevant modules, and dispatch parallel research Agents when the areas are independent. When you delegate (via `delegate`), give each sub-agent a NON-overlapping scope and tell it the exact return shape you need. Regularly check background tasks and subagents using `delegation_list` / `delegation_read` (or `process_list` / `process_logs` for shell processes) to monitor progress, and terminate them with `delegation_kill` / `process_stop` if they are no longer needed.",
+        "  3. PLAN — write a concrete, numbered plan via gsd_plan (or PLAN.md): the change per file, the order, and the acceptance criteria (how you'll know it's done). Then record the plan as a todo_write checklist (one item per step) so the user sees a live progress list.",
+        checkPlan,
         "  5. IMPLEMENT — execute in atomic steps; parallelize independent work. Keep the todo_write list accurate: mark each item in_progress before you start it and completed when it lands (exactly ONE item in_progress at a time). When you're in a git repo, COMMIT each completed chunk before starting the next one (small, logically-scoped commits; message ends with the mandatory attribution line) — do NOT pile the whole task into one commit at the end.",
         "  6. VERIFY — run the relevant tests / lint / type-check and report evidence (command + result) before claiming done.",
         "This depth is a recommendation from how the task reads. If, once you look, it's genuinely smaller than it appears, say so and drop to the STANDARD flow rather than over-processing it.",
@@ -92,10 +101,13 @@ function buildStandard(input) {
             "If the limits are blown and you still have no fix, STOP and report what you tried + why you're stuck.",
         ].join("\n");
     }
+    const checkStep = input.nativeGsd
+        ? "  2. CHECK — call gsd_plan_review (lightweight council: research + skeptic perspectives) before editing files."
+        : "  2. CHECK — sanity-check that plan against the real code (read the key files you named) and against the user's intent; fix the plan if reality differs. If a genuine ambiguity blocks you, ask ONE focused question via AskUserQuestion instead of guessing.";
     return [
         `${HEADER} This reads like a STANDARD task${phaseHint} — work like a senior engineer, but keep it lightweight:`,
-        "  1. PLAN — state a short, concrete plan: the files/functions you'll touch and in what order. A few bullets in your reply, not an essay. If it breaks into ≥3 steps, also record them with todo_write so the user gets a live checklist.",
-        "  2. CHECK — sanity-check that plan against the real code (read the key files you named) and against the user's intent; fix the plan if reality differs. If a genuine ambiguity blocks you, ask ONE focused question via AskUserQuestion instead of guessing.",
+        "  1. PLAN — state a short, concrete plan via gsd_plan: the files/functions you'll touch and in what order. A few bullets in your reply, not an essay. If it breaks into ≥3 steps, also record them with todo_write so the user gets a live checklist.",
+        checkStep,
         "  3. IMPLEMENT — execute the plan in small steps with the appropriate tools. If you made a todo_write checklist, keep it updated as you go (exactly one item in_progress at a time). When you're in a git repo, COMMIT each cohesive chunk as it lands (small commits; message ends with the mandatory attribution line) rather than batching everything into one final commit.",
         "  4. VERIFY — run the relevant tests / type-check / quick smoke and report evidence before claiming done.",
         "You don't need subagents or a discussion round for this. But if it turns out to be architectural or spans many files, escalate to the HEAVY flow (discuss → research → checked plan) rather than charging ahead.",

package/dist/src/product-loop/backlog-builder.d.ts

@@ -8,7 +8,7 @@
  * — NO hardcoded model id or provider anywhere in this file.
  */
 import type { ClarifiedSpec, CouncilLLM } from "../council/types.js";
-import type { Backlog, ImplementationPlanArtifact } from "./types.js";
+import type { Backlog, EffortPoints, ImplementationPlanArtifact } from "./types.js";
 export interface BuildBacklogInput {
     runId: string;
     productSlug: string;
@@ -18,6 +18,19 @@ export interface BuildBacklogInput {
     leaderModelId: string;
     costAware: boolean;
 }
+/**
+ * Deterministic keyword heuristic for a story-point prior (1 | 3 | 5).
+ *
+ * Used as the FALLBACK when the LLM effort estimate fails or returns unparseable
+ * JSON — cheap models (deepseek) often emit malformed arrays, and the previous
+ * flat-3 fallback made every item identical, so sprint bin-packing degenerated
+ * into a mechanical "≈2-3 items per sprint" split with no relation to real size
+ * (observed live: a "migrate 5 native modules" item and a "remove dependency"
+ * item both scored 3). A rough size signal from the title is strictly better than
+ * uniform. Verb-driven: creation/migration reads large, deletion/config reads
+ * small, everything else medium.
+ */
+export declare function heuristicEffort(title: string): EffortPoints;
 /**
  * Build a Backlog from a ClarifiedSpec + the Phase 1 implementation_plan artifact.
  *

package/dist/src/product-loop/backlog-builder.js

@@ -23,11 +23,35 @@ function hashSpec(spec) {
 function keywordMatch(haystack, needle) {
     return haystack.toLowerCase().includes(needle.toLowerCase());
 }
+/**
+ * Deterministic keyword heuristic for a story-point prior (1 | 3 | 5).
+ *
+ * Used as the FALLBACK when the LLM effort estimate fails or returns unparseable
+ * JSON — cheap models (deepseek) often emit malformed arrays, and the previous
+ * flat-3 fallback made every item identical, so sprint bin-packing degenerated
+ * into a mechanical "≈2-3 items per sprint" split with no relation to real size
+ * (observed live: a "migrate 5 native modules" item and a "remove dependency"
+ * item both scored 3). A rough size signal from the title is strictly better than
+ * uniform. Verb-driven: creation/migration reads large, deletion/config reads
+ * small, everything else medium.
+ */
+export function heuristicEffort(title) {
+    const t = title.toLowerCase();
+    const large = /\b(implement|build|create|migrat\w*|rewrite|refactor|orchestrat\w*|engine|subsystem|native|integrat\w*|pipeline|architect\w*)\b/;
+    const small = /\b(remove|delete|drop|inventory|rename|config\w*|flag|doc\w*|cleanup|wire|rename|bump|stub|export)\b/;
+    if (large.test(t))
+        return 5;
+    if (small.test(t))
+        return 1;
+    return 3;
+}
 /**
  * Ask the LLM to estimate effortPoints for a batch of feature titles in a
  * single call. Parses JSON array response: [1, 3, 5, ...].
  *
- * Falls back to 3 (medium) for any item that fails to parse correctly.
+ * Falls back to a per-title keyword heuristic ({@link heuristicEffort}) — NOT a
+ * flat 3 — for any item the LLM fails to score, so sprint packing keeps a real
+ * size signal even when the cheap model returns garbage.
  *
  * Model selection: pickCouncilTaskModel("effort_estimate", leaderModelId, costAware)
  */
@@ -46,25 +70,25 @@ async function estimateEffortBatch(titles, llm, leaderModelId, costAware) {
         raw = await llm.generate(model, system, prompt, 256);
     }
     catch {
-        // Graceful degrade: default everything to M=3
-        return titles.map(() => 3);
+        // Graceful degrade: keyword heuristic prior per title (NOT flat 3).
+        return titles.map((t) => heuristicEffort(t));
     }
     try {
         const match = raw.match(/\[[\s\S]*\]/);
         if (match) {
             const arr = JSON.parse(match[0]);
-            return titles.map((_, i) => {
+            return titles.map((t, i) => {
                 const v = arr[i];
                 if (v === 1 || v === 3 || v === 5)
                     return v;
-                return 3;
+                return heuristicEffort(t); // this item unscored/invalid → heuristic, not flat 3
             });
         }
     }
     catch {
         // JSON parse failed — fall through
     }
-    return titles.map(() => 3);
+    return titles.map((t) => heuristicEffort(t));
 }
 /**
  * Build a Backlog from a ClarifiedSpec + the Phase 1 implementation_plan artifact.

package/dist/src/product-loop/discovery-context-format.js

@@ -34,7 +34,9 @@ export function formatProjectContextForPrompt(ctx) {
         lines.push(`Backend stack: ${lang} / ${fw}${runtime}`);
     }
     if (c.dbStrategy) {
-        lines.push(`Database: ${c.dbStrategy.mode ?? "(unspecified)"} ${c.dbStrategy.engine ?? ""}`.trimEnd());
+        lines.push(c.dbStrategy.mode === "none"
+            ? "Database: none (stateless — no persistent storage)"
+            : `Database: ${c.dbStrategy.mode ?? "(unspecified)"} ${c.dbStrategy.engine ?? ""}`.trimEnd());
     }
     if (c.frontendApproach) {
         const harness = c.frontendApproach.agentHarness

package/dist/src/product-loop/discovery-ecosystem.js

@@ -164,7 +164,10 @@ export function buildEcosystemPreamble() {
         "- Angular with @muonroi/agent-harness-angular directive.",
         'When recommending `frontendApproach`, ALWAYS fill the optional `agentHarness` slot — pick "react" for React/Next, "angular" for Angular, "opentui" for terminal UI, "core" for non-DOM integration. Only use "none" when the project has no UI at all.',
         "",
-        "Recommend non-ecosystem options ONLY when the user's prompt explicitly opts out (e.g. mentions Node.js/Express/Django by name).",
+        "Strongest-default, still extensible:",
+        "- Keep the Muonroi/.NET path as the PRIMARY recommendation — it is the ecosystem's strongest, best-supported option.",
+        "- BUT for stack choices (architecture/stack/platform) ALWAYS include at least one mainstream NON-ecosystem alternative in `alternatives` (pick what genuinely fits the task — e.g. Python for data/ML/scripting, Go or Rust for a fast static-binary CLI, Node/TypeScript for JS-native tooling), with a one-line rationale. A user outside the Muonroi ecosystem must always see a real, viable path — never a .NET-only menu.",
+        "- Promote the non-ecosystem option to PRIMARY only when the prompt names another stack, or the task is a poor fit for .NET (e.g. a shell-glue one-liner, a data-science notebook, an npm-ecosystem plugin). Otherwise it stays a first-class alternative, not the default.",
     ].join("\n");
 }
 /**

package/dist/src/product-loop/discovery-interview.js

@@ -3,6 +3,13 @@ import { appendUserOverride, buildProjectContextFromState, markDone, markUserGat
 import { computePromptSpecificity, toEntry, } from "./discovery-recommender.js";
 import { DISCOVERY_QUESTIONS, isFePolicyAccepted, isRequiredForPlatform, REQUIRED_QUESTION_IDS, validateAnswer, } from "./discovery-schema.js";
 import { buildRepoBrief } from "./repo-brief.js";
+/**
+ * Under existing-repo collapse, keep ONLY these questions as interactive
+ * per-field cards — they are the fields whose answers actually shape the
+ * technical change. Everything else in DISCOVERY_QUESTIONS is auto-filled and
+ * surfaced together on the compact __user_gate__ confirm card.
+ */
+const KEEP_CARD_FOR_EXISTING = new Set(["backendArchitecture"]);
 export async function iterateInterview(opts) {
     const { flowDir, runId, detection } = opts;
     const _itvDbg = process.env.MUONROI_DEBUG_LEADER === "1";
@@ -20,7 +27,18 @@ export async function iterateInterview(opts) {
     // but optional ones (baStatus, designStatus, deployment, frontendApproach when
     // not web) are deferred unless the user explicitly re-runs with more context.
     const specificity = computePromptSpecificity(opts.idea);
-    const skipOptionalForMinimal = specificity === "minimal";
+    // Existing-codebase work (refactor / migration / feature-add on a repo that
+    // already has source) should NOT re-run the full greenfield product-scoping
+    // questionnaire. productType/audience/targetPlatform/frontend/design/deployment
+    // are derivable from the codebase and inert for the technical change — asking
+    // them per-field is the over-ask users complained about. For any non-greenfield
+    // classification (existing OR ambiguous polyglot) we collapse to the ONE
+    // decision-relevant card (backendArchitecture) plus the compact "assumed from
+    // codebase" confirm gate (the same __user_gate__ path used for minimal/detailed
+    // prompts). This mirrors the repoBrief-build condition below. Escape hatch:
+    // MUONROI_DISCOVERY_EXISTING_COLLAPSE=0 restores the full per-field interview.
+    const collapseForExisting = detection.classification !== "greenfield" && process.env.MUONROI_DISCOVERY_EXISTING_COLLAPSE !== "0";
+    const skipOptionalForMinimal = specificity === "minimal" || collapseForExisting;
     // G2-b: for a minimal OR well-specified ("detailed") prompt the recommender's
     // primary is high-confidence — minimal picks smallest-scope defaults, detailed
     // respects the stated context. In both cases surfacing a card for EVERY
@@ -30,7 +48,8 @@ export async function iterateInterview(opts) {
     // (the user gate) listing the assumptions so the user can proceed or adjust.
     // "moderate" prompts keep the per-question cards (genuinely ambiguous). Escape
     // hatch: MUONROI_DISCOVERY_AUTOFILL=0 restores per-question cards everywhere.
-    const autoFillRequired = (specificity === "minimal" || specificity === "detailed") && process.env.MUONROI_DISCOVERY_AUTOFILL !== "0";
+    const autoFillRequired = (specificity === "minimal" || specificity === "detailed" || collapseForExisting) &&
+        process.env.MUONROI_DISCOVERY_AUTOFILL !== "0";
     const assumed = [];
     // G1 follow-up: keep the recommendation behind each auto-filled assumption so
     // the user-gate "edit: <field>" path can re-render the SAME per-question card
@@ -94,7 +113,17 @@ export async function iterateInterview(opts) {
         // policy) so a malformed recommendation falls back to the normal card flow.
         // The assumed answers are surfaced together on the single user-gate card.
         let autoAccepted = false;
-        if (autoFillRequired && effectivelyRequired && recommendation.primary?.value != null) {
+        // Keep backendArchitecture interactive under existing-repo collapse (the one
+        // field whose answer shapes the technical work), and NEVER silently auto-accept
+        // a weakly-grounded recommendation (synthFailed = the rationale failed the
+        // repo-brief citation check twice) — fall through to a per-question card so the
+        // user can catch a hallucinated value instead of it being assumed.
+        const keepInteractive = collapseForExisting && KEEP_CARD_FOR_EXISTING.has(question.id);
+        if (autoFillRequired &&
+            effectivelyRequired &&
+            recommendation.primary?.value != null &&
+            !recommendation.synthFailed &&
+            !keepInteractive) {
             const v = recommendation.primary.value;
             const validation = validateAnswer(question.id, v);
             const feLib = question.id === "frontendApproach" ? v?.library : undefined;

package/dist/src/product-loop/discovery-schema.js

@@ -18,7 +18,7 @@ export const DISCOVERY_QUESTIONS = [
         id: "dbStrategy",
         required: true,
         recommendMode: "council",
-        prompt: "Database strategy: greenfield, existing schema, or migration?",
+        prompt: "Database strategy: none (stateless — no persistent storage), greenfield, existing schema, or migration? Choose none for a CLI/tool/filter that keeps no data.",
     },
     {
         id: "frontendApproach",
@@ -74,6 +74,10 @@ export function getSchemaHintForLeader(questionId) {
             return `value MUST be an object {"persona": string, "scale": one of ${Array.from(SCALES)
                 .map((s) => JSON.stringify(s))
                 .join("|")}, "geography": string}`;
+        case "dbStrategy":
+            // F7 — give the recommender an explicit "no persistence" option so it
+            // stops mis-ranking "greenfield" for stateless products (CLI/tool/filter).
+            return `value MUST be an object {"mode": one of "none"|"greenfield"|"existing-schema"|"migrate-from", "engine": string, "notes"?: string}. Pick "mode":"none" with "engine":"" when the product keeps NO persistent data (e.g. a stateless CLI, filter, or one-shot tool) — do NOT default to "greenfield" in that case.`;
         case "frontendApproach":
             return `value MUST be an object {"library": one of ${Array.from(ACCEPTED_FE_LIBRARIES)
                 .map((l) => JSON.stringify(l))

package/dist/src/product-loop/done-gate.js

@@ -142,9 +142,9 @@ async function runCustomerDebate(ctx) {
     const criteriaText = ctx.criteria
         .map((c) => `- ${c.id}: ${c.status}${c.evidence ? ` (Evidence: ${c.evidence})` : ""}`)
         .join("\n");
-    let conversation = `System: You are in a "Definition of Done" debate. 
-PO's goal: Prove the product is ready to ship.
-Customer's goal: Ensure all requirements are met and it's high quality.
+    let conversation = `System: You are in a "Definition of Done" debate. 
+PO's goal: Prove the product is ready to ship.
+Customer's goal: Ensure all requirements are met and it's high quality.
 Criteria:\n${criteriaText}\n`;
     for (let r = 1; r <= rounds; r++) {
         const poPrompt = `${conversation}\nRound ${r}: PO, explain why this is ready to ship.`;

package/dist/src/product-loop/ideal-trace.d.ts

@@ -0,0 +1,7 @@
+export declare function isIdealTraceEnabled(): boolean;
+/**
+ * Emit one diagnostic breadcrumb. `marker` is a stable dotted label
+ * (e.g. "council.persist.writeDecisionsLock.before"); `extra` carries small
+ * scalar context (sessionId, answer, lengths) — keep it tiny, this runs inline.
+ */
+export declare function idealTrace(marker: string, extra?: Record<string, unknown>): void;

package/dist/src/product-loop/ideal-trace.js

@@ -0,0 +1,64 @@
+// src/product-loop/ideal-trace.ts
+//
+// Env-gated diagnostic tracer for the /ideal → council → sprint path.
+//
+// WHY THIS EXISTS
+// ---------------
+// "blocker 5" — the observed but non-deterministic "Plan locked → idle" stall
+// after the sprint-planning debate synthesis — could not be root-caused from a
+// harness run because greenfield almost always halts at CB3 first, and the tail
+// path (post-debate menu → persist → writeDecisionsLock → stats → return, then
+// sprint-runner's Implementation stage) has no durable breadcrumb. When the flow
+// goes idle mid-tail, there is nothing to say WHICH line was last reached.
+//
+// This tracer writes one synchronous JSONL line per choke point when
+// `MUONROI_IDEAL_TRACE` is set. Synchronous (`appendFileSync`) is deliberate: if
+// the process hangs or is killed at the stall, the LAST line in the file is the
+// last point the flow reached — an async write could be lost to an unflushed
+// buffer. Unset → zero behaviour change (no file, no stderr, single env read).
+//
+// USAGE
+//   MUONROI_IDEAL_TRACE=1                         → <tmpdir>/muonroi-ideal-trace.jsonl
+//   MUONROI_IDEAL_TRACE=/path/to/ideal-trace.log  → explicit path
+// Then reproduce the stall and read the file; the trailing marker is the hang.
+import { appendFileSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/**
+ * Resolve the trace sink for the CURRENT env value, or null when disabled.
+ * Not cached — the flag is fixed for a CLI session, and re-reading env per call
+ * is trivial on this (slow, non-hot) council path; caching would wrongly pin an
+ * early "disabled" read for the whole process.
+ */
+function tracePath() {
+    const raw = process.env.MUONROI_IDEAL_TRACE;
+    if (!raw || raw === "0" || raw === "false")
+        return null;
+    return raw === "1" || raw === "true" ? path.join(os.tmpdir(), "muonroi-ideal-trace.jsonl") : raw;
+}
+export function isIdealTraceEnabled() {
+    return tracePath() !== null;
+}
+/**
+ * Emit one diagnostic breadcrumb. `marker` is a stable dotted label
+ * (e.g. "council.persist.writeDecisionsLock.before"); `extra` carries small
+ * scalar context (sessionId, answer, lengths) — keep it tiny, this runs inline.
+ */
+export function idealTrace(marker, extra) {
+    const file = tracePath();
+    if (!file)
+        return;
+    const record = { ts: new Date().toISOString(), marker, ...extra };
+    const line = JSON.stringify(record);
+    try {
+        appendFileSync(file, `${line}\n`, "utf8");
+    }
+    catch (err) {
+        // Best-effort diagnostics: a bad path must never break the council/sprint
+        // flow. Surface once on stderr so a misconfigured path is noticed.
+        process.stderr.write(`[ideal-trace] append failed (${file}): ${err?.message}\n`);
+    }
+    // Mirror to stderr so it also lands in MUONROI_DEBUG_LLM_WIRE-style captures.
+    process.stderr.write(`[ideal-trace] ${line}\n`);
+}
+//# sourceMappingURL=ideal-trace.js.map

package/dist/src/product-loop/index.d.ts

@@ -18,7 +18,7 @@ export interface ProductLoopOptions {
     /** Required for resume/abort/ship/status<runId>. */
     runId?: string;
     /** Subcommand selector. Default = start. */
-    subcommand?: "start" | "status" | "resume" | "abort" | "ship";
+    subcommand?: "start" | "status" | "resume" | "abort" | "ship" | "review";
     flowDir: string;
     /** Session model id from the orchestrator (this.modelId). Used to resolve real council models. */
     sessionModelId: string;
@@ -29,6 +29,8 @@ export interface ProductLoopOptions {
     /** Optional bridges; sprint-runner uses them when present. */
     cwd?: string;
     processMessageFn?: (message: string) => AsyncGenerator<StreamChunk, void, unknown>;
+    /** Isolated bounded task-runner bridge — see DriverContext.runIsolatedTask. */
+    runIsolatedTask?: (request: import("../types/index.js").TaskRequest) => Promise<import("../types/index.js").ToolResult>;
     detectVerifyRecipe?: () => Promise<VerifyRecipe | null>;
     /** Test hook: pre-resolved role assignments so the harness can pin model ids. */
     roleAssignments?: Map<RoleSlot, {
@@ -53,6 +55,16 @@ export interface ProductLoopOptions {
      * not set, the dispatcher routes to runHotPath (single sprint, no council debate).
      */
     complexity?: "low" | "medium" | "high";
+    /**
+     * LLM-decided clarity signal (PIL Layer 1 `needsClarification`). When true the
+     * request is UNDERSPECIFIED — the model judged it lacks information it would
+     * need to proceed without guessing. It earns the interview/Council path even
+     * on an existing repo where a well-specified `standard` task would hot-path.
+     * Agent-first replacement for the regex sufficiency scorer: only `quick`
+     * (complexity=low) tasks still hot-path when underspecified — a trivial ask is
+     * not worth an interview no matter how terse.
+     */
+    needsClarification?: boolean;
     /**
      * Sufficiency gaps from PIL Layer 1. When non-empty, the dispatcher forces
      * the Council path regardless of complexity — vague prompts MUST go through