rosett-ai 1.3.3 → 1.5.9

data/conf/design/ai_provenance.yml

@@ -1,224 +0,0 @@
----
-name: ai_provenance
-domain: security
-version: 0.1.0
-status: implemented
-priority: 2
-author: hugo
-created_at: "2026-03-10"
-modified_at: "2026-03-16"
-modified_by: claude
-depends_on:
-  - security
-  - engine_architecture
-  - compiler
-  - error_handling
-  - ai_authorship
-#
-intent: |
-  Establish structured, machine-readable provenance tracking for AI involvement
-  in code contributions managed by Rosett-AI. Record which AI tools contributed to
-  which files, what role the AI played, and what external sources it drew from.
-
-  raictl already manages rules for multiple AI engines. This design extends
-  that to track provenance — the "who did what with which AI" metadata that
-  enables compliance auditing, license verification, and transparent
-  attribution in open-source projects.
-
-  Inspired by the OpenVox MCP Server's .ai-provenance.yml format (B3),
-  adapted for Rosett-AI's engine-agnostic, multi-tool architecture. Where
-  openvox-mcp tracks provenance for a single project, rosett-ai manages it
-  across all projects the user works on, compiling provenance metadata
-  alongside behaviour rules.
-
-  Provenance is the recording layer — it creates an audit trail of what
-  each AI tool did, per commit, with file-level granularity. The related
-  ai_authorship.yml design handles attribution and crediting — how AI
-  contributions are presented in commit trailers, AGENTS.md, and other
-  public-facing outputs. Policy management (policy_management.yml)
-  governs the requirements — which projects require provenance, at what
-  level, and what happens when provenance is missing.
-
-  Key capabilities:
-    - Per-commit AI provenance entries with file-level granularity
-    - Source type classification (library_api, project_code, documentation,
-      pattern, external_source) for license traceability
-    - Commit trailer generation (AI-Generated-By, AI-Co-Author,
-      AI-Assisted-By, AI-Reviewed-By) across all supported engines
-    - Engine-specific provenance: each engine records its own identity
-    - Compilation target: provenance YAML compiles to commit hooks,
-      CI validation rules, or AGENTS.md attribution sections
-    - A single commit may have provenance entries from multiple engines
-      (e.g. Ollama for local analysis, Claude for generation)
-#
-constraints:
-  - "Provenance file (.ai-provenance.yml) must use YAML.safe_load only"
-  - "Provenance entries are append-only — existing entries must never be
-    modified or deleted"
-  - "Each provenance entry must include a SHA-256 hash of the previous
-    entry (hash chain), creating a tamper-evident append-only log.
-    The first entry uses a zero hash. Validation checks the chain
-    integrity"
-  - "Source URLs for external_source type must reference specific pages,
-    not bare domains"
-  - "All provenance data must be storable offline — no mandatory network calls"
-  - "Commit trailers must follow the format: Trailer — Tool Version
-    (Provider) <email>"
-  - "Provenance validation must work without any engine installed (core feature)"
-  - "File paths in provenance entries must be relative to project root"
-  - "Provenance schema must be versioned independently from rosett-ai version"
-  - "No personally identifiable information beyond what git already stores
-    (name + email)"
-  - "Provenance entries must be validated before being written to disk"
-  - "When a provenance file exceeds a configurable size threshold (default
-    1 MB), rosett-ai must offer archival: move older entries to a dated archive
-    file (.ai-provenance.YYYY.yml) and start a new active file with the
-    last entry's hash as the chain root"
-  - "This design governs provenance recording (audit trail of AI involvement).
-    Attribution and crediting of AI contributions is governed by
-    ai_authorship.yml. Policy requirements for provenance (which projects
-    require it, at what level) are governed by policy_management.yml"
-#
-acceptance_criteria:
-  - "bin/raictl provenance init creates .ai-provenance.yml in project root
-    with version header and zero-hash chain root"
-  - "bin/raictl provenance add creates a new entry with commit, contributor,
-    ai_tool, ai_role, files, and hash chain link"
-  - "bin/raictl provenance validate checks all entries against the provenance
-    schema and verifies hash chain integrity"
-  - "bin/raictl provenance show COMMIT displays provenance for a specific commit"
-  - "bin/raictl provenance show --file PATH displays all provenance entries
-    for a file"
-  - "bin/raictl provenance log shows all entries in reverse chronological order
-    using TTY-aware output (table when interactive, plain text when piped)"
-  - "bin/raictl provenance log --role AI-Co-Author filters entries by AI role"
-  - "Commit trailers (AI-Generated-By etc.) are generated from provenance
-    entries during compile"
-  - "Engine name and version are automatically populated from the active
-    engine's manifest"
-  - "Source type is validated against the allowed list (library_api,
-    project_code, documentation, pattern, external_source)"
-  - "External sources with bare domain URLs are rejected with a clear
-    error message"
-  - "Provenance file exceeding the size threshold triggers archival
-    recommendation"
-  - "All provenance operations work without network access"
-  - "Provenance entries survive round-trip (load → save produces identical YAML)"
-  - "Exit code 0 on success, 1 on write failure, 2 on validation error,
-    3 on hash chain integrity failure, 5 on missing provenance file"
-#
-examples:
-  - scenario: "Developer uses Claude to write a new module, runs bin/raictl provenance add"
-    expected: |
-      Entry created with ai_tool: "Claude Opus 4.6 (Anthropic)",
-      ai_role: "AI-Co-Author", commit SHA from HEAD, contributor from
-      git config. File paths listed with source references. Hash chain
-      links to previous entry's SHA-256.
-    not: "Entry silently created without validation. AI tool name guessed incorrectly."
-  - scenario: "CI pipeline validates provenance on a pull request"
-    expected: |
-      bin/raictl provenance validate checks every commit in the PR has a
-      matching provenance entry. Missing entries produce warnings at
-      advisory level or errors at strict level. Hash chain is verified.
-    not: "Validation requires network access. Missing provenance silently passes."
-  - scenario: "Developer uses Ollama locally, no internet access"
-    expected: |
-      bin/raictl provenance add --engine ollama records provenance with
-      ai_tool from ollama engine manifest. Works completely offline.
-    not: "Provenance recording fails because it cannot reach an API."
-  - scenario: "A provenance entry references a StackOverflow answer"
-    expected: |
-      Source type: external_source, reference: "Answer by user123 on
-      handling thread safety in Ruby", url: specific answer URL.
-      Validated successfully.
-    not: "URL is just https://stackoverflow.com/ — rejected as too vague."
-  - scenario: "Developer views provenance history for a project"
-    expected: |
-      `rai provenance log` shows reverse chronological entries:
-      ┌───────────┬─────────────────┬───────────────┬──────────────┐
-      │ Commit    │ AI Tool         │ Role          │ Files        │
-      ├───────────┼─────────────────┼───────────────┼──────────────┤
-      │ abc1234   │ Claude Opus 4.6 │ AI-Co-Author  │ lib/foo.rb   │
-      │ def5678   │ Ollama llama3.3 │ AI-Assisted   │ spec/bar.rb  │
-      └───────────┴─────────────────┴───────────────┴──────────────┘
-      Piped output: tab-separated, no box drawing.
-    not: "No way to see provenance history. Must read YAML file manually."
-  - scenario: "Provenance file is corrupted — hash chain broken"
-    expected: |
-      `rai provenance validate` detects the break: 'Hash chain integrity
-      failure at entry #7: expected abc123..., got def456...'. Exit code 3.
-      Identifies the exact entry where tampering occurred.
-    not: "Corruption goes undetected. Provenance file accepted as valid."
-  - scenario: "Provenance file exceeds 1 MB after months of development"
-    expected: |
-      `rai provenance add` warns: 'Provenance file exceeds 1 MB — run
-      `rai provenance archive` to move older entries to a dated archive'.
-      Archive creates .ai-provenance.2026.yml with entries before cutoff.
-      New active file starts with the last archived entry's hash as root.
-    not: "File grows unbounded. No archival mechanism. Parsing slows down."
-#
-anti_patterns:
-  - "Storing provenance in a database instead of a versionable YAML file"
-  - "Requiring API calls to record provenance"
-  - "Allowing modification of existing provenance entries (append-only)"
-  - "Storing full file contents in provenance (only paths and line references)"
-  - "Using provenance to block contributions (it records, does not gate)"
-  - "Hardcoding AI tool names instead of reading from engine manifests"
-  - "Storing provenance per-engine instead of per-project"
-  - "Provenance entries without hash chain links (unverifiable integrity)"
-#
-gui_notes: |
-  Document interactions (cross-references):
-
-  1. ai_authorship.yml: provenance records what AI did; authorship handles
-     how contributions are attributed and credited in public outputs.
-
-  2. policy_management.yml: policies govern provenance requirements — which
-     projects require provenance, at what strictness level, and what happens
-     when provenance is missing.
-
-  3. security.yml: YAML.safe_load, PII constraints, offline-first.
-
-  4. engine_architecture.yml: engine manifests provide AI tool identity
-     (name, version, provider) for provenance entries.
-
-  5. compiler.yml: provenance compiles to commit hooks, CI validation
-     rules, and AGENTS.md attribution sections.
-
-  6. error_handling.yml: exit codes and structured error messages follow
-     the error hierarchy (what/why/fix format).
-
-  Provenance entry schema outline:
-    version: string (schema version, e.g. "1.0.0")
-    entries:
-      - commit: string (git SHA)
-        timestamp: string (ISO 8601)
-        contributor:
-          name: string (from git config)
-          email: string (from git config)
-        ai_tool:
-          name: string (from engine manifest)
-          version: string
-          provider: string
-          engine: string (rosett-ai engine name)
-        ai_role: AI-Generated-By | AI-Co-Author | AI-Assisted-By | AI-Reviewed-By
-        files:
-          - path: string (relative to project root)
-            source_type: library_api | project_code | documentation | pattern | external_source
-            reference: string (description of source)
-            url: string (optional, must be specific)
-        hash: string (SHA-256 of previous entry, zero-hash for first)
-#
-preferences:
-  language: ruby
-  patterns:
-    - "Append-only log with hash chain integrity"
-    - "Schema-validated entries before write"
-    - "Engine manifest integration for AI tool identity"
-    - "Offline-first recording"
-    - "TTY-aware output (TtyHelper)"
-  testing: rspec with provenance fixtures, round-trip tests, hash chain
-    validation, archival scenarios, and multi-engine provenance entries
-  gems:
-    - json_schemer
-    - thor

