rosett-ai 1.3.3

data/doc/changes/2026-02-21-path-resolver.md

@@ -0,0 +1,128 @@
+# Implement ADR-002 PathResolver (Phase 3)
+
+**Branch**: `design_implementation`
+**Date**: 2026-02-21
+**ADR**: `doc/decisions/002-path-resolution-strategy.md`
+**Design docs affected**: `architecture.yml` (anti-pattern elimination)
+
+## Motivation
+
+Six library files contained hardcoded `~/.claude` paths and two files contained
+hardcoded `~/.config/rosett-ai` paths. The `architecture.yml` design document lists
+"hardcoded paths instead of XDG-compliant directory resolution" as an
+anti-pattern. ADR-002 was accepted to centralise all path resolution in a single
+class.
+
+## Design decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Class vs module | Class with instance methods | Future-proofed for ADR-006 multi-engine (pass `engine:` keyword) |
+| Return type | `Pathname` everywhere | Consistent API, chainable `.join()`, type-safe |
+| Display strings | Tilde form (`~/.claude/rules`) | Lockfile portability across machines |
+| Singleton accessor | `RosettAi.paths` on module | Clean call sites, single point to swap for multi-engine |
+
+## Changes by area
+
+### RosettAi::PathResolver (new)
+
+**File**: `lib/rosett_ai/path_resolver.rb` (36 lines)
+
+Centralises all filesystem path resolution into a single class:
+
+| Method | Returns | Domain |
+|--------|---------|--------|
+| `global_dir` | `Pathname(~/.claude)` | Claude Code |
+| `rules_dir` | `Pathname(~/.claude/rules)` | Claude Code |
+| `local_dir` | `Pathname(./claude)` | Claude Code |
+| `project_claude_md` | `Pathname(./CLAUDE.md)` | Claude Code |
+| `rai_config_dir` | `Pathname($XDG_CONFIG_HOME/rosett-ai)` | rosett-ai (XDG) |
+| `secrets_file` | `Pathname(rai_config_dir/secrets.yml)` | rosett-ai (XDG) |
+| `rules_display_path` | `'~/.claude/rules'` (String) | Lockfile display |
+
+Constructor accepts `engine:` keyword (defaults to `:claude`) for future
+multi-engine support per ADR-006.
+
+### RosettAi module accessor
+
+**File**: `lib/rosett_ai.rb`
+
+Added `RosettAi.paths` memoized accessor and updated `RosettAi.reset_config!` to clear
+the paths instance alongside the config instance.
+
+### Thor task refactoring (4 files)
+
+| File | Old | New |
+|------|-----|-----|
+| `compile.rb:70` | `Pathname.new(File.expand_path('~/.claude/rules'))` | `RosettAi.paths.rules_dir` |
+| `adopt.rb:64` | `Pathname.new(File.expand_path('~/.claude/rules'))` | `RosettAi.paths.rules_dir` |
+| `init.rb:49` | `File.expand_path('~/.claude')` | `RosettAi.paths.global_dir.to_s` |
+| `init.rb:59` | `File.join(Dir.pwd, '.claude')` | `RosettAi.paths.local_dir.to_s` |
+| `backup.rb:96` | `File.expand_path('~/.claude')` | `RosettAi.paths.global_dir.to_s` |
+| `backup.rb:107` | `File.join(Dir.pwd, '.claude')` | `RosettAi.paths.local_dir.to_s` |
+| `backup.rb:117` | `File.join(Dir.pwd, 'CLAUDE.md')` | `RosettAi.paths.project_claude_md.to_s` |
+
+### BehaviourCompiler lockfile paths
+
+**File**: `lib/rosett_ai/compiler/behaviour_compiler.rb`
+
+| Line | Old | New |
+|------|-----|-----|
+| 143 | `"~/.claude/rules/#{filename}"` | `"#{RosettAi.paths.rules_display_path}/#{filename}"` |
+| 155 | `'~/.claude/rules'` | `RosettAi.paths.rules_display_path` |
+
+### SecretsResolver constant elimination
+
+**File**: `lib/rosett_ai/secrets_resolver.rb`
+
+Removed `SECRETS_DIR` and `SECRETS_FILE` constants. All path references now go
+through `RosettAi.paths.secrets_file` and `RosettAi.paths.rai_config_dir`. The
+`raise_missing` error message dynamically includes the secrets file path.
+
+### Spec updates
+
+| File | Change |
+|------|--------|
+| `spec/rosett_ai/secrets_resolver_spec.rb` | `stub_const` replaced with `instance_double(RosettAi::PathResolver)` |
+| `spec/rosett_ai/thor/tasks/init_spec.rb` | `stub_home` uses PathResolver `instance_double` |
+| `spec/rosett_ai/thor/tasks/backup_spec.rb` | `stub_home` uses PathResolver `instance_double` |
+
+### Configuration
+
+| File | Change |
+|------|--------|
+| `.mutant.yml` | Added `RosettAi::PathResolver` and `RosettAi::SecretsResolver` to subjects |
+
+## Files inventory
+
+| Action | File |
+|--------|------|
+| New | `lib/rosett_ai/path_resolver.rb` |
+| New | `spec/rosett_ai/path_resolver_spec.rb` |
+| Modified | `lib/rosett_ai.rb` |
+| Modified | `lib/rosett_ai/thor/tasks/compile.rb` |
+| Modified | `lib/rosett_ai/thor/tasks/adopt.rb` |
+| Modified | `lib/rosett_ai/thor/tasks/init.rb` |
+| Modified | `lib/rosett_ai/thor/tasks/backup.rb` |
+| Modified | `lib/rosett_ai/compiler/behaviour_compiler.rb` |
+| Modified | `lib/rosett_ai/secrets_resolver.rb` |
+| Modified | `spec/rosett_ai/secrets_resolver_spec.rb` |
+| Modified | `spec/rosett_ai/thor/tasks/init_spec.rb` |
+| Modified | `spec/rosett_ai/thor/tasks/backup_spec.rb` |
+| Modified | `.mutant.yml` |
+| Modified | `doc/decisions/002-path-resolution-strategy.md` |
+
+## Verification
+
+- [x] `bundle exec rspec spec/rosett_ai/path_resolver_spec.rb` — 22 examples, 0 failures
+- [x] `bundle exec rspec spec/rosett_ai/secrets_resolver_spec.rb` — 18 examples, 0 failures
+- [x] `bundle exec rspec spec/rosett_ai/thor/tasks/init_spec.rb` — 9 examples, 0 failures
+- [x] `bundle exec rspec spec/rosett_ai/thor/tasks/backup_spec.rb` — 21 examples, 0 failures
+- [x] `bundle exec rspec spec/rosett_ai/thor/tasks/compile_spec.rb` — 11 examples, 0 failures
+- [x] `bundle exec rspec spec/rosett_ai/thor/tasks/adopt_spec.rb` — 14 examples, 0 failures
+- [x] `bundle exec rspec` — 501 examples, 0 failures
+- [x] `bundle exec rubocop` — 81 files, 0 offenses
+- [x] `bundle exec reek` — 0 warnings
+- [x] `bin/raictl compile --simulate --verbose` — CLI smoke test passes
+- [x] No hardcoded `~/.claude` paths remain outside PathResolver and display strings
+- [x] No hardcoded `~/.config/rosett-ai` paths remain outside PathResolver

