docs: MCP admission contract architecture for Epic #172

[Joncallim]

Summary

Documentation for the architecture pass on EPIC #172 — MCP Execution Readiness and Bounded Context Grants. Docs only; no code changes.

• New docs/adr/0009-mcp-admission-contract.md — the canonical, handoff-ready architecture: the unified McpAdmissionDecision contract, the capability taxonomy (planning-only / bounded read-only / deferred live MCP), the four-paths-to-one consolidation map (with file:line anchors), and per-slice implementation specs S1–S6.
• Fix ADR numbering collision — two ADRs were both numbered 0007. Renamed the filesystem bounded-context-grants ADR to 0008 (it had zero inbound references) and cross-linked it to 0009; the forge-agent-workforce-model ADR keeps 0007.
• developer-guide / operator-guide / roadmap / wiki — aligned to the single admission contract, the four operator-facing MCP states, and the [EPIC] MCP Execution Readiness and Bounded Context Grants #172 slice breakdown.

Context

The architecture pass also produced GitHub issues that carry the same file-level specs:

• Epic: [EPIC] MCP Execution Readiness and Bounded Context Grants #172 (now ready-for-agent)
• Child slices: [FEATURE] S1 — Unified MCP admission contract and capability taxonomy #176 (S1), [FEATURE] S2 — Consolidate MCP admission onto the shared core and enforce it at approval #177 (S2), [FEATURE] S3 — Deterministic bounded filesystem context grant/denial recovery #178 (S3), [FEATURE] S4 — Specialist prompt and bounded context packet assembly with run evidence #179 (S4), [FEATURE] S5 — Unified operator UI copy and recovery-action contract for MCP admission #180 (S5), [FEATURE] S6 — End-to-end MCP admission regression (tiny task-tracker flow) and preview==handoff invariant #181 (S6), plus [FEATURE] Add Architect-driven MCP assignment and agent prompt overlays #43

The root defect: the same MCP capability policy is re-derived by four divergent code paths, and plan approval never runs the handoff broker — so an approved package can stall at handoff. ADR 0009 defines the one contract that makes preview, approval, handoff, and recovery incapable of disagreeing.

Review notes

• Scope is intentionally docs-only. Unrelated in-progress changes to web/worker/work-package-executor.ts were deliberately left out of this branch.
• No runtime behavior changes; the implementation lands via the S1–S6 issues.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9a9c09f3df

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Joncallim]

Architecture-stage review for Epic #172.

I reviewed the proposed contract against the current planner, workforce materializer, approval route, handoff broker, filesystem grant lifecycle, executor, persistence schema, UI readers, child issues, and current origin/main after #175. The inline comments below focus on implementation blockers and contract inconsistencies. The existing unresolved operator-guide comment is valid and is not duplicated here.

[Joncallim]

Review round 2 — all 18 inline comments addressed

Thanks for the thorough pass. Every thread is replied-to and resolved. Because the ADR is meant to be handed to a coding agent with no reasoning left to do, I treated the P0/P1s as design gaps and rebuilt the affected parts of ADR 0009 rather than patching prose. The PR stays docs-only; #175 is preserved (the branch was rebased onto it).

Branch hygiene

• Rebased onto #175 (was one commit behind) and re-derived every executor anchor against main: mcpCapabilityList 1252→1527, filesystem-context throw ~1515→1790, filesystemRuntimeMetadata ~1764. Added an "anchor freshness / grep the symbol" note atop the ADR.

ADR 0009 hardening

• [P0] Deny-wins + subtasks — new package-normalization phase admitWorkPackageMcp: unions prohibitions package-wide and evaluates MCP-aware subtasks against normalized coverage (restores mcp-execution-design.ts:617-631,697-721 semantics the flat contract dropped).
• Delivery kind ≠ risk — mcpDeliveryKind from MCP_CATALOG.runtime.mode; GitHub reads are health-gated planning context (no producer), never an approvable bounded grant. SAFE_READ_SUPPLEMENT preserves the current allow-list breadth verbatim → deleting SAFE_BETA_CAPABILITY_PATTERNS is not a behavior change.
• Effective-grant lifecycle — projectGrantCovers: boolean → EffectiveGrantState (never-approved / denied / consumed-allow_once / revoked / insufficient / package-local / project-level).
• Total decision table — precedence-ordered; per-capability capabilityClasses stored; required-empty / unknown-capability / mixed-class / ask_user all defined; unknown_legacy for old artifacts (no invented approval state).
• Shape-preserving adapters — McpAdmissionEvaluation { decision, source, health } envelope + referencedHealth.
• Invariant — now expressed via the canonical admitWorkPackageMcp; requiresFilesystemGrantApproval is a tested filesystem projection, not a co-equal source.
• Approval health snapshot — getProjectMcpOverview runs outside the status-flip transaction; checkedAt persisted; parity narrowed to "no missed approval-time block", not "never blocks later".
• Recoverable denied state — required denial holds the package blocked (zero attempts, task not failed); closes the dead-end where the executor throws and the failed package has no mcpGrantBlock marker. Tests assert exact transitions.
• Project-wide reconciliation — one reconcileFilesystemGrantsForProject shared by both grant endpoints, plus a package-local-denial vs later project-always-allow precedence rule.
• Evidence lifecycle — planned scope (pre-run) vs issued packet metadata (post-run, incl. failed runs); file contents stay prompt-only, never persisted (ADR 0008).
• Deferred is actionable — required deferred_live_mcp gets a revise_plan CTA; optional is warning-only/approvable.
• Persisted schema — materializer + buildMcpBrokerBlockMetadata added to the map; metadata.mcpBroker (JSON) vs blocked_reason (text); versioned; multi-block aggregation → retryable + primaryRecoveryAction.
• Slice ownership — each edit has one owner with transitional exports; S4 now depends on S2, S5 on S4 (#179/#180/epic graph updated).

Release-truth (guides)

• operator-guide.md / wiki.md: approval↔handoff MCP parity is now target-state (S2), with the narrowed guarantee.
• developer-guide.md / roadmap.md: classifier is catalog + safe-read supplement, and a bounded packet is delivered only where a producer exists.

Issue graph

• [FEATURE] Add Architect-driven MCP assignment and agent prompt overlays #43 re-scoped to planning/overlay output only; runtime tool-issuance + tool-call-audit ACs deferred to the later security-reviewed live-MCP epic ([FEATURE] Add adversarial agent mode with default rules and project override editor #40, Add security review workforce architecture and subagent taxonomy #60); vocab standardized to github.* / filesystem.project.*.

Second-pass amendments (beyond the comments)

• Made ADR TypeScript self-consistent (named McpAdmissionMode / McpAdmissionStatus / McpRecoveryAction).
• Corrected stale "current divergence" claims against post-refactor main (the per-task grant route already recovers failed/blocked via the marker; the approve route already runs in a db.transaction loading mcpConfig) so the ADR's problem statement matches today's code.