@bridge_gpt/mcp-server 0.2.58 → 0.2.60

package/README.md

@@ -64,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).
@@ -368,7 +369,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.58", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.60", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -390,7 +391,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.58", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.60", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -412,7 +413,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.58", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.60", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -435,7 +436,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.58", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.60", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -454,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.58", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.60", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -567,7 +568,7 @@ The tools worth knowing for most tickets.
 - **What it does:** Creates one git worktree per ticket and spawns an agent session in each to implement them in parallel.
 - **When it's useful:** (Implementation | Automation) When you're ready to start building one or more refined tickets concurrently.
 - **How to use it:** `/start-tickets BAPI-248 BAPI-250` (see [CLI Subcommands](#cli-subcommands) for the full flag table and cross-platform behavior).
-- **Flags:** `--auto` skip the approval gates · `--base-branch <branch>` branch off something other than the default · `--workflow implement|review-and-implement` selects which slash command each spawned worktree runs · `--rounds=1|2` forwarded to the review phase, valid only with `--workflow review-and-implement` · `--tier cheap|basic|premium` coarse model-routing override.
+- **Flags:** `--auto` skip the approval gates · `--base-branch <branch>` branch off something other than the default · `--workflow implement|review-and-implement` selects which slash command each spawned worktree runs · `--rounds=1|2` forwarded to the review phase, valid only with `--workflow review-and-implement` · `--tier cheap|basic|premium` strict manual model-routing override · `--auto-tier cheap|basic|premium` machine-carried raw tier for chained automation (posture-adjusted; used internally by the `/review-and-implement` handoff), mutually exclusive with `--tier`.
 
 **3. Review and Start**
 - **What it does:** Spawns one worktree per ticket; each session reviews the ticket inline and, after a per-ticket proceed/halt gate, hands off to a **fresh implementation session** that reuses the same worktree — review and implementation run in two separate agent contexts, not one shared session.
@@ -575,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**
@@ -667,43 +668,49 @@ Useful once in a while.
 - **How to use it:** Ask your agent — "Post a comment on BAPI-123: blocked on the expired Atlassian token — will retry after it is rotated."
 - **Flags:** A long comment can be attached as a file instead of inlined.
 
-**6. Read Comments**
+**6. Report MCP Bug**
+- **What it does:** Reports a Bridge MCP failure; after receipt, a response and apology will follow. Never include secrets, PII, or proprietary code.
+- **When it's useful:** (Support) When a Bridge MCP tool misbehaves and you need to report it.
+- **How to use it:** Ask your agent to report the failed MCP tool, with no secrets, PII, or proprietary code.
+- **Flags:** Critical reports trigger an immediate page; successful reports receive a response and apology follow-up.
+
+**7. Read Comments**
 - **What it does:** Reads the comment thread on a ticket.
 - **When it's useful:** (Refinement | Implementation) When the discussion on a ticket matters and you want the agent to read it before acting.
 - **How to use it:** Ask your agent — "Read the comments on BAPI-123 and summarize what was decided."
 - **Flags:** None.
 
-**7. Ticket Attachments**
+**8. Ticket Attachments**
 - **What it does:** Downloads files from a ticket to your disk, or attaches a local file to a ticket.
 - **When it's useful:** (Refinement | Implementation) When a ticket has design files or logs you need locally, or you want to attach output back to it.
 - **How to use it:** Ask your agent — "Download the design mockups attached to BAPI-123 into my docs folder," or "Attach build-log.txt to BAPI-123."
 - **Flags:** Choose the direction (download from the ticket, or upload to it) and, for a download, where the files should land.
 
-**8. Estimate Epic**
+**9. Estimate Epic**
 - **What it does:** Estimates an epic, or an explicit group of tickets you name.
 - **When it's useful:** (Architecture | Refinement) When you need a sizing pass across an epic, or across a set of tickets you name explicitly.
 - **How to use it:** `/estimate-epic BAPI-123`
 - **Flags:** Pass an epic key, or an explicit list of ticket keys to estimate as one group.
 
-**9. Regression Check**
+**10. Regression Check**
 - **What it does:** Runs the deterministic regression-reviewer (lightweight mode) against a proposed code change and reports its blast radius — which real call-sites, tests, mocks, or config the change does and doesn't account for.
 - **When it's useful:** (Correctness) Before merging a change, to see which real callers, tests, or config it leaves unaccounted for.
 - **How to use it:** `/regression-check` reviews the working tree against `HEAD` by default; `/regression-check --diff main...HEAD` reviews an explicit range.
 - **Flags:** `--diff <range>` review a specific diff/PR range instead of the working tree vs. `HEAD` · `--symbols a,b,c` review a not-yet-diffed planned change by naming its symbols directly.
 
-**10. Scan Test Coverage**
+**11. Scan Test Coverage**
 - **What it does:** Scans recently shipped tickets from git history and reports which features have or could gain integration tests, and which can only be smoke tested.
 - **When it's useful:** (Testing) Periodically, to find recently shipped features still missing integration-test coverage and how each could be smoke tested instead.
 - **How to use it:** `/scan-test-coverage` runs incrementally from the last recorded marker in `docs/test-coverage/STATE.md`.
 - **Flags:** `--since=YYYY-MM-DD` override the window start date · `--full` ignore the marker and use a 6-month lookback · `--limit=N` cap the number of features investigated.
 
-**11. Estimate Ticket**
+**12. Estimate Ticket**
 - **What it does:** One-ticket shortcut over the existing epic estimation capability: estimates a single Jira ticket via the same `estimate_epic` tool.
 - **When it's useful:** (Estimation) When you want one ticket's estimate without typing out an epic key or an explicit ticket list.
 - **How to use it:** `/estimate-ticket BAPI-123`
 - **Flags:** `--allow-partial` the sole optional flag.
 
-**12. Draft Ticket**
+**13. Draft Ticket**
 - **What it does:** Delegates to the Jira Ticket Writer to create only a local Markdown draft — it does not create or update a Jira issue.
 - **When it's useful:** (Refinement) When you want a reviewable local ticket draft before committing to an upload workflow.
 - **How to use it:** `/draft-ticket <description>`
@@ -712,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.
@@ -740,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`.
@@ -792,16 +799,37 @@ Repository and ticket housekeeping commands, beyond the tiers above. Implementat
 | `/parse-repository` | Queue a background job to index the repository for Bridge AI agents |
 | `/scan-tickets` | Sync recently-updated Jira tickets and backfill workflow timestamps |
 
-> **GitHub Copilot modes.** On VS Code's Local agent, Bridge provisions one
-> `.github/prompts/<command>.prompt.md` prompt per packaged command, including
-> `/explore-ticket`. On VS Code Agent Host, prompt files are not loaded, so the
-> installer provisions the same canonical command as a project skill at
-> `.github/skills/<command>/SKILL.md`; invoke that skill by its slash-command
-> name. Bridge does not claim Copilot CLI or cloud-agent workflow support from
-> this scaffold alone. If either artifact is not discovered, use VS Code's Chat
-> Customizations diagnostics, confirm the workspace is trusted, and invoke the
-> workflow manually with its full instructions rather than assuming the slash
-> command is available.
+> **GitHub Copilot modes.** Bridge supports Copilot workflow commands in two
+> VS Code chat modes only. The recorded live results live in
+> [`smoke-test/COPILOT-COMMAND-SMOKE.md`](smoke-test/COPILOT-COMMAND-SMOKE.md),
+> which is the authoritative discovery contract.
+>
+> | Copilot mode | Artifact Bridge writes | How you invoke it |
+> |---|---|---|
+> | 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 |
+>
+> - **When they are written.** `--init` writes both artifacts for every packaged
+>   command whenever the project has a `.vscode/` directory. `.vscode/` is only
+>   Bridge's VS Code project heuristic; it does not prove that GitHub Copilot is
+>   installed or enabled.
+> - **Input.** A prompt file reads its input from `${input:task}`. Text supplied
+>   after the slash command takes precedence when present, and the agent asks
+>   you for the task when both are empty.
+> - **Tools.** Bridge MCP tools come from the generated `.vscode/mcp.json`
+>   registration. Prompt files carry no `tools` frontmatter restriction.
+> - **Reserved names.** `.github/prompts/<packaged-command>.prompt.md` and
+>   `.github/skills/<packaged-command>/SKILL.md` are Bridge-managed. Rerunning
+>   init overwrites a changed file at one of those paths and reports
+>   `Overwritten (content changed)`. Files with any other name are never
+>   modified.
+> - **Agent definitions are separate.** `.github/agents/*.agent.md` holds agent
+>   definitions, not reusable workflow commands.
+> - **If a command is not discovered.** Open VS Code's Chat Customizations
+>   diagnostics and confirm the workspace is trusted. If Agent Host is recorded
+>   as `UNSUPPORTED_DISCOVERY`, switch the chat session to the Local agent and
+>   use the `.github/prompts/` prompt files instead.
 
 ### Extra Capabilities
 
@@ -1004,14 +1032,15 @@ npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]
 | `--agent claude\|cursor-agent` | `claude` | Agent command to launch in each worktree |
 | `--workflow implement\|review-and-implement` | `implement` | Slash command each spawned worktree runs. `review-and-implement` reviews the ticket, then hands approval to a fresh implementation session in the same worktree. `--auto` applies to both phases. |
 | `--rounds 1\|2` | unset | Review round count forwarded to the review phase. Review-only — valid only with `--workflow review-and-implement`. |
-| `--tier cheap\|basic\|premium` | unset (difficulty routing) | Coarse model-routing override. Bypasses **only** the per-ticket difficulty/tier lookup (`GET /jira/tickets/{KEY}/model-tier`) and applies this one tier to every ticket; Claude/Cursor use their registry aliases and repository overrides, while Codex uses the authenticated Bridge catalog. It is **not** a raw `--model` alias and never carries an API key or credential. A malformed value fails open to premium routing when its alias is available. Used by the `/review-and-implement` handoff to reuse the review-time tier. |
+| `--tier cheap\|basic\|premium` | unset (difficulty routing) | Strict manual model-routing override. Bypasses **only** the per-ticket difficulty/tier lookup (`GET /jira/tickets/{KEY}/model-tier`) and applies this one tier to every ticket exactly as supplied, with no per-session posture adjustment; Claude/Cursor use their registry aliases and repository overrides, while Codex uses the authenticated Bridge catalog. It is **not** a raw `--model` alias and never carries an API key or credential. A malformed value fails open to premium routing when its alias is available. Mutually exclusive with `--auto-tier`. |
+| `--auto-tier cheap\|basic\|premium` | unset | Internal/advanced machine-carried raw backend tier for chained automation (BAPI-1236). Bypasses the per-ticket lookup like `--tier`, but remains subject to the launching session's own `maximize_subscription` downshift. Used by the `/review-and-implement` handoff to reuse the review-time raw tier snapshot without silently skipping that downshift. Mutually exclusive with `--tier`. |
 | `--terminal terminal\|iterm` | auto-detect via `$TERM_PROGRAM` | Override the macOS terminal app (honored on macOS only) |
 | `--dry-run` | off | Print intended actions; create no worktrees, open no tabs (any OS) |
 | `--branch KEY=BRANCH` | `feature/<KEY>` | Use a custom branch for that ticket (repeatable) |
 | `--base-branch <BRANCH>` | `main` | Cut new worktrees from `<BRANCH>` and refresh `origin/<BRANCH>` instead of `main` |
 | `--no-refresh-main` | off (the configured base branch is refreshed) | Skip refresh of the configured base branch (default `main`). Historical flag name preserved for backward compatibility — despite the name, it now skips refresh of whatever `--base-branch` resolves to. |
 | `--max-parallel N` | `3` | Max worktrees created concurrently |
-| `--conductor` | off | Opt into the Conductor system (per-worker `BAPI_CONDUCTOR_*` env + Claude hook injection, lifecycle ledger events, and a supervisor peer tab). **Default off** — a plain run spawns `cd <worktree> && <agent> '/implement-ticket <KEY>'`. |
+| `--conductor` | off | Opt into the Conductor system (per-worker `BAPI_EPIC_IMPLEMENTER_*` env + Claude hook injection, lifecycle ledger events, and a supervisor peer tab). **Default off** — a plain run spawns `cd <worktree> && <agent> '/implement-ticket <KEY>'`. |
 | `-h`, `--help` | — | Show usage |
 
 Each `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switches each worktree up front (throttled by `--max-parallel`), then opens one tab/session per successful worktree running the selected agent. Claude is the default. Cursor with `--auto` runs headlessly after a bounded authentication/readiness check; manual Cursor runs remain interactive for human review gates. To launch Cursor Agent instead of Claude Code:
@@ -1024,7 +1053,11 @@ npx -y @bridge_gpt/mcp-server start-tickets --agent cursor-agent BAPI-248
 
 For Codex, `GET /jira/codex-model-catalog?repo_name=...` is the sole tier-to-model authority. Bridge derives its three bare CLI IDs and SHA-256 mapping revision at request time from `MODEL_REGISTRY`; the launcher fetches and validates that catalog once per invocation. Repository `difficulty_model_tier_overrides` do not apply to Codex. A failed access, config, tier, catalog, revision, or alias check omits `--model` and launches the configured Codex default. The catalog expresses **Bridge provider policy only**: it cannot confirm that the local Codex login or subscription can use a model. The CLI has no supported non-interactive entitlement probe, so routing emits that limitation as a diagnostic and never uses Bridge's OpenAI API key as proof of local access.
 
-**Coarse `--tier` override.** Passing `--tier cheap|basic|premium` bypasses only the per-ticket difficulty lookup and applies that tier to every ticket. Claude/Cursor use the same alias resolution as normal routing; Codex uses the fetched catalog. It is never a raw model alias, and no API key or credential belongs in the spawned command. A malformed tier requests the premium fallback when its alias is available; otherwise the agent default launches. `/review-and-implement` uses this flag to hand its review-time tier snapshot to the fresh implementation session.
+**Maximize-subscription posture (BAPI-1224, extended by BAPI-1236).** The per-repository `optimization_posture` config field (`quality` | `speed` | `maximize_subscription`; unset/NULL, malformed, or unreadable all resolve to `quality`) is read once per invocation, isolated from the routing-config fetch above, and applied to a tier resolved by either the automatic per-ticket difficulty lookup **or** a carried `--auto-tier` raw snapshot — both paths share the same posture resolution and downshift call site. Only `maximize_subscription` downshifts that tier one level — `premium -> basic`, `basic -> cheap`, `cheap -> cheap` (the fixed floor) — before alias resolution; `quality`, `speed`, and every degraded posture outcome preserve current (Quality) routing unchanged. Claude and Cursor still resolve the downshifted tier through their unmodified registry aliases, and Codex still indexes the fetched catalog (`catalog.models[effectiveTier]`) — no maximize-specific alias table exists anywhere. An explicit `--tier` override remains an exact manual override (the posture is never even read on that path), and the harness-local premium fallback used when no usable tier is available stays on `premium` regardless of posture. A degraded posture read never fails a spawn; it appends a secret-free `optimization-posture-unavailable` warning to affected rows and stamps at most one de-duplicated diagnostic per invocation (stderr-only, never Sentry). A separate, additive `[model-routing]` stderr line (never stdout) reports the source/baseline/posture/adjustment/effective-tier/alias for every successfully baseline-routed row, across all three routing paths (`--tier`, `--auto-tier`, and the automatic difficulty lookup).
+
+**Coarse `--tier` override.** Passing `--tier cheap|basic|premium` bypasses only the per-ticket difficulty lookup and applies that tier to every ticket exactly as supplied — posture is never read on this path. Claude/Cursor use the same alias resolution as normal routing; Codex uses the fetched catalog. It is never a raw model alias, and no API key or credential belongs in the spawned command. A malformed tier requests the premium fallback when its alias is available; otherwise the agent default launches.
+
+**Machine-carried `--auto-tier` handoff (BAPI-1236).** Passing `--auto-tier cheap|basic|premium` also bypasses the per-ticket difficulty lookup, but — unlike `--tier` — the carried tier IS routed through the launching session's own `maximize_subscription` downshift, exactly once. A malformed, empty, or repeated `--auto-tier` value is a hard parser error (no fail-open sentinel), and `--tier`/`--auto-tier` are mutually exclusive regardless of order. `/review-and-implement` uses this flag, never `--tier`, to hand its review-time raw tier snapshot to the fresh implementation session — so a `maximize_subscription` repo still gets the downshift on the chained handoff instead of silently skipping it.
 
 **Conductor observability (opt-in via `--conductor`, BAPI-394).** Conductor is **off by default**. With `--conductor`, a run mints a conductor `run_id`, emits events into the local ledger (`~/.config/bridge/events.db`), opens a supervisor peer tab, and (for Claude Code) injects a secret-free lifecycle hook into each worktree; it also sets `BRIDGE_MCP_PROFILE=conductor` so workers get the conductor MCP tools. Observability is best-effort — a conductor failure never blocks a spawn, and `--dry-run` performs no conductor side effects. (Epic-tick dispatch always enables conductor internally.) See **[CONDUCTOR.md](./docs/CONDUCTOR.md)** for the full observability, git-hook, done-gate, and auto-merge reference.
 
@@ -1080,12 +1113,12 @@ your project can actually run:
 npx -y @bridge_gpt/mcp-server drive-epic <EPIC>
 ```
 
-You are never asked to choose. Bridge currently has two conductors and a standing
-rule that they must never operate on the same epic — two transition authorities on
-one epic wedge it permanently — so the choice is made structurally rather than by
-judgement. Readiness green routes to the v2 bootstrap below (pass `--plan-file`
-and `drive-epic` runs it for you); readiness not green prints the interactive
-pilot instruction instead. If readiness is **unknown** — unreachable,
+You are never asked to choose. `drive-epic` routes to exactly one conductor, the
+v2 engine — one transition authority per epic is what keeps an epic from wedging.
+Readiness green routes to the v2 bootstrap below (pass `--plan-file`
+and `drive-epic` runs it for you); readiness not green reports that the v2 engine
+is not ready to drive this epic — there is no alternative conductor to fall back
+to — and prints no conductor invocation. If readiness is **unknown** — unreachable,
 unauthorized, or malformed — it escalates and prints no conductor invocation at
 all, because an unknown owner is not the same as a not-ready one. No branch,
 including every error path, ever offers you two paths.
@@ -1200,85 +1233,132 @@ Once the plan is approved, the **server-side reconciler** picks the run up withi
 npx -y @bridge_gpt/mcp-server executor --repo <name>
 ```
 
-### `implement-epic`
+### Conductor (epic & multi-agent orchestration)
+
+Conductor is an **opt-in, off-by-default** layer for epic supervision, inter-agent messaging, done-gate evaluation, local git-hook event producers, and conditional auto-merge. Its full reference — the v2 architecture (server-side reconciler + local executor), `setup-epic`, `epic-implementer install-git-hooks`, the supervisor `done_gate_config` / `auto_merge_enabled` settings, and the observability stream — lives in **[CONDUCTOR.md](./docs/CONDUCTOR.md)**. (The event-ledger CLI was renamed from `conductor` to `epic-implementer`; the retained `conductor` bin name is now a fixed migration pointer.)
+
+> 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.
 
-The deterministic half of the `/conduct-epic` loop: it owns the epic branch, a
-versioned local checkpoint, a per-epic lock, and the read-only probes the loop
-decides on. It never creates or mutates an `epic_run` — that is the server-side
-v2 reconciler's job, and `init` refuses to start when one is already active.
-This is EPIC-LEVEL orchestration, distinct from the ticket-level
-`implement-ticket` command.
+<!-- 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 implement-epic <verb> [flags]
+npx -y @bridge_gpt/mcp-server install-bridge conductor --merge-workflow --codeowner <@org/team|@user>
 ```
 
-**Verbs**
-
-| Verb | Flags |
-| --- | --- |
-| `init <EPIC>` | `--tickets K1,K2,…` (required), `--base-branch <b>`, `--checkpoint-path <p>`, `--dry-run`, `--json` |
-| `status <EPIC>` | `--json` (required), `--checkpoint-path <p>` |
-| `checkpoint set <EPIC>` | `--ticket <KEY>` (required), `--field <name> <value>` (repeatable), `--journal "<line>"`, `--checkpoint-path <p>` |
-| `finish <EPIC>` | `--checkpoint-path <p>`, `--json` |
-| `spawn <EPIC>` | `--ticket <KEY>` and `--prompt-file <path>` (required), `--agent claude\|cursor-agent`, `--checkpoint-path <p>`, `--json` |
-
-**Local state.** Everything lives *outside* the repository, under
-`~/.config/bridge/conduct/<repo>/` (honoring `XDG_CONFIG_HOME`), so it resolves
-identically from the main checkout and from any worktree and can never be
-committed by an agent running `git add`:
-
-| Path | Purpose |
-| --- | --- |
-| `<EPIC>.json` | the version-1 checkpoint (file `0600`, directory `0700`) |
-| `<EPIC>.json.prev` | the previous valid checkpoint, retained on every write |
-| `<EPIC>.lock` | the per-epic lock |
-| `<EPIC>/prompts/<KEY>-<kind>-<n>.md` | prompt files the caller writes for `spawn` |
-
-`status` prints the resolved `checkpoint_path`. To unpark a run a human edits the
-checkpoint (`needs_human` → `null`, plus the ticket's `status`/counters);
-`last_seen_head`, `ci_last_poll`, and `lock` are observational and are never
-hand-edited.
-
-**`init` runs ONE preflight** that reports *every* failure in a single pass and
-writes nothing unless all of them pass: `gh auth status`; Worktrunk resolves
-(honoring `BAPI_WORKTRUNK_BIN`); Bridge credentials resolve; `auto_merge_enabled`
-is on — or is turned on by PUTting the *complete* effective config back with just
-that flag flipped, which prints a line beginning `announced:`; at least one
-required CI check exists (an empty required set would make the done gate pass
-vacuously); no active server-side `epic_run` for the key; the lock is free or its
-owner is provably dead; the base branch exists on `origin` after `git fetch`; and
-the indexed-branch override is either absent or this epic's own — a re-`init`
-after a crash is accepted and its `original_base_branch` becomes the default base,
-while a *foreign* override is refused by name. `resolve-ci-checks` is called
-exactly once either way, because that call is what warms the `poll-ci-checks`
-cache the first `status` depends on. Only then does `init` push
-`epic/<EPIC>` to `origin` at the fetched base tip (no local checkout), repoint the
-index, write the checkpoint, and take the lock. `--dry-run` prints the validated
-plan and mutates nothing. A second `init` refuses with `already initialized`.
-
-**Failure posture is split on purpose.** In `status`, each probe fails *open*: a
-`gh`, CI, review, or parse failure leaves that sub-object `null`, adds an entry to
-`probe_errors`, and the command still exits `0` with a complete object — the loop
-must be able to read its own checkpoint during a GitHub outage. Everything else
-fails *closed*: a corrupt or wrong-version checkpoint makes every verb but `init`
-exit non-zero **without rewriting it**, and `checkpoint set`, `spawn`, and
-`finish` refuse a lock held by another live process. `status` never takes the lock.
-
-**Exit codes.** `0` on success — including a missing checkpoint
-(`checkpoint_exists: false`) and an idempotent second `finish`. Non-zero on any
-other failure, with a one-line reason on stderr. With `--json`, stdout is exactly
-one JSON object carrying `ok`.
-
-**Credentials** resolve only from `BAPI_API_KEY` or the user-scoped
-`bapi:<repo>` credential target, travel only in the `X-API-Key` header, and never
-appear in a command argument, in stdout/stderr, or in a journal line.
+`--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.
 
-### Conductor (epic & multi-agent orchestration)
+**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.
 
-Conductor is an **opt-in, off-by-default** layer for epic supervision, inter-agent messaging, done-gate evaluation, local git-hook event producers, and conditional auto-merge. Its full reference — the v2 architecture (server-side reconciler + local executor), `setup-epic`, `epic-implementer install-git-hooks`, the supervisor `done_gate_config` / `auto_merge_enabled` settings, and the observability stream — lives in **[CONDUCTOR.md](./docs/CONDUCTOR.md)**. (The event-ledger CLI was renamed from `conductor` to `epic-implementer`; the retained `conductor` bin name is now a fixed migration pointer.)
+#### Files it generates
 
-> 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.
+| Path | What it is |
+|---|---|
+| `.github/workflows/epic-implementer-merge.yml` | The merge workflow, contract version 1. |
+| `.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: `3d4956c9447223c37075069352cdd9aae2d561dc`
+
+```yaml
+name: Epic Implementer merge
+
+env:
+  x-bridge-merge-contract-version: 1
+
+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
+
+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
 
@@ -1559,18 +1639,56 @@ 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.
 
 ### MCP tools
 
-The authoritative tool catalog covers **75 tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). 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 authoritative tool catalog covers **77 tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). 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` (its JSON also carries `docs_dir`, `role`, and `customer_type`)
 - **Team & access** — `invite_member` (admin-only; mints a scoped access key for a teammate on an already-configured project — the plaintext key is shown exactly once)
 - **Jira tickets** — `get_tickets`, `get_ticket`, `create_ticket`, `update_ticket_description`, `add_comment`, `get_comments`
-- **Attachments** — `attachment` (operations: `upload`, `download`, `list`)
+- **Attachments** — `attachment` (operations: `upload`, `download`, `list`, `delete`); `publish_reviewed_attachment` appends only a captured review's fixed Markdown copy during auto review, leaving older Jira attachments intact.
 - **AI generation (request/get)** — `request_plan_generation`/`get_plan`, `create_doc`/`get_doc` (design docs by `doc_type`: tdd/architecture/fsd/prd, where `architecture` is an alias of `tdd`), `request_ticket_review` (writes both `get_clarifying_questions` and `get_ticket_critique`), `request_reimplement_context`/`get_reimplement_context`, `request_council`/`get_council`, `request_deep_research`/`get_deep_research`
 - **Bounded waits** — `wait_for_ticket_review`, `wait_for_ci_checks`. Each returns `state: "ready" | "pending" | "error"`; review waits default to 20 s and CI waits default to 240 s (both accept up to 240 s explicitly). `pending` is a normal, resumable result you call again on, never a failure. They exist so an agent can wait without a foreground `sleep` and without binding a long server-side operation to the 900 s MCP client deadline. `wait_for_ci_checks` reports only that checks are **terminal** — deciding pass or fail stays with the caller.
 - **Other AI** — `second_opinion`, `generate_image`, `generate_decision_page`, `visual_diff` (deterministic pixel diff of a rendered URL vs a design comp)
@@ -1587,7 +1705,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` | Full ticket quality review: clarifying questions + critique plus an automatic second-opinion pass, then evaluation and decision capture. The backend owns round orchestration; pass `--rounds=1` for a single-pass review or `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend decide adaptively. Internal atomic pipeline invoked by `/review-tickets` (inline for one key, spawned per tab for several) and by `/review-and-implement`, `/review-and-start`, `/start-tickets`, and `/conduct-epic`. | `/review-tickets PROJ-123` |
+| `review-ticket` | Full ticket quality review: clarifying questions + critique plus an automatic second-opinion pass, then evaluation and decision capture. The backend owns round orchestration; pass `--rounds=1` for a single-pass review or `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend decide adaptively. Internal atomic pipeline invoked by `/review-tickets` (inline for one key, spawned per tab for several) and by `/review-and-implement`, `/review-and-start`, and `/start-tickets`. | `/review-tickets 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` | Client-side wrapper: runs the `idea-to-ticket` recipe, then hands the created keys to `/review-and-start --auto` | `/idea-to-pr "<idea>"` |

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.";

package/build/agent-registry.js

@@ -24,6 +24,21 @@ export function isValidModelAlias(value) {
 export function isModelTier(value) {
     return value === "cheap" || value === "basic" || value === "premium";
 }
+/**
+ * BAPI-1224 — downshift one model tier: `premium -> basic`, `basic -> cheap`,
+ * `cheap -> cheap` (the fixed floor). Total and exhaustive: no permissive
+ * default branch, so extending `ModelTier` forces an explicit decision here.
+ */
+export function downshiftModelTier(tier) {
+    switch (tier) {
+        case "premium":
+            return "basic";
+        case "basic":
+            return "cheap";
+        case "cheap":
+            return "cheap";
+    }
+}
 /**
  * The registry: the ONLY place mapping an agent name to its command/spec. Seeded
  * with `claude` (default), `cursor-agent`, and `codex`. `as const satisfies` keeps