rosett-ai 1.3.3

data/conf/design/policy_management.yml

@@ -0,0 +1,229 @@
+---
+name: policy_management
+domain: security
+version: 0.1.0
+status: implemented
+priority: 2
+author: hugo
+created_at: "2026-03-10"
+modified_at: "2026-03-16"
+modified_by: claude
+depends_on:
+  - security
+  - ai_provenance
+  - ai_authorship
+  - engine_architecture
+  - compiler
+  - error_handling
+#
+intent: |
+  Provide a structured framework for organisations to define, enforce, and
+  audit AI usage policies across their development teams. While rosett-ai's
+  behaviour rules govern how AI tools behave, policies govern what AI tools
+  are allowed to do — the organisational, legal, and compliance layer.
+
+  This bridges the gap between rosett-ai's technical configuration and the
+  real-world requirements of regulated industries (finance, healthcare,
+  government, defence) and compliance frameworks (EU AI Act, SOC 2,
+  ISO 27001, NIST AI RMF).
+
+  Policy is the governance layer in the provenance–authorship–policy triad:
+  ai_provenance.yml records what each AI tool did (audit trail),
+  ai_authorship.yml governs how that involvement is attributed (disclosure),
+  and this design governs the requirements — which projects require
+  provenance, at what level, what disclosure is mandated, and what
+  file access restrictions apply.
+
+  Inspired by openvox-mcp's nine policy areas (A-I), adapted for Rosett-AI's
+  compilation model. Policies are authored as YAML, validated against a
+  schema, and compiled into engine-specific enforcement rules.
+
+  Key capabilities:
+    - Policy tiers (mandatory, advisory, informational) with per-project override
+    - Deny lists for sensitive file patterns (keys, credentials, secrets)
+    - Protected files list (files AI may read but not modify)
+    - License allowlist/rejectlist for dependency auditing
+    - Rate limiting configuration for AI-assisted contributions
+    - Opt-out markers for files and directories
+    - Policy versioning with no retroactive enforcement
+    - Tiered enforcement: strict for org-critical, advisory for team projects
+#
+constraints:
+  - "Policies must never weaken security constraints from security.yml"
+  - "Policy files use YAML.safe_load only, validated against a policy schema"
+  - "Policy file content must be validated for ANSI escape sequences and
+    control characters — deny-list patterns and protected file paths are
+    stripped of control characters before compilation"
+  - "Deny-list patterns must be validated for path traversal — patterns
+    containing '..' or symlink resolution outside the project root are
+    rejected"
+  - "Deny-list patterns must be tested (no untested glob patterns) — a
+    dry-run mode shows which files each pattern would match"
+  - "Policy tiers can be tightened by child projects but never loosened"
+  - "Protected files are read-only for AI — human override requires explicit
+    waiver"
+  - "Rate limiting is advisory by default, enforceable only with explicit
+    configuration"
+  - "Policy changes must be auditable (git history is the audit trail)"
+  - "No policy enforcement requires network access (offline-first)"
+  - "Policy compilation must produce engine-specific output (e.g. Claude
+    denied paths, Cursor ignore patterns). Engines declare policy-compatible
+    features in their capability manifests"
+  - "Opt-out markers must be respected across all engines"
+  - "Policy files are subject to the same size limits as other YAML files
+    (1 MB per file, 10 nesting levels, 1000 keys per security.yml)"
+  - "This design governs compile-time policy governance — policies are
+    evaluated and compiled into engine-specific rules before AI tools run.
+    raictl does not enforce policies at runtime. Runtime behaviour of AI
+    tools is governed by the compiled output, not by Rosett-AI itself"
+#
+acceptance_criteria:
+  - "bin/raictl policy init creates .rosett-ai/conf/policies/ with default policy
+    template"
+  - "bin/raictl policy validate checks all policy files against the policy
+    schema"
+  - "bin/raictl policy show displays active policies with tier and enforcement
+    level using TTY-aware output (table when interactive, plain text when
+    piped)"
+  - "Deny-list patterns from policy compile to Claude Code denied paths in
+    settings.json"
+  - "Deny-list patterns from policy compile to Cursor ignore patterns in
+    .cursorrules"
+  - "Protected files from policy compile to read-only annotations in
+    AGENTS.md"
+  - "License allowlist integrates with bundler-audit and dependency checking"
+  - "Policy tier hierarchy is enforced (org > team > project, can only
+    tighten)"
+  - "Opt-out markers (AI-MODIFICATION disabled) are honoured during
+    compilation"
+  - "bin/raictl policy audit generates a compliance report for the current
+    project using TTY-aware output"
+  - "Rate limiting configuration is parsed and included in compiled output
+    where engines support it"
+  - "bin/raictl policy audit --framework 'EU AI Act' maps policies to
+    specific compliance requirements"
+  - "Exit code 0 on success, 1 on policy violation, 2 on validation error,
+    3 on tier weakening attempt, 5 on missing policy schema"
+#
+examples:
+  - scenario: "Financial services company mandates no AI access to PCI-DSS scoped files"
+    expected: |
+      Organisation policy defines deny-list patterns for card data files,
+      PCI-scoped directories. bin/raictl compile generates Claude Code
+      settings.json with denied paths. Cursor gets ignore patterns.
+      AGENTS.md gets "DO NOT ACCESS" annotations.
+    not: "Deny list only works for one engine. Other engines silently ignore restrictions."
+  - scenario: "Open-source project opts out specific files from AI modification"
+    expected: |
+      Files marked with # AI-MODIFICATION: disabled are included in
+      protected files list during compilation. AI tools can read but
+      not modify these files. Policy validation confirms markers are
+      consistent with .rosett-ai/conf/policies/protected_files.yml.
+    not: "Opt-out markers are ignored by some engines."
+  - scenario: "Team project wants to allow AI but cap contributions"
+    expected: |
+      Policy sets rate_limit: 5 AI-assisted PRs per week per contributor.
+      Compiled output includes advisory note in AGENTS.md and CLAUDE.md.
+      CI integration (if configured) flags exceeding the limit.
+    not: "Rate limiting silently blocks contributions without explanation."
+  - scenario: "Child project tries to loosen parent organisation's deny list"
+    expected: |
+      bin/raictl policy validate rejects the override with error:
+      'Cannot remove deny-list pattern from parent policy — tighten only'.
+      Exit code 3.
+    not: "Child project successfully removes security-critical deny patterns."
+  - scenario: "Running a compliance audit report"
+    expected: |
+      `rai policy audit` generates:
+      ┌───────────────────┬──────────┬─────────────┬─────────┐
+      │ Policy            │ Tier     │ Enforcement │ Status  │
+      ├───────────────────┼──────────┼─────────────┼─────────┤
+      │ deny_pci_files    │ mandatory│ strict      │ active  │
+      │ rate_limit        │ advisory │ advisory    │ active  │
+      │ ai_disclosure     │ mandatory│ standard    │ active  │
+      └───────────────────┴──────────┴─────────────┴─────────┘
+      Piped output: tab-separated, no box drawing.
+    not: "No audit capability. Must manually review policy files."
+  - scenario: "Deny-list pattern contains path traversal attempt"
+    expected: |
+      `rai policy validate` rejects: 'Deny-list pattern "../../etc/passwd"
+      contains path traversal — patterns must be relative to project root'.
+    not: "Path traversal pattern is accepted and compiled into engine config."
+#
+anti_patterns:
+  - "Policies that require API calls to validate (must work offline)"
+  - "Using behaviour YAML for policy concerns (separate policy from behaviour)"
+  - "Retroactive policy enforcement (evaluate against policy at submission time)"
+  - "Binary enforcement (allow/block) without advisory middle ground"
+  - "Hardcoding policy patterns instead of making them configurable"
+  - "Policy that cannot be audited (must be in version control)"
+  - "Rate limiting that blocks instead of flags (advisory by default)"
+  - "Policy tier weakening (child can only tighten, never loosen)"
+  - "Deny-list patterns without dry-run testing (untested patterns may
+    match unintended files)"
+  - "Runtime policy enforcement by Rosett-AI (rai compiles, it does not enforce)"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. ai_provenance.yml: policy governs provenance requirements — which
+     projects must record provenance, at what granularity.
+
+  2. ai_authorship.yml: policy governs disclosure requirements — which
+     projects must disclose AI involvement, at what level.
+
+  3. security.yml: policies must never weaken security constraints.
+     Deny-list patterns are subject to path validation and content
+     stripping from security.yml.
+
+  4. engine_architecture.yml: engines declare policy-compatible features
+     (deny paths, ignore patterns, read-only annotations) in manifests.
+
+  5. compiler.yml: policy is a compilation target — YAML policies compile
+     to engine-specific enforcement rules.
+
+  6. error_handling.yml: exit codes and structured error messages follow
+     the error hierarchy (what/why/fix format).
+
+  7. behaviour_composition.yml: policies govern what AI may do; behaviours
+     govern how AI behaves. Both compile to engine-native formats but
+     serve different purposes.
+
+  Policy schema outline:
+    version: string (schema version)
+    policies:
+      - name: string
+        tier: mandatory | advisory | informational
+        enforcement: strict | standard | advisory
+        scope: org | team | project
+        deny_list:
+          - pattern: string (glob)
+            reason: string
+        protected_files:
+          - pattern: string (glob)
+            access: read_only
+            waiver: string (conditions for override)
+        license_allowlist: [string (SPDX identifiers)]
+        license_rejectlist: [string (SPDX identifiers)]
+        rate_limit:
+          max_ai_prs: integer
+          period: string (e.g. "7d")
+          enforcement: advisory | blocking
+        disclosure_level: none | minimal | standard | full
+        provenance_required: boolean
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Tiered enforcement (mandatory/advisory/informational)"
+    - "Deny-list with schema validation and dry-run testing"
+    - "Protected files compilation to engine-native formats"
+    - "Hierarchical policy inheritance (tighten-only)"
+    - "Offline-first validation"
+    - "TTY-aware output (TtyHelper)"
+  testing: rspec with policy hierarchy fixtures, deny-list glob tests,
+    path traversal rejection, cross-engine compilation, tier weakening
+    prevention, and compliance audit report scenarios
+  gems:
+    - json_schemer
+    - thor

