rosett-ai 1.3.3

data/conf/design/migration.yml

@@ -0,0 +1,56 @@
+---
+name: migration
+domain: core
+version: 1.0.0
+status: approved
+priority: 1
+author: hugo
+created_at: "2026-03-31"
+modified_at: "2026-03-31"
+modified_by: claude
+depends_on:
+  - init_command
+  - scope_hierarchy
+  - backward_compatibility
+
+intent: |
+  Provide a safe, automated migration path when rai configuration paths
+  change between versions. The v1.0.0 -> v1.1.0 migration moves behaviours
+  from ~/.claude/conf/behaviour/ to ~/.config/rosett-ai/conf/behaviour/ (XDG).
+
+  Users must NEVER lose data or have silent behaviour changes. Every migration
+  must: detect the old layout, warn the user, offer automatic migration,
+  preserve originals as backups, and verify the migration succeeded.
+
+constraints:
+  - "Migration must be automatic on first compile or init after package upgrade"
+  - "User must be warned before any file move with a clear explanation"
+  - "Original files must be preserved as .backup until user explicitly deletes"
+  - "Migration must be idempotent — running twice produces no additional changes"
+  - "rai doctor must detect pending migrations and report them"
+  - "Compilation must work during migration (read from both old and new paths)"
+  - "BREAKING CHANGES section in CHANGELOG.md for every path change"
+
+acceptance_criteria:
+  - "User with ~/.claude/conf/behaviour/ files sees migration warning on first compile"
+  - "Migration copies (not moves) files to ~/.config/rosett-ai/conf/behaviour/"
+  - "After migration, compile reads from XDG path"
+  - "Original ~/.claude/conf/behaviour/ files renamed to .migrated-to-xdg"
+  - "rai doctor reports 'migration pending' if old path has files but new path is empty"
+  - "rai doctor reports 'migration complete' after successful migration"
+  - "CHANGELOG.md documents the path change with migration instructions"
+
+anti_patterns:
+  - "Moving files without backup"
+  - "Silent path changes between versions"
+  - "Deleting old config files during migration"
+  - "Requiring manual user action for migration to work"
+  - "Breaking compile because old path is no longer read"
+
+examples:
+  - scenario: "v1.0.0 to v1.1.0 XDG migration on first compile"
+    expected: >-
+      User with behaviours at ~/.claude/conf/behaviour/ runs rai compile.
+      Migration warning is shown. Files are copied to ~/.config/rosett-ai/conf/behaviour/.
+      Legacy directory renamed to ~/.claude/conf.migrated-to-xdg/.
+      Compile proceeds reading from XDG path.

data/conf/design/monitoring_observability.yml

