rosett-ai 1.3.3

data/doc/SESSION_2026-02-28_GTK4_HARDENING.md

@@ -0,0 +1,359 @@
+# Session Documentation: GTK4 Application Hardening & GUI Logging
+
+**Date:** 2026-02-28
+**Branch:** `engine/1-agents-md` (to be merged or rebased)
+**Status:** In Progress - Paused for breakfast
+
+## Executive Summary
+
+This session focused on making the GTK4 desktop application crash-proof and adding
+comprehensive debugging capabilities through structured GUI action logging.
+
+## Work Completed
+
+### 1. GTK4 Application Hardening
+
+The GTK4 application was completely rewritten with defensive programming principles
+to ensure it **never crashes** on user interaction.
+
+#### Files Modified
+
+| File | Purpose |
+|------|---------|
+| `lib/rosett_ai/desktop/dbus_client.rb` | D-Bus client with safe defaults |
+| `lib/rosett_ai/desktop/gtk4_app.rb` | Main GTK4 app with safe_action wrapper |
+| `lib/rosett_ai/desktop/gtk4_preferences.rb` | Preferences dialog with graceful degradation |
+| `lib/rosett_ai/desktop/gui_logger.rb` | **NEW** - Structured JSON logging for debugging |
+
+### 2. Safety Architecture
+
+```mermaid
+flowchart TB
+    subgraph UserAction["User Action"]
+        click["Button Click / Menu Selection"]
+    end
+
+    subgraph SafetyLayer["Safety Layer"]
+        safe_action["safe_action()"]
+        safe_callback["safe_callback()"]
+    end
+
+    subgraph Logging["Logging Layer"]
+        gui_logger["GuiLogger.action()"]
+        json_output["JSON Lines Output"]
+    end
+
+    subgraph ErrorHandling["Error Handling"]
+        rescue["rescue StandardError"]
+        dialog["show_error_dialog()"]
+        toast["show_toast()"]
+    end
+
+    subgraph BusinessLogic["Business Logic"]
+        dbus["DbusClient"]
+        safe_defaults["Safe Defaults"]
+    end
+
+    click --> safe_action
+    safe_action --> gui_logger
+    gui_logger --> rescue
+    rescue -->|success| BusinessLogic
+    rescue -->|error| dialog
+    dialog --> toast
+
+    dbus -->|always returns| safe_defaults
+```
+
+### 3. Design Principles Applied
+
+```mermaid
+mindmap
+  root((GTK4 Safety))
+    Never Crash
+      Wrap all handlers
+      Catch StandardError
+      Show error dialog
+    Safe Defaults
+      D-Bus returns defaults
+      Never raise to GUI
+      Graceful degradation
+    Logging
+      JSON Lines format
+      Action tracking
+      Full backtraces
+    Version Compatibility
+      Check defined?
+      Fallback widgets
+      PreferencesWindow fallback
+```
+
+## Decision Log
+
+### Decision 1: Error Handling Strategy
+
+**Context:** Application crashed when clicking Preferences menu.
+
+**Options Considered:**
+
+1. Fix specific crash only
+2. Add targeted try/catch blocks
+3. Comprehensive safety wrapper architecture
+
+**Decision:** Option 3 - Wrap ALL event handlers with `safe_action()` pattern.
+
+**Rationale:** User explicitly stated: *"It is imperative that the application is
+robust and does not crash under any circumstances of usage."*
+
+```mermaid
+flowchart LR
+    A[User Action] --> B{safe_action wrapper}
+    B -->|Success| C[Complete normally]
+    B -->|Error| D[Log error]
+    D --> E[Show error dialog]
+    E --> F[Continue running]
+```
+
+### Decision 2: D-Bus Client Safety
+
+**Context:** D-Bus operations can fail (service unavailable, method not found).
+
+**Decision:** D-Bus client NEVER raises exceptions. All methods return safe defaults.
+
+```ruby
+# Safe defaults defined as constants
+SAFE_STATUS = { 'error' => 'Service not available', 'version' => 'unknown' }.freeze
+SAFE_FOCUS = ['', ''].freeze
+SAFE_COMPILE_RESULT = 'Error: D-Bus service not available'
+```
+
+### Decision 3: GUI Logging System
+
+**Context:** Need to debug GUI issues without attaching debugger.
+
+**Decision:** Implement structured JSON Lines logging controlled by environment
+variables.
+
+```mermaid
+flowchart TB
+    subgraph Environment["Environment Variables"]
+        RAI_GUI_LOG["RAI_GUI_LOG=1"]
+        RAI_GUI_LOG_FILE["RAI_GUI_LOG_FILE=/path"]
+        RAI_GUI_LOG_LEVEL["RAI_GUI_LOG_LEVEL=debug"]
+    end
+
+    subgraph Logger["GuiLogger"]
+        action["action()"]
+        callback["callback()"]
+        dbus_call["dbus_call()"]
+        error["error()"]
+    end
+
+    subgraph Output["Output"]
+        stderr["stderr"]
+        file["Log File"]
+        json["JSON Lines Format"]
+    end
+
+    Environment --> Logger
+    Logger --> json
+    json --> stderr
+    json --> file
+```
+
+**Usage:**
+
+```bash
+RAI_GUI_LOG=1 RAI_GUI_LOG_FILE=/tmp/rosett-ai-gui.log bin/raictl desktop gtk4
+```
+
+**Log Format:**
+
+```json
+{"timestamp":"2026-02-28T06:21:05.991Z","level":"info","event":"action_start"}
+```
+
+### Decision 4: libadwaita Version Compatibility
+
+**Context:** System has two libadwaita versions:
+
+- Linuxbrew: 1.8.4 (newer)
+- Debian: 1.2.2-1 (GIR typelib source)
+
+**Decision:** Use `defined?` checks and graceful fallbacks.
+
+```mermaid
+flowchart TD
+    A[Create Preferences Dialog] --> B{defined? PreferencesDialog}
+    B -->|Yes| C[Use PreferencesDialog]
+    B -->|No| D{defined? PreferencesWindow}
+    D -->|Yes| E[Use PreferencesWindow]
+    D -->|No| F[Return nil, log error]
+
+    C --> G[present with parent arg]
+    E --> H[set transient_for]
+    H --> I[present without args]
+```
+
+## Library Version Status
+
+### Ruby Gems (Latest)
+
+| Gem | Installed | Latest | Status |
+|-----|-----------|--------|--------|
+| adwaita | 4.3.5 | 4.3.5 | Current |
+| gtk4 | 4.3.5 | 4.3.5 | Current |
+| glib2 | 4.3.5 | 4.3.5 | Current |
+| ruby-dbus | 0.25.0 | 0.25.0 | Current |
+
+### System Libraries
+
+| Library | Version | Source | Notes |
+|---------|---------|--------|-------|
+| libadwaita | 1.8.4 | Linuxbrew | Used by pkg-config |
+| libadwaita | 1.2.2-1 | Debian | Provides GIR typelib |
+| GIR typelib | 1.2.2 | Debian | Limits available classes |
+
+**Impact:** `PreferencesDialog` (added in libadwaita 1.4) is not available to Ruby
+bindings. Code gracefully falls back to `PreferencesWindow`.
+
+## Architecture Overview
+
+```mermaid
+graph TB
+    subgraph Desktop["Desktop Layer"]
+        GTK4["Gtk4App"]
+        Prefs["Gtk4Preferences"]
+        Logger["GuiLogger"]
+    end
+
+    subgraph IPC["IPC Layer"]
+        DBus["DbusClient"]
+    end
+
+    subgraph Service["D-Bus Service"]
+        Manager["Manager Interface"]
+        Focus["FocusMonitor Interface"]
+    end
+
+    GTK4 --> Logger
+    GTK4 --> DBus
+    GTK4 --> Prefs
+    Prefs --> Logger
+    Prefs --> DBus
+    DBus --> Manager
+    DBus --> Focus
+
+    Logger -->|JSON Lines| File["Log File"]
+    Logger -->|JSON Lines| Stderr["stderr"]
+```
+
+## Testing Results
+
+### Manual Testing Performed
+
+| Test | Result | Notes |
+|------|--------|-------|
+| App launch | Pass | Starts without crash |
+| Hamburger - Preferences | Pass | Opens dialog (uses fallback PreferencesWindow) |
+| Hamburger - About | Pass | Opens about window |
+| Compile Rules action | Pass | Shows toast with error (D-Bus service not running) |
+| Ctrl+Q quit | Pass | Clean shutdown |
+| Error logging | Pass | JSON Lines captured in log file |
+
+### Log Analysis
+
+Sample log showing successful action tracking:
+
+```text
+action_start: on_activate (599ms)
+action_start: show_preferences (17ms)
+action_start: show_about (39ms)
+action_start: on_compile_clicked (9ms)
+info: Application shutdown
+```
+
+## Pending Work
+
+### Immediate (Next Session)
+
+1. **Commit Changes** - All hardened files need to be committed
+2. **Integration Tests** - Add automated tests for GUI resilience
+3. **GIR Version** - Consider upgrading gir1.2-adw-1 for PreferencesDialog
+
+### Future Considerations
+
+```mermaid
+gantt
+    title Remaining GTK4 Work
+    dateFormat  YYYY-MM-DD
+    section Hardening
+    Commit current changes     :done, 2026-02-28, 1d
+    Add integration tests      :active, 2026-02-28, 2d
+    section Compatibility
+    Investigate GIR upgrade    :2026-03-01, 1d
+    Test on other systems      :2026-03-01, 2d
+    section Features
+    Implement D-Bus methods    :2026-03-02, 3d
+    Add preference persistence :2026-03-03, 2d
+```
+
+## How to Resume
+
+### On This Workstation
+
+```bash
+cd /home/hugo/git/Neatnerds/Anthropic/rosett-ai
+git status  # Check uncommitted changes
+```
+
+### On Another Workstation
+
+```bash
+git clone <repo-url>
+cd rosett-ai
+git checkout <branch-name>
+bundle install
+# Read this document for context
+```
+
+### Running the GTK4 App
+
+```bash
+# Without logging
+bundle exec bin/raictl desktop gtk4
+
+# With debug logging
+RAI_GUI_LOG=1 RAI_GUI_LOG_LEVEL=debug \
+  RAI_GUI_LOG_FILE=/tmp/rosett-ai-gui.log bundle exec bin/raictl desktop gtk4
+```
+
+## File Change Summary
+
+```text
+lib/rosett_ai/desktop/
+├── dbus_client.rb        # Modified: Safe defaults, never raises
+├── gtk4_app.rb           # Modified: safe_action wrapper, GuiLogger
+├── gtk4_preferences.rb   # Modified: safe_callback, version checks
+└── gui_logger.rb         # NEW: Structured JSON logging
+```
+
+## Conversation Context
+
+This session continued from a previous context where:
+
+- Engine Phase 1 (AGENTS.md) was completed
+- Engine Phase 2 (Ollama/GPT-NeoX) was completed
+- Desktop Phase 1 (D-Bus service) was completed
+- Desktop Phase 2 (GTK4 app) had crash issues
+
+The user's key requirement:
+
+> "It is imperative that the application is robust and does not crash under any
+> circumstances of usage. I am fully aware this is asking much but let's invest
+> the time and effort to make this reliable, security-aware and safe above speed
+> and snappiness."
+
+---
+
+*Document generated: 2026-02-28*
+*Session paused for breakfast*

