rosett-ai 1.3.3

data/conf/design/scope_hierarchy.yml

@@ -0,0 +1,352 @@
+---
+name: scope_hierarchy
+domain: core
+version: 1.0.0
+status: implemented
+priority: 2
+author: hugo
+created_at: "2026-03-23"
+modified_at: "2026-04-14"
+modified_by: claude opus-4.6
+depends_on:
+  - architecture
+  - security
+  - error_handling
+#
+intent: |
+  Define the three-level scope hierarchy that makes rosett-ai directory-aware.
+  Currently, all commands (compile, validate, design) operate on rosett-ai's own
+  conf/ directory regardless of where the user invokes them. This design
+  introduces a Hiera-like scope model where configuration sources are
+  discovered based on the user's working directory, merged according to
+  configurable strategies, and compiled to scope-appropriate output locations.
+
+  The three scope levels are:
+
+    1. Global (~/.config/rosett-ai/conf/) — user-wide defaults following XDG
+       Base Directory Specification. Applied everywhere unless overridden.
+
+    2. Local (<group-dir>/.rosett-ai/conf/) — multi-project workspace defaults.
+       A local scope groups related projects (e.g. a monorepo or a team
+       workspace) under shared configuration. Detected by a .rosett-ai/ marker
+       directory that has child directories also containing .rosett-ai/ markers.
+
+    3. Project (<project-dir>/.rosett-ai/conf/) — project-specific overrides.
+       The most specific scope. A project scope is a leaf .rosett-ai/ directory
+       (no children with their own .rosett-ai/ markers).
+
+  The merge order is global -> local -> project: each successive layer
+  overrides the previous one. Merge strategies are configurable per key.
+
+  Without this design, rosett-ai cannot serve users who work across multiple
+  projects with shared conventions. Every project must duplicate global
+  defaults, and there is no way to express workspace-level settings that
+  apply to a group of related projects. The scope hierarchy solves this
+  by making configuration inheritance explicit, configurable, and auditable.
+
+  This design is the authoritative specification for scope semantics.
+  All other design documents that reference scopes (compiler.yml,
+  behaviour_composition.yml, engine_architecture.yml, project_management.yml,
+  architecture.yml) defer to this document for scope definitions, detection
+  algorithm, and merge behaviour.
+#
+constraints:
+  - "Exactly three scope levels exist: global, local, project — no more, no fewer"
+  - "Global scope source directory is ~/.config/rosett-ai/conf/ (XDG_CONFIG_HOME/rosett-ai/conf/)"
+  - "Local scope source directory is <group-dir>/.rosett-ai/conf/ where <group-dir>
+    is detected by walking up from RAI_ORIGINAL_PWD"
+  - "Project scope source directory is <project-dir>/.rosett-ai/conf/ where
+    <project-dir> is the nearest directory containing a .rosett-ai/ marker"
+  - "Scope detection walks up from RAI_ORIGINAL_PWD (or Dir.pwd if unset),
+    finding the nearest .rosett-ai/ marker first"
+  - "A .rosett-ai/ directory is classified as local (workspace) if it has child
+    directories that also contain .rosett-ai/ markers; otherwise it is project"
+  - "Merge order is always global -> local -> project (lower scope wins)"
+  - "Merge strategies are configurable per key in .rosett-ai/config.yml under
+    a merge_strategies key"
+  - "Supported merge strategies: deep_merge (default for hashes), replace
+    (default for scalars), array_union (combine + deduplicate), first_found
+    (first non-nil from most-specific scope)"
+  - "Default merge strategy when unconfigured: replace for scalar values,
+    deep_merge for hash values, array_union for array values"
+  - "When no .rosett-ai/ marker is found in the directory tree, only the global
+    scope is active — this is not an error"
+  - "When no global config exists (~/.config/rosett-ai/ absent), commands work
+    with whatever scopes are available — global is not required"
+  - "At most one local scope and one project scope can be active at any time.
+    Nested workspaces (a .rosett-ai/ marker whose parent also has a .rosett-ai/ marker
+    with children) are resolved by nearest-wins: the deepest workspace-level
+    marker is selected as local, and any higher markers are ignored"
+  - "CLI flags --global, --local, --project select a scope level. These
+    flags are mutually exclusive — specifying more than one is an error
+    (exit 2). Each level includes all scopes above it: --global uses only
+    global sources; --local merges global+local; --project merges
+    global+local+project. Output is written to the selected level's output
+    directory. Without flags, scope is auto-detected from working directory"
+  - "Scope detection must not traverse above the filesystem root or into
+    unreadable directories"
+  - "All YAML files in scope source directories are parsed with YAML.safe_load
+    (per security.yml constraints)"
+  - "Scope resolution result must be deterministic for a given directory tree"
+  - "Each engine declares per-scope output directories in its target profile.
+    Global output uses an absolute path (e.g. ~/.claude/rules/). Local and
+    project outputs use a relative path (e.g. .claude/rules/) resolved against
+    the scope directory by the compiler"
+  - "Scope-related errors use the what/why/fix format from error_handling.yml"
+#
+acceptance_criteria:
+  - "ScopeResolver.resolve(working_dir) returns a ScopeResult with global,
+    local (optional), and project (optional) source directories"
+  - "When invoked from a project directory, all active scopes are discovered
+    and merged in order global -> local (if present) -> project"
+  - "When invoked from a directory with no .rosett-ai/ marker above it, only
+    the global scope is active and returned"
+  - "deep_merge strategy recursively merges hashes from all active scopes,
+    with lower (more-specific) scope keys winning on conflict"
+  - "replace strategy uses the value from the most-specific active scope,
+    ignoring all higher scopes"
+  - "array_union strategy combines arrays from all active scopes and
+    deduplicates entries, preserving order (most-specific scope first)"
+  - "first_found strategy returns the first non-nil value scanning from
+    project -> local -> global"
+  - "bin/raictl compile --global compiles only global-scope sources to
+    global output directories"
+  - "bin/raictl compile --local compiles merged global+local sources to
+    local output directories"
+  - "bin/raictl compile --project compiles merged global+local+project
+    sources to project output directories"
+  - "bin/raictl compile (no flag) auto-detects scope from working directory
+    and compiles to the appropriate output location"
+  - "bin/raictl compile --simulate --verbose shows scope-resolved source
+    directories and target output paths before showing diffs"
+  - "bin/raictl validate operates on sources from the auto-detected scope"
+  - "Merge strategy configuration in .rosett-ai/config.yml is validated against
+    scope_hierarchy_schema.json"
+  - "Scope detection terminates at filesystem root without error"
+  - "Exit code 0 on success, 2 on scope configuration error, 3 on missing
+    required scope (when --local or --project is used but no marker found)"
+#
+examples:
+  - scenario: "User runs bin/raictl compile from ~/projects/acme-api/"
+    expected: |
+      ScopeResolver finds:
+        project: ~/projects/acme-api/.rosett-ai/conf/
+        local:   ~/projects/.rosett-ai/conf/    (if ~/projects/.rosett-ai/ exists and has children with .rosett-ai/)
+        global:  ~/.config/rosett-ai/conf/
+      Merges global -> local -> project. Compiles to project-scope output
+      directories (e.g. ~/projects/acme-api/.claude/rules/ for Claude engine).
+    not: "Compiles from rosett-ai's own conf/ directory. Ignores working directory."
+  - scenario: "User runs bin/raictl compile --global"
+    expected: |
+      Only global scope sources (~/.config/rosett-ai/conf/) are compiled.
+      Output goes to global output directories (e.g. ~/.claude/rules/).
+      Local and project scopes are ignored even if .rosett-ai/ markers exist
+      in the current directory tree.
+    not: "All scopes are merged. Project-specific rules appear in global output."
+  - scenario: "User runs bin/raictl compile from /tmp (no .rosett-ai/ anywhere)"
+    expected: |
+      Only global scope is active. Compiles global sources to global output.
+      No warning about missing local/project scopes (this is normal).
+    not: "Error: no .rosett-ai/ found. Compilation refuses to run."
+  - scenario: "Two behaviours define the same key with different merge strategies"
+    expected: |
+      .rosett-ai/config.yml specifies:
+        merge_strategies:
+          editor_settings: deep_merge
+          allowed_tools: array_union
+      Global defines editor_settings: { theme: dark }.
+      Project defines editor_settings: { font_size: 14 }.
+      Merged result: { theme: dark, font_size: 14 }.
+    not: "Project replaces entire editor_settings hash."
+  - scenario: "User runs bin/raictl compile --project but no .rosett-ai/ exists"
+    expected: |
+      Error (exit 3): 'No project scope found: no .rosett-ai/ marker in directory
+      tree from /current/dir. Run `rai init --project` to create one, or
+      omit --project to use auto-detection.'
+    not: "Silent fallback to global scope. Compiles without indicating scope mismatch."
+  - scenario: "Local scope has a .rosett-ai/config.yml with merge_strategies"
+    expected: |
+      Merge strategies from local config apply to the local+project merge.
+      Global config may also declare merge_strategies; the most-specific
+      merge_strategies configuration wins (project > local > global).
+    not: "Only project-level merge_strategies are respected."
+  - scenario: "Engine declares per-scope output directories"
+    expected: |
+      Claude engine target profile contains:
+        output_dirs:
+          global: ~/.claude/rules/
+          scoped: .claude/rules/
+      Global output uses the absolute path. For local and project scopes,
+      the compiler resolves the relative path against the scope directory:
+        local:   ~/projects/.claude/rules/
+        project: ~/projects/acme-api/.claude/rules/
+    not: "All output goes to ~/.claude/rules/ regardless of scope."
+  - scenario: "User runs bin/raictl validate from a project directory"
+    expected: |
+      Validates sources from all active scopes (global, local, project).
+      Reports validation results grouped by scope:
+        [global]  conf/behaviour/security.yml: valid
+        [project] conf/behaviour/api_rules.yml: 2 errors
+    not: "Only validates rosett-ai's own conf/ directory."
+#
+anti_patterns:
+  - "Hardcoding source or output directories instead of resolving from scope"
+  - "Assuming a single fixed source directory for all commands"
+  - "Merging scopes in wrong order (project before global)"
+  - "Treating missing scopes as errors (only --local/--project flags require presence)"
+  - "Scope detection that follows symlinks across filesystem boundaries"
+  - "Merge strategies that silently drop data without user visibility"
+  - "Scope resolution that depends on environment variables other than
+    RAI_ORIGINAL_PWD and XDG_CONFIG_HOME"
+  - "Caching scope resolution results across commands (directory tree can change)"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. architecture.yml: scope hierarchy is an architectural principle.
+     Architecture declares scope-first as a constraint; this document
+     defines the full specification.
+
+  2. compiler.yml: compilation is scope-aware. Compiler resolves source
+     directories from the active scope before operating.
+
+  3. behaviour_composition.yml: composition uses the scope hierarchy for
+     layering behaviours. This document defines the scope model; composition
+     defines the merge and priority rules within that model.
+
+  4. engine_architecture.yml: engines declare per-scope output directories
+     in their target profiles. This document defines the scope levels;
+     engines map each level to tool-native paths.
+
+  5. project_management.yml: project lifecycle commands are scope-aware.
+     raictl init creates scope markers; rai project status reports scope.
+
+  6. security.yml: all YAML parsing in scope directories uses YAML.safe_load.
+     Path traversal in scope detection must be validated.
+
+  7. error_handling.yml: scope errors (missing marker, invalid config)
+     follow the what/why/fix format with dedicated exit codes.
+
+  Scope detection algorithm (pseudocode):
+
+    def resolve(start_dir):
+      global = XDG_CONFIG_HOME/rosett-ai/conf/ or ~/.config/rosett-ai/conf/
+      current = start_dir
+      markers = []
+
+      # Phase 1: collect all .rosett-ai/ markers from root to start_dir
+      while current != '/':
+        if current/.rosett-ai exists:
+          markers.prepend(current)
+        current = parent(current)
+
+      if markers.empty:
+        return ScopeResult(global: global, local: nil, project: nil)
+
+      # Phase 2: nearest marker (deepest) is the project candidate
+      project_candidate = markers.last
+
+      # Phase 3: scan remaining markers upward for a local (workspace) scope
+      # A marker is local if it has child directories that also contain
+      # .rosett-ai/ markers (i.e. it groups multiple projects)
+      local_candidate = nil
+      markers[0..-2].reverse_each do |dir|
+        if dir has child directories containing .rosett-ai/ markers:
+          local_candidate = dir
+          break
+        end
+      end
+
+      if local_candidate:
+        return ScopeResult(
+          global:  global,
+          local:   local_candidate/.rosett-ai/conf/,
+          project: project_candidate/.rosett-ai/conf/
+        )
+
+      # Single marker — check if it is local (workspace) or project (leaf)
+      if project_candidate has child directories containing .rosett-ai/ markers:
+        # User is at workspace level, not inside a child project
+        return ScopeResult(
+          global:  global,
+          local:   project_candidate/.rosett-ai/conf/,
+          project: nil
+        )
+      else:
+        return ScopeResult(
+          global:  global,
+          local:   nil,
+          project: project_candidate/.rosett-ai/conf/
+        )
+
+  Directory layout example:
+
+    ~/.config/rosett-ai/                   # Global scope
+    └── conf/
+        └── behaviour/
+            └── security.yml          # User-wide security defaults
+
+    ~/projects/                       # Local scope (workspace)
+    ├── .rosett-ai/
+    │   ├── config.yml                # merge_strategies, workspace settings
+    │   └── conf/
+    │       └── behaviour/
+    │           └── team_style.yml    # Shared across projects in workspace
+    ├── acme-api/                     # Project scope
+    │   ├── .rosett-ai/
+    │   │   ├── config.yml            # project_name, default_engine
+    │   │   └── conf/
+    │   │       └── behaviour/
+    │   │           └── api_rules.yml # Project-specific rules
+    │   └── src/
+    └── acme-web/                     # Another project in same workspace
+        ├── .rosett-ai/
+        │   └── conf/
+        │       └── behaviour/
+        │           └── web_rules.yml
+        └── src/
+#
+preferences:
+  language: ruby
+  patterns:
+    - "ScopeResolver with upward directory traversal"
+    - "ScopeResult value object (global, local, project)"
+    - "Strategy pattern for merge strategies"
+    - "XDG Base Directory compliance"
+    - "Marker-based scope detection (.rosett-ai/)"
+    - "Hiera-like configurable merge"
+  testing: rspec with directory tree fixtures, scope detection edge cases
+    (no markers, nested markers, symlinks), merge strategy property tests,
+    CLI flag override tests, and scope-aware compilation integration tests
+  gems:
+    - json_schemer
+    - thor
+
+implementation_notes: |
+  v1.2.0 implementation diverged from the original 3-level design:
+
+  1. ScopeResolver uses a 4-level model: global, organisation, project, local.
+     The "organisation" level was added to support multi-org workspaces.
+     SCOPE_ORDER = ['global', 'organisation', 'project', 'local'].
+
+  2. ScopeResolver.resolve() returns a scope name string
+     ('global'/'organisation'/'project'/'local') for a given file path,
+     not a ScopeResult value object. The ScopeResult contract from the
+     design is not yet implemented.
+
+  3. Workspace (local) detection via child-marker walking is not yet
+     implemented. ProjectContext.detect_project_root() walks upward
+     looking for .rosett-ai/ but treats all markers as "project".
+
+  4. Merge strategies: first_wins (default), deep_merge, array_union
+     are implemented. "replace" and "first_found" from design are not.
+     Per-key merge strategy configuration from .rosett-ai/config.yml
+     is not yet implemented.
+
+  5. CompilationPipeline accepts scope: :global or :project (no :local).
+     CLI flags --global/--local/--project not yet integrated.
+
+  6. Per-scope output_dirs not in TargetProfile — uses single output_dir.
+
+  These are known gaps. The 4-level model is the intentional direction;
+  the design doc's 3-level model should be updated to match.

