@bridge_gpt/mcp-server 0.2.66 → 0.2.67

package/docs/install/mcp-tool-integrations.md

@@ -44,7 +44,6 @@ marked **— none**.
 | **SFCC WebDAV logs** | WebDAV log credentials (separate from OCAPI) plus the `sfcc_log_monitor_enabled` flag. | `sfcc_webdav_hostname/username/access_key`, `sfcc_log_monitor_enabled` |
 | **Deep-research flag** | The `deep_research_enabled` config flag on the project (403 otherwise). Web research runs via Gemini/OpenAI. | `config_projects.deep_research_enabled` |
 | **Image provider** | An image model provider (OpenAI DALL·E / Google Imagen). | platform provider config |
-| **Conductor ledger** | The local conductor event ledger (`~/.config/bridge/events.db`) — a local file, not a remote service. | local file |
 
 ## Profiles (a form of BLOCK)
 
@@ -56,13 +55,13 @@ activated. `core` is always implicitly included.
 | Profile | Registered when |
 |---|---|
 | `core` | always |
-| `pipeline-authoring` | `BRIDGE_MCP_PROFILE` includes `pipeline-authoring` or `full` |
-| `conductor` | includes `conductor` or `full` |
-| `sfcc` | includes `sfcc` or `full` — the OCAPI **read** tools and `sfcc_log_query` (2 diagnostics ship in `core`) |
+| `epic_implementer` | includes `epic_implementer` or `full` — the Epic Implementer run tools. The old token `conductor` is not valid and is dropped |
+| `estimation` | includes `estimation` or `full` — `estimate_epic` |
+| `pipeline-authoring` | includes `pipeline-authoring` or `full` — registers **no** tools since BAPI-909; still accepted so old configs keep working |
+| `sfcc` | includes `sfcc` or `full` — the OCAPI **read** tools, `sfcc_log_query`, and the two SFCC diagnostics |
 | `sfcc-write` | includes `sfcc-write` or `full` — the destructive SFCC **write** tools. Independent of `sfcc`: neither group implies the other (BAPI-817) |
 
-The `pipeline-authoring` tools live in `index.ts` alongside core, gated by
-`ACTIVE_GROUPS.has("pipeline-authoring")`.
+`get_pipeline_recipe` was never gated by `pipeline-authoring`; it is a `core` tool.
 
 > **This document deliberately states no tool counts.** Counts drift on every
 > ticket that adds or moves a tool, and nothing here is generated, so a number
@@ -147,7 +146,14 @@ by tier.
 
 | Tool | Dependencies (class) |
 |---|---|
-| `estimate_epic` | Jira **[BLOCK]** (resolves the repo from `jira_ticket_key`); no code-index dep |
+| `estimate_epic` | Jira **[BLOCK]** (resolves the repo from `jira_ticket_key`); no code-index dep; registered only under the `estimation` profile |
+
+**Epic Implementer eligibility:**
+
+| Tool | Dependencies (class) |
+|---|---|
+| `assess_epic_implementer_eligibility` | — none (read-only; predicts which epic children change workflow files from their text; needs no VCS or code index; fails open to `status: "unavailable"`) |
+| `assess_epic_conductor_eligibility` | — none (retired name; always returns `tool_removed` / 410 naming `assess_epic_implementer_eligibility`) |
 
 ### Repository parse / index — VCS
 
@@ -247,21 +253,24 @@ Constraints worth knowing before calling it:
   authoritative, so a tool-side pass followed by a server refusal is expected for a
   legacy approved comment that carries no head proof.
 
-## `conductor` profile
+## `epic_implementer` profile
 
-Profile-gated **[BLOCK]** to register. The local conductor ledger
-(`~/.config/bridge/events.db`) is now driven by the `conductor` CLI and the git hooks
-rather than by MCP tools, so only the epic snapshot remains registered here.
+Profile-gated **[BLOCK]** to register. Both tools are read-only and need an Epic
+Implementer run to exist; for an unknown epic or run they return
+`status: "unknown"` rather than an error. The local event ledger
+(`~/.config/bridge/events.db`) is driven by the `epic-implementer` CLI and the git
+hooks, not by MCP tools.
 
 | Tool | Dependencies (class) |
 |---|---|
-| `get_epic_snapshot` | Profile-gated **[BLOCK]** · Bridge API epic snapshot (Jira epic keys) |
+| `get_epic_snapshot` | Profile-gated **[BLOCK]** · Bridge API epic run state (by epic key) |
+| `explain_run` | Profile-gated **[BLOCK]** · Bridge API epic run state (by run id or epic key; `ticket_key` narrows it) |
 
 ---
 
 ## `sfcc` group
 
