rosett-ai 1.3.3 → 1.5.9

data/doc/ADOPT.md

@@ -1,224 +0,0 @@
-# Rosett-AI - Adopt System
-
-## Overview
-
-The `adopt` command analyzes compiled rule files in `~/.claude/rules/` for quality and safety issues.
-It uses the Claude API to detect inconsistencies, conflicts, harmful content, jailbreaking attempts,
-duplicates, and other problems across your rule set.
-
-## How It Works
-
-1. Discovers managed rule files (those with `<!-- Generated by rosett-ai` markers) in `~/.claude/rules/`
-2. Filters out files whose source behaviour YAML is marked `sensitive: true`
-3. Checks the cache — if file contents haven't changed since the last analysis, returns cached results
-4. Applies redaction patterns from `conf/adopt_redactions.yml` to file contents
-5. Sends redacted content to the Claude API for analysis
-6. Runs local structural checks on all files (including sensitive ones)
-7. Merges API and local findings into a unified report
-8. Caches the result for future runs
-
-## CLI Usage
-
-```bash
-# Full API analysis
-bin/raictl adopt
-
-# Local-only structural checks (no API)
-bin/raictl adopt --local
-
-# Verbose output
-bin/raictl adopt --verbose
-
-# Detailed explanations
-bin/raictl adopt --elaborate
-
-# All flags combined
-bin/raictl adopt --elaborate --verbose
-```
-
-### Flags
-
-| Flag | Effect |
-|------|--------|
-| `--local` | Skip API calls, run structural checks only |
-| `--verbose` | Show file counts, checksums, cache status, skipped sensitive files |
-| `--elaborate` | Add an "Explanation" column to the findings table |
-
-## Finding Categories
-
-The analysis detects these categories of issues:
-
-| Category | Description |
-|----------|-------------|
-| `inconsistencies` | Rules that contradict each other in intent or wording |
-| `conflicts` | Rules that directly conflict and cannot both be followed |
-| `harmful` | Rules that instruct harmful actions |
-| `illegal` | Rules that instruct illegal activities |
-| `jailbreaking` | Rules that attempt to bypass AI safety measures |
-| `rule_breaking` | Rules that instruct breaking other rules |
-| `duplicates` | Rules with the same ID or identical descriptions across files |
-| `other` | Other structural or content issues |
-
-### Severity Levels
-
-| Severity | Meaning |
-|----------|---------|
-| `critical` | Must be fixed immediately — safety or compliance risk |
-| `high` | Should be fixed — significant quality issue |
-| `medium` | Worth addressing — potential confusion or redundancy |
-| `low` | Minor observation — nice to fix |
-
-### Overall Status
-
-| Status | Meaning |
-|--------|---------|
-| `pass` | No issues found |
-| `warn` | Low or medium severity findings only |
-| `fail` | High or critical severity findings |
-
-## Data Privacy
-
-Four layers of protection ensure sensitive content is handled appropriately.
-
-### 1. Opt-in Per File (Default)
-
-Add `sensitive: true` to a behaviour YAML file to exclude its compiled output from API analysis:
-
-```yaml
-name: internal_security
-description: Internal security policies
-version: 1.0.0
-sensitive: true
-rules:
-  - id: sec_001
-    description: Internal policy details
-    priority: 90
-    enabled: true
-```
-
-Sensitive files are still checked locally for structural issues (duplicate IDs, empty descriptions, missing priorities). They are reported as "skipped (sensitive)" in verbose output.
-
-### 2. Redaction
-
-Configure regex patterns in `conf/adopt_redactions.yml` to replace sensitive content before it reaches the API:
-
-```yaml
----
-patterns:
-  - pattern: '\b[A-Z0-9._%+-]+@neatnerds\.be\b'
-    replacement: '[EMAIL-REDACTED]'
-  - pattern: 'NeatNerds'
-    replacement: '[COMPANY]'
-  - pattern: 'gitlab\.neatnerds\.be'
-    replacement: '[INTERNAL-URL]'
-```
-
-Redaction is applied in-memory only — original files are never modified.
-
-### 3. Configurable Endpoint
-
-Set the `ANTHROPIC_API_BASE_URL` environment variable to route API calls through a private endpoint:
-
-```bash
-# Use AWS Bedrock
-export ANTHROPIC_API_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com
-
-# Use a corporate proxy
-export ANTHROPIC_API_BASE_URL=https://ai-proxy.internal.company.com
-```
-
-### 4. Local-Only Mode
-
-Use `--local` to skip API calls entirely. Only structural checks are performed:
-
-- Duplicate rule IDs across files
-- Empty or blank rule descriptions
-- Rules without priority set
-- Identical rule descriptions across different rule IDs
-
-```bash
-bin/raictl adopt --local --verbose
-```
-
-## Caching
-
-Results are cached in `conf/adopt.cache.yml`. The cache key is a SHA256 hash of all analyzed file contents (after filtering sensitive files). When files haven't changed, the cached result is returned without an API call.
-
-### Cache Format
-
-```yaml
----
-checksum: "sha256hex..."
-analyzed_at: "2026-01-29T12:00:00Z"
-result:
-  findings: [...]
-  overall_status: pass
-  summary: "No issues detected"
-```
-
-### Invalidating the Cache
-
-The cache is automatically invalidated when any managed rule file changes. To force a fresh analysis, delete the cache file:
-
-```bash
-rm conf/adopt.cache.yml
-bin/raictl adopt
-```
-
-## Local Structural Checks
-
-These checks run on all files (including sensitive ones) regardless of `--local`:
-
-| Check | Category | Severity |
-|-------|----------|----------|
-| Duplicate rule ID across files | `duplicates` | medium |
-| Empty/blank rule description | `other` | medium |
-| Missing priority | `other` | low |
-| Identical descriptions on different rule IDs | `duplicates` | low |
-
-## Environment Variables
-
-| Variable | Purpose | Required |
-|----------|---------|----------|
-| `ANTHROPIC_API_KEY` | API authentication key | Yes (API mode) |
-| `ANTHROPIC_API_BASE_URL` | Custom API endpoint | No |
-
-## Workflow Integration
-
-### Recommended Workflow
-
-```bash
-# 1. Compile behaviours to rules
-bin/raictl compile --verbose
-
-# 2. Run local checks first
-bin/raictl adopt --local --verbose
-
-# 3. Run full API analysis
-bin/raictl adopt --verbose
-
-# 4. Fix findings and recompile
-bin/raictl compile --verbose
-
-# 5. Verify fixes
-bin/raictl adopt --verbose
-```
-
-### CI/CD Integration
-
-```bash
-# In CI pipeline — local checks only (no API key needed)
-bin/raictl adopt --local || exit 1
-
-# Or with API key available
-ANTHROPIC_API_KEY=$CI_ANTHROPIC_KEY bin/raictl adopt || exit 1
-```
-
-## Architecture
-
-The adopt system consists of two components:
-
-- **`RosettAi::Adopter::RuleAdopter`** (`lib/rosett_ai/adopter/rule_adopter.rb`) — Core logic for file discovery, caching, redaction, API interaction, and local analysis
-- **`RosettAi::Thor::Tasks::Adopt`** (`lib/rosett_ai/thor/tasks/adopt.rb`) — Thor CLI task providing terminal output with tables, spinners, and colored status indicators
-
-The adopter uses the official [Anthropic Ruby SDK](https://github.com/anthropics/anthropic-sdk-ruby) (`anthropic` gem v1.16+) for API communication.

data/doc/AI_PROVENANCE.md

@@ -1,139 +0,0 @@
-# AI Provenance
-
-Transparency declaration for AI-assisted development in rosett-ai v1.0.0.
-
-## Overview
-
-raictl (Rosett-AI) was developed through human-AI collaboration.
-This document declares the scope and nature of AI involvement in accordance
-with responsible AI disclosure practices.
-
-## AI Tools Used
-
-| Tool | Model | Role |
-|------|-------|------|
-| Claude Code (CLI) | Claude Opus 4 / Opus 4.6 / Sonnet 4.5 | Code generation, architecture design, test writing, documentation |
-
-## Human Oversight
-
-All AI-generated code was:
-
-- **Reviewed** by the project author before merge
-- **Validated** by automated quality gates (RSpec, RuboCop, Reek, Mutant, bundler-audit, ruby-audit, gitleaks)
-- **Tested** against 1321 core RSpec examples + 458 engine gem examples (1779 total) with 86%+ line coverage
-- **Mutation-tested** via Mutant at 97.83% kill rate on critical subjects
-- **Architecturally directed** by human decisions documented in ADRs
-
-## Scope of AI Contribution
-
-### Architecture & Design
-
-AI assisted with:
-
-- Engine-agnostic architecture design (ADR-007, Q&A sessions Q1-Q9)
-- Design document authoring (23 design docs in `conf/design/`)
-- Implementation planning and phasing
-
-All architectural decisions were made by the human author. AI provided
-options, trade-off analysis, and implementation suggestions that were
-accepted, modified, or rejected by the author.
-
-### Code Generation
-
-AI generated initial implementations for:
-
-- Engine backends (11 engines: claude, generic, agents_md, ollama, gpt_neox, goose, aider, cursor, copilot, windsurf, acme)
-- Pluggable plugin architecture (contract modules, dynamic registry, `Gem.find_files` discovery)
-- Engine extraction to external gems (11 `rosett-ai-engine-*` gems including ACME reference)
-- D-Bus service interfaces and focus adapters
-- GTK4/Adwaita desktop application
-- Quorum multi-engine analysis module
-- Compiler pipeline and capability checker
-- CLI Thor tasks and subcommands
-- Custom RuboCop cops (ShellInterpolation, UnsafeYamlLoad)
-- JSON schemas for validation
-
-### Test Suite
-
-AI generated:
-
-- RSpec examples (1307 core + 458 engine gems = 1765 total, across 100+ spec files)
-- Engine stub infrastructure (`spec/support/stub_engines.rb`) for core-only testing without engine gems
-- Factory definitions (factory_bot)
-- Property-based tests (Rantly)
-- Test fixtures (valid, invalid, malicious, Unicode)
-
-### Documentation
-
-AI generated initial drafts for:
-
-- Man page (`doc/man/rai.1.ronn`)
-- ARCHITECTURE.md (with Mermaid diagrams)
-- USAGE.md, INSTALL.md, CONTRIBUTING.md
-- CHANGELOG.md entries
-- ADR documents
-
-### Build System & Packaging
-
-AI assisted with:
-
-- Build system fixes (Gemfile engine decoupling, Bundler env var cleanup)
-- Wrapper script template with runtime path substitution (`@@RUBY_ABI@@`, `@@RUBY_ARCH@@`)
-- Engine .deb packaging infrastructure (`build-engine-deb.sh`, per-engine `build-deb.sh`)
-- CI pipeline fixes (prefix-aware cache, smoke test without system Ruby)
-
-### CI/CD Pipeline
-
-AI assisted with:
-
-- GitLab CI job definitions
-- Security scan configuration
-- Release pipeline design
-- Package build scripts (fpm)
-
-## What AI Did NOT Do
-
-- **No unsupervised deployments** — all commits reviewed before push
-- **No credential handling** — secrets managed exclusively by human
-- **No production access** — AI operated only on development workstation
-- **No dependency selection** — gem choices made by human author
-- **No license decisions** — GPL-3.0-only chosen by human author
-
-## Commit Attribution
-
-AI-assisted commits include the trailer:
-
-```text
-Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
-```
-
-Earlier commits may use `Claude Sonnet 4.5` or `Claude Opus 4` depending
-on the model version active at the time.
-
-## Verification
-
-The following quality gates run on every commit and MR:
-
-| Gate | Tool | Threshold |
-|------|------|-----------|
-| Unit tests | RSpec | 0 failures |
-| Line coverage | SimpleCov | 88% overall, 25% per file |
-| Mutation testing | Mutant | Score tracked, no regression |
-| Style | RuboCop | 0 offenses (224 core + 147 engine gem files) |
-| Code smells | Reek | 0 smells |
-| Gem vulnerabilities | bundler-audit | 0 advisories |
-| Ruby vulnerabilities | ruby-audit | 0 advisories |
-| Secret detection | gitleaks | 0 findings |
-| Schema validation | json_schemer | 25 config files valid |
-
-## Contact
-
-For questions about AI involvement in this project:
-
-- Author: Hugo Antonio Sepulveda Manriquez
-- Email: query@neatnerds.be
-- License: GPL-3.0-only
-
----
-
-*Last updated: 2026-03-08 | rosett-ai v1.0.0 + pluggable-engines + engine .deb packaging*