rosett-ai 1.3.3

data/CONTRIBUTING.md

@@ -0,0 +1,734 @@
+# Contributing to rosett-ai
+
+This guide explains how to extend the Rosett-AI. Each section
+covers a specific expansion pattern with the exact files to create or modify.
+
+## Development Setup
+
+```bash
+git clone https://gitlab.neatnerds.be/neatnerds/NeatNerds-AI/rosett-ai.git
+cd rosett-ai
+bundle install
+overcommit --install
+overcommit --sign          # trust the hook signatures
+bundle exec rspec          # run tests
+bundle exec rubocop        # run linter
+bundle exec reek           # run code smell detector
+```
+
+## Bundler Groups and Dependencies
+
+The core Gemfile defines four groups:
+
+| Group | Purpose | Included locally | Included in CI |
+|-------|---------|:---:|:---:|
+| `:default` | Core runtime (gemspec) | Yes | Yes |
+| `:desktop` | GTK4/Adwaita desktop UI | Yes | No |
+| `:build` | Package building (fpm) | Yes | Yes |
+| `:development, :test` | Linters, test tools | Yes | Yes |
+
+Engine gems are **not** in the core Gemfile. For cross-repo engine development,
+use `Gemfile.dev` (gitignored):
+
+```bash
+BUNDLE_GEMFILE=Gemfile.dev bundle install
+```
+
+This loads all `rosett-ai-engine-*` gems from sibling directories. In production,
+engine gems are installed as separate `.deb` packages (see ADR-010).
+
+The `:desktop` group is excluded in CI (`bundle config without 'desktop'`)
+because it requires system libraries (`libgirepository1.0-dev`, `libgtk-4-dev`)
+that are not in the CI Docker image. No CI job needs GTK4 gems.
+
+If you are developing desktop features locally, install the system dependencies
+first:
+
+```bash
+sudo apt-get install -y libgirepository1.0-dev libgtk-4-dev
+bundle install   # includes :desktop group by default
+```
+
+If you do not need desktop features, you can exclude them locally too:
+
+```bash
+bundle config set --local without 'desktop'
+bundle install
+```
+
+### Updating dependencies
+
+`Gemfile.lock` is tracked in git (see ADR-008). CI runs with `frozen: true`,
+meaning it will reject any mismatch between `Gemfile` and `Gemfile.lock`.
+
+To update a dependency:
+
+```bash
+bundle update <gem-name>          # updates the lockfile
+bundle exec rspec                 # verify tests pass
+bundle exec rubocop               # verify no new offenses
+git add Gemfile.lock
+git commit -m "chore(deps): update <gem-name> to X.Y.Z"
+```
+
+To update all dependencies at once:
+
+```bash
+bundle update
+bundle exec rspec && bundle exec rubocop
+git add Gemfile.lock
+git commit -m "chore(deps): update all dependencies"
+```
+
+## Pre-commit Hooks (Overcommit)
+
+Overcommit runs quality gates on every commit. The key hooks:
+
+| Hook | Scope | What it checks |
+|------|-------|----------------|
+| `RubocopAll` | All files | Ruby style and lint offenses (full project scan) |
+| `Reek` | Changed files | Code smell detection |
+| `Flay` | Changed files | Structural code duplication (mass threshold: 16) |
+| `YamlLint` | Changed files | YAML syntax |
+| `Mdl` | Changed files | Markdown style |
+| `BundlerAudit` | Gemfile.lock | Known gem CVEs |
+| `RubyAudit` | Ruby stdlib | Known Ruby CVEs |
+| `CheckVersions` | Project-wide | Ruby version consistency across files |
+
+`RubocopAll` is a custom hook (`.git-hooks/pre_commit/rubocop_all.rb`) that
+scans all project files, not just changed files. This ensures new rubocop cops
+(from version updates) catch offenses everywhere, not just in the commit diff.
+See ADR-008 for the rationale.
+
+If a hook fails, fix the issue and commit again. To run hooks manually:
+
+```bash
+bundle exec overcommit --run       # run all pre-commit hooks
+```
+
+## Architecture Overview
+
+raictl follows a layered architecture with clear extension points:
+
+```text
+CLI Layer        lib/rosett_ai/thor/tasks/*.rb      Thor subcommands
+Library Layer    lib/rosett_ai/**/*.rb              Domain logic
+Engine Layer     lib/rosett_ai/engines/<name>/      AI engine backends & adapters
+Config Layer     conf/**/*.yml                 YAML configurations
+Schema Layer     conf/schemas/*.json           JSON Schema validation
+UI Layer         lib/rosett_ai/ui/                  Pluggable display adapters
+i18n Layer       locales/*.yml                 Translation files
+```
+
+---
+
+## Adding a New Translation (Locale)
+
+raictl uses ruby-i18n with YAML source files.
+
+### Create the locale file
+
+Create `locales/<code>.yml` (e.g., `locales/de.yml`). Copy the structure from
+`locales/en.yml` and translate every string value. The top-level key must be
+the locale code:
+
+```yaml
+de:
+  rosett_ai:
+    meta:
+      direction: ltr
+      language_name: "German"
+      language_name_native: "Deutsch"
+    cli:
+      version: "rosett-ai Version %{version}"
+```
+
+### Translation rules
+
+- Preserve all interpolation variables (`%{version}`, `%{count}`, etc.)
+  exactly as they appear in en.yml. Changing variable names will cause
+  runtime errors.
+- For RTL languages (Arabic, Hebrew), set `meta.direction: rtl`. The
+  `AccessibleTui` adapter reads this to set text direction.
+- For languages with plural rules (Arabic has 6 forms), use the ruby-i18n
+  plural keys (`zero`, `one`, `two`, `few`, `many`, `other`). See
+  `locales/ar.yml` for an example.
+
+### Compile and test
+
+Compile locale files (optional, for distribution):
+
+```bash
+bin/raictl compile --locales
+```
+
+This generates gettext `.pot`/`.po` and Qt Linguist `.ts` files.
+
+Test: Run `bin/raictl version --locale de` to verify.
+
+### Files to modify
+
+| File | Action |
+|------|--------|
+| `locales/<code>.yml` | Create (copy en.yml structure) |
+
+No code changes required — the locale is auto-discovered from the `locales/`
+directory at load time.
+
+---
+
+## Adding a New AI Engine
+
+Engines live under `lib/rosett_ai/engines/<name>/` with optional components.
+Each engine has a manifest declaring its capabilities and a backend for
+compilation. See the Claude and Generic engines for reference.
+
+### Create the engine gem
+
+Each engine is a separate gem. Use `rosett-ai-engine-acme` as a reference:
+
+```bash
+mkdir -p rosett-ai-engine-mistral/{lib/rosett_ai_engine/mistral,spec/rosett_ai_engine/mistral,conf}
+```
+
+### Create the manifest
+
+Create `conf/manifest.yml`:
+
+```yaml
+---
+name: mistral
+display_name: "Mistral AI"
+version: 1.0.0
+components:
+  backend: true
+  config_compiler: false
+  executor: false
+  detector: false
+  scaffolder: false
+detection: {}
+execution: {}
+capabilities:
+  compile: true
+  config: false
+  adopt_api: false
+  settings_json: false
+```
+
+### Create the backend class
+
+Create `lib/rosett_ai_engine/mistral/backend.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+module RosettAiEngine
+  module Mistral
+    class Backend < RosettAi::Compiler::Backend
+      MARKER_PREFIX = '<!-- rosett-ai-mistral-managed'
+
+      def render(data)
+        # Return a string representing the compiled output.
+        # See RosettAiEngine::Generic::Backend or
+        # RosettAiEngine::Claude::Backend for reference.
+        lines = []
+        lines << "#{generated_marker} -->"
+        # ... build your format
+        lines.join("\n") + "\n"
+      end
+
+      def generated_marker
+        MARKER_PREFIX
+      end
+    end
+  end
+end
+```
+
+### Create the engine module and self-registration
+
+Create `lib/rosett_ai_engine/mistral/engine.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require 'rosett_ai'
+require_relative 'version'
+require_relative 'backend'
+
+module RosettAiEngine
+  module Mistral
+    module Engine
+      include RosettAi::Plugins::EngineContract
+
+      class << self
+        def engine_name    = 'mistral'
+        def display_name   = 'Mistral AI'
+        def version        = VERSION
+        def backend_class  = RosettAiEngine::Mistral::Backend
+        def detector_class = nil
+        def executor_class = nil
+        def config_compiler_class = nil
+
+        def manifest_path
+          Pathname.new(__dir__).join('..', '..', '..', 'conf', 'manifest.yml').expand_path
+        end
+      end
+    end
+  end
+end
+```
+
+Create `lib/rosett_ai_engine/mistral/register.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require_relative 'engine'
+RosettAi::Plugins::Registry.register(:engine, 'mistral', RosettAiEngine::Mistral::Engine)
+```
+
+The engine self-registers via `Gem.find_files('rosett_ai_engine/*/register.rb')`.
+No core code changes needed — install the gem, and it appears automatically.
+
+### CLI executor type
+
+Some engines use CLI subprocess execution (`api_type: cli`) instead of an
+HTTP API. These engines spawn a child process via `Open3.capture3` and
+communicate through stdin/stdout.
+
+In the engine manifest, set:
+
+```yaml
+execution:
+  api_type: cli
+  binary: mistral-cli
+```
+
+Then create an executor at `lib/rosett_ai_engine/mistral/executor.rb` that
+implements `#analyze(prompt)` using `Open3.capture3`. See
+`rosett-ai-engine-goose` or `rosett-ai-engine-aider` for reference
+for reference.
+
+### Detector patterns
+
+Engines can provide automatic detection via a detector class. The detector
+checks for CLI binaries, config directories, or environment variables:
+
+```ruby
+module RosettAi
+  module Engines
+    module Mistral
+      class Detector < RosettAi::Engines::Detector
+        private
+
+        def detect_binary
+          system('which', 'mistral-cli', out: File::NULL, err: File::NULL)
+        end
+
+        def detect_config
+          File.directory?(File.expand_path('~/.mistral'))
+        end
+      end
+    end
+  end
+end
+```
+
+### Add tests and use
+
+Add tests at `spec/rosett_ai/engines/mistral/backend_spec.rb`, then use
+it with `bin/raictl compile --engine mistral`.
+
+You can set your new engine as the default by editing `~/.config/rosett-ai/config.yml`:
+
+```yaml
+default_engine: mistral
+```
+
+### Files to modify
+
+| File | Action |
+|------|--------|
+| `conf/engines/<name>/manifest.yml` | Create |
+| `conf/engines/<name>/target.yml` | Create |
+| `lib/rosett_ai/engines/<name>/backend.rb` | Create |
+| `lib/rosett_ai/engines/registry.rb` | Add to `ENGINES` hash |
+| `lib/rosett_ai/compiler/backend.rb` | Add to `BACKENDS` hash |
+| `spec/rosett_ai/engines/<name>/backend_spec.rb` | Create |
+
+---
+
+## Adding a New Configuration Section (Claude Code Scope)
+
+Claude Code settings are compiled from YAML scopes in `conf/engines/claude/config/`.
+
+### Edit or create scope files
+
+Edit the scope file (e.g., `conf/engines/claude/config/managed.yml`) to add new
+configuration keys. The schema at `conf/engines/claude/schemas/config_schema.json`
+defines which keys are valid per scope.
+
+To add an entirely new scope, create `conf/engines/claude/config/<scope>.yml` and
+register it in `lib/rosett_ai/engines/claude/scope_router.rb`.
+
+### Key mappings and domains
+
+- For new key mappings (snake\_case YAML to camelCase JSON), update
+  `lib/rosett_ai/engines/claude/key_map.rb` to add the mapping entry.
+- For new domains (like `mcp`, `api`), update
+  `lib/rosett_ai/engines/claude/domain_transformer.rb` to handle transformation rules.
+
+### Test
+
+Run `bin/raictl config compile --simulate --verbose` to verify.
+
+### Files to modify
+
+| File | Action |
+|------|--------|
+| `conf/engines/claude/config/<scope>.yml` | Edit or create |
+| `conf/engines/claude/schemas/config_schema.json` | Extend schema |
+| `lib/rosett_ai/engines/claude/key_map.rb` | Add key mapping (if new keys) |
+| `lib/rosett_ai/engines/claude/scope_router.rb` | Add scope route (if new scope) |
+
+---
+
+## Adding a New CLI Subcommand
+
+### Create the task file
+
+Create `lib/rosett_ai/thor/tasks/<name>.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'thor'
+require 'rainbow'
+
+module RosettAi
+  module Thor
+    module Tasks
+      class Example < ::Thor
+        desc 'execute', 'Run the example command'
+        def execute
+          puts t('success')
+        end
+
+        private
+
+        def t(key, **)
+          ::I18n.t("rosett-ai.cli.example.#{key}", **)
+        end
+      end
+    end
+  end
+end
+```
+
+### Register and configure
+
+Register the subcommand in `lib/rosett_ai/thor/cli.rb`:
+
+```ruby
+desc 'example SUBCOMMAND', 'Example commands'
+subcommand 'example', RosettAi::Thor::Tasks::Example
+```
+
+Add the error class in `lib/rosett_ai.rb`:
+
+```ruby
+class ExampleError < Error; end
+```
+
+### i18n, tests, and documentation
+
+- Add i18n strings to `locales/en.yml` and `locales/fr.yml` under
+  `rosett-ai.cli.example.*`.
+- Add reek exclusions in `.reek.yml` — at minimum add the class to
+  `DuplicateMethodCall` if it uses `puts`/`Rainbow` for output.
+- Add tests at `spec/rosett_ai/thor/tasks/example_spec.rb`.
+- Update `CLAUDE.md` (CLI Usage section) and `doc/man/rai.1.ronn`
+  (COMMANDS section).
+
+### Files to modify
+
+| File | Action |
+|------|--------|
+| `lib/rosett_ai/thor/tasks/<name>.rb` | Create |
+| `lib/rosett_ai/thor/cli.rb` | Register subcommand |
+| `lib/rosett_ai.rb` | Add error class |
+| `locales/en.yml` | Add i18n strings |
+| `locales/fr.yml` | Add i18n strings |
+| `.reek.yml` | Add exclusions |
+| `spec/rosett_ai/thor/tasks/<name>_spec.rb` | Create |
+| `CLAUDE.md` | Document command |
+| `doc/man/rai.1.ronn` | Document command |
+
+---
+
+## Adding a New Design Document
+
+Design documents define implementation standards in `conf/design/`.
+
+### Create the document
+
+Create `conf/design/<name>.yml` with the required fields:
+
+```yaml
+name: my_feature
+domain: core
+version: 0.1.0
+status: draft
+priority: 5
+author: your_name
+created_at: "2026-01-01"
+modified_at: "2026-01-01"
+modified_by: your_name
+depends_on: []
+intent: |
+  Why this exists and what problem it solves.
+constraints:
+  - Hard boundary that must not be crossed
+acceptance_criteria:
+  - Testable statement defining done
+```
+
+Valid domains: `core`, `ui`, `security`, `testing`, `styles`, `i18n`,
+`accessibility`, `licensing`, `ci`, `compiler`, `release`, `documentation`,
+`operations`.
+
+### Validate and approve
+
+Run `bin/raictl design validate my_feature` to check the document against
+the schema. If a new domain is needed, update `conf/schemas/design_schema.json`
+to add it to the `domain` enum. Set status to `approved` once reviewed.
+
+### Files to modify
+
+| File | Action |
+|------|--------|
+| `conf/design/<name>.yml` | Create |
+| `conf/schemas/design_schema.json` | Extend domain enum (if new domain) |
+
+---
+
+## Adding a New UI Adapter
+
+The UI layer uses a registry pattern. TUI is the default; GUI adapters are
+optional.
+
+### Create the adapter
+
+Create `lib/rosett_ai/ui/<name>.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+module RosettAi
+  module Ui
+    class MyAdapter < Base
+      def render(content)
+        # Render content string to the user
+      end
+
+      def display_table(headers:, rows:, title: nil)
+        # Display tabular data
+      end
+
+      def prompt_user(message, choices: [])
+        # Interactive prompt
+      end
+
+      def show_spinner(message)
+        # Show spinner, yield, return result
+        yield
+      end
+
+      def announce(message, priority: :polite)
+        # Accessibility announcement
+      end
+    end
+  end
+end
+```
+
+### Register and test
+
+Register in `lib/rosett_ai/ui/registry.rb`:
+
+```ruby
+register('myadapter', RosettAi::Ui::MyAdapter)
+```
+
+Add the `--ui` enum value in `lib/rosett_ai/thor/cli.rb`.
+
+Add tests using the shared examples at
+`spec/support/shared_examples/ui_implementation.rb`:
+
+```ruby
+RSpec.describe RosettAi::Ui::MyAdapter do
+  it_behaves_like 'a UI implementation'
+end
+```
+
+If this adapter is a separate .deb package (like `rosett-ai-gtk4`), create a
+packaging variant at `conf/packaging/<name>.yml`.
+
+### Files to modify
+
+| File | Action |
+|------|--------|
+| `lib/rosett_ai/ui/<name>.rb` | Create |
+| `lib/rosett_ai/ui/registry.rb` | Register adapter |
+| `lib/rosett_ai/thor/cli.rb` | Add to `--ui` enum |
+| `spec/rosett_ai/ui/<name>_spec.rb` | Create |
+| `conf/packaging/<name>.yml` | Create (if separate package) |
+
+---
+
+## Adding a New CI Job
+
+CI jobs live in `.gitlab-ci-files/<stage>/` and are included from
+`.gitlab-ci.yml`.
+
+### Create the job file
+
+Create `.gitlab-ci-files/<stage>/<name>.yml`:
+
+```yaml
+my_job:
+  stage: code_quality
+  extends:
+    - .ruby_base
+  script:
+    - echo "Running my check"
+  rules:
+    - if: $CI_MERGE_REQUEST_IID
+      when: on_success
+```
+
+Available stages: `validate`, `code_quality`, `security_scan`, `test`, `build`.
+Stages are defined in `.gitlab-ci-files/global/stages.yml`.
+
+### Include the job
+
+Add the include to `.gitlab-ci.yml`:
+
+```yaml
+- local: '.gitlab-ci-files/<stage>/<name>.yml'
+```
+
+---
+
+## Security Rules
+
+All contributions must follow these rules (enforced by CI):
+
+- **YAML.safe\_load only** — never `YAML.load`
+- **Array-form system()** — never string interpolation in shell commands
+- **File writes to whitelisted directories only**
+- **Secrets: 0600 permissions, never logged**
+- **All external input validated before use**
+- **SPDX headers** on every Ruby source file:
+  `# SPDX-License-Identifier: GPL-3.0-only`
+
+## Code Quality Gates
+
+Every commit must pass:
+
+- `bundle exec rspec` — all tests green
+- `bundle exec rubocop` — zero offenses
+- `bundle exec reek` — zero warnings (or excluded in `.reek.yml` with justification)
+- `bundle exec bundler-audit check` — no known CVEs
+- `bundle exec ruby-audit check` — no Ruby advisory violations
+- Overcommit pre-commit hooks (YAML lint, trailing whitespace, JSON syntax, etc.)
+
+## Branch Naming
+
+All branches must follow the pattern `<type>/<id>-<subject>`:
+
+- **type** --- a [Conventional Commits](https://www.conventionalcommits.org/)
+  type: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`,
+  `ci`, `build`, `revert`
+- **id** --- the OpenProject work package number (omit if no WP exists)
+- **subject** --- short kebab-case description
+
+Examples:
+
+```text
+feat/857-belspo-registration
+fix/712-compile-scope-bug
+docs/1286-security-md
+chore/update-deps
+```
+
+## Conventional Commits
+
+All commit messages must follow
+[Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```text
+type(scope): description
+
+Optional body explaining *why*, not *what*.
+
+OP#<work-package-id>
+
+Co-Authored-By: ...    (if applicable)
+Signed-off-by: ...     (if applicable)
+```
+
+Valid types match the branch naming types above. The scope is optional
+but encouraged (e.g. `fix(compile):`, `docs(security):`). The
+`OP#<id>` trailer is injected automatically by the overcommit
+`CommitMsg` hook when the branch follows the naming convention.
+
+## AI Disclosure
+
+When AI tools assist in writing code or documentation, contributors
+must disclose the assistance:
+
+1. **Co-Authored-By trailer** --- add to the commit message:
+
+   ```text
+   Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+   ```
+
+   Replace the model name and version with the actual tool used. This
+   trailer is required for any commit where AI generated or
+   substantially revised the content.
+
+2. **Provenance file** --- for NeatNerds maintainers, run
+   `raictl provenance add` after each AI-assisted commit to append
+   an entry to `.ai-provenance.yml`. External contributors are not
+   required to update this file.
+
+Contributions generated entirely by AI without human review will not
+be accepted. The human contributor remains responsible for
+correctness, security, and license compliance of all submitted code.
+
+## Developer Certificate of Origin (DCO)
+
+External contributors must sign off their commits to certify they
+have the right to submit the work under the project's license:
+
+```text
+Signed-off-by: Your Name <your-email@example.com>
+```
+
+Use `git commit --signoff` (or `-s`) to add this trailer
+automatically. By signing off, you agree to the
+[Developer Certificate of Origin](https://developercertificate.org/)
+(version 1.1).
+
+NeatNerds maintainers are covered by their employment or contractor
+agreement and do not need to sign off individually.
+
+## License
+
+raictl is licensed under GPL-3.0-only. All contributions must be compatible
+with this license.