rosett-ai 1.3.3

data/doc/changes/2026-02-18-packaging-fpm.md

@@ -0,0 +1,155 @@
+# Replace Omnibus with fpm + ruby-build for Debian packaging
+
+**Branch**: `packaging_fpm`
+**Date**: 2026-02-02 through 2026-02-18
+**Commits**: 11 (excluding merge commit)
+
+## Motivation
+
+The Omnibus-based packaging approach had become a significant maintenance burden. Key issues included:
+
+- **Excessive complexity**: 11 configuration files across `omnibus/` (Gemfile, Rakefile, omnibus.rb, project config, software config, ERB template, 4 package scripts)
+- **Long build times**: 30-60 minutes per build due to compiling Ruby, OpenSSL, zlib, and libyaml from source
+- **Large package size**: 100MB+ `.deb` files
+- **Hardcoded gem paths**: The wrapper template used hardcoded `gems/3.3.0` paths that would break on Ruby version changes
+- **Missing conffiles**: dpkg did not track `/etc/rosett-ai/settings.json`, causing user edits to be overwritten on upgrade
+- **Broken symlinks**: Removal scripts did not properly clean up `/usr/local/bin/raictl`
+- **Dependency overrides**: OpenSSL, zlib, libyaml were compiled from source despite always being present on Debian systems
+
+## Solution: fpm + ruby-build
+
+The replacement uses two focused tools:
+
+- **ruby-build** (already mirrored internally via rbenv): Compiles Ruby to `/opt/rosett-ai/embedded/` with system-linked shared libraries
+- **fpm** (~> 1.16, Ruby gem): Packages the staging directory into a `.deb` with proper metadata
+
+### Key design decisions
+
+1. **No source compilation of system libraries** - libc6, libssl3, zlib1g, and libyaml-0-2 are declared as package dependencies instead of being compiled from source. These are always present on Debian systems.
+2. **Dynamic GEM_HOME** - The wrapper script uses `RbConfig::CONFIG["ruby_program_version"]` instead of hardcoded paths.
+3. **Direct Ruby invocation** - `exec ruby -I"${APP_DIR}/lib" bin/raictl "$@"` instead of `bundle exec`, eliminating bundler overhead at runtime.
+4. **dpkg conffile management** - `settings.json` ships at `/etc/rosett-ai/settings.json` and is registered as a conffile, so dpkg handles user modifications on upgrade.
+
+## Changes by area
+
+### New: Packaging infrastructure
+
+| File | Purpose |
+|------|---------|
+| `lib/rosett_ai/thor/tasks/build.rb` (650 LOC) | Thor task orchestrating the full build pipeline |
+| `packaging/wrapper.sh` | Runtime wrapper with dynamic paths |
+| `packaging/scripts/postinst` | Post-install: creates `/usr/local/bin/raictl` symlink |
+| `packaging/scripts/prerm` | Pre-removal: removes symlink |
+| `packaging/scripts/postrm` | Post-removal: purge removes `/opt/rosett-ai` and `/etc/rosett-ai` |
+
+The build task implements a stage-based pipeline:
+
+1. **Validate environment** - Checks for ruby-build, fakeroot, dpkg-deb
+2. **Compile Ruby** - Runs ruby-build into staging directory
+3. **Sync application** - Copies app files (excluding `.git`, `spec`, `tmp`, `pkg`, etc.)
+4. **Install gems** - `bundle install --deployment` using embedded Ruby
+5. **Install wrapper** - Copies wrapper script to `staging/opt/rosett-ai/bin/raictl`
+6. **Install default config** - Ships settings.json as dpkg conffile
+7. **Build package** - Invokes fpm with all metadata, dependencies, and maintainer scripts
+
+Each stage is timed and reported in a summary table. Failures are caught and reported with context. Build logs are written to `tmp/build-<uuid>.log`.
+
+#### Build context extraction
+
+Mutable build state (build ID, log path, timings, failure info) was extracted into a `BuildContext` Struct to reduce class-level instance variable count and improve testability:
+
+```ruby
+BuildContext = Struct.new(
+  :build_id, :build_start, :build_log,
+  :stage_timings, :completed_stages,
+  :failed_stage, :failure_reason, :summary_printed,
+  keyword_init: true
+)
+```
+
+### Removed: Omnibus
+
+All files under `omnibus/` were deleted:
+
+- `omnibus/Gemfile` and `omnibus/Rakefile`
+- `omnibus/omnibus.rb` (configuration)
+- `omnibus/config/projects/rosett-ai.rb` (project definition)
+- `omnibus/config/software/rosett-ai.rb` (software definition)
+- `omnibus/config/templates/rosett-ai/nncc_wrapper.erb` (ERB wrapper template)
+- `omnibus/package-scripts/rosett-ai/{postinst,postrm,preinst,prerm}` (4 scripts)
+
+### Refactored: Init task
+
+The `init` command (`lib/rosett_ai/thor/tasks/init.rb`) was rewritten:
+
+- Extracted `RosettAi::Init::DirectoryBuilder` and `RosettAi::Init::FileCopier` for clear separation
+- `setup_global` and `setup_local` now properly delegate and store results
+- Added `--no-compile` flag to skip the compilation step after init
+- Summary table shows directory and file counts per scope
+
+### Refactored: Tooling
+
+- `lib/rosett_ai/thor/tasks/tooling.rb` was simplified from a multi-tool manager (~420 LOC) to a focused GitLab CI YAML validator
+- Five orphaned library files removed from `lib/rosett_ai/tooling/`:
+  - `detector.rb`, `display_helpers.rb`, `package_manager.rb`, `settings_manager.rb`, `tool_registry.rb`
+- Four corresponding spec files removed from `spec/rosett_ai/tooling/`
+
+### CI/CD pipeline
+
+| File | Change |
+|------|--------|
+| `.gitlab-ci-files/build/omnibus.yml` | Renamed to `package.yml`, rewritten for fpm |
+| `.gitlab-ci-files/global/defaults.yml` | Added retry policy (max 2) for transient failures |
+| `.gitlab-ci-files/global/stages.yml` | Updated stage ordering |
+| `.gitlab-ci-files/global/variables.yml` | Added build-related variables |
+| `.gitlab-ci-files/security_scan/gitleaks.yml` | Fixed false positives |
+| `.gitlab-ci.yml` | Updated include path from omnibus to package |
+| `.gitleaks.toml` | Added allowlist entries for test fixtures |
+
+Retry policy covers: `runner_system_failure`, `job_execution_timeout`, `stuck_or_timeout_failure`, `api_failure`.
+
+### Test suite
+
+- **277 examples, 0 failures** (up from ~230 on main)
+- **92.92% line coverage**
+- New spec files:
+  - `spec/rosett_ai/thor/tasks/build_package_spec.rb` (30 examples)
+  - `spec/rosett_ai/thor/tasks/build_spec.rb` (2 examples)
+  - `spec/rosett_ai/thor/tasks/init_spec.rb` (rewritten, 9 examples)
+
+#### Thor warning suppression
+
+RSpec's `allow_any_instance_of` uses `define_method` on Thor subclasses, which triggers Thor's `method_added` hook and produces `[WARNING] Attempted to create command` messages. This was solved by:
+
+1. Prepending `ThorTestSilencer` on `Thor.singleton_class` in `spec_helper.rb` - temporarily redirects `$stdout` during `create_command` to suppress the warning output
+2. Using `allow_any_instance_of` (required because Thor's `invoke` creates a new internal instance, making instance-level stubs ineffective)
+3. Adding `RSpec/AnyInstance` exclusion for `spec/rosett_ai/thor/tasks/**/*` in `.rubocop.yml`
+
+### Code quality configuration
+
+- `.reek.yml`: Added targeted exclusions for the build task's inherent complexity (stage orchestration, environment validation, summary printing)
+- `.rubocop.yml`: Added `RSpec/AnyInstance` exclusion for Thor task specs
+- All linters pass clean: rubocop (0 offenses), reek (0 warnings), overcommit (all hooks OK)
+
+## Package details
+
+| Property | Value |
+|----------|-------|
+| Package name | `rosett-ai` |
+| Install path | `/opt/rosett-ai/` |
+| Config path | `/etc/rosett-ai/` |
+| Binary symlink | `/usr/local/bin/raictl` |
+| Embedded Ruby | `/opt/rosett-ai/embedded/bin/ruby` |
+| Package size | ~38 MB |
+| Build time | ~5 minutes |
+| Dependencies | libc6, libssl3, zlib1g, libyaml-0-2 |
+| Compression | xz |
+
+## Verification checklist
+
+- [x] `bin/raictl build package --clean --verbose` produces a `.deb`
+- [x] `dpkg-deb --info` shows correct metadata and dependencies
+- [x] `bundle exec rspec` passes (277 examples, 0 failures)
+- [x] `bundle exec rubocop` passes (0 offenses)
+- [x] `bundle exec reek` passes (0 warnings)
+- [x] `overcommit -r` passes (all hooks OK)

data/doc/changes/2026-02-19-testing-infrastructure.md

@@ -0,0 +1,221 @@
+# Implement testing.yml design document (P1)
+
+**Branch**: `design_implementation`
+**Date**: 2026-02-19
+**Design doc**: `conf/design/testing.yml` v1.0.0
+
+## Motivation
+
+The testing design document establishes a testing strategy that validates both
+code correctness AND test quality. When AI writes both code and tests, the test
+suite can be perfectly consistent yet meaningless. Mutation testing (Mutant) acts
+as an independent third-party validator that mechanically verifies tests catch
+real bugs, regardless of who wrote them.
+
+This must be in place before feature development begins so all future code is
+validated from day one. Testing is the second P1 domain after security.
+
+## Acceptance criteria
+
+All 9 acceptance criteria from `testing.yml` are satisfied:
+
+| # | Criterion | Evidence |
+|---|-----------|----------|
+| 1 | mutant-rspec installed + `.mutant.yml` | `.mutant.yml` with `usage: opensource`, rspec integration |
+| 2 | SimpleCov thresholds block CI | 90% overall, 80% per-file (was 50/40) |
+| 3 | RSpec on every CI push + JUnit XML | Already existed in `.gitlab-ci-files/test/rspec.yml` |
+| 4 | Mutant on MR, blocks merge | `.gitlab-ci-files/test/mutant.yml`, `allow_failure: false` |
+| 5 | factory_bot factories | `spec/support/factories/{behaviours,rules}.rb` |
+| 6 | shared_examples for UI base | `spec/support/shared_examples/ui_implementation.rb` |
+| 7 | Test fixtures | 7 files in `spec/fixtures/behaviours/` |
+| 8 | AI test review checklist | `doc/ai_test_review_checklist.md` (11 points) |
+| 9 | Property-based test | `spec/rosett_ai/yaml_loader_property_spec.rb` using Rantly |
+
+## Changes by area
+
+### New gems
+
+| Gem | Version | Purpose |
+|-----|---------|---------|
+| `factory_bot` | ~> 6.5 | Test data factories for domain objects |
+| `mutant-rspec` | ~> 0.14 | Mutation testing with RSpec integration |
+| `rantly` | ~> 3.0 | Property-based / generative testing |
+
+### Mutant configuration (`.mutant.yml`)
+
+```yaml
+usage: opensource          # No license gem needed (>= 0.12)
+integration: rspec
+mutation:
+  timeout: 10.0
+matcher:
+  subjects:               # Library code with logic
+    - "RosettAi::Compiler*"
+    - "RosettAi::YamlLoader"
+    - "RosettAi::TextSanitizer"
+    - "RosettAi::Validators*"
+    - "RosettAi::Configuration"
+    - "RosettAi::Adopter*"
+  ignore:                 # CLI wiring (integration-tested)
+    - "RosettAi::Thor*"
+    - "RosettAi::VERSION"
+```
+
+Verified mutation scores (after targeted test hardening):
+
+- **Overall**: 97.83% (555 mutations, 543 killed, 12 equivalent survivors)
+- **YamlLoader**: all non-equivalent mutations killed
+- **TextSanitizer**: all non-equivalent mutations killed
+- **Configuration**: all non-equivalent mutations killed
+
+The 12 surviving mutations are all provably equivalent:
+
+| Pattern | Count | Why equivalent |
+|---------|-------|---------------|
+| `RosettAi::ValidationError` → `ValidationError` | 3 | Same class resolution inside `module RosettAi` |
+| `is_a?` → `instance_of?` | 4 | JSON.parse only produces plain Hash/Array |
+| `to_h.empty?` → `.empty?` / `to_hash.empty?` | 2 | Same behaviour for Hash |
+| `e.message` → `e` | 1 | StandardError#to_s == #message |
+| `.each_value.sum` → `.sum` | 1 | Hash#sum yields [k,v]; count_keys(string)=0 |
+| `.unicode_normalize(:nfc)` → `.unicode_normalize` | 1 | Ruby defaults to :nfc |
+
+### CI pipeline
+
+New job in `.gitlab-ci-files/test/mutant.yml`:
+
+- Runs only on merge requests (`merge_request_event`)
+- Uses `--since $CI_MERGE_REQUEST_TARGET_BRANCH_NAME` for incremental analysis
+- `GIT_DEPTH: 0` overrides the global shallow clone (mutant needs full history)
+- `allow_failure: false` blocks merge if mutation score drops
+
+### SimpleCov changes
+
+| Setting | Before | After |
+|---------|--------|-------|
+| `minimum_coverage` | 50% | 90% |
+| `minimum_coverage_by_file` | 40% | 80% |
+| Coverage groups | Library, Thor Tasks, Validators | Compilers, Validators, Adopter, Backup, Thor Tasks |
+
+Current coverage: **93.09%** (1562/1678 lines), well above the 90% threshold.
+
+### factory_bot factories
+
+Hash-based factories (not ActiveRecord) using `initialize_with` and `skip_create`:
+
+- **`:behaviour`** — full behaviour hash with traits `:sensitive`, `:empty_rules`
+- **`:rule`** — rule hash with sequenced IDs, traits `:disabled`, `:high_priority`
+
+All keys are strings (matching YAML load output).
+
+### Test fixtures
+
+| Fixture | Tests |
+|---------|-------|
+| `valid_behaviour.yml` | Happy path with 2 rules |
+| `invalid_missing_fields.yml` | Missing `name` and `version` |
+| `invalid_bad_types.yml` | Priority as string, enabled as string |
+| `malicious_yaml_bomb.yml` | YAML anchor expansion (blocked by `safe_load`) |
+| `malicious_ansi_injection.yml` | ANSI CSI + OSC sequences in descriptions |
+| `unicode_nfc.yml` | Precomposed NFC diacritics |
+| `unicode_mixed.yml` | NFD decomposed, CJK, RTL Arabic |
+
+### Property-based test
+
+`spec/rosett_ai/yaml_loader_property_spec.rb` uses Rantly to verify:
+
+1. Random valid hashes within bounds always load successfully (50 trials)
+2. Random oversized payloads always raise `ValidationError` (10 trials)
+3. Random deeply-nested structures beyond depth limit always raise (10 trials)
+
+### Shared examples
+
+`spec/support/shared_examples/ui_implementation.rb` defines the interface
+contract (`:render`, `:display_table`, `:prompt_user`, `:show_spinner`) that
+future UI implementations must satisfy. No consumers yet (P3 — ui_framework).
+
+### AI test review checklist
+
+`doc/ai_test_review_checklist.md` documents the 11-point checklist:
+
+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: empty, nil, boundary values
+7. Error cases tested
+8. No implementation coupling
+9. Behaviour-focused descriptions
+10. Mutant score >= 85%
+11. No redundant tests
+
+### Test hardening (mutation coverage 80% → 97.83%)
+
+Targeted test improvements to kill 99 of the 111 surviving mutations:
+
+**`spec/rosett_ai/configuration_spec.rb`**:
+
+- Replaced `include` matchers with exact `eq` assertions
+- Added nested hash deep-merge, array union, and deduplication tests
+- Added type-mismatch tests: scalar↔hash, scalar↔array in both directions
+- Added object identity test for empty overlay (kills `deep_merge` guard mutations)
+- Added error message content assertion (parser detail, not just filename)
+- Full `reload!` coverage: all 4 ivars cleared, re-reads files after reload
+- Exact `schema_path` assertion with `eq` instead of `end_with`
+
+**`spec/rosett_ai/yaml_loader_spec.rb`**:
+
+- Restructured all tests under `describe '.load_file'` (mutant test selection fix)
+- Added `Time` class permitted-by-default test
+- Added boundary tests at exactly 11 levels (hash and array nesting)
+- Added exact byte count and key count in error message assertions
+- Added mixed structure key counting: arrays-of-hashes, nested totals
+- Fixed context wording for RuboCop `RSpec/ContextWording`
+
+**`spec/rosett_ai/text_sanitizer_spec.rb`**:
+
+- Added non-UTF-8 encoding test (ISO-8859-1 → UTF-8 conversion)
+- Added NFC-specific single codepoint assertion (length=1, not NFD length=2)
+- Added encoding verification on output
+
+## Files created
+
+| File | Purpose |
+|------|---------|
+| `.mutant.yml` | Mutant configuration |
+| `.gitlab-ci-files/test/mutant.yml` | Mutant CI job (MR only) |
+| `spec/support/factory_bot.rb` | FactoryBot require + RSpec config |
+| `spec/support/factories/behaviours.rb` | Behaviour hash factory |
+| `spec/support/factories/rules.rb` | Rule hash factory |
+| `spec/support/shared_examples/ui_implementation.rb` | UI interface contract |
+| `spec/fixtures/behaviours/valid_behaviour.yml` | Valid fixture |
+| `spec/fixtures/behaviours/invalid_missing_fields.yml` | Invalid fixture |
+| `spec/fixtures/behaviours/invalid_bad_types.yml` | Invalid fixture |
+| `spec/fixtures/behaviours/malicious_yaml_bomb.yml` | Malicious fixture |
+| `spec/fixtures/behaviours/malicious_ansi_injection.yml` | Malicious fixture |
+| `spec/fixtures/behaviours/unicode_nfc.yml` | Unicode fixture |
+| `spec/fixtures/behaviours/unicode_mixed.yml` | Unicode fixture |
+| `doc/ai_test_review_checklist.md` | 11-point review checklist |
+| `spec/rosett_ai/yaml_loader_property_spec.rb` | Property-based test |
+| `doc/changes/2026-02-19-testing-infrastructure.md` | This change doc |
+
+## Files modified
+
+| File | Change |
+|------|--------|
+| `Gemfile` | Added factory_bot, mutant-rspec, rantly |
+| `spec/spec_helper.rb` | Thresholds 90/80, coverage groups, support autoloading |
+| `.gitlab-ci.yml` | Added mutant.yml include |
+| `.rubocop.yml` | Added rubocop-factory_bot plugin |
+| `CHANGELOG.md` | Added testing infrastructure entries |
+
+## Verification
+
+- [x] `bundle install` — 26 gems, 122 total
+- [x] `bundle exec rspec` — 351 examples, 0 failures
+- [x] `bundle exec rubocop` — 0 offenses
+- [x] `bundle exec reek lib/` — 0 warnings
+- [x] `bundle exec mutant run` — 97.83% coverage (543/555 killed, 12 equivalent)
+- [x] `.mutant.yml` auto-loaded (no `--usage` flag needed)
+- [x] Factory_bot factories produce valid string-keyed hashes
+- [x] All 7 fixture files parse correctly (YAML bomb blocked by `safe_load`)

data/doc/changes/2026-02-20-security-implementation.md

@@ -0,0 +1,281 @@
+# Implement security.yml design document (P1)
+
+**Branch**: `design_implementation`
+**Date**: 2026-02-19 to 2026-02-21
+**Design doc**: `conf/design/security.yml` v1.1.0
+**Commits**: fdb73e0, 9fc7e55, 46aa519, 1d0bfb9 (+ supporting: dc42c3c, 7423856, ff3d81e)
+
+## Motivation
+
+Security is the foundation layer of rosett-ai. Every line of code written after this
+document is adopted must follow its constraints. Retrofitting security is 10x
+more expensive than building it in. This implementation establishes hard rules,
+required tooling, and safe coding patterns that apply to ALL code in the project
+— core, TUI, GUI, compilers, and tests.
+
+The security design document defines 12 acceptance criteria covering: dependency
+auditing, static analysis, safe YAML parsing, shell injection prevention, file
+permissions, YAML bounds enforcement, ANSI sanitization, NFC normalization, and
+secrets resolution.
+
+## Acceptance criteria
+
+All 12 acceptance criteria from `security.yml` are satisfied:
+
+| # | Criterion | Evidence |
+|---|-----------|----------|
+| 1 | bundler-audit runs in CI and blocks merge on any known CVE | `.gitlab-ci-files/security_scan/bundler-audit.yml` (pre-existing), `.overcommit.yml` hook |
+| 2 | ruby_audit runs in CI and blocks merge on Ruby stdlib vulnerabilities | `.gitlab-ci-files/security_scan/ruby-audit.yml`, `.overcommit.yml` RubyAudit hook |
+| 3 | RuboCop security cops are enabled and enforced | `.rubocop.yml` requires `./lib/rubocop/rosett_ai`, cops at `Severity: error` |
+| 4 | No instance of YAML.load exists in codebase (only safe_load) | `RosettAi/UnsafeYamlLoad` cop blocks; all call sites migrated to `RosettAi::YamlLoader.load_file` |
+| 5 | No string-interpolated system() calls exist | `RosettAi/ShellInterpolation` cop blocks; backtick interpolation also detected |
+| 6 | All file write operations use explicit permission setting | All `File.open` calls use mode arg (0o644 for files, 0o600 for secrets) |
+| 7 | CI pipeline rejects code that violates any security constraint | Custom cops at `Severity: error` fail CI; bundler-audit + ruby-audit block |
+| 8 | Custom RuboCop cops flag unsafe patterns | `UnsafeYamlLoad` + `ShellInterpolation` cops with full test suites |
+| 9 | YAML files exceeding bounds are rejected with clear error | `YamlLoader` enforces 1 MB size, 10-level depth, 1000 key count |
+| 10 | TUI output containing ANSI escapes from YAML is sanitized | `TextSanitizer.sanitize_for_display` at all output boundaries |
+| 11 | Filenames and identifiers are NFC-normalized | `TextSanitizer.normalize_nfc` at input boundaries (compiler, behaviour, adopt) |
+| 12 | Secrets are never written to disk unless explicitly configured | `SecretsResolver`: ENV > secrets file (0600); never writes secrets |
+
+## Changes by area
+
+### Ruby upgrade 3.3.8 to 3.3.10
+
+**Commit**: fdb73e0
+
+Three CVEs resolved by upgrading the Ruby runtime:
+
+| CVE | Component | Severity |
+|-----|-----------|----------|
+| CVE-2025-24294 | resolv (DNS) | DoS via crafted response |
+| CVE-2025-58767 | REXML | DoS via XML entity expansion |
+| CVE-2025-61594 | URI | Credential leak in parsing |
+
+Files updated: `.ruby-version`, `CLAUDE.md`, `README.md`, `doc/PACKAGING.md`,
+`doc/USAGE.md`, `spec/rosett_ai/thor/tasks/build_package_spec.rb`.
+
+### Shell injection elimination
+
+**Commit**: 9fc7e55
+
+Every `system()` call using string interpolation was replaced with array-form,
+and every backtick command with interpolation was replaced with `IO.popen`.
+
+**build.rb** — backtick version check to IO.popen:
+
+```diff
+-          installed = `#{ruby_bin} -e "puts RUBY_VERSION"`.strip
++          installed = IO.popen([ruby_bin.to_s, '-e', 'puts RUBY_VERSION'], &:read).strip
+```
+
+**build.rb** — `command_available?` shell to pure Ruby:
+
+```diff
+-        def command_available?(cmd)
+-          system("command -v #{cmd} > /dev/null 2>&1")
++        def command_available?(cmd)
++          ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).any? do |dir|
++            File.executable?(File.join(dir, cmd))
++          end
+```
+
+**compressor.rb** — xz pipeline to array-form:
+
+```diff
+-        xz_cmd = "xz#{" -#{level}" if level} --stdout #{tar_path} > #{output_path}"
+-        success = system(xz_cmd)
++        xz_args = ['xz']
++        xz_args.push("-#{level}") if level
++        xz_args.push('--stdout', tar_path)
++        success = File.open(output_path, 'wb', 0o644) do |out|
++          system(*xz_args, out: out)
++        end
+```
+
+### File permissions enforcement
+
+**Commit**: 9fc7e55
+
+All `File.write` and `File.open(..., 'w')` calls now use explicit permission
+mode arguments:
+
+| File | Permission | Rationale |
+|------|-----------|-----------|
+| Build log | 0o644 | Non-sensitive output |
+| Compiled rules | 0o644 | User configuration files |
+| Lockfile | 0o644 | Version tracking metadata |
+| Behaviour temp files | 0o644 | Temporary editor copies |
+| Adopt cache | 0o644 | Non-sensitive cache |
+| Compressed archives | 0o644 | User-accessible output |
+| Secrets file | 0o600 | Contains API keys (validated by `SecretsResolver`) |
+
+### Custom RuboCop cops
+
+**Commit**: 46aa519
+
+Two custom cops enforce security rules statically:
+
+**`RosettAi/UnsafeYamlLoad`** (`lib/rubocop/cop/rosett-ai/unsafe_yaml_load.rb`):
+
+```ruby
+def_node_matcher :unsafe_yaml_load?, <<~PATTERN
+  (send (const {nil? cbase} :YAML) {:load :load_file} ...)
+PATTERN
+```
+
+Flags `YAML.load` and `YAML.load_file`. Severity: error (blocks CI).
+
+**`RosettAi/ShellInterpolation`** (`lib/rubocop/cop/rosett-ai/shell_interpolation.rb`):
+
+```ruby
+def_node_matcher :shell_with_interpolation?, <<~PATTERN
+  (send nil? {:system :exec :spawn} dstr ...)
+PATTERN
+
+def on_xstr(node)
+  return unless node.children.any?(&:begin_type?)
+  add_offense(node, message: BACKTICK_MSG)
+end
+```
+
+Flags `system("cmd #{arg}")`, `exec("#{cmd}")`, `spawn("#{x}")`, and backtick
+interpolation `` `#{cmd} --flag` ``. Severity: error (blocks CI).
+
+### YAML bounds enforcement (YamlLoader)
+
+**Commit**: 46aa519
+
+`lib/rosett_ai/yaml_loader.rb` enforces three bounds before returning parsed data:
+
+| Bound | Limit | Check method |
+|-------|-------|-------------|
+| File size | 1 MB (1,048,576 bytes) | `check_file_size!` — before parsing |
+| Nesting depth | 10 levels | `check_depth!` — recursive walk |
+| Key count | 1,000 keys | `check_key_count!` — recursive count |
+
+All existing YAML.safe_load call sites were migrated to use `YamlLoader.load_file`:
+`rule_adopter.rb`, `behaviour_compiler.rb`, `behaviour.rb` (5 call sites),
+`behaviour_validator.rb`.
+
+### ANSI sanitization (TextSanitizer)
+
+**Commit**: 46aa519
+
+`lib/rosett_ai/text_sanitizer.rb` provides two sanitization methods:
+
+**`strip_ansi`** — removes ANSI CSI sequences (`\e[...X`), OSC sequences
+(`\e]...\a`), and non-printable control characters (except tab, newline, CR):
+
+```ruby
+ANSI_PATTERN = /\e\[\d*(?:;\d*)*[A-Za-z]|\e\][^\a]*\a|[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/
+```
+
+**`sanitize_for_display`** — recursively strips ANSI from strings, hashes,
+and arrays. Integrated at display boundaries in `adopt.rb` and `behaviour.rb`.
+
+### NFC normalization
+
+**Commit**: 46aa519
+
+`TextSanitizer.normalize_nfc` applies Unicode NFC normalization at input
+boundaries. Used in:
+
+- `behaviour_compiler.rb` — filename normalization before key generation
+- `behaviour.rb` — name parameters in add/modify/delete/show/validate commands
+- `rule_adopter.rb` — sensitive source filename comparison
+
+### Secrets resolution (SecretsResolver)
+
+**Commit**: bf9f15e
+
+`lib/rosett_ai/secrets_resolver.rb` resolves secrets through an ordered fallback:
+
+1. Environment variable (`ENV.fetch`)
+2. Secrets file (`~/.config/rosett-ai/secrets.yml` with 0600 permissions)
+3. Raise with instructions if not found
+
+Permission validation rejects secrets files without 0600 permissions.
+
+### Backtick interpolation detection
+
+**Commit**: 1d0bfb9
+
+Extended the `ShellInterpolation` cop with `on_xstr` handler to detect
+backtick interpolation (`` `#{cmd}` ``), not just `system()`/`exec()`/`spawn()`.
+
+## Secrets resolution flow
+
+```mermaid
+flowchart TD
+    START[resolve env_key] --> ENV{ENV variable<br/>set and non-empty?}
+    ENV -->|yes| RETURN_ENV[Return ENV value]
+    ENV -->|no| FILE{Secrets file<br/>exists?}
+    FILE -->|no| ERROR[Raise: key not found<br/>with setup instructions]
+    FILE -->|yes| PERMS{Permissions<br/>== 0600?}
+    PERMS -->|no| PERMS_ERROR[Raise: insecure permissions<br/>expected 0600]
+    PERMS -->|yes| YAML[Load via YamlLoader]
+    YAML --> KEY{Key in<br/>YAML data?}
+    KEY -->|yes| RETURN_FILE[Return file value]
+    KEY -->|no| ERROR
+```
+
+## YAML bounds pipeline
+
+```mermaid
+flowchart LR
+    INPUT[YAML file path] --> SIZE{File size<br/>≤ 1 MB?}
+    SIZE -->|no| REJECT1[Raise: exceeds size limit]
+    SIZE -->|yes| PARSE[YAML.safe_load_file<br/>permitted: Date, Time]
+    PARSE --> DEPTH{Nesting<br/>≤ 10 levels?}
+    DEPTH -->|no| REJECT2[Raise: exceeds depth limit]
+    DEPTH -->|yes| KEYS{Key count<br/>≤ 1000?}
+    KEYS -->|no| REJECT3[Raise: exceeds key limit]
+    KEYS -->|yes| RETURN[Return parsed data]
+```
+
+## Files created
+
+| File | Purpose |
+|------|---------|
+| `lib/rosett_ai/yaml_loader.rb` | Centralized YAML loading with bounds |
+| `lib/rosett_ai/text_sanitizer.rb` | ANSI stripping + NFC normalization |
+| `lib/rosett_ai/secrets_resolver.rb` | Multi-source secret resolution |
+| `lib/rubocop/cop/rosett-ai/shell_interpolation.rb` | Shell injection detection cop |
+| `lib/rubocop/cop/rosett-ai/unsafe_yaml_load.rb` | Unsafe YAML.load detection cop |
+| `lib/rubocop/rosett_ai.rb` | Cop loader |
+| `spec/rosett_ai/yaml_loader_spec.rb` | YamlLoader unit tests |
+| `spec/rosett_ai/text_sanitizer_spec.rb` | TextSanitizer unit tests |
+| `spec/rosett_ai/secrets_resolver_spec.rb` | SecretsResolver unit tests (167 lines) |
+| `spec/rubocop/cop/rosett-ai/shell_interpolation_spec.rb` | ShellInterpolation cop tests |
+| `spec/rubocop/cop/rosett-ai/unsafe_yaml_load_spec.rb` | UnsafeYamlLoad cop tests |
+| `.gitlab-ci-files/security_scan/ruby-audit.yml` | Ruby stdlib CVE scanning CI job |
+
+## Files modified
+
+| File | Change |
+|------|--------|
+| `lib/rosett_ai/thor/tasks/build.rb` | Backtick to IO.popen, shell to pure Ruby, File.open with perms |
+| `lib/rosett_ai/backup/compressor.rb` | Shell pipeline to array-form, File.open with perms |
+| `lib/rosett_ai/thor/tasks/behaviour.rb` | YamlLoader + TextSanitizer integration (5 call sites) |
+| `lib/rosett_ai/thor/tasks/adopt.rb` | TextSanitizer for display, SecretsResolver for API key |
+| `lib/rosett_ai/adopter/rule_adopter.rb` | YamlLoader for cache/redactions, TextSanitizer for filenames |
+| `lib/rosett_ai/compiler/behaviour_compiler.rb` | YamlLoader + NFC filename normalization |
+| `lib/rosett_ai/validators/behaviour_validator.rb` | YamlLoader with ValidationError handling |
+| `lib/rosett_ai/thor/tasks/compile.rb` | File.open with explicit permissions |
+| `.rubocop.yml` | Added custom cop require + enforcement at Severity: error |
+| `.overcommit.yml` | Added RubyAudit hook |
+| `.ruby-version` | 3.3.8 to 3.3.10 |
+| `Gemfile` | Added ruby_audit, flog |
+
+## Verification
+
+- [x] `bundle exec ruby-audit check` — 0 vulnerabilities
+- [x] `bundle exec bundler-audit check` — 0 vulnerabilities
+- [x] `bundle exec rubocop` — 0 offenses (custom cops active)
+- [x] `bundle exec reek lib/` — 0 warnings
+- [x] `bundle exec rspec` — 437 examples, 0 failures
+- [x] `bundle exec mutant run` — 97.83% kill rate
+- [x] No `YAML.load` calls in codebase (cop enforced)
+- [x] No interpolated system/exec/spawn/backtick calls (cop enforced)
+- [x] All File.open/File.write use explicit permissions
+- [x] SecretsResolver validates 0600 on secrets file