muonroi-cli 1.8.3 → 1.8.5

package/dist/src/gsd/phase-sync.js

@@ -0,0 +1,321 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { slugify } from "../utils/slugify.js";
+import { logGsdNativeEvent } from "./ee-closure.js";
+import { isGsdNativeEnabled } from "./flags.js";
+import { dispatchPhaseAdd, dispatchPhaseComplete, dispatchRoadmapAnalyze, dispatchRoadmapPlanProgress, } from "./gsd-dispatch.js";
+import { phaseDirPath, planningArtifact, planningPhasesRoot, planningRoot } from "./paths.js";
+import { readState, readWorkflowKind, setStateField } from "./workflow-engine.js";
+const MILESTONE_PHASE_DIR_FIELD = "Milestone Phase Dir";
+export function extractPlanTitle(planBody) {
+    const h1 = planBody.match(/^#\s+(.+)$/m);
+    if (h1?.[1]?.trim())
+        return h1[1].trim().slice(0, 120);
+    const first = planBody.split("\n").find((l) => l.trim().length > 0);
+    return (first?.trim() ?? "Task").slice(0, 120);
+}
+export function derivePhaseSlug(title) {
+    return slugify(title).slice(0, 60) || "task";
+}
+export function findPhaseDirBySlug(cwd, slug) {
+    if (!existsSync(planningPhasesRoot(cwd)))
+        return null;
+    const needle = slug.toLowerCase();
+    for (const dir of readdirSync(planningPhasesRoot(cwd))) {
+        if (dir.toLowerCase().includes(needle))
+            return dir;
+    }
+    return null;
+}
+export function readMilestonePhaseDir(cwd) {
+    const statePath = planningArtifact(cwd, "STATE.md");
+    if (!existsSync(statePath))
+        return null;
+    try {
+        const raw = readFileSync(statePath, "utf8");
+        const row = raw.match(/^\|\s*Milestone Phase Dir\s*\|\s*([^|\n]+?)\s*\|/im);
+        const val = row?.[1]?.trim();
+        return val && val !== "—" && val.length > 0 ? val : null;
+    }
+    catch (err) {
+        console.error(`[gsd-phase-sync] readMilestonePhaseDir failed: ${err.message}`);
+        return null;
+    }
+}
+function storeMilestonePhaseDir(cwd, dirName) {
+    setStateField(cwd, MILESTONE_PHASE_DIR_FIELD, dirName);
+}
+/** Minimal gsd-compatible ROADMAP required before `phase add`. */
+export function ensureTaskRoadmap(cwd, milestoneTitle) {
+    const roadmapPath = planningArtifact(cwd, "ROADMAP.md");
+    if (existsSync(roadmapPath))
+        return;
+    const title = milestoneTitle.slice(0, 80) || "Task";
+    const stub = [
+        `# Roadmap: ${title}`,
+        "",
+        "## Overview",
+        "",
+        "Task-level GSD milestone — phases sync from native gsd_* workflow.",
+        "",
+        "## Phases",
+        "",
+        `- [ ] **Phase 1: ${title}** - In progress`,
+        "",
+        "## Phase Details",
+        "",
+        `### Phase 1: ${title}`,
+        "**Goal:** Ship scoped task via gsd-native workflow",
+        "**Depends on:** Nothing (first phase)",
+        "**Plans**: TBD",
+        "",
+        "Plans:",
+        "- [ ] 01-01: Task plan",
+        "",
+    ].join("\n");
+    writeFileSync(roadmapPath, `${stub}\n`, "utf8");
+}
+function resolvePhaseDirName(cwd, addResult) {
+    const padded = addResult.phaseNumber.padStart(2, "0");
+    const dirs = readdirSync(planningPhasesRoot(cwd));
+    const match = dirs.find((d) => d.startsWith(`${padded}-`) || d.startsWith(`${addResult.phaseNumber}-`));
+    return match ?? null;
+}
+export function copyPlanToPhaseDir(cwd, phaseDirName, planBody) {
+    const dest = phaseDirPath(cwd, phaseDirName, "PLAN.md");
+    mkdirSync(join(planningPhasesRoot(cwd), phaseDirName), { recursive: true });
+    writeFileSync(dest, planBody.trim(), "utf8");
+}
+export function writePhaseVerificationPassed(cwd, phaseDirName, phaseNumber, evidence) {
+    const padded = phaseNumber.padStart(2, "0");
+    const fileName = `${padded}-VERIFICATION.md`;
+    const path = phaseDirPath(cwd, phaseDirName, fileName);
+    const body = [
+        "---",
+        "status: passed",
+        "---",
+        "",
+        "# Verification",
+        "",
+        evidence?.trim() || "Verified via gsd_verify (muonroi-cli native host).",
+        "",
+    ].join("\n");
+    writeFileSync(path, body, "utf8");
+    return path;
+}
+export function writePhaseSummaryStub(cwd, phaseDirName, evidence) {
+    const path = phaseDirPath(cwd, phaseDirName, "SUMMARY.md");
+    const body = ["# Summary", "", evidence?.trim() || "Task verify passed — see VERIFY.md in .planning/.", ""].join("\n");
+    writeFileSync(path, body, "utf8");
+    return path;
+}
+function resolvePhaseNumberForComplete(cwd, phaseDirName) {
+    const analyze = dispatchRoadmapAnalyze(cwd);
+    if (analyze.ok && analyze.data?.current_phase) {
+        return String(analyze.data.current_phase).replace(/^0+/, "") || analyze.data.current_phase;
+    }
+    const token = phaseDirName.match(/^(\d+)/);
+    return token ? token[1].replace(/^0+/, "") || token[1] : "1";
+}
+/** After gsd_plan writes PLAN.md — task workflow only. */
+export function syncTaskPhaseOnPlan(cwd, opts) {
+    const steps = [];
+    if (readWorkflowKind(cwd) === "product") {
+        return { ok: true, skipped: true, skipReason: "product", steps };
+    }
+    const slug = derivePhaseSlug(opts.planTitle);
+    let phaseDirName = readMilestonePhaseDir(cwd) ?? findPhaseDirBySlug(cwd, slug);
+    if (!phaseDirName) {
+        ensureTaskRoadmap(cwd, opts.planTitle);
+        const add = dispatchPhaseAdd(cwd, opts.planTitle);
+        steps.push({
+            op: "phase-add",
+            ok: add.ok,
+            detail: add.data?.phaseNumber,
+            error: add.error,
+        });
+        if (!add.ok || !add.data) {
+            return { ok: false, skipped: false, steps, error: add.error };
+        }
+        phaseDirName = resolvePhaseDirName(cwd, add.data);
+        if (!phaseDirName) {
+            return { ok: false, skipped: false, steps, error: "phase add succeeded but phase dir not found" };
+        }
+        storeMilestonePhaseDir(cwd, phaseDirName);
+        logGsdNativeEvent(opts.sessionId ?? "gsd-native", {
+            phase: "plan",
+            depth: null,
+            loopPoint: "phase-sync:plan",
+            phaseNumber: add.data.phaseNumber,
+        });
+    }
+    else {
+        steps.push({ op: "phase-add", ok: true, detail: "skipped-existing-dir" });
+    }
+    try {
+        copyPlanToPhaseDir(cwd, phaseDirName, opts.planBody);
+        steps.push({ op: "copy-plan", ok: true, detail: phaseDirName });
+    }
+    catch (err) {
+        steps.push({ op: "copy-plan", ok: false, error: err.message });
+        return { ok: false, skipped: false, phaseDirName, steps };
+    }
+    return { ok: true, skipped: false, phaseDirName, steps };
+}
+/** After gsd_verify pass — task workflow only. */
+export function syncTaskPhaseOnVerifyPass(cwd, opts) {
+    const steps = [];
+    if (readWorkflowKind(cwd) === "product") {
+        return { ok: true, skipped: true, skipReason: "product", steps };
+    }
+    const phaseDirName = readMilestonePhaseDir(cwd) ?? latestPhaseDirName(cwd);
+    if (!phaseDirName) {
+        steps.push({ op: "phase-complete", ok: false, error: "no milestone phase dir" });
+        return { ok: false, skipped: false, steps };
+    }
+    const phaseNum = resolvePhaseNumberForComplete(cwd, phaseDirName);
+    try {
+        writePhaseSummaryStub(cwd, phaseDirName, opts?.evidence);
+        writePhaseVerificationPassed(cwd, phaseDirName, phaseNum, opts?.evidence);
+        steps.push({ op: "write-verification", ok: true });
+    }
+    catch (err) {
+        steps.push({ op: "write-verification", ok: false, error: err.message });
+        return { ok: false, skipped: false, phaseDirName, steps };
+    }
+    const complete = dispatchPhaseComplete(cwd, phaseNum);
+    steps.push({ op: "phase-complete", ok: complete.ok, error: complete.error });
+    if (!complete.ok) {
+        return { ok: false, skipped: false, phaseNumber: phaseNum, phaseDirName, steps };
+    }
+    const progress = dispatchRoadmapPlanProgress(cwd, phaseNum);
+    steps.push({ op: "roadmap-progress", ok: progress.ok, detail: progress.raw?.trim(), error: progress.error });
+    logGsdNativeEvent(opts?.sessionId ?? "gsd-native", {
+        phase: "verify",
+        depth: null,
+        loopPoint: "phase-sync:verify",
+        phaseNumber: phaseNum,
+    });
+    return {
+        ok: progress.ok,
+        skipped: false,
+        phaseNumber: phaseNum,
+        phaseDirName,
+        steps,
+    };
+}
+function latestPhaseDirName(cwd) {
+    if (!existsSync(planningPhasesRoot(cwd)))
+        return null;
+    const dirs = readdirSync(planningPhasesRoot(cwd)).sort();
+    return dirs.length ? dirs[dirs.length - 1] : null;
+}
+/** Copy root VERIFY.md into phase dir when present (best-effort). */
+export function mirrorVerifyMdToPhaseDir(cwd, phaseDirName) {
+    const src = planningArtifact(cwd, "VERIFY.md");
+    if (!existsSync(src))
+        return;
+    const dest = phaseDirPath(cwd, phaseDirName, "VERIFY.md");
+    try {
+        copyFileSync(src, dest);
+    }
+    catch (err) {
+        console.error(`[gsd-phase-sync] mirror VERIFY.md failed: ${err.message}`);
+    }
+}
+/** Automatically append user AskCard answers as clarifications to CONTEXT.md under GSD. */
+export function appendClarificationToContext(cwd, question, answer) {
+    const planningDir = planningRoot(cwd);
+    if (!existsSync(planningDir))
+        return;
+    const contextPath = join(planningDir, "CONTEXT.md");
+    let prior = "";
+    if (existsSync(contextPath)) {
+        prior = readFileSync(contextPath, "utf8");
+    }
+    else {
+        prior = "# CONTEXT\n\n## Clarifications\n\n";
+    }
+    const cleanQuestion = question.replace(/^Question:\s*/i, "").trim();
+    const entry = `### Clarification\n**Q**: ${cleanQuestion}\n**A**: ${answer.trim()}\n\n`;
+    writeFileSync(contextPath, prior + entry, "utf8");
+}
+/** Build TaskListSnapshot directly from GSD PLAN.md and STATE.md for automatic TUI checklist synchronization. */
+export function getTaskListSnapshotFromGsd(cwd) {
+    if (!isGsdNativeEnabled())
+        return null;
+    const planPath = join(planningRoot(cwd), "PLAN.md");
+    if (!existsSync(planPath))
+        return null;
+    try {
+        const content = readFileSync(planPath, "utf8");
+        const state = readState(cwd);
+        const lines = content.split(/\r?\n/);
+        const items = [];
+        // Regex to match markdown checklist items or numbered list items
+        const checkboxRegex = /^\s*[-*+]\s*\[([ xX/])\]\s*(.+)$/;
+        const numberedRegex = /^\s*(\d+)\.\s*(.+)$/;
+        let itemIndex = 0;
+        for (const line of lines) {
+            const checkboxMatch = line.match(checkboxRegex);
+            if (checkboxMatch) {
+                const marker = checkboxMatch[1];
+                const subject = checkboxMatch[2].trim();
+                let status = "pending";
+                if (marker === "x" || marker === "X") {
+                    status = "completed";
+                }
+                else if (marker === "/") {
+                    status = "in_progress";
+                }
+                items.push({
+                    id: `gsd_${itemIndex++}`,
+                    subject,
+                    status,
+                });
+                continue;
+            }
+            const numberedMatch = line.match(numberedRegex);
+            if (numberedMatch) {
+                const subject = numberedMatch[2].trim();
+                items.push({
+                    id: `gsd_${itemIndex++}`,
+                    subject,
+                    status: "pending",
+                });
+            }
+        }
+        if (items.length === 0)
+            return null;
+        // Adjust statuses based on active phase
+        if (state.phase === "execute" && !items.some((it) => it.status === "in_progress")) {
+            const firstPending = items.find((it) => it.status === "pending");
+            if (firstPending) {
+                firstPending.status = "in_progress";
+            }
+        }
+        else if (state.phase === "verify" || state.phase === "review") {
+            for (const item of items) {
+                if (item.status === "in_progress" || item.status === "pending") {
+                    item.status = "completed";
+                }
+            }
+        }
+        const counts = {
+            completed: items.filter((it) => it.status === "completed").length,
+            inProgress: items.filter((it) => it.status === "in_progress").length,
+            pending: items.filter((it) => it.status === "pending").length,
+            total: items.length,
+        };
+        return {
+            items,
+            counts,
+            ts: Date.now(),
+        };
+    }
+    catch (err) {
+        console.error(`[gsd-plan-parser] failed to parse PLAN.md: ${err.message}`);
+        return null;
+    }
+}
+//# sourceMappingURL=phase-sync.js.map

package/dist/src/gsd/pil-gate-context.d.ts

@@ -0,0 +1,13 @@
+export interface GateContextInput {
+    cwd: string;
+    conversationDigest?: string | null;
+    brainData?: unknown;
+}
+export interface GateContextBundle {
+    conversationDigest: string;
+    eeContext: string;
+    priorPlan: string;
+    projectHints: string;
+    totalChars: number;
+}
+export declare function buildGateContextBundle(input: GateContextInput): GateContextBundle;

package/dist/src/gsd/pil-gate-context.js

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from "node:fs";
+import { planningArtifact } from "./paths.js";
+import { readState } from "./workflow-engine.js";
+function cap(text, max) {
+    const t = (text ?? "").trim();
+    if (t.length <= max)
+        return t;
+    const suffix = "…[truncated]";
+    const keep = Math.max(0, max - suffix.length);
+    return `${t.slice(0, keep)}${suffix}`;
+}
+/** Render EE recall (BrainData shape from layer1's pilContext fetch) into a compact block. */
+function formatEeContext(brainData) {
+    if (!brainData || typeof brainData !== "object")
+        return "";
+    const b = brainData;
+    const principles = Array.isArray(b.t0_principles) ? b.t0_principles.map(String) : [];
+    const patterns = Array.isArray(b.t2_patterns) ? b.t2_patterns.map(String) : [];
+    const rules = Array.isArray(b.t1_rules) ? b.t1_rules.map(String) : [];
+    const lines = [
+        ...principles.slice(0, 3).map((p) => `- principle: ${p}`),
+        ...rules.slice(0, 3).map((r) => `- rule: ${r}`),
+        ...patterns.slice(0, 3).map((p) => `- pattern: ${p}`),
+    ];
+    return cap(lines.join("\n"), 600);
+}
+function readPriorPlan(cwd) {
+    const p = planningArtifact(cwd, "PLAN.md");
+    if (!existsSync(p))
+        return "";
+    let phase = "";
+    try {
+        phase = readState(cwd).phase ?? "";
+    }
+    catch (err) {
+        console.error(`[pil-gate] readState for prior-plan phase failed: ${err.message}`);
+    }
+    const body = cap(readFileSync(p, "utf8"), 800);
+    return phase ? `phase: ${phase}\n${body}` : body;
+}
+export function buildGateContextBundle(input) {
+    const conversationDigest = cap(input.conversationDigest ?? "", 1200);
+    let eeContext = "";
+    try {
+        eeContext = formatEeContext(input.brainData);
+    }
+    catch (err) {
+        console.error(`[pil-gate] formatEeContext failed: ${err.message}`);
+    }
+    let priorPlan = "";
+    try {
+        priorPlan = readPriorPlan(input.cwd);
+    }
+    catch (err) {
+        console.error(`[pil-gate] readPriorPlan failed: ${err.message}`);
+    }
+    // projectHints intentionally left "" in v1: the discovery ProjectContext scan is
+    // directory-level only (REPO_DEEP_MAP §src/pil) and produces mislead-prone
+    // substring matches. Hedged hints are the producer's job, not asserted here.
+    const projectHints = "";
+    const totalChars = conversationDigest.length + eeContext.length + priorPlan.length + projectHints.length;
+    return { conversationDigest, eeContext, priorPlan, projectHints, totalChars };
+}
+//# sourceMappingURL=pil-gate-context.js.map

package/dist/src/gsd/pil-gate-critic.d.ts

@@ -0,0 +1,19 @@
+import type { GateContextBundle } from "./pil-gate-context.js";
+export type GateVerdict = "adequate" | "enriched" | "needs-user";
+export interface CriticResult {
+    verdict: GateVerdict;
+    brief: string;
+}
+export type RunCriticFn = (prompt: string) => Promise<string>;
+declare const CRITIC_ROLES: readonly ["grounding", "noise", "sufficiency"];
+type CriticRole = (typeof CRITIC_ROLES)[number];
+export declare function buildCriticPrompt(role: CriticRole, draftBrief: string, draftVerdict: GateVerdict, bundle: GateContextBundle): string;
+/** Worst-wins AND downgrade-only: the result is never less severe than the producer verdict. */
+export declare function mergeCriticVerdicts(producer: GateVerdict, criticVerdicts: GateVerdict[]): GateVerdict;
+export declare function runGateCritics(args: {
+    draftBrief: string;
+    draftVerdict: GateVerdict;
+    bundle: GateContextBundle;
+    runCritic: RunCriticFn;
+}): Promise<CriticResult>;
+export {};

package/dist/src/gsd/pil-gate-critic.js

@@ -0,0 +1,74 @@
+const RANK = { adequate: 0, enriched: 1, "needs-user": 2 };
+const CRITIC_ROLES = ["grounding", "noise", "sufficiency"];
+const ROLE_MANDATE = {
+    grounding: "Strip any claim not traceable to the provided context. Flag ANY area/file reference not explicitly hedged as 'confirm via grep before anchoring' — an asserted file path is a defect.",
+    noise: "Strip any line that does not change what the coding agent does. If most of the brief is noise, downgrade the verdict.",
+    sufficiency: "Decide whether 'adequate' is honest or a blocker (intent/target/scope/acceptance) is being papered over. You may flip to needs-user; you may NOT upgrade toward adequate.",
+};
+export function buildCriticPrompt(role, draftBrief, draftVerdict, bundle) {
+    return [
+        `You are the ${role} critic for a prompt-enrichment gate. You may only TIGHTEN — downgrade the verdict and strip lines, never upgrade or add.`,
+        ROLE_MANDATE[role],
+        "",
+        "Provided context (the ONLY sources the brief may draw on):",
+        bundle.conversationDigest ? `Recent conversation:\n${bundle.conversationDigest}` : "(no recent conversation)",
+        bundle.eeContext ? `EE recall:\n${bundle.eeContext}` : "(no EE recall)",
+        bundle.priorPlan ? `Prior plan:\n${bundle.priorPlan}` : "(no prior plan)",
+        bundle.projectHints ? `Project hints:\n${bundle.projectHints}` : "(no project hints)",
+        "",
+        `Producer verdict: ${draftVerdict}`,
+        "Producer brief:",
+        draftBrief || "(empty)",
+        "",
+        "Respond with ONLY a fenced block:",
+        "```gate-critic",
+        '{ "verdict": "adequate|enriched|needs-user", "strippedBrief": "the brief with noise/ungrounded/unhedged lines removed" }',
+        "```",
+    ].join("\n");
+}
+function parseCritic(raw) {
+    const m = raw.match(/```gate-critic\s*([\s\S]*?)```/);
+    const body = m?.[1] ?? raw;
+    const brace = body.match(/\{[\s\S]*\}/);
+    if (!brace)
+        return null;
+    try {
+        const parsed = JSON.parse(brace[0]);
+        if (parsed.verdict !== "adequate" && parsed.verdict !== "enriched" && parsed.verdict !== "needs-user")
+            return null;
+        return { verdict: parsed.verdict, strippedBrief: String(parsed.strippedBrief ?? "") };
+    }
+    catch (err) {
+        console.error(`[pil-gate] critic parse failed: ${err.message}`);
+        return null;
+    }
+}
+/** Worst-wins AND downgrade-only: the result is never less severe than the producer verdict. */
+export function mergeCriticVerdicts(producer, criticVerdicts) {
+    let worst = producer;
+    for (const v of criticVerdicts) {
+        if (RANK[v] > RANK[worst])
+            worst = v;
+    }
+    return worst;
+}
+export async function runGateCritics(args) {
+    const settled = await Promise.all(CRITIC_ROLES.map((role) => args
+        .runCritic(buildCriticPrompt(role, args.draftBrief, args.draftVerdict, args.bundle))
+        .then((raw) => parseCritic(raw))
+        .catch((err) => {
+        console.error(`[pil-gate] critic ${role} threw: ${err.message}`);
+        return null;
+    })));
+    // Parse/throw failure is conservative: a null critic votes needs-user and keeps the producer brief.
+    const verdicts = settled.map((r) => r?.verdict ?? "needs-user");
+    const verdict = mergeCriticVerdicts(args.draftVerdict, verdicts);
+    // Prefer the shortest surviving stripped brief (most noise removed) among successful critics;
+    // fall back to the producer brief when none parsed.
+    const stripped = settled
+        .filter((r) => r !== null && r.strippedBrief.trim().length > 0)
+        .map((r) => r.strippedBrief)
+        .sort((a, b) => a.length - b.length)[0];
+    return { verdict, brief: (stripped ?? args.draftBrief).slice(0, 1500) };
+}
+//# sourceMappingURL=pil-gate-critic.js.map

package/dist/src/gsd/plan-council-prompts.d.ts

@@ -0,0 +1,25 @@
+import type { CouncilContextBundle } from "./council-context.js";
+import { type PlanGateDimensionId } from "./plan-gate-vocabulary.js";
+export type PlanPerspectiveId = "architect" | "skeptic" | "research" | "security" | "implementer";
+export interface PlanPerspective {
+    id: PlanPerspectiveId;
+    role: string;
+    mandate: string;
+    /**
+     * The shared gate axis this perspective primarily owns. Ties the headless
+     * perspective set to the same criteria the interactive debate uses; the full
+     * perspective set must cover every PLAN_GATE_DIMENSION (parity-tested).
+     */
+    dimension: PlanGateDimensionId;
+}
+export declare const PLAN_PERSPECTIVES: PlanPerspective[];
+export declare function perspectivesForDepth(depth: string): PlanPerspective[];
+export declare function buildPerspectivePrompt(perspective: PlanPerspective, planBody: string, bundle?: CouncilContextBundle): string;
+/**
+ * Build the debate topic fed to the council leader. Bundles prior GSD context
+ * (discuss notes, research, acceptance criteria, prior concerns) with the
+ * draft plan and the model-first output contract — the leader MUST end its
+ * synthesis with a ```council-verdict fenced block; extraction falls back
+ * conservatively when it doesn't.
+ */
+export declare function buildDebateTopic(planBody: string, bundle: CouncilContextBundle): string;

package/dist/src/gsd/plan-council-prompts.js

@@ -0,0 +1,79 @@
+import { renderCouncilContextBlock } from "./council-context.js";
+import { renderGateAxes } from "./plan-gate-vocabulary.js";
+import { VERDICT_OUTPUT_CONTRACT } from "./verdict-schema.js";
+export const PLAN_PERSPECTIVES = [
+    {
+        id: "architect",
+        role: "architect",
+        mandate: "Structural fit, file map correctness, dependency order, module boundaries.",
+        dimension: "structure",
+    },
+    {
+        id: "skeptic",
+        role: "devil's advocate",
+        mandate: "Challenge assumptions, missing edge cases, YAGNI violations, scope creep.",
+        dimension: "feasibility",
+    },
+    {
+        id: "research",
+        role: "researcher",
+        mandate: "Ground plan claims against codebase evidence (file:line citations required).",
+        dimension: "grounding",
+    },
+    {
+        id: "security",
+        role: "security reviewer",
+        mandate: "Permission model, path traversal, secret handling, dangerous bash patterns in planned edits.",
+        dimension: "safety",
+    },
+    {
+        id: "implementer",
+        role: "implementer",
+        mandate: "Feasibility, estimate realism, testability of acceptance criteria.",
+        dimension: "correctness",
+    },
+];
+export function perspectivesForDepth(depth) {
+    if (depth === "quick")
+        return [];
+    if (depth === "standard") {
+        return PLAN_PERSPECTIVES.filter((p) => p.id === "research" || p.id === "skeptic");
+    }
+    return PLAN_PERSPECTIVES;
+}
+export function buildPerspectivePrompt(perspective, planBody, bundle) {
+    const lines = [`You are the ${perspective.role} on a plan review council.`, `Mandate: ${perspective.mandate}`];
+    if (bundle) {
+        lines.push("", renderCouncilContextBlock(bundle, { forPerspective: perspective.id }));
+    }
+    lines.push("", 
+    // Shared gate axes (single source with the interactive debate) so headless
+    // and interactive reviews judge the plan against identical criteria.
+    renderGateAxes(), "", "Review the draft PLAN.md below, then emit your structured verdict.", VERDICT_OUTPUT_CONTRACT, "", "--- PLAN.md ---", planBody, "--- END PLAN ---");
+    return lines.join("\n");
+}
+/**
+ * Build the debate topic fed to the council leader. Bundles prior GSD context
+ * (discuss notes, research, acceptance criteria, prior concerns) with the
+ * draft plan and the model-first output contract — the leader MUST end its
+ * synthesis with a ```council-verdict fenced block; extraction falls back
+ * conservatively when it doesn't.
+ */
+export function buildDebateTopic(planBody, bundle) {
+    return [
+        "Review and debate the proposed plan to determine if it is complete, correct, safe, and optimal for the task.",
+        "Debate the trade-offs, then converge on a single merged verdict.",
+        "",
+        // Shared gate axes (single source with the headless perspective review) so
+        // both gate paths judge the plan against identical criteria — no drift.
+        renderGateAxes(),
+        "",
+        renderCouncilContextBlock(bundle),
+        "",
+        "### Proposed PLAN.md:",
+        planBody.trim(),
+        "",
+        VERDICT_OUTPUT_CONTRACT,
+    ].join("\n");
+}
+//# sourceMappingURL=plan-council-prompts.js.map

package/dist/src/gsd/plan-council.d.ts

@@ -0,0 +1,44 @@
+import type { ToolResult } from "../types/index.js";
+import { type PlanPerspective, type PlanPerspectiveId } from "./plan-council-prompts.js";
+export type PerspectiveVerdict = "approve" | "revise" | "block";
+export type VerdictSource = "structured" | "heuristic-fallback" | "parse-failed";
+export interface PerspectiveResult {
+    id: PlanPerspectiveId;
+    role: string;
+    verdict: PerspectiveVerdict;
+    concerns: string[];
+    evidence: string[];
+    /** Where the verdict came from — model-emitted JSON or heuristic fallback. */
+    source: VerdictSource;
+    raw?: string;
+}
+export interface PlanCouncilResult {
+    skipped: boolean;
+    perspectives: PerspectiveResult[];
+    planReviewPath?: string;
+    planVerifyPath?: string;
+    verdict: PerspectiveVerdict | "pass";
+    leaderModelId?: string;
+    revisionRequired: boolean;
+    /** Chars of GSD context fed to council (telemetry — surfaces grounding quality). */
+    contextBundleChars?: number;
+    /** True when prior PLAN-REVIEW concerns were surfaced to council. */
+    hadPriorConcerns?: boolean;
+    /** Where the merged verdict came from. */
+    verdictSource?: VerdictSource;
+    /** True when no structured verdict could be extracted (debate path). */
+    verdictParseFailed?: boolean;
+}
+export type RunPerspectiveFn = (prompt: string, perspective: PlanPerspective) => Promise<string>;
+export interface PlanCouncilOpts {
+    cwd: string;
+    sessionModelId: string;
+    depth: string;
+    /** Optional LLM runner for perspective sub-agents (tests use heuristic when omitted). */
+    runPerspectiveFn?: RunPerspectiveFn;
+    revisionCycle?: number;
+    runDebate?: (topic: string) => Promise<string>;
+}
+export declare function runPlanCouncil(opts: PlanCouncilOpts): Promise<PlanCouncilResult>;
+/** Adapter: wrap orchestrator runTask as perspective runner. */
+export declare function taskToPerspectiveRunner(runTask: (request: import("../types/index.js").TaskRequest) => Promise<ToolResult>, sessionModelId: string): RunPerspectiveFn;