rosett-ai 1.3.3

data/doc/context/plan-pluggable-engines.md

@@ -0,0 +1,590 @@
+# Pluggable Engine Architecture + Config Adapters
+
+## Context
+
+raictl currently hardcodes 10 engines in two maps (`Registry.ENGINES` + `Backend.BACKENDS`). Every new engine or engine change requires modifying rosett-ai core. This is fragile — AI tools evolve rapidly and new ones emerge constantly.
+
+This plan extracts engines into **separate repositories** as individual gems (`rosett-ai-engine-<name>`) with a pluggable discovery system. Each engine gem owns its backend, detector, executor, config compiler, manifests, schemas, and specs. rosett-ai core provides the CLI, compilation pipeline, registry, and base classes.
+
+The pluggable architecture applies to **all plugin types** — not just engines. GUIs (desktop environments), MCP servers, and future plugin categories each get their own contract module, discovery mechanism, and separate repository. The naming convention `rosett-ai-<plugin-type>-<name>` covers:
+- `rosett-ai-engine-<name>` — AI engine plugins (claude, goose, aider, cursor, etc.)
+- `rosett-ai-gui-<name>` — Desktop GUI plugins (gtk4, qt6, etc.)
+- `rosett-ai-mcp-<name>` — MCP server plugins
+- Other future plugin types as needed
+
+Config adapters for Goose, Aider, Cursor, Ollama, GPT-NeoX, and a new Mistral engine are built using this pluggable pattern.
+
+---
+
+## Plan A: Pluggable Architecture + Engine Extraction
+
+**Branch**: `feature/pluggable-engines`
+
+### Phase 1: Plugin contracts + dynamic registry
+
+#### 1a. Plugin contract modules
+
+Create contract modules for each plugin type. Each contract defines the interface that plugin gems must implement.
+
+**Engine contract** — `lib/rosett_ai/plugins/engine_contract.rb`:
+
+```ruby
+module RosettAi::Plugins::EngineContract
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    def plugin_type          = :engine
+    def engine_name          = raise NotImplementedError
+    def display_name         = raise NotImplementedError
+    def backend_class        = raise NotImplementedError
+    def detector_class       = nil  # optional
+    def executor_class       = nil  # optional
+    def config_compiler_class = nil # optional
+    def manifest_path        = raise NotImplementedError
+  end
+end
+```
+
+**GUI contract** — `lib/rosett_ai/plugins/gui_contract.rb`:
+
+```ruby
+module RosettAi::Plugins::GuiContract
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    def plugin_type          = :gui
+    def gui_name             = raise NotImplementedError
+    def display_name         = raise NotImplementedError
+    def toolkit              = raise NotImplementedError  # :gtk4, :qt6, etc.
+    def application_class    = raise NotImplementedError
+    def dbus_interface_class = nil  # optional D-Bus integration
+  end
+end
+```
+
+**MCP contract** — `lib/rosett_ai/plugins/mcp_contract.rb`:
+
+```ruby
+module RosettAi::Plugins::McpContract
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    def plugin_type          = :mcp
+    def mcp_name             = raise NotImplementedError
+    def display_name         = raise NotImplementedError
+    def server_class         = raise NotImplementedError
+    def tool_definitions     = raise NotImplementedError  # MCP tool schema
+    def resource_definitions = []  # optional MCP resources
+  end
+end
+```
+
+**Base contract** — `lib/rosett_ai/plugins/contract.rb` (shared interface for all plugin types):
+
+```ruby
+module RosettAi::Plugins::Contract
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    def plugin_type = raise NotImplementedError
+    def plugin_name = raise NotImplementedError
+    def display_name = raise NotImplementedError
+    def version = raise NotImplementedError
+  end
+end
+```
+
+#### 1b. Dynamic registry (multi-type)
+
+Replace hardcoded `ENGINES` and `BACKENDS` maps with a multi-type registry supporting engines, GUIs, and MCPs:
+
+```ruby
+module RosettAi::Plugins
+  class Registry
+    PLUGIN_TYPES = %i[engine gui mcp].freeze
+    @plugins = Hash.new { |h, k| h[k] = {} }
+
+    def self.register(type, name, plugin_module)
+      raise ArgumentError unless PLUGIN_TYPES.include?(type)
+      @plugins[type][name.to_s] = plugin_module
+    end
+
+    def self.available(type) = @plugins[type].keys
+    def self.plugin_module(type, name) = @plugins[type].fetch(name.to_s) { raise ... }
+
+    # Convenience aliases
+    def self.engines = @plugins[:engine]
+    def self.guis    = @plugins[:gui]
+    def self.mcps    = @plugins[:mcp]
+
+    # Discovery: find and load all installed plugin gems
+    def self.discover!
+      Gem.find_files('rosett_ai_engine/*/register.rb').each { |f| require f }
+      Gem.find_files('rosett_ai_gui/*/register.rb').each   { |f| require f }
+      Gem.find_files('rosett_ai_mcp/*/register.rb').each   { |f| require f }
+    end
+  end
+end
+```
+
+Refactor `Backend.for` to delegate to `Registry.plugin_module(:engine, name).backend_class` instead of the hardcoded `BACKENDS` map.
+
+#### 1c. Base config compiler
+
+Extract shared compilation pipeline from `RosettAi::Engines::Claude::ConfigCompiler` into `lib/rosett_ai/engines/base_config_compiler.rb`:
+- `discover_scope_files`, `compile`, `compile_scope`, `write_results`
+- Schema validation via json_schemer
+- Secret resolution via shared `RosettAi::Config::SecretResolver`
+- `CompileResult` return type (already shared)
+
+Each engine overrides: `transform(data, scope)`, `output_format`, `scope_routes`, `schema_path`.
+
+#### 1d. Engine-aware CLI
+
+Update `lib/rosett_ai/thor/tasks/config.rb`:
+- Add `--engine` option with cascade lookup: config → autodetect → prompt
+- Cascade: configured default → autodetect (Claude preferred, then alphabetical) → ask user for binary/endpoint
+- Resolve to engine's `config_compiler_class` via Registry
+- Remove hardcoded `RosettAi::Config::Compiler` (Claude alias)
+
+Update `bin/raictl config show` to also display **plugged engines** — list all registered engine gems with version, capabilities, and detection status.
+
+**Files to create:**
+- `lib/rosett_ai/plugins/contract.rb` (base contract)
+- `lib/rosett_ai/plugins/engine_contract.rb`
+- `lib/rosett_ai/plugins/gui_contract.rb`
+- `lib/rosett_ai/plugins/mcp_contract.rb`
+- `lib/rosett_ai/plugins/registry.rb`
+- `lib/rosett_ai/engines/base_config_compiler.rb`
+- `spec/rosett_ai/plugins/contract_spec.rb`
+- `spec/rosett_ai/plugins/engine_contract_spec.rb`
+- `spec/rosett_ai/plugins/gui_contract_spec.rb`
+- `spec/rosett_ai/plugins/mcp_contract_spec.rb`
+- `spec/rosett_ai/plugins/registry_spec.rb`
+- `spec/rosett_ai/engines/base_config_compiler_spec.rb`
+
+**Files to modify:**
+- `lib/rosett_ai/engines/registry.rb` — delegate to `Plugins::Registry`, deprecation alias
+- `lib/rosett_ai/compiler/backend.rb` — delegate to `Plugins::Registry`, remove `BACKENDS`
+- `lib/rosett_ai/thor/tasks/config.rb` — `--engine` flag, cascade lookup, plugged engines display
+- `lib/rosett_ai/thor/tasks/compile.rb` — use Registry for engine resolution
+- `lib/rosett_ai/thor/tasks/engines.rb` — use dynamic Registry
+- `spec/rosett_ai/engines/registry_spec.rb` — update
+- `spec/rosett_ai/compiler/backend_spec.rb` — update
+- `spec/rosett_ai/thor/tasks/config_spec.rb` — update
+
+---
+
+### Phase 2: Engine extraction to separate repositories
+
+#### 2a. Repository structure
+
+Each engine is a **separate git repository** at:
+```
+~/git/Neatnerds/NNSD/NeatNerds-ai/rosett-ai-engine-<name>/
+```
+
+Plugin naming convention for all rosett-ai plugin types:
+```text
+~/git/Neatnerds/NNSD/NeatNerds-ai/rosett-ai-<plugin-type>-<name>/
+```
+
+Examples:
+```text
+~/git/Neatnerds/NNSD/NeatNerds-ai/rosett-ai-engine-claude/
+~/git/Neatnerds/NNSD/NeatNerds-ai/rosett-ai-engine-goose/
+~/git/Neatnerds/NNSD/NeatNerds-ai/rosett-ai-gui-gtk4/
+~/git/Neatnerds/NNSD/NeatNerds-ai/rosett-ai-gui-qt6/
+~/git/Neatnerds/NNSD/NeatNerds-ai/rosett-ai-mcp-server/
+```
+
+#### 2b. Per-engine repository layout
+
+```text
+rosett-ai-engine-claude/
+├── rosett-ai-engine-claude.gemspec
+├── .gitlab-ci.yml                 # Same quality gates as core
+├── .rubocop.yml
+├── .reek.yml
+├── .license_finder.yml            # License compliance config
+├── .mutant.yml                    # Mutation testing config
+├── Gemfile
+├── CHANGELOG.md
+├── LICENSE                        # GPL-3.0-only (MANDATORY)
+├── lib/
+│   └── rosett_ai_engine/
+│       └── claude/
+│           ├── register.rb        # self-registration entry point
+│           ├── engine.rb          # includes EngineContract, declares components
+│           ├── backend.rb
+│           ├── detector.rb
+│           ├── executor.rb
+│           ├── config_compiler.rb
+│           ├── key_map.rb
+│           ├── scope_router.rb
+│           └── domain_transformer.rb
+├── conf/
+│   ├── manifest.yml
+│   ├── target.yml
+│   ├── config/
+│   │   ├── managed.yml
+│   │   ├── user.yml
+│   │   ├── project.yml
+│   │   └── local.yml
+│   └── schemas/
+│       └── config_schema.json
+└── spec/
+    ├── spec_helper.rb
+    ├── backend_spec.rb
+    ├── config_compiler_spec.rb
+    ├── key_map_spec.rb
+    └── ...
+```
+
+#### 2c. Quality gates per plugin repository
+
+Each plugin repo MUST have the same CI quality gates as rosett-ai core:
+- RSpec (all specs pass, SimpleCov coverage)
+- RuboCop (zero offenses)
+- Reek (zero smells)
+- **Mutant** (mutation testing on critical subjects)
+- bundler-audit + ruby-audit
+- **license_finder** (license compliance — all deps must be GPL-3.0-compatible)
+- Schema validation (manifest, config schemas)
+- **GPL-3.0-only** license file in every repository
+
+Generated `.gitlab-ci.yml` per plugin repo, reusing CI templates where possible.
+
+#### 2d. Claude extraction first
+
+Extract Claude engine first — this is the most complex engine (7 components) and must work flawlessly before extracting others. Steps:
+
+1. Create `~/git/Neatnerds/NNSD/NeatNerds-ai/rosett-ai-engine-claude/`
+2. Move `lib/rosett_ai/engines/claude/*.rb` → `lib/rosett_ai_engine/claude/`
+3. Move `conf/engines/claude/` → `conf/`
+4. Move `spec/rosett_ai/engines/claude/` → `spec/`
+5. Create gemspec, register.rb, engine.rb
+6. Set up CI pipeline with quality gates
+7. Verify all specs pass independently
+8. Update rosett-ai core Gemfile to reference via `path:` or git URL
+9. Verify full rosett-ai suite still passes
+
+Then extract remaining engines in order: generic, agents_md, goose, aider, cursor, copilot, windsurf, ollama, gpt_neox.
+
+#### 2e. GUI + MCP extraction
+
+After engine extraction is validated, extract GUI and MCP plugins:
+
+1. `rosett-ai-gui-gtk4/` — extract `lib/rosett_ai/desktop/gtk4/` + D-Bus adapters into `lib/rosett_ai_gui/gtk4/`
+2. `rosett-ai-gui-qt6/` — placeholder for future KDE/Qt6 desktop (currently deferred)
+3. `rosett-ai-mcp-server/` — extract `lib/rosett_ai/mcp/` into `lib/rosett_ai_mcp/server/`
+
+Each follows the same pattern: own repo, own gemspec, own CI, GPL-3.0-only, contract module inclusion, self-registration via `register.rb`.
+
+#### 2f. Core cleanup
+
+Remove from rosett-ai core after all extractions:
+- `lib/rosett_ai/engines/` (except `registry.rb`, `detector.rb`, `base_config_compiler.rb`)
+- `lib/rosett_ai/desktop/` (moved to gui plugins)
+- `lib/rosett_ai/mcp/` (moved to mcp plugins)
+- `conf/engines/` (except `conf/schemas/engine_manifest_schema.json`)
+- Engine/GUI/MCP-specific specs
+
+Retain in core:
+- `lib/rosett_ai/plugins/` (contract modules + registry)
+- `lib/rosett_ai/engines/base_config_compiler.rb`
+- Shared modules: `CompileResult`, `SecretResolver`, `CapabilityChecker`
+
+Update rosett-ai core Gemfile to reference all plugin gems.
+
+---
+
+### Phase 3: Example dummy plugins (ACME)
+
+A true pluggable architecture must include example plugins so end users can understand the contract between core and plugin. ACME examples cover **all plugin types** to demonstrate each contract.
+
+#### 3a. ACME example engine
+
+Create `rosett-ai-engine-acme` — an inert example engine plugin:
+
+**Placeholder organization**: ACME Corp (`acme-corp.tld`)
+- Example users: alice, bob, goku, Haru Urara, Momonga
+- Example roles: admin, developer, manager, analyst, hr, creator, student
+
+The ACME engine:
+- Includes `EngineContract` with all required methods
+- Backend renders a no-op output (e.g., `# ACME engine — no output`)
+- Detector always returns `detected: false`
+- Config compiler demonstrates the full pipeline with example settings
+- Has example config YAML with ACME-specific settings (using ACME users/roles)
+- Has example manifest declaring capabilities
+- **Tests exist and achieve minimal code coverage** (even though the engine is inert)
+- Extensive inline comments explaining each contract method and what it does
+- GPL-3.0-only license, mutant config, license_finder config
+
+#### 3b. ACME example GUI (optional, deferred until GUI extraction)
+
+Create `rosett-ai-gui-acme` — an inert example GUI plugin:
+- Includes `GuiContract` with all required methods
+- Application class returns immediately (no actual window)
+- Demonstrates how a GUI plugin registers and interfaces with core
+
+#### 3c. ACME example MCP (optional, deferred until MCP extraction)
+
+Create `rosett-ai-mcp-acme` — an inert example MCP plugin:
+- Includes `McpContract` with all required methods
+- Server class responds with dummy tool definitions
+- Demonstrates how an MCP plugin registers and interfaces with core
+
+#### 3d. ACME documentation focus
+
+The ACME plugins are **declarative and educational**:
+- Every file has comments explaining why it exists and what it fulfills
+- `README.md` walks through creating a plugin from scratch
+- Shows how to register, how discovery works, how manifests are validated
+- References the contract module and base classes in rosett-ai core
+- Documents the differences between engine, GUI, and MCP contracts
+
+---
+
+### Phase 4: Config adapters (using pluggable pattern)
+
+Each adapter follows the same pattern — engine gem adds `config_compiler.rb`, `key_map.rb`, scope YAML, and schema.
+
+#### 4a. Goose config adapter
+
+- **Output**: `~/.config/goose/config.yaml` (YAML)
+- **Settings**: provider, model, temperature, max_tokens, mode, max_turns, security, planner
+- **Scopes**: user only
+
+#### 4b. Aider config adapter
+
+- **Output**: `~/.aider.conf.yml` (user) + `./.aider.conf.yml` (project)
+- **Settings**: model, weak-model, editor-model, edit-format, API keys (secret refs), auto-commits, lint-cmd, test-cmd, dark-mode, stream, cache-prompts, reasoning-effort
+- **Scopes**: user + project
+
+#### 4c. Cursor config adapter
+
+- **Output**: `.cursor/settings.json` (JSON)
+- **Settings**: API keys (secret refs), model selection, custom endpoints, MCP servers
+- **Scopes**: project only
+
+#### 4d. Ollama config adapter
+
+- **Output**: Modelfile (text) + env var config
+- **Settings**: FROM (model), PARAMETER temperature/top_k/top_p, SYSTEM prompt, OLLAMA_HOST
+- **Scopes**: user only
+
+#### 4e. GPT-NeoX (vLLM) config adapter
+
+- **Output**: `config.yaml` for `vllm serve --config`
+- **Settings**: model, host, port, gpu-memory-utilization, max-model-len
+- **Scopes**: user only
+
+#### 4f. Mistral engine (new)
+
+Entirely new engine gem `rosett-ai-engine-mistral`:
+- Backend: compile behaviour YAML to Mistral instruction format
+- Detector: check `mistral` CLI binary or `MISTRAL_API_KEY` env var
+- Config adapter: API key (secret ref), model, endpoint, temperature
+- Manifest + target profile
+- Scopes: user only
+
+---
+
+### Phase 5: Design document updates
+
+#### 5a. Update existing design documents
+
+All existing design documents in `conf/design/` must be updated to reflect the pluggable architecture:
+- `engine_architecture.yml` — pluggable discovery, contract modules (engine + GUI + MCP), gem-based plugins
+- `compiler.yml` — base config compiler, engine-aware pipeline
+- `testing.yml` — per-plugin gem testing strategy (including mutant)
+- `distribution.yml` — per-plugin gem packaging, license_finder requirement
+- `architecture.yml` — updated system overview with multi-type plugin system
+- `desktop_integration.yml` — GUI contract module, gui plugin extraction
+- `mcp_integration.yml` — MCP contract module, mcp plugin extraction
+- Others as applicable
+
+#### 5b. Categorize design documents
+
+Design documents should be categorized by topic and purpose:
+- **Core architecture**: architecture, compiler, engine_architecture
+- **Security & quality**: security, testing, ci_pipeline
+- **Distribution**: distribution, release_management, version_management, lifecycle_management
+- **User interface**: ui_framework, accessibility, desktop_integration, styles
+- **Integrations**: mcp_integration, aaif_alignment, content_packs
+- **Operations**: monitoring_observability, usage_optimization
+- **Configuration**: claude_code_configuration, i18n
+- **Business**: licensing_system, documentation
+
+---
+
+### Phase 6: Documentation
+
+Documentation about the pluggable architecture is of **extreme importance**.
+
+- Update `doc/ARCHITECTURE.md` — pluggable engine diagrams, gem discovery flow
+- Update `doc/ENGINES.md` — per-engine config adapter docs, how plugins work
+- Update `doc/man/rai.1.ronn` — `config compile --engine`, `config show` plugged engines
+- Update `CONTRIBUTING.md` — "How to create an engine gem" guide (reference ACME example)
+- Update `INSTALL.md` — how to install engine gems
+- Update `CHANGELOG.md`
+- Update `doc/IMPLEMENTATION_PLAN.md` — new phases, engine delivery matrix
+- Full quality gate
+
+---
+
+## Key design decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Separate git repositories per plugin | Engines, GUIs, MCPs, and future plugin types each get full independence, own CI, own versioning |
+| `Gem.find_files('nncc_{engine,gui,mcp}/*/register.rb')` discovery | No config needed; install gem = available |
+| Namespaced dirs (`rosett_ai_engine/`, `rosett_ai_gui/`, `rosett_ai_mcp/`) | **Default approach** — avoids Zeitwerk root dir overlap with core gem |
+| Contract modules per plugin type | Engine, GUI, and MCP contracts define type-specific interfaces |
+| Base contract shared across all types | Common `plugin_type`, `plugin_name`, `display_name`, `version` |
+| Plugin gemspec `metadata['nncc_plugin_type']` | Enables `gem search` filtering by type |
+| Base config compiler in core | Shared pipeline logic, engines only override transforms |
+| `CompileResult` + `SecretResolver` stay in core | Shared across all plugins |
+| ACME example plugin | Teaches the contract without requiring real AI tool knowledge |
+| Claude extracted first | Most complex engine; validates the pattern |
+| GPL-3.0-only on ALL repositories | Uniform licensing across core and all plugin repos |
+| Mutant in every repo's CI | Mutation testing ensures real test coverage quality |
+| license_finder in every repo | Ensures all dependencies are GPL-3.0-compatible |
+
+## Risk areas
+
+| Risk | Mitigation |
+|------|-----------|
+| Zeitwerk root dir conflicts | **Namespacing is the default**: `rosett_ai_engine/`, `rosett_ai_gui/`, `rosett_ai_mcp/` — never overlap with core's `rosett-ai/` autoload root |
+| Gem discovery order | Registry sorts alphabetically; Claude preferred via config default |
+| Breaking existing specs | Claude extraction must be flawless before others |
+| Deprecation aliases | Keep `RosettAi::Config::Compiler` etc. for one release cycle |
+| CI complexity | Each plugin repo has own CI; core CI tests with all plugins installed |
+| License compatibility | license_finder enforced in CI — blocks merges with incompatible deps |
+| Contract drift across types | Base contract module ensures common interface; type-specific contracts extend it |
+| GUI/MCP contracts not yet battle-tested | Engine contract validated first via Claude extraction; GUI/MCP contracts refined during extraction |
+
+---
+
+## Plan B: Building/Packaging Fixes (separate plan, after Plan A)
+
+**Branch**: `fix/packaging-v1`
+
+Addresses three documented issues at `doc/issues/`:
+
+### Issue 001: Wrapper script missing LD_LIBRARY_PATH and RUBYLIB
+
+- **Severity**: Critical (application fails to launch)
+- **Fix**: Update `packaging/wrapper.sh` to set `LD_LIBRARY_PATH`, `RUBYLIB`, and hardcode `GEM_HOME` (or use ERB template at build time to avoid chicken-and-egg `ruby -e` call)
+- **Files**: `packaging/wrapper.sh` (or new `packaging/wrapper.sh.erb`), `lib/rosett_ai/thor/tasks/build.rb`
+
+### Issue 002: Embedded Ruby compiled with wrong --prefix
+
+- **Severity**: High (makes Issue 001 workarounds necessary)
+- **Root cause**: CI Docker pre-seeding copies `/usr/local/` Ruby (prefix `/usr/local`) to `/opt/rosett-ai/embedded/`; local builds use staging absolute path as prefix
+- **Fix**: Option A+C — compile Ruby with `RUBY_CONFIGURE_OPTS="--prefix=/opt/rosett-ai/embedded"` in both CI and local builds; update `ruby_already_compiled?` to verify prefix
+- **Files**: `.gitlab-ci-files/build/package.yml`, `lib/rosett_ai/thor/tasks/build.rb`
+
+### Issue 003: Smoke test may produce false positives
+
+- **Severity**: Medium (test reliability)
+- **Root cause**: Smoke test installs system Ruby (`apt-get install ruby`) before testing the package, masking missing deps
+- **Fix**: Remove `apt-get install ruby` from smoke test; test package in isolation on clean `debian:bookworm`; add `readelf` and `RbConfig::CONFIG["prefix"]` assertions
+- **Files**: `.gitlab-ci-files/build/package.yml`
+
+---
+
+## Plan C: Test Kitchen Integration (separate plan, after Plan A)
+
+**Branch**: `feature/test-kitchen`
+
+Imperative for fully testing the pluggable architecture in realistic deployment scenarios.
+
+### Overview
+
+Implement test-kitchen for integration testing of rosett-ai packages and plugin architecture.
+
+### InSpec via neatspec
+
+For compliance/verification profiles, use the **neatspec** project:
+- Location: `~/git/Neatnerds/NNSD/InSpec/neatspec`
+- Wraps `cinc-auditor` gem
+- Provides reusable profiles, role-based compliance, hierarchical data management
+
+### Scope
+
+- Kitchen configuration for testing .deb package installation on clean Debian
+- Verify wrapper script, embedded Ruby prefix, and `$LOAD_PATH`
+- Verify plugin discovery works with installed engine gems
+- Verify `bin/raictl` commands work after package install
+- neatspec profiles for rosett-ai compliance (file permissions, paths, service health)
+- Design document for test-kitchen exists or will be created in `conf/design/`
+
+---
+
+## Verification (Plan A)
+
+After Phase 1:
+```bash
+bundle exec rspec spec/rosett_ai/plugins/registry_spec.rb
+bundle exec rspec spec/rosett_ai/plugins/contract_spec.rb
+bundle exec rspec spec/rosett_ai/plugins/engine_contract_spec.rb
+bundle exec rspec spec/rosett_ai/plugins/gui_contract_spec.rb
+bundle exec rspec spec/rosett_ai/plugins/mcp_contract_spec.rb
+bundle exec rspec spec/rosett_ai/engines/base_config_compiler_spec.rb
+```
+
+After Phase 2 (per engine repo):
+```bash
+cd ~/git/Neatnerds/NNSD/NeatNerds-ai/rosett-ai-engine-claude && bundle exec rspec
+# ... repeat for each engine
+bundle exec rspec  # full suite from rosett-ai core
+```
+
+After Phase 3:
+```bash
+cd ~/git/Neatnerds/NNSD/NeatNerds-ai/rosett-ai-engine-acme && bundle exec rspec
+```
+
+After Phase 4:
+```bash
+bin/raictl config compile --engine goose --simulate --verbose
+bin/raictl config compile --engine aider --simulate --verbose
+bin/raictl config compile --engine cursor --simulate --verbose
+bin/raictl config compile --engine ollama --simulate --verbose
+bin/raictl config compile --engine gpt_neox --simulate --verbose
+bin/raictl config compile --engine mistral --simulate --verbose
+```
+
+Final (per-repo):
+```bash
+bundle exec rspec                    # All specs pass
+bundle exec rubocop                  # Clean
+bundle exec reek                     # Clean
+bundle exec mutant run               # Mutation score tracked
+bundle exec bundler-audit check      # No vulns
+bundle exec license_finder           # All deps GPL-3.0-compatible
+```
+
+Final (rosett-ai core with all plugins):
+```bash
+bundle exec rspec                    # All specs pass (including plugin integration)
+bundle exec rubocop                  # Clean
+bundle exec reek                     # Clean
+bundle exec mutant run               # Mutation score tracked
+bundle exec bundler-audit check      # No vulns
+bundle exec license_finder           # All deps GPL-3.0-compatible
+bin/raictl validate                    # All config valid
+bin/raictl engines list                # 12 engines (10 real + acme + mistral)
+bin/raictl config show                 # Shows plugged engines + GUIs + MCPs
+```

data/doc/decisions/001-flog-deferred.md

@@ -0,0 +1,32 @@
+# ADR-001: Flog Deferred from Lifecycle Verification Suite
+
+## Status
+
+Accepted (2026-02-20)
+
+## Context
+
+The lifecycle_management.yml design document (criterion 4) originally required
+RuboCop, Reek, Flay, **and Flog** to run without regressions after every upgrade.
+
+Flog measures method complexity using an ABC-based scoring algorithm. However,
+RuboCop already enforces method complexity through two Metrics cops:
+
+- `Metrics/CyclomaticComplexity` (default max: 7)
+- `Metrics/PerceivedComplexity` (default max: 8)
+
+These cops cover the same concern as Flog (identifying overly complex methods)
+and are already enforced in CI and pre-commit hooks.
+
+## Decision
+
+Defer Flog from the lifecycle verification suite. The complexity concern it
+addresses is already covered by RuboCop Metrics cops that are active in the
+project's CI pipeline and pre-commit configuration.
+
+## Consequences
+
+- One fewer tool to install and run in the verification pipeline
+- Complexity enforcement remains via RuboCop (already mandatory)
+- If RuboCop Metrics cops are ever disabled or relaxed, revisit this decision
+  and consider re-introducing Flog as a standalone check