rosett-ai 1.3.3

data/conf/design/licensing_system.yml

@@ -0,0 +1,88 @@
+---
+name: licensing_system
+domain: licensing
+version: 1.1.0
+status: implemented
+priority: 4
+author: hugo
+created_at: "2026-02-18"
+modified_at: "2026-03-17"
+modified_by: claude
+depends_on:
+  - security
+  - architecture
+
+intent: |
+  Implement a license key system that supports the open-core monetization model.
+  License keys unlock access to downloading premium content packs — they NEVER
+  restrict software functionality. The GPL-3.0 software is always fully
+  functional without a license key. Keys use Ed25519-signed JWTs that are
+  offline-verifiable with an embedded public key, ensuring users can validate
+  their license without internet access. Trust-first design means content
+  doesn't disappear on expiry — it stops updating.
+
+constraints:
+  - License keys NEVER enable or disable software features (GPL-3.0 compliance)
+  - License keys ONLY control access to downloading premium content
+  - User without a license has full rosett-ai software functionality
+  - License keys are Ed25519-signed JWTs with offline verification
+  - Public verification key is embedded in source (safe — cannot forge, only verify)
+  - Private signing key is never in the codebase or on client machines
+  - License file stored at ~/.config/rosett-ai/license.key with 0600 permissions
+  - Premium content works offline indefinitely for perpetual tier licenses
+  - Subscription content works offline for 30-day grace period after last sync
+  - Content does NOT disappear on subscription expiry — it freezes at last version
+  - Expiry grace period is 14 days after subscription end before content freezes
+  - License validation must complete in under 100ms (offline check)
+
+acceptance_criteria:
+  - bin/raictl license activate NNCC-... validates and stores license key
+  - bin/raictl license status shows current tier, expiry, and entitled features
+  - bin/raictl license deactivate removes license (reverts to community tier)
+  - Offline license validation works without internet
+  - Forged keys (wrong signature) are rejected with clear error message
+  - Expired subscription keys show warning but don't crash
+  - ~/.config/rosett-ai/license.key is created with 0600 permissions
+  - Property-based tests verify forged keys are always rejected
+  - Mutation score for licensing module is >= 95%
+
+examples:
+  - scenario: "User activates a valid Supporter license key"
+    expected: |
+      Key decoded, signature verified against embedded public key.
+      Tier set to supporter. License stored at ~/.config/rosett-ai/license.key (0600).
+      'License activated: Supporter tier. You have access to premium content packs.'
+    not: "Key stored without verification. Permissions set to 0644."
+  - scenario: "Someone forges a license key with a different private key"
+    expected: "Ed25519 signature verification fails. 'Invalid license key: signature verification failed.'"
+    not: "Key is accepted because the JWT structure looks valid."
+  - scenario: "Subscriber license expired 10 days ago"
+    expected: |
+      Warning: 'Subscription expired 10 days ago. Premium content available
+      for 4 more days. Renew to continue receiving updates.' Software works fully.
+      Previously downloaded content still accessible.
+    not: "Software crashes. Content deleted. Features disabled."
+  - scenario: "User runs rosett-ai on a machine with no internet and a valid perpetual license"
+    expected: "License validated offline against embedded public key. Full premium content access."
+    not: "Online check fails and license is rejected."
+
+anti_patterns:
+  - Checking license key to enable/disable software features
+  - Storing private signing key in the codebase
+  - Deleting premium content when a license expires
+  - Requiring internet for perpetual license validation
+  - Storing license files with world-readable permissions
+  - Logging or displaying the full license key in output
+  - Using symmetric signing (HMAC) where the secret would need to be in the client
+
+preferences:
+  language: ruby
+  gems:
+    - jwt
+    - ed25519
+    - faraday
+  patterns:
+    - offline_first_validation
+    - trust_first_expiry_design
+    - principle_of_least_privilege
+  testing: rspec with property-based tests for cryptographic validation

data/conf/design/lifecycle_management.yml

