docs: pin GlitchTip filing orchestrator contract (Closes #153)

docs/architecture/glitchtip-to-gitea-workflow-design.md

@@ -1,21 +1,34 @@
-# GlitchTip-to-Gitea Issue Filing Workflow Design
+# GlitchTip-to-Gitea Issue Filing Workflow Contract
 
-- **Status:** Design (no implementation in this repo)
-- **Issue:** #74 (parent umbrella: #75)
+- **Status:** Contract for the library-only implementation in
+  `Scaled-Tech-Consulting/mcp-control-plane` (#57)
+- **Issue:** #153 (supersedes #74/#78 as the Gitea-Tools tracker)
 - **Related:** #78 (deduplication design, child of #74)
-- **Date:** 2026-07-02
+- **Date:** 2026-07-07
 
 ## 1. Boundary and Orchestration
 
 * **GlitchTip-to-Gitea filing is NOT a GlitchTip MCP capability.** The `glitchtip-mcp` boundary remains strictly read-only per ADR-0001.
-* The filing capability lives in an **orchestrator / runbook / release workflow**. It **composes** separate GlitchTip **read** tools (from the `glitchtip-mcp` server) and Gitea **issue** tools (from the `gitea-mcp` server).
+* The filing capability lives in a **library-only orchestrator** in
+  `mcp-control-plane` and is not exposed through `glitchtip-mcp`.
+* The orchestrator composes the real GlitchTip read path with Gitea
+  issue-write tools. It must not use mocked GlitchTip issue data in production
+  filing paths.
 * The orchestrator **must not centralize credentials** into a single server. The GlitchTip MCP holds only GlitchTip tokens, and the Gitea MCP holds only Gitea tokens.
+* If a future MCP surface exposes filing, it must be a separate write-boundary
+  server/profile with explicit Gitea issue-write permission and the same audit
+  gates. It must not be added to the read-only `glitchtip-mcp` surface.
 
 ## 2. Invocation and Safety
 
 * **Explicit invocation only:** There is no automatic, unsupervised filing in phase 1. A human or an explicitly-triggered automation must initiate the workflow.
 * **Dry-run / Preview required:** The orchestrator must present a preview of the drafted Gitea issue (title, body, labels) and obtain explicit confirmation before calling the Gitea mutation tool to file the issue.
-* **Gitea Profile Checks & Audit Logging:** The actual Gitea issue creation relies on `gitea-mcp`, and therefore inherently subjects the mutation to Gitea profile checks and audit logging as standard.
+* **Gitea Profile Checks & Audit Logging:** The actual Gitea issue creation
+  relies on `gitea-mcp`, and therefore must pass Gitea profile checks and
+  fail-closed mutation audit before create/link/comment actions.
+* **Deduplication before create:** The orchestrator must run the
+  GlitchTip-to-Gitea dedup/linking logic before any Gitea create action. Create,
+  link, and skip decisions must be represented in tests.
 
 ## 3. Gitea Issue Format
 
@@ -51,6 +64,23 @@ To prevent PII or secret leakage into Gitea, the orchestrator and the underlying
 
 The principle is: **"Link, don't dump"**. The generated issue acts as an alert/pointer, while the raw context remains protected inside GlitchTip.
 
-## 5. Deduplication and Linking (Deferred)
+## 5. Deduplication and Linking
 
-Deduplication logic (e.g. searching existing Gitea issues, managing GlitchTip issue IDs, and race condition handling) is specifically handled by **Issue #78** and will augment this design.
+Deduplication logic (e.g. searching existing Gitea issues, managing GlitchTip
+issue IDs, and race condition handling) is integrated into the library-only
+filing orchestrator in `mcp-control-plane`. The orchestrator must reuse that
+dedup/linking path instead of duplicating or bypassing it.
+
+## 6. Gitea-Tools Acceptance Contract for #153
+
+Gitea-Tools does not host the filing implementation. This repository owns the
+operator-facing contract:
+
+* `glitchtip-mcp` remains read-only and exposes only GlitchTip inspection tools.
+* Filing is implemented in `mcp-control-plane`, not in this Gitea MCP runtime.
+* Filing uses the real GlitchTip read path, not mocked issue data.
+* Dedup runs before any Gitea create action.
+* Create/link/skip decisions and audit failure are covered by orchestrator tests.
+* Mutation audit fails closed before any Gitea create, link, or comment mutation.
+* Any future MCP exposure requires a separate write-boundary server/profile and
+  must not add Gitea write credentials to `glitchtip-mcp`.

docs/mcp-client-registration.md

@@ -95,7 +95,14 @@ back to shell commands, raw service APIs, or unrelated MCP servers.
 - Do not register `jenkins-write-mcp` until an operator approves a trigger
   profile; no shipped profile carries trigger capability by default.
 - `glitchtip-mcp` remains read-only. It must not file or mutate Gitea issues.
-- GlitchTip-to-Gitea filing is a separate orchestrator that composes GlitchTip
-  read tools with Gitea issue-write tools.
+- GlitchTip-to-Gitea filing is a separate library-only orchestrator in
+  `mcp-control-plane` that composes the real GlitchTip read path with Gitea
+  issue-write tools.
+- The filing orchestrator must run GlitchTip/Gitea dedup before any Gitea
+  create action, and its create/link/skip decisions must be covered by tests.
+- The filing orchestrator must fail closed on mutation-audit failure before
+  any Gitea create, link, or comment mutation.
+- If filing is ever MCP-exposed, it must use a separate write-boundary
+  server/profile. It must not be exposed by `glitchtip-mcp`.
 - Gitea credentials never enter Jenkins or GlitchTip runtimes.
 - Jenkins and GlitchTip credentials never enter the Gitea MCP runtime.

tests/test_external_mcp_registration_docs.py

@@ -59,6 +59,22 @@ def test_registration_doc_preserves_boundaries():
         assert phrase in text
 
 
+def test_registration_doc_pins_glitchtip_filing_boundary():
+    text = " ".join(_doc_text().split())
+    for phrase in (
+        "GlitchTip-to-Gitea filing is a separate library-only orchestrator in "
+        "`mcp-control-plane`",
+        "real GlitchTip read path",
+        "dedup before any Gitea create action",
+        "create/link/skip decisions",
+        "fail closed on mutation-audit failure before any Gitea create, link, "
+        "or comment mutation",
+        "must use a separate write-boundary server/profile",
+        "must not be exposed by `glitchtip-mcp`",
+    ):
+        assert phrase in text
+
+
 def test_registration_doc_separates_jenkins_trigger_from_read_surface():
     text = _doc_text()
     assert "jenkins_trigger_build" in text
@@ -100,3 +116,25 @@ def test_related_docs_keep_jenkins_trigger_off_read_surface():
         assert "jenkins-write-mcp" in text
         assert "jenkins_mcp.write_server" in text
         assert "jenkins-mcp" in text
+
+
+def test_glitchtip_filing_contract_doc_covers_issue_153_acceptance():
+    text = (
+        REPO_ROOT / "docs" / "architecture" /
+        "glitchtip-to-gitea-workflow-design.md"
+    ).read_text(encoding="utf-8")
+    flattened = " ".join(text.split())
+    for phrase in (
+        "**Status:** Contract for the library-only implementation in "
+        "`Scaled-Tech-Consulting/mcp-control-plane` (#57)",
+        "**Issue:** #153",
+        "not exposed through `glitchtip-mcp`",
+        "real GlitchTip read path",
+        "must not use mocked GlitchTip issue data",
+        "separate write-boundary server/profile",
+        "fail-closed mutation audit before create/link/comment actions",
+        "Deduplication before create",
+        "Create, link, and skip decisions must be represented in tests",
+        "Mutation audit fails closed",
+    ):
+        assert phrase in flattened