data/doc/changes/2026-02-24-ci-tmpdir-mutant-fetch.md

@@ -0,0 +1,45 @@
+# Fix CI pipeline: TMPDIR world-writable warnings and mutant git fetch
+
+**Date**: 2026-02-24
+**Branch**: `design_implementation`
+**Related jobs**: `test:rspec`, `test:mutant`
+
+## Summary
+
+Two CI pipeline failures resolved in a single change:
+
+1. **TMPDIR world-writable warnings** — Ruby's `Dir.tmpdir` emits warnings
+   when `/tmp` is world-writable (standard in Docker containers). RSpec and
+   other Ruby tools surfaced these as test output noise or failures.
+
+2. **Mutant git fetch permission denied** — The `.base` template sets the
+   git remote to SSH (`git@...`) via a deploy key, but `test:mutant` was the
+   only job that performed an explicit `git fetch` after setup. The deploy key
+   lacked the necessary read access for this operation.
+
+## Changes
+
+### `.gitlab-ci-files/global/defaults.yml`
+
+- Added `export TMPDIR=$(mktemp -d)` as the first line of `.base`
+  `before_script` — covers all jobs extending `.base`, `.ruby_base`, and
+  `.security_base`
+- Added the same to `.minimal_base` `before_script` for consistency
+- `mktemp -d` creates a directory with `0700` permissions, eliminating
+  the world-writable path warnings
+
+### `.gitlab-ci-files/test/mutant.yml`
+
+- Added `git remote set-url origin "${CI_REPOSITORY_URL}"` before
+  `git fetch` in the `test:mutant` job script
+- `CI_REPOSITORY_URL` is a predefined GitLab CI variable containing the
+  HTTPS URL with the ephemeral CI job token, providing guaranteed read
+  access to the project without depending on the SSH deploy key
+
+## Rationale
+
+- The TMPDIR fix is applied at the `.base` template level so every job
+  inherits it automatically — no per-job configuration needed
+- Using `CI_REPOSITORY_URL` for mutant's fetch is preferred over fixing
+  the deploy key because it uses GitLab's built-in authentication and
+  requires no infrastructure changes

