rosett-ai 1.3.3

data/conf/design/error_handling.yml

@@ -0,0 +1,103 @@
+---
+name: error_handling
+domain: core
+version: 0.1.0
+status: implemented
+priority: 1
+author: hugo
+created_at: "2026-03-15"
+modified_at: "2026-03-16"
+modified_by: claude
+depends_on:
+  - security
+  - architecture
+  - i18n
+#
+intent: |
+  Establish a structured error hierarchy, standardised exit codes, and localised
+  error messages for Rosett-AI. Every error the user encounters must be actionable —
+  stating what went wrong, why, and how to fix it. This document prevents ad-hoc
+  error handling that leads to cryptic messages, swallowed exceptions, and
+  inconsistent exit codes across CLI commands.
+#
+constraints:
+  - All rosett-ai errors must inherit from RosettAi::Error (the base class)
+  - Each module defines exactly one error subclass (e.g. RosettAi::Compiler::CompilerError)
+  - Exit codes must follow a defined mapping — 0 success, 1 general error, 2 validation error, 3 configuration error, 4 permission error, 5 dependency error
+  - Error messages must include three parts — what failed, why it failed, and a suggested fix
+  - Error messages must be translatable via i18n keys (not hardcoded English strings)
+  - Never rescue StandardError or Exception at module boundaries — rescue only specific error classes
+  - Never swallow exceptions silently — all rescued exceptions must be logged or re-raised
+  - Stack traces are shown only in DEBUG log level — user-facing output shows structured messages only
+  - CLI commands must set Process.exit with the correct mapped exit code
+  - Error display must respect the current UI mode (TUI table, GUI dialog, plain text for pipes)
+  - Errors from YAML parsing must include the file path and line number when available
+  - Validation errors must be collected and reported as a batch (not fail-fast on first error)
+#
+acceptance_criteria:
+  - RosettAi::Error base class exists with message, code, and suggestion attributes
+  - Every module error class inherits from RosettAi::Error and is documented in error_handling.yml
+  - bin/raictl exits with documented exit code for each error category
+  - Error messages display what/why/fix structure in TUI and plain text modes
+  - All error message strings are i18n keys resolvable from locales/ directory
+  - bin/raictl validate reports all validation errors in a single run (batch mode)
+  - stack traces are suppressed unless RAI_LOG_LEVEL=DEBUG
+  - YAML parse errors include filename and line number in the error message
+  - RSpec tests verify exit codes for each CLI command error path
+  - No instance of rescue StandardError or rescue Exception exists outside the top-level CLI handler
+#
+examples:
+  - scenario: "User runs bin/raictl compile with a malformed behaviour YAML"
+    expected: |
+      Exit code 2. Message: "Validation failed: conf/behaviour/broken.yml:14 —
+      missing required field 'rules'. Fix: add a 'rules' array to the behaviour file."
+    not: |
+      Exit code 1. Message: "undefined method `[]' for nil:NilClass" or
+      silent failure with no output.
+  - scenario: "User runs bin/raictl adopt --api without an API key configured"
+    expected: |
+      Exit code 3. Message: "Configuration error: ANTHROPIC_API_KEY not found.
+      Set it via environment variable or system keyring. See: bin/raictl help adopt"
+    not: |
+      Exit code 1. Message: "HTTP 401 Unauthorized" with no context.
+  - scenario: "User runs bin/raictl compile and two behaviour files have errors"
+    expected: |
+      Both errors displayed in a table. Exit code 2.
+      "2 validation errors in 2 files. Fix errors and re-run bin/raictl compile."
+    not: |
+      First error displayed, second file not checked. User must fix-and-retry repeatedly.
+  - scenario: "Developer pipes bin/raictl validate output to another tool"
+    expected: |
+      Plain text output (no colours, no table borders). One error per line.
+      Exit code reflects worst error category.
+    not: |
+      ANSI escape codes in output corrupt downstream parsing.
+  - scenario: "A permission error occurs writing to ~/.claude/rules/"
+    expected: |
+      Exit code 4. Message: "Permission denied: cannot write to ~/.claude/rules/security.md.
+      Fix: check directory permissions (expected 0755) or run with appropriate user."
+    not: |
+      Exit code 1. Message: "Errno::EACCES: Permission denied @ rb_sysopen"
+#
+anti_patterns:
+  - Using puts for error output instead of structured error objects
+  - Rescuing StandardError as a catch-all at module boundaries
+  - Hardcoded English error messages without i18n keys
+  - Returning nil on failure instead of raising a typed error
+  - Using exit(1) for all error types instead of specific exit codes
+  - Displaying raw Ruby exception messages to end users
+  - Fail-fast validation that stops at the first error
+  - Swallowing exceptions in rescue blocks without logging
+#
+preferences:
+  language: ruby
+  patterns:
+    - error_hierarchy
+    - structured_error_messages
+    - batch_validation
+    - exit_code_mapping
+  testing: rspec with exit code verification and i18n key resolution tests
+  gems:
+    - i18n
+    - thor
+    - pastel

