rosett-ai 1.3.3

data/conf/design/release_management.yml

@@ -0,0 +1,117 @@
+---
+name: release_management
+domain: release
+version: 0.2.0
+status: implemented
+priority: 5
+author: claude
+created_at: "2026-02-22"
+modified_at: "2026-03-17"
+modified_by: claude
+depends_on:
+  - ci_pipeline
+  - lifecycle_management
+  - testing
+
+intent: |
+  Define a repeatable, automated process for releasing rosett-ai versions. Every
+  release today requires manual version edits, manual CHANGELOG writing, manual
+  tag creation, and manual CI coordination. This creates inconsistency risk
+  (version drift across files), omission risk (forgetting CHANGELOG entries),
+  and human error (wrong tag format, missed verification step).
+
+  With release management:
+  - Version bumping is atomic — all files updated in one operation
+  - CHANGELOG entries are generated from conventional commit history
+  - Tags are annotated with release notes
+  - The verification suite is mandatory before any release commit
+  - CI creates GitLab releases automatically on tag push
+
+  Without release management:
+  - Manual edits to lib/rosett_ai/version.rb, CHANGELOG.md, gemspec
+  - Version references drift (SETUP.md said 4.0.0 while .ruby-version said 3.3.10)
+  - Release timing is ad-hoc with no checklist
+  - No auditable trail connecting a tag to its verification results
+
+constraints:
+  - Version follows Semantic Versioning 2.0.0 (semver.org) — MAJOR.MINOR.PATCH
+  - CHANGELOG follows Keep a Changelog 1.1.0 format (keepachangelog.com)
+  - Every release MUST pass the full verification suite before the release commit (rspec, rubocop, reek, bundler-audit, ruby-audit)
+  - Version references MUST be updated atomically — reuse lifecycle_management's atomic version update principle
+  - "Git tags MUST be annotated (not lightweight) and follow the pattern v{MAJOR}.{MINOR}.{PATCH}"
+  - "Release commits use the conventional commit format chore(release): prefix"
+  - No release may skip the pre-commit hooks — the release process calls git commit normally
+  - The release process MUST NOT push automatically — push is a separate explicit step (safety)
+  - CHANGELOG generation uses git-cliff with conventional commit parsing
+  - The version source of truth is lib/rosett_ai/version.rb — all other references derive from it
+
+acceptance_criteria:
+  - "A Thor task bin/raictl release prepare LEVEL (major|minor|patch) bumps version and updates CHANGELOG"
+  - The prepare task updates version in lib/rosett_ai/version.rb, CHANGELOG.md (moves Unreleased to versioned section), and creates a release commit
+  - bin/raictl release tag creates an annotated git tag vX.Y.Z from the current VERSION constant
+  - bin/raictl release status shows current version, unreleased changes count, and last tag
+  - All files containing version references are updated atomically (grepped and verified — lifecycle_management pattern)
+  - CHANGELOG entries are generated from conventional commits between the last tag and HEAD
+  - CI job release:publish triggers on tag push and creates a GitLab release with CHANGELOG excerpt
+  - Running bin/raictl release prepare with uncommitted changes aborts with a clear error
+  - Running bin/raictl release prepare with failing verification suite aborts before version bump
+  - git-cliff configuration file (cliff.toml) exists with conventional commit type mapping
+
+examples:
+  - scenario: "Releasing version 0.2.0 after adding P5 features"
+    expected: |
+      1. Developer runs: bin/raictl release prepare minor
+      2. Tool verifies working tree is clean (no uncommitted changes)
+      3. Tool runs full verification suite (rspec, rubocop, reek, audits)
+      4. Tool bumps version: 0.1.0 → 0.2.0 in lib/rosett_ai/version.rb
+      5. Tool generates CHANGELOG section from conventional commits since v0.1.0
+      6. Tool moves [Unreleased] content to [0.2.0] section with date
+      7. Tool creates commit: 'chore(release): prepare v0.2.0'
+      8. Developer reviews commit, then runs: bin/raictl release tag
+      9. Tool creates annotated tag v0.2.0 with CHANGELOG excerpt as message
+      10. Developer pushes: git push origin design_implementation --tags
+      11. CI detects tag, creates GitLab release with notes
+    not: |
+      Tool auto-pushes to remote. Tool creates tag before commit.
+      Tool skips verification. Tool uses lightweight tag.
+      CHANGELOG section is empty or missing date.
+
+  - scenario: "Attempting release with uncommitted changes"
+    expected: |
+      bin/raictl release prepare patch
+      → Error: "Working tree has uncommitted changes. Commit or stash before releasing."
+      No files are modified. Exit code 1.
+    not: |
+      Silently proceed with dirty working tree. Offer to auto-commit changes.
+
+  - scenario: "Attempting release when rspec has failures"
+    expected: |
+      bin/raictl release prepare minor
+      → Runs rspec, detects 2 failures
+      → Error: "Verification suite failed (rspec: 2 failures). Fix issues before releasing."
+      No version bump occurs. Exit code 1.
+    not: |
+      Bump version anyway with a warning. Skip verification.
+
+anti_patterns:
+  - Auto-pushing to remote as part of the release process (push must be explicit)
+  - Editing CHANGELOG manually when automation exists (defeats the purpose)
+  - Using lightweight git tags (cannot store release notes, unsigned)
+  - Skipping verification with --force or --no-verify flags
+  - Bumping version in some files but not others (atomic or nothing)
+  - Creating a release from a dirty working tree
+  - Releasing from a branch other than the designated release branch without explicit intent
+  - Coupling version bump and tag creation into one command (review step between them is valuable)
+
+preferences:
+  language: ruby
+  gems:
+    - thor
+  patterns:
+    - conventional_commits
+    - atomic_version_updates
+    - fail_fast_on_invalid_state
+  testing: rspec for release task unit tests with filesystem mocking
+  tools:
+    changelog: git-cliff
+    tag_format: "v%M.%m.%p"