data/conf/design/security.yml

@@ -0,0 +1,115 @@
+---
+name: security
+domain: security
+version: 1.2.0
+status: implemented
+priority: 1
+author: hugo
+created_at: "2026-02-18"
+modified_at: "2026-03-17"
+modified_by: claude
+depends_on: []
+#
+intent: |
+  Establish security as the foundation layer of Rosett-AI. Every line of code written
+  after this document is adopted must follow these constraints. Retrofitting
+  security is 10x more expensive than building it in. This document defines hard
+  rules, required tooling, and safe coding patterns that apply to ALL code in
+  the project — core, TUI, GUI, compilers, and tests.
+#
+constraints:
+  - Never use YAML.load — always YAML.safe_load with explicit permitted_classes
+  - Never interpolate user input into system() calls — use array form exclusively
+  - Never write files outside whitelisted directories (~/.claude/, project .claude/, ~/.config/rosett-ai/)
+  - All file writes must set restrictive permissions (0644 for files, 0755 for directories)
+  - Secrets files must use 0600 permissions
+  - Never log, display, or include in error messages any secrets, API keys, or tokens
+  - All external input (YAML, JSON, CLI arguments, environment variables) must be validated before use
+  - Tempfiles must use Tempfile.new with restrictive permissions and must be cleaned up in ensure blocks
+  - No information conveyed by colour alone (accessibility and security overlap)
+  - Destructive operations require explicit user confirmation before execution
+  - All dependencies must be audited for known CVEs before release
+  - No eval, instance_eval, or class_eval on user-supplied input
+  - File paths must be validated with File.expand_path and checked against whitelists
+  - YAML input must be bounded — max file size (1 MB), max nesting depth (10), max key count (1000)
+  - All user-authored content must be stripped of ANSI escape sequences and control characters before display in TUI/GUI
+  - Identifiers and filenames from external input must be NFC-normalized (Unicode) at input boundaries
+  - Secrets resolution order is ENV variable > system keyring (libsecret/kwallet) > secrets file (0600) — never write secrets to disk by default
+#
+acceptance_criteria:
+  - bundler-audit runs in CI and blocks merge on any known CVE
+  - ruby_audit runs in CI and blocks merge on Ruby stdlib vulnerabilities
+  - RuboCop security cops are enabled and enforced (no violations allowed)
+  - No instance of YAML.load exists in codebase (only YAML.safe_load)
+  - No string-interpolated system() calls exist in codebase
+  - All file write operations use explicit permission setting
+  - CI pipeline rejects code that violates any security constraint
+  - Custom RuboCop cop flags unsafe patterns (YAML.load, interpolated system calls)
+  - YAML files exceeding 1 MB, 10 levels nesting, or 1000 keys are rejected with clear error
+  - TUI output containing ANSI escape sequences from YAML content is sanitized before rendering
+  - Filenames and identifiers are NFC-normalized (verified by test with NFD input producing NFC output)
+  - Secrets are never written to disk unless user explicitly configures a secrets file
+#
+examples:
+  - scenario: "Code reads a user-provided YAML config file"
+    expected: "Uses YAML.safe_load(content, permitted_classes: [Date, Time]) with explicit class allowlist"
+    not: "Uses YAML.load(content) which allows arbitrary object instantiation"
+  - scenario: "Code executes a git command with a user-provided branch name"
+    expected: "system('git', 'checkout', '--', branch_name) using array form"
+    not: "system(\"git checkout #{branch_name}\") which allows shell injection"
+  - scenario: "Code writes a compiled behaviour file to disk"
+    expected: "Validates output path is within ~/.claude/rules/, writes with File.open(path, 'w', 0644)"
+    not: "Writes to arbitrary path without validation or permission setting"
+  - scenario: "An API key is needed for the adopt command"
+    expected: "Resolved via ENV['ANTHROPIC_API_KEY'] > system keyring > secrets file (0600). Never displayed in output."
+    not: "Hardcoded in source, logged in verbose mode, written to disk unprompted, or stored in world-readable config"
+  - scenario: "bundler-audit finds a CVE in a dependency"
+    expected: "CI pipeline fails, merge is blocked, developer must update or justify exception"
+    not: "Warning is ignored, code merges with known vulnerability"
+  - scenario: "A behaviour YAML file contains ANSI escape codes in a rule description"
+    expected: |
+      Control characters and escape sequences are stripped before TUI rendering.
+      'Rule description: clean text here' is displayed. Log warning in development mode.
+    not: "Terminal is cleared, title bar is changed, or garbled output is shown."
+  - scenario: "A 50 MB YAML file is provided as a behaviour config"
+    expected: "Rejected before parsing: 'File exceeds maximum size (1 MB): 50.0 MB'. No memory exhaustion."
+    not: "Parser attempts to load 50 MB into memory. Application hangs or crashes."
+  - scenario: "A filename contains Unicode NFD characters (e.g. e + combining acute)"
+    expected: "Filename is NFC-normalized at input boundary. Stored and compared as single precomposed character."
+    not: "Two visually identical filenames coexist. String comparisons fail silently."
+  - scenario: "User runs bin/raictl adopt and needs an API key"
+    expected: |
+      Checks ENV['ANTHROPIC_API_KEY'] first. If absent, checks system keyring.
+      If absent, checks ~/.config/rosett-ai/secrets.yml (0600). If no key found,
+      prompts user with instructions to set ENV variable.
+    not: "Prompts user to create a plaintext secrets file. Writes API key to disk unprompted."
+#
+anti_patterns:
+  - Using YAML.load for any reason (even when input seems trusted)
+  - String interpolation in shell commands (system, backticks, %x)
+  - Writing files without explicit permission bits
+  - Storing secrets in version-controlled files
+  - Silencing or skipping security audit failures in CI
+  - Using eval/instance_eval/class_eval on dynamic input
+  - Catching and swallowing exceptions without logging (hides security events)
+  - Trusting file paths from CLI arguments without canonicalization
+  - Rendering user-authored YAML content in TUI without stripping control characters
+  - Parsing unbounded YAML input without size or depth limits
+  - Writing secrets to disk as the default or first-choice storage method
+  - Comparing filenames or identifiers without Unicode normalization
+#
+preferences:
+  language: ruby
+  gems:
+    - bundler-audit
+    - ruby_audit
+    - rubocop
+    - rubocop-performance
+    - rubocop-rspec
+    - reek
+    - flay
+  patterns:
+    - input_validation_at_boundaries
+    - fail_fast_on_invalid_input
+    - principle_of_least_privilege
+  testing: rspec with security-focused fixtures

