@bridge_gpt/mcp-server 0.2.12 → 0.2.14

package/CONDUCTOR.md

@@ -0,0 +1,131 @@
+# Conductor — epic & multi-agent orchestration
+
+Conductor is the **opt-in, off-by-default** coordination layer for running many
+agent sessions together (epic supervision, inter-agent messaging, done-gate
+evaluation, and conditional auto-merge). A normal `start-tickets` run does **not**
+involve Conductor — you opt in per run with `--conductor`, and epic-tick dispatch
+enables it internally.
+
+This document is the reference for Conductor's observability stream, local git
+hooks, and the per-repo done-gate / auto-merge config. For the everyday
+`start-tickets` flags and cross-platform behavior, see
+[README → CLI Subcommands](./README.md#cli-subcommands).
+
+## Conductor observability (opt-in via `--conductor`, BAPI-394)
+
+Conductor is **off by default** — without `--conductor` no `BAPI_CONDUCTOR_*` env,
+supervisor tab, or message-relay prompt is produced. With `--conductor`, a 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, and opens a supervisor peer tab. 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.
+(Epic-tick dispatch always enables conductor internally, independent of this flag.)
+
+When `--conductor` is set, the spawn boundary also injects
+`BRIDGE_MCP_PROFILE=conductor` so each worker registers the 8 conductor/event/
+supervisor MCP tools (a plain `start-tickets` run stays on the default `core`
+profile). See [README → Environment Variables](./README.md#environment-variables).
+
+## `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.

package/README.md

@@ -1,19 +1,58 @@
 # @bridge_gpt/mcp-server
 
-MCP server for [Bridge API](https://bridgegpt-api.com) — exposes Jira integration endpoints as MCP tools for AI coding agents. Works with Claude Code, VS Code/Copilot, Cursor, Windsurf, and OpenAI Codex.
-
-> **New here?** Jump to [Usage Documentation](#usage-documentation) for what you can actually do with Bridge, grouped by how often you'll reach for it.
+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.
+
+## Contents
+
+- [Getting Started](#getting-started)
+- [Usage Documentation](#usage-documentation)
+  - [Tier 1 — Regularly useful](#tier-1--regularly-useful)
+  - [Tier 2 — Occasionally useful](#tier-2--occasionally-useful)
+  - [Tier 3 — Now and then](#tier-3--now-and-then)
+  - [Operational commands](#operational-commands)
+  - [Extra Capabilities](#extra-capabilities)
+- [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools)
+- [CLI Subcommands](#cli-subcommands)
+- [Custom Pipelines](#custom-pipelines)
+- [Environment Variables](#environment-variables)
+- [Worktree credentials and the `mcp-invoke` shim](#worktree-credentials-and-the-mcp-invoke-shim)
+- [Reference](#reference)
+
+For advanced epic/multi-agent orchestration, see [CONDUCTOR.md](./CONDUCTOR.md).
 
 ## Getting Started
 
-### Quick start (one command)
+### Quick start
 
-From your **project root**, run:
+From your **project root**, install and connect in one command:
 
 ```bash
 npx -y @bridge_gpt/mcp-server@latest install-bridge
 ```
 
+`install-bridge` scaffolds the project, writes your editor's MCP config with real
+values, verifies connectivity, persists your API key to the user-scoped credential
+store, and opens a fresh agent session to finish setup (`/install-bridge` then
+`/learn-repository`). The only inputs are an **API key** (generate one on the Bridge
+API web UI **Security** page) and a **repo name** — everything else is derived. Add
+`--dry-run` to preview every step without writing, pinging, or spawning anything.
+
+To upgrade later, run:
+
+```bash
+npx -y @bridge_gpt/mcp-server upgrade
+```
+
+`upgrade` re-execs from `@latest`, refreshes all scaffolded artifacts (slash
+commands, agents, pipelines), rewrites the version pin, and reconnects — also
+available as the `/upgrade-bridge` slash command. (The legacy `--upgrade` flag still
+works as a fallback.)
+
+<details>
+<summary><strong>Installation Instructions</strong></summary>
+
+#### What `install-bridge` does
+
 `install-bridge` collapses the whole setup into a single command. It:
 
 1. **Scaffolds** the project (the same artifacts `--init` writes: slash commands,
@@ -55,9 +94,9 @@ That's it — once `install-bridge` finishes you're connected. If you prefer to
 it by hand (or just want to understand each step), the manual flow below does the
 same thing.
 
-### Manual Setup (Alternative)
+#### Manual Setup (Alternative)
 
-#### 1. Install the Package
+##### 1. Install the Package
 
 From your **project root**, install the MCP server and scaffold slash commands:
 
@@ -74,7 +113,7 @@ npx -y @bridge_gpt/mcp-server --init
 
 Re-run `--init` after upgrading the package to get updated commands.
 
-#### 2. Generate an API Key
+##### 2. Generate an API Key
 
 1. Log in to [Bridge API](https://bridgegpt-api.com) and navigate to your project's **Security** page
 2. Click **Create New Key**
@@ -82,7 +121,7 @@ Re-run `--init` after upgrading the package to get updated commands.
 4. Click **Create Key**
 5. **Copy the key immediately** — it will not be shown again
 
-#### 3. Configure the MCP Server
+##### 3. Configure the MCP Server
 
 Add the following to your editor's MCP configuration file, pasting in the API key from step 2:
 
@@ -196,28 +235,30 @@ BAPI_DOCS_DIR = "docs/tmp"
 
 After saving the config, restart your editor or reload the MCP server connection. Verify connectivity by asking your AI assistant to call the `ping` tool.
 
-#### 4. First-Time Setup: Teach Bridge Your Codebase
+##### 4. First-Time Setup: Teach Bridge Your Codebase
 
 If you're the first person to install Bridge API on your project, run the `/learn-repository` slash command after completing setup. This analyzes your codebase's architecture, testing patterns, code review standards, and documentation conventions, then uploads the findings to Bridge API. This gives Bridge the context it needs to generate implementation plans, ticket critiques, and code reviews that are consistent with your project's actual architecture and conventions.
 
 You only need to do this once per project — the learned standards persist for all team members.
 
-### Upgrading
+##### Upgrading (details)
 
-To upgrade to the latest version and refresh all scaffolded artifacts in one step:
-
-```bash
-npx -y @bridge_gpt/mcp-server --upgrade
-```
-
-This runs `npm i @bridge_gpt/mcp-server@latest`, prints a before/after version summary, then re-runs the full `--init` scaffolding flow to update your slash commands, agents, and pipeline definitions.
+The one-command `npx -y @bridge_gpt/mcp-server upgrade` (shown above) is the
+recommended path. The legacy flag `npx -y @bridge_gpt/mcp-server --upgrade` still
+works: it runs `npm i @bridge_gpt/mcp-server@latest`, prints a before/after version
+summary, then re-runs the full `--init` scaffolding flow to update your slash
+commands, agents, and pipeline definitions.
 
 The MCP server also checks for updates automatically on startup. If a newer version is available, you'll see a notice in your editor's MCP output logs with the upgrade command to run. This check is cached for 24 hours and never blocks server startup.
 
+</details>
+
 ## Usage Documentation
 
 This is the Bridge API tooling worth knowing about as a software engineer — the things you'd ask an agent to do — grouped by how often you would use them. Each entry covers **what it does**, **when it's useful** and **how to use it**. The behind-the-scenes plumbing is summarized at the end under [Extra Capabilities](#extra-capabilities), and a full enumeration lives in [Reference](#reference).
 
+Working in a Salesforce B2C Commerce codebase? Bridge also ships read-only SFCC platform-introspection tools — see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools).
+
 For invocation, prefer the slash command — it's deterministic. A free-text example is shown only where natural-language phrasing reliably maps to the right automation; high-consequence or easily-misread automations show only the slash command on purpose.
 
 ### Tier 1 — Regularly useful
@@ -401,6 +442,66 @@ Behind-the-scenes capabilities an agent gains from the MCP tools — mostly invo
 - **Retrieve any generated artifact** (`get_*` for plans, critiques, questions, brainstorms, research, architecture) without regenerating it.
 - **Tiered-section execution telemetry** recording (internal measurement).
 
+## Salesforce B2C Commerce (SFCC) Tools
+
+Salesforce's official MCP server, `@salesforce/b2c-dx-mcp`, covers developer-experience tasks — cartridge deploy, step debugging, docs search, logs/MRT, and SCAPI Custom API scaffolding. As of its current toolset it has no way to *read* the platform's object model, custom objects, or site configuration — exactly the context an AI coding agent needs to write correct Commerce code and to inspect a sandbox before touching it. Bridge's SFCC tools install side-by-side with `b2c-dx-mcp` (they don't duplicate its surface) and close that gap with **read-only OCAPI Data API introspection** of system objects, custom object definitions, and site preferences.
+
+**v1 is read-only and developer-sandbox-only** — no writes, and non-sandbox instances are rejected. Credentials stay local (in `dw.json` or `SFCC_*` env vars) and are never sent to Bridge.
+
+<details>
+<summary><strong>Setup</strong></summary>
+
+The two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always available. The seven read tools must be enabled with a profile (step 3).
+
+**Prerequisites:** a running SFCC **sandbox** and its hostname, plus an Account Manager API client (`client-id` + `client-secret`).
+
+**1. Set the repo `version` config field** to your SFCC project type — one of `sfra | pwakit | sitegenesis | storefrontnext | hybrid`. The call-time gate reads this; a non-SFCC value blocks every SFCC tool except `sfcc_setup_status`. Set it via your normal config path, the `config_field` MCP tool (operation `update`, field `version`), or the `/teach-bridge` skill.
+
+**2. Provide SFCC credentials.** Create a `dw.json` in your project root:
+
+```json
+{
+  "hostname": "zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com",
+  "client-id": "<account-manager-client-id>",
+  "client-secret": "<account-manager-client-secret>"
+}
+```
+
+Accepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`, `client-secret`/`clientSecret`/`client_secret`. Prefer a single config — a multi-entry `configs[]` array forces you to pass an explicit `instance` on every call. `dw.json` is auto-added to git exclude and must never be committed. Alternatively, export `SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.
+
+**3. Enable the read tools.** Add `sfcc` to `BRIDGE_MCP_PROFILE` in the MCP server `env` block (it is comma-separated; `full` also works), then **restart the MCP client**:
+
+```json
+"env": { "BRIDGE_MCP_PROFILE": "sfcc" }
+```
+
+Without this, only the diagnostic tools are registered.
+
+**4. Verify and grant OCAPI access.** Ask your agent to run `sfcc_setup_status` (expect all checks ✓), then `check_permissions`. If it reports HTTP 401/403, it prints the exact OCAPI Settings JSON to paste in Business Manager (**Administration → Site Development → Open Commerce API Settings → Data API** tab); save it there and re-run. Restart the MCP client after any credential or env change — a running session does not pick them up.
+
+</details>
+
+### Tools
+
+All SFCC tools are read-only and target a developer sandbox. Oversized responses are automatically saved to `BAPI_DOCS_DIR/sfcc/` and previewed inline.
+
+**Diagnostics** (always available, no profile needed)
+- `sfcc_setup_status` — report on every prerequisite: Bridge API key, repo name, `version` config, `dw.json` presence/uniqueness, and AM token acquisition.
+- `check_permissions` — probe OCAPI access via `GET /system_object_definitions`; on 401/403, print the exact OCAPI Settings JSON to paste in Business Manager (split read-only vs. write/import grants).
+
+**System object model** (needs the `sfcc` profile)
+- `system_object_list` — list system object types (Product, Order, Customer, …).
+- `system_object_get` — fetch one type's definition, optionally with its full attribute definitions (`expand_attribute_definitions`).
+- `system_object_attribute_search` — search a type's attribute definitions; prefer this over a full dump when hunting a specific `c_` custom attribute.
+
+**Custom object definitions** (needs the `sfcc` profile)
+- `custom_object_definition_list` — list custom object type definitions.
+- `custom_object_definition_get` — fetch an existing custom type with its key definition and attribute definitions/groups. Read-only — creating a custom object *type* isn't possible via OCAPI; that's a future v2 metadata-import capability.
+
+**Site preferences** (needs the `sfcc` profile; sandbox only)
+- `site_preference_get` — read a preference group's effective preferences.
+- `site_preference_search` — search/filter preferences within a group.
+
 ## CLI Subcommands
 
 Beyond `--init` / `--upgrade`, the package ships operational subcommands of the **single `bridge-api-mcp-server` bin** (not separate binaries) — so they travel with the package to every consumer. See [Usage Documentation → Start Tickets](#tier-1--regularly-useful) for *when* to use `start-tickets`; this section is the full CLI reference.
@@ -433,7 +534,7 @@ 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 (opt-in via `--conductor`, BAPI-394).** Conductor is **off by default** — without `--conductor` no `BAPI_CONDUCTOR_*` env, supervisor tab, or message-relay prompt is produced. With `--conductor`, a 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, and opens a supervisor peer tab. 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. (Epic-tick dispatch always enables conductor internally, independent of this flag.)
+**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](./CONDUCTOR.md)** for the full observability, git-hook, done-gate, and auto-merge reference.
 
 **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.
 
@@ -453,55 +554,9 @@ 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"] }
-  ]
-}
-```
+### Conductor (epic & multi-agent orchestration)
 
-`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.
+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 — `conductor install-git-hooks`, the `conductor_done_gate` and `conductor_auto_merge_enabled` config fields, and the observability stream — lives in **[CONDUCTOR.md](./CONDUCTOR.md)**.
 
 ## Custom Pipelines
 
@@ -544,40 +599,6 @@ See `.bridge/pipelines/README.md` for the full schema reference.
 
 If a custom pipeline has the same key as a built-in pipeline, the custom version takes precedence (a warning is logged at startup).
 
-## Smoke testing
-
-The package ships a canonical, **opt-in** in-host smoke-test runbook at
-`smoke-test/SMOKE-TEST.md`. An AI agent running inside your host (Claude Code,
-Cursor, Codex, Windsurf, or VS Code/Copilot) executes it to verify that the MCP
-server actually works end-to-end *inside that host* — it calls the real tools and
-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 62 tools).
-- It is **opt-in**: default `--init` **does not scaffold `/smoke-test-mcp`**, so
-  consumer command palettes are not polluted.
-
-### Running it
-
-You have two options:
-
-1. **Copy the opt-in command manually.** Copy the packaged command stub into your
-   host's command directory, then invoke `/smoke-test-mcp`:
-
-   ```bash
-   # Claude Code
-   cp node_modules/@bridge_gpt/mcp-server/smoke-test/smoke-test-mcp.md .claude/commands/smoke-test-mcp.md
-   # Cursor
-   cp node_modules/@bridge_gpt/mcp-server/smoke-test/smoke-test-mcp.md .cursor/commands/smoke-test-mcp.md
-   ```
-
-2. **Open the runbook directly.** Alternatively, open
-   `smoke-test/SMOKE-TEST.md` and ask the host agent to execute it.
-
-Reports are written to `<BAPI_DOCS_DIR>/smoke-test/REPORT-<host>-<timestamp>.md`.
-
 ## Environment Variables
 
 | Variable | Required | Default | Description |
@@ -591,7 +612,8 @@ Reports are written to `<BAPI_DOCS_DIR>/smoke-test/REPORT-<host>-<timestamp>.md`
 | `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 |
-| `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile. Controls which tool groups are registered when the server starts. Valid values: `core` (default — normal coding tools only), `conductor` (core + 8 conductor/event/supervisor tools), `pipeline-authoring` (core + 5 pipeline run/admin tools — `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `full` (all tools, equivalent to the legacy unconditional registration). Unknown, blank, or malformed values fail safe to `core`. Dynamic mid-session switching via `tools/list_changed` is unsupported — the profile is resolved once at process startup. **Phase 2b note:** epic/conductor sessions launched via `start-tickets` will automatically inject `BRIDGE_MCP_PROFILE=conductor`; that injection is handled at the spawn boundary and is out of scope for this phase. |
+| `CURSOR_API_KEY` | No | _(none)_ | API key used to authenticate `cursor-agent` when launching `start-tickets`/scheduled runs with `--agent cursor-agent`. Not needed for the default Claude Code agent |
+| `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile — a **comma-separated** list of groups controlling which tool groups are registered when the server starts. `core` is always implicitly included. Valid groups: `core` (default — normal coding tools only), `conductor` (+ 8 conductor/event/supervisor tools), `pipeline-authoring` (+ 5 pipeline run/admin tools — `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `sfcc` (+ the 7 heavy SFCC read tools — see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools); the `sfcc_setup_status`/`check_permissions` diagnostics are always registered regardless), and `full` (shortcut that expands to every group). Example: `sfcc,conductor`. Unknown, blank, or malformed tokens are dropped (falling back to `core`). Dynamic mid-session switching via `tools/list_changed` is unsupported — groups are resolved once at process startup. Conductor/epic sessions launched via `start-tickets --conductor` automatically inject `BRIDGE_MCP_PROFILE=conductor` at the spawn boundary; a normal `start-tickets` run stays on `core`. |
 
 ## Worktree credentials and the `mcp-invoke` shim
 
@@ -666,7 +688,7 @@ The full surface, for when you need the complete enumeration. Day-to-day, use [U
 
 ### MCP tools
 
-The server registers **58 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 exposes **58 documented 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`, `get_my_role`, `get_docs_dir`
 - **Jira tickets** — `get_tickets`, `get_ticket`, `create_ticket`, `update_ticket_description`, `add_comment`, `get_comments`

package/build/conductor/doctor.js

@@ -7,6 +7,7 @@
  * failure. This module performs NO writes: no hook installation, no schema
  * migration, no event emission, and no scheduler unit creation.
  */
+import { spawnSync } from "node:child_process";
 import { doctorConductorLedger } from "./store.js";
 import { inspectConductorGitHooks } from "./git-hooks.js";
 /**
@@ -105,6 +106,65 @@ export function inspectMcpProfile(env, epicTick) {
     }
     return { resolved_profile, conductor_context_detected, degraded, warnings };
 }
+/**
+ * Read-only probe of the local-merge (F4) capability. Runs `gh --version` and
+ * `gh auth status` (no writes, no merge) and reports whether the host could merge
+ * a PR locally if `policy_json.local_merge.enabled` were set. Never throws.
+ */
+export function inspectLocalMerge(runCommand) {
+    const run = runCommand ??
+        ((cmd, args) => {
+            try {
+                // Static ESM import (this package is "type": "module"): a lazy
+                // require("child_process") throws ReferenceError under ESM, which the
+                // catch swallowed — making `gh` always look unavailable (false negative).
+                //
+                // `gh auth status` hits api.github.com; with no timeout a network stall
+                // (expired token, DNS hiccup, partition) blocks the doctor process until
+                // the OS TCP timeout fires (30s–2min). Bound it to 10s — a hung health
+                // check then simply reports `gh` unavailable. GH_PROMPT_DISABLED keeps an
+                // interactive prompt from holding the process past the timeout.
+                const r = spawnSync(cmd, args, {
+                    encoding: "utf8",
+                    timeout: 10_000,
+                    env: { ...process.env, GH_PROMPT_DISABLED: "1" },
+                });
+                return { status: r.status };
+            }
+            catch {
+                return { status: null };
+            }
+        });
+    let gh_available = false;
+    let gh_authed = false;
+    try {
+        gh_available = run("gh", ["--version"]).status === 0;
+    }
+    catch {
+        gh_available = false;
+    }
+    if (gh_available) {
+        try {
+            gh_authed = run("gh", ["auth", "status"]).status === 0;
+        }
+        catch {
+            gh_authed = false;
+        }
+    }
+    const warnings = [];
+    if (!gh_available) {
+        warnings.push("`gh` is not installed or not on PATH. Local merge (policy_json.local_merge.enabled) " +
+            "cannot run; install the GitHub CLI to enable conductor-driven merges.");
+    }
+    else if (!gh_authed) {
+        warnings.push("`gh` is installed but not authenticated (`gh auth status` failed). Run `gh auth login` " +
+            "to grant the conductor merge permission; otherwise local merge will emit merge.failed/skip.");
+    }
+    // Capability gap only — local merge is opt-in, so an unauthed host is not a hard
+    // failure unless the operator enabled it. Reported as degraded for visibility.
+    const degraded = !gh_available || !gh_authed;
+    return { gh_available, gh_authed, degraded, warnings };
+}
 /**
  * Build the combined read-only doctor report. Composes the existing ledger
  * doctor, git hook inspection, and the epic-tick schedule enablement check.
@@ -120,6 +180,7 @@ export async function buildConductorDoctorReport(deps = {}) {
         git_hooks: inspectHooks(deps.hooksDeps),
         epic_tick: epicTick,
         mcp_profile,
+        local_merge: inspectLocalMerge(deps.runCommand),
     };
 }
 /**
@@ -128,7 +189,7 @@ export async function buildConductorDoctorReport(deps = {}) {
  * status tags consistent with the git hooks section's visual hierarchy.
  */
 export function formatConductorDoctorReport(report) {
-    const { ledger, git_hooks, epic_tick, mcp_profile } = report;
+    const { ledger, git_hooks, epic_tick, mcp_profile, local_merge } = report;
     const lines = [
         "Conductor ledger doctor",
         "───────────────────────",
@@ -193,5 +254,21 @@ export function formatConductorDoctorReport(report) {
         for (const w of mcp_profile.warnings)
             lines.push(`  - ${w}`);
     }
+    lines.push("");
+    lines.push("Local merge capability (optional, opt-in)");
+    lines.push("─────────────────────────────────────────");
+    const ghTag = local_merge.gh_available
+        ? local_merge.gh_authed
+            ? "[OK]"
+            : "[WARNING] not authenticated"
+        : "[WARNING] not installed";
+    lines.push(`gh available:          ${local_merge.gh_available} ${ghTag}`);
+    lines.push(`gh authenticated:      ${local_merge.gh_authed}`);
+    lines.push(`degraded:              ${local_merge.degraded}`);
+    if (local_merge.warnings.length > 0) {
+        lines.push("local merge warnings:");
+        for (const w of local_merge.warnings)
+            lines.push(`  - ${w}`);
+    }
     return lines.join("\n");
 }