data/doc/changes/2026-03-01-ci-bundler-strategy.md

@@ -0,0 +1,120 @@
+# CI Bundler Strategy and RuboCop Compliance
+
+**Branch**: `docs/update-implementation-plan`
+**Date**: 2026-03-01
+**ADR**: `doc/decisions/008-ci-bundler-strategy.md`
+**Commits**: 17430f6 (desktop exclusion), 75f7c14 (rubocop fixes + frozen bundle)
+
+## Motivation
+
+Three CI jobs (`validate:ci_yaml`, `validate:schemas`,
+`validate:version_consistency`) failed in the pipeline because `bundle install`
+attempted to build the `gobject-introspection` native extension. This gem is a
+transitive dependency of the `:desktop` Bundler group (`adwaita -> gtk4 -> ...
+-> gobject-introspection`) and requires `libgirepository1.0-dev`, which is not
+present in the `ruby:3.3.10-bookworm` Docker image.
+
+Additionally, `quality:rubocop` reported 15 new offenses from cops introduced
+in RuboCop 1.85.0. CI resolved this version because `Gemfile.lock` was not
+tracked, allowing Bundler to resolve `~> 1.82` to the latest available release.
+Local development used 1.84.2 (from the local lockfile), masking the offenses.
+
+## Root cause analysis
+
+| Symptom | Root cause |
+|---------|------------|
+| `gobject-introspection` build failure | `:desktop` group installed in CI where no job needs GTK4 |
+| 15 new rubocop offenses in CI only | `Gemfile.lock` untracked; CI resolved rubocop 1.85.0 vs local 1.84.2 |
+| Offenses not caught by pre-commit hook | Overcommit `RuboCop` hook only lints changed files |
+
+## Changes
+
+### 1. Exclude `:desktop` Bundler group in CI
+
+**File**: `.gitlab-ci-files/global/defaults.yml`
+
+Added to `.ruby_base` before_script:
+
+```yaml
+- bundle config set --local without 'desktop'
+```
+
+This prevents the GTK4 dependency chain from being resolved in CI. No CI job
+requires desktop gems.
+
+### 2. Track `Gemfile.lock` and freeze CI installs
+
+**Files**: `.gitignore`, `Gemfile.lock`, `.gitlab-ci-files/global/defaults.yml`
+
+- Removed `Gemfile.lock` from `.gitignore`
+- Committed `Gemfile.lock` with rubocop 1.85.0 pinned
+- Added `bundle config set --local frozen true` to `.ruby_base`
+
+CI now fails immediately if the lockfile diverges from the Gemfile, preventing
+silent version drift.
+
+### 3. Fix all 15 rubocop 1.85.0 offenses
+
+**Files**: 7 source files updated
+
+| Cop | Count | Fix |
+|-----|-------|-----|
+| `Style/RedundantStructKeywordInit` | 4 | Removed redundant `keyword_init: true` |
+| `Style/ReduceToHash` | 10 | Replaced `each_with_object({})` with `to_h { ... }` |
+| `Style/FileOpen` | 1 | Inline-disabled (intentional persistent handle with explicit cleanup) |
+
+### 4. Replace overcommit RuboCop with full-project RubocopAll
+
+**Files**: `.overcommit.yml`, `.git-hooks/pre_commit/rubocop_all.rb`
+
+Disabled the built-in `RuboCop` hook (which only lints changed files) and
+replaced it with a custom `RubocopAll` hook that scans all project files on
+every commit. This catches offenses from new cops or config changes regardless
+of what files are in the commit.
+
+## `.ruby_base` template (after changes)
+
+```yaml
+.ruby_base:
+  image: 'ruby:${RUBY_VERSION}-${DEBIAN_RELEASE}'
+  extends: .base
+  before_script:
+    - !reference [.base, before_script]
+    - ruby --version
+    - gem install bundler --no-document
+    - bundle config set --local path "$BUNDLE_PATH"
+    - bundle config set --local jobs "$BUNDLE_JOBS"
+    - bundle config set --local without 'desktop'
+    - bundle config set --local frozen true
+    - bundle install
+```
+
+## Verification
+
+- [x] `bundle exec rubocop` -- 0 offenses (245 files, rubocop 1.85.0)
+- [x] `bundle exec rspec` -- 1005 examples, 0 failures
+- [x] Overcommit `RubocopAll` hook passes (full-project scan)
+- [x] All pre-commit and commit-msg hooks pass
+
+## Files created
+
+| File | Purpose |
+|------|---------|
+| `doc/decisions/008-ci-bundler-strategy.md` | ADR documenting decisions |
+| `doc/changes/2026-03-01-ci-bundler-strategy.md` | This change document |
+| `.git-hooks/pre_commit/rubocop_all.rb` | Custom overcommit hook |
+
+## Files modified
+
+| File | Change |
+|------|--------|
+| `.gitlab-ci-files/global/defaults.yml` | Added `without 'desktop'` and `frozen true` |
+| `.gitignore` | Removed `Gemfile.lock` entry |
+| `.overcommit.yml` | Disabled `RuboCop`, added `RubocopAll` |
+| `lib/rosett_ai/compiler/compiled_output.rb` | Removed redundant `keyword_init: true` |
+| `lib/rosett_ai/config/compile_result.rb` | Removed redundant `keyword_init: true` |
+| `lib/rosett_ai/desktop/gui_logger.rb` | Inline-disabled `Style/FileOpen` |
+| `lib/rosett_ai/thor/tasks/build.rb` | Removed `keyword_init: true`, replaced `each_with_object` |
+| `lib/rosett_ai/thor/tasks/compile.rb` | Removed redundant `keyword_init: true` |
+| `spec/rosett_ai/yaml_loader_property_spec.rb` | Replaced `each_with_object` with `to_h` |
+| `spec/rosett_ai/yaml_loader_spec.rb` | Replaced `each_with_object` with `to_h` (7 instances) |

