muonroi-cli 1.8.4 → 1.9.0

package/dist/src/product-loop/gather.js

@@ -2,12 +2,18 @@
 // Dispatcher that wires the discover phase into the adaptive interview flow.
 // buildDiscoveryDebateRunner ← Task 16
 // buildGatherUserPrompt      ← Task 17
-import { resolveLeaderModelDetailed } from "../council/leader.js";
+import { runClarification } from "../council/clarifier.js";
+import { resolveLeaderModelDetailed, resolveParticipants } from "../council/leader.js";
+import { isCouncilMultiProviderPreferred } from "../utils/settings.js";
 import { detectExistingProject } from "./discovery-detection.js";
 import { iterateInterview, } from "./discovery-interview.js";
-import { acquireRunLock, initDiscoveryState, readDiscoveryState, readProjectContext, releaseRunLock, resumeArtifactWriteIfNeeded, } from "./discovery-persistence.js";
+import { acquireRunLock, initDiscoveryState, markDone, readDiscoveryState, readProjectContext, releaseRunLock, resumeArtifactWriteIfNeeded, writeProjectContext, } from "./discovery-persistence.js";
 import { parsePromptForContext } from "./discovery-prompt-parser.js";
 import { councilRecommend, leaderRecommend, shouldFallbackToLeader } from "./discovery-recommender.js";
