rosett-ai 1.3.3

data/conf/design/rai_mcp_server.yml

@@ -0,0 +1,605 @@
+---
+name: rai_mcp_server
+domain: core
+version: 0.1.0
+status: draft
+priority: 2
+author: hugo
+created_at: "2026-04-17"
+modified_at: "2026-04-17"
+modified_by: claude
+depends_on:
+  - mcp_integration
+  - mcp_settings
+  - rai_mcp_asset_discovery
+  - compiler
+  - architecture
+  - scope_hierarchy
+  - security
+  - error_handling
+#
+intent: |
+  DES-RAI-MCP-002: Concrete implementation specification for the rai-mcp server
+  invoked via `raictl mcp serve`. This refines three prior design documents
+  (mcp_integration, mcp_settings, rai_mcp_asset_discovery) into a single
+  actionable spec with tool catalog, resource catalog, enforcement pipeline,
+  and phased implementation plan.
+
+  rai-mcp is the first step of the Bootstrap Loop: it enables enforcement that
+  improves every subsequent AI-assisted session. The server:
+
+  1. Serves rosett-ai assets (behaviours, rules, schemas) to any MCP-compliant
+     AI client via the instructions field for auto-discovery.
+  2. Provides decision-support tools ("what rules apply here?", "is this
+     file compliant?") that make AI clients rule-aware.
+  3. Generates and installs PreToolUse enforcement hooks from behaviour rules,
+     transforming declarative YAML into runtime enforcement.
+  4. Implements mutation safety: confirmation-by-default, auto-backup before
+     writes, configurable enforcement levels.
+
+  The server infrastructure (transport, middleware, governance, plugins) already
+  exists. This design focuses on closing gaps: the instructions field, the
+  enforcement pipeline, decision-support tools, asset discovery tools, and
+  fixing 6 partial tools + 1 stub.
+
+  Key principle: documentation-tool parity. Every tool documented here must
+  exist and behave as described. Every tool that exists must be documented.
+  The design doc is the acceptance test.
+
+  Session: W6-01-RAIMCP-DESIGN | WP#1557
+#
+constraints:
+  - "Must use the official MCP Ruby SDK (mcp gem >= 0.9.2) — no custom protocol implementation"
+  - "MCP spec version: 2025-03-26"
+  - "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 requires explicit opt-in"
+  - "No MCP tool may perform destructive operations without user confirmation (default)"
+  - "MCP tool annotations must accurately reflect behaviour (readOnlyHint, destructiveHint)"
+  - "Server-side secrets 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 all YAML processing within MCP tools"
+  - "Instructions field is MANDATORY — AI clients must auto-discover tools at launch"
+  - "Documentation-tool parity: every documented tool must work, every working tool must be documented"
+  - "Both manual and AI-assisted authoring paths must pass through EnforcementValidator — no bypass"
+  - "All new MCP code must have YARD documentation"
+  - "Enforcement pipeline (hook preview/install) is separate from compilation (raictl compile)"
+  - "Resolution strategy configurable: global, hybrid (default), per_request"
+  - "Mutation tools require auto-backup before execution (configurable, default on)"
+#
+acceptance_criteria:
+  # Instructions field
+  - "MCP server passes instructions field to MCP::Server.new on startup"
+  - "Instructions markdown contains tool inventory grouped by category"
+  - "Instructions markdown contains resource URI patterns with examples"
+  - "Instructions markdown contains scope hierarchy explanation"
+  - "Instructions markdown contains common workflow guides"
+  - "Instructions markdown contains mutation safety rules"
+  - "AI client auto-discovers all rosett-ai tools on session start via instructions"
+  # Tool catalog — shipping tools
+  - "All 19 SHIPPING tools registered and functional via MCP protocol"
+  - "All 19 SHIPPING tools documented in instructions with accurate annotations"
+  - "raictl mcp tools output matches design doc tool catalog exactly"
+  # Tool catalog — fixed tools
+  - "rai_compile delegates to real compiler (stub eliminated)"
+  - "rai_validate performs JSON Schema validation, not just YAML syntax check"
+  - "rai_project reads from gemspec/config, not hardcoded values"
+  - "rai_hooks_status filter handles all overcommit hook phases"
+  - "rosett_ai_engines surfaces errors instead of swallowing them"
+  - "rai_config_status surfaces errors instead of swallowing them"
+  # Tool catalog — new tools
+  - "rai_rule_search accepts keyword and returns matching rules with behaviour, rule_id, priority, snippet"
+  - "rai_rule_search supports optional filters: priority_min, scope, enabled_only"
+  - "rai_schema_get returns JSON Schema content for behaviour/design/tooling schemas"
+  - "rai_compile_status returns per-file staleness with source vs compiled checksums"
+  - "rai_hook_preview returns generated hook script for inspection without side effects"
+  - "rai_hook_install generates hook + writes to disk + registers in settings.json (mutation, confirmation required)"
+  - "rai_context_query returns applicable rules for a given file path, tool name, or action"
+  # Resources
+  - "rosett-ai://behaviour/{name} resolves via 3-tier lookup with configurable merge strategy"
+  - "rosett-ai://behaviour/{name}?tier=xdg returns content from specific tier"
+  - "rosett-ai://design/{name} returns design document YAML content"
+  - "rosett-ai://provenance/ returns AI provenance entries"
+  - "rosett-ai://config/{scope} returns settings for all scopes including user (bug fixed)"
+  - "rosett-ai://schema/{name} returns JSON Schema content"
+  - "rosett-ai://rules/{name} returns compiled rule markdown content"
+  - "rosett-ai://hooks/{scope} returns installed hook script content"
+  # Enforcement pipeline
+  - "Behaviour schema v1.3.0 adds optional enforcement block (type, pattern, applies_to, action)"
+  - "EnforcementValidator checks: pattern present, pattern compiles, pattern not degenerate, applies_to present, action valid"
+  - "EnforcementValidator downgrades invalid enforceable rules to advisory with warning"
+  - "EnforcementValidator runs on both manual and AI-assisted authoring paths"
+  - "rai_hook_install auto-backups affected scope before writing"
+  - "Generated hook scripts include YARD documentation, human-readable header, AI client instructions"
+  - "Hook scripts are traceable: source behaviour, rule ID, version, generator version, initiator identity"
+  # Mutation safety
+  - "Mutation confirmation default is required (configurable: required, optional, disabled)"
+  - "Auto-backup before mutation default is on (configurable)"
+  - "Instructions field directs AI clients to request user confirmation for mutation tools"
+  # Resolution
+  - "Resolution mode configurable: global, hybrid (default), per_request"
+  - "Hybrid mode: server config for mutations, per-request override on read-only tools"
+  - "Default merge strategy: first_wins (configurable: first_wins, deep_merge, array_union)"
+  # Integration
+  - "raictl init --global auto-registers MCP server in ~/.claude/settings.json"
+  - "raictl init --global documents MCP registration in output"
+  - "raictl init --local and --project do NOT modify global settings.json"
+  # Packaging
+  - "raictl mcp serve starts from .deb installation (kitchen VM verified)"
+  - "BUNDLE_WITHOUT does not exclude mcp group in .deb wrapper"
+  - "Build process reproducible: documented minimal dependencies, kitchen test builds .deb from source in clean VM"
+  - "Developer documentation enables independent reproducible builds"
+  # Quality
+  - "Integration tests verify MCP protocol handshake and tool execution"
+  - "All new code has YARD documentation"
+  - "MCP server gracefully handles malformed JSON-RPC messages"
+#
+examples:
+  - scenario: "AI client starts a session and discovers rosett-ai tools"
+    expected: |
+      Claude Code reads the MCP server's instructions field on session start.
+      The instructions list all available tools by category:
+
+      DISCOVERY: rai_behaviour_list, rai_behaviour_show, rai_rule_search,
+                 rai_schema_get, rai_compile_status, rai_design_list, rai_design_show
+      ENFORCEMENT: rai_hook_preview, rai_hook_install, rai_context_query
+      MANAGEMENT: rai_behaviour_manage, rai_compile, rai_config_compile, rai_validate
+      COMPLIANCE: rai_comply, rai_provenance, rai_provenance_init
+      OPERATIONS: rai_doctor, rai_backup, rai_init, rai_project, rosett_ai_engines
+
+      The AI client knows which tool to use for each task without manual lookup.
+    not: "AI client must guess tool names or read documentation files manually"
+  - scenario: "AI client queries applicable rules before editing a file"
+    expected: |
+      Tool call: { name: "rai_context_query", arguments: { tool_name: "Bash" } }
+      Response:
+      {
+        "applicable_rules": [
+          {
+            "rule_id": "rule_022",
+            "behaviour": "operational_discipline",
+            "priority": 90,
+            "enforcement": "enforceable",
+            "action": "block",
+            "description": "Never bypass git hooks with --no-verify"
+          },
+          ...
+        ],
+        "total": 5,
+        "scope": "global"
+      }
+    not: "AI client has no way to know which rules apply before acting"
+  - scenario: "User wants to install enforcement hooks"
+    expected: |
+      1. AI calls rai_hook_preview to show what would be generated
+      2. User reviews the preview output
+      3. AI calls rai_hook_install with confirmed: true
+      4. rai_hook_install auto-backups ~/.claude/hooks/ before writing
+      5. Hook script written to ~/.claude/hooks/rai-enforce-global.rb
+      6. settings.json updated with PreToolUse hook entry
+      7. Response includes: hook path, backup path, rules count, behaviours included
+    not: "Hook installed without preview, without confirmation, or without backup"
+  - scenario: "User manually writes a rule marked enforceable with an invalid pattern"
+    expected: |
+      User saves behaviour YAML with enforcement.type: enforceable but
+      enforcement.pattern: ".*" (degenerate).
+
+      EnforcementValidator detects degenerate pattern, downgrades to advisory:
+      "Rule rule_005 declares enforceable but pattern is degenerate (matches
+       everything). Downgraded to advisory. Fix the pattern to enable hook
+       generation."
+
+      The rule is saved as advisory. No hook is generated for this rule.
+      Warning appears in rai_validate, rai_compile, and rai_hook_preview output.
+    not: "Degenerate pattern silently generates a hook that blocks all tool calls"
+  - scenario: "AI-assisted rule creation"
+    expected: |
+      User describes intent: "Block any attempt to write to /etc/passwd"
+      AI client calls rai_behaviour_manage with:
+      {
+        "action": "modify",
+        "name": "security_custom",
+        "rule": {
+          "id": "rule_010",
+          "description": "Block writes to system password file",
+          "priority": 95,
+          "enforcement": {
+            "type": "enforceable",
+            "pattern": "/etc/passwd",
+            "applies_to": ["Edit", "Write", "Bash"],
+            "action": "block"
+          }
+        }
+      }
+
+      EnforcementValidator runs on the AI-generated enforcement block
+      (same validator as manual path). Pattern is valid, non-degenerate,
+      applies_to and action present. Rule saved as enforceable.
+    not: "AI-generated rules bypass validation or use a different code path"
+  - scenario: "Reading a behaviour resource with specific tier and strategy"
+    expected: |
+      Resource read: rosett-ai://behaviour/criticalthinking?tier=xdg
+      Returns the XDG user copy, ignoring project and packaged tiers.
+
+      Resource read: rosett-ai://behaviour/criticalthinking?strategy=deep_merge
+      Returns the deep-merged result across all tiers (only in hybrid/per_request mode).
+    not: "Tier parameter ignored, or strategy override works in global-only mode"
+  - scenario: "raictl init --global sets up MCP auto-discovery"
+    expected: |
+      $ raictl init --global
+      Setting up global rosett-ai structure...
+        Created ~/.config/rosett-ai/conf/behaviour/
+        Created ~/.config/rosett-ai/mcp/
+        Registered rosett-ai MCP server in ~/.claude/settings.json
+        -> AI clients will auto-discover rosett-ai tools on next session start
+    not: "User must manually edit settings.json to register the MCP server"
+  - scenario: "Mutation tool requires confirmation and backup"
+    expected: |
+      AI client calls rai_compile with simulate: false.
+      Instructions field has told the AI client: "Present the action to the
+      user and ask for confirmation before executing mutation tools."
+      AI asks user: "Compile will write 12 rule files to ~/.claude/rules/. Proceed?"
+      User confirms.
+      Auto-backup snapshots ~/.claude/rules/ before compilation.
+      Compilation proceeds. Response includes backup path for rollback.
+    not: "Mutation executes without user awareness, or backup is skipped"
+#
+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"
+  - "Coupling MCP tool implementation to Claude Code specific features"
+  - "Using MCP sampling (server-initiated LLM calls) without explicit user consent"
+  - "Generating enforcement hooks for rules that fail EnforcementValidator"
+  - "Allowing AI-assisted rule creation to bypass EnforcementValidator"
+  - "Documenting tools that do not exist or do not work as described"
+  - "Shipping PARTIAL or STUB tools as Supported without fixing them first"
+  - "Skipping auto-backup before mutation tool execution"
+  - "Per-request strategy override on mutation tools in hybrid mode"
+  - "Hardcoding paths in MCP tools instead of using PathResolver"
+  - "Caching tool responses across MCP sessions — always read fresh from disk"
+  - "Loading the full compilation pipeline just to list behaviours"
+#
+gui_notes: |
+  ## Tool Catalog
+
+  ### Category: Discovery (read-only)
+
+  | Tool | Description | Status | Annotations |
+  |------|-------------|--------|-------------|
+  | rai_behaviour_list | List behaviours with metadata, scope, source tier | SHIPPING | readOnly=true |
+  | rai_behaviour_show | Return full content of a named behaviour | SHIPPING | readOnly=true |
+  | rai_behaviour_display | Display behaviour configuration table | SHIPPING | readOnly=true |
+  | rai_design_list | List design documents with metadata | SHIPPING | readOnly=true |
+  | rai_design_show | Return full content of a design document | SHIPPING | readOnly=true |
+  | rai_rule_search | Keyword search across rules with filters | PLANNED (W6-03) | readOnly=true |
+  | rai_schema_get | Return JSON Schema content | PLANNED (W6-03) | readOnly=true |
+  | rai_compile_status | Per-file staleness check | PLANNED (W6-03) | readOnly=true |
+
+  ### Category: Enforcement (new)
+
+  | Tool | Description | Status | Annotations |
+  |------|-------------|--------|-------------|
+  | rai_hook_preview | Show generated hook script for inspection | PLANNED (W6-03) | readOnly=true |
+  | rai_hook_install | Generate + write + register enforcement hook | PLANNED (W6-03) | readOnly=false, destructive=false |
+  | rai_context_query | Return applicable rules for a context | PLANNED (W6-03) | readOnly=true |
+
+  ### Category: Management (mutation)
+
+  | Tool | Description | Status | Annotations |
+  |------|-------------|--------|-------------|
+  | rai_behaviour_manage | Add/modify/delete behaviours | SHIPPING | readOnly=false |
+  | rai_compile | Compile rules to target format | FIX REQUIRED (W6-02) | readOnly=false |
+  | rai_config_compile | Compile YAML scopes to JSON settings | SHIPPING | readOnly=false |
+  | rai_validate | Validate config files with schema check | FIX REQUIRED (W6-02) | readOnly=true |
+  | rai_init | Set up global/local/project structure | SHIPPING | readOnly=false |
+  | rai_backup | Back up configuration scopes | SHIPPING | readOnly=false |
+
+  ### Category: Compliance
+
+  | Tool | Description | Status | Annotations |
+  |------|-------------|--------|-------------|
+  | rai_comply | Run compliance checks (CRA, license, SPDX) | SHIPPING | readOnly=true |
+  | rai_provenance | Show provenance entries (log, show) | SHIPPING | readOnly=true |
+  | rai_provenance_init | Create .ai-provenance.yml | SHIPPING | readOnly=false |
+
+  ### Category: Operations
+
+  | Tool | Description | Status | Annotations |
+  |------|-------------|--------|-------------|
+  | rai_doctor | Run diagnostic checks | SHIPPING | readOnly=true |
+  | rai_project | Show project status and info | FIX REQUIRED (W6-02) | readOnly=true |
+  | rosett_ai_engines | List/detect/status of engines | FIX REQUIRED (W6-02) | readOnly=true |
+  | rai_hooks_status | Show git hook installation status | FIX REQUIRED (W6-02) | readOnly=true |
+  | rai_config_status | Show config scope status | FIX REQUIRED (W6-02) | readOnly=true |
+  | rai_documentation_status | Show documentation file status | SHIPPING | readOnly=true |
+  | rai_license_status | Show license status | SHIPPING | readOnly=true |
+  | rai_adopt | Analyze rules for adoption | SHIPPING | readOnly=true |
+  | rai_content | List/install/update content packs | SHIPPING | readOnly=false (install/update) |
+  | rai_retrofit | Scan/convert native configs | SHIPPING | readOnly=true (scan), readOnly=false (convert) |
+  | rai_tooling | Validate CI YAML, check versions | SHIPPING | readOnly=true |
+  | rai_workflow | List/validate/simulate workflows | SHIPPING | readOnly=true |
+  | rai_workflow_execute | Execute a named workflow | SHIPPING | readOnly=false |
+
+  ## Resource Catalog
+
+  | URI Pattern | Content Type | Description | Status |
+  |-------------|-------------|-------------|--------|
+  | rosett-ai://behaviour/{name} | application/x-yaml | Behaviour YAML via 3-tier lookup | SHIPPING |
+  | rosett-ai://design/{name} | application/x-yaml | Design document YAML | SHIPPING |
+  | rosett-ai://provenance/ | application/x-yaml | AI provenance entries | SHIPPING |
+  | rosett-ai://config/{scope} | application/json | Settings for a scope | FIX (W6-02) |
+  | rosett-ai://schema/{name} | application/json | JSON Schema content | PLANNED (W6-03) |
+  | rosett-ai://rules/{name} | text/markdown | Compiled rule content | PLANNED (W6-03) |
+  | rosett-ai://hooks/{scope} | text/x-ruby | Installed hook script | PLANNED (W6-03) |
+
+  Resource query parameters:
+  - ?tier=project|xdg|packaged — request specific tier (bypasses merge)
+  - ?strategy=first_wins|deep_merge|array_union — override merge strategy
+    (honoured only in hybrid/per_request resolution modes, read-only only)
+
+  ## Enforcement Pipeline
+
+  ### Behaviour Schema v1.3.0 — enforcement block (optional, backward-compatible)
+
+  ```yaml
+  rules:
+    - id: rule_022
+      description: "Never bypass git hooks"
+      priority: 90
+      enabled: true
+      enforcement:                    # NEW — optional
+        type: enforceable             # enforceable | advisory | informational
+        pattern: "--no-verify|OVERCOMMIT_DISABLE"
+        applies_to: ["Bash"]
+        action: block                 # block | warn | inform
+  ```
+
+  If enforcement block is absent, the rule defaults to informational.
+
+  ### EnforcementValidator
+
+  Runs on ALL authoring paths (manual YAML editing and AI-assisted creation).
+  Checks when enforcement.type == enforceable:
+  1. pattern is present and non-empty
+  2. pattern compiles as valid Ruby Regexp
+  3. pattern is not degenerate (rejects .*, .+, \s*, etc.)
+  4. applies_to is present and non-empty
+  5. action is one of: block, warn, inform
+
+  On failure: downgrade to advisory with warning. Never silently generate
+  a broken hook. Warning surfaces in rai_validate, rai_compile,
+  rai_hook_preview output.
+
+  ### Hook Generation Flow
+
+  1. rai_hook_preview (read-only):
+     - Reads behaviours via Composer with configured merge strategy
+     - Filters to enforceable rules that pass EnforcementValidator
+     - Generates Ruby hook script with YARD docs and human header
+     - Returns script content as text — no side effects
+
+  2. rai_hook_install (mutation, confirmation required):
+     - Runs rai_hook_preview internally
+     - Auto-backups target directory (configurable, default on)
+     - Writes hook script to scope-appropriate location:
+       - global: ~/.claude/hooks/rai-enforce-global.rb
+       - project: .claude/hooks/rai-enforce-project.rb
+       - personal: ~/.claude/hooks/rai-enforce-personal.rb
+     - Registers hook in settings.json PreToolUse section
+     - Returns: hook path, backup path, rules count, behaviours included
+
+  ### Hook Script Format
+
+  Generated Ruby script includes:
+  - PURPOSE: what the hook does
+  - INTENTION: user/auto-generated protection description
+  - TRIGGERED BY: source behaviours with version and rule counts
+  - GENERATED: timestamp, generator version, merge strategy, initiator (name + email)
+  - AI CLIENT INSTRUCTIONS: how AI should respond to blocks
+  - YARD @author, @since, @see tags
+  - Full YARD documentation on every constant, variable, and code block
+  - DO NOT EDIT MANUALLY warning with regeneration command
+  - Rules sorted by priority with full traceability (behaviour, rule_id, version)
+  - Exit codes: 0 = allow/warn, 1 = block
+
+  ### Hook Scope Merge (runtime)
+
+  When multiple scope hooks exist, they merge:
+  - project overrides global on same rule ID
+  - personal overrides both on same rule ID
+  - priority field is tiebreaker for different rule IDs
+
+  ## Mutation Safety Architecture
+
+  ### Confirmation
+
+  Default: required. Configurable in behaviour YAML:
+  ```yaml
+  mutation_confirmation: required    # required | optional | disabled
+  ```
+
+  When required: instructions field tells AI clients to present the action
+  and ask user before executing. Hard enforcement possible via PreToolUse
+  hook that blocks mutation tool calls without confirmed: true parameter.
+
+  ### Auto-Backup
+
+  Default: on. Configurable. Before any mutation tool executes,
+  RosettAi::Backup::Manager snapshots the affected scope. Response includes
+  backup path for rollback.
+
+  ## Resolution Strategy
+
+  Configured in ~/.config/rosett-ai/mcp/server.yml:
+  ```yaml
+  resolution:
+    strategy: first_wins          # first_wins | deep_merge | array_union
+    mode: hybrid                  # global | hybrid | per_request
+  ```
+
+  | Mode | Behaviour |
+  |------|-----------|
+  | global | Server config strategy everywhere, per-request ?strategy= ignored |
+  | hybrid (DEFAULT) | Server config for mutations, per-request override on read-only |
+  | per_request | Every call can specify strategy, server config is default |
+
+  Strategies mirror Hiera resolution:
+  - first_wins: highest-priority scope wins (Hiera first)
+  - deep_merge: recursive hash merge across scopes (Hiera deep)
+  - array_union: combine arrays, deduplicate (Hiera unique)
+
+  Implemented by existing Composition::MergeStrategy module.
+
+  ## File Layout
+
+  ```
+  lib/rosett_ai/mcp/
+  ├── server.rb                    # MCP server (EXISTING — add instructions:)
+  ├── governance.rb                # Tool/resource registration (EXISTING)
+  ├── plugins.rb                   # Plugin discovery (EXISTING)
+  ├── instructions.md              # Server instructions for auto-discovery (NEW)
+  ├── tools/
+  │   ├── [19 existing shipping tools]
+  │   ├── [6 existing tools to fix]
+  │   ├── rule_search_tool.rb      # NEW — keyword search across rules
+  │   ├── schema_get_tool.rb       # NEW — return JSON Schema content
+  │   ├── compile_status_tool.rb   # NEW — per-file staleness
+  │   ├── hook_preview_tool.rb     # NEW — preview generated hook
+  │   ├── hook_install_tool.rb     # NEW — generate + install hook
+  │   └── context_query_tool.rb    # NEW — applicable rules for context
+  ├── resources/
+  │   ├── behaviour_resource.rb    # EXISTING — update to use PathResolver
+  │   ├── config_resource.rb       # EXISTING — fix user scope bug
+  │   ├── design_resource.rb       # EXISTING
+  │   ├── provenance_resource.rb   # EXISTING
+  │   ├── schema_resource.rb       # NEW
+  │   ├── rules_resource.rb        # NEW
+  │   └── hooks_resource.rb        # NEW
+  ├── enforcement/
+  │   ├── enforcement_validator.rb # NEW — validate enforcement blocks
+  │   ├── hook_generator.rb        # NEW — YAML rules -> Ruby hook script
+  │   ├── hook_installer.rb        # NEW — write + register hooks
+  │   └── pattern_denylist.rb      # NEW — degenerate pattern detection
+  ├── middleware/                   # EXISTING — HTTP security stack
+  │   ├── authentication.rb
+  │   ├── content_type.rb
+  │   ├── cors.rb
+  │   ├── origin_validation.rb
+  │   ├── rate_limit.rb
+  │   └── request_size.rb
+  ├── admin/                       # EXISTING
+  │   ├── registry.rb
+  │   ├── health_checker.rb
+  │   ├── schema_validator.rb
+  │   └── auditor.rb
+  ├── keyfile.rb                   # EXISTING
+  ├── key_hasher.rb                # EXISTING
+  └── http_security_config.rb      # EXISTING
+  ```
+
+  ## Integration Points
+
+  | Component | Integration |
+  |-----------|-------------|
+  | PathResolver | All tools/resources use PathResolver for 3-tier file discovery |
+  | Composition::Composer | Resource handler uses Composer for merge strategy |
+  | Composition::MergeStrategy | Configurable: first_wins, deep_merge, array_union |
+  | Composition::ScopeResolver | Scope classification for rules |
+  | Behaviour::Manager | behaviour_manage tool delegates to Manager |
+  | Compiler::CompilationPipeline | rai_compile tool delegates to pipeline (after fix) |
+  | Backup::Manager | Auto-backup before mutation tools |
+  | Validators::BehaviourValidator | Schema validation in rai_validate (after fix) |
+  | Validators::EnforcementValidator | NEW — validates enforcement blocks |
+  | Init::GlobalInitializer | Auto-registers MCP server in settings.json |
+
+  ## Test Strategy
+
+  Unit tests:
+  - EnforcementValidator: valid patterns, degenerate patterns, missing fields, downgrade
+  - HookGenerator: template rendering, rule sorting, YARD output, header fields
+  - HookInstaller: backup creation, file write, settings.json registration
+  - PatternDenylist: degenerate pattern detection
+  - Each new tool: input validation, delegation, error handling, response structure
+
+  Integration tests:
+  - MCP protocol handshake (stdio transport)
+  - Tool execution via JSON-RPC (all 25+ tools)
+  - Resource retrieval via JSON-RPC (all 7 URI patterns)
+  - Instructions field present in server capabilities
+  - Enforcement round-trip: create rule -> preview hook -> install hook -> trigger block
+  - Resolution mode: verify hybrid blocks strategy override on mutations
+  - Mutation safety: verify backup created before write
+
+  Kitchen (packaging):
+  - Build .deb from source in clean VM with documented minimal dependencies
+  - Install .deb, verify raictl mcp serve starts
+  - Verify raictl mcp tools lists all expected tools
+  - Verify tool execution from installed package
+  - Atomic build: build succeeds or fails completely
+
+  ## Implementation Phases
+
+  ### W6-02: Fix + Instructions (prerequisites)
+  - Fix rai_compile stub (delegate to CompilationPipeline)
+  - Fix rai_validate (add JSON Schema validation)
+  - Fix rai_project (read from gemspec/config)
+  - Fix rai_hooks_status (fix phase filter)
+  - Fix rosett_ai_engines (surface errors)
+  - Fix rai_config_status (surface errors)
+  - Fix config_resource.rb user scope bug
+  - Implement instructions field in server.rb build_server
+  - Write lib/rosett_ai/mcp/instructions.md
+  - Update raictl init --global to auto-register MCP server
+  - All fixed tools pass integration tests
+
+  ### W6-03: Asset Discovery + Enforcement Pipeline
+  - Build rai_rule_search tool
+  - Build rai_schema_get tool
+  - Build rai_compile_status tool
+  - Build EnforcementValidator
+  - Build HookGenerator
+  - Build rai_hook_preview tool
+  - Build rai_hook_install tool (with backup integration)
+  - Build rai_context_query tool
+  - Update behaviour_resource.rb to use PathResolver + Composer
+  - Build schema_resource.rb, rules_resource.rb, hooks_resource.rb
+  - Update behaviour schema to v1.3.0 (add enforcement block)
+  - PatternDenylist for degenerate pattern detection
+
+  ### W6-04: Resolution + Mutation Safety
+  - Implement resolution mode config (global/hybrid/per_request)
+  - Wire resolution mode into resource handlers and mutation tools
+  - Implement mutation confirmation flow (instructions + optional hard enforcement)
+  - Implement auto-backup before mutation
+  - Integration tests for resolution modes
+  - Integration tests for mutation safety
+
+  ### W6-05: Packaging + Documentation
+  - Verify BUNDLE_WITHOUT does not exclude mcp group
+  - Kitchen test: build .deb from source in clean VM
+  - Kitchen test: raictl mcp serve from installed package
+  - Developer build documentation (minimal dependencies, reproducible build)
+  - YARD documentation audit on all new MCP code
+  - End-to-end enforcement round-trip test (kitchen)
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Service object per tool (RosettAi::Mcp::Tools::RuleSearchTool, etc.)"
+    - "PathResolver for all path discovery — never hardcode paths in tools"
+    - "Struct or Data for response objects — not raw hashes"
+    - "Composition::Composer for all multi-tier resolution"
+    - "EnforcementValidator as single validation gate for both authoring paths"
+    - "YARD documentation on all new public methods and classes"
+  testing: rspec with MCP protocol integration tests, tool response schema
+    validation, enforcement round-trip tests, resolution mode verification,
+    mutation safety tests, kitchen packaging tests
+  gems:
+    - mcp
+    - json_schemer
+    - thor
+    - zeitwerk