@bridge_gpt/mcp-server 0.2.2 → 0.2.4

package/build/index.js

@@ -8,11 +8,16 @@
  *   BAPI_REPO_NAME - Default repository name injected into every request
  *   BAPI_API_KEY   - API key for X-API-Key authentication
  *   BAPI_DOCS_DIR  - Base directory for local file output (default: docs/tmp)
+ *   BAPI_MCP_UPGRADE_ADVICE_ENABLED - Proactively surface the server's upgrade
+ *     advice in pipeline recipe preambles (BAPI-375). Defaults to ENABLED; set
+ *     to false/0/no/off/disabled to suppress proactive recipe-preamble
+ *     surfacing. Does NOT change the /jira/ping response or server-side upgrade
+ *     computation — it only gates the recipe-preamble convention.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { writeFile, mkdir, readFile, stat } from "fs/promises";
+import { writeFile, mkdir, readFile, stat, rename, chmod, unlink } from "fs/promises";
 import path from "path";
 import os from "os";
 import { fileURLToPath } from "url";
@@ -27,13 +32,18 @@ import { checkForUpdate } from "./update-check.js";
 import { reconstructAgentMarkdown, translateAgentToCopilot } from "./agent-utils.js";
 import { resolveRecipe, loadCustomPipelines } from "./pipeline-utils.js";
 import { runStartTicketsCli } from "./start-tickets.js";
+import { runReviewTicketsCli } from "./review-tickets.js";
 import { runDoctorCli } from "./doctor.js";
 import { runScheduleRunCli } from "./schedule-run.js";
 import { runMcpInvokeCli } from "./mcp-invoke.js";
 import { runAgentCapabilitiesCli } from "./agent-capabilities/cli.js";
 import { validateRepoName } from "./bridge-config.js";
 import { ensureGitignored as ensureGitignoredShared } from "./git-ignore-utils.js";
-import { resolveBapiCredentials } from "./credential-store.js";
+import { resolveBapiCredentials, upsertBapiCredential, getPrimaryCredentialStorePath, } from "./credential-store.js";
+import { runCredentialsCli } from "./credentials-cli.js";
+import { registerConductorTools } from "./conductor/tools.js";
+import { runConductorCli } from "./conductor/cli.js";
+import { observePrCiFromPollResponse } from "./conductor/pr-ci-producer.js";
 import { generateDecisionPageHtml } from "./decision-page-template.js";
 import { DecisionPageInputShape } from "./decision-page-schema.js";
 import { slugify, saveBrainstormResultsToDir, } from "./brainstorm-files.js";
@@ -48,6 +58,25 @@ let userPipelineKeys = new Set();
 // ---------------------------------------------------------------------------
 const BASE_URL = process.env.BAPI_BASE_URL ?? "https://bridgegpt-api.com";
 const REPO_NAME = process.env.BAPI_REPO_NAME ?? "";
+/**
+ * Parse a default-ON boolean env flag. `undefined` / blank → true; the
+ * normalized off-tokens (`false`, `0`, `no`, `off`, `disabled`) → false; any
+ * other value → true (preserving default-on / fail-open behavior).
+ */
+function parseDefaultOnEnvFlag(value) {
+    if (value === undefined)
+        return true;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "")
+        return true;
+    return !["false", "0", "no", "off", "disabled"].includes(normalized);
+}
+// BAPI-375: gate proactive upgrade-advice surfacing in recipe preambles with an
+// MCP-LOCAL env-var rather than backend config-field plumbing. This flag only
+// controls whether the surfacing convention is emitted; the backend remains
+// authoritative for whether advice exists and for its exact wording
+// (compute_upgrade()). Defaults to enabled; fail-open on any unexpected value.
+const UPGRADE_ADVICE_SURFACING_ENABLED = parseDefaultOnEnvFlag(process.env.BAPI_MCP_UPGRADE_ADVICE_ENABLED);
 // ---------------------------------------------------------------------------
 // Resolved-once credential + path accessors (BAPI-338)
 //
@@ -86,6 +115,45 @@ async function getResolvedApiKey() {
     }
     return resolvedApiKeyPromise;
 }
