Add Safe Outputs formal specification with comprehensive permission documentation

[Copilot]

Adds W3C-style specification defining the Safe Outputs MCP Gateway's security model, operational semantics, and conformance requirements. The specification establishes normative behavior for all 30+ safe output types based on existing JavaScript handlers and Go compiler implementation.

Specification Structure

• Security Architecture: Privilege separation model, threat scenarios, permission boundaries
• Common Features:
  • max limits (defaults, inheritance, special value semantics for staged mode)
  • staged mode (preview execution, per-type vs global configuration)
  • footer attribution (composition, template variables, conditional installation instructions)
  • Content sanitization (7-stage pipeline for XSS prevention, mention filtering)
• Safe Output Types: Complete MCP tool schemas, operational guarantees, validation rules for all types (create_issue, add_comment, push_to_pull_request_branch, etc.)
• GitHub Permissions: Required GitHub Actions Token and GitHub App permissions for each safe output type, including conditional permissions based on features
• Protocol Patterns: HTTP transport, NDJSON persistence, tool invocation lifecycle
• Execution Guarantees: Atomicity, ordering, idempotency, error handling

Key Semantics Documented

Max Limit Interpretation:

safe-outputs:
  create-issue:
    max: 5  # Allow up to 5 operations
  
  push-to-pull-request-branch:
    staged: true  # Per-type staged mode
    max: 1        # Compiled to max: 0 in MCP config (hide from AI, handler active)

Staged Mode Behavior:

• Global staged: true affects all types
• Per-type staged: true sets max: 0 in MCP configuration (tool hidden from AI but handler processes previews)
• Handlers check GH_AW_SAFE_OUTPUTS_STAGED environment variable and generate step summaries instead of GitHub API calls

Permission Documentation

Each safe output type now includes comprehensive permission requirements:

• GitHub Actions Token Permissions: Standard workflow token requirements with detailed scope descriptions
• GitHub App Permissions: Requirements when using safe-outputs.app configuration
• Conditional Permissions: Features that require additional permissions (e.g., fallback-as-issue for create_pull_request, create-issue for missing_tool/missing_data)
• Permission Scopes: contents, issues, pull-requests, discussions, security-events, actions, organization-projects
• Special Cases: GitHub App-only permissions (organization-projects), cross-repository requirements, system types with no permission requirements

Conformance

Follows RFC 2119 conventions with normative keywords (MUST, SHALL, SHOULD, MAY). Defines full and partial conformance classes with testable requirements.

File: docs/src/content/docs/reference/safe-outputs-specification.md (2,800+ lines)

Custom agent used: w3c-specification-writer
AI technical specification writer following W3C conventions and best practices for formal specifications

Original prompt

Create a specification that defines the foundational security features of safe outout , how to interpret common features like "max" or "staged" and document each safe outout type as well.

Focus on guarantees and operational requirements based on tbe exiting JavaScript implementation, the docs, the go compiler.

create file name the MCP-gateway specification.

Custom agent used: w3c-specification-writer
AI technical specification writer following W3C conventions and best practices for formal specifications

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[pelikhan]

@copilot name file as safe-outputs-specification.md next to mcp-gateway specification

[pelikhan]

@copilot for each safe output type specify the required GitHub action permissions or GitHub app permissions . Handle the case where some permissions are tied to features like fallback-as-issue

[Copilot]

@copilot name file as safe-outputs-specification.md next to mcp-gateway specification

Done! Renamed to safe-outputs-specification.md and updated internal URL reference. (commit 0392d15)

[pelikhan]

@copilot start at 1.0

[Copilot]

@copilot for each safe output type specify the required GitHub action permissions or GitHub app permissions . Handle the case where some permissions are tied to features like fallback-as-issue

Done! Added comprehensive "Required Permissions" sections for all 30+ safe output types with:

• Separate GitHub Actions Token vs GitHub App permission requirements
• Detailed permission scopes (contents, issues, pull-requests, discussions, security-events, actions, organization-projects)
• Conditional permissions tied to features (e.g., fallback-as-issue for create_pull_request, create-issue for missing_tool/missing_data)
• Special notes on GitHub App-only permissions (organization-projects) and cross-repository requirements

Each type now documents exactly which permissions are needed and explains conditional requirements. (commit 347f6df)