rosett-ai 1.3.3

data/doc/decisions/005-package-splitting-strategy.md

@@ -0,0 +1,200 @@
+# ADR-005: Package Splitting Strategy
+
+## Status
+
+Accepted (2026-02-21) — implementation deferred to P3/P4
+
+## Context
+
+The `architecture.yml` design document requires that GUI frontends are
+delivered as separate Debian packages (`rosett-ai-gtk4`, `rosett-ai-qt6`, `rosett-ai-kde`)
+that depend on the core `rosett-ai` package. The core must be fully functional
+without any GUI package installed.
+
+The `RosettAi::Ui::Registry` pattern is already in place. Adapters register
+themselves at require time, and `Registry.resolve(name)` instantiates the
+requested adapter. The TUI adapter is the default and the only adapter
+currently implemented.
+
+The build infrastructure exists: fpm-based `.deb` packaging via
+`bin/raictl build package`.
+
+The question is how to organise the source code for multiple packages.
+
+## Options
+
+### Option A: Monorepo with multiple gemspecs
+
+Single Git repository with a directory per package:
+
+```text
+rosett-ai/
+├── rosett-ai.gemspec            # Core + TUI
+├── packages/
+│   ├── rosett-ai-gtk4/
+│   │   ├── rosett-ai-gtk4.gemspec
+│   │   └── lib/rosett_ai/ui/gtk4.rb
+│   ├── rosett-ai-qt6/
+│   │   ├── rosett-ai-qt6.gemspec
+│   │   └── lib/rosett_ai/ui/qt6.rb
+```
+
+Pros:
+
+- Atomic cross-package changes (interface + adapter in one commit)
+- Single CI pipeline validates all packages together
+- Shared test infrastructure
+
+Cons:
+
+- Repository grows with each GUI toolkit's dependencies
+- CI must install GTK4, Qt6, and KDE libraries to test all packages
+- fpm build configuration becomes complex
+- Contributors must install all toolkit dev packages
+
+### Option B: Separate repositories
+
+Core stays in this repository. Each GUI package gets its own repository
+(`rosett-ai-gtk4`, `rosett-ai-qt6`).
+
+Pros:
+
+- Clean separation of concerns
+- Independent CI pipelines with toolkit-specific dependencies
+- Independent release cycles
+
+Cons:
+
+- Cross-repo coordination when Base interface changes
+- Version drift risk between core and GUI packages
+- Harder to run shared examples across repos
+- Changes to shared_examples require multi-repo updates
+
+### Option C: Plugin gems within core repo
+
+GUI adapter files live in the core repository under `lib/rosett_ai/ui/` but are
+excluded from the core `rosett-ai.gemspec`. Each plugin has its own gemspec at the
+repo root. Both core and plugins are built from the same repository but as
+separate gems and separate `.deb` packages.
+
+```text
+rosett-ai/
+├── rosett-ai.gemspec                  # Core: lib/rosett_ai/ui/{base,registry,tui}.rb
+├── rosett-ai-gtk4.gemspec             # Plugin: lib/rosett_ai/ui/gtk4.rb
+├── rosett-ai-qt6.gemspec              # Plugin: lib/rosett_ai/ui/qt6.rb
+├── lib/rosett_ai/ui/
+│   ├── base.rb                   # Shipped in rosett-ai
+│   ├── registry.rb               # Shipped in rosett-ai
+│   ├── tui.rb                    # Shipped in rosett-ai
+│   ├── gtk4.rb                   # Shipped in rosett-ai-gtk4
+│   └── qt6.rb                    # Shipped in rosett-ai-qt6
+├── spec/rosett_ai/ui/
+│   ├── base_spec.rb
+│   ├── tui_spec.rb
+│   ├── gtk4_spec.rb              # Runs shared_examples
+│   └── qt6_spec.rb              # Runs shared_examples
+```
+
+Auto-registration at the bottom of each adapter file:
+
+```ruby
+# lib/rosett_ai/ui/gtk4.rb
+RosettAi::Ui::Registry.register(:gtk4, Gtk4)
+```
+
+Debian packages:
+
+- `rosett-ai` ships `lib/rosett_ai/ui/{base,registry,tui}.rb` + all core
+- `rosett-ai-gtk4` ships `lib/rosett_ai/ui/gtk4.rb`, depends on `raictl (>= X.Y.Z)`
+  and `libgtk-4-dev`
+- `rosett-ai-qt6` ships `lib/rosett_ai/ui/qt6.rb`, depends on `raictl (>= X.Y.Z)`
+  and `qt6-base-dev`
+
+Pros:
+
+- Shared examples validate all adapters against the same interface contract
+- One CI pipeline — test matrix per toolkit (optional stages)
+- Interface changes and adapter updates in the same commit
+- `Registry.register` call in each adapter file provides auto-discovery
+- fpm can build multiple `.deb` packages from the same source tree
+
+Cons:
+
+- Gemspec file exclusion lists must be maintained carefully
+- CI needs conditional toolkit installation (only for GUI test stages)
+- Contributors see all adapter code even if they only work on one
+
+## Decision
+
+**Option C: Plugin gems within core repository** — because:
+
+- The shared_examples pattern (`'a UI implementation'`) is already in place
+  and validates the 7-method interface contract. Running these examples
+  against all adapters in one CI pipeline catches interface drift immediately.
+- `Registry.register(:gtk4, Gtk4)` at the bottom of `gtk4.rb` provides
+  automatic discovery — no configuration files, no plugin manifests.
+- The fpm-based build can produce multiple `.deb` packages from the same
+  source tree by varying the file inclusion list.
+- When `Base` adds a new abstract method (as happened with `announce`,
+  `accessible?`, `text_direction`), all adapter specs fail in the same CI
+  run, forcing immediate fixes.
+
+## Consequences
+
+Implementation is deferred to P3 (ui_framework) and P4 (packaging), but the
+architecture is documented now:
+
+- Future: `lib/rosett_ai/ui/gtk4.rb` + `rosett-ai-gtk4.gemspec` added to this repo
+- Debian `Depends:` on `raictl (>= current_version)` for all GUI packages
+- CI test matrix: core tests always run; GTK4/Qt6 tests run conditionally
+  based on toolkit availability
+- Shared examples validate all registered adapters in a single CI run
+- No code changes needed now — the Registry pattern already supports this
+
+### P4 detail: variant packaging
+
+`bin/raictl build package` will be extended with a `--variant` flag:
+
+```bash
+bin/raictl build package --variant core     # Core + TUI only (default)
+bin/raictl build package --variant gtk4     # rosett-ai-gtk4 .deb only
+bin/raictl build package --variant qt6      # Rosett-AI-qt6 .deb only
+bin/raictl build package --variant all      # Build all packages in one invocation
+```
+
+`--variant all` iterates over all known variants and produces one `.deb`
+per variant. This is the expected invocation for release automation.
+
+### P3/P4 detail: GUI adapter testing
+
+Every UI adapter — TUI and GUI — must have maximum test coverage. The TUI
+adapter is testable with standard RSpec (no display server required). GUI
+adapters require a different strategy because they render to a display.
+
+GUI testing approaches to evaluate during P3 implementation:
+
+| Approach | How it works | Toolkit support |
+|----------|-------------|-----------------|
+| Headless display (Xvfb) | Virtual X11 framebuffer; no physical display needed | GTK4, Qt6, KDE |
+| ATK/AT-SPI introspection | Query widget tree via accessibility API; assert structure and state | GTK4 (native), Qt6 (via bridge) |
+| dogtail / ldtp | Python libraries that drive GUI apps via AT-SPI; can click, type, assert | GTK4, Qt6 |
+| GLib test harness | GTK's own `Gtk.test_*` functions for widget testing | GTK4 only |
+| Qt Test / QTest | Qt's built-in test framework with `QTest::mouseClick`, `QTest::keyPress` | Qt6 only |
+| Screenshot comparison | Render to headless display, capture screenshot, compare against baseline | Any toolkit |
+
+The recommended layered approach:
+
+1. **Unit tests** (RSpec + shared_examples): validate that each adapter
+   implements the Base interface contract. No display server needed — mock
+   the toolkit bindings. This is the primary coverage layer.
+2. **Integration tests** (Xvfb + AT-SPI): run the adapter in a headless
+   display, query the widget tree via accessibility introspection. This
+   validates that widgets are created and accessible. Runs in CI with
+   `xvfb-run`.
+3. **Smoke tests** (optional, P4): screenshot comparison for visual
+   regression. Fragile and toolkit-version-sensitive, so only for release
+   validation, not CI gatekeeping.
+
+The accessibility introspection approach (layer 2) has a natural synergy
+with ADR-003's EN 301 549 compliance requirement — if the widget tree is
+queryable via AT-SPI, the application is accessible by construction.

