rosett-ai 1.3.3

data/doc/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,669 @@
+# Rosett-AI v1.0.0 Implementation Plan
+
+Engine-agnostic architecture pivot and desktop integration.
+
+Decisions captured in: `doc/decisions/007-engine-agnostic-pivot.md`
+Design document: `conf/design/engine_architecture.yml`
+Conversation transcript: `2026-02-26 Q&A session (9 questions, all resolved)`
+
+Last updated: 2026-03-05 (v1.0.0 tagged)
+
+---
+
+## Table of Contents
+
+1. [Decision Summary](#1-decision-summary)
+2. [Progress Overview](#2-progress-overview)
+3. [Dependency Graph](#3-dependency-graph)
+4. [Phase Details](#4-phase-details)
+5. [Branch Naming Convention](#5-branch-naming-convention)
+6. [Engine Architecture Diagram](#6-engine-architecture-diagram)
+7. [Layer Separation Diagram](#7-layer-separation-diagram)
+8. [Manual Tasks](#8-manual-tasks)
+
+---
+
+## 1. Decision Summary
+
+| # | Topic | Decision |
+|---|-------|---------|
+| Q1 | Naming | "Rosett-AI" (keep `rosett-ai` acronym) |
+| Q2 | Generic layer | Strict separation; capability manifests with compile-time warnings |
+| Q3 | Engine architecture | Option C: engine-as-namespace-directory, optional components |
+| Q4 | Config compilation | Moves inside each engine; `--target` → `--engine`; configurable default; autodetection; quorum as separate module |
+| Q5 | Output paths | XDG-compliant (`~/.config/rosett-ai/`); engines deploy to tool-native paths |
+| Q6 | Adopt system | Local-only default; `--api` opt-in; quorum-capable; anthropic gem out of core |
+| Q7 | Scope & phasing | 5 phases: restructure → AGENTS.md → Ollama+GPT-NeoX → Goose+Aider → Cursor+Copilot+Windsurf |
+| Q8 | Migration | Incremental (3 sub-phases for Phase 0); version 1.0.0 |
+| Q9 | Desktop priority | Engine Phase 0 first, then Desktop Phase 1 immediately after; parallel thereafter |
+| Q10 | KDE KCM | Deferred indefinitely — C++/QML complexity outside Ruby stack |
+| Q11 | Goose/Aider executors | Folded into Engine Phase 4 alongside Cursor/Copilot/Windsurf |
+| Q12 | GlobalShortcuts | Remains in Desktop Phase 1 scope as known gap |
+
+---
+
+## 2. Progress Overview
+
+### Completed Phases
+
+| Phase | Branch | Merged | Specs |
+|-------|--------|--------|-------|
+| Engine 0a — Rename + v1.0.0 | `engine/0a-rename-code-companion` | 2026-02-26 | 251 |
+| Engine 0b — Engine directories | `engine/0b-engine-directories` | 2026-02-26 | 966 |
+| Engine 0c — XDG + --engine + detectors | `engine/0c-xdg-engine-flag-detectors` | 2026-02-26 | 1017 |
+| Desktop 1 — D-Bus service | `desktop/1-dbus-service` | 2026-02-27 | ~1030 |
+| Engine 1 — AGENTS.md | `engine/1-agents-md` | 2026-02-27 | 1061 |
+| Desktop 2 — GTK4 app | `desktop/2-gtk4-app` | 2026-02-27 | ~1080 |
+| Engine 2 — Ollama + GPT-NeoX | `engine/2-ollama-gpt-neox` | 2026-02-27 | ~1100 |
+| Engine 3 — Goose + Aider (compilation) | `engine/3-goose-aider` | 2026-02-28 | ~1200 |
+| Consistency review | `refactor/consistency-review` | 2026-02-28 | 1382 |
+| Engine 4 — Cursor + Copilot + Windsurf + executors | `engine/4-cursor-copilot-windsurf` | 2026-03-02 | 1491 |
+| v1.0.0 Release prep | `release/v1.0.0-core` | 2026-03-04 | 1574 |
+
+### v1.0.0 Release Phases (2026-03-04)
+
+| Phase | Branch | Scope |
+|-------|--------|-------|
+| Design | `design/operations-monitoring-optimization` | Operations domain, monitoring + optimization design docs |
+| Test Quality | `test/quality-baseline` | SimpleCov thresholds, fixtures, Mutant subject expansion |
+| CI Pipeline | `ci/release-pipeline` | Validation includes, core-only rspec, smoke test, release-cli pin |
+| Documentation | `docs/v1-release-polish` | Man page, USAGE.md, ADR-009, INSTALL, CONTRIBUTING, REFERENCES |
+| Release Prep | `release/v1.0.0-core` | Core-only gemspec, Zeitwerk ignore, desktop graceful degradation, CHANGELOG |
+| Final | `chore/v1-release-final` | Security scan hardening, AI provenance, quality gate, tag |
+
+### Backfill Branches (all merged)
+
+| Branch | Scope |
+|--------|-------|
+| `backfill/executor-normalize` | Executor interface normalization |
+| `backfill/capability-checker` | Compile-time capability warnings |
+| `backfill/quorum-module` | Quorum dispatcher, collector, comparator |
+| `backfill/dbus-desktop` | D-Bus stop, StatusNotifierItem, GTK4 preferences |
+| `documentation` | 40 Mermaid diagrams across doc/ |
+
+### Engine Delivery Matrix
+
+| Engine | Backend | Detector | Executor | Config Adapter | Quorum |
+|--------|---------|----------|----------|----------------|--------|
+| Claude | done | done | done | done | done |
+| Generic | done | N/A | N/A | N/A | N/A |
+| AGENTS.md | done | done | N/A | N/A | N/A |
+| Ollama | done | done | done | N/A | done |
+| GPT-NeoX | done | done | done | N/A | done |
+| Goose | done | done | done | N/A | done |
+| Aider | done | done | done | N/A | done |
+| Cursor | done | done | N/A | N/A | N/A |
+| Copilot | done | done | N/A | N/A | N/A |
+| Windsurf | done | done | N/A | N/A | N/A |
+
+### Remaining Work
+
+| Phase | Status | Risk | Priority |
+|-------|--------|------|----------|
+| Desktop 1 — GlobalShortcuts gap | Known gap | Low | When needed |
+| Desktop 3 — KDE KCM | **Deferred indefinitely** | High | Low |
+
+---
+
+## 3. Dependency Graph
+
+```mermaid
+graph TD
+    E0a["Engine 0a<br/>Rename + v1.0.0<br/>&#9745; DONE"]
+    E0b["Engine 0b<br/>engines/ structure<br/>&#9745; DONE"]
+    E0c["Engine 0c<br/>XDG + --engine + detectors<br/>&#9745; DONE"]
+    D1["Desktop 1<br/>D-Bus service<br/>&#9745; DONE (1 gap)"]
+    E1["Engine 1<br/>AGENTS.md<br/>&#9745; DONE"]
+    D2["Desktop 2<br/>GTK4 app<br/>&#9745; DONE"]
+    E2["Engine 2<br/>Ollama + GPT-NeoX<br/>&#9745; DONE"]
+    E3["Engine 3<br/>Goose + Aider (compile)<br/>&#9745; DONE"]
+    E4["Engine 4<br/>Cursor + Copilot + Windsurf<br/>+ Goose/Aider executors<br/>&#9745; DONE"]
+    REL["v1.0.0 Release<br/>Core-only split<br/>&#9745; DONE"]
+    D3["Desktop 3<br/>KDE KCM<br/>DEFERRED"]
+
+    E0a --> E0b
+    E0b --> E0c
+    E0c --> D1
+    E0c --> E1
+    D1 --> D2
+    E1 --> E2
+    E2 --> E3
+    E3 --> E4
+    E4 --> REL
+
+    style E0a fill:#2ecc71,stroke:#333,color:#000
+    style E0b fill:#2ecc71,stroke:#333,color:#000
+    style E0c fill:#2ecc71,stroke:#333,color:#000
+    style D1 fill:#2ecc71,stroke:#333,color:#000
+    style D2 fill:#2ecc71,stroke:#333,color:#000
+    style E1 fill:#2ecc71,stroke:#333,color:#000
+    style E2 fill:#2ecc71,stroke:#333,color:#000
+    style E3 fill:#2ecc71,stroke:#333,color:#000
+    style E4 fill:#2ecc71,stroke:#333,color:#000
+    style D3 fill:#95a5a6,stroke:#333,color:#000
+```
+
+Legend:
+
+- Green: Completed
+- Grey: Deferred indefinitely
+
+---
+
+## 4. Phase Details
+
+### Engine Phase 0a — Rename + Version Bump
+
+| Field | Value |
+|-------|-------|
+| Branch | `engine/0a-rename-code-companion` |
+| Status | **DONE** — merged to main |
+| Tests | 251 examples, 0 failures |
+
+**Scope**:
+
+- [x] `rosett-ai.gemspec`: summary → "Rosett-AI", description updated
+- [x] `CLAUDE.md`: header and overview table
+- [x] `CONTRIBUTING.md`: header
+- [x] `INSTALL.md`: header and references (no occurrences found)
+- [x] `doc/*.md`: all "Claude Companion" → "Code Companion" references
+- [x] `locales/en.yml`, `locales/fr.yml`, `locales/ar.yml`: product name strings (no occurrences found)
+- [x] `lib/rosett_ai/version.rb`: bump to `1.0.0`
+- [x] `CHANGELOG.md`: v1.0.0 entry
+- [x] All CLI `desc` strings in `lib/rosett_ai/thor/tasks/*.rb` and `lib/rosett_ai/thor/cli.rb`
+- [x] `cliff.toml`: header text
+
+---
+
+### Engine Phase 0b — Create Engine Directory Structure
+
+| Field | Value |
+|-------|-------|
+| Branch | `engine/0b-engine-directories` |
+| Status | **DONE** — merged to main |
+| Tests | 966 examples, 0 failures |
+
+**Scope**:
+
+- [x] Create `lib/rosett_ai/engines/` directory
+- [x] Create `lib/rosett_ai/engines/claude/` with:
+  - `backend.rb` (moved from `lib/rosett_ai/compiler/backends/claude_backend.rb`)
+  - `config_compiler.rb` (moved from `lib/rosett_ai/config/compiler.rb`)
+  - `key_map.rb` (moved from `lib/rosett_ai/config/key_map.rb`)
+  - `scope_router.rb` (moved from `lib/rosett_ai/config/scope_router.rb`)
+  - `domain_transformer.rb` (moved from `lib/rosett_ai/config/domain_transformer.rb`)
+  - `executor.rb` (extracted from `lib/rosett_ai/adopter/rule_adopter.rb` Anthropic API code)
+- [x] Create `lib/rosett_ai/engines/generic/` with:
+  - `backend.rb` (moved from `lib/rosett_ai/compiler/backends/generic_backend.rb`)
+- [x] Create `conf/engines/claude/manifest.yml` and `conf/engines/generic/manifest.yml`
+- [x] Create `lib/rosett_ai/engines/registry.rb` (engine discovery from directories)
+- [x] Update `lib/rosett_ai/compiler/backend.rb` to delegate to engines
+- [x] Move `anthropic` gem from core `rosett-ai.gemspec` to `Gemfile` engines group
+- [x] Update all `require` paths (Zeitwerk handles autoload automatically)
+- [x] Move `conf/claude_code/*.yml` → `conf/engines/claude/config/`
+- [x] Move `conf/schemas/claude_code_config_schema.json` → `conf/engines/claude/schemas/config_schema.json`
+- [x] Move `conf/targets/claude.yml` → `conf/engines/claude/target.yml`
+- [x] Move `conf/targets/generic.yml` → `conf/engines/generic/target.yml`
+- [x] Keep backward-compatible aliases for one release cycle (deprecated, remove in v1.1.0)
+- [x] Update all specs to new paths
+
+---
+
+### Engine Phase 0c — XDG Paths + --engine Flag + Detectors
+
+| Field | Value |
+|-------|-------|
+| Branch | `engine/0c-xdg-engine-flag-detectors` |
+| Status | **DONE** — merged to main |
+| Tests | 1017 examples, 0 failures |
+
+**Scope**:
+
+- [x] Update `PathResolver` to use XDG paths (`~/.config/rosett-ai/`) as rosett-ai home
+- [x] Engine-specific path resolution delegates to each engine's `path_resolver.rb`
+- [x] Rename `--target` to `--engine` in `lib/rosett_ai/thor/tasks/compile.rb`
+- [x] Keep `--target` as deprecated alias (emit warning, remove in v1.1.0)
+- [x] Create engine detector framework:
+  - `lib/rosett_ai/engines/detector.rb` (base class, reads manifest detection rules)
+  - `lib/rosett_ai/engines/claude/detector.rb` (checks `which claude`, `~/.claude/` exists)
+- [x] Create `bin/raictl engines` CLI subcommand:
+  - `engines list` — show all known engines
+  - `engines detect` — probe system, report installed tools
+  - `engines status` — detected + configured + default
+- [x] Create `~/.config/rosett-ai/config.yml` schema and loader (default engine, etc.)
+- [x] Update `bin/raictl init` to suggest default engine based on autodetection
+- [x] Update adopt to default to `--local` (remove Anthropic API as default path)
+- [x] Add `--api` flag to adopt, wire to engine executor
+- [x] Add `--strict` flag to compile (warnings → errors)
+- [x] Create `conf/schemas/engine_manifest_schema.json` for manifest validation
+- [x] Update CLAUDE.md CLI Usage section
+- [x] Update man page `doc/man/rai.1.ronn`
+
+---
+
+### Desktop Phase 1 — D-Bus Service Foundation
+
+| Field | Value |
+|-------|-------|
+| Branch | `desktop/1-dbus-service` |
+| Status | **DONE** — merged to main (1 known gap: GlobalShortcuts) |
+| Tests | D-Bus service specs, integration tests with dbus-daemon |
+
+**Scope**: As defined in `conf/design/desktop_integration.yml` Phase 1:
+
+- [x] `be.neatnerds.rosettai` D-Bus session bus service (ruby-dbus)
+- [x] `be.neatnerds.rosettai.Manager` interface (Compile, SwitchContext, GetStatus, Shutdown, SetConfig, Version, ListEngines)
+- [x] `be.neatnerds.rosettai.FocusMonitor` interface (GetCurrentFocus, FocusChanged signal)
+- [x] StatusNotifierItem for system tray (`org.kde.StatusNotifierItem`)
+- [x] FocusMonitor with compositor adapters (GNOME, KWin, sway, i3, Hyprland, X11)
+- [ ] GlobalShortcuts portal registration (XDG portal `org.freedesktop.portal.GlobalShortcuts`) — **known gap, to be addressed**
+- [x] CLI: `bin/raictl dbus start` to start service
+- [x] CLI: `bin/raictl dbus stop` to stop service
+- [x] CLI: `bin/raictl dbus status` to check service state
+- [x] D-Bus service auto-activation `.service` file
+- [x] Introspection XML for all interfaces
+- [x] Graceful degradation if D-Bus session bus unavailable
+- [x] Engine selector: Manager.Compile accepts engine parameter
+- [x] Add `ruby-dbus` to gemspec (core dependency — D-Bus is transport, not engine-specific)
+
+---
+
+### Engine Phase 1 — AGENTS.md Engine
+
+| Field | Value |
+|-------|-------|
+| Branch | `engine/1-agents-md` |
+| Status | **DONE** — merged to main |
+| Tests | 1061 examples, 0 failures |
+
+**Scope**:
+
+- [x] Create `lib/rosett_ai/engines/agents_md/`
+  - `backend.rb` — compile behaviour YAML to AGENTS.md format
+  - `manifest.yml` — capabilities (no settings, no executor)
+  - `detector.rb` — check for existing AGENTS.md in project root
+  - `validator.rb` — validate output against AGENTS.md spec
+- [x] Create `conf/engines/agents_md/` (engine config, if any)
+- [x] `bin/raictl compile --engine agents_md` produces valid AGENTS.md
+- [x] Capability warnings for features AGENTS.md doesn't support
+- [x] Specs and integration tests
+
+---
+
+### Desktop Phase 2 — GTK4 App (rosett-ai-gtk4)
+
+| Field | Value |
+|-------|-------|
+| Branch | `desktop/2-gtk4-app` |
+| Status | **DONE** — merged to main |
+| Tests | GTK4 app specs, preferences dialog specs |
+
+**Scope**: As defined in `conf/design/desktop_integration.yml` Phase 2.
+
+**Delivered**:
+
+- [x] `lib/rosett_ai/desktop/gtk4_app.rb` — main GTK4/Adwaita application window
+- [x] `lib/rosett_ai/desktop/gtk4_preferences.rb` — preferences dialog with dynamic engine list
+- [x] `lib/rosett_ai/desktop/dbus_client.rb` — D-Bus client for GUI ↔ service communication
+- [x] `lib/rosett_ai/desktop/gui_logger.rb` — crash-proof GUI logging
+- [x] `lib/rosett_ai/ui/gtk4.rb` — GTK4 UI adapter (tables, spinners, prompts)
+- [x] CLI: `bin/raictl desktop gtk4` launches the application
+- [x] GNOME HIG instant-apply preferences pattern
+- [x] Graceful degradation if libadwaita/gtk4 gems unavailable
+
+---
+
+### Engine Phase 2 — Ollama + GPT-NeoX Engines
+
+| Field | Value |
+|-------|-------|
+| Branch | `engine/2-ollama-gpt-neox` |
+| Status | **DONE** — merged to main |
+| Tests | Executor specs with mocked HTTP endpoints |
+
+**Scope**:
+
+- [x] Create `lib/rosett_ai/engines/ollama/`
+  - `detector.rb` — check `which ollama`, probe localhost:11434
+  - `executor.rb` — Ollama native API (`/api/generate`) + `analyze` method
+  - `backend.rb` — inherits from Generic backend
+  - `manifest.yml` — execution metadata, compilation via Generic backend
+  - `target.yml` — target profile for compilation
+- [x] Create `lib/rosett_ai/engines/gpt_neox/`
+  - `detector.rb` — check for vLLM/TGI endpoint (configurable)
+  - `executor.rb` — OpenAI-compatible API, NeoX-specific params + `analyze` method
+  - `backend.rb` — inherits from Generic backend
+  - `manifest.yml` — independent from Ollama
+  - `target.yml` — target profile for compilation
+- [x] Create `lib/rosett_ai/quorum/` module (initial implementation):
+  - `dispatcher.rb` — send adopt analysis to N engines in parallel (Thread-based)
+  - `collector.rb` — gather responses, normalize to common format
+  - `comparator.rb` — compare structured findings, cross-engine promotion
+  - `strategies/adopt.rb` — adopt-specific consensus orchestration
+- [x] `lib/rosett_ai/adopter/executor_resolver.rb` — manifest-driven executor kwargs
+- [x] `lib/rosett_ai/compiler/capability_checker.rb` — compile-time capability gap warnings
+- [x] `bin/raictl adopt --api --quorum` works with local engines
+- [x] Specs with mocked endpoints and quorum integration tests
+
+---
+
+### Engine Phase 3 — Goose + Aider Engines (Compilation)
+
+| Field | Value |
+|-------|-------|
+| Branch | `engine/3-goose-aider` |
+| Status | **DONE** — merged to main |
+| Tests | Backend and detector specs for both engines |
+
+**Scope** (compilation-focused — executors deferred to Phase 4):
+
+- [x] Create `lib/rosett_ai/engines/goose/`
+  - `backend.rb` — compile behaviour YAML to `.goosehints` format
+  - `detector.rb` — check `which goose`, `~/.config/goose/` exists
+  - `manifest.yml` — compilation capabilities
+  - `target.yml` — target profile
+- [x] Create `lib/rosett_ai/engines/aider/`
+  - `backend.rb` — compile behaviour YAML to `CONVENTIONS.md` format
+  - `detector.rb` — check `which aider`, `~/.aider.conf.yml` exists
+  - `manifest.yml` — compilation capabilities
+  - `target.yml` — target profile
+- [x] Register both engines in `lib/rosett_ai/engines/registry.rb` (7 at time; expanded to 10 in Phase 4)
+- [x] Cross-engine marker rejection tests
+- [x] `bin/raictl compile --engine goose` produces `.goosehints`
+- [x] `bin/raictl compile --engine aider` produces `CONVENTIONS.md`
+
+**Deferred to Phase 4**: Goose/Aider executors, config adapters, quorum participation.
+
+---
+
+### Consistency Review
+
+| Field | Value |
+|-------|-------|
+| Branch | `refactor/consistency-review` |
+| Status | **DONE** — merged to main |
+| Tests | 1382 examples, 0 failures |
+
+Post-Engine-3 architectural review addressing 9 findings:
+
+- [x] render() signature: category moved into data hash
+- [x] Marker standardization: all engines use `<!-- rosett-ai-{engine}-managed -->`
+- [x] Ollama/GPT-NeoX added to BACKENDS hash + target profiles
+- [x] Capability warnings aggregated per-feature instead of per-file
+- [x] Executor API key guard with `--local` hint
+- [x] Bullet-list local analysis for AGENTS.md format rules
+- [x] D-Bus ListEngines method with dynamic GTK4 engine combo
+- [x] Documentation updated for engines (7 at time of review, later expanded to 10)
+
+---
+
+### Engine Phase 4 — Cursor + Copilot + Windsurf + Goose/Aider Executors
+
+| Field | Value |
+|-------|-------|
+| Branch | `engine/4-cursor-copilot-windsurf` |
+| Status | **DONE** — merged to main |
+| Tests | 1491 examples, 0 failures, 5 pending |
+
+**Scope — New compilation-only engines**:
+
+- [x] Create `lib/rosett_ai/engines/cursor/` (backend, detector, manifest)
+  - Output: `.cursorrules` in project root
+  - Detector: check for `cursor` binary, `~/.cursor/` directory
+- [x] Create `lib/rosett_ai/engines/copilot/` (backend, detector, manifest)
+  - Output: `.github/copilot-instructions.md`
+  - Detector: check for `.github/` config directory
+- [x] Create `lib/rosett_ai/engines/windsurf/` (backend, detector, manifest)
+  - Output: `.windsurfrules` in project root
+  - Detector: check for `windsurf` binary
+- [x] All three are non-invocable (no executor) — compilation only
+- [x] Register in BACKENDS hash (10 total) and update target_schema.json
+- [x] Update `bin/raictl engines list` to show all 10 engines
+
+**Scope — Goose/Aider executor support** (folded from Phase 3):
+
+- [x] Create `lib/rosett_ai/engines/goose/executor.rb` — CLI subprocess executor (`Open3.capture3`)
+- [x] Create `lib/rosett_ai/engines/aider/executor.rb` — CLI subprocess executor (`Open3.capture3`)
+- [x] New `api_type: cli` category in engine manifests for subprocess-based executors
+- [x] Enable quorum participation for both engines
+- [x] Update manifests to declare executor capability
+
+**Scope — Shared**:
+
+- [x] Update `engine_manifest_schema.json` — `api_type: cli` + `cli_binary`
+- [x] Update `target_schema.json` — backend enum includes cursor, copilot, windsurf
+- [x] ExecutorResolver CLI branch — `binary:` kwarg for cli-type executors
+- [x] Specs for all new backends, detectors, and executors
+
+---
+
+### Desktop Phase 3 — KDE KCM Module (rosett-ai-kde) — DEFERRED
+
+| Field | Value |
+|-------|-------|
+| Branch | `desktop/3-kde-kcm` |
+| Status | **Deferred indefinitely** |
+| Reason | C++/QML falls outside the Ruby stack; high risk, low priority |
+
+This phase requires KDE Frameworks and a compiled C++/QML KCM module, which
+is architecturally different from the rest of rosett-ai. Placeholder UI adapters
+exist in `lib/rosett_ai/ui/kde.rb` and `lib/rosett_ai/ui/qt6.rb` for future use.
+
+The D-Bus service (`be.neatnerds.rosettai`) provides a stable IPC contract
+that any future KDE integration can consume without changes to rosett-ai core.
+
+---
+
+## 5. Branch Naming Convention
+
+```text
+# Completed
+engine/0a-rename-code-companion
+engine/0b-engine-directories
+engine/0c-xdg-engine-flag-detectors
+engine/1-agents-md
+engine/2-ollama-gpt-neox
+engine/3-goose-aider
+desktop/1-dbus-service
+desktop/2-gtk4-app
+backfill/executor-normalize
+backfill/capability-checker
+backfill/quorum-module
+backfill/dbus-desktop
+documentation
+refactor/consistency-review
+
+# Engine Phase 4
+engine/4-cursor-copilot-windsurf
+```
+
+Each branch merges to `main` via MR. No long-lived feature branches.
+Each MR must pass all CI gates before merge.
+
+Backfill branches address gaps from earlier phases discovered before
+starting the next major phase. They branch from the last completed
+engine phase and merge back to main.
+
+---
+
+## 6. Engine Architecture Diagram
+
+```mermaid
+graph TB
+    subgraph "Generic Layer (Human Intent)"
+        B["conf/behaviour/*.yml"]
+        D["conf/design/*.yml"]
+        S["conf/schemas/*.json"]
+    end
+
+    subgraph "Engine Registry"
+        R["lib/rosett_ai/engines/registry.rb"]
+    end
+
+    subgraph "Engines (10 total)"
+        subgraph "Claude Engine"
+            CB["backend.rb"]
+            CC["config_adapter.rb"]
+            CD["detector.rb"]
+            CE["executor.rb"]
+            CM["manifest.yml"]
+        end
+        subgraph "AGENTS.md Engine"
+            AB["backend.rb"]
+            AD["detector.rb"]
+            AM["manifest.yml"]
+        end
+        subgraph "Goose Engine"
+            GB["backend.rb"]
+            GD["detector.rb"]
+            GE["executor.rb"]
+            GM["manifest.yml"]
+        end
+        subgraph "Aider Engine"
+            IB["backend.rb"]
+            ID["detector.rb"]
+            IE["executor.rb"]
+            IM["manifest.yml"]
+        end
+        subgraph "Ollama Engine"
+            OD["detector.rb"]
+            OE["executor.rb"]
+            OM["manifest.yml"]
+        end
+        subgraph "GPT-NeoX Engine"
+            ND["detector.rb"]
+            NE["executor.rb"]
+            NM["manifest.yml"]
+        end
+        subgraph "Cursor Engine"
+            UB["backend.rb"]
+            UD["detector.rb"]
+            UM["manifest.yml"]
+        end
+        subgraph "Copilot Engine"
+            PB["backend.rb"]
+            PD["detector.rb"]
+            PM["manifest.yml"]
+        end
+        subgraph "Windsurf Engine"
+            WB["backend.rb"]
+            WD["detector.rb"]
+            WM["manifest.yml"]
+        end
+    end
+
+    subgraph "Quorum Module"
+        QD["dispatcher.rb"]
+        QC["comparator.rb"]
+    end
+
+    subgraph "Output (Tool-Native Paths)"
+        O1["~/.claude/rules/*.md"]
+        O2["./AGENTS.md"]
+        O3["(quorum results)"]
+        O4["./.cursorrules"]
+        O5["./.goosehints"]
+        O6["./CONVENTIONS.md"]
+        O7[".github/copilot-instructions.md"]
+        O8["./.windsurfrules"]
+    end
+
+    B --> R
+    D --> R
+    R --> CB --> O1
+    R --> CC
+    R --> AB --> O2
+    R --> GB --> O5
+    R --> IB --> O6
+    R --> UB --> O4
+    R --> PB --> O7
+    R --> WB --> O8
+    CE --> QD
+    GE --> QD
+    IE --> QD
+    OE --> QD
+    NE --> QD
+    QD --> QC --> O3
+
+    style B fill:#f9f,stroke:#333
+    style D fill:#f9f,stroke:#333
+    style S fill:#f9f,stroke:#333
+    style R fill:#ffd700,stroke:#333
+    style QD fill:#ff6347,stroke:#333
+    style QC fill:#ff6347,stroke:#333
+```
+
+---
+
+## 7. Layer Separation Diagram
+
+```mermaid
+graph LR
+    subgraph "Layer 1: Human Intent"
+        direction TB
+        L1A["Behaviour YAML<br/>(rules, ethics, workflows)"]
+        L1B["Design YAML<br/>(architecture, constraints)"]
+        L1C["Schemas JSON<br/>(validation)"]
+    end
+
+    subgraph "Layer 2: Engine Translation"
+        direction TB
+        L2A["Engine Backend<br/>(compile)"]
+        L2B["Config Adapter<br/>(settings)"]
+        L2C["Path Resolver<br/>(where to write)"]
+    end
+
+    subgraph "Layer 3: Tool-Native Output"
+        direction TB
+        L3A["CLAUDE.md + rules/"]
+        L3B["settings.json"]
+        L3C[".cursorrules"]
+        L3D["AGENTS.md"]
+        L3E[".goosehints"]
+        L3F["CONVENTIONS.md"]
+        L3G["copilot-instructions.md"]
+        L3H[".windsurfrules"]
+    end
+
+    L1A --> L2A
+    L1B --> L2A
+    L2A --> L2C
+    L2B --> L2C
+    L2C --> L3A
+    L2C --> L3B
+    L2C --> L3C
+    L2C --> L3D
+    L2C --> L3E
+    L2C --> L3F
+    L2C --> L3G
+    L2C --> L3H
+
+    style L1A fill:#e6f3ff,stroke:#333
+    style L1B fill:#e6f3ff,stroke:#333
+    style L1C fill:#e6f3ff,stroke:#333
+    style L2A fill:#fff3e6,stroke:#333
+    style L2B fill:#fff3e6,stroke:#333
+    style L2C fill:#fff3e6,stroke:#333
+    style L3A fill:#e6ffe6,stroke:#333
+    style L3B fill:#e6ffe6,stroke:#333
+    style L3C fill:#e6ffe6,stroke:#333
+    style L3D fill:#e6ffe6,stroke:#333
+    style L3E fill:#e6ffe6,stroke:#333
+    style L3F fill:#e6ffe6,stroke:#333
+    style L3G fill:#e6ffe6,stroke:#333
+    style L3H fill:#e6ffe6,stroke:#333
+```
+
+---
+
+## 8. Manual Tasks
+
+These tasks require human action outside the codebase:
+
+| Task | Owner | When | Status |
+|------|-------|------|--------|
+| Update GitLab project description (remove "Claude", reflect "Code Companion") | hugo | After Engine 0a merges | Done |
+| Configure GitLab CI runners for D-Bus integration tests | hugo | Before Desktop 1 | Verify |
+| Register `be.neatnerds.rosettai` bus name with freedesktop.org (optional) | hugo | Before Desktop 1 release | Pending |
+| Set up APT repository for v1.0.0 packages | hugo | Before first v1.x release | Pending |
+| Implement GlobalShortcuts portal registration | dev | Desktop 1 gap | Pending |