rosett-ai 1.3.3

data/doc/issues/002-embedded-ruby-wrong-prefix.md

@@ -0,0 +1,217 @@
+# Issue 002: Embedded Ruby compiled with wrong --prefix
+
+| Field       | Value                                           |
+|-------------|-------------------------------------------------|
+| Severity    | **High** (makes Issue 001 workarounds necessary) |
+| Status      | **Resolved**                                    |
+| Component   | CI pipeline, `lib/rosett_ai/thor/tasks/build.rb`     |
+| Affects     | CI builds; local builds have a variant of this   |
+| Found in    | v1.0.0 (`nncc_1.0.0-1_amd64.deb`)              |
+| Resolved in | v1.1.0                                          |
+
+## Resolution
+
+Resolved via the wrapper template fix (see Issue 001). `ruby-build` does not
+support separating `--prefix` from the install destination, so overriding
+`--prefix` via `RUBY_CONFIGURE_OPTS` causes `make install` to write to the
+system path (Permission denied). Instead:
+
+1. Ruby is compiled into the staging path (ruby-build's default behavior).
+2. The runtime wrapper (`packaging/wrapper.sh.template`) sets `LD_LIBRARY_PATH`,
+   `RUBYLIB`, and `GEM_HOME` to the correct `/opt/rosett-ai/embedded/` paths,
+   overriding the compiled-in prefix at runtime.
+3. Ruby's `rbconfig.rb` has a `TOPDIR` self-healing mechanism that computes the
+   real prefix from `File.dirname(__FILE__)` once `RUBYLIB` is set.
+4. CI pipeline no longer pre-seeds from the Docker image's `/usr/local/` Ruby.
+
+## Summary
+
+The embedded Ruby binary at `/opt/rosett-ai/embedded/bin/ruby` was compiled with
+`--prefix=/usr/local` instead of `--prefix=/opt/rosett-ai/embedded`. This causes
+the binary's ELF `RUNPATH` and default `$LOAD_PATH` to reference
+`/usr/local/lib/...` paths that do not exist on the target system.
+
+## Root Cause
+
+### CI builds: Docker image pre-seeding
+
+The CI pipeline (`.gitlab-ci-files/build/package.yml`, lines 28-33)
+pre-populates the staging directory with the Docker image's Ruby to skip the
+13-minute `ruby-build` compilation:
+
+```yaml
+- mkdir -p tmp/staging/opt/rosett-ai/embedded
+- |
+  if ! tmp/staging/opt/rosett-ai/embedded/bin/ruby --version 2>/dev/null; then
+    echo "Seeding embedded Ruby from Docker image..."
+    rsync -a /usr/local/ tmp/staging/opt/rosett-ai/embedded/
+  fi
+```
+
+The Docker image (`ruby:3.3.10-bookworm`) installs Ruby at `/usr/local/` with
+`--prefix=/usr/local`. Copying these files to `tmp/staging/opt/rosett-ai/embedded/`
+does **not** change the compiled-in prefix. The binary retains:
+
+- **ELF RUNPATH**: `/usr/local/lib` (where it searches for `libruby.so.3.3`)
+- **Default `$LOAD_PATH`**: `/usr/local/lib/ruby/3.3.0`, etc.
+
+The `compile_ruby!` method's `ruby_already_compiled?` check (build.rb:327-333)
+only verifies `RUBY_VERSION` matches — it does not check the compiled prefix:
+
+```ruby
+def ruby_already_compiled?
+  ruby_bin = staging_embedded.join('bin', 'ruby')
+  return false unless ruby_bin.exist?
+
+  installed = IO.popen([ruby_bin.to_s, '-e', 'puts RUBY_VERSION'], &:read).strip
+  installed == ruby_version.sub(/\A(\d+\.\d+\.\d+).*/, '\1')
+end
+```
+
+### Local builds: staging absolute path as prefix
+
+When `ruby-build` is invoked locally (build.rb:306-307):
+
+```ruby
+run_clean_command('ruby-build', ruby_version, staging_embedded.to_s)
+```
+
+`staging_embedded` resolves to an absolute path like:
+
+```text
+/home/user/git/Neatnerds/NNCO/rosett-ai/tmp/staging/opt/rosett-ai/embedded
+```
+
+`ruby-build` passes this as `--prefix` to Ruby's `./configure`. The resulting
+binary has the full staging path compiled in, which won't exist on the target
+system after `dpkg -i` installs the files to `/opt/rosett-ai/embedded/`.
+
+## Evidence
+
+```text
+$ readelf -d /opt/rosett-ai/embedded/bin/ruby | grep RUNPATH
+  0x000000000000001d (RUNPATH)  Library runpath: [/usr/local/lib]
+
+$ strings /opt/rosett-ai/embedded/bin/ruby | grep '/usr/local'
+/usr/local/lib
+
+$ LD_LIBRARY_PATH=/opt/rosett-ai/embedded/lib \
+  /opt/rosett-ai/embedded/bin/ruby -e 'puts $LOAD_PATH'
+/usr/local/lib/ruby/site_ruby/3.3.0
+/usr/local/lib/ruby/site_ruby/3.3.0/x86_64-linux
+/usr/local/lib/ruby/site_ruby
+/usr/local/lib/ruby/vendor_ruby/3.3.0
+/usr/local/lib/ruby/vendor_ruby/3.3.0/x86_64-linux
+/usr/local/lib/ruby/vendor_ruby
+/usr/local/lib/ruby/3.3.0
+/usr/local/lib/ruby/3.3.0/x86_64-linux
+```
+
+Note: `rbconfig.rb` has a self-healing `TOPDIR` mechanism based on
+`File.dirname(__FILE__)`, so `RbConfig::CONFIG["prefix"]` reports
+`/opt/rosett-ai/embedded` when loaded via `RUBYLIB`. But the binary itself cannot
+load `rbconfig.rb` because the default `$LOAD_PATH` points elsewhere.
+
+## Proposed Solutions
+
+### Option A: Compile Ruby with correct prefix in CI (recommended)
+
+Replace the Docker pre-seeding with a dedicated compilation step that uses the
+correct prefix. To preserve the CI speed optimization, compile Ruby once in a
+separate CI job and cache the result.
+
+**CI pipeline change:**
+
+```yaml
+before_script:
+  - !reference [.ruby_base, before_script]
+  - apt-get install -y -qq fakeroot dpkg-dev rsync
+  - bundle exec fpm --version
+  # Compile Ruby with correct prefix if not cached
+  - mkdir -p tmp/staging/opt/rosett-ai/embedded
+  - |
+    RUBY_BIN=tmp/staging/opt/rosett-ai/embedded/bin/ruby
+    if [ -x "$RUBY_BIN" ] && \
+       "$RUBY_BIN" -e "exit(RbConfig::CONFIG['prefix'] == '/opt/rosett-ai/embedded' ? 0 : 1)" 2>/dev/null; then
+      echo "Cached Ruby has correct prefix — skipping compilation"
+    else
+      echo "Compiling Ruby with --prefix=/opt/rosett-ai/embedded..."
+      RUBY_CONFIGURE_OPTS="--prefix=/opt/rosett-ai/embedded" \
+        ruby-build 3.3.10 tmp/staging/opt/rosett-ai/embedded
+    fi
+```
+
+**Build.rb change** — update `ruby_already_compiled?` to verify prefix:
+
+```ruby
+def ruby_already_compiled?
+  ruby_bin = staging_embedded.join('bin', 'ruby')
+  return false unless ruby_bin.exist?
+
+  output = IO.popen(
+    [ruby_bin.to_s, '-e', 'puts RUBY_VERSION; puts RbConfig::CONFIG["prefix"]'],
+    &:read
+  ).strip
+  version, prefix = output.split("\n", 2)
+  version == ruby_version.sub(/\A(\d+\.\d+\.\d+).*/, '\1') &&
+    prefix == INSTALL_DIR + '/embedded'
+rescue StandardError
+  false
+end
+```
+
+### Option B: Fix prefix post-build with patchelf
+
+After pre-seeding from Docker, use `patchelf` to update the `RUNPATH` and
+rely on `RUBYLIB` in the wrapper for load path correction:
+
+```yaml
+- rsync -a /usr/local/ tmp/staging/opt/rosett-ai/embedded/
+- patchelf --set-rpath /opt/rosett-ai/embedded/lib tmp/staging/opt/rosett-ai/embedded/bin/ruby
+```
+
+This is faster than recompiling but only fixes `RUNPATH`. The `$LOAD_PATH`
+would still need `RUBYLIB` override in the wrapper (Issue 001 fix).
+
+### Option C: Use `RUBY_CONFIGURE_OPTS` for local builds
+
+For local builds, override the prefix passed to `ruby-build`:
+
+```ruby
+def compile_ruby!
+  # ... existing checks ...
+  env = clean_env.merge(
+    'RUBY_CONFIGURE_OPTS' => "--prefix=#{INSTALL_DIR}/embedded"
+  )
+  success = system(env, 'ruby-build', ruby_version, staging_embedded.to_s)
+  # ...
+end
+```
+
+`ruby-build` supports `RUBY_CONFIGURE_OPTS` to pass additional flags to
+Ruby's `./configure`. Setting `--prefix=/opt/rosett-ai/embedded` ensures the
+compiled binary has the correct install path, even though it's initially
+built into the staging directory.
+
+## Recommendation
+
+Implement **Option A + C** together:
+
+1. CI compiles Ruby with `--prefix=/opt/rosett-ai/embedded` (via `RUBY_CONFIGURE_OPTS`)
+2. Local builds also set `RUBY_CONFIGURE_OPTS` in `compile_ruby!`
+3. `ruby_already_compiled?` validates both version AND prefix
+4. The wrapper script fix from Issue 001 provides defense-in-depth
+
+Even with the correct prefix, the wrapper should still set `LD_LIBRARY_PATH`
+and `RUBYLIB` as defense-in-depth — the system dynamic linker does not search
+`/opt/rosett-ai/embedded/lib/` by default, and there is no `ldconfig` entry for it.
+
+## Affected Files
+
+- `.gitlab-ci-files/build/package.yml` (CI pre-seeding logic)
+- `lib/rosett_ai/thor/tasks/build.rb` (`compile_ruby!`, `ruby_already_compiled?`)
+
+## Related Issues
+
+- [001 - Wrapper script missing environment variables](001-wrapper-missing-environment-variables.md)
+- [003 - Smoke test installs system Ruby masking failures](003-smoke-test-false-positive.md)

data/doc/issues/003-smoke-test-false-positive.md

@@ -0,0 +1,127 @@
+# Issue 003: Smoke test may produce false positives
+
+| Field       | Value                                            |
+|-------------|--------------------------------------------------|
+| Severity    | **Medium** (test reliability)                    |
+| Status      | **Resolved**                                     |
+| Component   | `.gitlab-ci-files/build/package.yml`             |
+| Affects     | CI pipeline                                      |
+| Found in    | v1.0.0                                           |
+| Resolved in | v1.1.0                                           |
+
+## Resolution
+
+Removed `apt-get install ... ruby` from the smoke test. The test now installs only
+the built `.deb` and its declared APT dependencies. Added assertions to verify:
+
+- CLI commands (`raictl version`, `rai validate`, `rai engines list`) work
+- Embedded Ruby reports correct compiled prefix (`/opt/rosett-ai/embedded`)
+- ELF RUNPATH points to `/opt/rosett-ai/embedded/lib`
+
+## Summary
+
+The CI smoke test job (`build:package:smoke_test`) installs a system Ruby via
+`apt-get` before installing the rosett-ai `.deb` package. This may mask the runtime
+failures described in Issues 001 and 002, creating a false sense that the
+package works correctly on a clean target system.
+
+## Current Smoke Test
+
+```yaml
+build:package:smoke_test:
+  stage: build
+  image: debian:bookworm
+  script:
+    - apt-get update && apt-get install -y --no-install-recommends ruby
+    - dpkg -i pkg/*.deb || apt-get install -fy --no-install-recommends
+    - rosett-ai version
+    - rai validate
+    - rai engines list
+```
+
+## Analysis
+
+### Why `apt-get install ruby` is problematic
+
+The `apt-get install ... ruby` line installs Debian bookworm's system Ruby
+(3.1.x), which pulls in `libruby3.1`. This does **not** provide
+`libruby.so.3.3` (needed by the embedded Ruby 3.3.10), so it would not
+directly fix Failure 1 from Issue 001.
+
+However, installing system Ruby may have indirect side effects:
+
+- It places Ruby-related libraries in system library paths that `ld.so` scans
+- It may trigger `ldconfig` runs that update the linker cache
+- On certain Debian configurations it could install packages that satisfy
+  transitive dependencies
+
+### The test should validate the package in isolation
+
+The smoke test's purpose is to verify that `dpkg -i rosett-ai.deb` produces a
+working installation on a clean Debian system. Installing extra packages
+before the test defeats this purpose — it cannot detect missing dependencies
+or environment setup issues.
+
+### Current test outcome
+
+Given the `RUNPATH` and `$LOAD_PATH` issues documented in Issues 001 and 002,
+this smoke test should fail with the same errors the user observed. If it
+passes in CI, it may be because:
+
+1. The CI cache retains state from previous runs
+2. The Docker environment has additional libraries in system paths
+3. The test has not actually run on a clean system recently
+
+## Proposed Fix
+
+Remove the system Ruby installation and test the package in isolation:
+
+```yaml
+build:package:smoke_test:
+  stage: build
+  image: debian:bookworm
+  tags:
+    - docker
+  needs:
+    - job: build:package:amd64
+      artifacts: true
+  script:
+    # Install the package and its declared dependencies only
+    - apt-get update
+    - dpkg -i pkg/*.deb || apt-get install -fy --no-install-recommends
+    # Verify the CLI works without any extra packages installed
+    - rosett-ai version
+    - rai validate
+    - rai engines list
+    # Verify the embedded Ruby reports correct prefix
+    - /opt/rosett-ai/embedded/bin/ruby -e 'puts RbConfig::CONFIG["prefix"]' | grep -q '/opt/rosett-ai/embedded'
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+      when: on_success
+    - if: $CI_COMMIT_TAG
+      when: on_success
+```
+
+### Additional verification steps
+
+Consider adding these assertions to catch regressions:
+
+```bash
+# Verify libruby.so is found without manual LD_LIBRARY_PATH
+ldd /opt/rosett-ai/embedded/bin/ruby | grep -q 'libruby.so.3.3 => /opt/rosett-ai'
+
+# Verify RubyGems loads
+/opt/rosett-ai/bin/raictl version 2>&1 | grep -v 'were not loaded'
+
+# Verify no stale prefix in RUNPATH
+readelf -d /opt/rosett-ai/embedded/bin/ruby | grep RUNPATH | grep -q '/opt/rosett-ai/embedded/lib'
+```
+
+## Affected Files
+
+- `.gitlab-ci-files/build/package.yml` (smoke test job definition)
+
+## Related Issues
+
+- [001 - Wrapper script missing environment variables](001-wrapper-missing-environment-variables.md)
+- [002 - Embedded Ruby compiled with wrong prefix](002-embedded-ruby-wrong-prefix.md)

data/doc/issues/004-market-research-design-updates.md

@@ -0,0 +1,109 @@
+# ISSUE-004: Update Design Documents with Market Research Findings
+
+## Status
+
+Open (2026-03-22)
+
+## Context
+
+Market research conducted during NLnet grant preparation (see
+`doc/context/ai-engine-usage-trends-2026.md`) revealed industry data that validates
+rosett-ai's architecture and identifies areas where design documents should be updated to
+reflect the current landscape.
+
+## Research Summary
+
+- 59% of developers use 3+ AI tools; 20% use 5+
+- Engine switching is constant (Claude Code: 0 to #1 in 8 months)
+- Configuration portability between engines does not exist
+- Vendor lock-in in AI coding tools is now recognized as strategic risk
+- AGENTS.md standardization effort emerged (OpenAI, Google, Cursor, Factory)
+- Multi-agent coordination is a 2026 trend (Gartner: 1,445% inquiry surge)
+- Developer confidence declines with tool count (28% at 6+ tools)
+
+## Required Actions
+
+### 1. Update ADR-006 and ADR-007
+
+**Priority**: Medium
+**Files**: `doc/decisions/006-multi-engine-architecture.md`,
+`doc/decisions/007-engine-agnostic-pivot.md`
+
+Add a "Market Validation" section to both ADRs referencing the research data. The
+architectural decisions made in Feb 2026 are now backed by industry statistics. Key
+points to add:
+
+- The engine table in ADR-006 should be updated with current config locations (verify
+  Cursor uses `.cursor/rules/` not just `.cursor/`, verify Windsurf path)
+- ADR-007's "why engine-agnostic" rationale should cite the 59% multi-tool statistic
+  and the Claude Code migration velocity
+- Reference `doc/context/ai-engine-usage-trends-2026.md` as evidence
+
+### 2. AGENTS.md Positioning Document
+
+**Priority**: Medium
+**File**: `doc/AAIF_POSITIONING.md`
+
+Update with current AGENTS.md adoption data:
+
+- Which vendors have adopted AGENTS.md (OpenAI, Google, Cursor, Factory confirmed)
+- Which have not (Claude Code, Copilot, Windsurf, Ollama — verify current status)
+- rosett-ai's position: support AGENTS.md as ONE target among many, not as the only standard
+- Differentiation: rai compiles to engines that will never adopt AGENTS.md
+
+### 3. Quorum Proofing Design Document
+
+**Priority**: High (planned feature, grant-funded)
+**File**: New — `doc/decisions/012-quorum-proofing.md` (or appropriate next number)
+
+Create a new ADR for quorum proofing based on the multi-agent trend data:
+
+- Problem: how to cross-validate AI outputs across engines
+- Approach: parallel prompt execution, consensus detection
+- Budget implication: requires paid subscriptions to multiple engines
+- Reference Gartner multi-agent inquiry surge as market validation
+- Reference GitHub Agent HQ and xAI Grok Build as comparable approaches
+- Define what "agreement" means (exact match? semantic similarity? human review?)
+
+### 4. Deep Research Tasks
+
+**Priority**: Low (post-grant-submission)
+
+Conduct deeper research on:
+
+a. **Engine config format evolution**: Are any engines converging on shared formats?
+   Track quarterly. If Cursor adopts AGENTS.md, document impact on rosett-ai's engine count.
+
+b. **Developer governance pain points**: Survey or interview developers about their
+   actual workflow when switching engines. What do they lose? What do they wish they
+   could keep? This informs rosett-ai's feature priority.
+
+c. **Enterprise AI governance**: How do organizations with 50+ developers manage AI
+   tool governance today? Manual policy documents? Per-engine configs? Nothing?
+   This informs the enterprise content pack strategy.
+
+d. **Regulatory requirements for AI provenance**: Track EU AI Act implementation
+   details, especially re: disclosure requirements for AI-generated code in
+   regulated industries (finance, healthcare, government).
+
+e. **Authorship attribution standards**: Research existing standards for attributing
+   sources in AI-generated output. Are there emerging conventions? Academic work?
+   Legal precedent?
+
+### 5. Update ENGINE_DEVELOPMENT_GUIDE.md
+
+**Priority**: Low
+
+Add a section on market context for new engine contributors:
+
+- Why engine diversity matters (59% multi-tool, constant migration)
+- How to identify config format for a new engine target
+- How to verify compilation output against the engine's actual behaviour
+
+## References
+
+- `doc/context/ai-engine-usage-trends-2026.md` — full research data with sources
+- `doc/decisions/006-multi-engine-architecture.md` — original multi-engine ADR
+- `doc/decisions/007-engine-agnostic-pivot.md` — engine-agnostic architecture
+- `doc/AAIF_POSITIONING.md` — AGENTS.md positioning
+- `applications/nlnet-2026-q1/research/ai-engine-usage-trends.md` — grant repo copy

data/doc/issues/005-compile-scope-coexistence.md

@@ -0,0 +1,161 @@
+# Issue 005: Compile Cannot Merge Project-Level and Global Behaviours
+
+| Field       | Value                                                        |
+|-------------|--------------------------------------------------------------|
+| Severity    | **High**                                                     |
+| Status      | **Open**                                                     |
+| Component   | `lib/rosett_ai/thor/tasks/compile.rb`, `lib/rosett_ai/project_context.rb` |
+| Affects     | Any workspace with `.rosett-ai/conf/behaviour/` alongside global behaviours |
+| Found in    | v3.3.0 (packaged .deb, post WP#711/WP#712 fixes)            |
+| Resolved in | —                                                            |
+
+## Summary
+
+When `rai compile` is run from a directory that has an `.rosett-ai/conf/behaviour/`
+project structure (created by `rai init --project`), the compile discovers
+**only** the project-level behaviours. All previously compiled global behaviours
+are removed as "orphans". The reverse is also true: compiling from a non-project
+directory restores globals but removes any project-level rules.
+
+This means project-level and global behaviours are **mutually exclusive** after
+any single compile run. Users cannot extend the global rule set with
+project-specific behaviours.
+
+## Distinction from WP#711 / WP#712
+
+WP#711 fixed `ProjectContext#nncc_internal?` so the rosett-ai source tree is
+correctly identified. WP#712 added an `empty?` guard to `remove_orphans`.
+Both are merged (2026-03-27). This issue is **not** a regression of those
+fixes — it occurs in the normal case of a non-rai project directory with
+`.rosett-ai/` initialised via `rai init --project`.
+
+## Symptoms
+
+### Reproduction steps
+
+```bash
+# 1. Start with global behaviours compiled
+cd /mnt/claude-scratch && rai compile --verbose
+# Output: Unchanged: behaviour-criticalthinking.md, behaviour-operational_discipline.md,
+#         behaviour-session_retrospective.md
+# Result: 3 rules in ~/.claude/rules/
+
+# 2. Initialise a project with its own behaviour
+cd ~/git
+rai init --project --no-compile
+# Creates .rosett-ai/conf/behaviour/ (empty)
+
+# Place a behaviour file:
+cp documentation_first.yml .rosett-ai/conf/behaviour/
+
+# 3. Compile from the project directory
+rai compile --verbose
+```
+
+### Actual output
+
+```text
+Discovered categories:
+  behaviour
+  design
+
+  Created: behaviour-documentation_first.md (5f05146f)
+  Removed orphan: behaviour-criticalthinking.md
+  Removed orphan: behaviour-operational_discipline.md
+  Removed orphan: behaviour-session_retrospective.md
+
+╭─────────────────╮
+│ Compile Summary │
+├─────────┬───────┤
+│ Action  │ Count │
+╞═════════╪═══════╡
+│ Created │ 1     │
+╰─────────┴───────╯
+```
+
+### Expected output
+
+```text
+Discovered categories:
+  behaviour (global: 3, project: 1)
+  design (project scope only)
+
+  Unchanged: behaviour-criticalthinking.md (d966e8ae)
+  Unchanged: behaviour-operational_discipline.md (da9c39a9)
+  Unchanged: behaviour-session_retrospective.md (deaee56c)
+  Created:   behaviour-documentation_first.md (5f05146f)
+
+╭─────────────────╮
+│ Compile Summary │
+├─────────┬───────┤
+│ Action  │ Count │
+╞═════════╪═══════╡
+│ Unchanged │ 3   │
+│ Created   │ 1   │
+╰─────────┴───────╯
+```
+
+## Root Cause Analysis
+
+### Single-source discovery
+
+`ProjectContext#conf_root` (line ~44 of `lib/rosett_ai/project_context.rb`) returns a
+**single** path — either the global `/opt/rosett-ai/app/conf` or the project's
+`.rosett-ai/conf`. This single path is passed as `source_dir:` to
+`CompilationPipeline` via `build_compiler` (line ~116 of
+`lib/rosett_ai/thor/tasks/compile.rb`).
+
+`CompilationPipeline#compile` (line ~74 of
+`lib/rosett_ai/compiler/compilation_pipeline.rb`) reads **only** from `@source_dir`.
+There is no multi-source support.
+
+### Orphan removal sees only one scope
+
+`remove_orphans` in `compile.rb` (line ~276) computes orphans as:
+`managed_files - compiled_keys`. Since `compiled_keys` only contains
+project-level results, all global rules are classified as orphans and deleted.
+
+### Design exists but is not wired
+
+- `conf/design/scope_hierarchy.yml` (status: **draft**) defines a four-level
+  merge hierarchy: global → organisation → project → local
+- `RosettAi::Composition::ScopeResolver` exists at
+  `lib/rosett_ai/composition/scope_resolver.rb` and understands the hierarchy
+- Neither is connected to `CompilationPipeline` or `build_compiler`
+
+## Proposed Fix
+
+### Phase 1: Scope-aware compile (minimum viable)
+
+1. Modify `build_compiler` to collect **all active source directories** via
+   `ScopeResolver.resolve(working_dir)` instead of a single `conf_root`
+2. Pass multiple source dirs to `CompilationPipeline` (or run the pipeline
+   per-scope and merge results before orphan removal)
+3. `remove_orphans` receives the **union** of all compiled keys across scopes
+
+### Phase 2: CLI flags (from scope_hierarchy.yml design)
+
+Add `--global`, `--project`, `--local` flags to `rai compile` so users can
+target a single scope when needed (e.g. `rai compile --project` only
+recompiles project-level without touching globals).
+
+### Phase 3: Priority resolution
+
+When a project behaviour has the same `name` as a global behaviour, the
+project-level version should win (override), following the existing
+configuration hierarchy documented in CLAUDE.md.
+
+## Affected Files
+
+- `lib/rosett_ai/project_context.rb` — `conf_root` must support multi-source
+- `lib/rosett_ai/thor/tasks/compile.rb` — `build_compiler` and `remove_orphans`
+- `lib/rosett_ai/compiler/compilation_pipeline.rb` — accept multiple source dirs
+- `lib/rosett_ai/composition/scope_resolver.rb` — wire into compile flow
+- `conf/design/scope_hierarchy.yml` — update status from draft to in-progress
+
+## Related Issues
+
+- [Issue 001](001-wrapper-missing-environment-variables.md) — environment variable handling
+- WP#711 — `fix/711-compile-reads-rosett-ai-conf-instead-of-source` (merged)
+- WP#712 — `fix/712-compile-deletes-global-rules-as-orphans` (merged)
+- `conf/design/scope_hierarchy.yml` — design document for scope merging