data/doc/SETUP.md

@@ -0,0 +1,202 @@
+# Rosett-AI - Setup Guide
+
+## Prerequisites
+
+### Ruby 3.3.10 via rbenv
+
+This project requires Ruby 3.3.10. We use rbenv for Ruby version management.
+
+#### Installing rbenv
+
+```bash
+# On Debian/Ubuntu
+sudo apt-get update
+sudo apt-get install -y git curl autoconf bison build-essential \
+  libssl-dev libyaml-dev libreadline6-dev zlib1g-dev \
+  libncurses5-dev libffi-dev libgdbm6 libgdbm-dev libdb-dev
+
+# Install rbenv
+git clone https://github.com/rbenv/rbenv.git ~/.rbenv
+echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
+echo 'eval "$(rbenv init -)"' >> ~/.bashrc
+source ~/.bashrc
+
+# Install ruby-build plugin
+git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
+```
+
+#### Installing Ruby 3.3.10
+
+```bash
+# Install Ruby 3.3.10
+rbenv install 3.3.10
+
+# Verify installation
+rbenv versions
+
+# The .ruby-version file will automatically select 3.3.10 in this directory
+cd ~/.claude
+ruby --version  # Should show ruby 3.3.10
+```
+
+## Installation
+
+### 1. Clone/Initialize Repository
+
+If you haven't already initialized the repository:
+
+```bash
+cd ~/.claude
+git init
+```
+
+### 2. Install Dependencies
+
+```bash
+bundle install
+```
+
+This installs all Bundler groups including `:desktop` (GTK4). If you do not
+need desktop features or lack the GTK4 system libraries, exclude the group:
+
+```bash
+bundle config set --local without 'desktop'
+bundle install
+```
+
+For desktop development, install system dependencies first:
+
+```bash
+sudo apt-get install -y libgirepository1.0-dev libgtk-4-dev
+bundle install
+```
+
+### 3. Install Git Hooks (CRITICAL)
+
+**Important:** This step is mandatory. Without git hooks, code quality checks will not run before commits.
+
+```bash
+# Install overcommit hooks
+overcommit --install
+
+# Verify hooks are installed correctly
+ls -la .git/hooks/pre-commit && echo "✓ Pre-commit hook installed" || echo "✗ Hook installation failed"
+
+# Test the hooks work
+bundle exec overcommit --run
+```
+
+### 4. Verify Installation
+
+```bash
+# Check CLI works
+bin/raictl version
+
+# Run tests
+bundle exec rspec
+
+# Run mutation testing
+bundle exec mutant run
+
+# Run linter
+bundle exec rubocop
+
+# Check for CVEs
+bundle exec bundler-audit check
+```
+
+## Configuration
+
+### Global Settings
+
+Edit `settings.json` to configure global Claude Code permissions:
+
+```json
+{
+  "permissions": {
+    "allow": ["Bash(bundle:*)"],
+    "deny": ["Read(/home/user/.ssh/**)"]
+  }
+}
+```
+
+### Local Overrides
+
+Create `settings.local.json` for machine-specific settings (gitignored):
+
+```json
+{
+  "permissions": {
+    "additionalDirectories": ["/custom/path"]
+  }
+}
+```
+
+## Troubleshooting
+
+### Ruby version mismatch
+
+If you see "Your Ruby version is X, but your Gemfile specified 3.3.10":
+
+```bash
+rbenv install 3.3.10
+rbenv local 3.3.10
+```
+
+### Bundler issues
+
+If gems fail to install:
+
+```bash
+gem install bundler
+bundle config set --local path 'vendor/bundle'
+bundle install
+```
+
+### Permission errors
+
+Ensure the bin/raictl is executable:
+
+```bash
+chmod +x bin/raictl
+```
+
+## Updating Dependencies
+
+`Gemfile.lock` is tracked in git and CI uses frozen mode (see ADR-008).
+Always commit lockfile changes explicitly.
+
+To update a specific gem:
+
+```bash
+bundle update <gem-name>
+bundle exec rspec                 # verify tests pass
+bundle exec rubocop               # verify no new offenses
+bundle exec bundler-audit check   # verify no CVEs
+git add Gemfile.lock
+git commit -m "chore(deps): update <gem-name> to X.Y.Z"
+```
+
+To update all dependencies:
+
+```bash
+bundle update
+bundle exec rspec && bundle exec rubocop
+bundle exec bundler-audit check
+git add Gemfile.lock
+git commit -m "chore(deps): update all dependencies"
+```
+
+## Uninstalling
+
+To remove the project while preserving Claude Code data:
+
+```bash
+# Remove only the rosett-ai-related files
+rm -rf bin/ lib/ spec/ doc/ conf/
+rm -f Gemfile Gemfile.lock rosett-ai.gemspec Rakefile
+rm -f .ruby-version .rubocop.yml .reek.yml .rspec
+rm -f .overcommit.yml .gitleaks.toml
+rm -rf .gitlab-ci-files/ .gitlab-ci.yml
+rm -rf .git/
+```

