rosett-ai 1.3.3

data/doc/USER_MANUAL.md

@@ -0,0 +1,585 @@
+# Rosett-AI User Manual
+
+Version 1.2.0
+
+## Table of Contents
+
+1. [Getting Started](#getting-started)
+2. [Core Concepts](#core-concepts)
+3. [CLI Reference](#cli-reference)
+4. [Writing Behaviour Rules](#writing-behaviour-rules)
+5. [Engine System](#engine-system)
+6. [Project Configuration](#project-configuration)
+7. [Troubleshooting](#troubleshooting)
+
+---
+
+## Getting Started
+
+### Installation
+
+#### From .deb package (recommended)
+
+```bash
+sudo dpkg -i rosett-ai_1.2.0-1_amd64.deb
+```
+
+The package installs a self-contained Ruby environment at `/opt/rosett-ai/`
+with symlinks at `/usr/local/bin/raictl` and `/usr/local/bin/rai`.
+
+#### From APT repository
+
+```bash
+# Import the signing key
+curl -fsSL https://repo.neatnerds.be/gpg-key.asc | \
+  sudo gpg --dearmor -o /usr/share/keyrings/rosett-ai.gpg
+
+# Add stable channel
+echo "deb [signed-by=/usr/share/keyrings/rosett-ai.gpg] \
+  https://repo.neatnerds.be/stable bookworm main" | \
+  sudo tee /etc/apt/sources.list.d/rosett-ai.list
+
+sudo apt update && sudo apt install rosett-ai
+```
+
+#### From source (development)
+
+```bash
+git clone https://gitlab.neatnerds.be/foss/rosett-ai/rosett-ai.git
+cd rosett-ai
+bundle install
+bin/rai version
+```
+
+### First Run
+
+After installation, initialise the global configuration:
+
+```bash
+raictl init --global
+```
+
+This creates:
+
+- `~/.config/rosett-ai/conf/behaviour/` — your behaviour files
+- `~/.config/rosett-ai/conf/schemas/` — validation schemas
+- `~/.config/rosett-ai/config.yml` — global settings
+
+Verify the installation:
+
+```bash
+raictl version       # Show version
+raictl doctor        # Run diagnostics
+```
+
+### Your First Behaviour File
+
+Create a behaviour file at `~/.config/rosett-ai/conf/behaviour/code_style.yml`:
+
+```yaml
+name: code_style
+description: Code style guidelines for AI assistants
+version: 1.0.0
+rules:
+  - id: rule_001
+    description: "Use descriptive variable names."
+    priority: 50
+    enabled: true
+```
+
+See the [Writing Behaviour Rules](#writing-behaviour-rules) section for
+the full YAML schema reference.
+
+Validate and compile:
+
+```bash
+raictl validate                    # Validate all configs
+raictl compile --verbose           # Compile to default engine
+raictl compile --simulate --verbose  # Preview without writing
+```
+
+---
+
+## Core Concepts
+
+### Behaviour Files
+
+Behaviour files are YAML documents containing rules for AI assistants.
+Each file groups related rules under a descriptive name. Rules have
+priorities that control their ordering in the compiled output.
+
+**Location**: `~/.config/rosett-ai/conf/behaviour/` (global) or
+`.rosett-ai/conf/behaviour/` (project-level).
+
+### Engines
+
+Engines translate behaviour rules into tool-specific formats. Each AI
+tool (Claude Code, Cursor, AGENTS.md, etc.) has its own engine that
+knows the tool's native configuration format and filesystem layout.
+
+| Engine | Output Format | Output Location |
+|--------|--------------|-----------------|
+| claude | Markdown rules | `~/.claude/rules/` |
+| agents_md | AGENTS.md | Project root |
+| generic | Plain markdown | Configurable |
+
+### Scopes
+
+Configuration is layered in a scope hierarchy. Lower scopes override
+higher scopes:
+
+1. **Global** (`~/.config/rosett-ai/conf/`) — user-wide defaults
+2. **Project** (`.rosett-ai/conf/`) — project-specific overrides
+
+When you run `raictl compile` from a project directory containing a
+`.rosett-ai/` marker, project-scope rules merge with global rules.
+
+### Compilation Pipeline
+
+```text
+Behaviour YAML  ──>  Rule extraction  ──>  Priority sorting  ──>  Engine rendering  ──>  Output files
+```
+
+The compiler reads all `.yml` files from the active scope(s), extracts
+enabled rules, sorts by priority (highest first), and renders them
+through the selected engine's backend.
+
+### Rule Priorities
+
+| Range | Level | Use Case |
+|-------|-------|----------|
+| 90-100 | Critical | Security constraints, hard requirements |
+| 70-89 | High | Methodology enforcement, quality gates |
+| 50-69 | Medium | Style guidelines, conventions |
+| 30-49 | Low | Preferences, nice-to-haves |
+| 1-29 | Minimal | Background context |
+
+---
+
+## CLI Reference
+
+### Compile
+
+Compile behaviour rules to engine-specific output.
+
+```bash
+raictl compile                         # Compile with default engine
+raictl compile --verbose               # Show detailed output
+raictl compile --simulate --verbose    # Dry run — preview diffs
+raictl compile --vendor                # Compile and write lockfile
+raictl compile --engine claude         # Target Claude Code
+raictl compile --engine agents_md      # Target AGENTS.md
+raictl compile --engine generic        # Target plain markdown
+raictl compile --strict                # Treat warnings as errors
+raictl compile --locales               # Compile locale files
+```
+
+### Validate
+
+Validate all configuration files (behaviours, design docs, tooling).
+
+```bash
+raictl validate                        # Validate everything
+```
+
+### Behaviour Management
+
+```bash
+raictl behaviour list                  # List all behaviour files
+raictl behaviour display               # Show rules as table
+raictl behaviour show code_style       # Show specific behaviour
+raictl behaviour validate              # Validate all behaviours
+raictl behaviour validate code_style   # Validate one behaviour
+raictl behaviour manage add my_rules   # Create new behaviour
+raictl behaviour manage modify my_rules  # Edit existing behaviour
+raictl behaviour manage delete my_rules  # Delete behaviour
+```
+
+### Init
+
+Set up directory structures for rosett-ai.
+
+```bash
+raictl init --global                   # Set up ~/.config/rosett-ai/
+raictl init --project                  # Set up .rosett-ai/ in current dir
+raictl init --global --local           # Set up both
+raictl init --global --no-compile      # Skip compilation step
+```
+
+### Doctor
+
+Run diagnostic checks to verify your environment.
+
+```bash
+raictl doctor                          # Run all checks
+raictl doctor --check ruby_version     # Run specific check
+raictl doctor --format json            # Machine-readable output
+```
+
+Available checks: `ruby_version`, `gem_dependency`, `engine_detection`,
+`file_permission`, `cache_health`, `dbus_availability`,
+`stale_home_nncc`, `stale_config_nncc`.
+
+### Migrate
+
+Migrate legacy configuration from previous versions.
+
+```bash
+raictl migrate                         # Migrate ~/.config/nncc/ paths
+raictl migrate --workspace ~/projects  # Batch migrate project markers
+raictl migrate --dry-run               # Show what would change
+```
+
+### Build and Release (Developer Rake Tasks)
+
+Build and release commands are developer-only and available via Rake, not the user-facing CLI:
+
+```bash
+rake build:package                     # Build core .deb package
+rake build:package[gtk4]               # Build GTK4 variant
+rake build:engine                      # Build engine plugin .deb
+rake release:prepare[minor]            # Bump minor, changelog, commit
+rake release:prepare[patch]            # Bump patch version
+rake release:tag                       # Create annotated git tag
+rake release:status                    # Show version and tag info
+rake readme:update                     # Update README numbers
+```
+
+### Design Documents
+
+```bash
+raictl design list                     # List all design docs
+raictl design show compiler            # Show specific design doc
+raictl design validate                 # Validate all design docs
+```
+
+### Compliance
+
+```bash
+raictl comply                          # Run all compliance checks
+raictl comply --cra                    # CRA-specific checks
+raictl comply --license                # License audit
+raictl comply --headers                # SPDX header verification
+raictl comply --format json            # Machine-readable output
+```
+
+### Provenance
+
+Track AI contributions.
+
+```bash
+raictl provenance add                  # Record AI contribution
+raictl provenance validate             # Validate entries
+raictl provenance log                  # Show all entries
+raictl provenance show COMMIT          # Show entry for commit
+```
+
+### Engines
+
+```bash
+raictl engines list                    # List all known engines
+raictl engines detect                  # Detect installed engines
+raictl engines status                  # Show default engine
+```
+
+### Other Commands
+
+```bash
+raictl license activate KEY            # Activate license key
+raictl license status                  # Show license status
+raictl hooks install                   # Install git hooks
+raictl hooks status                    # Show hook status
+raictl backup --global                 # Back up ~/.claude/
+raictl completion install              # Install shell completions
+raictl config compile                  # Compile YAML to JSON settings
+raictl mcp serve                       # Start MCP server
+raictl retrofit scan                   # Scan for native configs
+raictl project status                  # Show project status
+```
+
+---
+
+## Writing Behaviour Rules
+
+### YAML Structure
+
+Every behaviour file follows this schema:
+
+```yaml
+---
+name: behaviour_name          # Required: unique identifier
+description: What these rules cover  # Required: human description
+version: 1.0.0                # Recommended: semver
+author: your_name             # Who wrote it
+created_at: "2026-01-01"      # Creation date
+modified_at: "2026-01-01"     # Last modified
+modified_by: your_name        # Who last modified
+sensitive: false              # true = excluded from API analysis
+used_in: []                   # Which projects use this
+rules:                        # Required: at least one rule
+  - id: rule_001              # Required: unique within file
+    description: |            # Required: the actual rule text
+      The rule content goes here. Use YAML block scalar (|)
+      for multi-line descriptions. This text is compiled
+      directly into the engine's output format.
+    priority: 50              # Required: 1-100
+    enabled: true             # Required: false to skip
+```
+
+### Priority Guidelines
+
+Rules are compiled in priority order (highest first). Use priorities
+to control which rules appear first in the compiled output:
+
+- **90+**: Security and compliance rules that must not be overridden
+- **70-89**: Methodology rules (TDD enforcement, review gates)
+- **50-69**: General coding style and conventions
+- **30-49**: Preferences that can be overridden per-project
+- **1-29**: Background context and documentation rules
+
+### Sensitive Rules
+
+Mark rules as `sensitive: true` to exclude them from API-based analysis
+(e.g., `raictl adopt --api`). Use this for rules containing internal
+processes, infrastructure details, or proprietary methods.
+
+### Cross-References Between Rules
+
+Rules in different behaviour files can reference each other by
+convention. Group related rules in the same file. Use the `used_in`
+field to document which projects rely on a behaviour.
+
+### Validation
+
+Always validate after editing:
+
+```bash
+raictl behaviour validate my_rules  # Validate specific file
+raictl validate                     # Validate everything
+```
+
+The validator checks:
+
+- YAML syntax
+- Required fields present
+- Rule IDs unique within file
+- Priority values in range 1-100
+- Schema compliance
+
+---
+
+## Engine System
+
+### What Engines Are
+
+Engines are plugins that translate your behaviour rules into the native
+configuration format of a specific AI tool. Each engine is a separate
+Ruby gem following the naming convention `rosett-ai-engine-<name>`.
+
+### Available Engines
+
+| Engine | Gem | Output |
+|--------|-----|--------|
+| Claude Code | rosett-ai-engine-claude | `~/.claude/rules/*.md` |
+| AGENTS.md | rosett-ai-engine-agents-md | `AGENTS.md` in project root |
+| Generic | (built-in) | Plain markdown files |
+
+### Using Engines
+
+```bash
+# Detect which AI tools are installed
+raictl engines detect
+
+# Compile for a specific engine
+raictl compile --engine claude
+raictl compile --engine agents_md
+
+# List all known engines
+raictl engines list
+
+# Show current default
+raictl engines status
+```
+
+### Installing Engines
+
+Engine gems are discovered automatically:
+
+```bash
+gem install rosett-ai-engine-claude
+gem install rosett-ai-engine-agents-md
+```
+
+After installation, `raictl engines list` will show the new engine.
+
+### Writing Your Own Engine
+
+See `doc/ENGINE_DEVELOPMENT_GUIDE.md` for the full plugin SDK. An engine
+gem needs:
+
+1. A `manifest.yml` declaring capabilities and detection rules
+2. A backend class that renders behaviour rules to the tool's format
+3. A `register.rb` entry point for plugin discovery
+
+Minimal engine structure:
+
+```text
+rosett-ai-engine-mytools/
+  lib/rosett_ai_engine/mytool/
+    register.rb      # Plugin entry point
+    engine.rb        # Engine class
+    backend.rb       # Compilation backend
+    manifest.yml     # Capabilities declaration
+```
+
+---
+
+## Project Configuration
+
+### Setting Up a Project
+
+Create a `.rosett-ai/` marker in your project root:
+
+```bash
+cd ~/projects/my-app
+raictl init --project
+```
+
+This creates:
+
+```text
+my-app/
+  .rosett-ai/
+    config.yml              # Project settings
+    conf/
+      behaviour/            # Project-specific rules
+      design/               # Project design docs
+```
+
+### Project Config File
+
+`.rosett-ai/config.yml` controls project-level settings:
+
+```yaml
+---
+project_name: my-app
+default_engine: claude
+```
+
+### Scope Override Rules
+
+Project-level behaviours override global behaviours with the same
+filename. If both `~/.config/rosett-ai/conf/behaviour/security.yml`
+and `.rosett-ai/conf/behaviour/security.yml` exist, the project
+version takes precedence.
+
+To compile only global rules (ignoring project scope):
+
+```bash
+raictl compile --global
+```
+
+### Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `RAI_ORIGINAL_PWD` | Preserves working directory | `Dir.pwd` |
+| `RAI_ENGINE_PATH` | Custom engine search paths (colon-separated) | None |
+| `RAI_LOG_LEVEL` | Log verbosity: DEBUG, INFO, WARN, ERROR | WARN |
+
+---
+
+## Troubleshooting
+
+### Command not found after installation
+
+The symlink may be missing. Recreate it:
+
+```bash
+sudo ln -sf /opt/rosett-ai/bin/raictl /usr/local/bin/raictl
+sudo ln -sf /opt/rosett-ai/bin/raictl /usr/local/bin/rai
+```
+
+### Engine not found when compiling
+
+Install the engine gem:
+
+```bash
+gem install rosett-ai-engine-claude
+raictl engines detect  # Verify detection
+```
+
+### Validation errors in behaviour files
+
+Run the validator with the specific file name:
+
+```bash
+raictl behaviour validate my_rules
+```
+
+Common causes: missing `name` or `description` field, rule priority
+outside 1-100 range, duplicate rule IDs, invalid YAML syntax.
+
+### Permission errors
+
+```bash
+sudo chown -R $(whoami) ~/.config/rosett-ai/
+chmod 755 ~/.config/rosett-ai/
+```
+
+### Diagnostics
+
+Run the built-in diagnostic tool:
+
+```bash
+raictl doctor
+```
+
+This checks: Ruby version, gem dependencies, engine detection, file
+permissions, cache health, D-Bus availability, and legacy config paths.
+
+For machine-readable output (CI integration):
+
+```bash
+raictl doctor --format json
+```
+
+### Migrating from nncc
+
+If you previously used the NeatNerds Code Companion (nncc), migrate
+your configuration:
+
+```bash
+raictl migrate --dry-run     # Preview changes
+raictl migrate               # Migrate ~/.config/nncc/ to ~/.config/rosett-ai/
+raictl migrate --workspace ~/projects  # Migrate .nncc/ project markers
+```
+
+Migration copies files (originals preserved with `.migrated-*` suffix).
+
+### Reporting Bugs
+
+File issues at the project repository or contact: query@neatnerds.be
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Warning (non-fatal issues) |
+| 2 | Error (operation failed) |
+
+---
+
+## Further Reading
+
+- `doc/QUICK_START.md` — 5-minute getting started guide
+- `doc/BEHAVIOUR.md` — Detailed behaviour system documentation
+- `doc/ENGINES.md` — Engine architecture deep dive
+- `doc/ENGINE_DEVELOPMENT_GUIDE.md` — Plugin SDK for engine authors
+- `doc/ARCHITECTURE.md` — System architecture overview
+- `doc/CONFIGURATION.md` — Configuration reference
+- `INSTALL.md` — Installation guide
+- `AI-DISCLOSURE.md` — AI governance policy

data/doc/ai_test_review_checklist.md

@@ -0,0 +1,110 @@
+# AI-Generated Test Review Checklist
+
+Every AI-generated test must pass all 11 checks before acceptance.
+Reviewers (human or AI) must verify each point explicitly.
+
+## Checklist
+
+### 1. No tautological assertions
+
+The test expectation must not reimplement the code under test.
+
+**Bad:** `expect(result).to eq(input.select(&:enabled?).count)`
+**Good:** `expect(result).to eq(3)`
+
+### 2. Concrete expected values
+
+Expectations must use literal, predetermined values.
+
+**Bad:** `expect(output).to include(name)`
+**Good:** `expect(output).to include('test_behaviour')`
+
+### 3. Mocks only at boundaries
+
+Mocking is only permitted for file system, network, shell commands,
+and external service calls. Internal collaborators must be real.
+
+**Bad:** `allow(compiler).to receive(:render).and_return('...')`
+**Good:** `allow(File).to receive(:read).and_return(yaml_content)`
+
+### 4. Unit under test never mocked
+
+The object being tested must never have its own methods stubbed.
+
+**Bad:** `allow(subject).to receive(:validate!).and_return(true)`
+**Good:** Test the actual `validate!` method with real input.
+
+### 5. Both positive and negative assertions
+
+Tests must assert what IS in the output AND what is NOT.
+
+**Bad:** Only checking `expect(result).to include('enabled_rule')`
+**Good:** Also checking `expect(result).not_to include('disabled_rule')`
+
+### 6. Edge cases: empty, nil, boundary values
+
+Every public method must have tests for:
+
+- Empty input (`[]`, `{}`, `""`)
+- Nil input
+- Boundary values (0, max, off-by-one)
+
+### 7. Error cases tested
+
+Tests must verify that invalid input raises the correct exception
+with an informative message.
+
+**Good:**
+
+```ruby
+expect { subject.load_file('/nonexistent') }
+  .to raise_error(RosettAi::ValidationError, /not found/)
+```
+
+### 8. No implementation coupling
+
+Tests must verify outcomes (what the code produces), not call
+sequences (how the code does it internally).
+
+**Bad:** `expect(subject).to have_received(:select).with(...)`
+**Good:** `expect(subject.compile(input)).to contain_exactly(...)`
+
+### 9. Behaviour-focused descriptions
+
+Test descriptions must describe observable behaviour, not
+implementation steps.
+
+**Bad:** `it 'calls select then map on the rules array'`
+**Good:** `it 'includes only enabled rules in the output'`
+
+### 10. Mutant score >= 85%
+
+After tests are written, run `bundle exec mutant run` against the
+class. The mutation score must be at least 85% for established code
+and 95% for security-critical paths.
+
+### 11. No redundant tests
+
+Each test must kill at least one unique mutation that no other test
+kills. If removing a test does not decrease the mutation score,
+the test is redundant and should be removed or strengthened.
+
+## Usage
+
+When reviewing a test file (human or AI review), check each point:
+
+```text
+[ ] 1. No tautological assertions
+[ ] 2. Concrete expected values
+[ ] 3. Mocks only at boundaries
+[ ] 4. Unit under test never mocked
+[ ] 5. Both positive and negative assertions
+[ ] 6. Edge cases covered
+[ ] 7. Error cases tested
+[ ] 8. No implementation coupling
+[ ] 9. Behaviour-focused descriptions
+[ ] 10. Mutant score >= 85%
+[ ] 11. No redundant tests
+```
+
+Any check that fails must be fixed before the test is accepted.