rosett-ai 1.3.3

data/doc/decisions/002-path-resolution-strategy.md

@@ -0,0 +1,158 @@
+# ADR-002: Path Resolution Strategy
+
+## Status
+
+Accepted (2026-02-21)
+
+## Context
+
+raictl manages two distinct path domains:
+
+1. **Claude Code's directory** (`~/.claude/`) — rules, settings, CLAUDE.md.
+   This path is Anthropic's convention, established by Claude Code itself.
+   We do not own or control this convention.
+
+2. **rosett-ai's own configuration** (`~/.config/rosett-ai/`) — secrets, license keys,
+   content packs. This path is already established in our design documents
+   (`security.yml`, `licensing_system.yml`, `content_packs.yml`) and
+   implemented in `SecretsResolver`.
+
+Currently, 6 Thor task files contain hardcoded `~/.claude` paths:
+
+| File | Hardcoded path |
+|------|---------------|
+| `lib/rosett_ai/thor/tasks/init.rb` | `File.expand_path('~/.claude')` |
+| `lib/rosett_ai/thor/tasks/backup.rb` | `File.expand_path('~/.claude')` |
+| `lib/rosett_ai/thor/tasks/compile.rb` | `File.expand_path('~/.claude/rules')` |
+| `lib/rosett_ai/thor/tasks/adopt.rb` | `File.expand_path('~/.claude/rules')` |
+| `lib/rosett_ai/compiler/behaviour_compiler.rb` | `~/.claude/rules/` (string literal) |
+| `lib/rosett_ai/thor/tasks/backup.rb` | `File.join(Dir.pwd, '.claude')` (local) |
+
+The `architecture.yml` design document lists "hardcoded paths instead of
+XDG-compliant directory resolution" as an anti-pattern (line 64).
+
+### XDG Base Directory Specification
+
+The [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/latest/)
+from freedesktop.org defines standard locations for user files:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `XDG_CONFIG_HOME` | `~/.config` | User-specific configuration |
+| `XDG_DATA_HOME` | `~/.local/share` | User-specific data files |
+| `XDG_CACHE_HOME` | `~/.cache` | Non-essential cached data |
+| `XDG_STATE_HOME` | `~/.local/state` | User-specific state data |
+
+Desktop environment compliance:
+
+| DE | XDG compliant | Notes |
+|----|--------------|-------|
+| GNOME | Yes | freedesktop.org founding member |
+| KDE Plasma | Yes | KDE UserBase documented |
+| XFCE | Yes | Adopted spec |
+| MATE | Yes | GNOME 2 fork, inherited |
+| Cinnamon | Yes | GNOME fork, inherited |
+| Headless/TTY | N/A | No DE; apps read env vars or use defaults |
+| Tiling WMs | N/A | Apps decide individually |
+
+Ruby ecosystem: RubyGems 3.0+ follows XDG. Pry follows XDG. Bundler supports
+it with environment variables.
+
+Sources:
+[ArchWiki XDG Base Directory](https://wiki.archlinux.org/title/XDG_Base_Directory),
+[freedesktop.org spec](https://specifications.freedesktop.org/basedir/latest/),
+[KDE XDG Hierarchy](https://userbase.kde.org/KDE_System_Administration/XDG_Filesystem_Hierarchy).
+
+## Options
+
+### Option A: PathResolver (centralise, keep ~/.claude)
+
+Create a single `RosettAi::PathResolver` module that owns all path constants.
+Claude Code paths stay at `~/.claude` (respecting upstream convention). rosett-ai's
+own config uses `XDG_CONFIG_HOME/rosett-ai` (defaults to `~/.config/rosett-ai`). All
+hardcoded paths in Thor tasks are replaced with `PathResolver.rules_dir`,
+`PathResolver.global_dir`, etc.
+
+Pros:
+
+- Single source of truth — one file to update if conventions change
+- Testable: specs override PathResolver methods, no filesystem coupling
+- DE-agnostic: works on any desktop environment or headless
+- Consistent with existing design docs (SecretsResolver already uses
+  `~/.config/rosett-ai/`)
+- Respects both upstream convention (Claude Code) and XDG (rosett-ai data)
+
+Cons:
+
+- Still "hardcodes" `~/.claude`, just centralised in one place
+- New dependency for all path-using code
+
+### Option B: Full XDG everywhere
+
+Move both Claude Code AND rai config under XDG directories. Claude Code rules
+would move to something like `~/.local/share/rosett-ai/claude/rules`.
+
+Pros:
+
+- Maximum standards compliance with freedesktop.org
+
+Cons:
+
+- Breaking change: Claude Code expects `~/.claude/`
+- Users must reconfigure or symlink existing `~/.claude`
+- Fights upstream convention for no practical gain
+- Claude Code itself does not follow XDG
+
+### Option C: Status quo + ADR (no code change)
+
+Document why we keep `~/.claude` and stop there.
+
+Pros:
+
+- No code changes needed
+
+Cons:
+
+- Hardcoded paths remain scattered across 6+ files
+- Every new feature adds more hardcoded paths
+- Testing remains coupled to filesystem (cannot mock paths)
+- Future refactor scope grows with each commit
+- Path changes require grep-and-replace with risk of partial updates
+- architecture.yml anti-pattern stays unresolved
+
+## Decision
+
+**Option A: PathResolver** — centralise all paths in `RosettAi::PathResolver` with
+dual-domain separation.
+
+Rationale:
+
+- We do not own `~/.claude` — Anthropic does. Changing it would break the
+  Claude Code integration that rosett-ai exists to manage.
+- We already use `~/.config/rosett-ai` for our own data (secrets, future license
+  keys, content packs). This is XDG-compliant.
+- Centralising eliminates the scattered-hardcoding anti-pattern without
+  fighting upstream conventions.
+- Testability: specs can override `PathResolver.global_dir` or inject a
+  mock, removing filesystem coupling from unit tests.
+- If Claude Code ever changes its directory convention, one file changes
+  instead of 6+.
+
+## Consequences
+
+- New file: `lib/rosett_ai/path_resolver.rb` with instance methods (future-proofed
+  for ADR-006 multi-engine via `engine:` keyword)
+- All 6 Thor task files + compiler updated to use `RosettAi.paths.*`
+- `~/.config/rosett-ai/` created by `bin/raictl init --global` alongside `~/.claude/`
+- `XDG_CONFIG_HOME` respected for rosett-ai data (non-default setups work)
+- `SecretsResolver` updated to use `RosettAi.paths.rai_config_dir` instead of
+  its own hardcoded `File.join(Dir.home, '.config', 'rosett-ai')`
+- `SECRETS_DIR` and `SECRETS_FILE` constants removed from SecretsResolver
+- Lockfile output uses `rules_display_path` (tilde form) for portability
+- Specs use `instance_double(RosettAi::PathResolver)` instead of `stub_const` or
+  `allow(File).to receive(:expand_path)` — cleaner, no filesystem coupling
+- Future: if Claude Code changes conventions, one file to update
+
+## Implementation
+
+Implemented in Phase 3 (2026-02-21). See `doc/changes/2026-02-21-path-resolver.md`.

data/doc/decisions/003-ui-adapter-selection.md

@@ -0,0 +1,193 @@
+# ADR-003: UI Adapter Selection Mechanism
+
+## Status
+
+Accepted (2026-02-21) -- implementation deferred to P3
+
+## Context
+
+The `RosettAi::Ui::Registry` pattern is implemented. UI adapters register
+themselves at require time (`Registry.register(:tui, Tui)`), and
+`Registry.resolve(name)` instantiates the requested adapter. Currently only
+the TUI adapter exists and it is selected automatically as the default.
+
+When GUI packages (`rosett-ai-gtk4`, `rosett-ai-qt6`) are introduced (P3), users will
+need a mechanism to select which adapter to use. The `architecture.yml` design
+document gives the example `bin/raictl --ui gtk4`, and the `ui_framework.yml`
+document states TUI is the default with GUI packages as separate Debian
+packages.
+
+The selection mechanism must be decided now (P2) so the architecture is ready
+for P3 implementation.
+
+### Existing precedent
+
+raictl already uses an ordered resolution pattern in `SecretsResolver`:
+ENV variable > secrets file > raise error. This pattern is understood and
+tested.
+
+### Multi-engine constraint
+
+ADR-006 establishes that rosett-ai should be engine-agnostic. The UI adapter
+selection must therefore not depend on any engine-specific configuration
+file (e.g. Claude Code's `settings.json`). The UI adapter is an rosett-ai
+concern and must be resolved from rosett-ai's own configuration.
+
+## Options
+
+### Option A: Global CLI flag only
+
+Add `--ui NAME` as a `class_option` on `Thor::CLI` (inherited by all
+subcommands). Selection happens via `Registry.resolve(options[:ui])`.
+
+Pros:
+
+- Explicit, visible in help output
+- No configuration infrastructure needed
+
+Cons:
+
+- Must be passed every invocation
+- No way to set a persistent default
+
+### Option B: Config file setting only
+
+Add `preferred_ui: gtk4` to rosett-ai's own configuration. Read at startup.
+
+Pros:
+
+- Set once, works always
+- Aligns with rosett-ai's own config infrastructure
+
+Cons:
+
+- No quick override for one-off invocations
+
+### Option C: Environment variable only
+
+Read `RAI_UI` environment variable. Default to `tui` if unset.
+
+Pros:
+
+- Simple, shell-profile level persistence
+- No code infrastructure needed
+
+Cons:
+
+- Less discoverable than CLI flag
+- Not visible in `--help` output
+
+### Option D: Cascade precedence (revised)
+
+Resolution order:
+
+```text
+1. --ui NAME          CLI flag override (highest priority)
+2. RAI_UI            Environment variable (session-level)
+3. rai config        Ordered adapter list (first available wins)
+4. DE auto-detection  Detect runtime desktop environment
+5. :tui               Always-available fallback (lowest priority)
+```
+
+Each layer is consulted in order. The first layer that produces a result
+wins. Layers 3-5 check adapter availability via `Registry.available?`
+before selecting — an adapter whose package is not installed is skipped.
+
+Layer 3 -- rai config adapter list:
+
+The rai configuration file (`~/.config/rosett-ai/`) contains an ordered
+array of preferred adapters. The first adapter in the list whose package
+is installed wins:
+
+```yaml
+ui:
+  adapters:
+    - gtk4
+    - qt6
+    - tui
+```
+
+Array position is priority — no explicit priority numbers needed. This
+is simpler and YAML arrays are inherently ordered. If per-project
+overrides with cross-source merging are needed in the future, explicit
+priority numbers can be added without breaking the simple form.
+
+Layer 4 -- Desktop environment auto-detection:
+
+When no explicit preference is configured, rosett-ai detects the running
+desktop environment at runtime via XDG environment variables and selects
+a matching adapter if its package is installed:
+
+| Env var | Value | Adapter |
+|---------|-------|---------|
+| `XDG_CURRENT_DESKTOP` | `GNOME` | gtk4 |
+| `XDG_CURRENT_DESKTOP` | `KDE` | qt6 |
+| `XDG_CURRENT_DESKTOP` | `XFCE` | gtk4 (GTK-based) |
+| `XDG_CURRENT_DESKTOP` | `MATE` | gtk4 (GTK-based) |
+| `XDG_CURRENT_DESKTOP` | `Cinnamon` | gtk4 (GTK-based) |
+| `XDG_SESSION_TYPE` | `tty` | tui |
+| Unset / empty | -- | tui |
+
+Note: `XDG_CURRENT_DESKTOP` can be colon-separated (e.g. `ubuntu:GNOME`).
+The detection logic must handle this by checking each component.
+
+Auto-detection only suggests adapters whose packages are installed. If
+`XDG_CURRENT_DESKTOP=GNOME` but `rosett-ai-gtk4` is not installed, detection
+falls through to TUI.
+
+Pros:
+
+- Most flexible — covers all use cases
+- Follows principle of least surprise
+- Consistent with existing `SecretsResolver` precedence pattern
+- Users can set-and-forget via env or config
+- Power users can override per-invocation
+- Zero-config experience: install rosett-ai + rosett-ai-gtk4 on GNOME, it just works
+- Users can switch desktop environments without reconfiguring rosett-ai
+- Engine-agnostic: no dependency on any AI engine's config format
+
+Cons:
+
+- 5 levels to test
+- Debug confusion if user forgets they set an env var or config
+
+The debug confusion is mitigated by the `rai config show` command (see
+Consequences below).
+
+## Decision
+
+**Option D: Cascade precedence (revised)** — because:
+
+- Consistent with the existing resolution pattern in `SecretsResolver`
+  (ENV > file > raise). Adding a CLI flag as highest priority and
+  auto-detection as a smart fallback is a natural extension.
+- Every use case is covered: one-off override (flag), session default
+  (env), persistent preference (config), smart default (DE detection),
+  and guaranteed fallback (TUI).
+- Engine-agnostic: the cascade uses rosett-ai's own configuration, not any
+  engine-specific settings file. This aligns with ADR-006.
+- When `rosett-ai-gtk4` is installed on a GNOME desktop, it works out of the
+  box with zero configuration via auto-detection. The user can still
+  override with `--ui tui` for a headless session.
+- The cascade is simple to explain: "flag wins, then env, then config
+  list, then desktop detection, then TUI".
+
+## Consequences
+
+Implementation is deferred to P3 (ui_framework), but the architecture is
+documented now:
+
+- New `class_option :ui` on `Thor::CLI` (type: string, default: nil)
+- Resolution logic in a `resolve_ui_adapter` method that implements the
+  5-level cascade
+- `Registry.resolve` called once at CLI startup with the resolved name
+- `Registry.available?(name)` used at layers 3-5 to skip missing adapters
+- Adapter instance available to tasks that produce output
+- `RAI_UI` documented in `bin/raictl --help` and `doc/USAGE.md`
+- New CLI commands for configuration transparency (P3):
+  - `bin/raictl config show` — display full rai configuration
+  - `bin/raictl config show ui` — display UI configuration with active
+    adapter and resolution source (e.g. "gtk4 (from: DE auto-detection)")
+- Desktop environment detection via `XDG_CURRENT_DESKTOP` and
+  `XDG_SESSION_TYPE`, with colon-separated value handling
+- P2 code does not need the flag yet — TUI is the only adapter

data/doc/decisions/004-design-document-validation.md

@@ -0,0 +1,179 @@
+# ADR-004: Design Document Validation
+
+## Status
+
+Accepted (2026-02-21)
+
+## Context
+
+The `architecture.yml` design document (criterion 6) requires that
+`conf/design/` documents are validated against `conf/schemas/design_schema.json`.
+
+The schema already exists (206 lines, comprehensive) and covers all required
+fields: name, domain, version, status, intent, constraints, acceptance_criteria,
+plus optional sections for examples, anti_patterns, preferences, assets,
+tui_layout, gui_notes, interactions, and accessibility.
+
+There are currently 13 design documents in `conf/design/`. No validation
+infrastructure exists for them.
+
+### Existing pattern
+
+`RosettAi::Validators::BehaviourValidator` validates behaviour configuration files
+against `conf/schemas/behaviour_schema.json`. It uses JSONSchemer, provides a
+`valid?`/`validate`/`errors` API, and is wired into the CLI via
+`bin/raictl behaviour validate [NAME]`. This is a proven, tested pattern.
+
+### Current schema inventory
+
+Three schemas exist in `conf/schemas/`, but only one has a validator:
+
+| Schema file | Validator class | CLI command | CI job |
+|-------------|----------------|-------------|--------|
+| `behaviour_schema.json` | `BehaviourValidator` | `behaviour validate` | Yes |
+| `design_schema.json` | *(none)* | *(none)* | *(none)* |
+| `tooling_schema.json` | *(none)* | *(none)* | *(none)* |
+
+This ADR addresses all three — not just design documents.
+
+### Code duplication concern
+
+`BehaviourValidator` is 80 lines. Creating a `DesignValidator` and a
+`ToolingValidator` with the same logic but different schema paths would be
+near-duplicates. With further validators coming in P2 (compiler, CC
+configuration), duplication becomes a maintenance burden.
+
+## Options
+
+### Option A: Dedicated validator class per schema
+
+Mirror `BehaviourValidator` exactly for each schema — same interface,
+different schema path.
+
+```ruby
+class DesignValidator
+  SCHEMA_PATH = 'conf/schemas/design_schema.json'
+  # ... identical logic to BehaviourValidator
+end
+```
+
+Pros:
+
+- Consistent pattern, easy to understand
+- No refactoring of existing code
+
+Cons:
+
+- Near-duplicate of `BehaviourValidator` (same logic, different constant)
+- Each future validator adds another copy
+- Bug fixes must be applied to all copies
+
+### Option B: Generic SchemaValidator with schema parameter
+
+Extract the shared logic into `RosettAi::Validators::SchemaValidator`. Accept
+the schema filename in the constructor. All validators become thin wrappers.
+
+```ruby
+class SchemaValidator
+  def initialize(schema:)
+    @schema_path = RosettAi.root.join('conf', 'schemas', schema)
+    # ... shared logic
+  end
+end
+
+# Thin wrappers
+class BehaviourValidator < SchemaValidator
+  def initialize = super(schema: 'behaviour_schema.json')
+end
+
+class DesignValidator < SchemaValidator
+  def initialize = super(schema: 'design_schema.json')
+end
+
+class ToolingValidator < SchemaValidator
+  def initialize = super(schema: 'tooling_schema.json')
+end
+```
+
+Pros:
+
+- DRY: shared validation logic in one place
+- Extensible: future validators reuse the same base
+- Existing API stays identical (`valid?`, `validate`, `errors`)
+- Bug fixes apply once
+
+Cons:
+
+- Refactor touches `BehaviourValidator` (existing tests must still pass)
+- Slightly more abstract (one level of inheritance)
+
+### Option C: Validation in compile step only
+
+Validate documents only when the compiler reads them. No standalone command.
+
+Pros:
+
+- No new CLI command needed
+- Validation happens where it matters
+
+Cons:
+
+- Errors only surface during compilation, not during authoring
+- No way to validate documents without a compile cycle
+- CI cannot validate documents independently of compilation
+
+## Decision
+
+**Option B: Generic SchemaValidator** — because:
+
+- DRY is justified: 3 validators today (behaviour, design, tooling), with
+  compiler and CC configuration confirmed for P2. This is not premature
+  abstraction — multiple consumers already exist.
+- The existing `BehaviourValidator` API (`valid?`, `validate`, `errors`)
+  does not change. Existing tests continue to pass.
+- Future validators become one-line subclasses.
+- CI can validate each document category independently.
+
+## Acceptance criteria
+
+1. `SchemaValidator` base class has its own spec covering the full API
+   (`valid?`, `validate`, `errors`, error reset, missing file, bad YAML,
+   missing schema, invalid JSON schema)
+2. Every subclass has its own spec proving correct schema wiring and
+   successful validation of all real documents in its category
+3. For every `conf/schemas/*_schema.json` file, a corresponding validator
+   class exists in `lib/rosett_ai/validators/`, with a spec and a CI job
+4. For every validator class in `lib/rosett_ai/validators/`, a corresponding
+   schema file exists in `conf/schemas/` (no orphan validators)
+5. Existing `BehaviourValidator` spec passes unchanged after the refactor
+
+## Consequences
+
+- Extract: `BehaviourValidator` logic moves to `SchemaValidator` base class
+- `BehaviourValidator` becomes a thin wrapper inheriting from `SchemaValidator`
+- New: `DesignValidator` wrapper inheriting from `SchemaValidator`
+- New: `ToolingValidator` wrapper inheriting from `SchemaValidator`
+- New CLI: `bin/raictl design validate [NAME]` — validates design docs
+- New CLI: `bin/raictl tooling validate [NAME]` — validates tooling docs
+- New CI jobs in validate stage for design and tooling documents
+- Existing `BehaviourValidator` tests pass unchanged (same API)
+- Future P2 validators (compiler, CC config) inherit from `SchemaValidator`
+- Acceptance criteria 3-4 can be enforced by a CI check that compares
+  schema files against validator classes, ensuring neither side drifts
+
+### File changes
+
+| Action | File |
+|--------|------|
+| New | `lib/rosett_ai/validators/schema_validator.rb` |
+| Refactor | `lib/rosett_ai/validators/behaviour_validator.rb` (inherits SchemaValidator) |
+| New | `lib/rosett_ai/validators/design_validator.rb` |
+| New | `lib/rosett_ai/validators/tooling_validator.rb` |
+| New | `lib/rosett_ai/thor/tasks/design.rb` |
+| Modify | `lib/rosett_ai/thor/tasks/tooling.rb` (add validate subcommand) |
+| New | `.gitlab-ci-files/validate/design-docs.yml` |
+| New | `.gitlab-ci-files/validate/tooling-docs.yml` |
+| Modify | `lib/rosett_ai/thor/cli.rb` (add design subcommand) |
+| New | `spec/rosett_ai/validators/schema_validator_spec.rb` |
+| New | `spec/rosett_ai/validators/design_validator_spec.rb` |
+| New | `spec/rosett_ai/validators/tooling_validator_spec.rb` |