docs: document sink-visibility field in MCP Gateway write-sink guard policy (spec v1.15.0) (#44305)

* Initial plan

* docs: add sink-visibility and write-sink guard policy to MCP Gateway spec

- Add Section 4.1.3.8 documenting the new `forcePublicRepos` gateway config field
- Add `forcePublicRepos` to the gateway config fields table (Section 4.1.3)
- Add Section 10.8 — Write-Sink Guard Policy with full `sink-visibility` field specification,
  enforcement model, DIFC semantics, runtime verification, and compiler behavior
- Add Section 10.9 — Cross-Visibility Opt-Out documenting `private-to-public-flows: allow`
  frontmatter option, its constraints, compiler responsibilities, and interaction matrix
- Add compliance test category 11.1.12 with T-WS-001 through T-WS-008
- Update compliance checklist with Write-Sink Guard Policy row
- Add changelog entry for spec version 1.15.0
- Update both JSON schema files (docs/public and pkg/workflow) with:
  - New `writeSinkGuardPolicyConfig` definition with `accept` and `sink-visibility` fields
  - Typed `write-sink` property in `guard-policies` for both stdioServerConfig and httpServerConfig
  - New `forcePublicRepos` boolean field in `gatewayConfig`
  - Added `guard-policies` to `stdioServerConfig` in docs/public schema (was missing)

Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

* fix: restore missing type and description in opentelemetryConfig definition

Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

* docs: clarify sink-visibility enforcement model and fallback behavior

Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

* docs: fix grammar, wording, and contradiction in mcp-gateway spec

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

* docs: add sinkVisibilityExemptServers, default visibility, and safety net

- Add sinkVisibilityExemptServers to gateway config fields table (section 4.1.3)
- Add to JSON schemas in both docs/public and pkg/workflow
- Document default sink-visibility="public" for non-safe-outputs (section 10.8.6)
- Document safe-outputs runtime safety net (section 10.8.7)
- Expand section 10.9 to support list form of private-to-public-flows
- Add compiler responsibilities for list form (validation + config emission)
- Update interaction matrix with list form compatibility

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Landon Cox <landon.cox@microsoft.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: 5 people

docs/public/schemas/mcp-gateway-config.schema.json

@@ -116,6 +116,16 @@
             "type": "string"
           },
           "default": ["*"]
+        },
+        "guard-policies": {
+          "type": "object",
+          "description": "Guard policies for access control at the MCP gateway level. Supports a 'write-sink' policy for DIFC-based output filtering. Additional server-specific policies may be provided.",
+          "properties": {
+            "write-sink": {
+              "$ref": "#/definitions/writeSinkGuardPolicyConfig"
+            }
+          },
+          "additionalProperties": true
         }
       },
       "required": ["container"],
@@ -163,7 +173,12 @@
         },
         "guard-policies": {
           "type": "object",
-          "description": "Guard policies for access control at the MCP gateway level. The structure of guard policies is server-specific. For GitHub MCP server, see the GitHub guard policy schema. For other servers (Jira, WorkIQ), different policy schemas will apply.",
+          "description": "Guard policies for access control at the MCP gateway level. Supports a 'write-sink' policy for DIFC-based output filtering. Additional server-specific policies may be provided.",
+          "properties": {
+            "write-sink": {
+              "$ref": "#/definitions/writeSinkGuardPolicyConfig"
+            }
+          },
           "additionalProperties": true
         },
         "auth": {
@@ -282,11 +297,43 @@
         "opentelemetry": {
           "$ref": "#/definitions/opentelemetryConfig",
           "description": "Optional OpenTelemetry configuration for emitting distributed tracing spans for MCP calls. When configured, the gateway exports OTLP/HTTP traces to the specified collector endpoint."
+        },
+        "forcePublicRepos": {
+          "type": "boolean",
+          "description": "When true (default), forces the allow-only policy to repos=\"public\" at runtime if the gateway detects it is running in a public repository. Set to false by the compiler when private-to-public-flows: allow is declared in workflow frontmatter, or via MCP_GATEWAY_FORCE_PUBLIC_REPOS=false environment variable. See MCP Gateway Specification section 4.1.3.8.",
+          "default": true
+        },
+        "sinkVisibilityExemptServers": {
+          "type": "array",
+          "description": "List of server IDs exempt from the default sink-visibility=\"public\" enforcement. Use [\"*\"] to exempt all servers. Set by the compiler when private-to-public-flows lists specific server IDs in workflow frontmatter. See MCP Gateway Specification section 10.9.",
+          "items": {
+            "type": "string"
+          }
         }
       },
       "required": ["port", "domain", "apiKey"],
       "additionalProperties": false
     },
+    "writeSinkGuardPolicyConfig": {
+      "type": "object",
+      "description": "Write-sink guard policy for DIFC-based output filtering. Controls whether an agent may write to the safe-outputs sink based on the agent's accumulated secrecy tags and the target repository visibility. Per MCP Gateway Specification section 10.8.",
+      "properties": {
+        "accept": {
+          "type": "array",
+          "description": "Secrecy tag patterns that are permitted to write to this sink. Use [\"*\"] to accept all secrecy levels. Required for all write-sink policies. When sink-visibility is \"public\", this field is syntactically required but has no runtime effect — resource secrecy is unconditionally set to empty.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "sink-visibility": {
+          "type": "string",
+          "description": "Declares the visibility of the safe-outputs target repository (always the workflow's own repo, i.e. GITHUB_REPOSITORY). When \"public\", agents with non-empty secrecy are blocked regardless of accept patterns. When \"private\" or \"internal\", standard accept-pattern matching applies. When omitted, backward-compatible accept-pattern matching applies.",
+          "enum": ["public", "private", "internal"]
+        }
+      },
+      "required": ["accept"],
+      "additionalProperties": false
+    },
     "opentelemetryConfig": {
       "type": "object",
       "description": "OpenTelemetry configuration for the MCP Gateway. When present, the gateway emits distributed tracing spans for each MCP tool invocation and exports them via OTLP/HTTP to the configured collector endpoint. Per MCP Gateway Specification section 4.1.3.6.",