data/conf/design/session_retrospective.yml

@@ -0,0 +1,85 @@
+---
+name: session_retrospective
+domain: operations
+version: 1.0.0
+status: draft
+priority: 6
+author: claude
+created_at: '2026-03-24'
+modified_at: '2026-03-24'
+modified_by: claude
+depends_on:
+  - testing
+  - ci_pipeline
+
+intent: |
+  Define a repeatable methodology for AI session self-evaluation within the Rosett-AI
+  ecosystem. When Claude Code completes a multi-session campaign (coverage push,
+  feature branch, refactoring), it must produce a structured retrospective that
+  identifies what went well, what went poorly, and what concrete process changes
+  would prevent the same failures from recurring.
+
+  This document exists because the coverage push campaign (2026-03-20 through
+  2026-03-24) demonstrated that unchecked agent delegation, insufficient API
+  verification, and poor resource management can waste significant human and
+  compute time. The retrospective methodology captures these lessons in a
+  machine-readable format that persists across sessions.
+
+constraints:
+  - Retrospectives must be honest assessments, never self-congratulatory
+  - Each failure identified must include a root cause (not just a symptom)
+  - Retrospectives must result in actionable process changes, not vague intentions
+  - The retrospective format must be machine-parseable (YAML or structured markdown)
+  - Retrospectives must not require user prompting to be triggered at session boundaries
+  - Agent-introduced failures count against the orchestrator, not the agent
+
+acceptance_criteria:
+  - A /retrospective skill exists that Claude Code can invoke at session end
+  - The skill produces a structured assessment covering successes, failures, and process changes
+  - Each failure includes root cause analysis and a specific preventive action
+  - The retrospective is written to persistent storage (auto memory or project docs)
+  - The methodology is documented in a behaviour file with enforceable rules
+
+examples:
+  - scenario: Claude Code completes a coverage push across 3 sessions
+    expected: >-
+      Before closing the final session, Claude invokes /retrospective and produces
+      a structured assessment. The assessment identifies that 27 agent-introduced
+      test failures were caused by agents writing specs against imagined APIs,
+      and proposes a process change: always read the implementation before writing
+      tests.
+    not: >-
+      Claude says 'the session went well' without identifying specific failures
+      or their root causes.
+
+  - scenario: A session hits the context window limit mid-task
+    expected: >-
+      The retrospective notes the context exhaustion, identifies what consumed
+      the context (e.g. reading too many files in the main window instead of
+      delegating to agents), and proposes a mitigation (e.g. use Explore agents
+      for initial research, keep main window for orchestration).
+    not: >-
+      The retrospective blames context limits as an external constraint without
+      analysing whether the session's approach was context-efficient.
+
+  - scenario: Rate limits are hit due to over-parallelisation
+    expected: >-
+      The retrospective identifies the specific parallel operation pattern that
+      triggered rate limits, estimates the wasted time, and proposes a concurrency
+      cap or sequential fallback strategy.
+    not: >-
+      The retrospective omits the rate limit incident or treats it as unavoidable.
+
+anti_patterns:
+  - Retrospectives that only list successes ('coverage went from X to Y')
+  - Root causes that blame external systems ('the API was slow')
+  - Process changes that are too vague to verify ('be more careful next time')
+  - Skipping the retrospective because the session 'went well'
+  - Writing the retrospective to ephemeral scratch space
+
+preferences:
+  language: ruby
+  patterns:
+    - structured_logging
+    - yaml_first_configuration
+  testing: rspec with schema validation