data/doc/decisions/006-multi-engine-architecture.md

@@ -0,0 +1,147 @@
+# ADR-006: Multi-Engine Architecture
+
+## Status
+
+Proposed (2026-02-21)
+
+## Context
+
+rosett-ai's stated goal is to be a configuration management tool for AI-assisted
+development workflows. While the initial implementation targets Claude Code
+exclusively, the architecture should not preclude support for other AI coding
+engines. The intent is "one program to rule them all" — author configuration
+once, compile to multiple engines, potentially invoke several simultaneously.
+
+Each engine has its own directory conventions, configuration format, and
+operational model:
+
+| Engine | Global config | Local config | Format |
+|--------|--------------|-------------|--------|
+| Claude Code | `~/.claude/` | `.claude/` | JSON + Markdown rules |
+| Cursor | `~/.cursor/` | `.cursor/` | JSON |
+| Windsurf (Codeium) | `~/.codeium/windsurf/` | `.windsurf/` | JSON |
+| Aider | `~/.aider.conf.yml` | `.aider.conf.yml` | YAML |
+| Continue.dev | `~/.continue/` | `.continue/` | JSON |
+
+ADR-002 (accepted) establishes `RosettAi::PathResolver` as the centralised path
+resolution module. This ADR extends that concept to accommodate multiple
+engines, and defines the compiler adapter pattern for generating
+engine-native configuration files.
+
+### Relationship to existing design documents
+
+- `architecture.yml` defines the multi-target AI compilation goal
+- `compiler.yml` covers the compilation pipeline (currently Claude-only)
+- `claude_code_configuration.yml` covers Claude Code settings specifically
+- ADR-002 establishes PathResolver (currently Claude-only)
+
+### Design constraint: no ERB for machine-parsed output
+
+Templating engines like ERB were considered for generating native config
+files (JSON, YAML). This was rejected on security and correctness grounds:
+
+- ERB is `Kernel#eval` under the hood, widening the attack surface beyond
+  what the security design document permits
+- ERB-in-JSON is fragile: indentation, trailing commas, and quote escaping
+  are common sources of invalid output
+- Programmatic hash construction (`Hash` → `JSON.generate`) guarantees
+  valid output by construction and keeps data separated from logic
+
+The existing pattern — YAML data → Ruby hash transforms → native format —
+is safer, testable, and sufficient for all known engine config formats.
+
+## Options
+
+### Option A: Engine-aware PathResolver + compiler adapters
+
+Extend `PathResolver` with an engine registry. Each engine declares its
+path conventions. A parallel compiler adapter pattern transforms rosett-ai's
+canonical YAML into each engine's native format.
+
+```ruby
+# Path resolution
+PathResolver.for(:claude).global_dir   # => ~/.claude
+PathResolver.for(:cursor).global_dir   # => ~/.cursor
+PathResolver.for(:aider).config_file   # => ~/.aider.conf.yml
+
+# Compilation
+EngineCompiler.for(:claude).compile(source)  # => JSON + Markdown
+EngineCompiler.for(:cursor).compile(source)  # => JSON
+EngineCompiler.for(:aider).compile(source)   # => YAML
+```
+
+Engine definitions live in `conf/engines/<name>.yml` and declare paths,
+format, and compiler class. New engines are added by writing a YAML
+definition and a compiler adapter — no changes to core code.
+
+Pros:
+
+- Clean separation: paths in PathResolver, transforms in compiler adapters
+- New engines require zero changes to existing code
+- Shared test infrastructure via shared_examples (same pattern as UI adapters)
+- Each compiler adapter is independently testable
+- Data/logic separation maintained (no eval surface)
+
+Cons:
+
+- Significant design work before implementation
+- Engine config formats may diverge enough that a common YAML source is
+  impractical for some engines
+- Risk of premature abstraction if only Claude Code is used for a long time
+
+### Option B: Separate tool per engine
+
+Create independent executables: `rosett-ai-claude`, `rosett-ai-cursor`, etc. Each
+is self-contained with its own paths and compiler.
+
+Pros:
+
+- Maximum simplicity per engine
+- No abstraction overhead
+
+Cons:
+
+- Duplicated logic across tools
+- No unified workflow for multi-engine users
+- Contradicts the "one program to rule them all" goal
+
+### Option C: Plugin-only extensibility
+
+Keep rosett-ai Claude-only in core. Third-party plugins add engine support.
+
+Pros:
+
+- Core stays simple
+- Community can contribute engines
+
+Cons:
+
+- No guarantee of interface consistency
+- Plugin API must be designed and maintained
+- Quality control is harder across third-party code
+
+## Decision
+
+Deferred — this ADR captures the architectural direction established during
+ADR-002 review. The recommended approach is **Option A**, but implementation
+details require further analysis during the compiler design phase (P2).
+
+Key principles agreed:
+
+1. PathResolver must be designed with engine extensibility in mind
+2. Compiler adapters (not templates) transform YAML to native formats
+3. No ERB or eval-based templating for machine-parsed output
+4. Engine definitions are declarative (YAML), not code-driven
+5. The existing Claude Code implementation is the first adapter, not a
+   special case
+
+## Consequences
+
+- PathResolver (ADR-002) should use a design that can later accept an
+  engine parameter without breaking the current single-engine API
+- The compiler design document should acknowledge multi-engine as a
+  future requirement
+- No implementation work is needed now — Claude Code remains the only
+  target until this ADR is accepted and scheduled
+- When implemented, `conf/engines/claude.yml` would replace the
+  hardcoded Claude Code assumptions in the current compiler

