@bridge_gpt/mcp-server 0.2.69 → 0.2.70

package/docs/epic-implementer/self-hosting.md

@@ -0,0 +1,133 @@
+# Epic Implementer: self-hosting
+
+**Audience:** owners and operators who run their own Bridge API server, or who host epic launches on a durable machine. If you use Bridge's hosted service, you do not need this document. Follow [the getting-started guide](./getting-started.md) instead.
+
+This document holds the material that the first-run path leaves out: the local plane, the composed bring-up, running the server from a source checkout, durable hosts, repository-wide executors, and launch profiles. `drive-epic --help-advanced` prints a short form of the same material.
+
+In every command below, `npx -y @bridge_gpt/mcp-server` is the launcher.
+
+## Prerequisites
+
+The readiness report lists these items only for a self-hosted deployment. Each bullet gives the item's name, its id, what it means, and the fix.
+
+- **Active-run progress** (`server.reconciler-liveness`) — The server's reconciler reports a recent heartbeat for the active run. Fix: Check that the reconciler process is running, then retry.
+- **Database migration** (`server.database-migration-current`) — The server database is at the current migration. Fix: Apply the pending database migrations on your Bridge server, then retry.
+- **Server worker** (`server.worker-present`) — The server's background worker is running. Fix: Start the server's background worker next to the server process.
+- **Single transition authority** (`server.single-transition-authority`) — Exactly one reconciler decides each epic's steps. Fix: Stop the extra reconciler so one remains.
+- **Legacy environment** (`plane.legacy-environment`) — No retired `BAPI_CONDUCTOR_*` environment names are set. Fix: Rename or unset the old names; the check lists each with its new name.
+- **Repository root** (`plane.repository-root`) — The command runs from the Bridge API checkout root (the top folder of your Bridge server source). Fix: Change to that folder and rerun.
+- **Git work tree** (`plane.worktree-presence`) — The current folder is a Git work tree. Fix: Run from inside a Git work tree.
+- **Claude login** (`plane.claude-login`) — Claude Code is signed in on the plane host. Fix: Run `claude` and sign in.
+- **Bridge repository identity** (`plane.repo-identity`) — The plane knows which Bridge repository it serves. Fix: Pass `--repo <name>` or set `BAPI_REPO_NAME`.
+- **Bridge API credential** (`plane.bridge-credentials`) — A Bridge API key is stored for the plane. Fix: Run `npx -y @bridge_gpt/mcp-server install` against the plane's server.
+- **Bridge credential file permissions** (`plane.credential-permissions`) — The stored credential file is readable only by you. Fix: Run `chmod 600 ~/.config/bridge/credentials.json`.
+- **Executor build freshness** (`plane.executor-build`) — The executor build is current with the source. Fix: Run `cd mcp_server && npm run build`.
+- **Runtime re-exec entrypoint** (`plane.runtime-entrypoint`) — The runtime can re-launch itself from the built entrypoint. Fix: Build `mcp_server` and rerun.
+- **Local server port** (`plane.server-port`) — The local plane's server port is free or already held by this repository's plane. Fix: Stop the other listener or choose another port with `BAPI_PLANE_PORT`.
+- **Database migration head** (`plane.alembic-head`) — The local database is at the migration head. Fix: Apply the pending migrations, then rerun.
+- **Existing plane** (`plane.existing-plane`) — No other plane for a different repository is running. Fix: Stop it with `plane down` from its checkout.
+- **Executor provisioning** (`conductor.install-section-executor-provisioning`) — A durable executor service is provisioned (only for durable hosts). Fix: Run `npx -y @bridge_gpt/mcp-server install conductor --executor-id <id> --repo-wide`.
+- **Executor service state** (`conductor.install-section-executor-service-state`) — The durable executor service is running. Fix: Start the service unit that `executor install-service` generated.
+- **Launch evidence: actor handshake** (`server.admission-durable-actor`) — Launch check: the durable host's actor handshake completed. Fix: Start the host's repository-wide executor, then launch again.
+- **Launch evidence: database migration** (`server.admission-migration-head`) — Launch check: the server database is at the migration head. Fix: Apply the pending migrations, then launch again.
+
+## The local plane
+
+A plane is the whole local stack in one command: the Bridge API server, the reconciler worker, the dead-man observer, and executor lanes scoped to one run. `plane up`, `plane status`, and `plane down` manage it. It needs a Bridge API **source checkout**: `plane up` runs from the checkout's top folder, and its executor lanes run from that checkout's `mcp_server/build/index.js`, never from npx.
+
+`drive-epic` starts or attaches to a plane by itself when `--plan-file` is given and `BAPI_BASE_URL` names the local plane endpoint (`127.0.0.1`, on the port in `BAPI_PLANE_PORT` or the default). It handles the port one of three ways and never asks you to choose:
+
+- **Cold start.** Nothing listens on the port. `drive-epic` brings the plane up, then creates the run.
+- **Attach.** This repository's own healthy plane is there. `drive-epic` creates the run against that plane and starts no second server or reconciler.
+- **Refusal.** Anything else holds the port: another listener, a manifest for a different repository, an unreadable manifest, or a plane that cannot take a run. `drive-epic` prints one named reason and starts nothing.
+
+**One epic per plane, for its lanes.** A plane's executor lanes serve the one run it is bound to. A second run attaches to the same plane's reconciler and gets its own run-scoped executor. A plane whose bound run cannot be read is refused as `plane-already-bound`. Two planes on one database are not supported.
+
+`plane status` reports the lifecycle phase (control plane starting or ready, lanes starting or ready, observer active, plane ready) and the epic run the plane is bound to. `plane down` handles every intermediate phase: it stops the bound run first, then signals the recorded process group.
+
+### Claim scope is required
+
+Every executor lane `plane up` starts needs an explicit claim scope:
+
+```bash
+npx -y @bridge_gpt/mcp-server plane up --epic-run-id <run-id>   # repeatable
+npx -y @bridge_gpt/mcp-server plane up --repo-wide              # or repository-wide
+```
+
+The two are mutually exclusive. Asked to start lanes with neither, `plane up` refuses before it spawns anything, in the executor's own words.
+
+After its migration-head check, `plane up` also checks that the launch-critical schema objects exist, because a migration stamp is not proof that a migration's DDL was applied. A **proven-missing** object is a refusal before anything is claimed or spawned ("Local schema incompatible", with the applied stamp and the missing objects). A check that **could not run** is only a warning ("Schema compatibility could not be verified"), and startup continues. Repair with a reviewed, forward-only migration, or rebuild the local database only with the owner's explicit consent. Never stamp the migration table by hand or downgrade.
+
+### Freshness checks
+
+Before a launch creates a run on this machine's plane, `drive-epic` checks that the plane's pinned snapshot is not behind `origin/main` and that the database is at the migration head. A confirmed problem refuses before any setup or run creation. Evidence it cannot read is a warning. Attaching to a run that already exists only warns. `--allow-stale-plane` bypasses only those two refusals for one invocation. It repairs nothing and does not bypass readiness, authentication, ownership, or admission.
+
+## The composed two-phase bring-up
+
+With `--plan-file` on a repository whose readiness is missing only the runtime facts, one `drive-epic` invocation runs, in order:
+
+1. the **control plane** (Bridge API server and reconciler, each gated on its own readiness);
+2. `setup-epic`, to create and approve the run;
+3. **executor lanes scoped to that run**, with `--epic-run-id <run>`;
+4. the **dead-man observer**, last;
+5. the ready banner.
+
+The order is forced: an executor lane must carry an explicit claim scope, and the run it is scoped to does not exist until the server is up and `setup-epic` has run. If `setup-epic` fails, the control plane is left running and no executor lane is spawned. If the lanes fail to become ready, the control plane and the committed run are left intact and the observer is not started. Nothing is rolled back, because a local process that failed to start says nothing about whether the run is valid.
+
+A report that is missing supervisor setup, supervisor configuration, GitHub App credentials, or an unattended prerequisite is **not** started. Those are owner-owned, and `drive-epic` exits with that one named reason.
+
+"Plane ready" reports processes, not dispatchability: if the run cuts an epic branch, the reconciler holds ticket dispatch until that branch's index scope finishes preparing.
+
+## Running the server yourself
+
+Skip this section if you use the hosted service.
+
+Run the Bridge API server from a source checkout. The checkout's top folder holds the server entry point, the background worker, and the migration config. Build the executor from the same checkout, so the server and the executor come from one commit:
+
+```bash
+cd mcp_server && npm run build
+node mcp_server/build/index.js executor --repo <name> --epic-run-id <id>
+```
+
+Do not use `npx` against a local server. The published package often lags the server's source, and a newer server can send a prompt the older executor rejects.
+
+Upgrade the server before the package. An older server simply yields a "capability not verified" warning for newer readiness rows.
+
+## Executors and durable hosts
+
+`drive-epic` starts a run-scoped executor for every run, from the launching checkout's Git top level. It claims only that run's jobs, logs to `.bridge/executors/<run>.log`, and exits when the run is done. A durable launch profile starts none: it requires a fresh repository-wide executor instead.
+
+Start an executor by hand only for a durable host or a manual recovery:
+
+```bash
+npx -y @bridge_gpt/mcp-server executor --repo <name> --epic-run-id <run-id> --exit-when-run-terminal
+npx -y @bridge_gpt/mcp-server executor --repo <name> --repo-wide    # every run in the repo
+```
+
+An executor needs exactly one claim scope, or it refuses to start. It also needs `--base-url` or `BAPI_BASE_URL`: it has no production fallback.
+
+### Repository-wide executors
+
+`--repo-wide` claims jobs for every run in the repository. A durable host uses it, so the host survives from one run to the next:
+
+```bash
+npx -y @bridge_gpt/mcp-server install conductor --executor-id <id> --repo-wide
+```
+
+Setup writes a launchd (macOS) or systemd (Linux) user unit that starts the executor with the claim scope you chose. Supplying `--executor-id` is what opts in to this phase, and exactly one of `--epic-run-id` or `--repo-wide` is set with it. `executor install-service` generates the same unit without the guided consent. Writing the unit and starting the service are separate consents, and the server's own observation, not the local process list, decides whether the executor is ready.
+
+## Launch profiles
+
+A launch profile saves a reusable, host-local launch target, so a durable host launches the same way every time.
+
+```bash
+npx -y @bridge_gpt/mcp-server install conductor --launch-profile <name> --base-url <url>
+```
+
+Setup records an explicit target (there is no production default), a confirmed credential binding, and verified consent, notification, and actor prerequisites. Only when all of them hold does it save the profile and print the one launch command that selects it. `--execution-mode local|durable` chooses the runtime (durable when `--executor-id` is given, otherwise local), and `--policy-file <path>` names the run policy the profile references.
+
+To launch with a profile, pass `--launch-profile <name>` to `drive-epic`, or set `BAPI_EPIC_LAUNCH_PROFILE`. The flag takes precedence. With a profile, `--base-url` must agree with it; an override never rebinds a profile. For an environment-selected profile, `BAPI_BASE_URL` remains the general CLI endpoint and does not conflict with the epic launch target. With none of the three, `drive-epic` targets production and uses the stored `bapi:<repo>` key when there is one. A stored key approved for a different endpoint is never sent.
+
+## A live run with no plan
+
+If the epic already has a live run and no plan was supplied or found, `drive-epic` creates nothing. It makes sure that run has an executor: it reuses a verified live one and never starts a second, starts one when the old one is gone, starts none for a durable launch profile with a confirmed repo-wide executor, and starts none when this checkout's plane is bound to that run. An epic with several active runs (`live-run-ambiguous`) or a run that cannot be read (`live-run-unknown`) is refused by name.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge_gpt/mcp-server",
-  "version": "0.2.69",
+  "version": "0.2.70",
   "description": "Bridge API MCP server — exposes Jira endpoints as MCP tools for Claude Code agents",
   "license": "MIT",
   "type": "module",
