@bridge_gpt/mcp-server 0.2.24 → 0.2.26

package/build/decision-page-template.js

@@ -64,7 +64,11 @@ export function generateDecisionPageHtml(data, assets = DEFAULT_ASSETS) {
     const { ticket_key, actionable_items, clear_improvements } = data;
     const hasDecisions = actionable_items.length > 0;
     const isPlanning = data.artifact_type === "pre_ticket_planning";
-    const needsForm = hasDecisions || (isPlanning && (data.system_goals?.nfrs?.length ?? 0) > 0);
+    // Acceptance criteria and NFRs both render stance controls, and the whole
+    // <script> block is gated on needsForm — so a page carrying either one must set
+    // it, or the radios render with no listeners and no capture loop behind them.
+    const stanceItemCount = (data.system_goals?.nfrs?.length ?? 0) + (data.system_goals?.acceptance_criteria?.length ?? 0);
+    const needsForm = hasDecisions || (isPlanning && stanceItemCount > 0);
     const effectiveLabels = resolveDecisionPageLabels(data.labels);
     const faviconLink = assets.faviconBase64
         ? `<link rel="icon" type="image/png" sizes="32x32" href="data:image/png;base64,${assets.faviconBase64}">`
@@ -437,18 +441,18 @@ ${fontFaces}
       color: var(--text-color);
       white-space: pre-wrap;
     }