data/doc/changes/2026-03-20-security-hardening-phase2.md

@@ -0,0 +1,163 @@
+# Security Hardening Phase 2
+
+**Branch**: `security/hardening-phase2`
+**Date**: 2026-03-20
+**Authors**: hugo, claude
+
+## Motivation
+
+Following the initial security implementation (v1.1.0), this phase addresses
+remaining gaps identified in the security review:
+
+1. Supply chain integrity via Gemfile.lock checksums
+2. Advisory cops for dynamic dispatch patterns
+3. Thread safety analysis
+4. Enhanced content pack path traversal protection
+5. D-Bus rate limiting for DoS prevention
+
+## Changes
+
+### 1. Gemfile.lock Checksums
+
+Added SHA-256 checksums to all gems in Gemfile.lock:
+
+```bash
+bundle lock --add-checksums
+```
+
+This ensures that gem integrity is verified on every `bundle install`, protecting
+against supply chain attacks where a compromised RubyGems registry could serve
+tampered gem versions.
+
+### 2. Advisory Custom Cops
+
+Two new RuboCop cops added with severity `warning` (advisory, not blocking):
+
+#### RosettAi/UnsafeConstGet
+
+Flags `Object.const_get` and `constantize` with non-literal arguments:
+
+```ruby
+# flagged
+Object.const_get(user_input)
+class_name.constantize
+
+# allowed
+Object.const_get(:MyClass)
+REGISTRY.fetch(name)  # use frozen allowlist
+```
+
+**Exclusions**: RuboCop cop files (use `on_send` AST pattern)
+
+#### RosettAi/UnsafeSend
+
+Flags `send`, `public_send`, `__send__` with non-literal method names:
+
+```ruby
+# flagged
+object.send(method_name)
+
+# allowed
+object.send(:known_method)
+```
+
+**Exclusions**: GTK4 desktop code, Thor tasks (validated dispatch patterns)
+
+### 3. Thread Safety Analysis
+
+Added `rubocop-thread_safety` gem and enabled cops:
+
+- `ThreadSafety/InstanceVariableInClassMethod`
+- `ThreadSafety/ClassAndModuleAttributes`
+- `ThreadSafety/MutableClassInstanceVariable`
+
+This catches potential thread safety issues, especially relevant for the D-Bus
+service which uses threads for shutdown handling.
+
+### 4. Enhanced Content Pack Security
+
+Strengthened `PackInstaller#reject_traversal!` to reject:
+
+| Attack Vector | Check |
+|---------------|-------|
+| Parent traversal | `..` in path |
+| Absolute paths | Starts with `/` |
+| Home expansion | Starts with `~` |
+| Null byte injection | Contains `\x00` |
+
+Added canonical path verification in `extract_entry`:
+
+```ruby
+canonical_target = File.expand_path(target)
+canonical_dest = File.expand_path(dest_dir)
+unless canonical_target.start_with?(canonical_dest + '/')
+  raise RosettAi::ContentError, "Path escape rejected"
+end
+```
+
+### 5. D-Bus Rate Limiting
+
+Added `RosettAi::DBus::RateLimiter` using token bucket algorithm:
+
+| Operation | Rate | Burst |
+|-----------|------|-------|
+| Default | 10 req/s | 20 |
+| Compile | 2 req/s | 5 |
+| Config | 5 req/s | 10 |
+
+Rate limiting is applied to all ManagerInterface methods:
+
+- `Compile`
+- `SwitchContext`
+- `GetStatus`
+- `SetConfig`
+- `ListEngines`
+
+Exceeded limits raise D-Bus `LimitsExceeded` error.
+
+## Files Created
+
+| File | Purpose |
+|------|---------|
+| `lib/rubocop/cop/rosett-ai/unsafe_const_get.rb` | Advisory cop for const_get |
+| `lib/rubocop/cop/rosett-ai/unsafe_send.rb` | Advisory cop for send |
+| `lib/rosett_ai/dbus/rate_limiter.rb` | Token bucket rate limiter |
+| `spec/rubocop/cop/rosett-ai/unsafe_const_get_spec.rb` | Cop tests |
+| `spec/rubocop/cop/rosett-ai/unsafe_send_spec.rb` | Cop tests |
+| `spec/rosett_ai/dbus/rate_limiter_spec.rb` | Rate limiter tests |
+
+## Files Modified
+
+| File | Change |
+|------|--------|
+| `Gemfile` | Added rubocop-thread_safety |
+| `Gemfile.lock` | Added checksums, new gem |
+| `.rubocop.yml` | Thread safety plugin, new cop configuration |
+| `lib/rosett_ai/content/pack_installer.rb` | Enhanced path traversal checks |
+| `lib/rosett_ai/dbus/manager_interface.rb` | Rate limiting integration |
+| `spec/rosett_ai/content/pack_installer_spec.rb` | New path traversal tests |
+| `.claude/SECURITY_REVIEW.md` | Updated gap status |
+
+## Verification
+
+- [ ] `bundle exec rubocop` — 0 offenses
+- [ ] `bundle exec rspec` — all tests pass
+- [ ] `overcommit -r` — all hooks pass
+- [ ] `bundle exec bundler-audit check` — 0 vulnerabilities
+- [ ] `bundle exec ruby-audit check` — 0 vulnerabilities
+- [ ] Test-kitchen integration tests pass
+
+## Security Impact
+
+| Threat | Mitigation |
+|--------|------------|
+| Supply chain attack | Gemfile.lock checksums |
+| Arbitrary class instantiation | UnsafeConstGet cop (advisory) |
+| Arbitrary method execution | UnsafeSend cop (advisory) |
+| Thread safety bugs | rubocop-thread_safety |
+| Content pack zip slip | Enhanced path validation |
+| D-Bus DoS | Token bucket rate limiting |
+
+---
+
+Generated by security hardening session on 2026-03-20