data/conf/design/feature_flags.yml

@@ -0,0 +1,142 @@
+---
+name: feature_flags
+domain: core
+version: 0.1.0
+status: implemented
+priority: 3
+author: hugo
+created_at: "2026-03-16"
+modified_at: "2026-03-16"
+modified_by: claude
+depends_on:
+  - architecture
+  - error_handling
+  - backward_compatibility
+#
+intent: |
+  Provide a lightweight, environment-variable-based feature gating mechanism
+  that allows experimental features to be developed on main without exposing
+  them to users by default. Setting `RAI_EXPERIMENTAL=workflow,mcp` enables
+  only the listed features; all others remain hidden. This prevents premature
+  exposure of incomplete features while allowing developers and testers to
+  exercise new code paths before a stable release.
+
+  Feature flags complement backward compatibility (backward_compatibility.yml):
+  deprecation warnings communicate removal of existing features, while feature
+  flags control visibility of new features before they are stable. Both serve
+  the same goal — protecting users from unexpected changes — but operate in
+  opposite directions (removal vs introduction).
+
+  This design intentionally avoids a database-backed, per-user, or remote
+  feature flag service. Flags are environment-only, process-scoped, and
+  resolved at startup. There is no runtime toggle, no A/B testing, and no
+  analytics integration. Complexity is kept minimal: a single module with
+  a class method interface.
+#
+constraints:
+  - "Feature flags are controlled exclusively via RAI_EXPERIMENTAL environment
+    variable — no config files, no CLI flags, no runtime API"
+  - "Format is comma-separated feature names: RAI_EXPERIMENTAL=workflow,mcp"
+  - "Unknown feature names emit a warning to stderr but do not cause an error"
+  - "Feature flag checks must be O(1) — flags are parsed once at startup into
+    a frozen Set"
+  - "When a gated command is invoked without its flag enabled, the error message
+    must name the required flag: 'rai workflow is experimental. Enable with:
+    RAI_EXPERIMENTAL=workflow'"
+  - "Feature flags must not affect the behaviour of stable (non-experimental)
+    commands"
+  - "All feature flag names must be snake_case, matching the design document
+    name they gate"
+  - "Feature flags are removed (replaced with unconditional code) when the
+    feature is promoted to stable in a release"
+  - "The list of known experimental features must be maintained in a single
+    constant (KNOWN_FLAGS) for discoverability"
+  - "This design governs feature visibility gating. Deprecation of existing
+    features is governed by backward_compatibility.yml. Configuration
+    compilation is governed by compiler.yml"
+#
+acceptance_criteria:
+  - "RosettAi::FeatureFlags.enabled?(:workflow) returns true when
+    RAI_EXPERIMENTAL includes 'workflow'"
+  - "RosettAi::FeatureFlags.enabled?(:workflow) returns false when
+    RAI_EXPERIMENTAL is unset or does not include 'workflow'"
+  - "Unknown flag names in RAI_EXPERIMENTAL emit a warning to stderr"
+  - "Gated CLI commands display an actionable error when invoked without
+    the required flag"
+  - "RosettAi::FeatureFlags.all_enabled returns the Set of currently active flags"
+  - "RosettAi::FeatureFlags::KNOWN_FLAGS contains all recognized flag names"
+  - "Stable commands are unaffected by RAI_EXPERIMENTAL values"
+  - "Flag parsing happens once at module load time, not on every check"
+  - "Exit code 1 when a gated command is invoked without its flag"
+#
+examples:
+  - scenario: "User runs `rai workflow run ci.yml` without the workflow flag"
+    expected: |
+      Error: "rai workflow is experimental and not enabled.
+      Enable with: RAI_EXPERIMENTAL=workflow bin/raictl workflow run ci.yml"
+      Exit code 1.
+    not: |
+      Command runs with unexpected behaviour. Error message does not mention
+      how to enable the feature. Exit code 0.
+  - scenario: "Developer enables workflow and mcp features"
+    expected: |
+      RAI_EXPERIMENTAL=workflow,mcp bin/raictl workflow run ci.yml succeeds.
+      bin/raictl mcp status succeeds. Other experimental features remain hidden.
+    not: "Enabling one feature enables all experimental features."
+  - scenario: "User sets RAI_EXPERIMENTAL=workflow,nonexistent"
+    expected: |
+      Warning on stderr: "Unknown experimental feature: nonexistent.
+      Known features: workflow, mcp, doctor, comply."
+      Workflow feature is enabled normally despite the unknown flag.
+    not: |
+      Error that prevents any command from running. Unknown flag silently
+      ignored without warning.
+  - scenario: "Feature is promoted to stable in v1.2.0"
+    expected: |
+      Feature flag guard is removed from the command. RAI_EXPERIMENTAL=workflow
+      has no effect (feature is always available). KNOWN_FLAGS no longer lists it.
+      CHANGELOG documents: "workflow command is now stable (no longer requires
+      RAI_EXPERIMENTAL)."
+    not: |
+      Flag guard remains in code. Users must set RAI_EXPERIMENTAL forever.
+      Promotion is not documented.
+#
+anti_patterns:
+  - "Database-backed or remote feature flag services (overkill for CLI tool)"
+  - "Per-user feature flags (rosett-ai is a single-user CLI)"
+  - "Runtime feature toggling (flags are resolved once at startup)"
+  - "Config file-based flags (environment variable is the only source)"
+  - "Enabling all experimental features with a single flag like 'all'
+    (explicit opt-in per feature prevents accidental exposure)"
+  - "Checking ENV on every call instead of parsing once into a frozen Set"
+  - "Using feature flags for A/B testing or analytics"
+  - "Leaving flag guards in code after a feature is promoted to stable"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. backward_compatibility.yml: deprecation warnings for existing features
+     and feature flags for new features are complementary mechanisms.
+
+  2. error_handling.yml: gated command errors follow the structured error
+     hierarchy with what/why/fix pattern and exit code 1.
+
+  3. architecture.yml: feature flags follow the minimal-dependency principle
+     (stdlib only, no external gems).
+
+  Module structure:
+
+  lib/rosett_ai/feature_flags.rb  — Single module with class methods
+                                KNOWN_FLAGS constant, .enabled?, .all_enabled,
+                                .gate! (raises if feature not enabled)
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Frozen Set for O(1) membership checks"
+    - "Module with class methods (no instances needed)"
+    - "Single constant for known flags (KNOWN_FLAGS)"
+    - "Parse-once at module load time"
+  testing: rspec with ENV stubbing for flag combinations, unknown flag
+    warnings, gated command errors, and promotion (flag removal) scenarios
+  gems: []

