rosett-ai 1.3.3

data/conf/design/architecture.yml

@@ -0,0 +1,139 @@
+---
+name: architecture
+domain: core
+version: 2.0.0
+status: draft
+priority: 2
+author: hugo
+created_at: "2026-02-18"
+modified_at: "2026-03-23"
+modified_by: claude
+depends_on:
+  - security
+  - testing
+  - ci_pipeline
+  - scope_hierarchy
+
+intent: |
+  Define the overall system architecture of Rosett-AI as a TUI-first, pluggable
+  application with optional GUI layers delivered as separate Debian packages.
+  The core must run on headless servers (CLI/TUI only) while desktop users
+  can install GUI packages for their environment. All UI variants share the
+  same backend logic. The architecture must support multi-target AI model
+  compilation, licensing, i18n, and accessibility from the ground up —
+  informed by the security constraints established in Priority 1.
+
+  A foundational architectural principle is scope-first: all commands resolve
+  their working context from the three-level scope hierarchy (global, local,
+  project) before operating. Configuration sources are discovered from the
+  user's working directory, merged according to configurable strategies, and
+  compiled to scope-appropriate output locations. See scope_hierarchy.yml for
+  the full scope specification.
+
+constraints:
+  - Core package (rai) must be fully functional without any GUI package installed
+  - GUI packages must not introduce dependencies on TUI-specific libraries
+  - All UI variants share the same backend logic in lib/rosett_ai/
+  - Only Linux is supported; Debian is the target distribution
+  - Ruby is the implementation language; version managed via rbenv
+  - Thor is the CLI framework
+  - All configuration files are YAML (validated by JSON Schema)
+  - Abstract UI interface (lib/rosett_ai/ui/base.rb) defines the contract all GUI plugins implement
+  - GUI plugins are discovered at runtime via a registry pattern
+  - Security constraints from security.yml apply to all architectural layers
+  - "Scope-first: all commands resolve their working context from the
+    three-level scope hierarchy (global, local, project) before operating
+    (see scope_hierarchy.yml)"
+  - Commands must never assume a single fixed source directory — source
+    directories are resolved from the active scope
+
+acceptance_criteria:
+  - bin/raictl runs without errors on a headless Debian server (no X11/Wayland)
+  - Installing rosett-ai-gtk4 adds GTK4 UI option without modifying core
+  - lib/rosett_ai/ui/base.rb defines the abstract interface with documented methods
+  - lib/rosett_ai/ui/registry.rb discovers installed UI plugins automatically
+  - All business logic is in lib/rosett_ai/ (not in TUI or GUI code)
+  - conf/design/ documents are validated against conf/schemas/design_schema.json
+  - conf/behaviour/ documents are validated against conf/schemas/behaviour_schema.json
+  - Package dependencies are correctly declared (rosett-ai-gtk4 depends on rosett-ai)
+  - "Configuration sources are resolved from the three-level scope hierarchy:
+    global (~/.config/rosett-ai/conf/), local (<group>/.rosett-ai/conf/), project
+    (<project>/.rosett-ai/conf/) — see scope_hierarchy.yml"
+  - All scope-aware commands (compile, validate, design, behaviour) resolve
+    source directories from the active scope before operating
+
+examples:
+  - scenario: "User installs only the Rosett-AI core package on a server"
+    expected: "All CLI commands work. TUI mode is available. No GUI-related errors or warnings."
+    not: "Application crashes due to missing GTK4 or Qt6 libraries."
+  - scenario: "User installs rosett-ai-gtk4 alongside rosett-ai on a GNOME desktop"
+    expected: "bin/raictl --ui gtk4 launches GTK4 interface. bin/raictl (no flag) uses TUI as default."
+    not: "GTK4 becomes the default. TUI mode breaks. Core behaviour changes."
+  - scenario: "Developer adds a new feature to the compiler"
+    expected: "Feature is implemented in lib/rosett_ai/compiler/. Both TUI and GUI see the feature without changes."
+    not: "Feature requires separate implementation in TUI and GUI code."
+  - scenario: "New AI model (e.g. Gemma) needs to be supported as compilation target"
+    expected: "Add conf/targets/gemma.yml with model profile. No code changes needed."
+    not: "Requires modifying compiler source code or adding conditional logic."
+
+anti_patterns:
+  - Business logic in UI layer (TUI or GUI code making domain decisions)
+  - GUI-specific dependencies in core package
+  - Hardcoded paths instead of XDG-compliant directory resolution
+  - Assuming a single fixed source directory for all commands regardless of
+    working directory (see scope_hierarchy.yml)
+  - Monolithic package that bundles all UI toolkits
+  - Plugin discovery that requires editing a config file instead of auto-detection
+
+gui_notes: |
+  Implicit Assumptions (documented per DESIGN_AUDIT.md recommendation #6):
+
+  1. Linux-only: rosett-ai targets Linux exclusively. macOS and Windows are not
+     supported. This is stated in constraints but deserves explicit callout
+     as it affects all design documents.
+
+  2. Debian-first: Primary packaging is .deb for Debian/Ubuntu. RPM support
+     (Fedora/RHEL) is Phase 2 of the distribution design. Other packaging
+     formats (AppImage, Homebrew, Winget) are Phase 3+.
+
+  3. Single-user: XDG paths (~/.config/rosett-ai/, ~/.cache/rosett-ai/) assume a
+     single user per HOME directory. Multi-user installations with shared
+     system-wide config are not designed for. Root-level managed settings
+     (/etc/claude-code/) are the exception for enterprise deployment.
+
+  4. Ruby 3.3.10: The project targets Ruby 3.3.10 managed via rbenv. This
+     is scattered across design documents but should be understood as a
+     hard constraint. Version bumps require updating rbenv, CI, and the
+     .ruby-version file.
+
+  5. Zeitwerk lazy loading: All module autoloading uses Zeitwerk. No
+     eager_load calls outside of test/CI. This affects startup time and
+     memory usage (see usage_optimization.yml).
+
+  6. UTF-8 everywhere: All text processing assumes UTF-8 encoding. YAML
+     files, CLI output, log files, and configuration all use UTF-8. No
+     other encodings are supported for configuration files.
+
+  7. Three-level scope hierarchy: The architecture supports three distinct
+     configuration scopes resolved from the user's working directory:
+       - Global: ~/.config/rosett-ai/conf/ (XDG user config, applied everywhere)
+       - Local:  <group-dir>/.rosett-ai/conf/ (workspace-level, multi-project groups)
+       - Project: <project-dir>/.rosett-ai/conf/ (project-specific overrides)
+     Each scope has its own conf/ subtree with the same structure as the
+     raictl source directory. Commands auto-detect the active scope from the
+     working directory. See scope_hierarchy.yml for the full specification.
+
+preferences:
+  language: ruby
+  patterns:
+    - hexagonal_architecture
+    - plugin_registry
+    - dependency_injection
+    - interface_contracts_via_shared_examples
+  testing: rspec with shared examples for interface contracts
+  gems:
+    - thor
+    - json_schemer
+    - tty-prompt
+    - tty-table
+    - pastel

data/conf/design/autocompletion.yml

@@ -0,0 +1,115 @@
+---
+name: autocompletion
+domain: ui
+version: 0.1.0
+status: implemented
+priority: 3
+author: hugo
+created_at: "2026-03-15"
+modified_at: "2026-03-16"
+modified_by: claude
+depends_on:
+  - ui_framework
+  - architecture
+  - security
+  - error_handling
+#
+intent: |
+  Generate shell completion scripts for bash, zsh, and fish from the Thor
+  command registry to reduce friction, prevent typos, and improve
+  discoverability across rosett-ai's 17+ subcommands with nested sub-subcommands,
+  flags, and dynamic arguments (behaviour names, design doc names, engine
+  names). Integrate completion installation into the .deb postinst script
+  for zero-configuration setup.
+
+  This design governs shell-level tab completion for the Rosett-AI CLI. It does
+  not cover in-prompt AI completions (which would be an engine-specific
+  feature) or TUI input field autocompletion (which is governed by
+  ui_framework.yml).
+#
+constraints:
+  - "Must support bash (>= 4.0), zsh (>= 5.0), and fish (>= 3.0)"
+  - "Completion scripts must be generated from the Thor command registry —
+    not hand-maintained"
+  - "Dynamic completions (behaviour names, engine names) must use rosett-ai
+    subcommands, not file globbing"
+  - "Completion script installation must integrate with the .deb postinst
+    script"
+  - "Must not slow down shell startup — lazy-load where possible"
+  - "Completion data must reflect the currently installed version of Rosett-AI"
+  - "Generated completion scripts must not contain shell injection
+    vulnerabilities — all dynamic values must be properly escaped"
+  - "This design governs shell tab completion for the Rosett-AI CLI binary.
+    TUI input completions are governed by ui_framework.yml"
+#
+acceptance_criteria:
+  - "`rai completion bash` outputs a bash completion script to stdout"
+  - "`rai completion zsh` outputs a zsh completion script to stdout"
+  - "`rai completion fish` outputs a fish completion script to stdout"
+  - "`rai completion install` installs the script for the current shell"
+  - "Tab-completing `raictl b<TAB>` suggests `backup`, `behaviour`, `build`"
+  - "Tab-completing `rai behaviour show <TAB>` lists available behaviour
+    names"
+  - "Tab-completing `rai compile --engine <TAB>` lists installed engines"
+  - ".deb postinst installs completions automatically"
+  - "Exit code 0 on success, 1 on generation failure, 3 on unsupported
+    shell"
+#
+examples:
+  - scenario: "User types `raictl com<TAB>` in bash"
+    expected: |
+      Shell completes to `raictl comp` then offers `compile`, `comply`,
+      `content`.
+    not: "No completion offered; user must type the full command"
+  - scenario: "User installs rosett-ai via .deb package"
+    expected: |
+      Completion script installed to
+      /usr/share/bash-completion/completions/rosett-ai automatically.
+    not: "User must manually source the completion script"
+  - scenario: "New engine installed after rosett-ai"
+    expected: |
+      Engine appears in `--engine <TAB>` completions on next invocation.
+    not: "Completions are stale until rosett-ai is reinstalled."
+  - scenario: "User requests completion for an unsupported shell"
+    expected: |
+      `rai completion tcsh` exits with code 3 and message: 'Shell tcsh
+      is not supported — available: bash, zsh, fish'. Suggests using
+      `rai completion bash` as a starting point.
+    not: "Silent failure or crash with unhandled exception."
+#
+anti_patterns:
+  - "Hand-maintaining completion scripts separate from the Thor command
+    registry"
+  - "Completion scripts that call rosett-ai on every tab press (too slow)"
+  - "Hardcoding command lists instead of generating from Thor metadata"
+  - "Shell-specific hacks that break on version upgrades"
+  - "Unescaped dynamic values in generated completion scripts"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. architecture.yml: completion installation integrates with the .deb
+     postinst script and the `rai init` setup flow.
+
+  2. ui_framework.yml: shell tab completion is distinct from TUI input
+     field completion. Both improve UX but at different layers.
+
+  3. engine_architecture.yml: dynamic engine name completion uses
+     `rai engines list` output, driven by engine manifests.
+
+  4. security.yml: generated completion scripts must escape dynamic values
+     to prevent shell injection.
+
+  5. error_handling.yml: exit codes follow the error hierarchy.
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Thor command introspection for completion data"
+    - "Template-based script generation per shell"
+    - "Lazy evaluation for dynamic completions"
+    - "Shell-safe escaping for generated scripts"
+  testing: rspec with shell completion script generation tests, dynamic
+    argument scenarios, and .deb postinst integration tests
+  gems:
+    - thor

data/conf/design/backward_compatibility.yml

@@ -0,0 +1,112 @@
+---
+name: backward_compatibility
+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:
+  - architecture
+  - security
+  - compiler
+  - engine_architecture
+  - error_handling
+#
+intent: |
+  Define the deprecation policy, migration paths, and versioning contracts for
+  rosett-ai. Users and engine authors must know which interfaces are stable, how
+  breaking changes are communicated, and what migration steps are required when
+  upgrading. Without this document, breaking changes surprise users and engine
+  authors lose trust in the platform stability.
+
+  Per-version migration guides (doc/migration/) provide step-by-step upgrade
+  instructions for each major version boundary. Each guide documents what
+  changed, why, what user action is required, and where automated migration
+  tooling (`bin/raictl migrate`) handles the transition automatically. Migration
+  guides are published alongside the release and linked from CHANGELOG.md.
+#
+constraints:
+  - Public CLI commands must not change behaviour without a deprecation cycle of at least one minor version
+  - Deprecated CLI options must emit a warning on stderr with the replacement and removal version
+  - Design document schema changes must be backward-compatible within a major version (additive only)
+  - Behaviour YAML format changes must include a migration path or automated migration tool
+  - Engine API (RosettAiEngine::Base interface) changes require a deprecation notice in CHANGELOG.md
+  - SemVer must be strictly enforced — patch for fixes, minor for features, major for breaking changes
+  - Compiled output format changes (rules/) must not silently change semantics between versions
+  - Configuration file migrations must be automated where possible (bin/raictl init handles upgrades)
+  - Removal of a public method or CLI command requires major version bump
+  - Deprecation warnings must include the version where the feature was deprecated and the planned removal version
+  - Per-version migration guides must exist in doc/migration/ for each major version
+  - Migration guides must document what changed, why, required user action, and automated tooling
+  - "`bin/raictl migrate` must detect the current config version and apply required migrations"
+#
+acceptance_criteria:
+  - Deprecated CLI options produce a warning on stderr with replacement and removal version
+  - CHANGELOG.md documents all breaking changes under a "BREAKING CHANGES" section
+  - bin/raictl version --check reports if running config files need migration
+  - Design schema version is tracked and validated against document version
+  - Engine gems declare minimum rai version via gemspec dependency
+  - At least one minor release exists between deprecation warning and removal
+  - Automated migration exists for behaviour YAML format changes (bin/raictl migrate)
+  - SemVer compliance is enforced by CI (conventional commits parsed for version bumps)
+  - Public Ruby API methods removed without deprecation cycle cause CI failure
+  - Release notes include a migration guide for any breaking change
+  - doc/migration/v1-to-v2.md (and subsequent) exist for each major version boundary
+  - "`bin/raictl migrate` detects current config version and applies migrations automatically"
+  - "Migration guides are linked from CHANGELOG.md release entries"
+#
+examples:
+  - scenario: "A CLI option --target is renamed to --engine in v1.1.0"
+    expected: |
+      v1.1.0: --target still works but emits warning: "WARNING: --target is
+      deprecated (since v1.1.0), use --engine instead. Will be removed in v2.0.0."
+      v2.0.0: --target is removed. Error message suggests --engine.
+    not: |
+      v1.1.0: --target silently stops working. No warning, no migration path.
+  - scenario: "Behaviour YAML gains a new required field in schema v1.2.0"
+    expected: |
+      New field has a default value. Existing files without the field pass
+      validation with a deprecation warning. bin/raictl migrate adds the field
+      to existing files.
+    not: |
+      Existing behaviour files fail validation immediately. Users must
+      manually edit every file.
+  - scenario: "Engine API method compile_rules is renamed to compile"
+    expected: |
+      v1.x: Both compile_rules and compile work. compile_rules emits
+      deprecation warning. Engine compatibility test verifies both.
+      v2.0: compile_rules removed. Engine scaffold generates compile.
+    not: |
+      Engine gems break on upgrade. No compatibility shim provided.
+  - scenario: "User upgrades rosett-ai from 1.0 to 2.0"
+    expected: |
+      bin/raictl init --global detects v1.0 config and offers migration.
+      CHANGELOG.md 2.0.0 section lists all breaking changes with fixes.
+      Engine gems with rosett-ai >= 1.0 dependency show compatibility warning.
+    not: |
+      Silent breakage. User discovers issues at runtime.
+#
+anti_patterns:
+  - Removing public API methods without a deprecation cycle
+  - Changing CLI command behaviour silently between versions
+  - Breaking schema backward compatibility within a major version
+  - Relying on users reading CHANGELOG.md for migration (automate where possible)
+  - Adding required fields to YAML schemas without default values
+  - Using internal constants or methods in engine gems (no stability guarantee)
+  - Skipping SemVer rules for "small" breaking changes
+  - Deprecation warnings without specifying the removal version
+#
+preferences:
+  language: ruby
+  patterns:
+    - deprecation_warnings
+    - semver_enforcement
+    - automated_migration
+    - compatibility_shims
+  testing: rspec with version migration scenarios
+  gems:
+    - thor
+    - semantic

data/conf/design/behaviour_composition.yml

@@ -0,0 +1,246 @@
+---
+name: behaviour_composition
+domain: core
+version: 1.0.0
+status: draft
+priority: 2
+author: hugo
+created_at: "2026-03-10"
+modified_at: "2026-03-23"
+modified_by: claude
+depends_on:
+  - compiler
+  - architecture
+  - engine_architecture
+  - security
+  - error_handling
+  - scope_hierarchy
+#
+intent: |
+  Define how multiple behaviour YAML files are composed, layered, and
+  merged during compilation. As rai projects grow, users author dozens
+  of behaviour files across different scopes (global, local, project).
+  This design governs the composition rules: what happens when behaviours
+  conflict, how priorities resolve ties, how scopes layer, and how the
+  final compiled output is deterministic.
+
+  Without explicit composition rules, behaviour merging becomes
+  unpredictable — a behaviour at priority 50 in the global scope might
+  silently override a project-specific rule at the same priority. This
+  design makes composition explicit, debuggable, and auditable.
+
+  Key capabilities:
+    - Scope hierarchy: global > local > project (each successive scope
+      overrides the previous at equal priority). The three-level scope
+      model is defined in scope_hierarchy.yml — this document defers to
+      that specification for scope definitions and detection algorithm
+    - Priority-based ordering within each scope (1-100, lower = higher priority)
+    - Conflict detection: when two rules with the same ID exist at the
+      same scope and priority, compilation emits a warning
+    - Composition modes: merge (combine rules), override (replace entire
+      behaviour), exclude (skip specific rules by ID)
+    - Hiera-like configurable merge strategies: first-found (highest
+      priority wins), deep-merge (recursive hash merge), array-union
+      (combine array values from all scopes)
+    - Dry-run composition: bin/raictl compile --simulate shows which rules
+      win, which are overridden, and why
+    - Lockfile: bin/raictl compile --vendor writes a lockfile capturing
+      the exact composition result for reproducible builds
+#
+constraints:
+  - This design governs composition rules (ordering, merging, conflict
+    resolution). The compilation pipeline (YAML-to-native transformation,
+    file I/O, target selection) is governed by compiler.yml
+  - Composition must be deterministic — same inputs always produce same output
+  - Merge strategy must be configurable per behaviour key — supported
+    strategies are first-found (highest priority wins), deep-merge
+    (recursive hash merge), and array-union (combine array values)
+  - When two rules have equal scope and priority, alphabetical behaviour
+    name breaks the tie
+  - Behaviour names must be NFC-normalized before alphabetical comparison
+    (per security.yml Unicode normalization constraint)
+  - Security-domain behaviours can never be overridden by non-security behaviours
+  - Behaviours marked as sensitive are excluded from non-internal compilation targets
+  - Composition order must be documented in the lockfile for auditability
+  - The lockfile must capture the active merge strategy configuration
+    alongside composition results — without it, determinism is not guaranteed
+  - Rule IDs must be unique within a single behaviour file
+  - Cross-behaviour rule ID collisions produce warnings (errors in --strict mode)
+  - Excluded rules must be explicitly listed — no wildcard exclusions
+  - Composition must handle circular depends_on with a clear error
+  - The lockfile must be a human-readable YAML file, not a binary format
+  - Lockfile parsing must use YAML.safe_load (same constraint as all
+    other YAML in the system)
+  - Compiled output must have snapshot baselines in spec/fixtures/snapshots/
+    for regression testing — baselines are committed to git and reviewed in MRs
+  - Property-based tests (Rantly) must verify composition determinism across
+    random priority/scope combinations
+  - Composed output must not exceed 50 MB total (configurable). Per-file
+    YAML limits (1 MB, 10 nesting, 1000 keys) from security.yml remain
+    unchanged
+#
+acceptance_criteria:
+  - bin/raictl compile merges all behaviour files respecting scope hierarchy and priority
+  - "Scope hierarchy (global > local > project) is applied correctly in
+    all cases — see scope_hierarchy.yml for scope definitions"
+  - Equal-priority rules within the same scope are ordered by behaviour name (alphabetical)
+  - Security-domain behaviours cannot be overridden by lower-domain behaviours
+  - bin/raictl compile --verbose shows composition trace (which rule wins, why)
+  - bin/raictl compile --simulate --verbose shows full composition without writing files
+  - bin/raictl compile --vendor writes a lockfile with exact composition result
+  - Lockfile can be used to reproduce exact compilation (bin/raictl compile --frozen)
+  - Cross-behaviour rule ID collisions produce warnings (or errors with --strict)
+  - Circular depends_on is detected and reported with the cycle path
+  - Behaviours with the sensitive flag are excluded when compiling for external targets
+  - Composition result is identical across Ruby versions (no hash ordering dependency)
+  - bin/raictl behaviour conflicts lists all detected rule ID collisions
+  - First-found merge strategy selects the value from the highest-priority scope only
+  - Deep-merge strategy recursively merges hash values from all scopes
+  - Array-union strategy combines array values from all scopes, deduplicating entries
+  - bin/raictl behaviour conflicts uses TTY-aware output (table when
+    interactive, plain text when piped)
+#
+examples:
+  - scenario: "Global behaviour sets Ruby style at priority 50, project overrides at priority 50"
+    expected: |
+      Project scope wins because later scopes override earlier at equal
+      priority. --verbose output shows: 'Rule ruby_style_001: project
+      scope overrides global scope (equal priority, scope wins)'.
+    not: "Undefined behaviour. Sometimes global wins, sometimes project."
+  - scenario: "Two project behaviours both define rule ID security_001"
+    expected: |
+      Warning: 'Rule ID collision: security_001 defined in both
+      code_security.yml and api_security.yml. Alphabetical tie-break:
+      api_security.yml wins'. In --strict mode, this is an error.
+    not: "Silent override. No indication which rule was used."
+  - scenario: "Local-scope behaviour marks rules as sensitive, compiled for external AGENTS.md"
+    expected: |
+      Sensitive rules are excluded from AGENTS.md compilation. --verbose
+      shows: 'Excluding 3 sensitive rules from agents_md target'.
+      Non-sensitive rules compile normally.
+    not: "Sensitive internal rules appear in public AGENTS.md."
+  - scenario: "Developer runs bin/raictl compile --frozen with a lockfile"
+    expected: |
+      Compilation uses exactly the composition recorded in the lockfile.
+      If behaviour files have changed since the lockfile was created,
+      a warning is emitted: 'Behaviour files changed since lockfile —
+      run bin/raictl compile --vendor to update'.
+    not: "Lockfile silently ignored. Compilation uses current files."
+  - scenario: "Behaviour A depends_on B, B depends_on A"
+    expected: |
+      bin/raictl compile detects circular dependency and fails with error:
+      'Circular dependency detected: A -> B -> A'. No output written.
+    not: "Infinite loop. Stack overflow. Silent incorrect output."
+  - scenario: "Project excludes specific global rules by ID"
+    expected: |
+      Project config contains 'exclude: [global_rule_001, global_rule_003]'.
+      Those rules are skipped during composition. --verbose shows:
+      'Rule global_rule_001: excluded by project scope'.
+    not: |
+      Exclude is silently ignored. Excluded rules still appear in output.
+      Wildcard 'exclude: [*]' is accepted (must be rejected).
+  - scenario: "Developer runs bin/raictl behaviour conflicts"
+    expected: |
+      TTY-aware output lists all rule ID collisions across scopes:
+      ┌─────────────────┬───────────────┬───────────────┬────────┐
+      │ Rule ID         │ File A        │ File B        │ Winner │
+      ├─────────────────┼───────────────┼───────────────┼────────┤
+      │ security_001    │ code_sec.yml  │ api_sec.yml   │ A      │
+      └─────────────────┴───────────────┴───────────────┴────────┘
+      Piped output: 'security_001\tcode_sec.yml\tapi_sec.yml\tA'
+    not: "No output. Developer must read compile --verbose logs to find collisions."
+  - scenario: "Deep-merge strategy combines settings from global and project scopes"
+    expected: |
+      Global defines { editor: { theme: dark } }. Project defines
+      { editor: { font_size: 14 } }. Deep-merge produces
+      { editor: { theme: dark, font_size: 14 } }.
+    not: "Project replaces entire editor hash. Global theme is lost."
+  - scenario: "Developer incorrectly uses a wildcard exclusion"
+    expected: |
+      bin/raictl compile rejects 'exclude: ["*"]' with error: 'Wildcard
+      exclusions are not permitted — list specific rule IDs to exclude'.
+    not: "All rules are excluded. Empty output is silently produced."
+  - scenario: "Lockfile schema example"
+    expected: |
+      The lockfile (rosett-ai-compose.lock.yml) contains:
+        rai_version: 1.0.0
+        composed_at: '2026-03-16T10:00:00Z'
+        merge_strategy:
+          default: first_found
+          overrides:
+            editor_settings: deep_merge
+            allowed_tools: array_union
+        composition:
+          - rule_id: ruby_style_001
+            source: project/code_quality.yml
+            scope: project
+            priority: 50
+            action: included
+          - rule_id: global_rule_003
+            source: global/defaults.yml
+            scope: global
+            priority: 80
+            action: excluded_by_project
+        scope_resolution:
+          global: ~/.config/rosett-ai/conf/
+          local: ~/projects/.rosett-ai/conf/
+          project: ~/projects/acme-api/.rosett-ai/conf/
+    not: "Lockfile is a binary blob or lacks merge strategy configuration."
+#
+anti_patterns:
+  - Non-deterministic composition (relying on hash iteration order)
+  - Implicit conflict resolution without user visibility
+  - Allowing non-security behaviours to override security constraints
+  - Wildcard exclusions that could accidentally suppress critical rules
+  - Binary lockfile formats that cannot be reviewed in pull requests
+  - Ignoring sensitive flags during cross-target compilation
+  - Circular dependency detection only at runtime (must be compile-time)
+  - Comparing behaviour names without Unicode NFC normalization
+  - Omitting merge strategy from lockfile (breaks reproducibility)
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. compiler.yml: composition feeds into the compilation pipeline as a
+     pre-processing phase. Compiler invokes composition, not vice versa.
+
+  2. security.yml: security-domain override protection and YAML.safe_load
+     constraints apply to all composition operations.
+
+  3. error_handling.yml: composition errors (circular deps, ID collisions)
+     follow the structured error hierarchy (exit code 2, what/why/fix format).
+
+  4. engine_architecture.yml: engines may express merge strategy preferences
+     via their capability manifests, but composition itself is engine-agnostic.
+
+  5. backward_compatibility.yml: composition rules are a public API surface —
+     changes to scope hierarchy or merge behaviour are breaking changes.
+
+  6. scope_hierarchy.yml: authoritative specification for the three-level
+     scope model (global > local > project). This document defines
+     composition rules within that model; scope_hierarchy.yml defines
+     scope detection, merge strategies, and directory resolution.
+
+  ScopeResolver specification:
+    SCOPE_ORDER = ['global', 'local', 'project']
+    # Each successive scope overrides the previous at equal priority.
+    # See scope_hierarchy.yml for detection algorithm and merge semantics.
+#
+preferences:
+  language: ruby
+  patterns:
+    - hiera_like_hierarchical_lookup
+    - configurable_merge_strategies
+    - deterministic_composition
+    - scope_hierarchy_with_priority
+    - explicit_conflict_resolution
+    - lockfile_for_reproducibility
+    - compile_time_cycle_detection
+  testing: rspec with multi-scope fixtures, conflict scenarios, merge strategy
+    tests, lockfile round-trip tests, snapshot baselines in spec/fixtures/snapshots/
+    for compiled output regression, and Rantly property-based tests for composition
+    determinism and priority ordering edge cases
+  gems:
+    - json_schemer
+    - thor
+    - rantly

data/conf/design/build_rake_extraction.yml

@@ -0,0 +1,57 @@
+---
+name: build_rake_extraction
+domain: core
+version: "1.0.0"
+status: implemented
+intent: |
+  Extract build, release, and documentation Thor tasks from the raictl CLI
+  into a Rakefile-based development toolchain. The Thor CLI serves the
+  application's end-user commands exclusively. Developer-facing tasks
+  (package building, engine .deb compilation, release preparation, version
+  tagging, documentation generation) belong in Rake, which is the standard
+  Ruby tool for project-internal automation.
+
+  Implemented in v1.2.0: build and release commands added to INTERNAL_COMMANDS
+  in cli.rb (hidden from raictl --help), Rake tasks delegate to existing
+  Thor task classes. The Thor classes remain in lib/ as the implementation;
+  Rake is the developer-facing entry point.
+
+constraints:
+  - "Thor CLI must only expose end-user commands (compile, validate, behaviour, design, etc.)"
+  - "Rake tasks must be invocable via `bundle exec rake <task>` from the source tree"
+  - "Rake tasks must NOT be shipped in the .deb package"
+  - "build and release are in INTERNAL_COMMANDS (hidden from non-internal contexts)"
+  - "Existing fpm integration, variant configs, and wrapper template must be preserved"
+  - "No regression in .deb quality — same postinst/prerm/postrm scripts"
+
+acceptance_criteria:
+  - "`rake build:package` builds the same .deb as the Thor task"
+  - "`rake build:engine` builds an engine .deb"
+  - "`rake release:prepare[minor]` bumps version and generates CHANGELOG"
+  - "`rake release:tag` creates an annotated git tag"
+  - "`rake readme:update` updates README version, test count, engine count"
+  - "`raictl help` does not show build or release commands"
+  - "InSpec integration tests pass"
+
+examples:
+  - scenario: "Developer builds core .deb package"
+    expected: "`bundle exec rake build:package` produces pkg/rosett-ai_*.deb"
+  - scenario: "Developer builds GTK4 variant"
+    expected: "`bundle exec rake build:package[gtk4]` produces GTK4 variant .deb"
+  - scenario: "Developer prepares a minor release"
+    expected: "`bundle exec rake release:prepare[minor]` bumps version and generates CHANGELOG"
+
+preferences:
+  language: ruby
+  patterns:
+    - "Namespace Rake tasks: build:package, build:engine, release:prepare, release:tag, readme:update"
+    - "Rake tasks delegate to Thor task classes via .new.invoke(:method)"
+    - "Keep variant_config.rb and packaging/ directory structure unchanged"
+  gems:
+    - rake
+    - fpm
+
+anti_patterns:
+  - "Do not create a separate build tool or script — use Rake"
+  - "Do not duplicate logic — Rake delegates to Thor task classes"
+  - "Do not ship Rakefile in the .deb package"