rUv
a34bfc246e
Add a read-only guidance CLI/MCP surface with reviewed capability maturity, repository citations, validation commands, limitations, and shared-brain evidence. Bump @ruvnet/ruview to 0.3.1 and add release-tarball smoke coverage.
3.1 KiB
ADR-283: RuView community metaharness and verified learning flywheel
| Field | Value |
|---|---|
| Status | Accepted — P0/P1 implemented |
| Date | 2026-07-28 |
| Builds on | ADR-182, ADR-263, ADR-265 |
Decision
Extend harness/ruview as the single contributor automation boundary for
repository exploration, development, debugging, testing and release
preparation. The published package remains runtime-dependency-free.
Repository exploration starts with a read-only guidance tool. Its reviewed catalog records capability maturity, fixed source paths, focused validation commands, and explicit limitations. In a checkout those citations are checked for existence; outside a checkout they are labelled as a packaged snapshot. Optional shared-brain matches remain cited evidence rather than instructions.
Two local hosts are supported with executable contracts:
- Claude Code uses non-interactive
claude -p --safe-mode, JSON output, no session persistence, plan mode, and only read/search tools by default. - Codex uses
codex exec -, a trusted-Croot,read-onlysandbox, ephemeral sessions, strict config parsing, ignored user config/exec rules and JSONL output.
Both use shell-free subprocesses, stdin prompts, allowlisted environments, bounded output/time, secret redaction and realpath-based RuView checkout validation. Write mode requires two explicit flags and never uses permission or sandbox bypasses.
Shared brain
The public brain is committed JSONL, not a shared mutable database. Canonical records are reviewed, bounded, source-relative, source-cited and content digested. Secret-shaped and instruction-shaped submissions are quarantined. Community learning enters through ordinary proposal pull requests.
Ruflo/AgentDB may build local semantic indexes and private overlays from that corpus. Those indexes, raw transcripts, credentials and personal/CSI data are not committed. This provides a common brain without turning retrieved text into executable policy.
Darwin and Flywheel
The seven policy surfaces are explicit in flywheel/genome.json. Evolution is
human-initiated and each Darwin candidate may mutate only one surface.
Contributor runs produce untrusted .metaharness/ artifacts.
Promotion is conjunctive:
- the frozen anchor cannot regress;
- the holdout must improve;
- legacy and security tests pass;
- no blocked action or secret exposure occurs;
- corpus, files and gate fingerprints verify;
- a maintainer reviews and approves the replay bundle.
Flywheel signatures establish bundle integrity, not maintainer authority. Authority comes from protected-branch review and release provenance. CI never autonomously promotes or publishes an evolved candidate.
Consequences
Contributors can explore RuView with either major local CLI and share durable findings without sharing secrets. Improvements become reproducible proposals with frozen evaluation evidence. The cost is a larger development-only npm lockfile, a 128 KiB unpacked-package budget (the current tarball is below that bound), and explicit maintenance of the corpus, genome and gate.