data/doc/decisions/007-engine-agnostic-pivot.md

@@ -0,0 +1,219 @@
+# ADR-007: Engine-Agnostic Architecture Pivot
+
+## Status
+
+Accepted (2026-02-26) — supersedes ADR-006 (Proposed)
+
+## Context
+
+raictl was designed as a configuration management tool for AI-assisted
+development workflows. Despite the stated goal of AI-agnosticism, the
+implementation is Claude Code-centric: the project is named "NeatNerds
+Claude Companion", rosett-ai lives inside `~/.claude/`, the config compiler
+targets Claude Code's `settings.json` format, and the adopt system
+hard-depends on the Anthropic API.
+
+A comprehensive audit (2026-02-26) revealed:
+
+- **2 hard couplings**: Config compilation (100% Claude Code) and Adopt
+  API analysis (Anthropic-only)
+- **3 soft couplings**: Default output paths, CLI description strings,
+  documentation references
+- **Existing abstraction**: The compiler already has a multi-target
+  backend pattern (ClaudeBackend, GenericBackend) via strategy pattern
+
+A structured Q&A session produced 9 architectural decisions that resolve
+ADR-006's deferred status and define the concrete path to AI-agnosticism.
+
+### Relationship to existing ADRs and design documents
+
+- **ADR-006** (Proposed): Identified multi-engine as a future need,
+  recommended Option A (engine-aware PathResolver + compiler adapters),
+  but deferred implementation. This ADR accepts and extends that
+  direction with specific decisions.
+- **ADR-002** (Accepted): PathResolver with `engine:` parameter — already
+  designed for multi-engine, just not activated.
+- **ADR-005** (Accepted): Package splitting strategy — applies to engine
+  packages (`rosett-ai-engine-*`) in addition to UI packages.
+- `architecture.yml`: Must be updated to reflect engine-agnostic core.
+- `compiler.yml`: Multi-target pipeline already designed; `--target`
+  renamed to `--engine`.
+- `claude_code_configuration.yml`: Becomes Claude engine-specific config.
+- `aaif_alignment.yml`: AGENTS.md becomes a first-class engine.
+
+## Decisions
+
+### Q1: Identity & Naming
+
+**Decision**: Rename from "NeatNerds Claude Companion" to **"NeatNerds
+Code Companion"**. The acronym `rosett-ai` is preserved. Binary name, package
+names (`rosett-ai`, `rosett-ai-gtk4`, `rosett-ai-kde`), and repository name are unchanged.
+
+Rationale: Path of least resistance. The acronym survives, all CLI
+commands stay `rosett-ai`, `.deb` package names don't change, git history is
+continuous.
+
+Scope: gemspec summary/description, CLAUDE.md headers, i18n strings,
+doc headers, CLI descriptions. SPDX copyright lines are unaffected
+(they reference the author, not the product).
+
+Note: GitLab project description must be updated manually by the
+project owner.
+
+### Q2: Generic vs Engine-Specific Layers
+
+**Decision**: Strict separation. The generic layer captures **only**
+human intent (behaviour rules, design constraints, coding standards).
+Engine-specific configuration lives entirely inside each engine's own
+config namespace (`conf/engines/<name>/`). No `extensions:` key in the
+generic schema.
+
+Each engine declares a **capability manifest** listing which generic
+features it supports. At compile time, rosett-ai warns about gaps:
+
+```text
+WARN  behaviour/security_internal.yml: sensitive filtering not supported
+      by cursor engine — file included without redaction (review manually)
+```
+
+Warnings are non-fatal by default. A `--strict` flag makes them fatal
+for CI gating.
+
+### Q3: Engine Registry Architecture
+
+**Decision**: Option C — **engine as namespace directory**. Each AI tool
+is a self-contained directory under `lib/rosett_ai/engines/<name>/` containing
+independent, optional components:
+
+```text
+lib/rosett_ai/engines/claude/
+  ├── backend.rb          # Compiler backend
+  ├── config_adapter.rb   # Settings compilation
+  ├── path_resolver.rb    # Output paths
+  ├── scaffolder.rb       # Init structure
+  ├── detector.rb         # Autodetection
+  ├── executor.rb         # API/CLI invocation (for quorum)
+  ├── validator.rb        # Output validation
+  └── manifest.yml        # Capabilities + required config + detection
+```
+
+Components are optional. A trivial engine (Cursor) may only have
+`backend.rb`, `detector.rb`, and `manifest.yml`. The engine registry
+discovers entire directories. No forced common interface — each
+component implements what's relevant and skips what isn't.
+
+### Q4: Config Compilation
+
+**Decision**: Config compilation moves inside each engine. The current
+`RosettAi::Config` namespace (KeyMap, ScopeRouter, DomainTransformer,
+Compiler) becomes `RosettAi::Engines::Claude::ConfigAdapter` internals.
+
+The `--target` flag is renamed to `--engine` universally. Default engine
+is configurable, suggested by autodetection at `bin/raictl init` time.
+
+Additional capabilities added to engine architecture:
+
+- **Autodetection**: Each engine can detect if its AI tool is installed
+  (binary in PATH, config directory exists, env vars set). Detection is
+  data-driven from the manifest, with optional Ruby override for custom
+  logic. CLI: `bin/raictl engines list|detect|status`.
+- **Quorum**: Separate module (`lib/rosett_ai/quorum/`) for dispatching the
+  same analysis to multiple engines and comparing results. Initial scope:
+  adopt use case only (structured findings comparison). Not an
+  orchestrator — rosett-ai stays configuration-focused.
+
+### Q5: Output Path Ownership
+
+**Decision**: XDG-compliant paths. rosett-ai owns `~/.config/rosett-ai/` for its
+own configuration. Compiled outputs deploy TO each engine's native
+directory.
+
+```text
+~/.config/rosett-ai/              # Rosett-AI's own config (XDG_CONFIG_HOME)
+  ├── config.yml             # default engine, quorum settings
+  ├── conf/behaviour/*.yml   # source YAML (human intent)
+  ├── conf/design/*.yml      # design documents
+  ├── conf/schemas/*.json    # validation schemas
+  └── conf/engines/          # per-engine config
+      ├── claude/
+      ├── cursor/
+      └── goose/
+
+# Compiled outputs deploy to each engine's native location:
+~/.claude/rules/                          # Claude
+./.cursorrules                            # Cursor
+./AGENTS.md                               # AGENTS.md
+./.github/copilot-instructions.md         # Copilot
+```
+
+Consistent with ADR-002 (PathResolver) and existing XDG research.
+
+### Q6: Adopt System
+
+**Decision**: Adopt defaults to local-only structural checks. API
+analysis is opt-in via `--api` flag. The `--api` flag is quorum-capable.
+
+```bash
+bin/raictl adopt                                    # Local only (default)
+bin/raictl adopt --api                              # Via default engine
+bin/raictl adopt --api --engine claude              # Via specific engine
+bin/raictl adopt --api --quorum                     # All invocable engines
+bin/raictl adopt --api --quorum --engines claude,ollama  # Specific set
+```
+
+The `anthropic` gem moves from rosett-ai core to the Claude engine's
+dependencies. Core rosett-ai has zero LLM API dependencies.
+
+### Q7: Engine Scope & Phasing
+
+**Decision**: Phased rollout, prioritising local testability:
+
+| Phase | Engines | Rationale |
+|-------|---------|-----------|
+| 0 | Claude (restructure), Generic (restructure) | Prove architecture |
+| 1 | AGENTS.md | First multi-engine story |
+| 2 | Ollama, GPT-NeoX | Local quorum without paid APIs |
+| 3 | Goose, Aider | CLI-invocable, richer config |
+| 4 | Cursor, Copilot, Windsurf | Trivial formats, large user bases |
+
+GPT-NeoX is a separate engine (not a model profile within Ollama) to
+ensure deployment independence. Air-gapped environments may run GPT-NeoX
+on vLLM, TGI, or custom inference without Ollama.
+
+### Q8: Migration Path
+
+**Decision**: Incremental migration. Version bump to **1.0.0** — the
+engine-agnostic architecture is the v1 identity.
+
+Engine Phase 0 splits into three sub-phases:
+
+- **0a**: Rename "Claude Companion" → "Code Companion", bump to 1.0.0
+- **0b**: Create `engines/` directory structure, move Claude + Generic
+- **0c**: XDG paths, `--engine` flag, detector framework
+
+Each sub-phase is a separate branch and merge request. Tests pass at
+every step. Existing `~/.claude/` workflows continue working — Claude
+engine writes to `~/.claude/rules/` as before.
+
+### Q9: Priority vs Desktop Integration
+
+**Decision**: Engine Phase 0 (restructure) lands first, then Desktop
+Phase 1 (D-Bus service) starts immediately after. The two workstreams
+are orthogonal — desktop integration is transport layer, engine
+architecture is content layer. They can interleave after Phase 0.
+
+## Consequences
+
+- ADR-006 is superseded (this ADR provides the concrete decisions it
+  deferred)
+- `architecture.yml` must be updated to reflect engine-agnostic core
+- A new design document `engine_architecture.yml` captures the engine
+  plugin system
+- The implementation plan defines 7 engine phases and 3 desktop phases
+  with explicit dependencies
+- All existing tests continue passing throughout the incremental
+  migration
+- The `anthropic` gem is removed from core runtime dependencies at
+  Phase 0b
+- Users on current `~/.claude/`-based installations experience no
+  breakage — the Claude engine continues to write to Claude-native paths

