Add D12: OpenAPI-first, MCP-ready transport-agnostic core

Tool handlers + shared auth/scope/PII/audit guard built independent of wire
protocol; OpenAPI adapter shipped now (Agentforce External Service actions, Apex
only for shaping); MCP adapter deferred to a named trigger (real IDE/Claude Code
workflow, or native remote-MCP per-user GA). Update decision log, §0.1 transport
architecture block, §1h test split (OpenAPI contract now, MCP conformance deferred),
and §4 deliverables (annotate design.md §4; transport-agnostic core story).

docs/agentforce-plan.md

@@ -47,6 +47,7 @@ off the per-user hop, so the risk is mitigated rather than load-bearing.
 | D9 | New separate **`sh-agentforce` SFDX repo** for agent metadata (Bot/GenAiPlannerBundle/GenAiPlugin/GenAiFunction) under Agentforce DX | Different toolchain (sf CLI, scratch orgs, deploy-to-org) than the CDK monorepo; one deploy target per repo | `FACT` developer.salesforce.com Agent DX metadata; handbook |
 | D10 | Build **Ops + Finance agents now**; HR/Gusto, SA8000 Q&A, IT/onboarding **later, corpus-gated**; add near-term capabilities as **Topics**, not new agents | Front/ops corpus is rich and current; HR/Amazon/SA8000 corpus is thin/stale/missing | Notion (below); design.md corpus notes |
 | D11 | Keep the **Bedrock guardrail on the BYOLLM model path** + MCP-layer PII redaction (defense in depth) | Agentforce Trust Layer does not redact OUR tool-response payloads | design.md §2.5, §11.2 |
+| D12 | **RESOLVED (2026-06-11, §0.1):** **OpenAPI-first, MCP-ready transport-agnostic core.** Tool handlers + the shared auth/scope/PII/audit guard are built independent of transport; ship the **OpenAPI adapter now** (Agentforce External Service actions; Apex only where an action needs request/response shaping); **defer the MCP adapter** to a named trigger. | Agentforce's per-user hop needs OpenAPI regardless (D4); no committed MCP consumer today, so a second public interface + its conformance/hardening cost isn't justified yet; a transport-agnostic core makes the MCP adapter a cheap later add, not a re-platform; deferring it also drops the IDE-session trifecta nuance until then. | Adam 2026-06-11; research wf_1bf9e142 (D4) |
 
 **Agent roster (the answer to "how many"):** **3** — Seahaven Ops, Seahaven Finance, Lauren Exec (§1a, §2).
 
@@ -89,6 +90,29 @@ provisional D4/D5 wording above and the open items in §6.
    redaction move entirely to the MCP/action layer** (already the plan for PII — design.md §2.5). This **revises
    D11**: the guardrail is applied at the MCP/action layer, not "on the BYOLLM model path."
 
+**Transport architecture (D12) — OpenAPI-first, MCP-ready core.** design.md §4 framed each server as a remote
+**MCP** server because the assumed consumer was Slack's built-in MCP client. That consumer is gone, and the chosen
+Agentforce per-user path (D4) is OpenAPI/Apex, not MCP. Decision:
+
+- **Build a transport-agnostic core.** The tool handlers and the shared auth/scope/PII-redaction/audit guard
+  (design.md §4 `shared` package) are written independent of wire protocol. The OpenAPI spec **and** any future MCP
+  tool list are generated from one tool registry, so the two can never drift.
+- **Ship the OpenAPI adapter now** — Agentforce **External Service (OpenAPI) actions** are the primary transport;
+  use **Apex `@InvocableMethod`** only for actions needing request/response shaping (e.g. extra redaction,
+  pagination). This is the one interface to build, secure (one API Gateway + Cognito authorizer + WAF web ACL),
+  and test on the critical path.
+- **Defer the MCP adapter** until a **named trigger**: (a) Claude Code / IDE consumption becomes a real recurring
+  workflow (not nice-to-have), **or** (b) Salesforce native remote-MCP per-user binding reaches GA (then MCP-native
+  could also collapse the Agentforce-side OpenAPI facade). When triggered, the MCP adapter is a thin add over the
+  same core/auth/scopes/audit — not a re-platform.
+- **Security note (why deferral is also a simplification):** an MCP/IDE consumer lets one human wire multiple
+  servers into one session (e.g. `ops`-with-Gmail **and** `finance`), softening the session-layer trifecta
+  separation that Agentforce's separate agents give for free. The token-layer guarantee still holds (separate
+  audiences → no single token spans tiers), but not shipping the IDE/MCP path removes the session-layer concern
+  entirely for now. If/when the MCP adapter ships, restrict IDE/MCP `finance` access to the admin tier and document
+  "don't co-connect finance with Gmail-read in one IDE session." The `sh-mcp` name stays accurate — MCP remains the
+  strategic protocol, just not the day-one transport.
+
 **Dropped claim:** the "BYOLLM = ~30% fewer Einstein Requests" figure was **not corroborated** by any verified
 source — removed from cost modeling.
 
