muonroi-cli 1.7.1 → 1.8.0

package/dist/src/council/__tests__/council-turn-length-emit.test.js

@@ -0,0 +1,130 @@
+/**
+ * council-turn-length emit contract (G2-b).
+ *
+ * Drives the REAL `runDebate` generator with a recording CouncilLLM and a
+ * capturing `globalThis.__muonroiAgentRuntime`, then asserts the observe-only
+ * `council-turn-length` harness event fires for each fully-assembled speaker
+ * turn — opening statements (round 0) and discussion turns (round 1+) — carrying
+ * the right charCount / wordCount / round / model / correlationId.
+ *
+ * This exercises the production emit path in src/council/debate.ts end-to-end
+ * (not a mocked re-implementation). The MCP harness tool surface only exposes
+ * toast/stream.delta via tui_last_event, so this generator-level drive is the
+ * faithful wire-level proof that the event fires during a real council run.
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { runDebate } from "../debate.js";
+const OPENING = "Opening alpha beta gamma."; // 25 chars, 4 words
+const ROUND = "Round response one two three."; // round-turn text
+function recordingLlm() {
+    return {
+        // openingWithRetry + leader-eval + summaries all go through generate. Opening
+        // statements use the returned text verbatim → that drives the round-0 emit.
+        generate: async () => OPENING,
+        // debateWithRetry (discussion turns) is the ONLY caller of debate → drives the
+        // round-1+ emit with a known, non-failure string.
+        debate: async () => ({ text: ROUND, toolCalls: [] }),
+        research: async () => "findings",
+    };
+}
+function makeParticipants() {
+    return [
+        { role: "architect", model: "model-arch", position: "", stance: { name: "architect", lens: "design" } },
+        { role: "qa", model: "model-qa", position: "", stance: { name: "qa", lens: "risk" } },
+    ];
+}
+function makeSpec() {
+    return {
+        problemStatement: "Decide X vs Y for a small service.",
+        constraints: [],
+        successCriteria: [],
+        scope: "",
+        rawQA: [],
+    };
+}
+function makeConfig(participants) {
+    return {
+        topic: "X vs Y",
+        conversationContext: "",
+        leaderModelId: "model-leader",
+        participants,
+        debatePlan: {
+            intentSummary: "Pick the better option.",
+            stances: [
+                { name: "architect", lens: "design" },
+                { name: "qa", lens: "risk" },
+            ],
+            outputShape: {
+                kind: "decision",
+                sections: [{ key: "rec", heading: "Recommendation", shape: "list" }],
+                guardrails: [],
+            },
+            plannedRounds: 1,
+        },
+        // Skip research so the flow goes straight to opening statements deterministically.
+        researchSkipOverride: true,
+        runId: "sess-turnlen-test",
+    };
+}
+describe("council-turn-length emit (real runDebate)", () => {
+    let captured;
+    let prevRuntime;
+    beforeEach(() => {
+        captured = [];
+        const g = globalThis;
+        prevRuntime = g.__muonroiAgentRuntime;
+        g.__muonroiAgentRuntime = { emitEvent: (e) => captured.push(e) };
+    });
+    afterEach(() => {
+        globalThis.__muonroiAgentRuntime = prevRuntime;
+    });
+    function turnLengthEvents() {
+        return captured.filter((e) => e.t === "event" && e.kind === "council-turn-length");
+    }
+    it("emits a round-0 event per opening speaker with correct counts + correlationId", async () => {
+        const participants = makeParticipants();
+        const gen = runDebate(makeSpec(), makeConfig(participants), recordingLlm());
+        let step = await gen.next();
+        while (!step.done)
+            step = await gen.next();
+        const opening = turnLengthEvents().filter((e) => e.round === 0);
+        // One opening statement per participant.
+        expect(opening.length).toBe(2);
+        for (const e of opening) {
+            expect(e.charCount).toBe(OPENING.length);
+            expect(e.wordCount).toBe(4);
+            expect(e.correlationId).toBe("sess-turnlen-test");
+            expect(typeof e.model).toBe("string");
+            expect(e.model.length).toBeGreaterThan(0);
+        }
+        // Roles are the participant stance names / roles.
+        const roles = opening.map((e) => e.role);
+        expect(roles).toContain("architect");
+        expect(roles).toContain("qa");
+    });
+    it("emits round-1 discussion-turn events with the discussion text's counts", async () => {
+        const gen = runDebate(makeSpec(), makeConfig(makeParticipants()), recordingLlm());
+        let step = await gen.next();
+        while (!step.done)
+            step = await gen.next();
+        const round1 = turnLengthEvents().filter((e) => e.round === 1);
+        expect(round1.length).toBeGreaterThanOrEqual(1);
+        for (const e of round1) {
+            expect(e.charCount).toBe(ROUND.trim().length);
+            expect(e.wordCount).toBe(ROUND.trim().split(/\s+/).filter(Boolean).length);
+            expect(e.correlationId).toBe("sess-turnlen-test");
+        }
+    });
+    it("does not emit when no agent runtime is installed (normal user mode)", async () => {
+        globalThis.__muonroiAgentRuntime = undefined;
+        const localCaptured = [];
+        // Re-install a capturer AFTER clearing to prove the helper truly no-ops when
+        // the runtime is absent: here it's absent, so localCaptured stays empty.
+        const gen = runDebate(makeSpec(), makeConfig(makeParticipants()), recordingLlm());
+        let step = await gen.next();
+        while (!step.done)
+            step = await gen.next();
+        expect(localCaptured.length).toBe(0);
+    });
+});
+//# sourceMappingURL=council-turn-length-emit.test.js.map

package/dist/src/council/__tests__/debate-round-budget.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/council/__tests__/debate-round-budget.test.js

@@ -0,0 +1,45 @@
+/**
+ * C (latency UX) — per-kind debate round cap. Before this, only implementation_plan
+ * was capped (3); a `decision` debate inherited the absolute ceiling (8) and ran as
+ * many rounds as the planner proposed. Live, a Redis-vs-in-memory decision ran 5
+ * rounds / ~10 min with the leader itself calling rounds 4-5 "minor disagreements".
+ * resolveDebateRoundBudget now caps the discussion kinds at 3 (exploration 5).
+ */
+import { describe, expect, it } from "vitest";
+import { resolveDebateRoundBudget } from "../debate.js";
+describe("resolveDebateRoundBudget — per-kind round cap (issue C)", () => {
+    it("caps a decision at 3 rounds even when the planner proposes 5", () => {
+        const r = resolveDebateRoundBudget("decision", 5);
+        expect(r.maxRounds).toBe(3);
+        expect(r.effectiveCeiling).toBe(3);
+        expect(r.kindCapped).toBe(true);
+    });
+    it("caps evaluation and investigation at 3", () => {
+        expect(resolveDebateRoundBudget("evaluation", 8).maxRounds).toBe(3);
+        expect(resolveDebateRoundBudget("investigation", 8).maxRounds).toBe(3);
+    });
+    it("keeps implementation_plan at its existing 3-round cap", () => {
+        expect(resolveDebateRoundBudget("implementation_plan", 5).maxRounds).toBe(3);
+    });
+    it("allows exploration more breadth (5)", () => {
+        const r = resolveDebateRoundBudget("exploration", 8);
+        expect(r.maxRounds).toBe(5);
+        expect(r.effectiveCeiling).toBe(5);
+    });
+    it("falls back to the absolute ceiling (8) for an unknown kind", () => {
+        const r = resolveDebateRoundBudget("something-else", 7);
+        expect(r.maxRounds).toBe(7);
+        expect(r.effectiveCeiling).toBe(8);
+        expect(r.kindCapped).toBe(false);
+    });
+    it("uses the default budget (3) when the planner proposes nothing", () => {
+        expect(resolveDebateRoundBudget("decision", undefined).maxRounds).toBe(3);
+        expect(resolveDebateRoundBudget(undefined, undefined).maxRounds).toBe(3);
+        expect(resolveDebateRoundBudget(undefined, 0).maxRounds).toBe(3);
+    });
+    it("respects a planner proposal lower than the cap", () => {
+        expect(resolveDebateRoundBudget("decision", 1).maxRounds).toBe(1);
+        expect(resolveDebateRoundBudget("implementation_plan", 2).maxRounds).toBe(2);
+    });
+});
+//# sourceMappingURL=debate-round-budget.test.js.map

package/dist/src/council/__tests__/evaluator-metrics.test.js

@@ -359,6 +359,7 @@ describe("CQ-10: planDebate returns FALLBACK_PLAN after double failure", () => {
         vi.doMock("../../providers/runtime.js", () => ({
             detectProviderForModel: vi.fn().mockReturnValue("openai"),
             createProviderFactory: vi.fn().mockReturnValue({ factory: {} }),
+            createProviderFactoryAsync: vi.fn().mockResolvedValue({ factory: {} }),
             resolveModelRuntime: vi.fn().mockReturnValue({ model: {}, providerOptions: undefined }),
         }));
         vi.doMock("../prompts.js", () => ({
@@ -401,6 +402,7 @@ describe("CQ-10: planDebate returns FALLBACK_PLAN after double failure", () => {
         vi.doMock("../../providers/runtime.js", () => ({
             detectProviderForModel: vi.fn().mockReturnValue("openai"),
             createProviderFactory: vi.fn().mockReturnValue({ factory: {} }),
+            createProviderFactoryAsync: vi.fn().mockResolvedValue({ factory: {} }),
             resolveModelRuntime: vi.fn().mockReturnValue({ model: {}, providerOptions: undefined }),
         }));
         vi.doMock("../prompts.js", () => ({
@@ -433,6 +435,7 @@ describe("CQ-10: planDebate returns FALLBACK_PLAN after double failure", () => {
         vi.doMock("../../providers/runtime.js", () => ({
             detectProviderForModel: vi.fn().mockReturnValue("openai"),
             createProviderFactory: vi.fn().mockReturnValue({ factory: {} }),
+            createProviderFactoryAsync: vi.fn().mockResolvedValue({ factory: {} }),
             resolveModelRuntime: vi.fn().mockReturnValue({ model: {}, providerOptions: undefined }),
         }));
         vi.doMock("../prompts.js", () => ({

package/dist/src/council/__tests__/post-debate-recommendation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/council/__tests__/post-debate-recommendation.test.js

@@ -0,0 +1,58 @@
+/**
+ * Issue #3 — post-debate default mismatch.
+ *
+ * Before the fix, `runCouncil`'s post-debate AskCard recommended "generate_plan"
+ * (Lock plan & execute Sprint 1) for ANY successful synthesis with no plan yet —
+ * ignoring `debatePlan.outputShape.kind`. For a pure decision/evaluation topic the
+ * user wanted a decision, not to build, so defaulting to "kick off a sprint" was
+ * the wrong next step. `pickPostDebateRecommendation` now only defaults to
+ * generate_plan for `implementation_plan`-shaped debates; everything else defaults
+ * to `save_exit` (the synthesis IS the deliverable). The generate_plan OPTION is
+ * still offered — only the pre-selected default changed.
+ */
+import { describe, expect, it } from "vitest";
+import { pickPostDebateRecommendation } from "../index.js";
+const base = {
+    synthesisFailed: false,
+    hasEmptySections: false,
+    refinementTopics: [],
+    confidenceLevel: "high",
+    hasPlan: false,
+};
+describe("pickPostDebateRecommendation — issue #3 default", () => {
+    it("defaults implementation_plan (no plan yet) to generate_plan", () => {
+        const r = pickPostDebateRecommendation({ ...base, outputKind: "implementation_plan" });
+        expect(r.value).toBe("generate_plan");
+    });
+    for (const kind of ["decision", "evaluation", "investigation", "exploration", "other"]) {
+        it(`defaults ${kind} (no plan) to save_exit, not generate_plan`, () => {
+            const r = pickPostDebateRecommendation({ ...base, outputKind: kind });
+            expect(r.value).toBe("save_exit");
+            // Reason names the shape so the card explains WHY save is the default.
+            expect(r.reason).toContain(kind);
+        });
+    }
+    it("retry_synthesis wins on synthesis failure regardless of kind", () => {
+        const r = pickPostDebateRecommendation({ ...base, synthesisFailed: true, outputKind: "decision" });
+        expect(r.value).toBe("retry_synthesis");
+    });
+    it("refine wins when the debate left sections empty", () => {
+        const r = pickPostDebateRecommendation({
+            ...base,
+            hasEmptySections: true,
+            refinementTopics: ["Risks", "Trade-offs"],
+            outputKind: "implementation_plan",
+        });
+        expect(r.value).toBe("refine");
+        expect(r.reason).toContain("2");
+    });
+    it("low confidence routes to ask_followup before the kind split", () => {
+        const r = pickPostDebateRecommendation({ ...base, confidenceLevel: "low", outputKind: "implementation_plan" });
+        expect(r.value).toBe("ask_followup");
+    });
+    it("an existing plan always defaults to save_exit", () => {
+        const r = pickPostDebateRecommendation({ ...base, hasPlan: true, outputKind: "implementation_plan" });
+        expect(r.value).toBe("save_exit");
+    });
+});
+//# sourceMappingURL=post-debate-recommendation.test.js.map

package/dist/src/council/__tests__/research-tools.test.js

@@ -51,6 +51,7 @@ describe("CQ-04: research() URL detection and gap annotation", () => {
             createProviderFactory: vi.fn().mockReturnValue({
                 factory: {},
             }),
+            createProviderFactoryAsync: vi.fn().mockResolvedValue({ factory: {} }),
             resolveModelRuntime: vi.fn().mockReturnValue({
                 model: {},
                 providerOptions: undefined,
@@ -93,6 +94,7 @@ describe("CQ-04: research() URL detection and gap annotation", () => {
         vi.doMock("../../providers/runtime.js", () => ({
             detectProviderForModel: vi.fn().mockReturnValue("openai"),
             createProviderFactory: vi.fn().mockReturnValue({ factory: {} }),
+            createProviderFactoryAsync: vi.fn().mockResolvedValue({ factory: {} }),
             resolveModelRuntime: vi.fn().mockReturnValue({ model: {}, providerOptions: undefined }),
         }));
         vi.doMock("../../tools/registry.js", () => ({
@@ -141,6 +143,7 @@ describe("CQ-03: research() MCP tool merge", () => {
         vi.doMock("../../providers/runtime.js", () => ({
             detectProviderForModel: vi.fn().mockReturnValue("openai"),
             createProviderFactory: vi.fn().mockReturnValue({ factory: {} }),
+            createProviderFactoryAsync: vi.fn().mockResolvedValue({ factory: {} }),
             resolveModelRuntime: vi.fn().mockReturnValue({ model: {}, providerOptions: undefined }),
         }));
         vi.doMock("../../tools/registry.js", () => ({
@@ -185,6 +188,7 @@ describe("CQ-03: research() MCP tool merge", () => {
         vi.doMock("../../providers/runtime.js", () => ({
             detectProviderForModel: vi.fn().mockReturnValue("openai"),
             createProviderFactory: vi.fn().mockReturnValue({ factory: {} }),
+            createProviderFactoryAsync: vi.fn().mockResolvedValue({ factory: {} }),
             resolveModelRuntime: vi.fn().mockReturnValue({ model: {}, providerOptions: undefined }),
         }));
         vi.doMock("../../tools/registry.js", () => ({

package/dist/src/council/__tests__/round-tools.test.js

@@ -33,6 +33,7 @@ describe("debate() call shape — tools off by default, on with explicit opt-in"
         vi.doMock("../../providers/runtime.js", () => ({
             detectProviderForModel: vi.fn().mockReturnValue("openai"),
             createProviderFactory: vi.fn().mockReturnValue({ factory: {} }),
+            createProviderFactoryAsync: vi.fn().mockResolvedValue({ factory: {} }),
             resolveModelRuntime: vi.fn().mockReturnValue({ model: {}, providerOptions: undefined }),
         }));
         vi.doMock("../prompts.js", () => ({
@@ -63,6 +64,7 @@ describe("debate() call shape — tools off by default, on with explicit opt-in"
         vi.doMock("../../providers/runtime.js", () => ({
             detectProviderForModel: vi.fn().mockReturnValue("openai"),
             createProviderFactory: vi.fn().mockReturnValue({ factory: {} }),
+            createProviderFactoryAsync: vi.fn().mockResolvedValue({ factory: {} }),
             resolveModelRuntime: vi.fn().mockReturnValue({ model: {}, providerOptions: undefined }),
         }));
         // Builtin tools — must contain grep+read_file so the filter keeps something
@@ -113,6 +115,7 @@ describe("debate() call shape — tools off by default, on with explicit opt-in"
         vi.doMock("../../providers/runtime.js", () => ({
             detectProviderForModel: vi.fn().mockReturnValue("openai"),
             createProviderFactory: vi.fn().mockReturnValue({ factory: {} }),
+            createProviderFactoryAsync: vi.fn().mockResolvedValue({ factory: {} }),
             resolveModelRuntime: vi.fn().mockReturnValue({ model: {}, providerOptions: undefined }),
         }));
         vi.doMock("../../tools/registry.js", () => ({
@@ -162,6 +165,7 @@ describe("CQ-07: debate() returns { text, toolCalls } — not bare string", () =
         vi.doMock("../../providers/runtime.js", () => ({
             detectProviderForModel: vi.fn().mockReturnValue("openai"),
             createProviderFactory: vi.fn().mockReturnValue({ factory: {} }),
+            createProviderFactoryAsync: vi.fn().mockResolvedValue({ factory: {} }),
             resolveModelRuntime: vi.fn().mockReturnValue({ model: {}, providerOptions: undefined }),
         }));
         vi.doMock("../../tools/registry.js", () => ({
@@ -209,6 +213,7 @@ describe("CQ-07: debate() returns { text, toolCalls } — not bare string", () =
         vi.doMock("../../providers/runtime.js", () => ({
             detectProviderForModel: vi.fn().mockReturnValue("openai"),
             createProviderFactory: vi.fn().mockReturnValue({ factory: {} }),
+            createProviderFactoryAsync: vi.fn().mockResolvedValue({ factory: {} }),
             resolveModelRuntime: vi.fn().mockReturnValue({ model: {}, providerOptions: undefined }),
         }));
         vi.doMock("../../tools/registry.js", () => ({
@@ -244,6 +249,7 @@ describe("CQ-07: debate() returns { text, toolCalls } — not bare string", () =
         vi.doMock("../../providers/runtime.js", () => ({
             detectProviderForModel: vi.fn().mockReturnValue("openai"),
             createProviderFactory: vi.fn().mockReturnValue({ factory: {} }),
+            createProviderFactoryAsync: vi.fn().mockResolvedValue({ factory: {} }),
             resolveModelRuntime: vi.fn().mockReturnValue({ model: {}, providerOptions: undefined }),
         }));
         vi.doMock("../../tools/registry.js", () => ({

package/dist/src/council/clarifier-question-cap.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * src/council/clarifier-question-cap.test.ts
+ *
+ * G2-a regression backstop. The clarifier prompt asks for "typically 0-2"
+ * questions and tells the model NOT to ask generic greenfield questions in an
+ * existing repo, but the model has repeatedly ignored both (session
+ * cfc711c57df0: 6 generic greenfield questions on "improve council quality").
+ * capClarifierQuestions enforces this deterministically in code. These tests
+ * pin that behaviour; the live council surfacing is verified via the MCP
+ * harness separately.
+ */
+export {};

package/dist/src/council/clarifier-question-cap.test.js

@@ -0,0 +1,73 @@
+/**
+ * src/council/clarifier-question-cap.test.ts
+ *
+ * G2-a regression backstop. The clarifier prompt asks for "typically 0-2"
+ * questions and tells the model NOT to ask generic greenfield questions in an
+ * existing repo, but the model has repeatedly ignored both (session
+ * cfc711c57df0: 6 generic greenfield questions on "improve council quality").
+ * capClarifierQuestions enforces this deterministically in code. These tests
+ * pin that behaviour; the live council surfacing is verified via the MCP
+ * harness separately.
+ */
+import { describe, expect, it } from "vitest";
+import { capClarifierQuestions, isGenericGreenfieldQuestion, MAX_CLARIFY_QUESTIONS_PER_ROUND } from "./clarifier.js";
+const scoped = (n) => Array.from({ length: n }, (_, i) => ({ question: `Scoped decision ${i} for this change?`, why: "scope" }));
+describe("isGenericGreenfieldQuestion", () => {
+    it("matches generic greenfield questions (English)", () => {
+        expect(isGenericGreenfieldQuestion({ question: "Who is the target audience?" })).toBe(true);
+        expect(isGenericGreenfieldQuestion({ question: "Which programming language should we use?" })).toBe(true);
+        expect(isGenericGreenfieldQuestion({ question: "Which database do you want?" })).toBe(true);
+        expect(isGenericGreenfieldQuestion({ question: "What is the deployment target?" })).toBe(true);
+        expect(isGenericGreenfieldQuestion({ question: "What kind of product is this?" })).toBe(true);
+    });
+    it("matches generic greenfield questions (Vietnamese)", () => {
+        expect(isGenericGreenfieldQuestion({ question: "Đối tượng người dùng là ai?" })).toBe(true);
+        expect(isGenericGreenfieldQuestion({ question: "Dùng ngôn ngữ lập trình nào?" })).toBe(true);
+        expect(isGenericGreenfieldQuestion({ question: "Cơ sở dữ liệu nào phù hợp?" })).toBe(true);
+    });
+    it("does NOT match scoped, change-specific questions", () => {
+        expect(isGenericGreenfieldQuestion({ question: "Should the clarifier cap be configurable?" })).toBe(false);
+        expect(isGenericGreenfieldQuestion({ question: "Phạm vi của thay đổi này là gì?", why: "scope" })).toBe(false);
+        expect(isGenericGreenfieldQuestion({ question: "Do we keep backward compat for the old flag?" })).toBe(false);
+    });
+});
+describe("capClarifierQuestions", () => {
+    it("hard-caps to MAX_CLARIFY_QUESTIONS_PER_ROUND when the model over-asks", () => {
+        const { kept, dropped } = capClarifierQuestions(scoped(6), false);
+        expect(kept.length).toBe(MAX_CLARIFY_QUESTIONS_PER_ROUND);
+        expect(dropped).toBe(6 - MAX_CLARIFY_QUESTIONS_PER_ROUND);
+    });
+    it("leaves a compliant 0-2 round untouched", () => {
+        expect(capClarifierQuestions(scoped(2), false)).toEqual({ kept: scoped(2), dropped: 0 });
+        expect(capClarifierQuestions([], false)).toEqual({ kept: [], dropped: 0 });
+    });
+    it("existing repo: drops generic greenfield questions then caps the rest", () => {
+        const qs = [
+            { question: "Who is the target audience?" },
+            { question: "Which framework should we use?" },
+            { question: "Should we preserve the legacy --flag for this change?" },
+            { question: "Is the cap value configurable via settings?" },
+        ];
+        const { kept, dropped } = capClarifierQuestions(qs, true);
+        expect(kept.every((q) => !isGenericGreenfieldQuestion(q))).toBe(true);
+        expect(kept.length).toBe(2); // 2 generic dropped → 2 scoped remain, within cap
+        expect(dropped).toBe(2);
+    });
+    it("existing repo: never zeroes out a round — keeps the top pick if all look generic", () => {
+        const allGeneric = [
+            { question: "Who is the target audience?" },
+            { question: "Which database?" },
+            { question: "What kind of product is this?" },
+        ];
+        const { kept, dropped } = capClarifierQuestions(allGeneric, true);
+        expect(kept.length).toBe(1);
+        expect(dropped).toBe(2);
+    });
+    it("greenfield topic (no Current Project snapshot): does NOT drop generics, only caps", () => {
+        const qs = [{ question: "Who is the target audience?" }, { question: "Which language?" }];
+        const { kept, dropped } = capClarifierQuestions(qs, false);
+        expect(kept.length).toBe(2); // legitimate for a greenfield build
+        expect(dropped).toBe(0);
+    });
+});
+//# sourceMappingURL=clarifier-question-cap.test.js.map

package/dist/src/council/clarifier.d.ts

@@ -3,6 +3,34 @@ import type { CouncilQuestionOption, StreamChunk } from "../types/index.js";
 import type { ClarifiedSpec, CouncilLLM, QuestionResponder } from "./types.js";
 /** P5: Hard cap on clarification rounds regardless of judge verdict. */
 export declare const MAX_CLARIFY_ROUNDS = 12;
+/**
+ * G2-a: Hard cap on clarifier questions SURFACED per round, regardless of how
+ * many the model emits. buildClarificationPrompt asks for "typically 0-2", but
+ * that soft hint has repeatedly been ignored (e.g. 6 generic greenfield
+ * questions on a scoped "improve council quality" topic). This deterministic
+ * cap enforces the documented target so the user is never carpet-bombed.
+ */
+export declare const MAX_CLARIFY_QUESTIONS_PER_ROUND = 2;
+export declare function isGenericGreenfieldQuestion(q: {
+    question: string;
+    why?: string;
+}): boolean;
+/**
+ * G2-a: deterministically enforce the clarifier's "typically 0-2 questions"
+ * rule. In an existing repo (`existingRepo` — a "## Current Project" snapshot
+ * is present) first drop generic greenfield questions the prompt already told
+ * the model not to ask; then hard-cap the remainder at
+ * MAX_CLARIFY_QUESTIONS_PER_ROUND. Never zero out a round that had questions —
+ * if every one looked generic, keep the model's top pick rather than asking
+ * nothing. Pure + exported so it is unit-testable in isolation.
+ */
+export declare function capClarifierQuestions<T extends {
+    question: string;
+    why?: string;
+}>(questions: T[], existingRepo: boolean): {
+    kept: T[];
+    dropped: number;
+};
 /**
  * P5: Call the readiness judge to determine whether the current spec + Q&A is
  * sufficient to start a productive debate, or whether critical gaps remain.
@@ -41,7 +69,7 @@ export interface ClarifyOptionsResult {
  * so the UI knows to suppress the "(Recommended)" tag.
  */
 export declare function buildClarifyOptions(suggestions: string[] | undefined, recommended?: string): ClarifyOptionsResult;
-export declare function runClarification(topic: string, leaderModelId: string, conversationContext: string, respondToQuestion: QuestionResponder, llm: CouncilLLM, _signal?: AbortSignal, seedQuestions?: GrayAreaQuestion[], maxRounds?: number, 
+export declare function runClarification(topic: string, leaderModelId: string, conversationContext: string, respondToQuestion: QuestionResponder, llm: CouncilLLM, signal?: AbortSignal, seedQuestions?: GrayAreaQuestion[], maxRounds?: number, 
 /**
  * Optional pre-filled answers keyed by seed-question id. When the loop's
  * discover phase has already proven a dimension from the project (e.g.

package/dist/src/council/clarifier.js

@@ -4,6 +4,47 @@ import { phaseDone, phaseError, phaseStart } from "./phase-events.js";
 import { buildClarificationPrompt, buildReadinessJudgePrompt, buildSpecSynthesisPrompt } from "./prompts.js";
 /** P5: Hard cap on clarification rounds regardless of judge verdict. */
 export const MAX_CLARIFY_ROUNDS = 12;
+/**
+ * G2-a: Hard cap on clarifier questions SURFACED per round, regardless of how
+ * many the model emits. buildClarificationPrompt asks for "typically 0-2", but
+ * that soft hint has repeatedly been ignored (e.g. 6 generic greenfield
+ * questions on a scoped "improve council quality" topic). This deterministic
+ * cap enforces the documented target so the user is never carpet-bombed.
+ */
+export const MAX_CLARIFY_QUESTIONS_PER_ROUND = 2;
+/**
+ * G2-a: Generic "greenfield" questions that the prompt already tells the model
+ * NOT to ask when a "## Current Project" snapshot is present (existing repo) —
+ * product type, target audience, which language/framework, which database,
+ * hosting/deploy target. Matched in both English and Vietnamese on the
+ * question + why text. Used only as an existing-repo filter; never applied to
+ * greenfield topics where these questions are legitimate.
+ */
+const GREENFIELD_QUESTION_RE = /\b(target audience|product type|what (kind|type) of (product|app|application)|which (programming )?language|which framework|which database|which db|hosting|deploy(ment)? target|tech stack)\b|đối tượng (người dùng|sử dụng)|loại (sản phẩm|ứng dụng)|ngôn ngữ (lập trình|nào)|framework nào|cơ sở dữ liệu|database nào|triển khai ở đâu/i;
+export function isGenericGreenfieldQuestion(q) {
+    return GREENFIELD_QUESTION_RE.test(`${q.question} ${q.why ?? ""}`);
+}
+/**
+ * G2-a: deterministically enforce the clarifier's "typically 0-2 questions"
+ * rule. In an existing repo (`existingRepo` — a "## Current Project" snapshot
+ * is present) first drop generic greenfield questions the prompt already told
+ * the model not to ask; then hard-cap the remainder at
+ * MAX_CLARIFY_QUESTIONS_PER_ROUND. Never zero out a round that had questions —
+ * if every one looked generic, keep the model's top pick rather than asking
+ * nothing. Pure + exported so it is unit-testable in isolation.
+ */
+export function capClarifierQuestions(questions, existingRepo) {
+    const before = questions.length;
+    let kept = questions;
+    if (existingRepo) {
+        const filtered = kept.filter((q) => !isGenericGreenfieldQuestion(q));
+        kept = filtered.length > 0 ? filtered : kept.slice(0, 1);
+    }
+    if (kept.length > MAX_CLARIFY_QUESTIONS_PER_ROUND) {
+        kept = kept.slice(0, MAX_CLARIFY_QUESTIONS_PER_ROUND);
+    }
+    return { kept, dropped: before - kept.length };
+}
 /**
  * P5: Call the readiness judge to determine whether the current spec + Q&A is
  * sufficient to start a productive debate, or whether critical gaps remain.
@@ -97,7 +138,7 @@ export function buildClarifyOptions(suggestions, recommended) {
     }
     return { options, defaultIndex };
 }
-export async function* runClarification(topic, leaderModelId, conversationContext, respondToQuestion, llm, _signal, seedQuestions, maxRounds, 
+export async function* runClarification(topic, leaderModelId, conversationContext, respondToQuestion, llm, signal, seedQuestions, maxRounds, 
 /**
  * Optional pre-filled answers keyed by seed-question id. When the loop's
  * discover phase has already proven a dimension from the project (e.g.
@@ -128,6 +169,11 @@ costAware = false) {
     // gaps from the previous readiness verdict, passed to the next question-generator
     let pendingGaps = [];
     for (let round = 0; round < max; round++) {
+        // User cancelled during clarification — stop asking further rounds. The
+        // generate calls themselves are already abort-aware (wrapped llm); this
+        // guard prevents starting a fresh round after a mid-round cancel.
+        if (signal?.aborted)
+            break;
         const useSeed = round === 0 && seeded.length > 0;
         const roundId = `phase:clarification-round-${round + 1}`;
         const roundStart = Date.now();
@@ -182,6 +228,23 @@ costAware = false) {
                 questions = [];
             }
         }
+        // G2-a: enforce the "typically 0-2 questions per round" rule the prompt asks
+        // for but the model/seeds repeatedly exceed. Applies to BOTH the LLM path
+        // AND the PIL gray-area SEED path — live drive (greenfield "/ideal") showed
+        // round-0 seeds (productType/targetPlatform/audience) surfacing uncapped,
+        // which a model-path-only cap missed. In an existing repo (a
+        // "## Current Project" snapshot is present) generic greenfield questions are
+        // also dropped — the documented EE-3589e10d failure. A non-silent content
+        // line surfaces whatever was trimmed.
+        const existingRepo = conversationContext.includes("## Current Project");
+        const capped = capClarifierQuestions(questions, existingRepo);
+        questions = capped.kept;
+        if (capped.dropped > 0) {
+            yield {
+                type: "content",
+                content: `\n_(clarifier: trimmed ${capped.dropped} question${capped.dropped === 1 ? "" : "s"} — cap ${MAX_CLARIFY_QUESTIONS_PER_ROUND}/round${existingRepo ? " + dropped generic greenfield questions for an existing repo" : ""})_\n`,
+            };
+        }
         if (questions.length === 0) {
             // The clarifier asking nothing IS the readiness signal — the leader already
             // decided no gaps remain. Mark the spec ready directly rather than leaving the

package/dist/src/council/debate-planner.d.ts

@@ -5,4 +5,5 @@ import type { ClarifiedSpec, CouncilLLM, DebatePlan } from "./types.js";
 export declare function planDebate(spec: ClarifiedSpec, leaderModelId: string, llm: CouncilLLM, eeWarnings?: CouncilWarning[], // CQ-13: experience snippets to seed prompt
 experienceMode?: CouncilExperienceMode, // CQ-14: controls Experience Auditor injection
 taskType?: string, // CQ-11: task type from PIL (e.g. "architecture", "bugfix")
-complexityTier?: string): AsyncGenerator<StreamChunk, DebatePlan, unknown>;
+complexityTier?: string, // CQ-11: complexity tier from PIL (e.g. "heavy", "medium", "light")
+signal?: AbortSignal): AsyncGenerator<StreamChunk, DebatePlan, unknown>;

package/dist/src/council/debate-planner.js

@@ -97,7 +97,8 @@ function injectAuditorStance(plan, eeWarnings, experienceMode) {
 export async function* planDebate(spec, leaderModelId, llm, eeWarnings, // CQ-13: experience snippets to seed prompt
 experienceMode, // CQ-14: controls Experience Auditor injection
 taskType, // CQ-11: task type from PIL (e.g. "architecture", "bugfix")
-complexityTier) {
+complexityTier, // CQ-11: complexity tier from PIL (e.g. "heavy", "medium", "light")
+signal) {
     const eeSnippets = eeWarnings?.map((w) => w.text).filter(Boolean) ?? [];
     const { system: baseSystem, prompt } = buildDebatePlanPrompt(spec);
     // Build calibration context from PIL metadata
@@ -133,7 +134,8 @@ complexityTier) {
         // Bound attempt-1: a wedged provider response here would freeze the whole
         // council/loop silently (no streamText stall watchdog covers generateObject).
         // On timeout this rejects → caught below → retry (guarded) → fallback plan.
-        const { signal: timedSignal, cleanup: cleanupTimeout } = withTimeoutSignal(undefined, getProviderStallTimeoutMs());
+        // The user-abort signal is combined in so an Esc during planning aborts it.
+        const { signal: timedSignal, cleanup: cleanupTimeout } = withTimeoutSignal(signal, getProviderStallTimeoutMs());
         const { object } = await withDeadlineRace(() => generateObject({
             model: runtime.model,
             schema: DebatePlanSchema,
@@ -141,7 +143,7 @@ complexityTier) {
             prompt,
             abortSignal: timedSignal,
             ...(runtime.providerOptions ? { providerOptions: runtime.providerOptions } : {}),
-        }), getProviderStallTimeoutMs() + 5_000, "plan_debate").finally(() => cleanupTimeout());
+        }), getProviderStallTimeoutMs() + 5_000, "plan_debate", signal).finally(() => cleanupTimeout());
         // Validate with existing sanitize helpers for normalization
         const stances = sanitizeStances(object.stances);
         const outputShape = sanitizeShape(object.outputShape);

package/dist/src/council/debate.d.ts

@@ -1,4 +1,13 @@
 import type { StreamChunk } from "../types/index.js";
 import type { ClarifiedSpec, CouncilConfig, CouncilLLM, DebateState } from "./types.js";
+/**
+ * Resolve the initial round budget + hard ceiling from the plan's output-shape kind
+ * and the planner-proposed round count. Pure + exported for unit testing the cap.
+ */
+export declare function resolveDebateRoundBudget(planKind: string | undefined, plannedRounds: number | undefined): {
+    maxRounds: number;
+    effectiveCeiling: number;
+    kindCapped: boolean;
+};
 export declare function runDebate(spec: ClarifiedSpec, config: CouncilConfig, llm: CouncilLLM): AsyncGenerator<StreamChunk, DebateState, unknown>;
 export declare function evaluateResearchNeed(spec: ClarifiedSpec, leaderModelId: string, conversationContext: string, llm: CouncilLLM, costAware?: boolean): AsyncGenerator<StreamChunk, boolean, unknown>;