rosett-ai 1.3.3

data/conf/design/structured_logging.yml

@@ -0,0 +1,148 @@
+---
+name: structured_logging
+domain: operations
+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
+  - security
+  - error_handling
+  - monitoring_observability
+#
+intent: |
+  Enhance the existing rosett-ai logger with correlation IDs and structured JSON
+  output for cross-command tracing and debugging. When a user reports a problem,
+  the support workflow requires correlating log entries from a single CLI
+  invocation — which is impossible with unstructured text logs that lack a
+  shared identifier. This design adds a per-invocation correlation ID (UUID v4)
+  to every log entry, enables JSON-formatted output for machine parsing, and
+  provides configurable log levels that align with the telemetry system.
+
+  Structured logging complements telemetry (monitoring_observability.yml):
+  telemetry captures high-level command events (start, end, duration) for
+  operational metrics, while structured logging captures detailed diagnostic
+  messages (debug, info, warn, error) for troubleshooting. Both share the
+  correlation ID so that telemetry events and log entries from the same
+  invocation can be joined. Error handling (error_handling.yml) governs
+  user-facing error display; structured logging governs developer-facing
+  diagnostic output.
+#
+constraints:
+  - "Each CLI invocation generates a unique correlation ID (UUID v4) at startup"
+  - "The correlation ID is included in every log entry and every telemetry event"
+  - "Log format is controlled via RAI_LOG_FORMAT={text,json} (default text)"
+  - "JSON log format produces one JSON object per line (JSON Lines compatible)"
+  - "Text log format produces human-readable output: [LEVEL] [correlation_id] message"
+  - "Log level is controlled via RAI_LOG_LEVEL={DEBUG,INFO,WARN,ERROR}
+    (default WARN)"
+  - "Log output goes to stderr — never stdout (stdout is for command output)"
+  - "Structured logger must be a drop-in replacement for the existing
+    Ruby Logger interface (respond_to debug, info, warn, error, fatal)"
+  - "No new runtime dependencies — uses stdlib Logger, JSON, SecureRandom"
+  - "Log entries must never contain secrets, API keys, or file contents
+    (same constraint as telemetry)"
+  - "Correlation ID is accessible via RosettAi::StructuredLogger.correlation_id
+    for passing to telemetry and error handlers"
+  - "Logger must be thread-safe (Mutex-protected writes)"
+  - "This design governs diagnostic logging (developer-facing debug output).
+    Runtime telemetry is governed by monitoring_observability.yml. User-facing
+    error display is governed by error_handling.yml"
+#
+acceptance_criteria:
+  - "RosettAi::StructuredLogger class exists and implements Ruby Logger interface"
+  - "Every log entry includes a correlation_id field (UUID v4)"
+  - "RAI_LOG_FORMAT=json produces JSON Lines output on stderr"
+  - "RAI_LOG_FORMAT=text produces [LEVEL] [correlation_id] message on stderr"
+  - "RAI_LOG_LEVEL filters entries below the configured severity"
+  - "Correlation ID is generated once per CLI invocation and reused for all
+    log entries"
+  - "RosettAi::StructuredLogger.correlation_id returns the current correlation ID"
+  - "Telemetry events include the same correlation_id as log entries"
+  - "Structured logger is wired as the default logger in RosettAi module"
+  - "Log entries include timestamp (ISO 8601), level, correlation_id, message"
+  - "JSON log entries additionally include pid, command (when available)"
+  - "No secrets or file contents appear in log output"
+  - "Logger is thread-safe under concurrent writes"
+#
+examples:
+  - scenario: "Developer debugs a compile failure with JSON logs"
+    expected: |
+      RAI_LOG_LEVEL=DEBUG RAI_LOG_FORMAT=json bin/raictl compile
+      stderr output (one JSON object per line):
+      {"timestamp":"2026-03-16T10:00:00.123Z","level":"debug","correlation_id":"a1b2c3d4-...","pid":12345,"command":"compile","message":"Loading behaviour files from conf/behaviour/"}
+      {"timestamp":"2026-03-16T10:00:00.145Z","level":"debug","correlation_id":"a1b2c3d4-...","pid":12345,"command":"compile","message":"Validating 8 behaviour files"}
+      {"timestamp":"2026-03-16T10:00:00.189Z","level":"error","correlation_id":"a1b2c3d4-...","pid":12345,"command":"compile","message":"Validation failed: conf/behaviour/broken.yml:14 — missing required field 'rules'"}
+    not: |
+      Log entries lack correlation_id. JSON output goes to stdout and
+      corrupts piped command output. Debug messages appear at default log level.
+  - scenario: "User runs rosett-ai with default settings (no log env vars)"
+    expected: |
+      Only WARN and ERROR messages appear on stderr in text format.
+      No DEBUG or INFO noise. Correlation ID is still generated internally
+      but not visible unless log level is lowered.
+    not: |
+      DEBUG output floods stderr by default. No log output at all even
+      for warnings.
+  - scenario: "Support request includes correlation ID for cross-referencing"
+    expected: |
+      User provides correlation_id from error output. Developer searches
+      telemetry logs and structured logs using that ID to find all events
+      from the same CLI invocation.
+    not: |
+      Correlation ID is different between log entries and telemetry events
+      from the same invocation.
+  - scenario: "Multiple CLI invocations run in parallel (e.g., CI)"
+    expected: |
+      Each invocation has a unique correlation ID. Log entries from
+      different invocations can be separated by filtering on correlation_id.
+      Thread-safe writes prevent interleaved JSON objects.
+    not: |
+      Same correlation ID used across invocations. JSON objects are
+      interleaved mid-line due to race conditions.
+#
+anti_patterns:
+  - "Using puts or $stderr.puts instead of the structured logger"
+  - "Logging file contents or secrets (even at DEBUG level)"
+  - "Generating a new correlation ID per log entry instead of per invocation"
+  - "Sending logs to stdout (reserved for command output)"
+  - "Different correlation IDs for log entries and telemetry events"
+  - "Requiring an external logging gem (use stdlib Logger)"
+  - "Eagerly formatting log messages when the level is filtered out"
+  - "Making log format or level configurable via config files (env vars only)"
+#
+gui_notes: |
+  Document interactions (cross-references):
+
+  1. monitoring_observability.yml: telemetry events include the same
+     correlation_id as log entries for cross-referencing.
+
+  2. error_handling.yml: error handler can include correlation_id in
+     user-facing error output for support reference.
+
+  3. security.yml: log entries must never contain secrets, API keys, or PII.
+
+  4. architecture.yml: structured logger replaces the simple logger in
+     RosettAi module as a drop-in compatible upgrade.
+
+  Module structure:
+
+  lib/rosett_ai/structured_logger.rb  — Logger subclass with correlation ID,
+                                    JSON/text formatters, level filtering
+#
+preferences:
+  language: ruby
+  patterns:
+    - "Ruby Logger interface compatibility"
+    - "Per-invocation correlation ID (UUID v4)"
+    - "JSON Lines structured output"
+    - "Mutex thread-safety for writes"
+    - "Lazy message formatting (block form)"
+  testing: rspec with correlation ID propagation, JSON output parsing,
+    level filtering, thread-safety under concurrent writes, and
+    telemetry integration
+  gems: []

