docs(specs): flag 058↔057 statelessness conflict + make roadmap.yaml authoritative (#790)

Cross-spec contradiction audit (2026-07-01) of merged-but-unimplemented specs.

Key finding: specs/README.md badges (tasks.md checkbox %) are systematically
stale — most 'drafted/0%' specs are actually shipped. The one genuine design
contradiction is Spec 058 (MCP 2026-07-28 upgrade, BLOCKED) vs SHIPPED Spec 057
(in-proxy profiles): 058 FR-012 forbids per-connection */list variation, but 057
selects the toolset by URL path /mcp/p/<slug>. 028 agent-token scoping is already
compatible (header-carried identity).

- specs/058: add a Cross-Spec Reconciliation note (Option A/B + a plan.md action);
  058 already had US3/FR-011-014 for the token case, this adds the 057 URL case.
- specs/README.md: point to roadmap.yaml/ROADMAP.md as the AUTHORITATIVE status
  source; badges are a stale checkbox heuristic (roadmap.yaml wins on disagreement).
- roadmap.yaml: record the genuinely merged-but-unimplemented specs as epics —
  058 (blocked, with the conflict note), 054 Tracks C/D, 065 discovery-eval half.

Docs/spec-only; no code touched.

Related: Spec 058 (specs/058-mcp-2026-upgrade)

Author: Dumbris

ROADMAP.md

@@ -125,6 +125,9 @@ graph TD
   paid_tier["Paid-tier MVP (billing / seats / license)<br/>MCP-40"]
   sdk_v1_migration["SDK v1 migration"]
   sso["SSO (server edition)"]
+  mcp_2026_upgrade["MCP protocol upgrade to 2026-07-28 revision"]
+  security_gateway_cd["Security gateway Tracks C/D (per-arg least-privilege + signature provenance)"]
+  discovery_eval_harness["Discovery-quality eval harness (Spec 065 second half)"]
 
   profiles_v2_indexes --> profiles_v2_set_profile
   profiles_v2_set_profile --> profiles_v2_profile_pin
@@ -167,7 +170,8 @@ graph TD
   class profiles_v2,profiles_v2_indexes,profiles_v2_set_profile,profiles_v2_profile_pin,profiles_v2_tray_switcher,sandbox_isolation,sandbox_spike,sandbox_mode_config,sandbox_launcher,sandbox_scanner_parity,sandbox_snap_docker_it,ts_code_exec_ga,ts_code_exec_cookbook,scanner_v2,scanner_v2_foundation,scanner_v2_hard_checks,scanner_v2_soft_checks,scanner_v2_consensus,scanner_v2_eval_gate,scanner_v2_docs,registries_official_protocol,scanner_simplification,scanner_simpl_baseline,scanner_simpl_unified_report,scanner_simpl_deep_optin,scanner_simpl_notifications,scanner_simpl_deepscan_fixes,upgrade_nudge_status_log,connect_trust_preview,connect_trust_backup_visibility,telemetry_machineid_client,hygiene_roadmap_github_check done;
   class upgrade_nudge,connect_trust,telemetry_identity in_progress;
   class windows_tray,windows_tray_window in_review;
-  class windows_tray_funnel_qa,ux_audit,ux_audit_webui_sweep,ux_audit_macos_sweep,action_log_transparency,action_log_glance_view,action_log_retention_tie_in,analytics_dashboard,analytics_token_drain_graphs,analytics_default_landing,registries_search_add,registries_search_ux,upgrade_nudge_surfacing,upgrade_nudge_channel,upgrade_nudge_quiet,connect_trust_undo,connect_trust_tcc_copy,telemetry_machineid_worker,telemetry_machineid_dash,telemetry_snapshot_alerting,planning_hygiene,hygiene_tasks_reconcile,hygiene_docs_facts,hygiene_quickstart_contract todo;
+  class mcp_2026_upgrade blocked;
+  class windows_tray_funnel_qa,ux_audit,ux_audit_webui_sweep,ux_audit_macos_sweep,action_log_transparency,action_log_glance_view,action_log_retention_tie_in,analytics_dashboard,analytics_token_drain_graphs,analytics_default_landing,registries_search_add,registries_search_ux,upgrade_nudge_surfacing,upgrade_nudge_channel,upgrade_nudge_quiet,connect_trust_undo,connect_trust_tcc_copy,telemetry_machineid_worker,telemetry_machineid_dash,telemetry_snapshot_alerting,planning_hygiene,hygiene_tasks_reconcile,hygiene_docs_facts,hygiene_quickstart_contract,security_gateway_cd,discovery_eval_harness todo;
   class marketplace,siem,paid_tier,sdk_v1_migration,sso parked;
 ```
 
@@ -179,11 +183,14 @@ graph TD
 | Connect step trust: preview, visible backup, one-click undo | In progress | unassigned | P0 | — | [078-connect-trust-preview](./specs/078-connect-trust-preview/) |  |
 | Telemetry identity & data quality (machine_id + CI-filter hardening) | In progress | unassigned | P1 | — |  |  |
 | Windows native tray app `MCP-43` | In review | BackendEngineer | P2 | 25/60 (42%) | [002-windows-installer](./specs/002-windows-installer/) |  |
+| MCP protocol upgrade to 2026-07-28 revision | Blocked |  | P3 | — | [058-mcp-2026-upgrade](./specs/058-mcp-2026-upgrade/) |  |
 | Web UI + macOS app UX audit | Todo | unassigned | P0 | — |  |  |
 | Action log / transparency — info at a glance | Todo | unassigned | P0 | — |  |  |
 | Analytics dashboard as default page | Todo | unassigned | P1 | 16/26 (62%) | [069-observability-usage-graphs](./specs/069-observability-usage-graphs/) |  |
 | Registries — easier search + add-server | Todo | unassigned | P1 | 3/24 (12%) | [070-registry-easy-upstream-add](./specs/070-registry-easy-upstream-add/) |  |
 | Planning/docs truth automation | Todo | unassigned | P2 | — |  |  |
+| Security gateway Tracks C/D (per-arg least-privilege + signature provenance) | Todo |  | P3 | — | [054-mcp-security-gateway](./specs/054-mcp-security-gateway/) |  |
+| Discovery-quality eval harness (Spec 065 second half) | Todo |  | P3 | — | [065-evaluation-foundation](./specs/065-evaluation-foundation/) |  |
 | Server marketplace `MCP-37` | Todo (parked) |  | P3 | — |  |  |
 | Audit SIEM integration `MCP-39` | Todo (parked) |  | P3 | — |  |  |
 | Paid-tier MVP (billing / seats / license) `MCP-40` | Todo (parked) |  | P3 | — |  |  |

roadmap.yaml

@@ -481,3 +481,29 @@ epics:
     priority: P3
     depends_on: []
     note: "PARKED. Single sign-on for the multi-user server edition."
+
+  # ── MERGED-BUT-UNIMPLEMENTED specs (cross-spec audit 2026-07-01) ───────────
+  # These specs are checked into specs/ but materially absent from code. Most
+  # "drafted/0%" specs are actually SHIPPED (stale tasks.md checkboxes) — these
+  # are the genuinely-unbuilt ones. See docs/personal-edition-polish.md audit.
+  - id: mcp-2026-upgrade
+    title: MCP protocol upgrade to 2026-07-28 revision
+    status: blocked
+    priority: P3
+    spec: specs/058-mcp-2026-upgrade
+    depends_on: []
+    note: "BLOCKED on mcp-go shipping 2026-07-28 (pinned v0.55.x tops out at 2025-11-25). CROSS-SPEC CONFLICT: FR-012 forbids per-connection */list variation; SHIPPED Spec 057 selects toolset by URL path /mcp/p/<slug>. Must reconcile at plan time (058 spec now carries a Cross-Spec Reconciliation note). 028 agent-token scoping is already compatible (header-carried)."
+  - id: security-gateway-cd
+    title: Security gateway Tracks C/D (per-arg least-privilege + signature provenance)
+    status: todo
+    priority: P3
+    spec: specs/054-mcp-security-gateway
+    depends_on: []
+    note: "Track A→Spec 056, Track B→Spec 059 (both shipped). UNBUILT: Track C per-ARGUMENT allow-listing (per-tool scope exists in mcp_direct_scope.go); Track D provenance + human-readable signature diff (SHA-256 pinning exists via Spec 032). Build ON 032/028, don't re-implement; honor the rug-pull re-quarantine interaction rule vs 032 auto-approve."
+  - id: discovery-eval-harness
+    title: Discovery-quality eval harness (Spec 065 second half)
+    status: todo
+    priority: P3
+    spec: specs/065-evaluation-foundation
+    depends_on: []
+    note: "Security recall/FP half SHIPPED (cmd/scan-eval, backs Spec 076/077 gate). UNBUILT: the discovery-quality (retrieve_tools recall) eval harness."

specs/058-mcp-2026-upgrade/spec.md

@@ -9,6 +9,16 @@
 
 This feature **cannot begin implementation** until the upstream MCP client/server library (`github.com/mark3labs/mcp-go`) ships support for protocol revision `2026-07-28`. As of 2026-05-28 the pinned library (v0.54.0) and the latest published release (v0.54.1) both target only `2025-11-25`; no `2026-07-28` constant exists in the library. This spec captures the full upgrade scope now so execution can start immediately once the gate clears. A scheduled tracking agent watches the library and the spec's RC→final status and notifies the maintainer when the gate opens.
 
+## Cross-Spec Reconciliation *(read at plan time)*
+
+> **Flagged 2026-07-01 (cross-spec contradiction audit).** FR-012 forbids per-connection variation of `*/list` results; identity-scoped views must be driven by request-carried identity (token / headers / `_meta`), **not connection state**. US3 + FR-013 already reconcile **Spec 028 agent-token scoping** — token identity travels in the `Authorization` header, so it is request-carried and compatible.
+>
+> **The unresolved case is Spec 057 (In-Proxy Profiles), which is SHIPPED on main.** Spec 057 selects a filtered per-profile toolset by **URL path** (`/mcp/p/<slug>`), not by `_meta`/header identity. Under FR-012 this MUST be classified before implementation:
+> - **Option A — treat the profile URL path as request-carried identity.** Each request line carries the slug, so arguably it is *not* connection state. But a client that opens a stream to `/mcp/p/<slug>` binds the profile to that endpoint, which is closer to connection state than to `_meta` identity, and FR-014 forbids relying on a long-lived GET stream — so profile routing must remain correct in a purely stateless, request-scoped model.
+> - **Option B — move profile selection into `_meta`/a header** (e.g. a `profile` field in per-request `_meta`), demoting or deprecating the `/mcp/p/<slug>` path form for `2026-07-28` clients while keeping it for `2025-11-25` clients during the deprecation window.
+>
+> **Action for plan.md:** pick A or B explicitly, add an acceptance scenario proving per-profile filtering (Spec 057) works under the stateless model without per-connection list variation, and confirm `GET`/`DELETE` on `/mcp/p/<slug>` follow FR-014. Do not implement 058 without resolving this — building FR-012 naively would break shipped per-profile routing. (028 needs no change; 057 does.)
+
 ## User Scenarios & Testing *(mandatory)*
 
 ### User Story 1 - Connecting clients negotiate the new protocol without breakage (Priority: P1)

specs/README.md

@@ -1,6 +1,8 @@
 # Specs Index
 
-Every numbered directory under `specs/` is a feature specification produced with [GitHub spec-kit](https://github.com/github/spec-kit). This page is the canonical list; badges reflect `tasks.md` checklist progress and are a quick heuristic — not a guarantee. When ambiguous, cross-check `git log --grep='<spec-number>'` and the spec's `plan.md`.
+Every numbered directory under `specs/` is a feature specification produced with [GitHub spec-kit](https://github.com/github/spec-kit).
+
+> **Authoritative status lives in [`../roadmap.yaml`](../roadmap.yaml)** (rendered to [`../ROADMAP.md`](../ROADMAP.md)), **not in the badges below.** The badges on this page are derived purely from `tasks.md` checkbox counts and are known to be **systematically stale** — many specs shown as `drafted`/`0%` are in fact shipped (the checkboxes were never ticked after implementation). `roadmap.yaml` carries an explicit `status` field (`todo`/`in_progress`/`in_review`/`blocked`/`done`) per epic that does not depend on checkbox hygiene. Treat the table below as a spec *directory*, and `roadmap.yaml`/`ROADMAP.md` as the source of truth for **what is actually built**. When a badge and `roadmap.yaml` disagree, `roadmap.yaml` wins; confirm against code (`git log --grep='<spec-number>'`, or grep for the spec's key symbols) rather than the badge.
 
 **Status legend**