data/conf/design/smart_ui_feedback.yml

@@ -0,0 +1,89 @@
+---
+name: smart_ui_feedback
+domain: ui
+version: 0.1.0
+status: implemented
+priority: 3
+author: hugo
+created_at: "2026-03-15"
+modified_at: "2026-03-16"
+modified_by: claude
+depends_on:
+  - ui_framework
+  - architecture
+  - autocompletion
+  - error_handling
+#
+intent: >-
+  Transform generic Thor error messages into actionable suggestions using
+  edit distance (Levenshtein) matching. Provide "Did you mean?" feedback
+  for mistyped commands, subcommands, flags, and arguments — reducing
+  frustration, accelerating learning, and making the CLI feel responsive
+  and helpful across rosett-ai's 17+ subcommands and dozens of flags.
+#
+constraints:
+  - "Suggestions must use edit distance (Levenshtein), not substring matching"
+  - "Maximum 3 suggestions per error — more is noise"
+  - "Suggestion threshold: edit distance <= 2 for commands, <= 3 for flags"
+  - "Must not add measurable latency to valid command execution"
+  - "Must work for commands, subcommands, flags, and named arguments"
+  - "Suggestions must respect the current command context (not global)"
+  - "Must integrate with Thor's error handling, not replace it"
+  - "This design governs CLI typo suggestions only. Shell-level tab
+    completion is governed by autocompletion.yml"
+#
+acceptance_criteria:
+  - "`raictl complie` suggests `compile`"
+  - "`rai behaviour shw` suggests `show`"
+  - "`rai compile --verboes` suggests `--verbose`"
+  - "`raictl build package --varient` suggests `--variant`"
+  - "No suggestions shown when edit distance > threshold"
+  - "Valid commands execute without any suggestion overhead"
+  - "Suggestions are formatted consistently: 'Did you mean `X`?'"
+  - "Exit code 1 for unknown command with suggestion, 1 for unknown
+    command without suggestion (same exit code, different message)"
+#
+examples:
+  - scenario: "User types `raictl complie` (transposed letters)"
+    expected: |
+      Error: Unknown command 'complie'. Did you mean `compile`?
+    not: "Error: Could not find command 'complie'."
+  - scenario: "User types `raictl xyz` (no close match)"
+    expected: |
+      Error: Unknown command 'xyz'. Run `raictl help` for available commands.
+    not: "A list of all 17+ commands as suggestions"
+  - scenario: "User types `raictl build package --clean --verboes`"
+    expected: |
+      Error: Unknown option '--verboes'. Did you mean `--verbose`?
+    not: "Generic Thor error with no suggestion."
+#
+anti_patterns:
+  - "Suggesting commands from unrelated subcommand contexts"
+  - "Using substring matching instead of edit distance"
+  - "Showing more than 3 suggestions"
+  - "Adding latency to the happy path (valid commands)"
+  - "Reimplementing Thor's command routing"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. autocompletion.yml: tab completion prevents typos proactively;
+     smart_ui_feedback handles typos reactively. Both improve CLI UX
+     but operate at different points in the interaction.
+
+  2. error_handling.yml: suggestions augment structured error messages.
+     The "Did you mean?" output follows the error hierarchy format.
+
+  3. ui_framework.yml: smart feedback is a CLI-layer feature, not a
+     TUI widget. TUI input fields may have their own completion logic.
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Levenshtein distance for fuzzy matching"
+    - "Thor error handler middleware"
+    - "Cached command registry for zero-latency lookup"
+  testing: rspec with typo fixtures, threshold boundary tests, and
+    context-aware suggestion scenarios
+  gems:
+    - thor