data/doc/TEST_PEER_REVIEW.md

@@ -0,0 +1,152 @@
+# Test Peer Review Process
+
+## Overview
+
+The test peer review process provides structured, human-verified quality
+assurance for all test suites across the rosett-ai ecosystem. It uses a
+questionnaire-based approach where each spec file is examined through 10
+standardized questions that expose gaps, redundancy, incorrect assumptions,
+and missing edge cases.
+
+## Why This Exists
+
+When AI generates both code and tests, the test suite can be perfectly
+consistent yet meaningless — tests that mirror the implementation rather than
+validate behaviour. The peer review process creates an independent human
+verification layer that cannot be short-circuited by AI.
+
+## Scope
+
+| Repository | Spec Files | Examples |
+|-----------|-----------|----------|
+| rosett-ai (core) | 141 | ~1,637 |
+| rosett-ai-engine-claude | 8 | ~104 |
+| rosett-ai-engine-aider | 4 | ~42 |
+| rosett-ai-engine-goose | 4 | ~42 |
+| rosett-ai-engine-gpt-neox | 4 | ~40 |
+| rosett-ai-engine-ollama | 4 | ~39 |
+| rosett-ai-engine-agents-md | 3 | ~25 |
+| rosett-ai-engine-copilot | 3 | ~25 |
+| rosett-ai-engine-cursor | 3 | ~25 |
+| rosett-ai-engine-windsurf | 3 | ~25 |
+| rosett-ai-engine-acme | 3 | ~21 |
+| rosett-ai-engine-generic | 2 | ~17 |
+| **Total** | **174** | **~1,882** |
+
+## Questionnaire (Q1–Q10)
+
+Each spec file is evaluated against these questions:
+
+| # | Question | Severity | What to look for |
+|---|----------|----------|-----------------|
+| Q1 | Intent Clarity | major | Can you explain what the file tests in one sentence? |
+| Q2 | Assertion Quality | critical | Concrete values, not computed from implementation? |
+| Q3 | Edge Case Coverage | major | Empty, nil, boundary, error paths tested? |
+| Q4 | Mock Appropriateness | critical | Mocks only at boundaries, never the unit under test? |
+| Q5 | Implementation Independence | critical | Would tests pass with a rewritten implementation? |
+| Q6 | Mutation Resilience | major | Would mutating the code cause test failures? |
+| Q7 | Naming Quality | minor | Behaviour specs, not implementation descriptions? |
+| Q8 | Fixture Quality | major | Minimal, representative, no sensitive data? |
+| Q9 | Completeness | major | All public methods covered, happy + unhappy paths? |
+| Q10 | Documentation | minor | New developer would understand why each test exists? |
+
+## Verdicts
+
+**Per question:** pass, concern, fail
+
+**Per file:**
+
+- `approved` — All questions pass or concern only
+- `approved_with_notes` — Minor concerns, acceptable as-is
+- `needs_fix` — Findings require code changes before sign-off
+- `rejected` — Fundamental issues, test needs rewriting
+
+## Finding Severities
+
+- **critical** — Blocks sign-off, must be resolved
+- **major** — Should be resolved, can be deferred with justification
+- **minor** — Noted for improvement, does not block
+
+## Workflow
+
+```text
+Phase 1: AI prepares review summary (intent, metrics, observations)
+Phase 2: Human reads spec file + AI summary, answers Q1-Q10
+Phase 3: AI records answers and findings in registry YAML
+Phase 4: If findings exist → AI proposes fixes → human approves
+Phase 5: Human signs off (or requests further changes)
+Phase 6: Progress report updated
+```
+
+## Review Batches (Priority Order)
+
+1. **Core foundation** — path_resolver, version, config (~10 files)
+2. **Core compiler** — compiler, composition (~15 files)
+3. **Core security** — policy, secrets, validation (~12 files)
+4. **Core CLI tasks** — thor/tasks/* (~26 files)
+5. **Core modules** — authorship, provenance, etc. (~30 files)
+6. **Core UI/desktop** — gtk4, qt6, tui (~8 files)
+7. **Core utilities** — gemspec, version, i18n (~5 files)
+8. **Engine: claude** — highest complexity (~8 files)
+9. **Remaining engines** — 10 engines (~25 files)
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `conf/design/test_peer_review.yml` | Design document (intent, constraints, decisions) |
+| `conf/review/questionnaire.yml` | Questionnaire template (Q1-Q10 definitions) |
+| `conf/review/rosett-ai-core.yml` | Review registry for core repository |
+| `conf/review/rosett-ai-engine-*.yml` | Review registries for engine repositories |
+
+## Controlled Stub Allowlists
+
+### Problem
+
+Thor's `invoke` instantiates command classes internally, so test code cannot
+obtain the instance before the call. This forces the use of RSpec's
+`allow_any_instance_of` — a known code smell that stubs methods on ALL
+instances of a class, bypassing normal instance-level mocking.
+
+See: [RSpec any_instance documentation](https://rspec.info/features/3-13/rspec-mocks/working-with-legacy-code/any-instance/)
+
+### Solution
+
+Build-related spec files define a `stubbable_methods` allowlist: a method
+returning a frozen array of the ONLY methods permitted for
+`allow_any_instance_of` stubbing. Three helper methods enforce the boundary:
+
+- `stub_all_stages` — stubs all build pipeline stages (the common case)
+- `stub_stages(*methods)` — stubs a subset (raises if not in allowlist)
+- `stub_stage(method, return: val)` — stubs one method with return value or
+  block implementation (raises if not in allowlist)
+
+A dedicated spec example verifies that every method in the allowlist still
+exists on the class under test. If the implementation renames or removes a
+method, this example fails immediately with a clear message.
+
+### Maintenance requirement
+
+When a new build stage or shell-boundary method is added to `BuildPackage`
+or `BuildEngine`, developers must:
+
+1. Add the method name to `stubbable_methods` in the corresponding spec file
+2. Use `stub_stages` or `stub_stage` to stub it (never raw
+   `allow_any_instance_of`)
+3. Verify the allowlist guard example still passes
+
+This is intentional friction — it forces conscious review of every method
+that bypasses real execution in tests. A raw `allow_any_instance_of` call
+outside the helpers will be caught in code review.
+
+### Affected files
+
+| Spec file | Allowlist method |
+|-----------|-----------------|
+| `spec/rosett_ai/thor/tasks/build_package_spec.rb` | `stubbable_methods` (12 methods) |
+| `spec/rosett_ai/thor/tasks/build_engine_spec.rb` | (to be added in future review) |
+
+## Design Reference
+
+See `conf/design/test_peer_review.yml` for the full design document including
+decisions TPR-1 through TPR-7.