mirror of
https://github.com/ruvnet/RuView
synced 2026-08-11 20:41:44 +00:00
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.
72 lines
3.1 KiB
Markdown
72 lines
3.1 KiB
Markdown
# 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 `-C` root, `read-only` sandbox,
|
|
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:
|
|
|
|
1. the frozen anchor cannot regress;
|
|
2. the holdout must improve;
|
|
3. legacy and security tests pass;
|
|
4. no blocked action or secret exposure occurs;
|
|
5. corpus, files and gate fingerprints verify;
|
|
6. 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.
|