@@ -0,0 +1,194 @@
+---
+name: monitoring_observability
+domain: operations
+version: 0.1.0
+status: implemented
+priority: 6
+author: hugo
+created_at: "2026-03-04"
+modified_at: "2026-03-16"
+modified_by: claude
+depends_on:
+  - security
+  - architecture
+  - error_handling
+  - workflow
+  - structured_logging
+#
+intent: |
+  Provide structured runtime telemetry for the Rosett-AI CLI so developers and
+  operators can diagnose errors, measure compile performance, and audit
+  command execution — all without sending any data externally. Every CLI
+  invocation should be observable after the fact via JSON Lines logs that
+  capture timing, outcome, and contextual metadata. The telemetry system
+  must be opt-in, impose negligible overhead when disabled, and follow the
+  same pluggable provider pattern used elsewhere in rosett-ai so that desktop
+  (D-Bus health), compile metrics, and engine probes can plug in later
+  without changing the core interface.
+
+  Telemetry is the observability layer — it captures runtime metrics and
+  events for diagnostic purposes. Related but distinct: workflow audit logs
+  (workflow.yml) record step-by-step execution history for reproducibility,
+  provenance logs (ai_provenance.yml) record AI involvement per commit for
+  attribution, error handling (error_handling.yml) governs structured
+  error display, and structured logging (structured_logging.yml) provides
+  per-invocation correlation IDs and detailed diagnostic messages. Telemetry
+  and structured logging share the same correlation ID so that high-level
+  events (command_start, command_end) and detailed log entries (debug, info,
+  warn, error) from the same invocation can be correlated.
+
+  Telemetry events and structured log entries are complementary: telemetry
+  captures what happened (event, duration, outcome), while structured logging
+  captures why it happened (debug traces, validation details, error context).
+  Together they provide full observability for a single CLI invocation.
+#
+constraints:
+  - "All telemetry is local-only — no external endpoints, no phone-home,
+    GDPR-safe by design"
+  - "Telemetry is disabled by default; enabled via RAI_TELEMETRY=1
+    environment variable"
+  - "Overhead must be less than 5ms per CLI invocation when telemetry is
+    disabled"
+  - "Output format is JSON Lines (one JSON object per line) for streaming
+    and tooling compatibility — telemetry output is raw structured data,
+    not TTY-formatted"
+  - "Log destination is stderr by default; RAI_TELEMETRY_FILE=<path>
+    redirects to a file"
+  - "Log level controlled via RAI_TELEMETRY_LEVEL={debug,info,warn,error}
+    (default info)"
+  - "Must use Mutex for thread-safe I/O (same pattern as Desktop::GuiLogger)"
+  - "No new runtime dependencies — uses only stdlib JSON, Time, Process"
+  - "Provider interface is a Ruby module (RosettAi::Telemetry::Provider) with
+    a single #report method"
+  - "Providers are registered at boot, not discovered dynamically, to keep
+    startup cost zero"
+  - "Never log secrets, API keys, file contents, or user-identifiable data"
+  - "Structured fields include timestamp (ISO 8601), level, event, pid,
+    duration_ms, command, engine, correlation_id"
+  - "Telemetry events must include the correlation_id from structured_logging
+    for cross-referencing with diagnostic log entries"
+  - "Telemetry log files must have a configurable rotation policy (default
+    10 MB max, 5 rotated files) to prevent unbounded disk growth"
+  - "This design governs runtime observability (metrics, timing, diagnostics).
+    Workflow audit logs (step execution history) are governed by workflow.yml.
+    Provenance logs (AI involvement per commit) are governed by
+    ai_provenance.yml. Structured error display is governed by
+    error_handling.yml"
+#
+acceptance_criteria:
+  - "RosettAi::Telemetry::Reporter class exists with write_event, command_start,
+    command_end methods"
+  - "RosettAi::Telemetry::Provider module defines the #report(event_hash)
+    interface contract"
+  - "RAI_TELEMETRY=1 enables telemetry; unset or any other value disables it"
+  - "RAI_TELEMETRY_FILE writes JSON Lines to the specified path (append mode,
+    sync flush)"
+  - "RAI_TELEMETRY_LEVEL filters events below the configured severity"
+  - "CLI commands (compile, validate, adopt, engines) emit command_start and
+    command_end events"
+  - "command_end events include duration_ms measured via Process::CLOCK_MONOTONIC"
+  - "Error events include error class, message, and truncated backtrace
+    (first 5 frames)"
+  - "Debug/verbose output standards are documented: --verbose maps to info,
+    --debug to debug"
+  - "Reporter.instance returns a singleton; Reporter.enabled? returns boolean"
+  - "No telemetry code executes (beyond the enabled? check) when
+    RAI_TELEMETRY is unset"
+  - "Provider#report receives a frozen Hash and must not mutate it"
+  - "Telemetry events include correlation_id matching structured logging entries"
+  - "Exit code 0 on success, 1 on telemetry write failure (non-blocking),
+    2 on invalid telemetry configuration"
+#
+examples:
+  - scenario: "Developer runs compile with telemetry enabled"
+    expected: |
+      RAI_TELEMETRY=1 bin/raictl compile emits two JSON Lines to stderr:
+      {"timestamp":"...","level":"info","event":"command_start","command":"compile","engine":"claude","pid":12345}
+      {"timestamp":"...","level":"info","event":"command_end","command":"compile","duration_ms":142.3,"status":"success","pid":12345}
+    not: |
+      Telemetry output is mixed with normal CLI output on stdout.
+      File paths or rule content appear in telemetry events.
+  - scenario: "Developer runs compile without RAI_TELEMETRY"
+    expected: |
+      No JSON Lines output. The only cost is a single ENV fetch and boolean
+      check at Reporter initialization. Measured overhead < 1ms.
+    not: |
+      Reporter allocates objects, opens file handles, or registers at_exit hooks.
+  - scenario: "A D-Bus health provider is added later"
+    expected: |
+      Provider implements RosettAi::Telemetry::Provider, is registered via
+      Reporter.register_provider(provider), and receives #report calls for
+      each event. No changes to Reporter or existing providers needed.
+    not: |
+      D-Bus health logic is added directly into Reporter. Conditional
+      require blocks litter the telemetry module.
+  - scenario: "Telemetry log file is unwritable"
+    expected: |
+      Reporter swallows the I/O error and continues CLI execution normally.
+      A single warning is emitted to stderr: 'rosett-ai: telemetry file
+      /path/to/log unwritable — telemetry disabled for this invocation'.
+      Exit code is not affected (telemetry failures are non-blocking).
+    not: |
+      CLI crashes because telemetry file cannot be written. User's compile
+      or validate operation fails due to a telemetry issue.
+  - scenario: "Telemetry log file exceeds rotation threshold"
+    expected: |
+      When the log file exceeds 10 MB, it is rotated to
+      telemetry.jsonl.1 (up to 5 files). Oldest rotated file is deleted.
+      Rotation happens atomically before writing the next event.
+    not: "Log file grows unbounded. Disk fills up over months of use."
+#
+anti_patterns:
+  - "Sending telemetry data to any external service or network endpoint"
+  - "Enabling telemetry by default (must be explicit opt-in)"
+  - "Logging file contents, secrets, API keys, or personally identifiable
+    information"
+  - "Using puts or print instead of structured JSON Lines"
+  - "Dynamic provider discovery via ObjectSpace or const_get (register
+    explicitly)"
+  - "Allocating telemetry objects when telemetry is disabled"
+  - "Blocking CLI execution on telemetry I/O failures (swallow and continue)"
+  - "Using global variables or class variables for telemetry state (use
+    singleton instance)"
+  - "Unbounded log file growth without rotation"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. workflow.yml: workflow audit logs record step execution history for
+     reproducibility. Telemetry observes workflow execution at the timing/
+     metrics level.
+
+  2. ai_provenance.yml: provenance logs record AI involvement per commit.
+     Telemetry captures the timing of provenance operations.
+
+  3. error_handling.yml: structured error display follows the error
+     hierarchy. Telemetry captures error events with class, message,
+     and truncated backtrace.
+
+  4. security.yml: telemetry must never log secrets, API keys, or PII.
+     Local-only constraint is absolute.
+
+  5. architecture.yml: the pluggable provider pattern follows rosett-ai's
+     extension architecture (register at boot, not discover dynamically).
+
+  6. desktop_integration.yml: D-Bus health provider is a future telemetry
+     provider that exposes rosett-ai health on the session bus.
+
+  7. structured_logging.yml: structured logging provides correlation IDs
+     and detailed diagnostic messages. Telemetry events include the same
+     correlation_id for cross-referencing.
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Singleton instance pattern for Reporter"
+    - "Provider interface module (RosettAi::Telemetry::Provider)"
+    - "JSON Lines structured logging"
+    - "Mutex thread-safety for I/O"
+    - "Monotonic clock timing (Process::CLOCK_MONOTONIC)"
+    - "Log rotation with configurable threshold"
+  testing: rspec with telemetry event capture, provider registration,
+    disabled-mode overhead benchmarks, I/O failure handling, and log
+    rotation scenarios
+  gems: []

