@bridge_gpt/mcp-server 0.2.66 → 0.2.67

package/docs/CONDUCTOR.md

@@ -1,605 +0,0 @@
-# Conductor — epic & multi-agent orchestration
-
-Conductor is the **opt-in, off-by-default** coordination layer for running many
-agent sessions together (epic supervision, inter-agent messaging, done-gate
-evaluation, and conditional auto-merge). A normal `start-tickets` run does **not**
-involve Conductor — you opt in per run with `--conductor`.
-
-This document is the reference for Conductor's architecture, epic setup,
-observability stream, local git hooks, and the per-repo done-gate / auto-merge
-config. For the everyday `start-tickets` flags and cross-platform behavior, see
-[README → CLI Subcommands](../README.md#cli-subcommands).
-
-## Epic Conductor v2 — how an epic is actually driven
-
-**The v1 `epic-implementer epic-tick` command is frozen.** It throws
-`EPIC_TICK_V1_FROZEN` on every invocation and advances nothing. There is nothing
-to schedule locally. If you have an epic-tick schedule registered from an earlier
-release, remove it — it is a dead timer.
-`epic-implementer doctor` flags one if it finds it. (S4/BAPI-1080 renamed the
-event-ledger CLI from `conductor` to `epic-implementer`; the retained
-`conductor` bin name is now a fixed migration pointer.)
-
-v2 splits the old local tick into two halves:
-
-| Half | Where it runs | What it does |
-| --- | --- | --- |
-| **Reconciler** | **Server-side**, on the Bridge API worker dyno, every 30s | Selects every epic run whose status is `active`, evaluates gates, and enqueues executor jobs. Nothing to install or schedule. |
-| **Executor** | **Locally**, on your machine | Polls for jobs, claims them, spawns worker agents, heartbeats. This is the only piece you run. |
-
-> **⚠️ For a run against a LOCAL server, do NOT use `npx`.** The npm-published
-> package routinely lags `main` — that is the normal steady state right after any
-> conductor ticket merges. When the server is built from a newer `main` it mints
-> `prompt_spec` placeholders the older published executor rejects, and the job dies
-> instantly with `ContractError.Prompt` (`prompt_spec for job N declares unsupported
-> placeholder '…'`). Confirmed on the BAPI-716 run: published `0.2.34` vs. local
-> `0.2.35`, over BAPI-699's `RELATED_CONTEXT`. Build and run the local tree so the
-> executor and server come from the same commit:
->
-> ```
-> cd mcp_server && npm run build
-> node mcp_server/build/index.js executor --repo <name>
-> ```
-
-For a run against a deployed server whose version you match, the published CLI is
-fine:
-
-```
-npx -y @bridge_gpt/mcp-server executor --repo <name>
-```
-
-The reconciler drives a run purely off `epic_runs.status = 'active'` — there is no
-local schedule, and no per-repo "enable the tick" flag. (An `epic_tick_enabled`
-config field existed briefly and was inert; it has been removed.)
-
-## Setting up an epic
-
-One command creates the run, stores the plan, and approves it:
-
-```
-npx -y @bridge_gpt/mcp-server setup-epic --epic-key BAPI-405 \
-  --plan-file docs/tmp/epic-plans/<slug>/epic-plan.dag.json
-```
-
-The plan sidecar (`epic-plan.dag.json`) is produced by the `decompose-epic`
-pipeline step. `setup-epic` validates it locally (unique ticket keys, resolvable
-`depends_on`/edge references, acyclicity) before sending anything, so a malformed
-plan fails legibly instead of as a bare HTTP 400.
-
-### Branch strategy: the epic branch is the default (BAPI-1009)
-
-The command above — no branch flag — now runs a **multi-ticket** epic on a
-dedicated `epic/<KEY>` branch. Every child-ticket PR targets that branch, and one
-**draft** integration PR targets the repository base branch. This applies on every
-path, CI and `--json` included. `drive-epic` forwards both flags below to
-`setup-epic`, so the universal entry point can select either strategy.
-
-| 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>` |
-| The old direct-to-base behavior | `--into-base` |
-
-> **Behavior change.** Before BAPI-1009 a run with no branch flag went straight to
-> the repository base branch. Automation that relied on that must now pass
-> `--into-base`. A single-node plan still keeps the base branch by default, matching
-> plain `start-tickets`. `--feature-branch` and `--into-base` together are a parse
-> error, refused before any file read, credential resolution, or network call.
-
-On an epic-branch run, a shadow-index verification that cannot be proven
-immediately resolves as bounded **hold-then-park** rather than blocking the run:
-independent tickets proceed, a dependent holds, and past the deadline it parks
-through the ordinary `needs_human` path. The epic run's gate snapshot carries a
-run-level `shadow_hold` object naming the reason and the recovery while that is
-live. This addresses BAPI-993 run issue A1.
-
-Since BAPI-754 it then calls the server's **real** validator
-(`POST /jira/epic-runs/plan/validate`) before creating anything, so a plan the
-server would reject — a node missing `status`, say, which the local checks do not
-cover — no longer creates a run and incurs an automation-start charge on its way
-to failing.
-
-It is **idempotent**: re-running it on an epic that already has a live run reuses
-that run rather than minting a second one. Use `--dry-run` to run that
-authoritative validation and preview the calls without mutating anything; add
-`--local-only` to skip the server entirely, which reports
-`partial (local checks only)` and is never a substitute for the server's verdict.
-
-Once the plan is approved the run becomes `active`, the server-side reconciler
-picks it up within ~30s, and your local `executor` starts claiming jobs.
-
-### `touched_files` — optional, but declare it anyway
-
-**Plan-time file-overlap serialization is live and on by default.**
-`planner_file_overlap_serialization_enabled` (BAPI-495, defaulted on by BAPI-677 /
-migration 0126, on `config_code_repositories`) makes overlapping siblings gain a
-`depends_on`/edge on each other *before* the DAG is validated, hashed, and stored,
-while siblings with disjoint files stay parallel.
-
-`touched_files` is the plan-time metadata that pass reads. It is a **best-effort
-prediction, never reconciled against the real diff**, so BAPI-722 made it optional.
-Three outcomes, and the difference between the first two is the point
-(`_extract_predicted_touched_files`, `api/library/db/epic_runs.py:3195`):
-
-| In the node | Meaning | Result |
-|---|---|---|
-| Field **absent** | The node **opts out** of preemptive serialization | **Accepted.** Every pair involving it is skipped (`undeclared_pairs_skipped`); no edge is added in either direction |
-| `"touched_files": []` | A deliberate "this ticket predicts no file overlap" | Accepted as a *declared* node with an empty set |
-| Field present but **malformed** | A non-list, or a list holding a blank, absolute, or non-string path | **400** — `EpicRunConflictError(code="VALIDATION")` |
-
-Only omission is relaxed. Data you *did* supply must be well-formed. Paths are
-repo-root-relative.
-
-```json
-{
-  "plan_version": 1,
-  "nodes": [
-    { "ticket_key": "BAPI-405", "status": "planned", "depends_on": [],
-      "touched_files": ["api/routes/jira_api.py"] }
-  ],
-  "edges": []
-}
-```
-
-> **`setup-epic --dry-run` warns on a missing `touched_files`, and that warning is
-> a planning-quality signal, not a predicted failure.** The server accepts the
-> plan. What you lose is scheduling protection: an undeclared node is never
-> pre-serialized against its siblings.
-
-Declare it anyway. Serialization only ever **adds** edges — it never removes an
-authored one — so hand-authored `depends_on` and `touched_files` compose safely.
-Author both: the edges as your reviewable statement of intent, `touched_files` so
-the scheduler can catch overlaps you did not anticipate.
-
-> **Serialization is a scheduling optimization, not a safety mechanism.** It avoids
-> *dispatching* file-overlapping siblings in parallel; it does not resolve a
-> conflict once one exists. The safety net is reactive and independent of any
-> prediction: a PR that a sibling's merge turns `CONFLICTING` is observed live and
-> routed to `JOB_TYPE_REBASE` (`_merge_entry_failure_requires_rebase` in the
-> reconciler). That backstop covers declared and undeclared nodes alike — which is
-> exactly why omitting `touched_files` is safe to accept.
-
-## The conductor CI gate — `epic-implementer-ci / gate` (BAPI-695)
-
-**Before driving a run you want CI-gated, wire its policy.** The reconciler's
-per-ticket `ci` gate reads **`policy_json.required_checks`** (a declared
-`RunPolicy` key) and observes those check-run conclusions at the ticket PR's
-**current head SHA**. If that list is empty, the observer short-circuits to
-`PASSED` with `{"no_required_checks": true}` and **runs no CI at all** — the loop
-merges on hand-verification only. `.github/workflows/epic-implementer-ci.yml` publishes
-the real, always-reporting required context **`epic-implementer-ci / gate`**; set
-
-```json
-"policy_json": { "required_checks": ["epic-implementer-ci / gate"] }
-```
-
-on every run you want gated. The workflow existing is not enough — the context has
-to be in the run policy.
-
-> **Wire it at creation with `--policy-file` (BAPI-754).** There is still no
-> `--required-checks` option, but `setup-epic --policy-file <path>` sends the
-> **complete** run policy on the create that mints the run, so the run is born with
-> `required_checks` already in force. A run created *without* a policy still starts
-> with an **empty** `required_checks` and a `ci` gate that short-circuits to
-> `PASSED` — and because `setup-epic` also approves the plan, making the run
-> `active` and visible to the reconciler within ~30s, there is no comfortable window
-> to fix that afterwards. Supply the policy file up front.
->
-> To change the policy on a run that is already live, re-run with `--policy-file`:
-> an identical policy is a no-op, and a divergent one is **refused** with a redacted
-> diff unless you also pass `--replace-policy` (which applies it as a complete
-> replacement).
-
-> **This is NOT `done_gate_config`.** The per-run `policy_json.required_checks`
-> read by the reconciler `ci` gate is a *different* surface from the supervisor
-> `done_gate_config.required_ci_checks_green` documented under "Supervisor config"
-> below. BAPI-695 wires only the former, per run; it does **not** change
-> `done_gate_config` defaults, repo-default policy, or GitHub branch protection.
-
-**Once gated, expect this behavior:**
-
-- The `ci` gate now waits for `epic-implementer-ci / gate` on the ticket PR's current head.
-  A complete **red** aggregator enters the bounded `ci_fix` remediation path; a
-  **missing or still-running** current-head context stays pending (never a hard
-  fail).
-- A **green from an older head** can never satisfy the gate after a rebase or
-  force-push — the poll is bound to the current head SHA, and the workflow's per-PR
-  concurrency cancels the superseded run so the new head publishes a fresh context.
-- Out-of-scope PRs (forks, `dependabot/*`, non-`feature/BAPI-*`) get an intentional
-  fast green — cost control, **not** proof the suites ran.
-
-For the exact new-run/PATCH procedure (and the **whole-object `policy_json`
-replacement** caution — GET, merge `required_checks` locally, PATCH the whole
-object), and the immutable case-sensitive matching of the context string, see the
-operator runbook, **§4a "Wire the conductor CI required check"**
-([`docs/claude/epic-implementer-v2-operator-runbook.md`](../../docs/claude/epic-implementer-v2-operator-runbook.md)).
-
-## Conductor observability (opt-in via `--conductor`, BAPI-394)
-
-Conductor is **off by default** — without `--conductor` no `BAPI_EPIC_IMPLEMENTER_*` env,
-supervisor tab, or message-relay prompt is produced. With `--conductor`, a run mints
-a single conductor `run_id` and emits one canonical `run.started` event into the
-local conductor ledger (`~/.config/bridge/events.db`), attributing each worker by
-`worker_id`, ticket key, and worktree path, and opens a supervisor peer tab. When
-the selected agent is **Claude Code**, the CLI also injects a conductor lifecycle
-hook into each created worktree's `.claude/settings.local.json` (preserving any
-existing hooks) so the spawned session streams local `run.started` / `run.stopped` /
-`agent.notification` (and, with `BAPI_EPIC_IMPLEMENTER_ENABLE_PRE_TOOL_USE=1`,
-`tool.intent`) events. Per-worker conductor identity is passed only via secret-free
-environment scoped to that one terminal/tab/session — no credentials are ever placed
-in the env, hook command, or run metadata. Override the gate/supervisor labels with
-`BAPI_EPIC_IMPLEMENTER_GATE_NAME` / `BAPI_EPIC_IMPLEMENTER_SUPERVISOR_MODE`. Inspect the stream
-with `epic-implementer doctor`. Observability is best-effort: a conductor failure never
-blocks or aborts a spawn, and `--dry-run` performs no conductor side effects.
-(Epic dispatch always enables conductor internally, independent of this flag.)
-
-When `--conductor` is set, the spawn boundary also injects
-`BRIDGE_MCP_PROFILE=conductor` so each worker registers the 8 conductor/event/
-supervisor MCP tools (a plain `start-tickets` run stays on the default `core`
-profile). See [README → Environment Variables](../README.md#environment-variables).
-
-### Environment-variable names and the legacy-name refusal (BAPI-1190)
-
-Every Epic Implementer environment variable uses the `BAPI_EPIC_IMPLEMENTER_`
-prefix, and the worker Node path is `EPIC_IMPLEMENTER_NODE_PATH`. These replaced
-the old Conductor names by a plain token swap: `CONDUCTOR` became
-`EPIC_IMPLEMENTER` and the rest of the name stayed the same. For example, the old
-run-id variable is now `BAPI_EPIC_IMPLEMENTER_RUN_ID`. There are no aliases and no
-dual reads.
-
-**Old names are refused, not ignored.** If any variable with the old
-`BAPI_CONDUCTOR_` prefix, or the old `CONDUCTOR_NODE_PATH`, is set, these entry
-points refuse to start:
-
-| 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 |
-| `epic-implementer-claude-hook` bin | same stderr diagnostic, **exit `0`**, no ledger event |
-
-The hook is the one exception to the non-zero exit. A hook must never block the
-Claude tool loop, so it stays loud but exits `0`. The two removed `conductor`
-stub bins are not guarded; they already fail with a fixed migration message.
-
-The diagnostic lists **every** offending key, sorted, in one message. Each line
-gives the exact successor, a "retired — remove it" note (the old MCP shadowing
-override), or, for an unknown old name, the generic advice: rename the prefix if
-it is still a current setting, otherwise remove it. It prints **key names only,
-never values**, because these variables can hold secrets. Old names copied from
-frozen records (`docs/BAPI-*.md`, run notes) are refused the same way. Stale
-names usually live in shell profiles, hand-edited executor service units, or CI
-environment configuration.
-
-**Version skew.** A worker environment injected by an **older** published package
-still carries the old names. A **newer** TypeScript process started inside it (for
-example the MCP server launched through `mcp-invoke`) will refuse to start. This
-is intended: it is the loud outcome, not a silent half-configured worker.
-
-- **Remedy:** re-spawn the worker so the launcher and the process it starts run
-  the same package version.
-- **If that does not fix it:** send the MCP package owner the launcher version,
-  the process version, and the offending **key names only** — never their values.
-
-The executor's worker-environment filter rejects both whole prefixes and both
-node-path spellings, so an old ambient name never reaches a worker it spawns.
-
-**No Python guard.** No production Python reads these variables, so they are
-inert there, and no broad Python `BAPI_*` guard is added. They are refused when
-inherited by a TypeScript child or MCP process. The Python dead-man variables
-(`CONDUCTOR_DEAD_MAN_ONLY`, `CONDUCTOR_DEADMAN_*`) are a separate exact-name
-contract owned by BAPI-1231.
-
-## `epic-implementer install-git-hooks` (BAPI-395)
-
-Installs local git hooks that opportunistically emit conductor git/PR/CI events into
-the local ledger:
-
-```
-epic-implementer install-git-hooks [--json]
-```
-
-The installed hooks are **local, unversioned, opportunistic, and bypassable**: they
-live in the worktree's git hooks directory (resolved via
-`git rev-parse --git-common-dir`), insert only a clearly-delimited managed block
-(preserving any existing user hook content), launch the producer **detached in the
-background** so a commit or ref update is never blocked, and tolerate every failure
-(`|| true`). A directory that is not a git worktree, or an existing hook that looks
-binary/unsafe, is left untouched and reported as a **degraded optional capability** —
-never a fatal error. The hooks installed are `post-commit` (emits
-`git.commit_created`) and `reference-transaction` (emits `worktree.changed` for
-committed ref updates).
-
-Missing hooks do **not** prevent PR/CI gate evaluation — `epic-implementer doctor` reads
-hook presence and managed-snippet status **read-only** (a new `git hooks` section /
-`git_hooks` JSON object alongside the ledger report), and the reconciler drives CI
-polling and gate evaluation regardless of whether hooks are installed.
-
-### 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 file lives. 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 package entry
-`<prefix>/lib/node_modules/@bridge_gpt/mcp-server/build/epic-implementer-bin.js`
-(POSIX single-quoted, so spaces and shell metacharacters stay literal) and launches it
-with `node` from PATH. It never embeds npm's `.bin` shim and never pins
-`process.execPath`.
-
-Running the installer through `npx` is allowed only as a front door: it looks up an
-**already installed** persistent global package with a bounded, offline
-`npm root -g` (at install time only) and embeds that package's entry. When no
-qualified persistent install exists, 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 existing hooks byte-for-byte and mode-for-mode unchanged.
-Hooks are optional observability: a refusal is **not** an engine-admission failure and
-not a setup-permission stop.
-
-**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** |
-
-A package-layout change or a Node/native ABI change must be requalified by re-running
-`npm run test:hooks-lifetime` before this table changes.
-
-**Publication.** The installer plans both hooks before writing either. It refuses a
-symlinked, non-regular, unreadable, or binary hook with a per-hook reason and changes
-nothing. Each hook is then written to a same-directory temporary file with its original
-mode plus only the missing execute bits, re-checked against its planned snapshot, and
-renamed atomically over the target. A hook edited in the meantime is left untouched
-(`intervening-edit`). Two renames are not a transaction: if one hook publishes and the
-other does not, the result is `PARTIAL` (exit 1), the published hook is not rolled
-back, and re-running the installer converges to exactly one managed block per hook.
-User content before and after the managed block is preserved.
-
-**Behavior changes to note.** A symlinked hook is refused rather than written
-through; one unsafe hook (symlinked, unreadable, binary, or not a regular file)
-blocks installing both; a source-checkout build is refused as
-`unqualified-runtime`; and on Windows `doctor` always reports `unqualified-runtime`.
-A persistent install older than this change cannot answer the runtime probe and is
-reported `unknown` — upgrade it with `npm i -g @bridge_gpt/mcp-server@latest`.
-
-**Diagnosis.** `epic-implementer doctor` (and `install doctor`) report each hook's
-`state` and `usable` verdict read-only: no npm lookup, no download, no hook rewrite,
-no service start, no ledger write. Its only subprocess is the bounded runtime probe.
-A hook that exists but 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**, never healthy. 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. Doctor reports them as `ephemeral-cache`. To repair:
-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; user content,
-modes, and the local ledger are preserved.
-
-**Upgrades and rollback.** `npm i -g @bridge_gpt/mcp-server@<version>` replaces the
-package in place, so the embedded path is unchanged and hooks keep working **without
-being rewritten**. While the replacement is in progress, or if it is interrupted,
-optional delivery may be temporarily unavailable and doctor reports it as degraded;
-completing the install (or re-running it) restores delivery. To roll back, install the
-previous compatible version the same way, then run `epic-implementer doctor` and, if
-it reports degraded, `epic-implementer install-git-hooks`. Removing the global package
-deliberately is outside the availability guarantee but stays diagnosable (`missing`).
-
-**What is not promised.** Events that occur while hook delivery is unavailable are
-**lost and not replayed**; the ledger is not complete for those intervals, and anyone
-relying on a missed observation must reconcile it from Git itself. Git commits and ref
-updates are never blocked or slowed by an unavailable runtime (the hook is detached and
-ends in `|| true`), and engine admission never depends on hooks. No run-speed
-improvement is claimed. Activating a hook build against a live or shared control plane
-remains a separately authorized operation.
-
-## Supervisor config — where the done gate and auto-merge live
-
-> **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 onto dedicated supervisor endpoints. Setting them via
-> `PUT /jira/config-field/...` returns **HTTP 400 "Invalid config field"** — that
-> rejection is correct, not a bug. Use the endpoints below.
-
-Two scopes exist for each: 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>` (see note below) |
-
-Since BAPI-1288 every project-default write is protected. A write that removes 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`)
-whatever the approval. That is an operator decision; see the account-settings
-operator runbook (`docs/claude/account-settings-operator-runbook.md`).
-
-Swap `…/defaults/` for `…/runs/{epic_key}/…` to scope a setting to one epic. The
-matching `GET` on each returns the effective value, with a `source` of `epic`,
-`project_default`, or `none` (nothing configured — fails closed).
-
-### `done_gate_config`
-
-Defines the done gate. It supports exactly one condition,
-`required_ci_checks_green`:
-
-```json
-{
-  "enabled": true,
-  "conditions": [
-    { "type": "required_ci_checks_green", "required_checks": ["build", "test"] }
-  ]
-}
-```
-
-`gate.met` is emitted (exactly once per `repo + pr_number + head_sha + effective
-config`) only when every listed required check is present, complete, and green for
-the bound PR head SHA. The gate **fails closed**: an unset, disabled (`enabled` not
-strictly `true`), malformed, empty, or unsupported config emits no `gate.met`.
-
-### `auto_merge_enabled` (C6 conditional auto-merge)
-
-When a worker's PR meets the done gate (`gate.met`), the supervisor can autonomously
-merge it — but **only** when the repo has explicitly opted in.
-`auto_merge_enabled` on the supervisor-config endpoint is the opt-in switch. On the
-project default it can no longer be turned on through the API (BAPI-1288); an
-operator sets it, as the note above describes. A per-epic override is unchanged.
-
-**Auto-merge is disabled by default.** Behavior:
-
-- **Disabled / unset / unconfigured → dry-run.** Anything other than an explicit
-  `true` — including a repo with no supervisor config at all (`source: "none"`) —
-  fails **closed**: the supervisor records a `merge.dry_run` event and **no PR is
-  ever merged**.
-- **Enabled → autonomous merge** when the gate is met and the deterministic guards
-  pass.
-- **Kill-switch.** Set `auto_merge_enabled` to `false` to immediately stop
-  autonomous merges. The protected merge endpoint **independently re-enforces** the
-  flag, so even a conductor that calls it cannot merge while the flag is off.
-
-Merge authority is **deterministic code, never an LLM**. The deterministic guards,
-all bound to **PR number + expected head SHA (never a branch name)**:
-
-- the per-repo enablement flag (off → dry-run),
-- the PR is still open,
-- the merge is bound to the PR number plus the expected head SHA — **head-SHA drift
-  between gate evaluation and merge aborts the merge**,
-- required CI checks are **revalidated green immediately before merge**.
-
-Idempotency is crash-safe and race-safe: a TTL lease keyed by the deterministic
-action key `merge:{repo}:{pr}:{head_sha}:{gate}` is claimed before acting, and an
-existing `merge.succeeded` for that key is terminal — the supervisor never
-double-merges across a crash/restart or two racing instances. The conductor never
-holds VCS write credentials: it calls the protected Bridge API endpoint
-`POST /vcs/pull-requests/{pr_number}/merge`, which owns the privileged merge, and
-records the returned `merge.dry_run` / `merge.attempted` / `merge.succeeded` /
-`merge.failed` / `merge.pending_approval` events into the local ledger.
-`merge.failed` is **retryable** (a drifted head SHA produces a new action key);
-`merge.pending_approval` is **nonterminal** — the worker remains active until a human
-redeems the approval token and the server returns `merge.succeeded`.
-**`merge.succeeded` is the only terminal merge event.** The local SQLite conductor
-store uses schema version 5 (BAPI-413) to accommodate the `merge.pending_approval`
-type in the `events.type` CHECK constraint.
-
-**Who performs the write (BAPI-832).** "Never holds VCS write credentials" above
-describes the *credential*, not the *typing*, and it remains true everywhere. Two
-paths now perform the provider write with the operator's local `gh` rather than
-with the GitHub App installation token, because GitHub's merge endpoint requires
-`contents: write` and the Bridge GPT App installation is `contents: read`:
-
-- the executor's `merge` job, via `makeLocalMergeExecutor` — the arrangement
-  BAPI-572 locked in; and
-- the `merge_pull_request` MCP tool, which since BAPI-832 sends
-  `execution: "local"`, receives a non-terminal `approved_for_local_execution`
-  from the route above, merges through that same `conductor/local-merge.ts` seam,
-  and reports the outcome to
-  `POST /vcs/pull-requests/{pr_number}/merge/complete`.
-
-In both, the server still owns every decision — the guards, the lease, and the
-terminal ledger row — and neither path holds a credential of its own; they borrow
-the operator's `gh` session. Mode is `merge_execution` on `epic_supervisor_config`
-(`local` by default, `server` for installations whose App holds
-`contents: write`). A caller that dies mid-merge is recovered by lease expiry, not
-by a new mechanism: the next call re-runs the whole tail, and the provider re-read
-reports `already_merged` if the merge landed.
-
-## Durable execution environment hardening (BAPI-527)
-
-Worker ledger operations are made **reliable again** — this is a robustness fix for
-the worker-facing path, **not** a new primary completion backstop. The done gate and
-supervisor remain the authority; this change only stops the worker's own ledger calls
-from failing.
-
-**The invariant.** Worker-facing ledger operations run through `conductor-bin.js`
-executed **under the captured conductor Node** (`EPIC_IMPLEMENTER_NODE_PATH`). **The worker
-Node must never load `better-sqlite3`.** Dispatch captures the conductor process's
-own Node executable and threads it to each worker as `EPIC_IMPLEMENTER_NODE_PATH`, paired
-with `BAPI_EPIC_IMPLEMENTER_CLI_FILE` (the packaged `conductor-bin.js` path). The
-worker-side boundary (`src/conductor/worker-ledger-cli.ts`) shells out with a fixed
-**list argv** via `execFile` (never `shell: true`, never a command string) and
-passes event JSON over **stdin** (`--data-json-stdin`), so raw payloads/secrets
-never enter the process argument list. Conductor-**owned** processes (the CLI,
-supervisor, and epic runtimes) keep calling `store.ts` directly — they legitimately
-own the native load.
-
-**Fail loud, never fall back.** A missing/invalid `EPIC_IMPLEMENTER_NODE_PATH` or absent
-`BAPI_EPIC_IMPLEMENTER_CLI_FILE` raises the typed `ConductorLedgerSubprocessRuntimeError`,
-surfaced to callers as the `LEDGER_SUBPROCESS_RUNTIME_UNAVAILABLE` (503) envelope
-with a fixed, path-free, secret-free `details: { env_var, reason }` bag
-(`reason ∈ missing | invalid | cli_missing | spawn_failed | malformed_stdout`). The
-boundary **never** falls back to the worker's `process.execPath` — doing so would
-re-introduce the native load into the worker Node, the exact failure this removes.
-`EPIC_IMPLEMENTER_NODE_PATH` is **non-secret operational metadata**: it is inherited from
-the worker shell env injected at the spawn boundary and is **not** persisted into
-`.mcp.json`, which stays intentionally env-free.
-
-**Rejected alternatives.**
-
-- **Local HTTP sidecar** (a long-lived ledger daemon the worker talks to over a
-  port) — rejected: port conflicts, zombie-process lifecycle management, capability-
-  token handling, and a large failure surface, all disproportionate for a
-  file-backed local ledger.
-- **WASM / pure-JS SQLite in the worker** — rejected: it replaces the proven
-  `better-sqlite3` WAL / synchronous-performance behavior and is a poor fit for a
-  database file shared by multiple processes (the conductor Node and any workers).
-
-### Three protective guarantees (operator view)
-
-BAPI-527 adds three independent reliability guarantees. Each is a protective
-default; none changes the interactive (non-conductor) `start-tickets` contract.
-
-1. **Ledger operations are isolated from the worker path.** Worker-facing ledger
-   operations run in a subprocess under `EPIC_IMPLEMENTER_NODE_PATH` (details above), so a
-   Node ABI mismatch degrades a worker convenience, never the whole session.
-
-2. **Dispatch does not alter your branch.** Unattended/epic dispatch is
-   **non-mutating**: it resolves the base with a fetch-only
-   `origin/<base>` lookup and cuts new worktrees from that fetched SHA. It never
-   checks out, fast-forwards (`git merge --ff-only`), force-moves
-   (`git branch --force`), or stashes the operator's live checkout. A **live-source
-   guard** additionally refuses dispatch (or, with an explicit override, warns
-   loudly) when the conductor's base repo path equals the operator's live
-   dev-server checkout:
-   - `BAPI_EPIC_IMPLEMENTER_LIVE_SOURCE_PATH` — the operator's live dev-server checkout
-     path to protect.
-   - `BAPI_EPIC_IMPLEMENTER_ALLOW_LIVE_SOURCE_DISPATCH` — truthy (`1`/`true`/`yes`/`on`)
-     override that downgrades a collision from fatal to a loud warning.
-   The read-only `doctor` command surfaces the guard state
-   (`not-configured` / `safe` / `collision`) without mutating anything.
-
-3. **Parse runs in a separate process.** The post-merge repository re-index runs
-   out-of-process via `asyncio.create_subprocess_exec`, so the FastAPI event loop
-   stays responsive to concurrent dispatch calls while a CPU-bound parse runs. The
-   ticket enters **`parse_pending`** after merge and folds to **`done`** only when
-   `/parse-status` reports terminal success; a permanent parse failure (or the
-   `max_wait_ms` budget being exhausted) folds it to **`blocked`** with a sanitized
-   reason and never silently wedges the epic. Parse status values are `idle`,
-   `queued`, `in_progress`, `succeeded`, and `failed`; terminal failure reasons are
-   bounded and sanitized (no stderr, tracebacks, argv, or secrets).

package/pipelines/idea-to-pr.json

@@ -1,49 +0,0 @@
-{
-  "name": "idea-to-pr",
-  "description": "Drive an idea end-to-end: create ticket(s) (idea-to-ticket), review each ticket (review-ticket fan-out), then hand off to the /start-tickets CLI seam to spawn worktrees.",
-  "variables": [
-    "idea",
-    "auto_approve",
-    "scheduled_at",
-    "max_children",
-    "allow_duplicate",
-    "agent"
-  ],
-  "stages": [
-    {
-      "pipeline_name": "idea-to-ticket",
-      "description": "Convert the idea into one or more Jira tickets.",
-      "variables": {
-        "idea": "{idea}",
-        "max_children": "{max_children}",
-        "allow_duplicate": "{allow_duplicate}",
-        "auto_approve_external": "{auto_approve}"
-      },
-      "outputs": {
-        "child_ticket_keys": "child_ticket_keys",
-        "epic_parent_key": "epic_parent_key",
-        "created_ticket_keys": "created_ticket_keys"
-      }
-    },
-    {
-      "pipeline_name": "review-ticket",
-      "description": "Review each created ticket (one child pipeline run per ticket).",
-      "fan_out_input": "child_ticket_keys",
-      "fan_out_variable": "ticket_key",
-      "variables": {
-        "ticket_key": "{ticket_key}"
-      },
-      "outputs": {
-        "reviewed_ticket_keys": "reviewed_ticket_keys"
-      }
-    },
-    {
-      "pipeline_name": "start-tickets",
-      "description": "Hand off the reviewed tickets to the /start-tickets CLI seam (agent-task; not a server pipeline).",
-      "fan_out_input": "reviewed_ticket_keys",
-      "outputs": {
-        "started_ticket_keys": "started_ticket_keys"
-      }
-    }
-  ]
-}