@bridge_gpt/mcp-server 0.2.2 → 0.2.4

package/README.md

@@ -174,10 +174,11 @@ For invocation, prefer the slash command — it's deterministic. A free-text exa
 These features are useful for most tickets.
 
 **1. Review Ticket**
-- **What it does:** Runs a two-round quality review of a ticket (clarifying questions + critique, plus an alternate-model second opinion) and produces a decision page to accept/reject findings.
+- **What it does:** Runs a full quality review of a ticket: clarifying questions + critique (initial round), an automatic alternate-model second opinion, then evaluates findings and produces a decision page to accept/reject them. The second-opinion pass is included by default and can be skipped with `--rounds=1`.
 - **When it's useful:** (Refinement) Right after a ticket is drafted, before anyone starts building — to surface gaps and tighten it.
 - **How to use it:** `/review-ticket BAPI-123` (command only — "review" as free text is easily mistaken for a freehand agent review).
-- **Flags:** `--auto` auto-accept findings / skip the approval gates.
+- **Flags:** `--auto` auto-accept findings / skip the approval gates · `--rounds=1` skip the automatic second-opinion review step while preserving downstream evaluation and decision-capture work (cheaper single-pass review). `--rounds=2` (default) runs the full two-round review.
+- **Multi-ticket fan-out:** `/review-tickets BAPI-123 BAPI-456` opens one terminal tab per ticket for parallel review with no worktrees (terminal launcher only — no `wt`/`git`). All `/review-ticket` flags apply; `--review KEY=auto,rounds=N` sets per-ticket overrides. Packaged CLI: `npx -y @bridge_gpt/mcp-server review-tickets KEY [KEY ...]`.
 
 **2. Start Tickets**
 - **What it does:** Creates one git worktree per ticket and spawns an agent session in each to implement them in parallel.
@@ -186,9 +187,9 @@ These features are useful for most tickets.
 - **Flags:** `--auto` skip the approval gates · `--base-branch <branch>` branch off something other than the default.
 
 **3. Brainstorm**
-- **What it does:** Fans your problem out to two different LLMs and synthesizes their approaches into one set of options. Runs in one of two modes: a **standard** brainstorm (implementation/architecture approaches) or a **design** brainstorm (UI/UX and visual direction).
-- **When it's useful:** (Architecture | Refinement) Early, when you want a spread of approaches — standard for *how to build it*, design for *how it should look*.
-- **How to use it:** ask your agent to brainstorm — *"Brainstorm approaches for adding rate limiting to the LLM client; fan it out to multiple models and synthesize."* For a design pass: *"Run a design brainstorm for the evidence-freshness dashboard UI."*
+- **What it does:** Fans your problem out to two different LLMs and returns their approaches directly. Runs in one of three modes, selected via `mode`: **`technical`** (default — implementation/architecture approaches), **`design`** (UI/UX and visual direction), or **`discovery`** (stakeholder discovery questions for early/vague tasks, grouped into `Technical Discovery Questions` and `Business / Stakeholder Discovery Questions` and tagged `[HUMAN]`/`[CODE]`/`[TICKET]`). Discovery needs no extra configuration. The legacy boolean `design=true` still works and maps to `mode: "design"`.
+- **When it's useful:** (Architecture | Refinement) Early, when you want a spread of approaches — `technical` for *how to build it*, `design` for *how it should look*, `discovery` for *what we still need to figure out* before a real ticket exists.
+- **How to use it:** ask your agent to brainstorm — *"Brainstorm approaches for adding rate limiting to the LLM client; fan it out to multiple models."* For a design pass: *"Run a design brainstorm for the evidence-freshness dashboard UI."* For early discovery: *"Run a discovery brainstorm — `request_brainstorm` with `mode: "discovery"` — for this vague request so we can collect the questions stakeholders need to answer first."*
 
 **4. Deep Research**
 - **What it does:** Runs multi-source, fact-checked web research on a technical topic and returns a cited report.
@@ -229,36 +230,42 @@ These features are good to know, but you probably won't use them every day.
 - **How to use it:** `/critique-ticket BAPI-123` — *"Critique BAPI-123 against our project standards and list what's missing or deviating."*
 - **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
 