data/conf/design/retrofit.yml

@@ -0,0 +1,199 @@
+---
+name: retrofit
+domain: core
+version: 0.1.0
+status: implemented
+priority: 2
+author: hugo
+created_at: "2026-03-16"
+modified_at: "2026-03-16"
+modified_by: claude
+depends_on:
+  - architecture
+  - compiler
+  - security
+  - engine_architecture
+  - claude_code_configuration
+  - error_handling
+#
+intent: |
+  Provide a reverse-compilation command (`rai retrofit`) that reads existing
+  AI tool configuration files from the local filesystem and generates
+  rosett-ai-managed YAML source files. Where `rai compile` transforms authored
+  YAML into native formats, retrofit transforms native formats back into
+  authored YAML — making ad-hoc, hand-edited configurations reproducible,
+  version-controllable, and shareable across projects and teams. Each engine
+  provides a retrofit adapter that knows how to parse its native config
+  format into the Rosett-AI schema.
+
+  Retrofit complements two adjacent commands: `rai init` creates the empty
+  .rosett-ai/ project structure, and `rai compile` transforms source YAML into
+  native formats. Retrofit closes the loop by importing existing native
+  configs back into source YAML. The lifecycle is:
+  init (scaffold) → retrofit (import) → edit → compile (deploy).
+  `rai project drift` (project_management.yml) detects when compiled output
+  diverges from source; `rai retrofit --simulate` detects the reverse —
+  when native configs diverge from what source YAML would produce.
+#
+constraints:
+  - "Retrofit is the only rosett-ai tool permitted to write to source YAML
+    directories — compiler.yml's 'source documents are never modified by
+    compilation' constraint explicitly exempts retrofit as a controlled
+    reverse-compilation operation"
+  - "Retrofit must never modify existing native config files — it is
+    read-only against them"
+  - "Generated YAML must pass `bin/raictl validate` without errors"
+  - "Generated YAML must round-trip — `rai compile` on retrofit output
+    must produce semantically equivalent native config (idempotent cycle)"
+  - "Retrofit must use engine-specific adapters — each engine gem provides
+    its own parser for native config discovery and extraction"
+  - "When no engine is specified, retrofit must auto-detect installed tools
+    by probing standard config paths (e.g. ~/.claude/, .cursor/, .github/)"
+  - "Retrofit must not silently overwrite existing Rosett-AI YAML files — prompt
+    for confirmation or require --force flag"
+  - "All file reads must validate paths against allowed directories (no
+    symlink traversal, no reads outside HOME)"
+  - "Sensitive values (API keys, tokens) detected in native configs must be
+    replaced with ${secret:env:NAME} references, never written as plaintext"
+  - "Retrofit output must include provenance metadata (source_file,
+    retrofit_date, engine, rai_version) as YAML comments"
+  - "YAML parsing of native files must use YAML.safe_load only"
+  - "Retrofit must work without network access — purely local file analysis"
+  - "Multiple engines can be retrofitted in a single invocation"
+  - "Unknown keys preserved as YAML comments must be sanitized — strip ANSI
+    escape sequences and control characters before writing (per security.yml)"
+  - "Retrofit complements `rai init` — init creates empty project structure,
+    retrofit populates it from existing native configs (init first, then
+    retrofit to import existing settings)"
+  - "This design governs reverse-compilation (native → source YAML). Forward
+    compilation (source → native) is governed by compiler.yml. Project
+    lifecycle management (drift, sync, templates) is governed by
+    project_management.yml"
+#
+acceptance_criteria:
+  - "`rai retrofit` auto-detects Claude Code config at ~/.claude/settings.json
+    and generates conf/claude_code/user.yml"
+  - "`rai retrofit --engine claude` targets Claude Code files specifically"
+  - "`rai retrofit --engine cursor` targets Cursor config files specifically"
+  - "Generated YAML files include all non-default settings from the source
+    config"
+  - "API keys and tokens in source configs are replaced with
+    ${secret:env:*} references"
+  - "Existing Rosett-AI YAML files are not overwritten without --force or
+    confirmation"
+  - "`rai retrofit --simulate` shows what files would be generated without
+    writing, using TTY-aware diff output (colour when interactive, plain
+    when piped)"
+  - "Round-trip test: retrofit then compile produces semantically equivalent
+    config"
+  - "Unknown or unsupported config keys are preserved as comments in the
+    generated YAML"
+  - "Retrofit generates a manifest (conf/retrofit_manifest.yml) listing
+    source files, extraction date, and engine versions"
+  - "Exit code 0 on success, 3 on config parse failure, 5 on missing
+    engine adapter"
+#
+examples:
+  - scenario: "Developer joins a project that already has .claude/settings.json hand-edited"
+    expected: |
+      `rai retrofit` reads .claude/settings.json, generates
+      conf/claude_code/project.yml with all settings expressed as
+      snake_case YAML. Developer commits the YAML and the team can
+      now reproduce the config via `rai compile`.
+    not: |
+      Developer manually transcribes JSON keys to YAML. Settings are
+      lost or mistyped. Team members have inconsistent configs.
+  - scenario: "Native config contains an ANTHROPIC_API_KEY in plaintext"
+    expected: |
+      Generated YAML contains `api_key: "${secret:env:ANTHROPIC_API_KEY}"`.
+      A warning is emitted: "Sensitive value detected in source — replaced
+      with secret reference. Set ANTHROPIC_API_KEY in your environment."
+    not: |
+      API key is written to the YAML file in plaintext. Secret is silently
+      dropped or the field is omitted.
+  - scenario: "User runs retrofit but conf/claude_code/user.yml already exists"
+    expected: |
+      Retrofit shows a diff of what would change and prompts for
+      confirmation. --force skips the prompt. --simulate shows the diff
+      without writing.
+    not: |
+      Existing YAML is silently overwritten. User loses their authored
+      config.
+  - scenario: "Team migrates from Cursor to Claude Code"
+    expected: |
+      `rai retrofit --engine cursor` imports Cursor config as Rosett-AI YAML.
+      `rai compile --engine claude` writes Claude Code native config.
+      Team commits the YAML — any member can compile for their preferred
+      engine.
+    not: |
+      Developer manually translates Cursor JSON to Claude JSON. Settings
+      are lost or mistyped. No version control.
+  - scenario: "Detecting reverse drift — native config was hand-edited after compile"
+    expected: |
+      `rai retrofit --simulate` shows a diff between current native
+      config and what the source YAML would generate. Effectively reverse
+      drift detection. See also: `rai project drift` for forward drift
+      (source → native).
+    not: |
+      No way to detect that someone hand-edited the native config after
+      compile.
+  - scenario: "Source config contains keys that rosett-ai does not recognise"
+    expected: |
+      Unknown keys are included in the generated YAML with a comment:
+      "# Unknown key — not in rosett-ai schema, preserved for compatibility".
+      A warning lists all unknown keys.
+    not: |
+      Unknown keys are silently dropped. Compiled output differs from
+      original.
+#
+anti_patterns:
+  - "Hardcoding config file paths instead of using engine adapter discovery"
+  - "Writing sensitive values to generated YAML without secret references"
+  - "Modifying native config files during the retrofit process"
+  - "Requiring network access to determine config structure"
+  - "Losing config values during the retrofit-compile round-trip"
+  - "Generating YAML that fails rosett-ai schema validation"
+  - "Silent overwrite of existing rosett-ai-managed YAML files"
+  - "Coupling retrofit logic to a single engine instead of using adapters"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. compiler.yml: compile transforms source → native; retrofit transforms
+     native → source. Retrofit is explicitly exempted from the compiler's
+     "source documents are never modified" constraint.
+
+  2. project_management.yml: `rai project drift` detects forward drift
+     (source → compiled). `rai retrofit --simulate` detects reverse drift
+     (native → source).
+
+  3. engine_architecture.yml: each engine provides a retrofit adapter via
+     its manifest. Adapters parse native config formats into rosett-ai schema.
+
+  4. security.yml: YAML.safe_load, path validation, secret redaction,
+     ANSI/control character stripping for unknown keys.
+
+  5. claude_code_configuration.yml: the Claude engine's retrofit adapter
+     parses settings.json, skills, hooks, and memory files.
+
+  6. error_handling.yml: exit codes and structured error messages follow
+     the error hierarchy (what/why/fix format).
+
+  7. architecture.yml: `rai init` creates the .rosett-ai/ structure that
+     retrofit populates. The lifecycle is: init → retrofit → edit → compile.
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Adapter pattern for engine-specific parsers"
+    - "Reverse compiler pipeline (native → source)"
+    - "Secret detection and redaction"
+    - "Round-trip validation (retrofit → compile → compare)"
+    - "TTY-aware diff output"
+  testing: rspec with fixture-based round-trip tests, secret detection
+    scenarios, multi-engine retrofit, overwrite protection, and unknown
+    key preservation tests
+  gems:
+    - json_schemer
+    - diffy
+    - thor