data/doc/decisions/008-ci-bundler-strategy.md

@@ -0,0 +1,129 @@
+# ADR-008: CI Bundler Strategy and Dependency Integrity
+
+## Status
+
+Accepted (2026-03-01)
+
+## Context
+
+The CI pipeline uses `.ruby_base` as the shared template for all Ruby jobs.
+This template runs `bundle install` in a Docker image (`ruby:3.3.10-bookworm`)
+without specifying which Bundler groups to include or exclude, and without
+pinning to a lockfile.
+
+Three problems emerged:
+
+1. **Native build failures**: The `:desktop` Bundler group contains the
+   `adwaita` gem, which transitively depends on `gobject-introspection`.
+   That gem requires `libgirepository1.0-dev` at build time. The CI Docker
+   image does not include this library, and the gem's auto-install attempt
+   fails without root privileges. No CI job needs GTK4 gems.
+
+2. **Version drift**: Without a committed `Gemfile.lock`, CI resolves
+   dependencies fresh on each run. RuboCop `~> 1.82` resolved to 1.85.0 in
+   CI while developers ran 1.84.2 locally. With `NewCops: enable` in
+   `.rubocop.yml`, new cops in 1.85.0 produced offenses that did not exist
+   in the local version, causing false CI failures.
+
+3. **Incomplete pre-commit linting**: The built-in overcommit `RuboCop`
+   hook only lints files in the commit diff. When a rubocop version update
+   introduces new cops, offenses in unchanged files are invisible to the
+   pre-commit hook. The CI rubocop job catches them, but the feedback loop
+   is slow and indirect.
+
+## Decisions
+
+### D1: Exclude the `:desktop` group in CI
+
+The `.ruby_base` template now runs:
+
+```yaml
+- bundle config set --local without 'desktop'
+```
+
+before `bundle install`. This prevents the entire GTK4 dependency chain
+(`adwaita -> gtk4 -> gsk4 -> gdk4 -> gdk_pixbuf2 -> gio2 ->
+gobject-introspection`) from being resolved and built in CI.
+
+**Rationale**: No CI job requires GTK4 gems. Desktop integration testing
+is deferred to a future dedicated job that would install system dependencies
+and override the `without` config.
+
+**Impact**: All jobs extending `.ruby_base` skip `:desktop` gems. If a
+desktop-specific CI job is ever needed, it must override the `before_script`
+to remove the `without` exclusion and install `libgirepository1.0-dev`,
+`libgtk-4-dev`, and related system packages.
+
+### D2: Track `Gemfile.lock` and freeze CI installs
+
+Two complementary changes:
+
+1. `Gemfile.lock` is removed from `.gitignore` and committed to the
+   repository. This captures exact resolved versions for all dependencies.
+
+2. The `.ruby_base` template now runs:
+
+   ```yaml
+   - bundle config set --local frozen true
+   ```
+
+   before `bundle install`. This makes CI fail immediately if the lockfile
+   does not match the Gemfile, preventing silent resolution to newer versions.
+
+**Rationale**: For application-like projects (as opposed to libraries),
+tracking the lockfile is standard practice. It ensures CI runs the same
+versions that developers test locally. The `frozen` flag enforces this.
+
+**Trade-off**: Developers must now run `bundle update <gem>` explicitly
+and commit the updated lockfile when upgrading dependencies. This is
+intentional friction that prevents accidental upgrades.
+
+### D3: Full-project RuboCop via custom overcommit hook
+
+The built-in overcommit `RuboCop` hook is disabled. A custom `RubocopAll`
+hook replaces it:
+
+- **File**: `.git-hooks/pre_commit/rubocop_all.rb`
+- **Behaviour**: Runs `bundle exec rubocop` against all project files, not
+  just changed files.
+- **Config**: Same flags as the original (`--config .rubocop.yml
+  --force-exclusion --display-cop-names`).
+
+**Rationale**: The per-file hook misses offenses in unchanged files. After
+a rubocop upgrade introduces new cops, the pre-commit hook must catch all
+offenses before they reach CI. Running rubocop on all ~245 files takes
+under 10 seconds, so the performance cost is acceptable.
+
+**Trade-off**: Every commit triggers a full rubocop scan regardless of
+what changed. For the current codebase size this is negligible, but may
+need revisiting if the project grows significantly.
+
+## Consequences
+
+### Positive
+
+- CI `bundle install` no longer attempts to build native GTK4 extensions.
+- All validate, code quality, security, test, and build jobs can run
+  without system-level GTK4 development libraries.
+- CI uses identical gem versions to development, eliminating false
+  positives from version drift.
+- Pre-commit hooks catch all rubocop offenses before code reaches CI.
+
+### Negative
+
+- Developers must explicitly update the lockfile: `bundle update <gem>`
+  followed by committing `Gemfile.lock`.
+- If a developer forgets to commit the lockfile after a Gemfile change,
+  CI will fail with a frozen bundle error. This is a feature, not a bug.
+- Pre-commit rubocop runs take ~10 seconds per commit instead of ~1 second
+  (full scan vs changed files only).
+
+## Files
+
+| File | Change |
+|------|--------|
+| `.gitlab-ci-files/global/defaults.yml` | Added `without 'desktop'` and `frozen true` to `.ruby_base` |
+| `.gitignore` | Removed `Gemfile.lock` entry |
+| `Gemfile.lock` | Now tracked |
+| `.overcommit.yml` | Disabled `RuboCop`, added `RubocopAll` |
+| `.git-hooks/pre_commit/rubocop_all.rb` | Custom overcommit hook |