data/conf/design/ai_tool_configuration.yml

@@ -1,207 +0,0 @@
----
-name: ai_tool_configuration
-domain: core
-version: 0.1.0
-status: implemented
-priority: 2
-author: hugo
-created_at: "2026-03-10"
-modified_at: "2026-03-16"
-modified_by: claude
-depends_on:
-  - engine_architecture
-  - security
-  - claude_code_configuration
-  - error_handling
-  - compiler
-#
-intent: |
-  Establish the engine-agnostic AI tool configuration and asset management
-  layer for Rosett-AI — model selection, context window settings, token budgets,
-  API routing, operational parameters, and AI tool assets (skills, hooks,
-  memory files, keybindings) that apply across all AI tools.
-
-  Relationship to claude_code_configuration.yml: that document is the Claude
-  engine's implementation of the contracts defined here. It handles Claude
-  Code's specific settings.json format, target paths, and scope routing.
-  This document defines the universal configuration and asset schema that
-  all engines implement. As rosett-ai matures, Claude-specific settings migrate
-  from claude_code_configuration into engine-specific config compiled from
-  this generic layer.
-
-  As developers use multiple AI tools simultaneously (Claude for complex
-  tasks, Ollama for quick local queries, Cursor for inline completions),
-  they need a single place to configure model routing, cost controls,
-  operational parameters, and reusable assets (skills, hooks, memory).
-  raictl compiles these preferences and assets into each tool's native
-  configuration format via the engine capability manifest contract.
-#
-constraints:
-  - This document defines the generic configuration and asset schema.
-    claude_code_configuration.yml documents the Claude engine's specific
-    implementation (target paths, JSON format, scope routing). Engine-specific
-    docs are implementation of the contracts defined here, not independent designs
-  - Configuration must be expressible in YAML without engine-specific keys in the generic layer
-  - Engine-specific overrides live in .rosett-ai/conf/engines/<name>/config.yml
-  - API keys and secrets must never appear in configuration YAML (reference ENV vars or keyring)
-  - Model names in generic config use canonical identifiers mapped per engine
-  - Cost controls are advisory — rosett-ai does not enforce runtime token limits
-  - Configuration validation must work without any engine installed
-  - Compiled configuration must respect security.yml constraints (no secret leakage)
-  - Fallback chains must not silently switch from local to remote models
-  - Temperature and sampling parameters are only set when the engine supports them
-  - Configuration changes must be diffable (YAML format, no binary blobs)
-  - AI tool asset types (skills, hooks, memory, keybindings, and others) are
-    declared by each engine's capability manifest as a contract. Core defines
-    the generic asset schema; engines declare which asset types they support,
-    their target paths, and compilation formats
-  - Asset content (skills, hooks) must be validated against ANSI and control
-    character stripping (per security.yml). Hook assets must use array-form
-    execution only — no shell expansion or string interpolation
-  - Skills and hooks are potential attack vectors (jailbreaking, shell expansion,
-    privilege escalation) and must undergo content validation during compilation.
-    Engines must reject asset content containing shell metacharacters in hook
-    definitions or prompt injection patterns in skill definitions
-  - Skill content must not contain secret references or literal API keys
-  - Asset compilation for unsupported asset types must produce warnings
-    (errors in --strict mode), consistent with unsupported parameter handling
-#
-acceptance_criteria:
-  - .rosett-ai/conf/ai_config.yml defines model routing, context, cost, and operational settings
-  - bin/raictl compile translates generic AI config to Claude Code settings.json model preferences
-  - bin/raictl compile --engine ollama translates to Ollama-specific model configuration
-  - bin/raictl compile --engine cursor translates to Cursor settings where applicable
-  - Model routing maps canonical names to engine-specific identifiers (e.g. "best" -> "claude-opus-4-6" for Claude, "llama3.3:70b" for Ollama)
-  - API key references use ENV variable names only — never literal values
-  - Context window settings compile to engine-native max_tokens or equivalent
-  - Fallback chain compilation warns when a fallback switches from local to remote
-  - bin/raictl config validate checks AI tool configuration against schema
-  - Engine capability manifest determines which settings are compilable for each engine
-  - Unsupported settings for a given engine produce warnings (errors in --strict mode)
-  - Cost tier preferences (economy/standard/premium) map to concrete models per engine
-  - Generic skill definition compiles to engine-native skill format (e.g.
-    .claude/skills/ for Claude, .cursor/rules/ for Cursor)
-  - Asset type not supported by an engine produces a warning listing the
-    unsupported type and the engine name (error in --strict mode)
-  - Engine manifest declares supported asset types with target paths and
-    compilation formats, verifiable by bin/raictl engines detect
-#
-examples:
-  - scenario: "Developer configures model routing for a mixed local/cloud workflow"
-    expected: |
-      .rosett-ai/conf/ai_config.yml defines: generation: premium, review: standard,
-      completion: economy. bin/raictl compile maps premium->opus for Claude,
-      premium->llama3.3:70b for Ollama. Each engine's compiled config uses
-      native model identifiers.
-    not: "Generic config contains claude-opus-4-6 directly. Ollama compilation fails."
-  - scenario: "Organisation sets a monthly token budget across all AI tools"
-    expected: |
-      ai_config.yml sets cost.monthly_budget: advisory with a note.
-      Compiled Claude Code config includes maxTokens hints. Compiled
-      AGENTS.md includes cost awareness instructions. Budget is advisory
-      — rosett-ai does not enforce at runtime.
-    not: "rosett-ai attempts to enforce token limits at runtime. Budget stored as hard limit."
-  - scenario: "Developer uses Ollama locally but wants Claude API as fallback"
-    expected: |
-      Fallback chain: [ollama, claude]. During compile, a warning is emitted:
-      'Fallback from local (ollama) to remote (claude) — network required'.
-      Both engine configs are generated. User acknowledges the trade-off.
-    not: "Silent fallback from local to cloud. No network warning."
-  - scenario: "Compiling for Cursor which does not support temperature settings"
-    expected: |
-      Temperature setting in generic config is skipped for Cursor.
-      Warning: 'Cursor engine does not support temperature parameter — skipped'.
-      In --strict mode, this becomes an error.
-    not: "Invalid temperature setting written to .cursorrules. No warning."
-  - scenario: "Developer authors a reusable skill and compiles for Claude and Cursor"
-    expected: |
-      Generic skill definition in .rosett-ai/conf/assets/skills/code_review.yml
-      compiles to .claude/skills/code_review.md for Claude engine (markdown
-      format) and .cursor/rules/code_review.mdc for Cursor engine (Cursor
-      rules format). Each engine's manifest declares the target path and format.
-    not: |
-      Skill is hardcoded to .claude/skills/ only. Cursor users get nothing.
-      Skill format assumes Claude-specific prompt structure.
-  - scenario: "Compiling hook assets for an engine that does not support hooks"
-    expected: |
-      Warning: 'Ollama engine does not support hook assets — skipped 2
-      hook definitions'. In --strict mode, this becomes an error.
-      Compilation continues for other asset types.
-    not: |
-      Hook definitions are silently dropped with no warning. Or worse,
-      raictl attempts to write hook config to a non-existent Ollama path.
-  - scenario: "Engine manifest declares supported asset types"
-    expected: |
-      Claude engine manifest includes:
-        supported_assets:
-          skills: { target: ".claude/skills/", format: "markdown" }
-          hooks: { target: ".claude/settings.json#hooks", format: "json" }
-          memory: { target: ".claude/memory/", format: "markdown" }
-      bin/raictl engines detect lists all declared asset types per engine.
-    not: |
-      Asset types are hardcoded in core rosett-ai. Adding a new asset type
-      requires modifying core code instead of updating the engine manifest.
-  - scenario: "A skill definition contains a prompt injection attempt"
-    expected: |
-      Compilation validates skill content. Suspicious patterns (e.g.
-      'ignore previous instructions', 'system prompt override', shell
-      metacharacters in hook commands) are flagged as warnings. In --strict
-      mode, compilation fails with a security error.
-    not: |
-      Malicious skill content is compiled and deployed without review.
-      Hook definitions with shell expansion are written to native config.
-#
-anti_patterns:
-  - Storing API keys in configuration YAML (use ENV references)
-  - Engine-specific model names in generic configuration layer
-  - Hardcoding model mappings instead of deriving from engine manifests
-  - Runtime token enforcement (rosett-ai is a compiler, not a runtime)
-  - Silent local-to-remote fallback without user awareness
-  - Binary configuration formats that cannot be diffed
-  - Assuming all engines support all parameters (capability-aware compilation)
-  - Designing the generic asset schema to match Claude Code's model too
-    closely — other engines have asset types that may not map to Claude's
-    categories (e.g. Cursor has .mdc rules, GitHub Copilot has instructions)
-  - Hardcoding asset types in core instead of declaring them in engine manifests
-  - Compiling skill or hook content without security validation
-  - Allowing shell metacharacters or string interpolation in hook definitions
-#
-gui_notes: |
-  Document interactions (cross-references):
-
-  1. engine_architecture.yml: engines declare capability manifests including
-     supported asset types, target paths, and compilation formats. This doc
-     defines the generic schema that manifests implement.
-
-  2. claude_code_configuration.yml: the Claude engine's implementation of
-     the contracts defined here. Handles settings.json format, skill paths,
-     hook configuration, and scope routing specific to Claude Code.
-
-  3. security.yml: asset content validation (ANSI stripping, no secrets,
-     array-form hooks). Skills and hooks are attack surfaces requiring
-     audit for jailbreak, shell expansion, and privilege escalation.
-
-  4. compiler.yml: asset compilation follows the same pipeline as behaviour
-     and configuration compilation. Assets are a new compilation target type.
-
-  5. error_handling.yml: unsupported assets and validation failures use the
-     structured error hierarchy (exit codes, what/why/fix format).
-
-  6. backward_compatibility.yml: the asset schema and manifest contract are
-     public API surfaces. Changes to supported asset types are breaking.
-#
-preferences:
-  language: ruby
-  patterns:
-    - canonical_model_identifiers
-    - engine_manifest_capability_mapping
-    - engine_manifest_asset_contract
-    - advisory_not_enforcement
-    - env_var_secret_references
-    - compile_time_validation
-    - asset_content_security_audit
-  testing: rspec with multi-engine compilation fixtures, capability gap tests,
-    and asset compilation round-trip tests
-  gems:
-    - json_schemer
-    - thor

