@bridge_gpt/mcp-server 0.2.46 → 0.2.48

package/README.md

@@ -351,7 +351,7 @@ later boot.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.45", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.47", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -373,7 +373,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.45", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.47", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -395,7 +395,7 @@ later boot.
     "bridge": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.45", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.47", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -420,7 +420,7 @@ you select `copilot-cli`; the shape below is what it produces.
     "bridge": {
       "type": "local",
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.45", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.47", "serve"],
       "tools": ["*"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
@@ -444,7 +444,7 @@ Windsurf only supports global MCP configuration.
   "mcpServers": {
     "bridge": {
       "command": "npx",
-      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.45", "serve"],
+      "args": ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.47", "serve"],
       "env": {
         "BAPI_BASE_URL": "https://bridgegpt-api.com",
         "BAPI_REPO_NAME": "your-repo",
@@ -463,7 +463,7 @@ Windsurf only supports global MCP configuration.
 ```toml
 [mcp_servers.bridge]
 command = "npx"
-args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.45", "serve"]
+args = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.47", "serve"]
 
 [mcp_servers.bridge.env]
 BAPI_BASE_URL = "https://bridgegpt-api.com"
@@ -617,54 +617,24 @@ Good to know, but not needed every day.
 - **How to use it:** `/plan-ticket BAPI-123`
 - **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check the plan with a second provider.
 
-**3. Clarify Ticket**
-- **What it does:** Generates clarifying questions for a ticket, or debugging guidance when the ticket is a bug.
-- **When it's useful:** (Refinement) When a ticket feels under-specified and you want the open questions made explicit.
-- **How to use it:** `/clarify-ticket BAPI-123`
-- **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
-
-**4. Critique Ticket**
-- **What it does:** Critiques a ticket against your project's standards and lists the deviations and improvements it found.
-- **When it's useful:** (Refinement) When you want a quality gate on a ticket before anyone works it.
-- **How to use it:** `/critique-ticket BAPI-123`
-- **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
-
-**5. Create Doc**
+**3. Create Doc**
 - **What it does:** Generates a design document for a ticket — a technical design document, a functional spec, or a product requirements document.
 - **When it's useful:** (Architecture | Refinement) When a ticket needs a fuller design write-up before planning or implementation, in the shape that fits your audience.
 - **How to use it:** `/create-doc BAPI-123 --doc-type tdd` (or `fsd` / `prd`)
 - **Flags:** `--doc-type tdd|fsd|prd` which document to generate (required) · `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
 
-**6. Second Opinion**
+**4. Second Opinion**
 - **What it does:** Gets an immediate critique of any text from a different model family, without saving an artifact.
 - **When it's useful:** (Architecture | Refinement | Implementation) Any time you want a quick sanity check on a plan, draft, or decision from a fresh perspective.
 - **How to use it:** Ask your agent — "Get a second opinion from Gemini on whether the BAPI-123 plan's migration step is safe to run against production."
 - **Flags:** Pick the provider (anthropic / openai / gemini) and the tier (cheap / basic / premium).
 
-**7. Generate Image**
+**5. Generate Image**
 - **What it does:** Generates an image from a text prompt using a provider image model, spending provider credits on every call.
 - **When it's useful:** (Architecture | Refinement) When you want a quick visual — a UI mockup, diagram, or illustration — to anchor a design discussion or attach to a ticket.
 - **How to use it:** Ask your agent — "Generate an image of a dashboard showing SOC2 evidence freshness as a traffic-light grid."
 - **Flags:** `provider` openai (`gpt-image-2`) / gemini (Imagen, which adds an invisible SynthID watermark) · `quality` low (default, cheapest) / medium / high · `size` 1024x1024 / 1024x1536 / 1536x1024. The image is saved to `BAPI_DOCS_DIR/images/` and also returned inline.
 
-**8. Request PRD**
-- **What it does:** Generates a product requirements document for a ticket covering the problem, the goals, and the success metrics.
-- **When it's useful:** (Architecture | Refinement) When a piece of work needs its problem, goals, and success metrics written down before anyone designs a solution.
-- **How to use it:** `/create-doc BAPI-123 --doc-type prd`
-- **Flags:** `--provider <name>` choose the model provider · `--second-opinion <provider>` cross-check with a second provider.
-
-**9. Full Automation**
-- **What it does:** Drives the whole chain from a raw idea through tickets and reviews to implementation sessions.
-- **When it's useful:** (Automation) When you want to go from a raw idea to in-progress implementation with minimal hands-on steps.
-- **How to use it:** `/full-automation <idea>` (command only — it creates tickets, spawns worktrees, and carries scheduling flags free text cannot).
-- **Flags:** `--require-approval` re-enable the approval gates; the chain runs end to end by default · `--max-children <n>` cap how many child tickets an epic decomposes into.
-
-**10. Update Ticket Description**
-- **What it does:** Rewrites a ticket's description with AI, using the ticket's own content and its reference material. A rewrite that changes more than 60% of the description is held for review instead of applied.
-- **When it's useful:** (Refinement) When a ticket has accumulated comments, attachments, or links and its description no longer reflects them.
-- **How to use it:** Ask your agent — "Update the description for BAPI-123."
-- **Flags:** None. Poll the ticket's state for the outcome; if the update was held for review, read the proposal instead of applying it blind.
-
 ### Now and then
 
 Useful once in a while.
@@ -682,10 +652,10 @@ Useful once in a while.
 - **Flags:** None.
 
 **3. Get Ticket**
-- **What it does:** Retrieves the full details of a ticket, including its summary, status, and description.
+- **What it does:** Retrieves the full details of a ticket, including its summary, status, and description, and optionally the model tier its difficulty routes to.
 - **When it's useful:** (Refinement | Implementation) Any time you want the agent to read a ticket before acting on it.
 - **How to use it:** Ask your agent — "Pull up BAPI-123 and show me its description, status, and acceptance criteria."
-- **Flags:** None.
+- **Flags:** `include_model_tier` adds the model tier the ticket's difficulty routes to; leave it off for an ordinary read.
 
 **4. Search Tickets**
 - **What it does:** Searches across the tickets in your project.
@@ -711,13 +681,7 @@ Useful once in a while.
 - **How to use it:** Ask your agent — "Download the design mockups attached to BAPI-123 into my docs folder," or "Attach build-log.txt to BAPI-123."
 - **Flags:** Choose the direction (download from the ticket, or upload to it) and, for a download, where the files should land.
 
-**8. Estimate Ticket**
-- **What it does:** Estimates the development effort for one ticket. Use Estimate Epic instead for a whole epic or a named group of tickets.
-- **When it's useful:** (Refinement) When you need a size for a single ticket before committing to it.
-- **How to use it:** Ask your agent — "Estimate BAPI-123."
-- **Flags:** Ask for a fresh estimate to regenerate rather than reuse a stored one.
-
-**9. Estimate Epic**
+**8. Estimate Epic**
 - **What it does:** Estimates an epic, or an explicit group of tickets you name.
 - **When it's useful:** (Architecture | Refinement) When you need a sizing pass across an epic, or across a set of tickets you name explicitly.
 - **How to use it:** `/estimate-epic BAPI-123`
@@ -799,14 +763,10 @@ step and no server call; the full rationale and the closed exception list ship a
 
 ### Operational commands
 
-Workflow commands you'll reach for during implementation and CI, beyond the tiers above:
+Repository and ticket housekeeping commands, beyond the tiers above. Implementation, commit/push, PR creation, and CI monitoring are steps of the `implement-ticket` recipe rather than standalone commands:
 
 | Command | What it does |
 |---|---|
-| `/code-ticket PROJ-123` | Download the implementation plan and questions, then execute the plan inline |
-| `/commit-ticket PROJ-123` | Stage, commit, and push changes; transition Jira status; post a smoke-test comment |
-| `/create-pr PROJ-123` | Resolve the base branch and open a pull request for the ticket's branch (run after `/commit-ticket`) |
-| `/check-ci PROJ-123` | Monitor CI checks for the current branch, triage failures, apply fixes, and report results |
 | `/parse-repository` | Queue a background job to index the repository for Bridge AI agents |
 | `/check-parse-status` | Check whether a background repository parse job is still running |
 | `/scan-tickets` | Sync recently-updated Jira tickets and backfill workflow timestamps |
@@ -817,15 +777,15 @@ Workflow commands you'll reach for during implementation and CI, beyond the tier
 
 Behind-the-scenes capabilities an agent gains from the MCP tools — mostly invoked automatically by the commands above, rarely requested by name:
 
-- **Ship a PR end-to-end:** commit & push, open a pull request, transition the Jira status, and discover/poll CI checks (powers `commit-ticket`, `create-pr`, `check-ci`, `implement-ticket`).
-- **Architecture plan** for a ticket (design-level guidance, separate from the implementation plan).
-- **Index the codebase** so Bridge's agents can reason about it: queue/parse the repo, check parse status, regenerate the directory map.
+- **Ship a PR end-to-end:** commit & push, open a pull request, transition the Jira status, and discover/poll CI checks — the commit-and-push, PR-creation, and CI-monitoring steps of the `implement-ticket` recipe, driven by its bundled instruction assets.
+- **Design documents** for a ticket (TDD / FSD / PRD, generated and retrieved through `create_doc` / `get_doc`).
+- **Index the codebase** so Bridge's agents can reason about it: queue/parse the repo and check parse status (`parse_repository`), regenerate the directory map.
 - **Read & tune project config/standards:** list/read/update config fields, fetch project standards, and the per-topic `learn-*` commands that populate them.
 - **Ticket lifecycle bookkeeping:** track tickets and backfill workflow-state timestamps (`scan-tickets`), search across tickets, read comments, list attachments.
-- **Pipeline machinery:** list/inspect pipeline recipes, run/resume/list/delete pipeline runs (the engine under the orchestration commands), and resume a full-automation chain that stopped at an approval gate or was interrupted.
+- **Pipeline machinery:** fetch a resolved pipeline recipe (the step list behind the orchestration commands) and execute its steps agent-side.
 - **Decision page** generation for capturing human review decisions as structured data.
-- **Connectivity & identity checks:** ping Bridge, check your role, resolve the local docs directory.
-- **Retrieve any generated artifact** (`get_*` for plans, critiques, questions, councils, research, architecture) without regenerating it.
+- **Connectivity check:** ping Bridge to confirm the API key and repository resolve.
+- **Retrieve any generated artifact** (`get_*` for plans, critiques, questions, councils, research, design docs) without regenerating it.
 - **Tiered-section execution telemetry** recording (internal measurement).
 
 ## Salesforce B2C Commerce (SFCC) Tools
@@ -841,7 +801,7 @@ For a step-by-step OCAPI client setup guide (including the Business Manager perm
 <details>
 <summary><strong>Setup</strong></summary>
 
-The two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always available. The read tools, the write tools, and `sfcc_log_query` must be enabled with a profile (step 3). Changing `BRIDGE_MCP_PROFILE` requires an MCP client restart.
+Every SFCC tool must be enabled with a profile (step 3) — including the two diagnostics, `sfcc_setup_status` and `check_permissions`, which belong to the `sfcc` profile. A session on the default `core` profile registers no SFCC tool at all. Changing `BRIDGE_MCP_PROFILE` requires an MCP client restart.
 
 **Prerequisites:** a running SFCC **sandbox** and its hostname, plus an Account Manager API client (`client-id` + `client-secret`).
 
@@ -877,7 +837,7 @@ Because tier 2 outranks tier 3, a stale `SFCC_HOSTNAME` left in the environment
 
 `sfcc` gives the eight read tools plus `sfcc_log_query`. For the nine destructive write tools as well, use `"sfcc,sfcc-write"`; `full` expands to every group and is therefore write-capable. Without any of these, only the diagnostic tools are registered.
 
-**4. Verify and grant OCAPI access.** Ask your agent to run `sfcc_setup_status` (expect all checks ✓), then `check_permissions`. If it reports HTTP 401/403, it prints the exact OCAPI Settings JSON to paste in Business Manager (**Administration → Site Development → Open Commerce API Settings → Data API** tab); save it there and re-run. Restart the MCP client after any credential or env change — a running session does not pick them up.
+**4. Verify and grant OCAPI access.** With `sfcc` selected in step 3 (both diagnostics live in that profile), ask your agent to run `sfcc_setup_status` (expect all checks ✓), then `check_permissions`. If it reports HTTP 401/403, it prints the exact OCAPI Settings JSON to paste in Business Manager (**Administration → Site Development → Open Commerce API Settings → Data API** tab); save it there and re-run. Restart the MCP client after any credential or env change — a running session does not pick them up.
 
 Read what it prints before pasting it. The output is **two labelled blocks**, and they are not equivalent:
 
@@ -926,11 +886,24 @@ domain with no suffix that separates them.
 
 | `BRIDGE_MCP_PROFILE` | SFCC tools registered |
 |---|---|
-| unset / `core` | `sfcc_setup_status`, `check_permissions` only |
-| `sfcc` | the above + 8 OCAPI read tools + `sfcc_log_query` |
-| `sfcc-write` | the above diagnostics + the 9 destructive write tools |
+| unset / `core` | none |
+| `estimation` | none — this group adds only `estimate_epic`, which is not an SFCC tool |
+| `sfcc` | `sfcc_setup_status`, `check_permissions`, the 8 OCAPI read tools, and `sfcc_log_query` |
+| `sfcc-write` | the 9 destructive write tools **only** — it does not imply `sfcc`, so neither diagnostic and no read tool is registered |
 | `sfcc,sfcc-write` | all 20 |
-| `full` | all 20 — `full` includes `sfcc-write` and is therefore write-capable |
+| `full` | all 20 — `full` includes `sfcc-write` and is therefore write-capable, and it also includes `estimation` |
+
+**`check_permissions` needs `sfcc`, even when you are diagnosing writes.** It is
+the tool that prints the mutation-grant OCAPI Settings JSON on a 401/403, but it
+is registered by the `sfcc` group, not `sfcc-write`. An `sfcc-write`-only session
+therefore cannot run it. Use `BRIDGE_MCP_PROFILE=sfcc,sfcc-write` whenever you
+need to diagnose write grants.
+
+**Diagnostics moved into `sfcc`.** `sfcc_setup_status` and `check_permissions`
+used to register unconditionally, on every session including non-SFCC ones. They
+no longer do. The accepted consequence is that a session without `sfcc` can no
+longer ask the server why SFCC tools are missing — run `npx -y @bridge_gpt/mcp-server doctor`
+for that instead, which reports the resolved profile without needing any tool.
 
 **Migration.** Enabling `sfcc` used to register the nine write tools as well. It
 no longer does. If you were relying on SFCC writes through
@@ -939,13 +912,13 @@ Users of `BRIDGE_MCP_PROFILE=full` keep write access and need no change.
 
 ### Tools
 
-Twenty tools in total: two always-on diagnostics, the `sfcc` profile's **read-only** surface (eight OCAPI reads plus `sfcc_log_query`), and the nine destructive writes that only the separate `sfcc-write` profile registers — see [Read and write profiles](#read-and-write-profiles). Every one of them is bounded to a developer sandbox by the same invocation-time check. All twenty are enumerated below.
+Twenty tools in total, none of them registered unconditionally: the `sfcc` profile's **read-only** surface (the two diagnostics, eight OCAPI reads, and `sfcc_log_query`), plus the nine destructive writes that only the separate `sfcc-write` profile registers — see [Read and write profiles](#read-and-write-profiles). Every one of them is bounded to a developer sandbox by the same invocation-time check. All twenty are enumerated below.
 
 An oversized response is saved in full to `BAPI_DOCS_DIR/sfcc/` and replaced by a parseable JSON descriptor — `truncated: true`, the `saved_path` it was written to, and the `page` metadata (`returned`, `total` when OCAPI supplied one, `has_more`) — so the collection metadata survives even though the data itself is on disk. If that save fails, the complete payload is returned inline instead, still as parseable JSON.
 
 Attribute-definition reads and writes can return an attribute's `default_value` at `projection: "full"`, and Bridge withholds it — every key is preserved except that one, whose value becomes `[REDACTED_BY_BRIDGE]` — from the inline response, the saved file, and a successful write echo alike. Attribute defaults are intentionally unavailable through this MCP surface; Business Manager is the supported path to read one.
 
-**Diagnostics** (always available, no profile needed)
+**Diagnostics** (registered by the `sfcc` profile)
 - `sfcc_setup_status` — report on every prerequisite: Bridge API key, repo name, `version` config, `dw.json` presence/uniqueness, AM (OCAPI) token acquisition, and the independent **SFCC Log Query (WebDAV)** capability that gates `sfcc_log_query`.
 - `check_permissions` — probe OCAPI access via `GET /system_object_definitions`; on 401/403, print the exact OCAPI Settings JSON to paste in Business Manager (read/search grants for the `sfcc` tools, mutation grants for the `sfcc-write` tools). An explicit `instance` hostname is still subject to the sandbox check below.
 
@@ -1008,7 +981,7 @@ npx -y @bridge_gpt/mcp-server start-tickets [flags] KEY [KEY ...]
 | `--base-branch <BRANCH>` | `main` | Cut new worktrees from `<BRANCH>` and refresh `origin/<BRANCH>` instead of `main` |
 | `--no-refresh-main` | off (the configured base branch is refreshed) | Skip refresh of the configured base branch (default `main`). Historical flag name preserved for backward compatibility — despite the name, it now skips refresh of whatever `--base-branch` resolves to. |
 | `--max-parallel N` | `3` | Max worktrees created concurrently |
-| `--conductor` | off | Opt into the Conductor system (per-worker `BAPI_CONDUCTOR_*` env + Claude hook injection, a supervisor peer tab, and the `check_messages` message-relay prompt). **Default off** — a plain run spawns `cd <worktree> && <agent> '/implement-ticket <KEY>'`. |
+| `--conductor` | off | Opt into the Conductor system (per-worker `BAPI_CONDUCTOR_*` env + Claude hook injection, lifecycle ledger events, and a supervisor peer tab). **Default off** — a plain run spawns `cd <worktree> && <agent> '/implement-ticket <KEY>'`. |
 | `-h`, `--help` | — | Show usage |
 
 Each `KEY` must match `[A-Z]+-[0-9]+` (e.g., `BAPI-248`). The CLI creates/switches each worktree up front (throttled by `--max-parallel`), then opens one tab/session per successful worktree running the selected agent's `'/implement-ticket <KEY>'` — `claude '/implement-ticket <KEY>'` by default, or `cursor-agent '/implement-ticket <KEY>'` with `--agent cursor-agent`. The `/implement-ticket <KEY>` prompt is unchanged for both agents. To launch Cursor Agent instead of Claude Code:
@@ -1234,12 +1207,58 @@ If a custom pipeline has the same key as a built-in pipeline, the custom version
 | `BAPI_MCP_TOOL_SURFACE_POLL_ENABLED` | No | _(disabled)_ | Opt IN to the recurring tool-surface **poll**. Default-**off**: a session gates once via the startup probe and never re-probes. Set to `true`/`1`/`yes`/`on`/`enabled` to restore the jittered 12–18 s heartbeat that pushes `notifications/tools/list_changed` on mid-session capability changes. No effect when gating itself is disabled |
 | `BAPI_MCP_UPDATE_CHECK_ENABLED` | No | _(enabled)_ | MCP-local kill switch for the cached update check run at startup. Default-on; set to `false`/`0`/`no`/`off`/`disabled` to skip it entirely — no npm registry request, no update-cache read/write, no stderr advice, and no `tools/list` advisory decoration. Any other value is treated as enabled. Useful behind a firewall/registry-restricted network, and used by the payload-measurement harness so a stale local cache can never perturb a capture |
 | `CURSOR_API_KEY` | No | _(none)_ | API key used to authenticate `cursor-agent` when launching `start-tickets`/scheduled runs with `--agent cursor-agent`. Not needed for the default Claude Code agent |
-| `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile — a **comma-separated** list of groups controlling which tool groups are registered when the server starts. `core` is always implicitly included. Valid groups: `core` (default — normal coding tools only), `conductor` (+ 8 conductor/event/supervisor tools), `pipeline-authoring` (+ 5 pipeline run/admin tools — `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `sfcc` (+ the 8 heavy SFCC read tools and `sfcc_log_query` — read-only, see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools); the `sfcc_setup_status`/`check_permissions` diagnostics are always registered regardless), `sfcc-write` (+ the 9 destructive SFCC write tools — independent of `sfcc`, which does not enable them; see [Read and write profiles](#read-and-write-profiles)), and `full` (shortcut that expands to every group, **including `sfcc-write`**). Example: `sfcc,conductor`; use `sfcc,sfcc-write` for reads plus writes. Unknown, blank, or malformed tokens are dropped (falling back to `core`). Dynamic mid-session switching via `tools/list_changed` is unsupported — groups are resolved once at process startup. Conductor/epic sessions launched via `start-tickets --conductor` **merge** `conductor` into the parent process's already-resolved groups at the spawn boundary rather than replacing them — a project running on `sfcc` spawns workers on `core,sfcc,conductor`. A normal `start-tickets` run stays on `core`. |
+| `BRIDGE_MCP_PROFILE` | No | `core` | Startup-time tool registration profile — a **comma-separated** list of groups controlling which tool groups are registered when the server starts. `core` is always implicitly included. Valid groups: `core` (default — normal coding tools only), `conductor` (+ 8 conductor/event/supervisor tools), `pipeline-authoring` (+ 5 pipeline run/admin tools — `get_pipeline_recipe` is NOT gated; it stays in `core` because the recipe-driven slash commands depend on it), `estimation` (+ `estimate_epic`, which is **hidden by default** — `/estimate-epic` needs this group), `sfcc` (+ the 8 heavy SFCC read tools, `sfcc_log_query`, and the `sfcc_setup_status`/`check_permissions` diagnostics — read-only, see [Salesforce B2C Commerce (SFCC) Tools](#salesforce-b2c-commerce-sfcc-tools)), `sfcc-write` (+ the 9 destructive SFCC write tools — independent of `sfcc`, which does not enable them; see [Read and write profiles](#read-and-write-profiles)), and `full` (shortcut that expands to every group, **including `estimation` and `sfcc-write`**). Example: `sfcc,conductor`; use `sfcc,sfcc-write` for reads plus writes. Unknown, blank, or malformed tokens are dropped (falling back to `core`). Dynamic mid-session switching via `tools/list_changed` is unsupported — groups are resolved once at process startup, so **changing this variable requires restarting the MCP server**. That is separate from the learn/onboarding tools, which are gated per session and can appear mid-session without a restart (see [Learn/onboarding tool availability](#learnonboarding-tool-availability)). Conductor/epic sessions launched via `start-tickets --conductor` **merge** `conductor` into the parent process's already-resolved groups at the spawn boundary rather than replacing them — a project running on `sfcc` spawns workers on `core,sfcc,conductor`. A normal `start-tickets` run stays on `core`. |
 
 Environment values are **trimmed**, and only a non-empty result wins. A
 whitespace-only `BAPI_API_KEY` therefore does not override anything: it falls
 through to credential-store resolution exactly as an unset variable would.
 
+## Learn/onboarding tool availability
+
+Three tools are **gated per session** rather than by profile:
+
+- `apply_install_manifest`
+- `invite_member`
+- `regenerate_directory_map`
+
+They are registered in the `core` profile like any other core tool, but the
+server starts them **disabled**, so a client that honors mid-session tool-list
+changes does not see them in its first `tools/list`. They are revealed — all
+three together, once per session — by either of two successful requests:
+
+1. a successful **`get_install_manifest`** call, or
+2. a **`get_pipeline_recipe`** request for the **`learn-repository`** pipeline.
+
+On reveal the server emits `notifications/tools/list_changed`, so a client that
+honors it picks the three tools up **without a restart**.
+
+`get_install_manifest` and `persist_routing_credential` stay ungated in `core` at
+all times, so the install and `start-tickets` flows always have their entry
+points. Only the first of those two is a trigger — `persist_routing_credential`
+never reveals anything; it is listed here because `/start-tickets` calls it and
+it therefore must never be gated.
+
+**Unrecognized clients get all three at startup.** The hide-then-reveal behavior
+applies only to clients verified to honor mid-session `tools/list_changed`. Any
+other client — including one that sends no name, a blank name, or a name the
+server does not recognize — is enabled at session initialization instead and
+therefore sees all three tools in its **first** `tools/list`. This is deliberate:
+the failure mode of guessing wrong should be an extra tool, never a permanently
+missing one.
+
+**A failed request changes nothing.** Only a genuinely successful manifest
+reveals the tools — the response must parse as JSON and carry a nonblank
+`snapshot_token`. An error response, a non-JSON body, or a manifest without a
+token leaves the three tools hidden, and the response you receive is unchanged by
+the check either way. Likewise, only the exact `learn-repository` pipeline is a
+trigger; other recipes and failed lookups reveal nothing.
+
+**Capability filtering still applies independently.** Revealing these tools does
+not override the backend capability gate described below. The effective surface
+is the *intersection* of the two, so a tool can be enabled for the session and
+still be absent from `tools/list` because this repository lacks the integration
+it needs. That is expected behavior, not a bug — check the integration first.
+
 ## Dynamic tool-surface gating (capability availability)
 
 The **effective advertised tool surface** is the intersection of three things:
@@ -1405,18 +1424,18 @@ The full surface, for when you need the complete enumeration. Day-to-day, use [U
 
 ### MCP tools
 
-The authoritative tool catalog covers **92 tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
+The authoritative tool catalog covers **69 tools** (enumerated below). What's actually registered in a session depends on `BRIDGE_MCP_PROFILE`: the default `core` profile loads a trimmed subset, and the conductor/pipeline-authoring/SFCC tools are added only under their respective profiles (see [Environment Variables](#environment-variables)). Async AI tools follow a request/get pattern: call the `request_*` tool to kick off generation, then the matching `get_*` tool to retrieve the result (or pass `wait_for_result: true` to poll automatically).
 
-- **Connectivity & identity** — `ping`, `get_my_role`, `get_docs_dir`
+- **Connectivity & identity** — `ping` (its JSON also carries `docs_dir`, `role`, and `customer_type`)
 - **Team & access** — `invite_member` (admin-only; mints a scoped access key for a teammate on an already-configured project — the plaintext key is shown exactly once)
 - **Jira tickets** — `get_tickets`, `get_ticket`, `create_ticket`, `update_ticket_description`, `add_comment`, `get_comments`
 - **Attachments** — `attachment` (operations: `upload`, `download`, `list`)
-- **AI generation (request/get)** — `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `create_doc`/`get_doc` (design docs by `doc_type`: tdd/fsd/prd), `request_prd`/`get_prd`, `request_clarifying_questions`/`get_clarifying_questions`, `request_ticket_critique`/`get_ticket_critique`, `request_ticket_review`, `request_reimplement_context`/`get_reimplement_context`, `request_council`/`get_council`, `request_deep_research`/`get_deep_research`
+- **AI generation (request/get)** — `request_plan_generation`/`get_plan`, `create_doc`/`get_doc` (design docs by `doc_type`: tdd/architecture/fsd/prd, where `architecture` is an alias of `tdd`), `request_ticket_review` (writes both `get_clarifying_questions` and `get_ticket_critique`), `request_reimplement_context`/`get_reimplement_context`, `request_council`/`get_council`, `request_deep_research`/`get_deep_research`
 - **Other AI** — `second_opinion`, `generate_image`, `generate_decision_page`, `visual_diff` (deterministic pixel diff of a rendered URL vs a design comp)
 - **Ticket lifecycle** — `track_ticket`, `update_ticket_state`, `get_ticket_state`, `get_ticket_state_tree` (live repo-wide lifecycle + dependency tree; read-only, no mutation parameter)
-- **Jira status** — `get_jira_transitions`, `update_jira_status`, `resolve_target_status`
-- **Repository & CI** — `parse_repository`, `get_parse_status`, `regenerate_directory_map`, `create_pull_request`, `merge_pull_request`, `resolve_ci_checks`, `poll_ci_checks`
-- **Pipelines & automation** — `list_pipelines`, `get_pipeline_recipe`, `run_pipeline`, `resume_pipeline`, `list_pipeline_runs`, `delete_pipeline_run`, `run_full_automation`, `resume_full_automation`
+- **Jira status** — `update_jira_status` (pass `status: "auto"` to resolve the configured post-PR status server-side)
+- **Repository & CI** — `parse_repository` (`action`: `start`, `status`), `regenerate_directory_map`, `create_pull_request`, `merge_pull_request`, `resolve_ci_checks`, `poll_ci_checks`
+- **Pipelines & automation** — `get_pipeline_recipe` (returns a fully resolved recipe the agent executes step-by-step)
 - **Config** — `get_project_standards`, `config_field` (operations: `get`, `update`, `list`)
 
 ### Bundled pipelines
@@ -1429,17 +1448,14 @@ Pipelines are declarative, multi-step workflows your AI agent executes step-by-s
 | `review-ticket` | Full ticket quality review: clarifying questions + critique plus an automatic second-opinion pass, then evaluation and decision capture. The backend owns round orchestration; pass `--rounds=1` for a single-pass review or `--rounds=2` to force the full second-opinion review, or omit `--rounds` to let the backend decide adaptively. | `/review-ticket PROJ-123` |
 | `idea-to-ticket` | Turn an idea into a Jira Task/Spike (or Epic + children) with research, dedup, and critique | `/idea-to-ticket "<idea>"` |
 | `plan-epic` | Decompose an epic into sub-tasks with a structured exploration doc for each | `/plan-epic "<epic>"` |
-| `full-automation` | Chain: idea → ticket(s) → review each → spawn worktrees to implement | `/full-automation "<idea>"` |
-| `pr-ticket` | Commit changes and open a pull request | `/create-pr PROJ-123` |
-| `check-ci-ticket` | Commit, open a PR, then monitor CI checks until they pass or fail | `/check-ci PROJ-123` |
+| `full-automation` | Client-side wrapper: runs the `idea-to-ticket` recipe, then hands the created keys to `/review-and-start --auto` | `/full-automation "<idea>"` |
 | `learn-repository` | Analyze codebase architecture, testing, review, and documentation standards, then upload to Bridge | `/learn-repository` |
 
 ### Pipeline response envelope
 
-`run_pipeline`, `resume_pipeline`, and `list_pipeline_runs` share a unified envelope keyed on `status`:
-
-- `completed` — terminal success; `results` holds per-step output.
-- `needs_agent_task` — the orchestrator paused. Read `instruction`, perform the task, then call `resume_pipeline` with `pipeline_run_id` and a string `agent_result`.
-- `failed` — terminal failure. `error_code` is one of `VALIDATION`, `NOT_FOUND`, `EXPIRED`, `REPO_MISMATCH`, `TOOL_ERROR`.
-
-Paused runs auto-expire after an idle TTL (default 24 hours; override with `ttl_seconds`). The TTL is reset on every state transition. List output is metadata-only — it never includes resolved recipes, params, instructions, results, or agent outputs.
+`get_pipeline_recipe` returns a fully resolved recipe: an ordered `steps` array
+plus `total_steps`, `auto_approve`, and `execution_mode`. Each step is either an
+`mcp_call` (a tool name with resolved params) or an `agent_task` (instruction
+text). `execution_mode` is `inline` — the calling agent executes every step
+itself and keeps its own durable record through `record_phase_result` /
+`record_checkpoint`. There is no server-side orchestrator and no run to resume.

package/build/agent-capabilities/default-deps.js

@@ -5,8 +5,8 @@
  * timeout guard in `probe-context.ts` can actually kill a hung agent (the
  * version-sensitive `cursor-agent -p` non-exit bug) instead of leaking it.
  *
- * Mirrors `createDefaultScheduleRunDeps()` in `schedule-run.ts`, adding the temp-dir
- * filesystem ops and a unique-suffix source the probes need.
+ * Mirrors the executor's own default deps, adding the temp-dir filesystem ops
+ * and a unique-suffix source the probes need.
  */
 import { execFile } from "node:child_process";
 import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises";

package/build/agent-launchers/claude.js

@@ -1,21 +1,20 @@
 /**
  * The `claude` agent launcher (BAPI-327, generalized in BAPI-351).
  *
- * Resolves the `claude` binary against the *baked schedule-time PATH* (not the
- * ambient process default) and builds the scheduled-run invocation by delegating
+ * Resolves the `claude` binary against the *explicitly supplied PATH* (not the
+ * ambient process default) and builds the launched-run invocation by delegating
  * to the shared `renderScheduledPrompt` renderer (no hard-coded `/full-automation`
  * prompt). It emits `{ exe, args: ["-p", prompt] }`. Claude Code has no
- * working-directory flag, so the cwd is always set by the scheduler unit — this
+ * working-directory flag, so the cwd is always set by the launching unit — this
  * adapter must never add a working-directory argument to the invocation.
  */
-import { pathApiForPlatform } from "../scheduler-backends/types.js";
-import { posixShellQuote, windowsCmdQuote } from "../scheduler-backends/escaping.js";
-import { renderScheduledPrompt } from "../scheduled-prompt.js";
-import { quotePromptToken } from "../scheduled-prompt.js";
+import { pathApiForPlatform } from "../worktree-core.js";
+import { posixShellQuote, windowsCmdQuote } from "../platform-escaping.js";
+import { renderScheduledPrompt, quotePromptToken } from "./prompt.js";
 /**
  * Resolve a bare command to an absolute path using the platform PATH-probe,
- * forcing the baked PATH so the schedule resolves the same binary the user had
- * at creation time. On Windows both `PATH` and `Path` are overridden (Node and
+ * forcing the supplied PATH so the launch resolves the same binary the caller
+ * captured. On Windows both `PATH` and `Path` are overridden (Node and
  * `where.exe` disagree on casing). Returns the first non-empty *absolute* path
  * from stdout, or `null` when the probe fails or yields only relative paths.
  */
@@ -57,15 +56,7 @@ export { quotePromptToken };
  * shared renderer. Exposed for focused unit testing of the launcher wiring.
  */
 export function buildClaudePrompt(input) {
-    return renderScheduledPrompt({
-        scheduleId: input.scheduleId,
-        scheduledAt: input.runAtIso,
-        autoApprove: input.autoApprove,
-        commandName: input.commandName,
-        args: input.args,
-        commandBody: input.commandBody,
-        schema: input.schema,
-    });
+    return renderScheduledPrompt(input);
 }
 const CLAUDE_CAPABILITY = {
     name: "claude",
@@ -82,7 +73,7 @@ export function createClaudeLauncher() {
         },
         buildInvocation(exe, input) {
             const prompt = buildClaudePrompt(input);
-            // No working-directory flag: cwd is owned by the scheduler unit.
+            // No working-directory flag: cwd is owned by the launching unit.
             return { exe, args: [CLAUDE_CAPABILITY.promptFlag, prompt], prompt };
         },
         formatInvocationLine(invocation, platform) {

package/build/agent-launchers/cursor.js

@@ -2,7 +2,7 @@
  * The `cursor-agent` agent launcher (BAPI-351).
  *
  * A near-mirror of the Claude launcher: it resolves the `cursor-agent` binary
- * against the baked schedule-time PATH and builds the scheduled-run prompt via
+ * against the explicitly supplied PATH and builds the launched-run prompt via
  * the shared `renderScheduledPrompt` renderer (so the drift gate and command body
  * are identical across agents). A local spike confirmed cursor-agent resolves the
  * same `.claude/commands` catalog and exits cleanly in headless mode.
@@ -14,20 +14,12 @@
  *  - headless auth is via the `CURSOR_API_KEY` environment variable. This adapter
  *    never reads or prints that value — auth readiness is a prerequisite check.
  */
-import { posixShellQuote, windowsCmdQuote } from "../scheduler-backends/escaping.js";
-import { renderScheduledPrompt } from "../scheduled-prompt.js";
+import { posixShellQuote, windowsCmdQuote } from "../platform-escaping.js";
+import { renderScheduledPrompt } from "./prompt.js";
 import { resolveCommandOnPath } from "./claude.js";
 /** Build the scheduled-run prompt for the Cursor launcher via the shared renderer. */
 export function buildCursorPrompt(input) {
-    return renderScheduledPrompt({
-        scheduleId: input.scheduleId,
-        scheduledAt: input.runAtIso,
-        autoApprove: input.autoApprove,
-        commandName: input.commandName,
-        args: input.args,
-        commandBody: input.commandBody,
-        schema: input.schema,
-    });
+    return renderScheduledPrompt(input);
 }
 const CURSOR_CAPABILITY = {
     name: "cursor-agent",

package/build/agent-launchers/prompt.js

@@ -0,0 +1,117 @@
+/** The fixed late-fire threshold, in seconds, shared by every launched run. */
+export const LATE_FIRE_THRESHOLD_SECONDS = 60;
+/**
+ * Quote a single argument token for safe inclusion in the rendered prompt while
+ * preserving its boundary. Simple tokens (alphanumerics plus a small set of
+ * path/flag-safe punctuation) are left bare; anything containing whitespace or
+ * prompt/markup-sensitive characters is wrapped in double quotes with embedded
+ * double quotes escaped. This is prompt-token quoting, NOT shell quoting — no
+ * shell ever sees these strings.
+ */
+export function quotePromptToken(token) {
+    if (token === "")
+        return '""';
+    // Safe: letters, digits, and characters that never need quoting in a prompt
+    // (path separators, ISO-timestamp punctuation, flag dashes, etc.).
+    if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(token))
+        return token;
+    return `"${token.replace(/"/g, '\\"')}"`;
+}
+/**
+ * True when a command's declared argument schema can parse a boolean `--auto`
+ * flag. Private to this module: the launchers only need the rendering decision,
+ * not a general command-schema query API.
+ */
+function schemaSupportsAutoFlag(schema) {
+    if (!schema)
+        return false;
+    return schema.flags.some((f) => f.flag === "--auto" && f.type === "boolean");
+}
+/**
+ * Compute the augmented argv tokens the launched run delegates to the command:
+ * the normalized `input.args`, plus (only where the command can parse them)
+ * `--scheduled-at <ISO>` and `--auto`.
+ *
+ * `--scheduled-at` is appended for `full-automation` (legacy) and `epic-tick`
+ * (BAPI-418), both of whose parsers accept it as a first-class argument. Every
+ * other command rejects unrecognized flags and halts (e.g. `start-tickets` stops
+ * on any unsupported flag), and the shared late-fire gate already embeds the
+ * scheduled time — so injecting `--scheduled-at` into their argv would break an
+ * otherwise launchable command for no benefit.
+ *
+ * `--auto` is appended when auto-approve is set AND the command supports it (its
+ * schema declares a boolean `--auto` flag, or it is `full-automation` / `epic-tick`).
+ * It is never duplicated if already present in `input.args`.
+ *
+ * This is the SINGLE source of the delegated argv: both the rendered target
+ * command line and the `$ARGUMENTS` body substitution derive from it, so the body
+ * parse and the command line never disagree (e.g. `review-ticket`, which reads
+ * `--auto` out of `$ARGUMENTS`, sees the same `--auto` the command line shows).
+ */
+function buildAugmentedArgs(input) {
+    const args = [...input.args];
+    // Commands whose parsers accept --scheduled-at as a first-class argument.
+    // epic-tick already accepts --scheduled-at (parseEpicTickArgs, cli.ts) so it
+    // receives the scheduled time as a structured arg for the late-fire decision,
+    // not just via the embedded gate text.
+    if (input.commandName === "full-automation" || input.commandName === "epic-tick") {
+        args.push("--scheduled-at", input.runAtIso);
+    }
+    const supportsAuto = schemaSupportsAutoFlag(input.schema) ||
+        input.commandName === "full-automation" ||
+        input.commandName === "epic-tick";
+    const alreadyHasAuto = input.args.includes("--auto");
+    if (input.autoApprove && supportsAuto && !alreadyHasAuto) {
+        args.push("--auto");
+    }
+    return args;
+}
+/**
+ * Render the delegated target command line as
+ * `/<commandName> <augmented args...>` (see {@link buildAugmentedArgs}).
+ */
+function buildTargetCommandLine(input) {
+    const parts = [`/${input.commandName}`];
+    for (const arg of buildAugmentedArgs(input))
+        parts.push(quotePromptToken(arg));
+    return parts.join(" ");
+}
+/** Render only the fixed late-fire gate text. */
+function renderLateFireGate(scheduleId, scheduledAt, autoApprove) {
+    const lateAction = autoApprove
+        ? "explain that the run is firing late and then PROCEED with the command below (this schedule was created with auto-approve)."
+        : "explain that the run is firing late and then HALT WITHOUT EXECUTING the command below (this schedule was created without auto-approve, and a headless run must not proceed unconfirmed).";
+    return [
+        "## Scheduled-run drift gate",
+        "",
+        `This is an automated, headless scheduled run (schedule id: ${scheduleId}).`,
+        `It was scheduled to fire at ${scheduledAt}.`,
+        "",
+        `Before doing anything else, check how late this run is firing. If it is more than ${LATE_FIRE_THRESHOLD_SECONDS} seconds later than the scheduled time above, ${lateAction}`,
+        `If it is within ${LATE_FIRE_THRESHOLD_SECONDS} seconds of the scheduled time, proceed silently.`,
+        "",
+        "Then run the following command exactly as written:",
+    ].join("\n");
+}
+/**
+ * Replace `$ARGUMENTS` in a command body with the safely-quoted, normalized
+ * argument string. Every occurrence is replaced (commands often repeat the
+ * placeholder in a title and a body line).
+ */
+function replaceArgumentsPlaceholder(body, argString) {
+    return body.split("$ARGUMENTS").join(argString);
+}
+/**
+ * Render the full launched-run prompt: gate + delegated command line + command
+ * body (with `$ARGUMENTS` substituted). Deterministic for identical inputs.
+ */
+export function renderScheduledPrompt(input) {
+    const gate = renderLateFireGate(input.scheduleId, input.runAtIso, input.autoApprove);
+    const targetCommandLine = buildTargetCommandLine(input);
+    // `$ARGUMENTS` must match what the command line shows — including the appended
+    // `--scheduled-at` / `--auto` — so a body that re-parses `$ARGUMENTS` (e.g.
+    // review-ticket reading `--auto`) agrees with the rendered command line.
+    const argString = buildAugmentedArgs(input).map(quotePromptToken).join(" ");
+    const body = replaceArgumentsPlaceholder(input.commandBody, argString);
+    return [gate, "", targetCommandLine, "", body].join("\n");
+}