data/conf/design/namespace_cleanup.yml

@@ -0,0 +1,145 @@
+---
+name: namespace_cleanup
+domain: core
+version: 1.0.0
+status: implemented
+priority: 1
+author: hugo
+created_at: '2026-04-14'
+modified_at: '2026-04-14'
+modified_by: claude opus-4.6
+depends_on:
+- migration
+- doctor
+- architecture
+- ci_pipeline
+intent: |
+  Eliminate all remaining references to the legacy "nncc" namespace from the
+  rosett-ai codebase, configuration, and project ecosystem. The project was
+  renamed from NeatNerds Code Companion (nncc) to Rosett-AI in v1.0.0, but
+  residual nncc references persist in method names, test modules, design docs,
+  schema filenames, code comments, and the user's filesystem. These stale
+  references create confusion for contributors, break the naming contract
+  established by the rename, and will appear unprofessional in a published
+  release.
+
+  This design document records the decisions for each cleanup area. A separate
+  implementation session will execute the changes based on these decisions.
+
+  Pre-flight findings (2026-04-14):
+  - ~/.config/nncc/ contains 6 behaviour files, schemas, and config.yml
+  - 12 projects across ~/git have .nncc/ directories (+ ~/git/.nncc)
+  - Zero .rosett-ai/ project directories exist on disk
+  - RAI_MARKER and MARKER_PREFIX already use rosett-ai naming
+  - nncc_managed? method persists in installer.rb and chain_detector.rb
+  - NnccTestStubs module in spec/support/stub_engines.rb
+  - 5 design docs reference nncc
+  - Schema files: nncc_config_schema.json, nncc_project_schema.json
+  - CLAUDE.md is missing from the project root
+constraints:
+- No data loss — user files in ~/.config/nncc/ and .nncc/ must be preserved or migrated,
+  never silently deleted
+- Rename operations must not break the test suite — run rspec after each atomic rename
+- CI lint job must distinguish intentional nncc references (migration code, doctor
+  checks) from stale ones
+- The CLAUDE.md must reflect the current rosett-ai identity, not the nncc identity
+  from the parent CLAUDE.md
+- Schema file renames must be accompanied by updates to all $ref pointers
+- Design doc updates must preserve git blame utility — use targeted edits, not wholesale
+  rewrites
+acceptance_criteria:
+- grep -r 'Nncc::' lib/ returns zero matches
+- grep -r 'nncc_managed?' lib/ returns zero matches
+- grep -r 'NnccTestStubs' spec/ returns zero matches
+- grep -r 'nncc' conf/design/ returns only namespace_cleanup.yml itself and migration.yml
+  (which documents the nncc->rosett-ai migration)
+- ls conf/schemas/nncc_*.json returns zero matches
+- CLAUDE.md exists at project root with raictl CLI reference
+- CI lint job catches future nncc regressions
+- raictl doctor detects ~/.config/nncc/ and .nncc/ directories
+- Full test suite passes after all renames
+anti_patterns:
+- Bulk search-replace without context analysis — nncc in paths uses hyphens, in Ruby
+  identifiers uses underscores, in module names uses CamelCase
+- Renaming migration/doctor code that intentionally references nncc
+- Deleting ~/.config/nncc/ or .nncc/ directories without migration
+- Writing CLAUDE.md by copying the parent CLAUDE.md and editing
+examples:
+- scenario: Developer greps for stale nncc references after cleanup
+  expected: |
+    $ grep -rn 'nncc' lib/ --include='*.rb'
+    lib/rosett_ai/doctor/checks/stale_home_nncc_check.rb:18:        check_name 'stale_home_nncc'
+    lib/rosett_ai/doctor/checks/stale_config_nncc_check.rb:18:        check_name 'stale_config_nncc'
+
+    Only doctor checks that detect legacy nncc artifacts appear.
+    No Nncc:: modules, no nncc_managed? methods, no NnccTestStubs.
+  not: |
+    Hundreds of nncc references across lib/, spec/, conf/.
+    Doctor checks renamed to remove nncc from their name (they describe
+    what they detect — the nncc artifacts).
+preferences:
+  language: ruby
+  patterns:
+  - Targeted search-replace with context awareness
+  - Atomic commits per rename area (method, module, schema, docs)
+  - Test suite validation between each rename
+  testing: rspec full suite after each atomic rename, CI lint job as final gate
+gui_notes: |
+  Decisions, schema renames, and action list archived below.
+
+  DECISIONS:
+    q01_project_marker_directory:
+      Q: What should the project-level marker directory be named?
+      A: Option A — keep .rosett-ai/
+
+    q02_xdg_global_config_path:
+      Q: What should the XDG global config path be?
+      A: Option A — keep ~/.config/rosett-ai/
+
+    q03_legacy_config_nncc_migration:
+      Q: How to handle the stale ~/.config/nncc/ directory?
+      A: Option C — raictl migrate command
+
+    q04_legacy_nncc_project_markers:
+      Q: How to handle .nncc/ directories in projects?
+      A: Option B — raictl migrate renames .nncc/ to .rosett-ai/
+
+    q05_method_name_nncc_managed:
+      Q: What should the nncc_managed? method be renamed to?
+      A: Option B — rename to rai_managed?
+
+    q06_test_stub_module:
+      Q: What should the NnccTestStubs module be renamed to?
+      A: Option B — rename to RaiTestStubs
+
+    q07_design_doc_nncc_references:
+      Q: How to handle nncc references in design docs?
+      A: Option A — search-replace nncc references
+
+    q08_claude_backend_stale_comment:
+      Q: Is nncc-claude-managed in compiled output or just a comment?
+      A: Code comment only — fix the comment
+
+    q09_ci_lint_job:
+      Q: What should the CI namespace regression lint check?
+      A: Grep-based lint job with allowlist
+
+    q10_claude_md_rewrite:
+      Q: What should the CLAUDE.md contain?
+      A: Complete rewrite for rosett-ai identity
+
+
+  SCHEMA FILE RENAMES:
+    conf/schemas/nncc_config_schema.json -> conf/schemas/rosett_ai_config_schema.json
+    conf/schemas/nncc_project_schema.json -> conf/schemas/rosett_ai_project_schema.json
+
+  PRIORITIZED ACTIONS (all completed):
+    1. Write CLAUDE.md (Q10) — release blocker, no code dependencies
+    2. Rename nncc_managed? to rai_managed? (Q5) — code change, test after
+    3. Rename NnccTestStubs to RaiTestStubs (Q6) — test infra, test after
+    4. Fix claude_backend.rb comment (Q8) — trivial, no test impact
+    5. Rename schema files (supplementary) — update refs, test after
+    6. Update design doc references (Q7) — 5 files, no code impact
+    7. Add stale_config_nncc doctor check (Q3) — new code, test after
+    8. Extend raictl migrate for .nncc/ and ~/.config/nncc/ (Q3, Q4)
+    9. Add CI lint job (Q9) — must run after all renames complete

