From 2fb7724eecdaa0ccb68681bcd064c88787ae6fbe Mon Sep 17 00:00:00 2001 From: ruv Date: Thu, 20 Aug 2026 09:07:41 -0400 Subject: [PATCH] =?UTF-8?q?docs(adr):=20fix=20review=20blockers=20on=20Wav?= =?UTF-8?q?e-2=20ADRs=20=E2=80=94=20ADR-134=20cites,=20preprint=20rule?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses the CHANGES-REQUIRED verdict on PR #868: B1: disambiguate bare "ADR-134" citations per ADR-316's slug rule (ADR-318 L44; ADR-323 trust/gates/consequences) -> "ADR-134 (witness-schema-log-format)", matching merged ADR-312's form. B2: add the preprint-reproduction rule as a labeled paragraph to ADR-319 and ADR-323 (present in the other four; PR body promised it in all six). Non-blocking cleanups folded into the same commit: - 06: fix stale pointer to 07's now-resolved "Missing input" note; add an "as of" timestamp to the #837 comment-count snapshot and cross-reference issue #862 as the acceptance test's canonical written record. - 07: correct "TRUSS/Trussed AI" -> "TRUSS/truss-agent.com" (Trussed AI is unsourced); fix the four-misattribution-instances enumeration to name all four with their real addendum sections (ADR-103 per ADR-305 §4; §5; §8b for the phantom "metaharness ADR-251"; §8c), dropping §8d which is not itself a wrong-repo-number instance; correct the agentdb surface path to crates/rvf/rvf-adapters/agentdb (WP18). - ADR-320: same agentdb path correction in Affected Repos. - ADR-323: restore the elided "not in the frozen historical list above" qualifier in the ADR-316 Decision §5 quote; apply the same four-instances and agentdb-adjacent fixes as above. Co-Authored-By: claude-flow --- ...gedworkspace-content-hash-state-binding.md | 3 +- ...shadow-execution-generated-capabilities.md | 12 +++++++ ...pattern-atomic-observation-causal-graph.md | 2 +- ...R-323-governed-pipeline-shard-placement.md | 32 ++++++++++++++----- .../06-wave2-evidence-review.md | 18 +++++++---- .../07-wave2-program-plan.md | 13 +++++--- 6 files changed, 58 insertions(+), 22 deletions(-) diff --git a/docs/adr/ADR-318-stagedworkspace-content-hash-state-binding.md b/docs/adr/ADR-318-stagedworkspace-content-hash-state-binding.md index 71528ecc2..3587129d5 100644 --- a/docs/adr/ADR-318-stagedworkspace-content-hash-state-binding.md +++ b/docs/adr/ADR-318-stagedworkspace-content-hash-state-binding.md @@ -41,7 +41,8 @@ to TRUSS in this wave (ADR-319). `ruvector` already has the durable-artifact and provenance primitives this pattern needs: RVF (`crates/rvf`, append-only crash-safe segments with canonical format, ruvector ADR-029) and RVM's witness records -(`crates/rvm`, hash-chained per privileged action, ruvector ADR-134), +(`crates/rvm`, hash-chained per privileged action, ruvector ADR-134 +(witness-schema-log-format)), formalized as the transactional memory tier in ADR-307 and anchored across layers via ADR-312's shared witness schema and cross-layer anchoring contract. ADR-312 was designed for mutation/promotion records specifically; diff --git a/docs/adr/ADR-319-truss-pattern-shadow-execution-generated-capabilities.md b/docs/adr/ADR-319-truss-pattern-shadow-execution-generated-capabilities.md index 846a02ea4..bcde03747 100644 --- a/docs/adr/ADR-319-truss-pattern-shadow-execution-generated-capabilities.md +++ b/docs/adr/ADR-319-truss-pattern-shadow-execution-generated-capabilities.md @@ -55,6 +55,18 @@ comment, or issue derived from it, and never uses bare "TRUSS" as a product, package, or crate name — the same discipline this program applied to TARL in Wave 1 (ADR-307). +**Preprint-reproduction rule** (applies uniformly across this program, per +`07-wave2-program-plan.md`): TRUSS's own reported figures (task +effectiveness 17.11%→52.94%, security rate 50.80%→100%, repair reducing +attack success with zero attack regression) describe the paper's own +benchmark and its own authors' unreleased implementation, not this +program's shadow-execution stage. This ADR treats the shadow-execution +mechanism it defines as a **candidate mutation**, not adopted prior art — +promotion of any candidate through this gate is conditioned on this +program's own `research-gate`-recomputed benchmark delta over the pre-gate +baseline, never on citing TRUSS's published numbers as if they already +describe this program's implementation. + `ruvector` already has two of the three pieces this pattern needs: ADR-311's anomaly quarantine (HMAC integrity + statistical anomaly scoring on latent-channel payloads) and ADR-315's constitutional capability-expansion diff --git a/docs/adr/ADR-320-memfuse-pattern-atomic-observation-causal-graph.md b/docs/adr/ADR-320-memfuse-pattern-atomic-observation-causal-graph.md index ddfddce58..8beba5465 100644 --- a/docs/adr/ADR-320-memfuse-pattern-atomic-observation-causal-graph.md +++ b/docs/adr/ADR-320-memfuse-pattern-atomic-observation-causal-graph.md @@ -152,7 +152,7 @@ architecture (arXiv:2608.18704) and adapting the confirmed-live ## Affected Repos -- `ruvnet/ruvector` only — `agentdb`, `crates/rvf` (continuous-latent-state +- `ruvnet/ruvector` only — `crates/rvf/rvf-adapters/agentdb`, `crates/rvf` (continuous-latent-state tier), coordinates with `latentmesh-align`-consuming code per the existing ADR-310 CI gate. Single-repo scope per `07-wave2-program-plan.md`. diff --git a/docs/adr/ADR-323-governed-pipeline-shard-placement.md b/docs/adr/ADR-323-governed-pipeline-shard-placement.md index 8e4d195ed..e54beb35c 100644 --- a/docs/adr/ADR-323-governed-pipeline-shard-placement.md +++ b/docs/adr/ADR-323-governed-pipeline-shard-placement.md @@ -11,10 +11,13 @@ **This ADR is deliberately numbered ADR-323. `ruvector`'s own ADR-322 number is skipped, not merely left unused by coincidence.** The reason is a cross-repo citation-ambiguity risk this program has already hit four -separate times (per ADR-305 §6 and ADR-313's Context: the "metaharness -ADR-322" misattribution, the ADR-150 misattribution, and two further -instances documented in `04-verification-addendum.md` §5, §8c, §8d) — -assuming the wrong repo owns an ADR number before checking. +separate times (per ADR-305 §6 and ADR-313's Context): the ADR-103 +cross-repo ambiguity (ADR-305 §4); the "metaharness ADR-322" misattribution, +resolved to `ruflo` ADR-322 (`04-verification-addendum.md` §5); the phantom +"metaharness ADR-251" citation, which does not exist at all +(`04-verification-addendum.md` §8b); and the "ruvector ADR-150" +misattribution, resolved to `ruflo` ADR-150 (`04-verification-addendum.md` +§8c) — each one assuming the wrong repo owns an ADR number before checking. **`ruflo` ADR-322** (with children 322A/322B/322C) is the single most-cited external ADR in this program: ADR-305, ADR-306, ADR-310, @@ -45,7 +48,8 @@ ADR-322"**, per ADR-316's citation rule. ADR-316's collision-check tooling (`scripts/adr-index.mjs --check`) gates on duplicate numbers, not on gaps in the sequence, so this deliberate skip does not trip that gate — confirmed against ADR-316's own Decision §5 (the check "exits non-zero if `docs/adr/` -contains a duplicate plain number," not an unused one). +contains a duplicate plain number that is not in the frozen historical list +above (or if a frozen number's file count grows)," not an unused one). ## Context @@ -95,6 +99,18 @@ released reproduction package rather than rebuilding from the paper alone. **Name collision**: no significant collision found for "pipeline-sharded inference" or the paper's likely short names in a targeted search. +**Preprint-reproduction rule** (applies uniformly across this program, per +`07-wave2-program-plan.md`): the paper's own 1.79× concurrent-throughput +figure and its 4-node/70B interactive-serving figures (5.72/6.43 tok/s) +describe the source paper's own hardware and benchmark run, not this +program's fleet. This ADR treats governed pipeline-shard placement as a +**candidate mutation**, not adopted prior art — promotion follows the same +`research-gate`-recomputed-delta discipline as every other Wave-2 item +(ADR-306): the paper's figures are the target shape this program aims to +reproduce internally, never numbers this program is entitled to cite as its +own acceptance bar without independently measuring them on its own +2-node/8B and 4-node/70B setups. + ADR-314 already implements `ruvllm`'s closed-form linear KV-cache mapper for **cross-model** migration within a single node (`kv_cache.rs`, `paged_attention.rs`, `serving/kv_cache_manager.rs`). This ADR is a distinct @@ -124,7 +140,7 @@ live `labscommunity/pipeline-sharded-inference-paper` reproduction package assignment. - **Cost** — resource/compute cost of the candidate placement. - **Trust** — node attestation and witness status (per this program's - existing RVM witness-chain discipline, ADR-134/ADR-312) — an + existing RVM witness-chain discipline, ADR-134 (witness-schema-log-format)/ADR-312) — an unattested or under-trusted node is not eligible to host a shard carrying sensitive state. - **Data residency** — placement constraints where shard state must not @@ -161,7 +177,7 @@ live `labscommunity/pipeline-sharded-inference-paper` reproduction package build. - Governing shard placement on trust/residency/hardware, not just latency/cost, extends this program's existing witness-chain and isolation - disciplines (ADR-134, ADR-312, the hosted-RVM honesty discipline from + disciplines (ADR-134 (witness-schema-log-format), ADR-312, the hosted-RVM honesty discipline from ruvector ADR-285) into the serving-placement layer, rather than treating placement as a pure performance-optimization problem. - Explicitly separating the 1.79× and 4-node/70B results prevents this @@ -194,7 +210,7 @@ live `labscommunity/pipeline-sharded-inference-paper` reproduction package latency/cost score. - **Witness-chain requirement**: node trust/attestation status consumed by the placement policy is verified via this program's existing RVM witness - chain (ADR-134, anchored per ADR-312), not a separately-trusted signal. + chain (ADR-134 (witness-schema-log-format), anchored per ADR-312), not a separately-trusted signal. - **Precision citation discipline**: the 1.79× figure is always cited as specific to the 2-node/8B-class configuration; the 4-node/70B result is always cited separately, never combined into one headline number. diff --git a/docs/research/perpetual-intelligence-runtime/06-wave2-evidence-review.md b/docs/research/perpetual-intelligence-runtime/06-wave2-evidence-review.md index 55740dc26..0386765c8 100644 --- a/docs/research/perpetual-intelligence-runtime/06-wave2-evidence-review.md +++ b/docs/research/perpetual-intelligence-runtime/06-wave2-evidence-review.md @@ -10,13 +10,17 @@ fabricate a citation, flag name collisions, and — per ADR-305 §6's fix-history rule — treat every "code is available" claim as unverified until the repository itself is checked, not just the paper's prose. -**One item could not be completed and is flagged rather than guessed**: the -brief for this wave asked for "ruv's acceptance test verbatim." That text -was not present in the Wave-2 brief as relayed to this research pass, and a -search of the tracking issue (`ruvnet/ruvector#837`, all 14 comments) found -only the priority order, not an acceptance-test statement. `07-wave2- -program-plan.md` flags this as an open item rather than inventing test -criteria — see that document's "Missing input" note. +**One item was initially incomplete and is now resolved**: the brief for +this wave asked for "ruv's acceptance test verbatim." That text was not +present in the Wave-2 brief as relayed to this research pass, and a search +of the tracking issue (`ruvnet/ruvector#837`, all 14 comments as of +2026-08-20T12:41:41Z — the issue has since accumulated further comments) +found only the priority order, not an acceptance-test statement. +`07-wave2-program-plan.md` originally flagged this as an open item rather +than inventing test criteria; ruv subsequently supplied the exact wording +directly (2026-08-20), which is now carried verbatim in +`07-wave2-program-plan.md`'s acceptance-test section and in ADR-317. Issue +#862 is the test's canonical written record. ## Summary table diff --git a/docs/research/perpetual-intelligence-runtime/07-wave2-program-plan.md b/docs/research/perpetual-intelligence-runtime/07-wave2-program-plan.md index 1cb452ea4..25bca7534 100644 --- a/docs/research/perpetual-intelligence-runtime/07-wave2-program-plan.md +++ b/docs/research/perpetual-intelligence-runtime/07-wave2-program-plan.md @@ -78,9 +78,12 @@ same as Wave 1's plan stated for ADR-305–315. **Why 322 is skipped deliberately, not just left free**: a `ruvector`-local ADR-322 would not be a filename collision (`ruflo`'s ADR-322 lives in a different repo's `v3/docs/adr/`), but this exact program has already hit the -"wrong repo owns this ADR number" failure mode four times in one document -(`04-verification-addendum.md` §5, §8c, §8d — "metaharness ADR-322" → -actually `ruflo` ADR-322; "ruvector ADR-150" → actually `ruflo` ADR-150), and +"wrong repo owns this ADR number" failure mode four times: the ADR-103 +cross-repo ambiguity (ADR-305 §4); "metaharness ADR-322" → actually +`ruflo` ADR-322 (`04-verification-addendum.md` §5); the phantom "metaharness +ADR-251" citation, which does not exist at all +(`04-verification-addendum.md` §8b); and "ruvector ADR-150" → actually +`ruflo` ADR-150 (`04-verification-addendum.md` §8c). Separately, ADR-305/306/310/312/313 already cite `ruflo` ADR-322/322A/322B/322C by number repeatedly as the flywheel-receipt/promotion authority this very program adopted. Minting an unrelated `ruvector` ADR-322 for pipeline-sharded @@ -150,7 +153,7 @@ autogenous, or RuView. Specific surfaces: - **WP15** (ADR-317): `crates/ruvector-sota-bench/harness` (vetoes.ts extension), `crates/sona/src/darwin_guard.rs` - **WP16** (ADR-318): `crates/rvf`, `crates/rvm` (extends the ADR-312 anchoring contract), `ruvector-agent-memory` - **WP17** (ADR-319): new module alongside `crates/rvm/crates/rvm-cap` (capability/tool-broker enforcement) and Darwin's mutation-proposal surface (`harness/src/darwin.ts`) -- **WP18** (ADR-320): `agentdb`, `crates/rvf` (continuous-latent-state tier), coordinates with `latentmesh-align`-consuming code per the existing ADR-310 CI gate +- **WP18** (ADR-320): `crates/rvf/rvf-adapters/agentdb`, `crates/rvf` (continuous-latent-state tier), coordinates with `latentmesh-align`-consuming code per the existing ADR-310 CI gate - **WP19** (ADR-321): `harness/src/darwin.ts`, `examples/mragent` `scorePolicy` — same surfaces WP9 already owns - **WP20** (ADR-323): `crates/ruvllm` (`kv_cache.rs`, `paged_attention.rs`, `serving/kv_cache_manager.rs` — same files WP13 touches, coordinate to avoid merge conflicts) @@ -169,7 +172,7 @@ autogenous, or RuView. Specific surfaces: 1. **Two of six papers have no confirmed upstream code (TRUSS, StagedWorkspace) — both are top-3 priority.** (MemFuse was initially suspected to lack code too; a second verification pass found and confirmed `Darwin-Agent/Mi-Memory/tree/master/MemFuse` is real and live.) WP16 and WP17 are reproduction-from-description efforts, not integration efforts, which is a materially larger scope than WP15/18/19/20's "adapt a released repo" pattern. Size these two WPs accordingly and do not schedule them as if a working reference implementation exists to port. 2. **The preprint-reproduction risk, handled ruv's way**: every one of these six papers reports numbers on its own benchmark, evaluated by its own authors. Per the "candidate mutation" framing above, none of those numbers may be cited as the acceptance bar for a promoted PIR change — only this program's own `research-gate`-recomputed delta counts. The risk is schedule pressure causing a WP to shortcut this and cite the paper's number directly; the mitigation is already structural (ADR-306's existing gate), but it depends on WP15–20 actually routing through it rather than treating it as optional given each paper's own artifact already "proves" the number. -3. **Two sharp name collisions (TRUSS/Trussed AI, MemFuse/memfuse) create real mislabeling risk in fast-moving swarm work.** Unlike Wave 1's low-risk LiveMem/iOS-app collision, both of this wave's collisions are with live products in the *same* problem domain, meaning a hurried commit message, ADR reference, or Slack-style status update reading just "TRUSS" or "MemFuse" is genuinely ambiguous to a reader who doesn't already know this program's citation-discipline rule. +3. **Two sharp name collisions (TRUSS/`truss-agent.com`, MemFuse/memfuse) create real mislabeling risk in fast-moving swarm work.** Unlike Wave 1's low-risk LiveMem/iOS-app collision, both of this wave's collisions are with live products in the *same* problem domain, meaning a hurried commit message, ADR reference, or Slack-style status update reading just "TRUSS" or "MemFuse" is genuinely ambiguous to a reader who doesn't already know this program's citation-discipline rule. 4. **The pipeline-shards headline number requires care to cite correctly.** The 1.79× figure and the 4-node/70B configuration are two separate results in the source paper; WP20 and any ADR-323 text must keep them separate, per the conflation flag in `06-wave2-evidence-review.md`. 5. **The novelty claim is not proven, only not-yet-falsified.** If a full 5-property match surfaces later (the evidence review's caveat explicitly says this search wasn't exhaustive), it would not block this wave's WPs — they're framed as internal candidate mutations either way — but it would change how this program is allowed to describe its own novelty in any public-facing ADR or status update. 6. **The Wave-2 acceptance test (now resolved, see above) is a combined-effect test spanning three ADRs (317/318/319).** WP15–17 issues should reference it explicitly rather than each WP inventing its own narrower success criterion, and no WP should claim the combined test is satisfied until all three of WP15/16/17 have landed and been benchmarked together against a HarnessRisk rerun.