@bridge_gpt/mcp-server 0.2.38 → 0.2.41

package/build/start-tickets-prereqs.js

@@ -18,7 +18,7 @@ import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./creden
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { probeWorktreeMcpRegistration } from "./mcp-registration-doctor.js";
 import { probeWorktreeCommandAssets } from "./command-assets-doctor.js";
-import { CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING_ENV, formatClaudeMcpShadowFinding, formatClaudeUserConfigDiagnostic, inspectClaudeUserConfigForMcpShadowing, resolveClaudeUserConfigPath, } from "./claude-user-config-doctor.js";
+import { CLAUDE_MCP_SHADOWING_REMEDIATION_COMMAND, formatClaudeMcpShadowFinding, formatClaudeUserConfigDiagnostic, inspectClaudeUserConfigForMcpShadowing, resolveClaudeUserConfigPath, } from "./claude-user-config-doctor.js";
 // ---------------------------------------------------------------------------
 // Constants (moved here from start-tickets.ts so both consumers share them)
 // ---------------------------------------------------------------------------
@@ -531,12 +531,11 @@ export async function resolveMainWorktreePathForDoctor(deps) {
  * which is why the advice below is phrased as "delete, or move aside". Keep every
  * such identifier out of this file, even inside a comment like this one.
  */
-const CLAUDE_MCP_SHADOWING_HINT = "Delete, or move aside, the 'bridge-api' MCP registration in ~/.claude.json (at user scope, " +
-    "or under the projects entry for this repository/worktree) so the registration the " +
-    "conductor provisions into each worker worktree is the one that takes effect. If the " +
-    "collision is deliberate, set " +
-    `${CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING_ENV}=1 to override the executor's refusal ` +
-    "(doctor still reports it).";
+const CLAUDE_MCP_SHADOWING_HINT = `Run \`${CLAUDE_MCP_SHADOWING_REMEDIATION_COMMAND}\` to clear the 'bridge-api' MCP ` +
+    "registration in ~/.claude.json (use the matching scope if it is registered at user scope, " +
+    "or under the projects entry for this repository/worktree). This is ADVISORY: workers load " +
+    "MCP servers with --strict-mcp-config from their own worktree registration, so this entry " +
+    "does not reach a worker and does not block a conductor run.";
 const CLAUDE_MCP_SHADOWING_INSTALL_HINTS = {
     darwin: CLAUDE_MCP_SHADOWING_HINT,
     linux: CLAUDE_MCP_SHADOWING_HINT,
@@ -547,17 +546,25 @@ const CLAUDE_MCP_SHADOWING_INSTALL_HINTS = {
  * configuration register a `bridge-api` MCP server that could shadow a worker's
  * provisioned registration?
  *
+ * ADVISORY SINCE BAPI-790. Every outcome reports `found: true`, so this never
+ * fails the prerequisite section or the exit code; a confirmed collision is
+ * surfaced through the DETAIL, which names the scope and carries the exact
+ * remediation command. The downgrade is not a softening of the diagnostic — it
+ * reflects that strict flag-scoped worker MCP loading means the collision can no
+ * longer reach a worker (inventory Finding 6), so reporting it as a broken
+ * prerequisite would tell an operator to fix something that is not breaking
+ * anything.
+ *
  * Status mapping:
  *   - no registration, or only acceptable provisioned shims → `found: true`
- *   - a CONFIRMED foreign registration                      → `found: false`
+ *   - a CONFIRMED foreign registration                      → `found: true` + advisory detail
  *   - unreadable / malformed config, or an unresolved main
  *     worktree path                                          → `found: true` + detail
  *
- * The failing case is deliberately independent of
- * `BAPI_CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING`: the override changes what the
- * EXECUTOR does at runtime, not whether the collision exists. A diagnostic that
- * went quiet because an override happened to be exported would hide the exact
- * condition an operator ran doctor to find.
+ * Reporting stays deliberately independent of the retired
+ * `BAPI_CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING` override: whether that variable is
+ * exported has never had any bearing on whether the collision exists, and now it
+ * has no bearing on anything at all.
  */
 export function claudeMcpShadowingDescriptor() {
     return {
@@ -589,8 +596,11 @@ export function claudeMcpShadowingDescriptor() {
                 degraded.push("the main worktree path could not be resolved; only user and current-worktree scopes were checked");
             }
             if (inspection.findings.length > 0) {
-                const findings = inspection.findings.map(formatClaudeMcpShadowFinding);
-                return { found: false, detail: [...findings, ...degraded].join("; ") };
+                // Advisory (BAPI-790): reported in full, with the remediation command,
+                // but `found: true` so it never fails the prerequisite or the exit code.
+                const findings = inspection.findings.map((finding) => `advisory: ${formatClaudeMcpShadowFinding(finding)} — not loaded by a worker under ` +
+                    `strict MCP loading; clear it with \`${CLAUDE_MCP_SHADOWING_REMEDIATION_COMMAND}\``);
+                return { found: true, detail: [...findings, ...degraded].join("; ") };
             }
             return {
                 found: true,

package/build/start-tickets.js

@@ -59,6 +59,10 @@ import os from "node:os";
 import path from "path";
 import { VERSION } from "./version.generated.js";
 import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./credential-store.js";
+// BAPI-814/E1b: the read-only index-branch override probe. `getIndexBranch` is
+// reused from the conduct-epic client rather than re-wrapped, so both conductor
+// paths read the one repository-wide override through the same client.
+import { getIndexBranch } from "./conduct-epic/bridge-client.js";
 import { resolveStartTicketsRepoName as resolveSharedStartTicketsRepoName, resolveRequiredStartTicketsRepoName, } from "./start-tickets-repo.js";
 import { provisionMcpRegistrationsForCreatedWorktrees, } from "./mcp-provisioning.js";
 import { provisionCommandsForCreatedWorktrees, } from "./command-provisioning.js";
@@ -173,6 +177,7 @@ export function parseStartTicketsArgs(argv) {
     let maxParallelRaw;
     let agentName = DEFAULT_AGENT_NAME;
     let baseBranch = "main";
+    let baseBranchExplicit = false;
     let conductorEnabled = false;
     let workflow = "implement";
     let reviewRoundsRaw;
@@ -342,6 +347,7 @@ export function parseStartTicketsArgs(argv) {
                 return { status: "error", message: `Invalid --base-branch value: ${error}` };
             }
             baseBranch = trimmed;
+            baseBranchExplicit = true;
             continue;
         }
         if (arg === "--dry-run") {
@@ -449,6 +455,7 @@ export function parseStartTicketsArgs(argv) {
             branchOverrides,
             agentName,
             baseBranch,
+            ...(baseBranchExplicit ? { baseBranchExplicit: true } : {}),
             conductorEnabled,
             workflow,
             reviewRounds,
@@ -506,16 +513,19 @@ export function resolveStartTicketsPlatformConfig(deps, agent, autoApprove = fal
 // instruction to the resume-mode worker's prompt.
 resumeMode = false, workflow = "implement", reviewRounds, 
 // BAPI-586: the effective run base branch (incl. epic.base_branch override).
-// Injected as BAPI_BASE_BRANCH for conductor workers so their PR targets it,
-// and threaded (BAPI-593) into the spawned workflow command.
+// Injected as BAPI_BASE_BRANCH so the spawned worker's PR targets it — for
+// conductor runs always, and (BAPI-801) for plain runs whose base is a
+// non-default branch — and threaded (BAPI-593) into the spawned workflow command.
 baseBranch) {
     if (!isSupportedStartTicketsPlatform(deps.platform)) {
         return { ok: false, error: unsupportedPlatformMessage(deps.platform) };
     }
     const platform = deps.platform;
-    // Only conductor dispatch uses the PR-base contract; interactive dispatch omits
-    // the BAPI_BASE_BRANCH assignment so its worker launch is unchanged.
-    const prBaseBranch = conductorEnabled ? baseBranch : null;
+    // BAPI-801: both conductor and plain dispatch carry the PR-base ENVIRONMENT
+    // contract (see resolvePrBaseBranchEnvValue). Only the conductor launch
+    // INSTRUCTION remains conductor-only — a plain worker's prompt stays bare and
+    // learns the base from the env plus the create-PR instruction files.
+    const prBaseBranch = resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch);
     return {
         ok: true,
         config: {
@@ -523,7 +533,8 @@ baseBranch) {
             worktrunkBinary: resolveWorktrunkBinary(platform, deps.env),
             // Inject the resolved repo identity so the spawned worktree session never
             // falls back to the basename-derived repo name (the 403 root cause), and
-            // (BAPI-586) the run base so the conductor worker opens its PR against it.
+            // (BAPI-586/BAPI-801) the run base so the spawned worker opens its PR
+            // against it. The base assignment stays outermost.
             buildAgentShellCommand: (key, worktreePath, modelAlias) => prependBaseBranchEnvAssignment(prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, resumeMode, workflow, reviewRounds, baseBranch), repoName, platform), prBaseBranch, platform),
             spawnTerminalTab: deps.spawnTerminalTab,
         },
@@ -555,14 +566,40 @@ export function prependRepoNameEnvAssignment(command, repoName, platform = "darw
     return `export BAPI_REPO_NAME='${shSquoteInner(repoName)}' && ${command}`;
 }
 /**
- * BAPI-586: prepend a `BAPI_BASE_BRANCH` environment assignment to a spawned
- * conductor worker's shell command so the worker can open its PR against the run
- * base via `gh pr create --base "$BAPI_BASE_BRANCH"` (paired with the PR-base
- * launch instruction), instead of inferring the repo default branch. Platform
- * correct — `$env:VAR = '…'; …` on PowerShell, `export VAR='…' && …` on POSIX —
- * with the value quoted by the same escaper used for the rest of the command.
- * Fail-open: a null/empty `baseBranch` returns the command unchanged (interactive
- * dispatch does not use the PR-base contract).
+ * BAPI-801: decide the `BAPI_BASE_BRANCH` value a spawned worker's shell should
+ * carry — the single rule shared by the real spawn builder
+ * ({@link resolveStartTicketsPlatformConfig}) and the dry-run preview builder
+ * ({@link getDryRunPlatformDetails}), so the preview can never drift from what
+ * is actually spawned.
+ *
+ * - Conductor runs export whatever base was resolved, `main` included — BAPI-586
+ *   behavior, unchanged.
+ * - Plain runs export only a non-empty base other than the CLI default `main`.
+ *   This mirrors the `--base-branch` threading rule in {@link buildAgentPrompt},
+ *   keeps today's plain spawn strings byte-stable on the default base, and costs
+ *   nothing: the create-PR fallback tier is `main` anyway.
+ *
+ * Returns `null` when nothing should be exported;
+ * {@link prependBaseBranchEnvAssignment} is fail-open on that value.
+ */
+function resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch) {
+    if (conductorEnabled)
+        return baseBranch ?? null;
+    if (!baseBranch || baseBranch === "main")
+        return null;
+    return baseBranch;
+}
+/**
+ * BAPI-586/BAPI-801: prepend a `BAPI_BASE_BRANCH` environment assignment to a
+ * spawned worker's shell command so the worker opens its PR against the run base
+ * instead of inferring the repo default branch. Conductor workers additionally
+ * receive the paired launch instruction; plain workers (BAPI-801) carry the same
+ * env and learn the contract from the create-PR instruction files, which resolve
+ * `$BAPI_BASE_BRANCH` first. Platform correct — `$env:VAR = '…'; …` on
+ * PowerShell, `export VAR='…' && …` on POSIX — with the value quoted by the same
+ * escaper used for the rest of the command. Fail-open: a null/empty `baseBranch`
+ * returns the command unchanged (the caller's rule already decided not to
+ * export — see {@link resolvePrBaseBranchEnvValue}).
  */
 export function prependBaseBranchEnvAssignment(command, baseBranch, platform = "darwin") {
     if (!baseBranch)
@@ -1061,6 +1098,9 @@ export function buildAgentPrompt(key, opts = {}) {
         parts.push(buildConductorMessageRelayLaunchInstruction());
         // BAPI-586: conductor implementation workers must open their PR against the
         // run base (injected as BAPI_BASE_BRANCH), never the repo default branch.
+        // The launch INSTRUCTION stays conductor-only. BAPI-801 gave plain runs the
+        // same env, but their prompt stays bare — the create-PR instruction files
+        // read $BAPI_BASE_BRANCH for them.
         parts.push(buildPrBaseContractLaunchInstruction());
     }
     if (opts.resumeMode)
@@ -1723,11 +1763,13 @@ export function getDryRunPlatformDetails(agent, platform = process.platform, env
         worktrunkBinary: resolveWorktrunkBinary(platform, env),
         // The builder accepts an optional resolved modelAlias; the dry-run caller
         // now passes the previewed tier's alias so `--model` shows in the preview.
-        // The resolved repo name (when known) is injected as a BAPI_REPO_NAME prefix
-        // so the dry-run preview matches the real spawn command exactly. Reuses the
-        // same buildAgentShellCommand/buildAgentPrompt path as a real spawn — dry-run
-        // is never special-cased — so the previewed workflow prompt is exact.
-        buildAgentShellCommand: (key, worktreePath, modelAlias) => prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, false, workflow, reviewRounds, baseBranch), repoName, platform),
+        // The resolved repo name (when known) is injected as a BAPI_REPO_NAME prefix,
+        // and (BAPI-801) the PR base as a BAPI_BASE_BRANCH prefix through the SAME
+        // resolvePrBaseBranchEnvValue rule and the same outermost ordering the real
+        // spawn builder uses — dry-run shares both environment renderings with real
+        // spawning. Reuses the same buildAgentShellCommand/buildAgentPrompt path as a
+        // real spawn — dry-run is never special-cased — so the preview is exact.
+        buildAgentShellCommand: (key, worktreePath, modelAlias) => prependBaseBranchEnvAssignment(prependRepoNameEnvAssignment(buildAgentShellCommand(agent, key, worktreePath, platform, autoApprove, modelAlias, conductorEnabled, false, workflow, reviewRounds, baseBranch), repoName, platform), resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch), platform),
     };
 }
 /**
@@ -1769,10 +1811,17 @@ export function buildDryRunDetailLines(agent, key, branch, platform = process.pl
     const { worktrunkBinary, buildAgentShellCommand: build } = getDryRunPlatformDetails(agent, platform, env, autoApprove, conductorEnabled, repoName, workflow, reviewRounds, baseBranch);
     const wtArgs = buildWtSwitchArgs(branch, false, baseBranch);
     const agentInvocation = build(key, "<worktree-path>", modelAlias);
+    // BAPI-801: one concise secondary detail naming the PR base, emitted only when
+    // the shared rule actually exports BAPI_BASE_BRANCH. It sits AFTER the rendered
+    // spawn command so the copyable command stays the primary scan target, and it
+    // is ordinary routing detail — never warning-like. An ordinary plain run on
+    // `main` exports nothing and so keeps its existing output density verbatim.
+    const prBaseBranch = resolvePrBaseBranchEnvValue(conductorEnabled, baseBranch);
     return [
         `DRY-RUN: ${key} -> branch=${branch}`,
         `DRY-RUN:   ${worktrunkBinary} ${wtArgs.join(" ")}`,
         `DRY-RUN:   ${agentInvocation}`,
+        ...(prBaseBranch ? [`DRY-RUN:   PR base: ${prBaseBranch}`] : []),
         ...buildDryRunMcpProvisioningLines("<worktree-path>", platform, mcpServerInvocation),
     ];
 }
@@ -2792,8 +2841,10 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     const platformConfig = resolveStartTicketsPlatformConfig(deps, agent, options.autoApprove, options.conductorEnabled ?? false, resolvedRepoName, 
     // BAPI-494: resume-mode dispatches get the full-suite remediation finalize prompt.
     options.resumeMode ?? false, options.workflow, options.reviewRounds, 
-    // BAPI-586: the effective run base (already carries any epic.base_branch
-    // override applied above) so conductor workers get BAPI_BASE_BRANCH.
+    // BAPI-586/BAPI-801: the effective run base (already carries any
+    // epic.base_branch override applied above) so the spawned worker gets
+    // BAPI_BASE_BRANCH — every conductor worker, and a plain worker whose base
+    // is non-default.
     options.baseBranch);
     if (!platformConfig.ok)
         return { ok: false, error: platformConfig.error };
@@ -2940,6 +2991,54 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     const rows = await spawnTabsFn(deps, routed, terminal, platformConfig.config.buildAgentShellCommand);
     return { ok: true, rows };
 }
+/**
+ * Warn when an implicit base branch could be resolved through an active
+ * repository-wide index-branch override (BAPI-814/E1b).
+ *
+ * Informational only, and deliberately narrow:
+ *
+ * - **Only for an IMPLICIT base.** An explicit `--base-branch` is the caller's
+ *   own decision and is unaffected by the override, so the probe is skipped
+ *   entirely — no request is made and no warning is printed.
+ * - **Only with resolvable credentials.** `start-tickets` creates worktrees and
+ *   opens tabs; it does not require Bridge access to do its job. "No credential"
+ *   is therefore an ordinary state for this command, not a diagnostic, and
+ *   staying silent keeps an unrelated command from growing a credential
+ *   complaint. A lookup that FAILS after credentials resolved is different, and
+ *   does produce one bounded, sanitized line.
+ * - **Never a refusal.** Nothing here changes the exit code, the base branch, or
+ *   any spawn behavior.
+ *
+ * Warnings go to `errorLog` (stderr), so machine-readable stdout stays clean.
+ */
+async function warnOnIndexOverrideForImplicitBase(deps, options, errorLog, fetchImpl) {
+    if (options.baseBranchExplicit)
+        return;
+    const access = await resolveConductorBridgeApiAccess({
+        env: deps.env,
+        cwd: deps.cwd,
+        homedir: os.homedir,
+        platform: deps.platform,
+        readFile: deps.readFile ?? ((filePath) => readFile(filePath, "utf-8")),
+        stat: (filePath) => stat(filePath).then((info) => ({ mode: info.mode })),
+    });
+    if (!access.ok)
+        return;
+    const result = await getIndexBranch(access.access, fetchImpl);
+    if (!result.ok) {
+        errorLog(`Warning: the repository's indexed-branch override could not be read: ${result.error}. ` +
+            "Continuing — ticket startup is unaffected.");
+        return;
+    }
+    const override = result.value.override;
+    if (override === null)
+        return;
+    errorLog(`Warning: ${access.access.repoName} has an ACTIVE index-branch override: ` +
+        `'${override.override_branch}'. No --base-branch was given, so the implicit base — ` +
+        "the base-branch config field and feature-branch provisioning — may resolve through " +
+        "that override rather than the repository's usual base. Ticket startup is ALLOWED and " +
+        "continues; pass --base-branch to choose explicitly.");
+}
 /** Platform-specific guidance printed when one or more tabs fail to spawn. */
 function spawnFailureHintForPlatform(platform) {
     if (platform === "darwin") {
@@ -2995,6 +3094,9 @@ export async function runStartTicketsCli(argv, overrides = {}) {
         errorLog("Warning: --tier value was not one of cheap|basic|premium; ignoring the override and " +
             "using premium model routing for every ticket.");
     }
+    // BAPI-814/E1b: informational only, ahead of the dry-run branch so both a
+    // preview and a real run report the same repository-wide condition.
+    await warnOnIndexOverrideForImplicitBase(deps, options, errorLog, overrides.fetchImpl ?? globalThis.fetch);
     if (options.dryRun) {
         // Resolve the repo identity for the preview so the dry-run command matches
         // what the real spawn injects (see prependRepoNameEnvAssignment). The real

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.38";
+export const VERSION = "0.2.41";

package/build/worktree-core.js

@@ -186,9 +186,15 @@ const CLEANUP_FAILURE_DIAGNOSTIC = "untracked-file cleanup did not complete; con
  * settings, MCP registrations/trust, and worker logging are provisioned again — so
  * anything cleanup removes is re-created by the provisioning that follows it.
  *
- * Stale, non-ignored `.conductor/result.json` and `.conductor/critique.md` from a
- * prior attempt are removed intentionally: a leftover verdict artifact read by a
- * later attempt would be a prior run's answer presented as this one's.
+ * `.conductor/` content is NOT removed here, and must not be assumed to be
+ * (BAPI-814/D1). `.conductor/` is an ignored path in this repository, and `-fd`
+ * without `-x` leaves ignored paths alone — so a prior attempt's
+ * `.conductor/result.json` and `.conductor/critique.md` survive this cleanup
+ * entirely. Removing them is the ATTEMPT OWNER's job, performed explicitly in
+ * `executor/job-runner.ts` after the worktree lock is acquired and before the
+ * worker spawns (`removeStaleVerdictArtifacts`). That placement is deliberate:
+ * cleanup must be serialized against the lock, whereas this function runs during
+ * unlocked worktree preparation.
  *
  * FAIL-OPEN. Pre-change behavior performed no cleanup at all, so being unable to
  * clean must never change the worktree row or the job outcome. Every failure path —

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

@@ -58,7 +58,8 @@ activated. `core` is always implicitly included.
 | `core` | always |
 | `pipeline-authoring` | `BRIDGE_MCP_PROFILE` includes `pipeline-authoring` or `full` |
 | `conductor` | includes `conductor` or `full` |
-| `sfcc` | includes `sfcc` or `full` (2 diagnostics ship in `core`; the rest are gated) |
+| `sfcc` | includes `sfcc` or `full` — the OCAPI **read** tools and `sfcc_log_query` (2 diagnostics ship in `core`) |
+| `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")`.
@@ -178,10 +179,43 @@ by tier.
 | Tool | Dependencies (class) |
 |---|---|
 | `create_pull_request` | VCS **[BLOCK]** (Tier-1) |
+| `merge_pull_request` | VCS **[BLOCK]** (Tier-1; protected server-decided merge — see below) |
 | `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) |
 
+#### `merge_pull_request` — what the caller can observe
+
+The tool holds no VCS credential and performs no merge of its own; it asks the
+server and reports the answer. Four constraints are worth knowing before calling it:
+
+- **Only `merged: true` is success.** `dry_run`, `pending_approval`, and
+  `lease_held` are non-progress outcomes — nothing was merged, and repeating the
+  call unchanged will produce the same answer until the named condition moves.
+- **Workflow files are refused.** The server reads the pull request's complete
+  changed-file list and declines any PR touching `.github/workflows/`, including a
+  file *renamed out of* that directory. A file list it cannot prove complete is
+  refused the same way, as `workflow_files_unreadable` — an unreadable diff is not
+  a clean one.
+- **`auto_merge_enabled` must be on.** Merge configuration that is missing,
+  disabled, or malformed produces `dry_run` rather than a merge. Enable it on the
+  project default via `PUT /jira/epic-runs/supervisor-config/defaults/`; the
+  `dry_run` envelope carries that exact remediation in its `hint`.
+- **No required checks, no merge.** When no authoritative required-check set can be
+  resolved, the tool returns `gate_unresolved` and never sends the merge request —
+  "zero required checks are all green" is not a CI pass.
+- **Review is refused too, when the repository opts in.** If the done gate carries a
+  `review_state` condition, the tool also refuses when the verdict is not approving
+  for the exact `expected_head_sha`. `review_not_approved` is a wait — a verdict for
+  this head may still be posted, so it carries `retry_hint: "retry_later"`. The other
+  four need intervention (`needs_human`): `review_unavailable` (review state could not
+  be read), `review_source_unsupported` (`min_approvals` / `combination`, refused
+  rather than downgraded), `review_config_invalid` (review configuration exists but is
+  malformed), and `head_sha_drift` (the verdict belongs to a different commit). The
+  tool's own check is advisory; the server's head-bound review observation is
+  authoritative, so a tool-side pass followed by a server refusal is expected for a
+  legacy approved comment that carries no head proof.
+
 ### Full-automation (composite)
 
 These orchestrate an idea → ticket → review → start chain, so they inherit the
@@ -239,11 +273,16 @@ integration dependency.
 | `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
+### Gated behind the `sfcc` group (reads + logs)
 
 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.
+`version` config + a reachable sandbox → SFCC OCAPI **[BLOCK]**.
+
+Every SFCC tool — including the two always-on 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
+(BAPI-817).
 
 **Reads:**
 
@@ -258,7 +297,13 @@ sandbox-only and destructive.
 | `site_preference_get` | Profile-gated **[BLOCK]** · SFCC OCAPI **[BLOCK]** |
 | `site_preference_search` | Profile-gated **[BLOCK]** · SFCC OCAPI **[BLOCK]** |
 
-**Writes (9, sandbox-only):**
+### Gated behind the `sfcc-write` group
+
+Writes are destructive and sandbox-only. They are **not** registered by the
+`sfcc` group — enabling introspection must never enable mutation — so a session
+wanting both selects `sfcc,sfcc-write` (or `full`).
+
+**Writes (sandbox-only):**
 
 | Tool | Dependencies (class) |
 |---|---|
@@ -272,7 +317,7 @@ sandbox-only and destructive.
 | `custom_object_definition_attribute_update` | Profile-gated **[BLOCK]** · SFCC OCAPI write **[BLOCK]** |
 | `site_preference_values_set` | Profile-gated **[BLOCK]** · SFCC OCAPI write **[BLOCK]** |
 
-**Logs:**
+**Logs** (gated by `sfcc`, not `sfcc-write`)**:**
 
 | Tool | Dependencies (class) |
 |---|---|
@@ -286,12 +331,12 @@ sandbox-only and destructive.
 |---|---|---|
 | **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) |
+| **Version control (VCS)** | `create_pull_request`, `merge_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_council` in `technical`/`discovery` modes | Tier-4 clarifying-questions/critique/review/prd/fsd |
-| **SFCC OCAPI** | `check_permissions` + all 16 SFCC read/write tools | — |
+| **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`, and gated `sfcc` tools | — |
+| **Profile gating** | all `pipeline-authoring`, `conductor`, `sfcc`, and `sfcc-write` tools | — |
 
 ## Notes & caveats
 

package/docs/install/sfcc-integration.md

@@ -6,11 +6,25 @@ small set of sandbox-only writes — through the **OCAPI Data API**. This guide
 setting up the OCAPI client that those tools authenticate against.
 
 > **Sandbox / local development only.** This integration is intended for a **developer
-> sandbox**. The tools reject non-sandbox instances, and the permissions grant below is
-> deliberately broad (all methods, all resources) — appropriate for a throwaway dev
-> sandbox, **never** for staging or production. Do not configure this grant on any
-> instance that holds real data. Credentials stay local (in `dw.json` or `SFCC_*` env
-> vars) and are never sent to Bridge.
+> sandbox**, and that restriction is **enforced in code**: before any SFCC tool runs,
+> Bridge validates the hostname your credentials actually resolve to — from `dw.json`
+> or `SFCC_*` — against the sandbox forms listed below. An unrecognized host is refused
+> with a `403` (`error.code: "TARGET_NOT_SANDBOX"`) before any request leaves your
+> machine. The check reads the resolved hostname, never the `instance` tool argument,
+> so omitting `instance` or passing `"sandbox"` cannot bypass it.
+>
+> Accepted sandbox hostname forms:
+>
+> - `<realm>-<nnn>.sandbox.<region>.dx.commercecloud.salesforce.com`
+> - `<realm>-<nnn>.sandbox.dx.commercecloud.salesforce.com`
+> - `<realm>-<nnn>.dx.commercecloud.salesforce.com`
+>
+> Anything else — a `production-`/`staging-`/`development-` prefixed host, or any
+> `*.demandware.net` host — is rejected.
+>
+> Still do not configure the grants below on an instance that holds real data.
+> Credentials stay local (in `dw.json` or `SFCC_*` env vars) and are never sent to
+> Bridge.
 
 For the full per-tool list and what each SFCC tool depends on, see
 [MCP Tool Integration Dependencies](./mcp-tool-integrations.md). For the tool reference
@@ -34,20 +48,39 @@ In Business Manager for the sandbox:
 
 **Administration → Site Development → Open Commerce API Settings → Data API** tab.
 
-Add the following client entry to the `clients` array of the Data API settings, then
-**Save**. This grants the client full read/write access to every Data API resource —
-acceptable only on a developer sandbox:
+Add the client entry below to the `clients` array of the Data API settings, then
+**Save**. It grants only the resource families and HTTP methods Bridge's SFCC tools
+actually call — not a global `/**` grant. `check_permissions` prints the same JSON on
+a 401/403, split into the two blocks.
+
+**READ/SEARCH TOOL GRANTS** — required by the `sfcc` read tools. (`post` is OCAPI's
+convention for its `*_search` endpoints, not a mutation.)
+
+```json
+{
+  "client_id": "<your-client-id-here>",
+  "resources": [
+    { "resource_id": "/system_object_definitions",    "methods": ["get"],         "read_attributes": "(**)", "write_attributes": "(**)" },
+    { "resource_id": "/system_object_definitions/**", "methods": ["get", "post"], "read_attributes": "(**)", "write_attributes": "(**)" },
+    { "resource_id": "/site_preferences/**",          "methods": ["get", "post"], "read_attributes": "(**)", "write_attributes": "(**)" },
+    { "resource_id": "/custom_object_definitions/**", "methods": ["get", "post"], "read_attributes": "(**)", "write_attributes": "(**)" }
+  ]
+}
+```
+
+**MUTATION GRANTS** — required **only if you enable `BRIDGE_MCP_PROFILE=sfcc-write`**,
+which registers the nine destructive write tools. These are shipped capabilities, not
+future work. No `delete` is granted, because no shipped write tool performs one; the
+`get` entries are needed for the If-Match ETag round trip that precedes each `PATCH`.
 
 ```json
 {
   "client_id": "<your-client-id-here>",
   "resources": [
-    {
-      "methods": ["get", "post", "put", "patch", "delete"],
-      "read_attributes": "(**)",
-      "write_attributes": "(**)",
-      "resource_id": "/**"
-    }
+    { "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": "(**)" }
   ]
 }
 ```
@@ -57,7 +90,9 @@ Notes:
 - 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.
-- If the Data API settings are empty, wrap the entry in the standard settings envelope:
+- If the Data API settings are empty, wrap the entries in the standard settings
+  envelope. Merge the resource lists from the block(s) above into one `resources`
+  array — do not substitute a global `"resource_id": "/**"` grant:
 
   ```json
   {
@@ -66,12 +101,10 @@ Notes:
       {
         "client_id": "<your-client-id-here>",
         "resources": [
-          {
-            "methods": ["get", "post", "put", "patch", "delete"],
-            "read_attributes": "(**)",
-            "write_attributes": "(**)",
-            "resource_id": "/**"
-          }
+          { "resource_id": "/system_object_definitions",    "methods": ["get"],         "read_attributes": "(**)", "write_attributes": "(**)" },
+          { "resource_id": "/system_object_definitions/**", "methods": ["get", "post"], "read_attributes": "(**)", "write_attributes": "(**)" },
+          { "resource_id": "/site_preferences/**",          "methods": ["get", "post"], "read_attributes": "(**)", "write_attributes": "(**)" },
+          { "resource_id": "/custom_object_definitions/**", "methods": ["get", "post"], "read_attributes": "(**)", "write_attributes": "(**)" }
         ]
       }
     ]
@@ -109,14 +142,28 @@ or the `/teach-bridge` skill.
 ## 4. Enable the SFCC tools
 
 The two diagnostic tools (`sfcc_setup_status`, `check_permissions`) are always
-registered. The read tools, write tools, and `sfcc_log_query` are gated behind the
-`sfcc` profile. Add `sfcc` to `BRIDGE_MCP_PROFILE` in the MCP server `env` block (it is
-comma-separated; `full` also works), then **restart the MCP client**:
+registered. Everything else is gated, behind **two independent profile groups**:
+
+| Group | Registers |
+|---|---|
+| `sfcc` | the 8 OCAPI read tools + `sfcc_log_query` — read-only |
+| `sfcc-write` | the 9 destructive write tools |
+
+Neither implies the other. Add what you need to `BRIDGE_MCP_PROFILE` in the MCP server
+`env` block (it is comma-separated), then **restart the MCP client**:
 
 ```json
 "env": { "BRIDGE_MCP_PROFILE": "sfcc" }
 ```
 
+For reads plus writes, use `"sfcc,sfcc-write"`. `full` expands to every group and is
+therefore write-capable.
+
+> **Migration.** `sfcc` used to register the nine write tools too. It no longer does.
+> If you were relying on SFCC writes through `BRIDGE_MCP_PROFILE=sfcc`, change it to
+> `BRIDGE_MCP_PROFILE=sfcc,sfcc-write`. `full` users keep write access and need no
+> change.
+
 ## 5. Verify
 
 Ask your agent to run: