docs(054): MCP security gateway hardening — umbrella spec (5 tracks)

docs/mcp-registry-publishing.md

@@ -2,7 +2,7 @@
 
 This guide covers how to publish (or update) the `server.json` at the repo root to the official [MCP Registry](https://registry.modelcontextprotocol.io).
 
-**Publishing is automated.** The [`.github/workflows/publish-mcp-registry.yml`](../.github/workflows/publish-mcp-registry.yml) workflow publishes `server.json` on every GitHub Release using keyless GitHub OIDC auth — no stored token or secret. It syncs `server.json`'s `version` to the release tag at publish time, so you don't need to hand-bump it. The manual steps below remain useful for first-time setup, validation, ad-hoc `workflow_dispatch` runs, and deprecating versions.
+**Publishing is already automated** by the `mcp-registry` job in [`.github/workflows/release.yml`](../.github/workflows/release.yml). On every tag/release it authenticates with keyless GitHub OIDC (no stored token/secret), syncs `server.json`'s `version` to the release tag, and publishes — so you never hand-publish a release. The job is `continue-on-error: true`, so a duplicate-version push (the registry stores versions immutably) won't fail the release. The manual steps below remain useful for first-time setup, local validation, and deprecating versions.
 
 ## Prerequisites
 
@@ -92,8 +92,8 @@ mcp-publisher status --status deleted \
 
 ## What Requires the User
 
-- **GitHub authentication**: Only a member/owner of the `smart-mcp-proxy` GitHub org can authenticate for the `io.github.smart-mcp-proxy` namespace. There is no way to delegate or automate this without adding a GitHub Actions workflow with `id-token: write` permission to the release pipeline.
-- **Automating via CI** (done): [`.github/workflows/publish-mcp-registry.yml`](../.github/workflows/publish-mcp-registry.yml) runs `mcp-publisher login github-oidc` + `mcp-publisher publish` on `release: published` (and via manual `workflow_dispatch`). It declares `id-token: write`, downloads the pinned `mcp-publisher` binary, syncs `version` from the release tag, validates, then publishes. The OIDC token is minted per run and valid only for that run — no secret is stored. The first run must succeed as a member identity of the `smart-mcp-proxy` org (the workflow's repo identity satisfies this).
+- **Nothing, for the normal release path.** The `mcp-registry` job in [`.github/workflows/release.yml`](../.github/workflows/release.yml) already runs `mcp-publisher login github-oidc` + `mcp-publisher publish` on every tag (`id-token: write`, `continue-on-error: true`). The workflow's repo OIDC identity proves `smart-mcp-proxy` org membership, which owns the `io.github.smart-mcp-proxy` namespace — no secret or interactive login is involved.
+- **Manual interactive login** (`mcp-publisher login github`) is only needed for out-of-band actions: validating locally, deprecating/deleting a published version, or a one-off re-publish. Note its browser-issued token is short-lived and expires quickly.
 
 ## Registry Schema Notes
 

specs/054-mcp-security-gateway/checklists/requirements.md

@@ -0,0 +1,36 @@
+# Specification Quality Checklist: MCP Security Gateway Hardening
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-05-23
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+  - Note: file:line pointers appear in a clearly-labelled "Context" section as gap-analysis grounding for an umbrella eng spec; FRs and success criteria themselves stay behavioural/technology-agnostic.
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders (user stories framed as operator outcomes)
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain (informed assumptions documented in Assumptions)
+- [x] Requirements are testable and unambiguous (each FR has a verifiable behaviour; each story has an Independent Test)
+- [x] Success criteria are measurable (SC-001…SC-008, mostly 100%/detection-rate framed)
+- [x] Success criteria are technology-agnostic
+- [x] All acceptance scenarios are defined (Given/When/Then per track)
+- [x] Edge cases are identified (per-track, incl. the ContextForge #4042 trap and async-vs-hash-chain)
+- [x] Scope is clearly bounded (5 tracks + Non-Goals + "docs restructure is a separate spec")
+- [x] Dependencies and assumptions identified (Context section maps each track to existing Spec; Assumptions section)
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows (one prioritised story per track A–E)
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into the requirements/success sections
+
+## Notes
+
+- This is an **umbrella spec**; each track should get its own `/speckit.plan` (and `/speckit.tasks`) when implementation starts. Recommend running `/speckit.plan` per track (A first) rather than for the whole umbrella at once.
+- Validation passed on first iteration; no [NEEDS CLARIFICATION] markers.