@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/docs/EPIC-IMPLEMENTER.md

@@ -4,18 +4,16 @@ The **Epic Implementer** drives a multi-ticket epic from an approved plan to
 `done`. It dispatches each child ticket to an agent, watches CI and review, merges
 each child PR, and re-indexes the repository after each merge.
 
-> **Naming.** The Epic Implementer used to be called the "Conductor". It was
-> renamed in BAPI-1077 to BAPI-1083, BAPI-1190, BAPI-1232, and BAPI-1233. A few
-> real identifiers still carry the old name and are spelled as-is below: the
-> `--conductor` flag on `start-tickets`, the `install conductor` subcommand, the
-> `mcp_server/src/conductor/` source directory, and two retired `conductor` bins.
+> **Names.** A few real identifiers still carry an older product name and are
+> spelled as-is below: the `start-tickets --conductor` flag, the
+> `install conductor` subcommand, and `.conductor/` paths.
 
 It has two parts. Keep them apart when you read this guide:
 
 | Part | What it is | Opt-in? |
 | --- | --- | --- |
 | **The v2 engine** | A server-side **reconciler** plus a local **executor**. This is what drives an epic. | No. It runs for every epic run. |
-| **The observability layer** | A local event ledger, Claude Code lifecycle hooks, optional git hooks, and a supervisor tab for `start-tickets --conductor` runs. | Yes, per run, with `--conductor`. |
+| **The observability layer** | A local event ledger, Claude Code lifecycle hooks, optional git hooks, and a supervisor tab for `start-tickets --conductor` runs. | Yes, per run, with `start-tickets --conductor`. |
 
 For the everyday `start-tickets` flags, see
 [README → CLI Subcommands](../README.md#cli-subcommands).
@@ -48,7 +46,7 @@ server's readiness report and routes to exactly one path. You never choose
 between engines.
 
 ```
-npx -y @bridge_gpt/mcp-server drive-epic BAPI-405 \
+npx -y @bridge_gpt/mcp-server drive-epic PROJ-123 \
   --plan-file docs/tmp/epic-plans/<slug>/epic-plan.dag.json
 ```
 
@@ -58,7 +56,7 @@ Run it from a Git checkout of the target repository. In one command it:
    A check that fails here creates nothing.
 2. Validates the plan with the server's real validator, then creates and approves
    the run (it delegates this to `setup-epic`).
-3. Starts a **run-scoped executor** for the run in the background (BAPI-1279). It
+3. Starts a **run-scoped executor** for the run in the background. It
    claims only that run's jobs, logs to `.bridge/executors/<run>.log`, and exits by
    itself when the run is `done` or `abandoned`. Re-running `drive-epic` for the
    same live run never starts a second one.
@@ -90,7 +88,6 @@ attach, and `1` for refuse or stop.
 | `--policy-file <path>` | The **complete** run policy, applied when the run is created. |
 | `--review-policy <src>` | The review policy for this run only: `repository_policy`, `verdict_protocol`, `native_review_decision`, or `none`. Omit it and the server stamps `repository_policy` at first approval for a new feature-branch run. `verdict_protocol` (AI review) is an explicit opt-in. An already-approved run with no stored policy is unchanged and still resolves to `verdict_protocol`. |
 | `--replace-policy` | Allow replacing a live run's stored policy with `--policy-file`. |
-| `--launch-profile <name>` | Use a host-local launch profile approved by `install conductor --launch-profile <name>`. `BAPI_EPIC_LAUNCH_PROFILE` selects one too; the flag wins. |
 | `--base-url <url>` | Explicit Bridge API target. It must agree with a profile. |
 | `--dry-run`, `--json` | Read-only preview (see above). |
 
@@ -131,7 +128,7 @@ branch.
 |---|---|
 | The epic branch on a plan with 2 or more nodes | *nothing* — it is the default |
 | Your own branch name, or a branch for a single-node plan | `--feature-branch <name>` |
-| Direct-to-base (the pre-BAPI-1009 behavior) | `--into-base` |
+| Direct-to-base (children target the base branch) | `--into-base` |
 
 A single-node plan keeps the base branch by default. `--feature-branch` and
 `--into-base` together are a parse error.
@@ -173,7 +170,7 @@ host or a manual recovery:
 npx -y @bridge_gpt/mcp-server executor --repo <name> --epic-run-id <id>
 ```
 
-- **A claim scope is required** (BAPI-1026). Pass exactly one of
+- **A claim scope is required.** Pass exactly one of
   `--epic-run-id <id>` (repeatable) or `--repo-wide`. With neither, the executor
   refuses to start.
 - **A base URL is required.** Pass `--base-url` or set `BAPI_BASE_URL`. The
@@ -185,22 +182,7 @@ npx -y @bridge_gpt/mcp-server executor --repo <name> --epic-run-id <id>
   systemd (Linux) user unit so an executor survives a reboot. For the guided,
   consented setup, use `install conductor` instead.
 
-> **Running against a local Bridge API server? Do not use `npx`.** The published
-> package often lags the server's source. A newer server can send a `prompt_spec`
-> the older executor rejects (`ContractError.Prompt ... unsupported placeholder`).
-> Build and run the local tree so both come from the same commit:
->
-> ```
-> cd mcp_server && npm run build
-> node mcp_server/build/index.js executor --repo <name> --epic-run-id <id>
-> ```
-
-**The plane.** `plane up|status|down` brings up a whole local stack in one
-command: the Bridge API server, the dead-man observer, the reconciler worker, and
-scoped executor lanes. It is for operators who run the Bridge API server
-themselves, and it runs executors from that checkout's `mcp_server/build/`.
-`drive-epic` starts or attaches to a plane on its own when `BAPI_BASE_URL` names
-the local plane endpoint.
+Owners who run their own Bridge server have extra steps. Run `npx -y @bridge_gpt/mcp-server drive-epic --help-advanced` to read them.
 
 ## The CI gate
 
@@ -218,7 +200,7 @@ neither `required_checks` nor `no_ci_gate`:
    passes without CI.
 3. Otherwise nothing is stamped.
 
-**With a confirmed gate profile (BAPI-1390)** the stamp follows the profile
+**With a confirmed gate profile** the stamp follows the profile
 instead, and always records `gate_profile_revision` and a `gate_profile_snapshot`
 that later profile edits never change:
 
@@ -242,7 +224,7 @@ run being admitted never count.
 | Admission reason | Meaning | Remedy |
 |---|---|---|
 | `provider_check_unseen` | The named check never reported in that window | Make the check report on the default branch once, or edit the gate profile |
-| `provider_evidence_unavailable` | The walk could not finish (rate limit, permission, truncation, moving head) | Retry readiness; escalate to Bridge operations if it persists |
+| `provider_evidence_unavailable` | The walk could not finish (rate limit, permission, truncation, moving head) | Retry readiness; email info@bridgegpt.ai if it persists |
 | `local_command_unqualified` | No current passing executor qualification for the profile's revision and command digests | Qualify the local commands, then retry |
 | `migration_guard_unset` | Root `alembic.ini` present and no confirmed member marked as the migration guard | Mark a confirmed check or command as `migration_guard` |
 
@@ -303,8 +285,8 @@ Paths are relative to the repository root.
 {
   "plan_version": 1,
   "nodes": [
-    { "ticket_key": "BAPI-405", "status": "planned", "depends_on": [],
-      "touched_files": ["api/routes/jira_api.py"] }
+    { "ticket_key": "PROJ-123", "status": "planned", "depends_on": [],
+      "touched_files": ["src/example/service.py"] }
   ],
   "edges": []
 }
@@ -328,6 +310,8 @@ or not the node declared `touched_files`.
 - `notifications --repo <repo> --run <epic-key|run-id> [--follow]` prints the
   run's notification feed.
 - `epic-implementer epic-status --epic-key <KEY>` prints a read-only health summary.
+- `epic-implementer wait-run --epic-run-id <id> [--since <token>]` waits, read-only,
+  until the run's observable state changes (see [Waiting between passes](#waiting-between-passes-wait-run)).
 
 Both MCP tools need the `epic_implementer` profile group (see
 [MCP profile](#mcp-profile)).
@@ -345,6 +329,7 @@ Both MCP tools need the `epic_implementer` profile group (see
 | `adopt-current-head-and-unpark --ticket-key <key>` | Recover a ticket parked by a PR-head change: adopt the current head and unpark. |
 | `continue-child --ticket-key <key> [--reason <text>]` | Continue a parked child's current attempt without a reset. |
 | `continuation-receipt --ticket-key <key> [--request-id <id>]` | Read-only: whether a continuation request committed. |
+| `wait-run [--ticket-key <key>] [--since <token>] [--timeout <seconds>]` | Read-only: wait until the run's observable state changes. Not a verb; changes nothing. |
 | `resume-ci --ticket-key <key>` | Resume a child parked on a CI stop once CI is green. |
 | `dispatch-remediation --ticket-key <key> --context-file <path>` | Queue a repair job carrying your notes (at most 16384 bytes). |
 | `merge-child --pr <number>` | Merge the run's child PR through the shared merge service. |
@@ -356,8 +341,31 @@ Most verbs accept `--json`. A replay that changes nothing prints
 `committed: false` and exits `0`. A refusal carries the server's closed code, such
 as `TICKET_NOT_IN_RUN`.
 
+### Waiting between passes: `wait-run`
+
+`epic-implementer wait-run --epic-run-id <id> [--ticket-key <key>] [--since <token>] [--timeout <seconds>] [--json]`
+is a CLI-only, read-only wait. It reads only `GET /jira/epic-runs/runs/{id}/state`,
+using the same shared credential resolver as the verbs, and writes nothing. The
+window defaults to 110 seconds; a larger value is clamped to 240.
+
+| Outcome | Meaning | Exit |
+| --- | --- | --- |
+| `changed` | The run's stable state moved. Within one window it lists up to 20 `{ticket_key, field, from, to}` changes (`truncated: true` when more were dropped). | `0` |
+| `changed` + `baseline: "since"` | The first read already differed from `--since`. It carries no field history: the token says *that* something changed, not what. | `0` |
+| `terminal` | The run is `done` or `abandoned`. This outranks a token mismatch. | `0` |
+| `pending` | `WAIT_WINDOW_ELAPSED` (nothing moved) or `UPSTREAM_TRANSIENT` (three reads in a row failed). Run it again. | `0` |
+| failure | Bad arguments, a credential gap, a `401`/`403`/`404`/other `4xx`, a malformed response, or a `--ticket-key` that names no ticket in the run. One line on stderr, nothing on stdout. | `1` |
+
+Every successful result carries a `v1:` `token`. Pass it back as `--since`, with
+the same run and the same `--ticket-key`. A well-formed token from another run or
+selector simply reports `changed`. Before any read succeeds, `token` is the
+supplied `--since` (or `null`) and `run_status` is `null`. The token ignores
+reconciler clocks, heartbeats, and row versions, so a tick alone never reports a
+change. wait-run reports the latest observable state, not event history: always
+run a fresh full pass before choosing an action.
+
 **Check prerequisites.** `epic-implementer readiness` is a read-only advisory
-report of every prerequisite (install, doctor, plane preflight, and server), each
+report of every prerequisite (install, doctor, and server), each
 with one named fix. It never runs a fix and always exits `0`.
 `epic-implementer doctor` reports local health read-only.
 
@@ -384,7 +392,7 @@ register only when `BRIDGE_MCP_PROFILE` includes the `epic_implementer` group (o
 BRIDGE_MCP_PROFILE=core,epic_implementer
 ```
 
-The old `conductor` profile token is retired and ignored. `epic-implementer
+The old profile token is retired and ignored. `epic-implementer
 doctor` flags it.
 
 ## Binaries
@@ -392,18 +400,18 @@ doctor` flags it.
 | Bin | Purpose |
 | --- | --- |
 | `epic-implementer` | The CLI: the recovery verbs above, `readiness`, `doctor`, `epic-status`, `approve-plan`, `install-git-hooks`, and the observability-layer ledger commands (`emit-event`, `supervise`, `send-message`, `check-messages`, `purge`, `git-hook`, `file-scope-guard`). |
-| `epic-implementer-claude-hook` | The Claude Code lifecycle hook for `--conductor` runs. |
-| `conductor`, `conductor-claude-hook` | Retired names (renamed by BAPI-1080). They print a fixed migration message and exit `1`. |
+| `epic-implementer-claude-hook` | The Claude Code lifecycle hook for `start-tickets --conductor` runs. |
+| `conductor`, `conductor-claude-hook` | Retired names. They print a fixed migration message and exit `1`. |
 
 The same CLI is available as the `epic-implementer` subcommand:
 `npx -y @bridge_gpt/mcp-server epic-implementer <command>`.
 
-## Environment-variable names and the legacy-name refusal (BAPI-1190)
+## Environment-variable names and the legacy-name refusal
 
 Every Epic Implementer environment variable uses the `BAPI_EPIC_IMPLEMENTER_`
 prefix. The worker Node path is `EPIC_IMPLEMENTER_NODE_PATH`. These replaced the
-old names by a plain token swap: `CONDUCTOR` became `EPIC_IMPLEMENTER` and the
-rest stayed the same. For example, the run-id variable is now
+old `BAPI_CONDUCTOR_*` and `CONDUCTOR_*` names with the matching
+`BAPI_EPIC_IMPLEMENTER_*` and `EPIC_IMPLEMENTER_*` names; the rest stayed the same. For example, the run-id variable is now
 `BAPI_EPIC_IMPLEMENTER_RUN_ID`. There are no aliases and no dual reads.
 
 The three dead-man variables that the Python worker reads were renamed the same
@@ -418,12 +426,10 @@ way: `EPIC_IMPLEMENTER_DEAD_MAN_ONLY`, `EPIC_IMPLEMENTER_DEADMAN_CHANNEL_TYPE`,
 |---|---|
 | MCP server (bare startup) and every `npx @bridge_gpt/mcp-server <subcommand>` | stderr diagnostic, exit `1`, before any spawn, network call, ledger open, or file write |
 | `epic-implementer` bin | stderr diagnostic, exit `1`, before argv reaches the CLI |
-| `plane up` preflight | refused as the first check, before anything starts |
 | `epic-implementer-claude-hook` bin | same stderr diagnostic, **exit `0`**, no ledger event |
-| Bridge API `worker.py` (dead-man names only) | refuses at boot |
 
 The hook exits `0` because a hook must never block the Claude tool loop. The two
-retired `conductor` bins are not guarded; they already fail with a fixed message.
+retired bins are not guarded; they already fail with a fixed message.
 
 The diagnostic lists **every** offending key, sorted, in one message, with its
 successor, a "retired — remove it" note, or generic advice for an unknown name. It
@@ -440,10 +446,10 @@ versions and the offending **key names only**.
 The executor's worker-environment filter also strips both prefixes and both
 node-path spellings, so an old name never reaches a worker it spawns.
 
-## Observability layer (`--conductor`, opt-in, BAPI-394)
+## Observability layer (`start-tickets --conductor`, opt-in)
 
 This layer is **off by default**. It is separate from the v2 engine and never
-decides a transition. Without `--conductor`, `start-tickets` produces no
+decides a transition. Without `start-tickets --conductor`, `start-tickets` produces no
 `BAPI_EPIC_IMPLEMENTER_*` env, supervisor tab, or message-relay prompt.
 
 With `start-tickets --conductor`, a run mints one `run_id`, writes a `run.started`
@@ -467,7 +473,7 @@ with `BAPI_EPIC_IMPLEMENTER_ENABLE_PRE_TOOL_USE=1`.
 Inspect the stream with `epic-implementer doctor`. See also
 [README → Environment Variables](../README.md#environment-variables).
 
-## `epic-implementer install-git-hooks` (BAPI-395)
+## `epic-implementer install-git-hooks`
 
 Installs local git hooks that emit git events into the local ledger:
 
@@ -488,7 +494,7 @@ committed ref updates).
 Missing hooks do **not** block anything. `epic-implementer doctor` reports hook
 state read-only, and the reconciler drives CI polling and gates either way.
 
-### Durable hook installation (BAPI-1290)
+### Durable hook installation
 
 A managed hook embeds one absolute entry path and runs it on every commit for as
 long as the hook exists. So the installer embeds only a **qualified persistent
@@ -519,7 +525,7 @@ read-only:
 |---|---|
 | The entry is not inside the prunable `_npx` cache | `ephemeral-cache` |
 | The canonical entry is a regular `build/epic-implementer-bin.js` | `missing` |
-| It is not the retired `conductor-bin.js` name | `legacy-name` |
+| It is not a retired entry name | `legacy-name` |
 | It sits at `…/node_modules/@bridge_gpt/mcp-server/build/`, and the adjacent `package.json` has that `name`, a compatible `version` (`>=0.2.0 <1.0.0`), and `bin.epic-implementer` → `./build/epic-implementer-bin.js` | `unqualified-runtime` |
 | The platform is macOS or Linux | `unqualified-runtime` |
 | `node` from PATH launches the entry's private probe within 15 seconds | `node-unavailable` / `unknown` |
@@ -553,8 +559,8 @@ atomically over the target. A hook edited in the meantime is left alone
 (`native-unavailable`) is **unavailable**. The raw embedded path appears only in
 `--json` output (`embedded_bin_path`).
 
-**Repairing old cache-backed hooks.** Hooks installed from `npx` before BAPI-1290
-point into the npx cache. Install persistently (`npm i -g @bridge_gpt/mcp-server`),
+**Repairing old cache-backed hooks.** Hooks installed from `npx` before durable
+hook installation point into the npx cache. Install persistently (`npm i -g @bridge_gpt/mcp-server`),
 then re-run `epic-implementer install-git-hooks` (or `install conductor` and
 accept the local-observability consent). The managed block is replaced in place.
 
@@ -568,9 +574,8 @@ never depends on hooks.
 
 ## Supervisor config
 
-> **These are not config fields.** They used to be `conductor_done_gate` and
-> `conductor_auto_merge_enabled` on the generic config-field route. BAPI-438 moved
-> them to dedicated supervisor endpoints. Setting them through
+> **These are not config fields.** They used to be set through the generic
+> config-field route. They now have dedicated supervisor endpoints. Setting them through
 > `PUT /jira/config-field/...` returns **HTTP 400 "Invalid config field"**, which
 > is correct.
 
@@ -585,11 +590,11 @@ Swap `…/defaults/` for `…/runs/{epic_key}/…` to scope a setting to one epi
 matching `GET` returns the effective value with a `source` of `epic`,
 `project_default`, or `none` (nothing configured; fails closed).
 
-Since BAPI-1288 every project-default write is protected. Removing a configured
+Every project-default write is protected. Removing a configured
 requirement needs a preview (`POST …/defaults/preview/`) and the exact approval it
 returns. Turning `auto_merge_enabled` **on**, or dropping a required
 `merge_approval_required`, on the project default is refused
-(`409 NON_RELAXABLE`); ask Bridge support.
+(`409 NON_RELAXABLE`); email info@bridgegpt.ai.
 
 ### `done_gate_config`
 
@@ -640,7 +645,7 @@ results are `merge.dry_run`, `merge.attempted`, `merge.succeeded`,
 `merge.failed` (retryable), and `merge.pending_approval` (waits for a human).
 **`merge.succeeded` is the only terminal merge event.**
 
-**Who performs the write (BAPI-832).** GitHub's merge endpoint needs
+**Who performs the write.** GitHub's merge endpoint needs
 `contents: write`, and the Bridge GPT App is `contents: read`. So two paths merge
 with the operator's local `gh` session instead of the App token:
 
@@ -653,7 +658,7 @@ The mode is `merge_execution` on the supervisor config (`local` by default,
 `server` when the App holds `contents: write`). A caller that dies mid-merge is
 recovered by lease expiry; a retry reports `already_merged` if the merge landed.
 
-## Worker ledger hardening (BAPI-527)
+## Worker ledger hardening
 
 This section applies to the observability layer. It keeps a worker's own ledger
 calls reliable. It is not a completion backstop.
@@ -705,14 +710,33 @@ or a missing `BAPI_EPIC_IMPLEMENTER_CLI_FILE`, returns the
 Run `epic-implementer likely-tests --base <sha>` with the executor's immutable,
 full 40-character comparison commit, after committing and before the first push.
 Fallback: `npx -y -p @bridge_gpt/mcp-server epic-implementer likely-tests --base <sha>`.
-Refresh after additional commits. Map references through the repository's declared
-targeted runner; references are data, never commands.
-
-This local read-only command returns zero even on invalid input or discovery failure.
-Stdout contains only one reference per line; stderr contains fixed advisory notes.
-Recent failures come first, then explicit `.bridge/verification-hints.json` pins,
-then sorted tracked tests containing literal changed-path/import references.
-Exact duplicates are removed before the 100-reference output limit.
+Run either alone and keep stderr and the exit status visible. Refresh after
+additional commits. Map references through the repository's declared targeted
+runner; references are data, never commands.
+
+This local read-only command returns `1` with a distinct bounded note on stderr
+for invalid arguments (`invalid_arguments`), for git discovery that could not run
+(`git_unavailable`), and for an internal discovery failure (including a failed
+import). A failure never prints the `empty` note. A successful discovery returns
+`0` and stays advisory: `empty`, `hints_missing`, `truncated`, and
+`data_unavailable` are notes, not failures. A success that prints no reference
+always prints the `empty` note once, so empty stdout with no `empty` note means
+the command did not run. Stdout contains only one reference per line; stderr
+contains fixed advisory notes.
+Recent failures come first, then the sorted test files named in the worker's
+declared touched files, then explicit `.bridge/verification-hints.json` pins, then
+sorted tracked tests containing literal changed-path/import references. Exact
+duplicates are removed before the 100-reference output limit; omitted candidates
+raise the `truncated` note.
+
+Declared files come from `BAPI_EPIC_IMPLEMENTER_DECLARED_TOUCHED_FILES_JSON`. An
+entry is admitted only when it is a test file and exists in the worktree; a missing
+accepted candidate raises `skipped_entries`, and malformed JSON raises
+`data_unavailable`. When the variable is absent or blank the command is silent about
+it. Ordinary `implement` and `ci_fix` workers do not currently receive this variable,
+so for them declared files add nothing. Worker payloads are unchanged here; the
+epic-owner server-payload follow-up is pending (no identifier exists in version-controlled
+planning material yet).
 
 The optional worker-worktree `.conductor/recently-failed-tests.json` is
 `{"version":1,"tests":["most-recent-first reference"],"truncated":false}`. Child 3
@@ -726,3 +750,20 @@ file, 16 MiB scanned text, 10,000 sorted candidates, 10 seconds per Git subproce
 and 4 MiB Git output. Missing recent failures are silent. Disclose unavailable,
 malformed, unreadable, truncated, or unmappable coverage in the existing handoff.
 Retain available targeted verification; do not run a whole suite as fallback.
+
+### Worktree git-exclude provisioning
+
+The executor writes `.claude/settings.local.json` and `.conductor/` into the shared
+common `info/exclude` before any worktree lock, recently-failed file, or pre-spawn
+verification (`provisionWorktreeSettingsExclude`, called at the start of the
+reserved-spawn workflow against the executor clone). The writer keeps existing
+content verbatim, appends only absent canonical lines, and publishes through a
+uniquely named temporary file plus rename.
+
+- **Detection:** a failure produces a bounded `excludeWarning` line in the executor's
+  error log (a category plus the worktree path, nothing else).
+- **Containment:** the job continues. The deny layer's own exclude call is an
+  idempotent second attempt, and the existing dirty-worktree refusal in pre-spawn
+  verification is unchanged.
+- **Remediation:** the warning tells the operator to inspect the worktree before
+  trusting its staged changes.

package/docs/epic-implementer/getting-started.md

@@ -0,0 +1,131 @@
+# Run your first epic with the Epic Implementer
+
+The Epic Implementer takes a planned epic, hands each child ticket to an agent on your computer, waits for CI and review, and merges each child pull request into an `epic/<EPIC>` branch. A person merges the final pull request into your default branch.
+
+You do four things, in this order: install, set up, define the epic, launch it. The same steps work with Bridge's own ticket storage and with Jira.
+
+In every command below, `npx -y @bridge_gpt/mcp-server` is the launcher. Keep the `-y`; without it, `npx` stops to ask before it installs the package.
+
+## Prerequisites
+
+Setup checks every item below for you, fixes what it can, and prints the one step it cannot fix. Read this list only when setup reports an item. Each bullet gives the item's name, its id, what it means, and the fix.
+
+- **Unattended posture (Setup page)** (`server.unattended-posture`) — Bridge allows unattended runs for this repository. Fix: Turn on **Allow unattended Epic Implementer runs** on the repository Setup page, or launch with `--attended`.
+- **Resolved merge mode** (`server.resolved-merge-mode`) — Bridge knows how child pull requests will be merged (your computer, a machine token, or GitHub Actions). Fix: Run `npx -y @bridge_gpt/mcp-server install conductor`; it fixes what it can and prints the one step it cannot.
+- **Provider repository** (`server.provider-repository`) — Bridge knows the GitHub `owner/name` of this repository. Fix: Run `npx -y @bridge_gpt/mcp-server connect-github`, then run setup again.
+- **Supervisor setup** (`server.supervisor-setup`) — The repository has a stored supervisor record. Fix: Run `npx -y @bridge_gpt/mcp-server install conductor`; it fixes what it can and prints the one step it cannot.
+- **Supervisor configuration** (`server.supervisor-config`) — The supervisor record is complete: the test gate and the safe defaults are stored. Fix: Run `npx -y @bridge_gpt/mcp-server install conductor`; it fixes what it can and prints the one step it cannot.
+- **Supervisor required CI checks** (`server.supervisor-required-checks`) — The CI checks a child pull request must pass before it merges are stored. Fix: Run setup and confirm the gate it proposes, or name a check with `--required-check <name>`.
+- **Review policy** (`server.review-policy`) — The review policy for child pull requests is known. AI review is an opt-in choice by the repository admin. Fix: Nothing is needed unless you want AI review. Choose a policy at launch with `--review-policy`.
+- **GitHub App credentials** (`server.github-credentials`) — Bridge's GitHub App is connected and can read this repository. Fix: Run `npx -y @bridge_gpt/mcp-server connect-github`, then run setup again.
+- **GitHub App actions permission** (`server.github-actions-permission`) — The GitHub App may start workflow runs. Only needed when merges go through GitHub Actions. Fix: Accept the updated permission on the GitHub App's installation page, then run setup again.
+- **Merge workflow eligibility** (`server.merge-execution-workflow`) — The merge workflow file is on the default branch and current. Only needed when merges go through GitHub Actions. Fix: Run `npx -y @bridge_gpt/mcp-server install conductor --merge-workflow --codeowner <@org/team|@user>`, merge the pull request it opens, then run setup again.
+- **Merge branch policy** (`server.merge-execution-branch-policy`) — The default branch rules let the merge workflow do its job. Only needed when merges go through GitHub Actions. Fix: Adjust the branch rule or ruleset as setup describes, then run setup again.
+- **Executor server observation** (`server.executor-readiness`) — Bridge has seen a heartbeat from an executor for this repository. Before your first run this can be missing: `drive-epic` starts the executor for each run. Fix: Launch the epic with `npx -y @bridge_gpt/mcp-server drive-epic <EPIC>`.
+- **Review workflow protocol** (`server.review-workflow`) — The review workflow on the default branch matches the review policy. Only needed with AI review. Fix: Run setup; it names the workflow change to make.
+- **Conductor CI migration guard** (`server.conductor-ci-workflow`) — The CI workflow file `epic-implementer-ci.yml` is on the default branch and runs the migration guard where needed. Fix: Run setup, merge the setup pull request it opens, then run setup again.
+- **Escalation channel (webhook or email)** (`server.unattended-notify-default`) — Bridge has somewhere to send an escalation: a verified notify webhook, or your account email. Fix: Declare a notify webhook, or verify your account email.
+- **Repository workflow readiness** (`server.repository-workflow-readiness`) — The CI and review workflows are confirmed on the default branch. Fix: Run setup, merge the setup pull request, then run setup again.
+- **Workflows at indexed commit** (`server.indexed-workflows`) — The repository index includes the workflow files on the default branch. Fix: Merge the setup pull request, then run setup again. It starts the re-index and reports this item as pending until the index reaches that commit.
+- **Known test command** (`server.test-command`) — Bridge knows the command that runs this repository's tests. Fix: Run setup and give the test command when it asks, or run the learn step.
+- **Service availability** (`server.service-availability`) — Bridge could read this repository's readiness from the server. Fix: Retry in a few minutes. If it keeps failing, email info@bridgegpt.ai.
+- **Claude login** (`install.claude-login`) — Claude Code is signed in on this computer. Fix: Run `claude` and sign in, then run setup again.
+- **Repository identity** (`install.identity`) — Bridge knows which repository this folder is. Fix: Run setup from the repository root, or pass `--repo <name>`.
+- **Bridge API credential** (`install.credential`) — A Bridge API key is stored for this repository. Fix: Run `npx -y @bridge_gpt/mcp-server install`.
+- **Server connectivity** (`install.connectivity`) — This computer can reach the Bridge server. Fix: Check your network and any `BAPI_BASE_URL` setting, then run setup again.
+- **Bootstrap config fields** (`install.bootstrap`) — The repository's Bridge configuration fields are filled in. Fix: Run `npx -y @bridge_gpt/mcp-server install`.
+- **Integration credentials** (`install.integrations`) — The integration credentials this repository uses, such as Jira or GitHub, are stored. Fix: Run `npx -y @bridge_gpt/mcp-server install`.
+- **GitHub connection** (`install.github`) — Bridge's GitHub App is connected to this repository. Fix: Run `npx -y @bridge_gpt/mcp-server connect-github`.
+- **Repository indexing** (`install.indexing`) — The repository has been indexed by Bridge. Fix: Run `/parse-repository`, or let setup queue the index.
+- **Conductor event ledger** (`conductor.ledger`) — The local Epic Implementer event ledger can be read. Fix: Run `npx -y @bridge_gpt/mcp-server epic-implementer doctor` and follow what it prints.
+- **Conductor git hooks** (`conductor.git-hooks`) — Optional: the git hooks that feed the local event ledger are installed. Fix: Run `npx -y @bridge_gpt/mcp-server epic-implementer install-git-hooks`.
+- **Epic Implementer MCP profile** (`conductor.mcp-profile`) — The `epic_implementer` tool profile is on in your MCP host. Fix: Let setup add it (it asks first), then restart your MCP client.
+- **GitHub CLI availability** (`conductor.gh-cli`) — The GitHub CLI (`gh`) is installed and signed in. Fix: Install `gh` and run `gh auth login`.
+- **Configured merge credential** (`conductor.merge-credential`) — A GitHub token for merging child pull requests is available on this computer. Fix: Let setup store one (it asks first), or set `GITHUB_MERGE_TOKEN`.
+- **Native ledger binding** (`conductor.native-ledger`) — The ledger's native component loads on this computer. Fix: Run `npx -y @bridge_gpt/mcp-server epic-implementer doctor` and follow what it prints.
+- **Worker MCP registration form** (`conductor.mcp-registration-form`) — Workers register the Bridge tools in the form the executor expects. Fix: Run `npx -y @bridge_gpt/mcp-server epic-implementer doctor` and follow what it prints.
+- **Expected Node engine** (`conductor.node-engine`) — The Node.js version meets the package's engine range. Fix: Install a supported Node.js (18 or newer; 20 or newer for the git hooks).
+- **Deny-layer enforcement** (`conductor.deny-enforcement`) — Claude Code enforces the permission denials that keep workers inside the repository. Fix: Run `npx -y @bridge_gpt/mcp-server epic-implementer doctor` to see why the check could not confirm it.
+- **Claude login** (`conductor.claude-login`) — Claude Code is signed in for the workers. Fix: Run `claude` and sign in, then run setup again.
+- **Merge credential capability** (`conductor.merge-credential-capability`) — The merge token can push to the repository and read pull requests. Fix: Replace the token (setup offers to), then run setup again.
+- **Worktree preparation** (`conductor.worktree-preparation`) — The executor's clone can keep its working files out of git (`.git/info/exclude` exists or can be written). Fix: Make `.git/info/exclude` writable in this clone.
+- **Supervisor gate profile** (`conductor.install-section-supervisor-gate-profile`) — The repository's test gate profile is stored and valid. Fix: Run `npx -y @bridge_gpt/mcp-server install conductor`; it fixes what it can and prints the one step it cannot.
+- **Supervisor required CI checks** (`conductor.install-section-supervisor-required-checks`) — The required CI checks in the gate match checks the provider reports. Fix: Run `npx -y @bridge_gpt/mcp-server install conductor`; it fixes what it can and prints the one step it cannot.
+- **Supervisor review-policy alignment** (`conductor.install-section-supervisor-review-alignment`) — The review policy and the review workflow agree. Fix: Run `npx -y @bridge_gpt/mcp-server install conductor`; it fixes what it can and prints the one step it cannot.
+- **GitHub App actions permission** (`conductor.install-section-github-actions-permission`) — The GitHub App may start workflow runs. Only needed when merges go through GitHub Actions. Fix: Accept the updated permission on the GitHub App's installation page.
+- **Merge execution eligibility** (`conductor.install-section-merge-execution-eligibility`) — This repository can use GitHub Actions merges. Only needed for that merge mode. Fix: Run `npx -y @bridge_gpt/mcp-server install conductor --merge-workflow --codeowner <@org/team|@user>` and merge its pull request.
+- **Epic Implementer MCP profile token** (`conductor.install-section-epic-implementer-profile-token`) — The Bridge key used by the Epic Implementer tool profile is stored. Fix: Run `npx -y @bridge_gpt/mcp-server install conductor`; it fixes what it can and prints the one step it cannot.
+- **Conductor hook targets** (`conductor.install-section-conductor-hook-targets`) — The git hook targets are in place for this clone. Fix: Run `npx -y @bridge_gpt/mcp-server epic-implementer install-git-hooks`.
+- **GitHub Actions merge: local observation prerequisites** (`conductor.install-section-gh-actions-merge-auth`) — This computer can observe GitHub Actions merges. Only needed for that merge mode. Fix: Sign in with `gh auth login` and rerun setup.
+- **GitHub Actions merge: capability observability** (`conductor.install-section-gh-actions-merge-observable`) — Bridge can observe the outcome of GitHub Actions merges. Only needed for that merge mode. Fix: Rerun setup and follow the step it prints.
+- **Epic Implementer ledger loadability** (`conductor.install-section-epic-implementer-ledger-loadability`) — The local ledger can be loaded by the tools that read it. Fix: Run `npx -y @bridge_gpt/mcp-server epic-implementer doctor` and follow what it prints.
+- **Launch evidence** (`server.admission-evidence`) — Bridge has the evidence it needs to admit a launch. Fix: Run setup, then launch again.
+- **Launch evidence: unattended consent** (`server.admission-unattended-consent`) — Launch check: unattended runs are allowed. Fix: Turn on **Allow unattended Epic Implementer runs** on the Setup page, or launch with `--attended`.
+- **Launch evidence: notification destination** (`server.admission-notify-webhook`) — Launch check: an escalation destination is verified. Fix: Declare a notify webhook, or verify your account email.
+- **Launch evidence: repository workflows** (`server.admission-repository-readiness`) — Launch check: the CI and review workflows are confirmed. Fix: Run setup, merge the setup pull request, then run setup again.
+- **Launch evidence: required CI checks** (`server.admission-required-checks`) — Launch check: the required CI checks are stored. Fix: Run `npx -y @bridge_gpt/mcp-server install conductor`; it fixes what it can and prints the one step it cannot.
+- **Launch evidence: indexed repository** (`server.admission-index-provenance`) — Launch check: the index reaches the commit that holds the workflows. Fix: Merge the setup pull request, then run setup again.
+- **Repository test gate** (`server.gate-profile`) — The repository's test gate is stored. Fix: Run `npx -y @bridge_gpt/mcp-server install conductor`; it fixes what it can and prints the one step it cannot.
+- **Repository test gate warnings** (`server.gate-profile-warnings`) — The stored test gate has no unresolved warnings. Fix: Read the warnings setup prints and confirm or edit the gate.
+- **Effective review mode** (`server.effective-review-mode`) — Bridge shows which review mode child pull requests will use. Fix: Choose a review policy at launch with `--review-policy` if you want a different one.
+- **Epic branch CI** (`server.epic-branch-ci-decision`) — Someone has decided whether CI runs on pull requests into the epic branch. Fix: Run setup and answer the epic-branch CI question, or pass `--epic-branch-ci-decision include|decline`.
+- **Epic branch CI coverage** (`server.epic-branch-ci-coverage-warning`) — Your CI covers pull requests into the epic branch. Fix: Add `epic/**` to the branches your CI workflow runs on.
+- **Additional readiness diagnostics** (`server.diagnostics`) — Extra readiness diagnostics from the server are clear. Fix: Read the diagnostic text; each names its own fix.
+- **Command versions** (`conductor.command-drift`) — The installed Epic Implementer commands match this package's version. Fix: Run `npx -y @bridge_gpt/mcp-server install` to refresh them.
+- **Escalation delivery** (`escalation-reachability`) — An escalation can actually be delivered. Fix: Verify your account email or fix the webhook, then run setup again.
+
+## 1. Install
+
+Run this once per project. Skip it when Bridge is already installed.
+
+```bash
+npx -y @bridge_gpt/mcp-server install
+```
+
+It writes this guide to `docs/install/epic-implementer-install.md` in your project. Run it again any time to refresh that file.
+
+## 2. Set up
+
+Run this once per repository, from the repository root, in your own terminal:
+
+```bash
+npx -y @bridge_gpt/mcp-server install conductor
+```
+
+`install-bridge conductor` is the same command with another spelling. Setup checks everything first (read-only), fixes only what is missing, checks again, and ends with one verdict: "Ready for your first epic" or "Not ready: N steps left", with the fix for each step. It asks before anything that writes, and without a terminal every question is a "no".
+
+When setup reports that its setup pull request is waiting, it prints `merge the setup PR` with the pull request's address. Merge that pull request, then run setup again. Setup starts the re-index, and reports the item as pending ("indexing is running; re-run setup when it finishes", or "indexing was queued; re-run setup when it finishes") until the index reaches the merged commit. Run setup again until it says "Ready for your first epic".
+
+## 3. Define the epic
+
+In Claude Code, run:
+
+```text
+/define-tickets
+```
+
+It writes real child ticket keys, `epic-plan.dag.json`, and `epic-plan.meta.json`, then hands off to `/drive-epic-run`. The meta file is how the launch finds the plan from the epic key.
+
+## 4. Launch
+
+In Claude Code, run:
+
+```text
+/drive-epic-run <EPIC> [<plan path>]
+```
+
+It previews the launch, asks you once, creates the run through `drive-epic`, and drives the run to the end. From a shell, run the same launch yourself:
+
+```bash
+npx -y @bridge_gpt/mcp-server drive-epic <EPIC>
+```
+
+Add `--dry-run` for a read-only preview, or `--attended` to opt out of unattended merging. `drive-epic --help` lists the common options, and `drive-epic --help-advanced` lists the rest.
+
+## Advanced: the planner
+
+`/plan-epic` is the advanced planner. It writes placeholder `TBD-N` keys instead of real ones. You create the child tickets yourself, run `emit-epic-implementer-bundle finalize` to replace the placeholders and write the plan files, then run `/drive-epic-run`. Planning never creates or approves a run.
+
+## If something goes wrong
+
+Every refusal names the missing item and its fix, and creates nothing. Run setup again after you fix an item. For a read-only report of every item, run `npx -y @bridge_gpt/mcp-server epic-implementer readiness --json`. If you are stuck, email info@bridgegpt.ai.