data/doc/context/SESSION-HANDOFF.md

@@ -0,0 +1,69 @@
+# Session Handoff — Pluggable Engine Architecture
+
+**Date:** 2026-03-07
+**Status:** All phases COMPLETE — merged via MR
+
+---
+
+## Current State Summary
+
+### Pluggable Engine Architecture — COMPLETE
+
+All 6 phases of the pluggable engine architecture have been implemented:
+
+| Phase | Description | Status | Branch |
+|-------|-------------|--------|--------|
+| 1 | Plugin contracts + dynamic registry | Done | `feature/pluggable-engines` |
+| 2a | Extract Claude engine to separate gem | Done | `feature/pluggable-engines` |
+| 2b | Extract remaining 9 engines to gems | Done | `feature/pluggable-engines` |
+| 2c | Remove built-in engine code from core | Done | `feature/pluggable-engines` |
+| 3 | ACME example engine plugin | Done | `feature/acme-example-engine` |
+| 5-6 | Design doc + documentation updates | Done | `feature/acme-example-engine` |
+
+### Quality Gates (all pass)
+
+| Repository | RSpec | RuboCop | Reek | bundler-audit |
+|-----------|-------|---------|------|---------------|
+| rosett-ai core | 1285/0 (28 pending) | 224 files, 0 | 0 | 0 |
+| rosett-ai-engine-claude | 123/0 | 21 files, 0 | 0 | 0 |
+| rosett-ai-engine-generic | 21/0 | 10 files, 0 | 0 | 0 |
+| rosett-ai-engine-agents-md | 29/0 | 12 files, 0 | 0 | 0 |
+| rosett-ai-engine-acme | 27/0 | 12 files, 0 | 0 | 0 |
+| rosett-ai-engine-ollama | 39/0 | 14 files, 0 | 0 | 0 |
+| rosett-ai-engine-gpt-neox | 40/0 | 14 files, 0 | 0 | 0 |
+| rosett-ai-engine-goose | 46/0 | 14 files, 0 | 0 | 0 |
+| rosett-ai-engine-aider | 46/0 | 14 files, 0 | 0 | 0 |
+| rosett-ai-engine-cursor | 29/0 | 12 files, 0 | 0 | 0 |
+| rosett-ai-engine-copilot | 29/0 | 12 files, 0 | 0 | 0 |
+| rosett-ai-engine-windsurf | 29/0 | 12 files, 0 | 0 | 0 |
+| **Total** | **1743/0** | **0 offenses** | **0** | **0** |
+
+### External Gem Repositories
+
+| Gem | Location | Specs | Components |
+|-----|----------|-------|------------|
+| rosett-ai-engine-claude | `rosett-ai-engine-claude/` | 123 | backend, detector, executor, config_compiler, key_map, scope_router, domain_transformer |
+| rosett-ai-engine-generic | `rosett-ai-engine-generic/` | 21 | backend |
+| rosett-ai-engine-agents-md | `rosett-ai-engine-agents-md/` | 29 | backend, detector |
+| rosett-ai-engine-acme | `rosett-ai-engine-acme/` | 27 | backend, detector (example) |
+| rosett-ai-engine-ollama | `rosett-ai-engine-ollama/` | 39 | backend, detector, executor |
+| rosett-ai-engine-gpt-neox | `rosett-ai-engine-gpt-neox/` | 40 | backend, detector, executor |
+| rosett-ai-engine-goose | `rosett-ai-engine-goose/` | 46 | backend, detector, executor |
+| rosett-ai-engine-aider | `rosett-ai-engine-aider/` | 46 | backend, detector, executor |
+| rosett-ai-engine-cursor | `rosett-ai-engine-cursor/` | 29 | backend, detector |
+| rosett-ai-engine-copilot | `rosett-ai-engine-copilot/` | 29 | backend, detector |
+| rosett-ai-engine-windsurf | `rosett-ai-engine-windsurf/` | 29 | backend, detector |
+
+### Key Architecture Decisions
+
+- **Plugin types**: engine, gui, mcp (each with own contract module)
+- **Discovery**: `Gem.find_files('nncc_{engine,gui,mcp}/*/register.rb')`
+- **Namespace**: `RosettAiEngine::<Name>` in `lib/rosett_ai_engine/<name>/` (avoids Zeitwerk conflicts)
+- **Base classes in core**: `RosettAi::Compiler::Backend`, `RosettAi::Engines::Detector`, `RosettAi::Engines::BaseConfigCompiler`
+- **Self-registration**: Each gem's `register.rb` calls `RosettAi::Plugins::Registry.register(:engine, ...)`
+- **Deprecated aliases**: `RosettAi::Config::*` and `RosettAi::Compiler::Backends::*` point to `RosettAiEngine::*`
+- **GPL-3.0-only** on all repositories
+
+---
+
+*Last updated: 2026-03-07*

