rosett-ai 1.3.3

data/doc/ARCHITECTURE.md

@@ -0,0 +1,920 @@
+# Architecture
+
+## System Overview
+
+raictl (Rosett-AI) is an engine-agnostic configuration management tool.
+It separates **human intent** (generic YAML) from **engine translation** (tool-specific
+compilation) from **tool-native output** (deployed files).
+
+```mermaid
+graph TB
+    subgraph Layer1["Layer 1: Human Intent"]
+        BEHAV["conf/behaviour/*.yml<br/>Operational rules"]
+        DESIGN["conf/design/*.yml<br/>Design documents"]
+        TOOL["conf/tooling/*.yml<br/>CI tooling"]
+    end
+
+    subgraph Layer2["Layer 2: Engine Translation"]
+        PIPELINE["Compiler::CompilationPipeline"]
+        BACKEND["Engine Backend"]
+        MANIFEST["Engine Manifest"]
+        PROFILE["Target Profile"]
+    end
+
+    subgraph Layer3["Layer 3: Tool-Native Output"]
+        CLAUDE_OUT["~/.claude/rules/*.md"]
+        CURSOR_OUT[".cursorrules"]
+        COPILOT_OUT[".github/copilot-instructions.md"]
+        WINDSURF_OUT[".windsurfrules"]
+        AGENTS_OUT["./AGENTS.md"]
+        GOOSE_OUT[".goosehints"]
+        AIDER_OUT["CONVENTIONS.md"]
+        OLLAMA_OUT["Ollama modelfile"]
+        NEOX_OUT["vLLM prompt"]
+        GENERIC_OUT["*.md (generic)"]
+    end
+
+    BEHAV --> PIPELINE
+    DESIGN --> PIPELINE
+    TOOL --> PIPELINE
+    PIPELINE --> BACKEND
+    MANIFEST --> BACKEND
+    PROFILE --> BACKEND
+    BACKEND --> CLAUDE_OUT
+    BACKEND --> CURSOR_OUT
+    BACKEND --> COPILOT_OUT
+    BACKEND --> WINDSURF_OUT
+    BACKEND --> AGENTS_OUT
+    BACKEND --> GOOSE_OUT
+    BACKEND --> AIDER_OUT
+    BACKEND --> OLLAMA_OUT
+    BACKEND --> NEOX_OUT
+    BACKEND --> GENERIC_OUT
+```
+
+## Class Hierarchy
+
+### Core Module Tree
+
+```mermaid
+classDiagram
+    direction TB
+
+    class RosettAi {
+        +root() Pathname
+        +logger() Logger
+        +VERSION String
+    }
+
+    class Configuration {
+        +settings() Hash
+        +local_settings() Hash
+        +merged_settings() Hash
+        +behaviour_files() Array
+        +reload!()
+    }
+
+    class PathResolver {
+        +claude_home() Pathname
+        +claude_rules_dir() Pathname
+        +rai_config_home() Pathname
+        +project_claude_md() Pathname
+    }
+
+    class RaiConfig {
+        +load() Hash
+        +default_engine String
+        +cache_enabled Boolean
+    }
+
+    class YamlLoader {
+        +load_file(path) Hash
+        -check_file_size!(path)
+        -check_depth!(data)
+        -check_key_count!(data)
+        MAX_FILE_SIZE = 1MB
+        MAX_NESTING = 10
+        MAX_KEYS = 1000
+    }
+
+    class TextSanitizer {
+        +sanitize(text) String
+    }
+
+    RosettAi --> Configuration
+    RosettAi --> PathResolver
+    RosettAi --> RaiConfig
+    RosettAi --> YamlLoader
+    RosettAi --> TextSanitizer
+```
+
+### Compiler Pipeline
+
+```mermaid
+classDiagram
+    direction TB
+
+    class CompilationPipeline {
+        +compile(behaviours, engine) Array~CompiledOutput~
+        +compile_all(engine) Array~CompiledOutput~
+    }
+
+    class BehaviourCompiler {
+        +compile(behaviour, backend) CompiledOutput
+    }
+
+    class CompiledOutput {
+        +filename String
+        +content String
+        +source String
+        +category String
+        +name String
+        +version String
+    }
+
+    class Backend {
+        <<abstract>>
+        +render(behaviour) String
+        +file_extension() String
+        +metadata_comment(source, category, version) String
+    }
+
+    class TargetProfile {
+        +name String
+        +output_dir Pathname
+        +file_extension String
+    }
+
+    class LocaleCompiler {
+        +compile(locale, format) String
+    }
+
+    CompilationPipeline --> BehaviourCompiler
+    CompilationPipeline --> TargetProfile
+    BehaviourCompiler --> Backend
+    BehaviourCompiler --> CompiledOutput
+```
+
+### Engine Backends
+
+```mermaid
+classDiagram
+    direction TB
+
+    class Backend {
+        <<abstract>>
+        +render(behaviour) String
+        +file_extension() String
+    }
+
+    class ClaudeBackend {
+        +render(behaviour) String
+        +file_extension() ".md"
+        -metadata_header(source, category, version) String
+        -priority_annotation(rule) String
+    }
+
+    class AgentsMdBackend {
+        +render(behaviour) String
+        +file_extension() ".md"
+        -bullet_list_rules(rules) String
+        -instructions_heading() String
+    }
+
+    class GenericBackend {
+        +render(behaviour) String
+        +file_extension() ".md"
+    }
+
+    class OllamaBackend {
+        +render(behaviour) String
+        +file_extension() ".txt"
+    }
+
+    class GptNeoxBackend {
+        +render(behaviour) String
+        +file_extension() ".txt"
+    }
+
+    class GooseBackend {
+        +render(behaviour) String
+        +file_extension() ".md"
+    }
+
+    class AiderBackend {
+        +render(behaviour) String
+        +file_extension() ".md"
+    }
+
+    class CursorBackend {
+        +render(behaviour) String
+        +file_extension() ".md"
+    }
+
+    class CopilotBackend {
+        +render(behaviour) String
+        +file_extension() ".md"
+    }
+
+    class WindsurfBackend {
+        +render(behaviour) String
+        +file_extension() ".md"
+    }
+
+    Backend <|-- ClaudeBackend
+    Backend <|-- AgentsMdBackend
+    Backend <|-- GenericBackend
+    Backend <|-- OllamaBackend
+    Backend <|-- GptNeoxBackend
+    Backend <|-- GooseBackend
+    Backend <|-- AiderBackend
+    Backend <|-- CursorBackend
+    Backend <|-- CopilotBackend
+    Backend <|-- WindsurfBackend
+```
+
+### Validator Hierarchy
+
+```mermaid
+classDiagram
+    direction TB
+
+    class SchemaValidator {
+        +valid?(path) Boolean
+        +validate(path) Array~String~
+        +errors Array~String~
+        -load_schema() Hash
+        -validate_schema(content)
+    }
+
+    class BehaviourValidator {
+        schema = "behaviour_schema.json"
+    }
+
+    class DesignValidator {
+        schema = "design_schema.json"
+    }
+
+    class ToolingValidator {
+        schema = "tooling_schema.json"
+    }
+
+    SchemaValidator <|-- BehaviourValidator
+    SchemaValidator <|-- DesignValidator
+    SchemaValidator <|-- ToolingValidator
+```
+
+### UI Adapter Registry
+
+```mermaid
+classDiagram
+    direction TB
+
+    class Registry {
+        +register(name, klass)$
+        +resolve(name) Base
+        +available() Array~String~
+        +registered?(name) Boolean
+        +reset!()
+    }
+
+    class Base {
+        <<abstract>>
+        +display_table(data)
+        +display_list(data)
+        +prompt_confirm(message) Boolean
+        +spinner(message)
+    }
+
+    class Tui {
+        Rainbow + TTY integration
+    }
+    class AccessibleTui {
+        Screen reader compatible
+    }
+    class Gtk4 {
+        GTK4/Adwaita adapter
+    }
+    class Qt6 {
+        Qt6 adapter
+    }
+    class Kde {
+        KDE KCM adapter
+    }
+
+    Registry --> Base
+    Base <|-- Tui
+    Base <|-- AccessibleTui
+    Base <|-- Gtk4
+    Base <|-- Qt6
+    Base <|-- Kde
+```
+
+### Licensing System
+
+```mermaid
+classDiagram
+    direction TB
+
+    class LicenseKey {
+        +decode(key_string) Hash
+        +valid?() Boolean
+        +tier() String
+        +expired?() Boolean
+        +within_grace?() Boolean
+        PUBLIC_KEY Ed25519
+        GRACE_PERIOD = 14d
+    }
+
+    class LicenseValidator {
+        +validate(key) Result
+        +tier_for(key) Tier
+    }
+
+    class LicenseStore {
+        +save(key)
+        +load() LicenseKey
+        +remove()
+    }
+
+    class Tier {
+        +name String
+        +features Array
+        FREE = "free"
+        PRO = "pro"
+        ENTERPRISE = "enterprise"
+    }
+
+    LicenseValidator --> LicenseKey
+    LicenseValidator --> LicenseStore
+    LicenseValidator --> Tier
+```
+
+## Engine Architecture
+
+### Engine Component Structure
+
+Each engine is a separate gem (`rosett-ai-engine-<name>`) with optional components,
+discovered at runtime by `RosettAi::Plugins::Registry.discover!`:
+
+```mermaid
+graph TB
+    subgraph Core["rosett-ai core"]
+        REG["RosettAi::Plugins::Registry<br/>discover! / register / resolve"]
+        BASE["Base classes:<br/>Compiler::Backend<br/>Engines::Detector<br/>Engines::BaseConfigCompiler"]
+    end
+
+    subgraph Gems["External Engine Gems (rosett-ai-engine-*)"]
+        GEM_CLAUDE["rosett-ai-engine-claude<br/>backend, detector, executor,<br/>config_compiler, key_map, scope_router"]
+        GEM_GENERIC["rosett-ai-engine-generic<br/>backend"]
+        GEM_AGENTS["rosett-ai-engine-agents-md<br/>backend, detector"]
+        GEM_OTHERS["rosett-ai-engine-{cursor,copilot,windsurf}<br/>backend, detector"]
+        GEM_EXEC["rosett-ai-engine-{goose,aider,ollama,gpt-neox}<br/>backend, detector, executor"]
+        GEM_ACME["rosett-ai-engine-acme (example)<br/>backend, detector"]
+    end
+
+    REG -->|Gem.find_files| Gems
+    BASE -.->|inherits| Gems
+```
+
+### Engine Detection Flow
+
+```mermaid
+flowchart TD
+    A[bin/raictl engines detect] --> B[Load all manifests]
+    B --> C{For each engine}
+    C --> D[Check cli_binary in PATH]
+    D --> E{Found?}
+    E -->|Yes| F[Check config_dir exists]
+    E -->|No| G[Mark not detected]
+    F --> H{Exists?}
+    H -->|Yes| I[Mark detected + available]
+    H -->|No| J[Mark partially detected]
+    G --> C
+    I --> C
+    J --> C
+    C -->|Done| K[Return detection results]
+```
+
+### Compilation Pipeline
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI as Thor::CLI
+    participant Pipeline as CompilationPipeline
+    participant Loader as YamlLoader
+    participant Backend as Engine::Backend
+    participant FS as Filesystem
+
+    User->>CLI: bin/raictl compile --engine agents_md
+    CLI->>Pipeline: compile_all(engine: "agents_md")
+    Pipeline->>Loader: load_file(conf/behaviour/*.yml)
+    Loader-->>Pipeline: behaviour_data[]
+
+    loop Each behaviour
+        Pipeline->>Backend: render(behaviour)
+        Backend-->>Pipeline: CompiledOutput
+    end
+
+    Pipeline->>FS: write(output_dir/filename)
+    FS-->>Pipeline: success
+    Pipeline-->>CLI: results[]
+    CLI-->>User: "Compiled 5 files to ./AGENTS.md"
+```
+
+## Desktop Architecture
+
+### D-Bus Service Stack
+
+```mermaid
+graph TB
+    subgraph Apps["Desktop Applications"]
+        GTK4_APP["GTK4 App<br/>(RosettAi::Desktop::Gtk4App)"]
+        QT6_APP["Qt6 App<br/>(future)"]
+        THIRD["Third-party clients"]
+    end
+
+    subgraph IPC["D-Bus Session Bus"]
+        BUS["be.neatnerds.rosettai<br/>/be/neatnerds/rosett-ai"]
+    end
+
+    subgraph Service["D-Bus Service"]
+        MGR["ManagerInterface<br/>Compile, SwitchContext, GetStatus"]
+        FOCUS_IF["FocusMonitorInterface<br/>GetCurrentFocus, FocusChanged signal"]
+    end
+
+    subgraph Adapters["Focus Adapters"]
+        GNOME["GnomeAdapter"]
+        KWIN["KwinAdapter"]
+        I3["I3Adapter"]
+        HYPR["HyprlandAdapter"]
+        X11["X11Adapter"]
+    end
+
+    subgraph Detect["CompositorDetector"]
+        DET["detect() -> :gnome | :kde | :i3 | :hyprland | :x11"]
+    end
+
+    GTK4_APP -->|D-Bus calls| BUS
+    QT6_APP -->|D-Bus calls| BUS
+    THIRD -->|D-Bus calls| BUS
+    BUS --> MGR
+    BUS --> FOCUS_IF
+    FOCUS_IF --> GNOME
+    FOCUS_IF --> KWIN
+    FOCUS_IF --> I3
+    FOCUS_IF --> HYPR
+    FOCUS_IF --> X11
+    DET --> FOCUS_IF
+```
+
+### GTK4 Safety Architecture
+
+```mermaid
+flowchart TB
+    subgraph UserAction["User Interaction"]
+        CLICK["Button Click"]
+        MENU["Menu Selection"]
+        PREF["Preference Change"]
+    end
+
+    subgraph Safety["Safety Wrappers"]
+        SA["safe_action(name)"]
+        SC["safe_callback(name)"]
+    end
+
+    subgraph Logging["GuiLogger"]
+        LOG["JSON Lines Output"]
+        FILE["Log File"]
+        STDERR["stderr"]
+    end
+
+    subgraph Error["Error Handling"]
+        RESCUE["rescue StandardError"]
+        DIALOG["show_error_dialog()"]
+        TOAST["show_toast()"]
+    end
+
+    subgraph Logic["Business Logic"]
+        DBUS["DbusClient<br/>(never raises)"]
+        DEFAULTS["Safe Defaults<br/>SAFE_STATUS, SAFE_FOCUS"]
+    end
+
+    CLICK --> SA
+    MENU --> SA
+    PREF --> SC
+    SA --> LOG
+    SC --> LOG
+    LOG --> FILE
+    LOG --> STDERR
+    SA --> RESCUE
+    SC --> RESCUE
+    RESCUE -->|success| Logic
+    RESCUE -->|error| DIALOG
+    DIALOG --> TOAST
+    DBUS --> DEFAULTS
+```
+
+## Configuration Flow
+
+### Configuration Hierarchy
+
+```mermaid
+flowchart LR
+    subgraph Sources["Configuration Sources"]
+        direction TB
+        S1["settings.json<br/>(global)"]
+        S2["settings.local.json<br/>(local overrides)"]
+        S3["Group CLAUDE.md"]
+        S4["Project CLAUDE.md"]
+    end
+
+    subgraph Merge["Deep Merge"]
+        M["Later overrides earlier"]
+    end
+
+    subgraph Output["Effective Config"]
+        O["Merged settings"]
+    end
+
+    S1 --> M
+    S2 --> M
+    S3 --> M
+    S4 --> M
+    M --> O
+```
+
+### Path Resolution
+
+```mermaid
+flowchart TB
+    subgraph PathResolver
+        direction TB
+        CLAUDE_DOMAIN["Claude Domain<br/>~/.claude/"]
+        RAI_DOMAIN["rosett-ai Domain (XDG)<br/>~/.config/rosett-ai/"]
+    end
+
+    subgraph Claude["Claude Paths"]
+        CR["~/.claude/rules/"]
+        CS["~/.claude/settings.json"]
+        CM["./CLAUDE.md"]
+    end
+
+    subgraph NNCC["rosett-ai Paths"]
+        NC["~/.config/rosett-ai/config.yml"]
+        NB["~/.config/rosett-ai/conf/behaviour/"]
+        ND["~/.config/rosett-ai/conf/design/"]
+    end
+
+    subgraph EngineNative["Engine-Native Paths"]
+        EN1["~/.claude/rules/ (Claude)"]
+        EN2["./AGENTS.md (AGENTS.md)"]
+        EN3["./.cursorrules (Cursor)"]
+        EN4["./.github/copilot-instructions.md"]
+    end
+
+    CLAUDE_DOMAIN --> Claude
+    RAI_DOMAIN --> NNCC
+    PathResolver --> EngineNative
+```
+
+## Dependency Graph
+
+### Runtime Dependencies
+
+```mermaid
+graph LR
+    NNCC((rosett-ai))
+    NNCC --> ZEIT[zeitwerk ~> 2.6]
+    NNCC --> THOR[thor ~> 1.3]
+    NNCC --> RAIN[rainbow ~> 3.1]
+    NNCC --> JSCH[json_schemer ~> 0.2]
+    NNCC --> JWT[jwt ~> 2.8]
+    NNCC --> ED25[ed25519 ~> 1.3]
+    NNCC --> RDBUS[ruby-dbus ~> 0.24]
+    NNCC --> I18N[i18n ~> 1.14]
+
+    subgraph Optional
+        ANTH[anthropic ~> 1.16]
+        ADW[adwaita ~> 4.3]
+        FPM[fpm ~> 1.17]
+    end
+
+    NNCC -.->|engines group| ANTH
+    NNCC -.->|desktop group| ADW
+    NNCC -.->|build group| FPM
+```
+
+### Development Dependencies
+
+```mermaid
+graph LR
+    DEV((dev/test))
+    DEV --> RSPEC[rspec]
+    DEV --> RCOP[rubocop<br/>+ plugins]
+    DEV --> REEK[reek]
+    DEV --> MUTANT[mutant-rspec]
+    DEV --> SIMP[simplecov]
+    DEV --> FBOT[factory_bot]
+    DEV --> RANTLY[rantly]
+    DEV --> AUDIT[bundler-audit<br/>ruby_audit]
+    DEV --> FLAY[flay]
+    DEV --> YARD[yard]
+    DEV --> RONN[ronn-ng]
+    DEV --> WEBM[webmock]
+```
+
+## Git History
+
+### Commit Timeline
+
+```mermaid
+gitgraph
+    commit id: "init" tag: "v0.1.0"
+    branch critical_thinking
+    commit id: "criticalthinking"
+    checkout main
+    merge critical_thinking
+    commit id: "adopt+backup"
+    branch packaging_fpm
+    commit id: "fpm packaging"
+    checkout main
+    merge packaging_fpm
+    commit id: "tooling"
+    commit id: "ci fixes"
+    branch design_implementation
+    commit id: "design docs P1-P5"
+    checkout main
+    merge design_implementation
+    commit id: "desktop+refs"
+    commit id: "ADR-007" tag: "v1.0.0"
+    branch engine/0a-rename
+    commit id: "rename to rosett-ai"
+    checkout main
+    branch engine/0b-dirs
+    commit id: "engine dirs"
+    checkout main
+    branch engine/0c-xdg
+    commit id: "XDG+detect"
+    checkout main
+    branch engine/1-agents-md
+    commit id: "AGENTS.md engine"
+    checkout main
+    merge engine/1-agents-md
+    commit id: "D-Bus service"
+    commit id: "GTK4 app"
+    commit id: "Ollama+GPT-NeoX"
+    commit id: "merge D2+E2"
+    commit id: "GTK4 hardening"
+    branch backfill/quorum-module
+    commit id: "executor normalize"
+    commit id: "capability checker"
+    commit id: "quorum module"
+    checkout main
+    merge backfill/quorum-module
+    branch backfill/dbus-desktop
+    commit id: "D-Bus stop+SNI+prefs"
+    checkout main
+    merge backfill/dbus-desktop
+    branch documentation
+    commit id: "docs update"
+    checkout main
+    merge documentation
+    branch engine/3-goose-aider
+    commit id: "Goose+Aider compile"
+    checkout main
+    merge engine/3-goose-aider
+    branch refactor/consistency-review
+    commit id: "consistency review"
+    checkout main
+    merge refactor/consistency-review
+    branch engine/4-cursor-copilot-windsurf
+    commit id: "Cursor+Copilot+Windsurf"
+    commit id: "Goose+Aider executors"
+    checkout main
+    merge engine/4-cursor-copilot-windsurf
+```
+
+### Key Milestones
+
+```mermaid
+timeline
+    title rosett-ai Project History
+    section Foundation
+        Feb 2026 : Initial CLI
+                 : Behaviour management
+                 : Adopt command
+                 : Backup system
+    section Design
+        Feb 18 : FPM packaging
+        Feb 19 : Testing infrastructure
+        Feb 20 : Security + Styles
+        Feb 21 : Architecture P1-P5
+               : CI Pipeline
+               : Compiler pipeline
+    section v1.0.0 Pivot
+        Feb 26 : ADR-007 Engine-agnostic
+               : Rename to rosett-ai
+               : Engine directories
+               : XDG + detection
+               : AGENTS.md engine
+    section Desktop + Engines
+        Feb 27-28 : D-Bus service
+                  : GTK4/Adwaita app
+                  : Ollama engine
+                  : GPT-NeoX engine
+                  : GTK4 hardening
+    section Backfill + Engine 3
+        Feb 28 : Executor normalization
+               : Capability checker
+               : Quorum module
+               : D-Bus stop command
+               : StatusNotifierItem
+               : GTK4 preference callbacks
+               : Documentation (40 diagrams)
+               : Goose + Aider compilation
+               : Consistency review
+    section Engine 4
+        Mar 2 : Cursor engine
+              : Copilot engine
+              : Windsurf engine
+              : Goose CLI executor
+              : Aider CLI executor
+              : 10 engines total
+    section v1.0.0 Release
+        Mar 4 : Operations design domain
+              : Monitoring + optimization docs
+              : SimpleCov thresholds
+              : CI pipeline hardening
+              : Core-only gemspec split
+              : ADR-009 core release
+        Mar 5 : Security scan hardening
+              : AI provenance documentation
+              : Full quality gate verification
+              : v1.0.0 tagged
+```
+
+### Backfill Branches
+
+Between Engine Phase 2 and Engine Phase 3, six gaps from earlier phases were
+addressed across two backfill branches:
+
+| Branch | Items | Merged |
+|--------|-------|--------|
+| `backfill/quorum-module` | ExecutorResolver, CapabilityChecker, Quorum module | Fast-forward into main |
+| `backfill/dbus-desktop` | D-Bus stop, StatusNotifierItem, GTK4 preferences | Merge commit into main |
+
+The intermediate branches `backfill/executor-normalize` and
+`backfill/capability-checker` were subsets rolled into `backfill/quorum-module`.
+
+```mermaid
+flowchart LR
+    subgraph BF1["backfill/quorum-module"]
+        direction TB
+        E1["fix: normalize executor<br/>interface across engines"]
+        E2["feat: capability warnings<br/>during compilation"]
+        E3["feat: quorum multi-engine<br/>adopt analysis"]
+        E1 --> E2 --> E3
+    end
+
+    subgraph BF2["backfill/dbus-desktop"]
+        direction TB
+        D1["feat: D-Bus stop command"]
+        D2["feat: StatusNotifierItem"]
+        D3["feat: GTK4 preference callbacks"]
+        D1 --- D2 --- D3
+    end
+
+    MAIN1["main<br/>(GTK4 hardening)"] --> BF1
+    MAIN1 --> BF2
+    BF1 --> MAIN2["main<br/>(merged)"]
+    BF2 --> MAIN2
+
+    style BF1 fill:#e6ffe6,stroke:#333
+    style BF2 fill:#e6f3ff,stroke:#333
+```
+
+## Security Architecture
+
+### Trust Boundaries
+
+```mermaid
+flowchart TB
+    subgraph Untrusted["Untrusted Input"]
+        YAML_IN["YAML files"]
+        USER_IN["CLI arguments"]
+        DBUS_IN["D-Bus messages"]
+        API_IN["API responses"]
+    end
+
+    subgraph Validation["Validation Layer"]
+        YL["YamlLoader<br/>Size + depth + key limits"]
+        SV["SchemaValidator<br/>JSON Schema checks"]
+        TS["TextSanitizer<br/>Content filtering"]
+        RC["RuboCop Cops<br/>ShellInterpolation<br/>UnsafeYamlLoad"]
+    end
+
+    subgraph Trusted["Trusted Core"]
+        COMP_T["Compiler"]
+        CONFIG_T["Configuration"]
+        LICENSE_T["License Validator"]
+    end
+
+    subgraph Output["Output Boundaries"]
+        FS_OUT["Filesystem<br/>(whitelisted dirs only)"]
+        DBUS_OUT["D-Bus signals"]
+        LOG_OUT["Logs<br/>(no secrets)"]
+    end
+
+    YAML_IN --> YL
+    USER_IN --> TS
+    DBUS_IN --> SV
+    API_IN --> TS
+    YL --> Trusted
+    SV --> Trusted
+    TS --> Trusted
+    Trusted --> FS_OUT
+    Trusted --> DBUS_OUT
+    Trusted --> LOG_OUT
+```
+
+### Security Rules
+
+| Rule | Enforcement |
+|------|-------------|
+| YAML.safe_load only | Custom RuboCop cop `RosettAi/UnsafeYamlLoad` |
+| Array-form system() | Custom RuboCop cop `RosettAi/ShellInterpolation` |
+| File writes to whitelisted dirs | PathResolver + Configuration |
+| Secrets never logged | MaskingSecretResolver |
+| Secrets 0600 permissions | LicenseStore |
+| Max YAML size 1MB | YamlLoader |
+| Max YAML nesting 10 | YamlLoader |
+| Max YAML keys 1000 | YamlLoader |
+| Ed25519-signed JWT | LicenseKey |
+
+## Test Architecture
+
+```mermaid
+pie title Test Distribution (119 spec files, 1574 examples)
+    "Thor CLI Tasks" : 18
+    "Engine Backends" : 17
+    "Compiler" : 6
+    "D-Bus + Desktop" : 8
+    "Validators" : 4
+    "Licensing" : 4
+    "Content" : 4
+    "Config" : 6
+    "UI" : 7
+    "Quorum" : 4
+    "Adopter" : 3
+    "Other (i18n, backup, etc.)" : 38
+```
+
+### Testing Strategy
+
+```mermaid
+flowchart LR
+    subgraph Unit["Unit Tests"]
+        RSPEC["RSpec<br/>1574 examples"]
+    end
+
+    subgraph Quality["Code Quality"]
+        RCOP2["RuboCop"]
+        REEK2["Reek"]
+        FLAY2["Flay"]
+    end
+
+    subgraph Mutation["Mutation Testing"]
+        MUT["Mutant<br/>97.83% coverage"]
+    end
+
+    subgraph Security2["Security"]
+        BA["bundler-audit"]
+        RA["ruby-audit"]
+        GL["gitleaks"]
+    end
+
+    subgraph Property["Property-Based"]
+        RANT["Rantly<br/>yaml_loader_property_spec"]
+    end
+
+    Unit --> Quality
+    Quality --> Mutation
+    Quality --> Security2
+    Unit --> Property
+```
+
+---
+
+### Core-Only Packaging (ADR-009)
+
+The v1.0.0 release ships as core-only. Desktop dependencies (`ruby-dbus`,
+`i3ipc`) are moved to the `:desktop` Bundler group and excluded from the
+gemspec. Zeitwerk conditionally ignores `rosett-ai/dbus` and `rosett-ai/desktop` when
+`ruby-dbus` is unavailable. Desktop features are delivered via the separate
+`rosett-ai-gtk4` package.
+
+---
+
+*Generated: 2026-03-05 | rosett-ai v1.0.0 | Branch: main*