data/conf/design/project_management.yml

@@ -0,0 +1,183 @@
+---
+name: project_management
+domain: core
+version: 0.2.0
+status: draft
+priority: 3
+author: hugo
+created_at: "2026-03-15"
+modified_at: "2026-03-23"
+modified_by: claude
+depends_on:
+  - architecture
+  - engine_architecture
+  - security
+  - compiler
+  - error_handling
+  - backward_compatibility
+  - scope_hierarchy
+#
+intent: |
+  Provide project lifecycle management beyond initial scaffolding — adding
+  behaviours, configuring engines, managing design documents, and
+  synchronising with upstream rosett-ai updates. Centralise project-specific
+  operations that currently require manual file manipulation or multiple
+  unrelated commands into the `rai project` command, covering template
+  application, configuration drift detection, and project health reporting.
+
+  Project management complements two adjacent commands in the Rosett-AI lifecycle:
+  `rai init` creates the initial .rosett-ai/ directory structure (scaffolding),
+  and `rai retrofit` imports existing native AI tool configs into Rosett-AI YAML.
+  Once a project is initialised and optionally retrofitted, `rai project`
+  manages its ongoing lifecycle — applying templates, detecting drift,
+  syncing with upstream, and reporting health. The lifecycle flow is:
+  init (scaffold) → retrofit (import) → project (manage) → compile (deploy).
+#
+constraints:
+  - "All project operations must work within the .rosett-ai/ directory scope.
+    Project scope (.rosett-ai/conf/) is distinct from local scope (parent
+    .rosett-ai/conf/) — see scope_hierarchy.yml for the full specification"
+  - "Template application must never overwrite user-modified files without
+    confirmation or --force flag"
+  - "Forward drift detection compares source YAML against compiled native
+    config (source → compiled). Template drift detection compares project
+    config against the template baseline that generated it (config → template)"
+  - "Must support both interactive and non-interactive (CI) modes"
+  - "Project configuration changes must be logged to a structured audit log
+    (JSON Lines format in .rosett-ai/logs/project.jsonl)"
+  - "Templates must be engine-agnostic — engine-specific content is added by
+    engines during compilation, not by templates during application"
+  - "All template YAML files must be parsed with YAML.safe_load only"
+  - "Template content must be validated for security — imported behaviour
+    rules are subject to the same content validation as authored behaviours
+    (ANSI stripping, control character removal, no secret references)"
+  - "`rai project sync` must verify upstream source integrity before applying
+    changes. Sync sources must be explicitly configured in .rosett-ai/config.yml
+    — no implicit network access or unsigned content"
+  - "`rai project sync` must warn when upstream changes include breaking
+    modifications (removed keys, changed semantics) and require --force or
+    explicit confirmation to apply"
+  - "This design governs project lifecycle management (templates, drift,
+    sync, status). Initial scaffolding is governed by architecture.yml
+    (rai init). Config import is governed by retrofit.yml. Source-to-native
+    compilation is governed by compiler.yml. Per-engine drift at the native
+    config level is handled by compile, not project_management"
+  - "`rai init --project` creates a project-level .rosett-ai/ marker and
+    conf/ subtree. `rai init --local` creates a local-level (workspace)
+    .rosett-ai/ marker. The scope type (local vs project) is determined by
+    the presence of child .rosett-ai/ markers — see scope_hierarchy.yml"
+#
+acceptance_criteria:
+  - "`rai project status` shows current project configuration and health
+    using TTY-aware output (table when interactive, plain text when piped)"
+  - "`rai project apply-template NAME` applies a project template with
+    conflict resolution (skip, overwrite, merge)"
+  - "`rai project drift` detects both forward drift (source → compiled)
+    and template drift (config → template baseline), reporting each type
+    separately"
+  - "`rai project drift --type forward` shows only source-to-compiled drift"
+  - "`rai project drift --type template` shows only config-to-template drift"
+  - "`rai project sync` updates project configs from upstream rosett-ai changes
+    with breaking-change detection"
+  - "`rai project info` shows project metadata (name, engine, behaviours,
+    template origin)"
+  - "Non-interactive mode uses safe defaults (skip conflicts, report only)"
+  - "Exit code 0 on success, 1 on operation failure, 2 on validation error,
+    3 on missing project config, 4 on drift detected, 5 on sync conflict"
+  - "`rai init --project` creates project-level .rosett-ai/ with config.yml
+    and conf/ subtree. `rai init --local` creates local-level .rosett-ai/ for
+    workspace grouping"
+  - "`rai project status` shows which scope is active (global, local,
+    project) and the resolved source and output directories"
+#
+examples:
+  - scenario: "Developer applies the 'ruby-gem' template to a new project"
+    expected: |
+      Template populates .rosett-ai/conf/behaviour/ with Ruby-specific behaviours.
+      Existing files are not overwritten. --verbose shows each file applied.
+    not: "Template overwrites existing custom behaviours without asking"
+  - scenario: "rosett-ai was upgraded and project configs are outdated"
+    expected: |
+      `rai project drift --type template` lists specific files that differ
+      from the new baseline: 'conf/behaviour/security.yml: 3 keys changed
+      (added: cve_scanning, removed: none, modified: audit_level)'.
+    not: "Silent acceptance of outdated configs"
+  - scenario: "Running `rai project status` in CI"
+    expected: |
+      Clean machine-readable output with exit code indicating health.
+      Non-interactive mode: no prompts, no colour, tab-separated values.
+    not: "Interactive prompts that block CI pipeline"
+  - scenario: "Sync finds breaking changes in upstream"
+    expected: |
+      `rai project sync` warns: 'Upstream v1.2.0 removes key
+      behaviour.max_priority (breaking change). Use --force to apply or
+      review changes with --simulate.' Exit code 5.
+    not: "Breaking changes applied silently. Existing config corrupted."
+  - scenario: "Forward drift detected — compiled config differs from source YAML"
+    expected: |
+      `rai project drift --type forward` shows: 'Forward drift detected:
+      .claude/settings.json differs from compiled output of conf/claude_code/.
+      Run `rai compile` to sync, or `rai retrofit --simulate` to review.'
+    not: "No way to detect that native config was hand-edited after compile."
+  - scenario: "Template contains a behaviour file with suspicious content"
+    expected: |
+      Template validation detects ANSI escape sequences or shell metacharacters
+      in a behaviour rule. Warning: 'Template behaviour security_001 contains
+      suspicious content — review before applying'. --strict mode rejects.
+    not: "Malicious content in template is applied without any validation."
+#
+anti_patterns:
+  - "Modifying files outside the .rosett-ai/ directory scope"
+  - "Requiring interactive input in CI environments"
+  - "Templates that embed engine-specific configuration"
+  - "Drift detection that flags cosmetic differences (comments, whitespace)"
+  - "Sync that silently downgrades or removes configuration keys"
+  - "Drift detection that requires network access to compute"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. architecture.yml: `rai init` creates the .rosett-ai/ structure that
+     project_management operates within. Init is scaffolding;
+     project is lifecycle.
+
+  2. retrofit.yml: retrofit imports existing native configs into Rosett-AI YAML.
+     Project management manages the ongoing lifecycle after import.
+     The flow is: init → retrofit → project → compile.
+
+  3. compiler.yml: forward drift detection compares source YAML against
+     compiled native config. Per-engine drift at the native level is
+     handled by compile, not project_management.
+
+  4. backward_compatibility.yml: `rai project sync` must handle upstream
+     breaking changes according to the deprecation policy.
+
+  5. security.yml: template content validation, YAML.safe_load, sync
+     source trust verification.
+
+  6. error_handling.yml: exit codes and structured error messages follow
+     the error hierarchy (what/why/fix format).
+
+  7. engine_architecture.yml: templates are engine-agnostic. Engine-specific
+     content is added during compilation via engine manifests.
+
+  8. scope_hierarchy.yml: defines the three-level scope model (global,
+     local, project). Project management commands operate within the
+     scope hierarchy. `rai init` creates scope markers; `rai project
+     status` reports the active scope.
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Template pattern with conflict resolution strategy"
+    - "Baseline comparison for drift detection (forward and template)"
+    - "Command pattern for project operations"
+    - "TTY-aware output (TtyHelper)"
+    - "Structured audit logging (JSON Lines)"
+  testing: rspec with project fixture directories, drift detection scenarios
+    (forward and template), template conflict resolution tests, sync
+    breaking-change handling, and CI non-interactive mode tests
+  gems:
+    - json_schemer
+    - thor
+    - diffy

