rosett-ai 1.3.3

data/SECURITY.md

@@ -0,0 +1,114 @@
+# Security Policy
+
+## Scope
+
+This policy covers the following NeatNerds open-source projects:
+
+- **Rosett-AI** (raictl) --- the core CLI and compiler
+- **rosett-ai-engine-\*** --- all official engine adapter gems
+- **auditor-mcp** --- InSpec MCP server
+- **openvox-mcp** --- OpenVox MCP server
+- **neatspec** --- Compliance-as-a-Service wrapper
+
+Third-party forks and community plugins are outside this scope unless
+they ship under the `neatnerds` GitLab namespace.
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| Latest release | Yes |
+| Previous minor | Security fixes only |
+| Older | No |
+
+Only the latest tagged release and the immediately preceding minor
+release receive security patches. If you are running an older version,
+please upgrade before reporting.
+
+## Reporting a Vulnerability
+
+**Do not open a public issue for security vulnerabilities.**
+
+### Email (primary channel --- no account required)
+
+Send an email to **security@neatnerds.be** with:
+
+1. Affected project and version
+2. Description of the vulnerability
+3. Steps to reproduce (proof-of-concept if possible)
+4. Impact assessment (what an attacker could achieve)
+
+Email is the primary reporting channel. It requires no account, no
+registration, and no prior relationship with the project. Anyone who
+discovers a vulnerability can report it immediately.
+
+You may optionally encrypt your report using the PGP key for
+`security@neatnerds.be`, available on
+[keys.openpgp.org](https://keys.openpgp.org). Search for the email
+address to retrieve the public key.
+
+### GitLab Confidential Issue (alternative --- requires account)
+
+If you already have an account on our self-hosted GitLab instance
+(`gitlab.neatnerds.be`), you may open a **confidential** issue on
+the affected project's repository instead. Mark it confidential
+before submitting and use the `Security` issue template.
+
+This channel is mainly useful for existing contributors and
+community members who already have access. If you do not have an
+account, use the email channel above --- do not create an account
+solely to report a vulnerability.
+
+## Response Timeline
+
+| Stage | Target |
+|-------|--------|
+| Acknowledgement | 48 hours |
+| Initial assessment | 7 calendar days |
+| Fix or mitigation | 90 calendar days |
+
+If we cannot meet a target, we will communicate the revised timeline
+in the acknowledgement or assessment response.
+
+## Disclosure Policy
+
+We follow **coordinated disclosure**:
+
+1. The reporter and maintainers agree on a disclosure date (default:
+   90 days after the initial report).
+2. A fix is developed and tested in a private branch.
+3. The fix is released, and a security advisory is published on
+   the same day.
+4. The reporter is credited in the advisory (unless they request
+   anonymity).
+
+We will never disclose a vulnerability before a fix is available
+unless active exploitation is detected in the wild.
+
+## Credit
+
+We gratefully acknowledge security researchers who report
+vulnerabilities responsibly. Unless you request otherwise, your name
+(or handle) and a link to your profile will appear in the security
+advisory and the CHANGELOG entry for the fix.
+
+## Security Advisories
+
+| ID | Date | Severity | Summary |
+|----|------|----------|---------|
+| [NNSA-2026-001](https://gitlab.neatnerds.be/foss/rosett-ai/rosett-ai/-/issues/2) | 2026-04-18 | Medium | Session data included in v1.2.0 gem package. Yanked. Fixed in v1.3.0+. |
+
+## Security Best Practices for Contributors
+
+All contributions must follow these rules (enforced by CI and
+overcommit hooks):
+
+- Use `YAML.safe_load` exclusively --- never `YAML.load`
+- Use array-form `system()` calls --- never string interpolation
+  in shell commands
+- Write files only to whitelisted directories
+- Set 0600 permissions on any file containing secrets
+- Never log secrets or credentials
+- Validate all external input before use
+- Include `# SPDX-License-Identifier: GPL-3.0-only` in every
+  Ruby source file

data/bin/rai

@@ -0,0 +1 @@
+raictl

data/cliff.toml

@@ -0,0 +1,52 @@
+# git-cliff configuration for NeatNerds Code Companion
+# Generates Keep a Changelog 1.1.0 formatted CHANGELOG from conventional commits.
+#
+# Reference: https://git-cliff.org/docs/configuration
+
+[changelog]
+header = """
+# Changelog
+
+All notable changes to the NeatNerds Code Companion (nncc) are documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).\n
+"""
+
+body = """
+{% if version %}\
+    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}\
+    ## [Unreleased]
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | striptags | trim | upper_first }}
+    {% for commit in commits %}
+        - {% if commit.scope %}**{{ commit.scope }}:** {% endif %}\
+            {{ commit.message | split(pat=":") | last | trim | upper_first }}\
+    {% endfor %}
+{% endfor -%}
+"""
+
+footer = ""
+trim = true
+
+[git]
+conventional_commits = true
+filter_unconventional = false
+split_commits = false
+protect_breaking_commits = false
+filter_commits = false
+tag_pattern = "v[0-9].*"
+sort_commits = "oldest"
+commit_parsers = [
+  { message = "^feat", group = "<!-- 0 -->Added" },
+  { message = "^fix", group = "<!-- 1 -->Fixed" },
+  { message = "^refactor", group = "<!-- 2 -->Changed" },
+  { message = "^perf", group = "<!-- 2 -->Changed" },
+  { message = "^docs", group = "<!-- 3 -->Documentation" },
+  { message = "^chore\\(release\\)", skip = true },
+  { message = "^chore", group = "<!-- 4 -->Other" },
+  { message = "^ci", group = "<!-- 4 -->Other" },
+  { message = "^test", group = "<!-- 5 -->Other" },
+  { body = ".*", group = "<!-- 6 -->Other" },
+]

data/conf/adopt_redactions.yml

@@ -0,0 +1,8 @@
+---
+patterns:
+  - pattern: '(?i)\b[A-Z0-9._%+-]+@neatnerds\.be\b'
+    replacement: '[EMAIL-REDACTED]'
+  - pattern: 'NeatNerds'
+    replacement: '[COMPANY]'
+  - pattern: 'gitlab\.neatnerds\.be'
+    replacement: '[INTERNAL-URL]'

data/conf/compliance/cra_rules.yml

@@ -0,0 +1,25 @@
+---
+name: cra_compliance
+version: 1.0.0
+description: EU Cyber Resilience Act (CRA) compliance checks
+rules:
+  - id: CRA-001
+    description: SBOM must be present and current
+    severity: error
+    check: sbom_present
+    remediation: "Generate SBOM with: rai comply --sbom"
+  - id: CRA-002
+    description: Vulnerability disclosure policy must be documented
+    severity: error
+    check: vulnerability_policy
+    remediation: "Create SECURITY.md with vulnerability disclosure policy"
+  - id: CRA-003
+    description: All dependencies must have known licenses
+    severity: warning
+    check: dependency_licenses_known
+    remediation: "Audit dependencies with: rai comply --license"
+  - id: CRA-004
+    description: Contact information for security reports must be provided
+    severity: error
+    check: security_contact
+    remediation: "Add security contact to SECURITY.md or package metadata"

data/conf/compliance/license_rules.yml

@@ -0,0 +1,20 @@
+---
+name: license_compliance
+version: 1.0.0
+description: GPL-3.0-only license compatibility checks
+rules:
+  - id: LIC-001
+    description: All dependencies must have GPL-3.0-compatible licenses
+    severity: error
+    check: gpl_compatible
+    remediation: "Replace GPL-incompatible dependency or add to allowlist"
+  - id: LIC-002
+    description: Project LICENSE file must be present
+    severity: error
+    check: license_file_present
+    remediation: "Create LICENSE file with GPL-3.0-only text"
+  - id: LIC-003
+    description: All source files must have SPDX license headers
+    severity: warning
+    check: spdx_headers
+    remediation: "Add SPDX-License-Identifier header to source files"

data/conf/design/aaif_alignment.yml

@@ -0,0 +1,181 @@
+---
+name: aaif_alignment
+domain: core
+version: 0.1.0
+status: implemented
+priority: 2
+author: hugo
+created_at: "2026-02-24"
+modified_at: "2026-03-16"
+modified_by: claude
+depends_on:
+  - security
+  - architecture
+  - compiler
+  - mcp_integration
+  - error_handling
+#
+intent: |
+  Position rosett-ai as a standards-compliant tool within the Agentic AI Foundation (AAIF)
+  ecosystem by implementing AAIF-governed protocols and compilation targets.
+
+  The AAIF (Linux Foundation, Dec 2025) governs three founding projects:
+  - MCP (Anthropic) — protocol for AI-tool integration
+  - AGENTS.md (OpenAI) — vendor-neutral project instruction files
+  - goose (Block) — open-source AI agent framework
+
+  raictl fills a gap none of these projects address: structured, validated, versioned,
+  auditable configuration management for AI agent workflows. This document defines
+  how rosett-ai integrates with the AAIF ecosystem without losing its core value proposition.
+
+  Key alignments:
+  1. AGENTS.md as a compilation target (alongside CLAUDE.md and generic)
+  2. MCP as the integration protocol (see mcp_integration.yml)
+  3. Vendor-neutral multi-agent support (Claude, Goose, Cursor, Copilot, etc.)
+  4. Potential AAIF project contribution pathway
+
+  AAIF contribution pathway:
+  - Recommended: modular extraction (rosett-ai-mcp as Apache-2.0, core stays GPL-3.0)
+  - Timeline: build MCP integration first, extract after validation, pitch at MCP Dev Summit NYC (April 2-3, 2026)
+  - License tension: AAIF projects use Apache-2.0/MIT; GPL-3.0 is copyleft outlier
+  - Open-core model survives relicensing (content packs are data, not derivative works)
+
+  This design document is part of the AAIF Alignment epic (P2).
+#
+constraints:
+  - AGENTS.md compilation must produce valid, idiomatic Markdown (no YAML frontmatter unless spec adds it)
+  - AGENTS.md output must be readable by all 21+ compatible tools listed on agents.md
+  - Multi-target compilation must not degrade existing CLAUDE.md output quality
+  - Vendor-neutral features must not break Claude Code specific features
+  - AAIF spec tracking must be explicit — pin to known spec versions, not "latest"
+  - No AAIF-specific code paths that circumvent security constraints from security.yml
+  - No code may be contributed to AAIF without a documented license compatibility assessment
+  - AGENTS.md files must be compilable from the same YAML sources as CLAUDE.md
+  - Goose .goosehints format support is optional — only add if demand exists
+  - Any AAIF governance participation must be documented in project decisions log
+#
+acceptance_criteria:
+  - 'bin/raictl compile --engine agents_md produces valid AGENTS.md file'
+  - AGENTS.md output includes all enabled behaviours, properly sectioned by domain
+  - AGENTS.md output is tested against at least 3 tools (manual verification with Claude Code, Goose, Cursor)
+  - Compiler target registry includes agents_md alongside claude, generic, and model-specific targets
+  - Design documents reference AAIF spec versions explicitly (MCP 2025-03-26, AGENTS.md v0.1.0)
+  - Multi-agent configuration support documented with examples for Claude Code, Goose, and generic agents
+  - AAIF ecosystem positioning documented in project README or CONTRIBUTING.md
+  - Compilation lockfile tracks AGENTS.md output alongside existing targets
+  - conf/targets/agents_md.yml target profile exists with format-specific compilation rules
+  - Modular extraction plan documented for Rosett-AI-mcp (Apache-2.0) contribution pathway
+  - License compatibility matrix maintained for AAIF contribution scenarios
+  - AAIF governance participation options documented (Silver member vs project donation)
+  - Compliance differentiator (CRA/NIS2/DORA) integrated into MCP admin capabilities
+#
+examples:
+  - scenario: "User compiles behaviours to AGENTS.md format"
+    expected: |
+      $ bin/raictl compile --engine agents_md --verbose
+      Compiling 12 behaviours to AGENTS.md format...
+      Output: AGENTS.md (project root)
+      Sections: Project Overview, Build & Test, Code Style, Security, Testing
+      Format: Standard Markdown with ## headings per domain
+    not: "Output contains YAML, JSON Schema references, or rosett-ai-internal metadata"
+  - scenario: "User compiles for multiple targets simultaneously"
+    expected: |
+      $ bin/raictl compile --engine claude --engine agents_md
+      Compiling to ~/.claude/rules/ (claude target)
+      Compiling to ./AGENTS.md (agents_md target)
+      Both outputs reflect the same source behaviours with format-appropriate rendering.
+    not: "One target's compilation affects the other's output"
+  - scenario: "User wants to use rosett-ai with Goose instead of Claude Code"
+    expected: |
+      $ bin/raictl compile --engine agents_md
+      Creates AGENTS.md file. Goose reads it as hints (alongside .goosehints).
+      User can also configure rosett-ai as an MCP server in Goose's config.yaml.
+    not: "User must maintain separate configuration for each AI agent"
+  - scenario: "AAIF updates the MCP spec from 2025-03-26 to a newer revision"
+    expected: |
+      raictl tracks spec version in conf/targets/ and mcp_integration design doc.
+      Maintainer reviews changelog, updates pinned version, runs compatibility tests.
+      Release notes document spec version bump.
+    not: "rosett-ai silently breaks on spec change or auto-adopts unreviewed spec versions"
+  - scenario: "Preparing rosett-ai-mcp for AAIF contribution"
+    expected: |
+      1. MCP integration built and tested within rosett-ai (GPL-3.0)
+      2. MCP admin module extracted as rosett-ai-mcp (relicensed Apache-2.0)
+      3. rosett-ai-mcp has own repo, CI, tests, README, GOVERNANCE.md
+      4. Pitched at MCP Dev Summit NYC (April 2-3, 2026)
+      5. If accepted: project hosted under AAIF, copyright to LF Projects, LLC
+      Core rosett-ai remains GPL-3.0 with open-core content model intact.
+    not: "Full rosett-ai donated, GPL-3.0 abandoned, open-core model compromised"
+  - scenario: "AAIF contribution not accepted, continuing independently"
+    expected: |
+      raictl continues as independent project using AAIF standards (MCP, AGENTS.md).
+      Optional: join as Silver member for ecosystem participation without project donation.
+      MCP integration and AGENTS.md compilation still provide value regardless.
+    not: "Project abandoned because AAIF didn't accept it"
+  - scenario: "Evaluating license options for AAIF contribution"
+    expected: |
+      Options evaluated:
+      1. Relicense to Apache-2.0 (content model survives, copyleft lost)
+      2. Dual-license GPL-3.0 + Apache-2.0 (complex but preserves both)
+      3. Extract MCP only as Apache-2.0 (recommended — clean separation)
+      4. Participate as member without donation (keep full control)
+      Decision documented in project decisions log with rationale.
+    not: "License changed without evaluating impact on open-core model"
+  - scenario: "User asks about AAIF compliance status"
+    expected: |
+      $ bin/raictl status --aaif
+      AAIF Alignment Status:
+        MCP Server: enabled (spec 2025-03-26, mcp gem 0.7.1)
+        AGENTS.md: supported (compiled target)
+        CLAUDE.md: supported (compiled target, primary)
+        Goose hints: not supported (planned)
+    not: "No visibility into AAIF ecosystem alignment"
+#
+anti_patterns:
+  - Treating AGENTS.md as a structured format (it is deliberately unstructured Markdown)
+  - Adding AAIF-specific fields to the core behaviour YAML schema (keep source format neutral)
+  - Coupling compilation logic to a single AAIF project (MCP, AGENTS.md, goose are independent)
+  - Auto-updating to new AAIF spec versions without maintainer review
+  - Claiming AAIF compliance or endorsement without actual contribution/acceptance
+  - Ignoring AGENTS.md security concerns (hidden Unicode injection, prompt injection via Markdown)
+  - Duplicating behaviour content across targets instead of compiling from single source
+  - Assuming AGENTS.md will gain a formal schema (design for current unstructured format)
+  - Donating full rosett-ai to AAIF without extracting MCP component first (loses GPL-3.0 protection)
+  - Relicensing core rosett-ai to Apache-2.0 without evaluating open-core model impact
+  - Claiming AAIF membership or endorsement before formal acceptance
+  - Pitching "AI agent config compiler" without the MCP admin angle (too narrow for AAIF)
+  - Ignoring the compliance differentiator (CRA/NIS2/DORA) — this is the strongest enterprise pitch
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. mcp_integration.yml: MCP is the integration protocol. AAIF alignment
+     governs the strategic positioning; MCP integration handles the technical
+     implementation.
+
+  2. compiler.yml: AGENTS.md is a compilation target alongside CLAUDE.md
+     and generic. Target profile: conf/targets/agents_md.yml.
+
+  3. security.yml: AGENTS.md output must not contain hidden Unicode injection
+     or prompt injection patterns.
+
+  4. licensing_system.yml: license compatibility assessment for AAIF
+     contribution (Apache-2.0 vs GPL-3.0 tension).
+
+  5. comply.yml: CRA/NIS2/DORA compliance is the enterprise differentiator
+     for AAIF pitch.
+
+  6. error_handling.yml: exit codes and structured errors for compilation
+     targets.
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Compiler target pattern (AGENTS.md as target)"
+    - "Adapter pattern for format-specific rendering"
+    - "Strategy pattern for multi-target compilation"
+  testing: rspec with AGENTS.md output validation, multi-target compilation
+    tests, and spec version pinning verification
+  gems:
+    - json_schemer
+    - thor

data/conf/design/ab_testing.yml

@@ -0,0 +1,172 @@
+---
+name: ab_testing
+domain: ui
+version: 0.1.0
+status: draft
+priority: 4
+author: hugo
+created_at: "2026-03-23"
+modified_at: "2026-03-23"
+modified_by: claude
+depends_on:
+  - architecture
+  - ui_framework
+  - structured_logging
+  - testing
+#
+intent: |
+  Define a framework for running survey-based A/B preference studies on CLI
+  UX variants. Users manually opt into a variant via `rai config set`, use
+  raictl normally, then submit feedback through a public survey (GitLab issue
+  template or external form). No automated telemetry or data collection of
+  any kind — the framework only controls which UX variant is active.
+
+  The first test case is tree subcommand placement: Variant A (control)
+  keeps `tree` on every command group (current behaviour); Variant B
+  restricts `tree` to top-level only (`raictl tree`). This question cannot
+  be answered by author intuition — it requires empirical measurement
+  from real users.
+
+  Each UX study is defined as a YAML file in `conf/ux_studies/` specifying
+  variants, survey questions, target sample size, and duration. The active
+  variant is stored in `~/.config/rosett-ai/config.yml` under a `ux_variants`
+  key. Default is always the current behaviour (no user-visible change
+  unless explicitly opted in).
+
+  This design intentionally avoids runtime analytics, automatic data
+  reporting, or any mechanism that collects usage data without the user
+  actively choosing to fill out a survey. Privacy is non-negotiable.
+#
+constraints:
+  - "No automated telemetry, usage tracking, or data collection of any kind"
+  - "Variant switching is manual only: `rai config set ux_variant.<study> <variant>`"
+  - "Active variant is stored in `~/.config/rosett-ai/config.yml` under the
+    `ux_variants` key (XDG-compliant path)"
+  - "Survey feedback is submitted manually by users via external survey
+    (GitLab issue template or hosted form) — rosett-ai never transmits data"
+  - "Default variant is always the current behaviour (control) — no
+    user-visible change unless the user explicitly opts in"
+  - "Variant switching takes effect on next command invocation — no
+    process restart required"
+  - "Each UX study definition must specify: variants (2+), survey
+    questions, target sample size, duration, and survey link"
+  - "UX study definitions live in `conf/ux_studies/` as YAML files
+    validated against a schema"
+  - "Study YAML files are shipped with rosett-ai but are informational —
+    the framework reads them to display survey links and variant
+    descriptions, not to enforce participation"
+  - "This design governs UX preference testing. Feature visibility
+    gating is governed by feature_flags.yml. User configuration
+    management is governed by claude_code_configuration.yml"
+#
+acceptance_criteria:
+  - "`rai config set ux_variant.tree_placement per_command` activates
+    Variant A (control: tree on every command group)"
+  - "`rai config set ux_variant.tree_placement top_level` activates
+    Variant B (tree at top level only)"
+  - "`rai config show` displays active UX variants alongside other
+    configuration"
+  - "Default behaviour (no ux_variants key set) is Variant A — no
+    regression from current behaviour"
+  - "UX study YAML files in `conf/ux_studies/` are validated against
+    a JSON schema during `rai validate`"
+  - "Framework is reusable for future UX studies beyond tree placement
+    — no tree-specific logic in the core variant-switching mechanism"
+#
+examples:
+  - scenario: "User opts into the top-level-only tree variant"
+    expected: |
+      $ rai config set ux_variant.tree_placement top_level
+      UX variant set: tree_placement = top_level
+
+      `raictl tree` shows the full command hierarchy.
+      `rai compile tree` is not available (removed from subcommand groups).
+      `raictl tree` output includes a survey link for feedback.
+    not: |
+      Variant change requires a restart. Subcommand `tree` silently
+      disappears without the user opting in.
+  - scenario: "User has never configured any UX variant"
+    expected: |
+      All commands behave exactly as today. `raictl tree` works.
+      `rai compile tree` works. `rai behaviour tree` works.
+      No survey prompts, no variant notices, no behavioural change.
+    not: |
+      User sees A/B testing notices without opting in. Default
+      behaviour changes. Any data is collected silently.
+  - scenario: "User switches back to the default variant"
+    expected: |
+      $ rai config set ux_variant.tree_placement per_command
+      UX variant set: tree_placement = per_command
+
+      All subcommand groups have `tree` again (identical to default).
+    not: |
+      Cannot revert to the original variant. Switching requires
+      editing config files manually.
+  - scenario: "UX study YAML file has invalid structure"
+    expected: |
+      $ rai validate
+      conf/ux_studies/tree_placement.yml: FAIL — missing required key 'target_sample_size'
+      Exit code 1.
+    not: |
+      Invalid study files are silently ignored. Validation does not
+      cover UX study definitions.
+#
+anti_patterns:
+  - "Automated telemetry or usage analytics of any kind"
+  - "Changing default behaviour without explicit user opt-in"
+  - "Collecting any data without the user actively filling out a survey"
+  - "Hardcoding study-specific logic in the variant switching framework"
+  - "Making survey participation a prerequisite for using rosett-ai"
+  - "Shipping a variant as default before the study concludes"
+  - "Using feature flags (RAI_EXPERIMENTAL) for UX variants — different
+    concern, different mechanism"
+  - "Remote configuration or server-side variant assignment"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. feature_flags.yml: feature flags gate experimental features; UX
+     variants switch between alternative implementations of stable
+     features. Both use opt-in mechanisms but serve different purposes.
+
+  2. ui_framework.yml: variant switching affects CLI command registration
+     (Thor subcommand groups), which is a UI framework concern.
+
+  3. structured_logging.yml: variant switching events can be logged
+     locally for debugging, but logs are never transmitted.
+
+  4. architecture.yml: UX study definitions follow the data-driven
+     pattern (YAML config, not hardcoded logic).
+
+  First study definition (conf/ux_studies/tree_placement.yml):
+
+  name: tree_placement
+  description: "Tree subcommand placement preference study"
+  status: active
+  variants:
+    per_command:
+      description: "tree available on every command group (current)"
+      default: true
+    top_level:
+      description: "tree available only as top-level `raictl tree`"
+  survey:
+    questions:
+      - "Which variant do you prefer? (A: per-command / B: top-level)"
+      - "Rate discoverability of the tree command (1-5)"
+      - "Free-text: any other feedback on tree command placement?"
+    link: "https://gitlab.neatnerds.be/neatnerds/NeatNerds-AI/rosett-ai/-/issues/new?issuable_template=ux_study_tree_placement"
+  target_sample_size: 30
+  duration_days: 90
+  created_at: "2026-03-23"
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Data-driven variant definitions (YAML, not hardcoded)"
+    - "Config-based opt-in (XDG config.yml, not environment variables)"
+    - "Strategy pattern for variant-specific command registration"
+    - "Schema validation for UX study definitions"
+  testing: rspec with variant switching scenarios, default behaviour
+    regression tests, config persistence, and study YAML validation
+  gems:
+    - thor

data/conf/design/accessibility.yml

@@ -0,0 +1,84 @@
+---
+name: accessibility
+domain: accessibility
+version: 1.1.0
+status: implemented
+priority: 3
+author: hugo
+created_at: "2026-02-18"
+modified_at: "2026-03-17"
+modified_by: claude
+depends_on:
+  - architecture
+
+intent: |
+  Ensure rosett-ai is usable by humans with any kind of disability — visual
+  impairment, motor impairment, cognitive difficulties, or those using
+  assistive technologies. Accessibility is a core design constraint, not a
+  feature to add later. As a Belgium/EU project, rosett-ai targets EN 301 549
+  compliance and WCAG 2.2 Level AA principles. Building to this standard
+  from the start avoids costly retrofitting required by the European
+  Accessibility Act (EAA).
+
+constraints:
+  - All interactive elements must be keyboard-accessible in all UI variants
+  - All interactive elements must have accessible labels (no unlabelled buttons or controls)
+  - No information may be conveyed by colour alone (use icons or text alongside)
+  - No audio-only feedback (always provide visual or text equivalent)
+  - Focus indicator must be visible at all times (never hidden)
+  - Error messages must identify the specific field and describe the error clearly
+  - Destructive actions require confirmation (undo capability or explicit prompt)
+  - TUI accessible mode must produce linear, sequential text (no box drawing)
+  - GTK4 must use GtkAccessible roles and labels on all widgets
+  - Qt6 must use QAccessible roles, accessibleName, and accessibleDescription
+  - Minimum touch/click target size is 44x44dp (WCAG 2.2 Level AA)
+  - No auto-dismissing notifications or time-limited interactions
+  - Animations must respect prefers-reduced-motion system setting
+
+acceptance_criteria:
+  - Accessible mode (--accessible) auto-activates when ORCA_RUNNING or BRLTTY_TTY is set
+  - Keyboard-only navigation reaches all interactive elements in TUI mode
+  - Screen reader (Orca) can read all content and announce state changes
+  - High-contrast system theme produces no invisible or unreadable elements
+  - UI works at 200% font scaling without clipping or overlap (GTK4/Qt6 — deferred to GUI phase)
+  - accerciser audit reports no missing roles or labels in GTK4 implementation (GTK4 — deferred to GUI phase)
+  - All design documents with domain=ui include an accessibility section
+  - shared_examples "a UI implementation" includes accessibility method checks
+
+examples:
+  - scenario: "Visually impaired user navigates settings with Orca"
+    expected: |
+      Screen reader announces: 'Settings categories, navigation'.
+      Arrow keys move between items. Orca announces each item name.
+      Enter selects. Detail pane announces: 'Settings for General, form'.
+      Tab moves between form fields. Each field label is announced.
+    not: "Orca reads box drawing characters. Navigation is silent. Fields have no labels."
+  - scenario: "Motor-impaired user uses switch access (2 buttons)"
+    expected: |
+      Sequential focus order moves through all controls in logical order.
+      Each focusable element has visible focus indicator. Activation targets
+      are at least 44x44dp.
+    not: "Focus jumps erratically. Small targets require precision. No visible focus indicator."
+  - scenario: "User enables high-contrast theme in GNOME"
+    expected: "All text remains readable. No elements become invisible. No colour-only indicators."
+    not: "Status indicators that were green/red become indistinguishable."
+  - scenario: "Arabic-speaking user runs rosett-ai with locale ar"
+    expected: "TUI text direction is RTL. GUI layout mirrors. Screen reader reads in correct direction."
+    not: "RTL text renders backwards. Layout remains LTR. Mixed content is garbled."
+
+anti_patterns:
+  - Treating accessibility as a separate feature to add later
+  - Using colour as the sole indicator of state (red/green for error/success)
+  - Creating custom widgets without accessibility roles
+  - Hardcoding colours instead of respecting system theme
+  - Auto-dismissing notifications without user action
+  - Mouse-only interactions with no keyboard equivalent
+  - Skipping accessibility testing in CI or review process
+
+preferences:
+  language: ruby
+  patterns:
+    - accessible_by_default
+    - semantic_roles_on_all_widgets
+    - keyboard_first_interaction_design
+  testing: rspec with accerciser integration for GTK4 (future)