data/conf/design/plugin_test_segregation.yml

@@ -0,0 +1,145 @@
+---
+name: plugin_test_segregation
+domain: testing
+version: 0.1.0
+status: draft
+priority: 3
+author: hugo
+created_at: "2026-04-17"
+modified_at: "2026-04-17"
+modified_by: claude
+depends_on:
+  - testing
+  - engine_architecture
+  - gui_plugins
+  - desktop_integration
+  - mcp_integration
+intent: |
+  Decouple plugin test suites from the core rosett-ai test suite so that
+  (a) the core suite runs fast and deterministically without optional gems,
+  (b) each plugin gem owns its own specs and CI, and (c) the contract
+  boundary between core and plugins is explicit and testable from both sides.
+
+  Currently 25 spec files (dbus/13, desktop/4, ui/8) live in the core repo
+  but depend on optional gems (ruby-dbus, gtk4, libadwaita). The PrePush
+  hook already excludes them via --exclude-pattern, proving they are not
+  core tests. Thor task specs (dbus_spec.rb, desktop_spec.rb) and doctor
+  checks (dbus_availability_check_spec.rb) add further coupling. This
+  design formalises the decoupling.
+
+constraints:
+  - Core test suite (bundle exec rspec) must pass with ZERO optional gems installed
+  - Plugin gems must be independently testable (bundle exec rspec in plugin repo)
+  - Contract specs must exist on BOTH sides — core verifies the contract interface, plugin verifies it satisfies the contract
+  - Shared examples ('a UI implementation', 'a compiler backend') must live in a shared gem or be duplicated in each plugin that uses them
+  - No spec file in the core repo may require ruby-dbus, gtk4, gi, or any optional gem at load time
+  - The PrePush --exclude-pattern hack must be eliminated — if specs live in the right repo, no exclusion is needed
+  - stub_engines.rb must remain in core — engine stubs test the compilation pipeline, not engine plugins
+  - Plugin CI must pull the core gem as a dependency (not git submodule) to test integration
+  - Mutation testing (mutant) must run per-repo — core mutant tests core, plugin mutant tests plugin
+  - Packaging specs (variant_config_spec.rb) that reference GTK4 must use stubs, not real GTK4
+
+acceptance_criteria:
+  - Core rspec suite passes without --exclude-pattern and without optional gems
+  - No spec file under spec/ requires ruby-dbus, gtk4, gi, or qt5 gems
+  - rosett-ai-gtk4 gem has its own spec/ directory with desktop, dbus, and ui/gtk4 specs
+  - rosett-ai-gtk4 spec suite passes independently with bundle exec rspec
+  - Shared example 'a UI implementation' is available to plugin specs via rosett-ai core gem or shared spec gem
+  - Shared example 'a compiler backend' remains in core (engines are core infrastructure)
+  - Thor task specs for dbus and desktop commands use stub doubles, not real D-Bus/GTK classes
+  - Doctor dbus_availability_check_spec tests the check logic with stubs, not real D-Bus probing
+  - Plugin registry specs (gui_contract_spec.rb) test the contract interface, not a real GTK4 implementation
+  - PrePush RspecCore hook no longer needs --exclude-pattern for desktop/dbus/ui paths
+  - packaging/variant_config_spec.rb uses config stubs for gtk4 variant, not real GTK4 detection
+  - CI pipeline for core repo has no gtk4/dbus stage or dependency
+  - CI pipeline for rosett-ai-gtk4 installs ruby-dbus + gtk4 introspection in its own job
+  - Integration test exists that installs core .deb + gtk4 .deb and verifies plugin discovery
+
+examples:
+  - scenario: Developer runs core test suite on a server with no desktop environment
+    expected: |
+      $ bundle exec rspec
+      4200 examples, 0 failures
+
+      No --exclude-pattern needed. All 25 desktop/dbus/ui specs have been
+      moved to the rosett-ai-gtk4 plugin gem. Core specs that previously
+      tested D-Bus/GTK behaviour now use contract doubles.
+    not: Test suite fails with LoadError for ruby-dbus or gi gem
+
+  - scenario: Plugin developer adds a new D-Bus interface to rosett-ai-gtk4
+    expected: |
+      1. Write spec in rosett-ai-gtk4/spec/dbus/new_interface_spec.rb
+      2. Implement in rosett-ai-gtk4/lib/rosett_ai_gtk4/dbus/new_interface.rb
+      3. Run: cd rosett-ai-gtk4 && bundle exec rspec — passes
+      4. Core repo unchanged — no new spec, no new exclude pattern
+    not: Developer must add spec to core repo and update --exclude-pattern
+
+  - scenario: Core contract changes — UI implementation interface adds a new required method
+    expected: |
+      1. Update shared example 'a UI implementation' in core
+      2. Core specs pass (TUI and AccessibleTUI satisfy new contract)
+      3. rosett-ai-gtk4 CI fails — GTK4 UI adapter missing new method
+      4. Plugin developer adds method to GTK4 adapter
+      5. Both repos green
+    not: Contract change is invisible to plugin authors until runtime
+
+  - scenario: Stubbing strategy for Thor desktop task spec in core
+    expected: |
+      The desktop_spec.rb in core tests the Thor task routing, not GTK4.
+      It stubs RosettAi::Plugins::Registry.available(:gui) to return
+      a contract double that responds_to launch, available?, gui_name.
+      No real GTK4 classes are loaded.
+
+      The rosett-ai-gtk4 repo has its own desktop_integration_spec.rb
+      that tests the real GTK4App class with the real D-Bus client.
+    not: Core desktop_spec.rb loads GTK4 classes or requires ruby-dbus
+
+anti_patterns:
+  - Moving specs but keeping require lines that pull in optional gems — the LoadError just moves to a different location
+  - Using allow_any_instance_of to stub optional gem constants — fragile and hides real coupling
+  - Sharing spec helpers via git submodule — version drift, merge conflicts, CI complexity
+  - Conditionally skipping specs with pending/skip based on gem availability — this is the current anti-pattern, it hides failures
+  - Mocking the Zeitwerk loader instead of fixing the actual dependency graph
+  - Keeping shared examples in core gem spec/support/ — creates coupling between plugin test setup and core internals
+
+preferences:
+  language: ruby
+  patterns:
+    - Contract doubles (not instance_double) for cross-gem boundaries — mocked via RSpec double() with method stubs
+    - Shared examples in a separate rosett-ai-test-support gem for cross-repo reuse
+    - RSpec tag filtering (:plugin => true) as a transitional measure before full extraction
+  testing: Core specs runnable with core Gemfile only (no optional groups). Plugin specs use own Gemfile with rosett-ai + rosett-ai-test-support as dependencies. Integration tests live in plugin repo.
+  gems:
+    - rosett-ai-test-support (new) — shared examples and contract double factories
+    - rosett-ai-gtk4 — separate GitLab repo (private until mature), owns all GTK4/D-Bus specs
+
+gui_notes: |
+  DECISIONS (2026-04-17, approved by hugo):
+
+  1. SEPARATE REPO: rosett-ai-gtk4 is a separate GitLab repository,
+     private until maturity. Not a monorepo subdirectory. This gives
+     clean CI isolation and independent release cycle. Harmonisation
+     (namespace alignment, contract stabilisation) is a prerequisite
+     before the full extraction starts.
+
+  2. SEPARATE TEST SUPPORT GEM: rosett-ai-test-support gem ships shared
+     examples ('a UI implementation', 'a compiler backend') and contract
+     double factories. Both core and plugin repos depend on it for testing.
+     TUI implementation stays in core. Some duplication across repos is
+     accepted — the cost of tight coupling is greater.
+
+  3. CONTRACT DOUBLES WITH MOCKING: Use RSpec double()/class_double()
+     for cross-gem boundaries. No instance_double (requires the real
+     class). Contract doubles mock the interface defined by GuiContract,
+     EngineContract, McpContract. The contract classes themselves remain
+     in core and define the expected method signatures.
+
+  4. PHASED APPROACH: First move away the problematic test code from
+     core (Phase 1). Then create the plugin repo and stabilise the
+     contract boundary (Phase 2). The harmonisation work is a
+     prerequisite before Phase 2 starts.
+
+  Extraction targets: lib/rosett_ai/desktop/, lib/rosett_ai/dbus/
+  (except rate_limiter.rb which has no optional deps),
+  lib/rosett_ai/ui/gtk4.rb, lib/rosett_ai/ui/kde.rb,
+  lib/rosett_ai/ui/qt6.rb, and all corresponding specs.