-**4. Explore Ticket**
+**4. Create Doc**
+- **What it does:** Generates a design document for a ticket — a TDD (technical design, engineer audience), an FSD (functional spec, for product/design/QA), or a PRD (product requirements: problem, goals, success metrics) — and saves it locally.
+- **When it's useful:** (Architecture | Refinement) When a ticket needs a fuller design write-up before planning or implementation, in the shape that fits your audience.
+- **How to use it:** `/create-doc BAPI-123 --doc-type tdd` (or `fsd` / `prd`)
+- **Flags:** `--doc-type tdd|fsd|prd` which document to generate (required) · `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
+
+**5. Explore Ticket**
 - **What it does:** Explores the codebase for a task and recommends implementation options or surfaces clarifying questions, with optional research.
 - **When it's useful:** (Architecture | Refinement) Before writing a ticket or plan, when you're unsure how a change would fit the existing code.
 - **How to use it:** `/explore-ticket <task>` — *"Explore the codebase for how we'd add a Mistral LLM provider and recommend 2–3 implementation options."*
 
-**5. Second Opinion**
+**6. Second Opinion**
 - **What it does:** Gets an immediate critique of any text from a different model family — no artifact saved, just the reply.
 - **When it's useful:** (Architecture | Refinement | Implementation) Any time you want a quick sanity check on a plan, draft, or decision from a fresh perspective.
 - **How to use it:** ask your agent — *"Get a second opinion from Gemini on whether the BAPI-123 plan's migration step is safe to run against prod."*
 - **Options:** pick the provider (anthropic / openai / gemini) and the tier (cheap / basic / premium).
 
-**6. Generate Image**
+**7. Generate Image**
 - **What it does:** Generates an image from a text prompt using a provider image model (OpenAI `gpt-image-2` by default, or Google Imagen) and returns the image directly. Spends provider credits on every call.
 - **When it's useful:** (Architecture | Refinement) When you want a quick visual — a UI mockup, diagram, or illustration — to anchor a design discussion or attach to a ticket.
 - **How to use it:** ask your agent — *"Generate an image of a dashboard showing SOC2 evidence freshness as a traffic-light grid."*
 - **Options:** `provider` openai (`gpt-image-2`) / gemini (Imagen — adds an invisible SynthID watermark) · `quality` low (default, cheapest) / medium / high · `size` 1024x1024 / 1024x1536 / 1536x1024. The image is always saved to `BAPI_DOCS_DIR/images/` and also returned inline.
 
-**7. Implement Ticket**
+**8. Implement Ticket**
 - **What it does:** Full build for one ticket: generate a plan, write the code, commit, open a PR, and monitor CI.
 - **When it's useful:** (Implementation) When a ticket is ready and you want it taken from plan to open PR in one go.
 - **How to use it:** `/implement-ticket BAPI-123` (command only — "implement X" as free text almost always triggers a freehand build instead of the Bridge plan→code→PR→CI pipeline).
 - **Flags:** `--auto` skip the approval gates (e.g. auto-commit/push).
 
-**8. Full Automation**
+**9. Full Automation**
 - **What it does:** Drives the whole chain end-to-end: idea → ticket(s) → review each → spawn worktrees to implement.
 - **When it's useful:** (Automation) When you want to go from a raw idea to in-progress implementation with minimal hands-on steps.
 - **How to use it:** `/full-automation <idea>` (command only — creates tickets, spawns worktrees, and carries scheduling/`--max-children` flags that free text can't).
 - **Flags:** `--require-approval` toggle the approval gates, full automation runs end to end by default.
 
-**9. Idea to Ticket**
+**10. Idea to Ticket**
 - **What it does:** Turns a one-line idea into a Jira Task/Spike (or an Epic plus child tickets), with research, duplicate detection, and a critique pass built in.
 - **When it's useful:** (Refinement | Automation) When you have a rough idea and want a fully-formed, uploaded ticket without the manual draft-and-refine loop.
 - **How to use it:** `/idea-to-ticket <idea>`
@@ -374,6 +381,8 @@ npx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248
 
 **Difficulty-based model routing.** Before launching each agent, the CLI selects an implementation **model tier** from the ticket's `difficulty` (1-2 → cheap, 3-5 → basic, 6+ → premium) and injects it as a `--model` flag at the spawn boundary. The Python backend returns only the coarse tier (`GET /jira/tickets/{KEY}/model-tier`, computing + caching difficulty on demand); this CLI alone maps a tier to the agent-specific alias (`claude`: `haiku`/`sonnet`/`opus`; `cursor-agent`: version-suffixed strings validated against `cursor-agent --list-models`). It is gated per repo by `difficulty_model_routing_enabled` (default **ON**) with an optional `difficulty_model_tier_overrides` JSON map (tier → alias). Routing is **fail-open**: missing credentials, an evaluation failure/timeout, a backend `fallback`, an invalid/unavailable alias, an unadvertised Cursor model, or an agent without `--model` support all omit `--model` (the agent uses its default) and surface a per-ticket warning rather than failing the spawn. `--dry-run` does **not** fetch tiers or inject `--model`.
 
+**Conductor observability (BAPI-394).** A real run mints a single conductor `run_id` and emits one canonical `run.started` event into the local conductor ledger (`~/.config/bridge/events.db`), attributing each worker by `worker_id`, ticket key, and worktree path. When the selected agent is **Claude Code**, the CLI also injects a conductor lifecycle hook into each created worktree's `.claude/settings.local.json` (preserving any existing hooks) so the spawned session streams local `run.started` / `run.stopped` / `agent.notification` (and, with `BAPI_CONDUCTOR_ENABLE_PRE_TOOL_USE=1`, `tool.intent`) events. Per-worker conductor identity is passed only via secret-free environment scoped to that one terminal/tab/session — no credentials are ever placed in the env, hook command, or run metadata. Override the gate/supervisor labels with `BAPI_CONDUCTOR_GATE_NAME` / `BAPI_CONDUCTOR_SUPERVISOR_MODE`. Inspect the stream with `conductor doctor`. Observability is best-effort: a conductor failure never blocks or aborts a spawn, and `--dry-run` performs no conductor side effects.
+
 **Cross-platform spawning.** The CLI routes spawning per platform; `--dry-run` previews the platform-correct command form on any OS. An unsupported `process.platform` (not `darwin`/`win32`/`linux`) fails fast with a clear "unsupported platform" message.
 
 - **macOS** — opens a Terminal.app or iTerm tab via `osascript`.
@@ -392,6 +401,56 @@ npx -y @bridge_gpt/mcp-server doctor [--agent <name>]
 
 It is **read-only**: it never installs anything, modifies your system, adds an npm `postinstall`, spawns a terminal, or starts the MCP server, and there is no `--fix`. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command **as a manual instruction you run yourself**. The checked set is the `start-tickets` preflight prerequisites **plus `uv`** **plus the selected agent's command** (`claude` by default, or `cursor-agent` with `--agent cursor-agent`). The Worktrunk binary is probed via the resolved name (honoring `BAPI_WORKTRUNK_BIN`), not a hard-coded one. **Exit code:** `0` when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing `start-tickets` preflight now hints you to run `doctor` for an actionable diagnostics report.
 
+### `conductor install-git-hooks` (BAPI-395)
+
+Installs local git hooks that opportunistically emit conductor git/PR/CI events into the local ledger:
+
+```
+conductor install-git-hooks [--json]
+```
+
+The installed hooks are **local, unversioned, opportunistic, and bypassable**: they live in the worktree's git hooks directory (resolved via `git rev-parse --git-common-dir`), insert only a clearly-delimited managed block (preserving any existing user hook content), launch the producer **detached in the background** so a commit or ref update is never blocked, and tolerate every failure (`|| true`). A directory that is not a git worktree, or an existing hook that looks binary/unsafe, is left untouched and reported as a **degraded optional capability** — never a fatal error. The hooks installed are `post-commit` (emits `git.commit_created`) and `reference-transaction` (emits `worktree.changed` for committed ref updates).
+
+Missing hooks do **not** prevent PR/CI gate evaluation — `conductor doctor` reads hook presence and managed-snippet status **read-only** (a new `git hooks` section / `git_hooks` JSON object alongside the ledger report), and the `wait_for_done_gate` MCP tool drives CI polling and gate evaluation regardless of whether hooks are installed.
+
+#### `conductor_done_gate` config
+
+The per-repo `conductor_done_gate` config field (read through the existing config-field route) defines the v1 done gate. It supports exactly one condition, `required_ci_checks_green`:
+
+```json
+{
+  "enabled": true,
+  "conditions": [
+    { "type": "required_ci_checks_green", "required_checks": ["build", "test"] }
+  ]
+}
+```
+
+`gate.met` is emitted (exactly once per `repo + pr_number + head_sha + effective config`) only when every listed required check is present, complete, and green for the bound PR head SHA. The gate **fails closed**: an unset, disabled (`enabled` not strictly `true`), malformed, empty, or unsupported config emits no `gate.met`.
+
+#### `conductor_auto_merge_enabled` config (C6 conditional auto-merge)
+
+When a worker's PR meets the done gate (`gate.met`), the supervisor can autonomously merge it — but **only** when the repo has explicitly opted in. The per-repo `conductor_auto_merge_enabled` config field (read through the same config-field route as `conductor_done_gate`) is the opt-in switch:
+
+```json
+{ "enabled": true }
+```
+
+A bare JSON boolean (`true`) is also accepted. **Auto-merge is disabled by default.** Behavior:
+
+- **Disabled / unset / malformed → dry-run.** Anything other than `true` or `{"enabled": true}` — including unset, `false`, `{"enabled": false}`, or any malformed value — fails **closed**: the supervisor records a `merge.dry_run` event and **no PR is ever merged**.
+- **Enabled → autonomous merge** when the gate is met and the deterministic guards pass.
+- **Kill-switch.** Set `conductor_auto_merge_enabled` to `false` or remove the field to immediately stop autonomous merges. The protected merge endpoint **independently re-enforces** the flag, so even a conductor that calls it cannot merge while the flag is off.
+
+Merge authority is **deterministic code, never an LLM**. The deterministic guards, all bound to **PR number + expected head SHA (never a branch name)**:
+
+- the per-repo enablement flag (off → dry-run),
+- the PR is still open,
+- the merge is bound to the PR number plus the expected head SHA — **head-SHA drift between gate evaluation and merge aborts the merge**,
+- required CI checks are **revalidated green immediately before merge**.
+
+Idempotency is crash-safe and race-safe: a TTL lease keyed by the deterministic action key `merge:{repo}:{pr}:{head_sha}:{gate}` is claimed before acting, and an existing `merge.succeeded` for that key is terminal — the supervisor never double-merges across a crash/restart or two racing instances. The conductor never holds VCS write credentials: it calls the protected Bridge API endpoint `POST /vcs/pull-requests/{pr_number}/merge`, which owns the privileged merge, and records the returned `merge.dry_run` / `merge.attempted` / `merge.succeeded` / `merge.failed` / `merge.pending_approval` events into the local ledger. `merge.failed` is **retryable** (a drifted head SHA produces a new action key); `merge.pending_approval` is **nonterminal** — the worker remains active until a human redeems the approval token and the server returns `merge.succeeded`. **`merge.succeeded` is the only terminal merge event.** The local SQLite conductor store uses schema version 5 (BAPI-413) to accommodate the `merge.pending_approval` type in the `events.type` CHECK constraint.
+
 ## Custom Pipelines
 
 You can create your own pipelines by adding JSON files to `.bridge/pipelines/`. Running `--init` scaffolds this directory with a `README.md` and an example pipeline to get you started.
@@ -444,7 +503,7 @@ records a PASS/FAIL verdict for each one in a markdown report.
 - `smoke-test/SMOKE-TEST.md` **ships with the npm package** and is the
   **canonical** source of truth for the smoke test.
 - The smoke test **adds no MCP tool** and **does not change the registered
-  tool surface** (the server still registers its existing 55 tools).
+  tool surface** (the server still registers its existing 62 tools).
 - It is **opt-in**: default `--init` **does not scaffold `/smoke-test-mcp`**, so
   consumer command palettes are not polluted.
 
@@ -479,6 +538,7 @@ Reports are written to `<BAPI_DOCS_DIR>/smoke-test/REPORT-<host>-<timestamp>.md`
 | `BAPI_PIPELINES_DIR` | No | `.bridge/pipelines` | Directory for user-defined custom pipeline JSON files |
 | `BAPI_WORKTRUNK_BIN` | No | `wt` (`git-wt` on Windows) | Override the Worktrunk executable name/path used by `start-tickets` for nonstandard installs |
 | `BAPI_TMUX_SESSION` | No | `bridge-start-tickets` | Override the tmux session-name prefix used by `start-tickets` on Linux |
+| `BAPI_MCP_UPGRADE_ADVICE_ENABLED` | No | _(enabled)_ | MCP-local opt-out for proactively surfacing upgrade advice in pipeline recipe preambles. Set to `false`/`0`/`no`/`off`/`disabled` to suppress. Disabling it does **not** change the `/jira/ping` response or server-side upgrade computation — it only gates the recipe-preamble convention |
 
 ## Worktree credentials and the `mcp-invoke` shim
 
@@ -525,18 +585,40 @@ chmod 600 ~/.config/bridge/credentials.json
 `mcp-invoke` warns (but continues) if the file is group/world-readable, and it
 never creates or initializes the credential file for you.
 
+### Populating the credential store
+
+The same store also backs the shell-spawned `start-tickets` CLI (its
+difficulty→model routing runs in a Bash process that cannot see an `env` block in
+`.mcp.json` / `.cursor/mcp.json`), so the store must hold the key for routing to
+work. Two supported paths write it for you:
+
+- **Install-time upsert.** `/install-bridge`'s final stage persists the validated
+  routing credential into `~/.config/bridge/credentials.json` (target
+  `bapi:<repo>`) via the `persist_routing_credential` MCP tool — the tool resolves
+  the key inside the MCP process and writes the store, so no secret crosses the
+  wire.
+- **One-shot migration.** If a key currently lives only in `.mcp.json` /
+  `.cursor/mcp.json`, migrate it into the user-scoped store with the consent-gated
+  command (a compatibility aid, not a live fallback):
+
+  ```bash
+  npx -y @bridge_gpt/mcp-server credentials migrate-agent-config [--write-credentials]
+  ```
+
+  Run it without `--write-credentials` to preview; add the flag to write the store.
+
 ## Reference
 
 The full surface, for when you need the complete enumeration. Day-to-day, use [Usage Documentation](#usage-documentation) instead — you don't call MCP tools directly; you ask your AI assistant to perform a task, or compose tools into a pipeline.
 
 ### MCP tools
 
-The server registers **55 tools**. Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
+The server registers **62 tools**. Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
 
 - **Connectivity & identity** — `ping`, `get_my_role`, `get_docs_dir`
 - **Jira tickets** — `get_tickets`, `get_ticket`, `create_ticket`, `update_ticket_description`, `add_comment`, `get_comments`
 - **Attachments** — `list_attachments`, `upload_attachment`, `download_attachment`
-- **AI generation (request/get)** — `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `request_clarifying_questions`/`get_clarifying_questions`, `request_ticket_critique`/`get_ticket_critique`, `request_ticket_review`, `request_reimplement_context`/`get_reimplement_context`, `request_brainstorm`/`get_brainstorm`, `request_deep_research`/`get_deep_research`
+- **AI generation (request/get)** — `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `create_doc`/`get_doc` (design docs by `doc_type`: tdd/fsd/prd), `request_prd`/`get_prd`, `request_clarifying_questions`/`get_clarifying_questions`, `request_ticket_critique`/`get_ticket_critique`, `request_ticket_review`, `request_reimplement_context`/`get_reimplement_context`, `request_brainstorm`/`get_brainstorm`, `request_deep_research`/`get_deep_research`
 - **Other AI** — `second_opinion`, `generate_image`, `generate_decision_page`
 - **Ticket lifecycle** — `track_ticket`, `update_ticket_state`, `get_ticket_state`
 - **Jira status** — `get_jira_transitions`, `update_jira_status`, `resolve_target_status`
@@ -551,7 +633,7 @@ Pipelines are declarative, multi-step workflows your AI agent executes step-by-s
 | Pipeline | Description | Invoke with |
 |---|---|---|
 | `implement-ticket` | Generate a plan, execute the implementation, commit, open a PR, and monitor CI | `/implement-ticket PROJ-123` |
-| `review-ticket` | Two-round ticket quality review: clarifying questions and critique from multiple providers | `/review-ticket PROJ-123` |
+| `review-ticket` | Full ticket quality review: initial clarifying questions + critique, automatic second-opinion pass (default), then evaluation and decision capture. Pass `--rounds=1` to skip the second-opinion step (`--rounds=2` is the default). | `/review-ticket PROJ-123` |
 | `idea-to-ticket` | Turn an idea into a Jira Task/Spike (or Epic + children) with research, dedup, and critique | `/idea-to-ticket "<idea>"` |
 | `plan-epic` | Decompose an epic into sub-tasks with a structured exploration doc for each | `/plan-epic "<epic>"` |
 | `full-automation` | Chain: idea → ticket(s) → review each → spawn worktrees to implement | `/full-automation "<idea>"` |

package/build/agent-config-credential-migration.js

@@ -0,0 +1,272 @@
+/**
+ * agent-config-credential-migration — read-only scan + consent-gated migration of
+ * a `BAPI_API_KEY` found in an agent's MCP config file (`.mcp.json` /
+ * `.cursor/mcp.json`) into the user-scoped, durable credential store.
+ *
+ * Why this exists (BAPI-377): a secret pasted into `.mcp.json`/`.cursor/mcp.json`
+ * is visible to the MCP server process but NOT to a Bash-spawned CLI (e.g.
+ * `start-tickets`), which is a different runtime surface. Difficulty→model
+ * routing runs in the spawned CLI, so it needs the credential in the durable
+ * `~/.config/bridge/credentials.json` store. This module locates that pasted key
+ * and, ONLY with explicit consent, upserts it into the store via the single
+ * mutation primitive {@link upsertBapiCredential}.
+ *
+ * Secret-safety contract: the extracted API key value is INTERNAL. It is carried
+ * only as far as the writer and NEVER returned to display/printing code paths,
+ * never logged, and never placed in any error message. Callers may only ever
+ * DISPLAY a candidate's `filePath`/`serverName`.
+ */
+import path from "path";
+import { upsertBapiCredential, } from "./credential-store.js";
+import { resolveRequiredStartTicketsRepoName } from "./start-tickets-repo.js";
+// ---------------------------------------------------------------------------
+// Read-only parsing
+// ---------------------------------------------------------------------------
+/**
+ * Read-only parser for a single `.mcp.json` / `.cursor/mcp.json`. A missing file
+ * (`ENOENT`) yields `{state:"missing"}`. Invalid JSON yields `{state:"error"}`
+ * with a generic message that NEVER echoes file contents (the raw text could
+ * contain the secret). Otherwise the parsed (untyped) JSON is returned.
+ */
+export async function readAgentMcpConfigIfPresent(filePath, readFile) {
+    let raw;
+    try {
+        raw = await readFile(filePath);
+    }
+    catch (err) {
+        const code = err && typeof err === "object" ? err.code : undefined;
+        if (code === "ENOENT") {
+            return { state: "missing" };
+        }
+        return { state: "error", error: `Unable to read agent MCP config at ${filePath}.` };
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        // Never echo the raw text — it could contain the secret.
+        return { state: "error", error: `Agent MCP config at ${filePath} is not valid JSON.` };
+    }
+    return { state: "present", json };
+}
+// ---------------------------------------------------------------------------
+// Candidate extraction
+// ---------------------------------------------------------------------------
+/** Narrow an unknown to a plain (non-array) object. */
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Walk the standard `mcpServers` object (and tolerate a top-level `servers` key,
+ * used by some configs). For each server whose `env.BAPI_API_KEY` is a non-empty
+ * string, emit a candidate retaining the source `filePath`, the `serverName` (the
+ * mcpServers key), the `topLevelKey` (`"mcpServers"` or `"servers"`), and the
+ * secret `apiKey`. Servers without a non-empty `BAPI_API_KEY` are ignored.
+ */
+export function extractBapiApiKeyCandidates(filePath, json) {
+    const candidates = [];
+    if (!isPlainObject(json)) {
+        return candidates;
+    }
+    for (const topLevelKey of ["mcpServers", "servers"]) {
+        const serversBlock = json[topLevelKey];
+        if (!isPlainObject(serversBlock)) {
+            continue;
+        }
+        for (const [serverName, serverConfig] of Object.entries(serversBlock)) {
+            if (!isPlainObject(serverConfig)) {
+                continue;
+            }
+            const env = serverConfig.env;
+            if (!isPlainObject(env)) {
+                continue;
+            }
+            const rawKey = env.BAPI_API_KEY;
+            if (typeof rawKey !== "string") {
+                continue;
+            }
+            const apiKey = rawKey.trim();
+            if (apiKey.length === 0) {
+                continue;
+            }
+            candidates.push({ filePath, serverName, topLevelKey, apiKey });
+        }
+    }
+    return candidates;
+}
+export const AGENT_CONFIG_SOURCE_NAMES = [
+    ".mcp.json",
+    ".cursor/mcp.json",
+];
+/**
+ * Resolve which agent-config files to scan under `cwd`. When `sources` is empty
+ * or omitted, BOTH files are scanned (the default). Otherwise only the named
+ * sources are scanned, preserving the canonical scan order. Unknown source
+ * tokens are ignored here (the CLI validates them before they reach this point).
+ */
+export function resolveAgentConfigScanTargets(cwd, sources) {
+    const selected = sources && sources.length > 0
+        ? AGENT_CONFIG_SOURCE_NAMES.filter((name) => sources.includes(name))
+        : AGENT_CONFIG_SOURCE_NAMES;
+    return selected.map((name) => ({
+        name,
+        filePath: name === ".mcp.json"
+            ? path.join(cwd, ".mcp.json")
+            : path.join(cwd, ".cursor", "mcp.json"),
+    }));
+}
+/**
+ * Scan the selected agent-config files (`<cwd>/.mcp.json` and/or
+ * `<cwd>/.cursor/mcp.json`, one-shot via `path.join`) and aggregate candidates.
+ * `sources` restricts which files are scanned; empty/omitted scans BOTH. Missing
+ * files are skipped; parse errors are skipped (non-fatal) so one malformed config
+ * never blocks a migration from the other.
+ */
+export async function scanAgentMcpConfigsForBapiApiKey(deps) {
+    const targets = resolveAgentConfigScanTargets(deps.cwd, deps.sources);
+    const candidates = [];
+    for (const { filePath } of targets) {
+        const result = await readAgentMcpConfigIfPresent(filePath, deps.readFile);
+        if (result.state !== "present") {
+            // Missing or malformed configs are simply skipped (not fatal).
+            continue;
+        }
+        candidates.push(...extractBapiApiKeyCandidates(filePath, result.json));
+    }
+    return candidates;
+}
+// ---------------------------------------------------------------------------
+// Classification
+// ---------------------------------------------------------------------------
+/**
+ * Classify a candidate set: `none` when empty; `single-value` when every
+ * candidate shares the same `apiKey` (returns that shared value + candidates);
+ * `conflicting-values` when candidates disagree on the key value. The returned
+ * object is internal — callers must only ever DISPLAY `filePath`/`serverName`.
+ */
+export function classifyAgentConfigCredentialCandidates(candidates) {
+    if (candidates.length === 0) {
+        return { kind: "none" };
+    }
+    const firstValue = candidates[0].apiKey;
+    const allSame = candidates.every((c) => c.apiKey === firstValue);
+    if (allSame) {
+        return { kind: "single-value", value: firstValue, candidates };
+    }
+    return { kind: "conflicting-values", candidates };
+}
+// ---------------------------------------------------------------------------
+// Migration (consent-gated)
+// ---------------------------------------------------------------------------
+/** Render the actually-scanned paths for a secret-free message (no values). */
+function describeScannedFiles(cwd, sources) {
+    return resolveAgentConfigScanTargets(cwd, sources)
+        .map((t) => t.filePath)
+        .join(" and ");
+}
+/** Render candidate source locations for a secret-free message (no values). */
+function describeCandidateSources(candidates) {
+    return candidates.map((c) => `${c.serverName} in ${c.filePath}`).join(", ");
+}
+/**
+ * Scan, classify, and (only with explicit consent) migrate a `BAPI_API_KEY` from
+ * `.mcp.json`/`.cursor/mcp.json` into the user-scoped credential store.
+ *
+ * Flow:
+ *   1. Resolve the repo name; failure → `repo-missing`.
+ *   2. Scan + classify.
+ *   3. `none` → `no-candidates` (message names the two scanned files, secret-free).
+ *   4. `!writeCredentials` → `consent-required` WITHOUT writing (re-run with
+ *      `--write-credentials`); lists only source paths/server names.
+ *   5. `conflicting-values` → with `promptChoice`, pick by index (null → aborted);
+ *      without it, refuse with `conflicting-values` (lists only filePath/serverName).
+ *   6. `single-value` → use that candidate.
+ *   7. `upsertBapiCredential` and map its result.
+ *
+ * The api key value never appears in any returned field or message.
+ */
+export async function migrateAgentConfigCredentialToStore(deps) {
+    // 1. Repo identity (shared resolver so the store target cannot drift).
+    const repoResult = await resolveRequiredStartTicketsRepoName({
+        env: deps.env,
+        cwd: deps.cwd,
+        readFile: deps.readFile,
+    });
+    if (!repoResult.ok) {
+        return { ok: false, kind: "repo-missing", message: repoResult.error };
+    }
+    // 2. Scan + classify (honoring any --source restriction).
+    const candidates = await scanAgentMcpConfigsForBapiApiKey({
+        cwd: deps.cwd,
+        readFile: deps.readFile,
+        sources: deps.sources,
+    });
+    const classification = classifyAgentConfigCredentialCandidates(candidates);
+    // 3. Nothing found.
+    if (classification.kind === "none") {
+        return {
+            ok: false,
+            kind: "no-candidates",
+            message: `No BAPI_API_KEY found in ${describeScannedFiles(deps.cwd, deps.sources)}.`,
+        };
+    }
+    // 4. Consent gate — preview only, no write.
+    if (!deps.writeCredentials) {
+        return {
+            ok: false,
+            kind: "consent-required",
+            message: `Found a BAPI_API_KEY to migrate (${describeCandidateSources(classification.candidates)}). ` +
+                `Re-run with --write-credentials to store it in the user-scoped credential store.`,
+            candidates: classification.candidates,
+        };
+    }
+    // 5/6. Resolve a single chosen candidate.
+    let chosenCandidate;
+    if (classification.kind === "conflicting-values") {
+        if (!deps.promptChoice) {
+            return {
+                ok: false,
+                kind: "conflicting-values",
+                message: `Found conflicting BAPI_API_KEY values across ` +
+                    `${describeCandidateSources(classification.candidates)}. ` +
+                    `Re-run interactively to choose, or reconcile the configs so they agree.`,
+                candidates: classification.candidates,
+            };
+        }
+        const chosenIndex = await deps.promptChoice(classification.candidates);
+        if (chosenIndex === null) {
+            return {
+                ok: false,
+                kind: "aborted",
+                message: "Migration aborted: no credential source was chosen.",
+            };
+        }
+        const picked = classification.candidates[chosenIndex];
+        if (!picked) {
+            return {
+                ok: false,
+                kind: "aborted",
+                message: "Migration aborted: the chosen credential source was out of range.",
+            };
+        }
+        chosenCandidate = picked;
+    }
+    else {
+        // single-value — use the first candidate (all share the same value).
+        chosenCandidate = classification.candidates[0];
+    }
+    // 7. Write via the single mutation primitive.
+    const result = await upsertBapiCredential(repoResult.repoName, chosenCandidate.apiKey, deps);
+    if (!result.ok) {
+        return { ok: false, kind: result.kind, message: result.error };
+    }
+    return {
+        ok: true,
+        action: result.action,
+        target: result.target,
+        path: result.path,
+        sourceFilePath: chosenCandidate.filePath,
+        sourceServerName: chosenCandidate.serverName,
+    };
+}

package/build/agents.generated.js

@@ -8,6 +8,6 @@ export const AGENTS = {
             "model": "opus",
             "color": "blue"
         },
-        "body": "\nYou are an elite software engineering project manager and technical analyst with deep expertise in codebase archaeology and Jira ticket crafting. You excel at understanding complex codebases, identifying relevant existing code, and translating problem descriptions into precisely-scoped, actionable Jira tickets that engineers can pick up and execute with minimal ambiguity.\n\n## Your Mission\n\nGiven a problem description from the user, you will:\n1. Conduct thorough codebase research to understand the existing architecture, patterns, and relevant code\n2. Write a structured Jira ticket as a new markdown file that references specific files, functions, and patterns from the codebase\n\n## Phase 1: Deep Codebase Research\n\nThis is the most critical phase. You MUST spend significant time here before writing anything. Do NOT rush this phase.\n\n### Research Protocol\n\n1. **Understand the Problem Space**: Re-read the user's problem description carefully. Identify the domain, the affected areas, and the type of change needed (new feature, bug fix, refactor, enhancement).\n\n2. **Map the Relevant Architecture**: \n   - Search for files, modules, and directories related to the problem domain\n   - Read the key source files thoroughly — do not skim\n   - Trace code paths: how does data flow through the relevant parts of the system?\n   - Identify controller -> helper -> service -> model chains if applicable\n\n3. **Identify Extension Points**:\n   - What existing code can be reused or extended?\n   - What patterns does the codebase already use for similar functionality?\n   - Are there helper functions, utilities, or base classes that should be leveraged?\n   - Are there configuration files, metadata definitions, or templates that need modification?\n\n4. **Identify Constraints**:\n   - What conventions does the project follow? (Check CLAUDE.md, README, existing patterns)\n   - What testing patterns are used?\n   - Are there ES5 limitations, specific framework patterns, or platform constraints?\n\n5. **Catalog Your Findings**: Keep mental notes of every relevant file path, function name, pattern, and architectural decision you discover. You will reference these in the ticket.\n\n### Research Depth Guidelines\n- Read at least 5-15 relevant source files in full, more if the problem is complex\n- Follow import chains to understand dependencies\n- Check test files to understand expected behaviors and testing patterns\n- Review configuration and metadata files if relevant\n- Search for TODO comments, known limitations, or related existing issues in the code\n\n## Phase 2: Write the Jira Ticket\n\nAfter completing research, create a new markdown file with the ticket. Use the naming convention `tickets/TICKET-<short-descriptive-name>.md`. If the `tickets/` directory does not exist, create it.\n\n### Ticket Structure\n\nThe markdown file MUST contain exactly these sections:\n\n```markdown\n# [Concise Title Describing the Task]\n\n## Summary\n\n[2-4 sentences describing what this task is about, why it matters, and the high-level approach. Be specific — reference the actual system components involved.]\n\n## Requirements\n\n[Numbered list of specific, actionable requirements. Each requirement should be a clear unit of work.]\n\n1. **[Requirement Title]**: [Description of what needs to be done.]\n   - *Relevant code*: `path/to/file.js` — `functionName()` [brief note on how this code relates]\n   - *Relevant code*: `path/to/other/file.js` — [brief note]\n\n2. **[Requirement Title]**: [Description]\n   - *Relevant code*: ...\n\n[Continue for all requirements]\n\n## Acceptance Criteria\n\n[Bullet list. Each criterion is a testable, verifiable condition.]\n\n- [Specific, testable criterion]\n- [Another criterion]\n- [Continue as needed]\n```\n\n### Writing Guidelines\n\n**Summary**:\n- Be concrete, not abstract. Name the actual components, cartridges, or subsystems involved.\n- State the \"why\" — what problem does this solve or what value does it add?\n- Mention the general technical approach if it's clear from the research.\n\n**Requirements**:\n- Each requirement should represent a logical unit of work\n- Order requirements in a logical implementation sequence when possible\n- ALWAYS cite relevant existing files and functions when they exist. Use exact file paths relative to the project root.\n- Explain HOW the existing code relates: \"extend this function\", \"follow this pattern\", \"reuse this helper\", \"modify this configuration\"\n- If a requirement involves creating new files, suggest where they should live based on existing project structure conventions\n- Be specific about what needs to change vs. what needs to be created new\n- Include requirements for tests, documentation, and configuration/metadata changes if applicable\n\n**Acceptance Criteria**:\n- Every criterion must be independently verifiable\n- Cover functional requirements, edge cases, testing, and non-functional requirements\n- Include criteria for backwards compatibility if relevant\n- Include criteria for test coverage\n- Use plain `-` bullets (Jira's ADF has no native checkbox, so `- [ ]` renders as literal text)\n\n### Output Formatting (Jira upload)\n\nThe ticket is uploaded to Jira, which converts the Markdown to Atlassian Document Format (ADF) and hard-caps the description at **32,767 characters**. Keep the output clean and within budget:\n\n- **Length**: aim for under ~30,000 characters. If the scope genuinely needs more, split into a parent ticket plus sub-tickets rather than one oversized ticket.\n- **Acceptance Criteria**: plain `-` bullets, not `- [ ]` (ADF has no native checkbox).\n- **No images**: do not embed images or use relative image links.\n- **No empty headings**: every heading must have text on its line.\n- **Placeholders**: prefer `{placeholder}` over `<placeholder>`.\n\n## Quality Standards\n\n- **No vague language**: Replace \"should handle errors properly\" with \"should catch LLM provider timeouts and return a normalized error response with errorType 'TimeoutError'\"\n- **No assumptions without evidence**: Only reference code you actually read during research. If you're unsure about something, say so explicitly in the ticket.\n- **Appropriate scope**: The ticket should represent a coherent, deliverable unit of work. If the problem is too large, note that it may need to be broken into sub-tasks, but still write the parent ticket.\n- **Developer empathy**: Write as if the developer picking this up has general project knowledge but hasn't recently worked on this specific area. Give them enough context to get started quickly.\n\n## Important Reminders\n\n- Do NOT skip or abbreviate the research phase. The quality of the ticket depends entirely on the depth of your codebase understanding.\n- Do NOT make up file paths or function names. Only reference code you have actually found and read.\n- DO create the markdown file — do not just output the content to the chat. Write it to disk.\n- If the project has specific conventions (from CLAUDE.md or similar), ensure your ticket's requirements align with those conventions.\n"
+        "body": "\nYou are an elite software engineering project manager and technical analyst with deep expertise in codebase archaeology and Jira ticket crafting. You excel at understanding complex codebases, identifying relevant existing code, and translating problem descriptions into precisely-scoped, actionable Jira tickets that engineers can pick up and execute with minimal ambiguity.\n\n## Your Mission\n\nGiven a problem description from the user, you will:\n1. Conduct thorough codebase research to understand the existing architecture, patterns, and relevant code\n2. Write a structured Jira ticket as a new markdown file that references specific files, functions, and patterns from the codebase\n\n## Phase 1: Deep Codebase Research\n\nThis is the most critical phase. You MUST spend significant time here before writing anything. Do NOT rush this phase.\n\n### Research Protocol\n\n1. **Understand the Problem Space**: Re-read the user's problem description carefully. Identify the domain, the affected areas, and the type of change needed (new feature, bug fix, refactor, enhancement).\n\n2. **Map the Relevant Architecture**: \n   - Search for files, modules, and directories related to the problem domain\n   - Read the key source files thoroughly — do not skim\n   - Trace code paths: how does data flow through the relevant parts of the system?\n   - Identify controller -> helper -> service -> model chains if applicable\n\n3. **Identify Extension Points**:\n   - What existing code can be reused or extended?\n   - What patterns does the codebase already use for similar functionality?\n   - Are there helper functions, utilities, or base classes that should be leveraged?\n   - Are there configuration files, metadata definitions, or templates that need modification?\n\n4. **Identify Constraints**:\n   - What conventions does the project follow? (Check CLAUDE.md, README, existing patterns)\n   - What testing patterns are used?\n   - Are there ES5 limitations, specific framework patterns, or platform constraints?\n\n5. **Catalog Your Findings**: Keep mental notes of every relevant file path, function name, pattern, and architectural decision you discover. You will reference these in the ticket.\n\n### Research Depth Guidelines\n- Read at least 5-15 relevant source files in full, more if the problem is complex\n- Follow import chains to understand dependencies\n- Check test files to understand expected behaviors and testing patterns\n- Review configuration and metadata files if relevant\n- Search for TODO comments, known limitations, or related existing issues in the code\n\n## Phase 2: Write the Jira Ticket\n\nAfter completing research, create a new markdown file with the ticket. Use the naming convention `tickets/TICKET-<short-descriptive-name>.md`. If the `tickets/` directory does not exist, create it.\n\n### Ticket Structure\n\nThe markdown file MUST contain exactly these sections:\n\n```markdown\n# [Concise Title Describing the Task]\n\n## Summary\n\n[2-4 sentences describing what this task is about, why it matters, and the high-level approach. Be specific — reference the actual system components involved.]\n\n## Requirements\n\n[Numbered list of specific, actionable requirements. Each requirement should be a clear unit of work.]\n\n1. **[Requirement Title]**: [Description of what needs to be done.]\n   - *Relevant code*: `path/to/file.js` — `functionName()` [brief note on how this code relates]\n   - *Relevant code*: `path/to/other/file.js` — [brief note]\n\n2. **[Requirement Title]**: [Description]\n   - *Relevant code*: ...\n\n[Continue for all requirements]\n\n## Acceptance Criteria\n\n[Bullet list. Each criterion is a testable, verifiable condition.]\n\n- [Specific, testable criterion]\n- [Another criterion]\n- [Continue as needed]\n\n## Materials & Access\n\n[Trailing audit-trail section — always the LAST section of the draft. Inventory every material the ticket references, grouped by source. Use monospace backticks for file paths and other technical provenance. Redact any embedded secrets.]\n\n### Reachable Local Files\n\n- `path/to/local/file.ext` — [what it is; will be gathered and attached post-create]\n\n### External/Auth-Gated Links\n\n- [Name or purpose] — `https://example.com/...` (record-only; external/auth-gated)\n\n### Binary/Image Materials (Record-Only)\n\n- `path/to/screenshot.png` — [sanitized location/access note; not attached]\n```\n\n### Writing Guidelines\n\n**Summary**:\n- Be concrete, not abstract. Name the actual components, cartridges, or subsystems involved.\n- State the \"why\" — what problem does this solve or what value does it add?\n- Mention the general technical approach if it's clear from the research.\n\n**Requirements**:\n- Each requirement should represent a logical unit of work\n- Order requirements in a logical implementation sequence when possible\n- ALWAYS cite relevant existing files and functions when they exist. Use exact file paths relative to the project root.\n- Explain HOW the existing code relates: \"extend this function\", \"follow this pattern\", \"reuse this helper\", \"modify this configuration\"\n- If a requirement involves creating new files, suggest where they should live based on existing project structure conventions\n- Be specific about what needs to change vs. what needs to be created new\n- Include requirements for tests, documentation, and configuration/metadata changes if applicable\n\n**Acceptance Criteria**:\n- Every criterion must be independently verifiable\n- Cover functional requirements, edge cases, testing, and non-functional requirements\n- Include criteria for backwards compatibility if relevant\n- Include criteria for test coverage\n- Use plain `-` bullets (Jira's ADF has no native checkbox, so `- [ ]` renders as literal text)\n\n**Materials Completeness Inventory**:\n- After the draft is written, INVENTORY every material the ticket references: local file paths, URLs/links, named docs/designs, screenshots, and specs. This pass only INVENTORIES and RECORDS — it does NOT attach anything. The actual attachment of reachable local files happens post-create (after the Jira `ticket_key` exists) via a separate gather-and-attach step.\n- Classify each material by source using a scheme-based rule (no network probe required):\n  - **Local filesystem paths** named in the ticket body are the only **low-risk** materials — eligible to be gathered and attached post-create.\n  - Every **`http(s)` URI is external/auth-gated** — regardless of whether the user explicitly linked it (an explicitly-linked Confluence or Google Doc URL is still external/auth-gated) — and is **record-only** here.\n  - **Binary/image materials** (screenshots, PDFs, etc.) are **record-only** — document them with sanitized location/access notes; do NOT attempt to attach them.\n- Write the trailing `## Materials & Access` section (the LAST section of the draft) grouping items under the sub-headings *Reachable Local Files*, *External/Auth-Gated Links*, and *Binary/Image Materials (Record-Only)*, using bulleted lists. Use monospace formatting (backticks) for technical provenance such as file paths.\n- **Redact secrets before writing anything**: before writing any URL or access note, sanitize and redact embedded credentials, SAS tokens, API keys, and basic-auth secrets using a high-visibility placeholder such as `[REDACTED_TOKEN]`. A location/access note must NEVER expose a plaintext secret.\n\n### Output Formatting (Jira upload)\n\nThe ticket is uploaded to Jira, which converts the Markdown to Atlassian Document Format (ADF) and hard-caps the description at **32,767 characters**. Keep the output clean and within budget:\n\n- **Length**: aim for under ~30,000 characters. If the scope genuinely needs more, split into a parent ticket plus sub-tickets rather than one oversized ticket.\n- **Acceptance Criteria**: plain `-` bullets, not `- [ ]` (ADF has no native checkbox).\n- **No images**: do not embed images or use relative image links. This \"No images\" rule applies strictly to inline images in the description body; it does NOT restrict the attachments produced by the Materials Completeness Inventory / gather-and-attach pass.\n- **No empty headings**: every heading must have text on its line.\n- **Placeholders**: prefer `{placeholder}` over `<placeholder>`.\n\n## Quality Standards\n\n- **No vague language**: Replace \"should handle errors properly\" with \"should catch LLM provider timeouts and return a normalized error response with errorType 'TimeoutError'\"\n- **No assumptions without evidence**: Only reference code you actually read during research. If you're unsure about something, say so explicitly in the ticket.\n- **Appropriate scope**: The ticket should represent a coherent, deliverable unit of work. If the problem is too large, note that it may need to be broken into sub-tasks, but still write the parent ticket.\n- **Developer empathy**: Write as if the developer picking this up has general project knowledge but hasn't recently worked on this specific area. Give them enough context to get started quickly.\n\n## Important Reminders\n\n- Do NOT skip or abbreviate the research phase. The quality of the ticket depends entirely on the depth of your codebase understanding.\n- Do NOT make up file paths or function names. Only reference code you have actually found and read.\n- DO create the markdown file — do not just output the content to the chat. Write it to disk.\n- If the project has specific conventions (from CLAUDE.md or similar), ensure your ticket's requirements align with those conventions.\n"
     }
 };

