rosett-ai 1.3.3

data/conf/design/ai_authorship.yml

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

data/conf/design/ai_provenance.yml

@@ -0,0 +1,224 @@
+---
+name: ai_provenance
+domain: security
+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:
+  - security
+  - engine_architecture
+  - compiler
+  - error_handling
+  - ai_authorship
+#
+intent: |
+  Establish structured, machine-readable provenance tracking for AI involvement
+  in code contributions managed by Rosett-AI. Record which AI tools contributed to
+  which files, what role the AI played, and what external sources it drew from.
+
+  raictl already manages rules for multiple AI engines. This design extends
+  that to track provenance — the "who did what with which AI" metadata that
+  enables compliance auditing, license verification, and transparent
+  attribution in open-source projects.
+
+  Inspired by the OpenVox MCP Server's .ai-provenance.yml format (B3),
+  adapted for Rosett-AI's engine-agnostic, multi-tool architecture. Where
+  openvox-mcp tracks provenance for a single project, rosett-ai manages it
+  across all projects the user works on, compiling provenance metadata
+  alongside behaviour rules.
+
+  Provenance is the recording layer — it creates an audit trail of what
+  each AI tool did, per commit, with file-level granularity. The related
+  ai_authorship.yml design handles attribution and crediting — how AI
+  contributions are presented in commit trailers, AGENTS.md, and other
+  public-facing outputs. Policy management (policy_management.yml)
+  governs the requirements — which projects require provenance, at what
+  level, and what happens when provenance is missing.
+
+  Key capabilities:
+    - Per-commit AI provenance entries with file-level granularity
+    - Source type classification (library_api, project_code, documentation,
+      pattern, external_source) for license traceability
+    - Commit trailer generation (AI-Generated-By, AI-Co-Author,
+      AI-Assisted-By, AI-Reviewed-By) across all supported engines
+    - Engine-specific provenance: each engine records its own identity
+    - Compilation target: provenance YAML compiles to commit hooks,
+      CI validation rules, or AGENTS.md attribution sections
+    - A single commit may have provenance entries from multiple engines
+      (e.g. Ollama for local analysis, Claude for generation)
+#
+constraints:
+  - "Provenance file (.ai-provenance.yml) must use YAML.safe_load only"
+  - "Provenance entries are append-only — existing entries must never be
+    modified or deleted"
+  - "Each provenance entry must include a SHA-256 hash of the previous
+    entry (hash chain), creating a tamper-evident append-only log.
+    The first entry uses a zero hash. Validation checks the chain
+    integrity"
+  - "Source URLs for external_source type must reference specific pages,
+    not bare domains"
+  - "All provenance data must be storable offline — no mandatory network calls"
+  - "Commit trailers must follow the format: Trailer — Tool Version
+    (Provider) <email>"
+  - "Provenance validation must work without any engine installed (core feature)"
+  - "File paths in provenance entries must be relative to project root"
+  - "Provenance schema must be versioned independently from rosett-ai version"
+  - "No personally identifiable information beyond what git already stores
+    (name + email)"
+  - "Provenance entries must be validated before being written to disk"
+  - "When a provenance file exceeds a configurable size threshold (default
+    1 MB), rosett-ai must offer archival: move older entries to a dated archive
+    file (.ai-provenance.YYYY.yml) and start a new active file with the
+    last entry's hash as the chain root"
+  - "This design governs provenance recording (audit trail of AI involvement).
+    Attribution and crediting of AI contributions is governed by
+    ai_authorship.yml. Policy requirements for provenance (which projects
+    require it, at what level) are governed by policy_management.yml"
+#
+acceptance_criteria:
+  - "bin/raictl provenance init creates .ai-provenance.yml in project root
+    with version header and zero-hash chain root"
+  - "bin/raictl provenance add creates a new entry with commit, contributor,
+    ai_tool, ai_role, files, and hash chain link"
+  - "bin/raictl provenance validate checks all entries against the provenance
+    schema and verifies hash chain integrity"
+  - "bin/raictl provenance show COMMIT displays provenance for a specific commit"
+  - "bin/raictl provenance show --file PATH displays all provenance entries
+    for a file"
+  - "bin/raictl provenance log shows all entries in reverse chronological order
+    using TTY-aware output (table when interactive, plain text when piped)"
+  - "bin/raictl provenance log --role AI-Co-Author filters entries by AI role"
+  - "Commit trailers (AI-Generated-By etc.) are generated from provenance
+    entries during compile"
+  - "Engine name and version are automatically populated from the active
+    engine's manifest"
+  - "Source type is validated against the allowed list (library_api,
+    project_code, documentation, pattern, external_source)"
+  - "External sources with bare domain URLs are rejected with a clear
+    error message"
+  - "Provenance file exceeding the size threshold triggers archival
+    recommendation"
+  - "All provenance operations work without network access"
+  - "Provenance entries survive round-trip (load → save produces identical YAML)"
+  - "Exit code 0 on success, 1 on write failure, 2 on validation error,
+    3 on hash chain integrity failure, 5 on missing provenance file"
+#
+examples:
+  - scenario: "Developer uses Claude to write a new module, runs bin/raictl provenance add"
+    expected: |
+      Entry created with ai_tool: "Claude Opus 4.6 (Anthropic)",
+      ai_role: "AI-Co-Author", commit SHA from HEAD, contributor from
+      git config. File paths listed with source references. Hash chain
+      links to previous entry's SHA-256.
+    not: "Entry silently created without validation. AI tool name guessed incorrectly."
+  - scenario: "CI pipeline validates provenance on a pull request"
+    expected: |
+      bin/raictl provenance validate checks every commit in the PR has a
+      matching provenance entry. Missing entries produce warnings at
+      advisory level or errors at strict level. Hash chain is verified.
+    not: "Validation requires network access. Missing provenance silently passes."
+  - scenario: "Developer uses Ollama locally, no internet access"
+    expected: |
+      bin/raictl provenance add --engine ollama records provenance with
+      ai_tool from ollama engine manifest. Works completely offline.
+    not: "Provenance recording fails because it cannot reach an API."
+  - scenario: "A provenance entry references a StackOverflow answer"
+    expected: |
+      Source type: external_source, reference: "Answer by user123 on
+      handling thread safety in Ruby", url: specific answer URL.
+      Validated successfully.
+    not: "URL is just https://stackoverflow.com/ — rejected as too vague."
+  - scenario: "Developer views provenance history for a project"
+    expected: |
+      `rai provenance log` shows reverse chronological entries:
+      ┌───────────┬─────────────────┬───────────────┬──────────────┐
+      │ Commit    │ AI Tool         │ Role          │ Files        │
+      ├───────────┼─────────────────┼───────────────┼──────────────┤
+      │ abc1234   │ Claude Opus 4.6 │ AI-Co-Author  │ lib/foo.rb   │
+      │ def5678   │ Ollama llama3.3 │ AI-Assisted   │ spec/bar.rb  │
+      └───────────┴─────────────────┴───────────────┴──────────────┘
+      Piped output: tab-separated, no box drawing.
+    not: "No way to see provenance history. Must read YAML file manually."
+  - scenario: "Provenance file is corrupted — hash chain broken"
+    expected: |
+      `rai provenance validate` detects the break: 'Hash chain integrity
+      failure at entry #7: expected abc123..., got def456...'. Exit code 3.
+      Identifies the exact entry where tampering occurred.
+    not: "Corruption goes undetected. Provenance file accepted as valid."
+  - scenario: "Provenance file exceeds 1 MB after months of development"
+    expected: |
+      `rai provenance add` warns: 'Provenance file exceeds 1 MB — run
+      `rai provenance archive` to move older entries to a dated archive'.
+      Archive creates .ai-provenance.2026.yml with entries before cutoff.
+      New active file starts with the last archived entry's hash as root.
+    not: "File grows unbounded. No archival mechanism. Parsing slows down."
+#
+anti_patterns:
+  - "Storing provenance in a database instead of a versionable YAML file"
+  - "Requiring API calls to record provenance"
+  - "Allowing modification of existing provenance entries (append-only)"
+  - "Storing full file contents in provenance (only paths and line references)"
+  - "Using provenance to block contributions (it records, does not gate)"
+  - "Hardcoding AI tool names instead of reading from engine manifests"
+  - "Storing provenance per-engine instead of per-project"
+  - "Provenance entries without hash chain links (unverifiable integrity)"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. ai_authorship.yml: provenance records what AI did; authorship handles
+     how contributions are attributed and credited in public outputs.
+
+  2. policy_management.yml: policies govern provenance requirements — which
+     projects require provenance, at what strictness level, and what happens
+     when provenance is missing.
+
+  3. security.yml: YAML.safe_load, PII constraints, offline-first.
+
+  4. engine_architecture.yml: engine manifests provide AI tool identity
+     (name, version, provider) for provenance entries.
+
+  5. compiler.yml: provenance compiles to commit hooks, CI validation
+     rules, and AGENTS.md attribution sections.
+
+  6. error_handling.yml: exit codes and structured error messages follow
+     the error hierarchy (what/why/fix format).
+
+  Provenance entry schema outline:
+    version: string (schema version, e.g. "1.0.0")
+    entries:
+      - commit: string (git SHA)
+        timestamp: string (ISO 8601)
+        contributor:
+          name: string (from git config)
+          email: string (from git config)
+        ai_tool:
+          name: string (from engine manifest)
+          version: string
+          provider: string
+          engine: string (rosett-ai engine name)
+        ai_role: AI-Generated-By | AI-Co-Author | AI-Assisted-By | AI-Reviewed-By
+        files:
+          - path: string (relative to project root)
+            source_type: library_api | project_code | documentation | pattern | external_source
+            reference: string (description of source)
+            url: string (optional, must be specific)
+        hash: string (SHA-256 of previous entry, zero-hash for first)
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Append-only log with hash chain integrity"
+    - "Schema-validated entries before write"
+    - "Engine manifest integration for AI tool identity"
+    - "Offline-first recording"
+    - "TTY-aware output (TtyHelper)"
+  testing: rspec with provenance fixtures, round-trip tests, hash chain
+    validation, archival scenarios, and multi-engine provenance entries
+  gems:
+    - json_schemer
+    - thor

