From 313543ace31397021d2d99a24909798c8d8ad9c8 Mon Sep 17 00:00:00 2001 From: ruv Date: Wed, 19 Aug 2026 21:32:58 -0400 Subject: [PATCH] =?UTF-8?q?docs(adr):=20address=20PR=20#847=20review=20?= =?UTF-8?q?=E2=80=94=20fix=20cross-repo=20citations,=20rescope=20ADR-315?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes three blocking findings and several non-blocking ones from adr-reviewer's adversarial review of the PIR ADR set, cross-checked against direct clones of ruvnet/LatentMesh, ruvnet/autogenous, ruvnet/dream-machine, ruvnet/metaharness, and ruvnet/ruflo: - B-1: ADR-315 and ADR-305 wrongly treated autogenous ADR-401's Better/Safe/Authorized/Reversible promotion predicate as open work. ADR-401's Update 1 section 3 marks it DONE upstream (mesh-evolve.ts's promoteAuthorized, proven by test/promote-authorized.test.ts) — the capability-table row cited was stale relative to ADR-401's own Decision section. ADR-315 now adopts promoteAuthorized instead of scoping work to close it. - B-2: "metaharness ADR-251" does not exist (metaharness's ADR series tops out at ADR-250; the Nightly Dream Cycle lives in docs/dream-cycle/, not an ADR). ADR-306's four citations now point at docs/dream-cycle/ and note the bad citation's provenance (inherited from dream-machine ADR-0001) instead of restating it as fact. - B-3: "ruvector ADR-150 (optionalDependencies policy)" was a misattribution — ruvector's own ADR-150 and metaharness's own ADR-150 are both unrelated documents; METAHARNESS-README.md attributes the policy to an upstream ADR-150 neither clone contains. Every reference (ADR-306, ADR-313, 03-program-plan.md) now cites METAHARNESS-README.md's documented invariant directly, with the upstream attribution flagged unverified. Also fixed in the same push: - ADR-313's WP0b gate: the ruvllm HTTP-307 redirect bug is already fixed on main (commit 946275a61, PR #590, 2026-06-18); the real remaining blocker is a GGUF glob/alias mismatch in ruvllm-cli's get_files_to_download() (download.rs:193, models.rs:65). - 03-program-plan.md: recorded the 7th governing invariant (ruflo ADR-322B's proposer/promotion separation, adopted in ADR-305) that was missing from the "six, unchanged" list; reworded ADR-list items 0 and 12 as work-package-only entries so the plan's promised ADR count (11) matches what shipped. - ADR-306 now attributes "the machine never merges; a human does" to dream-machine's README (verbatim source) rather than claiming it verbatim from ADR-0001, whose own section 2.4 phrases the same substance differently. - ADR-306/310/312 replace the ruflo ADR-322/322C citations with source-verified detail (three signing domains, evidence-grading vocabulary, verbatim 322B quote) now that a full ruflo clone confirmed them, and correct ADR-381: it is Proposed, not Accepted, and its own contribution is stream-identity/budget-epoch-reset governance — the 0.6% false-promotion figure and the alpha_k allocation belong to ruflo PR #2956's mechanism, which ADR-381 governs. Every family-wise bound is now stated per-epoch, not globally, per ADR-381's own text. - ADR-305 adds a standing fix-history verification rule: an inherited "known bug/gap/not-yet-implemented" claim must be checked against the named path's actual fix history before being repeated in a PIR ADR — the root cause shared by all three blocking findings above. docs/research/perpetual-intelligence-runtime/04-verification-addendum.md records the full correction trail (new section 8) without editing 02-asset-map.md or 03-program-plan.md's prior content in place. Co-Authored-By: claude-flow --- ...pt-latentmesh-adr009-control-loop-spine.md | 52 ++++++-- ...6-dream-machine-sona-darwin-unification.md | 64 ++++++---- ...l-attribution-gate-latent-communication.md | 31 +++-- ...hared-witness-schema-anchoring-contract.md | 76 +++++++---- ...r-frozen-weight-skill-harness-evolution.md | 82 ++++++++---- ...nance-constitution-capability-expansion.md | 55 +++++--- .../03-program-plan.md | 54 ++++++-- .../04-verification-addendum.md | 118 ++++++++++++++++++ 8 files changed, 414 insertions(+), 118 deletions(-) diff --git a/docs/adr/ADR-305-adopt-latentmesh-adr009-control-loop-spine.md b/docs/adr/ADR-305-adopt-latentmesh-adr009-control-loop-spine.md index 74389493f..22bf8e820 100644 --- a/docs/adr/ADR-305-adopt-latentmesh-adr009-control-loop-spine.md +++ b/docs/adr/ADR-305-adopt-latentmesh-adr009-control-loop-spine.md @@ -94,13 +94,23 @@ ruflo ADR-322 has a directly load-bearing implementation detail for this program: its child ADR-322B states, verbatim, *"A proposer produces untrusted candidates only. It cannot issue promotion decisions or mutate active policy."* This is the same separation-of-powers boundary autogenous -ADR-401 admits it has not yet fully closed (capability 5: `Promote = Better -∧ Safe ∧ Authorized ∧ Reversible` is "not yet one checked predicate"). ruflo -ADR-322A already implements it as one atomic transaction -(`promoteFlywheelCandidate` as sole promotion authority, verified under 100 -concurrent promotion attempts producing exactly one commit). This program +ADR-401's capability-5 table row describes as "not yet one checked +predicate" — **but that row is stale relative to ADR-401's own Decision +section.** ADR-401's **Update 1 §3, "Converge the promotion invariant to one +predicate," is marked DONE**: `mesh-evolve.ts` exports +`promoteAuthorized(candidate, champion, { authorized, reversible }) → +PromotionDecision`, the single gate `Promote = Better ∧ Safe ∧ Authorized ∧ +Reversible`, with each conjunct independently blocking and +`evolveMesh` routing every promotion through it — proven by +`test/promote-authorized.test.ts` (all-four promotes; any three-of-four does +not). This program cites the Decision section, not the stale capability +table, as ADR-401's authoritative status on this point (see ADR-315 for the +corrected scope this implies). ruflo ADR-322A independently implements the +same separation as one atomic transaction (`promoteFlywheelCandidate` as +sole promotion authority, verified under 100 concurrent promotion attempts +producing exactly one commit). This program adopts that separation-of-powers invariant as a **governing invariant**, -alongside the six carried from the original brief (see Decision §2 below). +alongside the six carried from the original brief (see Decision §3 below). **This changes the decision below**: LatentMesh ADR-009 is a *proposed, unwired, ~1.4K-LOC integration contract*. Autogenous ADR-400/401 are @@ -158,12 +168,30 @@ levels: 5. The program's committed first work package (WP1) is, before any other PIR work starts: (a) read autogenous ADR-401 in full and produce the explicit adopt/diverge decision required above, (b) confirm LatentMesh - ADR-009's loop against source (done — see Verification note), and (c) - read ruflo ADR-322/322A/322B/322C in full and confirm its - separation-of-powers invariant is correctly adopted by every PIR ADR that - defines a promotion mechanism (done for citation purposes here; binding - confirmation against source is WP1's responsibility, mirroring the - LatentMesh verification pattern above). + ADR-009's loop against source (done — see Verification note), (c) + confirm ruflo ADR-322/322A/322B/322C against source (**done**: cloned + directly, HEAD `fa13ee4`, 2026-08-15; the separation-of-powers quote, + the 322C canonical-encoding/signature stack including its three signing + domains, and the evidence-grading vocabulary all check out verbatim — + see `04-verification-addendum.md` §8), and (d) apply the **fix-history + verification rule** below to every remaining inherited claim this + program has not yet independently checked. +6. **Fix-history verification rule (added after PR #847 review)**: an + inherited "known bug," "gap," or "not yet implemented" claim from any + source document — the program brief, an upstream ADR, or a prior research + pass in this program itself — must be checked against that path's actual + fix history (`git log` on the named file/module, the owning repo's + release notes or merged PRs) before being repeated in a PIR ADR. It is + not sufficient that the asserting document's prose says the bug is open. + This rule exists because all three of this ADR set's blocking review + findings (ADR-401's promotion predicate, the "metaharness ADR-251" + citation, and the ADR-150 misattribution — see ADR-315, ADR-306, ADR-313) + shared the same root cause: a claim was carried forward from an upstream + document without checking whether upstream's own state had since moved + past it, or whether the citation resolved to a real document at all. The + `ruvllm` HTTP-307 bug ADR-313 originally cited as open (later found + already fixed on `main`, commit `946275a61`) is the concrete instance + that surfaced this pattern. ## Consequences diff --git a/docs/adr/ADR-306-dream-machine-sona-darwin-unification.md b/docs/adr/ADR-306-dream-machine-sona-darwin-unification.md index 3fd08df4a..8ec204092 100644 --- a/docs/adr/ADR-306-dream-machine-sona-darwin-unification.md +++ b/docs/adr/ADR-306-dream-machine-sona-darwin-unification.md @@ -3,7 +3,7 @@ - **Status**: Proposed - **Date**: 2026-08-19 - **Deciders**: RuV Perpetual Intelligence Runtime (PIR) Program -- **Related**: ADR-305 (PIR, depends on); ADR-312 (PIR, shares verification stack); ADR-313 (PIR, downstream consumer); ruvector ADR-282 (research-gate); ruflo ADR-322/322A/322B/322C (flywheel integration); ruflo ADR-381 (sequential promotion evidence); dream-machine ADR-0001 (Accepted, engine v0.1.0 shipped); metaharness ADR-251 (Nightly Dream Cycle); see `docs/research/perpetual-intelligence-runtime/04-verification-addendum.md` §6 +- **Related**: ADR-305 (PIR, depends on); ADR-312 (PIR, shares verification stack); ADR-313 (PIR, downstream consumer); ruvector ADR-282 (research-gate); ruflo ADR-322/322A/322B/322C (flywheel integration, Accepted — verified against source); ruflo ADR-381 (Proposed — stream identity + budget-exhaustion recovery only, not the statistics; see Context); ruflo PR #2956 (the anytime-valid statistics mechanism itself); dream-machine ADR-0001 (Accepted, engine v0.1.0 shipped); metaharness `docs/dream-cycle/` (Nightly Dream Cycle — not an ADR; corrects "metaharness ADR-251," which does not exist); see `docs/research/perpetual-intelligence-runtime/04-verification-addendum.md` §6, §8 - **Tags**: pir, dream-machine, promotion, evaluation, cross-repo ## Context @@ -31,8 +31,15 @@ parent."* This ADR's premise changed twice during research for this program `@metaharness/flywheel`, `@metaharness/darwin`, `@metaharness/redblue`, the `metaharness` CLI, `ruvector`, and `agentdb` as optional/peer dependencies, and its own text names two prior instances it - **subsumes**: `ruvnet/ruflo`'s nightly dream cycle and metaharness - ADR-251 ("MetaHarness Nightly Dream Cycle"). + **subsumes**: `ruvnet/ruflo`'s nightly dream cycle and, per its own + "Prior instances" line, "metaharness ADR-251 (MetaHarness Nightly Dream + Cycle)." **That second citation does not exist and this ADR does not + restate it as fact**: `ruvnet/metaharness`'s ADR series is 230 files + topping out at `ADR-250-sota-proof-ladder.md` — no ADR-251. Its Nightly + Dream Cycle material instead lives in `docs/dream-cycle/` + (`2026-08-13-gist.md`, `2026-08-14-gist.md`, `LEDGER.md`), not as an ADR. + The bad citation is inherited from dream-machine ADR-0001's own text, + noted here as its provenance rather than independently verified. **"Dream Machine" therefore now exists in four places**, and this program must name which is canonical for which layer rather than building a fifth: @@ -41,15 +48,18 @@ must name which is canonical for which layer rather than building a fifth: |---|---| | Generalized, product-level evaluation engine (compile/ledger/witness/schedule/memory, CLI/TUI) | `ruvnet/dream-machine` ADR-0001 (Accepted, v0.1.0 shipped) | | Statistical significance + hard vetoes + signed replay bundles, already CI-wired inside `ruvector` | `ruvector` ADR-282 (`scripts/research-gate/`, `crates/ruvector-sota-bench/harness`) | -| Evaluation↔promotion transaction model, separation of proposer vs. promotion authority | ruflo ADR-322A/322B (see ADR-305, ADR-313) | -| Sequential/anytime-valid statistical evidence across adaptively-chosen candidates | ruflo ADR-381 (0.6% measured family-wise false-promotion rate over 1,000 simulated nulls) | -| Earlier reference instances, now subsumed | `ruvnet/ruflo` nightly dream cycle; `ruvnet/metaharness` ADR-251 | +| Evaluation↔promotion transaction model, separation of proposer vs. promotion authority | ruflo ADR-322/322A/322B (Accepted — implemented; see ADR-305, ADR-313) | +| Sequential/anytime-valid statistical evidence across adaptively-chosen candidates | ruflo **PR #2956** (the mechanism: `α_k = α_total·6/(π²k²)`, 0.6% measured family-wise false-promotion rate over 1,000 simulated nulls, bound holds **per epoch**); ruflo **ADR-381** (Proposed — governs stream identity and budget-exhaustion recovery *over* that mechanism, not the statistics themselves) | +| Earlier reference instances, now subsumed | `ruvnet/ruflo` nightly dream cycle; `ruvnet/metaharness` `docs/dream-cycle/` (not an ADR — see above) | **Version drift**: `ruvnet/dream-machine` composes `@metaharness/darwin` 0.9.1 / `@metaharness/flywheel` 0.1.10; `ruvector` currently pins `darwin` 0.8.0 / `flywheel` 0.1.7. This program's WP0b (MetaHarness dependency-compliance remediation) should account for this drift when it -fixes the ADR-150 `optionalDependencies` non-compliance bug. +fixes the `optionalDependencies` non-compliance documented in +`METAHARNESS-README.md` (see ADR-313 for the corrected citation — the +policy is attributed there to an upstream metaharness ADR-150 not present +in either repo, not to `ruvector`'s own ADR-150, which is unrelated). ## Decision @@ -72,17 +82,23 @@ core**, wired to `ruvector`'s already-CI-integrated statistical layer: 4. The evaluation↔promotion transaction boundary follows ruflo ADR-322A/ 322B: an evaluation verdict is advisory input, never a promotion decision in itself. -5. **ADR-0001's constitutional principle is adopted verbatim and is not +5. **Dream-machine's constitutional principle is adopted and is not negotiable within this program: "Evaluation is not promotion — the - machine never merges; a human does."** Automated gates (research-gate's - statistics, dream-machine's ledger/witness pipeline, ruflo's promotion - transaction) may recommend promote/reject; only a human-authorized action - performs the final merge into an active policy or codebase. This - constrains the frozen-weights-and-governed-mutation loop this program - builds (ADR-313, ADR-315) — no PIR work package may wire an unattended - `/loop`-style auto-merge path, mirroring ADR-0001's own explicit - phase-3/4 gating of unattended promotion pending separate privilege, - spend, and rollout controls. + machine never merges; a human does."** This exact sentence is verbatim in + dream-machine's `README.md` (L19–20) and `packages/cli/README.md`, not in + ADR-0001 itself — ADR-0001 §2.4 states the same substance in its own + words: *"Evaluation is not promotion. The session never merges, never + self-promotes flywheel state…"* and *"Promotion is a human act."* This + ADR cites the README's phrasing because it is the more quotable form, and + attributes it to the repo rather than to ADR-0001 specifically. Automated + gates (research-gate's statistics, dream-machine's ledger/witness + pipeline, ruflo's promotion transaction) may recommend promote/reject; + only a human-authorized action performs the final merge into an active + policy or codebase. This constrains the frozen-weights-and-governed-mutation + loop this program builds (ADR-313, ADR-315) — no PIR work package may + wire an unattended `/loop`-style auto-merge path, mirroring ADR-0001's + own explicit phase-3/4 gating of unattended promotion pending separate + privilege, spend, and rollout controls. ## Consequences @@ -91,9 +107,11 @@ core**, wired to `ruvector`'s already-CI-integrated statistical layer: - Converts what was the program's single largest identified risk (building a promotion-evaluation system from nothing) into a consolidation task across four already-Accepted-or-implemented pieces of prior art. -- Inherits ruflo ADR-381's measured statistical guarantee (0.6% family-wise - false-promotion rate) instead of needing to re-derive or re-validate a - sequential-testing scheme from scratch. +- Inherits ruflo PR #2956's measured statistical guarantee (0.6% family-wise + false-promotion rate, per epoch) instead of needing to re-derive or + re-validate a sequential-testing scheme from scratch; ADR-381 (Proposed) + layers stream-identity and budget-recovery governance on top of that + already-implemented mechanism. - The "evaluation is not promotion, a human merges" principle gives invariant 5 a hard human-in-the-loop backstop, directly addressing the acceptance test's "zero unapproved capability expansion" requirement @@ -102,7 +120,7 @@ core**, wired to `ruvector`'s already-CI-integrated statistical layer: ### Negative - Four separate prior instances (dream-machine, ruflo dream cycle, - metaharness ADR-251, ruvector research-gate) must be reconciled into one + metaharness `docs/dream-cycle/`, ruvector research-gate) must be reconciled into one coherent pipeline for this program; no repo checked by this program's research passes has published that reconciliation yet — it is WP1/WP2's deliverable, not a pre-existing fact this ADR can cite. @@ -138,8 +156,8 @@ core**, wired to `ruvector`'s already-CI-integrated statistical layer: - `ruvnet/dream-machine` (adopted engine, external dependency) - `ruvnet/ruvector` (`scripts/research-gate/`, `crates/ruvector-sota-bench/harness`, ADR-282; SONA dream-replay) -- `ruvnet/ruflo` (ADR-322A/322B transaction model, ADR-381 statistics) -- `ruvnet/metaharness` (ADR-251, prior reference instance) +- `ruvnet/ruflo` (ADR-322/322A/322B transaction model — Accepted, verified verbatim against source; PR #2956 — the sequential-statistics mechanism; ADR-381 — Proposed, stream-identity/budget-recovery governance only) +- `ruvnet/metaharness` (`docs/dream-cycle/`, prior reference instance — not an ADR) ## Dependencies diff --git a/docs/adr/ADR-310-causal-attribution-gate-latent-communication.md b/docs/adr/ADR-310-causal-attribution-gate-latent-communication.md index 6448a7fd7..84732641b 100644 --- a/docs/adr/ADR-310-causal-attribution-gate-latent-communication.md +++ b/docs/adr/ADR-310-causal-attribution-gate-latent-communication.md @@ -3,7 +3,7 @@ - **Status**: Proposed - **Date**: 2026-08-19 - **Deciders**: RuV Perpetual Intelligence Runtime (PIR) Program -- **Related**: ADR-309 (PIR, depends on); ADR-311 (PIR, downstream consumer); ruflo ADR-381 (sequential promotion evidence) +- **Related**: ADR-309 (PIR, depends on); ADR-311 (PIR, downstream consumer); ruflo PR #2956 (anytime-valid sequential-evidence mechanism); ruflo ADR-381 (Proposed — stream identity + budget-exhaustion recovery over that mechanism) - **Tags**: pir, causal-audit, ci-gate, latent-communication, security ## Context @@ -47,10 +47,18 @@ claims can justify further rollout. Concretely: with a control (unrelated or null) payload and confirm the receiving agent's behavior changes accordingly when the real payload is restored. 3. Statistical claims produced by this gate (e.g. "the latent channel's - effect on receiver behavior is significant") follow ruflo ADR-381's - anytime-valid sequential-evidence scheme when the gate runs repeatedly - across many PRs over time, rather than treating each PR's audit as an - independent, uncorrected significance test. + effect on receiver behavior is significant") follow ruflo PR #2956's + anytime-valid e-process scheme (`α_k = α_total·6/(π²k²)` per-test + allocation, so `Σα_k = α_total` holds across arbitrarily many + adaptively-chosen PRs) when the gate runs repeatedly over time, rather + than treating each PR's audit as an independent, uncorrected significance + test. Ruflo ADR-381 (Proposed) is the governance layer over that + mechanism — per-project stream identity and an audited, + `confirm: true`-gated evidence-epoch reset for budget exhaustion. **The + false-promotion bound this composition provides is per-epoch, not + global**: after a reset, the guarantee is family-wise false-promotion + probability ≤ `α_total` for that epoch, and this gate's own statistical + claims must be stated the same way. 4. A CI failure on this gate blocks merge; it does not merely warn. ## Consequences @@ -63,10 +71,10 @@ claims can justify further rollout. Concretely: after a later change would otherwise go undetected. - Reuses a peer-reviewed, grade-A methodology instead of inventing an in-house causal-attribution test from scratch. -- Composing with ruflo ADR-381's sequential-evidence scheme keeps the gate's - statistical claims sound even as it runs many times over the program's - lifetime, rather than accumulating false-positive risk across repeated - single tests. +- Composing with ruflo PR #2956's sequential-evidence scheme (governed by + ADR-381) keeps the gate's statistical claims sound, per epoch, even as it + runs many times over the program's lifetime, rather than accumulating + false-positive risk across repeated single tests. ### Negative @@ -90,8 +98,9 @@ claims can justify further rollout. Concretely: the audit history for any given latent-channel change is queryable end-to-end. - **Sequential-evidence discipline**: statistical claims from repeated gate - runs follow ruflo ADR-381's scheme rather than compounding uncorrected - significance tests. + runs follow ruflo PR #2956's e-process scheme (governed by ADR-381) rather + than compounding uncorrected significance tests, and are stated as + per-epoch bounds, not global ones. ## Affected Repos diff --git a/docs/adr/ADR-312-shared-witness-schema-anchoring-contract.md b/docs/adr/ADR-312-shared-witness-schema-anchoring-contract.md index 477fab325..d80ac23f8 100644 --- a/docs/adr/ADR-312-shared-witness-schema-anchoring-contract.md +++ b/docs/adr/ADR-312-shared-witness-schema-anchoring-contract.md @@ -3,7 +3,7 @@ - **Status**: Proposed - **Date**: 2026-08-19 - **Deciders**: RuV Perpetual Intelligence Runtime (PIR) Program -- **Related**: ADR-305 (PIR, depends on); ADR-306, ADR-307, ADR-309, ADR-315 (PIR, consumers); ruflo ADR-322C (flywheel receipt/ledger/verification protocol); ruflo ADR-381 (sequential promotion evidence); ruvector ADR-134 (witness schema/log format); see `docs/research/perpetual-intelligence-runtime/04-verification-addendum.md` §3, §5 +- **Related**: ADR-305 (PIR, depends on); ADR-306, ADR-307, ADR-309, ADR-315 (PIR, consumers); ruflo ADR-322/322C (flywheel receipt/ledger/verification protocol, Accepted — implemented, verified verbatim against source); ruflo PR #2956 (anytime-valid sequential-evidence mechanism); ruflo ADR-381 (Proposed — stream identity + budget-exhaustion recovery over that mechanism); ruvector ADR-134 (witness schema/log format); see `docs/research/perpetual-intelligence-runtime/04-verification-addendum.md` §3, §5, §8 - **Tags**: pir, witness, provenance, security, cross-repo ## Context @@ -33,19 +33,43 @@ keyed-MAC chain is deliberately not a signature scheme suitable for cross-service, offline verification. **Merging them, or making one depend on the other, would be a design error**, not a simplification. -A better anchor already exists. `ruflo ADR-322C` (part of the Accepted, -phases-0–2-implemented ADR-322 flywheel-integration series) defines a -receipt/ledger/verification protocol built specifically to be a portable, -offline-verifiable, cross-layer wire format: **RFC 8785 JCS canonical JSON, -SHA-256 digests, Ed25519 signatures with domain separation** -(`Ed25519(domainPrefix || 0x00 || canonicalBytes)`), UUIDv7 run IDs, -deterministic paired-bootstrap statistical recomputation, and fail-closed -verification (unknown fields, non-finite numbers, and negative zero all -rejected). Separately, `ruflo ADR-381` defines an anytime-valid sequential -statistical evidence scheme (`α_k = α_total · 6/(π²k²)`, measured 0.6% -family-wise false-promotion rate over 1,000 simulated nulls) for the -statistical claims a witness chain needs to carry when it records a -promotion decision. +A better anchor already exists, and this program has now verified it +directly against a clone of `ruvnet/ruflo` (HEAD `fa13ee4`, 2026-08-15; 177 +ADRs in `v3/docs/adr/`), not merely inherited it. `ruflo ADR-322C` (part of +the Accepted — phases-0–2-implemented — ADR-322 flywheel-integration series) +defines a receipt/ledger/verification protocol built specifically to be a +portable, offline-verifiable, cross-layer wire format: **RFC 8785 JCS +canonical JSON, SHA-256 digests, Ed25519 signatures with domain separation** +(`Ed25519(domainPrefix || 0x00 || canonicalBytes)`) — confirmed to use +**three distinct signing domains** (bootstrap, receipt, ledger-head), not +one, with explicit identity derivation (`candidateId = +SHA-256(JCS(candidate policy))`, `receiptId = SHA-256(JCS(unsigned receipt +payload))`). Every authorizing term in a 322C record carries an explicit +evidence grade — **`recomputed`, `signature-verified`, or +`trusted-assertion`** — a vocabulary this ADR adopts below for grading +anchored claims. UUIDv7 run IDs, deterministic paired-bootstrap statistical +recomputation, an O_EXCL cross-process lock with directory-fsynced +compare-and-swap, and fail-closed verification (unknown fields, non-finite +numbers, and negative zero all rejected) are likewise confirmed against +source. **This same verification pass corroborates the ADR-103 ambiguity +this program flagged elsewhere (ADR-305)**: ADR-322C line 105 states its +keys "use ADR-103's provider mechanism but a distinct purpose/domain" — +confirming the witness-manifest ADR-103 is `ruflo`'s, not `ruvector`'s. + +Separately, `ruflo ADR-381` is **Proposed** (not Accepted; date 2026-08-10) +and governs a narrower scope than this ADR originally attributed to it. The +anytime-valid sequential statistical evidence scheme itself — `α_k = +α_total · 6/(π²k²)` per-test allocation so `Σα_k = α_total`, and the +measured 0.6% family-wise false-promotion rate over 1,000 simulated nulls — +belongs to **ruflo PR #2956**, which ADR-381 *governs* rather than defines: +ADR-381's own decision is (1) scoping the α ledger to the ADR-322 +transaction state, one stream per project root, and (2) +`resetSequentialEvidence`, an explicit, `confirm: true`-gated, human-reasoned +**evidence-epoch** reset for budget exhaustion that expires all outstanding +receipts so stale evidence cannot be replayed against a fresh budget. +**The false-promotion bound is per-epoch, not global**: after a reset, the +guarantee is family-wise false-promotion probability ≤ `α_total` for that +epoch — any PIR document citing this bound must state it the same way. ## Decision @@ -66,11 +90,17 @@ cross-layer anchoring contract**, not a crate merge or dependency edge: anchoring boundary, regardless of each crate's own internal representation. 3. Where a witness record makes a statistical claim (e.g. "this mutation's - improvement was significant"), that claim's evidence follows ruflo - ADR-381's sequential-evidence scheme rather than a single uncorrected + improvement was significant"), that claim's evidence follows ruflo PR + #2956's anytime-valid e-process scheme (governed by ADR-381's stream + identity and evidence-epoch reset) rather than a single uncorrected significance test — this is the concrete mechanism that makes "outperform its parent" (invariant 5) auditable across an arbitrarily long sequence of - promotion attempts, not just a single one. + promotion attempts within an epoch. Any witness record's statistical + claim is stated as a **per-epoch** bound, not a global one, and each + authorizing term is tagged with 322C's evidence grade + (`recomputed`/`signature-verified`/`trusted-assertion`) so a reader can + tell which parts of the claim were independently recomputed versus merely + asserted. 4. ruvector ADR-134's witness schema (the 64-byte cache-line-aligned, hash-chained record format used by `rvm-witness`) is unchanged by this ADR; this decision governs the boundary where a non-RVM witness record @@ -116,10 +146,12 @@ cross-layer anchoring contract**, not a crate merge or dependency edge: verification rules — this program does not weaken that contract at the boundary. - **Sequential-evidence discipline**: any witness record carrying a - statistical promotion claim states its evidence per ruflo ADR-381's - anytime-valid scheme, not a single-test p-value, so the acceptance - harness's (ADR-306, WP12) day-30 comparison remains statistically sound - across many promotion attempts. + statistical promotion claim states its evidence per ruflo PR #2956's + anytime-valid e-process scheme (governed by ADR-381), not a single-test + p-value, expressed as a **per-epoch** bound, so the acceptance harness's + (ADR-306, WP12) day-30 comparison remains statistically sound within each + evidence epoch — a day-30-vs-day-1 comparison spanning an epoch reset must + not silently claim a global bound it does not have. - **Standard repo gate**: `npx @claude-flow/cli@latest security scan` after any change to signing, canonicalization, or verification code in either witness crate or the anchoring boundary. @@ -128,7 +160,7 @@ cross-layer anchoring contract**, not a crate merge or dependency edge: - `ruvnet/rvm` (`rvm-witness`, unchanged internally) - `ruvnet/autogenous` (`witness` crate, unchanged internally) -- `ruvnet/ruflo` (ADR-322C canonical encoding/signature scheme, ADR-381 statistics — consumed, not modified, by this ADR) +- `ruvnet/ruflo` (ADR-322/322C canonical encoding/signature scheme — Accepted; PR #2956's sequential-evidence mechanism; ADR-381's stream-identity/epoch-reset governance — Proposed; all consumed, not modified, by this ADR) - `ruvnet/ruvector` (anchoring-boundary implementation, RVM witness consumer) ## Dependencies diff --git a/docs/adr/ADR-313-shaper-frozen-weight-skill-harness-evolution.md b/docs/adr/ADR-313-shaper-frozen-weight-skill-harness-evolution.md index 7ef18d3ca..1fe3efc20 100644 --- a/docs/adr/ADR-313-shaper-frozen-weight-skill-harness-evolution.md +++ b/docs/adr/ADR-313-shaper-frozen-weight-skill-harness-evolution.md @@ -3,7 +3,7 @@ - **Status**: Proposed - **Date**: 2026-08-19 - **Deciders**: RuV Perpetual Intelligence Runtime (PIR) Program -- **Related**: ADR-306 (PIR, depends on); ADR-308 (PIR, downstream consumer); ADR-305 (PIR, separation-of-powers invariant); ruvector ADR-150 (optionalDependencies policy); ruvector ADR-259 (ruvllm mutator backend); ruvector ADR-271 (darwin_guard); ruflo ADR-322B (proposer/promotion separation) +- **Related**: ADR-306 (PIR, depends on); ADR-308 (PIR, downstream consumer); ADR-305 (PIR, separation-of-powers invariant); `METAHARNESS-README.md`'s documented integration invariant (attributed to an upstream metaharness ADR-150 not present in either repo — unverified; see Context); ruvector ADR-259 (ruvllm mutator backend); ruvector ADR-271 (darwin_guard); ruflo ADR-322/322A/322B (proposer/promotion separation, Accepted — verified verbatim against source) - **Tags**: pir, shaper, darwin, frozen-weights, evolution ## Context @@ -30,16 +30,37 @@ mutate (seven approved surfaces via `CodeGenerator`, e.g. `OpenRouterMutator`, `RuvllmMutator`) → sandbox → 6-term score → archive-as-tree → repeat. `ruvllm` is a real, wired local mutator backend (ruvector ADR-259). -**Two concrete, already-identified bugs block this work package** and must +**One concrete, already-identified bug blocks this work package** and must be fixed first (program plan WP0b), not discovered mid-implementation: -1. `METAHARNESS-README.md` claims ruvector ADR-150 `optionalDependencies` - compliance, but the nine `@metaharness/*` packages in - `crates/ruvector-sota-bench/harness` are plain (hard) dependencies — the - harness currently hard-fails to install without them, contradicting its - own documented policy. -2. A known HTTP-307 redirect bug in `ruvllm`'s model-download path blocks - end-to-end live-serve testing of the mutator backend. +1. `METAHARNESS-README.md` claims `optionalDependencies` compliance, + attributing the policy to "**ADR-150**: MetaHarness Integration Surfaces + (**upstream**)." **That attribution does not resolve to a real document + in either repo**: `ruvector`'s own ADR-150 is + `ADR-150-pi-brain-ruvltra-tailscale.md` ("π Brain + RuvLtra via Tailscale + — Semantic Embedding Upgrade") — unrelated; `metaharness`'s own ADR-150 + is `ADR-150-tailscale-local-frontier-concurrent-benchmarks.md` — also + unrelated. `METAHARNESS-README.md` labels its source "upstream," meaning + a document neither clone contains. This ADR cites the bug directly rather + than repeating the dangling number: the nine `@metaharness/*` packages in + `crates/ruvector-sota-bench/harness` are plain (hard) dependencies, + contradicting `METAHARNESS-README.md`'s own documented + `optionalDependencies` policy — the harness currently hard-fails to + install without them. + +**A second bug this ADR previously cited — an HTTP-307 redirect bug in +`ruvllm`'s model-download path — is already fixed on `main`** (commit +`946275a61`, PR #590, 2026-06-18). This ADR no longer treats it as a +blocker. Verifying that fix surfaced the actual remaining download blocker: +a **GGUF glob/alias bug in `ruvllm-cli`'s `get_files_to_download()`** +(`download.rs:193`'s glob pattern and `models.rs:65`'s alias resolution +disagree on which files a given model alias should pull), which still +blocks reliable end-to-end live-serve testing of the mutator backend. This +correction is itself an instance of the verification discipline ADR-305 now +states as a program-wide rule: an inherited "known bug" claim must be +checked against fix history (`git log` on the named path, upstream release +notes) before being repeated in a new ADR, not trusted from the asserting +document's prose alone. ## Decision @@ -57,16 +78,23 @@ weights frozen throughout, following SHAPER's pattern (arXiv:2608.11350): verification requirement (day-30 re-hash must be bit-identical to day 0). 3. Darwin's mutation proposals are exactly that — proposals. Per ruflo ADR-322B's separation-of-powers invariant, adopted as a governing - invariant in ADR-305: *"a proposer produces untrusted candidates only; it - cannot issue promotion decisions or mutate active policy."* Darwin's - mutation surfaces never gain promotion authority; every proposal routes + invariant in ADR-305, quoted here verbatim against source (confirmed + `ADR-322B-darwin-proposer-adapter.md` line 10): *"A proposer produces + untrusted candidates only. It cannot issue promotion decisions or mutate + active policy."* ADR-322 line 15 reinforces the same point from the + Darwin-adapter side: *"Darwin adapters remain candidate generators and + never gain promotion authority."* Darwin's mutation surfaces in this + program never gain promotion authority either; every proposal routes through ADR-306's adopted evaluation pipeline before any change to active policy. -4. WP0b's two blocking bugs are fixed before this work package's live-serve - testing begins: the ADR-150 `optionalDependencies` non-compliance (make - the nine `@metaharness/*` packages genuinely optional, or correct the - documentation to state the real hard-dependency requirement) and the - `ruvllm` HTTP-307 redirect bug in the model-download path. +4. WP0b's remaining blocking bug is fixed before this work package's + live-serve testing begins: the `optionalDependencies` non-compliance + (make the nine `@metaharness/*` packages genuinely optional, or correct + `METAHARNESS-README.md` to state the real hard-dependency requirement) + and the `ruvllm-cli` GGUF glob/alias bug in `get_files_to_download()` + (`download.rs:193`, `models.rs:65`). The previously-cited HTTP-307 + redirect bug is not part of this gate — it shipped fixed on `main` before + this ADR was written. ## Consequences @@ -84,9 +112,12 @@ weights frozen throughout, following SHAPER's pattern (arXiv:2608.11350): ### Negative -- This work package cannot start live-serve testing until WP0b's two bugs - are fixed — an explicit, tracked blocking dependency, not a soft - preference. +- This work package cannot start live-serve testing until WP0b's remaining + bug (the GGUF glob/alias mismatch) is fixed — an explicit, tracked + blocking dependency, not a soft preference. The HTTP-307 bug this ADR + originally also gated on turned out to already be fixed on `main`, + illustrating why every inherited bug claim needs a fix-history check + before it is repeated (see ADR-305). - Darwin currently exists as an external npm dependency (`@metaharness/darwin`) called from three sites, not a first-class in-repo asset; this ADR does not itself resolve that architectural @@ -108,8 +139,9 @@ weights frozen throughout, following SHAPER's pattern (arXiv:2608.11350): - **Proof-gated promotion**: every mutation still passes through `ruvector-proof-gate`/`rvm-proof` regardless of SHAPER-pattern compliance. - **WP0b blocking gate**: this work package's live-serve acceptance criteria - cannot be claimed complete while either the ADR-150 compliance bug or the - ruvllm HTTP-307 bug remains open. + cannot be claimed complete while either the `optionalDependencies` + compliance bug or the `ruvllm-cli` GGUF glob/alias bug + (`get_files_to_download()`) remains open. ## Affected Repos @@ -129,7 +161,7 @@ produces. can't handle**: rejected — this directly contradicts the acceptance test's central constraint and SHAPER's own pattern; any capability gap should be addressed via richer harness/skill mutation surfaces, not weight updates. -- **Defer fixing WP0b's two bugs until they actually block a specific - task**: rejected — both are already identified, small, and cheap to fix; - deferring them guarantees they surface mid-implementation of this ADR's +- **Defer fixing WP0b's remaining bug until it actually blocks a specific + task**: rejected — it is already identified, small, and cheap to fix; + deferring it guarantees it surfaces mid-implementation of this ADR's higher-priority work instead of being resolved ahead of time. diff --git a/docs/adr/ADR-315-governance-constitution-capability-expansion.md b/docs/adr/ADR-315-governance-constitution-capability-expansion.md index 2560c1115..faa25264b 100644 --- a/docs/adr/ADR-315-governance-constitution-capability-expansion.md +++ b/docs/adr/ADR-315-governance-constitution-capability-expansion.md @@ -3,7 +3,7 @@ - **Status**: Proposed - **Date**: 2026-08-19 - **Deciders**: RuV Perpetual Intelligence Runtime (PIR) Program -- **Related**: ADR-312 (PIR, depends on); ADR-306 (PIR, distinct from ordinary promotion gating); autogenous ADR-393 "Product Thesis — Adaptive Agent Firewall" (autogenous repo); autogenous ADR-401 capability 5 (governed self-improvement) +- **Related**: ADR-312 (PIR, depends on); ADR-306 (PIR, distinct from ordinary promotion gating); autogenous ADR-393 "Product Thesis — Adaptive Agent Firewall" (autogenous repo); autogenous ADR-401 capability 5 and Update 1 §3 (governed self-improvement, `promoteAuthorized` — Done) - **Tags**: pir, governance, constitution, capability-expansion, security ## Context @@ -17,10 +17,18 @@ for exactly this purpose (`constitution` crate, part of its observe → explain → mutate → prove → canary → promote/rollback loop), and its own ADR-401 (see ADR-305's reconciliation) frames governed self-improvement as capability 5 of its 10-capability map: `Promote = Better ∧ Safe ∧ -Authorized ∧ Reversible`. ADR-401 admits this predicate is **not yet fully -closed as one checked gate** — the "Authorized" conjunct in particular is -enforced by a human-anchor flywheel step (autogenous ADR-399/ruflo ADR-322), -not yet a single automated predicate. +Authorized ∧ Reversible`. + +**Correction from PR review**: an earlier draft of this ADR described that +predicate as "not yet fully closed as one checked gate," citing ADR-401's +capability-table row 5. **That row is stale relative to ADR-401's own +Decision section.** ADR-401's **Update 1 §3 is marked DONE**: `mesh-evolve.ts` +exports `promoteAuthorized(candidate, champion, { authorized, reversible }) +→ PromotionDecision`, the single gate is implemented with each conjunct +independently blocking, `evolveMesh` routes every promotion through it, and +`test/promote-authorized.test.ts` proves no promotion path can skip a +conjunct. The predicate is closed upstream — this ADR does not scope work +to close it. **Maturity caveat, corrected in this program's verification pass** (see `04-verification-addendum.md` §2): `ruvnet/autogenous`'s README self-labels @@ -37,9 +45,9 @@ total), not the Rust `constitution` crate alone. ## Decision -Adopt `autogenous`'s constitution/admission-gate pattern as the enforcement -point for zero-unapproved-capability-expansion, while closing the specific -gap ADR-401 itself admits is open: +Adopt `autogenous`'s constitution/admission-gate pattern, **anchored on the +already-implemented `promoteAuthorized` predicate**, as the enforcement point +for zero-unapproved-capability-expansion: 1. Every mutation that would expand an agent's capability set — new tool access, new physical action class, new communication peer — requires @@ -48,11 +56,19 @@ gap ADR-401 itself admits is open: pipeline). A mutation passing ADR-306's promotion gate does not automatically pass this gate; capability expansion needs its own, separately-authorized approval record. -2. This program contributes toward closing autogenous ADR-401's own - admitted gap — converging `Promote = Better ∧ Safe ∧ Authorized ∧ - Reversible` into one checked predicate — specifically for the - "Authorized" conjunct as it applies to capability-expanding mutations, - rather than leaving it a human-anchor-only step indefinitely. +2. This program **adopts** `mesh-evolve.ts`'s `promoteAuthorized` predicate + (`Promote = Better ∧ Safe ∧ Authorized ∧ Reversible`, all four conjuncts + already independently blocking upstream) as the mechanism whose + "Authorized" conjunct this gate's capability-expansion approval satisfies. + The residual work this program actually scopes is narrower than the + original framing: (a) the `ruvector`-side integration wiring PIR's + capability/tool/action tables into `promoteAuthorized`'s `authorized` + parameter, and (b) the distinctness rule in §1 above — ensuring a + capability-expanding mutation's "Authorized" check is evaluated against + *this program's* capability-expansion approval record specifically, not + merely against `promoteAuthorized`'s general authorization state. This + program does not build or close the predicate itself; that work is + already done upstream. 3. Approval records for capability expansion are anchored via this program's shared witness contract (ADR-312), so the 30-day acceptance harness (per `03-program-plan.md`) can query "zero unapproved capability @@ -77,16 +93,21 @@ gap ADR-401 itself admits is open: promotion (ADR-306) prevents the specific failure mode where a statistically-significant, well-tested mutation quietly also expands an agent's capability set without anyone noticing. +- `promoteAuthorized` being DONE upstream (ADR-401 Update 1 §3) meaningfully + reduces this ADR's scope versus the original framing — this program + integrates against a finished, tested predicate instead of building or + completing one. ### Negative - Coupling to a self-labeled research-prototype API means this integration carries real churn risk; the API-stability buffer in Decision §4 adds engineering overhead specifically to manage that risk. -- Converging autogenous's own `Better ∧ Safe ∧ Authorized ∧ Reversible` - predicate is, by ADR-401's own admission, not yet done even inside - autogenous itself — this program's contribution to closing that gap is - real, unstarted work, not an integration against a finished mechanism. +- This program's residual scope depends on `promoteAuthorized`'s upstream + API remaining stable (see the research-prototype caveat above) — a + breaking change to its `authorized`/`reversible` parameters or return + shape would require rework on the `ruvector`-side integration, even though + the predicate's core logic is not this program's responsibility to build. - Two separate approval paths (behavioral promotion via ADR-306, capability expansion via this ADR) add process overhead versus a single unified promotion gate — deliberate, per the acceptance test's own requirement diff --git a/docs/research/perpetual-intelligence-runtime/03-program-plan.md b/docs/research/perpetual-intelligence-runtime/03-program-plan.md index aaedcb21a..c34745db9 100644 --- a/docs/research/perpetual-intelligence-runtime/03-program-plan.md +++ b/docs/research/perpetual-intelligence-runtime/03-program-plan.md @@ -4,7 +4,12 @@ Status: draft for ADR seeding, swarm work-package assignment, and GitHub issue f **Revision note**: the second inventory pass materially changed two things worth knowing before reading the rest of this plan. First, "Dream Machine" is *not* a from-scratch build — real, CI-wired, cryptographically-signed statistical promotion machinery already exists (`scripts/research-gate/`, `crates/ruvector-sota-bench/harness`, ADR-282) and should be adopted/renamed, not reinvented; this meaningfully de-risks what was previously flagged as the top program risk. Second, ADR numbering in this repo is not the "ADR-001 through ADR-118" stated in the root `CLAUDE.md` — the true count is 283 files with duplicated numbers up to ADR-304 (see asset map §6 of the cross-cutting notes) — every new ADR in this program must be numbered above 304. -## Governing invariants (carried from the brief, unchanged) +## Governing invariants + +Invariants 1–6 are carried from the brief, unchanged. Invariant 7 was added +during ADR authoring (PR #847, ADR-305), adopted from ruflo ADR-322B's +proposer/promotion separation-of-powers rule — see ADR-305 for the source +citation. 1. Every observation may change memory. 2. Every memory change is transactional. @@ -12,6 +17,9 @@ Status: draft for ADR seeding, swarm work-package assignment, and GitHub issue f 4. Every behavioral mutation is tested. 5. Every promoted mutation must outperform its parent. 6. Every physical action produces new evidence. +7. A proposer produces untrusted candidates only; it cannot issue promotion + decisions or mutate active policy (adopted from ruflo ADR-322B, binding + on ADR-306, ADR-313, ADR-315). Risk control: Darwin proposes, RVM gates what can change, Dream Machine requires statistically credible improvement before promotion. @@ -39,7 +47,19 @@ Build **1 + 2 + 3** (self-evolving physical intelligence, persistent transaction Numbers are placeholders — assign real numbers **above ADR-304** via `ruflo-adr:adr-create` at kickoff (the repo's true max, not the stale "ADR-118" in root `CLAUDE.md` — see asset map §6), and confirm against both `ruvector`'s and `LatentMesh`'s ADR sequences before merging (see asset map note on ADR-103 ambiguity). ADR-create should also register each new ADR in `ruflo-adr:adr-index` immediately to avoid adding to the duplicate-number problem it's meant to fix. -0. **ADR — ADR numbering hygiene remediation.** Decision: run a one-time audit + fix pass over `docs/adr/` to resolve the ~15+ duplicate ADR numbers found (ADR-272 ×5, ADR-264/252/194/144/040 ×3 each, ~12 more ×2), by renumbering the later-created duplicate in each collision to the next free number above 304 and updating all in-repo references (code comments, other ADRs, tool descriptions like `ruflo-core:witness`'s ADR-103 citation) to match. This is process hygiene, not glamorous, but every ADR this program creates depends on the numbering space being trustworthy. +**This list has eleven ADRs (1–11 below); the two work packages below numbered +WP0a and WP0b are process/bug-fix work with no corresponding ADR** — they +were mistakenly written as "ADR — …" entries in an earlier draft of this +plan, which claimed thirteen ADRs against the eleven PR #847 actually +shipped (ADR-305 through ADR-315). Reworded here as work-package-only items +so this plan and the shipped ADR set agree: + +- **WP0a — ADR numbering hygiene remediation** (no ADR). Audit + fix pass + over `docs/adr/` to resolve the ~15+ duplicate ADR numbers found (ADR-272 + ×5, ADR-264/252/194/144/040 ×3 each, ~12 more ×2), by renumbering the + later-created duplicate in each collision to the next free number above + 304 and updating all in-repo references to match. Process hygiene, + tracked as a separate issue, not a PIR ADR. 1. **ADR — Adopt LatentMesh ADR-009 as the Perpetual Intelligence Runtime's control-loop spine.** Decision: rather than defining a new cross-mechanism architecture, this program formally adopts the `execute → transfer → causal audit → measure → update authority → persist → evolve topology` loop from LatentMesh ADR-009, and commits to closing the specific gap that ADR names ("statistical primitive and admission gate implemented; closed loop across live components not wired"). Coordination channel opened with LatentMesh maintainers before any conflicting ADR numbers are assigned. @@ -63,7 +83,25 @@ Numbers are placeholders — assign real numbers **above ADR-304** via `ruflo-ad 11. **ADR — Governance constitution for capability expansion.** Decision: adopt `autogenous`'s constitution/admission-gate pattern as the enforcement point for "zero unapproved capability expansion" (acceptance-test requirement); every mutation that would expand an agent's capability set (new tool access, new physical action class, new communication peer) requires explicit constitutional approval logged to the witness chain, distinct from ordinary behavioral mutation promotion. Note `autogenous`'s own README self-labels it "research prototype" status — treat its APIs as unstable and budget time for API churn, don't assume production-grade stability. -12. **ADR — MetaHarness dependency-compliance remediation.** Decision: fix the confirmed bug where `crates/ruvector-sota-bench/harness`'s nine `@metaharness/*` npm dependencies are declared as plain (hard) dependencies while `METAHARNESS-README.md` claims ADR-150 `optionalDependencies` compliance — either make them genuinely optional per the documented policy, or correct the documentation to state the real (hard-dependency) install requirement. Also track and fix the known HTTP-307 redirect bug in `ruvllm`'s model-download path that currently blocks live-serve end-to-end testing of Darwin's local mutator backend (ADR-259). +- **WP0b — MetaHarness dependency-compliance remediation** (no ADR). Fix the + confirmed bug where `crates/ruvector-sota-bench/harness`'s nine + `@metaharness/*` npm dependencies are declared as plain (hard) + dependencies while `METAHARNESS-README.md` claims `optionalDependencies` + compliance, attributed there to "**ADR-150**: MetaHarness Integration + Surfaces (**upstream**)" — a document neither the `ruvector` nor the + `metaharness` clone contains (`ruvector`'s own ADR-150 is + `pi-brain-ruvltra-tailscale`, unrelated; `metaharness`'s own ADR-150 is + `tailscale-local-frontier-concurrent-benchmarks`, also unrelated). Fix the + bug directly — make the nine packages genuinely optional per the + documented policy, or correct the documentation to state the real + (hard-dependency) install requirement — rather than repeating the + dangling citation. **The previously-tracked HTTP-307 redirect bug in + `ruvllm`'s model-download path is already fixed on `main`** (commit + `946275a61`, PR #590, 2026-06-18); it is not part of this work package. + Verifying that fix surfaced the actual remaining download blocker: a GGUF + glob/alias bug in `ruvllm-cli`'s `get_files_to_download()` + (`download.rs:193`'s glob pattern, `models.rs:65`'s alias resolution), + which this work package tracks and fixes instead. --- @@ -72,7 +110,7 @@ Numbers are placeholders — assign real numbers **above ADR-304** via `ruflo-ad | # | Package | Bounded context | Team composition | Depends on | |---|---|---|---|---| | WP0a | ADR numbering hygiene remediation | Governance | coordinator, adr-architect | — | -| WP0b | MetaHarness dependency-compliance + ruvllm HTTP-307 fix | Physical Skill Evolution | coordinator, backend-dev, tester | — | +| WP0b | MetaHarness dependency-compliance + ruvllm-cli GGUF glob/alias fix | Physical Skill Evolution | coordinator, backend-dev, tester | — | | WP1 | LatentMesh coordination & ADR alignment | Governance | coordinator, adr-architect, system-architect | WP0a | | WP2 | Adopt research-gate/sota-bench as Dream Machine; wire to Darwin | World Verification | coordinator, system-architect, coder ×2, tester | WP1 | | WP3 | Three-level memory tiers on RuVector (LiveMem + TARL ledger on top of existing proof-gated writes) | Persistent Memory Governance | coordinator, backend-dev, memory-specialist, tester | WP1 | @@ -140,7 +178,7 @@ Use `hierarchical` topology, `max-agents 8`, `specialized` strategy per project 1. **Cross-repo coordination overhead, not Dream Machine, is now the top risk.** Four of the seven bounded contexts depend on sibling repos (`LatentMesh`, `rvm`, `autogenous`, `RuView`) maintained outside this program's direct control — LatentMesh's own ADR-009 shows its maintainers are still actively revising scope (twice in one day, per its own text), `autogenous` self-labels "research prototype," and `ruvector` has zero existing wiring to either LatentMesh or Autogenous today. This program's timeline is exposed to their churn and to genuinely new (not integration) engineering effort on the `ruvector` side. *(Dream Machine was the top risk in the first pass of this plan — the second inventory pass found real, CI-wired promotion machinery already exists under `research-gate`/`ruvector-sota-bench`, which downgrades that specific risk substantially.)* 2. **Two of eight founding claims are unverified, and one previously-"external" component (LATTE) turns out to have zero prior art anywhere.** Treating WP7 (quarantine) and WP14 (universal CSI vocabulary) as "implement the paper" instead of "build it for the first time" will produce schedule and credibility risk if that distinction gets lost downstream (e.g., in an ADR that cites "LATTE" as if it were a real paper). 3. **ADR numbering hygiene is worse than expected and could actively cause confusion mid-program.** 283 files, true max ADR-304, with ~15+ genuine duplicate numbers (one number reused 5 times). If WP0a isn't run early, this program's own new ADRs risk colliding with existing (possibly still-duplicate) numbers, and cross-references to "ADR-X" throughout this plan and the asset map need the reader to know which of several same-numbered documents is meant. -4. **Two real dependency/compliance bugs are already blocking parts of the pipeline this program needs.** The MetaHarness `optionalDependencies` non-compliance (hard dependency on nine `@metaharness/*` packages) and the `ruvllm` HTTP-307 download bug (blocks Darwin's local-mutator live-serve e2e testing) are both concrete, small, already-known issues — cheap to fix (WP0b) but currently unfixed, and WP9 (the SHAPER-pattern evolution loop, arguably the program's centerpiece) depends on both being resolved first. +4. **A real dependency/compliance bug is already blocking part of the pipeline this program needs.** The MetaHarness `optionalDependencies` non-compliance (hard dependency on nine `@metaharness/*` packages) and the `ruvllm-cli` GGUF glob/alias bug in `get_files_to_download()` (blocks Darwin's local-mutator live-serve e2e testing) are concrete, small, already-known issues — cheap to fix (WP0b) but currently unfixed, and WP9 (the SHAPER-pattern evolution loop, arguably the program's centerpiece) depends on both being resolved first. (A third bug this plan previously tracked here, an HTTP-307 redirect in `ruvllm`'s model-download path, is already fixed on `main` — commit `946275a61`, PR #590, 2026-06-18 — and is not part of WP0b's remaining scope.) --- @@ -169,10 +207,10 @@ Each epic body: one paragraph linking to `docs/research/perpetual-intelligence-r - Title: `[PIR][WP0a] Resolve duplicate ADR numbers in docs/adr/ (ADR-272 ×5, ADR-264/252/194/144/040 ×3, ~12 more ×2)` - Body — Goal: audit `docs/adr/` and resolve every duplicate ADR number by renumbering the later-created file in each collision to the next free number above the true max (currently ADR-304), updating all in-repo references. Acceptance criteria: `ruflo-adr:adr-index` reports zero duplicate numbers; every renumbered ADR's old-number references (code comments, other ADRs, MCP tool descriptions) are updated; a CI check is added that fails on future duplicate ADR numbers. Dependencies: none — do this first, it blocks every other ADR this program creates. -**WP0b — MetaHarness dependency compliance + ruvllm HTTP-307 fix** +**WP0b — MetaHarness dependency compliance + ruvllm-cli GGUF glob/alias fix** - Repo: `ruvnet/ruvector`. Labels: `pir`, `phase-0`. -- Title: `[PIR][WP0b] Fix MetaHarness optionalDependencies non-compliance and ruvllm HTTP-307 download bug` -- Body — Goal: (1) make the nine `@metaharness/*` packages in `crates/ruvector-sota-bench/harness` genuinely optional per ADR-150's documented policy, or correct `METAHARNESS-README.md` to state the real hard-dependency requirement; (2) fix the HTTP-307 redirect bug in `ruvllm`'s model-download path blocking Darwin's local-mutator live-serve e2e tests (ADR-259). Acceptance criteria: `npm install` succeeds without the `@metaharness/*` packages present (if made optional) or documentation matches reality (if not); `ruvllm`-backed Darwin mutator passes a live-serve end-to-end test. Dependencies: none. **Blocks WP9.** +- Title: `[PIR][WP0b] Fix MetaHarness optionalDependencies non-compliance and ruvllm-cli GGUF glob/alias bug` +- Body — Goal: (1) make the nine `@metaharness/*` packages in `crates/ruvector-sota-bench/harness` genuinely optional per `METAHARNESS-README.md`'s documented policy (attributed there to an upstream metaharness ADR-150 not present in either repo — unverified; do not cite a `ruvector` or `metaharness` ADR-150, both of which are unrelated documents), or correct the documentation to state the real hard-dependency requirement; (2) fix the GGUF glob/alias mismatch in `ruvllm-cli`'s `get_files_to_download()` (`download.rs:193`, `models.rs:65`) blocking Darwin's local-mutator live-serve e2e tests (ADR-259). Note: the HTTP-307 redirect bug this issue previously also tracked is already fixed on `main` (commit `946275a61`, PR #590, 2026-06-18) and is out of scope here. Acceptance criteria: `npm install` succeeds without the `@metaharness/*` packages present (if made optional) or documentation matches reality (if not); `ruvllm`-backed Darwin mutator passes a live-serve end-to-end test. Dependencies: none. **Blocks WP9.** **WP1 — LatentMesh coordination & ADR alignment** - Repo: `ruvnet/ruvector` (primary) + linked issue in `ruvnet/LatentMesh`. Labels: `pir`, `adr`, `cross-repo`, `phase-0`. diff --git a/docs/research/perpetual-intelligence-runtime/04-verification-addendum.md b/docs/research/perpetual-intelligence-runtime/04-verification-addendum.md index 8ee72b30b..d8708c5c3 100644 --- a/docs/research/perpetual-intelligence-runtime/04-verification-addendum.md +++ b/docs/research/perpetual-intelligence-runtime/04-verification-addendum.md @@ -276,3 +276,121 @@ None remaining from the original metaharness-ADR-322 question (resolved in between `ruvnet/dream-machine` ADR-0001, `ruvector`'s ADR-282 (`research-gate`), and autogenous ADR-400/401's flywheel — WP1/WP2 own producing that reconciliation, per ADR-305 and ADR-306. + +## 8. PR #847 review corrections — a fourth research pass (adr-reviewer + asset-scout, post-merge-review) + +An adversarial review of the initial PIR ADR set (PR #847) verified every +cross-repo claim against direct clones of `ruvnet/LatentMesh`, `ruvnet/autogenous`, +`ruvnet/dream-machine`, and `ruvnet/metaharness`, and separately against a +clone of `ruvnet/ruflo` (HEAD `fa13ee4`, 2026-08-15; 177 ADRs in +`v3/docs/adr/`) that §1–§7 above did not have access to. Three findings were +blocking; this addendum records the corrected facts so future PIR work +doesn't regress to the earlier drafts' claims. + +### 8a. Autogenous ADR-401's promotion predicate is DONE, not open + +§2a above (and the earlier draft of ADR-305/ADR-315) cited ADR-401's +capability-table row 5 ("not yet one checked predicate") as the program's +residual scope. **That row is stale relative to ADR-401's own Decision +section.** ADR-401's Update 1 §3, "Converge the promotion invariant to one +predicate," is marked **DONE**: `mesh-evolve.ts` exports +`promoteAuthorized(candidate, champion, { authorized, reversible }) → +PromotionDecision`, the single gate `Promote = Better ∧ Safe ∧ Authorized ∧ +Reversible` with each conjunct independently blocking, `evolveMesh` routing +every promotion through it, proven by `test/promote-authorized.test.ts` +(all-four promotes; any three-of-four does not). ADR-315 (this program) is +rescoped accordingly: it adopts `promoteAuthorized`, it does not build or +close it. + +### 8b. "metaharness ADR-251" does not exist — corrected provenance + +ADR-306 (and this addendum's own §6, before this correction) restated +dream-machine ADR-0001's "Prior instances" citation of "metaharness ADR-251 +(MetaHarness Nightly Dream Cycle)" as fact. Direct inspection of +`ruvnet/metaharness` (HEAD `5453c8c`) finds **230 ADR files topping out at +`ADR-250-sota-proof-ladder.md`** — no ADR-251. The Nightly Dream Cycle +material instead lives in `docs/dream-cycle/` (`2026-08-13-gist.md`, +`2026-08-14-gist.md`, `LEDGER.md`), not as an ADR. ADR-306 now cites +`docs/dream-cycle/` and states the bad citation's provenance (inherited from +dream-machine ADR-0001) rather than repeating it as independently verified. + +### 8c. "ruvector ADR-150 (optionalDependencies policy)" is a misattribution + +ADR-313 (and ADR-306, and `03-program-plan.md`) cited "ruvector ADR-150" as +the source of the `optionalDependencies` policy `METAHARNESS-README.md` +claims compliance with. Checked against both clones: + +- `ruvector`'s own `ADR-150` is `ADR-150-pi-brain-ruvltra-tailscale.md` — "π + Brain + RuvLtra via Tailscale — Semantic Embedding Upgrade." Unrelated. +- `metaharness`'s own `ADR-150` is + `ADR-150-tailscale-local-frontier-concurrent-benchmarks.md`. Also + unrelated. +- `METAHARNESS-README.md` itself attributes the policy to "**ADR-150**: + MetaHarness Integration Surfaces (**upstream**)" — a document neither + clone contains. + +This is the exact failure mode ADR-305 §4 requires PIR documents to avoid +(repo-qualify every cross-repo ADR reference) reproduced inside the set +meant to enforce it. Every reference is now corrected to cite +`METAHARNESS-README.md`'s documented invariant directly, with the upstream +attribution noted as unverified rather than repeated as a resolvable +citation. + +### 8d. The ruflo ADR-322 family verified verbatim; ADR-381 needed two corrections + +A full clone of `ruvnet/ruflo` confirms the ADR-322 family exactly as this +program's ADR-306/310/312/313 cite it: + +| ADR | Title | Status | +|---|---|---| +| 322 | Adopt `@metaharness/{flywheel,darwin}` as pluggable engines behind ruflo's ADR-176 self-improvement flywheel | Accepted — phases 0–2 implemented (2026-07-28) | +| 322A | Evaluation and promotion transaction model | Accepted — implemented (`RUFLO_FLYWHEEL_TRANSACTION_V1`) | +| 322B | Darwin proposer adapter | Accepted — implemented for bounded retrieval-policy candidates (`RUFLO_FLYWHEEL_DARWIN_V1`) | +| 322C | Receipt, ledger, and verification protocol | Accepted — implemented (`RUFLO_FLYWHEEL_RECEIPT_V1`) | + +322B's separation-of-powers sentence is verbatim (`ADR-322B-darwin-proposer-adapter.md` +line 10): *"A proposer produces untrusted candidates only. It cannot issue +promotion decisions or mutate active policy."* ADR-322 line 15 reinforces it: +*"Darwin adapters remain candidate generators and never gain promotion +authority."* 322C's stack is confirmed with more precision than this +program's earlier drafts stated: canonical JSON is RFC 8785 JCS, digest is +SHA-256, signature is `Ed25519(domainPrefix || 0x00 || canonicalBytes)` +across **three distinct signing domains** (bootstrap, receipt, ledger-head — +not one), with `candidateId = SHA-256(JCS(candidate policy))` and `receiptId += SHA-256(JCS(unsigned receipt payload))`. Every authorizing term in a 322C +record is graded `recomputed`, `signature-verified`, or `trusted-assertion`. +322C line 105 also settles the ADR-103 cross-repo ambiguity this program +flagged in ADR-305: keys "use ADR-103's provider mechanism but a distinct +purpose/domain," confirming the witness-manifest ADR-103 is `ruflo`'s. + +**ADR-381 needed two corrections.** (a) **Status is Proposed, not +Accepted** (line 3, dated 2026-08-10; no supersede or later Accepted line — +earlier drafts of ADR-306/310/312 implied it was settled governance +alongside its Accepted siblings). (b) **The 0.6% figure and the `α_k = +α_total · 6/(π²k²)` allocation belong to `ruflo` PR #2956's mechanism**, +which ADR-381 *governs*, not to ADR-381's own decision. ADR-381's actual +contribution is narrower: scoping the α ledger to one stream per project +root within the ADR-322 transaction state, and `resetSequentialEvidence` — an +explicit, `confirm: true`-gated, human-reasoned evidence-epoch reset for +budget exhaustion, expiring all outstanding receipts so stale evidence +can't be replayed against a fresh budget. (c) The false-promotion bound is +**per-epoch**, not global: line 33 states the guarantee as "family-wise +false-promotion probability is ≤ α_total **per epoch**" after a reset. Any +PIR document citing this bound now states it the same way. + +### 8e. The `ruvllm` HTTP-307 bug is already fixed; the systemic lesson + +ADR-313 (and `03-program-plan.md`) cited an HTTP-307 redirect bug in +`ruvllm`'s model-download path as an open blocker. It was already fixed on +`main` before this ADR set was written (commit `946275a61`, PR #590, +2026-06-18). The actual remaining download blocker is a GGUF glob/alias bug +in `ruvllm-cli`'s `get_files_to_download()` (`download.rs:193`'s glob +pattern disagreeing with `models.rs:65`'s alias resolution). + +All three blocking findings (8a–8c) and this one share a root cause: a claim +was carried forward from a source document — an upstream ADR's stale table +row, a citation inherited from another repo's ADR, a documented-but-unlocated +upstream attribution, or an earlier bug report — without checking that +source's own current state via fix history (`git log` on the named path, +merged PRs, release notes). ADR-305 now states this as a standing +verification rule for the remainder of this program (see its Decision §6).