package/build/chain-orchestrator.js

@@ -721,6 +721,20 @@ export function resolveStartTicketKeys(row, stageIndex, fanOutInput) {
  * only records the completed child and increments current_child_index; the
  * caller's loop decides when the whole stage is finished.
  */
+/**
+ * Format a child pipeline's recipe preamble for inclusion in a chain pause
+ * instruction (BAPI-375). Returns an empty string when the child carries no
+ * preamble (or only whitespace); otherwise the trimmed preamble followed by a
+ * blank-line separator. This is what surfaces the child recipe's shared
+ * conventions — including the upgrade-advice surfacing convention — to the
+ * agent driving a paused full-automation chain.
+ */
+function formatChildPreamble(childEnv) {
+    const preamble = childEnv.preamble;
+    if (typeof preamble !== "string" || preamble.trim() === "")
+        return "";
+    return `${preamble.trim()}\n\n`;
+}
 async function handleChildPipelineEnvelope(persistence, recipe, row, childEnv, opts) {
     const idx = row.current_stage_index;
     const stageRecipe = recipe.stages[idx];
@@ -748,7 +762,8 @@ async function handleChildPipelineEnvelope(persistence, recipe, row, childEnv, o
         catch (err) {
             return { kind: "fail", envelope: persistenceFailEnvelope(err, row, recipe) };
         }
-        const instruction = `${childEnv.instruction}` +
+        const instruction = `${formatChildPreamble(childEnv)}` +
+            `${childEnv.instruction}` +
             `${buildPriorResultsAppendix(childEnv.results)}\n\n` +
             `When done, call \`resume_full_automation\` with \`chain_run_id\` ` +
             `"${row.chain_run_id}" and \`agent_result\` set to the result described above.`;