@@ -0,0 +1,208 @@
+---
+name: lifecycle_management
+domain: core
+version: 1.1.0
+status: implemented
+priority: 1
+author: hugo
+created_at: "2026-02-19"
+modified_at: "2026-03-17"
+modified_by: claude
+depends_on:
+  - security
+  - testing
+  - ci_pipeline
+
+intent: |
+  Define repeatable, auditable processes for upgrading software components
+  (Ruby runtime, gems, system libraries, build tools) across the rai project.
+  Upgrades are security-critical operations — a missed CVE fix is a vulnerability,
+  a botched upgrade is downtime. This document captures the methodology, decision
+  criteria, and verification steps so that every upgrade follows the same rigorous
+  pattern regardless of who (or what AI) performs it.
+
+  Without lifecycle management:
+  - Version references drift across files (CLAUDE.md says one thing, .ruby-version another)
+  - Security patches are applied late or inconsistently
+  - Upgrades break things because verification was incomplete
+  - Knowledge about how to upgrade is tribal, not documented
+
+  With lifecycle management:
+  - Single source of truth for version pins
+  - CVE-driven upgrade triggers with clear escalation
+  - Repeatable verification checklist
+  - Auditable trail of what changed and why
+
+constraints:
+  - Every upgrade must be triggered by a documented reason (CVE, EOL, dependency requirement, performance)
+  - Version references must be updated atomically — no partial updates where some files say old and others say new
+  - The full verification suite must pass before an upgrade is committed (security audit, linter, smell detector, tests)
+  - Upgrades must not skip intermediate verification steps even when the change appears trivial
+  - Breaking changes in a dependency must be researched against official documentation before upgrading
+  - Rollback path must be identified before starting (e.g. rbenv still has the old version installed)
+  - Pre-commit hooks must pass — never bypass hooks to land an upgrade faster
+  - Gem version constraints must use pessimistic operator (~>) to allow patch updates while preventing breaking changes
+  - The commit message must reference the specific CVEs or reasons that triggered the upgrade
+
+acceptance_criteria:
+  - All version references across the codebase are consistent after an upgrade
+  - ruby-audit reports 0 vulnerabilities after a Ruby upgrade
+  - bundler-audit reports 0 vulnerabilities after a gem upgrade
+  - RuboCop, Reek, Flay, and Flog run without regressions (Flog deferred — covered by RuboCop Metrics cops)
+  - Full RSpec suite passes with 0 failures
+  - Commit message includes CVE identifiers or upgrade rationale
+  - No files contain stale version references (verified by grep)
+
+examples:
+  - scenario: "ruby-audit flags 3 CVEs in Ruby 3.3.8 (resolv DoS, REXML DoS, URI credential leak)"
+    expected: |
+      1. Research: check ruby-lang.org/en/downloads/releases/ for latest 3.3.x patch
+      2. Research: verify rbenv has the target version (rbenv install --list | grep 3.3)
+      3. Identify scope: grep codebase for all '3.3.8' references
+      4. Install: rbenv install 3.3.10
+      5. Pin: update .ruby-version to 3.3.10
+      6. Reinstall: bundle install (full gem reinstall under new Ruby)
+      7. Update refs: all files containing old version (CLAUDE.md, README.md, docs, specs)
+      8. Verify: ruby-audit (0 vulns), rubocop (0 offenses), reek (0 warnings), rspec (0 failures)
+      9. Commit: reference CVE-2025-24294, CVE-2025-58767, CVE-2025-61594 in message
+    not: |
+      Upgrade Ruby without checking all file references. Commit with failing ruby-audit.
+      Skip bundle install assuming old gems work. Use --no-verify to bypass hooks.
+
+  - scenario: "bundler-audit flags a CVE in a direct dependency"
+    expected: |
+      1. Research: check RubyGems for latest patched version
+      2. Verify: the new version is compatible with existing Gemfile constraints
+      3. Update: Gemfile constraint if needed, run bundle update <gem>
+      4. Verify: full suite passes (rubocop, reek, rspec, bundler-audit)
+      5. Commit: reference CVE and gem name in commit message
+    not: |
+      Blindly run 'bundle update' without targeting the specific gem.
+      Ignore transitive dependency CVEs. Skip test suite.
+
+  - scenario: "A Ruby minor version reaches end-of-life"
+    expected: |
+      1. Research: check endoflife.date/ruby and ruby-lang.org for EOL dates
+      2. Plan: identify next supported minor version (e.g. 3.3 → 3.4)
+      3. Research: read CHANGELOG for breaking changes between minor versions
+      4. Test: install new version in parallel, run full suite
+      5. Update: .ruby-version, gemspec required_ruby_version, all doc references
+      6. Verify: all tools pass, no deprecation warnings in test output
+      7. Commit: reference EOL policy in commit message
+    not: |
+      Stay on EOL version indefinitely. Jump multiple minor versions without
+      reading changelogs. Update .ruby-version without updating gemspec constraint.
+
+  - scenario: "A new pre-commit hook (e.g. RubyAudit) blocks commits due to existing issues"
+    expected: |
+      1. Assess: determine if the issues are fixable before committing the hook
+      2. If fixable: fix the issues first, then commit hook + fixes together
+      3. If not immediately fixable: set hook to on_warn: warn (report, don't block),
+         commit with a plan to promote to on_warn: fail after the issues are resolved
+    not: |
+      Use --no-verify to bypass the new hook. Remove the hook because it's inconvenient.
+      Leave on_warn: warn permanently without a follow-up plan.
+
+  - scenario: "Upgrading flog or flay reveals new code quality findings"
+    expected: |
+      Review new findings. If they represent real improvements, fix them.
+      If the tool changed thresholds or scoring, update exclusions with justification.
+      Never suppress findings without documenting why.
+    not: |
+      Downgrade the tool to avoid new findings. Add blanket exclusions without review.
+
+anti_patterns:
+  - Upgrading without checking official release notes or changelogs
+  - Partial version reference updates (some files updated, others forgotten)
+  - Running 'bundle update' without targeting specific gems (risks cascading breakage)
+  - Skipping the verification suite because "it's just a patch version"
+  - Bypassing pre-commit hooks with --no-verify to land an upgrade faster
+  - Upgrading production dependencies based on blog posts instead of official documentation
+  - Leaving stale version pins in documentation after an upgrade
+  - Mixing unrelated changes into an upgrade commit (keep upgrades atomic)
+  - Upgrading multiple unrelated components in a single commit (one concern per commit)
+  - Ignoring deprecation warnings in test output after an upgrade
+  - Assuming backwards compatibility without verification
+
+preferences:
+  language: ruby
+  gems:
+    - ruby_audit
+    - bundler-audit
+  patterns:
+    - cve_driven_upgrades
+    - atomic_version_updates
+    - grep_before_commit
+    - full_suite_verification
+  testing: rspec with version-sensitive fixtures
+  # Research plan methodology — the repeatable process for any component upgrade.
+  # This was derived from the Ruby 3.3.8 → 3.3.10 upgrade (2026-02-19).
+  research_methodology:
+    trigger: |
+      An upgrade is triggered by one of: security audit finding (ruby-audit, bundler-audit),
+      end-of-life announcement, dependency requirement, or performance regression.
+    phases:
+      - name: discovery
+        description: Identify what needs upgrading and why
+        tasks:
+          - Run security audit tools (ruby-audit, bundler-audit) to identify CVEs
+          - Record each CVE identifier, severity, and affected component
+          - Determine the minimum version that resolves all identified CVEs
+      - name: research
+        description: Verify the target version exists and is suitable
+        tasks:
+          - Check official release page (e.g. ruby-lang.org/en/downloads/releases/)
+          - Check version manager availability (rbenv install --list | grep <version>)
+          - Read release notes for breaking changes or new deprecations
+          - Verify target version satisfies gemspec/dependency constraints
+      - name: scope
+        description: Map every file that references the current version
+        tasks:
+          - "grep -r '<current_version>' across the entire codebase"
+          - Categorize findings into config (.ruby-version), docs (CLAUDE.md, README), specs, build scripts
+          - Note any version-dependent logic in source code
+      - name: execute
+        description: Perform the upgrade
+        tasks:
+          - Install new version (rbenv install <version>)
+          - Update version pin (.ruby-version)
+          - Reinstall dependencies (bundle install)
+          - Update all version references identified in scope phase
+      - name: verify
+        description: Confirm nothing is broken
+        tasks:
+          - "Security: ruby-audit check → 0 vulnerabilities"
+          - "Security: bundler-audit check → 0 vulnerabilities"
+          - "Style: rubocop → 0 offenses"
+          - "Smells: reek lib/ → 0 warnings"
+          - "Duplication: flay lib/ → no regressions"
+          - "Complexity: flog lib/ → no regressions"
+          - "Tests: rspec → 0 failures"
+          - "Grep: no stale version references remain"
+      - name: commit
+        description: Create an auditable record
+        tasks:
+          - Stage only upgrade-related files (no unrelated changes)
+          - Write commit message referencing CVEs or upgrade rationale
+          - Let pre-commit hooks run (never --no-verify)
+          - Verify hooks pass (especially the newly relevant security hooks)
+    reference_execution:
+      date: "2026-02-19"
+      component: Ruby runtime
+      from_version: 3.3.8
+      to_version: 3.3.10
+      trigger: ruby-audit flagged CVE-2025-24294, CVE-2025-58767, CVE-2025-61594
+      files_updated:
+        - .ruby-version
+        - CLAUDE.md
+        - README.md
+        - doc/USAGE.md
+        - doc/PACKAGING.md
+        - spec/rosett_ai/thor/tasks/build_package_spec.rb
+      verification_results:
+        ruby_audit: 0 vulnerabilities
+        rubocop: 44 files, 0 offenses
+        reek: 0 warnings
+        flay: 199 total score (unchanged)
+        rspec: 277 examples, 0 failures
+        coverage: 92.92%

data/conf/design/mcp_integration.yml

@@ -0,0 +1,207 @@
+---
+name: mcp_integration
+domain: core
+version: 0.1.0
+status: implemented
+priority: 2
+author: hugo
+created_at: "2026-02-24"
+modified_at: "2026-03-16"
+modified_by: claude
+depends_on:
+  - security
+  - architecture
+  - compiler
+  - engine_architecture
+  - error_handling
+#
+intent: |
+  Enable rosett-ai to participate in the Model Context Protocol (MCP) ecosystem as both
+  a provider and an administrator. This serves two purposes:
+
+  1. **rosett-ai as MCP server**: Expose rosett-ai's validation, compilation, and configuration
+     management capabilities as MCP tools/resources/prompts, making them available to
+     any MCP-compatible AI agent (Claude Code, Goose, Cursor, Copilot, etc.).
+
+  2. **MCP administration**: Provide structured management of multiple MCP server
+     configurations — discovery, validation, lifecycle management, and health monitoring.
+     This fills a gap in the AAIF ecosystem where no tool currently provides structured,
+     validated, auditable MCP server administration.
+
+  MCP is now an AAIF-governed standard (donated by Anthropic, Dec 2025) with 10,000+
+  published servers and 97M+ monthly SDK downloads. The Ruby SDK (mcp gem v0.7.1,
+  Apache-2.0) provides production-ready server and client implementations.
+
+  A key differentiator is compliance auditing: the CRA (Cyber Resilience Act),
+  NIS2, and DORA require demonstrable security practices. MCP admin tooling that
+  provides auditable configuration management and compliance reporting has genuine
+  enterprise value that no current AAIF project addresses.
+
+  For the OpenVox Puppet ecosystem specifically, building an MCP server from the
+  Ruby SDK is estimated at 6-10 weeks for an MVP. Puppet Enterprise already ships
+  native MCP (proprietary Infra Assistant), but OpenVox has no equivalent.
+
+  This design governs protocol participation and MCP server/admin implementation.
+  Trust-first server installation and configuration management is governed by
+  mcp_settings.yml. AAIF ecosystem strategic positioning is governed by
+  aaif_alignment.yml. Error handling for MCP commands follows error_handling.yml.
+#
+constraints:
+  - "Must use the official MCP Ruby SDK (mcp gem) — no custom protocol implementation"
+  - "MCP spec version support must be explicit — start with 2025-03-26, track newer revisions"
+  - "All MCP tools must validate input against JSON Schema before execution"
+  - "MCP server must run via stdio transport by default (subprocess model)"
+  - "Streamable HTTP transport is optional and must require explicit opt-in"
+  - "No MCP tool may perform destructive operations without user confirmation"
+  - "MCP tool annotations must accurately reflect behaviour (readOnlyHint, destructiveHint)"
+  - "Server-side secrets (API keys, tokens) must never be exposed via MCP resources"
+  - "MCP server must declare capabilities honestly — no overclaiming"
+  - "Array-form system() for any subprocess spawning within MCP tools"
+  - "YAML.safe_load only for any YAML processing within MCP tools"
+  - "MCP admin configurations must be validated against a schema before use"
+  - "MCP server health checks must timeout (max 5s) and never block the main process"
+  - "This design governs MCP protocol participation and server/admin implementation.
+    Trust-first configuration management is governed by mcp_settings.yml.
+    AAIF ecosystem positioning is governed by aaif_alignment.yml"
+#
+acceptance_criteria:
+  - "rosett-ai exposes at least 5 MCP tools (validate, compile, behaviour_list, design_list, config_status)"
+  - "rosett-ai exposes behaviours and design documents as MCP resources with proper URIs"
+  - "rosett-ai exposes at least 2 MCP prompts (validation workflow, compilation workflow)"
+  - "MCP server starts via `bin/raictl mcp serve` and communicates over stdio"
+  - "MCP server passes the MCP reference test suite (if available)"
+  - "MCP admin can list, validate, and report status of configured MCP servers"
+  - "MCP admin configurations are validated against conf/schemas/mcp_server_schema.json"
+  - "All MCP tools have accurate annotations (readOnlyHint, destructiveHint)"
+  - "Integration tests verify MCP protocol handshake and tool execution"
+  - "MCP server gracefully handles malformed JSON-RPC messages (no crash, proper error response)"
+  - "Documentation includes example Claude Code MCP configuration for Rosett-AI"
+  - "MCP admin supports at least stdio and streamable HTTP server types"
+  - "MCP admin provides compliance-relevant audit output (who configured what, when, validation status)"
+  - "CLI command `bin/raictl mcp list` shows all configured MCP servers with status"
+  - "CLI command `bin/raictl mcp validate` validates MCP server configurations against schema"
+  - "CLI command `bin/raictl mcp status` reports health of configured MCP servers"
+  - "Exit code 0 on success, 1 on MCP server errors, 2 on validation failures"
+  - "TTY-aware output: formatted table when interactive, JSON when piped"
+#
+examples:
+  - scenario: "User configures Claude Code to use rosett-ai as an MCP server"
+    expected: |
+      In ~/.claude/settings.json:
+      {
+        "mcpServers": {
+          "rosett-ai": {
+            "command": "bin/raictl",
+            "args": ["mcp", "serve"],
+            "env": {}
+          }
+        }
+      }
+      Claude Code discovers rosett-ai tools and can validate/compile behaviours.
+    not: "User must manually configure JSON-RPC endpoints or protocol details"
+  - scenario: "AI agent calls the rai validate tool via MCP"
+    expected: |
+      Tool call: { name: "rai_validate", arguments: { scope: "behaviour" } }
+      Response: structured validation results with file paths, errors, warnings.
+      Tool annotation: readOnlyHint=true, destructiveHint=false.
+    not: "Validation modifies any files or returns unstructured text"
+  - scenario: "AI agent calls the rai compile tool via MCP"
+    expected: |
+      Tool call: { name: "rai_compile", arguments: { simulate: true, verbose: true } }
+      Response: diff output showing what would change, no files written.
+      Tool annotation: readOnlyHint=true (simulate), destructiveHint=false.
+      When simulate=false: readOnlyHint=false, user confirmation required.
+    not: "Compilation runs without simulate flag and overwrites files without confirmation"
+  - scenario: "AI agent requests list of configured MCP servers from admin"
+    expected: |
+      Tool call: { name: "rosett_ai_mcp_list", arguments: {} }
+      Response: JSON array of configured servers with name, type, status, transport.
+    not: "Returns internal config file paths or credentials"
+  - scenario: "MCP server receives malformed JSON-RPC request"
+    expected: "Returns JSON-RPC error response with code -32700 (Parse error). Server continues running."
+    not: "Server crashes or hangs"
+  - scenario: "MCP admin validates a server configuration"
+    expected: |
+      Checks: schema validity, transport reachability (with 5s timeout), capability negotiation.
+      Returns structured report per server.
+    not: "Hangs indefinitely on unreachable server or skips schema validation"
+  - scenario: "Enterprise needs CRA compliance audit of MCP server configurations"
+    expected: |
+      $ bin/raictl mcp audit --format json
+      Returns: per-server audit report with configuration provenance (who, when, what),
+      validation status, transport security assessment, tool permission summary.
+      Suitable for inclusion in CRA technical documentation.
+    not: "No audit trail, no provenance tracking, manual documentation required"
+  - scenario: "User manages MCP servers for multiple AI agents (Claude Code, Goose, Cursor)"
+    expected: |
+      $ bin/raictl mcp list
+      NAME          TRANSPORT  AGENT        STATUS
+      puppet-mcp    stdio      claude,goose  healthy
+      terraform-mcp http       claude        healthy
+      db-query      stdio      goose         unreachable
+      Each server's configuration is validated, health-checked, and reported per-agent.
+    not: "Each AI agent's MCP config must be managed independently with no cross-visibility"
+#
+anti_patterns:
+  - "Implementing custom JSON-RPC handling instead of using the mcp gem"
+  - "Exposing file system paths outside whitelisted directories as MCP resources"
+  - "Making MCP tools that perform side effects without accurate annotations"
+  - "Running MCP server over HTTP without explicit user opt-in"
+  - "Storing MCP server credentials in plaintext configuration files"
+  - "Spawning MCP admin health checks without timeouts"
+  - "Coupling MCP tool implementation to Claude Code specific features"
+  - "Using MCP sampling (server-initiated LLM calls) without explicit user consent"
+  - "Mixing MCP server logic with core rosett-ai library code (keep separate module)"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. mcp_settings.yml: mcp_integration governs protocol participation and
+     server/admin implementation. mcp_settings governs trust-first configuration
+     management and server installation policies.
+
+  2. aaif_alignment.yml: AAIF governs ecosystem strategic positioning.
+     MCP integration handles the technical protocol implementation.
+
+  3. engine_architecture.yml: MCP server exposes engine capabilities. Engine
+     manifests declare which MCP tools each engine can provide.
+
+  4. security.yml: all MCP tool handlers follow security constraints —
+     YAML.safe_load, array-form system(), no secret exposure.
+
+  5. comply.yml: MCP admin audit output supports CRA/NIS2 compliance
+     documentation requirements.
+
+  6. error_handling.yml: MCP command errors follow the structured error
+     hierarchy with exit codes and localised messages.
+
+  7. compiler.yml: MCP server can trigger compilation via tool call,
+     respecting simulate/verbose flags.
+
+  MCP module structure:
+
+  lib/rosett_ai/mcp/
+    server.rb            — MCP server entry point (stdio transport)
+    tools/               — Tool implementations (validate, compile, etc.)
+    resources/           — Resource providers (behaviours, design docs)
+    prompts/             — Prompt templates (validation, compilation)
+    admin/
+      registry.rb        — Configured server registry
+      health_checker.rb  — Health check with 5s timeout
+      auditor.rb         — CRA compliance audit reporter
+      schema_validator.rb — Server config validation
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Service object pattern for MCP tool implementations"
+    - "Command pattern for MCP admin operations"
+    - "Adapter pattern for transport abstraction (stdio, HTTP)"
+    - "Registry pattern for configured server management"
+  testing: rspec with MCP protocol handshake tests, tool execution
+    scenarios, malformed input handling, health check timeout verification,
+    and audit output format validation
+  gems:
+    - mcp
+    - json_schemer
+    - thor

data/conf/design/mcp_settings.yml

@@ -0,0 +1,126 @@
+---
+name: mcp_settings
+domain: core
+version: 0.1.0
+status: implemented
+priority: 2
+author: hugo
+created_at: "2026-03-15"
+modified_at: "2026-03-16"
+modified_by: claude
+depends_on:
+  - mcp_integration
+  - security
+  - claude_code_configuration
+  - error_handling
+#
+intent: |
+  Manage MCP (Model Context Protocol) server configuration with a trust-first
+  model that prevents untrusted servers from being silently added to a
+  developer's configuration. Restrict MCP server installation to explicitly
+  trusted sources (rosett-ai Enterprise Manager Server, configured trusted domains,
+  the Goose project) and provide centralised management for teams using rosett-ai
+  Enterprise Manager.
+
+  This design governs MCP server trust, installation, and configuration
+  lifecycle. The MCP protocol implementation (server, tools, resources, admin)
+  is governed by mcp_integration.yml. Engine-specific MCP compilation is
+  governed by engine_architecture.yml. Error handling for MCP settings
+  commands follows error_handling.yml.
+#
+constraints:
+  - "MCP servers must come from a trusted source before installation"
+  - "Trust sources are: rosett-ai Enterprise Manager Server, user-configured
+    trusted domains, Goose project registry"
+  - "MCP server configs are stored in XDG-compliant paths (~/.config/rosett-ai/mcp/)"
+  - "Enterprise Manager can push MCP configurations to managed installations"
+  - "All MCP server URIs must use HTTPS — no plaintext HTTP"
+  - "MCP server removal must be explicit — never garbage-collected"
+  - "Configuration must be engine-agnostic — compiled to engine-native format
+    by the compiler"
+  - "YAML.safe_load only for all MCP configuration parsing"
+  - "Array-form system() for any subprocess spawning during server validation"
+  - "This design governs MCP server trust and configuration lifecycle.
+    Protocol implementation is governed by mcp_integration.yml.
+    Engine-specific compilation is governed by engine_architecture.yml"
+#
+acceptance_criteria:
+  - "`rai mcp list` shows all configured MCP servers with trust source"
+  - "`rai mcp add URI` installs a server from a trusted source"
+  - "`rai mcp add URI` from an untrusted source is rejected with explanation"
+  - "`rai mcp remove NAME` removes a configured server"
+  - "`rai mcp trust-sources` lists configured trust sources"
+  - "Enterprise Manager can remotely provision MCP server configs"
+  - "Compile step translates generic MCP config to engine-specific format"
+  - "Exit code 0 on success, 1 on trust rejection, 2 on validation failure"
+  - "TTY-aware output: formatted table when interactive, JSON when piped"
+#
+examples:
+  - scenario: "Developer adds an MCP server from a trusted company domain"
+    expected: "Server is installed, validated, and appears in `rai mcp list`"
+    not: "Server installed without trust validation"
+  - scenario: "Enterprise Manager pushes a new MCP server to all team members"
+    expected: "Server appears in managed section, cannot be removed by user"
+    not: "User can override or delete enterprise-managed servers"
+  - scenario: "Developer tries to add an MCP server from unknown domain"
+    expected: |
+      Clear rejection message explaining trusted sources and how to add trust.
+      Exit code 1 (trust rejection). Suggests `rai mcp trust-sources add DOMAIN`.
+    not: "Silent failure or generic error message"
+  - scenario: "User lists MCP servers in a CI pipeline"
+    expected: |
+      $ bin/raictl mcp list --format json | ruby -rjson -e 'puts JSON.parse(STDIN.read).length'
+      3
+      Machine-readable JSON output when piped.
+    not: "Human-readable table with ANSI codes breaks CI parsing"
+#
+anti_patterns:
+  - "Allowing arbitrary MCP server installation without trust verification"
+  - "Storing MCP credentials in plaintext configuration files"
+  - "Engine-specific MCP config in the generic layer"
+  - "Auto-discovering MCP servers from network scanning"
+  - "Bypassing trust validation for localhost servers without explicit opt-in"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. mcp_integration.yml: mcp_settings governs trust and configuration
+     lifecycle. mcp_integration governs protocol implementation (server,
+     tools, resources, admin).
+
+  2. security.yml: trust-first model enforces supply-chain security.
+     All URI validation and credential handling follow security constraints.
+
+  3. claude_code_configuration.yml: MCP server entries are compiled into
+     Claude Code's settings.json mcpServers section.
+
+  4. engine_architecture.yml: engine manifests declare MCP compilation
+     format. The generic MCP config is compiled per-engine.
+
+  5. error_handling.yml: trust rejection and validation failure messages
+     follow the structured error hierarchy with exit codes.
+
+  6. comply.yml: MCP server audit trail supports CRA compliance reporting.
+
+  MCP trust chain:
+
+  1. User configures trust sources in ~/.config/rosett-ai/mcp/trust.yml
+  2. `rai mcp add URI` validates URI against trust sources
+  3. If trusted: download, validate schema, store in ~/.config/rosett-ai/mcp/servers/
+  4. If untrusted: reject with explanation and suggestion to add trust
+  5. Enterprise Manager can push configs bypassing user trust (managed scope)
+  6. `rai compile` translates generic MCP config to engine-native format
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Trust chain validation before installation"
+    - "XDG Base Directory Specification for config paths"
+    - "Declarative YAML for MCP server definitions"
+    - "Scope separation (managed vs user-configured)"
+  testing: rspec with trust source validation scenarios, untrusted
+    rejection tests, Enterprise Manager push simulation, engine-specific
+    compilation output verification, and TTY-aware output format tests
+  gems:
+    - json_schemer
+    - thor