data/conf/design/git_hooks.yml

@@ -0,0 +1,165 @@
+---
+name: git_hooks
+domain: core
+version: 0.1.0
+status: implemented
+priority: 3
+author: hugo
+created_at: "2026-03-16"
+modified_at: "2026-03-16"
+modified_by: claude
+depends_on:
+  - architecture
+  - compiler
+  - security
+  - error_handling
+  - workflow
+  - monitoring_observability
+#
+intent: >-
+  Provide configurable, opt-in git hook integration that runs rai commands
+  at key points in the git lifecycle — keeping compiled output, validation
+  state, and configuration in sync with the working tree automatically. Hooks
+  are declared in the project's .rosett-ai/config.yml (not installed imperatively),
+  coexist with existing hook managers (overcommit, husky, lefthook), and
+  respect the user's choice to enable or disable them per project.
+#
+constraints:
+  - "Git hook integration must be opt-in — never installed automatically by
+    `rai init` without explicit user consent"
+  - "Hook definitions must be declarative YAML in the project root config
+    (.rosett-ai/config.yml, hooks section), not imperatively installed shell scripts"
+  - "All hook commands must use array-form execution — no string interpolation
+    or shell expansion"
+  - "Hooks must coexist with existing hook managers — rosett-ai writes to its own
+    hook script and chains to any pre-existing hook via the GIT_HOOK_CHAIN
+    convention"
+  - "Hook execution must be silent on success (exit 0, no stdout) and
+    informative on failure (structured error to stderr)"
+  - "Hook failures must never corrupt the git operation — pre-commit failures
+    block the commit, but post-checkout failures must not block checkout"
+  - "Hooks must respect RAI_SKIP_HOOKS=1 to allow emergency bypass without
+    removing the hook installation"
+  - "Hook installation must be reversible — `rai hooks uninstall` restores
+    the pre-rosett-ai hook state exactly"
+  - "Hooks must complete within a configurable timeout (default 30 seconds) to
+    prevent blocking interactive git workflows"
+  - "Hook scripts must be POSIX sh for portability — they invoke rosett-ai as an
+    external command, not as inline Ruby. This is the same infrastructure
+    exception as CI/packaging Bash scripts (per language purity rules)"
+  - "Hooks must log their execution to the Rosett-AI audit trail when
+    monitoring_observability is enabled"
+  - "The set of supported git hooks is limited to pre-commit, post-commit,
+    post-checkout, post-merge, and pre-push — no server-side hooks"
+  - "This design governs git hook integration (automated reactions to git
+    lifecycle events). Multi-step workflow orchestration (independent of git)
+    is governed by workflow.yml. A hook may trigger a workflow, but hooks
+    and workflows are independently defined"
+#
+acceptance_criteria:
+  - "`rai hooks install` reads .rosett-ai/config.yml and installs configured
+    hooks to .git/hooks/"
+  - "`rai hooks uninstall` removes rai hooks and restores any previous
+    hook scripts"
+  - "`rai hooks list` shows installed hooks with their configured commands
+    using TTY-aware output (table when interactive, plain text when piped)"
+  - "`rai hooks status` shows which hooks are installed and whether they
+    match the current config, using TTY-aware output"
+  - "pre-commit hook runs `rai validate` and blocks commit on failure"
+  - "post-checkout hook runs `rai compile` and reports if compilation changes
+    any output files"
+  - "post-merge hook runs `rai compile` to sync output with merged changes"
+  - "pre-push hook runs `rai validate --strict` and blocks push on failure"
+  - "RAI_SKIP_HOOKS=1 bypasses all rai hooks for the current git operation"
+  - "Hook timeout terminates the Rosett-AI process after the configured limit"
+  - "Existing hooks (overcommit, husky) continue to function when rai hooks
+    are installed alongside them"
+  - "Hook configuration changes in .rosett-ai/config.yml are detected by
+    `rai hooks status` as drift"
+  - "`rai hooks install` detects existing hooks (including symlinks from
+    overcommit/husky) and chains correctly without breaking them"
+  - "Exit code 0 on success, 1 on hook execution failure, 3 on missing
+    or invalid hook configuration, 5 on missing rosett-ai dependency"
+  - "Hooks are complementary to workflows — hooks automate git lifecycle
+    events, workflows orchestrate multi-step sequences independent of git"
+#
+examples:
+  - scenario: "Developer enables pre-commit validation in a project"
+    expected: |
+      .rosett-ai/config.yml contains `hooks: { pre_commit: ["validate"] }`.
+      `rai hooks install` writes .git/hooks/pre-commit that invokes
+      `rai validate`. Next `git commit` runs validation first.
+    not: |
+      Hook is installed globally affecting all repositories. Hook is a
+      raw shell script that must be manually maintained.
+  - scenario: "Developer switches branches with different behaviour configs"
+    expected: |
+      post-checkout hook runs `rai compile`. If compiled output changes,
+      a brief message is printed: "rosett-ai: recompiled 3 rules for branch
+      feature/x". If nothing changed, no output.
+    not: |
+      Stale compiled rules from the previous branch remain in place.
+      Developer must manually remember to run `rai compile`.
+  - scenario: "Project uses overcommit for linting and rosett-ai for config validation"
+    expected: |
+      Both hook managers coexist. rosett-ai's pre-commit script detects the
+      existing overcommit hook, chains to it after running rosett-ai's own
+      checks. Both run on every commit.
+    not: |
+      raictl overwrites overcommit's pre-commit hook. Linting stops working.
+  - scenario: "Hook takes too long during pre-commit"
+    expected: |
+      After 30 seconds (or configured timeout), the hook process is
+      terminated. Commit is blocked with message: "rosett-ai: pre-commit
+      timed out after 30s. Run `rai validate` manually or set
+      RAI_SKIP_HOOKS=1."
+    not: |
+      Developer waits indefinitely. Only option is Ctrl-C.
+#
+anti_patterns:
+  - "Installing hooks without explicit user opt-in"
+  - "Using string-form shell execution in hook scripts"
+  - "Overwriting existing hook managers instead of chaining"
+  - "Silent failures in post-checkout or post-merge hooks that hide errors"
+  - "Hooks that require network access and block offline git workflows"
+  - "Coupling hook logic to a specific hook manager's internal format"
+  - "Hardcoding hook commands instead of reading from declarative config"
+  - "Server-side hooks that run on remote repositories"
+  - "Assuming all hook managers use the same chaining mechanism — detect
+    symlinks, wrapper scripts, and direct hooks individually"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. workflow.yml: hooks may trigger workflows but are independently defined.
+     Hooks automate git lifecycle reactions; workflows orchestrate multi-step
+     sequences independent of git.
+
+  2. compiler.yml: post-checkout and post-merge hooks invoke `rai compile`
+     to keep compiled output in sync with the working tree.
+
+  3. security.yml: array-form execution for hook commands, no string
+     interpolation or shell expansion.
+
+  4. error_handling.yml: hook failures emit structured errors to stderr
+     (what/why/fix format). Exit codes follow the error hierarchy.
+
+  5. monitoring_observability.yml: hooks log execution to the telemetry
+     system when enabled.
+
+  6. architecture.yml: hook configuration lives in .rosett-ai/config.yml, the
+     project root config managed by `rai init`.
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Declarative hook configuration in YAML"
+    - "Hook chaining convention (GIT_HOOK_CHAIN)"
+    - "Timeout-wrapped execution"
+    - "POSIX sh hook scripts (infrastructure exception)"
+    - "TTY-aware output (TtyHelper)"
+  testing: rspec with git repository fixtures, hook chaining scenarios,
+    timeout handling, RAI_SKIP_HOOKS bypass, overcommit/husky coexistence,
+    and drift detection tests
+  gems:
+    - thor