rosett-ai 1.3.3 → 1.5.9

data/conf/design/ab_testing.yml

@@ -1,172 +0,0 @@
----
-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

@@ -1,84 +0,0 @@
----
-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)

data/conf/design/ai_authorship.yml

@@ -1,210 +0,0 @@
----
-name: ai_authorship
-domain: core
-version: 0.1.0
-status: implemented
-priority: 2
-author: hugo
-created_at: "2026-03-10"
-modified_at: "2026-03-16"
-modified_by: claude
-depends_on:
-  - ai_provenance
-  - security
-  - engine_architecture
-  - compiler
-  - error_handling
-  - policy_management
-#
-intent: |
-  Define how AI co-authorship is attributed, disclosed, and managed across
-  all projects using rosett-ai. While ai_provenance.yml tracks the raw data,
-  this design governs the human-facing policies: who gets credit, what
-  trailers appear on commits, how authorship is disclosed in compiled
-  output, and how the "hammer principle" (the human bears responsibility)
-  is operationalised.
-
-  This is particularly important for GPL-3.0 projects where copyright
-  attribution matters legally, and for organisations that need to comply
-  with emerging AI disclosure regulations (EU AI Act transparency
-  obligations, US executive orders on AI).
-
-  Authorship is the attribution layer in the provenance–authorship–policy
-  triad: ai_provenance.yml records what each AI tool did (audit trail),
-  this design governs how that involvement is attributed and disclosed
-  (human-facing output), and policy_management.yml governs the
-  requirements — which projects require what disclosure level.
-
-  Key decisions:
-    - AI tools are never listed as copyright holders (they are tools)
-    - The human operator is always the accountable author
-    - AI involvement is disclosed via standardised commit trailers
-    - Compiled CLAUDE.md / AGENTS.md / .cursorrules include authorship
-      attribution sections generated from provenance data
-    - Behaviour rules can mandate disclosure levels per project
-
-  Inspired by openvox-mcp's Area A (Attribution & Disclosure) and Area F
-  (Accountability), adapted for Rosett-AI's multi-engine compilation model.
-#
-constraints:
-  - "AI tools must never appear as copyright holders in SPDX headers or
-    LICENSE files"
-  - "The human who invoked the AI tool is always the accountable party"
-  - "Commit trailers must use one of the four standardised roles
-    (AI-Generated-By, AI-Co-Author, AI-Assisted-By, AI-Reviewed-By)"
-  - "Trailer format must follow: Role — Tool Version (Provider) <email>"
-  - "Trailer content must be validated against the format specification —
-    tool names must match known engine manifests or be explicitly
-    registered. Unknown tool names produce a warning (error in --strict)"
-  - "Authorship disclosure level is configurable per project (none,
-    minimal, standard, full)"
-  - "Changing disclosure level mid-project applies to future compilations
-    only — existing compiled output is not retroactively updated. A
-    recompile regenerates attribution for all provenance data at the
-    new level"
-  - "Compiled output must include attribution metadata when disclosure
-    level is standard or above"
-  - "Attribution metadata in compiled output must not expose information
-    beyond what the disclosure level permits — disclosure:minimal must
-    not leak per-file AI involvement details even if provenance data
-    contains them"
-  - "No contribution may be blocked solely on authorship grounds (record,
-    do not gate)"
-  - "Authorship rules must compile to every supported engine format.
-    Engines declare supported authorship features (trailers, metadata
-    sections, comments) in their capability manifest"
-  - "Human-Reviewed-By trailer must reference a different person than
-    the submitter"
-  - "Authorship configuration lives in .rosett-ai/config.yml, not in behaviour
-    YAML"
-  - "This design governs attribution and disclosure of AI involvement.
-    Provenance recording (audit trail) is governed by ai_provenance.yml.
-    Policy requirements for disclosure levels are governed by
-    policy_management.yml"
-#
-acceptance_criteria:
-  - "bin/raictl compile generates authorship attribution section when
-    disclosure is standard or above"
-  - "Commit trailer templates are generated for the active engine during
-    compile"
-  - "AI-Generated-By trailer uses the active engine name and version from
-    manifest"
-  - "Human-Reviewed-By validation rejects same-person review (submitter
-    must differ from reviewer)"
-  - "Disclosure level (none, minimal, standard, full) is configurable in
-    .rosett-ai/config.yml"
-  - "Disclosure level none produces no authorship metadata in compiled
-    output"
-  - "Disclosure level full includes per-file AI involvement summary"
-  - "Authorship rules are engine-agnostic — same YAML compiles to all
-    targets"
-  - "bin/raictl authorship status shows current disclosure level and recent
-    AI attributions using TTY-aware output (table when interactive,
-    plain text when piped)"
-  - "Compiled AGENTS.md includes an AI Attribution section when disclosure
-    is standard or above"
-  - "Compiled CLAUDE.md includes Co-Authored-By guidance when disclosure
-    is minimal or above"
-  - "Exit code 0 on success, 1 on compilation failure, 2 on validation
-    error, 3 on invalid trailer format, 5 on missing provenance data"
-#
-examples:
-  - scenario: "Open-source project with GPL-3.0 wants full AI transparency"
-    expected: |
-      .rosett-ai/config.yml sets disclosure: full. bin/raictl compile produces
-      CLAUDE.md with authorship section listing all AI tools used.
-      AGENTS.md includes "## AI Attribution" with provenance summary.
-      Commit hook template includes all four trailer types.
-    not: "AI appears as copyright holder. Attribution silently omitted."
-  - scenario: "Private corporate project wants minimal disclosure"
-    expected: |
-      .rosett-ai/config.yml sets disclosure: minimal. Compiled output includes
-      only a brief note that AI tools were used. No per-file details.
-      Commit trailers still generated (they are in git history, not public).
-    not: "Minimal disclosure disables provenance tracking entirely."
-  - scenario: "Developer submits code and reviews their own AI-generated PR"
-    expected: |
-      If Human-Reviewed-By matches the commit author, validation warns
-      that self-review does not satisfy the review requirement.
-      At strict level, this is an error.
-    not: "Self-review silently accepted as meaningful review."
-  - scenario: "Compiling for Cursor engine which has no trailer concept"
-    expected: |
-      Authorship metadata is embedded in .cursorrules comments or
-      omitted gracefully. Engine capability manifest indicates whether
-      the engine supports commit trailers. Warning emitted for gaps.
-    not: "Compilation fails because Cursor doesn't support trailers."
-  - scenario: "Project sets disclosure level to none"
-    expected: |
-      bin/raictl compile produces no authorship metadata in any compiled
-      output. Provenance tracking continues (recording is separate from
-      disclosure). `raictl authorship status` shows: 'Disclosure: none
-      (provenance recording active, no attribution in compiled output)'.
-    not: "Disclosure:none also disables provenance recording."
-  - scenario: "Commit trailer contains an unrecognised AI tool name"
-    expected: |
-      `raictl authorship validate` warns: 'Trailer AI-Co-Author references
-      unknown tool "GPT-5" — not found in any engine manifest. Register
-      via .rosett-ai/config.yml or install the engine.' --strict mode rejects.
-    not: "Unknown tool names silently accepted in trailers."
-#
-anti_patterns:
-  - "Listing AI tools as copyright holders or contributors in LICENSE files"
-  - "Using 'AI wrote this' as a defence for code quality issues"
-  - "Blocking contributions based solely on AI involvement level"
-  - "Storing authorship preferences in behaviour YAML (it belongs in
-    project config)"
-  - "Requiring all engines to support all authorship features (graceful
-    degradation via capability manifest)"
-  - "Making disclosure mandatory for all projects regardless of context"
-  - "Treating AI-Reviewed-By as equivalent to human review"
-  - "Leaking per-file AI details when disclosure level is minimal or none"
-  - "Retroactively changing compiled output when disclosure level changes
-    (recompile instead)"
-#
-gui_notes: |
-  Document interactions (cross-references):
-
-  1. ai_provenance.yml: provenance records what AI did; authorship governs
-     how that involvement is attributed and disclosed in human-facing output.
-
-  2. policy_management.yml: policies govern disclosure requirements — which
-     projects require what level, and compliance enforcement.
-
-  3. security.yml: SPDX/LICENSE protection, trailer format validation,
-     compiled metadata exposure limits.
-
-  4. engine_architecture.yml: engines declare supported authorship features
-     (trailers, metadata sections, comments) in capability manifests.
-
-  5. compiler.yml: authorship attribution is a compilation output target.
-     Compiler invokes authorship generation as part of the pipeline.
-
-  6. error_handling.yml: exit codes and structured error messages follow
-     the error hierarchy (what/why/fix format).
-
-  7. backward_compatibility.yml: disclosure level changes affect future
-     compilations only — no retroactive output modification.
-
-  Disclosure level matrix:
-    | Level    | Commit Trailers | CLAUDE.md | AGENTS.md | Per-file |
-    |----------|-----------------|-----------|-----------|----------|
-    | none     | No              | No        | No        | No       |
-    | minimal  | Yes             | Brief     | No        | No       |
-    | standard | Yes             | Section   | Section   | No       |
-    | full     | Yes             | Section   | Section   | Yes      |
-#
-preferences:
-  language: ruby
-  patterns:
-    - "Configurable disclosure levels (none/minimal/standard/full)"
-    - "Engine capability-aware compilation"
-    - "Trailer template generation from provenance"
-    - "Separation of tracking (provenance) and policy (authorship)"
-    - "TTY-aware output (TtyHelper)"
-  testing: rspec with disclosure level fixtures, cross-engine compilation
-    tests, trailer format validation, self-review detection, and
-    disclosure level change scenarios
-  gems:
-    - json_schemer
-    - thor