@@ -26,7 +26,7 @@
   "//test": "The `test` script delegates to the bounded launcher (scripts/run-unit-tests.js → src/run-unit-tests-launcher.ts, BAPI-683), which discovers build/*.test.js at runtime and spawns them in size-bounded batches so the argv never exceeds Windows' ~8191-char command-line limit. Two determinism rules from the pre-launcher script are preserved INSIDE the launcher: (1) multi-file batches run WITHOUT --test-force-exit, because that flag makes node:test exit before aggregating per-subprocess summaries and the tally becomes nondeterministic (failures still surface and still set exit 1, but the count cannot be trusted as a completeness signal); (2) build/secret-safety.test.js leaks a handle that holds the event loop ~60s after its tests finish (they run in ~147ms), so the launcher quarantines it into its own single-file --test-force-exit invocation (FORCE_EXIT_QUARANTINE in src/run-unit-tests-launcher.ts) where the tally stays exact. Do NOT add --test-force-exit to batched invocations, and do NOT remove the quarantine, until the underlying handle leak is fixed.",
   "//version": "BAPI-930: fired by `npm version <level>` AFTER npm rewrites package.json's version field, so the bumped version, repinned README and version-rendered command mirrors land in the SAME commit. A bump performed by hand-editing package.json instead of running `npm version` bypasses this hook entirely and must repin manually via `node scripts/sync-readme-host-examples.js` and `node ../commands/build.js` — the `--check` wired into `build` below is the backstop that catches that case.",
   "scripts": {
-    "build": "node scripts/bundle-version.js && node scripts/sync-readme-host-examples.js --check && node scripts/validate-packaged-command-references.js && node scripts/bundle-readme.js && node scripts/bundle-pipelines.js && node scripts/bundle-commands.js && node scripts/bundle-agents.js && node scripts/bundle-docs.js && node scripts/bundle-agent-guidance.js && tsc && node scripts/sync-readme-merge-workflow.js --check && node scripts/sync-agent-mirrors.js && node scripts/bundle-esbuild.js",
+    "build": "node scripts/generate-readiness-prerequisites.mjs && node scripts/bundle-version.js && node scripts/sync-readme-host-examples.js --check && node scripts/validate-packaged-command-references.js && node scripts/bundle-readme.js && node scripts/bundle-pipelines.js && node scripts/bundle-commands.js && node scripts/bundle-agents.js && node scripts/bundle-docs.js && node scripts/bundle-agent-guidance.js && tsc && node scripts/sync-readme-merge-workflow.js --check && node scripts/sync-agent-mirrors.js && node scripts/bundle-esbuild.js",
     "version": "node scripts/sync-readme-host-examples.js --write && node ../commands/build.js && git add -- ../.claude/commands ../.cursor/commands .claude/commands && git add -- README.md package.json package-lock.json && git commit -m \"chore(mcp-server): release $npm_package_version\" && git tag \"mcp-server/v$npm_package_version\"",
     "check:version-generated": "node scripts/bundle-version.js && node scripts/check-version-generated.js",
     "assert:release-identity": "node scripts/assert-release-identity.js",
@@ -36,7 +36,7 @@
     "test:normal": "node scripts/run-unit-tests.js normal",
     "test:module-mocks": "node scripts/run-unit-tests.js module-mocks",
     "test:integration": "node scripts/run-integration-tests.js",
-    "test:smoke": "node --test build/integration/packaged-cli-smoke.test.js",
+    "test:smoke": "node --test build/integration/packaged-cli-smoke.test.js && node scripts/check-package-contents.js",
     "test:hooks-lifetime": "node --test build/integration/packaged-git-hooks-lifetime.test.js",
     "canary:agent-capabilities": "npm run build && node scripts/agent-capabilities-canary.mjs",
     "prepublishOnly": "node scripts/bundle-assets.js && npm run build && node scripts/verify-shebang.cjs && npm run assert:release-identity"

package/pipelines/idea-to-ticket.json

@@ -77,7 +77,7 @@
     {
       "type": "agent_task",
       "instruction_file": "upload-and-track.md",
-      "description": "Upload to Jira and track the new ticket(s) idempotently"
+      "description": "Create label-free tickets from unchanged slim_description, persist confirmed keys immediately, reuse upload state on resume, and track the tickets"
     }
   ]
 }