-    .nfr-list, .order-list {
+    .nfr-list, .ac-list, .order-list {
       list-style: none;
       padding: 0;
       margin-top: 0.5rem;
     }
-    .nfr-list li, .order-list li {
+    .nfr-list li, .ac-list li, .order-list li {
       padding: 0.75rem 0;
       border-bottom: 1px solid var(--border-color);
     }
-    .nfr-list li:last-child, .order-list li:last-child { border-bottom: none; }
-    .nfr-category { font-weight: 600; }
-    .nfr-implication, .order-meta {
+    .nfr-list li:last-child, .ac-list li:last-child, .order-list li:last-child { border-bottom: none; }
+    .nfr-category, .ac-id { font-weight: 600; }
+    .nfr-implication, .ac-verification, .order-meta {
       font-size: 0.9rem;
       color: var(--secondary-color);
       margin-top: 0.25rem;
@@ -481,20 +485,22 @@ ${fontFaces}
       border-color: var(--primary-color);
       box-shadow: 0 0 0 3px rgba(226, 98, 75, 0.2);
     }
-    .nfr-feedback .comment-area {
+    /* display:block !important deliberately defeats the generic .hidden rule so
+       the max-height transition below can run; .hidden then collapses it. */
+    .nfr-feedback .comment-area, .ac-feedback .comment-area {
       display: block !important;
       overflow: hidden;
       transition: max-height 150ms cubic-bezier(0.4, 0, 0.2, 1),
                   opacity 150ms cubic-bezier(0.4, 0, 0.2, 1),
                   margin-top 150ms cubic-bezier(0.4, 0, 0.2, 1);
     }
-    .nfr-feedback .comment-area.hidden {
+    .nfr-feedback .comment-area.hidden, .ac-feedback .comment-area.hidden {
       max-height: 0;
       opacity: 0;
       margin-top: 0;
       pointer-events: none;
     }
-    .nfr-feedback .radio-group {
+    .nfr-feedback .radio-group, .ac-feedback .radio-group {
       display: flex;
       flex-direction: row;
       gap: 1.5rem;
@@ -508,7 +514,7 @@ ${fontFaces}
         align-items: stretch;
         flex-direction: column;
       }
-      .nfr-feedback .radio-group {
+      .nfr-feedback .radio-group, .ac-feedback .radio-group {
         flex-direction: column;
         gap: 0.75rem;
       }
@@ -583,14 +589,81 @@ function renderNoDecisions(isPlanning = false) {
         <p>${escapeHtml(message)}</p>
       </div>`;
 }
-// Read-only system-goals panel for the pre_ticket_planning artifact. Returns ""
-// when no goals are supplied so the review_decisions page is byte-for-byte
-// unchanged. Every model-supplied string is escaped via escapeHtml().
-// When isPlanning is true, each NFR renders an interactive stance control
-// (Agreed / Ask about this / Disagree) with a conditional comment textarea.
+// Renders the acceptance-criteria list — what the system must do — as the
+// centerpiece of the planning panel, above the NFRs. Returns "" when the list is
+// empty so pages that predate acceptance criteria (plan-epic) are unchanged.
+// When isPlanning is true each criterion carries the same Agreed / Ask about this
+// / Disagree stance control the NFR list uses.
+function renderAcceptanceCriteriaList(acs, isPlanning) {
+    if (acs.length === 0)
+        return "";
+    let items = "";
+    for (let i = 0; i < acs.length; i++) {
+        const ac = acs[i];
+        const statusClass = ac.status === "confirmed"
+            ? "status-confirmed"
+            : ac.status === "assumed"
+                ? "status-assumed"
+                : "status-open";
+        // acId is used as data-ac-id (becomes the JSON output key) and aria-label.
+        // acHtmlId is a whitespace-free variant for id/name/for attributes — HTML5
+        // forbids spaces in id values. The loop index i prefixes the radio/textarea
+        // identifiers so each criterion is its own radio group, mirroring the NFR
+        // list's disambiguation: without it, two ids that collapse to the same slug
+        // would share a name and clobber each other's selection.
+        const acId = escapeHtml(ac.id);
+        const acHtmlId = escapeHtml(ac.id.replace(/\s+/g, "-"));
+        const radioName = `ac-stance-${i}-${acHtmlId}`;
+        const textareaId = `ac-comment-${i}-${acHtmlId}`;
+        const stanceControls = isPlanning ? `
+              <div class="ac-feedback" data-ac-id="${acId}">
+                <div class="radio-group" role="radiogroup" aria-label="Stance on ${acId}">
+                  <div class="radio-option">
+                    <input type="radio" id="${radioName}-agreed" name="${radioName}" value="agreed" checked data-testid="ac-stance-radio">
+                    <label for="${radioName}-agreed">Agreed</label>
+                  </div>
+                  <div class="radio-option">
+                    <input type="radio" id="${radioName}-ask" name="${radioName}" value="ask" data-testid="ac-stance-radio">
+                    <label for="${radioName}-ask">Ask about this</label>
+                  </div>
+                  <div class="radio-option">
+                    <input type="radio" id="${radioName}-disagree" name="${radioName}" value="disagree" data-testid="ac-stance-radio">
+                    <label for="${radioName}-disagree">Disagree</label>
+                  </div>
+                </div>
+                <div class="comment-area hidden">
+                  <label for="${textareaId}">Comment</label>
+                  <textarea id="${textareaId}" name="${textareaId}" placeholder="Explain your question or concern..." data-testid="ac-comment"></textarea>
+                </div>
+              </div>` : "";
+        items += `
+            <li data-testid="system-goal-ac" data-status="${escapeHtml(ac.status)}">
+              <span class="ac-id">${escapeHtml(ac.id)}</span><span class="status-tag ${statusClass}">${escapeHtml(ac.status)}</span>
+              <div class="goal-body">${escapeHtml(ac.criterion)}</div>
+              <div class="ac-verification">Verify: ${escapeHtml(ac.verification)}</div>${stanceControls}
+            </li>`;
+    }
+    return `
+          <div class="goal-label">Acceptance criteria</div>
+          <ul class="ac-list">${items}
+          </ul>`;
+}
+// System-goals panel for the pre_ticket_planning artifact. Returns "" when no
+// goals are supplied so the review_decisions page is byte-for-byte unchanged.
+// Every model-supplied string is escaped via escapeHtml().
+// When isPlanning is true, each acceptance criterion and each NFR renders an
+// interactive stance control (Agreed / Ask about this / Disagree) with a
+// conditional comment textarea.
 function renderSystemGoals(goals, isPlanning = false) {
     if (!goals)
         return "";
+    const acceptanceCriteria = goals.acceptance_criteria ?? [];
+    const acHtml = renderAcceptanceCriteriaList(acceptanceCriteria, isPlanning);
+    // The heading leads with acceptance criteria only when there are some. Pages
+    // that carry goals + NFRs alone (plan-epic) keep the original heading.
+    const sectionHeading = acceptanceCriteria.length > 0
+        ? "Acceptance Criteria &amp; System Goals"
+        : "System Goals &amp; Non-Functional Requirements";
     const nfrs = goals.nfrs ?? [];
     let nfrHtml = "";
     if (nfrs.length > 0) {
@@ -647,7 +720,7 @@ function renderSystemGoals(goals, isPlanning = false) {
           </ul>`;
     }
     return `      <section class="planning-section" data-testid="system-goals">
-      <h2>System Goals &amp; Non-Functional Requirements</h2>
+      <h2>${sectionHeading}</h2>
       <div class="goal-row">
         <div class="goal-label">Business goal</div>
         <div class="goal-body" data-testid="system-goal-business">${escapeHtml(goals.business_goal)}</div>
@@ -659,7 +732,7 @@ function renderSystemGoals(goals, isPlanning = false) {
       <div class="goal-row">
         <div class="goal-label">System behavior</div>
         <div class="goal-body" data-testid="system-goal-behavior">${escapeHtml(goals.system_behavior)}</div>
-      </div>${nfrHtml}
+      </div>${acHtml}${nfrHtml}
       </section>`;
 }
 // Read-only recommended implementation order (epic surfaces). Returns "" when the
@@ -853,9 +926,11 @@ function renderScript(data, isPlanning = false) {
         postSubmitContainer = document.getElementById("post-submit-container");
         jsonOutput = document.getElementById("json-output");
 
-        ${isPlanning ? `// NFR stance radio disclosure (planning mode only)
-        var nfrContainers = document.querySelectorAll(".nfr-feedback");
-        nfrContainers.forEach(function(container) {
+        ${isPlanning ? `// Stance radio disclosure (planning mode only). Acceptance criteria and
+        // NFRs behave identically here, so they share one listener set; only the
+        // capture step below distinguishes them, since their JSON keys differ.
+        var stanceContainers = document.querySelectorAll(".nfr-feedback, .ac-feedback");
+        stanceContainers.forEach(function(container) {
           var radios = container.querySelectorAll('input[type="radio"]');
           radios.forEach(function(radio) {
             radio.addEventListener("change", function() {
@@ -874,7 +949,7 @@ function renderScript(data, isPlanning = false) {
               }
             });
           });
-        });` : `var nfrContainers = [];`}
+        });` : `var stanceContainers = [];`}
 
         submitBtn.addEventListener("click", function() {
           var cards = document.querySelectorAll(".card[data-item-id]");
@@ -909,8 +984,8 @@ function renderScript(data, isPlanning = false) {
             }
           });
 
-          // Validate NFR feedback: ask/disagree stance requires a comment.
-          nfrContainers.forEach(function(container) {
+          // Validate stance feedback: ask/disagree requires a comment.
+          stanceContainers.forEach(function(container) {
             var selected = container.querySelector('input[type="radio"]:checked');
             if (!selected) return;
             if (selected.value === "ask" || selected.value === "disagree") {
@@ -957,22 +1032,29 @@ function renderScript(data, isPlanning = false) {
             };
           });
 
-          ${isPlanning ? `// Capture NFR feedback stances
-          var nfrFeedback = {};
-          nfrContainers.forEach(function(container) {
-            var nfrId = container.getAttribute("data-nfr-id");
-            var selected = container.querySelector('input[type="radio"]:checked');
-            var commentArea = container.querySelector(".comment-area");
-            var textarea = commentArea ? commentArea.querySelector("textarea") : null;
-            nfrFeedback[nfrId] = {
-              stance: selected ? selected.value : "agreed",
-              comment: textarea ? textarea.value : ""
-            };
-          });` : ""}
+          ${isPlanning ? `// Capture stances. Acceptance criteria and NFRs land in separate maps
+          // because their keys differ: AC are keyed by id, NFRs by category.
+          function captureStances(selector, idAttr) {
+            var out = {};
+            document.querySelectorAll(selector).forEach(function(container) {
+              var key = container.getAttribute(idAttr);
+              var selected = container.querySelector('input[type="radio"]:checked');
+              var commentArea = container.querySelector(".comment-area");
+              var textarea = commentArea ? commentArea.querySelector("textarea") : null;
+              out[key] = {
+                stance: selected ? selected.value : "agreed",
+                comment: textarea ? textarea.value : ""
+              };
+            });
+            return out;
+          }
+          var acceptanceCriteriaFeedback = captureStances(".ac-feedback", "data-ac-id");
+          var nfrFeedback = captureStances(".nfr-feedback", "data-nfr-id");` : ""}
 
           var output = {
             ticket_key: ${safeJsonForScript(data.ticket_key)},
             decisions: decisions,
+            ${isPlanning ? "acceptance_criteria_feedback: acceptanceCriteriaFeedback," : ""}
             ${isPlanning ? "nfr_feedback: nfrFeedback," : ""}
             general_comment: document.getElementById("general-comment").value
           };

package/build/docs.generated.js

@@ -1,5 +1,6 @@
 // AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
 // This file is produced by scripts/bundle-docs.js
 export const DOCS = {
-    "docs/mcp-tool-integrations.md": "# MCP tool integrations — the human \"why\" behind the capability report\n\nThis catalog is **explanatory prose only**. It exists so the `/install-bridge`\ncapability report can cite a human-readable \"why\" for each gate. It is **not** a\nsource of truth for gating: the server computes every `locked_tools` /\n`unlocked_tools` membership decision itself and the agent must never recompute a\ntool's dependencies from this document.\n\n**Authoritative source of gating.** The enforced rules — which tools are blocked,\nwhich are degraded, and what each requires — live in\n`api/library/vcs/vcs_route_operations.py`:\n\n- `VCS_ROUTE_REQUIREMENTS` — routes that **BLOCK** (are unavailable) without a\n  VCS connection.\n- `VCS_ROUTE_WARNINGS` — routes that **DEGRADE** (stay usable, but without\n  codebase context) without a VCS connection.\n- `NEVER_GATED_ROUTE_KEYS` — routes that are never gated on any integration.\n- `INDEX_REQUIRED_ROUTE_KEYS`, `INDEX_REQUIRED_BRAINSTORM_MODES`,\n  `CREATE_DOC_CODEBASE_CONTEXT_DOC_TYPES`, `CREATE_DOC_WARN_DOC_TYPES` — the\n  conditional \"requires a successful code index\" dimension.\n- The resolver helpers `get_required_vcs_operation()`, `get_warn_vcs_operation()`,\n  and `requires_successful_index()` are the authoritative functions that decide a\n  case. The capability report is derived from these; this catalog explains them.\n\n## Reading the capability report\n\nEach tool entry the server returns has the exact shape\n`{tool, effect, missing, semantics}`:\n\n- **`effect`**\n  - **`BLOCK`** — the tool is **unavailable** until every listed dependency is\n    met. It will refuse to run without them.\n  - **`DEGRADE`** — the tool is **usable right now**, but **without codebase\n    context** (it cannot ground its output in your repository). Connecting the\n    listed dependency upgrades it from \"works blind\" to \"works with full context\".\n    A `DEGRADE` tool is never \"failed\".\n- **`missing`** — the server-computed dependency identifiers still needed:\n  integration ids such as `github_app` / `vcs_access_token`, and the synthetic\n  `code_index` (a successful repository index).\n- **`semantics`**\n  - **`all_of`** — every id in `missing` is required.\n  - **`any_of`** — the VCS-provider candidates in `missing` are alternatives:\n    **either** `github_app` **or** `vcs_access_token` satisfies the VCS\n    requirement (this is the \"provider unknown\" case). When `code_index` also\n    appears, it remains separately required — `semantics` describes only the VCS\n    provider candidates, and a code index is always mandatory in addition.\n\nThe three readiness dimensions `configured` / `learned` / `indexed` are reported\nindependently. `indexed` may be `true`, `false`, or `null` — a `null` means the\nindex status could not be confirmed and must **not** be read as \"indexed\".\n\n## The integrations\n\n| Integration id | What it is | What it unlocks |\n| --- | --- | --- |\n| `jira` | Jira API access | Ticket reads/writes, estimation and review automations, status transitions. |\n| `github_app` | GitHub App installation | Pull requests, code review, and private-repo parsing on GitHub projects. |\n| `vcs_access_token` | VCS access token | Pull requests, code review, and private-repo parsing on Bitbucket projects. |\n| `vcs_webhook` | VCS webhook secret | Merge webhooks and CI follow-up triggers. |\n| `code_index` | A successful repository index | Codebase-grounded planning, architecture, reimplementation, and technical/discovery brainstorms. Produced by `/parse-repository`. |\n\nA project's `github_app` **or** `vcs_access_token` provides the VCS connection;\nwhich one applies depends on the project's version-control system. When the\nproject's provider is unknown, either credential satisfies the requirement — the\nreport expresses that as `semantics: any_of`.\n\n## The gates, by capability\n\n### Pull requests and CI (BLOCK on VCS)\n\nTools like `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, and\n`materialize_fresh_base` are **unavailable** (`BLOCK`) until a VCS connection is\nconfigured. They act directly on the version-control host, so without a\nconnection there is nothing for them to talk to.\n\n### Repository indexing and maps (BLOCK on VCS)\n\n`parse_repository` and `regenerate_directory_map` need a VCS connection to read\nthe repository. They **BLOCK** until VCS is connected.\n\n### Codebase-grounded generation (BLOCK on VCS **and** a code index)\n\nPlanning and architecture tools — `generate_plan_direct`,\n`generate_architecture_direct`, `request_reimplement_context`,\n`code_writer_generate_plan`, `code_writer_generate_architecture`, and\n`create_doc` for **TDD** / **architecture** documents — ground their output in\nyour indexed codebase. They **BLOCK** until BOTH a VCS connection AND a\nsuccessful code index exist (`all_of`, with `code_index` in `missing`).\n\n### Brainstorms (BLOCK on a code index, mode-dependent)\n\n`request_brainstorm` in **technical** or **discovery** mode searches your indexed\ncodebase, so it **BLOCK**s on `code_index`. **Design**-mode brainstorming never\nqueries the index and is never gated.\n\n### Document generation that DEGRADEs (usable without codebase context)\n\nTools like `generate_prd_direct`, `generate_fsd_direct`,\n`code_writer_generate_fsd`, `generate_clarifying_questions_direct`,\n`generate_ticket_critique_direct`, `generate_ticket_review_direct`, and\n`create_doc` for **PRD** / **FSD** documents **DEGRADE** rather than block: they\nrun today from the ticket alone, and connecting VCS simply lets them ground their\noutput in your codebase. They always appear under \"Tools you can use now\", with a\nreduced-context caveat when the VCS connection is missing.\n\n### Never gated\n\nSetup and bootstrap tools (`ping`, `config_field`, `get_install_manifest`,\n`apply_install_manifest`, `get_my_role`, `persist_routing_credential`,\n`get_docs_dir`, and the bootstrap-invite exchange) are always available — they\nare how you configure everything else.\n"
+    "docs/mcp-tool-integrations.md": "# MCP tool integrations — the human \"why\" behind the capability report\n\nThis catalog is **explanatory prose only**. It exists so the `/install-bridge`\ncapability report can cite a human-readable \"why\" for each gate. It is **not** a\nsource of truth for gating: the server computes every `locked_tools` /\n`unlocked_tools` membership decision itself and the agent must never recompute a\ntool's dependencies from this document.\n\n**Authoritative source of gating.** The enforced rules — which tools are blocked,\nwhich are degraded, and what each requires — live in\n`api/library/vcs/vcs_route_operations.py`:\n\n- `VCS_ROUTE_REQUIREMENTS` — routes that **BLOCK** (are unavailable) without a\n  VCS connection.\n- `VCS_ROUTE_WARNINGS` — routes that **DEGRADE** (stay usable, but without\n  codebase context) without a VCS connection.\n- `NEVER_GATED_ROUTE_KEYS` — routes that are never gated on any integration.\n- `INDEX_REQUIRED_ROUTE_KEYS`, `INDEX_REQUIRED_BRAINSTORM_MODES`,\n  `CREATE_DOC_CODEBASE_CONTEXT_DOC_TYPES`, `CREATE_DOC_WARN_DOC_TYPES` — the\n  conditional \"requires a successful code index\" dimension.\n- The resolver helpers `get_required_vcs_operation()`, `get_warn_vcs_operation()`,\n  and `requires_successful_index()` are the authoritative functions that decide a\n  case. The capability report is derived from these; this catalog explains them.\n\n## Reading the capability report\n\nEach tool entry the server returns has the exact shape\n`{tool, effect, missing, semantics}`:\n\n- **`effect`**\n  - **`BLOCK`** — the tool is **unavailable** until every listed dependency is\n    met. It will refuse to run without them.\n  - **`DEGRADE`** — the tool is **usable right now**, but **without codebase\n    context** (it cannot ground its output in your repository). Connecting the\n    listed dependency upgrades it from \"works blind\" to \"works with full context\".\n    A `DEGRADE` tool is never \"failed\".\n- **`missing`** — the server-computed dependency identifiers still needed:\n  integration ids such as `github_app` / `vcs_access_token`, and the synthetic\n  `code_index` (a successful repository index).\n- **`semantics`**\n  - **`all_of`** — every id in `missing` is required.\n  - **`any_of`** — the VCS-provider candidates in `missing` are alternatives:\n    **either** `github_app` **or** `vcs_access_token` satisfies the VCS\n    requirement (this is the \"provider unknown\" case). When `code_index` also\n    appears, it remains separately required — `semantics` describes only the VCS\n    provider candidates, and a code index is always mandatory in addition.\n\nThe three readiness dimensions `configured` / `learned` / `indexed` are reported\nindependently. `indexed` may be `true`, `false`, or `null` — a `null` means the\nindex status could not be confirmed and must **not** be read as \"indexed\".\n\n## The integrations\n\n| Integration id | What it is | What it unlocks |\n| --- | --- | --- |\n| `jira` | Jira API access | Ticket reads/writes, estimation and review automations, status transitions. |\n| `github_app` | GitHub App installation | Pull requests, code review, and private-repo parsing on GitHub projects. |\n| `vcs_access_token` | VCS access token | Pull requests, code review, and private-repo parsing on Bitbucket projects. |\n| `vcs_webhook` | VCS webhook secret | Merge webhooks and CI follow-up triggers. |\n| `code_index` | A successful repository index | Codebase-grounded planning, architecture, reimplementation, and technical/discovery brainstorms. Produced by `/parse-repository`. |\n\nA project's `github_app` **or** `vcs_access_token` provides the VCS connection;\nwhich one applies depends on the project's version-control system. When the\nproject's provider is unknown, either credential satisfies the requirement — the\nreport expresses that as `semantics: any_of`.\n\n## The gates, by capability\n\n### Pull requests and CI (BLOCK on VCS)\n\nTools like `create_pull_request`, `resolve_ci_checks`, `poll_ci_checks`, and\n`materialize_fresh_base` are **unavailable** (`BLOCK`) until a VCS connection is\nconfigured. They act directly on the version-control host, so without a\nconnection there is nothing for them to talk to.\n\n### Repository indexing and maps (BLOCK on VCS)\n\n`parse_repository` and `regenerate_directory_map` need a VCS connection to read\nthe repository. They **BLOCK** until VCS is connected.\n\n### Codebase-grounded generation (BLOCK on VCS **and** a code index)\n\nPlanning and architecture tools — `generate_plan_direct`,\n`generate_architecture_direct`, `request_reimplement_context`,\n`code_writer_generate_plan`, `code_writer_generate_architecture`, and\n`create_doc` for **TDD** / **architecture** documents — ground their output in\nyour indexed codebase. They **BLOCK** until BOTH a VCS connection AND a\nsuccessful code index exist (`all_of`, with `code_index` in `missing`).\n\n### Council (BLOCK on a code index, mode-dependent)\n\n`request_council` in **technical** or **discovery** mode searches your indexed\ncodebase, so it **BLOCK**s on `code_index`. **Design**-mode brainstorming never\nqueries the index and is never gated.\n\n### Document generation that DEGRADEs (usable without codebase context)\n\nTools like `generate_prd_direct`, `generate_fsd_direct`,\n`code_writer_generate_fsd`, `generate_clarifying_questions_direct`,\n`generate_ticket_critique_direct`, `generate_ticket_review_direct`, and\n`create_doc` for **PRD** / **FSD** documents **DEGRADE** rather than block: they\nrun today from the ticket alone, and connecting VCS simply lets them ground their\noutput in your codebase. They always appear under \"Tools you can use now\", with a\nreduced-context caveat when the VCS connection is missing.\n\n### Never gated\n\nSetup and bootstrap tools (`ping`, `config_field`, `get_install_manifest`,\n`apply_install_manifest`, `get_my_role`, `persist_routing_credential`,\n`get_docs_dir`, and the bootstrap-invite exchange) are always available — they\nare how you configure everything else.\n",
+    "docs/install/sfcc-integration.md": "# Installing the SFCC Integration (OCAPI)\n\nBridge's Salesforce B2C Commerce (SFCC) tools give an AI coding agent read access to\na sandbox's object model, custom object definitions, and site preferences — plus a\nsmall set of sandbox-only writes — through the **OCAPI Data API**. This guide covers\nsetting up the OCAPI client that those tools authenticate against.\n\n> **Sandbox / local development only.** This integration is intended for a **developer\n> sandbox**. The tools reject non-sandbox instances, and the permissions grant below is\n> deliberately broad (all methods, all resources) — appropriate for a throwaway dev\n> sandbox, **never** for staging or production. Do not configure this grant on any\n> instance that holds real data. Credentials stay local (in `dw.json` or `SFCC_*` env\n> vars) and are never sent to Bridge.\n\nFor the full per-tool list and what each SFCC tool depends on, see\n[MCP Tool Integration Dependencies](./mcp-tool-integrations.md). For the tool reference\nand the `BRIDGE_MCP_PROFILE` gating, see the SFCC section of the\n[package README](../../README.md).\n\n## Prerequisites\n\n- A running SFCC **developer sandbox** and its hostname\n  (e.g. `zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com`).\n- An **Account Manager API client** — a `client-id` and `client-secret`. This is the\n  OCAPI client the tools use to obtain an OAuth token. Create one in Account Manager\n  (**API Client** → *Add API Client*) if you don't already have it, and note its\n  `client_id`.\n- Business Manager access to the sandbox with permission to edit **Open Commerce API\n  Settings**.\n\n## 1. Grant the OCAPI client access in Business Manager\n\nIn Business Manager for the sandbox:\n\n**Administration → Site Development → Open Commerce API Settings → Data API** tab.\n\nAdd the following client entry to the `clients` array of the Data API settings, then\n**Save**. This grants the client full read/write access to every Data API resource —\nacceptable only on a developer sandbox:\n\n```json\n{\n  \"client_id\": \"<your-client-id-here>\",\n  \"resources\": [\n    {\n      \"methods\": [\"get\", \"post\", \"put\", \"patch\", \"delete\"],\n      \"read_attributes\": \"(**)\",\n      \"write_attributes\": \"(**)\",\n      \"resource_id\": \"/**\"\n    }\n  ]\n}\n```\n\nNotes:\n\n- The `client_id` **must match** the Account Manager API client whose credentials you\n  put in `dw.json` / `SFCC_*` below. Replace the value above with your own client id if\n  it differs.\n- If the Data API settings are empty, wrap the entry in the standard settings envelope:\n\n  ```json\n  {\n    \"_v\": \"23.2\",\n    \"clients\": [\n      {\n        \"client_id\": \"<your-client-id-here>\",\n        \"resources\": [\n          {\n            \"methods\": [\"get\", \"post\", \"put\", \"patch\", \"delete\"],\n            \"read_attributes\": \"(**)\",\n            \"write_attributes\": \"(**)\",\n            \"resource_id\": \"/**\"\n          }\n        ]\n      }\n    ]\n  }\n  ```\n\n- `check_permissions` (below) prints a ready-to-paste grant JSON on a 401/403, so you can\n  also let the tool tell you exactly what to add.\n\n## 2. Provide credentials locally\n\nCreate a `dw.json` in your project root (auto-added to git exclude — never commit it):\n\n```json\n{\n  \"hostname\": \"zzzz-001.sandbox.us01.dx.commercecloud.salesforce.com\",\n  \"client-id\": \"<your-client-id-here>\",\n  \"client-secret\": \"<account-manager-client-secret>\"\n}\n```\n\nAccepted key spellings: `hostname`/`host`, `client-id`/`clientId`/`client_id`,\n`client-secret`/`clientSecret`/`client_secret`. Prefer a single config — a multi-entry\n`configs[]` array forces an explicit `instance` on every call. Alternatively, export\n`SFCC_HOSTNAME` / `SFCC_CLIENT_ID` / `SFCC_CLIENT_SECRET` in the MCP server environment.\n\n## 3. Set the repo `version` config field\n\nSet the repo's `version` config to your SFCC project type — one of\n`sfra | pwakit | sitegenesis | storefrontnext | hybrid`. The call-time gate reads this;\na non-SFCC value blocks every SFCC tool except `sfcc_setup_status`. Set it via your\nnormal config path, the `config_field` MCP tool (operation `update`, field `version`),\nor the `/teach-bridge` skill.\n\n## 4. Enable the SFCC tools\n\nThe two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always\nregistered. The read tools, write tools, and `sfcc_log_query` are gated behind the\n`sfcc` profile. Add `sfcc` to `BRIDGE_MCP_PROFILE` in the MCP server `env` block (it is\ncomma-separated; `full` also works), then **restart the MCP client**:\n\n```json\n\"env\": { \"BRIDGE_MCP_PROFILE\": \"sfcc\" }\n```\n\n## 5. Verify\n\nAsk your agent to run:\n\n1. `sfcc_setup_status` — expect all prerequisite checks ✓ (Bridge API key, repo name,\n   `version` config, `dw.json` presence/uniqueness, AM/OCAPI token acquisition).\n2. `check_permissions` — probes OCAPI via `GET /system_object_definitions`. A 200 (with\n   the OCAPI version) confirms the grant. On 401/403 it prints the exact grant JSON to\n   paste back in step 1.\n\nRestart the MCP client after any credential, grant, or env change — a running session\ndoes not pick them up.\n\n## Notes\n\n- **WebDAV logs are separate.** `sfcc_log_query` authenticates with a Business Manager\n  username + a 40-character **WebDAV access key** over HTTP Basic auth — *not* the OCAPI\n  OAuth token configured here. `sfcc_setup_status` reports OCAPI (step 5) and WebDAV\n  (step 6) independently; one can be green while the other is not.\n- **Writes are sandbox-only.** The write tools (attribute/preference create/update) target\n  a developer sandbox and echo a paste-ready grant JSON on a 403.\n"
 };

package/build/doctor.js

@@ -20,7 +20,11 @@ import os from "os";
 import path from "path";
 import { createDefaultStartTicketsDeps } from "./start-tickets.js";
 import { VERSION } from "./version.generated.js";
-import { collectInstallStatusChecks, formatInstallStatusReport, } from "./install-doctor.js";
+import { collectInstallStatusChecks, formatInstallStatusReport, resolveInstallDoctorTarget, } from "./install-doctor.js";
+import { parseDefaultOnEnvFlag } from "./env-flags.js";
+import { createBridgeApiUrls } from "./bridge-api-urls.js";
+import { probeToolSurface } from "./tool-surface-gating.js";
+import { resolveBapiCredentials } from "./credential-store.js";
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
 import { getDoctorPrereqDescriptors, probePrerequisite, } from "./start-tickets-prereqs.js";
 import { resolveProfiles } from "./mcp-profile.js";
@@ -51,6 +55,14 @@ export function getDoctorUsage() {
         "bootstrap-field completeness, and repository-indexing state. It performs",
         "read-only GETs only and never affects the exit code.",
         "",
+        "It also includes an advisory 'MCP tool surface' section (BAPI-641): what",
+        "dynamic capability gating would advertise for this repo. It performs at most",
+        "one read-only GET to /jira/mcp/tool-surface (none under the kill switch) and",
+        "is advisory/fail-open — a timeout or malformed response is reported as",
+        "'fail-open to full surface' and never affects the exit code. Clients that",
+        "ignore notifications/tools/list_changed must reconnect or start a new MCP",
+        "session to observe surface changes; no project MCP config change is required.",
+        "",
         "Conductor ledger / native-module diagnostics (the SQLite ledger's native",
         "binding load status and Node-version skew) live under a separate command:",
         "  conductor doctor",
@@ -363,6 +375,111 @@ export function formatLauncherCacheReport(inspections) {
     }
     return lines.join("\n");
 }
+/**
+ * Collect the read-only tool-surface diagnostic. Evaluates the kill switch first
+ * and returns without any network request when disabled. For an enabled flag and
+ * a resolved repo/credential, performs ONE 500 ms `probeToolSurface()` GET to the
+ * deployed route. Credential values live ONLY in the request headers and never in
+ * the returned result. Never throws.
+ */
+export async function collectToolSurfaceDiagnostic(deps) {
+    const enabled = parseDefaultOnEnvFlag(deps.env.BAPI_MCP_TOOL_SURFACE_GATING_ENABLED);
+    if (!enabled) {
+        return { enabled: false, reason: "kill-switch" };
+    }
+    const target = await resolveInstallDoctorTarget(deps);
+    if (!target.repoName) {
+        return {
+            enabled: true,
+            reason: "unresolved",
+            detail: "no BAPI_REPO_NAME in the environment or project-local MCP configs",
+        };
+    }
+    const credDeps = {
+        env: deps.env,
+        homedir: deps.homedir,
+        platform: deps.platform,
+        readFile: deps.readFile,
+        stat: deps.stat,
+        stderr: () => { },
+    };
+    const cred = await resolveBapiCredentials(target.repoName, credDeps);
+    if (!cred.ok) {
+        return {
+            enabled: true,
+            reason: "unresolved",
+            detail: `no Bridge API credential resolved (${cred.kind})`,
+        };
+    }
+    const apiKey = cred.credentials.apiKey;
+    const urls = createBridgeApiUrls(target.baseUrl);
+    const url = urls.buildGetUrl("/mcp/tool-surface", {
+        repo_name: target.repoName,
+    });
+    const result = await probeToolSurface({
+        url,
+        resolveHeaders: async () => ({ "X-API-Key": apiKey }),
+        fetchFn: deps.fetch,
+    });
+    if (result.reason === "blocked") {
+        return {
+            enabled: true,
+            reason: "blocked",
+            blockedTools: Array.from(result.blockedTools),
+            catalogRevision: result.catalogRevision,
+            evaluatedToolCount: result.evaluatedToolCount,
+        };
+    }
+    if (result.reason === "timeout") {
+        return { enabled: true, reason: "timeout" };
+    }
+    return { enabled: true, reason: "malformed", subtype: result.subtype };
+}
+/**
+ * Render the advisory "MCP tool surface" section (pure formatting — no probing).
+ * States the kill-switch state, probe reachability, decision reason/subtype,
+ * fail-open behavior when applicable, blocked IDs/count/revision for a valid
+ * response, and clarifies that blocked IDs are intersected with the locally
+ * active profile and SDK-enabled baseline only when an MCP session starts.
+ */
+export function formatToolSurfaceDiagnosticReport(diag) {
+    const lines = ["", "MCP tool surface (dynamic capability gating — advisory)", ""];
+    lines.push(`Kill switch: ${diag.enabled ? "ENABLED (gating active)" : "DISABLED (full surface)"}`);
+    switch (diag.reason) {
+        case "kill-switch":
+            lines.push("Reason: kill-switch — BAPI_MCP_TOOL_SURFACE_GATING_ENABLED is off, so the full profile surface is advertised and no probe is performed.");
+            break;
+        case "unresolved":
+            lines.push(`Reason: unresolved — ${diag.detail ?? "repo/credential not resolved"}; the probe was skipped and the full surface is advertised (fail-open to full surface).`);
+            break;
+        case "blocked": {
+            const ids = diag.blockedTools ?? [];
+            lines.push("Reason: blocked — the backend returned a valid capability decision.");
+            lines.push(`Probe: reachable (HTTP 200, valid response).`);
+            lines.push(`Blocked tools (${ids.length}): [${ids.join(", ")}]`);
+            if (diag.catalogRevision)
+                lines.push(`Catalog revision: ${diag.catalogRevision}`);
+            if (typeof diag.evaluatedToolCount === "number") {
+                lines.push(`Evaluated tool count: ${diag.evaluatedToolCount}`);
+            }
+            break;
+        }
+        case "timeout":
+            lines.push("Reason: timeout — the 500 ms probe deadline elapsed; fail-open to full surface.");
+            break;
+        case "malformed":
+            lines.push(`Reason: malformed (${diag.subtype ?? "unknown"}) — fail-open to full surface.`);
+            break;
+    }
+    lines.push("");
+    lines.push("Blocked IDs are intersected with the locally active MCP profile and the current SDK-enabled");
+    lines.push("baseline only when an MCP session starts, so IDs unknown to this package or excluded by the");
+    lines.push("active profile have no effect. Capability-hidden tools remain registered and callable — the");
+    lines.push("backend is the enforcement boundary. This section is advisory and never changes the exit code.");
+    lines.push("Clients that ignore notifications/tools/list_changed must reconnect or start a new MCP session");
+    lines.push("to observe surface changes; no project MCP configuration change is required.");
+    return lines.join("\n");
+}
 /**
  * CLI entry for the read-only `doctor` subcommand. Returns a process exit code.
  * Help returns 0; parser errors return 1; otherwise it prints the report and
@@ -429,6 +546,36 @@ export async function runDoctorCli(argv, overrides = {}) {
             /* install-status diagnostics are advisory; never block the doctor report */
         }
     }
+    // Advisory MCP tool-surface capability section (BAPI-641). Strictly read-only:
+    // one 500 ms GET (or none, under the kill switch). Any timeout, malformed
+    // response, or unexpected throw degrades to a "fail-open to full surface" line
+    // and never affects the exit code, exactly like install-status above.
+    if (overrides.toolSurface !== false) {
+        try {
+            const injectedFs = deps;
+            const toolSurfaceDeps = {
+                env: overrides.toolSurface?.env ?? deps.env,
+                cwd: overrides.toolSurface?.cwd ?? deps.cwd,
+                platform: overrides.toolSurface?.platform ?? deps.platform,
+                homedir: overrides.toolSurface?.homedir ?? injectedFs.homedir ?? os.homedir,
+                readFile: overrides.toolSurface?.readFile ??
+                    injectedFs.readFile ??
+                    ((p) => readFile(p, "utf-8")),
+                stat: overrides.toolSurface?.stat ?? injectedFs.stat ?? ((p) => stat(p)),
+                fetch: overrides.toolSurface?.fetch ?? ((...args) => fetch(...args)),
+            };
+            const diagnostic = await collectToolSurfaceDiagnostic(toolSurfaceDeps);
+            log(formatToolSurfaceDiagnosticReport(diagnostic));
+        }
+        catch {
+            // Any unexpected failure still degrades to a sanitized advisory section.
+            log(formatToolSurfaceDiagnosticReport({
+                enabled: parseDefaultOnEnvFlag(deps.env.BAPI_MCP_TOOL_SURFACE_GATING_ENABLED),
+                reason: "malformed",
+                subtype: "unexpected",
+            }));
+        }
+    }
     if (!collection.ok)
         return 1;
     return collection.results.some((r) => !r.found) ? 1 : 0;

package/build/env-flags.js

@@ -0,0 +1,31 @@
+/**
+ * env-flags — shared parsing for default-ON boolean environment flags.
+ *
+ * Extracted from `index.ts` (BAPI-641) so normal server startup and the
+ * `doctor` diagnostic share ONE implementation of the default-on semantics.
+ * A default-on flag is enabled unless explicitly set to a recognized off-token,
+ * so an unknown value fails OPEN (enabled) rather than silently disabling a
+ * feature.
+ */
+/** The recognized, case-insensitive off-tokens for a default-on flag. */
+const OFF_TOKENS = new Set([
+    "false",
+    "0",
+    "no",
+    "off",
+    "disabled",
+]);
+/**
+ * Parse a default-ON boolean env flag. `undefined` / blank → true; the
+ * normalized off-tokens (`false`, `0`, `no`, `off`, `disabled`) → false; any
+ * other value → true (preserving default-on / fail-open behavior). Matching is
+ * case-insensitive and trims surrounding whitespace.
+ */
+export function parseDefaultOnEnvFlag(value) {
+    if (value === undefined)
+        return true;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "")
+        return true;
+    return !OFF_TOKENS.has(normalized);
+}