rosett-ai 1.3.3

data/doc/BEHAVIOUR.md

@@ -0,0 +1,409 @@
+# Rosett-AI - Behaviour System
+
+## Overview
+
+The behaviour system allows you to define and manage operational rules for Claude Code. Behaviours are stored as YAML files in `conf/behaviour/` and can be validated, displayed, and managed through the CLI.
+
+## Concepts
+
+### What is a Behaviour
+
+A behaviour is a collection of rules that guide Claude Code's operation. Each behaviour file defines:
+
+- **Name**: Unique identifier for the behaviour
+- **Description**: Human-readable explanation
+- **Rules**: Specific operational guidelines
+
+### Rule Priority
+
+Rules have priorities from 1-100:
+
+| Range | Description |
+|-------|-------------|
+| 90-100 | Critical - Always apply |
+| 70-89 | High - Apply unless conflicting |
+| 50-69 | Medium - Standard rules |
+| 30-49 | Low - Apply when relevant |
+| 1-29 | Minimal - Suggestions only |
+
+## File Structure
+
+### Location
+
+Behaviour files can exist at two scope levels:
+
+```text
+# Global behaviours (applied to all projects)
+<rosett-ai-install>/conf/behaviour/
+
+# Project behaviours (extend or override global)
+<project>/.rosett-ai/conf/behaviour/
+```
+
+When compiling from a project directory (one with `.rosett-ai/`), both scopes
+are merged: global behaviours are included alongside project-specific
+ones. If a project behaviour has the same filename as a global one,
+the project version takes precedence.
+
+See: `spec/rosett_ai/compiler/compilation_pipeline_spec.rb` — "multi-source
+compilation" context for authoritative test cases.
+
+### Naming Convention
+
+- Use snake_case for file names
+- Extension must be `.yml`
+- Name should describe the behaviour's purpose
+
+Examples:
+
+- `code_review.yml`
+- `security_audit.yml`
+- `documentation_standards.yml`
+
+### Schema
+
+Behaviour files are validated against a JSON Schema definition stored at:
+
+```text
+conf/schemas/behaviour_schema.json
+```
+
+This external schema file is loaded at runtime by `RosettAi::Validators::BehaviourValidator`.
+It uses [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/schema) and is
+processed by the [json_schemer](https://rubygems.org/gems/json_schemer) gem.
+
+The schema includes metadata in its `$comment` field:
+
+| Key | Description |
+|-----|-------------|
+| `date` | Date the schema was last updated |
+| `version` | Schema version (semantic versioning) |
+| `source` | Originating project (`rosett-ai`) |
+| `compatible_claude_code_versions` | Compatible rai version range |
+
+#### Behaviour Fields
+
+```yaml
+# Required fields
+name: string          # Unique identifier (1-100 chars)
+description: string   # What this behaviour does (min 1 char)
+rules: array          # List of rules (min 1 item)
+
+# Optional fields
+version: string       # Semantic version (e.g., "1.0.0")
+author: string        # Creator's name/email
+created_at: date      # Creation date (YYYY-MM-DD)
+modified_at: date     # Last modification date (YYYY-MM-DD)
+modified_by: string   # Last modifier
+sensitive: boolean    # Exclude from API analysis during adopt (default: false)
+used_in: array        # Projects using this behaviour
+```
+
+No additional properties are allowed beyond those listed above. See `conf/schemas/behaviour_schema.json` for the canonical schema definition.
+
+#### Rule Fields
+
+```yaml
+rules:
+  - id: string          # Unique rule identifier (required)
+    description: string # What this rule does (required)
+    priority: integer   # 1-100 (optional, default: 50)
+    enabled: boolean    # Active or not (optional, default: true)
+```
+
+#### Modifying the Schema
+
+To change validation rules, edit `conf/schemas/behaviour_schema.json` directly.
+After changes, update the `$comment.date` and `$comment.version` fields, then
+run the test suite to verify nothing breaks:
+
+```bash
+bundle exec rspec spec/rosett_ai/validators/behaviour_validator_spec.rb
+```
+
+## Creating Behaviours
+
+### Using the CLI
+
+```bash
+bin/raictl behaviour manage add my_behaviour --description="Description here"
+```
+
+This will:
+
+1. Create a template file in a temporary directory
+2. Open it in your `$EDITOR`
+3. Validate on save
+4. Copy to `conf/behaviour/` if valid
+
+### Manual Creation
+
+Create a YAML file directly:
+
+```yaml
+name: manual_behaviour
+description: Manually created behaviour
+version: 1.0.0
+author: developer@neatnerds.be
+created_at: "2025-01-17"
+modified_at: "2025-01-17"
+modified_by: developer@neatnerds.be
+used_in: []
+rules:
+  - id: rule_001
+    description: First rule description
+    priority: 50
+    enabled: true
+```
+
+Then validate:
+
+```bash
+bin/raictl behaviour validate manual_behaviour
+```
+
+## Example Behaviours
+
+### Code Review
+
+```yaml
+name: code_review
+description: Guidelines for reviewing code changes
+version: 1.0.0
+author: team@neatnerds.be
+created_at: "2025-01-17"
+modified_at: "2025-01-17"
+modified_by: team@neatnerds.be
+used_in:
+  - all_projects
+rules:
+  - id: security_first
+    description: Check for security vulnerabilities before other concerns
+    priority: 95
+    enabled: true
+  - id: test_coverage
+    description: Ensure changes have appropriate test coverage
+    priority: 85
+    enabled: true
+  - id: code_style
+    description: Verify code follows project style guidelines
+    priority: 70
+    enabled: true
+  - id: documentation
+    description: Check that public APIs are documented
+    priority: 60
+    enabled: true
+```
+
+### Security Audit
+
+```yaml
+name: security_audit
+description: Security-focused code analysis rules
+version: 1.0.0
+author: security@neatnerds.be
+created_at: "2025-01-17"
+modified_at: "2025-01-17"
+modified_by: security@neatnerds.be
+used_in:
+  - production_apps
+rules:
+  - id: injection_check
+    description: Scan for SQL/command injection vulnerabilities
+    priority: 100
+    enabled: true
+  - id: auth_verification
+    description: Verify authentication mechanisms
+    priority: 95
+    enabled: true
+  - id: data_exposure
+    description: Check for sensitive data exposure risks
+    priority: 90
+    enabled: true
+  - id: dependency_audit
+    description: Review third-party dependencies for known CVEs
+    priority: 85
+    enabled: true
+```
+
+## Validation
+
+### Automatic Validation
+
+Files are validated when:
+
+- Created via `behaviour manage add`
+- Modified via `behaviour manage modify`
+- CI/CD pipeline runs
+
+### Manual Validation
+
+```bash
+# Validate all files
+bin/raictl behaviour validate
+
+# Validate specific file
+bin/raictl behaviour validate code_review
+```
+
+### Validation Rules
+
+1. Required fields must be present
+2. `rules` array must have at least one item
+3. Each rule must have `id` and `description`
+4. `version` must follow semantic versioning
+5. `priority` must be between 1 and 100
+6. No additional properties allowed
+
+## Integration
+
+### In CLAUDE.md
+
+Reference behaviours in your CLAUDE.md:
+
+```markdown
+## Active Behaviours
+
+This project uses the following behaviours:
+- code_review
+- security_audit
+```
+
+### In Rules
+
+Behaviours can be referenced in rule files:
+
+```yaml
+# rules/project_rules.yml
+includes:
+  - behaviour: code_review
+  - behaviour: security_audit
+    override:
+      - id: test_coverage
+        priority: 95  # Increase priority for this project
+```
+
+## Compiling Rules
+
+The `compile` command renders behaviour YAML files into markdown rule files that Claude Code reads from `~/.claude/rules/`.
+
+### Usage
+
+```bash
+# Compile all categories (auto-detects scope from working directory)
+bin/raictl compile
+
+# Dry run — show what would change
+bin/raictl compile --simulate --verbose
+
+# Compile with detailed output
+bin/raictl compile --verbose
+
+# Compile and write lockfile
+bin/raictl compile --vendor
+```
+
+### Scope-Aware Compilation
+
+When run from a project directory (containing `.rosett-ai/`), compile
+automatically merges global and project-level behaviours:
+
+```bash
+# From a project directory with .rosett-ai/conf/behaviour/api_rules.yml:
+cd ~/projects/acme-api
+rai compile --verbose
+# Output includes BOTH global behaviours AND project-specific api_rules
+```
+
+Project behaviours with the same filename as a global behaviour
+override the global version. All other global behaviours are preserved.
+
+See: `spec/rosett_ai/thor/tasks/compile_spec.rb` — "with scope detection"
+and "with multi-source compilation" contexts.
+
+### How It Works
+
+1. Discovers compilable categories from all active source directories (global + project if applicable)
+2. Collects YAML files from each source; project-level files override global files with the same name
+3. Validates each YAML file against its schema
+4. Renders enabled rules (sorted by priority descending) into markdown
+5. Writes to `~/.claude/rules/<category>-<name>.md`
+6. Removes orphaned rule files that no longer have a source in any active scope
+
+### Idempotency
+
+The compiler computes SHA256 checksums and only writes when content changes. Running `compile` twice produces no changes on the second run.
+
+### Lockfile
+
+With `--vendor`, a `conf/compile.lock.yml` is written capturing the compiled state (versions, checksums, timestamps) for reproducibility.
+
+## Adopting Rules
+
+The `adopt` command analyzes compiled rule files for inconsistencies, conflicts, harmful content, duplicates, and other issues using the Claude API.
+
+### Usage
+
+```bash
+# Full API analysis
+bin/raictl adopt
+
+# Local-only structural checks (no API)
+bin/raictl adopt --local
+
+# Verbose output with details
+bin/raictl adopt --verbose
+
+# Show detailed explanations
+bin/raictl adopt --elaborate --verbose
+```
+
+### Data Privacy
+
+Four layers of privacy protection are available:
+
+1. **Opt-in per file** (default) — Add `sensitive: true` to a behaviour YAML to exclude it from API analysis
+2. **Redaction** — Configure patterns in `conf/adopt_redactions.yml` to replace sensitive content before sending to the API
+3. **Configurable endpoint** — Set `ANTHROPIC_API_BASE_URL` environment variable for Bedrock, Vertex, or proxy endpoints
+4. **Local-only mode** — Use `--local` flag to skip API calls entirely
+
+### Sensitive Files
+
+Mark a behaviour file as sensitive to exclude it from API analysis:
+
+```yaml
+name: internal_security
+description: Internal security policies
+sensitive: true
+rules:
+  - id: sec_001
+    description: ...
+```
+
+Sensitive files are still checked locally for structural issues.
+
+### Redaction
+
+Configure `conf/adopt_redactions.yml` with regex patterns:
+
+```yaml
+---
+patterns:
+  - pattern: '\b[A-Z0-9._%+-]+@company\.com\b'
+    replacement: '[EMAIL-REDACTED]'
+  - pattern: 'CompanyName'
+    replacement: '[COMPANY]'
+```
+
+### Caching
+
+Results are cached in `conf/adopt.cache.yml`, keyed on the SHA256 of all analyzed file contents. Running `adopt` twice with unchanged files returns the cached result without an API call.
+
+## Best Practices
+
+1. **Keep behaviours focused**: One behaviour per concern
+2. **Use descriptive IDs**: `security_sql_injection` > `rule_1`
+3. **Document thoroughly**: Descriptions should be actionable
+4. **Version your changes**: Update version on modifications
+5. **Track usage**: Maintain `used_in` for dependency tracking
+6. **Review regularly**: Audit behaviours periodically

data/doc/BUILD.md

@@ -0,0 +1,138 @@
+# Building rosett-ai Packages
+
+This document describes how to build Debian packages for rosett-ai core and engine plugins.
+
+## Prerequisites
+
+Install the following tools before building:
+
+```bash
+# Debian build tools
+sudo apt-get install fakeroot dpkg-dev rsync
+
+# Ruby build (for core package only)
+# Ensure ruby-build is on PATH (typically via rbenv)
+
+# Install all gem dependencies (includes fpm from :build group)
+bundle install
+```
+
+## Building rosett-ai Core
+
+The core package bundles a self-contained Ruby runtime, the rosett-ai application,
+vendored gems, and maintainer scripts into a Debian package at `/opt/rosett-ai`.
+
+```bash
+cd rosett-ai/
+
+# Default build (core variant)
+bin/raictl build package
+
+# With options
+bin/raictl build package --clean --verbose
+bin/raictl build package --variant gtk4
+bin/raictl build package --variant qt6
+bin/raictl build package --architecture arm64
+bin/raictl build package --ruby-version 3.3.10
+bin/raictl build package --output-dir /tmp/pkg
+```
+
+### Variants
+
+| Variant | Package Name | Description |
+|---------|-------------|-------------|
+| `core`  | `rosett-ai`      | CLI + TUI (default) |
+| `gtk4`  | `rosett-ai-gtk4` | GTK4/Adwaita desktop interface |
+| `qt6`   | `rosett-ai-qt6`  | Qt6/KDE desktop interface |
+
+## Building an Engine Plugin
+
+Engine plugins are packaged as Debian packages that install their gem into the
+raictl embedded Ruby's gem directory.
+
+```bash
+# From the engine directory
+cd rosett-ai-engine-claude/
+rai build engine --verbose
+
+# From the rosett-ai repo with --path
+cd rosett-ai/
+bin/raictl build engine --path ../rosett-ai-engine-claude --verbose
+
+# Custom output and dependency version
+rai build engine --output-dir /tmp/pkg --rosett-ai-min-version 1.0.0
+```
+
+### Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--path` | Current directory | Engine repo directory |
+| `--verbose` | `false` | Show detailed build output |
+| `--output-dir` | `pkg/` | Output directory for `.deb` |
+| `--rosett-ai-min-version` | Current rai version | Minimum rosett-ai dependency |
+| `--build-iteration` | `1` | Package iteration number |
+
+### How It Works
+
+1. Detects the engine gemspec (`rosett-ai-engine-*.gemspec`) in the target directory
+2. Extracts name and version from the gemspec (no hardcoded values)
+3. Derives Ruby ABI from the current runtime (`RbConfig::CONFIG['ruby_version']`)
+4. Runs `gem build` to produce a `.gem` file
+5. Creates a staging tree at `tmp/staging/opt/rosett-ai/embedded/lib/ruby/gems/<ABI>/`
+6. Installs the gem into the staging tree with `gem install --local`
+7. Packages with fpm, setting `--depends "rosett-ai (>= <version>)"`
+
+## Building All Packages
+
+To build all packages (core + engines):
+
+```bash
+#!/usr/bin/env ruby
+# build_all.rb — build core + all engines
+
+system('bin/raictl', 'build', 'package', '--verbose') || abort('Core build failed')
+
+Dir.glob('../rosett-ai-engine-*/').each do |engine_dir|
+  name = File.basename(engine_dir)
+  puts "\nBuilding #{name}..."
+  system('bin/raictl', 'build', 'engine', '--path', engine_dir, '--verbose') || warn("#{name} failed")
+end
+```
+
+## Version Management
+
+Versions are never hardcoded in build scripts:
+
+- **Core**: reads `RosettAi::VERSION` from `lib/rosett_ai/version.rb`
+- **Engines**: parsed from the engine's gemspec (`spec.version`)
+- **Ruby ABI**: derived from `RbConfig::CONFIG['ruby_version']` at build time
+- **Ruby version**: read from `.ruby-version` (core only)
+
+## Package Layout
+
+After installation, the rosett-ai package tree looks like:
+
+```text
+/opt/rosett-ai/
+  bin/raictl              # Wrapper script
+  app/                  # Application source
+  embedded/             # Self-contained Ruby runtime
+    bin/ruby
+    lib/ruby/gems/3.3.10/
+      gems/
+        rosett-ai-engine-claude-1.0.0/
+        rosett-ai-engine-cursor-1.0.0/
+        ...
+  etc/                  # Default configuration
+/etc/rosett-ai/
+  settings.json         # dpkg conffile (preserved on upgrade)
+/usr/share/man/man1/
+  rai.1.gz             # Man page
+```
+
+## CI/CD Integration
+
+Engine builds in CI use the shared component from `ci-components/templates/rosett-ai-engine.yml`.
+The `bin/raictl build engine` command is the canonical build method for both local
+development and CI pipelines.

data/doc/CI_CD_RECIPES.md

@@ -0,0 +1,171 @@
+# CI/CD Recipes
+
+Patterns and recipes for rosett-ai continuous integration and deployment.
+
+## Pipeline Architecture
+
+The rosett-ai pipeline is split across multiple YAML files in
+`.gitlab-ci-files/` for maintainability:
+
+```text
+.gitlab-ci.yml                      # Root includes
+├── global/stages.yml               # Stage ordering
+├── global/defaults.yml             # Default image, cache, retry
+├── global/variables.yml            # Shared CI variables
+├── global/resource-limits.yml      # CPU/memory limits
+├── validate/*.yml                  # YAML, JSON, Ruby syntax, schemas
+├── code_quality/*.yml              # RuboCop, Reek, Fasterer, Flay
+├── security_scan/*.yml             # Bundler-audit, Trivy, Gitleaks
+├── test/*.yml                      # RSpec, Mutant
+├── build/package.yml               # .deb packaging (amd64 + arm64)
+├── release/publish.yml             # GitLab release creation
+└── deploy/pulp.yml                 # Pulp repository publishing
+```
+
+## Stages
+
+| Stage | Purpose | Example Jobs |
+|-------|---------|--------------|
+| `validate` | Syntax and schema validation | yaml, json, ruby-syntax, schemas |
+| `code_quality` | Static analysis | rubocop, reek, fasterer, flay |
+| `security_scan` | Vulnerability detection | bundler-audit, trivy, gitleaks |
+| `test` | Functional testing | rspec, mutant |
+| `build` | Package creation | amd64, arm64, smoke test |
+| `deploy` | Repository publishing | pulp stable, pulp unstable |
+
+## Multi-Architecture Builds
+
+The `.package_build_template` in `build/package.yml` supports parallel
+architecture builds:
+
+```yaml
+build:package:amd64:
+  extends: .package_build_template
+  variables:
+    PACKAGE_ARCH: "amd64"
+
+build:package:arm64:
+  extends: .package_build_template
+  variables:
+    PACKAGE_ARCH: "arm64"
+```
+
+### Adding a New Architecture
+
+1. Add a new job extending `.package_build_template`
+2. Set `PACKAGE_ARCH` to the dpkg architecture name
+3. Add it to `build:package:release` needs list
+4. Ensure a CI runner with matching `tags` is available
+
+## Release Automation
+
+Releases are triggered by annotated tags matching `v*.*.*`:
+
+```bash
+# Prepare release (bumps VERSION, generates CHANGELOG)
+bin/raictl release prepare minor
+
+# Create annotated tag
+bin/raictl release tag
+
+# Push tag to trigger CI
+git push origin --tags
+```
+
+The pipeline then:
+
+1. Runs all quality gates (validate → test)
+2. Builds `.deb` packages for both architectures
+3. Collects artifacts with SHA256 checksums
+4. Creates a GitLab release with CHANGELOG notes
+5. Publishes to the Pulp stable repository
+
+## Smoke Testing
+
+The `build:package:smoke_test` job installs the built `.deb` in a clean
+`debian:bookworm` container with no pre-installed Ruby:
+
+```yaml
+script:
+  - dpkg -i pkg/*.deb || apt-get install -fy
+  - rosett-ai version
+  - rai validate
+  - rai engines list
+```
+
+This verifies the package is self-contained (embedded Ruby, all gems).
+
+## Cache Strategy
+
+| Cache Key | Contents | Policy |
+|-----------|----------|--------|
+| `Gemfile.lock` hash | `vendor/bundle/` | pull |
+| `package-${REF}` | Compiled Ruby in staging | pull-push |
+
+The compiled Ruby cache avoids the ~13 minute compilation on every build.
+
+## Engine Gem CI
+
+Engine gems use the shared CI component from `ci-components` (v1.0.1):
+
+```yaml
+include:
+  - component: gitlab.neatnerds.be/neatnerds/NeatNerds-AI/ci-components/rosett-ai-engine@v1.0.1
+```
+
+This provides standard jobs for: RuboCop, Reek, RSpec, Mutant, and
+SimpleCov with tiered coverage thresholds.
+
+### Adding a New Engine
+
+1. Scaffold with `rosett-ai-dev-tools`: `rosett-ai-dev-tools scaffold engine <name>`
+2. The scaffold includes a `.gitlab-ci.yml` that references the shared component
+3. Push to GitLab and the pipeline runs automatically
+
+## Integration Testing (Future)
+
+Integration tests require Docker (Phase 7):
+
+```yaml
+integration:test_kitchen:
+  stage: test
+  image: docker:24
+  services:
+    - docker:24-dind
+  script:
+    - kitchen test
+  rules:
+    - if: $CI_COMMIT_TAG
+```
+
+This will use Test Kitchen with a Debian container to verify:
+
+- Package installation
+- Engine detection
+- Configuration compilation
+- D-Bus service lifecycle
+
+## Security Scanning
+
+| Scanner | What It Checks |
+|---------|----------------|
+| Bundler-audit | Known CVEs in gem dependencies |
+| Ruby-audit | Ruby stdlib vulnerabilities |
+| Trivy | Container image vulnerabilities |
+| Gitleaks | Leaked secrets in git history |
+
+## Quality Gates
+
+All quality gates must pass before merge:
+
+| Gate | Threshold |
+|------|-----------|
+| RuboCop | 0 offenses |
+| Reek | 0 warnings (with exclusions) |
+| Fasterer | 0 offenses |
+| Flay | mass threshold 16 |
+| RSpec | 0 failures |
+| SimpleCov | >= 87% line coverage |
+| Mutant | All configured subjects |
+| Bundler-audit | No known vulnerabilities |
+| Gitleaks | No secrets detected |