package/pipelines/implement-ticket.json

@@ -1,6 +1,6 @@
 {
   "name": "implement-ticket",
-  "description": "Initial feature workflow: generate a plan, produce artifacts, checkpoint to origin, verify, commit, open a PR, close post-PR gaps, and monitor CI. Re-entry of this initial workflow may reuse a fresh plan, but remaining-work corrections and continuations use versioned focused intent on the retained branch and never re-enter this recipe.",
+  "description": "Initial feature workflow: generate a plan, register the delivery binding and produce artifacts, checkpoint to origin, verify, commit, ask the server to publish (an ordinary or draft PR, or a held blocked checkpoint), close accepted post-PR gaps, and monitor CI. Finishing every recipe step is not delivery completion: the server readiness outcome decides that, and the final report states it. Re-entry of this initial workflow may reuse a fresh plan, but remaining-work corrections and continuations use versioned focused intent on the retained branch and never re-enter this recipe.",
   "variables": ["ticket_key", "docs_dir", "provider", "verification_scope"],
   "steps": [
     {
@@ -23,33 +23,33 @@
     {
       "type": "agent_task",
       "instruction_file": "execute-plan.md",
-      "description": "Produce the plan's implementation artifacts. Under the Epic Implementer, a minor requirement that cannot be met unattended gets a guarded workaround plus a record at .bridge/epic-workarounds/<TICKET>.md, committed on the ticket branch with git add -f; a core requirement is never worked around and is left unfinished so the run parks the ticket."
+      "description": "Produce the plan's implementation artifacts. Before any production edit, get_phase_context registers or recovers the execution's delivery binding. Unresolved obligations stay escalated, never dropped. Before dependent work, a targeted prerequisite preflight checks only the capabilities and platform facts the plan explicitly requires, records each as available, verified_absent, or uninvestigated, and escalates the affected steps while preparation and independent owned work still proceed. Under the Epic Implementer, a minor requirement that cannot be met unattended gets a guarded workaround plus a record at .bridge/epic-workarounds/<TICKET>.md, committed on the ticket branch with git add -f; a core requirement is never worked around and is left unfinished so the run parks the ticket. An unattended workaround never counts an unmet mandatory prerequisite as satisfied: the dependent step stays escalated."
     },
     {
       "type": "agent_task",
       "instruction_file": "checkpoint-work.md",
-      "description": "Checkpoint produced work to origin before verification begins"
+      "description": "Checkpoint produced work to origin before verification begins. Any blocked exit later in the run first pushes and proves its head on origin the same way."
     },
     {
       "type": "agent_task",
       "instruction_file": "execute-plan-verification.md",
-      "description": "Execute the plan's remaining review, test, and rendered-UI steps before the PR opens"
+      "description": "Execute the plan's remaining review, test, and rendered-UI steps before the PR opens, record them with the server, and report its readiness outcome. Only a check that genuinely needs an open PR carries prDependency; a missing local capability stays a pre-PR blocker."
     },
     {
       "type": "agent_task",
       "instruction_file": "commit-and-push.md",
-      "description": "Stage, commit, and push changes",
+      "description": "Stage, commit, and push changes. A new commit after verification moves the head, so verification is re-run and re-recorded before the PR step.",
       "requires_approval": true
     },
     {
       "type": "agent_task",
       "instruction_file": "create-pr.md",
-      "description": "Create a pull request with a title derived from the commit subject"
+      "description": "Check server delivery readiness, then create a pull request with a title derived from the commit subject. A delivery hold is a supported blocked-checkpoint exit: the branch and head are preserved and the run ends there."
     },
     {
       "type": "agent_task",
       "instruction_file": "verify-plan.md",
-      "description": "Close post-PR plan gaps and push any correction"
+      "description": "Close post-PR plan gaps, including the accepted PR-dependent steps this phase owns, and push any correction"
     },
     {
       "type": "mcp_call",
@@ -72,7 +72,7 @@
       "id": "monitor-ci-checks",
       "type": "agent_task",
       "instruction_file": "monitor-ci-checks.md",
-      "description": "Monitor CI checks and report results"
+      "description": "Monitor CI checks, record post-PR resolutions, and report results with the server readiness outcome. CI green is not delivery readiness, and neither is a merge."
     }
   ]
 }

package/pipelines/review-ticket.json

@@ -55,7 +55,7 @@
     {
       "type": "agent_task",
       "instruction_file": "capture-review-decisions.md",
-      "description": "Generate HTML decision page, capture user decisions, and interpretively rewrite clarifying questions and critique docs"
+      "description": "Generate HTML decision page, capture user decisions, and interpretively rewrite clarifying questions and critique docs. BAPI-1428: for an epic-aware review this step consumes the evaluated epic-contract resolution block; a recorded mandatory incompatibility ends this step with a not-finalized report instead of a terminal capture, which is an ordinary outcome, not a failure, so the cleanup step below still runs"
     },
     {
       "type": "mcp_call",
@@ -65,7 +65,7 @@
         "action": "cleanup",
         "fresh_base_root": "<the fresh_base_root path returned by the earlier fresh_base materialize step's result>"
       },
-      "description": "Remove the temp workspace created by the earlier fresh_base materialize step. fresh_base_root is a RUNTIME value, not a static recipe variable: call this tool with the actual path string returned by that step's result, not the placeholder text shown in params above.",
+      "description": "Remove the temp workspace created by the earlier fresh_base materialize step. Runs after normal completion and after a not-finalized epic-contract incompatibility alike; resumed analysis that needs code again rematerializes through the ordinary fresh_base materialize step. fresh_base_root is a RUNTIME value, not a static recipe variable: call this tool with the actual path string returned by that step's result, not the placeholder text shown in params above.",
       "on_error": "warn_and_continue"
     }
   ]