+import { DISCOVERY_QUESTIONS } from "./discovery-schema.js";
+import { triageInterview } from "./discovery-triage.js";
+import { buildRepoBrief } from "./repo-brief.js";
+import { SEED_DIMENSIONS } from "./seed-questions.js";
 /**
  * Decide whether detection signals are STRONG enough to synthesize a
  * backendStack answer (skipping the interview question). Returns null when
@@ -251,6 +257,30 @@ llm, sessionModelId, io) {
             },
             prefillAnswers: { ...prefillFromDetection, ...prompted },
         });
+        // Unified agent-driven interview (default). The LLM leader generates every
+        // clarification question itself from the idea + injected context and emits
+        // its own askcards — the same engine `/council` uses (runClarification) —
+        // instead of walking the fixed DISCOVERY_QUESTIONS list. The CLI only
+        // injects context (repo brief / prompt-extracted hints); it hardcodes no
+        // questions. Requires a wired driver (emit + respondToQuestion); pure-unit
+        // callers without io fall through to the legacy fixed-question path below.
+        // Opt out with MUONROI_IDEAL_AGENT_INTERVIEW=0.
+        if (process.env.MUONROI_IDEAL_AGENT_INTERVIEW !== "0" && io?.emit && io?.respondToQuestion) {
+            return await runAgentDrivenGather({
+                flowDir,
+                runId,
+                idea,
+                cwd,
+                detection,
+                leaderModelId,
+                sessionModelId,
+                llm: llm,
+                prompted,
+                prefillFromDetection,
+                emit: io.emit,
+                respondToQuestion: io.respondToQuestion,
+            });
+        }
         // Recommender: always leader-only. The council debate runner (Task 16) is
         // a stub that throws; until it is wired we delegate council asks to the
         // leader so the gather phase doesn't crash on greenfield projects with
@@ -270,6 +300,22 @@ llm, sessionModelId, io) {
         // (only hit by tests that don't supply io).
         const tuiAsk = io?.emit && io?.respondToQuestion ? buildLiveTuiAsk(io.emit, io.respondToQuestion) : async () => "";
         const userPrompt = buildGatherUserPrompt(tuiAsk);
+        // Model-decided interview triage — the PRIMARY signal for how deep to
+        // interview (replaces the keyword `computePromptSpecificity` heuristic as the
+        // lead). A trivial idea (e.g. a hello-world script) collapses to ONE confirm
+        // card instead of 6 generic productType/audience/architecture/db cards; a
+        // complex idea keeps only the questions the model flags as decision-shaping.
+        // Only the required questions are triaged (optional ones are gated separately).
+        // Never throws — degrades to the specificity fallback (see discovery-triage.ts).
+        const requiredQuestions = DISCOVERY_QUESTIONS.filter((q) => q.required);
+        const triage = await triageInterview(idea, leader, requiredQuestions);
+        if (process.env.MUONROI_DEBUG_LEADER === "1") {
+            process.stderr.write(`[interview-triage] ${JSON.stringify({
+                complexity: triage.complexity,
+                relevant: triage.relevant,
+                source: triage.source,
+            })}\n`);
+        }
         return await iterateInterview({
             flowDir,
             runId,
@@ -278,6 +324,7 @@ llm, sessionModelId, io) {
             detection,
             userPrompt,
             recommender,
+            triage,
         });
     }
     finally {
@@ -285,6 +332,90 @@ llm, sessionModelId, io) {
     }
 }
 // ---------------------------------------------------------------------------
+// Agent-driven interview (unified clarifier engine)
+// ---------------------------------------------------------------------------
+/**
+ * Run the gather interview by delegating to the SAME agent-driven clarifier the
+ * council uses (`runClarification`): the LLM leader generates its own
+ * clarification questions from the idea + injected context, emits its own
+ * `council_question` askcards, self-judges readiness, and synthesizes a
+ * `ClarifiedSpec`. The CLI contributes only context (repo brief for existing
+ * repos, prompt-extracted hints) and the askcard plumbing — it hardcodes no
+ * questions and no answer enums.
+ *
+ * Output is a `ProjectContext` that carries the clarifier's `ClarifiedSpec`
+ * verbatim (`clarified`), so `clarifiedSpecFromContext` returns the real
+ * LLM-synthesized successCriteria/constraints/scope instead of re-deriving a
+ * thin persona+scale spec. `context` is populated best-effort from detection +
+ * prompt hints purely as a supplement for the (fully-guarded) downstream
+ * `formatProjectContextForPrompt`.
+ */
+async function runAgentDrivenGather(args) {
+    // Context the CLI injects for the agent to interview AGAINST — never questions.
+    let conversationContext = "";
+    if (args.detection.classification !== "greenfield") {
+        try {
+            const brief = await buildRepoBrief(args.cwd, args.detection);
+            // The "## Current Project" header switches the clarifier into existing-repo
+            // mode (drops generic greenfield questions, grounds rationales in real files).
+            conversationContext += `## Current Project\n${brief.markdown}\n\n`;
+        }
+        catch {
+            // Brief failure must NEVER block the interview — fall through context-light.
+        }
+    }
+    if (Object.keys(args.prompted).length > 0) {
+        conversationContext += `## Extracted from the request\n${JSON.stringify(args.prompted, null, 2)}\n`;
+    }
+    // Reachable panel models — passed as the clarifier's fallbackModels so its
+    // research-first step can prefer a native-web-research model on any reachable
+    // provider (and spec-synth can fall back off a flaky leader proxy). Never
+    // blocks gather: resolution failure degrades to leader-only.
+    let panelModels = [];
+    try {
+        const participants = await resolveParticipants(args.sessionModelId, isCouncilMultiProviderPreferred());
+        panelModels = participants.map((p) => p.model).filter(Boolean);
+    }
+    catch {
+        // leader-only reachability is fine — research-first still runs on the leader.
+    }
+    // Drive the clarifier generator; forward each emitted chunk to the driver so
+    // the TUI renders each dynamically-generated askcard, then capture the spec.
+    // seedQuestions is intentionally empty — the clarifier's own research-first
+    // step (runClarification) now grounds the questions; no CLI-owned seed list.
+    const gen = runClarification(args.idea, args.leaderModelId, conversationContext, args.respondToQuestion, args.llm, undefined, // signal — no abort wired through gather today
+    undefined, // seedQuestions
+    undefined, // maxRounds → clarifier default
+    undefined, // prefillAnswers
+    false, // costAware
+    panelModels);
+    let result;
+    do {
+        result = await gen.next();
+        if (!result.done && result.value)
+            args.emit(result.value);
+    } while (!result.done);
+    const clarified = result.value;
+    const context = { ...args.prefillFromDetection, ...args.prompted };
+    const projectContext = {
+        version: 1,
+        schemaName: "project-context",
+        generatedAt: new Date().toISOString(),
+        idea: args.idea,
+        detection: args.detection,
+        context,
+        clarified,
+        recommendations: {
+            byField: {},
+            constraints: { fePolicy: "headless-ui-only", feEnforced: true },
+        },
+        userOverrides: [],
+    };
+    await writeProjectContext(args.flowDir, args.runId, projectContext);
+    await markDone(args.flowDir, args.runId);
+    return projectContext;
+}
+// ---------------------------------------------------------------------------
 // ClarifiedSpec bridge
 // ---------------------------------------------------------------------------
 /**
@@ -294,6 +425,23 @@ llm, sessionModelId, io) {
  * has passed (or all required questions are answered).
  */
 export function clarifiedSpecFromContext(pc) {
+    // Agent-driven path: the clarifier already synthesized a full ClarifiedSpec
+    // (real LLM-derived successCriteria/constraints/scope + rawQA). Return it
+    // verbatim, deriving the loop-driver resolution gate from the agent's OWN
+    // readiness judgment rather than the hardcoded 6-dimension answered-check:
+    // when the clarifier declared the spec ready (or didn't flag it not-ready),
+    // mark every SEED_DIMENSION resolved so the gate passes; otherwise leave them
+    // unspecified so the existing insufficient_resolution safety net still fires.
+    if (pc.clarified) {
+        const ready = pc.clarified.ready !== false;
+        const status = ready ? "answered" : "unspecified";
+        const resolved = {
+            ...(pc.clarified.resolved ?? {}),
+        };
+        for (const d of SEED_DIMENSIONS)
+            resolved[d.id] = status;
+        return { ...pc.clarified, resolved };
+    }
     const ctx = pc.context;
     const problemStatement = pc.idea;
     const constraints = [];

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