data/conf/design/styles.yml

@@ -0,0 +1,123 @@
+---
+name: styles
+domain: styles
+version: 1.1.0
+status: implemented
+priority: 1
+author: hugo
+created_at: "2026-02-18"
+modified_at: "2026-03-17"
+modified_by: claude
+depends_on:
+  - security
+  - testing
+
+intent: |
+  Codify all code conventions, linting rules, YAML formatting, documentation
+  structure, and commit message standards into a single authoritative design
+  document. Style enforcement eliminates bikeshedding, ensures consistency
+  across human and AI contributors, and makes code review focus on logic
+  rather than formatting. This depends on testing because the enforcement
+  tools (rubocop, yamllint, reek, mdl, overcommit) must be present and
+  configured before style gates can be enforced. Style rules are enforced
+  automatically via pre-commit hooks (overcommit) and CI pipeline — they
+  are not optional guidelines.
+
+constraints:
+  - All Ruby code must pass RuboCop with zero violations (no rubocop:disable without justification)
+  - All YAML files must pass yamllint with the project .yamllint configuration
+  - All Ruby code must pass Reek with zero violations above configured thresholds
+  - All JSON files must be syntactically valid (validated by overcommit JsonSyntax hook)
+  - All Markdown documentation must pass mdl (markdownlint) with project rules
+  - "Commit messages must follow Conventional Commits format: type(scope): description"
+  - Frozen string literal comment is required on every Ruby file
+  - Single quotes for strings unless interpolation is needed
+  - 2-space indentation for Ruby, YAML, and JSON — no tabs except Makefiles
+  - Maximum line length is 120 characters for Ruby, 240 for YAML (warning)
+  - RSpec examples follow behaviour-driven descriptions (what it does, not how)
+  - No trailing whitespace (except Markdown where it may be intentional)
+  - Structural duplication detected by Flay must stay below threshold (mass >= 16)
+  - Cyclomatic complexity enforced by RuboCop Metrics cops (AbcSize <= 25, CyclomaticComplexity <= 10, PerceivedComplexity <= 10)
+
+acceptance_criteria:
+  - .rubocop.yml exists with all project conventions and zero violations on main
+  - .yamllint exists with project YAML formatting rules
+  - .reek.yml exists with code smell detection thresholds
+  - .overcommit.yml enforces rubocop, yamllint, reek, json, bundler-audit, and trailing whitespace on pre-commit
+  - Commit message format is enforced by overcommit CommitMsg hooks (Conventional Commits pattern)
+  - mdl (markdownlint) is configured and enforced for all .md files in doc/
+  - bundle exec rubocop exits zero on the entire codebase
+  - bundle exec reek exits zero on the entire codebase
+  - yamllint exits zero on all YAML files outside vendor/ and tmp/
+  - Flay is configured with mass threshold 16 and enforced via overcommit pre-commit hook; cyclomatic complexity enforced by RuboCop Metrics cops (AbcSize <= 25, CyclomaticComplexity <= 10, PerceivedComplexity <= 10)
+
+examples:
+  - scenario: "AI generates a new Ruby class with double-quoted strings"
+    expected: |
+      Pre-commit hook catches the violation: RuboCop Style/StringLiterals
+      flags double quotes. Developer (or AI) fixes to single quotes. Commit
+      proceeds after fix.
+    not: "Code merges with inconsistent quoting style."
+  - scenario: "Developer writes a commit message 'fixed the bug'"
+    expected: |
+      Overcommit CommitMsg hook rejects: 'Commit message must follow
+      Conventional Commits format: <type>(<scope>): <description>'.
+      Developer rewrites as 'fix(compiler): handle nil input in validate method'.
+    not: "Freeform commit messages merge without convention."
+  - scenario: "New YAML configuration file uses 4-space indentation"
+    expected: |
+      yamllint flags indentation violation. Pre-commit hook blocks commit.
+      Developer fixes to 2-space indentation per project convention.
+    not: "Mixed indentation styles across YAML files."
+  - scenario: "New method has cyclomatic complexity of 15"
+    expected: |
+      RuboCop Metrics/CyclomaticComplexity flags the method above threshold
+      (max 10). Reek flags complexity smells. Developer refactors into smaller
+      methods. If threshold exception is truly justified, it is added to
+      .reek.yml or .rubocop.yml with a comment explaining why.
+    not: "Complex code merges without review. Thresholds silently increased."
+  - scenario: "Documentation in doc/ uses inconsistent heading styles"
+    expected: |
+      mdl flags heading style violation (e.g., mixed ATX and setext headings).
+      CI lint stage blocks merge. Author fixes to consistent ATX style (# headings).
+    not: "Documentation has mixed formatting that degrades readability."
+
+anti_patterns:
+  - Disabling linting rules inline without a justification comment
+  - Blanket rubocop:disable at file level instead of fixing the issue
+  - Excluding entire directories from style checks without justification
+  - Treating style warnings as non-blocking (all style violations block in this project)
+  - Inconsistent configuration between local hooks and CI (they must match)
+  - Skipping pre-commit hooks with --no-verify
+  - Adding Reek exclusions without first attempting to refactor the code smell
+  - Commit messages that bypass Conventional Commits format
+
+preferences:
+  language: ruby
+  gems:
+    - rubocop
+    - rubocop-performance
+    - rubocop-rspec
+    - rubocop-rake
+    - reek
+    - flay
+    - overcommit
+  tools:
+    - yamllint
+    - mdl
+  patterns:
+    - convention_over_configuration
+    - automated_enforcement_over_manual_review
+    - zero_tolerance_for_style_violations
+  conventions:
+    string_literals: single_quotes
+    frozen_string_literal: always
+    indentation: 2_spaces
+    line_length_ruby: 120
+    line_length_yaml: 240
+    hash_syntax: ruby19
+    array_style: brackets
+    symbol_array_style: brackets
+    trailing_comma: no_comma
+    class_children: nested
+    commit_format: conventional_commits

data/conf/design/test_peer_review.yml

@@ -0,0 +1,89 @@
+---
+name: test_peer_review
+domain: testing
+version: 0.1.0
+status: implemented
+priority: 1
+author: hugo
+created_at: "2026-03-14"
+modified_at: "2026-03-15"
+modified_by: claude
+depends_on:
+  - testing
+  - security
+
+intent: |
+  Establish a structured, questionnaire-based peer review process for all
+  test suites across the Rosett-AI ecosystem (core + 11 engine plugins). This
+  addresses the fundamental trust problem: when AI generates both code and
+  tests, a human must independently verify that tests reflect actual
+  requirements, not just mirror implementation details.
+
+  The process produces a signed-off test registry where every spec file has
+  been reviewed, its intent documented, and its correctness confirmed by the
+  human maintainer. This creates an auditable trail of test quality that is
+  independent of the AI that wrote the tests.
+
+  The review follows a questionnaire format (similar to the Q1-Q5 design
+  review process) where each test file is examined through structured
+  questions that expose gaps, redundancy, incorrect assumptions, and
+  missing edge cases. The human reviewer signs off on each file, creating
+  a permanent record.
+
+constraints:
+  - Every spec file must be reviewed before v1.0.0 release
+  - Each review must be signed off by the human maintainer (hugo)
+  - The review questionnaire must be reproducible and version-controlled
+  - Reviews must cover intent, correctness, completeness, and independence
+  - AI cannot sign off on its own tests — only the human reviewer can
+  - Review findings that require code changes must be tracked as issues
+  - The review registry must be machine-readable (YAML) for automation
+  - Reviews are per-file, not per-example, to keep the process practical
+
+acceptance_criteria:
+  - A review questionnaire template exists with numbered questions (Q1-Qn)
+  - A review registry YAML file tracks status per spec file per repo
+  - Each registry entry includes reviewer, date, verdict, and notes
+  - The questionnaire covers at minimum these dimensions — intent clarity, assertion quality, edge case coverage, mock appropriateness, independence from implementation, mutation resilience, naming quality, fixture quality
+  - A CLI command or script can report review progress across all repos
+  - All 174 spec files (141 core + 33 engine) have been reviewed
+  - All critical findings have been resolved before sign-off
+  - The review process is documented in doc/TEST_PEER_REVIEW.md
+
+examples:
+  - scenario: "Reviewing spec/rosett_ai/compiler/behaviour_compiler_spec.rb"
+    expected: |
+      Reviewer reads the file, answers each questionnaire question,
+      records findings in the registry. If Q3 (edge cases) reveals
+      missing nil input handling, this is recorded as a finding with
+      severity. The file is not signed off until the finding is resolved.
+      Once all questions are answered satisfactorily, the reviewer signs
+      off with date and verdict.
+
+  - scenario: "Reviewing spec/rosett_ai_engine/acme/backend_spec.rb"
+    expected: |
+      Reviewer examines engine contract tests. Q5 (implementation
+      independence) reveals that a test checks internal hash structure
+      rather than observable behaviour. This is flagged as a finding.
+      After the test is rewritten to check only the public interface,
+      the reviewer re-examines and signs off.
+
+  - scenario: "Generating progress report"
+    expected: |
+      CLI command reads all registry files and outputs a summary table:
+      Total files: 174, Reviewed: 87, Signed off: 72, Pending fixes: 15,
+      Not started: 87. Per-repo breakdown shows completion percentage.
+
+anti_patterns:
+  - AI signing off on its own tests (only human reviewer can sign off)
+  - Reviewing tests without reading the implementation under test
+  - Batch sign-off without individual file assessment
+  - Skipping edge case review for seemingly simple specs
+  - Using test count as a proxy for test quality
+  - Approving tests that mirror implementation details
+
+preferences:
+  questionnaire_format: "Numbered Q1-Q10 with verdict per question (pass/concern/fail)"
+  registry_format: "One YAML file per repo in conf/review/, keyed by spec file path"
+  review_workflow: "AI summary → human Q&A → registry → fix → sign-off"
+  batch_order: "Foundation → compiler → security → CLI → modules → UI → utils → engines"

data/conf/design/testing.yml

@@ -0,0 +1,136 @@
+---
+name: testing
+domain: testing
+version: 0.3.0
+status: implemented
+priority: 1
+author: hugo
+created_at: "2026-02-18"
+modified_at: "2026-03-17"
+modified_by: claude
+depends_on:
+  - security
+
+intent: |
+  Establish a testing strategy that validates both code correctness AND test
+  quality, specifically addressing the circular trust problem of AI-generated
+  tests. When AI writes both code and tests, the test suite can be perfectly
+  consistent yet meaningless. Mutation testing (Mutant) acts as an independent
+  third-party validator that mechanically verifies tests catch real bugs,
+  regardless of who wrote them. This must be in place before feature development
+  begins so all future code is validated from day one.
+
+constraints:
+  - Mutation testing (mutant-rspec) must be integrated before feature development begins
+  - All AI-generated tests must pass the 11-point review checklist before acceptance
+  - Unit tests must use concrete expected values, never computed expectations that mirror implementation
+  - Mocking is only permitted at boundaries (file system, network, shell commands)
+  - The unit under test must never be mocked
+  - Every public method must have tests for happy path, edge cases (empty, nil, boundary), negative cases, and error cases
+  - Test descriptions must be behaviour-focused, not implementation-focused
+  - "SimpleCov minimum line coverage is 88% overall and 25% per file (target: 90% line, 80% per-file)"
+  - Mutation score must meet threshold before code can merge (70% initial, 85% established, 95% critical paths)
+  - CI must run rspec on every push and mutant on merge requests
+  - Property-based testing must be used for cryptographic/security-critical code (licensing validation)
+  - Snapshot testing must be used for compiled output regression — baseline snapshots stored in spec/fixtures/snapshots/
+  - Snapshot files must be committed to git and reviewed in merge requests (not auto-updated)
+  - Property-based testing uses Rantly gem for random input generation
+  - Rantly generators for domain objects are defined in spec/support/rantly_generators.rb
+
+acceptance_criteria:
+  - mutant-rspec is installed and configured with .mutant.yml
+  - SimpleCov is configured with minimum thresholds that block CI on violation
+  - RSpec runs on every CI push and produces JUnit XML report
+  - Mutant runs on every merge request for changed code and blocks merge if score drops
+  - spec/support/factories/ contains factory_bot factories for core domain objects
+  - spec/support/shared_examples/ contains interface contract tests for UI base
+  - spec/fixtures/ contains valid, invalid, malicious, and unicode test fixtures
+  - AI-generated test review checklist is documented and enforced in review process
+  - At least one property-based test exists for licensing key validation
+  - spec/fixtures/snapshots/ contains baseline compiled output for each engine backend
+  - Snapshot tests compare compiled output against committed baselines (exact match)
+  - spec/support/rantly_generators.rb contains Rantly generators for behaviour rules, design documents, and policy objects
+  - Property-based tests exist for composition edge cases (priority ordering, merge strategies)
+
+examples:
+  - scenario: "AI generates tests for RosettAi::Compiler::BehaviourCompiler"
+    expected: |
+      Tests use concrete values (eq(3), not input.select(&:enabled?).count).
+      Tests cover enabled rules included, disabled rules excluded, empty input,
+      nil input, and invalid rule format. Mutant score >= 85%.
+    not: |
+      Tests reimplement the code logic in expectations. Tests only cover
+      happy path. Mocks replace the compiler itself. Descriptions say
+      'calls select then map' instead of 'includes only enabled rules'.
+  - scenario: "Mutant reports a surviving mutation: select changed to reject"
+    expected: |
+      Developer (or AI) writes a new test that explicitly asserts disabled
+      rules are NOT in the output. Mutant is re-run to confirm the mutation
+      is now killed. New commit created (not amending).
+    not: |
+      Surviving mutation is ignored. Mutant threshold is lowered to accommodate.
+      Test is marked as pending.
+  - scenario: "AI generates tests and mutant score is 60%"
+    expected: |
+      Surviving mutations are fed back to AI with prompt: 'These mutations
+      survived, write tests to kill them: [list]'. AI generates targeted
+      tests. Mutant re-run. Repeat until >= 85%.
+    not: "Tests are accepted at 60%. Mutant is skipped."
+  - scenario: "New code adds a security-critical licensing validator"
+    expected: |
+      Unit tests with concrete values. Property-based tests with random
+      payloads verifying forged keys always rejected. Mutant score >= 95%.
+      Fixtures include valid, expired, forged, and tampered keys.
+  - scenario: "Compiled output changes unexpectedly after a refactor"
+    expected: |
+      Snapshot test compares compiled output against spec/fixtures/snapshots/
+      baseline. Test fails with a diff showing exactly what changed. Developer
+      reviews the diff and either fixes the regression or updates the snapshot.
+    not: |
+      Compiled output changes go undetected. Snapshots auto-update without
+      human review. No baseline exists for regression comparison.
+  - scenario: "Composition with random priority and scope combinations"
+    expected: |
+      Rantly generates 100 random behaviour rule sets with varying priorities,
+      scopes, and merge strategies. Property: output is always deterministic
+      (same input → same output). Property: security-domain rules are never
+      overridden by non-security rules.
+    not: |
+      Only hand-crafted examples are tested. Edge cases in priority ordering
+      are missed because the test space is too small.
+  - scenario: "Developer refactors compile method from select+map to filter_map"
+    expected: "All tests continue to pass because they test outcomes, not method calls"
+    not: "Tests break because they asserted select was called"
+
+anti_patterns:
+  - Tautological tests (expectation reimplements the code logic)
+  - Over-mocking (mocking the unit under test, mocking everything)
+  - Weak assertions (not_to be_nil, to be_a(Array) without content checks)
+  - Happy path only (no edge cases, no error paths, no boundary values)
+  - Implementation coupling (testing call sequences instead of outcomes)
+  - Missing negative tests (no assertions about what should NOT be in output)
+  - Computed expectations (expect(x).to eq(input.select(&:foo?).count))
+  - Lowering mutation score thresholds to accommodate weak tests
+  - Skipping mutant on merge requests to save time
+  - Accepting AI-generated tests without review checklist verification
+  - Auto-updating snapshot baselines without human review
+  - Using only hand-crafted examples when property-based testing would catch more edge cases
+  - Defining Rantly generators outside spec/support/ (scattered generator definitions)
+
+preferences:
+  language: ruby
+  testing: rspec with factory_bot and mutant-rspec
+  gems:
+    - rspec
+    - factory_bot
+    - mutant-rspec
+    - simplecov
+    - rspec-junit-formatter
+    - rantly
+  patterns:
+    - behaviour_driven_test_descriptions
+    - concrete_value_assertions
+    - boundary_only_mocking
+    - context_blocks_for_scenarios
+    - shared_examples_for_interfaces
+    - named_subjects_and_let_blocks

data/conf/design/threat_model.yml

@@ -0,0 +1,108 @@
+---
+name: threat_model
+domain: security
+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
+  - engine_architecture
+  - content_packs
+  - licensing_system
+#
+intent: |
+  Define the adversary model, trust boundaries, and threat scenarios for Rosett-AI.
+  Security.yml establishes coding rules; this document maps the attack surface —
+  who might attack, what they target, and which mitigations apply. Without a
+  threat model, security constraints are disconnected from real-world risks.
+  This document ensures every security decision traces back to a concrete threat.
+#
+constraints:
+  - Trust boundaries must be defined for every external input channel (CLI args, YAML files, content packs, engine gems, environment variables, D-Bus messages)
+  - Each identified threat must map to at least one mitigation in security.yml or this document
+  - Content packs from untrusted sources must be treated as hostile input (sandboxed parsing, no code execution)
+  - Engine gems are trusted only if installed via system package manager or bundler with locked checksums
+  - YAML files from external sources must pass schema validation before any processing
+  - D-Bus messages must be validated against expected method signatures before dispatch
+  - Supply chain attacks on dependencies must be mitigated by lockfile pinning and bundler-audit
+  - The threat model must be reviewed whenever a new input channel or external integration is added
+  - File path traversal attacks must be prevented by canonicalisation and whitelist checks
+  - No design document may introduce a new trust boundary without updating this threat model
+#
+acceptance_criteria:
+  - Trust boundary diagram exists (ASCII art or structured YAML) covering all input channels
+  - Each trust boundary has documented validation rules
+  - Content pack installation validates integrity (checksum verification) before extraction
+  - Engine gem loading validates gemspec metadata against expected patterns
+  - D-Bus method handlers reject messages with unexpected argument types or counts
+  - bin/raictl compile rejects YAML files containing path traversal sequences (../, symlinks to outside whitelist)
+  - bundler-audit and gitleaks run in CI and block merge on any finding
+  - Supply chain risk assessment exists for each runtime dependency (Gemfile.lock pinned)
+  - RSpec tests exist for each trust boundary validation (at least one positive and one negative test)
+  - Threat model review checklist is referenced in the design document template
+#
+examples:
+  - scenario: "User installs a content pack from an untrusted community repository"
+    expected: |
+      Content pack is downloaded to a temporary directory. Checksum is verified
+      against manifest. YAML files are validated against schemas. No Ruby code
+      in content packs is executed. Pack is installed only after all checks pass.
+    not: |
+      Content pack is extracted directly into ~/.config/rosett-ai/. Ruby files in
+      the pack are loaded via require. No checksum verification.
+  - scenario: "A malicious YAML behaviour file contains a path traversal in a rule's output path"
+    expected: |
+      Path is canonicalised with File.expand_path. Resulting path is checked
+      against whitelist (~/. claude/rules/, project .claude/). Traversal
+      detected: "Validation failed: output path escapes allowed directory."
+    not: |
+      Path traversal succeeds. File is written to /etc/cron.d/ or ~/.ssh/.
+  - scenario: "A compromised RubyGem is pushed as a dependency update"
+    expected: |
+      bundler-audit detects known CVE in CI. Merge is blocked. Developer
+      reviews advisory and pins to safe version in Gemfile.lock.
+    not: |
+      Compromised gem is installed. Malicious code executes at require time.
+  - scenario: "A D-Bus client sends an unexpected method call to be.neatnerds.rosettai"
+    expected: |
+      Method signature is validated. Unknown methods return D-Bus error
+      org.freedesktop.DBus.Error.UnknownMethod. Arguments are type-checked.
+    not: |
+      Arbitrary method calls are dispatched to internal handlers.
+  - scenario: "An engine gem's gemspec declares a dependency on a gem that executes native code"
+    expected: |
+      Engine loader checks gemspec dependencies against an allowlist.
+      Unknown native extensions trigger a warning. User must explicitly
+      approve gems with native extensions.
+    not: |
+      Native extension compiles and executes arbitrary C code without notice.
+#
+anti_patterns:
+  - Trusting input from any external channel without validation
+  - Assuming content packs are safe because they are YAML (YAML deserialization attacks)
+  - Loading engine gems via require without validating source or integrity
+  - Processing D-Bus messages without type-checking arguments
+  - Relying solely on file permissions for security (defence in depth needed)
+  - Hardcoding trust assumptions instead of documenting them in the threat model
+  - Treating all RubyGems as equally trusted regardless of source
+  - Skipping threat model review when adding new external integrations
+  - Using string comparison for paths instead of canonicalised path comparison
+#
+preferences:
+  language: ruby
+  patterns:
+    - defence_in_depth
+    - trust_boundary_validation
+    - input_sanitisation_at_boundaries
+    - least_privilege
+    - fail_secure
+  testing: rspec with adversarial input fixtures
+  gems:
+    - bundler-audit
+    - gitleaks
+    - json_schemer