+/**
+ * Resolve the Bridge API key env-first, then from the home-dir credential store,
+ * for an EXPLICIT `repoName` (not the module-level `REPO_NAME`). Used by the
+ * install-time persistence tool, which targets the repo the user is installing
+ * into. Uncached. Returns an empty string on any failure and never logs secrets.
+ */
+async function getResolvedApiKeyForRepo(repoName) {
+    try {
+        const result = await resolveBapiCredentials(repoName, {
+            env: process.env,
+            homedir: os.homedir,
+            platform: process.platform,
+            readFile: (p) => readFile(p, "utf-8"),
+            stat: (p) => stat(p),
+        });
+        return result.ok ? result.credentials.apiKey : "";
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Build {@link CredentialStoreWriteDeps} from the local MCP-server runtime
+ * boundaries (`process.env`, `os.homedir`, `process.platform`, `fs/promises`).
+ * The returned deps are what the writer mutates the user-scoped store through.
+ */
+function buildCredentialStoreWriteDeps() {
+    return {
+        env: process.env,
+        homedir: os.homedir,
+        platform: process.platform,
+        readFile: (p) => readFile(p, "utf-8"),
+        mkdir: (p, options) => mkdir(p, options),
+        writeFile: (p, data, options) => writeFile(p, data, options),
+        rename: (oldPath, newPath) => rename(oldPath, newPath),
+        chmod: (p, mode) => chmod(p, mode),
+        unlink: (p) => unlink(p),
+    };
+}
 /** GET auth headers, with the API key resolved once via {@link getResolvedApiKey}. */
 async function getGetHeaders() {
     return {
@@ -458,6 +526,78 @@ async function resolveTextOrFile(textValue, filePath, textLabel) {
     }
     return { ok: true, text: resolvedText, note };
 }
+const BINARY_EXTENSIONS = new Set([
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".heic", ".heif",
+    ".bmp", ".tiff", ".pdf", ".zip", ".docx", ".xlsx", ".pptx",
+]);
+async function resolveUploadAttachment(textValue, filePath, textLabel) {
+    if (!filePath && !textValue) {
+        return {
+            ok: false,
+            errorResponse: {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ error: "BAD_REQUEST", status: 400, message: `Either ${textLabel} or file_path must be provided.` }),
+                    }],
+            },
+        };
+    }
+    if (!filePath) {
+        return { ok: true, text: textValue, encoding: undefined, note: "" };
+    }
+    try {
+        const fileStat = await stat(filePath);
+        if (fileStat.size > 10 * 1024 * 1024) { // mirrors MAX_ATTACHMENT_SIZE in api/library/jira/jira_lib.py
+            return {
+                ok: false,
+                errorResponse: {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({ error: "BAD_REQUEST", status: 400, message: `File at ${filePath} exceeds 10MB size limit.` }),
+                        }],
+                },
+            };
+        }
+        const ext = path.extname(filePath).toLowerCase();
+        const buf = await readFile(filePath);
+        let isBinary = BINARY_EXTENSIONS.has(ext);
+        if (!isBinary) {
+            try {
+                new TextDecoder("utf-8", { fatal: true }).decode(buf);
+            }
+            catch {
+                isBinary = true;
+            }
+        }
+        const note = textValue ? `\n\nNote: Both file_path and ${textLabel} were provided. file_path content was used.` : "";
+        if (isBinary) {
+            return { ok: true, text: buf.toString("base64"), encoding: "base64", note };
+        }
+        if (buf.length > 1_048_576) {
+            return {
+                ok: false,
+                errorResponse: {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({ error: "BAD_REQUEST", status: 400, message: `Text file at ${filePath} exceeds 1MB size limit.` }),
+                        }],
+                },
+            };
+        }
+        return { ok: true, text: buf.toString("utf8"), encoding: undefined, note };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            errorResponse: {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({ error: "BAD_REQUEST", status: 400, message: `Error reading file at ${filePath}: ${err instanceof Error ? err.message : String(err)}` }),
+                    }],
+            },
+        };
+    }
+}
 async function pollForResult(getUrl, timeoutMs, label) {
     const startTime = Date.now();
     let pollIntervalMs = 15_000;
@@ -507,7 +647,7 @@ const TICKET_ARTIFACTS = {
         requestErrorPrefix: "Failed to request architecture generation: ",
         confirmationText: (n) => `Architecture generation requested for ${n}. ` +
             `Processing typically takes 2-4 minutes. ` +
-            `Use get_architecture with ticket_number "${n}" to retrieve the architecture plan once processing completes.`,
+            `Use get_architecture with ticket_number "${n}" (or get_doc with doc_type "tdd") to retrieve the architecture plan once processing completes.`,
         pollLabel: (n) => `Architecture generation for ${n}`,
     },
     fsd: {
@@ -519,9 +659,21 @@ const TICKET_ARTIFACTS = {
         requestErrorPrefix: "Failed to request FSD generation: ",
         confirmationText: (n) => `FSD generation requested for ${n}. ` +
             `Processing typically takes 2-4 minutes. ` +
-            `Use get_design_doc with ticket_number "${n}" and doc_type "fsd" to retrieve the functional specification document once processing completes.`,
+            `Use get_doc with ticket_number "${n}" and doc_type "fsd" to retrieve the functional specification document once processing completes.`,
         pollLabel: (n) => `FSD generation for ${n}`,
     },
+    prd: {
+        kind: "single",
+        generateEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/generate-prd`,
+        getEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/prd`,
+        saveSubdir: "prd",
+        filename: (n) => `${n}-prd-plan.md`,
+        requestErrorPrefix: "Failed to request PRD generation: ",
+        confirmationText: (n) => `PRD generation requested for ${n}. ` +
+            `Processing typically takes 2-4 minutes. ` +
+            `Use get_prd with ticket_number "${n}" (or get_doc with doc_type "prd") to retrieve the PRD once processing completes.`,
+        pollLabel: (n) => `PRD generation for ${n}`,
+    },
     clarifying_questions: {
         kind: "single",
         generateEndpoint: (n) => `/ticket/${encodeURIComponent(n)}/generate-clarifying-questions`,
@@ -598,6 +750,7 @@ async function getTicketArtifactDocsPath(subdir) {
             return getDocsPath("architecture");
         case "fsd":
             return getDocsPath("fsd");
+        case "prd": return getDocsPath("prd");
         case "clarifying-questions":
             return getDocsPath("clarifying-questions");
         case "ticket-critiques":
@@ -610,11 +763,15 @@ async function getTicketArtifactDocsPath(subdir) {
 // `tdd` reuses the existing "architecture" artifact (the TDD/architecture
 // document) WITHOUT renaming it, preserving the back-compatible
 // request_architecture / get_architecture tools. `fsd` routes to the new "fsd"
-// artifact.
+// artifact, and `prd` routes to the new "prd" artifact.
 function resolveDesignDocArtifactType(docType) {
-    return docType === "fsd" ? "fsd" : "architecture";
+    if (docType === "fsd")
+        return "fsd";
+    if (docType === "prd")
+        return "prd";
+    return "architecture";
 }
-// Shared request flow for the five single-artifact request_* tools: POST the
+// Shared request flow for the six single-artifact request_* tools: POST the
 // generate endpoint, return the per-tool error prefix on a non-OK POST, and on
 // wait_for_result poll the get endpoint (900_000 ms) and optionally save.
 async function requestTicketArtifact(type, args) {
@@ -647,7 +804,7 @@ async function requestTicketArtifact(type, args) {
         content: [{ type: "text", text: config.confirmationText(args.ticket_number) }],
     };
 }
-// Shared GET/save flow for the five single-artifact get_* tools. Normal gets
+// Shared GET/save flow for the six single-artifact get_* tools. Normal gets
 // save only on `resp.ok && save_locally`. reimplement_context is asymmetric: it
 // short-circuits a 404 with a custom NOT_FOUND envelope (without leaking the
 // backend body) and otherwise saves on ANY non-404 response when save_locally.
@@ -1286,6 +1443,9 @@ async function dispatchCliSubcommand(argv) {
     if (argv[0] === "start-tickets") {
         return runStartTicketsCli(argv.slice(1));
     }
+    if (argv[0] === "review-tickets") {
+        return runReviewTicketsCli(argv.slice(1));
+    }
     // The internal `mcp-invoke` worktree shim (BAPI-337) is a positional
     // subcommand routed before the flag guards and well before MCP server
     // construction: it resolves identity/credentials from `--project-root` and
@@ -1311,6 +1471,21 @@ async function dispatchCliSubcommand(argv) {
     if (argv[0] === "agent-capabilities") {
         return runAgentCapabilitiesCli(argv.slice(1));
     }
+    // The `credentials` subcommand (BAPI-377) hosts the consent-gated agent-config
+    // credential migration. It is a positional subcommand routed before the
+    // --init / --upgrade flag guards and well before MCP server construction so
+    // migration never falls through to the normal no-subcommand startup path. It
+    // is the ONLY place credential migration lives — doctor stays strictly read-only.
+    if (argv[0] === "credentials") {
+        return runCredentialsCli(argv.slice(1));
+    }
+    // The `conductor` subcommand (BAPI-393) is the local event-ledger CLI for fast
+    // hooks and operator diagnostics. It is a positional subcommand routed before
+    // the --init / --upgrade flag guards and well before MCP server construction;
+    // it talks ONLY to the local SQLite ledger and never starts the MCP server.
+    if (argv[0] === "conductor") {
+        return runConductorCli(argv.slice(1));
+    }
     // --init takes precedence over --upgrade; both are position-independent flags.
     if (argv.includes("--init")) {
         return runInitCli(cwd);
@@ -1418,6 +1593,16 @@ const registerTool = ((name, config, handler) => {
     }
     return toolHandle;
 });
+// ---------------------------------------------------------------------------
+// Conductor event-ledger tools (BAPI-393)
+// ---------------------------------------------------------------------------
+//
+// The conductor tools (emit_event, poll_events, wait_for_event,
+// get_supervisor_snapshot) operate against a LOCAL SQLite ledger at
+// ~/.config/bridge/events.db and intentionally do NOT route through the Bridge
+// API HTTP helpers. They are registered through the same `registerTool` wrapper
+// as every other tool so they share enable/disable + in-process dispatch.
+registerConductorTools(registerTool);
 registerTool("ping", {
     annotations: {
         readOnlyHint: true,
@@ -1462,14 +1647,14 @@ registerTool("ping", {
 });
 registerTool("second_opinion", {
     annotations: {
-        readOnlyHint: true,
+        readOnlyHint: false, // handler POSTs and creates a second_opinion_requests row every call
         destructiveHint: false,
-        idempotentHint: true,
+        idempotentHint: false, // each call submits a fresh LLM request
         openWorldHint: true,
     },
     description: "Get an IMMEDIATE, ad hoc independent critique or pushback on a plan, recommendation, or analysis you ALREADY HAVE in hand, from a different LLM model family. " +
         "Use this when you want a second, independent opinion before acting on a non-trivial decision — for example, when committing to an implementation approach, a risky refactor, an architectural trade-off, or a recommendation you would otherwise present to a user with no further validation. " +
-        "This tool does NOT create or retrieve any Bridge artifact: it does not generate or fetch plans, ticket critiques, clarifying questions, architecture docs, deep research, brainstorms, or reimplementation context, and it stores nothing. It simply returns the other model's reply to your prompt right now. " +
+        "This tool does NOT create or retrieve any Bridge artifact: it does not generate or fetch plans, ticket critiques, clarifying questions, architecture docs, deep research, brainstorms, or reimplementation context, and it persists only an internal request-tracking row, no retrievable artifact. It simply returns the other model's reply to your prompt right now. " +
         "If instead you want a Bridge ARTIFACT (a plan, critique, clarifying questions, architecture doc, reimplementation context, etc.) generated by a different provider, do NOT use this tool — call the matching `request_*` tool and set that tool's own `second_opinion` or `provider` parameter to route its generation to another provider. " +
         "Pick a provider from a DIFFERENT model family than the one you are running on so the response is genuinely independent (e.g. if you are an OpenAI agent, ask 'anthropic' or 'gemini'). " +
         "Pick a model tier appropriate for the depth of pushback you want: CHEAP_MODEL for a quick sanity check, BASIC_MODEL for a focused review, PREMIUM_MODEL for serious architectural pushback. " +
@@ -1490,7 +1675,10 @@ registerTool("second_opinion", {
             .describe("Model tier within the chosen provider. CHEAP_MODEL for quick sanity checks, BASIC_MODEL for focused reviews, PREMIUM_MODEL for serious architectural pushback."),
     },
 }, async ({ prompt, provider, model }) => {
-    const resp = await fetch(buildApiUrl("/llm/second-opinion"), {
+    // The backend is async (submit -> poll -> result) so a slow second opinion
+    // no longer exceeds the server's 30s request timeout (H12). This tool
+    // absorbs the polling so the agent still gets the reply in a single call.
+    const submitResp = await fetch(buildApiUrl("/llm/second-opinion"), {
         method: "POST",
         headers: await getPostHeaders(),
         body: JSON.stringify({
@@ -1500,7 +1688,65 @@ registerTool("second_opinion", {
             model,
         }),
     });
-    const text = await handleResponse(resp);
+    if (!submitResp.ok) {
+        const text = await handleResponse(submitResp);
+        return { content: [{ type: "text", text }] };
+    }
+    const submitBody = (await submitResp.json());
+    const requestId = submitBody.request_id;
+    if (typeof requestId !== "number") {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ error: "Second opinion submit response is missing request_id", status: 500 }),
+                },
+            ],
+        };
+    }
+    const repoQuery = `repo_name=${encodeURIComponent(REPO_NAME)}`;
+    const statusUrl = buildApiUrl(`/llm/second-opinion/${requestId}/status?${repoQuery}`);
+    const resultUrl = buildApiUrl(`/llm/second-opinion/${requestId}/result?${repoQuery}`);
+    // Poll /status until terminal. A second opinion is typically 20-90s but can
+    // approach the server's 240s tool-loop deadline; start at 3s, back off to 8s
+    // after 30s, cap at 300s. The server-side janitor fails truly-stuck rows
+    // only after 15 min, so this cap always returns the recoverable message well
+    // before a live row is touched.
+    const startTime = Date.now();
+    const timeoutMs = 300_000;
+    let pollIntervalMs = 3_000;
+    let finalStatus = "";
+    while (true) {
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+        if (Date.now() - startTime >= timeoutMs) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Second opinion is still processing after ${Math.round(timeoutMs / 1000)}s (request_id=${requestId}). The result is recoverable from the server via GET /llm/second-opinion/${requestId}/result?${repoQuery} once it finishes.`,
+                    },
+                ],
+            };
+        }
+        if (Date.now() - startTime > 30_000) {
+            pollIntervalMs = 8_000;
+        }
+        const statusResp = await fetch(statusUrl, { headers: await getGetHeaders() });
+        if (!statusResp.ok) {
+            const text = await handleResponse(statusResp);
+            return { content: [{ type: "text", text }] };
+        }
+        const statusBody = (await statusResp.json());
+        finalStatus = typeof statusBody.status === "string" ? statusBody.status : "";
+        if (finalStatus === "completed" || finalStatus === "failed") {
+            break;
+        }
+    }
+    // Both terminal states are served by /result: completed returns the
+    // {response, provider, tier, model} JSON; failed returns the sanitized 409
+    // failure detail. handleResponse preserves the prior single-call output shape.
+    const resultResp = await fetch(resultUrl, { headers: await getGetHeaders() });
+    const text = await handleResponse(resultResp);
     return { content: [{ type: "text", text }] };
 });
 registerTool("generate_image", {
@@ -1892,11 +2138,10 @@ registerTool("get_plan", {
         idempotentHint: true,
         openWorldHint: true,
     },
-    description: "RETRIEVE an already-generated implementation plan for a Jira ticket. This tool only fetches an existing plan — it does NOT start or trigger plan generation. " +
+    description: "RETRIEVE an already-generated implementation plan for a Jira ticket as markdown. This tool only fetches an existing plan — it does NOT start or trigger plan generation. " +
         "If no plan exists yet (or you need a fresh one), call `request_plan_generation` first; it starts the async generation and this `get_plan` tool retrieves the result. " +
-        "Returns the full plan as markdown text — present it verbatim without summarizing. " +
-        "The plan includes step-by-step implementation guidance with code file references. " +
-        "Returns a 404 / not-found response when no plan is ready yet (the ticket may not have been processed by Bridge API) — that means generation has not run, not that this tool failed. " +
+        "Returns the full plan as markdown verbatim — present it without summarizing. " +
+        "Returns a 404 / not-found response when no plan is ready yet — that means generation has not run, not that this tool failed. " +
         "Tip: call get_clarifying_questions for the same ticket to get the full context for implementation.",
     inputSchema: {
         ticket_number: z
@@ -1906,7 +2151,7 @@ registerTool("get_plan", {
             .boolean()
             .optional()
             .default(true)
-            .describe("Whether to save the plan to a local file in the BAPI_DOCS_DIR/plans/ directory. " +
+            .describe("Whether to save the retrieved plan to a local file. Saves to BAPI_DOCS_DIR/plans/{ticket}-plan.md. " +
             "Defaults to true. Set to false to skip saving."),
     },
 }, async (args) => {
@@ -1938,6 +2183,32 @@ registerTool("get_architecture", {
 }, async (args) => {
     return getTicketArtifact("architecture", args);
 });
+registerTool("get_prd", {
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    description: "RETRIEVE an already-generated Product Requirements Document (PRD) for a Jira ticket. This tool only fetches an existing PRD — it does NOT start or trigger generation. " +
+        "If no PRD exists yet (or you need a fresh one), call `request_prd` first; it starts the async generation and this `get_prd` tool retrieves the result. " +
+        "Returns the full PRD as markdown text — present it verbatim without summarizing. " +
+        "The PRD is product/stakeholder-facing: problem framing, goals, success metrics, scope, and product requirements. " +
+        "Returns a 404 / not-found response when no PRD is ready yet — that means generation has not run, not that this tool failed.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Whether to save the PRD to a local file in the BAPI_DOCS_DIR/prd/ directory. " +
+            "Defaults to true. Set to false to skip saving."),
+    },
+}, async (args) => {
+    return getTicketArtifact("prd", args);
+});
 registerTool("get_clarifying_questions", {
     annotations: {
         readOnlyHint: true,
@@ -2151,11 +2422,14 @@ registerTool("upload_attachment", {
         openWorldHint: true,
     },
     description: "Upload a local file as an attachment to a Jira ticket. " +
-        "Supports text/UTF-8 files only (markdown, plain text, etc.). " +
-        "Optionally syncs the content to Bridge API's tickets_links table so retrieval endpoints " +
+        "Supports binary files up to `10 MB` and text files up to `1 MB`. " +
+        "Binary files are auto-detected (extension list or UTF-8 probe) and sent as base64. " +
+        "Optionally syncs text content to Bridge API's tickets_links table so retrieval endpoints " +
         "(get_clarifying_questions, get_ticket_critique, get_plan) return the updated content without re-generation. " +
         "Use link_type to specify which retrieval endpoint should serve this content. " +
-        "Known link_type values: clarifying-questions.md, debugging-guidance.md, ticket-quality-critique.md, architecture-plan.md, fsd-plan.md.",
+        "Known link_type values: clarifying-questions.md, debugging-guidance.md, ticket-quality-critique.md, architecture-plan.md, fsd-plan.md, prd-plan.md. " +
+        "Note: link_type is text-only; cannot be used with base64 uploads. " +
+        "⚠️ SECURITY: Binary bytes cannot be secret-redacted by automated text scrubbers; review sensitive visual content before upload.",
     inputSchema: {
         ticket_number: z
             .string()
@@ -2164,13 +2438,13 @@ registerTool("upload_attachment", {
             .string()
             .optional()
             .describe("Path to a local file to upload as an attachment. " +
-            "The file must be UTF-8 encoded and under 1MB. " +
+            "Binary files (images, PDFs, etc.) are supported up to `10 MB`; text files up to `1 MB`. " +
             "If both file_path and content are provided, file_path takes precedence."),
         content: z
             .string()
             .max(1_048_576)
             .optional()
-            .describe("Inline text content to upload (max 1MB). Optional if file_path is provided."),
+            .describe("Inline text content to upload (max `1 MB`). Optional if file_path is provided."),
         file_name: z
             .string()
             .optional()
@@ -2180,8 +2454,9 @@ registerTool("upload_attachment", {
             .string()
             .optional()
             .describe("When provided, also syncs the content to Bridge API's tickets_links table. " +
-            "Known values: clarifying-questions.md, debugging-guidance.md, ticket-quality-critique.md, architecture-plan.md. " +
-            "Unknown values are accepted with a warning."),
+            "Known values: clarifying-questions.md, debugging-guidance.md, ticket-quality-critique.md, architecture-plan.md, fsd-plan.md, prd-plan.md. " +
+            "Unknown values are accepted with a warning. " +
+            "Cannot be used with binary file uploads."),
         replace_existing: z
             .boolean()
             .optional()
@@ -2190,7 +2465,7 @@ registerTool("upload_attachment", {
             "Set to false to allow duplicate filenames."),
     },
 }, async ({ ticket_number, file_path, content, file_name, link_type, replace_existing }) => {
-    const resolved = await resolveTextOrFile(content, file_path, "content");
+    const resolved = await resolveUploadAttachment(content, file_path, "content");
     if (!resolved.ok)
         return resolved.errorResponse;
     const derivedFileName = file_name
@@ -2201,6 +2476,9 @@ registerTool("upload_attachment", {
         file_name: derivedFileName,
         replace_existing,
     };
+    if (resolved.encoding) {
+        payload.encoding = resolved.encoding;
+    }
     if (link_type) {
         payload.link_type = link_type;
     }
@@ -2438,7 +2716,55 @@ registerTool("request_architecture", {
 }, async (args) => {
     return requestTicketArtifact("architecture", args);
 });
-registerTool("request_design_doc", {
+registerTool("request_prd", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    description: "START (or refresh) async generation of a Product Requirements Document (PRD) for a Jira ticket. " +
+        "This triggers an asynchronous background job — results are NOT immediate. " +
+        "Processing typically takes 2-4 minutes depending on ticket complexity. " +
+        "The matching get_prd tool retrieves the generated PRD later (call get_prd with the same ticket_number) — unless you set wait_for_result, in which case this call blocks and returns it directly. " +
+        "Returns 202 if the request was accepted, 404 if the ticket does not exist in Jira, " +
+        "or 403 if the API key is unauthorized. " +
+        "Set wait_for_result to true to block until the result is ready (typically 2-4 minutes) instead of returning immediately.",
+    inputSchema: {
+        ticket_number: z
+            .string()
+            .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate a PRD for"),
+        wait_for_result: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("When true, the tool blocks and polls until the PRD is ready (typically 2-4 minutes), " +
+            "then returns the full PRD content directly. When false (default), returns immediately " +
+            "with a confirmation message — use get_prd later to retrieve results."),
+        save_locally: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("When wait_for_result is true, whether to save the PRD to a local file in the " +
+            "BAPI_DOCS_DIR/prd/ directory. Defaults to true. Only takes effect when wait_for_result is true."),
+        second_opinion: z
+            .string()
+            .optional()
+            .describe("Provider routing override for THIS artifact-generation request " +
+            "(e.g. 'anthropic', 'openai', 'gemini'). When set, the artifact is " +
+            "generated by the named provider and, where supported, a cross-provider " +
+            "second-opinion pass is applied to this request only. " +
+            "This is NOT the standalone `second_opinion` tool — it does not return " +
+            "an ad hoc critique; it only changes which provider produces this " +
+            "request's artifact. Takes precedence over `provider` when both are set."),
+        provider: z.string().optional().describe("Pure provider switch — use a specific LLM provider (openai, anthropic, gemini) without " +
+            "triggering second-opinion semantics. If both provider and second_opinion are set, " +
+            "second_opinion takes precedence."),
+    },
+}, async (args) => {
+    return requestTicketArtifact("prd", args);
+});
+registerTool("create_doc", {
     annotations: {
         readOnlyHint: false,
         destructiveHint: false,
@@ -2446,27 +2772,28 @@ registerTool("request_design_doc", {
         openWorldHint: true,
     },
     description: "START (or refresh) async generation of a design document for a Jira ticket, routed by doc_type. " +
-        "Use doc_type 'tdd' for a Technical Design Document (architecture-focused, for engineers) or 'fsd' for a " +
-        "Functional Specification Document (product/functional-focused, for PMs, designers, and QA). " +
+        "Use doc_type 'tdd' for a Technical Design Document (architecture-focused, for engineers), 'fsd' for a " +
+        "Functional Specification Document (product/functional-focused, for PMs, designers, and QA), or 'prd' for a " +
+        "Product Requirements Document (product-requirements-focused: problem, goals, and success metrics). " +
         "This triggers an asynchronous background job — results are NOT immediate. " +
         "Processing typically takes 2-4 minutes depending on ticket complexity. " +
-        "The matching get_design_doc tool retrieves the generated document later (call get_design_doc with the same ticket_number and doc_type) — unless you set wait_for_result, in which case this call blocks and returns it directly. " +
+        "The matching get_doc tool retrieves the generated document later (call get_doc with the same ticket_number and doc_type) — unless you set wait_for_result, in which case this call blocks and returns it directly. " +
         "Returns 202 if the request was accepted, 404 if the ticket does not exist in Jira, or 403 if the API key is unauthorized.",
     inputSchema: {
         ticket_number: z
             .string()
             .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123) to generate a design document for"),
-        doc_type: z
-            .enum(["tdd", "fsd"])
-            .describe("Which design document to generate: 'tdd' (Technical Design Document, engineer audience) or " +
-            "'fsd' (Functional Specification Document, product/functional audience)."),
+        doc_type: z.enum(["tdd", "fsd", "prd"])
+            .describe("Which design document to generate: 'tdd' (Technical Design Document, engineer audience), " +
+            "'fsd' (Functional Specification Document, product/functional audience), or " +
+            "'prd' (Product Requirements Document, product-requirements focused: problem, goals, success metrics)."),
         wait_for_result: z
             .boolean()
             .optional()
             .default(false)
             .describe("When true, the tool blocks and polls until the document is ready (typically 2-4 minutes), " +
             "then returns the full content directly. When false (default), returns immediately " +
-            "with a confirmation message — use get_design_doc later to retrieve results."),
+            "with a confirmation message — use get_doc later to retrieve results."),
         save_locally: z
             .boolean()
             .optional()
@@ -2488,7 +2815,7 @@ registerTool("request_design_doc", {
 }, async (args) => {
     return requestTicketArtifact(resolveDesignDocArtifactType(args.doc_type), args);
 });
-registerTool("get_design_doc", {
+registerTool("get_doc", {
     annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -2496,19 +2823,19 @@ registerTool("get_design_doc", {
         openWorldHint: true,
     },
     description: "RETRIEVE an already-generated design document for a Jira ticket, routed by doc_type. " +
-        "Use doc_type 'tdd' for the Technical Design Document or 'fsd' for the Functional Specification Document. " +
+        "Use doc_type 'tdd' for the Technical Design Document, 'fsd' for the Functional Specification Document, or " +
+        "'prd' for the Product Requirements Document. " +
         "This tool only fetches an existing document — it does NOT start or trigger generation. " +
-        "If no document exists yet (or you need a fresh one), call `request_design_doc` first with the same doc_type. " +
+        "If no document exists yet (or you need a fresh one), call `create_doc` first with the same doc_type. " +
         "Returns the full document as markdown text — present it verbatim without summarizing. " +
         "Returns a 404 / not-found response when no document is ready yet — that means generation has not run, not that this tool failed.",
     inputSchema: {
         ticket_number: z
             .string()
             .describe("Jira ticket key in PROJECT-NUMBER format (e.g. PROJ-123, BAPI-42)"),
-        doc_type: z
-            .enum(["tdd", "fsd"])
-            .describe("Which design document to retrieve: 'tdd' (Technical Design Document) or " +
-            "'fsd' (Functional Specification Document)."),
+        doc_type: z.enum(["tdd", "fsd", "prd"])
+            .describe("Which design document to retrieve: 'tdd' (Technical Design Document), " +
+            "'fsd' (Functional Specification Document), or 'prd' (Product Requirements Document)."),
         save_locally: z
             .boolean()
             .optional()
@@ -2941,7 +3268,7 @@ registerTool("resolve_target_status", {
 // ---------------------------------------------------------------------------
 const VALID_CONFIG_FIELDS = [
     "review_instructions", "documentation_instructions", "architecture_instructions",
-    "tdd_document_instructions", "fsd_document_instructions",
+    "tdd_document_instructions", "fsd_document_instructions", "prd_document_instructions",
     "unit_testing_instructions", "e2e_testing_instructions",
     "unit_testing_stack", "e2e_testing_stack",
     "frontend_correctness_standards", "backend_correctness_standards",
@@ -2950,6 +3277,7 @@ const VALID_CONFIG_FIELDS = [
     "post_pr_target_status", "ci_check_config", "ci_followup_config",
     "allow_mutating_smoke_ops",
     "selected_mcp_slugs",
+    "split_review_reorder_enabled",
     "base_branch",
     "difficulty_model_routing_enabled",
     "difficulty_model_tier_overrides",
@@ -3124,7 +3452,7 @@ registerTool("update_config_field", {
     }
     // Scalar boolean config fields: reject file-path updates and normalize boolean
     // true/false and string "true"/"false" to a real boolean before persisting.
-    const BOOLEAN_CONFIG_FIELDS = ["allow_mutating_smoke_ops", "difficulty_model_routing_enabled"];
+    const BOOLEAN_CONFIG_FIELDS = ["allow_mutating_smoke_ops", "difficulty_model_routing_enabled", "split_review_reorder_enabled"];
     if (BOOLEAN_CONFIG_FIELDS.includes(field_name)) {
         if (file_path) {
             return {
@@ -3249,6 +3577,99 @@ registerTool("apply_install_manifest", {
     const text = await handleResponse(resp);
     return { content: [{ type: "text", text }] };
 });
+registerTool("persist_routing_credential", {
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    description: "Persist the ALREADY-VALIDATED Bridge API key for this repo into the user-scoped credential " +
+        "store (`~/.config/bridge/credentials.json`) under the target `bapi:<repo_name>`, so that " +
+        "Bash-spawned CLI features such as `start-tickets` (a different runtime surface than the MCP " +
+        "server) can resolve it for difficulty→model routing. This is the final stage of `/install-bridge`. " +
+        "The key is resolved INSIDE the MCP server process (env-first, then the existing store) using the " +
+        "provided `repo_name` as the store identity — it is NEVER passed as a tool argument. Existing " +
+        "credentials are preserved; only `BAPI_API_KEY` for this repo is upserted. The response is " +
+        "secret-free (it reports ok/action/target/path only) and never echoes the key value.",
+    inputSchema: {
+        repo_name: z
+            .string()
+            .describe("The repository name to store the routing credential under (target `bapi:<repo_name>`). " +
+            "This is the ONLY input — do not pass the API key, a secret, or a token; the key is " +
+            "resolved inside the MCP server process."),
+    },
+}, async ({ repo_name }) => {
+    const repoName = typeof repo_name === "string" ? repo_name.trim() : "";
+    const deps = buildCredentialStoreWriteDeps();
+    const storePath = getPrimaryCredentialStorePath(deps);
+    if (repoName.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ok: false,
+                        message: "Cannot persist routing credential: repo_name is required. Pass the repo name " +
+                            "this install is configuring.",
+                        path: storePath,
+                    }),
+                },
+            ],
+        };
+    }
+    const target = `bapi:${repoName}`;
+    const apiKey = await getResolvedApiKeyForRepo(repoName);
+    if (apiKey.length === 0) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ok: false,
+                        target,
+                        path: storePath,
+                        message: `No BAPI_API_KEY could be resolved for ${target}. Set BAPI_API_KEY in the ` +
+                            `environment (or add it under ${target} in ${storePath}) and rerun /install-bridge.`,
+                    }),
+                },
+            ],
+        };
+    }
+    const result = await upsertBapiCredential(repoName, apiKey, deps);
+    if (!result.ok) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ok: false,
+                        target: result.target,
+                        path: result.path,
+                        kind: result.kind,
+                        message: `Failed to persist routing credential for ${result.target}: ${result.error} ` +
+                            `You can rerun /install-bridge or migrate manually.`,
+                    }),
+                },
+            ],
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    ok: true,
+                    action: result.action,
+                    target: result.target,
+                    path: result.path,
+                    migratedFallback: result.migratedFallback,
+                    message: `Stored routing credential for ${result.target} at ${result.path}.`,
+                }),
+            },
+        ],
+    };
+});
 function formatDeepResearchProviderReason(meta) {
     if (!meta)
         return "";
@@ -3568,21 +3989,23 @@ registerTool("request_brainstorm", {
         openWorldHint: true,
     },
     description: "START an async brainstorm that fans out the task to two opinion-provider LLMs " +
-        "(default: OpenAI + Gemini) and then runs a synthesizer pass over the completed opinions. " +
+        "(default: OpenAI + Gemini) and returns each provider's opinion directly (no synthesizer pass). " +
         "Returns a brainstorm_id; the matching get_brainstorm tool retrieves the finished result later (unless you set wait_for_result). " +
         "\n\n" +
         "BEHAVIOR: By default, returns immediately with a brainstorm_id. Set wait_for_result=true " +
         "to poll for terminal status (up to 15 minutes), then retrieve and optionally save the result. " +
         "When save_locally=true (default), each provider's markdown is written with a semantic " +
         "filename derived from task_description: " +
-        "BAPI_DOCS_DIR/brainstorm/{slugified-task-description}-{short_brainstorm_id}-{provider}.md, " +
-        "and the synthesizer row follows the same pattern " +
-        "({slugified-task-description}-{short_brainstorm_id}-synthesizer.md). " +
+        "BAPI_DOCS_DIR/brainstorm/{slugified-task-description}-{short_brainstorm_id}-{provider}.md. " +
         "(If task_description is empty or slugifies to nothing, it falls back to {brainstorm_id}-{provider}.md.) " +
         "\n\n" +
-        "DESIGN MODE: Set design=true to run the brainstorm as web-page/UI design ideation focused on " +
-        "visual appeal and conversion, rather than the default software-engineering framing. Omit the " +
-        "design field unless you want design mode (absent is treated as false).",
+        "MODES: Set mode to pick the brainstorm style. 'technical' (default) runs the implementation/" +
+        "architecture brainstorm. 'design' runs web-page/UI design ideation focused on visual appeal and " +
+        "conversion. 'discovery' generates stakeholder discovery questions for early/vague tasks, grouped " +
+        "into 'Technical Discovery Questions' and 'Business / Stakeholder Discovery Questions' and tagged " +
+        "[HUMAN], [CODE], or [TICKET]; discovery needs no extra configuration. " +
+        "The legacy boolean design=true still works and maps to mode='design'; prefer the explicit mode " +
+        "selector for new callers.",
     inputSchema: {
         task_description: z.string().describe("Free-form description of the task to brainstorm about. Sent verbatim — " +
             "this tool does NOT read task_description from a file."),
@@ -3590,7 +4013,8 @@ registerTool("request_brainstorm", {
         ticket_number: z.string().optional().describe("Optional Jira ticket key (e.g. PROJ-123) to associate with the brainstorm. " +
             "Ticket 1 only stores this for cross-reference — no Jira writes happen."),
         providers: z.array(z.string()).optional().describe("Opinion-provider LLMs. Defaults to ['openai', 'gemini']. " +
-            "A single-provider request still inserts a synthesizer row but pre-skips it."),
+            "A single-provider request runs one opinion provider and returns that " +
+            "provider's markdown directly."),
         concerns: z.string().optional().describe("Optional caller-supplied concerns to surface to the brainstorm agents."),
         wait_for_result: z.boolean().optional().describe("When true, polls until every row reaches a terminal status (max 15 minutes), " +
             "then returns the full result envelope. When false (default), returns immediately."),
@@ -3598,11 +4022,17 @@ registerTool("request_brainstorm", {
             "after the result is fetched. Request-time saves use semantic filenames derived from " +
             "task_description (slugified) plus a short brainstorm-id segment."),
         prior_brainstorm_id: z.string().optional().describe("Optional brainstorm_id from an earlier brainstorm to refine. " +
-            "When provided, the new brainstorm receives the prior brainstorm's " +
-            "synthesizer markdown, or a completed opinion-provider fallback, as prior context."),
-        design: z.boolean().optional().describe("Set to true for web-page/UI design ideation focused on visual appeal and conversion. Omit this field when not requesting design mode; absent is treated as false."),
+            "When provided, the prior brainstorm's completed opinion-provider " +
+            "markdowns are concatenated and supplied as prior context."),
+        mode: z.enum(["technical", "design", "discovery"]).optional().describe("Preferred brainstorm-mode selector for new callers. 'technical' (default) is the " +
+            "implementation/architecture brainstorm; 'design' is web-page/UI visual-direction ideation; " +
+            "'discovery' generates grouped technical and business/stakeholder discovery questions for " +
+            "early/vague tasks. Takes precedence over the legacy boolean design field."),
+        design: z.boolean().optional().describe("Legacy compatibility flag: set to true for web-page/UI design ideation focused on visual appeal " +
+            "and conversion. New callers should use mode: \"design\" instead. Omit this field when not " +
+            "requesting design mode; absent is treated as false."),
     },
-}, async ({ task_description, repo_name, ticket_number, providers, concerns, wait_for_result, save_locally, prior_brainstorm_id, design, }) => {
+}, async ({ task_description, repo_name, ticket_number, providers, concerns, wait_for_result, save_locally, prior_brainstorm_id, mode, design, }) => {
     const effectiveRepo = repo_name && repo_name.length > 0 ? repo_name : REPO_NAME;
     const effectiveProviders = providers !== undefined ? providers : ["openai", "gemini"];
     const shouldWait = wait_for_result === true;
@@ -3619,6 +4049,14 @@ registerTool("request_brainstorm", {
     if (prior_brainstorm_id) {
         submitPayload.prior_brainstorm_request_id = prior_brainstorm_id;
     }
+    // Forward `mode` only when the caller explicitly set one, mirroring the
+    // legacy `design` handling below. Leaving it absent lets the backend apply
+    // its own precedence (legacy `design` → prior-row inheritance → technical),
+    // which is required for a design/discovery refinement to keep its mode.
+    if (mode)
+        submitPayload.mode = mode;
+    // Preserve the legacy boolean mapping so a backend that only reads `design`
+    // still behaves correctly.
     if (design)
         submitPayload.design = true;
     const submitResp = await fetch(buildUrl("/brainstorms"), {
@@ -3630,11 +4068,13 @@ registerTool("request_brainstorm", {
         const errorText = await handleResponse(submitResp);
         return { content: [{ type: "text", text: errorText }] };
     }
+    // ``synthesizer_status`` is a temporary backend compatibility sentinel
+    // (always "removed"); it is optional here and never drives control flow.
     const submitBody = (await submitResp.json());
     if (!shouldWait) {
         const confirmation = `Brainstorm submitted (brainstorm_id: ${submitBody.brainstorm_id}). ` +
             `Providers: ${submitBody.providers.join(", ")}. ` +
-            `Synthesizer status: ${submitBody.synthesizer_status}. ` +
+            `Synthesis step: removed; provider opinions will be returned directly. ` +
             `Use get_brainstorm with brainstorm_id ${submitBody.brainstorm_id} to retrieve results.`;
         return { content: [{ type: "text", text: confirmation }] };
     }
@@ -3677,9 +4117,9 @@ registerTool("get_brainstorm", {
     },
     description: "RETRIEVE the result envelope for a previously submitted brainstorm by brainstorm_id. This tool only fetches an existing/in-progress result — it does NOT start or trigger a new brainstorm. " +
         "If you have not submitted a brainstorm yet (or you need a new one), call `request_brainstorm` first; it starts the async brainstorm and returns the brainstorm_id this `get_brainstorm` tool retrieves by. " +
-        "Returns all rows (opinion providers + synthesizer), including error_kind for every row; a not-found / still-processing response means the brainstorm has not completed, not that this tool failed. " +
+        "Returns opinion-provider rows only, including error_kind for every row; a not-found / still-processing response means the brainstorm has not completed, not that this tool failed. " +
         "When save_locally=true (default), writes each provider's markdown to " +
-        "BAPI_DOCS_DIR/brainstorm/{brainstorm_id}-{provider}.md (including the synthesizer file). " +
+        "BAPI_DOCS_DIR/brainstorm/{brainstorm_id}-{provider}.md. " +
         "Retrieval uses this UUID-only filename (not the semantic task-description name that " +
         "request_brainstorm uses) because the original task description is not available in the " +
         "result envelope on retrieval. " +
@@ -3818,6 +4258,23 @@ const pollCiChecksTool = registerTool("poll_ci_checks", {
     });
     const resp = await fetch(url, { headers: await getGetHeaders() });
     const text = await handleResponse(resp);
+    // BAPI-395: opportunistically emit conductor PR/CI/gate events from the
+    // already-fetched poll response. Fully best-effort — the producer validates
+    // that commit_ref binds to the local PR head before emitting, and any failure
+    // is swallowed so this NEVER changes the poll_ci_checks response body.
+    try {
+        const parsed = JSON.parse(text);
+        const looksLikePollStatus = parsed !== null &&
+            typeof parsed === "object" &&
+            !("error" in parsed) &&
+            (Array.isArray(parsed.checks) || typeof parsed.all_complete === "boolean");
+        if (looksLikePollStatus) {
+            void observePrCiFromPollResponse(commit_ref, parsed).catch(() => { });
+        }
+    }
+    catch {
+        /* non-JSON or non-poll response — nothing to produce */
+    }
     return { content: [{ type: "text", text }] };
 });
 // ---------------------------------------------------------------------------
@@ -3973,7 +4430,7 @@ registerTool("get_pipeline_recipe", {
         if ("idea" in mergedVariables) {
             mergedVariables.idea_hash = deriveIdeaHash(mergedVariables.idea);
         }
-        const recipe = resolveRecipe(pipelineDef, INSTRUCTIONS, mergedVariables, skip_steps, !!auto_approve);
+        const recipe = resolveRecipe(pipelineDef, INSTRUCTIONS, mergedVariables, skip_steps, !!auto_approve, { includeUpgradeAdviceSurfacing: UPGRADE_ADVICE_SURFACING_ENABLED });
         return {
             content: [{
                     type: "text",
@@ -4015,6 +4472,7 @@ async function buildPipelineOrchestratorDeps() {
         pipelines: PIPELINES,
         instructions: INSTRUCTIONS,
         toolHandlers: TOOL_HANDLERS,
+        includeUpgradeAdviceSurfacing: UPGRADE_ADVICE_SURFACING_ENABLED,
     };
 }
 // BAPI-326: dependency injection for the full-automation chain orchestrator.
@@ -4031,6 +4489,7 @@ async function buildChainOrchestratorDeps() {
         chainRecipes: CHAIN_RECIPES,
         instructions: INSTRUCTIONS,
         toolHandlers: TOOL_HANDLERS,
+        includeUpgradeAdviceSurfacing: UPGRADE_ADVICE_SURFACING_ENABLED,
     };
 }
 registerTool("run_pipeline", {
@@ -4376,7 +4835,11 @@ registerTool("generate_decision_page", {
         "original-question and closed-by-default codebase-evidence display, and an optional confirmed-" +
         "improvements list. Presentation labels (title, intro, section/improvements headings) are " +
         "overridable, and the output location under the docs directory is configurable, so automations " +
-        "beyond ticket review can reuse it. The user opens the HTML file in a browser, makes selections, " +
+        "beyond ticket review can reuse it. Pass artifact_type=\"pre_ticket_planning\" to additionally " +
+        "render read-only system_goals (business goal, desired end-state, system behavior, classified " +
+        "NFRs) and a read-only implementation_order section for pre-ticket epic/task framing; open NFRs " +
+        "still go in actionable_items so the human can decide them. The default artifact_type " +
+        "\"review_decisions\" is unchanged. The user opens the HTML file in a browser, makes selections, " +
         "and copies the resulting JSON output back to the agent.",
     inputSchema: DecisionPageInputShape,
 }, async (input) => {
@@ -4393,8 +4856,13 @@ registerTool("generate_decision_page", {
     if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(input.ticket_key)) {
         return validationError(`Invalid ticket_key "${input.ticket_key}": must start with a letter and contain only letters, digits, hyphens, or underscores.`);
     }
-    // No-decisions fast path: return structured response without writing a file
-    if (input.actionable_items.length === 0) {
+    // No-decisions fast path: return structured response without writing a file.
+    // pre_ticket_planning pages still render when they carry read-only goals or an
+    // implementation order even with zero open NFRs, so only short-circuit when
+    // there is genuinely nothing to show. review_decisions behavior is unchanged
+    // (it never sets system_goals/implementation_order).
+    const hasPlanningContent = input.system_goals !== undefined || (input.implementation_order?.length ?? 0) > 0;
+    if (input.actionable_items.length === 0 && !hasPlanningContent) {
         return {
             content: [{
                     type: "text",
@@ -4436,10 +4904,27 @@ registerTool("generate_decision_page", {
     if (!outputTarget.ok) {
         return validationError(outputTarget.message);
     }
-    // Read design assets and base64-encode for embedding
+    // Read design assets and base64-encode for embedding.
+    // Prefer the project root (local dev); fall back to the installed package root
+    // (consumer projects where design-assets/ isn't part of the project tree).
     const projectRootForAssets = await getProjectRoot();
-    const assetsDir = path.join(projectRootForAssets, "design-assets");
-    const fontsDir = path.join(projectRootForAssets, "public", "fonts");
+    const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../");
+    let assetsDir;
+    try {
+        await stat(path.join(projectRootForAssets, "design-assets"));
+        assetsDir = path.join(projectRootForAssets, "design-assets");
+    }
+    catch {
+        assetsDir = path.join(pkgRoot, "design-assets");
+    }
+    let fontsDir;
+    try {
+        await stat(path.join(projectRootForAssets, "public", "fonts"));
+        fontsDir = path.join(projectRootForAssets, "public", "fonts");
+    }
+    catch {
+        fontsDir = path.join(pkgRoot, "public", "fonts");
+    }
     let faviconBase64 = "";
     let logoBase64 = "";
     try {
@@ -4470,8 +4955,11 @@ registerTool("generate_decision_page", {
                 text: JSON.stringify({
                     status: "decision_page_generated",
                     file_path: filePath,
+                    artifact_type: input.artifact_type,
                     actionable_items_count: input.actionable_items.length,
                     clear_improvements_count: input.clear_improvements.length,
+                    system_goals_nfr_count: input.system_goals?.nfrs?.length ?? 0,
+                    implementation_order_count: input.implementation_order?.length ?? 0,
                 }),
             }],
     };