Merge docs/refine-2026-06: documentation refinement pass

Brings the ccode-ultracode docs engagement (4 waves + 1 reconciliation)
into main: channel-3 provenance correction, gap-honesty, dead-link fixes,
archived point-in-time wave reviews (with redirect stubs), new OVERVIEW.md,
ADR-014 indexing. Reconciled the main-lags-master foot-gun guidance to its
RESOLVED state (main is canonical and synced). Docs-only; no source touched.

BACKLOG.md

@@ -71,8 +71,8 @@ Updated 2026-05-29 to reflect shipped waves (ingestion, diloco, packaging, datag
 **Acceptance**:
 1. `pyproject.toml` at repo root, package name `composer_replication`.
 2. `composer_replication/` dir with `__init__.py` re-exporting `composer_total_loss`, `OPSDLoss`, `TeacherReplayBuffer`, `compose_loss`, `TraceIngester`, etc.
-3. `examples/qwen3_05b_quickstart/` with end-to-end script that loads model, runs 10 training steps, prints loss curve.
-4. README quickstart updated to `pip install -e .` + `python examples/qwen3_05b_quickstart/run.py`.
+3. `examples/qwen_05b_quickstart/` with end-to-end script that loads model, runs 10 training steps, prints loss curve.
+4. README quickstart updated to `pip install -e .` + `python examples/qwen_05b_quickstart/run.py`.
 5. `pip install -e .` succeeds and quickstart runs end-to-end on CPU.
 
 ### Post-Skeleton Waves (Datagen, Alignment, Quality)

README.md

@@ -28,11 +28,14 @@ pretty_name: "Composer 2.5 Replication Framework — Research Synthesis"
 > **Author:** [Codeseys](https://huggingface.co/Codeseys)
 > **Goal:** Replicate Cursor's [Composer 2.5](https://cursor.com/blog/composer-2-5) (a post-trained Kimi K2.5 specialised for agentic coding) on **any HuggingFace causal LM with a chat template** (Qwen, Llama, Mistral, DeepSeek, Phi, Gemma families), using a synthesis of decentralized RL post-training techniques. *(LM-CE + DPO channels empirically verified on Qwen2.5-0.5B-Instruct via Spike 006; the SDPO channel is verified via the `compose_loss` integration test suite + the `examples/gsm8k_grpo_with_sdpo/` and `examples/sdpo_with_real_traces/` end-to-end smokes — Spike 006's run zeroed the SDPO channel because the hint-context shape didn't align with the student context, the same alignment discipline `ComposerDataCollator` enforces in production. Encoder-decoder models, base models without chat templates, and VLMs are out of scope for v0.)*
 
-This repository is the **"paper of the project"** — it is the methodology / research / framework specification for an open replication of Cursor's Composer 2.5 system, plus a **novel multi-teacher trace-replay distillation channel** that stacks on top of the Composer recipe.
+This repository is the **"paper of the project"** — it is the methodology / research / framework specification for an open replication of Cursor's Composer 2.5 system, plus a **novel multi-teacher trace-replay distillation channel** that stacks on top of the Composer recipe (this channel is the *framework's own addition* — it is **not** part of Cursor's actual recipe; see [ADR-014](docs/adrs/ADR-014-policy-optimization-objective-menu.md)).
+
+> 🧭 **New here?** Read [`docs/OVERVIEW.md`](docs/OVERVIEW.md) for a 5-minute, honestly-scoped tour: what this is, the three channels with their real provenance, what's proven, and what's still gapped.
 
 ## Install
 
 ```bash
+# `main` is canonical and synced with `master` — a fresh clone works as-is.
 pip install -e .
 python examples/qwen_05b_quickstart/run.py
 ```
@@ -163,7 +166,7 @@ The novel contribution is channel (3) — no published work systematically repla
 | Phase | Timeline | Goal | Trained variant repo | Data repo |
 |---|---|---|---|---|
 | **v0.0 spike** | 1–2 weeks | Prove trace-replay-DPO beats plain GRPO on Qwen3-7B + SWE-bench-lite | `Codeseys/composer-replication-qwen3-7b-v0` | `Codeseys/composer-replication-traces-v0` |
-| **v0.1** | 1–2 months | Full Composer recipe (RLVR + hint-distill + trace-replay) on Qwen3-32B + Feature Deletion env. Match Cursor's ~50% SWE-bench-multilingual at 32B scale. | `Codeseys/composer-replication-qwen3-32b-v1` | `Codeseys/composer-replication-traces-v1` |
+| **v0.1** | 1–2 months | Full Composer recipe (RLVR + hint-distill, i.e. channels 1–2 = Dr.GRPO + SDPO) **plus** the framework's own additive trace-replay-DPO channel, on Qwen3-32B + Feature Deletion env. Match Cursor's ~50% SWE-bench-multilingual at 32B scale. *(trace-replay-DPO is our addition, not part of Cursor's recipe — see [ADR-014](docs/adrs/ADR-014-policy-optimization-objective-menu.md).)* | `Codeseys/composer-replication-qwen3-32b-v1` | `Codeseys/composer-replication-traces-v1` |
 | **v0.2** | 3–6 months | Decentralized scaling: Streaming DiLoCo + SHARDCAST + Monarch. Multi-cluster reproduction of v0.1 across **Modal + HF Jobs + on-prem** via the new serverless-DiLoCo executor abstraction (ADR-005). | `Codeseys/composer-replication-qwen3-32b-decentralized` | (re-uses v1 data) |
 
 Each variant will get its own model repo (LoRA adapters or full fine-tunes) per the [HF multi-artifact research project layout](https://huggingface.co/docs/hub/repositories). This methodology repo will be linked from each variant's README and via an HF Collection once v0.0 produces a result.

docs/ALTERED_MINDS_TIE_IN.md

@@ -111,11 +111,24 @@ only — never rationale style, so distorted-but-persuasive reasoning is not
 rewarded), and `dual_kl_logger` (logs KL-to-altered-init **and** KL-to-base each
 step — the washout-vs-amplification instrument).
 
-Train for ~500 steps per arm on a single GPU (Qwen-0.5B feasibility-test
-already confirmed; for Llama-8B, use Modal + the framework's `ServerlessExecutor`
-per ADR-005 — local 5090 is too small). The real 8B/LMA-checkpoint run remains
-**user-gated** (it spends grant budget) — ADR-013 ships the capability, proven
-CPU-only on a small model (`examples/altered_minds_channel_ladder/`).
+Train for ~500 steps per arm on a single GPU. **Runnability today (2026-06):**
+only **A1 (GRPO-only)** has a real Modal runner — [ADR-014](adrs/ADR-014-policy-optimization-objective-menu.md)
+records that "the A1 run used `dr_grpo`" and that wiring the `objective=` menu through the
+rest of the ladder runners is an open follow-up (Qwen-0.5B feasibility-test confirmed;
+for Llama-8B use Modal + the framework's `ServerlessExecutor` per ADR-005 — local 5090
+is too small). **A2 (SDPO) / A3 (replay-DPO) / A4 (combined) are scaffold + plan-builder
+only**: running them on a real 8B checkpoint additionally needs a real error-trace SDPO
+dataset, a replay-DPO preference corpus, and an A100 entrypoint that don't exist yet —
+none of those is a closed artifact today. The real 8B/LMA-checkpoint run is *additionally*
+**user-gated** (it spends grant budget). [ADR-013](adrs/ADR-013-lma-integration-channel-ladder.md)
+ships the ladder scaffolding + the A1 capability, proven CPU-only on a small model
+(`examples/altered_minds_channel_ladder/`); its sole remaining acceptance-gate box is that
+user-gated real-spend go/no-go.
+
+> **strip_thinking × SDPO foot-gun (A2/A4).** When the SDPO arms become runnable on real
+> agent traces, SDPO REQUIRES `strip_thinking=False`: ~67% of error-recovery turns are
+> pure thinking, so stripping them yields empty SDPO masks (the channel silently
+> contributes nothing). Keep thinking tokens in the context for any SDPO-active arm.
 
 ### Phase 4 — re-evaluate
 

docs/DEEP_WORK_LOOP_LOG.md

@@ -1,47 +1,7 @@
 # Deep Work Loop Log — Composer 2.5 Replication Framework
 
-Started: 2026-05-26
-Operator: Codeseys (Hermes Agent autonomous loop)
-Skill: `deep-work-loop` v1.0.0
-
-## Vision
-
-> Take any HuggingFace model → further RL train it using:
-> 1. RLVR (tests-pass reward),
-> 2. SDPO/hint-distillation (Composer 2.5's "targeted RL with textual feedback"),
-> 3. multi-teacher trace-replay DPO,
-> integrated against TRL/VeRL/OpenEnv with DiLoCo-style outer loop sync.
->
-> Output: a published, reproducible framework — the "Composer 2.5 replication" the open ecosystem is missing.
-
-## Starting state
-
-- HEAD: `040eff8` (Wave 6: vision validation self-audit, 5/10 scorecard)
-- Tests: 38/38 green in `spikes/005-integrated-trainer-skeleton/`
-- Working tree: clean
-
-## Phase ledger
-
-| Phase | Description | Status | Started | Done |
-|---|---|---|---|---|
-| 1 | commit-state | ✅ | 2026-05-26 | 2026-05-26 |
-| 2 | backlog-audit (BACKLOG.md from VISION_VALIDATION) | ✅ | 2026-05-26 | 2026-05-26 |
-| 3 | parallel-research (3 subagents) | 🟡 | 2026-05-26 |  |
-| 4 | architect with ADRs (ADR-001..003) | ⏳ |  |  |
-| 5 | plan in waves (W7–W10) | ⏳ |  |  |
-| 6 | execute W7 — Spike 006 (real HF model smoke) | ⏳ |  |  |
-| 7 | execute W8 — Spike 007 (real trace ingestion) | ⏳ |  |  |
-| 8 | execute W9 — Spike 008 (DiLoCo smoke) | ⏳ |  |  |
-| 9 | execute W10 — packaging | ⏳ |  |  |
-| 10 | (Modal-gated) Spike 002a-mini real GPU smoke | ⏳ |  |  |
-| 11 | cross-model-final-review | ⏳ |  |  |
-| 12 | update scorecard + push | ⏳ |  |  |
-
-## Constraints
-
-- Verify ALL claims against primary sources (Wave 2 lesson — subagent synthesis is not evidence).
-- Tests must pass before commit.
-- Memory L1 is at 99% — write to L2 wiki + L3 fact_store, not L1.
-- Modal budget: $20 hard cap for this loop. Anything more goes to user for approval.
-- No `upload_file` mixing with `git push` — `git push hf master:main` only.
-- Commit messages via `-F /tmp/<wave>-commit-msg.txt`.
+> **📦 Archived (2026-06-08).** This running log of the deep-work-loop sessions has
+> been moved to [`docs/_archive/DEEP_WORK_LOOP_LOG.md`](_archive/DEEP_WORK_LOOP_LOG.md).
+> It is preserved verbatim for provenance but is superseded by the current
+> [`docs/METHODOLOGY.md`](METHODOLOGY.md) and [`BACKLOG.md`](../BACKLOG.md). See
+> [`docs/_archive/README.md`](_archive/README.md) for the archive index.

docs/HF_REPO_LAYOUT.md

@@ -17,7 +17,7 @@ When the v0.0 spike produces a result, the following repos will be created:
 | Repo | Type | Created when | Contents |
 |---|---|---|---|
 | `Codeseys/composer-replication-traces-v0` | dataset | v0.0 spike data is collected | 100 frozen agentic-coding traces (JSON), used for trace-replay-distillation experiments |
-| `Codeseys/composer-replication-qwen3-7b-v0` | model | v0.0 spike produces a checkpoint | LoRA adapter or full fine-tune of Qwen3-7B trained with GRPO + trace-replay-DPO |
+| `Codeseys/composer-replication-qwen3-7b-v0` | model | v0.0 spike produces a checkpoint | LoRA adapter or full fine-tune of Qwen3-7B trained with Dr.GRPO + the framework's own additive trace-replay-DPO research channel (channel 3 is our addition, **not** part of Cursor's Composer recipe — see [ADR-014](adrs/ADR-014-policy-optimization-objective-menu.md)) |
 | `Codeseys/composer-replication-qwen3-7b-v0-baseline` | model | v0.0 spike produces a baseline checkpoint | Same training, plain GRPO only (A/B comparison) |
 
 After v0.1:
@@ -26,7 +26,7 @@ After v0.1:
 |---|---|---|
 | `Codeseys/composer-replication-traces-v1` | dataset | Larger trace corpus + Feature-Deletion environment seed repos |
 | `Codeseys/composer-replication-feature-deletion-env-v1` | dataset | Repos with passing tests, with deletion masks for the env to apply |
-| `Codeseys/composer-replication-qwen3-32b-v1` | model | Full Composer-recipe v1 trained variant |
+| `Codeseys/composer-replication-qwen3-32b-v1` | model | Full Composer-channel (Dr.GRPO + SDPO) v1 trained variant, combined with the framework's additive trace-replay-DPO research channel (trace-replay is our addition, not Composer's recipe) |
 
 All trained-variant repos will:
 - Link back to **this repo** (`Codeseys/composer-replication-framework`) in their `README.md` as the methodology source.

docs/INTEGRATION_RECIPES.md

@@ -978,7 +978,7 @@ adapter boundary, not because the loss math is wrong.
 - ADRs:
   [`docs/adrs/ADR-005-serverless-diloco.md`](adrs/ADR-005-serverless-diloco.md),
   [`docs/adrs/ADR-006-rl-frameworks.md`](adrs/ADR-006-rl-frameworks.md),
-  [`docs/adrs/ADR-007-distillation-losses.md`](adrs/ADR-007-distillation-losses.md)
+  [`docs/adrs/ADR-007-self-distillation-losses.md`](adrs/ADR-007-self-distillation-losses.md)
 
 ---
 

docs/OVERVIEW.md

@@ -0,0 +1,97 @@
+# Overview — Composer 2.5 Replication Framework (5-minute read)
+
+*Current through [ADR-014](adrs/ADR-014-policy-optimization-objective-menu.md) (2026-06). For
+the front-door pitch see [`README.md`](../README.md); for the honest gap list see
+[`BACKLOG.md`](../BACKLOG.md); for the clause-by-clause vision audit see
+[`docs/VISION_VALIDATION.md`](VISION_VALIDATION.md).*
+
+## What it is
+
+An **open, methodology-first replication of Cursor's [Composer 2.5](https://cursor.com/blog/composer-2-5)**
+recipe — the post-training pipeline that turned a Kimi-K2.5 MoE base into a strong agentic
+coder — generalized so it runs on **any HuggingFace causal LM with a chat template** (Qwen,
+Llama, Mistral, DeepSeek, Phi, Gemma families). It ships as an installable Python package
+(`pip install -e .` → `composer_replication`) plus a research corpus (ADRs, deep-dives,
+recipes). Encoder-decoder models, base models without chat templates, and VLMs are out of
+scope for v0.
+
+This repo is the **methodology repo** ("the paper of the project"). Trained-variant model
+repos and trace datasets are split out per [`docs/HF_REPO_LAYOUT.md`](HF_REPO_LAYOUT.md).
+
+## The three channels — with honest provenance
+
+The framework composes a single training loss out of three additive channels. **Two replicate
+Cursor's published recipe; the third is the framework's own research addition.** Getting this
+provenance right is the whole point — see [ADR-014](adrs/ADR-014-policy-optimization-objective-menu.md).
+
+| # | Channel | What it is | Provenance |
+|---|---|---|---|
+| **1** | **Base policy optimization** | RL on verifiable rewards (RLVR). Default **Dr.GRPO**, now a **selectable menu** (`make_po_config(objective=…)` over `{grpo, dr_grpo, bnpo, dapo, gspo, cispo}`, per ADR-014). | ✅ **Genuine replication.** Composer 2's report (arXiv:2603.24477) resolves the base objective as Dr.GRPO. |
+| **2** | **SDPO self-distillation** | Composer's "targeted RL with textual feedback": insert a hint into the context → use that hint-conditioned forward pass as a *self-teacher* → on-policy KL pulls the student toward it at the error turn. Published as SDPO/OPSD (arXiv:2601.20802 / 2601.18734, MIT code). | ✅ **Genuine replication.** This is Composer 2.5's headline trick; Cursor cites the SDPO/OPSD papers in the blog's footnote 1. |
+| **3** | **Trace-replay-DPO** | Replay each step of a frozen agentic trace with N external teachers; turn teacher (dis)agreement into DPO preference pairs. A deliberate β-gated washout probe in the A0→A4 channel ladder ([ADR-013](adrs/ADR-013-lma-integration-channel-ladder.md)). | ⚠️ **The framework's OWN additive research channel — NOT part of Cursor's recipe.** Composer's primary sources contain no DPO, no preference pairs, no reward models, no multiple teachers. Stacks *on top of* the genuine replication; it does not define it. |
+
+> **Read this before citing the framework.** Any statement of the form "Composer does
+> trace-replay-DPO" or "the replication target includes channel 3" is **wrong**. Cursor's
+> recipe = channels 1 + 2. Channel 3 is our addition, and the docs are careful to say so.
+
+The full loss (verification-harness form) is `total = lm_ce + α·sdpo_jsd + β·trace_replay_dpo`;
+production uses `ComposerReplicationTrainer._compute_loss` (a real `trl.GRPOTrainer` subclass),
+where channel 1 is real GRPO rather than the LM-CE stub. See
+[`docs/USER_GUIDE.md`](USER_GUIDE.md) and [`docs/COMPOSER_RECIPE_MAPPING.md`](COMPOSER_RECIPE_MAPPING.md).
+
+## What's proven
+
+- **CPU SDPO-fires.** On real Qwen2.5-0.5B-Instruct, the SDPO channel demonstrably fires
+  (`sdpo_jsd > 0`) and SDPO-on vs SDPO-off totals differ — the "is the loss decrease just
+  memorization?" critique is closed (Spike 006-strict).
+- **Real GPU run.** Qwen2.5-0.5B in bf16 on a local 5090 (sm_120): 50 steps, loss
+  0.7354 → 0.00034, 5.31 GB peak VRAM (Spike 002a-mini).
+- **A1 8B-ladder Modal run.** The GRPO-only arm (A1) of the LMA channel ladder has a real
+  Modal runner and has been run with `dr_grpo`.
+- **GSM8K GRPO.** The `examples/gsm8k_grpo*` end-to-end examples exercise the production
+  trainer on a real reasoning benchmark.
+- **Economic feasibility of channel 3.** 150 real OpenRouter calls, $0.98/trace mean, 0
+  errors (Spike 001).
+- **Installable + tested.** `pip install -e .` works; **115 passing tests + 1 skip-marked**
+  (canonical count: [`docs/V1_V8_COVERAGE.md`](V1_V8_COVERAGE.md)).
+
+## What's gapped (honest, NOT closed)
+
+1. **Docker / TorchForge substrate E2E** is **hardware-blocked** — the test exists and skips
+   cleanly, but there is no local multi-GPU rig to run the orchestrator layer end-to-end.
+2. **The full 8B LMA channel ladder (A2–A4) is not yet runnable.** Only **A1 (GRPO-only)**
+   has a real Modal runner. **A2 (SDPO) / A3 (replay-DPO) / A4 (combined)** are scaffold +
+   plan-builder only — running them on a real 8B checkpoint additionally needs a real
+   error-trace SDPO dataset, a replay-DPO preference corpus, and an A100 entrypoint that
+   don't exist yet. The real 8B run is *additionally* user-budget-gated.
+3. **The empirical question** — does the method actually beat plain GRPO at scale? — is the
+   GPU-budget-gated v0.1 work (Spikes 002b/003/004) and remains open by design.
+
+See [`BACKLOG.md`](../BACKLOG.md) for the live gap list and [`docs/TROUBLESHOOTING.md`](TROUBLESHOOTING.md)
+for known foot-guns.
+
+## Foot-guns worth knowing on day one
+
+- **Branch sync (resolved 2026-06-09).** `main` is canonical and kept in sync with `master`,
+  so a fresh Hub clone of `main` installs the complete tree. If you ever `ImportError` on
+  `make_dr_grpo_config`, your clone is stale (`git fetch && git checkout main`). Historically
+  `main` lagged `master`; that's fixed as long as both stay synced.
+- **`strip_thinking` × SDPO.** On real agent traces, SDPO requires `strip_thinking=False`:
+  ~67% of error-recovery turns are pure thinking, so stripping them yields empty SDPO masks.
+- **KL estimator delta.** TRL uses the **k3** estimator; Composer's report describes **k1**.
+  This is a documented, intentional delta — the framework does not silently claim k1 parity.
+- **`compose_loss` is the verification harness, not production.** Its channel-1 is an LM-CE
+  stub, not real GRPO. Production training is `ComposerReplicationTrainer`.
+
+## Where to go next
+
+| You want to… | Read |
+|---|---|
+| Pitch / status / roadmap | [`README.md`](../README.md) |
+| Run it end-to-end | [`docs/USER_GUIDE.md`](USER_GUIDE.md) |
+| Wire the loss into TRL / VeRL / PRIME-RL / DiLoCo / Monarch | [`docs/INTEGRATION_RECIPES.md`](INTEGRATION_RECIPES.md) |
+| Exact kwargs / signatures | [`docs/API_REFERENCE.md`](API_REFERENCE.md) |
+| Why each design decision | [`docs/adrs/README.md`](adrs/README.md) |
+| How Cursor's recipe maps to our components | [`docs/COMPOSER_RECIPE_MAPPING.md`](COMPOSER_RECIPE_MAPPING.md) |
+| Honest gaps / open work | [`BACKLOG.md`](../BACKLOG.md), [`docs/VISION_VALIDATION.md`](VISION_VALIDATION.md) |
+| Fix a broken install / run | [`docs/TROUBLESHOOTING.md`](TROUBLESHOOTING.md) |

docs/USER_GUIDE.md

@@ -62,6 +62,13 @@ cd composer-replication-framework
 pip install -e .
 ```
 
+> **Branch note (resolved 2026-06-09).** `main` is the canonical branch and is kept in
+> sync with `master` (`main == master`). A fresh clone of `main` has the complete tree
+> (incl. `make_dr_grpo_config` / `make_po_config`), so no branch switch is needed.
+> Historically `main` lagged `master` — if you ever see an `ImportError` on those symbols,
+> the clone is stale; `git fetch && git checkout main` (or pin a current SHA) fixes it.
+> See [`docs/HF_REPO_LAYOUT.md`](HF_REPO_LAYOUT.md).
+
 That gets you `torch>=2.0` + `transformers>=4.46` and is enough for the
 verification harness on CPU (sections 3, 5, 6).
 

docs/VISION_VALIDATION.md

@@ -1,11 +1,28 @@
 # Vision Validation: Does the Framework Encapsulate the Original Brief?
 
-> **## Status as of 2026-05-29**
-> The framework is past-skeleton: 8 subpackages (`composer_replication/*`), 210 passing tests, and operational end-to-end examples (`gsm8k_grpo`, `sdpo_with_real_traces_production`). The 3-channel loss, layered hint-generation, trace-ingestion, and DiLoCo have all shipped and been cross-family reviewed. 
+> **## Status as of 2026-06 (current through ADR-014)**
+> The framework is past-skeleton: 8 subpackages (`composer_replication/*`), 115 passing
+> tests + 1 skip-marked (see [`docs/V1_V8_COVERAGE.md`](V1_V8_COVERAGE.md) for the
+> canonical count), and operational end-to-end examples (`gsm8k_grpo`,
+> `sdpo_with_real_traces_production`). The 3-channel loss, layered hint-generation,
+> trace-ingestion, and DiLoCo have all shipped and been cross-family reviewed. The base
+> RL objective is now a **selectable menu** (default Dr.GRPO; ADR-014) rather than
+> hardcoded. **Channel 3 (trace-replay-DPO) is the framework's own additive research
+> channel — not part of Cursor's Composer recipe** (Composer = channels 1 Dr.GRPO + 2
+> SDPO only; ADR-014).
 > 
-> **Two remaining honest gaps:** 
-> 1. Docker/TorchForge substrate E2E is hardware-blocked (lacking local multi-GPU rig for the orchestrator layer). 
-> 2. Real LMA full-scale run (8B model, 10k SWE-bench traces) is user-budget-gated.
+> **Two remaining honest gaps (NOT closed):** 
+> 1. Docker/TorchForge substrate E2E is hardware-blocked — the test exists and skips
+>    cleanly, but lacking a local multi-GPU rig the orchestrator layer is unrun.
+> 2. The 8B LMA channel-ladder is **not fully runnable today**: only **A1 (GRPO-only)**
+>    has a real Modal runner — [ADR-014](adrs/ADR-014-policy-optimization-objective-menu.md)
+>    records that "the A1 run used `dr_grpo`" and that threading the `objective=` menu
+>    through the rest of the ladder runners is an open follow-up. **A2 (SDPO) / A3
+>    (replay-DPO) / A4 (combined)** are scaffold + plan-builder only; running them on a
+>    real 8B checkpoint additionally needs a real error-trace SDPO dataset, a replay-DPO
+>    preference corpus, and an A100 entrypoint that don't exist yet. The real 8B run is
+>    *additionally* user-budget-gated (the sole remaining acceptance-gate box in
+>    [ADR-013](adrs/ADR-013-lma-integration-channel-ladder.md)).
 
 > **Status:** Self-audit, 2026-05-25 (Wave 6).
 > **Question:** Does what we've built reflect what was originally asked for, or did we drift?
@@ -259,7 +276,7 @@ In recommended-do-next order:
 1. **Spike 006 (real-HF-model smoke)** — half a day, CPU-only. Closes V8's biggest credibility gap and surfaces any tokenizer / chat-template / vocab-size issues hiding in the skeleton. *Highest value per hour.*
 2. **Spike 007 (real-trace ingestion)** — 1 day, CPU + ~$5 OpenRouter. Closes V5's real-vs-synthetic gap. Picks one source (Claude Code session JSONL? Cline transcripts?) and writes the adapter.
 3. **Soften over-claims in README and paper** — half-hour. README: "TRL coded, VeRL design-only." Paper: "any causal LM with a chat template." `verl_path/README.md`: add `STATUS: design-only — validate via spike 002b before production use`.
-4. **Wave 7 (packaging)** — half a day, after 006 + 007 land. `pyproject.toml` + `examples/qwen3_05b_quickstart/` directory + entry-point exposure.
+4. **Wave 7 (packaging)** — half a day, after 006 + 007 land. `pyproject.toml` + `examples/qwen_05b_quickstart/` directory + entry-point exposure.
 5. **Spike 008 (Streaming DiLoCo smoke)** — 2 days, CPU-only. Closes V2's biggest deviation from the brief. Lowest priority because the deferral is technically defensible, but worth doing for completeness.
 
 Items 3 + 4 are documentation/packaging chores. Items 1 + 2 + 5 are real engineering. None require GPU budget. Total: ~5 days of sequential effort to take the framework from 5/10 to 9/10 vision encapsulation.

docs/WAVE_COMPOSER_DATAGEN_RL_2026-05-29.md

@@ -1,75 +1,9 @@
 # Wave: Composer 2.5 data-gen + targeted-RL textual-feedback (2026-05-29)
 
-> Deep-work-loop wave bringing Composer 2.5's **dataset generation** and
-> **targeted RL with textual feedback** into the framework, per Codeseys'
-> directive. This doc encapsulates what shipped and ties it to the ask.
-
-## The ask (verbatim intent)
-
-> "make sure that our framework for data-generation and massive deep RL similar
-> to composer 2.5 is able to … train a model like nanochat on modal … also …
-> diloco … bring the composer 2.5 blog's discussion on dataset generation into
-> the fray … the composer 2.5 RL method of targeted RL with textual feedback
-> should also be included in the RL framework as well as the dataset generation
-> framework."
-
-## What shipped (all on `hf/master`)
-
-| Capability | Status | Artifact |
-|---|---|---|
-| **Targeted RL w/ textual feedback** (SDPO) live in a Dr. GRPO loop | ✅ ADR-008 accepted | `trainer/composer_trainer.py` (`make_dr_grpo_config`, strict SDPO alignment), `examples/composer_grpo_sdpo_smoke/` |
-| **Hint generation** (the unstated #1 gap) — layered generator | ✅ ADR-009 accepted | `hint_generator.py` (Template→RawError→LLMJudge→sibling-bootstrap, `as_collator_hook`) |
-| **Dataset generation** (Feature Deletion) | ✅ ADR-010 accepted | `composer_replication/datagen/` (env, sandbox+safeguards, monitor, curriculum, validator, SWE-substrate adapter) |
-| nanochat-on-Modal + DiLoCo A/B | ✅ (prior wave, same session) | DiLoCo tied vanilla within noise; SFT ChatCORE 0.3076; RL Pass@1 doubled |
-| SDPO loss math end-to-end on real traces | ✅ (prior wave, same session) | `examples/sdpo_real_trace_train_smoke/` |
-
-## Key research resolutions (5 docs, `research/06-10`)
-
-- **RL algorithm = Dr. GRPO** (Composer 2 tech report arXiv:2603.24477): length-standardization removed, no std-dev advantage norm, Adam, single-epoch, k1 (`−log r`) KL. TRL 1.5.0 supports this natively (`loss_type="dr_grpo"`, `scale_rewards="none"`).
-- **Hint generation is unstated in every Cursor artifact** — so the SDPO/OPSD reconstruction is the legitimate path, not a missed detail. SDPO's "successful-rollout-as-implicit-feedback" is the bootstrap fallback.
-- **Composer 2 hint-free behavior-shaping alternative** documented (aux scalar rewards + nonlinear length/effort penalty) for when hints aren't available.
-- Corrections to the mapping doc: optimizer Adam (not Muon — 2.5-blog-only); sharding FSDP+CP+decoupled-EP (not HSDP).
-
-## Test posture
-
-- 187 passed / 16 skipped across the full package (no regressions).
-- New: 7 (Dr.GRPO config + SDPO alignment), 12 (layered hints), 19 (datagen).
-- The SDPO channel is proven both as loss-math-on-real-traces AND wired into a live `trl.GRPOTrainer` Dr. GRPO step.
-
-## Reusable for the adjacent project
-
-`composer_replication.datagen` is the data-gen primitive Codeseys wanted for
-another project: **"invert a solved-repo dataset into a reimplement-to-pass
-verifiable-reward task,"** with reward-hacking safeguards and an online
-difficulty curriculum. `SweBenchAdapter` makes any SWE-bench-shaped dataset
-(SWE-Gym, R2E-Gym, SWE-rebench — tens of thousands of tasks) a drop-in source.
-
-## Owed / unblocked-by (constraints this wave hit)
-
-- **Cross-family adversarial ADR review** (GPT-5.5 / Gemini 3.1 Pro / DeepSeek
-  V4 Pro / Kimi K2.6 / Grok 4.3) — ✅ **DONE 2026-05-29** once OpenRouter credits
-  were restored. 4/5 clean reviews (Kimi starved its budget). Verdicts: ADR-008
-  3-REJECT/1-fix, ADR-009 unanimous-fix, ADR-010 3-REJECT/1-fix — the REJECTs all
-  amounted to "accepted-status outran the evidence," not "design is wrong." The
-  review **caught a real policy-corrupting P0 the solo pre-mortem missed**: the
-  SDPO alignment guard was a shape-check that let hint-shifted tokens silently
-  misalign. That plus 6 other convergent defects (sandbox scrub unimplemented,
-  curriculum partial-reward→full-pass, reward_fn truncation, shell injection,
-  LLM-judge cache non-determinism, scale_rewards assert dup) were **fixed and
-  tested** (192 pass / 16 skip, was 187). Full synthesis + the 4 reviews:
-  `docs/reviews/cross-family-adr-008-009-010-2026-05-29/`. Each ADR now carries a
-  "Post-acceptance cross-family review" section documenting fixed vs open items.
-- **Live Docker substrate-inversion e2e** for ADR-010 (pull one SWE-bench-Lite
-  image, run the 4 gates against it) — STILL deferred (no Docker in the CPU dev
-  env). The review confirmed this is the gate that matters: it closes the
-  remaining OPEN findings (real reachability/provenance, FakeSandbox-tautology
-  objection). Marked `[~]` in ADR-010. Needs a box with Docker + a SWE-bench-Lite
-  image.
-- Gateway restarted 6× during the original wave; all work kept durable via
-  phase-boundary commits + detached `systemd-run` scopes.
-
-## Commit trail
-
-`7090729` (SDPO smoke) → `6049d00` (research) → `36ab61e` (ADRs) →
-`bde5c5e` (ADR-008 code) → `2a34df4` (ADR-008 smoke+accept) →
-`84740d4` (ADR-009) → `9336af3` (ADR-010).
+> **📦 Archived (2026-06-08).** This point-in-time wave log has been moved to
+> [`docs/_archive/WAVE_COMPOSER_DATAGEN_RL_2026-05-29.md`](_archive/WAVE_COMPOSER_DATAGEN_RL_2026-05-29.md).
+> It is preserved verbatim for provenance but is superseded by the current
+> [`docs/METHODOLOGY.md`](METHODOLOGY.md), [`BACKLOG.md`](../BACKLOG.md), and the
+> accepted ADRs (notably [ADR-008](adrs/ADR-008-drgrpo-sdpo-live-channel.md) and
+> [ADR-014](adrs/ADR-014-policy-optimization-objective-menu.md)). See
+> [`docs/_archive/README.md`](_archive/README.md) for the archive index.

docs/_archive/DEEP_WORK_LOOP_LOG.md

@@ -0,0 +1,47 @@
+# Deep Work Loop Log — Composer 2.5 Replication Framework
+
+Started: 2026-05-26
+Operator: Codeseys (Hermes Agent autonomous loop)
+Skill: `deep-work-loop` v1.0.0
+
+## Vision
+
+> Take any HuggingFace model → further RL train it using:
+> 1. RLVR (tests-pass reward),
+> 2. SDPO/hint-distillation (Composer 2.5's "targeted RL with textual feedback"),
+> 3. multi-teacher trace-replay DPO,
+> integrated against TRL/VeRL/OpenEnv with DiLoCo-style outer loop sync.
+>
+> Output: a published, reproducible framework — the "Composer 2.5 replication" the open ecosystem is missing.
+
+## Starting state
+
+- HEAD: `040eff8` (Wave 6: vision validation self-audit, 5/10 scorecard)
+- Tests: 38/38 green in `spikes/005-integrated-trainer-skeleton/`
+- Working tree: clean
+
+## Phase ledger
+
+| Phase | Description | Status | Started | Done |
+|---|---|---|---|---|
+| 1 | commit-state | ✅ | 2026-05-26 | 2026-05-26 |
+| 2 | backlog-audit (BACKLOG.md from VISION_VALIDATION) | ✅ | 2026-05-26 | 2026-05-26 |
+| 3 | parallel-research (3 subagents) | 🟡 | 2026-05-26 |  |
+| 4 | architect with ADRs (ADR-001..003) | ⏳ |  |  |
+| 5 | plan in waves (W7–W10) | ⏳ |  |  |
+| 6 | execute W7 — Spike 006 (real HF model smoke) | ⏳ |  |  |
+| 7 | execute W8 — Spike 007 (real trace ingestion) | ⏳ |  |  |
+| 8 | execute W9 — Spike 008 (DiLoCo smoke) | ⏳ |  |  |
+| 9 | execute W10 — packaging | ⏳ |  |  |
+| 10 | (Modal-gated) Spike 002a-mini real GPU smoke | ⏳ |  |  |
+| 11 | cross-model-final-review | ⏳ |  |  |
+| 12 | update scorecard + push | ⏳ |  |  |
+
+## Constraints
+
+- Verify ALL claims against primary sources (Wave 2 lesson — subagent synthesis is not evidence).
+- Tests must pass before commit.
+- Memory L1 is at 99% — write to L2 wiki + L3 fact_store, not L1.
+- Modal budget: $20 hard cap for this loop. Anything more goes to user for approval.
+- No `upload_file` mixing with `git push` — `git push hf master:main` only.
+- Commit messages via `-F /tmp/<wave>-commit-msg.txt`.

docs/_archive/README.md

@@ -0,0 +1,39 @@
+# docs/_archive — historical, point-in-time artifacts
+
+This directory holds **non-research** documents that captured the state of the
+project at a specific moment (wave logs, dated cross-family review bundles).
+They are preserved **verbatim for provenance** and are **not** maintained as
+current truth.
+
+> **What's current instead.** For the live state of the framework, read
+> [`docs/OVERVIEW.md`](../OVERVIEW.md), [`README.md`](../../README.md),
+> [`BACKLOG.md`](../../BACKLOG.md), [`docs/METHODOLOGY.md`](../METHODOLOGY.md),
+> [`docs/V1_V8_COVERAGE.md`](../V1_V8_COVERAGE.md), and the accepted ADRs under
+> [`docs/adrs/`](../adrs/README.md). Where an archived doc and a current doc
+> disagree, the current doc wins.
+
+Each archived file's original path still contains a one-line **redirect stub** so
+that older prose references (including those baked into immutable accepted ADRs)
+keep resolving.
+
+## Contents
+
+| Archived file | Original path | What it is | Superseded by |
+|---|---|---|---|
+| [`WAVE_COMPOSER_DATAGEN_RL_2026-05-29.md`](WAVE_COMPOSER_DATAGEN_RL_2026-05-29.md) | `docs/WAVE_COMPOSER_DATAGEN_RL_2026-05-29.md` | Wave log: Composer datagen + targeted-RL textual-feedback work, 2026-05-29 | ADR-008, ADR-009, ADR-010, ADR-014; `BACKLOG.md` |
+| [`DEEP_WORK_LOOP_LOG.md`](DEEP_WORK_LOOP_LOG.md) | `docs/DEEP_WORK_LOOP_LOG.md` | Running log of deep-work-loop sessions | `docs/METHODOLOGY.md`; `BACKLOG.md` |
+| [`reviews/cross-family-adr-008-009-010-2026-05-29/`](reviews/cross-family-adr-008-009-010-2026-05-29/) | `docs/reviews/cross-family-adr-008-009-010-2026-05-29/` | 5-family adversarial review of ADR-008/009/010 (SYNTHESIS + 4 per-model reviews) | ADR-008 / ADR-012 acceptance records |
+| [`reviews/final-verify-deep-work-2026-05-29/`](reviews/final-verify-deep-work-2026-05-29/) | `docs/reviews/final-verify-deep-work-2026-05-29/` | Phase-8 final cross-family verify (SYNTHESIS + per-model verifies) | accepted ADRs; `BACKLOG.md` |
+
+## Why archive instead of delete
+
+These documents record *how the decisions were reached* — the adversarial
+findings, the wave-by-wave reasoning, the cross-model disagreements. That
+provenance is valuable for anyone auditing the framework's claims, and the
+accepted ADRs cite these paths by name. Deleting them would orphan those
+citations and erase the audit trail. Archiving keeps the trail intact while
+making clear they are snapshots, not the live spec.
+
+> Research-flavored point-in-time reviews (the `WAVE_*_FINAL_REVIEW.md`
+> cross-model audits and the Wave-16 recon audit) live in the sibling
+> [`docs/research/_archive/`](../research/_archive/README.md) instead.

docs/_archive/WAVE_COMPOSER_DATAGEN_RL_2026-05-29.md

@@ -0,0 +1,75 @@
+# Wave: Composer 2.5 data-gen + targeted-RL textual-feedback (2026-05-29)
+
+> Deep-work-loop wave bringing Composer 2.5's **dataset generation** and
+> **targeted RL with textual feedback** into the framework, per Codeseys'
+> directive. This doc encapsulates what shipped and ties it to the ask.
+
+## The ask (verbatim intent)
+
+> "make sure that our framework for data-generation and massive deep RL similar
+> to composer 2.5 is able to … train a model like nanochat on modal … also …
+> diloco … bring the composer 2.5 blog's discussion on dataset generation into
+> the fray … the composer 2.5 RL method of targeted RL with textual feedback
+> should also be included in the RL framework as well as the dataset generation
+> framework."
+
+## What shipped (all on `hf/master`)
+
+| Capability | Status | Artifact |
+|---|---|---|
+| **Targeted RL w/ textual feedback** (SDPO) live in a Dr. GRPO loop | ✅ ADR-008 accepted | `trainer/composer_trainer.py` (`make_dr_grpo_config`, strict SDPO alignment), `examples/composer_grpo_sdpo_smoke/` |
+| **Hint generation** (the unstated #1 gap) — layered generator | ✅ ADR-009 accepted | `hint_generator.py` (Template→RawError→LLMJudge→sibling-bootstrap, `as_collator_hook`) |
+| **Dataset generation** (Feature Deletion) | ✅ ADR-010 accepted | `composer_replication/datagen/` (env, sandbox+safeguards, monitor, curriculum, validator, SWE-substrate adapter) |
+| nanochat-on-Modal + DiLoCo A/B | ✅ (prior wave, same session) | DiLoCo tied vanilla within noise; SFT ChatCORE 0.3076; RL Pass@1 doubled |
+| SDPO loss math end-to-end on real traces | ✅ (prior wave, same session) | `examples/sdpo_real_trace_train_smoke/` |
+
+## Key research resolutions (5 docs, `research/06-10`)
+
+- **RL algorithm = Dr. GRPO** (Composer 2 tech report arXiv:2603.24477): length-standardization removed, no std-dev advantage norm, Adam, single-epoch, k1 (`−log r`) KL. TRL 1.5.0 supports this natively (`loss_type="dr_grpo"`, `scale_rewards="none"`).
+- **Hint generation is unstated in every Cursor artifact** — so the SDPO/OPSD reconstruction is the legitimate path, not a missed detail. SDPO's "successful-rollout-as-implicit-feedback" is the bootstrap fallback.
+- **Composer 2 hint-free behavior-shaping alternative** documented (aux scalar rewards + nonlinear length/effort penalty) for when hints aren't available.
+- Corrections to the mapping doc: optimizer Adam (not Muon — 2.5-blog-only); sharding FSDP+CP+decoupled-EP (not HSDP).
+
+## Test posture
+
+- 187 passed / 16 skipped across the full package (no regressions).
+- New: 7 (Dr.GRPO config + SDPO alignment), 12 (layered hints), 19 (datagen).
+- The SDPO channel is proven both as loss-math-on-real-traces AND wired into a live `trl.GRPOTrainer` Dr. GRPO step.
+
+## Reusable for the adjacent project
+
+`composer_replication.datagen` is the data-gen primitive Codeseys wanted for
+another project: **"invert a solved-repo dataset into a reimplement-to-pass
+verifiable-reward task,"** with reward-hacking safeguards and an online
+difficulty curriculum. `SweBenchAdapter` makes any SWE-bench-shaped dataset
+(SWE-Gym, R2E-Gym, SWE-rebench — tens of thousands of tasks) a drop-in source.
+
+## Owed / unblocked-by (constraints this wave hit)
+
+- **Cross-family adversarial ADR review** (GPT-5.5 / Gemini 3.1 Pro / DeepSeek
+  V4 Pro / Kimi K2.6 / Grok 4.3) — ✅ **DONE 2026-05-29** once OpenRouter credits
+  were restored. 4/5 clean reviews (Kimi starved its budget). Verdicts: ADR-008
+  3-REJECT/1-fix, ADR-009 unanimous-fix, ADR-010 3-REJECT/1-fix — the REJECTs all
+  amounted to "accepted-status outran the evidence," not "design is wrong." The
+  review **caught a real policy-corrupting P0 the solo pre-mortem missed**: the
+  SDPO alignment guard was a shape-check that let hint-shifted tokens silently
+  misalign. That plus 6 other convergent defects (sandbox scrub unimplemented,
+  curriculum partial-reward→full-pass, reward_fn truncation, shell injection,
+  LLM-judge cache non-determinism, scale_rewards assert dup) were **fixed and
+  tested** (192 pass / 16 skip, was 187). Full synthesis + the 4 reviews:
+  `docs/reviews/cross-family-adr-008-009-010-2026-05-29/`. Each ADR now carries a
+  "Post-acceptance cross-family review" section documenting fixed vs open items.
+- **Live Docker substrate-inversion e2e** for ADR-010 (pull one SWE-bench-Lite
+  image, run the 4 gates against it) — STILL deferred (no Docker in the CPU dev
+  env). The review confirmed this is the gate that matters: it closes the
+  remaining OPEN findings (real reachability/provenance, FakeSandbox-tautology
+  objection). Marked `[~]` in ADR-010. Needs a box with Docker + a SWE-bench-Lite
+  image.
+- Gateway restarted 6× during the original wave; all work kept durable via
+  phase-boundary commits + detached `systemd-run` scopes.
+
+## Commit trail
+
+`7090729` (SDPO smoke) → `6049d00` (research) → `36ab61e` (ADRs) →
+`bde5c5e` (ADR-008 code) → `2a34df4` (ADR-008 smoke+accept) →
+`84740d4` (ADR-009) → `9336af3` (ADR-010).

docs/_archive/reviews/cross-family-adr-008-009-010-2026-05-29/SYNTHESIS.md

@@ -0,0 +1,90 @@
+# Cross-family adversarial review — ADR-008 / 009 / 010 (2026-05-29)
+
+> The "owed" cross-family adversarial ADR review from the Composer 2.5
+> data-gen + targeted-RL wave. Deferred during the wave because OpenRouter ran
+> out of credits mid-run (blocking `delegate_task`); run here once credits were
+> restored (~$50 free at review time). This is the proper GPT-5.5 / Gemini /
+> DeepSeek / Kimi / Grok scatter the wave summary promised.
+
+## Method
+
+Route-fidelity-safe urllib scatter (no `delegate_task` per-task-override risk)
+to 5 diverse families, full corpus embedded inline: the 3 ADRs **plus their
+implementation code plus the tests** (~100KB / ~25K tokens), so reviewers
+critiqued the *implementation against the decision*, not just the prose.
+
+| Family | Slug (served) | Result |
+|---|---|---|
+| OpenAI | gpt-5.5-20260423 | clean, very specific (7981 tok) |
+| Google | gemini-3.1-pro-preview-20260219 | clean, sharpest (9174 tok @ retry 16K) |
+| DeepSeek | deepseek-v4-pro-20260423 | clean, math/correctness lens (10308 tok @ retry 16K) |
+| xAI | grok-4.3-20260430 | clean, terse/decisive (1645 tok) |
+| Moonshot | kimi-k2.6-20260420 | starved token budget (63K reasoning, content=None) — excluded |
+
+4 of 5 clean reviews. Raw reviews: `review_*.md` in this directory.
+
+## Verdict matrix
+
+| ADR | GPT-5.5 | Gemini | DeepSeek | Grok | Consensus |
+|---|---|---|---|---|---|
+| 008 (Dr.GRPO+SDPO) | REJECT | REJECT | ACCEPT-w-FIXES | REJECT | **3 REJECT / 1 fix** |
+| 009 (layered hints) | ACCEPT-w-FIXES | ACCEPT-w-FIXES | ACCEPT-w-FIXES | ACCEPT | **unanimous: fixable** |
+| 010 (FeatureDeletion datagen) | REJECT | REJECT | REJECT | ACCEPT-w-FIXES | **3 REJECT / 1 fix** |
+
+The REJECTs were not "the design is wrong" — every reviewer agreed the
+architecture is sound. They were "the **accepted** status outruns the
+**evidence**": gates marked `[x]` were satisfied by shape-checks and FakeSandbox
+tautologies, not by the hard guarantee the gate language implied.
+
+## Convergent findings (≥2 reviewers, ALL verified against code by the orchestrator)
+
+| # | Finding | Reviewers | Status |
+|---|---|---|---|
+| 1 | SDPO alignment guard = shape-check only; hint-shifted tokens silently misalign → policy poisoning | 4/4 | **FIXED** (explicit alignment-index gather + strict-raise; tests rewritten) |
+| 2 | Sandbox denylist trivially bypassable (`python -c`, abs paths, `sh -c`) + ADR-claimed scrub UNIMPLEMENTED | 4/4 | **FIXED** (`_scrub_tree` primary control implemented + tested) |
+| 3 | Curriculum `int(reward>0)` logs 0.5 partial as full pass → premature retire | 3/4 | **FIXED** (fractional credit + tests) |
+| 4 | `scale_rewards` assertion dup literal `("none","False","False")` | 4/4 | **FIXED** (case-insensitive) |
+| 5 | CPU smoke is tautological — never enters `_compute_sdpo_loss` (early return) | 3/4 | **RE-SCOPED** (gate honestly reworded) |
+| 6 | FakeSandbox validator tests prove plumbing, not real inversion | 3/4 | **RE-SCOPED** (= the `[~]` Docker gate) |
+| 7 | HackMonitor is substring matcher, not AST-provenance as advertised | 2/4 | **RE-SCOPED + OPEN** (follow-up) |
+| 8 | Validator gate-2/"deletion reachable" doesn't test reachability | 2/4 | **OPEN** (needs Docker materializers) |
+| 9 | `shell=True` + node-id interpolation = injection + param-test breakage | 2/4 | **FIXED** (`shlex.quote`) |
+| 10 | LLM-judge cache key non-deterministic (memory addr) + unbounded output | 2/4 | **FIXED** (addr-strip + version + clamp + atomic write) |
+| 11 | KL estimator k1 never configured/asserted | 2/4 | **OPEN** (fidelity follow-up) |
+| 12 | `reward_fn` zip truncates on length mismatch | 1 (GPT) | **FIXED** (length-guard) |
+
+## What was fixed in this pass (all tested, 192 pass / 16 skip, 0 fail)
+
+- **SDPO alignment** (`composer_trainer.py`): require `student_response_idx` /
+  `teacher_response_idx` from the collator; gather aligned post-hint logits
+  before JSD; strict-mode raises on missing/mismatched indices. The
+  silent-misalignment P0 (the only finding that would actually corrupt a run) is
+  closed and tested across different-length sequences.
+- **Sandbox scrub** (`sandbox.py`): `boot()` physically removes byte-code/type
+  caches + `.git`/`.hg` — the ADR-claimed PRIMARY reward-hack control, previously
+  absent. Denylist re-documented as defense-in-depth + `shlex.quote` on node ids.
+- **Curriculum** (`curriculum.py` + `env.py`): fractional pass credit; hacked /
+  guard-broken rollouts contribute 0 credit but count as exposures.
+- **reward_fn** (`env.py`): length-guard against silent truncation.
+- **LLM judge** (`hint_generator.py`): address-stripped + versioned cache key,
+  600-char output clamp, atomic disk write.
+- **`make_dr_grpo_config`** (`composer_trainer.py`): fixed the duplicated
+  assertion literal.
+
+## What remains OPEN (honest follow-ups, none corrupt a run)
+
+1. **Live Docker substrate-inversion e2e** — the central `[~]` gate. Closes
+   findings #6, #8 (real reachability/provenance on a materialized repo) and the
+   "FakeSandbox is tautological" objection. **Blocked: no Docker in this env.**
+2. **k1 KL estimator** assert/config vs TRL 1.5.0's actual GRPO KL branch (#11).
+3. **HackMonitor → real AST provenance** check (#7).
+4. **Hint-generator default layer routing** so style/communication sites reach
+   the judge (ADR-009 P1).
+5. **Curriculum turn/think-token signals** for full Composer recipe fidelity.
+
+All five are documented in the ADRs' "Post-acceptance cross-family review"
+sections.
+
+## Cost
+
+~$2-4 OpenRouter (2 scatters: 5×8K + 3×16K tokens on a 25K-token corpus).

docs/_archive/reviews/final-verify-deep-work-2026-05-29/SYNTHESIS.md

@@ -0,0 +1,33 @@
+# Phase-8 final cross-family verify — deep-work-loop 2026-05-29
+
+The deep-work-loop exit gate (Hard Rule 6: two independent confirmations). After
+Waves A+B shipped (ADR-011/012/013, 227 tests), the net session code diff
+(~92KB) was scattered to 3 diverse families for a final "would this break a real
+run" pass. 2 of 3 returned clean (GPT-5.5, Gemini; DeepSeek starved its reasoning
+budget). The verify EARNED ITS KEEP — it found a latent P0 + a convergent bug +
+a self-bug in this session's own new code.
+
+## Findings (all verified against code, all FIXED)
+
+| # | Finding | Severity | Reviewers | Fix |
+|---|---|---|---|---|
+| 1 | SDPO sentinel-mask used only `student_response_valid`, ignored `teacher_response_valid` — a future divergent teacher tail would distill against clamped position 0 | P0 (latent) | GPT-5.5 | `aligned_mask = (s_idx>=0)&(t_idx>=0)&student_valid&teacher_valid` |
+| 2 | Curriculum `_TaskStats` shared one `n_effort` denominator for both turns + think_tokens → corrupts a mean when only one signal is present | P1 (convergent) | GPT-5.5 + Gemini | separate `n_turns`/`n_think` counters |
+| 3 | Docker E2E test ran `pip install pytest` under `--network none` → would fail exactly when the gate activates | P1 | GPT-5.5 | dropped pytest; stdlib `python -c` expression runner, no network needed |
+| 4 | MMLU reward: `Answer: A or B` hedge parsed as `A` with `n_distinct=1` → full credit | P1 | GPT-5.5 | `_HEDGE_RE` adds the hedged second letter to the distinct set → multiple-answers penalty |
+| 5 | HackMonitor read-markers bare-substring matched `import` in `important`, `cat` in `concatenate`; and scanned the submitted patch as read-evidence → false positives | P1 | GPT-5.5 | whole-word `_READ_VERB_RE` + exclude `submit_patch`/`patch`/`diff` payloads from BOTH layers |
+
+Finding 5's fix surfaced a follow-on: layer-1's signature matcher ALSO scanned
+the patch payload (a legit patch mentioning `__pycache__` in a comment got
+flagged). The regression test caught it; fixed by excluding the patch payload
+from layer-1 too. Net: the monitor now only treats actual read ACTIONS as
+provenance evidence, never the agent's own output patch.
+
+## Outcome
+
+All 5 findings fixed + 5 regression tests added. Final suite: **232 passed / 18
+skipped, 0 failed**. Both the execution view (workers reported done) and the
+review view (final verify findings all closed) confirm the loop is empty — the
+two independent confirmations the deep-work-loop requires.
+
+Raw reviews: `verify_gpt-5.5.md`, `verify_gemini-3.1-pro.md`.

docs/_refine-2026-06-SUMMARY.md

@@ -0,0 +1,113 @@
+# Docs Refine 2026-06 — Change Summary
+
+> Branch: `docs/refine-2026-06` (off `master` HEAD `aae66fa`). **Docs-only.** Not merged,
+> no PR opened — left for human review. Commit range: `aae66fa..e130879` (3 commits).
+
+This engagement refined the documentation corpus to (1) enforce the ground-truth provenance
+correction recorded in [ADR-014](adrs/ADR-014-policy-optimization-objective-menu.md), (2)
+archive point-in-time historical artifacts without breaking references, and (3) add a single
+honest newcomer overview. **No `.py`, `pyproject.toml`, or any file under
+`composer_replication/ examples/ spikes/ tests/` was touched** — proven by
+`git diff --name-only aae66fa..HEAD` showing only `.md` paths (see end of this doc).
+
+## Method
+
+Plan → parallel read-only audit (4 agents over the living docs) → apply fixes in the main
+thread → two independent adversarial review passes (one per the post-wave-1 commit, one over
+the whole changeset) → iterate to convergence. Both adversaries + a deterministic link/invariant
+script signed off with zero blockers.
+
+## Commits
+
+| SHA | Wave | Theme |
+|---|---|---|
+| `20e3bd9` | Wave 1 | Correctness: channel-3 provenance, gap honesty, dead links |
+| `f00833d` | Wave 2 | Archive point-in-time wave reviews + dated review bundles (move + redirect stub) |
+| `e130879` | Wave 3 | Add `docs/OVERVIEW.md`, index ADR-014, fold in adversarial-review corrections |
+
+## Files touched — what changed and why
+
+### Wave 1 — correctness (commit `20e3bd9`)
+
+| File | Change | Fact |
+|---|---|---|
+| `README.md` | v0.1 roadmap cell reframed: "Full Composer recipe" = channels 1 (Dr.GRPO) + 2 (SDPO); trace-replay-DPO labelled the framework's own addition with an ADR-014 link. | A |
+| `docs/HF_REPO_LAYOUT.md` | v0 and v1 trained-variant rows: stop bundling trace-replay-DPO into "Composer recipe"; mark it additive. | A |
+| `docs/VISION_VALIDATION.md` | Status banner: stale "210 passing tests" → "115 + 1 skip-marked" pointing to the canonical `V1_V8_COVERAGE.md`; note the PO-objective menu (default Dr.GRPO, ADR-014); keep both honest gaps OPEN (Docker e2e; A1-done / A2–A4-scaffold). | B, D |
+| `docs/ALTERED_MINDS_TIE_IN.md` | Phase-3: only A1 has a real Modal runner; A2/A3/A4 scaffold + plan-builder only, blocked on dataset construction; real 8B run additionally user-gated. Added a `strip_thinking=False`-for-SDPO foot-gun note. | D, E |
+| `docs/USER_GUIDE.md` | Clone+install block: add `git checkout master` + a branch foot-gun callout (HF `main` lags `master`; else ImportError on `make_dr_grpo_config`). | F |
+| `BACKLOG.md` | Fixed two dead paths `examples/qwen3_05b_quickstart/` → `examples/qwen_05b_quickstart/`. | dead-link |
+| `docs/INTEGRATION_RECIPES.md` | Fixed dead link `ADR-007-distillation-losses.md` → `ADR-007-self-distillation-losses.md`. | dead-link |
+| `framework/composer-replication-framework.md` | Fixed 2 root-relative links that 404 from a subdirectory on HF Hub (`docs/…`, `spikes/…` → `../…`). | dead-link |
+| `publications/HF_DISCUSSION_POST.md` | Fixed 7 root-relative links (same subdirectory-resolution issue → `../` / same-dir). | dead-link |
+
+### Wave 2 — archive historical artifacts (commit `f00833d`)
+
+Moved (via `git mv`, history preserved) into archives, with a **one-line redirect stub** left
+at every original path so prose references — including those baked into immutable accepted ADRs
+(ADR-007/008/012) and off-limits spike verdicts that cannot be edited — keep resolving:
+
+- → `docs/research/_archive/`: `WAVE_7_10_FINAL_REVIEW.md`, `WAVE_13/14/15_FINAL_REVIEW.md`.
+- → `docs/_archive/`: `DEEP_WORK_LOOP_LOG.md`, `WAVE_COMPOSER_DATAGEN_RL_2026-05-29.md`.
+- → `docs/_archive/reviews/`: the two dated review bundles
+  (`cross-family-adr-008-009-010-2026-05-29/`, `final-verify-deep-work-2026-05-29/`) — all 8
+  per-model review/verify files moved as renames; a `SYNTHESIS.md` redirect stub remains at each
+  origin (the entry point ADRs cite by directory).
+- Added `docs/_archive/README.md` and `docs/research/_archive/README.md` indexing what was
+  archived and why ("point-in-time, superseded by current METHODOLOGY / BACKLOG / V1_V8_COVERAGE
+  / ADRs"), extending the existing `_archive` convention (`WAVE_16_RECON_AUDIT.md` already lived
+  in `docs/research/_archive/`).
+
+### Wave 3 — new overview + ADR index + review fixes (commit `e130879`)
+
+| File | Change |
+|---|---|
+| `docs/OVERVIEW.md` | **New.** 5-minute newcomer tour: what it is, the three channels with honest provenance (1+2 = genuine Composer replication; 3 = framework's additive channel), what's proven (CPU SDPO-fires, A1 8B Modal run, GSM8K GRPO, $0.98/trace, 115 tests), what's gapped (Docker e2e, A2–A4 ladder), day-one foot-guns (main-lag, strip_thinking, k1/k3 delta, compose_loss-is-harness). Linked from README + both `_archive` READMEs. |
+| `README.md` | Added a "🧭 New here? → OVERVIEW.md" pointer + clarified the intro that trace-replay is the framework's own addition (not Cursor's). Added the master-branch guard to the Install block (adversary finding). |
+| `docs/adrs/README.md` | Added the missing ADR-014 row + a provenance note recording the channel-3 correction. |
+| `docs/ALTERED_MINDS_TIE_IN.md`, `docs/VISION_VALIDATION.md` | Adversary corrections: dropped the parent-commit SHA mislabelled as "HEAD"; re-attributed the A2–A4 gap claim to cite ADR-014 only for "the A1 run used dr_grpo" (and ADR-013 for its sole user-gated box) instead of ADR-014's acceptance gate, which doesn't contain the dataset-construction detail; fixed one more stale `qwen3_05b_quickstart` path. |
+
+## Deliberately left alone — and why
+
+- **Accepted ADR bodies (ADR-001…014).** Immutable once `accepted` (per the ADR index's own
+  rule). Only the ADR *index* (`docs/adrs/README.md`) was updated. The provenance correction
+  was propagated into the *living* docs that ADR-014 supersedes, not by editing older ADRs.
+- **`research/01..12`, `framework/`, `publications/PAPER_v0.md` deep-dive bodies.** Preserved as
+  point-in-time research snapshots (only the 9 dead links in `framework/` +
+  `publications/HF_DISCUSSION_POST.md` were repaired). `docs/COMPOSER_RECIPE_MAPPING.md` and
+  `docs/METHODOLOGY.md` were audited and found **already correct** on channel-3 provenance (they
+  already frame channel 3 as "NOVEL — our addition / not in Composer"), so they were not rewritten.
+- **`docs/VISION_VALIDATION.md` dated update blocks (e.g. the "77 tests" Wave-12 line).** These
+  are explicitly-dated historical self-audit snapshots in the doc's house style; only the current
+  top status banner was refreshed. Rewriting dated snapshots would falsify the audit trail.
+- **The two `qwen3_7b_*` proposals in VISION_VALIDATION (lines ~80, ~138).** These accurately
+  record example dirs that were *proposed* in the Wave-6 audit but never built under any name;
+  "fixing" them to the 0.5B path would misrepresent history. Only the line describing the
+  packaging deliverable that actually shipped (`qwen_05b_quickstart`) was corrected.
+
+## Notes for a maintainer (issues found but NOT fixable under docs-only / scope)
+
+1. **Off-limits dead link.** `examples/gsm8k_grpo_with_sdpo/README.md:66` links to
+   `docs/adrs/ADR-002-channel2-sdpo.md`, which does not exist (ADR-002 is `ADR-002-trace-source.md`;
+   the SDPO design decision is **ADR-008**). This file is under `examples/` (off-limits to this
+   docs-only engagement), so it was left unchanged. **Recommended fix:** repoint that link to
+   `docs/adrs/ADR-008-drgrpo-sdpo-live-channel.md`.
+2. **API_REFERENCE freshness gap.** `docs/API_REFERENCE.md` documents the `composer_replication`
+   surface but has **no section for the trainer config factories** — neither `make_dr_grpo_config`
+   (ADR-008) nor the new `make_po_config(objective=…)` / `PO_OBJECTIVES` menu (ADR-014). This is a
+   *missing* doc, not a *wrong* one; it was not added here because the public signatures could not
+   be verified against source without reading the `.py` (out of scope), and Invariant 7 forbids
+   fabricating an API surface. **Recommended fix:** add a config-factory section to API_REFERENCE
+   from the verified `composer_replication/trainer/composer_trainer.py` signatures.
+
+## Verification (proof, not claim)
+
+- **Docs-only invariant:** `git diff --name-only aae66fa..HEAD` → every path ends in `.md`
+  (no `.py`, no `pyproject.toml`, nothing under `composer_replication/ examples/ spikes/ tests/`).
+- **Link integrity:** a scripted scan of every relative `[](…)` link across all in-scope `.md`
+  (root + `docs/` + `framework/` + `publications/`, excluding the 4 off-limits trees) reports
+  **zero dead links** in the changeset. The one known dead link (`ADR-002-channel2-sdpo.md`) is
+  pre-existing and lives in off-limits `examples/` — see note 1.
+- **Archive integrity:** every archived file has both a redirect stub at its origin and a
+  full-content copy under `_archive/`; all 8 review-dir files preserved (renames, no content loss).
+- **Two adversarial reviews + a deterministic check** all returned zero blockers.

docs/adrs/README.md

@@ -15,5 +15,12 @@
 | [ADR-011](ADR-011-sdpo-alignment-indices.md) | Collator-emitted SDPO alignment indices (close strict-guard regression) | accepted (amends ADR-008) | 2026-05-29 |
 | [ADR-012](ADR-012-close-review-findings.md) | Close open cross-family-review findings (KL/hint-routing/provenance/curriculum) | accepted (amends 008/009/010) | 2026-05-29 |
 | [ADR-013](ADR-013-lma-integration-channel-ladder.md) | LMA integration — isolated-channel ladder (supersedes tie-in Phase-3 hyperparams) | accepted | 2026-05-29 |
+| [ADR-014](ADR-014-policy-optimization-objective-menu.md) | Policy-optimization objective MENU: base RL objective selectable (default Dr.GRPO) over TRL 1.5.0 GRPOConfig (builds-on ADR-006/007/008) | accepted | 2026-05-30 |
 
 Sorted by number ascending. ADRs are immutable after `accepted`; supersede or amend rather than edit.
+
+> **Provenance note (ADR-014).** ADR-014 also records the canonical correction that the
+> framework's **trace-replay-DPO channel (channel 3) is an additive research channel, NOT
+> part of Cursor's Composer recipe** -- Composer's primary sources contain no DPO / preference
+> pairs / reward models / multiple teachers. Genuine replication is channels 1 (Dr.GRPO base)
+> + 2 (SDPO). See [`docs/OVERVIEW.md`](../OVERVIEW.md) for the honest three-channel summary.

docs/research/WAVE_13_FINAL_REVIEW.md

@@ -1,239 +1,8 @@
 # Wave 13 Adversarial Cross-Model Review
 
-**Reviewer:** Claude Opus 4.7 (sub-agent via delegate_task)
-**Date:** 2026-05-26
-**Scope:** Wave 13 additions only (35 new tests, 4 ADRs, 6 new modules)
-**Method:** Read-and-grep audit + targeted test runs (CPU)
-
-## Top-line verdict
-
-**CONDITIONAL PASS with two BLOCKERs.** Wave 13 substantially advances
-the brief expansion (serverless DiLoCo abstraction, replaysim
-normalization, three distillation losses, PRIME-RL recipe, Monarch
-tie-in). The **distillation losses are the strongest deliverable** —
-real, well-tested, mathematically faithful to the cited papers. The
-serverless-DiLoCo local executor + ObjectStoreAllReduce barrier are
-also genuine and exercised by 3 real multi-process tests.
-
-**However, two material claims are not test-validated, and one new
-module silently produces a degenerate loss in its primary code path.**
-ADR claims that say "X is added to compose_loss" describe code that
-wasn't actually written. The MockManager → DiLoCo "drop-in" is
-unverified end-to-end.
-
-Wave 11's reviewer found 2 genuine BLOCKERs. This review finds **2
-BLOCKERs + 4 SUGGESTIONs + 2 NITs**.
-
----
-
-## Finding 1 — BLOCKER: PRIME-RL `composer_loss.loss_fn` SDPO term is mathematically degenerate (always 0)
-
-**Severity:** BLOCKER
-**Evidence:** `composer_replication/recipes/prime_rl/composer_loss.py:79-86`
-
-The PRIME-RL composer-loss adapter applies `unsqueeze(-1)` to `(B, T)`
-log-prob tensors before passing them to `generalized_jsd_loss`, which
-calls `F.log_softmax(..., dim=-1)`. Softmax of a single-element vector
-is exactly 1.0; its log is 0. Therefore both `student_log_probs` and
-`teacher_log_probs` are identically zero, the JSD between them is 0,
-and the SDPO contribution **is always 0 regardless of `alpha_sdpo` or
-the actual log-prob values.**
-
-```python
->>> import torch.nn.functional as F
->>> F.log_softmax(torch.randn(2, 3, 1), dim=-1)
-tensor([[[0.],[0.],[0.]],[[0.],[0.],[0.]]])
-```
-
-The docstring calls this "a deliberate approximation," but it is not
-an approximation — it's a mathematically degenerate operation that
-silently disables channel 2.
-
-**Fix direction:**
-- Gate the SDPO branch behind `len(trainer_lp.shape) >= 3`, raising
-  `NotImplementedError` until PRIME-RL surfaces full logits.
-- Update `prime_rl_recipe.md` and ADR-006 to stop claiming PRIME-RL
-  has working SDPO; mark it deferred.
-
----
-
-## Finding 2 — BLOCKER: ADR-007 declares `compose_loss` kwargs that were never added
-
-**Severity:** BLOCKER
-**Evidence:**
-- `docs/adrs/ADR-007-self-distillation-losses.md:103-108` claims:
-  > `composer_replication.compose_loss` gets new optional kwargs:
-  >   - `dpo_variant: Literal["dpo", "simpo"] = "dpo"` — switches channel 3
-  >   - `sdpo_wrapper: Literal["none", "taid", "entropy_opd"] = "none"` — wraps channel 2
-  >   - `taid_schedule_step: int | None = None`
-  >   - `taid_total_steps: int | None = None`
-- `composer_replication/loss.py:54-65` actual signature has **none**
-  of these. `grep -n "dpo_variant\|sdpo_wrapper\|taid"
-  composer_replication/loss.py` returns empty.
-
-The new losses live in `composer_replication.distillation` as
-standalone functions but **are not wired into the framework's actual
-loss composition.** A user reading ADR-007 + the README would believe
-`compose_loss(model, inputs, dpo_variant="simpo", sdpo_wrapper="taid", ...)`
-works; it would raise `TypeError`. The 17 distillation tests verify
-the standalone losses but never exercise integration.
-
-**Fix direction:**
-- Either (a) add the kwargs to `compose_loss` and write at least one
-  integration test combining e.g. SDPO+TAID (~30 LOC change), or
-- (b) downgrade ADR-007 status to "Standalone losses landed;
-  integration deferred to Wave 14."
-
----
-
-## Finding 3 — SUGGESTION: `default.yaml` replaysim recipe uses string ops on list-of-dict fields
-
-**Severity:** SUGGESTION (would be BLOCKER if a test exercised the real path)
-**Evidence:**
-- `composer_replication/recipes/replaysim/default.yaml` configures
-  `text_length_filter`, `words_num_filter`, `special_characters_filter`,
-  `document_deduplicator` with `text_keys: ["chosen", "rejected"]`.
-- In the record produced by `_dpo_pair_to_dj_record`, `chosen` and
-  `rejected` are **lists of dicts**
-  (`[{"role": "assistant", "content": "..."}]`) — not strings.
-- data-juicer's `text_length_filter` expects string-typed fields;
-  running it on a list will either crash or no-op silently.
-
-The reason no test catches this: tests only validate the real path *if
-data-juicer is installed*, and even then only check `__init__` succeeds.
-There is no test that calls `normalize()` against a real data-juicer
-executor with the default recipe.
-
-**Fix direction:**
-- Reshape `_dpo_pair_to_dj_record` to extract `content` strings
-  alongside the messages-format list.
-- Add one test (skip-marked unless `data_juicer` is importable) that
-  runs the real op-graph on 3 hand-crafted records.
-
----
-
-## Finding 4 — SUGGESTION: MockManager → torchft.DiLoCo "drop-in" claim is unverified end-to-end
-
-**Severity:** SUGGESTION
-**Evidence:**
-- `composer_replication/diloco/serverless/allreduce.py:188-191` claims
-  MockManager "drops into" `make_diloco_outer_loop`.
-- The only test covering MockManager (`test_mock_manager_shape_compat`)
-  is a `hasattr` smoke that calls `.allreduce` on a `world_size=1`
-  store (passthrough).
-- torchft.Manager has additional surface area
-  (`current_step`, `is_leader`, `_pg`, `report_error`,
-  internal step accounting) that DiLoCo's `_apply_pseudogradient`
-  may consult depending on version.
-
-**Fix direction:**
-- Add a single integration test that constructs
-  `make_diloco_outer_loop(manager=MockManager(store), ...)` against a
-  tiny `nn.Linear` and runs one outer round — even single-process.
-- Audit `torchft/local_sgd.py` for the `Manager`-rooted call sites and
-  add stubs for any methods DiLoCo actually consults beyond `allreduce`.
-
----
-
-## Finding 5 — SUGGESTION: README claim "9 multi-process tests" is mildly inflated
-
-**Severity:** SUGGESTION (NIT bordering)
-**Evidence:**
-- README.md and V1_V8_COVERAGE both state: *"9 multi-process tests
-  pinning the allreduce barrier."*
-- Actual breakdown:
-  - 4 single-process unit tests + `test_mock_manager_shape_compat` (5)
-  - 4 multi-process tests spawning subprocesses (parametrized [2,3] of
-    `_runs_allreduce_across_replicas`, `_handles_multiple_rounds`,
-    `_reports_failed_replicas`)
-- Of the 4 multi-process tests, only **3 actually exercise the
-  allreduce barrier**; `_reports_failed_replicas` deliberately raises
-  before any allreduce call.
-
-**Wave 13 clearly does NOT fake-pass via world_size=1** — the multi-
-process barrier is real. But the count is rounded up.
-
-**Fix direction:** Replace "9 multi-process tests" with "9 tests
-covering the serverless DiLoCo layer, of which 4 spawn real
-subprocesses and 3 exercise the allreduce barrier across replicas."
-
----
-
-## Finding 6 — SUGGESTION: PRIME-RL channel 1 is REINFORCE not GRPO; ignores `inference_logprobs`
-
-**Severity:** SUGGESTION
-**Evidence:** `composer_replication/recipes/prime_rl/composer_loss.py:62-68`
-computes:
-```python
-grpo_loss = -(advantages * trainer_lp * mask).sum() / mask.sum().clamp_min(epsilon)
-```
-
-This is plain REINFORCE with advantage. PRIME-RL's `LossInputs`
-exposes `inference_logprobs` precisely because GRPO-with-replay-buffer
-requires the importance-sampling ratio
-`exp(trainer_lp - inference_lp)` (PPO-style clipped objective).
-
-The file says "SKELETON" so this isn't a hidden bug per se, but the
-loss is **labeled GRPO and is not GRPO**.
-
-**Fix direction:** Either implement the ratio + clipping (~20 LOC) or
-rename channel-1 comment to "REINFORCE-with-advantage stub" with a TODO.
-
----
-
-## Finding 7 — NIT: ModalExecutor / HFJobsExecutor are skeleton-only with `NotImplementedError` in `__init__`
-
-**Severity:** NIT (this is documented, but README phrasing is slightly soft)
-**Evidence:** Honestly documented as skeletons in the code, ADR-005,
-and README. NIT: a user trying `ModalExecutor()` gets a runtime error
-rather than an import-time clue.
-
-**Fix direction:** Low priority. Update README phrase to "skeleton-only
-— raises NotImplementedError until v0.x." Or use a `__getattr__` on
-the package that raises a clearer message.
-
----
-
-## Finding 8 — NIT: SimPO test uses positive log-probs (impossible values)
-
-**Severity:** NIT
-**Evidence:** `test_distillation_losses.py:27-46` calls `simpo_loss`
-with `chosen=tensor([0.5, 0.4, 0.3])`. Log-probabilities are bounded
-above by 0; positive values aren't possible from any softmax. The tests
-still verify the formula correctly, but the test inputs aren't legal.
-
-**Fix direction:** Use negative values — purely cosmetic.
-
----
-
-## Cross-cutting risk check
-
-73 tests passed in 29.29s on the CPU-fast subset. Spike 008 5/5 still
-pass. The new `composer_replication.diloco.serverless` package is
-purely additive; the existing `make_diloco_outer_loop` is untouched.
-**No cross-wave regressions detected on CPU.** GPU tests + slow CPU
-e2e tests not re-run; regression risk low since Wave 13 doesn't touch
-their dependencies.
-
----
-
-## Summary scorecard
-
-| Item | Verdict |
-|---|---|
-| Distillation module (SimPO/TAID/Entropy-Aware OPD) standalone | ✅ Real, well-tested, paper-faithful |
-| Distillation integrated into `compose_loss` | ❌ **Not implemented** despite ADR-007 (Finding 2) |
-| ObjectStoreAllReduce + LocalProcessExecutor | ✅ Real multi-process barrier validated |
-| MockManager → DiLoCo drop-in | 🟡 Shape-checked only; integration unverified (Finding 4) |
-| Modal/HFJobs adapters | 🟡 Honestly documented as skeletons (Finding 7) |
-| Replaysim DJNormalizer passthrough | ✅ Works |
-| Replaysim default.yaml against real data-juicer | ❌ **Recipe field types don't match record shape** (Finding 3) |
-| PRIME-RL composer_loss.loss_fn | ❌ **SDPO term silently 0** (Finding 1); channel 1 is REINFORCE not GRPO (Finding 6) |
-| Monarch actors | ✅ Honest skeleton; raises NotImplementedError |
-| Altered-minds tie-in doc | ✅ Design-only, scoped honestly |
-| 35 new tests | All pass; 3 of 4 multi-process tests are genuine (Finding 5) |
-
-**Recommendation:** Address Findings 1 and 2 before publishing the
-Wave 13 expansion as "closed." Findings 3 and 4 should be addressed
-before any user attempts the real data-juicer or real torchft DiLoCo
-path. Findings 5–8 are cleanup.
+> **📦 Archived (2026-06-08).** This point-in-time wave review has been moved to
+> [`docs/research/_archive/WAVE_13_FINAL_REVIEW.md`](_archive/WAVE_13_FINAL_REVIEW.md).
+> It is preserved verbatim for provenance (ADR-007 cites its "Finding 2") but is
+> superseded by the current [`docs/METHODOLOGY.md`](../METHODOLOGY.md) and
+> [`BACKLOG.md`](../../BACKLOG.md). See
+> [`docs/research/_archive/README.md`](_archive/README.md) for the archive index.

docs/research/WAVE_14_FINAL_REVIEW.md

@@ -1,263 +1,7 @@
 # Wave 14 Adversarial Cross-Model Review
 
-**Reviewer:** Claude Opus 4.7 (sub-agent via delegate_task)
-**Date:** 2026-05-26
-**Method:** Read every Wave 13 finding, every Wave 14 closure, all 4 doc files, **cloned PRIME-RL upstream to verify T4 claims**, ran 61 wave-relevant tests.
-
-## Top-line verdict
-
-**CONDITIONAL PASS with 1 BLOCKER + 4 SUGGESTIONs + 2 NITs.** Wave 14
-closes Wave 13 BLOCKER 2 (T1 — compose_loss kwargs) and Suggestion 3
-(T2 — replaysim) cleanly. T3 (MockManager surface audit) is solid but
-only tests `world_size=1`. **T4 (PRIME-RL "real GRPO + DPPO") does not
-match PRIME-RL's actual `default_loss_fn`** despite claiming to mirror
-it; that error has been pasted into USER_GUIDE.md, INTEGRATION_RECIPES.md,
-and API_REFERENCE.md.
-
-Same signal-to-noise as Wave 11 + Wave 13 reviewers: 1 genuine BLOCKER.
-
----
-
-## Finding 1 — BLOCKER: T4 PRIME-RL "DPPO importance-sampling-ratio clip" is neither importance sampling nor matches PRIME-RL.
-
-**Severity:** BLOCKER
-**Evidence:** `composer_replication/recipes/prime_rl/composer_loss.py:118-131`.
-The implementation computes
-```python
-grpo_loss = -(advantages * trainer_lp * keep_mask).sum() / keep_mask.sum()
-```
-That's **pure REINFORCE-with-advantage** — the masking gate is the only
-nod toward DPPO; there is no importance-sampling ratio multiplication
-anywhere.
-
-**Real PRIME-RL** (`/tmp/prime-rl-clone/src/prime_rl/trainer/rl/loss.py:128-153`,
-the `default_loss_fn` on `main` as of 2026-05-26):
-```python
-log_importance_ratio = trainer_logprobs - inference_logprobs
-importance_ratio     = torch.exp(log_importance_ratio)
-probs_diff           = torch.exp(trainer_logprobs) - torch.exp(inference_logprobs)
-positive_advantages  = advantages > 0
-dppo_invalid_mask_high = probs_diff > loss_config.dppo_mask_high
-dppo_invalid_mask_low  = probs_diff < -loss_config.dppo_mask_low
-dppo_invalid_mask = torch.where(positive_advantages, dppo_invalid_mask_high, dppo_invalid_mask_low)
-keep_mask = loss_mask & ~dppo_invalid_mask
-pg_loss = -(keep_mask * advantages * importance_ratio).sum()  # NO division
-kl_loss = adv_tau * (log_importance_ratio**2 * keep_mask).sum()  # KL term
-```
-
-**Three concrete divergences from Wave 14's implementation:**
-
-1. **Mask gate is on `probs_diff`** (a probability-space quantity), NOT
-   `log_ratio` (a log-space quantity). These have different magnitudes:
-   `probs_diff=0.2` corresponds to `log_ratio≈log(1.2)≈0.18` for a
-   trainer prob of 1.0 vs inference prob of 0.8. With our `log_ratio>4.0`
-   gate, the mask never fires for normal training distributions; PRIME-RL's
-   `probs_diff>0.2` gate fires routinely.
-
-2. **PRIME-RL multiplies by `importance_ratio = exp(log_ratio)`**;
-   Wave 14 multiplies by `trainer_lp` directly. This is the difference
-   between actual policy-gradient correction (PRIME-RL) and naive
-   REINFORCE.
-
-3. **PRIME-RL's mask is sign-conditioned on advantage** (positive
-   advantages clipped against `dppo_mask_high`, negative against
-   `-dppo_mask_low`); Wave 14 ORs them together unconditionally.
-
-**Plus:** the KL term is missing entirely.
-
-**Plus:** the defaults claimed as "PRIME-RL's defaults" — `dppo_mask_high=4.0,
-dppo_mask_low=-4.0` — are wrong. PRIME-RL's `DefaultLossConfig`
-(`configs/trainer.py:412-424`) sets `dppo_mask_high=0.2, dppo_mask_low=0.2`
-with `Field(..., ge=0)` validation that would *reject* a negative value.
-PRIME-RL's code negates at use site: `probs_diff < -loss_config.dppo_mask_low`.
-
-**Plus:** the docstring (`composer_loss.py:32-49`), USER_GUIDE.md:599-608,
-INTEGRATION_RECIPES.md:426-429 + 482-487, and API_REFERENCE.md:1364 all
-repeat the wrong formula and the wrong "matches PRIME-RL" claim.
-
-**Fix direction:** Either (a) actually mirror `default_loss_fn` (mask on
-`probs_diff`, multiply by `importance_ratio`, add KL term, advantage-
-conditioned mask, `.sum()` reduction with token-count returned for
-caller-side scaling), or (b) drop the "matches PRIME-RL" framing and
-rename to "REINFORCE-with-advantage stub + log-ratio mask" everywhere.
-
-Wave 13 Finding 6 is **not actually closed** by Wave 14.
-
----
-
-## Finding 2 — SUGGESTION: ADR-007 still says Wave 14 hasn't done the integration.
-
-**Severity:** SUGGESTION
-**Evidence:** `docs/adrs/ADR-007-self-distillation-losses.md:104-122` reads:
-> **Wave 14+ work — `compose_loss` integration is NOT in this wave**
-> ... Wave 14 plan: add the four kwargs ...
-
-But Wave 14 *did* add them (verified — `loss.py:80-93`). The ADR was
-written defensively after Wave 13 review and never updated when T1 landed.
-
-**Net effect:** a user reading ADR-007 is told the SimPO/TAID kwargs
-don't work; a user reading USER_GUIDE/API_REFERENCE is told they do.
-
-**Fix direction:** flip ADR-007 status section to "Closed in Wave 14 —
-see test_compose_loss_integration.py".
-
----
-
-## Finding 3 — SUGGESTION: ModalExecutor instantiation example in INTEGRATION_RECIPES is dead code.
-
-**Severity:** SUGGESTION
-**Evidence:** `docs/INTEGRATION_RECIPES.md:519-533` shows
-```python
-executor = ModalExecutor(app="composer-prime-rl")
-executor.launch_replicas(...)
-```
-But `composer_replication/diloco/serverless/modal.py:64-66` raises
-`NotImplementedError` from `__init__`. Same pattern in `HFJobsExecutor`.
-The recipe doc warns about skeleton-status much further down (line 731),
-but the inline code example at line 519 will break the moment a reader
-copy-pastes it.
-
-Wave 13 Finding 7 noted this softness; Wave 14 made it worse by writing
-example code that calls a constructor that always raises.
-
-**Fix direction:** in every code block that calls `ModalExecutor(...)`,
-prepend a comment `# Wave 14: skeleton — raises NotImplementedError`
-or flip examples to `LocalProcessExecutor`.
-
----
-
-## Finding 4 — SUGGESTION: MockManager + DiLoCo integration test only exercises `world_size=1`.
-
-**Severity:** SUGGESTION
-**Evidence:** `composer_replication/diloco/serverless/tests/test_serverless_diloco_integration.py:44-51`,
-`:108-109`, `:161`. Both `test_mockmanager_diloco_outer_round_completes`
-and `test_mockmanager_diloco_two_outer_rounds_step_counter` use
-`world_size=1`.
-
-With one replica, `ObjectStoreAllReduce.allreduce` returns the tensor
-unchanged (its own mean), so an averaging bug in the multi-replica path
-could not be caught by this test. The pseudo-gradient sign convention
-is pinned by the unrelated spike-008 test, but **no test combines
-MockManager + DiLoCo + multi-process** — i.e. the actual deployment
-scenario is unverified end-to-end.
-
-Wave 13 Finding 4 is closed in spirit (call surface is now exhaustive)
-but not in the deepest sense.
-
-**Fix direction:** add one multi-process test that spawns `n_replicas`
-subprocesses, each constructing `MockManager(store) → make_diloco_outer_loop`,
-and asserts that after one outer round all replicas converge to the same
-parameter values (i.e. averaging actually happened).
-
----
-
-## Finding 5 — SUGGESTION: T4 unit tests pin the wrong implementation as ground truth.
-
-**Severity:** SUGGESTION
-**Evidence:** `composer_replication/recipes/prime_rl/tests/test_composer_loss.py:90-128`
-(`test_dppo_mask_clips_extreme_ratios`). The expected value `1.5/3` is
-computed against the buggy formula (Finding 1).
-
-The 10 PRIME-RL tests all pass — but they're testing self-consistency,
-not parity with PRIME-RL. A reader looking at "10 unit tests, all green"
-infers correctness; correctness is not what they verify. This is the
-kind of test honesty failure that Wave 11 + Wave 13 reviewers found in
-different forms.
-
-**Fix direction:** add at least one test whose expected value is
-hand-computed from `default_loss_fn` in PRIME-RL (or import + invoke
-`default_loss_fn` if the dependency is available, mark the test
-`@pytest.mark.skipif(not _HAS_PRIME_RL)`).
-
----
-
-## Finding 6 — NIT: README/test-count drift.
-
-Wave 14 task description claims "124 tests passing as of Wave 14"; actual
-`pytest --collect-only` reports **134 collected**. Of those, the 61-test
-wave-relevant subset all pass. Not a defect, but the headline number is
-now off in the same way Wave 13's "9 multi-process tests" was off.
-
----
-
-## Finding 7 — NIT: `loss_fn` docstring claims "DPPO importance-sampling-ratio clipping — implemented" (`composer_loss.py:9`).
-
-Implementation contains no importance-ratio multiplication anywhere.
-Even if Finding 1 is rejected and the team decides "PRIME-RL match isn't
-a goal", the docstring is internally false: it announces ISR clipping
-in a function that does not multiply by `exp(log_ratio)`.
-
----
-
-## Cross-cutting
-
-The four doc subagents wrote internally consistent text but inherited
-T4's mathematical error. **Three of the four doc files repeat the same
-wrong formula verbatim.** This is exactly the failure mode Wave 11/13
-reviewers flagged: parallel subagents cross-citing each other rather
-than the upstream source of truth.
-
-The 61 tests in the Wave-14-touched dirs pass cleanly. T1, T2, and T3
-are real closures with real coverage. The framework is in a **better**
-state than end-of-Wave-13 — but it has not actually closed Wave 13
-Finding 6, and it has propagated a subtler version of the same
-mathematical-mismatch bug into the user-facing documentation.
-
----
-
-## Summary scorecard
-
-| Wave 13 Finding | Wave 14 status | Verdict |
-|---|---|---|
-| BLOCKER 1 (PRIME-RL SDPO degenerate) | Fixed parent-side; channel 2 raises NotImplementedError | ✅ closed |
-| BLOCKER 2 (compose_loss kwargs not added) | T1 added them + 11 integration tests | ✅ closed |
-| Suggestion 3 (replaysim YAML field types) | T2 dual-shape reshape + real DJ e2e + caught related bug | ✅ closed |
-| Suggestion 4 (MockManager → DiLoCo gap) | T3 surface audit + integration test | 🟡 closed for `world_size=1`; multi-process unverified |
-| Suggestion 5 ("9 multi-process tests" inflated count) | Not addressed | 🟡 carried over |
-| Suggestion 6 (PRIME-RL channel 1 REINFORCE not GRPO) | T4 thought it closed this | ❌ **NOT closed — mathematically wrong** |
-| Suggestion 7 (Modal/HFJobs skeleton clarity) | Made worse by INTEGRATION_RECIPES dead code | 🟡 regression |
-| NIT 8 (SimPO test positive log-probs) | Not addressed | 🟡 carried over |
-
-## Wave 14b follow-up (2026-05-26)
-
-After Wave 14b closed Finding 1 by re-reading PRIME-RL upstream and
-matching `default_loss_fn` byte-for-byte, the Wave 14b subagent flagged
-a **new** structural issue not in the Wave 14 review:
-
-**PRIME-RL's `setup_loss_fns` (upstream `loss.py:320-327`) expects the
-custom loss function to return `LossOutputs(loss, metrics={...})`, not
-a bare scalar tensor.** Our recipe still returns a bare scalar. This
-predates Wave 14 (it's been wrong since the recipe was first written in
-Wave 13) but was never caught because no test runs against actual
-PRIME-RL.
-
-**Status:** documented; deferred to Wave 15. Not blocking for Wave 14b's
-closure of Finding 1, because the formula now matches upstream — the
-return-shape mismatch is a separate adapter-level issue. Tests still
-pass because they invoke our `loss_fn` directly without going through
-PRIME-RL's `compute_loss` pipeline.
-
-**Fix direction (Wave 15):** wrap the return value in a duck-typed
-`LossOutputs` (provided by PRIME-RL when installed; substituted with a
-NamedTuple shim when not). Add an integration smoke test against PRIME-RL
-to catch this and similar adapter-shape regressions.
-
-## Final Wave 14 + 14b status
-
-| Wave 13 / 14 finding | Wave 14b status |
-|---|---|
-| W13 BLOCKER 1: PRIME-RL SDPO degenerate | ✅ closed (parent, channel 2 deferred) |
-| W13 BLOCKER 2: compose_loss kwargs not added | ✅ closed (Wave 14 T1) |
-| W13 Suggestion 3: replaysim YAML field types | ✅ closed (Wave 14 T2) |
-| W13 Suggestion 4: MockManager → DiLoCo gap | ✅ closed (Wave 14 T3 + Wave 14b multi-process test) |
-| W13 Suggestion 6: PRIME-RL channel 1 REINFORCE not GRPO | ✅ **closed in Wave 14b** (matches upstream `default_loss_fn`) |
-| W14 Finding 1: PRIME-RL impl wrong | ✅ closed in Wave 14b |
-| W14 Finding 2: ADR-007 stale | ✅ closed in Wave 14b |
-| W14 Finding 3: ModalExecutor dead code | ✅ closed in Wave 14b |
-| W14 Finding 4: world_size=1 only | ✅ closed in Wave 14b (multi-process convergence test) |
-| W14 Finding 5: tests pin wrong impl as ground truth | ✅ closed in Wave 14b (parity test added) |
-| W14 NIT 6: test count drift | 🟡 carried |
-| W14 NIT 7: docstring claims ISR clipping | ✅ closed in Wave 14b (real ISR now implemented) |
-| **NEW (Wave 14b)**: PRIME-RL `LossOutputs` return shape | 🟡 deferred to Wave 15 |
-
-**Tests as of Wave 14b: 115 passing + 1 skip-marked (OPSD parity test, runs when upstream cloned).** (Wave 12: 72; Wave 13: 93; Wave 14: 124; Wave 14b: 130; Wave 15: 115 after TAID rewrite consolidation + OPSD parity.)
+> **📦 Archived (2026-06-08).** This point-in-time wave review has been moved to
+> [`docs/research/_archive/WAVE_14_FINAL_REVIEW.md`](_archive/WAVE_14_FINAL_REVIEW.md).
+> It is preserved verbatim for provenance but is superseded by the current
+> [`docs/METHODOLOGY.md`](../METHODOLOGY.md) and [`BACKLOG.md`](../../BACKLOG.md). See
+> [`docs/research/_archive/README.md`](_archive/README.md) for the archive index.

docs/research/WAVE_15_FINAL_REVIEW.md

@@ -1,76 +1,7 @@
 # Wave 15 Final Review — Multi-Angle Self-Critique + Fix Wave
 
-**Date:** 2026-05-26
-**Method:** 4 parallel adversarial reviewers (math / tests / docs / user-journey), each given a different framing to maximize independent-angle coverage. Then targeted fix scatter on findings.
-
-## Headline finding
-
-**The math reviewer found 2 BLOCKERs that all 8+ prior subagents missed.** Both came from `git clone`-ing upstream and doing line-by-line diffs against the framework's `composer_replication/opsd.py` and `composer_replication/distillation/taid.py` — something no prior reviewer had done for those files (Wave 14b reviewer did it for PRIME-RL only).
-
-This validates the user's instinct that "every angle" multi-model orchestration is worth doing — the math angle, given a sharp prompt that mandated upstream verification, found genuine bugs in the framework's primary loss kernel.
-
-## Wave 15a reviews (all 4 deliverables)
-
-| Reviewer | Focus | BLOCKERs | Severity-weighted findings |
-|---|---|---|---|
-| Math correctness (Opus 4.7) | 7 claimed implementations vs primary sources | **2 BLOCKER + 3 minor** | `generalized_jsd_loss` math wrong; `taid_loss` algorithm wrong |
-| Test honesty (Opus 4.7) | 3 specific test files | 0 BLOCKER + 3 weak-assertions | PRIME-RL parity skip silently never runs; bit-exact uses `allclose` not `equal`; entropy-OPD test is pure smoke |
-| Documentation drift (Opus 4.7) | 6 major docs + ADRs | 0 BLOCKER + 7 drifts | test count drift (77/107/124 vs actual 145); `compose_loss` kwarg drift; PRIME-RL test count 10 vs 16; stale "Deferred to Wave 14" claim |
-| User journey (Opus 4.7) | RL-finetune Qwen-7B on GSM8K | 0 BLOCKER + 10 friction items | **No GSM8K example** (#1 ask); no runnable `ComposerReplicationTrainer` recipe; data-collator gap undocumented; defaults activate channels users haven't configured |
-
-Reports saved at `/tmp/wave15_{math,test,doc,user}_review.md`.
-
-## Wave 15b — fix scatter outcomes
-
-5 parallel fix subagents dispatched. Outcomes:
-
-| Task | Subagent outcome |
-|---|---|
-| (1) OPSD math rewrite vs upstream | ✅ Completed. New parity test (skip-marked) verifies 31 cases against upstream `siyan-zhao/OPSD`. Mixture distribution now β-weighted (was hardcoded 0.5); β coefficient on correct terms (was swapped); reduction matches upstream (was off by 100-2000× factor). Docstring labels fixed (β=0 = reverse KL, β=1 = forward KL). |
-| (2) TAID rewrite vs upstream | ⚠️ Subagent timed out at 600s but **work landed**: logit-space mix (was prob-space), current-student-detached anchor (was frozen step-0), forward-KL criterion (was JSD), optional `TAIDScheduler` for adaptive scheme. Docstring rewritten to acknowledge the breaking change. Tests updated. Parity test added. |
-| (3) GSM8K example | ⚠️ Subagent timed out but **work landed**: `examples/gsm8k_grpo/run.py` runs end-to-end on CPU with Qwen2.5-0.5B-Instruct, 100 GSM8K rows, regex-based verifiable reward, 2 outer steps in 58s. README written by parent agent. The `run_with_sdpo.py` variant deferred to Wave 16. |
-| (4) Doc drift + install ergonomics | ⚠️ Subagent timed out. **Parent completed:** flipped `alpha_sdpo` and `beta_replay` defaults to 0.0; added clear ImportError if TRL missing; fixed TROUBLESHOOTING `[replay]` extras claim; updated README + USER_GUIDE + INTEGRATION_RECIPES test counts to reference V1_V8_COVERAGE; closed stale "Deferred to Wave 14" claim. |
-| (5) Test hardening + LossOutputs wrap | ✅ Completed (3 of 4 sub-tasks). PRIME-RL `loss_fn` now returns `LossOutputs(loss, metrics)`. Bit-exact test tightened to `torch.equal`. PRIME-RL parity test now emits visible warning when prime-rl unavailable. Gradient-flow tests deferred to Wave 16. |
-
-## Final test count post-Wave-15: 115 passing + 1 skip-marked
-
-- Wave-by-wave: 72 (W12) → 93 (W13) → 124 (W14) → 130 (W14b) → **115** (W15)
-- Net decrease from 130: TAID rewrite consolidated 16 schedule-specific tests into 7 `t`-parameterized tests (smaller surface but stronger contracts: each test now exercises the actual paper algorithm). Plus 1 skip-marked OPSD parity test.
-- Trade-off: fewer tests, but 2 BLOCKER-class math bugs eliminated. Net correctness improvement is large.
-
-## What this round caught vs missed
-
-### Caught (improvements over Wave 14b state)
-- 2 math BLOCKERs in primary loss kernels, fixed against upstream byte-for-byte
-- TAID rewrite from misnamed prob-space-JSD-with-frozen-anchor to actual SakanaAI/TAID
-- PRIME-RL `LossOutputs` adapter wrap — recipe is now actually invokable from PRIME-RL
-- GSM8K real-task example — closes the user-reviewer's #1 friction
-- Default kwargs (`alpha_sdpo=0.1` → `0.0`) — no more silent activation of unconfigured channels
-- TRL ImportError clarity — no more cryptic `object.__init__()` errors
-- Test count drift — single canonical doc (V1_V8_COVERAGE)
-- TROUBLESHOOTING `[replay]` extras correctly described
-
-### Missed (Wave 16 candidates)
-- `run_with_sdpo.py` — promised but not shipped this wave
-- 3 gradient-flow tests for compose_loss channels (test reviewer's #4)
-- Multi-process MockManager + DiLoCo convergence test was added in Wave 14b but only at world_size=2; user reviewer didn't probe larger
-- Recon docs (`docs/research/*RECONNAISSANCE.md`) not cross-checked against current code state — likely some staleness
-- PRIME-RL recipe still hasn't been run end-to-end against actual prime-rl (parity test skip-marks; LossOutputs wrap added but not exercised)
-
-## Methodological lessons for future waves
-
-1. **Prompt subagents to clone upstream and diff** when the task is "verify against external truth." 8+ prior reviewers checked papers but did not `git clone`. The instruction "read /tmp/X-clone/file.py and find every divergence" produced the BLOCKER-class findings.
-
-2. **600s subagent timeout is the dominant constraint at this scope.** 3 of 5 fix subagents timed out despite making real progress. Workaround: write the report file FIRST as a skeleton, iterate in place. (Subagents that did this completed; subagents that read everything then tried to write at the end timed out.)
-
-3. **Cross-cutting parallel-subagent failure mode**: subagents cite each other instead of upstream. Wave 14 caught this for PRIME-RL math. Wave 15 caught it for OPSD + TAID math. The mitigation is mandate-upstream-verification in the prompt.
-
-4. **Prompt injection in tool outputs**: one subagent flagged that fake "don't reproduce copyrighted material" instructions appeared in its tool outputs throughout, designed to make it abandon the OPSD math fix. The subagent correctly ignored the injection and completed the task. The framework's MIT-licensed work with attribution is fully authorized; no copyright concern.
-
-## Open items for Wave 16
-
-1. `examples/gsm8k_grpo_with_sdpo/` — demonstrate SDPO column wiring end-to-end
-2. Gradient-flow tests for compose_loss channels (pre-staged in test reviewer's report)
-3. Recon-doc currency sweep: cross-check `docs/research/*RECONNAISSANCE.md` against current code state
-4. Real PRIME-RL end-to-end run with the new `LossOutputs` wrap (verify the wrap shape works in the real `setup_loss_fns` pipeline)
-5. `INTEGRATION_RECIPES.md` `compose_loss` signature display — collapse to `...` and link to `API_REFERENCE.md`, OR sync to all 17 kwargs
+> **📦 Archived (2026-06-08).** This point-in-time wave review has been moved to
+> [`docs/research/_archive/WAVE_15_FINAL_REVIEW.md`](_archive/WAVE_15_FINAL_REVIEW.md).
+> It is preserved verbatim for provenance but is superseded by the current
+> [`docs/METHODOLOGY.md`](../METHODOLOGY.md) and [`BACKLOG.md`](../../BACKLOG.md). See
+> [`docs/research/_archive/README.md`](_archive/README.md) for the archive index.

docs/research/WAVE_7_10_FINAL_REVIEW.md

@@ -1,423 +1,8 @@
 # Wave 7–10 Final Review — Cross-model adversarial check
 
-**Reviewer**: external model, Phase 11 of the deep work loop.
-**Date**: 2026-05-26.
-**Mandate**: find substantive flaws. The research thesis is
-primary-source-validated; this attacks *implementation correctness* and
-*scope creep*, not the thesis.
-
----
-
-## (a) Are the tests real evidence or theater?
-
-### Spike 006 (Qwen2.5-0.5B-Instruct CPU smoke, 9 tests)
-
-**Verdict: mostly tautology, with usable ablation tests.**
-
-The headline "loss 0.7390 → 0.0031, 99.6% reduction in 5 steps" is
-technically true and substantively near-tautological:
-
-1. **The same fixed ~50-token batch is reused for all 5 steps.**
-   `build_batch` returns one conversation; the test loop calls
-   `compose_loss(model, batch)` five times in a row. No reshuffle, no
-   second batch, no held-out anything.
-2. **0.5B params × AdamW(lr=1e-5) × identical 50-token batch ×
-   5 steps = textbook memorization regime.** A randomly-initialized MLP
-   would also reduce loss in this setup. The test does not distinguish
-   "the 3-channel composition is correct" from "AdamW reduces fixed-batch
-   loss on any non-degenerate objective."
-3. **The SDPO channel is zero throughout** (`sdpo_jsd=0.0` on every
-   row of `loss_curve.csv`). The verdict calls this "correct fallback
-   behavior"; what it actually is is *the entire SDPO channel never
-   being tested by this smoke*. The fallback is a literal `_zero(device)`.
-   `generalized_jsd_loss` has no end-to-end test on a real HF model
-   anywhere in the codebase. **This is the largest evidence gap for
-   V8.**
-4. **DPO uses dummy hard-coded reference logprobs** (`-30.0`, `-35.0`).
-   This tests that `-logsigmoid(small_positive)` is differentiable, not
-   that the trace-replay-DPO pipeline (reference-policy precompute +
-   collator + loss) wires together.
-5. The "loss decreases" assertion is `losses[-1] < losses[0]` — the
-   weakest version of monotonicity.
-
-**Genuine value**: model-loads test, chat-template test, the three
-α=0 / β=0 ablation tests. The ablations would catch a regression where
-weights stop disabling channels. The "5-step decrease" is the weakest
-test in the file.
-
-**Run.log inconsistency, not flagged anywhere**:
-`examples/qwen_05b_quickstart/run.log` shows step-1 total = 0.0379;
-the spike `verdict.md` quotes step-1 total = 0.2090 for the same code,
-same model. Either the seed isn't pinned through the model forward
-(likely — `torch.manual_seed(42)` is in `build_batch` only), or the
-package's `compose_loss` differs subtly from the spike's. **Quoting
-exact numbers from a non-reproducible run as evidence is the sloppy
-version of every research-replication scandal.**
-
-### Spike 007 (Claude Code ingester, 15 tests)
-
-**Verdict: strongest test suite of the three. Caveats apply.**
-
-Real engineering value:
-- Synthetic fixture exercises the actual record types (assistant,
-  user/tool_result, summary, system, sidechain). Tests assert structural
-  properties: history grows monotonically, `[THINKING]` stripped on
-  replay but kept in student_action, unique state_ids, tool_use
-  serialization, tool_result tagging.
-- `test_truncated_line_tolerated` would catch a real failure-mode
-  removal of the JSON-decode try/except.
-- Subagent and sidechain skip tests catch real production cases.
-
-Caveats:
-- **The "real session" test is hardcoded to one path on the author's
-  machine** (`/home/codeseys/.claude/projects/…/e4a34e2b-….jsonl`).
-  No env var, no fixture-discovery; the test is `skipif(not exists)`.
-  This is a manual integration test, not a CI test. ADR-002 said "CI
-  users substitute their own"; the substitution mechanism doesn't
-  exist.
-- The synthetic fixture is **author-written** and presumably designed
-  alongside the ingester. There is no scrubbed third-party fixture.
-- Acceptance criterion #3 in BACKLOG ("end-to-end smoke: real trace →
-  ingester → collator → 1-step `composer_total_loss`") is **unmet** —
-  the spike stops at "ingester emits TraceStates correctly." There is
-  no test that takes ingested records, runs the data collator, and runs
-  through `compose_loss`.
-
-This suite would catch real regressions in the ingester. Its weakest
-property: ships no contributor-runnable real-trace test.
-
-### Spike 008 (DiLoCo, 5 tests, single-process)
-
-**Verdict: the caveat is honest but says the test does not test what
-users will assume it tests.**
-
-BACKLOG acceptance criterion: *"Smoke test: 2 replicas × 4 inner steps
-× 2 outer rounds on the toy model from Spike 005, both replicas converge
-toward the same solution within tolerance."*
-
-What ships: **one** replica, mock manager whose `allreduce` is a
-**`passthrough` no-op** (test_diloco_smoke.py:78). This is "one
-replica's outer optimizer machinery fires," not "two replicas
-converge." The acceptance criterion was silently re-defined; the
-spike's verdict.md calls this a "limitation" but it is a redefinition.
-
-The recon doc (per ADR-003) claimed a "ready-to-paste" pattern with real
-shared-buffer averaging. The implementation hits a "post-hook
-sequencing bug." **One of the recon claim and the implementation is
-wrong**, and the gap is buried in verdict.md instead of fixed.
-
-**Genuine value**: `test_diloco_pseudogradient_sign_convention` is the
-**single best test in all of Wave 7-10**. It pins the sign convention
-with a concrete arithmetic prediction (`final == θ_initial + nudge`)
-and reports `wrong_sign_diff` on failure. A future torchft upgrade that
-flips the sign breaks this test loudly. ADR-003 specifically flagged
-this hazard, and the test catches it. Credit where due.
-
-**Separate flaw in `composer_diloco.py` docstring (lines 13–28)**: the
-"wrong-sign pseudogradient combined with SGD's subtract-grad semantics
-gives net step in the local-Δ direction once momentum builds up" gloss
-is incoherent. There is no "wrong-sign" pseudogradient.
-`θ_initial − θ_local` is the exact DiLoCo paper convention; SGD's
-`p ← p − lr·g` semantics are designed for it. The test is correct; the
-prose explaining why is wrong, and will mislead anyone porting the
-convention.
-
----
-
-## (b) Is the package a real framework or a shim?
-
-**Verdict: a structured shim around three real components and two
-stubs. Not yet a framework.**
-
-What `pip install composer-replication` delivers:
-- `compose_loss` — labeled in its own top docstring as "Do NOT use as
-  the production training loss." Re-exported as the headline package
-  API and used in the quickstart.
-- `build_batch` — a hard-coded fixed-conversation factory built for the
-  smoke (factorial / binary-search examples). Anyone using this in
-  real training is using example code as production.
-- `ClaudeCodeIngester` — real, working component. Solid.
-- `generalized_jsd_loss` — real, working (extracted from OPSD, MIT).
-- `extract_dpo_pairs`, `replay_trace`, teacher specs — real, but
-  require OpenRouter credentials + spend.
-- `ComposerReplicationTrainer` — TRL `GRPOTrainer` subclass.
-  Useful only with `[train]` extra. Not exercised end-to-end on any
-  real model in this repo.
-- `make_diloco_outer_loop` — wrapper. Useful only with `[diloco]` extra.
-
-What is missing for "pip install and start training":
-1. No GPU end-to-end example. The brief targets Qwen3-7B / Qwen3-32B.
-2. No CLI. `pyproject.toml` declares no `[project.scripts]`.
-3. No config schema (Hydra/Pydantic). Users hand-construct teacher
-   specs, hint generators, data collators.
-4. The `[train]` extra pulls TRL but **no integration test** of
-   `ComposerReplicationTrainer` against a real GRPO rollout exists in
-   this repo. Spike 005 used TinyLM; Spike 006 stubbed GRPO out
-   precisely to avoid TRL.
-5. **`build_batch` should not be public API.** It belongs in
-   `examples/`. Re-exporting at top level implies it is a general-purpose
-   utility.
-6. **Two sources of truth**: `composer_replication/loss.py` is a
-   near-copy of `spikes/006-…/compose_loss.py` with one import path
-   changed. The spike tests still import from the spike file. A bug fix
-   in one will not propagate. Same for `composer_diloco.py` ↔
-   `composer_replication/diloco/__init__.py`.
-
-Real framework value:
-- `ClaudeCodeIngester` with non-trivial logic.
-- `generalized_jsd_loss` with token-clip + temperature.
-- DiLoCo wrapper with sign-pinning test.
-- Sane package layout with optional extras for heavy deps.
-
-Net: **a successful directory restructure plus an installable wrapper
-around three real components and two stubs.** Calling Wave 10 "framework
-is installable with working entrypoints (✅)" is letter-of-the-law;
-the brief's "framework" connotation isn't yet earned.
-
----
-
-## (c) ADR defensibility
-
-### ADR-001 (local 5090 over Modal)
-
-**Reasoning defensible; execution missing.** The
-"iteration cycle 25–40s vs 3–5min" argument is concrete and matches
-reality. The "verification smoke, not production" framing is correct.
-
-**Gap**: Spike 002a-mini was never run on the 5090 either. Phase 10 in
-DEEP_WORK_LOOP_LOG.md is ⏳ pending. ADR-001 chose the 5090 over Modal,
-and **then nothing ran on either.** No `nvidia-smi` snapshot, no GPU
-step-time CSV, no bf16 numerics check. The "rule out CPU-only blind
-spots" goal is unmet. The ADR should be marked "Accepted (execution
-deferred)" or the spike should run.
-
-### ADR-002 (Claude Code JSONL trace source)
-
-**Defensible on every dimension the ADR considers; the dimensions are
-partial.** "1,015 real sessions, zero acquisition cost" is real. License
-and schema-stability arguments are well-sourced.
-
-**Adversarial counter not in the ADR**: Claude Code JSONL is the most
-self-serving choice. The framework targets training a coding-agent model.
-The training data is the author's own Claude Code sessions where the
-agent was Claude. The teacher pool (Spike 001) is OpenRouter-based and
-*includes Claude*. So:
-- "student action" = what Claude did.
-- teacher pool includes Claude.
-- DPO pairs = teachers' agreement vs Claude's literal text.
-
-This is **circular imitation**: training a future model to imitate
-Claude using Claude's outputs as the gold reference and Claude as one
-of the disagreement teachers. The teacher-disagreement signal density
-argument from Spike 001 is strongest with diverse teachers. With this
-trace source, the student-action is locked to one teacher family,
-biasing the disagreement signal. The ADR doesn't consider this; the
-ingester README doesn't flag it. **The ADR rationalizes the easy path
-without naming the data-leakage tradeoff.**
-
-### ADR-003 (torchft for DiLoCo)
-
-**Genuinely defensible choice.** Meta-maintained library; rolling-own
-trap correctly identified; license analysis (rejecting `diloco_simple`)
-is right; sign-convention risk named and tested.
-
-**Gap is in delivery, not decision.** ADR-003 §Consequences §1 says:
-"2 replicas, 4 inner steps, 2 outer rounds on a TinyMLP, shared-buffer
-mock allreduce, assertions: replica equality after sync, params actually
-moved, Nesterov state populated, sync count matches expected." Spike 008
-implements one replica + passthrough manager. The ADR commits to an
-implementation that the spike does not deliver, and the gap is flagged
-only in the spike's verdict, not in the ADR.
-
-If the recon doc said the pattern was "ready-to-paste" but actually
-hits a sequencing bug, **the recon doc is wrong** and an adversarial
-reviewer is allowed to point that out.
-
----
-
-## (d) Scorecard inflation
-
-The 5/10 → 9/10 update overstates. Test by test:
-
-- **Test 6 (DiLoCo integrated in runnable stack) → ✅?**
-  Letter-of-law yes, spirit no. `make_diloco_outer_loop` exists and
-  fires on one replica. **Zero references to torchft or DiLoCo in
-  `composer_trainer.py`** — DiLoCo is not integrated with the trainer.
-  No two-replica integration test, no real distributed run.
-
-- **Test 7 (real HF model loads + runs) → ✅?**
-  Yes — most legitimately closed item. Caveats from §(a) about depth
-  of evidence apply, but the literal test is met.
-
-- **Test 8 (real LLM-application trace ingested end-to-end) → ✅?**
-  Mostly yes. Ingester real and tested. **BACKLOG acceptance criterion
-  #3 ("end-to-end: real trace → ingester → collator → 1-step
-  `composer_total_loss`") is unmet.**
-
-- **Test 9 (framework installable with working entrypoints) → ✅?**
-  Letter-of-law yes, spirit partial. `pip install -e .` works; the
-  quickstart runs the smoke harness. Production entrypoint
-  (`ComposerReplicationTrainer` driven by a config) does not exist.
-
-- **Test 10 (non-author can complete the journey) → ✅?**
-  No. The supporting evidence is "Quickstart README + working
-  installable demonstrate the full path on Qwen2.5-0.5B in <5min, $0."
-  Test 10's original journey was "I have Qwen3-7B, I want a
-  Composer-style variant." The parenthetical concession in the update
-  ("For Qwen3-7B etc., GPU phase still gates the empirical demo")
-  ✅'s the item anyway.
-
-**Honest re-scoring**: 5/10 → **7/10 ✅, 1/10 ⚠️ partial (test 8),
-2/10 ❌ in spirit (tests 6, 10).** "9/10" overstates by ~2 points.
-
----
-
-## (e) Commit quality
-
-```
-ac05fbf Wave 10 — packaging: composer_replication is now pip-installable
-d52e126 Tidy .gitignore (de-dup *.jsonl, restore section blank lines)
-a35a8d7 Spike 007: include synthetic_session.jsonl fixture in repo
-57af35d Wave 7+8+9: spikes 006/007/008 — close vision-validation gaps V2/V5/V8
-ac4bfb4 Wave 7: Phase 2-4 of deep work loop — backlog, parallel research, three ADRs
-040eff8 Wave 6: vision validation self-audit (5/10 to 9/10 in 5 days, no GPU)
-```
-
-- `ac05fbf`, `d52e126`: accurate.
-- `a35a8d7`: accurate. Implies `57af35d` shipped a Spike 007 that did
-  not actually run cleanly for anyone cloning before this commit. Mild
-  overclaim risk on `57af35d`.
-- **`57af35d` is the single most overclaiming commit.** Title: "close
-  vision-validation gaps V2/V5/V8."
-  - V8: closed in the weakest sense (tautology critique above).
-  - V5: structural ingestion closes; BACKLOG acceptance #3 unmet.
-  - V2: silently re-defined (one replica, no convergence).
-  Three closures claimed; one partial, one redefined.
-- **Chronology problem**: `040eff8` (Wave 6) declared the **5/10 → 9/10
-  forecast** in the commit subject. `ac4bfb4` (Wave 7, *next* commit)
-  added the BACKLOG and ADRs — i.e., the *plan* to make the forecast
-  true. `57af35d` (Wave 7-9) executed and ratified the 9/10 without
-  re-auditing whether each item was actually closed in spirit. **No
-  commit re-audits the scorecard against actually delivered evidence.**
-
----
-
-## (f) Adversarial reviewer's strongest line of attack
-
-> "You have a research replication framework whose only published smoke
-> is a 5-step fixed-batch overfit on a 0.5B model on CPU, where the SDPO
-> channel is silently disabled (sdpo_jsd=0 throughout), the DPO channel
-> uses dummy reference logprobs, and the GRPO channel is replaced with
-> a stub. Of the three channels you advertise, **zero are tested
-> end-to-end on a real HF model.** Your DiLoCo integration is one
-> replica with a no-op `allreduce`. Your real-trace ingester is tested
-> against a fixture you wrote yourself plus a hardcoded path on your
-> laptop. Your scorecard moved from 5/10 to 9/10 with no GPU spend, no
-> third-party validation, and one commit that closed three vision-
-> validation gaps with one commit message. You are asking the reader to
-> believe that a $9B-startup commercial product is replicated by a CPU
-> smoke and three green test files — none of which the company itself
-> would call 'replicated.'"
-
-**Weakest defense**: "It's just v0.1 / smoke phase / GPU is the next
-phase." The *commit log and scorecard claim otherwise.* The defense
-"v0.1 caveat" only works if the v0.1 framing is honest at the top of
-the README and scorecard — and it is not.
-
-**Strongest actual defense**: the four primary-source-validated recon
-docs and Spike 001's measured cost floor. The *thesis* is credible and
-auditable. The *implementation phase* is overclaimed.
-
----
-
-## What to fix before publishing publicly (priority order)
-
-### 1. Re-state the scorecard honestly (BLOCKER)
-Replace 5/10 → 9/10 with **5/10 → 7/10 ✅, 1/10 ⚠️, 2/10 ❌-spirit.**
-List the spirit-failures explicitly (test 6 trainer integration, test 8
-end-to-end, test 10 non-author). Single most important fix; everything
-else compounds on the inflated scorecard.
-
-### 2. Fix Spike 008's V2 claim (BLOCKER)
-Either (a) add a real two-replica multiprocessing test (ADR-003 says
-this is feasible; the spike claims it isn't — reconcile), or (b) mark
-V2 as ⚠️ partial and rewrite BACKLOG: "machinery fires on one replica,
-sign convention pinned; cross-replica convergence deferred to GPU
-phase." Pick one.
-
-### 3. Strengthen Spike 006 against the tautology critique
-Two cheap wins:
-- Test that loss decreases on **two alternating fixed batches** over 10
-  rounds (not just one memorized batch).
-- Test where **`alpha_sdpo=10.0` and SDPO actually fires** (truncate
-  ctx_teacher to T_s tokens for matching shape). The SDPO channel is
-  *not exercised on a real HF model anywhere* in the codebase. Largest
-  evidence gap for V8.
-
-### 4. Run Spike 002a-mini on the local 5090
-ADR-001 made the choice; the spike was not run. Either drop the ADR
-(decision deferred) or run the spike (~30 min wall-clock per ADR's own
-estimate). Until then, the framework has zero GPU evidence of any kind.
-
-### 5. Fix the run.log / verdict.md numerical inconsistency
-Quickstart run.log shows step-1=0.0379; spike verdict shows step-1=0.2090.
-Either pin the seed properly or document non-reproducibility and quote
-a band rather than exact numbers.
-
-### 6. Acknowledge Claude Code JSONL's circularity in ADR-002
-Add a "Risks accepted" entry naming the data-leakage concern: training
-on Claude's outputs while Claude is in the teacher pool produces a
-biased disagreement signal. Spike 007 README should also flag it.
-
-### 7. Decide what `compose_loss` and `build_batch` are
-Either rename to `compose_loss_smoke` (and keep
-`ComposerReplicationTrainer._compute_loss` as production), or make
-`compose_loss` actually production-grade and demote `build_batch` out
-of public API. Production-disclaimed harness as the package's headline
-import is confusing.
-
-### 8. Eliminate dual sources of truth
-`spikes/006-…/compose_loss.py` ↔ `composer_replication/loss.py`, and
-`spikes/008-…/composer_diloco.py` ↔ `composer_replication/diloco/__init__.py`.
-Make the spike import from the package; delete the duplicate.
-
-### 9. Add the missing real-trace end-to-end test in Spike 007
-Take ingester output → Spike 005 data collator → 1 step of `compose_loss`.
-This is BACKLOG acceptance #3; ~50 lines of test code closes V5's
-spirit gap.
-
-### 10. Fix the sign-convention docstring in `composer_diloco.py`
-Replace the incoherent "wrong-sign + SGD subtract = right answer with
-momentum" gloss with: *"DiLoCo defines pseudo-gradient as
-`θ_initial − θ_local`; this is the negative of the local update
-direction, and standard SGD subtracts gradients, so the outer step
-moves in the local-update direction. No negation required."* The test
-is correct; the prose explaining it isn't.
-
----
-
-## Credit where due
-
-- **Spike 007's `ClaudeCodeIngester`** is real, working, well-tested
-  software with non-trivial logic (sidechain skip, thinking-block
-  strip-on-replay, malformed-line tolerance). The synthetic fixture
-  exercises the structural cases properly.
-- **Spike 008's pseudogradient-sign-convention test** is the single
-  best test in all of Wave 7-10. It pins a known torchft hazard with an
-  explicit arithmetic prediction and a `wrong_sign_diff` reported on
-  failure.
-- **Spike 006's α=0 / β=0 ablation tests** would catch real regressions
-  and document channel-disable semantics.
-- **All three ADRs are properly traceable to recon documents**
-  (MODAL_RECONNAISSANCE, TRACE_SOURCE_RECONNAISSANCE,
-  DILOCO_RECONNAISSANCE). The decisions can be challenged; the *process*
-  is auditable, which is rare.
-- **Package layout** (`loss`, `batch`, `opsd`, `teacher_replay`,
-  `ingestion/claude_code`, `diloco`, `trainer`) is sane; optional
-  extras correctly avoid forcing TRL/torchft on every install.
-
-The work product is not zero. It is overclaimed by roughly one
-scorecard tier and one BACKLOG acceptance criterion. Fixing items
-1, 2, 3, 5 above moves the framework from "publishable with a generous
-reviewer" to "publishable with a critical reviewer." Items 4 and 6
-move it from "research replication" to "evidenced research replication."
+> **📦 Archived (2026-06-08).** This point-in-time wave review has been moved to
+> [`docs/research/_archive/WAVE_7_10_FINAL_REVIEW.md`](_archive/WAVE_7_10_FINAL_REVIEW.md).
+> It is preserved verbatim for provenance but is superseded by the current
+> [`docs/METHODOLOGY.md`](../METHODOLOGY.md), [`BACKLOG.md`](../../BACKLOG.md), and
+> [`docs/V1_V8_COVERAGE.md`](../V1_V8_COVERAGE.md). See
+> [`docs/research/_archive/README.md`](_archive/README.md) for the archive index.

docs/research/_archive/README.md

@@ -0,0 +1,39 @@
+# docs/research/_archive — historical research reviews
+
+This directory holds **research-flavored, point-in-time** documents: the
+cross-model adversarial wave reviews and recon audits that critiqued the
+framework at a specific commit. They are preserved **verbatim for provenance**
+and are **not** maintained as current truth.
+
+> **What's current instead.** For live research/methodology, read
+> [`docs/METHODOLOGY.md`](../../METHODOLOGY.md), the standing reconnaissance and
+> landscape notes still in [`docs/research/`](../), and the accepted ADRs under
+> [`docs/adrs/`](../../adrs/README.md). For the live framework state, see
+> [`docs/OVERVIEW.md`](../../OVERVIEW.md) and [`BACKLOG.md`](../../../BACKLOG.md).
+> Where an archived review and a current doc disagree, the current doc wins.
+
+Each archived `WAVE_*_FINAL_REVIEW.md` file's original path under
+`docs/research/` still contains a one-line **redirect stub** so older prose
+references (e.g. ADR-007's citation of Wave-13 "Finding 2") keep resolving.
+
+## Contents
+
+| Archived file | Original path | What it is | Superseded by |
+|---|---|---|---|
+| [`WAVE_7_10_FINAL_REVIEW.md`](WAVE_7_10_FINAL_REVIEW.md) | `docs/research/WAVE_7_10_FINAL_REVIEW.md` | Cross-model adversarial check of Waves 7–10 | `docs/METHODOLOGY.md`; `docs/V1_V8_COVERAGE.md` |
+| [`WAVE_13_FINAL_REVIEW.md`](WAVE_13_FINAL_REVIEW.md) | `docs/research/WAVE_13_FINAL_REVIEW.md` | Wave 13 adversarial cross-model review (ADR-007 cites Finding 2) | ADR-007; `BACKLOG.md` |
+| [`WAVE_14_FINAL_REVIEW.md`](WAVE_14_FINAL_REVIEW.md) | `docs/research/WAVE_14_FINAL_REVIEW.md` | Wave 14 adversarial cross-model review | `docs/TROUBLESHOOTING.md`; `BACKLOG.md` |
+| [`WAVE_15_FINAL_REVIEW.md`](WAVE_15_FINAL_REVIEW.md) | `docs/research/WAVE_15_FINAL_REVIEW.md` | Wave 15 multi-angle self-critique + fix wave | `docs/V1_V8_COVERAGE.md`; `BACKLOG.md` |
+| [`WAVE_16_RECON_AUDIT.md`](WAVE_16_RECON_AUDIT.md) | (already archived here) | Wave 16 reconnaissance audit of the recon/landscape docs | the recon/landscape docs it audited |
+
+## Why archive instead of delete
+
+These reviews are the framework's adversarial audit trail — they record which
+claims were challenged, which were fixed, and which were left open. Several
+accepted ADRs cite them by path. Archiving (rather than deleting) preserves the
+provenance and keeps those citations resolvable, while signalling that the
+reviews are snapshots superseded by the current methodology and coverage docs.
+
+> Non-research point-in-time artifacts (wave logs, the dated cross-family /
+> final-verify review bundles) live in the sibling
+> [`docs/_archive/`](../../_archive/README.md) instead.

docs/research/_archive/WAVE_13_FINAL_REVIEW.md

@@ -0,0 +1,239 @@
+# Wave 13 Adversarial Cross-Model Review
+
+**Reviewer:** Claude Opus 4.7 (sub-agent via delegate_task)
+**Date:** 2026-05-26
+**Scope:** Wave 13 additions only (35 new tests, 4 ADRs, 6 new modules)
+**Method:** Read-and-grep audit + targeted test runs (CPU)
+
+## Top-line verdict
+
+**CONDITIONAL PASS with two BLOCKERs.** Wave 13 substantially advances
+the brief expansion (serverless DiLoCo abstraction, replaysim
+normalization, three distillation losses, PRIME-RL recipe, Monarch
+tie-in). The **distillation losses are the strongest deliverable** —
+real, well-tested, mathematically faithful to the cited papers. The
+serverless-DiLoCo local executor + ObjectStoreAllReduce barrier are
+also genuine and exercised by 3 real multi-process tests.
+
+**However, two material claims are not test-validated, and one new
+module silently produces a degenerate loss in its primary code path.**
+ADR claims that say "X is added to compose_loss" describe code that
+wasn't actually written. The MockManager → DiLoCo "drop-in" is
+unverified end-to-end.
+
+Wave 11's reviewer found 2 genuine BLOCKERs. This review finds **2
+BLOCKERs + 4 SUGGESTIONs + 2 NITs**.
+
+---
+
+## Finding 1 — BLOCKER: PRIME-RL `composer_loss.loss_fn` SDPO term is mathematically degenerate (always 0)
+
+**Severity:** BLOCKER
+**Evidence:** `composer_replication/recipes/prime_rl/composer_loss.py:79-86`
+
+The PRIME-RL composer-loss adapter applies `unsqueeze(-1)` to `(B, T)`
+log-prob tensors before passing them to `generalized_jsd_loss`, which
+calls `F.log_softmax(..., dim=-1)`. Softmax of a single-element vector
+is exactly 1.0; its log is 0. Therefore both `student_log_probs` and
+`teacher_log_probs` are identically zero, the JSD between them is 0,
+and the SDPO contribution **is always 0 regardless of `alpha_sdpo` or
+the actual log-prob values.**
+
+```python
+>>> import torch.nn.functional as F
+>>> F.log_softmax(torch.randn(2, 3, 1), dim=-1)
+tensor([[[0.],[0.],[0.]],[[0.],[0.],[0.]]])
+```
+
+The docstring calls this "a deliberate approximation," but it is not
+an approximation — it's a mathematically degenerate operation that
+silently disables channel 2.
+
+**Fix direction:**
+- Gate the SDPO branch behind `len(trainer_lp.shape) >= 3`, raising
+  `NotImplementedError` until PRIME-RL surfaces full logits.
+- Update `prime_rl_recipe.md` and ADR-006 to stop claiming PRIME-RL
+  has working SDPO; mark it deferred.
+
+---
+
+## Finding 2 — BLOCKER: ADR-007 declares `compose_loss` kwargs that were never added
+
+**Severity:** BLOCKER
+**Evidence:**
+- `docs/adrs/ADR-007-self-distillation-losses.md:103-108` claims:
+  > `composer_replication.compose_loss` gets new optional kwargs:
+  >   - `dpo_variant: Literal["dpo", "simpo"] = "dpo"` — switches channel 3
+  >   - `sdpo_wrapper: Literal["none", "taid", "entropy_opd"] = "none"` — wraps channel 2
+  >   - `taid_schedule_step: int | None = None`
+  >   - `taid_total_steps: int | None = None`
+- `composer_replication/loss.py:54-65` actual signature has **none**
+  of these. `grep -n "dpo_variant\|sdpo_wrapper\|taid"
+  composer_replication/loss.py` returns empty.
+
+The new losses live in `composer_replication.distillation` as
+standalone functions but **are not wired into the framework's actual
+loss composition.** A user reading ADR-007 + the README would believe
+`compose_loss(model, inputs, dpo_variant="simpo", sdpo_wrapper="taid", ...)`
+works; it would raise `TypeError`. The 17 distillation tests verify
+the standalone losses but never exercise integration.
+
+**Fix direction:**
+- Either (a) add the kwargs to `compose_loss` and write at least one
+  integration test combining e.g. SDPO+TAID (~30 LOC change), or
+- (b) downgrade ADR-007 status to "Standalone losses landed;
+  integration deferred to Wave 14."
+
+---
+
+## Finding 3 — SUGGESTION: `default.yaml` replaysim recipe uses string ops on list-of-dict fields
+
+**Severity:** SUGGESTION (would be BLOCKER if a test exercised the real path)
+**Evidence:**
+- `composer_replication/recipes/replaysim/default.yaml` configures
+  `text_length_filter`, `words_num_filter`, `special_characters_filter`,
+  `document_deduplicator` with `text_keys: ["chosen", "rejected"]`.
+- In the record produced by `_dpo_pair_to_dj_record`, `chosen` and
+  `rejected` are **lists of dicts**
+  (`[{"role": "assistant", "content": "..."}]`) — not strings.
+- data-juicer's `text_length_filter` expects string-typed fields;
+  running it on a list will either crash or no-op silently.
+
+The reason no test catches this: tests only validate the real path *if
+data-juicer is installed*, and even then only check `__init__` succeeds.
+There is no test that calls `normalize()` against a real data-juicer
+executor with the default recipe.
+
+**Fix direction:**
+- Reshape `_dpo_pair_to_dj_record` to extract `content` strings
+  alongside the messages-format list.
+- Add one test (skip-marked unless `data_juicer` is importable) that
+  runs the real op-graph on 3 hand-crafted records.
+
+---
+
+## Finding 4 — SUGGESTION: MockManager → torchft.DiLoCo "drop-in" claim is unverified end-to-end
+
+**Severity:** SUGGESTION
+**Evidence:**
+- `composer_replication/diloco/serverless/allreduce.py:188-191` claims
+  MockManager "drops into" `make_diloco_outer_loop`.
+- The only test covering MockManager (`test_mock_manager_shape_compat`)
+  is a `hasattr` smoke that calls `.allreduce` on a `world_size=1`
+  store (passthrough).
+- torchft.Manager has additional surface area
+  (`current_step`, `is_leader`, `_pg`, `report_error`,
+  internal step accounting) that DiLoCo's `_apply_pseudogradient`
+  may consult depending on version.
+
+**Fix direction:**
+- Add a single integration test that constructs
+  `make_diloco_outer_loop(manager=MockManager(store), ...)` against a
+  tiny `nn.Linear` and runs one outer round — even single-process.
+- Audit `torchft/local_sgd.py` for the `Manager`-rooted call sites and
+  add stubs for any methods DiLoCo actually consults beyond `allreduce`.
+
+---
+
+## Finding 5 — SUGGESTION: README claim "9 multi-process tests" is mildly inflated
+
+**Severity:** SUGGESTION (NIT bordering)
+**Evidence:**
+- README.md and V1_V8_COVERAGE both state: *"9 multi-process tests
+  pinning the allreduce barrier."*
+- Actual breakdown:
+  - 4 single-process unit tests + `test_mock_manager_shape_compat` (5)
+  - 4 multi-process tests spawning subprocesses (parametrized [2,3] of
+    `_runs_allreduce_across_replicas`, `_handles_multiple_rounds`,
+    `_reports_failed_replicas`)
+- Of the 4 multi-process tests, only **3 actually exercise the
+  allreduce barrier**; `_reports_failed_replicas` deliberately raises
+  before any allreduce call.
+
+**Wave 13 clearly does NOT fake-pass via world_size=1** — the multi-
+process barrier is real. But the count is rounded up.
+
+**Fix direction:** Replace "9 multi-process tests" with "9 tests
+covering the serverless DiLoCo layer, of which 4 spawn real
+subprocesses and 3 exercise the allreduce barrier across replicas."
+
+---
+
+## Finding 6 — SUGGESTION: PRIME-RL channel 1 is REINFORCE not GRPO; ignores `inference_logprobs`
+
+**Severity:** SUGGESTION
+**Evidence:** `composer_replication/recipes/prime_rl/composer_loss.py:62-68`
+computes:
+```python
+grpo_loss = -(advantages * trainer_lp * mask).sum() / mask.sum().clamp_min(epsilon)
+```
+
+This is plain REINFORCE with advantage. PRIME-RL's `LossInputs`
+exposes `inference_logprobs` precisely because GRPO-with-replay-buffer
+requires the importance-sampling ratio
+`exp(trainer_lp - inference_lp)` (PPO-style clipped objective).
+
+The file says "SKELETON" so this isn't a hidden bug per se, but the
+loss is **labeled GRPO and is not GRPO**.
+
+**Fix direction:** Either implement the ratio + clipping (~20 LOC) or
+rename channel-1 comment to "REINFORCE-with-advantage stub" with a TODO.
+
+---
+
+## Finding 7 — NIT: ModalExecutor / HFJobsExecutor are skeleton-only with `NotImplementedError` in `__init__`
+
+**Severity:** NIT (this is documented, but README phrasing is slightly soft)
+**Evidence:** Honestly documented as skeletons in the code, ADR-005,
+and README. NIT: a user trying `ModalExecutor()` gets a runtime error
+rather than an import-time clue.
+
+**Fix direction:** Low priority. Update README phrase to "skeleton-only
+— raises NotImplementedError until v0.x." Or use a `__getattr__` on
+the package that raises a clearer message.
+
+---
+
+## Finding 8 — NIT: SimPO test uses positive log-probs (impossible values)
+
+**Severity:** NIT
+**Evidence:** `test_distillation_losses.py:27-46` calls `simpo_loss`
+with `chosen=tensor([0.5, 0.4, 0.3])`. Log-probabilities are bounded
+above by 0; positive values aren't possible from any softmax. The tests
+still verify the formula correctly, but the test inputs aren't legal.
+
+**Fix direction:** Use negative values — purely cosmetic.
+
+---
+
+## Cross-cutting risk check
+
+73 tests passed in 29.29s on the CPU-fast subset. Spike 008 5/5 still
+pass. The new `composer_replication.diloco.serverless` package is
+purely additive; the existing `make_diloco_outer_loop` is untouched.
+**No cross-wave regressions detected on CPU.** GPU tests + slow CPU
+e2e tests not re-run; regression risk low since Wave 13 doesn't touch
+their dependencies.
+
+---
+
+## Summary scorecard
+
+| Item | Verdict |
+|---|---|
+| Distillation module (SimPO/TAID/Entropy-Aware OPD) standalone | ✅ Real, well-tested, paper-faithful |
+| Distillation integrated into `compose_loss` | ❌ **Not implemented** despite ADR-007 (Finding 2) |
+| ObjectStoreAllReduce + LocalProcessExecutor | ✅ Real multi-process barrier validated |
+| MockManager → DiLoCo drop-in | 🟡 Shape-checked only; integration unverified (Finding 4) |
+| Modal/HFJobs adapters | 🟡 Honestly documented as skeletons (Finding 7) |
+| Replaysim DJNormalizer passthrough | ✅ Works |
+| Replaysim default.yaml against real data-juicer | ❌ **Recipe field types don't match record shape** (Finding 3) |
+| PRIME-RL composer_loss.loss_fn | ❌ **SDPO term silently 0** (Finding 1); channel 1 is REINFORCE not GRPO (Finding 6) |
+| Monarch actors | ✅ Honest skeleton; raises NotImplementedError |
+| Altered-minds tie-in doc | ✅ Design-only, scoped honestly |
+| 35 new tests | All pass; 3 of 4 multi-process tests are genuine (Finding 5) |
+
+**Recommendation:** Address Findings 1 and 2 before publishing the
+Wave 13 expansion as "closed." Findings 3 and 4 should be addressed
+before any user attempts the real data-juicer or real torchft DiLoCo
+path. Findings 5–8 are cleanup.

docs/research/_archive/WAVE_14_FINAL_REVIEW.md

@@ -0,0 +1,263 @@
+# Wave 14 Adversarial Cross-Model Review
+
+**Reviewer:** Claude Opus 4.7 (sub-agent via delegate_task)
+**Date:** 2026-05-26
+**Method:** Read every Wave 13 finding, every Wave 14 closure, all 4 doc files, **cloned PRIME-RL upstream to verify T4 claims**, ran 61 wave-relevant tests.
+
+## Top-line verdict
+
+**CONDITIONAL PASS with 1 BLOCKER + 4 SUGGESTIONs + 2 NITs.** Wave 14
+closes Wave 13 BLOCKER 2 (T1 — compose_loss kwargs) and Suggestion 3
+(T2 — replaysim) cleanly. T3 (MockManager surface audit) is solid but
+only tests `world_size=1`. **T4 (PRIME-RL "real GRPO + DPPO") does not
+match PRIME-RL's actual `default_loss_fn`** despite claiming to mirror
+it; that error has been pasted into USER_GUIDE.md, INTEGRATION_RECIPES.md,
+and API_REFERENCE.md.
+
+Same signal-to-noise as Wave 11 + Wave 13 reviewers: 1 genuine BLOCKER.
+
+---
+
+## Finding 1 — BLOCKER: T4 PRIME-RL "DPPO importance-sampling-ratio clip" is neither importance sampling nor matches PRIME-RL.
+
+**Severity:** BLOCKER
+**Evidence:** `composer_replication/recipes/prime_rl/composer_loss.py:118-131`.
+The implementation computes
+```python
+grpo_loss = -(advantages * trainer_lp * keep_mask).sum() / keep_mask.sum()
+```
+That's **pure REINFORCE-with-advantage** — the masking gate is the only
+nod toward DPPO; there is no importance-sampling ratio multiplication
+anywhere.
+
+**Real PRIME-RL** (`/tmp/prime-rl-clone/src/prime_rl/trainer/rl/loss.py:128-153`,
+the `default_loss_fn` on `main` as of 2026-05-26):
+```python
+log_importance_ratio = trainer_logprobs - inference_logprobs
+importance_ratio     = torch.exp(log_importance_ratio)
+probs_diff           = torch.exp(trainer_logprobs) - torch.exp(inference_logprobs)
+positive_advantages  = advantages > 0
+dppo_invalid_mask_high = probs_diff > loss_config.dppo_mask_high
+dppo_invalid_mask_low  = probs_diff < -loss_config.dppo_mask_low
+dppo_invalid_mask = torch.where(positive_advantages, dppo_invalid_mask_high, dppo_invalid_mask_low)
+keep_mask = loss_mask & ~dppo_invalid_mask
+pg_loss = -(keep_mask * advantages * importance_ratio).sum()  # NO division
+kl_loss = adv_tau * (log_importance_ratio**2 * keep_mask).sum()  # KL term
+```
+
+**Three concrete divergences from Wave 14's implementation:**
+
+1. **Mask gate is on `probs_diff`** (a probability-space quantity), NOT
+   `log_ratio` (a log-space quantity). These have different magnitudes:
+   `probs_diff=0.2` corresponds to `log_ratio≈log(1.2)≈0.18` for a
+   trainer prob of 1.0 vs inference prob of 0.8. With our `log_ratio>4.0`
+   gate, the mask never fires for normal training distributions; PRIME-RL's
+   `probs_diff>0.2` gate fires routinely.
+
+2. **PRIME-RL multiplies by `importance_ratio = exp(log_ratio)`**;
+   Wave 14 multiplies by `trainer_lp` directly. This is the difference
+   between actual policy-gradient correction (PRIME-RL) and naive
+   REINFORCE.
+
+3. **PRIME-RL's mask is sign-conditioned on advantage** (positive
+   advantages clipped against `dppo_mask_high`, negative against
+   `-dppo_mask_low`); Wave 14 ORs them together unconditionally.
+
+**Plus:** the KL term is missing entirely.
+
+**Plus:** the defaults claimed as "PRIME-RL's defaults" — `dppo_mask_high=4.0,
+dppo_mask_low=-4.0` — are wrong. PRIME-RL's `DefaultLossConfig`
+(`configs/trainer.py:412-424`) sets `dppo_mask_high=0.2, dppo_mask_low=0.2`
+with `Field(..., ge=0)` validation that would *reject* a negative value.
+PRIME-RL's code negates at use site: `probs_diff < -loss_config.dppo_mask_low`.
+
+**Plus:** the docstring (`composer_loss.py:32-49`), USER_GUIDE.md:599-608,
+INTEGRATION_RECIPES.md:426-429 + 482-487, and API_REFERENCE.md:1364 all
+repeat the wrong formula and the wrong "matches PRIME-RL" claim.
+
+**Fix direction:** Either (a) actually mirror `default_loss_fn` (mask on
+`probs_diff`, multiply by `importance_ratio`, add KL term, advantage-
+conditioned mask, `.sum()` reduction with token-count returned for
+caller-side scaling), or (b) drop the "matches PRIME-RL" framing and
+rename to "REINFORCE-with-advantage stub + log-ratio mask" everywhere.
+
+Wave 13 Finding 6 is **not actually closed** by Wave 14.
+
+---
+
+## Finding 2 — SUGGESTION: ADR-007 still says Wave 14 hasn't done the integration.
+
+**Severity:** SUGGESTION
+**Evidence:** `docs/adrs/ADR-007-self-distillation-losses.md:104-122` reads:
+> **Wave 14+ work — `compose_loss` integration is NOT in this wave**
+> ... Wave 14 plan: add the four kwargs ...
+
+But Wave 14 *did* add them (verified — `loss.py:80-93`). The ADR was
+written defensively after Wave 13 review and never updated when T1 landed.
+
+**Net effect:** a user reading ADR-007 is told the SimPO/TAID kwargs
+don't work; a user reading USER_GUIDE/API_REFERENCE is told they do.
+
+**Fix direction:** flip ADR-007 status section to "Closed in Wave 14 —
+see test_compose_loss_integration.py".
+
+---
+
+## Finding 3 — SUGGESTION: ModalExecutor instantiation example in INTEGRATION_RECIPES is dead code.
+
+**Severity:** SUGGESTION
+**Evidence:** `docs/INTEGRATION_RECIPES.md:519-533` shows
+```python
+executor = ModalExecutor(app="composer-prime-rl")
+executor.launch_replicas(...)
+```
+But `composer_replication/diloco/serverless/modal.py:64-66` raises
+`NotImplementedError` from `__init__`. Same pattern in `HFJobsExecutor`.
+The recipe doc warns about skeleton-status much further down (line 731),
+but the inline code example at line 519 will break the moment a reader
+copy-pastes it.
+
+Wave 13 Finding 7 noted this softness; Wave 14 made it worse by writing
+example code that calls a constructor that always raises.
+
+**Fix direction:** in every code block that calls `ModalExecutor(...)`,
+prepend a comment `# Wave 14: skeleton — raises NotImplementedError`
+or flip examples to `LocalProcessExecutor`.
+
+---
+
+## Finding 4 — SUGGESTION: MockManager + DiLoCo integration test only exercises `world_size=1`.
+
+**Severity:** SUGGESTION
+**Evidence:** `composer_replication/diloco/serverless/tests/test_serverless_diloco_integration.py:44-51`,
+`:108-109`, `:161`. Both `test_mockmanager_diloco_outer_round_completes`
+and `test_mockmanager_diloco_two_outer_rounds_step_counter` use
+`world_size=1`.
+
+With one replica, `ObjectStoreAllReduce.allreduce` returns the tensor
+unchanged (its own mean), so an averaging bug in the multi-replica path
+could not be caught by this test. The pseudo-gradient sign convention
+is pinned by the unrelated spike-008 test, but **no test combines
+MockManager + DiLoCo + multi-process** — i.e. the actual deployment
+scenario is unverified end-to-end.
+
+Wave 13 Finding 4 is closed in spirit (call surface is now exhaustive)
+but not in the deepest sense.
+
+**Fix direction:** add one multi-process test that spawns `n_replicas`
+subprocesses, each constructing `MockManager(store) → make_diloco_outer_loop`,
+and asserts that after one outer round all replicas converge to the same
+parameter values (i.e. averaging actually happened).
+
+---
+
+## Finding 5 — SUGGESTION: T4 unit tests pin the wrong implementation as ground truth.
+
+**Severity:** SUGGESTION
+**Evidence:** `composer_replication/recipes/prime_rl/tests/test_composer_loss.py:90-128`
+(`test_dppo_mask_clips_extreme_ratios`). The expected value `1.5/3` is
+computed against the buggy formula (Finding 1).
+
+The 10 PRIME-RL tests all pass — but they're testing self-consistency,
+not parity with PRIME-RL. A reader looking at "10 unit tests, all green"
+infers correctness; correctness is not what they verify. This is the
+kind of test honesty failure that Wave 11 + Wave 13 reviewers found in
+different forms.
+
+**Fix direction:** add at least one test whose expected value is
+hand-computed from `default_loss_fn` in PRIME-RL (or import + invoke
+`default_loss_fn` if the dependency is available, mark the test
+`@pytest.mark.skipif(not _HAS_PRIME_RL)`).
+
+---
+
+## Finding 6 — NIT: README/test-count drift.
+
+Wave 14 task description claims "124 tests passing as of Wave 14"; actual
+`pytest --collect-only` reports **134 collected**. Of those, the 61-test
+wave-relevant subset all pass. Not a defect, but the headline number is
+now off in the same way Wave 13's "9 multi-process tests" was off.
+
+---
+
+## Finding 7 — NIT: `loss_fn` docstring claims "DPPO importance-sampling-ratio clipping — implemented" (`composer_loss.py:9`).
+
+Implementation contains no importance-ratio multiplication anywhere.
+Even if Finding 1 is rejected and the team decides "PRIME-RL match isn't
+a goal", the docstring is internally false: it announces ISR clipping
+in a function that does not multiply by `exp(log_ratio)`.
+
+---
+
+## Cross-cutting
+
+The four doc subagents wrote internally consistent text but inherited
+T4's mathematical error. **Three of the four doc files repeat the same
+wrong formula verbatim.** This is exactly the failure mode Wave 11/13
+reviewers flagged: parallel subagents cross-citing each other rather
+than the upstream source of truth.
+
+The 61 tests in the Wave-14-touched dirs pass cleanly. T1, T2, and T3
+are real closures with real coverage. The framework is in a **better**
+state than end-of-Wave-13 — but it has not actually closed Wave 13
+Finding 6, and it has propagated a subtler version of the same
+mathematical-mismatch bug into the user-facing documentation.
+
+---
+
+## Summary scorecard
+
+| Wave 13 Finding | Wave 14 status | Verdict |
+|---|---|---|
+| BLOCKER 1 (PRIME-RL SDPO degenerate) | Fixed parent-side; channel 2 raises NotImplementedError | ✅ closed |
+| BLOCKER 2 (compose_loss kwargs not added) | T1 added them + 11 integration tests | ✅ closed |
+| Suggestion 3 (replaysim YAML field types) | T2 dual-shape reshape + real DJ e2e + caught related bug | ✅ closed |
+| Suggestion 4 (MockManager → DiLoCo gap) | T3 surface audit + integration test | 🟡 closed for `world_size=1`; multi-process unverified |
+| Suggestion 5 ("9 multi-process tests" inflated count) | Not addressed | 🟡 carried over |
+| Suggestion 6 (PRIME-RL channel 1 REINFORCE not GRPO) | T4 thought it closed this | ❌ **NOT closed — mathematically wrong** |
+| Suggestion 7 (Modal/HFJobs skeleton clarity) | Made worse by INTEGRATION_RECIPES dead code | 🟡 regression |
+| NIT 8 (SimPO test positive log-probs) | Not addressed | 🟡 carried over |
+
+## Wave 14b follow-up (2026-05-26)
+
+After Wave 14b closed Finding 1 by re-reading PRIME-RL upstream and
+matching `default_loss_fn` byte-for-byte, the Wave 14b subagent flagged
+a **new** structural issue not in the Wave 14 review:
+
+**PRIME-RL's `setup_loss_fns` (upstream `loss.py:320-327`) expects the
+custom loss function to return `LossOutputs(loss, metrics={...})`, not
+a bare scalar tensor.** Our recipe still returns a bare scalar. This
+predates Wave 14 (it's been wrong since the recipe was first written in
+Wave 13) but was never caught because no test runs against actual
+PRIME-RL.
+
+**Status:** documented; deferred to Wave 15. Not blocking for Wave 14b's
+closure of Finding 1, because the formula now matches upstream — the
+return-shape mismatch is a separate adapter-level issue. Tests still
+pass because they invoke our `loss_fn` directly without going through
+PRIME-RL's `compute_loss` pipeline.
+
+**Fix direction (Wave 15):** wrap the return value in a duck-typed
+`LossOutputs` (provided by PRIME-RL when installed; substituted with a
+NamedTuple shim when not). Add an integration smoke test against PRIME-RL
+to catch this and similar adapter-shape regressions.
+
+## Final Wave 14 + 14b status
+
+| Wave 13 / 14 finding | Wave 14b status |
+|---|---|
+| W13 BLOCKER 1: PRIME-RL SDPO degenerate | ✅ closed (parent, channel 2 deferred) |
+| W13 BLOCKER 2: compose_loss kwargs not added | ✅ closed (Wave 14 T1) |
+| W13 Suggestion 3: replaysim YAML field types | ✅ closed (Wave 14 T2) |
+| W13 Suggestion 4: MockManager → DiLoCo gap | ✅ closed (Wave 14 T3 + Wave 14b multi-process test) |
+| W13 Suggestion 6: PRIME-RL channel 1 REINFORCE not GRPO | ✅ **closed in Wave 14b** (matches upstream `default_loss_fn`) |
+| W14 Finding 1: PRIME-RL impl wrong | ✅ closed in Wave 14b |
+| W14 Finding 2: ADR-007 stale | ✅ closed in Wave 14b |
+| W14 Finding 3: ModalExecutor dead code | ✅ closed in Wave 14b |
+| W14 Finding 4: world_size=1 only | ✅ closed in Wave 14b (multi-process convergence test) |
+| W14 Finding 5: tests pin wrong impl as ground truth | ✅ closed in Wave 14b (parity test added) |
+| W14 NIT 6: test count drift | 🟡 carried |
+| W14 NIT 7: docstring claims ISR clipping | ✅ closed in Wave 14b (real ISR now implemented) |
+| **NEW (Wave 14b)**: PRIME-RL `LossOutputs` return shape | 🟡 deferred to Wave 15 |
+
+**Tests as of Wave 14b: 115 passing + 1 skip-marked (OPSD parity test, runs when upstream cloned).** (Wave 12: 72; Wave 13: 93; Wave 14: 124; Wave 14b: 130; Wave 15: 115 after TAID rewrite consolidation + OPSD parity.)

docs/research/_archive/WAVE_15_FINAL_REVIEW.md

@@ -0,0 +1,76 @@
+# Wave 15 Final Review — Multi-Angle Self-Critique + Fix Wave
+
+**Date:** 2026-05-26
+**Method:** 4 parallel adversarial reviewers (math / tests / docs / user-journey), each given a different framing to maximize independent-angle coverage. Then targeted fix scatter on findings.
+
+## Headline finding
+
+**The math reviewer found 2 BLOCKERs that all 8+ prior subagents missed.** Both came from `git clone`-ing upstream and doing line-by-line diffs against the framework's `composer_replication/opsd.py` and `composer_replication/distillation/taid.py` — something no prior reviewer had done for those files (Wave 14b reviewer did it for PRIME-RL only).
+
+This validates the user's instinct that "every angle" multi-model orchestration is worth doing — the math angle, given a sharp prompt that mandated upstream verification, found genuine bugs in the framework's primary loss kernel.
+
+## Wave 15a reviews (all 4 deliverables)
+
+| Reviewer | Focus | BLOCKERs | Severity-weighted findings |
+|---|---|---|---|
+| Math correctness (Opus 4.7) | 7 claimed implementations vs primary sources | **2 BLOCKER + 3 minor** | `generalized_jsd_loss` math wrong; `taid_loss` algorithm wrong |
+| Test honesty (Opus 4.7) | 3 specific test files | 0 BLOCKER + 3 weak-assertions | PRIME-RL parity skip silently never runs; bit-exact uses `allclose` not `equal`; entropy-OPD test is pure smoke |
+| Documentation drift (Opus 4.7) | 6 major docs + ADRs | 0 BLOCKER + 7 drifts | test count drift (77/107/124 vs actual 145); `compose_loss` kwarg drift; PRIME-RL test count 10 vs 16; stale "Deferred to Wave 14" claim |
+| User journey (Opus 4.7) | RL-finetune Qwen-7B on GSM8K | 0 BLOCKER + 10 friction items | **No GSM8K example** (#1 ask); no runnable `ComposerReplicationTrainer` recipe; data-collator gap undocumented; defaults activate channels users haven't configured |
+
+Reports saved at `/tmp/wave15_{math,test,doc,user}_review.md`.
+
+## Wave 15b — fix scatter outcomes
+
+5 parallel fix subagents dispatched. Outcomes:
+
+| Task | Subagent outcome |
+|---|---|
+| (1) OPSD math rewrite vs upstream | ✅ Completed. New parity test (skip-marked) verifies 31 cases against upstream `siyan-zhao/OPSD`. Mixture distribution now β-weighted (was hardcoded 0.5); β coefficient on correct terms (was swapped); reduction matches upstream (was off by 100-2000× factor). Docstring labels fixed (β=0 = reverse KL, β=1 = forward KL). |
+| (2) TAID rewrite vs upstream | ⚠️ Subagent timed out at 600s but **work landed**: logit-space mix (was prob-space), current-student-detached anchor (was frozen step-0), forward-KL criterion (was JSD), optional `TAIDScheduler` for adaptive scheme. Docstring rewritten to acknowledge the breaking change. Tests updated. Parity test added. |
+| (3) GSM8K example | ⚠️ Subagent timed out but **work landed**: `examples/gsm8k_grpo/run.py` runs end-to-end on CPU with Qwen2.5-0.5B-Instruct, 100 GSM8K rows, regex-based verifiable reward, 2 outer steps in 58s. README written by parent agent. The `run_with_sdpo.py` variant deferred to Wave 16. |
+| (4) Doc drift + install ergonomics | ⚠️ Subagent timed out. **Parent completed:** flipped `alpha_sdpo` and `beta_replay` defaults to 0.0; added clear ImportError if TRL missing; fixed TROUBLESHOOTING `[replay]` extras claim; updated README + USER_GUIDE + INTEGRATION_RECIPES test counts to reference V1_V8_COVERAGE; closed stale "Deferred to Wave 14" claim. |
+| (5) Test hardening + LossOutputs wrap | ✅ Completed (3 of 4 sub-tasks). PRIME-RL `loss_fn` now returns `LossOutputs(loss, metrics)`. Bit-exact test tightened to `torch.equal`. PRIME-RL parity test now emits visible warning when prime-rl unavailable. Gradient-flow tests deferred to Wave 16. |
+
+## Final test count post-Wave-15: 115 passing + 1 skip-marked
+
+- Wave-by-wave: 72 (W12) → 93 (W13) → 124 (W14) → 130 (W14b) → **115** (W15)
+- Net decrease from 130: TAID rewrite consolidated 16 schedule-specific tests into 7 `t`-parameterized tests (smaller surface but stronger contracts: each test now exercises the actual paper algorithm). Plus 1 skip-marked OPSD parity test.
+- Trade-off: fewer tests, but 2 BLOCKER-class math bugs eliminated. Net correctness improvement is large.
+
+## What this round caught vs missed
+
+### Caught (improvements over Wave 14b state)
+- 2 math BLOCKERs in primary loss kernels, fixed against upstream byte-for-byte
+- TAID rewrite from misnamed prob-space-JSD-with-frozen-anchor to actual SakanaAI/TAID
+- PRIME-RL `LossOutputs` adapter wrap — recipe is now actually invokable from PRIME-RL
+- GSM8K real-task example — closes the user-reviewer's #1 friction
+- Default kwargs (`alpha_sdpo=0.1` → `0.0`) — no more silent activation of unconfigured channels
+- TRL ImportError clarity — no more cryptic `object.__init__()` errors
+- Test count drift — single canonical doc (V1_V8_COVERAGE)
+- TROUBLESHOOTING `[replay]` extras correctly described
+
+### Missed (Wave 16 candidates)
+- `run_with_sdpo.py` — promised but not shipped this wave
+- 3 gradient-flow tests for compose_loss channels (test reviewer's #4)
+- Multi-process MockManager + DiLoCo convergence test was added in Wave 14b but only at world_size=2; user reviewer didn't probe larger
+- Recon docs (`docs/research/*RECONNAISSANCE.md`) not cross-checked against current code state — likely some staleness
+- PRIME-RL recipe still hasn't been run end-to-end against actual prime-rl (parity test skip-marks; LossOutputs wrap added but not exercised)
+
+## Methodological lessons for future waves
+
+1. **Prompt subagents to clone upstream and diff** when the task is "verify against external truth." 8+ prior reviewers checked papers but did not `git clone`. The instruction "read /tmp/X-clone/file.py and find every divergence" produced the BLOCKER-class findings.
+
+2. **600s subagent timeout is the dominant constraint at this scope.** 3 of 5 fix subagents timed out despite making real progress. Workaround: write the report file FIRST as a skeleton, iterate in place. (Subagents that did this completed; subagents that read everything then tried to write at the end timed out.)
+
+3. **Cross-cutting parallel-subagent failure mode**: subagents cite each other instead of upstream. Wave 14 caught this for PRIME-RL math. Wave 15 caught it for OPSD + TAID math. The mitigation is mandate-upstream-verification in the prompt.
+
+4. **Prompt injection in tool outputs**: one subagent flagged that fake "don't reproduce copyrighted material" instructions appeared in its tool outputs throughout, designed to make it abandon the OPSD math fix. The subagent correctly ignored the injection and completed the task. The framework's MIT-licensed work with attribution is fully authorized; no copyright concern.
+
+## Open items for Wave 16
+
+1. `examples/gsm8k_grpo_with_sdpo/` — demonstrate SDPO column wiring end-to-end
+2. Gradient-flow tests for compose_loss channels (pre-staged in test reviewer's report)
+3. Recon-doc currency sweep: cross-check `docs/research/*RECONNAISSANCE.md` against current code state
+4. Real PRIME-RL end-to-end run with the new `LossOutputs` wrap (verify the wrap shape works in the real `setup_loss_fns` pipeline)
+5. `INTEGRATION_RECIPES.md` `compose_loss` signature display — collapse to `...` and link to `API_REFERENCE.md`, OR sync to all 17 kwargs

docs/research/_archive/WAVE_7_10_FINAL_REVIEW.md

@@ -0,0 +1,423 @@
+# Wave 7–10 Final Review — Cross-model adversarial check
+
+**Reviewer**: external model, Phase 11 of the deep work loop.
+**Date**: 2026-05-26.
+**Mandate**: find substantive flaws. The research thesis is
+primary-source-validated; this attacks *implementation correctness* and
+*scope creep*, not the thesis.
+
+---
+
+## (a) Are the tests real evidence or theater?
+
+### Spike 006 (Qwen2.5-0.5B-Instruct CPU smoke, 9 tests)
+
+**Verdict: mostly tautology, with usable ablation tests.**
+
+The headline "loss 0.7390 → 0.0031, 99.6% reduction in 5 steps" is
+technically true and substantively near-tautological:
+
+1. **The same fixed ~50-token batch is reused for all 5 steps.**
+   `build_batch` returns one conversation; the test loop calls
+   `compose_loss(model, batch)` five times in a row. No reshuffle, no
+   second batch, no held-out anything.
+2. **0.5B params × AdamW(lr=1e-5) × identical 50-token batch ×
+   5 steps = textbook memorization regime.** A randomly-initialized MLP
+   would also reduce loss in this setup. The test does not distinguish
+   "the 3-channel composition is correct" from "AdamW reduces fixed-batch
+   loss on any non-degenerate objective."
+3. **The SDPO channel is zero throughout** (`sdpo_jsd=0.0` on every
+   row of `loss_curve.csv`). The verdict calls this "correct fallback
+   behavior"; what it actually is is *the entire SDPO channel never
+   being tested by this smoke*. The fallback is a literal `_zero(device)`.
+   `generalized_jsd_loss` has no end-to-end test on a real HF model
+   anywhere in the codebase. **This is the largest evidence gap for
+   V8.**
+4. **DPO uses dummy hard-coded reference logprobs** (`-30.0`, `-35.0`).
+   This tests that `-logsigmoid(small_positive)` is differentiable, not
+   that the trace-replay-DPO pipeline (reference-policy precompute +
+   collator + loss) wires together.
+5. The "loss decreases" assertion is `losses[-1] < losses[0]` — the
+   weakest version of monotonicity.
+
+**Genuine value**: model-loads test, chat-template test, the three
+α=0 / β=0 ablation tests. The ablations would catch a regression where
+weights stop disabling channels. The "5-step decrease" is the weakest
+test in the file.
+
+**Run.log inconsistency, not flagged anywhere**:
+`examples/qwen_05b_quickstart/run.log` shows step-1 total = 0.0379;
+the spike `verdict.md` quotes step-1 total = 0.2090 for the same code,
+same model. Either the seed isn't pinned through the model forward
+(likely — `torch.manual_seed(42)` is in `build_batch` only), or the
+package's `compose_loss` differs subtly from the spike's. **Quoting
+exact numbers from a non-reproducible run as evidence is the sloppy
+version of every research-replication scandal.**
+
+### Spike 007 (Claude Code ingester, 15 tests)
+
+**Verdict: strongest test suite of the three. Caveats apply.**
+
+Real engineering value:
+- Synthetic fixture exercises the actual record types (assistant,
+  user/tool_result, summary, system, sidechain). Tests assert structural
+  properties: history grows monotonically, `[THINKING]` stripped on
+  replay but kept in student_action, unique state_ids, tool_use
+  serialization, tool_result tagging.
+- `test_truncated_line_tolerated` would catch a real failure-mode
+  removal of the JSON-decode try/except.
+- Subagent and sidechain skip tests catch real production cases.
+
+Caveats:
+- **The "real session" test is hardcoded to one path on the author's
+  machine** (`/home/codeseys/.claude/projects/…/e4a34e2b-….jsonl`).
+  No env var, no fixture-discovery; the test is `skipif(not exists)`.
+  This is a manual integration test, not a CI test. ADR-002 said "CI
+  users substitute their own"; the substitution mechanism doesn't
+  exist.
+- The synthetic fixture is **author-written** and presumably designed
+  alongside the ingester. There is no scrubbed third-party fixture.
+- Acceptance criterion #3 in BACKLOG ("end-to-end smoke: real trace →
+  ingester → collator → 1-step `composer_total_loss`") is **unmet** —
+  the spike stops at "ingester emits TraceStates correctly." There is
+  no test that takes ingested records, runs the data collator, and runs
+  through `compose_loss`.
+
+This suite would catch real regressions in the ingester. Its weakest
+property: ships no contributor-runnable real-trace test.
+
+### Spike 008 (DiLoCo, 5 tests, single-process)
+
+**Verdict: the caveat is honest but says the test does not test what
+users will assume it tests.**
+
+BACKLOG acceptance criterion: *"Smoke test: 2 replicas × 4 inner steps
+× 2 outer rounds on the toy model from Spike 005, both replicas converge
+toward the same solution within tolerance."*
+
+What ships: **one** replica, mock manager whose `allreduce` is a
+**`passthrough` no-op** (test_diloco_smoke.py:78). This is "one
+replica's outer optimizer machinery fires," not "two replicas
+converge." The acceptance criterion was silently re-defined; the
+spike's verdict.md calls this a "limitation" but it is a redefinition.
+
+The recon doc (per ADR-003) claimed a "ready-to-paste" pattern with real
+shared-buffer averaging. The implementation hits a "post-hook
+sequencing bug." **One of the recon claim and the implementation is
+wrong**, and the gap is buried in verdict.md instead of fixed.
+
+**Genuine value**: `test_diloco_pseudogradient_sign_convention` is the
+**single best test in all of Wave 7-10**. It pins the sign convention
+with a concrete arithmetic prediction (`final == θ_initial + nudge`)
+and reports `wrong_sign_diff` on failure. A future torchft upgrade that
+flips the sign breaks this test loudly. ADR-003 specifically flagged
+this hazard, and the test catches it. Credit where due.
+
+**Separate flaw in `composer_diloco.py` docstring (lines 13–28)**: the
+"wrong-sign pseudogradient combined with SGD's subtract-grad semantics
+gives net step in the local-Δ direction once momentum builds up" gloss
+is incoherent. There is no "wrong-sign" pseudogradient.
+`θ_initial − θ_local` is the exact DiLoCo paper convention; SGD's
+`p ← p − lr·g` semantics are designed for it. The test is correct; the
+prose explaining why is wrong, and will mislead anyone porting the
+convention.
+
+---
+
+## (b) Is the package a real framework or a shim?
+
+**Verdict: a structured shim around three real components and two
+stubs. Not yet a framework.**
+
+What `pip install composer-replication` delivers:
+- `compose_loss` — labeled in its own top docstring as "Do NOT use as
+  the production training loss." Re-exported as the headline package
+  API and used in the quickstart.
+- `build_batch` — a hard-coded fixed-conversation factory built for the
+  smoke (factorial / binary-search examples). Anyone using this in
+  real training is using example code as production.
+- `ClaudeCodeIngester` — real, working component. Solid.
+- `generalized_jsd_loss` — real, working (extracted from OPSD, MIT).
+- `extract_dpo_pairs`, `replay_trace`, teacher specs — real, but
+  require OpenRouter credentials + spend.
+- `ComposerReplicationTrainer` — TRL `GRPOTrainer` subclass.
+  Useful only with `[train]` extra. Not exercised end-to-end on any
+  real model in this repo.
+- `make_diloco_outer_loop` — wrapper. Useful only with `[diloco]` extra.
+
+What is missing for "pip install and start training":
+1. No GPU end-to-end example. The brief targets Qwen3-7B / Qwen3-32B.
+2. No CLI. `pyproject.toml` declares no `[project.scripts]`.
+3. No config schema (Hydra/Pydantic). Users hand-construct teacher
+   specs, hint generators, data collators.
+4. The `[train]` extra pulls TRL but **no integration test** of
+   `ComposerReplicationTrainer` against a real GRPO rollout exists in
+   this repo. Spike 005 used TinyLM; Spike 006 stubbed GRPO out
+   precisely to avoid TRL.
+5. **`build_batch` should not be public API.** It belongs in
+   `examples/`. Re-exporting at top level implies it is a general-purpose
+   utility.
+6. **Two sources of truth**: `composer_replication/loss.py` is a
+   near-copy of `spikes/006-…/compose_loss.py` with one import path
+   changed. The spike tests still import from the spike file. A bug fix
+   in one will not propagate. Same for `composer_diloco.py` ↔
+   `composer_replication/diloco/__init__.py`.
+
+Real framework value:
+- `ClaudeCodeIngester` with non-trivial logic.
+- `generalized_jsd_loss` with token-clip + temperature.
+- DiLoCo wrapper with sign-pinning test.
+- Sane package layout with optional extras for heavy deps.
+
+Net: **a successful directory restructure plus an installable wrapper
+around three real components and two stubs.** Calling Wave 10 "framework
+is installable with working entrypoints (✅)" is letter-of-the-law;
+the brief's "framework" connotation isn't yet earned.
+
+---
+
+## (c) ADR defensibility
+
+### ADR-001 (local 5090 over Modal)
+
+**Reasoning defensible; execution missing.** The
+"iteration cycle 25–40s vs 3–5min" argument is concrete and matches
+reality. The "verification smoke, not production" framing is correct.
+
+**Gap**: Spike 002a-mini was never run on the 5090 either. Phase 10 in
+DEEP_WORK_LOOP_LOG.md is ⏳ pending. ADR-001 chose the 5090 over Modal,
+and **then nothing ran on either.** No `nvidia-smi` snapshot, no GPU
+step-time CSV, no bf16 numerics check. The "rule out CPU-only blind
+spots" goal is unmet. The ADR should be marked "Accepted (execution
+deferred)" or the spike should run.
+
+### ADR-002 (Claude Code JSONL trace source)
+
+**Defensible on every dimension the ADR considers; the dimensions are
+partial.** "1,015 real sessions, zero acquisition cost" is real. License
+and schema-stability arguments are well-sourced.
+
+**Adversarial counter not in the ADR**: Claude Code JSONL is the most
+self-serving choice. The framework targets training a coding-agent model.
+The training data is the author's own Claude Code sessions where the
+agent was Claude. The teacher pool (Spike 001) is OpenRouter-based and
+*includes Claude*. So:
+- "student action" = what Claude did.
+- teacher pool includes Claude.
+- DPO pairs = teachers' agreement vs Claude's literal text.
+
+This is **circular imitation**: training a future model to imitate
+Claude using Claude's outputs as the gold reference and Claude as one
+of the disagreement teachers. The teacher-disagreement signal density
+argument from Spike 001 is strongest with diverse teachers. With this
+trace source, the student-action is locked to one teacher family,
+biasing the disagreement signal. The ADR doesn't consider this; the
+ingester README doesn't flag it. **The ADR rationalizes the easy path
+without naming the data-leakage tradeoff.**
+
+### ADR-003 (torchft for DiLoCo)
+
+**Genuinely defensible choice.** Meta-maintained library; rolling-own
+trap correctly identified; license analysis (rejecting `diloco_simple`)
+is right; sign-convention risk named and tested.
+
+**Gap is in delivery, not decision.** ADR-003 §Consequences §1 says:
+"2 replicas, 4 inner steps, 2 outer rounds on a TinyMLP, shared-buffer
+mock allreduce, assertions: replica equality after sync, params actually
+moved, Nesterov state populated, sync count matches expected." Spike 008
+implements one replica + passthrough manager. The ADR commits to an
+implementation that the spike does not deliver, and the gap is flagged
+only in the spike's verdict, not in the ADR.
+
+If the recon doc said the pattern was "ready-to-paste" but actually
+hits a sequencing bug, **the recon doc is wrong** and an adversarial
+reviewer is allowed to point that out.
+
+---
+
+## (d) Scorecard inflation
+
+The 5/10 → 9/10 update overstates. Test by test:
+
+- **Test 6 (DiLoCo integrated in runnable stack) → ✅?**
+  Letter-of-law yes, spirit no. `make_diloco_outer_loop` exists and
+  fires on one replica. **Zero references to torchft or DiLoCo in
+  `composer_trainer.py`** — DiLoCo is not integrated with the trainer.
+  No two-replica integration test, no real distributed run.
+
+- **Test 7 (real HF model loads + runs) → ✅?**
+  Yes — most legitimately closed item. Caveats from §(a) about depth
+  of evidence apply, but the literal test is met.
+
+- **Test 8 (real LLM-application trace ingested end-to-end) → ✅?**
+  Mostly yes. Ingester real and tested. **BACKLOG acceptance criterion
+  #3 ("end-to-end: real trace → ingester → collator → 1-step
+  `composer_total_loss`") is unmet.**
+
+- **Test 9 (framework installable with working entrypoints) → ✅?**
+  Letter-of-law yes, spirit partial. `pip install -e .` works; the
+  quickstart runs the smoke harness. Production entrypoint
+  (`ComposerReplicationTrainer` driven by a config) does not exist.
+
+- **Test 10 (non-author can complete the journey) → ✅?**
+  No. The supporting evidence is "Quickstart README + working
+  installable demonstrate the full path on Qwen2.5-0.5B in <5min, $0."
+  Test 10's original journey was "I have Qwen3-7B, I want a
+  Composer-style variant." The parenthetical concession in the update
+  ("For Qwen3-7B etc., GPU phase still gates the empirical demo")
+  ✅'s the item anyway.
+
+**Honest re-scoring**: 5/10 → **7/10 ✅, 1/10 ⚠️ partial (test 8),
+2/10 ❌ in spirit (tests 6, 10).** "9/10" overstates by ~2 points.
+
+---
+
+## (e) Commit quality
+
+```
+ac05fbf Wave 10 — packaging: composer_replication is now pip-installable
+d52e126 Tidy .gitignore (de-dup *.jsonl, restore section blank lines)
+a35a8d7 Spike 007: include synthetic_session.jsonl fixture in repo
+57af35d Wave 7+8+9: spikes 006/007/008 — close vision-validation gaps V2/V5/V8
+ac4bfb4 Wave 7: Phase 2-4 of deep work loop — backlog, parallel research, three ADRs
+040eff8 Wave 6: vision validation self-audit (5/10 to 9/10 in 5 days, no GPU)
+```
+
+- `ac05fbf`, `d52e126`: accurate.
+- `a35a8d7`: accurate. Implies `57af35d` shipped a Spike 007 that did
+  not actually run cleanly for anyone cloning before this commit. Mild
+  overclaim risk on `57af35d`.
+- **`57af35d` is the single most overclaiming commit.** Title: "close
+  vision-validation gaps V2/V5/V8."
+  - V8: closed in the weakest sense (tautology critique above).
+  - V5: structural ingestion closes; BACKLOG acceptance #3 unmet.
+  - V2: silently re-defined (one replica, no convergence).
+  Three closures claimed; one partial, one redefined.
+- **Chronology problem**: `040eff8` (Wave 6) declared the **5/10 → 9/10
+  forecast** in the commit subject. `ac4bfb4` (Wave 7, *next* commit)
+  added the BACKLOG and ADRs — i.e., the *plan* to make the forecast
+  true. `57af35d` (Wave 7-9) executed and ratified the 9/10 without
+  re-auditing whether each item was actually closed in spirit. **No
+  commit re-audits the scorecard against actually delivered evidence.**
+
+---
+
+## (f) Adversarial reviewer's strongest line of attack
+
+> "You have a research replication framework whose only published smoke
+> is a 5-step fixed-batch overfit on a 0.5B model on CPU, where the SDPO
+> channel is silently disabled (sdpo_jsd=0 throughout), the DPO channel
+> uses dummy reference logprobs, and the GRPO channel is replaced with
+> a stub. Of the three channels you advertise, **zero are tested
+> end-to-end on a real HF model.** Your DiLoCo integration is one
+> replica with a no-op `allreduce`. Your real-trace ingester is tested
+> against a fixture you wrote yourself plus a hardcoded path on your
+> laptop. Your scorecard moved from 5/10 to 9/10 with no GPU spend, no
+> third-party validation, and one commit that closed three vision-
+> validation gaps with one commit message. You are asking the reader to
+> believe that a $9B-startup commercial product is replicated by a CPU
+> smoke and three green test files — none of which the company itself
+> would call 'replicated.'"
+
+**Weakest defense**: "It's just v0.1 / smoke phase / GPU is the next
+phase." The *commit log and scorecard claim otherwise.* The defense
+"v0.1 caveat" only works if the v0.1 framing is honest at the top of
+the README and scorecard — and it is not.
+
+**Strongest actual defense**: the four primary-source-validated recon
+docs and Spike 001's measured cost floor. The *thesis* is credible and
+auditable. The *implementation phase* is overclaimed.
+
+---
+
+## What to fix before publishing publicly (priority order)
+
+### 1. Re-state the scorecard honestly (BLOCKER)
+Replace 5/10 → 9/10 with **5/10 → 7/10 ✅, 1/10 ⚠️, 2/10 ❌-spirit.**
+List the spirit-failures explicitly (test 6 trainer integration, test 8
+end-to-end, test 10 non-author). Single most important fix; everything
+else compounds on the inflated scorecard.
+
+### 2. Fix Spike 008's V2 claim (BLOCKER)
+Either (a) add a real two-replica multiprocessing test (ADR-003 says
+this is feasible; the spike claims it isn't — reconcile), or (b) mark
+V2 as ⚠️ partial and rewrite BACKLOG: "machinery fires on one replica,
+sign convention pinned; cross-replica convergence deferred to GPU
+phase." Pick one.
+
+### 3. Strengthen Spike 006 against the tautology critique
+Two cheap wins:
+- Test that loss decreases on **two alternating fixed batches** over 10
+  rounds (not just one memorized batch).
+- Test where **`alpha_sdpo=10.0` and SDPO actually fires** (truncate
+  ctx_teacher to T_s tokens for matching shape). The SDPO channel is
+  *not exercised on a real HF model anywhere* in the codebase. Largest
+  evidence gap for V8.
+
+### 4. Run Spike 002a-mini on the local 5090
+ADR-001 made the choice; the spike was not run. Either drop the ADR
+(decision deferred) or run the spike (~30 min wall-clock per ADR's own
+estimate). Until then, the framework has zero GPU evidence of any kind.
+
+### 5. Fix the run.log / verdict.md numerical inconsistency
+Quickstart run.log shows step-1=0.0379; spike verdict shows step-1=0.2090.
+Either pin the seed properly or document non-reproducibility and quote
+a band rather than exact numbers.
+
+### 6. Acknowledge Claude Code JSONL's circularity in ADR-002
+Add a "Risks accepted" entry naming the data-leakage concern: training
+on Claude's outputs while Claude is in the teacher pool produces a
+biased disagreement signal. Spike 007 README should also flag it.
+
+### 7. Decide what `compose_loss` and `build_batch` are
+Either rename to `compose_loss_smoke` (and keep
+`ComposerReplicationTrainer._compute_loss` as production), or make
+`compose_loss` actually production-grade and demote `build_batch` out
+of public API. Production-disclaimed harness as the package's headline
+import is confusing.
+
+### 8. Eliminate dual sources of truth
+`spikes/006-…/compose_loss.py` ↔ `composer_replication/loss.py`, and
+`spikes/008-…/composer_diloco.py` ↔ `composer_replication/diloco/__init__.py`.
+Make the spike import from the package; delete the duplicate.
+
+### 9. Add the missing real-trace end-to-end test in Spike 007
+Take ingester output → Spike 005 data collator → 1 step of `compose_loss`.
+This is BACKLOG acceptance #3; ~50 lines of test code closes V5's
+spirit gap.
+
+### 10. Fix the sign-convention docstring in `composer_diloco.py`
+Replace the incoherent "wrong-sign + SGD subtract = right answer with
+momentum" gloss with: *"DiLoCo defines pseudo-gradient as
+`θ_initial − θ_local`; this is the negative of the local update
+direction, and standard SGD subtracts gradients, so the outer step
+moves in the local-update direction. No negation required."* The test
+is correct; the prose explaining it isn't.
+
+---
+
+## Credit where due
+
+- **Spike 007's `ClaudeCodeIngester`** is real, working, well-tested
+  software with non-trivial logic (sidechain skip, thinking-block
+  strip-on-replay, malformed-line tolerance). The synthetic fixture
+  exercises the structural cases properly.
+- **Spike 008's pseudogradient-sign-convention test** is the single
+  best test in all of Wave 7-10. It pins a known torchft hazard with an
+  explicit arithmetic prediction and a `wrong_sign_diff` reported on
+  failure.
+- **Spike 006's α=0 / β=0 ablation tests** would catch real regressions
+  and document channel-disable semantics.
+- **All three ADRs are properly traceable to recon documents**
+  (MODAL_RECONNAISSANCE, TRACE_SOURCE_RECONNAISSANCE,
+  DILOCO_RECONNAISSANCE). The decisions can be challenged; the *process*
+  is auditable, which is rare.
+- **Package layout** (`loss`, `batch`, `opsd`, `teacher_replay`,
+  `ingestion/claude_code`, `diloco`, `trainer`) is sane; optional
+  extras correctly avoid forcing TRL/torchft on every install.
+
+The work product is not zero. It is overclaimed by roughly one
+scorecard tier and one BACKLOG acceptance criterion. Fixing items
+1, 2, 3, 5 above moves the framework from "publishable with a generous
+reviewer" to "publishable with a critical reviewer." Items 4 and 6
+move it from "research replication" to "evidenced research replication."

docs/reviews/cross-family-adr-008-009-010-2026-05-29/SYNTHESIS.md

@@ -1,90 +1,9 @@
 # Cross-family adversarial review — ADR-008 / 009 / 010 (2026-05-29)
 
-> The "owed" cross-family adversarial ADR review from the Composer 2.5
-> data-gen + targeted-RL wave. Deferred during the wave because OpenRouter ran
-> out of credits mid-run (blocking `delegate_task`); run here once credits were
-> restored (~$50 free at review time). This is the proper GPT-5.5 / Gemini /
-> DeepSeek / Kimi / Grok scatter the wave summary promised.
-
-## Method
-
-Route-fidelity-safe urllib scatter (no `delegate_task` per-task-override risk)
-to 5 diverse families, full corpus embedded inline: the 3 ADRs **plus their
-implementation code plus the tests** (~100KB / ~25K tokens), so reviewers
-critiqued the *implementation against the decision*, not just the prose.
-
-| Family | Slug (served) | Result |
-|---|---|---|
-| OpenAI | gpt-5.5-20260423 | clean, very specific (7981 tok) |
-| Google | gemini-3.1-pro-preview-20260219 | clean, sharpest (9174 tok @ retry 16K) |
-| DeepSeek | deepseek-v4-pro-20260423 | clean, math/correctness lens (10308 tok @ retry 16K) |
-| xAI | grok-4.3-20260430 | clean, terse/decisive (1645 tok) |
-| Moonshot | kimi-k2.6-20260420 | starved token budget (63K reasoning, content=None) — excluded |
-
-4 of 5 clean reviews. Raw reviews: `review_*.md` in this directory.
-
-## Verdict matrix
-
-| ADR | GPT-5.5 | Gemini | DeepSeek | Grok | Consensus |
-|---|---|---|---|---|---|
-| 008 (Dr.GRPO+SDPO) | REJECT | REJECT | ACCEPT-w-FIXES | REJECT | **3 REJECT / 1 fix** |
-| 009 (layered hints) | ACCEPT-w-FIXES | ACCEPT-w-FIXES | ACCEPT-w-FIXES | ACCEPT | **unanimous: fixable** |
-| 010 (FeatureDeletion datagen) | REJECT | REJECT | REJECT | ACCEPT-w-FIXES | **3 REJECT / 1 fix** |
-
-The REJECTs were not "the design is wrong" — every reviewer agreed the
-architecture is sound. They were "the **accepted** status outruns the
-**evidence**": gates marked `[x]` were satisfied by shape-checks and FakeSandbox
-tautologies, not by the hard guarantee the gate language implied.
-
-## Convergent findings (≥2 reviewers, ALL verified against code by the orchestrator)
-
-| # | Finding | Reviewers | Status |
-|---|---|---|---|
-| 1 | SDPO alignment guard = shape-check only; hint-shifted tokens silently misalign → policy poisoning | 4/4 | **FIXED** (explicit alignment-index gather + strict-raise; tests rewritten) |
-| 2 | Sandbox denylist trivially bypassable (`python -c`, abs paths, `sh -c`) + ADR-claimed scrub UNIMPLEMENTED | 4/4 | **FIXED** (`_scrub_tree` primary control implemented + tested) |
-| 3 | Curriculum `int(reward>0)` logs 0.5 partial as full pass → premature retire | 3/4 | **FIXED** (fractional credit + tests) |
-| 4 | `scale_rewards` assertion dup literal `("none","False","False")` | 4/4 | **FIXED** (case-insensitive) |
-| 5 | CPU smoke is tautological — never enters `_compute_sdpo_loss` (early return) | 3/4 | **RE-SCOPED** (gate honestly reworded) |
-| 6 | FakeSandbox validator tests prove plumbing, not real inversion | 3/4 | **RE-SCOPED** (= the `[~]` Docker gate) |
-| 7 | HackMonitor is substring matcher, not AST-provenance as advertised | 2/4 | **RE-SCOPED + OPEN** (follow-up) |
-| 8 | Validator gate-2/"deletion reachable" doesn't test reachability | 2/4 | **OPEN** (needs Docker materializers) |
-| 9 | `shell=True` + node-id interpolation = injection + param-test breakage | 2/4 | **FIXED** (`shlex.quote`) |
-| 10 | LLM-judge cache key non-deterministic (memory addr) + unbounded output | 2/4 | **FIXED** (addr-strip + version + clamp + atomic write) |
-| 11 | KL estimator k1 never configured/asserted | 2/4 | **OPEN** (fidelity follow-up) |
-| 12 | `reward_fn` zip truncates on length mismatch | 1 (GPT) | **FIXED** (length-guard) |
-
-## What was fixed in this pass (all tested, 192 pass / 16 skip, 0 fail)
-
-- **SDPO alignment** (`composer_trainer.py`): require `student_response_idx` /
-  `teacher_response_idx` from the collator; gather aligned post-hint logits
-  before JSD; strict-mode raises on missing/mismatched indices. The
-  silent-misalignment P0 (the only finding that would actually corrupt a run) is
-  closed and tested across different-length sequences.
-- **Sandbox scrub** (`sandbox.py`): `boot()` physically removes byte-code/type
-  caches + `.git`/`.hg` — the ADR-claimed PRIMARY reward-hack control, previously
-  absent. Denylist re-documented as defense-in-depth + `shlex.quote` on node ids.
-- **Curriculum** (`curriculum.py` + `env.py`): fractional pass credit; hacked /
-  guard-broken rollouts contribute 0 credit but count as exposures.
-- **reward_fn** (`env.py`): length-guard against silent truncation.
-- **LLM judge** (`hint_generator.py`): address-stripped + versioned cache key,
-  600-char output clamp, atomic disk write.
-- **`make_dr_grpo_config`** (`composer_trainer.py`): fixed the duplicated
-  assertion literal.
-
-## What remains OPEN (honest follow-ups, none corrupt a run)
-
-1. **Live Docker substrate-inversion e2e** — the central `[~]` gate. Closes
-   findings #6, #8 (real reachability/provenance on a materialized repo) and the
-   "FakeSandbox is tautological" objection. **Blocked: no Docker in this env.**
-2. **k1 KL estimator** assert/config vs TRL 1.5.0's actual GRPO KL branch (#11).
-3. **HackMonitor → real AST provenance** check (#7).
-4. **Hint-generator default layer routing** so style/communication sites reach
-   the judge (ADR-009 P1).
-5. **Curriculum turn/think-token signals** for full Composer recipe fidelity.
-
-All five are documented in the ADRs' "Post-acceptance cross-family review"
-sections.
-
-## Cost
-
-~$2-4 OpenRouter (2 scatters: 5×8K + 3×16K tokens on a 25K-token corpus).
+> **📦 Archived (2026-06-08).** This cross-family review (SYNTHESIS + the four
+> per-model reviews) has been moved to
+> [`docs/_archive/reviews/cross-family-adr-008-009-010-2026-05-29/`](../../_archive/reviews/cross-family-adr-008-009-010-2026-05-29/).
+> It is preserved verbatim for provenance — ADR-008 and ADR-012 cite this review
+> directory — but is superseded as a status source by the accepted ADRs and the
+> current [`BACKLOG.md`](../../../BACKLOG.md). See
+> [`docs/_archive/README.md`](../../_archive/README.md) for the archive index.

docs/reviews/final-verify-deep-work-2026-05-29/SYNTHESIS.md

@@ -1,33 +1,8 @@
 # Phase-8 final cross-family verify — deep-work-loop 2026-05-29
 
-The deep-work-loop exit gate (Hard Rule 6: two independent confirmations). After
-Waves A+B shipped (ADR-011/012/013, 227 tests), the net session code diff
-(~92KB) was scattered to 3 diverse families for a final "would this break a real
-run" pass. 2 of 3 returned clean (GPT-5.5, Gemini; DeepSeek starved its reasoning
-budget). The verify EARNED ITS KEEP — it found a latent P0 + a convergent bug +
-a self-bug in this session's own new code.
-
-## Findings (all verified against code, all FIXED)
-
-| # | Finding | Severity | Reviewers | Fix |
-|---|---|---|---|---|
-| 1 | SDPO sentinel-mask used only `student_response_valid`, ignored `teacher_response_valid` — a future divergent teacher tail would distill against clamped position 0 | P0 (latent) | GPT-5.5 | `aligned_mask = (s_idx>=0)&(t_idx>=0)&student_valid&teacher_valid` |
-| 2 | Curriculum `_TaskStats` shared one `n_effort` denominator for both turns + think_tokens → corrupts a mean when only one signal is present | P1 (convergent) | GPT-5.5 + Gemini | separate `n_turns`/`n_think` counters |
-| 3 | Docker E2E test ran `pip install pytest` under `--network none` → would fail exactly when the gate activates | P1 | GPT-5.5 | dropped pytest; stdlib `python -c` expression runner, no network needed |
-| 4 | MMLU reward: `Answer: A or B` hedge parsed as `A` with `n_distinct=1` → full credit | P1 | GPT-5.5 | `_HEDGE_RE` adds the hedged second letter to the distinct set → multiple-answers penalty |
-| 5 | HackMonitor read-markers bare-substring matched `import` in `important`, `cat` in `concatenate`; and scanned the submitted patch as read-evidence → false positives | P1 | GPT-5.5 | whole-word `_READ_VERB_RE` + exclude `submit_patch`/`patch`/`diff` payloads from BOTH layers |
-
-Finding 5's fix surfaced a follow-on: layer-1's signature matcher ALSO scanned
-the patch payload (a legit patch mentioning `__pycache__` in a comment got
-flagged). The regression test caught it; fixed by excluding the patch payload
-from layer-1 too. Net: the monitor now only treats actual read ACTIONS as
-provenance evidence, never the agent's own output patch.
-
-## Outcome
-
-All 5 findings fixed + 5 regression tests added. Final suite: **232 passed / 18
-skipped, 0 failed**. Both the execution view (workers reported done) and the
-review view (final verify findings all closed) confirm the loop is empty — the
-two independent confirmations the deep-work-loop requires.
-
-Raw reviews: `verify_gpt-5.5.md`, `verify_gemini-3.1-pro.md`.
+> **📦 Archived (2026-06-08).** This Phase-8 final-verify review (SYNTHESIS + the
+> per-model verifies) has been moved to
+> [`docs/_archive/reviews/final-verify-deep-work-2026-05-29/`](../../_archive/reviews/final-verify-deep-work-2026-05-29/).
+> It is preserved verbatim for provenance but is superseded as a status source by
+> the accepted ADRs and the current [`BACKLOG.md`](../../../BACKLOG.md). See
+> [`docs/_archive/README.md`](../../_archive/README.md) for the archive index.

framework/composer-replication-framework.md

@@ -41,7 +41,7 @@ From `01-composer-2.5.md`:
 
 ## How the 5 component pieces fit together
 
-For the **rigorous integration architecture** — exact extension points in TRL (`GRPOTrainer._compute_loss` subclass), VeRL (`@register_adv_est` + `DataProto`), the OPSD loss `generalized_jsd_loss` lifted from `siyan-zhao/OPSD`, and the per-channel sequence diagrams — see [`docs/INTEGRATION_ARCHITECTURE.md`](docs/INTEGRATION_ARCHITECTURE.md). A working code skeleton with **38 passing unit tests** verifying the SDPO loss math, the trace-replay DPO-pair extraction, the data collator, and an end-to-end 5-step gradient run that decreases loss with all 3 channels active is at [`spikes/005-integrated-trainer-skeleton/`](spikes/005-integrated-trainer-skeleton/).
+For the **rigorous integration architecture** — exact extension points in TRL (`GRPOTrainer._compute_loss` subclass), VeRL (`@register_adv_est` + `DataProto`), the OPSD loss `generalized_jsd_loss` lifted from `siyan-zhao/OPSD`, and the per-channel sequence diagrams — see [`docs/INTEGRATION_ARCHITECTURE.md`](../docs/INTEGRATION_ARCHITECTURE.md). A working code skeleton with **38 passing unit tests** verifying the SDPO loss math, the trace-replay DPO-pair extraction, the data collator, and an end-to-end 5-step gradient run that decreases loss with all 3 channels active is at [`spikes/005-integrated-trainer-skeleton/`](../spikes/005-integrated-trainer-skeleton/).
 
 The high-level topology:
 
@@ -128,7 +128,7 @@ From `05-trace-replay-distillation.md`:
 - Composer's hint-loss = **same-model self-teacher with hint context** pulls student at error sites (~1 extra forward pass / cheap, no API)
 - Trace-replay-loss = **N external teachers** pull student at all sites (or high-uncertainty sites with VOI gating; ~$0.30/trace with gating per spike 001)
 
-These are **complementary**, not competing. Both give per-step KL signals that bypass the long-horizon credit assignment problem, but they tap different supervision sources. v0.1 of the framework runs both simultaneously. See [`docs/COMPOSER_RECIPE_MAPPING.md`](docs/COMPOSER_RECIPE_MAPPING.md) for the precise mathematical distinction and the implementation-handle table.
+These are **complementary**, not competing. Both give per-step KL signals that bypass the long-horizon credit assignment problem, but they tap different supervision sources. v0.1 of the framework runs both simultaneously. See [`docs/COMPOSER_RECIPE_MAPPING.md`](../docs/COMPOSER_RECIPE_MAPPING.md) for the precise mathematical distinction and the implementation-handle table.
 
 **Cost mitigation** (the report does this analysis well):
 - VOI gating (only query teachers when student entropy is high) → 60-80% savings

publications/HF_DISCUSSION_POST.md

@@ -12,15 +12,15 @@ I'm releasing this repo as a **pre-experimental methodology paper + integration
 
 ## What's in the box right now
 
-**1. Methodology paper.** [`publications/PAPER_v0.md`](publications/PAPER_v0.md) — longform writeup of the framework, audit of Cursor's blog vs secondary-source extrapolations, integration architecture across TRL/VeRL/OpenEnv, and a risk-ordered spike plan.
+**1. Methodology paper.** [`publications/PAPER_v0.md`](PAPER_v0.md) — longform writeup of the framework, audit of Cursor's blog vs secondary-source extrapolations, integration architecture across TRL/VeRL/OpenEnv, and a risk-ordered spike plan.
 
-**2. Composer 2.5 blog audit.** [`docs/COMPOSER_RECIPE_MAPPING.md`](docs/COMPOSER_RECIPE_MAPPING.md) — every claim tagged `[BLOG-VERIFIED]` / `[INFERRED]` / `[EXTRAPOLATED]`. Major finding: Cursor's "Targeted RL with Textual Feedback" is **mathematically the same as published SDPO** (Hübotter et al., ICLR 2026; [arXiv:2601.20802](https://arxiv.org/abs/2601.20802)) and OPSD (Zhao et al., [arXiv:2601.18734](https://arxiv.org/abs/2601.18734)), with **MIT-licensed reference code at [`siyan-zhao/OPSD`](https://github.com/siyan-zhao/OPSD)**. Cursor cites both papers in their blog's footnote 1. This was missed by the initial parallel-research dispatch I ran for this project — I only caught it when I read the blog directly.
+**2. Composer 2.5 blog audit.** [`docs/COMPOSER_RECIPE_MAPPING.md`](../docs/COMPOSER_RECIPE_MAPPING.md) — every claim tagged `[BLOG-VERIFIED]` / `[INFERRED]` / `[EXTRAPOLATED]`. Major finding: Cursor's "Targeted RL with Textual Feedback" is **mathematically the same as published SDPO** (Hübotter et al., ICLR 2026; [arXiv:2601.20802](https://arxiv.org/abs/2601.20802)) and OPSD (Zhao et al., [arXiv:2601.18734](https://arxiv.org/abs/2601.18734)), with **MIT-licensed reference code at [`siyan-zhao/OPSD`](https://github.com/siyan-zhao/OPSD)**. Cursor cites both papers in their blog's footnote 1. This was missed by the initial parallel-research dispatch I ran for this project — I only caught it when I read the blog directly.
 
-**3. Integration architecture doc.** [`docs/INTEGRATION_ARCHITECTURE.md`](docs/INTEGRATION_ARCHITECTURE.md) — verified extension points (via [DeepWiki](https://deepwiki.com/) audits) for TRL, VeRL, TorchForge, Monarch, OpenEnv. Sequence diagrams. The unified loss form `total = grpo + α·sdpo + β·trace_replay_dpo` and an argument that the three channels don't compete for any shared resource.
+**3. Integration architecture doc.** [`docs/INTEGRATION_ARCHITECTURE.md`](../docs/INTEGRATION_ARCHITECTURE.md) — verified extension points (via [DeepWiki](https://deepwiki.com/) audits) for TRL, VeRL, TorchForge, Monarch, OpenEnv. Sequence diagrams. The unified loss form `total = grpo + α·sdpo + β·trace_replay_dpo` and an argument that the three channels don't compete for any shared resource.
 
-**4. Empirical economic feasibility result for the novel channel.** [`spikes/001-teacher-replay-cost/verdict.md`](spikes/001-teacher-replay-cost/verdict.md) — 150 real OpenRouter calls (Opus 4.7 + GPT-5 + DeepSeek V4 Pro on 50 synthetic agentic-coding states), 0 errors, **mean per-trace cost $0.98 with 5× headroom on the $5 cap, p95 step latency 20.5s**. Reproducible: set `OPENROUTER_API_KEY` and run the three scripts.
+**4. Empirical economic feasibility result for the novel channel.** [`spikes/001-teacher-replay-cost/verdict.md`](../spikes/001-teacher-replay-cost/verdict.md) — 150 real OpenRouter calls (Opus 4.7 + GPT-5 + DeepSeek V4 Pro on 50 synthetic agentic-coding states), 0 errors, **mean per-trace cost $0.98 with 5× headroom on the $5 cap, p95 step latency 20.5s**. Reproducible: set `OPENROUTER_API_KEY` and run the three scripts.
 
-**5. Working code skeleton with 38 passing unit tests.** [`spikes/005-integrated-trainer-skeleton/`](spikes/005-integrated-trainer-skeleton/) — ports of OPSD's `generalized_jsd_loss`, the teacher-replay DPO-pair extractor, the data collator, both a `ComposerReplicationTrainer(GRPOTrainer)` for TRL and a `@register_adv_est("grpo_composer")` stub for VeRL. The end-to-end loss-composition smoke test runs all three channels on a 10K-parameter custom model and confirms a 5-step train run *decreases* loss with α=0.1, β=0.05 — the channels don't fight each other.
+**5. Working code skeleton with 38 passing unit tests.** [`spikes/005-integrated-trainer-skeleton/`](../spikes/005-integrated-trainer-skeleton/) — ports of OPSD's `generalized_jsd_loss`, the teacher-replay DPO-pair extractor, the data collator, both a `ComposerReplicationTrainer(GRPOTrainer)` for TRL and a `@register_adv_est("grpo_composer")` stub for VeRL. The end-to-end loss-composition smoke test runs all three channels on a 10K-parameter custom model and confirms a 5-step train run *decreases* loss with α=0.1, β=0.05 — the channels don't fight each other.
 
 ```
 $ python3 -m pytest tests/ -v
@@ -44,7 +44,7 @@ Translation: *I have a framework that compiles, integration that's verified at t
 
 2. **Adjacent-work pointers.** Does multi-teacher trace-replay-with-disagreement-as-DPO-signal already exist in published work I missed? My survey (rStar / Math-Shepherd / OmegaPRM / Magpie / MoA) didn't find it but absence of evidence isn't evidence of absence.
 
-3. **Reward-hacking ideas for the v0.1 environment.** Cursor mentions agents decompiling Java bytecode and reverse-engineering Python type-checking caches to recover deleted features in their Feature Deletion env. Their mitigation is opaque ("agentic monitoring tools"). I have proposals in [`PAPER_v0.md` §8](publications/PAPER_v0.md#8-reward-hacking-safeguards-proposed-for-v01) but more eyes welcome.
+3. **Reward-hacking ideas for the v0.1 environment.** Cursor mentions agents decompiling Java bytecode and reverse-engineering Python type-checking caches to recover deleted features in their Feature Deletion env. Their mitigation is opaque ("agentic monitoring tools"). I have proposals in [`PAPER_v0.md` §8](PAPER_v0.md#8-reward-hacking-safeguards-proposed-for-v01) but more eyes welcome.
 
 4. **Collaboration interest for spike 002.** If you have a Modal account or a small GPU budget and want to run the trace-collection experiments — particularly the head-to-head TRL-vs-PRIME-RL comparison — I'd happily co-author a follow-up paper. Total budget for spikes 002–004 is ~$500 + a couple of weeks of wallclock.