@bridge_gpt/mcp-server 0.2.66 → 0.2.67

package/docs/EPIC-IMPLEMENTER.md

@@ -0,0 +1,662 @@
+# Epic Implementer — driving a multi-ticket epic
+
+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.
+
+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`. |
+
+For the everyday `start-tickets` flags, see
+[README → CLI Subcommands](../README.md#cli-subcommands).
+
+## How the v2 engine works
+
+| Half | Where it runs | What it does |
+| --- | --- | --- |
+| **Reconciler** | Server-side, on the Bridge API worker, about every 30s | Picks up every run whose status is `active`, evaluates each ticket's gates, and queues executor jobs. It is the **only** component that decides a transition. Nothing to install or schedule. |
+| **Executor** | Locally, on your machine | Polls for jobs, claims them, spawns worker agents, and heartbeats. Workers report facts; the reconciler decides. |
+
+**Run statuses** are `planning`, `pending_approval`, `active`, `blocked`,
+`abandoned`, and `done`. A paused, quarantined, or stopped run is `blocked` with a
+typed run-control record that says why and what clears it.
+
+**Ticket statuses** are `planned`, `spec_review`, `implementing`, `ci`,
+`code_review`, `merging`, `parsing`, `smoke`, `needs_human`, `done`, and
+`abandoned`. A ticket that needs a person **parks** as `needs_human`. See
+[Recovering a parked run](#recovering-a-stuck-or-parked-run).
+
+**The v1 `epic-implementer epic-tick` command is frozen.** It throws
+`EPIC_TICK_V1_FROZEN` and advances nothing. There is nothing to schedule
+locally. If you registered an epic-tick schedule with an older release, remove
+it; it is a dead timer.
+
+## Drive an epic: `drive-epic`
+
+`drive-epic` is the **one entry point** for running an epic. It reads the
+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 \
+  --plan-file docs/tmp/epic-plans/<slug>/epic-plan.dag.json
+```
+
+Run it from a Git checkout of the target repository. In one command it:
+
+1. Checks readiness and, for an unattended run, the unattended prerequisites.
+   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
+   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.
+
+**Finding the plan.** `--plan-file` is optional. Without it, `drive-epic` looks
+for `{docs_dir}/epic-plans/*/epic-plan.meta.json` naming this epic, where
+`docs_dir` is `BAPI_DOCS_DIR` or `docs/tmp`. It uses exactly one match. No match,
+or more than one, stops with the paths it found. The plan files come from the
+epic planning flow (`/define-tickets` for an epic, or `/plan-epic`).
+
+**A live run with no plan.** If the epic already has a live run and you pass no
+plan, `drive-epic` creates nothing. It makes sure the run has an executor and
+reports it.
+
+**Preview first.** `--dry-run` resolves the target, reads readiness and any live
+run, finds the plan, and runs the server's plan validation. It changes nothing.
+Add `--json` for one machine-readable document. It exits `0` for create or
+attach, and `1` for refuse or stop.
+
+### Main flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--plan-file <path>` | The plan DAG. Optional (see above). |
+| `--repo <name>` | Repo name. Default: `BAPI_REPO_NAME` or `.bridge/config`. |
+| `--feature-branch <name>` | Use your own epic branch name. |
+| `--into-base` | Opt out of the epic branch; child PRs target the base branch. |
+| `--attended` | Opt out of the unattended default (see below). |
+| `--policy-file <path>` | The **complete** run policy, applied when the run is created. |
+| `--review-policy <src>` | The review policy for this run only. |
+| `--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). |
+
+**Target.** With no profile, `--base-url`, or `BAPI_BASE_URL`, `drive-epic`
+targets production.
+
+### Unattended by default
+
+A run on an epic branch is created **unattended**. Child PRs merge automatically
+into the epic branch. The one **integration PR** from the epic branch into the
+base branch stays human-gated: a person merges it. Pass `--attended` to opt out;
+the run then has no auto-merge authorization.
+
+An unattended run needs three things. Each is refused **by name** before any run
+is created, and `drive-epic --dry-run` lists them:
+
+| Prerequisite | How to satisfy it |
+| --- | --- |
+| Repository consent | On by default. The repository owner can switch "Allow unattended Epic Implementer runs" off and on in the Bridge admin panel's Setup page. |
+| An escalation channel | A `--policy-file` that declares `notify.webhook_url`, **or** an email address on the account. `notify.local_sink` does not count. |
+| Repository readiness | `.github/workflows/claude-review.yml` and `.github/workflows/epic-implementer-ci.yml` confirmed on the default branch. The refusal names what is missing. |
+
+**Merge-execution eligibility.** If the repository cannot perform a merge without
+a standing write credential, `setup-epic` refuses with
+`merge_execution_ineligible`, names the remedy
+`npx -y @bridge_gpt/mcp-server install conductor --merge-workflow --codeowner <@org/team|@user>`
+(replace the placeholder with the one `@user` or `@org/team` who should review the
+workflow file; Bridge cannot infer it), and ends with `No run was created.`
+This applies to attended and unattended runs alike.
+
+### Branch strategy
+
+A plan with **two or more** nodes runs on a dedicated `epic/<KEY>` branch. Every
+child PR targets that branch, and one **draft** integration PR targets the base
+branch.
+
+| You want | Pass |
+|---|---|
+| 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` |
+
+A single-node plan keeps the base branch by default. `--feature-branch` and
+`--into-base` together are a parse error.
+
+On an epic-branch run, a shadow-index check that cannot be proven right away
+**holds, then parks**: independent tickets go on, a dependent ticket waits, and
+past the deadline it parks as `needs_human`. The run's gate snapshot carries a
+`shadow_hold` object naming the reason and the recovery.
+
+### `setup-epic` (what `drive-epic` delegates to)
+
+`setup-epic --epic-key <KEY> --plan-file <path>` creates the run, stores the
+plan, and approves it. `drive-epic` calls it for you; call it yourself only when
+you need its lower-level flags (`--plan-version`, `--local-only`).
+
+- It validates the plan locally (unique keys, resolvable `depends_on`, no cycles),
+  then with the server's real validator, **before** creating anything. A bad plan
+  creates no run and incurs no automation-start charge.
+- It is **idempotent**: re-running on an epic with a live run reuses that run.
+- `--dry-run` runs the server's validation and stops. `--dry-run --local-only`
+  skips the server and is labeled `partial (local checks only)`.
+
+Unlike `drive-epic`, `setup-epic` does not start an executor.
+
+### One command for the whole session: `/drive-epic-run`
+
+The `/drive-epic-run <EPIC> [<plan path>]` slash command wraps all of this for an
+agent session. It previews with `drive-epic --dry-run`, asks you once, creates the
+run through `drive-epic`, and then watches the run until it is terminal. It may
+apply one sanctioned recovery verb at a time, within a fixed scope and budget, and
+records each one. It never edits gate state or code.
+
+## The executor
+
+`drive-epic` starts the executor for you. Start one by hand only for a durable
+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
+  `--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
+  executor never falls back to production.
+- `--exit-when-run-terminal` exits once the one `--epic-run-id` run is finished.
+- `--once` runs a single claim cycle. `--max-concurrent` defaults to 1.
+- `executor watch <job-id>` attaches read-only to a job's worker log.
+- `executor install-service --executor-id <id> ...` writes one launchd (macOS) or
+  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.
+
+## The CI gate
+
+Each ticket's `ci` gate reads `policy_json.required_checks` and waits for those
+checks at the ticket PR's **current head SHA**.
+
+**The server stamps the CI gate at first approval** when your policy declares
+neither `required_checks` nor `no_ci_gate`:
+
+1. If the repository's default done gate (`done_gate_config`, see
+   [below](#supervisor-config)) lists required checks, those become the run's
+   `required_checks`.
+2. Otherwise, on an epic-branch run that auto-merges, and whose plan declares no
+   node-level checks, the server records `no_ci_gate: true`. That run's `ci` gate
+   passes without CI.
+3. Otherwise nothing is stamped.
+
+A run left with **no** effective check and **no** `no_ci_gate` declaration does
+not pass trivially. Its tickets **park** (`required_checks_empty_no_mode`). An
+auto-merge run on the base branch with no check parks as `required_checks_empty`.
+
+To set the checks yourself, put them in the policy file:
+
+```json
+{ "required_checks": ["epic-implementer-ci / gate"] }
+```
+
+To change the policy of a live run, re-run with `--policy-file`. An identical
+policy is a no-op. A different one is refused with a redacted diff unless you add
+`--replace-policy`. For a targeted change, use `epic-implementer patch-policy`.
+
+**Once gated:**
+
+- A complete **red** check enters the bounded `ci_fix` repair path. A missing or
+  still-running check stays pending.
+- A green result from an **older head** never satisfies the gate after a rebase
+  or force-push.
+- In Bridge's own `epic-implementer-ci` workflow, PRs from forks, bots, and
+  branches other than same-repository `feature/BAPI-*` and `epic/**` get an
+  immediate green. That is cost control, not proof the suites ran.
+
+## Plan metadata: `touched_files`
+
+**Plan-time file-overlap serialization is on by default**
+(`planner_file_overlap_serialization_enabled`). Before the plan is stored, two
+sibling tickets that predict overlapping files gain a dependency edge. Siblings
+with disjoint files stay parallel.
+
+`touched_files` is that prediction. It is optional and never checked against the
+real diff:
+
+| In the node | Meaning | Result |
+|---|---|---|
+| Field **absent** | The node opts out of serialization | Accepted. No edge is added for it. |
+| `"touched_files": []` | "This ticket predicts no overlap" | Accepted as declared and empty. |
+| Present but **malformed** | Not a list, or a blank, absolute, or non-string path | **400** (`VALIDATION`) |
+
+Paths are relative to the repository root.
+
+```json
+{
+  "plan_version": 1,
+  "nodes": [
+    { "ticket_key": "BAPI-405", "status": "planned", "depends_on": [],
+      "touched_files": ["api/routes/jira_api.py"] }
+  ],
+  "edges": []
+}
+```
+
+Declare it anyway. `setup-epic --dry-run` warns when it is missing; that is a
+planning-quality signal, not a predicted failure. Serialization only **adds**
+edges, so your own `depends_on` and `touched_files` combine safely.
+
+Serialization is a scheduling aid, not a safety net. If a sibling's merge makes a
+PR conflict, the reconciler sees it and routes the ticket to a rebase job, whether
+or not the node declared `touched_files`.
+
+## Recovering a stuck or parked run
+
+**Diagnose first:**
+
+- The `explain_run` MCP tool explains why a run, or one ticket, is stuck: current
+  gate, latest observation, outstanding jobs, lease, blockers, and head SHA.
+- The `get_epic_snapshot` MCP tool returns the full run state.
+- `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.
+
+Both MCP tools need the `epic_implementer` profile group (see
+[MCP profile](#mcp-profile)).
+
+**Then apply one verb.** These are CLI-only (never MCP tools) and run as
+`npx -y @bridge_gpt/mcp-server epic-implementer <verb> ...` or through the
+`epic-implementer` bin. Each takes `--epic-run-id <id>`.
+
+| Verb | What it does |
+| --- | --- |
+| `stop-run` | Stop the run: block dispatch and cancel queued work. The record stays. |
+| `abandon-run` | Abandon the run. Terminal and irreversible. |
+| `resume-run [--clear-quarantine]` | Resume a paused run (a quarantined one only with the flag). |
+| `unpark --ticket-key <key>` | Move a `needs_human` ticket back into its gates. |
+| `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. |
+| `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. |
+| `scope-reparse --scope-id <scope>` | Re-drive the run's own index scope and schedule its parse. |
+| `scope-catch-up --scope-id <scope>` | Replay merges the run's scope did not observe. |
+| `patch-policy --patch-file <path>` | Merge-patch (RFC 7396) the run's policy. Protected paths are refused. |
+
+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`.
+
+**Check prerequisites.** `epic-implementer readiness` is a read-only advisory
+report of every prerequisite (install, doctor, plane preflight, and server), each
+with one named fix. It never runs a fix and always exits `0`.
+`epic-implementer doctor` reports local health read-only.
+
+## Setting up a repository: `install conductor`
+
+`npx -y @bridge_gpt/mcp-server install conductor` bootstraps a repository for the
+Epic Implementer. It runs a read-only doctor first, then asks for consent before
+each write: the supervisor project defaults, an optional `claude-review` workflow,
+adding `epic_implementer` to your MCP config, and the local git hooks.
+
+`npx -y @bridge_gpt/mcp-server install conductor --merge-workflow --codeowner <@org/team|@user>`
+generates the merge workflow and its CODEOWNERS fragment, pushes a branch with your own git, and
+opens a PR with your own `gh`. It never merges that PR. Replace
+`<@org/team|@user>` with the one reviewer of the workflow file before running;
+Bridge cannot infer it.
+
+## MCP profile
+
+The Epic Implementer MCP tools are `get_epic_snapshot` and `explain_run`. They
+register only when `BRIDGE_MCP_PROFILE` includes the `epic_implementer` group (or
+`full`). The default profile is `core`, which does not include them.
+
+```
+BRIDGE_MCP_PROFILE=core,epic_implementer
+```
+
+The old `conductor` profile token is retired and ignored. `epic-implementer
+doctor` flags it.
+
+## Binaries
+
+| 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`. |
+
+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)
+
+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
+`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
+way: `EPIC_IMPLEMENTER_DEAD_MAN_ONLY`, `EPIC_IMPLEMENTER_DEADMAN_CHANNEL_TYPE`, and
+`EPIC_IMPLEMENTER_DEADMAN_DESTINATION_REF`.
+
+**Old names are refused, not ignored.** If any `BAPI_CONDUCTOR_*` variable,
+`CONDUCTOR_NODE_PATH`, or an old `CONDUCTOR_DEAD_MAN_ONLY` /
+`CONDUCTOR_DEADMAN_*` name is set, these entry points refuse:
+
+| Entry point | On an old name |
+|---|---|
+| 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.
+
+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
+prints **key names only, never values**, because these variables can hold secrets.
+Stale names usually live in shell profiles, hand-edited executor service units, or
+CI settings.
+
+**Version skew.** A worker environment injected by an **older** package still
+carries old names, so a **newer** process started inside it refuses to start. This
+is intended. Re-spawn the worker so the launcher and the process it starts use the
+same package version. If that does not fix it, send the MCP package owner both
+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)
+
+This layer is **off by default**. It is separate from the v2 engine and never
+decides a transition. Without `--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`
+event to the local ledger (`~/.config/bridge/events.db`), attributes each worker by
+`worker_id`, ticket key, and worktree path, and opens a supervisor tab. With
+**Claude Code**, it also adds a lifecycle hook to each worktree's
+`.claude/settings.local.json` (keeping existing hooks). The hook streams
+`run.started`, `run.stopped`, and `agent.notification` events, plus `tool.intent`
+with `BAPI_EPIC_IMPLEMENTER_ENABLE_PRE_TOOL_USE=1`.
+
+- Worker identity passes only through secret-free env scoped to one tab. No
+  credential is ever placed in env, the hook command, or run metadata.
+- Override labels with `BAPI_EPIC_IMPLEMENTER_GATE_NAME` and
+  `BAPI_EPIC_IMPLEMENTER_SUPERVISOR_MODE`.
+- Observability is best-effort. A failure never blocks a spawn, and `--dry-run`
+  has no side effects.
+- Each worker's `BRIDGE_MCP_PROFILE` becomes the parent's resolved groups **plus**
+  `epic_implementer`, so the worker gets the two Epic Implementer tools. A plain
+  `start-tickets` run keeps the parent profile.
+
+Inspect the stream with `epic-implementer doctor`. See also
+[README → Environment Variables](../README.md#environment-variables).
+
+## `epic-implementer install-git-hooks` (BAPI-395)
+
+Installs local git hooks that emit git events into the local ledger:
+
+```
+epic-implementer install-git-hooks [--json]
+```
+
+The hooks are **local, unversioned, opportunistic, and bypassable**. They live in
+the worktree's git hooks directory (from `git rev-parse --git-common-dir`), add
+only a clearly delimited managed block (keeping your own hook content), run the
+producer **detached in the background** so a commit is never blocked, and end in
+`|| true`. A directory that is not a git worktree, or an existing hook that looks
+binary or unsafe, is left alone and reported as a **degraded optional
+capability**, never a fatal error. The hooks are `post-commit` (emits
+`git.commit_created`) and `reference-transaction` (emits `worktree.changed` for
+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)
+
+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
+runtime** and refuses anything that can disappear under it.
+
+**Supported installation.** Install the package persistently, then install the
+hooks from that install:
+
+```bash
+npm i -g @bridge_gpt/mcp-server
+epic-implementer install-git-hooks
+```
+
+A user-owned persistent prefix (`npm i -g --prefix <dir>`, with `<dir>/bin` on
+PATH) works the same way. The hook embeds the fixed entry
+`<prefix>/lib/node_modules/@bridge_gpt/mcp-server/build/epic-implementer-bin.js`
+(POSIX single-quoted) and launches it with `node` from PATH. It never embeds npm's
+`.bin` shim and never pins `process.execPath`.
+
+Running the installer through `npx` works only as a front door: it looks up an
+**already installed** global package with a bounded, offline `npm root -g` and
+embeds that. With no qualified persistent install, it refuses.
+
+**What "qualified" means.** Before touching any hook, the installer checks,
+read-only:
+
+| Check | Refusal classification |
+|---|---|
+| 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 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` |
+| That Node is an even LTS line ≥ 20 | `unqualified-runtime` |
+| `better-sqlite3` loads for that Node | `native-unavailable` |
+
+A refusal exits 1, prints only the classification and a fixed action (never a
+path or error text), and leaves both hooks unchanged. Hooks are optional: a
+refusal never blocks the engine.
+
+**Qualified matrix.** Recorded evidence, not inference:
+
+| OS | Install | Node | Native | Status |
+|---|---|---|---|---|
+| macOS 26 (Darwin 25.6, arm64) | persistent `npm i -g --prefix` (npm 11.13.0) | v24.16.0 (ABI 137) | better-sqlite3 13.0.3 | qualified by `packaged-git-hooks-lifetime.test.ts` |
+| Linux | persistent `npm i -g` | even LTS ≥ 20 | better-sqlite3 13.x | accepted by policy; **not yet locally qualified** |
+| Windows | any | any | any | **unqualified** — always refused |
+| Any | `npx` cache only, version-manager switches (nvm/fnm/volta), other layouts | — | — | **unqualified** |
+
+**Publication.** The installer plans both hooks before writing either. It refuses
+a symlinked, non-regular, unreadable, or binary hook and changes nothing. Each
+hook is written to a temporary file in the same directory, re-checked, and renamed
+atomically over the target. A hook edited in the meantime is left alone
+(`intervening-edit`). If one hook publishes and the other does not, the result is
+`PARTIAL` (exit 1); re-running converges to one managed block per hook.
+
+**Diagnosis.** `epic-implementer doctor` (and `install doctor`) report each hook's
+`state` and `usable` verdict read-only. A hook that points into the npx cache
+(`ephemeral-cache`), at a removed install (`missing`), at the retired name
+(`legacy-name`), or at a runtime whose native binding no longer loads
+(`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`),
+then re-run `epic-implementer install-git-hooks` (or `install conductor` and
+accept the local-observability consent). The managed block is replaced in place.
+
+**Upgrades and rollback.** `npm i -g @bridge_gpt/mcp-server@<version>` replaces
+the package in place, so hooks keep working without a rewrite. To roll back,
+install the previous version the same way, then run `epic-implementer doctor`.
+
+**What is not promised.** Events that happen while hook delivery is unavailable
+are **lost and not replayed**. Commits are never blocked or slowed, and the engine
+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
+> `PUT /jira/config-field/...` returns **HTTP 400 "Invalid config field"**, which
+> is correct.
+
+Each setting has a per-repo **project default** and a per-epic override:
+
+| Setting | Endpoint (project default) |
+| --- | --- |
+| `done_gate_config` | `PUT /jira/epic-runs/supervisor-setup/defaults/?repo_name=<repo>` |
+| `auto_merge_enabled`, `merge_approval_required` | `PUT /jira/epic-runs/supervisor-config/defaults/?repo_name=<repo>` |
+
+Swap `…/defaults/` for `…/runs/{epic_key}/…` to scope a setting to one epic. The
+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
+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.
+
+### `done_gate_config`
+
+Defines the done gate. It supports one condition, `required_ci_checks_green`:
+
+```json
+{
+  "enabled": true,
+  "conditions": [
+    { "type": "required_ci_checks_green", "required_checks": ["build", "test"] }
+  ]
+}
+```
+
+It serves two readers:
+
+- **The v2 engine** takes its first-approval `required_checks` stamp from the
+  project default's checks (see [The CI gate](#the-ci-gate)).
+- **The `merge_pull_request` tool and the observability-layer supervisor** emit
+  `gate.met` (once per repo, PR, head SHA, and config) only when every listed
+  check is present, complete, and green for the PR head. An unset, disabled,
+  malformed, or empty config emits nothing.
+
+### `auto_merge_enabled`
+
+This switch governs the `merge_pull_request` tool and the observability-layer
+supervisor. It does **not** govern v2 epic merges: those read only the run's
+`policy_json.v2_auto_merge_enabled`, which an unattended epic-branch run sets on.
+
+**For the switch's own consumers, auto-merge is off by default.**
+
+- **Off, unset, or unconfigured → dry-run.** The supervisor records a
+  `merge.dry_run` event and merges nothing.
+- **On → autonomous merge** when the gate is met and the guards pass.
+- **Kill-switch.** Set it to `false` to stop autonomous merges at once. The
+  protected merge endpoint re-checks the flag itself.
+
+Merge authority is **deterministic code, never an LLM**. Every guard is bound to
+**PR number + expected head SHA** (never a branch name): the enablement flag, the
+PR still open, **no head-SHA drift** between gate and merge, and required checks
+**re-validated green right before the merge**.
+
+A TTL lease keyed by `merge:{repo}:{pr}:{head_sha}:{gate}` makes merging
+crash-safe and race-safe; an existing `merge.succeeded` for that key is terminal.
+The caller never holds VCS write credentials: it calls
+`POST /vcs/pull-requests/{pr_number}/merge`, which owns the privileged merge. The
+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
+`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:
+
+- the executor's `merge` job; and
+- the `merge_pull_request` MCP tool, which receives `approved_for_local_execution`,
+  merges locally, and reports to `POST /vcs/pull-requests/{pr_number}/merge/complete`.
+
+The server still owns every decision: the guards, the lease, and the final record.
+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)
+
+This section applies to the observability layer. It keeps a worker's own ledger
+calls reliable. It is not a completion backstop.
+
+**The invariant: the worker Node never loads `better-sqlite3`.** Worker ledger
+operations run through `epic-implementer-bin.js` under the Node that owns the
+ledger. Dispatch passes that Node to each worker as `EPIC_IMPLEMENTER_NODE_PATH`,
+and the packaged `epic-implementer-bin.js` path as
+`BAPI_EPIC_IMPLEMENTER_CLI_FILE`. The worker side shells out with a fixed list
+argv through `execFile` (never a shell string) and sends event JSON over stdin, so
+payloads never enter the argument list. Processes that own the ledger (the CLI and
+supervisor) call the store directly. The local ledger store is at schema version 8.
+
+**Fail loud, never fall back.** A missing or invalid `EPIC_IMPLEMENTER_NODE_PATH`,
+or a missing `BAPI_EPIC_IMPLEMENTER_CLI_FILE`, returns the
+`LEDGER_SUBPROCESS_RUNTIME_UNAVAILABLE` (503) envelope with a path-free
+`details: { env_var, reason }`. It never falls back to the worker's own Node.
+`EPIC_IMPLEMENTER_NODE_PATH` is non-secret and is never written to `.mcp.json`.
+
+**Rejected alternatives.**
+
+- **Local HTTP sidecar** (a ledger daemon on a port): port conflicts, zombie
+  processes, and token handling, all too much for a file-backed ledger.
+- **WASM / pure-JS SQLite in the worker**: it gives up `better-sqlite3`'s proven
+  WAL behavior and fits poorly with a database file shared by several processes.
+
+### Three protective guarantees
+
+1. **Ledger operations are isolated from the worker.** A Node ABI mismatch
+   degrades a worker convenience, never the whole session.
+
+2. **Non-mutating dispatch.** Dispatch resolves the base with a fetch-only
+   `origin/<base>` lookup and cuts new worktrees from that SHA. It never checks
+   out, fast-forwards, force-moves, or stashes your live checkout. A live-source
+   guard also refuses dispatch when the base repo path equals your live dev-server
+   checkout:
+   - `BAPI_EPIC_IMPLEMENTER_LIVE_SOURCE_PATH` — the checkout to protect.
+   - `BAPI_EPIC_IMPLEMENTER_ALLOW_LIVE_SOURCE_DISPATCH` — a truthy override that
+     turns a collision into a loud warning.
+   `doctor` reports the guard state (`not-configured`, `safe`, or `collision`).
+
+3. **Parse runs in a separate process.** The post-merge re-index runs outside the
+   API server's event loop, so the server stays responsive during a parse. A
+   merged ticket enters `parsing` and moves on only after the parse succeeds. A failed parse is retried within a budget and then parks the ticket
+   as `needs_human`; it never silently wedges the epic.