@bridge_gpt/mcp-server 0.2.59 → 0.2.62

package/README.md

@@ -2,44 +2,6 @@
 
 The Bridge MCP is an end-to-end accelerator for shipping code within SFCC, powered by [Bridge API](https://bridgegpt-api.com). Works with Claude Code, Github Copilot, Cursor, Windsurf, and OpenAI Codex.
 
-## Personal model routing preferences
-
-Create `~/.config/bridge/model-routing.json` to choose ordered providers for
-ticket review, Second Opinion, and Council without changing shared project
-configuration. The file is personal and uncommitted, contains no credentials,
-and is reread for every request. The repository key must exactly match Bridge's
-`repo_name`:
-
-```json
-{
-  "version": 1,
-  "defaults": {
-    "review_ticket": ["gemini", "anthropic"],
-    "second_opinion": ["anthropic", "gemini"],
-    "council": ["anthropic", "gemini"]
-  },
-  "repositories": {
-    "my-repo": { "council": ["gemini"] }
-  }
-}
-```
-
-A repository entry replaces the machine entry only for a feature key it
-contains. Remove a key or set it to `[]` to restore automatic selection for
-that feature; an empty repository entry suppresses the machine entry. Delete
-the file to clear every preference. Malformed, unreadable, or unsafe files are
-ignored with a bounded local warning. Keep the file owned by your user and not
-writable by your group or others.
-
-Only the exact initialized MCP client names `codex` and `claude-code`, or their
-installer markers, identify the Codex and Claude Code families. Cursor, GitHub
-Copilot, and unlisted clients remain neutral. Automatic Codex requests prefer
-eligible Anthropic then Gemini; Claude Code requests prefer eligible OpenAI
-then Gemini. Explicit per-call choices override this personal order but must
-still pass model support, project restrictions, and feature entitlement. A
-populated project Allowed Providers list can reduce an automatic request or
-refuse an incompatible explicit request.
-
 ## Install
 
 From your **project root**, run:
@@ -102,6 +64,7 @@ account — it will ask.
 - [Custom Pipelines](#custom-pipelines)
 - [Environment Variables](#environment-variables)
 - [Worktree credentials and the `mcp-invoke` shim](#worktree-credentials-and-the-mcp-invoke-shim)
+- [Personal model routing preferences](#personal-model-routing-preferences)
 - [Reference](#reference)
 
 For advanced epic/multi-agent orchestration, see [CONDUCTOR.md](./docs/CONDUCTOR.md).
@@ -406,7 +369,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.59", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.62", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -428,7 +391,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.59", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.62", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -450,7 +413,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.59", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.62", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -473,7 +436,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.59", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.62", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -492,7 +455,7 @@ Windsurf only supports global MCP configuration.
 ```toml
 [mcp_servers.bridge]
 command = "npx"
-args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.59", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.62", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -613,16 +576,16 @@ The tools worth knowing for most tickets.
 - **How to use it:** `/review-and-start BAPI-248 BAPI-250` (single or multiple keys flow through the identical code path).
 - **Flags:** `--auto` auto-approves both the review and the implementation phase of every spawned session · `--rounds=1|2` forwarded to the review phase · `--agent`, `--base-branch`, `--max-parallel`, `--dry-run` mirror `/start-tickets`.
 
-**4. Explore Ticket**
-- **What it does:** Maps the code paths, dependencies, and project conventions a task would touch, settles its acceptance criteria with you on a decision page, then compares the viable implementation approaches and their trade-offs and writes up a proposed design. Along the way it surfaces the ambiguities that still need deciding and can pull in optional web or deep research where the answer is not in the code.
+**4. Define Tickets**
+- **What it does:** Analyzes a single task or feature specification to define, refine, and structure one or more actionable Jira tickets. It maps the code paths, dependencies, and project conventions the task would touch, settles acceptance criteria with you on a decision page, then compares the viable implementation approaches and their trade-offs so the ticket work is grounded in the real codebase. Along the way it surfaces the ambiguities that still need deciding and can pull in optional web or deep research where the answer is not in the code.
 - **When it's useful:** (Architecture | Refinement) Before writing a ticket or a plan, when you're unsure how a change would fit the existing code and want the open questions and the realistic options laid out first.
-- **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."*
+- **How to use it:** `/define-tickets <task>` — *"Define the tickets we'd need to add a Mistral LLM provider."*
 - **Flags:** None.
 
-**5. Council**
+**5. AI Council**
 - **What it does:** Fans your problem out to two different models and returns their approaches, in technical, design, discovery, or general mode.
 - **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 still needs figuring out before a real ticket exists, general for a quick brief-driven pass before the repository is indexed.
-- **How to use it:** `/council <question>`
+- **How to use it:** `/ai-council <question>`
 - **Flags:** `--mode` selects one of four modes, passed to the underlying `request_council` tool as e.g. `mode: "discovery"`: `technical` (the default — implementation/architecture approaches), `design` (UI/UX and visual direction), `discovery` (stakeholder discovery questions, grouped into `Technical Discovery Questions` and `Business / Stakeholder Discovery Questions` and tagged `[HUMAN]`/`[CODE]`/`[TICKET]`), and `general` (brief-driven ideation from your task description alone). `technical` and `discovery` are codebase-grounded and need an indexed repository; `general` needs no code index at all, so it works immediately after install. The legacy boolean `design=true` still works and maps to `mode: "design"`.
 
 **6. Deep Research**
@@ -756,7 +719,7 @@ Useful once in a while.
 
 ### Workflow commands
 
-Slash commands that drive several tools at once. Start Tickets, Review and Start, and Explore Ticket are documented above under [Regularly useful](#regularly-useful); Create Decision Page is documented above under [Occasionally useful](#occasionally-useful); Regression Check and Scan Test Coverage are documented above under [Now and then](#now-and-then) — the rest live here.
+Slash commands that drive several tools at once. Start Tickets, Review and Start, and Define Tickets are documented above under [Regularly useful](#regularly-useful); Create Decision Page is documented above under [Occasionally useful](#occasionally-useful); Regression Check and Scan Test Coverage are documented above under [Now and then](#now-and-then) — the rest live here.
 
 **1. Implement Ticket**
 - **What it does:** Full build for one ticket: generate a plan, write the code, commit, open a PR, and monitor CI.
@@ -784,7 +747,7 @@ Slash commands that drive several tools at once. Start Tickets, Review and Start
 
 #### Ticket-authoring posture
 
-`/explore-ticket`, `/idea-to-ticket`, and `/plan-epic` all decide ticket shape
+`/define-tickets`, `/idea-to-ticket`, and `/plan-epic` all decide ticket shape
 the same way, as does the `jira-ticket-writer` agent they draft through. A fresh install inherits this with no configuration
 step and no server call; the full rationale and the closed exception list ship as
 `docs/bridge-ticket-authoring.md`.
@@ -843,7 +806,7 @@ Repository and ticket housekeeping commands, beyond the tiers above. Implementat
 >
 > | Copilot mode | Artifact Bridge writes | How you invoke it |
 > |---|---|---|
-> | VS Code Local agent | `.github/prompts/<command>.prompt.md` | `/<command>`, for example `/explore-ticket` |
+> | VS Code Local agent | `.github/prompts/<command>.prompt.md` | `/<command>`, for example `/define-tickets` |
 > | VS Code Agent Host | `.github/skills/<command>/SKILL.md` (a separately verified project skill; prompt files are not loaded in this mode) | `/<command>` |
 > | Copilot CLI, Copilot cloud coding agent | None | Out of scope |
 >
@@ -1276,6 +1239,135 @@ Conductor is an **opt-in, off-by-default** layer for epic supervision, inter-age
 
 > The v1 `epic-implementer epic-tick` command is **frozen** — it throws on every invocation. There is nothing to schedule locally, and `epic-implementer doctor` flags any epic-tick schedule left over from an earlier release so you can cancel it.
 
+<!-- BEGIN GENERATED: merge-workflow-install (managed by mcp_server/scripts/sync-readme-merge-workflow.js — DO NOT EDIT BY HAND) -->
+### `install-bridge conductor --merge-workflow`
+
+Generates the Epic Implementer **merge workflow** plus its CODEOWNERS fragment
+and repository-rule guidance, commits them on a managed branch, pushes with
+**your own git identity**, and opens a pull request with **your own `gh`**.
+
+```
+npx -y @bridge_gpt/mcp-server install-bridge conductor --merge-workflow --codeowner <@org/team|@user>
+```
+
+`--codeowner` is **required** and takes exactly one `@user` or `@org/team`. It is
+never inferred from repository metadata, and a documentation placeholder is
+rejected. `--dry-run` prints the plan and performs **no** write: no branch, no
+file, no install-state write, no commit, no push, and no pull request.
+
+**Bridge performs no repository write, and the pull request is never merged for
+you.** Reviewing the workflow before it lands is the security control — it is the
+one file in your repository that can perform a privileged merge.
+
+#### Files it generates
+
+| Path | What it is |
+|---|---|
+| `.github/workflows/epic-implementer-merge.yml` | The merge workflow, contract version 2. |
+| `.bridge/merge-workflow/CODEOWNERS.fragment` | A CODEOWNERS rule for that path. Not in force until you merge it into your active CODEOWNERS file. |
+| `.bridge/merge-workflow/REPOSITORY-RULES.md` | The setup steps, including the repository rule that actually enforces review. |
+
+#### The four content outcomes
+
+Re-running is safe and reports exactly one of these:
+
+| Outcome | What happens |
+|---|---|
+| **not installed** | The workflow and companions are written on a managed branch and a pull request is opened. |
+| **managed version is older** | The same, labelled explicitly as an *upgrade* in the branch, commit, pull request title, and terminal summary. |
+| **identical** | A clean no-op. Nothing is written and no pull request is opened. |
+| **modified/unrecognized** | Fail-closed. Your file is preserved untouched and never overwritten — including a file that merely *claims* an older version in its marker. |
+
+An already-open installation or upgrade pull request is **reported, not
+duplicated**: the command verifies its branch, base, and file set and prints its
+URL instead of creating a second branch, commit, push, or pull request.
+
+#### What you must do after merging
+
+1. Create a repository Actions **secret** named `BAPI_API_KEY` holding a Bridge API key for the repository. Its value must **never** be passed to the installer, committed, printed, or placed in `--dry-run` output — the CLI has no flag, prompt, or file field that accepts one.
+2. Merge the generated CODEOWNERS rule into your active CODEOWNERS file. The fragment enforces nothing by itself.
+3. Add a default-branch repository rule requiring a pull request and code-owner review. **Until this rule exists, the workflow path is not protected.**
+
+Optionally set a repository Actions **variable** named `BAPI_BASE_URL` to point the workflow at a non-default Bridge deployment (default `https://bridgegpt-api.com`). A variable, not a workflow input: the base URL decides which server authorizes a merge.
+
+#### Merge credentials (`local` and `machine_token` modes)
+
+No merge path reads an ambient `gh` login. Each mode reads exactly one
+process-launch configuration key, with **no fallback** between them and none to
+an inherited `GH_TOKEN`, `GITHUB_TOKEN`, a `gh auth` session, or the Bridge
+credential store. Bridge never stores either value.
+
+| Mode | Key | Provenance |
+|---|---|---|
+| `local` | `BAPI_LOCAL_MERGE_TOKEN` | A configured local scoped credential. |
+| `machine_token` | `BAPI_MACHINE_MERGE_TOKEN` | Your machine user's credential. |
+
+Supply them at process launch, or from an approved external secret manager.
+
+| Preflight outcome | Remediation |
+|---|---|
+| `*_credential_missing` | Set the mode's key in the environment this MCP server is launched with. |
+| `*_credential_invalid` | GitHub rejected the configured credential. Rotate it and relaunch. |
+| `*_credential_unpermitted` | It authenticates but cannot write to this repository. Grant it merge permission. |
+| `local_gh_unavailable` | Install the GitHub CLI (`gh`) on the machine running this MCP server. |
+
+#### What the workflow does and does not do
+
+- It **never checks out** the repository and never runs pull-request content.
+- It uses **no third-party action** and no `uses:` step — only runner-provided bash, curl, jq, and `gh`.
+- It merges only under an **expected-head-SHA precondition**.
+- It **refuses a fork-origin** or otherwise unverifiable head.
+- It **refuses any base that is the repository default branch**, without retrying.
+- It **reports** the result to Bridge after the merge and read-back; the report decides nothing.
+
+`workflow_dispatch` always runs the workflow definition on the **trusted default
+branch**, so a pull request that edits the file cannot change the version that runs
+against it.
+
+#### Canonical template
+
+Git blob SHA of the rendered workflow: `83089be700759e2e4d423ecedb7373829676ef39`
+
+```yaml
+name: Epic Implementer merge
+
+env:
+  x-bridge-merge-contract-version: 2
+
+on:
+  workflow_dispatch:
+    inputs:
+      action_key:
+        description: >-
+          Durable merge-action key naming the approved attempt. A wake-up and a
+          correlator only; it authorizes nothing by itself.
+        required: true
+        type: string
+      lease_owner:
+        description: >-
+          Per-attempt lease secret proving this run is the live attempt. Never
+          printed, never echoed, never written to an output.
+        required: true
+        type: string
+      operation:
+        description: >-
+          Which job runs. `child_merge` (the default) merges an approved
+          child pull request; `integration_action` performs one integration
+          action. Selects a job only; the work itself is fetched from Bridge.
+        required: false
+        default: child_merge
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: epic-implementer-merge-${{ inputs.action_key }}
+  cancel-in-progress: false
+```
+<!-- END GENERATED: merge-workflow-install -->
+
 ## 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.
@@ -1555,6 +1647,44 @@ there is no fallback path for it.
 informational only: it cannot confirm the next worker spawn will authenticate,
 and it never blocks the doctor run or changes its exit code.
 
+## Personal model routing preferences
+
+Create `~/.config/bridge/model-routing.json` to choose ordered providers for
+ticket review, Second Opinion, and AI Council without changing shared project
+configuration. The file is personal and uncommitted, contains no credentials,
+and is reread for every request. The repository key must exactly match Bridge's
+`repo_name`:
+
+```json
+{
+  "version": 1,
+  "defaults": {
+    "review_ticket": ["gemini", "anthropic"],
+    "second_opinion": ["anthropic", "gemini"],
+    "council": ["anthropic", "gemini"]
+  },
+  "repositories": {
+    "my-repo": { "council": ["gemini"] }
+  }
+}
+```
+
+A repository entry replaces the machine entry only for a feature key it
+contains. Remove a key or set it to `[]` to restore automatic selection for
+that feature; an empty repository entry suppresses the machine entry. Delete
+the file to clear every preference. Malformed, unreadable, or unsafe files are
+ignored with a bounded local warning. Keep the file owned by your user and not
+writable by your group or others.
+
+Only the exact initialized MCP client names `codex` and `claude-code`, or their
+installer markers, identify the Codex and Claude Code families. Cursor, GitHub
+Copilot, and unlisted clients remain neutral. Automatic Codex requests prefer
+eligible Anthropic then Gemini; Claude Code requests prefer eligible OpenAI
+then Gemini. Explicit per-call choices override this personal order but must
+still pass model support, project restrictions, and feature entitlement. A
+populated project Allowed Providers list can reduce an automatic request or
+refuse an incompatible explicit request.
+
 ## 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.

package/build/agent-guidance.generated.js

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
 // This file is produced by scripts/bundle-agent-guidance.js from mcp_server/agent-guidance.md
-export const AGENT_GUIDANCE = "### Get Project Standards (`get_project_standards`)\n\n**When to use it:** (Implementation | Refinement) Before writing or reviewing code, so the agent applies this project's recorded coding standards instead of generic defaults.\n\n**How to use it:** Call the `get_project_standards` MCP tool directly — it takes no required input and returns the project's recorded standards text.\n\n### Second Opinion (`second_opinion`)\n\n**When to use it:** (Architecture | Refinement | Implementation) Any time you want a quick sanity check on a plan, draft, or decision from a fresh perspective.\n\n**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 production.\"\n\n### Council (`request_council`)\n\n**When to use it:** (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 still needs figuring out before a real ticket exists, general for a quick brief-driven pass before the repository is indexed.\n\n**How to use it:** `/council <question>`\n\n### Review Ticket (`request_ticket_review`)\n\n**When to use it:** (Refinement) Right after a ticket is drafted, before anyone starts building — to surface gaps and tighten it.\n\n**How to use it:** `/review-tickets BAPI-123` (command only — \"review\" as free text is easily mistaken for a freehand agent review). A single key reviews inline in the current session — no terminal tab, no worktree. For several tickets at once, `/review-tickets BAPI-123 BAPI-456` opens one terminal tab per ticket and reviews them in parallel with no worktrees; every review flag applies, and `--review KEY=auto,rounds=N` sets per-ticket overrides.";
+export const AGENT_GUIDANCE = "### Get Project Standards (`get_project_standards`)\n\n**When to use it:** (Implementation | Refinement) Before writing or reviewing code, so the agent applies this project's recorded coding standards instead of generic defaults.\n\n**How to use it:** Call the `get_project_standards` MCP tool directly — it takes no required input and returns the project's recorded standards text.\n\n### Second Opinion (`second_opinion`)\n\n**When to use it:** (Architecture | Refinement | Implementation) Any time you want a quick sanity check on a plan, draft, or decision from a fresh perspective.\n\n**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 production.\"\n\n### AI Council (`request_council`)\n\n**When to use it:** (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 still needs figuring out before a real ticket exists, general for a quick brief-driven pass before the repository is indexed.\n\n**How to use it:** `/ai-council <question>`\n\n### Review Ticket (`request_ticket_review`)\n\n**When to use it:** (Refinement) Right after a ticket is drafted, before anyone starts building — to surface gaps and tighten it.\n\n**How to use it:** `/review-tickets BAPI-123` (command only — \"review\" as free text is easily mistaken for a freehand agent review). A single key reviews inline in the current session — no terminal tab, no worktree. For several tickets at once, `/review-tickets BAPI-123 BAPI-456` opens one terminal tab per ticket and reviews them in parallel with no worktrees; every review flag applies, and `--review KEY=auto,rounds=N` sets per-ticket overrides.";

package/build/agent-notes.js

@@ -33,6 +33,7 @@ const AGENTS_MD_PLATFORMS = new Set([
 export function resolveAgentNotesTargets(selectedPlatforms) {
     const targets = new Set();
     const unsupported = new Set();
+    const supported = new Set();
     for (const platform of selectedPlatforms) {
         if (platform === "windsurf") {
             unsupported.add(platform);
@@ -40,6 +41,7 @@ export function resolveAgentNotesTargets(selectedPlatforms) {
         }
         if (AGENTS_MD_PLATFORMS.has(platform)) {
             targets.add("AGENTS.md");
+            supported.add(platform);
         }
         // Claude Code additionally gets a CLAUDE.md pointer — never a substitute
         // for AGENTS.md, since @AGENTS.md would otherwise dangle.
@@ -52,7 +54,11 @@ export function resolveAgentNotesTargets(selectedPlatforms) {
         ordered.push("AGENTS.md");
     if (targets.has("CLAUDE.md"))
         ordered.push("CLAUDE.md");
-    return { targets: ordered, unsupportedPlatforms: [...unsupported] };
+    return {
+        targets: ordered,
+        unsupportedPlatforms: [...unsupported],
+        supportedPlatforms: [...supported],
+    };
 }
 /** The one-line pointer note CLAUDE.md's owned region carries (BAPI-1207). */
 const CLAUDE_NOTES_POINTER_NOTE = "Bridge MCP usage guidance is maintained in AGENTS.md — see the section above.";