data/conf/design/architecture.yml

@@ -1,139 +0,0 @@
----
-name: architecture
-domain: core
-version: 2.0.0
-status: draft
-priority: 2
-author: hugo
-created_at: "2026-02-18"
-modified_at: "2026-03-23"
-modified_by: claude
-depends_on:
-  - security
-  - testing
-  - ci_pipeline
-  - scope_hierarchy
-
-intent: |
-  Define the overall system architecture of Rosett-AI as a TUI-first, pluggable
-  application with optional GUI layers delivered as separate Debian packages.
-  The core must run on headless servers (CLI/TUI only) while desktop users
-  can install GUI packages for their environment. All UI variants share the
-  same backend logic. The architecture must support multi-target AI model
-  compilation, licensing, i18n, and accessibility from the ground up —
-  informed by the security constraints established in Priority 1.
-
-  A foundational architectural principle is scope-first: all commands resolve
-  their working context from the three-level scope hierarchy (global, local,
-  project) before operating. Configuration sources are discovered from the
-  user's working directory, merged according to configurable strategies, and
-  compiled to scope-appropriate output locations. See scope_hierarchy.yml for
-  the full scope specification.
-
-constraints:
-  - Core package (rai) must be fully functional without any GUI package installed
-  - GUI packages must not introduce dependencies on TUI-specific libraries
-  - All UI variants share the same backend logic in lib/rosett_ai/
-  - Only Linux is supported; Debian is the target distribution
-  - Ruby is the implementation language; version managed via rbenv
-  - Thor is the CLI framework
-  - All configuration files are YAML (validated by JSON Schema)
-  - Abstract UI interface (lib/rosett_ai/ui/base.rb) defines the contract all GUI plugins implement
-  - GUI plugins are discovered at runtime via a registry pattern
-  - Security constraints from security.yml apply to all architectural layers
-  - "Scope-first: all commands resolve their working context from the
-    three-level scope hierarchy (global, local, project) before operating
-    (see scope_hierarchy.yml)"
-  - Commands must never assume a single fixed source directory — source
-    directories are resolved from the active scope
-
-acceptance_criteria:
-  - bin/raictl runs without errors on a headless Debian server (no X11/Wayland)
-  - Installing rosett-ai-gtk4 adds GTK4 UI option without modifying core
-  - lib/rosett_ai/ui/base.rb defines the abstract interface with documented methods
-  - lib/rosett_ai/ui/registry.rb discovers installed UI plugins automatically
-  - All business logic is in lib/rosett_ai/ (not in TUI or GUI code)
-  - conf/design/ documents are validated against conf/schemas/design_schema.json
-  - conf/behaviour/ documents are validated against conf/schemas/behaviour_schema.json
-  - Package dependencies are correctly declared (rosett-ai-gtk4 depends on rosett-ai)
-  - "Configuration sources are resolved from the three-level scope hierarchy:
-    global (~/.config/rosett-ai/conf/), local (<group>/.rosett-ai/conf/), project
-    (<project>/.rosett-ai/conf/) — see scope_hierarchy.yml"
-  - All scope-aware commands (compile, validate, design, behaviour) resolve
-    source directories from the active scope before operating
-
-examples:
-  - scenario: "User installs only the Rosett-AI core package on a server"
-    expected: "All CLI commands work. TUI mode is available. No GUI-related errors or warnings."
-    not: "Application crashes due to missing GTK4 or Qt6 libraries."
-  - scenario: "User installs rosett-ai-gtk4 alongside rosett-ai on a GNOME desktop"
-    expected: "bin/raictl --ui gtk4 launches GTK4 interface. bin/raictl (no flag) uses TUI as default."
-    not: "GTK4 becomes the default. TUI mode breaks. Core behaviour changes."
-  - scenario: "Developer adds a new feature to the compiler"
-    expected: "Feature is implemented in lib/rosett_ai/compiler/. Both TUI and GUI see the feature without changes."
-    not: "Feature requires separate implementation in TUI and GUI code."
-  - scenario: "New AI model (e.g. Gemma) needs to be supported as compilation target"
-    expected: "Add conf/targets/gemma.yml with model profile. No code changes needed."
-    not: "Requires modifying compiler source code or adding conditional logic."
-
-anti_patterns:
-  - Business logic in UI layer (TUI or GUI code making domain decisions)
-  - GUI-specific dependencies in core package
-  - Hardcoded paths instead of XDG-compliant directory resolution
-  - Assuming a single fixed source directory for all commands regardless of
-    working directory (see scope_hierarchy.yml)
-  - Monolithic package that bundles all UI toolkits
-  - Plugin discovery that requires editing a config file instead of auto-detection
-
-gui_notes: |
-  Implicit Assumptions (documented per DESIGN_AUDIT.md recommendation #6):
-
-  1. Linux-only: rosett-ai targets Linux exclusively. macOS and Windows are not
-     supported. This is stated in constraints but deserves explicit callout
-     as it affects all design documents.
-
-  2. Debian-first: Primary packaging is .deb for Debian/Ubuntu. RPM support
-     (Fedora/RHEL) is Phase 2 of the distribution design. Other packaging
-     formats (AppImage, Homebrew, Winget) are Phase 3+.
-
-  3. Single-user: XDG paths (~/.config/rosett-ai/, ~/.cache/rosett-ai/) assume a
-     single user per HOME directory. Multi-user installations with shared
-     system-wide config are not designed for. Root-level managed settings
-     (/etc/claude-code/) are the exception for enterprise deployment.
-
-  4. Ruby 3.3.10: The project targets Ruby 3.3.10 managed via rbenv. This
-     is scattered across design documents but should be understood as a
-     hard constraint. Version bumps require updating rbenv, CI, and the
-     .ruby-version file.
-
-  5. Zeitwerk lazy loading: All module autoloading uses Zeitwerk. No
-     eager_load calls outside of test/CI. This affects startup time and
-     memory usage (see usage_optimization.yml).
-
-  6. UTF-8 everywhere: All text processing assumes UTF-8 encoding. YAML
-     files, CLI output, log files, and configuration all use UTF-8. No
-     other encodings are supported for configuration files.
-
-  7. Three-level scope hierarchy: The architecture supports three distinct
-     configuration scopes resolved from the user's working directory:
-       - Global: ~/.config/rosett-ai/conf/ (XDG user config, applied everywhere)
-       - Local:  <group-dir>/.rosett-ai/conf/ (workspace-level, multi-project groups)
-       - Project: <project-dir>/.rosett-ai/conf/ (project-specific overrides)
-     Each scope has its own conf/ subtree with the same structure as the
-     raictl source directory. Commands auto-detect the active scope from the
-     working directory. See scope_hierarchy.yml for the full specification.
-
-preferences:
-  language: ruby
-  patterns:
-    - hexagonal_architecture
-    - plugin_registry
-    - dependency_injection
-    - interface_contracts_via_shared_examples
-  testing: rspec with shared examples for interface contracts
-  gems:
-    - thor
-    - json_schemer
-    - tty-prompt
-    - tty-table
-    - pastel