data/conf/design/ai_tool_configuration.yml

@@ -0,0 +1,207 @@
+---
+name: ai_tool_configuration
+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:
+  - engine_architecture
+  - security
+  - claude_code_configuration
+  - error_handling
+  - compiler
+#
+intent: |
+  Establish the engine-agnostic AI tool configuration and asset management
+  layer for Rosett-AI — model selection, context window settings, token budgets,
+  API routing, operational parameters, and AI tool assets (skills, hooks,
+  memory files, keybindings) that apply across all AI tools.
+
+  Relationship to claude_code_configuration.yml: that document is the Claude
+  engine's implementation of the contracts defined here. It handles Claude
+  Code's specific settings.json format, target paths, and scope routing.
+  This document defines the universal configuration and asset schema that
+  all engines implement. As rosett-ai matures, Claude-specific settings migrate
+  from claude_code_configuration into engine-specific config compiled from
+  this generic layer.
+
+  As developers use multiple AI tools simultaneously (Claude for complex
+  tasks, Ollama for quick local queries, Cursor for inline completions),
+  they need a single place to configure model routing, cost controls,
+  operational parameters, and reusable assets (skills, hooks, memory).
+  raictl compiles these preferences and assets into each tool's native
+  configuration format via the engine capability manifest contract.
+#
+constraints:
+  - This document defines the generic configuration and asset schema.
+    claude_code_configuration.yml documents the Claude engine's specific
+    implementation (target paths, JSON format, scope routing). Engine-specific
+    docs are implementation of the contracts defined here, not independent designs
+  - Configuration must be expressible in YAML without engine-specific keys in the generic layer
+  - Engine-specific overrides live in .rosett-ai/conf/engines/<name>/config.yml
+  - API keys and secrets must never appear in configuration YAML (reference ENV vars or keyring)
+  - Model names in generic config use canonical identifiers mapped per engine
+  - Cost controls are advisory — rosett-ai does not enforce runtime token limits
+  - Configuration validation must work without any engine installed
+  - Compiled configuration must respect security.yml constraints (no secret leakage)
+  - Fallback chains must not silently switch from local to remote models
+  - Temperature and sampling parameters are only set when the engine supports them
+  - Configuration changes must be diffable (YAML format, no binary blobs)
+  - AI tool asset types (skills, hooks, memory, keybindings, and others) are
+    declared by each engine's capability manifest as a contract. Core defines
+    the generic asset schema; engines declare which asset types they support,
+    their target paths, and compilation formats
+  - Asset content (skills, hooks) must be validated against ANSI and control
+    character stripping (per security.yml). Hook assets must use array-form
+    execution only — no shell expansion or string interpolation
+  - Skills and hooks are potential attack vectors (jailbreaking, shell expansion,
+    privilege escalation) and must undergo content validation during compilation.
+    Engines must reject asset content containing shell metacharacters in hook
+    definitions or prompt injection patterns in skill definitions
+  - Skill content must not contain secret references or literal API keys
+  - Asset compilation for unsupported asset types must produce warnings
+    (errors in --strict mode), consistent with unsupported parameter handling
+#
+acceptance_criteria:
+  - .rosett-ai/conf/ai_config.yml defines model routing, context, cost, and operational settings
+  - bin/raictl compile translates generic AI config to Claude Code settings.json model preferences
+  - bin/raictl compile --engine ollama translates to Ollama-specific model configuration
+  - bin/raictl compile --engine cursor translates to Cursor settings where applicable
+  - Model routing maps canonical names to engine-specific identifiers (e.g. "best" -> "claude-opus-4-6" for Claude, "llama3.3:70b" for Ollama)
+  - API key references use ENV variable names only — never literal values
+  - Context window settings compile to engine-native max_tokens or equivalent
+  - Fallback chain compilation warns when a fallback switches from local to remote
+  - bin/raictl config validate checks AI tool configuration against schema
+  - Engine capability manifest determines which settings are compilable for each engine
+  - Unsupported settings for a given engine produce warnings (errors in --strict mode)
+  - Cost tier preferences (economy/standard/premium) map to concrete models per engine
+  - Generic skill definition compiles to engine-native skill format (e.g.
+    .claude/skills/ for Claude, .cursor/rules/ for Cursor)
+  - Asset type not supported by an engine produces a warning listing the
+    unsupported type and the engine name (error in --strict mode)
+  - Engine manifest declares supported asset types with target paths and
+    compilation formats, verifiable by bin/raictl engines detect
+#
+examples:
+  - scenario: "Developer configures model routing for a mixed local/cloud workflow"
+    expected: |
+      .rosett-ai/conf/ai_config.yml defines: generation: premium, review: standard,
+      completion: economy. bin/raictl compile maps premium->opus for Claude,
+      premium->llama3.3:70b for Ollama. Each engine's compiled config uses
+      native model identifiers.
+    not: "Generic config contains claude-opus-4-6 directly. Ollama compilation fails."
+  - scenario: "Organisation sets a monthly token budget across all AI tools"
+    expected: |
+      ai_config.yml sets cost.monthly_budget: advisory with a note.
+      Compiled Claude Code config includes maxTokens hints. Compiled
+      AGENTS.md includes cost awareness instructions. Budget is advisory
+      — rosett-ai does not enforce at runtime.
+    not: "rosett-ai attempts to enforce token limits at runtime. Budget stored as hard limit."
+  - scenario: "Developer uses Ollama locally but wants Claude API as fallback"
+    expected: |
+      Fallback chain: [ollama, claude]. During compile, a warning is emitted:
+      'Fallback from local (ollama) to remote (claude) — network required'.
+      Both engine configs are generated. User acknowledges the trade-off.
+    not: "Silent fallback from local to cloud. No network warning."
+  - scenario: "Compiling for Cursor which does not support temperature settings"
+    expected: |
+      Temperature setting in generic config is skipped for Cursor.
+      Warning: 'Cursor engine does not support temperature parameter — skipped'.
+      In --strict mode, this becomes an error.
+    not: "Invalid temperature setting written to .cursorrules. No warning."
+  - scenario: "Developer authors a reusable skill and compiles for Claude and Cursor"
+    expected: |
+      Generic skill definition in .rosett-ai/conf/assets/skills/code_review.yml
+      compiles to .claude/skills/code_review.md for Claude engine (markdown
+      format) and .cursor/rules/code_review.mdc for Cursor engine (Cursor
+      rules format). Each engine's manifest declares the target path and format.
+    not: |
+      Skill is hardcoded to .claude/skills/ only. Cursor users get nothing.
+      Skill format assumes Claude-specific prompt structure.
+  - scenario: "Compiling hook assets for an engine that does not support hooks"
+    expected: |
+      Warning: 'Ollama engine does not support hook assets — skipped 2
+      hook definitions'. In --strict mode, this becomes an error.
+      Compilation continues for other asset types.
+    not: |
+      Hook definitions are silently dropped with no warning. Or worse,
+      raictl attempts to write hook config to a non-existent Ollama path.
+  - scenario: "Engine manifest declares supported asset types"
+    expected: |
+      Claude engine manifest includes:
+        supported_assets:
+          skills: { target: ".claude/skills/", format: "markdown" }
+          hooks: { target: ".claude/settings.json#hooks", format: "json" }
+          memory: { target: ".claude/memory/", format: "markdown" }
+      bin/raictl engines detect lists all declared asset types per engine.
+    not: |
+      Asset types are hardcoded in core rosett-ai. Adding a new asset type
+      requires modifying core code instead of updating the engine manifest.
+  - scenario: "A skill definition contains a prompt injection attempt"
+    expected: |
+      Compilation validates skill content. Suspicious patterns (e.g.
+      'ignore previous instructions', 'system prompt override', shell
+      metacharacters in hook commands) are flagged as warnings. In --strict
+      mode, compilation fails with a security error.
+    not: |
+      Malicious skill content is compiled and deployed without review.
+      Hook definitions with shell expansion are written to native config.
+#
+anti_patterns:
+  - Storing API keys in configuration YAML (use ENV references)
+  - Engine-specific model names in generic configuration layer
+  - Hardcoding model mappings instead of deriving from engine manifests
+  - Runtime token enforcement (rosett-ai is a compiler, not a runtime)
+  - Silent local-to-remote fallback without user awareness
+  - Binary configuration formats that cannot be diffed
+  - Assuming all engines support all parameters (capability-aware compilation)
+  - Designing the generic asset schema to match Claude Code's model too
+    closely — other engines have asset types that may not map to Claude's
+    categories (e.g. Cursor has .mdc rules, GitHub Copilot has instructions)
+  - Hardcoding asset types in core instead of declaring them in engine manifests
+  - Compiling skill or hook content without security validation
+  - Allowing shell metacharacters or string interpolation in hook definitions
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. engine_architecture.yml: engines declare capability manifests including
+     supported asset types, target paths, and compilation formats. This doc
+     defines the generic schema that manifests implement.
+
+  2. claude_code_configuration.yml: the Claude engine's implementation of
+     the contracts defined here. Handles settings.json format, skill paths,
+     hook configuration, and scope routing specific to Claude Code.
+
+  3. security.yml: asset content validation (ANSI stripping, no secrets,
+     array-form hooks). Skills and hooks are attack surfaces requiring
+     audit for jailbreak, shell expansion, and privilege escalation.
+
+  4. compiler.yml: asset compilation follows the same pipeline as behaviour
+     and configuration compilation. Assets are a new compilation target type.
+
+  5. error_handling.yml: unsupported assets and validation failures use the
+     structured error hierarchy (exit codes, what/why/fix format).
+
+  6. backward_compatibility.yml: the asset schema and manifest contract are
+     public API surfaces. Changes to supported asset types are breaking.
+#
+preferences:
+  language: ruby
+  patterns:
+    - canonical_model_identifiers
+    - engine_manifest_capability_mapping
+    - engine_manifest_asset_contract
+    - advisory_not_enforcement
+    - env_var_secret_references
+    - compile_time_validation
+    - asset_content_security_audit
+  testing: rspec with multi-engine compilation fixtures, capability gap tests,
+    and asset compilation round-trip tests
+  gems:
+    - json_schemer
+    - thor