-### Always-on diagnostics (ship in `core`)
+### Diagnostics (gated behind the `sfcc` group since BAPI-912)
 
 | Tool | Dependencies (class) |
 |---|---|
@@ -273,7 +282,7 @@ rather than by MCP tools, so only the epic snapshot remains registered here.
 All are profile-gated **[BLOCK]** to register, and all require SFCC OCAPI creds +
 `version` config + a reachable sandbox → SFCC OCAPI **[BLOCK]**.
 
-Every SFCC tool — including the two always-on diagnostics above — additionally
+Every SFCC tool — including the two diagnostics above — additionally
 crosses the resolved-hostname sandbox boundary at invocation time: if the host
 the credentials resolve to is not a recognized developer sandbox, the call is
 refused with `403 TARGET_NOT_SANDBOX` before any request leaves the machine
@@ -331,7 +340,7 @@ wanting both selects `sfcc,sfcc-write` (or `full`).
 | **SFCC OCAPI** | `check_permissions` + every gated SFCC read and write tool | — |
 | **SFCC WebDAV logs** | `sfcc_log_query` | — |
 | **Deep-research flag** | `request_deep_research`, `get_deep_research` | — |
-| **Profile gating** | all `pipeline-authoring`, `conductor`, `sfcc`, and `sfcc-write` tools | — |
+| **Profile gating** | all `epic_implementer`, `estimation`, `sfcc`, and `sfcc-write` tools | — |
 
 ## Notes & caveats
 

package/docs/install/sfcc-integration.md

@@ -80,13 +80,20 @@ future work. No `delete` is granted, because no shipped write tool performs one;
     { "resource_id": "/system_object_definitions",    "methods": ["get"],                  "read_attributes": "(**)", "write_attributes": "(**)" },
     { "resource_id": "/system_object_definitions/**", "methods": ["get", "put", "patch"],  "read_attributes": "(**)", "write_attributes": "(**)" },
     { "resource_id": "/custom_object_definitions/**", "methods": ["get", "put", "patch"],  "read_attributes": "(**)", "write_attributes": "(**)" },