data/conf/design/rai_mcp_asset_discovery.yml

@@ -0,0 +1,164 @@
+---
+name: rai_mcp_asset_discovery
+domain: core
+version: 0.1.0
+status: draft
+priority: 3
+author: hugo
+created_at: "2026-04-16"
+modified_at: "2026-04-16"
+modified_by: claude
+depends_on:
+  - mcp_integration
+  - compiler
+  - architecture
+  - scope_hierarchy
+#
+intent: |
+  Expose rosett-ai's behaviour files, compiled rules, and schemas as discoverable
+  MCP tools. This solves a concrete problem identified in W5-01 post-retrospective:
+  sessions outside the rosett-ai dev directory cannot find behaviour files because
+  they lack bundle context and don't know the XDG/packaged/project path hierarchy.
+
+  By exposing asset discovery via MCP, any AI session with the rosett-ai MCP server
+  configured can query behaviour files, search rules, and check compilation status
+  without knowing filesystem paths. This eliminates the root cause of the
+  retrospective skill path failure and enables other tools (skills, hooks, external
+  scripts) to discover rosett-ai assets programmatically.
+
+  The tools defined here are read-only discovery operations. Write operations
+  (compilation, behaviour management) are covered by the parent mcp_integration
+  design. This design focuses exclusively on the 5 asset discovery tools.
+#
+constraints:
+  - "All 5 tools must be read-only (readOnlyHint=true, destructiveHint=false)"
+  - "Tools must use the 3-tier lookup: project > XDG user > packaged defaults"
+  - "Tools must work without bundle context — no require of dev dependencies"
+  - "Tool responses must be structured JSON, not formatted text"
+  - "File paths in responses must use display paths (~/ prefix), never absolute /home/ paths"
+  - "rai_behaviour_get must not return sensitive behaviours unless explicitly requested"
+  - "rai_rule_search must search compiled output, not raw YAML source"
+  - "All tools must respect the scope field introduced in behaviour schema v1.2.0"
+  - "Tools must not expose file contents that match deny-list patterns (credentials, keys)"
+  - "Response payloads must be bounded — rai_behaviour_list returns metadata not full content"
+#
+acceptance_criteria:
+  - "rai_behaviour_list returns all discoverable behaviours with name, path, scope, rule count, and source tier (project/xdg/packaged)"
+  - "rai_behaviour_get returns the full YAML content of a named behaviour file"
+  - "rai_behaviour_get returns an error for non-existent or sensitive behaviours"
+  - "rai_rule_search accepts a keyword and returns matching rules with behaviour name, rule ID, priority, and matching text"
+  - "rai_rule_search supports optional filters: priority_min, scope, enabled_only"
+  - "rai_schema_get returns the behaviour YAML schema (behaviour_schema.json)"
+  - "rai_schema_get accepts an optional schema_name parameter to retrieve other schemas (design, tooling)"
+  - "rai_compile_status returns per-file staleness: source checksum vs compiled checksum"
+  - "rai_compile_status reports orphaned compiled files (no source) and uncompiled sources (no output)"
+  - "All 5 tools are registered in the MCP server tool manifest with accurate annotations"
+  - "Integration test verifies each tool via MCP JSON-RPC protocol handshake"
+  - "Tools work from any working directory, not just the rosett-ai source tree"
+#
+examples:
+  - scenario: "AI session needs to find behaviour files to propose a new rule"
+    expected: |
+      Tool call: { name: "rai_behaviour_list", arguments: {} }
+      Response:
+      {
+        "behaviours": [
+          {
+            "name": "operational_discipline",
+            "scope": "global",
+            "source_tier": "xdg",
+            "path": "~/.config/rosett-ai/conf/behaviour/operational_discipline.yml",
+            "version": "1.0.0",
+            "rules_count": 76,
+            "enabled_rules_count": 76
+          },
+          ...
+        ],
+        "total": 8,
+        "source_dirs": {
+          "project": null,
+          "xdg": "~/.config/rosett-ai/conf/behaviour/",
+          "packaged": "/opt/rosett-ai/app/conf/behaviour/"
+        }
+      }
+    not: "Tool returns empty list or crashes when run outside rosett-ai directory"
+  - scenario: "AI session searches for rules about git hooks"
+    expected: |
+      Tool call: { name: "rai_rule_search", arguments: { keyword: "git hook" } }
+      Response:
+      {
+        "matches": [
+          {
+            "behaviour": "operational_discipline",
+            "rule_id": "rule_022",
+            "priority": 90,
+            "scope": "global",
+            "snippet": "Never use OVERCOMMIT_DISABLE, --no-verify, or any mechanism to bypass git hooks..."
+          },
+          ...
+        ],
+        "total": 3
+      }
+    not: "Search returns raw YAML or requires knowledge of file paths"
+  - scenario: "AI session checks if compiled rules are up to date"
+    expected: |
+      Tool call: { name: "rai_compile_status", arguments: {} }
+      Response:
+      {
+        "status": "stale",
+        "files": [
+          {
+            "name": "behaviour-operational_discipline",
+            "source_checksum": "sha256:abc123...",
+            "compiled_checksum": "sha256:def456...",
+            "stale": true,
+            "compiled_at": "2026-04-15T10:30:00Z"
+          },
+          ...
+        ],
+        "orphaned": [],
+        "uncompiled": ["behaviour-new_feature"]
+      }
+    not: "Status check triggers recompilation or modifies files"
+  - scenario: "AI session retrieves a specific behaviour to read its rules"
+    expected: |
+      Tool call: { name: "rai_behaviour_get", arguments: { name: "criticalthinking" } }
+      Response:
+      {
+        "name": "criticalthinking",
+        "path": "~/.config/rosett-ai/conf/behaviour/criticalthinking.yml",
+        "source_tier": "xdg",
+        "content": { ... full parsed YAML ... }
+      }
+    not: "Returns raw file content as string instead of parsed structure"
+  - scenario: "AI session needs the schema to validate a behaviour before writing"
+    expected: |
+      Tool call: { name: "rai_schema_get", arguments: {} }
+      Response:
+      {
+        "schema_name": "behaviour_schema",
+        "version": "1.2.0",
+        "content": { ... full JSON Schema ... }
+      }
+    not: "Returns a file path instead of the schema content"
+#
+anti_patterns:
+  - "Returning absolute /home/user/ paths in tool responses — use display paths"
+  - "Loading the full compilation pipeline just to list behaviours"
+  - "Caching tool responses across MCP sessions — always read fresh from disk"
+  - "Implementing search by loading all YAML into memory — search compiled .md files"
+  - "Exposing raw file system operations (read, write, delete) as MCP tools"
+  - "Making rai_compile_status trigger compilation as a side effect"
+  - "Returning unstructured text — all responses must be parseable JSON objects"
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Service object per tool (RosettAi::Mcp::Tools::BehaviourList, etc.)"
+    - "PathResolver for all path discovery — never hardcode paths in tools"
+    - "Struct or Data for response objects — not raw hashes"
+  testing: rspec with MCP protocol integration tests, tool response schema
+    validation, edge cases for missing dirs and empty results
+  gems:
+    - mcp
+    - json_schemer