data/conf/design/retrospective_analyzer.yml

@@ -0,0 +1,79 @@
+---
+name: retrospective_analyzer
+domain: operations
+version: 0.1.0
+status: draft
+priority: 6
+author: hugo
+created_at: "2026-03-26"
+modified_at: "2026-03-26"
+modified_by: claude
+depends_on:
+  - compiler
+intent: |
+  Close the feedback loop between session retrospectives and rai behaviour
+  rules. Currently, retrospectives produce markdown files with Process Changes
+  (checkbox lists) and Failure Preventive Actions, but these remain as
+  unchecked items unless manually converted to rules.
+
+  This design adds a `bin/raictl retrospective` subcommand that parses
+  retrospective files, classifies findings into categories (behavioural,
+  tooling, process, mcp, memory), proposes rosett-ai resources, and tracks which
+  findings have been acted on.
+
+  CLI interface:
+    bin/raictl retrospective analyze [--path FILE] [--all] [--dry-run] [--verbose]
+    bin/raictl retrospective list
+    bin/raictl retrospective status
+
+  Ruby modules (lib/rosett_ai/retrospective/):
+    finding_parser.rb       - Extracts Process Changes and Preventive Actions
+    finding_classifier.rb   - Keyword-based classification (offline, no API)
+    proposal_builder.rb     - Generates candidate behaviour rule YAML
+    proposal_presenter.rb   - Renders approval prompt via tty-prompt
+
+  Thor task: lib/rosett_ai/thor/tasks/retrospective.rb (follows adopt.rb pattern)
+
+  State tracking via conf/retrospective.cache.yml (gitignored) recording
+  which findings have been converted to rules, with finding hash, category,
+  target behaviour, and acted-at timestamp.
+
+  Estimation: 5-6 hours (4 modules + Thor task + RSpec coverage).
+constraints:
+  - Must work offline with keyword-based classification (no API calls by default)
+  - Must not break existing compile workflow
+  - User must approve all proposed changes (staged execution with approval gates)
+  - Must follow the adopt.rb Thor task pattern (spinner, verbose flags, result printing)
+  - Ruby only, GPL-3.0-only
+  - Must conform to behaviour schema v1.1.0 when generating rule proposals
+acceptance_criteria:
+  - bin/raictl retrospective list discovers all retrospective-YYYY-MM-DD.md files across ~/.claude/projects/*/memory/
+  - bin/raictl retrospective analyze --dry-run parses findings and shows classified proposals without modifying any files
+  - bin/raictl retrospective analyze creates valid behaviour rules that pass bin/raictl behaviour validate
+  - bin/raictl retrospective status shows the backlog of unacted findings
+  - FindingParser extracts both Process Change checkboxes and Preventive Action lines
+  - FindingClassifier correctly categorizes at least 80% of findings from the existing 3 retrospectives
+  - No rule ID collisions with existing behaviour rules
+  - RSpec coverage for all 4 modules in spec/rosett_ai/retrospective/
+examples:
+  - scenario: User runs analyze on a retrospective with 5 process changes
+    expected: 5 findings extracted, classified, and presented as proposals grouped by category
+  - scenario: User approves a behavioural proposal
+    expected: Rule added to operational_discipline.yml, validated, compiled to ~/.claude/rules/
+  - scenario: User runs status after acting on 3 of 5 findings
+    expected: Shows 2 pending findings with source retrospective and date
+anti_patterns:
+  - Auto-executing behaviour modifications without user approval
+  - Using API calls for classification when offline heuristics suffice
+  - Generating duplicate rules that overlap with existing session_retrospective.yml
+  - Merging the retrospective cache with the adopt cache (different concerns)
+preferences:
+  language: ruby
+  patterns:
+    - Thor subcommand (thin task delegating to domain modules)
+    - Keyword-based heuristic classification
+    - SHA256 finding hash for deduplication
+  testing: rspec
+  gems:
+    - tty-prompt (approval prompts)
+    - tty-spinner (progress indication)