-    { "resource_id": "/site_preferences/**",          "methods": ["get", "patch"],         "read_attributes": "(**)", "write_attributes": "(**)" }
+    { "resource_id": "/sites/*/site_preferences/**", "methods": ["get", "patch"],         "read_attributes": "(**)", "write_attributes": "(**)" }
   ]
 }
 ```
 
 Notes:
 
+- Value writes (`site_preference_values_set`) are site-scoped: they need the mutation
+  resource `/sites/*/site_preferences/**`. The read/search grant keeps the org-level
+  `/site_preferences/**`. **If you pasted an earlier mutation grant, it lacks the
+  site-scoped resource.** Replace `<YOUR_CLIENT_ID>` with your client id in the newly
+  printed grant (`check_permissions` prints it) and paste it again before running
+  value writes.
+- `check_permissions` probes a GET only. It shows read access, not write access.
 - The `client_id` **must match** the Account Manager API client whose credentials you
   put in `dw.json` / `SFCC_*` below. Replace the value above with your own client id if
   it differs.
@@ -127,9 +134,10 @@ Create a `dw.json` in your project root (auto-added to git exclude — never com
 ```
 
 Accepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`,
-`client-secret`/`clientSecret`/`client_secret`. Use a single config — a multi-entry
-`configs[]` array is rejected outright, not worked around with an explicit `instance`
-(see the README's SFCC section for why). Alternatively, export
+`client-secret`/`clientSecret`/`client_secret`. A single config is simplest. With a
+multi-entry `configs[]` array, pass one of the listed sandbox hostnames as `instance`
+and that config's credentials are used (an unapproved host is refused before any
+credential lookup); without an `instance` the call fails as `multi-sandbox`. Alternatively, export
 `SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.
 
 ## 3. Set the repo `version` config field

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge_gpt/mcp-server",
-  "version": "0.2.66",
+  "version": "0.2.67",
   "description": "Bridge API MCP server — exposes Jira endpoints as MCP tools for Claude Code agents",
   "license": "MIT",
   "type": "module",

package/pipelines/plan-epic.json

@@ -54,11 +54,6 @@
       "type": "agent_task",
       "instruction_file": "write-epic-summary.md",
       "description": "Write epic overview and summary document"
-    },
-    {
-      "type": "agent_task",
-      "instruction_file": "store-and-approve-epic-plan.md",
-      "description": "Create epic run, store the plan DAG, and approve it in the backend"
     }
   ]
 }

package/pipelines/review-ticket.json

@@ -30,7 +30,7 @@
     {
       "type": "agent_task",
       "id": "wait-for-ticket-review",
-      "instruction": "FIRST, check whether a review was actually submitted. The previous step runs with `on_error: warn_and_continue`, so a rejected submission (a 402, 403 or 500 from the generate endpoint, or a dropped connection) lets the pipeline continue into this step. If that step returned an error message rather than its submission confirmation or a `recovery_get` envelope, do NOT wait: nothing is running, and `wait_for_ticket_review` cannot tell \"never submitted\" from \"still running\" \u2014 it would read `pending` in every window until the caller's own timeout. Treat a failed submission as a terminal failure, report the error the previous step gave, and take the verdict contract's `revise` path.\n\nOtherwise, wait for the review submitted by the previous step to finish, using repeated BOUNDED windows.\n\nCall `wait_for_ticket_review` with `ticket_number` set to the ticket key. Each call uses the default 20-second window (set `budget_ms: 20000` explicitly if needed); do not use a longer window, because some MCP clients time out before a pending result arrives. The tool returns a JSON body with a `state` field:\n\n- `state: \"pending\"` \u2014 NORMAL and expected. The review is still running. Call the tool again immediately. Do NOT sleep, do NOT poll in a shell loop, and do NOT re-run `request_ticket_review`: re-submitting starts a second billable multi-model review and abandons the one already in flight.\n- `state: \"ready\"` \u2014 the review is over. BAPI-1121: a ready result has ALREADY persisted exactly the accepted documents and reconciled the canonical source files \u2014 it writes every leg in `saved_legs` to its canonical path and removes the stale canonical file for every leg in `withheld_legs`. Do NOT call `get_clarifying_questions` or `get_ticket_critique` after a ready result; those retrieval calls were removed from this recipe because reading them again could reintroduce exactly the stale content the wait just withheld. Treat `saved_legs` as the authoritative source set for the next steps, not file presence.\n  - `freshness_basis: \"generation\"` is the normal case: `advanced_legs`/`saved_legs` are current-review evidence, proven newer than the submission. Any leg in `withheld_legs` was delivered but NOT proven current \u2014 surface its `reason` (`generation_not_advanced` or `identity_unreadable`) as a visible warning; do not describe the result as an ordinary cost-saved one-leg review when a withholding occurred. A leg in `absent_legs` with `reason: \"not_delivered\"` is an ordinary policy omission (e.g. an Easy-ticket clarify-only review) unless its status also flags it as policy-expected, in which case call that out too.\n  - `freshness_basis: \"terminality_only\"` means no submission baseline was available (e.g. a resumed session) \u2014 `advanced_legs` is empty by construction and `saved_legs` was accepted on terminal delivery alone. Surface this prominently as a DEGRADED-freshness warning: the saved artifact(s) may be indistinguishable from a prior attachment, and the downstream identity-footer agreement check is the remaining backstop. Retain this warning when reporting to the next steps rather than treating a `terminality_only` ready result as equivalent to a `generation`-backed one.\n  - If the result instead carries `state: \"error\"` alongside a persistence failure (an `ARTIFACT_PERSISTENCE_FAILED` `error`/`status`/`message` envelope), HALT rather than proceeding with whatever files happen to exist on disk \u2014 report the failure; the accepted legs already on disk before the failure are named in the envelope and are not lost, but nothing new was persisted for this window.\n- `state: \"error\"` \u2014 terminal. Report the `reason` and stop; the review will not complete on its own. `UPSTREAM_TERMINAL` means the review failed or expired server-side \u2014 take the verdict contract's `revise` path; do NOT open another wait window and do NOT re-run `request_ticket_review`. `INVALID_RESPONSE` means the delivered document could not be read.\n\nKeep looping on `pending` for as long as this session's own budget allows. There is no iteration cap here: the bound is the caller's \u2014 for the conductor's spec-review worker that is the existing 120-minute job timeout, which produces the ordinary liveness outcome if the review never lands. Never fabricate a verdict or a review result from a pending state.",
+      "instruction": "FIRST, check whether a review was actually submitted. The previous step runs with `on_error: warn_and_continue`, so a rejected submission (a 402, 403 or 500 from the generate endpoint, or a dropped connection) lets the pipeline continue into this step. If that step returned an error envelope \u2014 a JSON object with a string `error`, a numeric `status`, and an `operation` field (for example `status: 403` with `error: \"ENTITLEMENT_REQUIRED\"`, or `status: 422` for too little ticket detail) \u2014 rather than its submission confirmation or a `recovery_get` envelope, do NOT wait: nothing is running, and `wait_for_ticket_review` cannot tell \"never submitted\" from \"still running\" \u2014 it would read `pending` in every window until the caller's own timeout. Treat a failed submission as a terminal failure, report the `status`, `error`, and `message` the previous step gave, and take the verdict contract's `revise` path.\n\nOtherwise, wait for the review submitted by the previous step to finish, using repeated BOUNDED windows.\n\nCall `wait_for_ticket_review` with `ticket_number` set to the ticket key. Each call uses the default 20-second window (set `budget_ms: 20000` explicitly if needed); do not use a longer window, because some MCP clients time out before a pending result arrives. The tool returns a JSON body with a `state` field:\n\n- `state: \"pending\"` \u2014 NORMAL and expected. The review is still running. Call the tool again immediately. Do NOT sleep, do NOT poll in a shell loop, and do NOT re-run `request_ticket_review`: re-submitting starts a second billable multi-model review and abandons the one already in flight.\n- `state: \"ready\"` \u2014 the review is over. BAPI-1121: a ready result has ALREADY persisted exactly the accepted documents and reconciled the canonical source files \u2014 it writes every leg in `saved_legs` to its canonical path and removes the stale canonical file for every leg in `withheld_legs`. Do NOT call `get_clarifying_questions` or `get_ticket_critique` after a ready result; those retrieval calls were removed from this recipe because reading them again could reintroduce exactly the stale content the wait just withheld. Treat `saved_legs` as the authoritative source set for the next steps, not file presence.\n  - `freshness_basis: \"generation\"` is the normal case: `advanced_legs`/`saved_legs` are current-review evidence, proven newer than the submission. Any leg in `withheld_legs` was delivered but NOT proven current \u2014 surface its `reason` (`generation_not_advanced` or `identity_unreadable`) as a visible warning; do not describe the result as an ordinary cost-saved one-leg review when a withholding occurred. A leg in `absent_legs` with `reason: \"not_delivered\"` is an ordinary policy omission (e.g. an Easy-ticket clarify-only review) unless its status also flags it as policy-expected, in which case call that out too.\n  - `freshness_basis: \"terminality_only\"` means no submission baseline was available (e.g. a resumed session) \u2014 `advanced_legs` is empty by construction and `saved_legs` was accepted on terminal delivery alone. Surface this prominently as a DEGRADED-freshness warning: the saved artifact(s) may be indistinguishable from a prior attachment, and the downstream identity-footer agreement check is the remaining backstop. Retain this warning when reporting to the next steps rather than treating a `terminality_only` ready result as equivalent to a `generation`-backed one.\n  - If the result instead carries `state: \"error\"` alongside a persistence failure (an `ARTIFACT_PERSISTENCE_FAILED` `error`/`status`/`message` envelope), HALT rather than proceeding with whatever files happen to exist on disk \u2014 report the failure; the accepted legs already on disk before the failure are named in the envelope and are not lost, but nothing new was persisted for this window.\n- `state: \"error\"` \u2014 terminal. Report the `reason` and stop; the review will not complete on its own. `UPSTREAM_TERMINAL` means the review failed or expired server-side \u2014 take the verdict contract's `revise` path; do NOT open another wait window and do NOT re-run `request_ticket_review`. `NO_REVIEW_REQUESTED` means no review was submitted from this session and none is running; `NO_REVIEW_RUNNING` means the submitted review is no longer running on the server \u2014 treat both like `UPSTREAM_TERMINAL`. `INVALID_RESPONSE` means the delivered document could not be read.\n\nKeep looping on `pending` for as long as this session's own budget allows. There is no iteration cap here: the bound is the caller's \u2014 for the conductor's spec-review worker that is the existing 120-minute job timeout, which produces the ordinary liveness outcome if the review never lands. Never fabricate a verdict or a review result from a pending state.",
       "description": "Wait for the submitted review in repeated bounded windows; a ready result has already persisted the accepted documents and reconciled the canonical files (BAPI-1121). Resumable: a pending result is a normal observation, not a failure.",
       "on_error": "halt"
     },