data/doc/context/ai-engine-usage-trends-2026.md

@@ -0,0 +1,80 @@
+# AI Engine Usage Trends — Market Research (2026)
+
+Compiled: 2026-03-22
+Context: NLnet grant research, validates ADR-006/ADR-007 multi-engine architecture
+
+## Summary
+
+Industry data confirms that multi-engine usage and engine switching are standard practice,
+not edge cases. rosett-ai's engine-agnostic architecture (ADR-007) is validated by market
+reality. The problem rosett-ai solves — portable human intent across AI engines — is now
+recognized industry-wide as "the new cloud vendor lock-in."
+
+## Key Statistics
+
+| Metric | Value | Source |
+|--------|-------|--------|
+| Developers using 3+ AI tools | 59% | Panto (2026) |
+| Developers using 5+ AI tools | 20% | Panto (2026) |
+| ChatGPT adoption | 82% | Stack Overflow (2025) |
+| GitHub Copilot adoption | 68% | Stack Overflow (2025) |
+| Daily AI tool usage | 51% | Stack Overflow (2025) |
+| Developers using/planning AI tools | 84% | Stack Overflow (2025) |
+| Positive sentiment (declining) | 60% (was 70%+) | Stack Overflow (2025) |
+| Confidence in AI code quality (6+ tools) | 28% | Panto (2026) |
+
+## Engine Migration Is Constant
+
+- **Claude Code**: zero to #1 most-used tool in 8 months (launched May 2025)
+- **Claude Code**: 46% "most loved" vs Cursor 19% vs Copilot 9%
+- **When switching**: ALL project configuration and context is lost
+- **Configuration portability**: does not exist between any two engines
+- Developers must "re-explain project conventions from scratch every session"
+
+### Implication for rosett-ai
+The human intent declarations in `conf/behaviour/*.yml`, `conf/design/*.yml`, and
+`conf/tooling/*.yml` survive engine migrations. A team that switches from Cursor to
+Claude Code runs `rai compile` and retains all governance. This is the core value
+proposition — validated by the data showing constant migration.
+
+## Vendor Lock-In Is a Recognized Strategic Risk
+
+- Framed as "the new cloud vendor lock-in of the AI era"
+- Each tool has proprietary config: CLAUDE.md, .cursorrules, .windsurfrules
+- AGENTS.md emerged (2025) as standardization attempt (OpenAI, Google, Cursor, Factory)
+- rosett-ai already supports AGENTS.md as a compilation target (ADR-007)
+
+### Implication for rosett-ai
+raictl is positioned ahead of the standardization curve. While AGENTS.md addresses format
+convergence for a subset of tools, rosett-ai treats ALL engines as compilation targets —
+including those that will never adopt AGENTS.md (Copilot, Ollama, GPT-NeoX).
+
+## Multi-Agent Trend (2026)
+
+- Gartner: 1,445% surge in multi-agent system inquiries (Q1 2024 → Q2 2025)
+- Trend: specialized teams of AI agents, not single assistants
+- GitHub Agent HQ (Feb 2026): run Claude, Codex, Copilot simultaneously
+- xAI Grok Build: up to 8 agents working simultaneously on different codebase parts
+
+### Implication for rosett-ai
+Validates the planned quorum proofing feature — parallel execution across engines for
+cross-validation. Also validates the need for consistent governance across agents that
+may be working simultaneously on the same codebase.
+
+## Sources
+
+- [AI Coding Statistics & Trends 2026 — Panto](https://www.getpanto.ai/blog/ai-coding-assistant-statistics)
+- [Stack Overflow 2025 Developer Survey](https://survey.stackoverflow.co/2025/)
+- [Stack Overflow Blog — Developers Remain Willing but Reluctant](https://stackoverflow.blog/2025/12/29/developers-remain-willing-but-reluctant-to-use-ai-the-2025-developer-survey-results-are-here/)
+- [Breaking Free from AI Vendor Lock-In — Medium](https://medium.com/@alexzanfir/breaking-free-from-ai-vendor-lock-in-the-case-for-system-agnostic-development-568fea21b3c8)
+- [AI Vendor Lock-In Trap 2025 — Fusion](https://tryfusion.ai/blog/the-2025-ai-vendor-lock-in-trap-and-how-to-build-your-exit)
+- [AI Vendor Lock-In Strategic Risk — Kellton](https://www.kellton.com/kellton-tech-blog/why-vendor-lock-in-is-riskier-in-genai-era-and-how-to-avoid-it)
+- [AI Vendor Lock-In — CTO Magazine](https://ctomagazine.com/ai-vendor-lock-in-cto-strategy/)
+- [DEV Community — AI Coding Assistants Comparison 2025](https://dev.to/_d7eb1c1703182e3ce1782/best-ai-coding-assistants-2025-claude-vs-copilot-vs-cursor-honest-comparison-4oh8)
+- [DEV Community — Claude Code vs Cursor vs Copilot 2026](https://dev.to/alexcloudstar/claude-code-vs-cursor-vs-github-copilot-the-2026-ai-coding-tool-showdown-53n4)
+- [Agentic Coding 2026 — Multi-Agent Teams](https://aiautomationglobal.com/blog/agentic-coding-revolution-multi-agent-teams-2026)
+- [State of AI Coding Agents 2026 — Medium](https://medium.com/@dave-patten/the-state-of-ai-coding-agents-2026-from-pair-programming-to-autonomous-ai-teams-b11f2b39232a)
+
+## Action Items
+
+See `doc/issues/004-market-research-design-updates.md` for follow-up tasks.