@@ -284,7 +308,15 @@ audience-binding rejection (an `ops` token rejected by `finance`); per-tool **se
 UNMASKED** (legacy Alex deliberately left names unmasked — Trust Layer must not re-mask them, Gap G3); per-tool
 rate limit + per-session cap; finance audit-record shape.
 
-Eval criteria: behavioral suite ≥ agreed pass rate before each cutover; MCP suite at design.md coverage gate
+**Transport-test note (D12):** the active interface is the **OpenAPI adapter**, so the design.md §7.3
+"Contract / MCP conformance" layer is split — **OpenAPI contract tests** (schema validation, the generated spec
+matches the tool registry) run now; **MCP protocol-conformance tests defer with the MCP adapter**. The security
+tests above are transport-agnostic and unchanged: server-side per-tool scope enforcement is the authoritative
+boundary on either transport, and `list_tools` tool-hiding (MCP-only) is replaced on the OpenAPI path by
+**per-agent action assignment** (each Agentforce agent is granted only its tier's actions) — still a convenience,
+never the boundary (design.md §2.5).
+
+Eval criteria: behavioral suite ≥ agreed pass rate before each cutover; MCP/core suite at design.md coverage gate
 (80% lines, 100% on the shared auth/scope guard) — both green are the parity gate for retiring a bot.
 
 ---
@@ -452,14 +484,23 @@ the single flip point; no legacy component is deleted until the corresponding pa
   per-user auth model + Gap G1, Data Library/retriever design, model choice, Testing Center plan); "Agentforce
   DX & Release Process" (the `sh-agentforce` repo, `cd-sfdx`, scratch-org flow).
 
+**Repo docs:**
+- **`sh-mcp/docs/design.md` §4 (annotation, D12):** design.md §4 frames each server as a remote *MCP* server
+  (assumed Slack MCP-client consumer). Annotate it to record the **transport-agnostic core** decision — OpenAPI
+  adapter shipped now for Agentforce, MCP adapter deferred to its named trigger — so the build doesn't couple
+  tool logic to either protocol. (Annotation, not a reopening — the locked auth/scope/trust-tier decisions are
+  unchanged.)
+
 **Jira (INFRA project — no migration epic exists yet; related done: INFRA-92 AOSS lockdown, INFRA-37 reminder
 removal):**
 - **New epic:** "Agentforce migration & MCP platform."
 - Stories (representative): foundation/Cognito+Google federation; `sh-agentforce` repo + `cd-sfdx` reusable
-  workflow (G10); **verify per-user MCP connector auth / build Apex-External-Service per-user wrapper (G1/G2)** —
-  gates everything, do first; Data Cloud Data Library + repoint `notion-sync`; retire `po-sync`/`workorder-sync`
-  (D7); Ops agent build + parity; Finance agent + audit; Lauren Exec + per-user Google grant; **author SA8000 +
-  employee-handbook corpus** (G8); Testing Center suites; teardown (Bedrock agents/KB/AOSS/guardrail/sync
+  workflow (G10); **Phase-0 per-user auth spike** — prove the Per-User Browser Flow External Service action in
+  Slack (real `sub` reaches the server, consent UX, token refresh; §6 verify gate) — **gates everything, do
+  first**; **build the transport-agnostic core + OpenAPI adapter** (D12), MCP adapter deferred to its trigger;
+  Data Cloud Data Library + repoint `notion-sync`; retire `po-sync`/`workorder-sync` (D7); Ops agent build +
+  parity; Finance agent + audit; Lauren Exec + per-user Google grant; **author SA8000 + employee-handbook
+  corpus** (G8, fund when needed); Testing Center suites; teardown (Bedrock agents/KB/AOSS/guardrail/sync
   Lambdas). Every IAM/auth/connection story carries the **mandatory cross-review** label (design.md §8/§10).
 
 ---