@bridge_gpt/mcp-server 0.2.66 → 0.2.67

package/docs/EPIC-IMPLEMENTER-INSTALL.md

@@ -0,0 +1,849 @@
+# Epic Implementer install guide (for agents)
+
+This guide is for a coding agent (Claude Code, Cursor, or similar) working in a
+customer repository. Your human said "set up the Epic Implementer" and does not
+know how. Follow the steps below in order. Each step says why it matters, the
+exact command, how to check it worked, what to do if it fails, and whether you
+must ask the human first.
+
+Bridge copies this file into every installed project at
+`docs/install/epic-implementer-install.md`. The same text ships in the npm
+package as `docs/EPIC-IMPLEMENTER-INSTALL.md`. For the full reference, read
+`docs/EPIC-IMPLEMENTER.md` inside the `@bridge_gpt/mcp-server` package.
+
+In this guide, `<launcher>` means `npx -y @bridge_gpt/mcp-server`. Always keep
+the `-y`. Without it, `npx` stops to ask whether to install the package.
+
+---
+
+## 0. Rules for you, the agent
+
+1. **Read first, write later.** Run every read-only check in a step before any
+   step that writes.
+2. **Ask before any write or push.** Ask the human before you install a GitHub
+   App, open a pull request, create a secret, change an admin setting, or push a
+   branch. Say what will change and why.
+3. **Replace every placeholder before you run a printed remedy.** The tools now
+   print complete commands, with the `npx -y @bridge_gpt/mcp-server` prefix and
+   every required flag. Some carry a placeholder that only a real value can fill:
+   `<@org/team|@user>` (the one reviewer of the workflow file; Bridge cannot infer
+   it) and `<check-name>` (the exact name of a CI check this repository requires;
+   repeat `--required-check` for more than one). Older tool versions printed
+   shorthand; the table in [§12](#12-troubleshooting-and-known-wrong-remedies)
+   maps it to the full command.
+4. **Stop at human-only access.** Some steps need a browser, a GitHub admin, or
+   the Bridge admin panel. Stop, say exactly what the human must do, and wait.
+5. **Interactive commands go to the human.** `install`, `connect-github`, and
+   both `install conductor` forms ask questions on a terminal. A shell you run
+   has no terminal (no TTY), so the answer is always "no":
+   - `install conductor` prints `Aborted` and **exits `0`**. The exit code does
+     not tell you it failed.
+   - `install conductor --merge-workflow` prints `consent_declined` and exits `1`.
+
+   Ask the human to run these commands in their own terminal, from the
+   repository root. Then read what they paste back.
+6. **Never write a secret into the repository.** No token, API key, or merge
+   credential goes into a tracked file, a command argument you print, or a
+   commit.
+7. **Keep notes.** Record which step you finished. Step 5 asks the human to
+   restart the MCP client, which may end this session.
+
+## 1. What you are setting up
+
+The Epic Implementer drives a multi-ticket epic from an approved plan to merged
+pull requests. It cuts an `epic/<EPIC-KEY>` branch, hands each child ticket to
+an agent on this machine, waits for CI and code review on each child PR, and
+merges each child PR into the epic branch. A person merges the final
+integration PR into the default branch.
+
+By default a run with two or more tickets is **unattended**: it merges child
+PRs on its own. `--attended` is the opt-out: the run then has no permission to
+merge by itself.
+
+Both kinds of run still need CI and code review to actually run on child PRs
+into `epic/<EPIC-KEY>`, or every ticket waits forever. Unattended runs also need
+the server to confirm the setup (steps 6 to 9). Attended runs skip that
+confirmation, but have their own launch path ([§11c](#11c-attended-runs)).
+
+## 2. Preflight checklist (read-only)
+
+**Why:** the executor that runs the jobs lives on this machine. It refuses to
+start without certain tools, and several later steps need `gh` and push rights.
+
+**Ask first?** No. Everything here only reads.
+
+| Check | Command | Pass when |
+|---|---|---|
+| Node.js 18 or newer | `node --version` | `v18` or later. The optional git hooks want an even LTS line, `v20` or later. |
+| Operating system | `uname -s` | `Darwin` or `Linux`. The executor does not run on Windows. |
+| git | `git --version` | Prints a version. |
+| GitHub CLI, logged in | `gh auth status` | Logged in to github.com. |
+| Claude Code CLI | `claude --version` | Prints a version. The human must also be logged in to `claude`. |
+| Worktrunk | `wt --version` | Prints a version. The executor refuses to start without it. |
+| Push rights | `gh repo view --json viewerPermission -q .viewerPermission` | `WRITE`, `MAINTAIN`, or `ADMIN`. Setup pushes an `epic/<EPIC-KEY>` branch with the human's own git. |
+| No retired variables | The command below | Prints nothing. |
+
+Retired-variable check (prints names only, never values):
+
+```bash
+env | grep -E '^(BAPI_CONDUCTOR_|CONDUCTOR_(NODE_PATH|DEAD_MAN_ONLY|DEADMAN_CHANNEL_TYPE|DEADMAN_DESTINATION_REF)=)' | cut -d= -f1
+```
+
+These are old Epic Implementer variable names. If any is set, every
+`<launcher>` command exits `1` and lists each old name with its new one. Show
+the names to the human and ask them to rename or remove them in their shell
+profile, then open a fresh shell.
+
+If a tool is missing, stop and tell the human which one. Do not install tools
+yourself without asking.
+
+Then run the three Bridge diagnostics. All three only read:
+
+```bash
+npx -y @bridge_gpt/mcp-server doctor
+npx -y @bridge_gpt/mcp-server epic-implementer doctor
+npx -y @bridge_gpt/mcp-server epic-implementer readiness --json
+```
+
+- `doctor` checks the base install: repository identity, credentials, server
+  connection, and whether the repository is indexed.
+- `epic-implementer doctor` checks this machine: the local ledger, git hooks,
+  and the merge credential. It briefly starts a headless `claude` probe to check
+  that permission denials are enforced.
+- `epic-implementer readiness --json` combines all of these with the server's
+  view. It is the one report you will re-run after every step. It always exits
+  `0`, even when things fail, so read the JSON.
+
+**How to read `readiness --json`:** look at the `checks` array. Each entry has an
+`id` (for example `server.github-credentials`), a `status`, a `label`, and
+sometimes a `detail` and a `remediation`.
+
+- `pass` — fine.
+- `warn` — works but degraded. Note it.
+- `fail` — not met, **or could not be checked**. Read the `detail` to tell which.
+- `skip` — does not apply here.
+
+Rows whose `id` starts with `plane.` only matter when the human runs their own
+Bridge API server. Against the hosted service you can ignore them. The
+`server.executor-readiness` row may fail before the first run. That is fine:
+`drive-epic` starts an executor for each run by itself.
+
+Map each failing row to a step below. Do not run the `remediation` text as a
+command; see rule 3.
+
+## 3. Base install (only if Bridge is not installed yet)
+
+**Why:** every Epic Implementer command needs the repository's Bridge identity
+and API key.
+
+**Check first:** if `.bridge/config` exists and `doctor` reports the credential
+and server connection as fine, skip this step.
+
+**Ask first?** Yes. It is interactive and writes files.
+
+Ask the human to run this in their own terminal, from the repository root:
+
+```bash
+npx -y @bridge_gpt/mcp-server install
+```
+
+It asks for an email (new account) or a key or invite (existing account). It
+writes `.bridge/config`, the editor's MCP config, and the slash commands. It
+stores the API key outside the repository.
+
+**How credentials are found.** Every command looks for the API key in this
+order: the `BAPI_API_KEY` environment variable, then the file
+`~/.config/bridge/credentials.json` under the key `bapi:<repo_name>`. A key
+that lives only in the editor's MCP config is **not** visible to a shell you
+start, so rely on the credentials file.
+
+**The `repo_name` rule.** `repo_name` must match byte for byte everywhere:
+`.bridge/config`, the `BAPI_REPO_NAME` in the MCP config, the `bapi:<repo_name>`
+key, and any `--repo` flag. Never derive it from the folder or GitHub name. A
+hyphen where Bridge has an underscore gives a **403** that looks like a
+permissions problem. Read it:
+
+```bash
+grep '^repo_name' .bridge/config
+```
+
+**Check it worked:** re-run `npx -y @bridge_gpt/mcp-server doctor`. The identity,
+credential, and connectivity rows should pass.
+
+**If it fails:** a 403 almost always means a `repo_name` mismatch. A 401 means
+the key was rejected or rotated. Ask the human for a fresh key.
+
+## 4. Connect GitHub
+
+**Why:** the server watches CI and review through the Bridge GitHub App. Without
+App credentials, `drive-epic` refuses to start any run (`github_credentials`).
+
+**Check first:** in `readiness --json`, find `server.github-credentials`. If it
+passes, skip to the permission check below.
+
+**Ask first?** Yes. It opens a browser and installs a GitHub App.
+
+Ask the human to run, in their own terminal:
+
+```bash
+npx -y @bridge_gpt/mcp-server connect-github --repo <repo_name>
+```
+
+It opens the GitHub App install page. The human installs the App there, comes
+back to the terminal, and confirms the repository. No GitHub token is ever
+typed. If someone else administers the GitHub organization, use
+`connect-github --handoff --repo <repo_name>` instead. It prints a link to send
+to that admin. After they finish, run `connect-github --resume --repo <repo_name>`.
+
+**Permission check.** Find `server.github-actions-permission` in
+`readiness --json`. It should read `actions: write`. Without it, the Epic
+Implementer cannot re-run a flaky workflow (the rerun fails with a 403). This is
+a warning, not a blocker. If it shows a lower level, ask the human to check the
+Bridge GitHub App's installation in their GitHub settings and accept any
+pending permission request. If `detail` says the permission could not be
+checked, re-run readiness after credentials resolve.
+
+**Check it worked:** `server.github-credentials` passes.
+
+## 5. Bootstrap the repository: `install conductor`
+
+**Why:** this writes the repository's default Epic Implementer settings on the
+server: the required CI check each ticket must pass, merge approval, and the
+review policy. `drive-epic` refuses a repository without them
+(`supervisor_setup`, `supervisor_config`). With extra flags it also writes the
+`claude-review` workflow that step 6 needs, and it adds the Epic Implementer MCP
+tools to your editor config.
+
+The subcommand is still named `install conductor` (the Epic Implementer's old
+name). `install-bridge conductor` is the same command.
+
+**Ask first?** Yes. It asks several yes/no questions and writes to the server
+and to local files. It needs a real terminal.
+
+### 5a. Choose the required check
+
+`--required-check` is **required**. It must be the exact name of a CI check run
+that GitHub reports on child PRs into `epic/<EPIC-KEY>`. A name that never
+reports leaves every ticket waiting forever.
+
+- **Unattended runs (the default):** the name must be a job `name:` written
+  literally in `.github/workflows/epic-implementer-ci.yml` or
+  `.github/workflows/claude-review.yml` on the default branch. At approval the
+  server checks each required check against those two files. Any other name,
+  including a real check from another workflow, is refused as
+  `admission_evidence_unverifiable`. Use **`epic-implementer-ci / gate`**, the
+  gate job in the step 6 template.
+- **Attended runs only:** any real check name works, as long as that check runs
+  on pull requests into `epic/**`. List the names on a recent pull request:
+
+  ```bash
+  gh pr view <pr-number> --json statusCheckRollup \
+    | jq -r '.statusCheckRollup[] | .name // .context'
+  ```
+
+**Never use `claude-review` as a required check.** It is the review signal, not
+a test run. The review gate reads it separately.
+
+### 5b. Choose the review workflow values
+
+`.github/workflows/claude-review.yml` produces the review verdict the review
+gate waits for. For unattended runs it must also emit two markers (`run-id:`
+and `Reviewed-SHA:`). This command writes a correct file when you pass **all
+three** of these flags. If one is missing, phase 3 prints a `skipped — …` line
+and writes nothing.
+
+| Flag | Value |
+|---|---|
+| `--allowed-bot` | The GitHub App bot whose PRs get reviewed. Child PRs are opened by the Bridge GitHub App. For hosted Bridge, use `bridge-gpt-ai-tools-for-sfcc[bot]`. A self-hosted Bridge uses its own App's `<app-slug>[bot]`. |
+| `--secret-name` | The **name** (not the value) of a GitHub Actions secret that holds a Claude Code OAuth token, for example `CLAUDE_CODE_OAUTH_TOKEN`. Upper-case letters, digits, and underscores only. |
+| `--branches` | The pull-request base branches to review: the default branch plus `epic/**`, for example `main,epic/**`. Child PRs target `epic/<EPIC-KEY>`, so without `epic/**` they are never reviewed. |
+
+The review policy defaults to `verdict_protocol`, which is the one that uses
+this workflow. You do not need to pass `--review-policy`. Passing it explicitly
+also stores it as the repository default.
+
+If the repository already has a `claude-review.yml`, the command asks before
+overwriting it. An older or hand-written file may lack the markers. Readiness
+tells you which marker is missing.
+
+### 5c. Run it
+
+Find the default branch:
+
+```bash
+gh repo view --json defaultBranchRef -q .defaultBranchRef.name
+```
+
+First ask the human to preview with `--dry-run`. The preview still asks one
+question (whether to use the shown Bridge API URL) because it reads from the
+server. It writes nothing:
+
+```bash
+npx -y @bridge_gpt/mcp-server install conductor \
+  --required-check "epic-implementer-ci / gate" \
+  --allowed-bot "bridge-gpt-ai-tools-for-sfcc[bot]" \
+  --secret-name CLAUDE_CODE_OAUTH_TOKEN \
+  --branches "main,epic/**" \
+  --dry-run
+```
+
+Replace `main` with the real default branch and adjust the other values. Then
+ask the human to run the same command **without** `--dry-run`, in their own
+terminal, from the repository root. It runs eight phases:
+
+1. A read-only doctor. It stops before any write if something fatal is missing.
+2. A preview of the server settings, then "Write the safe project-default
+   supervisor posture now?". If the change would remove an existing
+   requirement, it asks a second, separate question.
+3. The `claude-review` workflow (only with the three flags from 5b).
+4. **Tool visibility:** adds `epic_implementer` to `BRIDGE_MCP_PROFILE` in the
+   Bridge entry of `.mcp.json`, `.vscode/mcp.json`, and `.cursor/mcp.json`. It
+   only edits files that already have a Bridge entry. It never creates a file
+   and never touches Codex or Copilot config.
+5. Local observability: the optional local git hooks. Safe to decline.
+6. A plan check, only with `--epic-key` and `--plan-file`. Skip it for now.
+7. An executor service, only with `--executor-id`. Skip it: `drive-epic` starts
+   one for each run.
+8. A capability report and a final doctor.
+
+The last line is `complete` or `complete-with-manual-steps`. Before the first
+run, `complete-with-manual-steps` is normal, because no executor has been seen
+yet. Read the "Manual actions" list it prints.
+
+**After it finishes:**
+
+- The workflow file (phase 3) was only written locally. It lands in step 6.
+- **Restart the MCP client** (the editor or `claude` session). The server reads
+  its tool groups at startup, so `get_epic_snapshot` and `explain_run` appear
+  only after a restart. Save your notes first. After the restart, confirm those
+  two tools are listed. If they are not, check that the Bridge entry's
+  `BRIDGE_MCP_PROFILE` contains `epic_implementer`, for example
+  `core,epic_implementer`.
+
+**Check it worked:** in `readiness --json`, `server.supervisor-setup`,
+`server.supervisor-config`, and `server.supervisor-required-checks` pass.
+
+**If it fails:** if the output says `Aborted` right after the URL question, it
+had no terminal or the human answered no. Ask them to run it again in their own
+terminal. If phase 1 lists a fatal row, fix that row first (usually step 3 or 4).
+
+## 6. The two workflows, on the default branch
+
+**Why:** child PRs need CI and review that really run. For unattended runs, the
+server also reads two files from the **default branch**, at fixed paths, before
+it creates or approves a run. If either is wrong, it refuses with
+`repository_readiness_unconfirmed`. **No install command fixes this.** The files
+must be merged into the default branch.
+
+| File | Requirement |
+|---|---|
+| `.github/workflows/claude-review.yml` | Must emit the `run-id:` and `Reviewed-SHA:` markers. Written by step 5 with the three flags from 5b. |
+| `.github/workflows/epic-implementer-ci.yml` | Must exist and parse as a workflow. Nothing in the package writes it. Use the template below. |
+
+A different file name does not count, even if it runs the same tests.
+
+**Ask first?** Yes. You will create a branch and open a pull request.
+
+### 6a. The `epic-implementer-ci.yml` template
+
+This is a minimal, generic starting point. It runs the repository's tests on the
+Epic Implementer's pull requests and reports one check,
+`epic-implementer-ci / gate`. That name is the required check from step 5.
+`gh pr view --json statusCheckRollup` shows it as `epic-implementer-ci / gate`.
+The GitHub web page may show it as `epic-implementer-ci / epic-implementer-ci / gate`
+(workflow name, then job name). The required check is still
+`epic-implementer-ci / gate`.
+
+The Epic Implementer names each child branch `feature/<TICKET-KEY>` and the
+epic branch `epic/<EPIC-KEY>`. Child PRs go from `feature/…` into `epic/…`. The
+final integration PR goes from `epic/…` into the default branch. The template
+tests every same-repository PR from a `feature/` or `epic/` branch. To test only
+the Epic Implementer's tickets, you may narrow `feature/` to
+`feature/<PREFIX>-`, where `<PREFIX>` is the ticket prefix of the **child**
+tickets. Get that wrong and every child PR counts as out of scope, so the gate
+passes **without running any tests**.
+
+```yaml
+name: epic-implementer-ci
+
+on:
+  pull_request:
+    # The default branch (change main if yours differs) and the epic branches
+    # that child pull requests target.
+    branches: [main, "epic/**"]
+
+permissions:
+  contents: read
+
+# A new push cancels the run for the older head of the same pull request.
+concurrency:
+  group: epic-implementer-ci-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  tests:
+    name: tests
+    # Same-repository feature/ and epic/ branches only.
+    if: >-
+      ${{ github.event.pull_request.head.repo.full_name == github.repository &&
+      (startsWith(github.event.pull_request.head.ref, 'feature/') ||
+      startsWith(github.event.pull_request.head.ref, 'epic/')) }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Test the exact head commit of the pull request.
+          ref: ${{ github.event.pull_request.head.sha }}
+          persist-credentials: false
+      # Add the repository's real setup steps here (language runtime,
+      # dependency install), then its real test command.
+      - name: Run tests
+        run: |
+          echo "Replace this step with the repository's test command."
+          exit 1
+
+  gate:
+    # This name IS the check-run name the done gate waits for. Keep it literal.
+    name: epic-implementer-ci / gate
+    needs: [tests]
+    if: ${{ always() }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Aggregate the result
+        env:
+          # Keep this identical to the tests job's condition.
+          IN_SCOPE: ${{ github.event.pull_request.head.repo.full_name == github.repository && (startsWith(github.event.pull_request.head.ref, 'feature/') || startsWith(github.event.pull_request.head.ref, 'epic/')) }}
+          TESTS_RESULT: ${{ needs.tests.result }}
+        run: |
+          if [ "$IN_SCOPE" != "true" ]; then
+            echo "Out-of-scope pull request: the gate passes without running tests."
+            exit 0
+          fi
+          if [ "$TESTS_RESULT" = "success" ]; then
+            echo "Tests passed."
+            exit 0
+          fi
+          echo "Tests concluded '$TESTS_RESULT', so the gate fails."
+          exit 1
+```
+
+Fill in the `tests` job with the repository's real test command. Find it in the
+existing CI workflows, `package.json` scripts, a `Makefile`, or the README. Ask
+the human if it is unclear. Do not leave the placeholder step: it fails on
+purpose.
+
+**Things to keep**, in this file and in `claude-review.yml`:
+
+- `if: ${{ always() }}` on the gate. Without it, a failed or skipped test job
+  would leave the gate check missing instead of red.
+- The gate is green only when the tests job concluded `success`. A skipped or
+  cancelled test job is never treated as a pass.
+- `persist-credentials: false` and the checkout of the pull request's head SHA.
+- **Static job names.** For unattended runs the server must read every job's
+  check name straight from both files. If either file has any of the following,
+  the server cannot read the names, and approval refuses every required check:
+  - a `strategy.matrix` on any job;
+  - a job-level `uses:` (a reusable workflow call). A `uses:` inside a step is
+    fine;
+  - a `${{ … }}` expression in any job id or job `name:`.
+
+  Put matrix or reusable-workflow jobs in a different workflow file if you need
+  them.
+
+### 6b. The `migration-guard` job (only for Alembic repositories)
+
+Check whether the repository has `alembic.ini` at its **root** on the default
+branch:
+
+```bash
+git fetch origin
+git ls-tree --name-only origin/<default-branch> alembic.ini
+```
+
+If that prints nothing, skip this part. If it prints `alembic.ini`, the server
+also requires a job whose id is exactly `migration-guard`, with a step that runs
+exactly `python scripts/check_alembic_migration_graph.py`. The repository must
+contain that script. It should fail when the Alembic revision graph has more
+than one head, a duplicate revision id, a missing parent, or a cycle. Add the
+job to `needs:` in the gate and fail the gate unless it concluded `success`. If
+the human does not want this, they can run attended instead.
+
+### 6c. Land both files
+
+1. Ask the human before you branch and push.
+2. Create a branch, for example `chore/epic-implementer-workflows`.
+3. Commit `.github/workflows/epic-implementer-ci.yml` and the
+   `.github/workflows/claude-review.yml` that step 5 wrote.
+4. Open a pull request into the default branch with `gh pr create`.
+5. Ask the human to review and merge it. Do not merge it yourself.
+
+**Secret the human must add** (repository Settings, then Secrets and variables,
+then Actions): a secret with the exact name you passed to `--secret-name`,
+holding a Claude Code OAuth token. The human can create one with
+`claude setup-token`. Never ask them to paste the token to you.
+
+**Check it worked:** after the merge, re-run `readiness --json`.
+`server.review-workflow`, `server.conductor-ci-workflow`, and
+`server.repository-workflow-readiness` should pass.
+
+**If it fails:** readiness names the missing item, for example "does not emit
+the Reviewed-SHA: marker". A detail saying Bridge "could not read" a file means
+the read failed, not that the file is wrong. Re-run readiness. If it keeps
+failing, contact Bridge support.
+
+## 7. Index the repository, after the workflows merge
+
+**Why:** `setup-epic` cuts `epic/<EPIC-KEY>` at the exact commit the code index
+was built from, not at the tip of the default branch. If that commit is older
+than the merge from step 6, the epic branch has no workflows. Then child PRs into
+it get no CI and no review, and every ticket waits forever. Each child ticket's
+plan also uses the index to find code.
+
+**Ask first?** No. Indexing runs on the server and changes nothing in the
+repository. It can take a while on a large repository.
+
+After the step 6 pull request has merged, run the `/parse-repository` slash
+command, even if the repository was indexed before. Then poll the
+`parse_repository` MCP tool with `action: "status"` until it reports completed.
+`doctor` also shows the indexing state.
+
+You will confirm the cut commit in [§11a](#11a-plan-the-epic), once a plan
+exists.
+
+**If it fails:** report the status message to the human. Do not start a real
+run until indexing has completed after the merge.
+
+## 8. Unattended prerequisites
+
+**Why:** an unattended run merges on its own, so three things are checked
+before a run is created. `--attended` skips them. `setup-epic` (which `/plan-epic`
+runs) and the `drive-epic` preview name each one differently.
+
+**Repository consent**
+- `setup-epic` refusal: `target_not_allowed`. `drive-epic` preview:
+  `unattended_consent`. Readiness row: `server.unattended-consent`.
+- It is **on by default**. The repository owner switches "Allow unattended Epic
+  Implementer runs" on the repository's Setup page in the Bridge admin panel.
+  Only a human can change it. If it is already on, contact Bridge support.
+
+**An escalation channel** (where alerts go when the run needs a person)
+- `setup-epic` refusal: `webhook_unverified`. `drive-epic` preview:
+  `unattended_notify_default`. Readiness row: `server.unattended-notify-default`.
+- The simplest channel is the email address on the Bridge account. It needs no
+  extra step when the account has one.
+- A webhook also works, but only through a `--policy-file` that sets
+  `notify.webhook_url`. `/plan-epic` and `/drive-epic-run` never pass a policy
+  file, so the webhook route needs the shell `drive-epic` ([§11c](#11c-attended-runs)
+  shows the command form). `notify.local_sink` does not count.
+
+  ```json
+  { "notify": { "webhook_url": "https://example.com/your-webhook" } }
+  ```
+
+  A policy file is the **complete** run policy, so keep it minimal. The server
+  tests the webhook when the run activates, so it must be reachable from the
+  internet.
+
+**The two workflows**
+- `setup-epic` refusal: `repository_readiness_unconfirmed`. `drive-epic`
+  preview: `repository_readiness`. Readiness row:
+  `server.repository-workflow-readiness`.
+- Finish step 6. The message names the missing file, marker, or job.
+
+**Readiness could not be read**
+- `setup-epic` refusal: `readiness_unreadable`.
+- The server did not report these facts. Retry. If it persists, contact Bridge
+  support.
+
+**Ask first?** Yes for anything that changes an account or admin setting. Only
+the human can change these.
+
+## 9. Merge credential and merge modes
+
+**Why:** in an unattended run, the executor on this machine merges each child PR
+into the epic branch with `gh pr merge`. In the default local mode it uses
+**only** the token in `BAPI_LOCAL_MERGE_TOKEN`. (A run in machine-user mode uses
+only `BAPI_MACHINE_MERGE_TOKEN` instead.) It never falls back to the human's `gh`
+login, `GH_TOKEN`, or `GITHUB_TOKEN`. Without the token, merges are refused. The
+diagnostics show this only as a warning (`conductor.merge-credential`), so it is
+easy to miss.
+
+**Ask first?** Yes. This concerns the human's GitHub credential.
+
+The executor inherits its environment from the process that runs `drive-epic`.
+So the variable must be set in the shell that launches `drive-epic`. If you use
+`/drive-epic-run`, that is **your own session's** environment, so the human must
+set it before starting the editor or `claude`.
+
+The simplest source is the human's own GitHub CLI token:
+
+```bash
+export BAPI_LOCAL_MERGE_TOKEN="$(gh auth token)"
+```
+
+To make it last, suggest the human add that exact line (the command, not the
+token value) to their shell profile, for example `~/.zshrc`, then open a new
+terminal and restart the editor. Never write the token value into any file, and
+never add it to the repository.
+
+If an executor is already running for a run, it will not see a newly exported
+value. It must be restarted from a shell that has it.
+
+**Check it worked:** `npx -y @bridge_gpt/mcp-server epic-implementer doctor`
+no longer warns about the merge credential. Run it from the same shell.
+
+### Optional: GitHub Actions merge mode
+
+Use this only if the human wants merges done by a GitHub Actions workflow
+instead of this machine. It applies only to a run whose policy file declares
+`"merge_execution_mode": "github_actions"`. Otherwise skip it.
+
+Ask the human to run, in their own terminal (it asks before writing):
+
+```bash
+npx -y @bridge_gpt/mcp-server install conductor --merge-workflow --codeowner <@org/team|@user>
+```
+
+`--codeowner` is required: the one GitHub user or team who must review changes
+to the merge workflow. Add `--dry-run` first to preview. The command writes
+`.github/workflows/epic-implementer-merge.yml` and two helper files, pushes a
+branch with the human's own git, and opens a pull request with their own `gh`.
+It never merges it.
+
+After the human merges that pull request, three manual steps remain. The human
+does all three:
+
+1. Create a repository Actions secret named `BAPI_API_KEY` holding the
+   repository's Bridge API key.
+2. Merge the rule from `.bridge/merge-workflow/CODEOWNERS.fragment` into the
+   active CODEOWNERS file. The fragment does nothing on its own.
+3. Add a default-branch rule that requires a pull request and code-owner review.
+   Until it exists, the workflow file is not protected.
+
+## 10. Verify
+
+**Before a plan exists**, use readiness only:
+
+```bash
+npx -y @bridge_gpt/mcp-server epic-implementer readiness --json
+```
+
+The `drive-epic` preview is not useful yet. Without a plan it only says
+`decision: stop`, with no reason, or a generic "not ready" refusal.
+
+**Done means:**
+
+- These rows pass: `server.supervisor-setup`, `server.supervisor-config`,
+  `server.supervisor-required-checks`, and `server.github-credentials`.
+- For unattended runs, these pass too: `server.unattended-consent`,
+  `server.unattended-notify-default`, and `server.repository-workflow-readiness`.
+  If a `server.admission-required-checks` row is present, it passes too.
+- `server.worker-present` and `server.single-transition-authority` pass. These
+  are the server's own health. If they fail, contact Bridge support.
+- `conductor.merge-credential` passes in the shell that will launch runs.
+- The `get_epic_snapshot` and `explain_run` tools are available.
+- Every other `fail` is explained, and the human accepted it.
+
+**After `/plan-epic` has written a plan**, preview the launch:
+
+```bash
+npx -y @bridge_gpt/mcp-server drive-epic <EPIC> --plan-file <path to epic-plan.dag.json> --dry-run --json
+```
+
+It changes nothing. Its `decision` is `create`, `attach`, `refuse`, or `stop`. A
+`refuse` carries `refusal.reason_id` and `refusal.remedy`. Map the `reason_id`:
+
+- `supervisor_setup`, `supervisor_config` — step 5.
+- `github_credentials` — step 4.
+- `unattended_consent`, `unattended_notify_default`, `repository_readiness` — step 8.
+- `remote-reconciler-not-live` — the Bridge server side. Contact Bridge support.
+- Anything else — read its `remedy`, then check the table in step 12 before you
+  run anything.
+
+Report to the human what passed, what failed, and what they still need to do.
+
+## 11. First run
+
+### 11a. Plan the epic
+
+`/plan-epic` needs an **existing epic ticket**. Run `/plan-epic <EPIC>` with its
+key, for example `SHOP-100`. Free text instead of a key gives no epic key, and
+no run can be created from it.
+
+It explores the code, splits the epic into child tickets, and asks the human to
+approve the split. It writes its files to `<docs_dir>/epic-plans/<slug>/`, where
+`<docs_dir>` is the docs folder the `ping` MCP tool reports (often `docs/tmp`).
+The plan file is `epic-plan.dag.json`.
+
+**Before the plan is approved, check every `ticket_key` in
+`epic-plan.dag.json`.** Each one must be a real ticket key. A placeholder such as
+`TBD-1` must not reach approval. If you see one, stop and create or link the
+real tickets first.
+
+**The last step of `/plan-epic` creates and approves an unattended run** (it
+runs `setup-epic` without `--attended`). For an attended run, see §11c before
+you reach that step.
+
+Before that step runs `setup-epic` for real, run its dry run and check the cut
+commit (plain output, not `--json`):
+
+```bash
+npx -y @bridge_gpt/mcp-server setup-epic --epic-key <EPIC> \
+  --plan-file <path to epic-plan.dag.json> --dry-run
+git fetch origin
+git ls-tree --name-only <sha from the "Cut:" line> .github/workflows/
+```
+
+The listing must include `claude-review.yml` and `epic-implementer-ci.yml`. If
+it does not, the index is older than the step 6 merge. Go back to step 7 and
+re-index first.
+
+**If `setup-epic` fails, what happened depends on where it failed:**
+
+- **`setup-epic REFUSED (<reason>)`** — a check before creation failed.
+  `target_not_allowed`, `webhook_unverified`, `repository_readiness_unconfirmed`,
+  and `readiness_unreadable` are all this kind. **Nothing was created.** Fix the
+  named item (step 8) and run it again.
+- **`The plan was NOT approved: …`** — the server refused at approval. By then
+  the run **was** created, the epic branch **was** cut, and the plan **was**
+  stored. The run waits in `planning`. The message always talks about unattended
+  consent, whatever the real cause. Ignore that wording and read the `Detail:`
+  line for `predicate` and `reason_code`:
+  - `admission_evidence_unverifiable` or `admission_evidence_denied` with
+    predicate `required_checks` — the required check is not a static job name in
+    the two workflow files (step 5a, and "Things to keep" in 6a).
+  - predicate `repository_readiness` — step 6.
+  - predicate `webhook` or `notify_webhook` — step 8, escalation channel.
+  - predicate `target_allowed` or `unattended_consent` — step 8, consent.
+  - any other predicate — report the `predicate` and `reason_code` to the human.
+
+  Fix the cause, then run the same `setup-epic` command again. It reuses the
+  existing run instead of creating a second one.
+
+### 11b. Drive an unattended run
+
+In Claude Code or Cursor:
+
+```text
+/drive-epic-run <EPIC> <path to epic-plan.dag.json>
+```
+
+It previews the launch, asks the human once, creates the run (or attaches to the
+one `/plan-epic` created), starts an executor, and watches the run to the end. It
+accepts no flags, so it cannot pass `--attended` or `--policy-file`. When it
+creates a run, the run must be unattended.
+
+From a shell, the same launch is:
+
+```bash
+npx -y @bridge_gpt/mcp-server drive-epic <EPIC> --plan-file <path to epic-plan.dag.json>
+```
+
+Add `--policy-file <policy.json>` for a webhook (step 8). Run it from the
+repository root, in a shell that has `BAPI_LOCAL_MERGE_TOKEN`. Always pass
+`--plan-file`. Without it, `drive-epic` searches only `docs/tmp/epic-plans/` (or
+`BAPI_DOCS_DIR`), which may not be where `/plan-epic` wrote. `drive-epic` starts
+a run-scoped executor in the background. Its log is
+`.bridge/executors/<run>.log`. The executor exits by itself when the run is done
+or abandoned.
+
+### 11c. Attended runs
+
+An attended run never merges by itself. It still needs a required check that
+really runs on child PRs into `epic/<EPIC-KEY>` (step 5a, attended branch), and a
+review verdict on those PRs (step 5b, `--branches` including `epic/**`).
+
+1. Plan with `/plan-epic <EPIC>`, but **do not let its last step run
+   `setup-epic`**. That step would create an unattended run whenever the
+   unattended prerequisites hold. Tell the human, and skip that step with their
+   agreement. If it has already run and refused with `setup-epic REFUSED`,
+   nothing was created and you can continue.
+2. Check every `ticket_key` in `epic-plan.dag.json`, as in §11a.
+3. Launch from a shell, from the repository root:
+
+   ```bash
+   npx -y @bridge_gpt/mcp-server drive-epic <EPIC> \
+     --plan-file <path to epic-plan.dag.json> --attended
+   ```
+
+`/drive-epic-run` cannot create an attended run.
+
+### 11d. Monitor
+
+- MCP tools: `get_epic_snapshot` (the full run state) and `explain_run` (why a
+  run or ticket is stuck). Both need the `epic_implementer` profile from step 5.
+- Notifications: `npx -y @bridge_gpt/mcp-server notifications --repo <repo_name> --run <EPIC> --follow`.
+- Quick health: `npx -y @bridge_gpt/mcp-server epic-implementer epic-status --epic-key <EPIC>`.
+
+### 11e. Stop and recover
+
+Always diagnose with the `explain_run` MCP tool first. Then apply one verb. Ask
+the human before any of them. Each runs as:
+
+```bash
+npx -y @bridge_gpt/mcp-server epic-implementer <verb> --epic-run-id <EPIC>
+```
+
+`--epic-run-id` takes the run id, or the epic key when the epic has exactly one
+active run.
+
+The two you will use most:
+
+| Verb | Use it to |
+|---|---|
+| `unpark --ticket-key <key>` | Send a parked (`needs_human`) ticket back into its gates once the cause is fixed. |
+| `stop-run` | Stop the run now: no new work, queued work cancelled. The record stays. |
+
+Advanced verbs. Use them only when `explain_run` points at them:
+
+| Verb | Use it to |
+|---|---|
+| `abandon-run` | End the run for good. **Terminal and irreversible.** |
+| `resume-run [--clear-quarantine]` | Resume a paused run. |
+| `adopt-current-head-and-unpark --ticket-key <key>` | Recover a ticket parked because someone pushed to its PR. |
+| `continue-child --ticket-key <key>` | Let a parked child carry on without resetting its attempt. |
+| `continuation-receipt --ticket-key <key>` | Check whether a `continue-child` request took effect (read-only). |
+| `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 with your notes. |
+| `merge-child --pr <number>` | Merge the run's child PR through the shared merge service. |
+| `scope-reparse --scope-id <scope>` | Re-index the run's own index scope. |
+| `scope-catch-up --scope-id <scope>` | Replay merges the run's scope missed. |
+| `patch-policy --patch-file <path>` | Change part of the run's policy. |
+
+In Claude Code or Cursor, `/drive-epic-run` applies these for you within limits,
+and asks when it must.
+
+## 12. Troubleshooting and known-wrong remedies
+
+Current tools print complete commands. Replace any placeholder in them with a
+real value before you run them. Older tool versions printed the shorthand in the
+left-hand column below, which does not work as typed. Use the right-hand column
+instead.
+
+| Printed remedy | Problem | Run this instead |
+|---|---|---|
+| `install-bridge connect-github` | `install` accepts no such argument, and there is no `npx` prefix. | `npx -y @bridge_gpt/mcp-server connect-github --repo <repo_name>` (step 4) |
+| `install-bridge conductor` or `install conductor` with no flags | Missing the `npx` prefix and the required `--required-check`. | The full command in step 5c |
+| `install-bridge conductor --merge-workflow` (older tools) | Missing the `npx` prefix and the required `--codeowner`. | `npx -y @bridge_gpt/mcp-server install conductor --merge-workflow --codeowner <@org/team\|@user>`; replace the placeholder with the one reviewer (step 9) |
+| `npx @bridge_gpt/mcp-server install` | Missing `-y`, so `npx` stops to ask. | `npx -y @bridge_gpt/mcp-server install` (step 3) |
+| Any remedy for `repository_readiness_unconfirmed` that names an install command | No install command creates the workflows. | Step 6, then step 7 |
+| `The plan was NOT approved: this repository is no longer authorized for unattended runs` | Printed for every approval refusal, whatever the cause. | Read `Detail:` (§11a) |
+| `install conductor --executor-id <id> --repo-wide` for executor readiness | Not needed to launch. | Nothing. `drive-epic` starts an executor per run. |
+
+Other common problems:
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Every `<launcher>` command exits `1` with a list of variable names | Old Epic Implementer variable names are set. | Step 2, retired-variable check. |
+| `install conductor` prints `Aborted` and exits `0` | No terminal, or the human answered no. | Rule 5: the human runs it in their own terminal. |
+| `--merge-workflow` prints `consent_declined` | No terminal, or the human answered no. | Rule 5. |
+| 403 on any command | `repo_name` does not match byte for byte. | Step 3. |
+| `get_epic_snapshot` is not available | The MCP client was not restarted, or the profile lacks `epic_implementer`. | Step 5, "After it finishes". |
+| Child PRs get no CI or no review at all | The epic branch was cut before the workflows merged, or `--branches` / the CI trigger lacks `epic/**`. | Steps 5b, 6a, and 7. |
+| Tickets wait forever at CI | The required check name does not match a check that runs on child PRs. | Step 5a. Compare with `gh pr view <n> --json statusCheckRollup`. |
+| Tickets pass CI but no tests ran | A narrowed `feature/<PREFIX>-` does not match the child branches. | Step 6a. |
+| Approval refused: `admission_evidence_unverifiable` on `required_checks` | The required check is not a static job name in the two workflow files. | Steps 5a and 6a. |
+| Child PRs are never merged | `BAPI_LOCAL_MERGE_TOKEN` was not set for the executor. | Step 9. |
+| `merge_execution_ineligible` | The policy declares `github_actions` merge mode, but the merge workflow is missing or not ready. | Step 9, optional part. Or remove that line from the policy. |
+| `drive-epic` cannot find the plan | It searched `docs/tmp/epic-plans/` only. | Pass `--plan-file`. |
+| The reconciler or worker rows fail | The Bridge server side is not healthy. | Nothing to fix locally. Contact Bridge support. |