@bridge_gpt/mcp-server 0.2.23 → 0.2.24

package/build/sfcc/setup-status.js

@@ -19,7 +19,8 @@ import { getAmToken } from "./client.js";
  *   2. Repo name set (REPO_NAME)
  *   3. version config field is an SFCC version
  *   4. dw.json found / instance unambiguous
- *   5. AM token acquisition
+ *   5. AM token acquisition (OCAPI Account Manager — NOT log/WebDAV access)
+ *   6. SFCC Log Query capability (WebDAV Basic auth — independent of steps 3–5)
  *
  * Never throws; each check is caught independently so partial states are
  * always reported. Output is completely secret-free.
@@ -97,8 +98,37 @@ export async function sfccSetupStatusTool(deps) {
             tokenStatus = `✗ ${msg}`;
         }
     }
-    lines.push(`5. AM Token: ${tokenStatus}`);
-    lines.push("\nRun `check_permissions` to probe OCAPI access once steps 1–5 are all green.");
+    lines.push(`5. AM Token (OCAPI): ${tokenStatus}`);
+    // 6. SFCC Log Query capability — WebDAV Basic auth, independent of OCAPI/AM.
+    // A single Bridge backend probe (secret-free) reports readiness. This is a
+    // separate credential surface: an SFCC repo can have OCAPI working (steps 3–5)
+    // while log/WebDAV access is not configured, and vice versa.
+    let logQueryStatus = "— Skipped (Bridge API not configured)";
+    if (apiKeyOk && repoOk) {
+        try {
+            const url = deps.buildGetUrl("/sfcc/logs/capability", { repo_name: deps.repoName });
+            const resp = await fetch(url, { headers: await deps.getGetHeaders() });
+            if (!resp.ok) {
+                logQueryStatus = `✗ Could not read (Bridge API ${resp.status})`;
+            }
+            else {
+                const body = (await resp.json());
+                if (body?.configured === true) {
+                    logQueryStatus = "✓ Configured (WebDAV log access ready)";
+                }
+                else {
+                    const msg = typeof body?.message === "string" ? body.message : "Not configured";
+                    logQueryStatus = `✗ ${msg}`;
+                }
+            }
+        }
+        catch (err) {
+            logQueryStatus = `✗ Resolution error: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    lines.push(`6. SFCC Log Query (WebDAV): ${logQueryStatus}`);
+    lines.push("\nRun `check_permissions` to probe OCAPI access once steps 1–5 are all green. " +
+        "Step 6 (log/WebDAV access) is independent and gates `sfcc_log_query`.");
     return {
         content: [{ type: "text", text: lines.join("\n") }],
     };

package/build/version.generated.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
-export const VERSION = "0.2.23";
+export const VERSION = "0.2.24";

package/{CONDUCTOR.md → docs/CONDUCTOR.md}

@@ -8,7 +8,7 @@ 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).
+[README → CLI Subcommands](../README.md#cli-subcommands).
 
 ## Epic Conductor v2 — how an epic is actually driven
 
@@ -81,7 +81,7 @@ blocks or aborts a spawn, and `--dry-run` performs no conductor side effects.
 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).
+profile). See [README → Environment Variables](../README.md#environment-variables).
 
 ## `conductor install-git-hooks` (BAPI-395)
 

package/docs/install/github-app.md

@@ -0,0 +1,189 @@
+# Installing the Bridge GitHub App
+
+Bridge connects to GitHub through a **GitHub App**, not a personal access token. Once
+the app is installed on your repository and linked to your Bridge project, Bridge can
+open pull requests, run automated code review, read CI check status, and (when enabled)
+auto-merge — all using short-lived, per-call installation tokens. Your code and
+credentials stay on GitHub; Bridge mints a fresh token for each operation and stores no
+long-lived GitHub token.
+
+## The app
+
+| | |
+|---|---|
+| **Name** | Bridge GPT - AI Tools for SFCC |
+| **Owner** | [@Bridge-GPT](https://github.com/Bridge-GPT) |
+| **Public install page** | <https://github.com/apps/bridge-gpt-ai-tools-for-sfcc> |
+| **App ID** | `954077` |
+| **Client ID** | `Iv23liBEyDUeD25W06ix` |
+
+> The App ID and Client ID are **public** identifiers (GitHub shows them on the app's
+> settings page). They are not secrets. Only the app's **private key** and webhook
+> secret are sensitive, and those are held by whoever operates the Bridge deployment —
+> see [Self-hosting / operator setup](#self-hosting--operator-setup) at the end. As an
+> end user you never handle them.
+
+## Prerequisites
+
+- A GitHub repository you want Bridge to work on.
+- Permission to install a GitHub App on the account that owns it:
+  - **Personal repo:** you can install it yourself.
+  - **Organization repo:** you must be an **organization owner**, or a member who can
+    *request* the install for an owner to approve. (GitHub decides which button you see —
+    **Install**, **Install & request**, or **Request** — based on your role.)
+- Your Bridge project already registered (you have a Bridge API key and repo name).
+
+---
+
+## Option A — Connect GitHub button (recommended)
+
+This is the normal path. Bridge captures the installation automatically — you never copy
+an ID by hand.
+
+1. Open your project's **Get Started** page in the Bridge web UI.
+2. Click **Connect GitHub**. Bridge mints a short-lived, single-use link scoped to your
+   project and sends you to GitHub's app-install screen.
+3. On GitHub, choose the **account or organization** that owns the repository.
+4. Under **Repository access**, choose **Only select repositories** and pick the repo(s)
+   you want Bridge to cover (or **All repositories**). See
+   [Choosing repositories](#choosing-repositories) below.
+5. Review the requested permissions and click **Install** (or **Install & request** /
+   **Request** if an org owner must approve).
+6. GitHub redirects you back to Bridge. Bridge verifies the installation directly with
+   GitHub, links it to your project, and stores the installation automatically. If the
+   installation covers exactly one repo — or one repo clearly matches your project —
+   Bridge binds it for you; otherwise it shows a short **repository picker** so you can
+   confirm which repo maps to this project.
+
+That's it — no manual ID entry. If the automatic link fails for any reason, Bridge tells
+you and points you to Option B.
+
+---
+
+## Option B — Manual install + Installation ID (fallback)
+
+Use this if the Connect GitHub button isn't available to you, or automatic linking
+failed.
+
+### 1. Install the app
+
+Go to the public install page and install it on the owning account/organization,
+selecting the repository/repositories you want Bridge to access:
+
+<https://github.com/apps/bridge-gpt-ai-tools-for-sfcc/installations/new>
+
+(Same repository-selection and permissions-review screen as Option A, steps 3–5.)
+
+### 2. Find the Installation ID
+
+The Installation ID is the trailing number in the app's **Configure** URL:
+
+- **Personal account:** open **Settings → Applications → Installed GitHub Apps**, click
+  **Configure** next to *Bridge GPT - AI Tools for SFCC*. The URL is
+  `https://github.com/settings/installations/<INSTALLATION_ID>`.
+- **Organization:** open **Organization Settings → Third-party Access → GitHub Apps**,
+  click **Configure** next to the app. The URL is
+  `https://github.com/organizations/<ORG>/settings/installations/<INSTALLATION_ID>`.
+
+For example, `https://github.com/organizations/Bridge-GPT/settings/installations/61661616`
+has Installation ID **`61661616`**.
+
+### 3. Enter it in Bridge
+
+On your project's **Setup** page, in the GitHub section, paste the **Installation ID**
+into the field provided and save. Make sure the project's **version control system** is
+set to `github`. Bridge fills in the account owner and repository from your project
+settings.
+
+---
+
+## Choosing repositories
+
+When installing (either option), GitHub asks which repositories the app may access:
+
+- **All repositories** — the app can access every current and future repo on the account.
+- **Only select repositories** — pick specific repos from the **Select repositories**
+  dropdown. Recommended: grant only the repo(s) you actually want Bridge to work on.
+
+You can change this later at any time: **Configure** the installation (paths above),
+adjust **Repository access**, and click **Save**. If the app creates a repository, it is
+automatically granted access to that repo.
+
+## What the app can access
+
+At install time GitHub shows the **authoritative** list of permissions the app requests —
+review it there. Functionally, the Bridge integration exercises these GitHub permissions:
+
+| Permission | Why |
+|---|---|
+| **Contents** (read & write) | Read repo files for parsing/review; manage branch refs when opening/cleaning up PRs |
+| **Pull requests** (read & write) | List/read PRs and diffs; post review comments and reviews; merge when auto-merge is enabled |
+| **Checks / Commit statuses** (read) | Poll CI check-run and status results for a commit |
+| **Administration** (read) | Read branch-protection required-status-checks to resolve which checks must pass |
+| **Metadata** (read) | Baseline repo metadata; verify the installation's repository list |
+| **Webhook events** | Receive `pull_request`, `installation`, and review/merge events that drive automated review and merge |
+
+> These are inferred from the GitHub REST endpoints the integration calls. The exact set
+> the app is *registered* with is shown by GitHub on the install screen; treat that
+> screen as the source of truth.
+
+## Verifying the connection
+
+After linking, confirm Bridge can act on the repo:
+
+- The Bridge **Setup / integration status** should show version control as connected.
+- A Bridge operation that needs GitHub — e.g. `create_pull_request`, `resolve_ci_checks`,
+  or `poll_ci_checks` from the MCP — should succeed rather than return a
+  "no VCS connection" refusal. (See
+  [MCP Tool Integration Dependencies](./mcp-tool-integrations.md) for which tools require
+  a VCS connection.)
+
+If a GitHub-dependent tool refuses, the installation isn't linked to that project yet —
+re-run Option A, or set the Installation ID via Option B.
+
+## Managing or removing the app
+
+- **Change repo access / review permissions:** **Configure** the installation (URLs
+  above) → adjust **Repository access** → **Save**.
+- **Uninstall:** on the same Configure page, scroll to **Danger zone → Uninstall**.
+  Uninstalling revokes Bridge's access immediately; existing stored installation IDs stop
+  working.
+
+---
+
+## Self-hosting / operator setup
+
+*Skip this section if you are an end user connecting to a hosted Bridge deployment — it is
+for whoever runs the Bridge API server.*
+
+The GitHub App identity is configured **once per deployment** via environment variables.
+Bridge uses the App private key to mint short-lived installation tokens on demand; it
+persists no long-lived GitHub token.
+
+| Env var | Value / purpose |
+|---|---|
+| `GIT_APP_ID` | The app's numeric App ID — `954077` for *Bridge GPT - AI Tools for SFCC*. |
+| `GIT_PRIVATE_KEY` | **base64-encoded PEM** private key generated for the app (GitHub → app settings → *Generate a private key*). This is the one true secret. |
+| `GITHUB_APP_INSTALL_URL` | The public install URL the **Connect GitHub** button sends users to: `https://github.com/apps/bridge-gpt-ai-tools-for-sfcc/installations/new`. |
+| `GITHUB_WEBHOOK_SECRET` | App-level shared secret validating signed `installation` / merge webhooks. If unset, those webhooks are disabled (the redirect-callback path still works). |
+| `BGPT_ENCRYPTION_KEY` | Fernet key used to encrypt per-repo credentials at rest. |
+
+The app's **Setup URL** (in GitHub app settings) must point at the deployment's
+`GET /setup/github/callback` endpoint so the post-install redirect can auto-link the
+installation. Webhook endpoints used by the integration include the code-review hook
+(e.g. `https://<deployment-host>/github/code-review`); configure these on the app to match
+your deployment host.
+
+> **Note:** an older placeholder app slug (`bridge-gpt-code-reviewer`) still appears as a
+> stale default string in the codebase. The runtime install URL and App ID always come
+> from `GITHUB_APP_INSTALL_URL` / `GIT_APP_ID`, so set those to the `954077` /
+> `bridge-gpt-ai-tools-for-sfcc` values above rather than relying on the code default.
+
+## See also
+
+- [MCP Tool Integration Dependencies](./mcp-tool-integrations.md) — which MCP tools need a
+  VCS connection (BLOCK) vs merely degrade without one.
+- [Installing the SFCC Integration (OCAPI)](./sfcc-integration.md) — the separate
+  Salesforce B2C sandbox integration.
+- GitHub docs: [Installing a GitHub App from a third party](https://docs.github.com/en/apps/using-github-apps/installing-a-github-app-from-a-third-party),
+  [Reviewing and modifying installed GitHub Apps](https://docs.github.com/en/apps/using-github-apps/reviewing-and-modifying-installed-github-apps).

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

@@ -0,0 +1,305 @@
+# MCP Tools — Integration Dependencies
+
+This catalog lists every tool exposed by the Bridge API MCP server
+(`@bridge_gpt/mcp-server`) and the external integrations each one depends on. It
+answers a single operational question: *before I call this tool, what needs to be
+connected, and what happens if it isn't?*
+
+For the tool **reference** (parameters, endpoints, examples) see the
+[package README](../../README.md). The dependency classes below are not editorial —
+they mirror the enforced policy in the Bridge API backend
+(`api/library/vcs/vcs_route_operations.py`, the single source of truth for
+route → capability gating, and its probes in `api/library/vcs/vcs_preflight.py`).
+
+## Two dependency classes
+
+- **BLOCK** — the tool refuses, or its output is untrustworthy enough that it should
+  not be used, without the integration. This covers both hard blockers (the backend
+  returns a refusal) and "no local alternative" tools. Codebase-grounded generators
+  are blocked on an unindexed repo on purpose: *"plan output on an unindexed repo is
+  worthless"* (`api/routes/jira_api.py`). In code, BLOCK ≈ `VCS_ROUTE_REQUIREMENTS`
+  (VCS-credential refusal) + `INDEX_REQUIRED_ROUTE_KEYS` (parse/index refusal).
+
+- **DEGRADE** — the tool still runs and returns useful output, but quality is weaker
+  without the integration. In code, DEGRADE ≈ `VCS_ROUTE_WARNINGS` (Tier-4
+  "warn, never block"): the shared research helper `plan_researcher` returns *empty*
+  code research instead of erroring, so the tool falls back to ticket text alone and
+  attaches a non-blocking disclosure.
+
+**Baseline (assumed for every tool, not repeated below):** every non-`LOCAL` tool
+needs the Bridge API reachable plus a valid API key with repo access
+(`verify_repo_access`); every AI tool needs an LLM provider (platform-managed).
+`LOCAL` tools make no backend call at all. A tool with no integration dependency is
+marked **— none**.
+
+## Integrations glossary
+
+| Integration | What "connected" means | Where configured |
+|---|---|---|
+| **Ticket backend** | A ticket store in the repo's `ticket_backend_mode` — `jira` (Jira connection) or `local` (Postgres, no external service). Default is `jira`. | `config_projects.ticket_backend_mode`; Jira token in `config_projects_access` |
+| **Jira (only)** | A live Jira connection specifically — for surfaces with no local-mode equivalent (comment threads, binary attachments). | `config_projects_access.jira_api_token` |
+| **Version control (VCS)** | GitHub App or Bitbucket credentials for the repo. | `git_app_installation_id` / `git_app_owner` (GitHub) or `workspace` / `version_control_access_token` (Bitbucket) |
+| **Code index** | A **succeeded** `parse_repository` run (Pinecone code embeddings). A repo can have valid VCS creds yet never have been parsed. | `config_projects_access.pinecone_index_name`; status in `repository_parse_runs` / `code_repositories` |
+| **SFCC OCAPI** | Salesforce B2C sandbox OCAPI access: `dw.json` / AM token + `version` config field + OCAPI grants. | `dw.json`, `version` config field, OCAPI data-API grants |
+| **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)
+
+The server registers **90 tools** total, gated by `BRIDGE_MCP_PROFILE`
+(comma-separated group list, resolved once at startup by
+`mcp_server/src/mcp-profile.ts`). A tool outside
+the active profile is **not registered at all** — an absolute block until the group is
+activated. `core` is always implicitly included.
+
+| Profile | Tools | Registered when |
+|---|---|---|
+| `core` | **57** | always |
+| `pipeline-authoring` | **+5** | `BRIDGE_MCP_PROFILE` includes `pipeline-authoring` or `full` |
+| `conductor` | **+8** | includes `conductor` or `full` |
+| `sfcc` | **+20** (2 diagnostics ship in `core`; 18 gated) | includes `sfcc` or `full` |
+
+(57 core + 5 + 8 + 20 = 90. The 5 pipeline-authoring tools live in `index.ts` alongside
+core, gated by `ACTIVE_GROUPS.has("pipeline-authoring")`, so `index.ts` holds 62
+`registerTool` calls.)
+
+---
+
+## Core profile (57)
+
+### Connectivity, config & setup — no integration deps
+
+These are never gated (`NEVER_GATED_ROUTE_KEYS`) or run entirely locally.
+
+| Tool | Dependencies (class) |
+|---|---|
+| `ping` | — none |
+| `get_project_standards` | — none |
+| `get_my_role` | — none |
+| `config_field` (get/update/list) | — none |
+| `get_install_manifest` | — none |
+| `apply_install_manifest` | — none |
+| `persist_routing_credential` | — none (`LOCAL`) |
+| `get_docs_dir` | — none (`LOCAL`) |
+| `get_parse_status` | — none |
+| `track_ticket` | — none (Bridge DB tracking record) |
+| `update_ticket_state` | — none (Bridge DB) |
+| `get_ticket_state` | — none (Bridge DB) |
+| `get_ticket_model_tier` | — none (Bridge DB difficulty) |
+| `get_pipeline_recipe` | — none (`LOCAL`, bundled recipes) |
+| `generate_decision_page` | — none (`LOCAL` HTML) |
+| `cleanup_fresh_base` | — none (`LOCAL`) |
+
+### Ticket CRUD — ticket backend
+
+Backend-agnostic (work in `jira` **or** `local` mode; Jira-named for v1 compatibility).
+BLOCK applies only in `jira` mode without a Jira connection — `local` mode needs no
+external integration.
+
+| Tool | Dependencies (class) |
+|---|---|
+| `create_ticket` | Ticket backend **[BLOCK in jira mode]** |
+| `get_tickets` | Ticket backend **[BLOCK in jira mode]** |
+| `get_ticket` | Ticket backend **[BLOCK in jira mode]** |
+| `update_ticket_description` | Ticket backend **[BLOCK in jira mode]** |
+| `update_jira_status` | Ticket backend **[BLOCK in jira mode]** (local sets a fixed status) |
+| `get_jira_transitions` | Ticket backend **[BLOCK in jira mode]** (local returns fixed statuses) |
+
+Jira-only — no local-mode equivalent (comment threads and binary attachments are out of
+scope for local v1):
+
+| Tool | Dependencies (class) |
+|---|---|
+| `get_comments` | Jira (only) **[BLOCK]** |
+| `add_comment` | Jira (only) **[BLOCK]** |
+| `attachment` (upload/download/list) | Jira (only) **[BLOCK]** |
+
+### AI ticket-artifact generators — ticket backend + VCS + code index
+
+All read the ticket through the ticket-store seam (`_fetch_ticket_webhook_payload` →
+`ticket_store_lib.get_ticket`, which the local store fully supports), so they run in
+`local` mode too — they are **not** hard-Jira-blocked. Their VCS/index behavior splits
+by tier.
+
+**Tier-3 — codebase-grounded (refuse without VCS creds AND a succeeded parse):**
+
+| Tool (request / retrieve) | Dependencies (class) |
+|---|---|
+| `request_plan_generation` / `get_plan` | Ticket backend [BLOCK in jira mode] · VCS **[BLOCK]** · Code index **[BLOCK]** |
+| `request_architecture` / `get_architecture` | Ticket backend [BLOCK in jira mode] · VCS **[BLOCK]** · Code index **[BLOCK]** |
+| `request_reimplement_context` / `get_reimplement_context` | Ticket backend [BLOCK in jira mode] · VCS **[BLOCK]** · Code index **[BLOCK]** |
+| `create_doc` / `get_doc` — `doc_type` ∈ {tdd, architecture} | Ticket backend [BLOCK in jira mode] · VCS **[BLOCK]** · Code index **[BLOCK]** |
+
+**Tier-4 — ticket-text (warn, never block; research empties without index):**
+
+| Tool (request / retrieve) | Dependencies (class) |
+|---|---|
+| `request_clarifying_questions` / `get_clarifying_questions` | Ticket backend [BLOCK in jira mode] · VCS **[DEGRADE]** · Code index **[DEGRADE]** |
+| `request_ticket_critique` / `get_ticket_critique` | Ticket backend [BLOCK in jira mode] · VCS **[DEGRADE]** · Code index **[DEGRADE]** |
+| `request_ticket_review` | Ticket backend [BLOCK in jira mode] · VCS **[DEGRADE]** · Code index **[DEGRADE]** |
+| `request_prd` / `get_prd` | Ticket backend [BLOCK in jira mode] · VCS **[DEGRADE]** · Code index **[DEGRADE]** |
+| `create_doc` / `get_doc` — `doc_type` ∈ {prd, fsd} | Ticket backend [BLOCK in jira mode] · VCS **[DEGRADE]** · Code index **[DEGRADE]** |
+
+**Estimation:**
+
+| Tool | Dependencies (class) |
+|---|---|
+| `estimate_epic` | Jira **[BLOCK]** (resolves the repo from `jira_ticket_key`); no code-index dep |
+
+### Repository parse / index — VCS
+
+| Tool | Dependencies (class) |
+|---|---|
+| `parse_repository` | VCS **[BLOCK]** (Tier-2; refuses without a VCS connection — it *produces* the index) |
+| `regenerate_directory_map` | VCS **[BLOCK]** (Tier-2) |
+
+### LLM utilities & research
+
+| Tool | Dependencies (class) |
+|---|---|
+| `second_opinion` | — none (pure LLM; repo access only) |
+| `generate_image` | — none beyond an image provider |
+| `visual_diff` | — none (`LOCAL` render + pixel diff; needs a reachable `target_url`) |
+| `request_deep_research` / `get_deep_research` | Deep-research flag **[BLOCK]** (403 if `deep_research_enabled` off) |
+| `request_brainstorm` / `get_brainstorm` | Code index **[BLOCK] for `technical`/`discovery` modes**; **— none for `design` mode** |
+
+### VCS & CI
+
+| Tool | Dependencies (class) |
+|---|---|
+| `create_pull_request` | VCS **[BLOCK]** (Tier-1) |
+| `resolve_ci_checks` | VCS **[BLOCK]** (Tier-1) |
+| `poll_ci_checks` | VCS **[BLOCK]** (Tier-1); also **hidden until `ci_check_config` is resolved** (needs a prior `resolve_ci_checks`) |
+| `materialize_fresh_base` | VCS / git base ref **[BLOCK]** (Tier-1; materializes a pinned base tree) |
+
+### Full-automation (composite)
+
+These orchestrate an idea → ticket → review → start chain, so they inherit the
+**strictest** dependency of every child step.
+
+| Tool | Dependencies (class) |
+|---|---|
+| `run_full_automation` | Ticket backend [BLOCK in jira mode] · VCS **[BLOCK]** · Code index **[BLOCK]** (via child plan/review steps) |
+| `resume_full_automation` | Same as `run_full_automation` |
+
+---
+
+## `pipeline-authoring` profile (5)
+
+Profile-gated **[BLOCK]** to register at all. `run_pipeline` / `resume_pipeline`
+additionally inherit the dependencies of whatever steps the invoked pipeline runs
+(e.g. the `implement-ticket` pipeline pulls in ticket-backend + VCS + code-index deps).
+Run state is persisted via the Bridge API.
+
+| Tool | Dependencies (class) |
+|---|---|
+| `list_pipelines` | Profile-gated **[BLOCK]** |
+| `run_pipeline` | Profile-gated **[BLOCK]** · inherits invoked pipeline's step deps |
+| `resume_pipeline` | Profile-gated **[BLOCK]** · inherits invoked pipeline's step deps |
+| `list_pipeline_runs` | Profile-gated **[BLOCK]** |
+| `delete_pipeline_run` | Profile-gated **[BLOCK]** |
+
+---
+
+## `conductor` profile (8)
+
+Profile-gated **[BLOCK]** to register. Most operate on the **local** conductor ledger
+(`~/.config/bridge/events.db`), so beyond the profile gate they have no remote
+integration dependency.
+
+| Tool | Dependencies (class) |
+|---|---|
+| `emit_event` | Profile-gated **[BLOCK]**; else `LOCAL` ledger |
+| `poll_events` | Profile-gated **[BLOCK]**; else `LOCAL` ledger |
+| `wait_for_event` | Profile-gated **[BLOCK]**; else `LOCAL` ledger |
+| `get_supervisor_snapshot` | Profile-gated **[BLOCK]**; else `LOCAL` ledger |
+| `send_message` | Profile-gated **[BLOCK]**; else `LOCAL` relay |
+| `check_messages` | Profile-gated **[BLOCK]**; else `LOCAL` relay |
+| `get_epic_snapshot` | Profile-gated **[BLOCK]** · Bridge API epic snapshot (Jira epic keys) |
+| `wait_for_done_gate` | Profile-gated **[BLOCK]** · VCS **[BLOCK]** (resolves PR number + head SHA) |
+
+---
+
+## `sfcc` group (20)
+
+### Always-on diagnostics (ship in `core`)
+
+| Tool | Dependencies (class) |
+|---|---|
+| `sfcc_setup_status` | — none (its purpose is to report which SFCC prerequisites are missing) |
+| `check_permissions` | SFCC OCAPI **[BLOCK]** (probes OCAPI; reports not-OK without access / version config) |
+
+### Gated behind the `sfcc` group (18)
+
+All are profile-gated **[BLOCK]** to register, and all require SFCC OCAPI creds +
+`version` config + a reachable sandbox → SFCC OCAPI **[BLOCK]**. Writes are
+sandbox-only and destructive.
+
+**Reads (8):**
+
+| Tool | Dependencies (class) |
+|---|---|
+| `system_object_list` | Profile-gated **[BLOCK]** · SFCC OCAPI **[BLOCK]** |
+| `system_object_get` | Profile-gated **[BLOCK]** · SFCC OCAPI **[BLOCK]** |
+| `system_object_attribute_search` | Profile-gated **[BLOCK]** · SFCC OCAPI **[BLOCK]** |
+| `custom_object_definition_attributes_get` | Profile-gated **[BLOCK]** · SFCC OCAPI **[BLOCK]** |
+| `custom_object_definition_attribute_search` | Profile-gated **[BLOCK]** · SFCC OCAPI **[BLOCK]** |
+| `site_preference_group_list` | Profile-gated **[BLOCK]** · SFCC OCAPI **[BLOCK]** |
+| `site_preference_get` | Profile-gated **[BLOCK]** · SFCC OCAPI **[BLOCK]** |
+| `site_preference_search` | Profile-gated **[BLOCK]** · SFCC OCAPI **[BLOCK]** |
+
+**Writes (9, sandbox-only):**
+
+| Tool | Dependencies (class) |
+|---|---|
+| `system_object_attribute_definition_create` | Profile-gated **[BLOCK]** · SFCC OCAPI write **[BLOCK]** |
+| `system_object_attribute_definition_update` | Profile-gated **[BLOCK]** · SFCC OCAPI write **[BLOCK]** |
+| `system_object_attribute_group_create` | Profile-gated **[BLOCK]** · SFCC OCAPI write **[BLOCK]** |
+| `system_object_attribute_group_update` | Profile-gated **[BLOCK]** · SFCC OCAPI write **[BLOCK]** |
+| `system_object_attribute_assign_to_group` | Profile-gated **[BLOCK]** · SFCC OCAPI write **[BLOCK]** |
+| `custom_preference_definition_create` | Profile-gated **[BLOCK]** · SFCC OCAPI write **[BLOCK]** |
+| `custom_object_definition_attribute_create` | Profile-gated **[BLOCK]** · SFCC OCAPI write **[BLOCK]** |
+| `custom_object_definition_attribute_update` | Profile-gated **[BLOCK]** · SFCC OCAPI write **[BLOCK]** |
+| `site_preference_values_set` | Profile-gated **[BLOCK]** · SFCC OCAPI write **[BLOCK]** |
+
+**Logs (1):**
+
+| Tool | Dependencies (class) |
+|---|---|
+| `sfcc_log_query` | Profile-gated **[BLOCK]** · SFCC WebDAV creds **[BLOCK]** · `sfcc_log_monitor_enabled` **[BLOCK]** · required `environment` scope |
+
+---
+
+## Quick matrix: integration → dependent tools
+
+| Integration | BLOCK without it | DEGRADE without it |
+|---|---|---|
+| **Ticket backend** (jira mode) | `create_ticket`, `get_ticket(s)`, `update_ticket_description`, `update_jira_status`, `get_jira_transitions`, and every AI generator (they read the ticket) | — |
+| **Jira (only)** | `get_comments`, `add_comment`, `attachment`, `estimate_epic` | — |
+| **Version control (VCS)** | `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, `materialize_fresh_base`, `parse_repository`, `regenerate_directory_map`, `wait_for_done_gate`; **Tier-3** `request_plan_generation`/`get_plan`, `request_architecture`/`get_architecture`, `request_reimplement_context`/`get_reimplement_context`, `create_doc`(tdd/architecture) | **Tier-4** `request_clarifying_questions`, `request_ticket_critique`, `request_ticket_review`, `request_prd`, `create_doc`(prd/fsd) |
+| **Code index** (succeeded parse) | Tier-3 plan/architecture/reimplement/`create_doc`(tdd/architecture); `request_brainstorm` in `technical`/`discovery` modes | Tier-4 clarifying-questions/critique/review/prd/fsd |
+| **SFCC OCAPI** | `check_permissions` + all 16 SFCC read/write tools | — |
+| **SFCC WebDAV logs** | `sfcc_log_query` | — |
+| **Deep-research flag** | `request_deep_research`, `get_deep_research` | — |
+| **Profile gating** | all `pipeline-authoring` (5), `conductor` (8), gated `sfcc` (18) tools | — |
+
+## Notes & caveats
+
+- **Refusals are graceful.** VCS/index BLOCKs are enforced by
+  `build_vcs_preflight_refusal_response`; they return a refusal in the route's normal
+  success-class status (e.g. 202 for job-submit routes) rather than a new 4xx/5xx, so a
+  capability gap never looks like a server error.
+- **DEGRADE is deliberately non-fatal.** Tier-4 tools attach a disclosure via
+  `build_vcs_preflight_warning_disclosure`; `plan_researcher` returns empty research on
+  an unindexed repo instead of raising — the same fallback the Tier-3 routes rely on.
+- **Index check fails open.** A transient DB error during the index probe collapses to
+  "available" (blocking an indexed repo on a flaky read is worse than a rare ungrounded
+  generation). Legacy repos parsed before `repository_parse_runs` existed fall back to a
+  `code_repositories` existence check and are not falsely refused.
+- **Ticket-backend default is `jira`.** The seam is fail-safe: any config/DAL problem
+  resolves to `jira`, so a misconfigured repo behaves as jira-mode (and thus BLOCKs
+  without a Jira connection) rather than silently using local.
+- **Baseline is assumed.** A reachable Bridge API + valid API key (and, for AI tools, an
+  LLM provider) underlies everything above and is not listed per tool.