whiletrue 0.1.1__tar.gz → 0.2.0__tar.gz

{whiletrue-0.1.1 → whiletrue-0.2.0}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.2.0
+
+- **Recursive self-improvement (`rsi`), off by default.** The Harness² method (Xu et al., arXiv:2610.14224) ported into `whiletrue.rsi.harness2`: isolated rollouts, improver sessions that edit the harness, composition, blind selection, a per-domain experience library, human-approved adoption, `rsi.budget_usd` and the R = 4k / P = 3k budget identity. New: top-level `rsi:` setting, strategy `rsi.harness2`, `whiletrue rsi status|diff|library|adopt|reset`. Claude Code and Codex surfaces. Apache-2.0 code keeps its headers; see THIRD_PARTY_NOTICES.md. Guide: docs/rsi.md.
+- Core: a scope can redirect its steps to another directory (`cwd`), runners can pass raw messages (`RunContext.on_raw`), agents expose an event tap, and the item scope has `project_dir`.
+
 ## 0.1.1
 
 - Fixed: parallel interactive items raced to create the tmux session. The loser failed with `duplicate session` and that error was fed to the agent as its previous failure. Session and pane creation now run one at a time, and parallel agents share one window grid.

{whiletrue-0.1.1 → whiletrue-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: whiletrue
-Version: 0.1.1
+Version: 0.2.0
 Summary: Local orchestrator that runs pipelines of agent and deterministic steps around Claude Code, opencode and Codex, with gates, human approval, parallel git worktrees and crash-safe resume.
 Project-URL: Repository, https://github.com/dariussingh/whiletrue
 Project-URL: Changelog, https://github.com/dariussingh/whiletrue/blob/main/CHANGELOG.md
@@ -8,7 +8,9 @@ Project-URL: Documentation, https://github.com/dariussingh/whiletrue/tree/main/d
 Author: Darius Singh
 License-Expression: MIT
 License-File: LICENSE
-Keywords: agents,ai-agents,claude-code,codex,coding-agents,git-worktree,human-in-the-loop,opencode,orchestration,pipelines,ralph,tmux
+License-File: THIRD_PARTY_NOTICES.md
+License-File: third_party/harness2/LICENSE
+Keywords: agents,ai-agents,claude-code,codex,coding-agents,git-worktree,human-in-the-loop,opencode,orchestration,pipelines,ralph,recursive-self-improvement,tmux
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -137,7 +139,7 @@ Every agent must declare `limits`; `validate` refuses the config otherwise.
 
 <img src="docs/assets/architecture.svg" alt="Architecture: whiletrue.yaml and the CLI drive the core engine (loader, scheduler, pipeline runtime, park and resume, plugin registry, SQLite store); built-in plugins connect it to agent CLIs, git, GitHub and tmux" width="900">
 
-The core knows nothing about git, GitHub, tmux or any agent. Every integration is a plugin built on the public plugin API, so you can add your own ([plugins](docs/plugins.md), [architecture](docs/architecture.md)).
+The core knows nothing about git, GitHub, tmux or any agent. Every integration is a plugin built on the public plugin API, including the optional `rsi` layer, so you can add your own ([plugins](docs/plugins.md), [architecture](docs/architecture.md)).
 
 ## Concepts
 
@@ -263,6 +265,16 @@ whiletrue --help        # installed editable into .devenv/state/venv
 
 Live tests against real agent CLIs are opt-in: `WHILETRUE_LIVE=1 uv run pytest tests/live -v`.
 
+## Recursive self-improvement
+
+Optional and off by default: `rsi: true` lets whiletrue improve the harness around your agent (prompts, skills, subagents) item by item with the Propose, Probe, Compose method from Harness², using isolated rollouts, blind selection and a per-domain experience library. A person approves what is adopted. It multiplies agent spend (about 7 times at `k: 1`) and is capped by `budget_usd`. See [docs/rsi.md](docs/rsi.md). Next: Gemini CLI support.
+
+<img src="docs/assets/rsi-architecture.svg" alt="rsi architecture: task-level recursion per item (reference rollouts, propose, INV and DOM candidates, compose, blind selection, apply) and harnessing-level recursion across items (reflect, human adoption, experience library)" width="900">
+
+## Acknowledgements and citation
+
+The `rsi` feature builds on **Harness²: Recursive Agent Harnessing for an Open World** (Xu et al., Google Research, 2026; [arXiv:2610.14224](https://arxiv.org/abs/2610.14224), [code](https://github.com/google-research/harness2), Apache-2.0). If you use `rsi` in research, please cite the paper (BibTeX in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)). whiletrue is an independent project, not affiliated with Google or the Harness² authors.
+
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE). Third-party code under `third_party/`, benchmarks, and datasets retain their upstream licenses; see [third-party notices](THIRD_PARTY_NOTICES.md).

{whiletrue-0.1.1 → whiletrue-0.2.0}/README.md

@@ -112,7 +112,7 @@ Every agent must declare `limits`; `validate` refuses the config otherwise.
 
 <img src="docs/assets/architecture.svg" alt="Architecture: whiletrue.yaml and the CLI drive the core engine (loader, scheduler, pipeline runtime, park and resume, plugin registry, SQLite store); built-in plugins connect it to agent CLIs, git, GitHub and tmux" width="900">
 
-The core knows nothing about git, GitHub, tmux or any agent. Every integration is a plugin built on the public plugin API, so you can add your own ([plugins](docs/plugins.md), [architecture](docs/architecture.md)).
+The core knows nothing about git, GitHub, tmux or any agent. Every integration is a plugin built on the public plugin API, including the optional `rsi` layer, so you can add your own ([plugins](docs/plugins.md), [architecture](docs/architecture.md)).
 
 ## Concepts
 
@@ -238,6 +238,16 @@ whiletrue --help        # installed editable into .devenv/state/venv
 
 Live tests against real agent CLIs are opt-in: `WHILETRUE_LIVE=1 uv run pytest tests/live -v`.
 
+## Recursive self-improvement
+
+Optional and off by default: `rsi: true` lets whiletrue improve the harness around your agent (prompts, skills, subagents) item by item with the Propose, Probe, Compose method from Harness², using isolated rollouts, blind selection and a per-domain experience library. A person approves what is adopted. It multiplies agent spend (about 7 times at `k: 1`) and is capped by `budget_usd`. See [docs/rsi.md](docs/rsi.md). Next: Gemini CLI support.
+
+<img src="docs/assets/rsi-architecture.svg" alt="rsi architecture: task-level recursion per item (reference rollouts, propose, INV and DOM candidates, compose, blind selection, apply) and harnessing-level recursion across items (reflect, human adoption, experience library)" width="900">
+
+## Acknowledgements and citation
+
+The `rsi` feature builds on **Harness²: Recursive Agent Harnessing for an Open World** (Xu et al., Google Research, 2026; [arXiv:2610.14224](https://arxiv.org/abs/2610.14224), [code](https://github.com/google-research/harness2), Apache-2.0). If you use `rsi` in research, please cite the paper (BibTeX in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)). whiletrue is an independent project, not affiliated with Google or the Harness² authors.
+
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE). Third-party code under `third_party/`, benchmarks, and datasets retain their upstream licenses; see [third-party notices](THIRD_PARTY_NOTICES.md).

whiletrue-0.2.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,32 @@
+# Third-party notices
+
+whiletrue is MIT licensed (see [LICENSE](LICENSE)). Third-party code under `third_party/`, benchmarks and datasets retain their upstream licenses.
+
+## Harness²
+
+The `rsi` feature builds on **Harness²: Recursive Agent Harnessing for an Open World** (Xu et al., Google Research, 2026; [arXiv:2610.14224](https://arxiv.org/abs/2610.14224), [code](https://github.com/google-research/harness2), Apache-2.0). If you use `rsi` in research, please cite the paper (BibTeX below). whiletrue is an independent project, not affiliated with Google or the Harness² authors.
+
+The optional recursive self-improvement feature (`rsi`) is built on the method and code of Harness² by Google Research. The method code is ported and refactored into this repository as `whiletrue.rsi.harness2`; users install no extra dependency.
+
+- Source: https://github.com/google-research/harness2 (pinned commit `1cfe254e8d25b15f37048c3730134686abe60335`)
+- License: Apache License 2.0. The license text is at [third_party/harness2/LICENSE](third_party/harness2/LICENSE).
+- Copyright 2026 Google LLC.
+- Each ported file in `whiletrue/rsi/harness2/` keeps its upstream copyright header and carries a notice that it was modified. The files, their upstream paths and the modifications are listed in [third_party/harness2/PROVENANCE.md](third_party/harness2/PROVENANCE.md). Those files are licensed under Apache-2.0, not MIT.
+- Not taken: the benchmark runners, patches and datasets in the upstream repository (JobBench, LAB, WorkBuddy-Bench). They have their own licenses, and the WorkBuddy-derived code includes a territorial limitation on use. whiletrue does not copy, bundle or redistribute them.
+
+Please cite the paper if you use `rsi` in research:
+
+```bibtex
+@misc{xu2026harness2,
+  title         = {Harness$^2$: Recursive Agent Harnessing for an Open World},
+  author        = {Xu, Ruiyao and Chen, Yanfei and CuiZhu, Zhongying and Dalvi Mishra, Bhavana and Ming, Yifei and Yu, Han and Han, Rujun and Lee, Chen-Yu and Pfister, Tomas},
+  year          = {2026},
+  eprint        = {2610.14224},
+  archivePrefix = {arXiv},
+  primaryClass  = {cs.AI},
+  doi           = {10.48550/arXiv.2610.14224},
+  url           = {https://arxiv.org/abs/2610.14224}
+}
+```
+
+whiletrue is an independent project. It is not affiliated with or endorsed by Google or the Harness² authors.

{whiletrue-0.1.1 → whiletrue-0.2.0}/docs/README.md

@@ -7,12 +7,15 @@
 | [tutorial.md](tutorial.md)             | Tutorial: install, first loop, then build your own gates, review, parallel and human steps |
 | [authoring.md](authoring.md)           | Authoring guide: pipelines, composites, agents, choosing a backend                |
 | [cli.md](cli.md)                       | CLI reference: every command, option, exit code and environment variable          |
+| [rsi.md](rsi.md)                       | Recursive self-improvement: turn it on, what it costs, adoption, limits           |
 | [reference.md](reference.md)           | User reference: modules, control flow, expressions, composites, recipes, replay   |
 | [plugins.md](plugins.md)               | Extending whiletrue: modules, strategies, runners, caps, entry points              |
 | [developing.md](developing.md)         | Contributing: setup, layout, run flow, workflow                                    |
+| [rsi-plan.md](rsi-plan.md)             | Execution plan for M5: Harness² recursive self-improvement and the Gemini CLI backend |
 | [plan.md](plan.md)                     | Implementation plan: milestones M0–M4, dependencies, exit criteria, risks, spikes |
 | [todo.md](todo.md)                     | Numbered, ordered implementation checklist (work top to bottom)                   |
 | [open-questions.md](open-questions.md) | Undecided design questions, each tied to the milestone that forces the decision   |
+| [spike-rsi.md](spike-rsi.md)           | Findings: Harness² method, what is ported, concept mapping and decisions            |
 | [spike-interactive.md](spike-interactive.md) | Findings: plugin hooks and MCP in interactive Claude Code (OQ-1)               |
 | [conventions.md](conventions.md)       | Engineering conventions, test and docs rules (the non-negotiables made concrete)  |
 

{whiletrue-0.1.1 → whiletrue-0.2.0}/docs/architecture.md

@@ -417,6 +417,74 @@ pipeline:
 
 The pipeline exercises every core feature: the item graph, parallel worktrees, retry with feedback, deterministic gates, a side-effect journal (push and PR), a conversational human gate that answers every comment, with a `rejected` route, a nested loop, a reusable composite, a second runner, a shared session across steps, and a resource lock for merges.
 
+## Recursive harness improvement (RSI)
+
+**Status: built (M5), off by default.** User guide: [rsi.md](rsi.md). Source method: Harness² (Xu et al., Google Research, 2026, [arXiv:2610.14224](https://arxiv.org/abs/2610.14224), [code](https://github.com/google-research/harness2), Apache-2.0). The method code is ported into this repo as `whiletrue.rsi.harness2` (Apache-2.0 headers kept; see [THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md)). Other RSI methods can sit beside it as `whiletrue.rsi.<method>`; `rsi.method` selects one (default `harness2`).
+
+A pipeline normally runs the same agent harness (the agent file, plus the project's `CLAUDE.md`, skills, subagents, hooks and scripts) for every item. With `rsi: true`, whiletrue improves that harness while the backlog runs, keeping model weights fixed. It works at two levels.
+
+- **Task-level recursion** refines the harness for the current item with a contrastive **Propose, Probe, Compose** step. Reference rollouts of the base harness give evidence. An improver proposes general (invariant, INV) and domain-specific (DOM) edits. Each candidate is probed by running it on the same item. Compositions combine the candidates using the behavioral contrasts between their rollouts. A blind selector, which never sees scores, picks one final output.
+- **Harnessing-level recursion** keeps what worked. After an item, a reflector stores the adopted harness and evidence-supported lessons in a per-domain library that later items read.
+
+```mermaid
+flowchart LR
+  A[Item] --> B[k reference rollouts<br/>base harness]
+  B --> C[Propose: INV and DOM edits]
+  C --> D[Probe: run each candidate<br/>in its own worktree]
+  D --> E[Compose: k refined harnesses]
+  E --> F[Final rollouts]
+  F --> G[Blind selection]
+  G --> H{Adopt?}
+  H -- approve --> I[Diff at human gate,<br/>commit on approval]
+  G --> J[Reflect]
+  J --> K[(Per-domain library)]
+  K -. read before the next item .-> C
+```
+
+### Setting
+
+```yaml
+rsi: false                  # default; every existing config behaves exactly as before
+
+agents:                     # or per agent file: `rsi:` in the header
+  rsi:
+    k: 1                    # task-level recursion budget
+    mode: parallel          # parallel | sequential
+    domain: "item.labels[0]"   # expression; default is the source label or project
+    adopt: approve          # approve (default) | auto | never
+    evidence: blind         # blind (default) | gates
+    budget_usd: 12          # required; hard cap, parks the item when reached
+    when: "iter.index > 1"  # optional guard
+```
+
+`whiletrue run --rsi` and `--no-rsi` override the file. `validate` refuses `rsi` without a budget, without limits on the improver and selector agents, without `workspace: git-worktree`, or without an adoption policy. `plan` prints the RSI stages and the worst-case cost: one step at `k` is **R = 4k rollouts and P = 3k improvement sessions**, so `k: 1` costs about 7 times a plain agent run.
+
+### How it maps onto whiletrue
+
+| Harness² | whiletrue |
+|---|---|
+| Task, domain, task stream | Item, `rsi.domain`, item order |
+| Base harness | The agent file and the project's agent surface in the item's worktree |
+| Rollout | The pipeline's agent step run under a harness, in an isolated worktree |
+| Executor | A runner: `claude-code-headless`, `claude-code`, `opencode`, `codex`, 
+| Improver, composer, selector, reflector | Ordinary whiletrue agent steps with limits, on any backend |
+| c1..c8 component tree | A `SurfaceSpec` per runner: system prompt, guardrails, memory, tool guidance, subagents, skills, scripts, plugins |
+| Budget ledger | `cost`, split by stage, with a hard `budget_usd` |
+| Experience library | `.whiletrue/rsi/`, linked to `history` and `learnings` |
+
+### Principles
+
+1. **Off unless asked.** `rsi: false` is the default and leaves behavior unchanged. This is regression-tested.
+2. **Answer-free by default.** Evidence and selection never contain a verifier's verdict, as in the paper. A coding pipeline already has deterministic gates, so `evidence: gates` and `selection: gate-first` are opt-in (OQ-12).
+3. **A human adopts.** Candidate harnesses live in worktrees. Adopting one into the repo is a diff at a `human.approve` gate. Hooks, scripts and permission rules are never adopted automatically, because they execute code.
+4. **Bounded.** A required budget, the `4k` and `3k` identity checked at run time, and a `when:` guard.
+5. **Resumable.** Rollouts are journaled; a finished rollout is reused through its completion marker and harness fingerprint.
+6. **Core stays clean.** `whiletrue.rsi` is a plugin on the public API. `whiletrue.core` imports nothing from it.
+
+### What is taken from Harness²
+
+Only method code (`core/`: component tree, spec seam, ledger, library, selection, run markers, evidence context, prompts), ported and refactored into `whiletrue/rsi/harness2/` with the upstream headers kept, modifications noted, and each file listed in `third_party/harness2/PROVENANCE.md`. The orchestration is rebuilt on whiletrue's runtime. Benchmark runners, patches and datasets are not taken; they keep their upstream licenses, and the WorkBuddy-derived code carries a territorial limitation. whiletrue is an independent project and is not affiliated with Google or the Harness² authors.
+
 ## Packages and repo layout
 
 One Python distribution, `whiletrue`, published to PyPI. Each row below is a subpackage (`whiletrue.<name>`); the core has no knowledge of git, GitHub, tmux or any specific agent, and that boundary is enforced by an import test. Third-party plugins are separate distributions that advertise a `Plugin` under the `whiletrue.plugins` entry-point group (or a module exposing `plugin`), and are named in `uses:`.
@@ -434,6 +502,7 @@ One Python distribution, `whiletrue`, published to PyPI. Each row below is a sub
 | `whiletrue.tmux` | TUI: session, panes, control panel | core |
 | `whiletrue.cli` | The `whiletrue` command; loads plugins listed in `whiletrue.yaml` | all of the above as defaults |
 | `whiletrue.recipes` | Shareable composites: `ralph`, `review-pass`, `issue-loop` | control, basics |
+| `whiletrue.rsi` | Optional recursive harness improvement. `whiletrue.rsi.harness2` is the Harness² method (component tree, surfaces, ledger, library, selection, evidence, prompts, `rsi.harness2` strategy, adoption gate); other methods can be added beside it | core, git |
 
 ### CLI surface (v0.1)
 
@@ -444,6 +513,7 @@ One Python distribution, `whiletrue`, published to PyPI. Each row below is a sub
 - `whiletrue.yaml` is the pipeline, and `whiletrue.lock` pins plugin versions.
 - `agents/*.md` and `loops/*.yaml` hold the project's agent modules and composites.
 - `.whiletrue/` holds `state.db`, logs and session transcripts. It is git-ignored.
+- `third_party/` holds the upstream license text and provenance for code ported into this repo (today: Harness²). See [THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md).
 
 ## Implementation status (M0 to M4)
 

{whiletrue-0.1.1 → whiletrue-0.2.0}/docs/assets/architecture.svg

@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 600" width="960" height="600" role="img" aria-label="whiletrue architecture: CLI and whiletrue.yaml feed the core engine, which uses plugins to drive agent CLIs, git, GitHub and tmux, with state in SQLite">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 668" width="960" height="668" role="img" aria-label="whiletrue architecture: CLI and whiletrue.yaml feed the core engine, which uses plugins to drive agent CLIs, git, GitHub and tmux, with state in SQLite">
   <style>
     text{font:13px ui-monospace,SFMono-Regular,Menlo,Consolas,'DejaVu Sans Mono',monospace;fill:#d5dbe3}
     .t{font-size:15px;font-weight:700}.d{fill:#7d8896}.b{fill:#151b23;stroke:#2b3440;stroke-width:1.5}
@@ -6,7 +6,7 @@
     .l{stroke:#7d8896;stroke-width:1.5;fill:none;marker-end:url(#a)}
   </style>
   <defs><marker id="a" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#7d8896"/></marker></defs>
-  <rect width="960" height="600" rx="10" fill="#0f1419"/>
+  <rect width="960" height="668" rx="10" fill="#0f1419"/>
 
   <rect class="b" x="30" y="24" width="900" height="64" rx="6"/>
   <text class="t" x="48" y="50">You</text>
@@ -31,7 +31,7 @@
 
   <path class="l" d="M480 320V346"/>
 
-  <rect class="c" x="30" y="348" width="900" height="122" rx="6"/>
+  <rect class="c" x="30" y="348" width="900" height="190" rx="6"/>
   <text class="t" x="48" y="374">Built-in plugins  (public plugin API only)</text>
   <rect class="b" x="48" y="388" width="140" height="64" rx="5"/><text x="60" y="414">control</text><text class="d" x="60" y="434">loop map switch</text>
   <rect class="b" x="200" y="388" width="140" height="64" rx="5"/><text x="212" y="414">basics</text><text class="d" x="212" y="434">agent shell</text>
@@ -39,10 +39,13 @@
   <rect class="b" x="504" y="388" width="140" height="64" rx="5"/><text x="516" y="414">github</text><text class="d" x="516" y="434">issues, PRs</text>
   <rect class="b" x="656" y="388" width="130" height="64" rx="5"/><text x="668" y="414">claude_code</text><text class="d" x="668" y="434">headless tmux</text>
   <rect class="b" x="798" y="388" width="114" height="64" rx="5"/><text x="810" y="414">opencode</text><text class="d" x="810" y="434">codex</text>
+  <rect x="48" y="462" width="864" height="64" rx="5" fill="#241a2e" stroke="#8b66b0" stroke-width="1.5" stroke-dasharray="6 4"/>
+  <text class="t" x="60" y="486" style="fill:#c9a8e8">rsi (optional, off by default) · Harness²</text>
+  <text class="d" x="60" y="508">rsi.harness2: rollouts, improver sessions, blind selection, library, human adoption</text>
+  
+  <path class="l" d="M480 538V564"/>
 
-  <path class="l" d="M480 470V496"/>
-
-  <rect class="o" x="30" y="498" width="900" height="74" rx="6"/>
-  <text class="t" x="48" y="524">Outside world</text>
-  <text class="d" x="48" y="546">claude · opencode · codex CLIs   |   git   |   gh (GitHub)   |   tmux   |   your tests and scripts</text>
+  <rect class="o" x="30" y="566" width="900" height="74" rx="6"/>
+  <text class="t" x="48" y="592">Outside world</text>
+  <text class="d" x="48" y="614">claude · opencode · codex CLIs   |   git   |   gh (GitHub)   |   tmux   |   your tests and scripts</text>
 </svg>

whiletrue-0.2.0/docs/assets/rsi-architecture.svg

@@ -0,0 +1,69 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 560" width="960" height="560" role="img" aria-label="rsi architecture: task-level recursion runs reference rollouts, proposes general and domain harness edits, probes them in isolated workspaces, composes final harnesses and selects one blind; harnessing-level recursion reflects into a per-domain library read by the next item; a person approves what is adopted">
+<style>
+text{font:13px ui-monospace,SFMono-Regular,Menlo,Consolas,'DejaVu Sans Mono',monospace;fill:#d5dbe3}
+.t{font-weight:700;font-size:15px}.d{fill:#7d8896}.p{fill:#c9a8e8}.ok{fill:#7fd48a}.hu{fill:#e8935a}
+.n{fill:#151b23;stroke:#2b3440;stroke-width:1.5}.a{fill:#10222b;stroke:#3a7f96;stroke-width:1.5}
+.g{fill:#12251a;stroke:#3f7a50;stroke-width:1.5}.y{fill:#2a2812;stroke:#a89a3a;stroke-width:1.5}
+.h{fill:#2a1f14;stroke:#a8683a;stroke-width:1.5}.v{fill:#241a2e;stroke:#8b66b0;stroke-width:1.5}
+.l{stroke:#7d8896;stroke-width:1.5;fill:none;marker-end:url(#m)}
+.lp{stroke:#8b66b0;stroke-width:2;fill:none;marker-end:url(#mp)}
+</style>
+<defs>
+<marker id="m" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#7d8896"/></marker>
+<marker id="mp" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0 0L10 5L0 10z" fill="#8b66b0"/></marker>
+</defs>
+<rect width="960" height="560" rx="10" fill="#0f1419"/>
+<text class="t" x="30" y="32">rsi.harness2: recursion around one item, repeated across items</text>
+
+<rect x="20" y="48" width="920" height="352" rx="12" fill="#12161d" stroke="#3a3f4d" stroke-width="1.5"/>
+<text class="t p" x="36" y="74">Task-level recursion, per item</text>
+
+<rect class="n" x="36" y="92" width="140" height="150" rx="6"/>
+<text class="t" x="48" y="116">Reference</text><text class="t" x="48" y="134">rollouts</text>
+<text class="d" x="48" y="158">k runs of your</text><text class="d" x="48" y="174">steps with the</text><text class="d" x="48" y="190">current harness,</text><text class="d" x="48" y="206">in a workspace</text><text class="d" x="48" y="222">copy</text>
+
+<rect class="a" x="206" y="92" width="150" height="150" rx="6"/>
+<text class="t" x="218" y="116">Propose</text>
+<text class="d" x="218" y="138">improver sessions</text><text class="d" x="218" y="154">edit the harness</text><text class="d" x="218" y="170">from full</text><text class="d" x="218" y="186">trajectories,</text><text class="d" x="218" y="202">no scores</text>
+
+<rect class="g" x="388" y="92" width="190" height="66" rx="6"/>
+<text class="t" x="400" y="116">INV candidates</text><text class="d" x="400" y="138">how the agent works</text>
+<rect class="y" x="388" y="176" width="190" height="66" rx="6"/>
+<text class="t" x="400" y="200">DOM candidates</text><text class="d" x="400" y="222">what an expert knows</text>
+<text class="d" x="388" y="262">Probe: each candidate rolled out once</text>
+
+<rect class="a" x="610" y="92" width="150" height="150" rx="6"/>
+<text class="t" x="622" y="116">Compose</text>
+<text class="d" x="622" y="138">merge using the</text><text class="d" x="622" y="154">rollouts; k final</text><text class="d" x="622" y="170">harnesses, each</text><text class="d" x="622" y="186">rolled out</text>
+
+<rect class="n" x="792" y="92" width="132" height="150" rx="6"/>
+<text class="t" x="804" y="116">Select</text>
+<text class="d" x="804" y="138">anonymous</text><text class="d" x="804" y="154">outputs, blind;</text><text class="d" x="804" y="170">falls back to</text><text class="d" x="804" y="186">a base run</text>
+
+<path class="l" d="M176 167H204"/><path class="l" d="M356 167H386"/><path class="l" d="M578 125H608"/><path class="l" d="M578 209H608"/><path class="l" d="M760 167H790"/>
+<path class="l" d="M858 242V290H241V298"/>
+
+<rect class="h" x="36" y="300" width="410" height="84" rx="6"/>
+<text class="t hu" x="48" y="324">The chosen result is applied</text>
+<text class="d" x="48" y="346">file changes go into the item's workspace;</text>
+<text class="d" x="48" y="364">your gates, commit and PR run on them</text>
+
+<rect class="v" x="478" y="300" width="446" height="84" rx="6"/>
+<text class="t p" x="490" y="324">Budget: R = 4k rollouts, P = 3k sessions</text>
+<text class="d" x="490" y="346">hard cap per item (budget_usd);</text>
+<text class="d" x="490" y="364">finished stages are reused on resume</text>
+
+<rect x="20" y="416" width="920" height="124" rx="12" fill="#17121f" stroke="#8b66b0" stroke-width="1.5"/>
+<text class="t p" x="36" y="442">Harnessing-level recursion, across items</text>
+
+<rect class="v" x="36" y="454" width="190" height="72" rx="6"/>
+<text class="t" x="48" y="478">Reflect</text><text class="d" x="48" y="498">what each edit did,</text><text class="d" x="48" y="514">one lesson at most</text>
+<rect class="h" x="262" y="454" width="250" height="72" rx="6"/>
+<text class="t hu" x="274" y="478">Human adoption gate</text><text class="d" x="274" y="498">approve | auto | never;</text><text class="d" x="274" y="514">code files always a person</text>
+<rect class="v" x="548" y="454" width="250" height="72" rx="6"/>
+<text class="t" x="560" y="478">Experience library</text><text class="d" x="560" y="498">per domain; read by the</text><text class="d" x="560" y="514">next item's improvers</text>
+<path class="lp" d="M226 490H260"/><path class="lp" d="M512 490H546"/>
+<path class="lp" d="M798 490H830V408H462V250H282V244"/>
+<text class="d" x="838" y="478" style="fill:#c9a8e8">next item</text>
+<text class="d" x="36" y="556">Method: Harness² (Xu et al., Google Research, 2026, arXiv:2610.14224), ported into whiletrue.rsi.harness2.</text>
+</svg>

{whiletrue-0.1.1 → whiletrue-0.2.0}/docs/cli.md

@@ -42,6 +42,11 @@
 | `whiletrue comment <item> "text"` | Leave a comment the pipeline must answer at its next wake |
 | `whiletrue history <item>` | The item's timeline: parks, decisions (who, when, note), comments, replies, steers |
 | `whiletrue learnings [list \| approve <id> \| reject <id>]` | Review the lessons `history.distill` proposed; only approved ones reach agents |
+| `whiletrue rsi status` | Every item's recursive self-improvement proposal: state, chosen candidate, spend |
+| `whiletrue rsi diff <item>` | The harness change an item proposed |
+| `whiletrue rsi library` | The experience library, by domain |
+| `whiletrue rsi adopt <item> [--yes]` | Write a proposed harness into the project and store its lesson; `--yes` is required when it changes executable files |
+| `whiletrue rsi reset <item>` | Forget an item's rollouts and proposal |
 
 ## Watching
 

{whiletrue-0.1.1 → whiletrue-0.2.0}/docs/open-questions.md

@@ -11,6 +11,14 @@
 | 7   | ~~License: MIT or Apache-2.0~~ **Resolved: MIT**                                                                                                                                | Done        |
 | 8   | ~~Claim npm org / GitHub org~~ **Superseded by OQ-9:** no npm packages. The PyPI name `whiletrue` is free (checked 2026-10-16); CLI binary stays `whiletrue`. No GitHub org needed. | Done        |
 | 9   | ~~Implementation language~~ **Resolved: Python 3.12+** (2026-10-16), not TypeScript. Nothing in the design needs Node: agents are driven as subprocesses. One `whiletrue` distribution; pydantic, stdlib `sqlite3`, asyncio, pytest, ruff, pyright. | Done        |
+| 11  | ~~Vendor, depend on, or re-implement Harness²?~~ **Resolved (2026-10-26, owner): port and refactor** the method code into this repo as `whiletrue.rsi.harness2` so users install nothing extra and other RSI methods can sit beside it (`whiletrue.rsi.<method>`). Apache-2.0 headers kept, modifications noted, license copy in `third_party/harness2/`. Not ported: benchmark runners, WorkBuddy-derived code (territorial license), datasets. | Done |
+| 12  | Harness² is deliberately answer-free (no ground truth, no grader verdicts in evidence). whiletrue has deterministic gates. Do gate results enter the evidence and selection? Default **blind** (faithful to the paper); opt-in `rsi.evidence: gates` and `selection: gate-first`. | M5 (items 84, 86) |
+| 13  | What are "task", "domain" and the "task stream" for coding work? Proposal: task = item, domain = `rsi.domain` expression (default the source's label or milestone, else the project), stream = item order, library persists across items and runs. | M5 (item 88) |
+| 14  | Where do harness edits live, and who approves them? Candidates run in per-candidate worktrees. Adopting a harness into the repo (`CLAUDE.md`, `.claude/`, `agents/`) is a human decision: `rsi.adopt: approve` (default) shows the diff at a `human.approve` gate; `auto` and `never` exist. Edits to hooks and scripts always need approval. | M5 (item 90) |
+| 15  | Cost. One RSI step at k=1 is 4 rollouts and 3 improvement sessions, about 7x one agent run. How do we keep it affordable: required `rsi.budget_usd`, a `when:` guard (for example only after a gate failure, or every Nth item), worst-case estimate in `plan`? | M5 (items 81, 87) |
+| 16  | The editable surface for Claude Code: which of the eight components map to which files, and which are too dangerous to edit unattended (hooks, scripts, permission rules, MCP). Opencode and Codex surfaces come from Harness²'s `SurfaceSpec`s. | M5 spike (items 79, 82) |
+| 17  | Does `rsi` measurably help on coding backlogs where a gate already exists? Needs an honest evaluation against the existing rule-based `history.distill` baseline before it is recommended. | M5 (item 94) |
+| 18  | Gemini CLI as a backend. Its docs show `-p`, `-o stream-json`, `--approval-mode`, exit codes `0/1/42/53` and `GEMINI.md`, but no budget, turn or structured-output flag, and the layout of skills, extensions and agents is not specified. The README also says unpaid-tier and Google One users moved to Antigravity CLI on 2026-06-18, so access depends on the account type. Verify against the real binary first; treat budget and turn limits as unsupported (like Codex). | M6 spike (item 98) |
 
 ## Decision: expression language (OQ-6)
 

{whiletrue-0.1.1 → whiletrue-0.2.0}/docs/plan.md

@@ -6,7 +6,7 @@ From M1 onward, whiletrue is built using its own workflow (dogfooding). Each mil
 
 ## Status
 
-M0 to M4 are built (M0 and M1 reviewed); what remains is the v0.1 release work in [todo.md](todo.md) (see [todo.md](todo.md)).
+M0 to M4 are built and v0.1.0 and v0.1.1 are published to PyPI. Next is **M5 · recursive harness improvement (`rsi`)**, then v0.2. Open work is in [todo.md](todo.md).
 
 ## Milestone graph
 
@@ -16,7 +16,10 @@ M0 Core engine
      ├─ M2 Interactive Claude Code  ─┐   (M2 and M3 are independent: parallelizable)
      └─ M3 Parallel items & DAG     ─┤
                                      └─ M4 GitHub, human gates, review
-                                          └─ v0.1 release gate
+                                          └─ v0.1 release gate (shipped)
+                                               └─ M5 Recursive harness improvement (rsi)
+                                                    └─ v0.2 release
+                                                         └─ M6 Gemini CLI backend
 ```
 
 | Milestone                        | Scope                                                                                                                 | Exit criterion                           |
@@ -27,6 +30,9 @@ M0 Core engine
 | M3 · Parallel items & DAG        | Item graph, parallel `map`, git worktrees, resource locks, side-effect journal, crash recovery                        | 4 JSON tasks run in parallel             |
 | M4 · GitHub, human gates, review | `github_issues` source, PR/review/merge modules, park/approve/reject, comment replies, opencode runner, control panel | One issue goes open → merged             |
 | v0.1 release                     | Reference pipeline merges a real milestone, 4 items in parallel                                                       | Release gate (see below)                 |
+| M5 · Recursive harness improvement | Optional `rsi` setting (off by default): Propose, Probe, Compose over the agent harness, per-domain experience library, blind selection, human-approved adoption, built on ported Harness² code (Apache-2.0) | A 6-item backlog improves its harness item by item; `rsi: false` is unchanged |
+| v0.2 release                     | `rsi` documented, evaluated and released                                                                              | See M5 exit                              |
+| M6 · Gemini CLI backend          | `runner: gemini` (headless stream-json), tests, docs, plus a Gemini surface for RSI                                    | Gemini runs a pipeline step; v0.3        |
 
 ## Cross-cutting rules (apply in every milestone)
 
@@ -87,6 +93,20 @@ M0 Core engine
 - `whiletrue.opencode` runner; tmux control panel; `logs`, `cost`.
 - `issue-loop` recipe.
 
+### M5 · Recursive harness improvement (RSI)
+
+Goal: an optional `rsi: true | false` setting (default `false`) that lets whiletrue improve the harness around its agents as items flow through a pipeline. The method is Harness² (Xu et al., Google Research, 2026, [arXiv:2610.14224](https://arxiv.org/abs/2610.14224)); we port and refactor its method code into this repo as `whiletrue.rsi.harness2` (Apache-2.0 headers kept, provenance recorded, no extra dependency for users), so other RSI methods can later sit beside it as `whiletrue.rsi.<method>`. Design: [architecture.md](architecture.md#recursive-harness-improvement-rsi).
+
+- **Provenance first:** third-party notices, license copy, pinned commit, citation, a provenance check in CI. No benchmark runners or datasets are ported.
+- **Setting:** `rsi` at the top level and per agent, `--rsi/--no-rsi` on `run`; `validate` requires a budget, limits and an adoption policy; `plan` prints the stages and the worst-case cost multiplier (R = 4k rollouts, P = 3k improvement stages).
+- **Task-level recursion:** reference rollouts of the base harness, general (INV) and domain (DOM) proposals, probes in per-candidate git worktrees, `k` compositions, blind answer-free selection, in parallel and sequential modes.
+- **Harnessing-level recursion:** a per-domain experience library (adopted harness plus evidence-supported lessons), read before each item and appended after, connected to `history` and `learnings`.
+- **Human accountable:** an adopted harness is a diff shown at a human gate before it enters the repo; hooks and scripts always need approval.
+- **Surfaces:** Claude Code (new), opencode and Codex (ported from Harness²).
+Step-by-step execution plan, with stages, dependencies, tests and decisions for you: [rsi-plan.md](rsi-plan.md).
+
+**Exit:** with `rsi: true`, a 6-item backlog improves its agent harness item by item and a person reviews every adopted change; with `rsi: false`, behavior is unchanged (regression-tested). An evaluation against the `history.distill` baseline is published with honest numbers.
+
 ## v0.1 release gate
 
 - Reference pipeline merges a real milestone, 4 items parallel, with at least one `rejected` → fix route and one crash/resume exercised.
@@ -102,3 +122,7 @@ M0 Core engine
 | Crash recovery of tmux panes (re-attach vs. `--resume`)     | Decide via experiment; make policy configurable      | M3          |
 | `session: item` resume with changed cwd                     | Test explicitly; pin worktree per item               | M3          |
 | Expression language scope creep                             | Pick small sandboxed lib early; no Python eval           | M1          |
+| RSI costs about 7x an agent run per item at k=1             | Required `rsi.budget_usd`, `when:` guard, worst-case estimate in `plan` | M5          |
+| Self-edited hooks and scripts are a code-execution surface  | Allow-list; always human-approved; never auto-adopted    | M5          |
+| Ported code loses its attribution or license                | Pinned commit, header and provenance check in CI, notices, no benchmark code | M5          |
+| RSI may not help where a gate already exists                | Opt-in; evaluate against `history.distill` before recommending | M5          |

{whiletrue-0.1.1 → whiletrue-0.2.0}/docs/reference.md

@@ -168,6 +168,17 @@ Built-in recipes use `uses: "recipe:<name>"`:
 - **`on_idle: watch`** keeps the run alive and polls; **`exit`** (default) ends the run `parked` (exit code 2) for `resume`.
 - **Resume** replays every recorded step except those that parked (`needs_human`), runs the rest for real, and keeps the same lineage. Gates, loops and expressions re-run against the recorded results.
 
+## Recursive self-improvement
+
+Optional, off by default. The top-level `rsi:` key (`true`, `false` or settings) wraps the steps around the first agent in the `rsi.harness2` strategy and adds `rsi.review`, `rsi.adopt` and `rsi.discard`. Full guide: [rsi.md](rsi.md).
+
+| Module | Kind | What it does |
+| --- | --- | --- |
+| `rsi.harness2` | strategy | Runs its children in isolated workspace copies, improves the harness, selects blind, applies the chosen rollout's file changes |
+| `rsi.review` | strategy | Asks a person (`human.approve`) when the proposed harness changed |
+| `rsi.adopt` | deterministic | Writes the chosen harness into the workspace and stores the lesson |
+| `rsi.discard` | deterministic | Keeps the current harness |
+
 ## Reproducibility
 
 - **`whiletrue lock`** writes `whiletrue.lock`, pinning the version of each plugin in use. Once it exists, `validate`/`plan`/`run` fail if the plugins drift; run `whiletrue lock` again to accept.

whiletrue-0.2.0/docs/rsi-plan.md

@@ -0,0 +1,121 @@
+# Execution plan: Harness² recursive self-improvement (M5)
+
+How we build [M5](plan.md#m5--recursive-harness-improvement-rsi), in order, with what to write, how to prove each step, and where a person decides. Item numbers refer to [todo.md](todo.md). Gemini CLI support is deliberately later (M6, items 98 to 102). Design: [architecture.md](architecture.md#recursive-harness-improvement-rsi). Open questions: OQ-11 to OQ-17 in [open-questions.md](open-questions.md).
+
+Source: Harness² ([arXiv:2610.14224](https://arxiv.org/abs/2610.14224), [code](https://github.com/google-research/harness2), Apache-2.0, pinned `1cfe254`).
+
+## Approach
+
+1. **Walking skeleton first.** Get the whole Propose, Probe, Compose loop running end to end with a deterministic fake improver and fake executor before any real model is involved. Then swap in real agents one at a time.
+2. **Port and refactor, inside this repo.** The method code becomes `whiletrue.rsi.harness2` (typed to pyright strict, our error and logging conventions, no global state, our test layout), so users install nothing extra and other methods can sit beside it as `whiletrue.rsi.<method>`. Only the method is ported; the orchestration is rebuilt on whiletrue's runtime (items are tasks, pipeline scopes are rollouts, improver sessions are agent steps). Every ported file keeps its Apache header, gains a modification notice and is listed in `third_party/harness2/PROVENANCE.md`.
+3. **Off by default, provably.** A regression test runs existing pipelines with and without the `rsi` key present and requires identical runs.
+4. **Small commits.** One todo item or a tight group per commit, tests and docs in the same change, `poe check` green, and your explicit approval before each commit and push (and before any tag).
+5. **Spend carefully.** Live tests are opt-in (`WHILETRUE_LIVE=1`), use the smallest items, and print their cost. No full runs without a budget you set.
+
+## Dependency graph
+
+```mermaid
+flowchart TD
+  S0[Stage 0 · Provenance, spike, port<br/>items 77-80] --> S2[Stage 2 · Config and validation<br/>item 81]
+  S0 --> S3[Stage 3 · Surfaces and rollouts<br/>items 82-83]
+  S2 --> S3
+  S3 --> S4[Stage 4 · Task-level recursion<br/>items 84-87]
+  S4 --> S5[Stage 5 · Library and reflection<br/>items 88-89]
+  S4 --> S6[Stage 6 · Adoption by a human<br/>item 90]
+  S5 --> S7[Stage 7 · CLI and panel<br/>item 91]
+  S6 --> S7
+  S7 --> S8[Stage 8 · Hardening and live tests<br/>items 92-93]
+  S8 --> S9[Stage 9 · Evaluation, docs, release<br/>items 94-97]
+  S9 --> M6[M6 · Gemini CLI backend<br/>items 98-102]
+```
+
+Stage 2 (config) and the surface half of Stage 3 only need Stage 0, so they can overlap. The rollout adapter reads the `rsi` config.
+
+## Stage 0 · Provenance and spike (items 77 to 80)
+
+**Goal:** know exactly what we take and prove we can run it.
+
+- **77 (done):** `THIRD_PARTY_NOTICES.md`, `third_party/harness2/{LICENSE,PROVENANCE.md}`, README citation and the license sentence.
+- **78 provenance check:** `scripts/check_provenance.py`. `PROVENANCE.md` maps each ported file to its upstream path. The script fails when a file under `whiletrue/rsi/harness2/` lacks the upstream Apache header or a modification notice, or is not listed. It runs inside `poe docs-check` and CI.
+- **79 spike (`docs/spike-rsi.md`):** clone the pinned commit into a scratch directory, run `harness2-demo --k 2` (no credentials) and trace one task: reference rollouts, INV and DOM proposals, probes, compositions, selection, reflection. Fill the mapping table (task, domain, harness, rollout, executor, improver) and the Claude Code surface and unsafe list (OQ-16).
+- **80 port (`whiletrue/rsi/harness2/`):** `tree.py` and `surfaces.py` (component tree, `SurfaceSpec`), `ledger.py`, `library.py`, `runmark.py`, `selection.py`, `context.py` (evidence tree and leak tripwires), `prompts.py`. Refactor to this repo: typed models, no module globals, our error types, small functions that pass the repo's lint rules, tests in `tests/unit/rsi/harness2/`. Not ported: benchmarks, judge, report, the sweep scheduler, CLI, install and the substrates (our runners replace them).
+
+**Exit:** the ported modules pass their tests and reproduce the upstream budget identity, tree validation and selection behavior; the provenance check is in CI.
+
+## Stage 2 · Config and validation (item 81)
+
+**Goal:** the `rsi` setting exists, validates, plans, and changes nothing when off.
+
+- Pydantic models for `rsi: bool | {k, mode, domain, adopt, evidence, budget_usd, when}` at the top level and in agent headers; precedence agent over top level; `--rsi/--no-rsi` on `run`.
+- `validate` rules: budget required, limits on improver and selector agents, `workspace: git-worktree`, an adoption policy.
+- `plan`: prints the RSI stages and the worst-case multiplier (R = 4k rollouts, P = 3k improvement sessions) and the worst-case cost from the agents' limits.
+- Tests: golden outputs for `validate` and `plan`, and the regression test that every existing example and recipe yields identical plans and runs with the key absent versus `rsi: false`.
+
+**Exit:** `whiletrue plan` shows an RSI-expanded pipeline for a sample config; nothing runs yet.
+
+## Stage 3 · Surfaces and rollouts (items 82 and 83)
+
+**Goal:** read, edit and run a candidate harness in isolation.
+
+- **82 surfaces (`whiletrue/rsi/surface_*.py`):** one `SurfaceSpec` each for Claude Code, opencode and Codex (reuse upstream's). Claude Code maps the eight components to files in the worktree: system prompt (agent file prompt), guardrails (permission settings), memory (`CLAUDE.md`), tool guidance (agent `tools:` and prompt section), subagents (`.claude/agents/`), skills (`.claude/skills/`), scripts, plugins (hooks, MCP). Read, validate, write and diff trees; flag hooks, scripts, permission rules and MCP as always-approve. Tests with golden trees.
+- **83 rollout adapter (`rollout.py`):** run the pipeline's agent step under a candidate tree in its own worktree (`git worktree add` from the item's base), collect trajectory (run record events and transcript) and deliverable, and write the completion marker and harness fingerprint so a finished rollout is reused on resume. Tests with the fake executor: isolation (two candidates never share files), reuse on resume, crash mid-rollout.
+
+**Exit:** with a fake executor, a candidate harness is applied, run and recorded in a worktree, then cleaned up.
+
+## Stage 4 · Task-level recursion (items 84 to 87)
+
+**Goal:** Propose, Probe, Compose, select, with the budget identity enforced.
+
+- **84 improver and evidence:** the improver, composer and selector are ordinary whiletrue agent steps (limits, any backend), prompts adapted from `prompts.py`. The evidence tree builder writes task, rollouts, deliverables, current harness and library as files, with the answer-free tripwires (no gate verdicts unless `evidence: gates`). Tests: a planted gate verdict in evidence is rejected.
+- **85 `rsi` strategy:** k reference rollouts, k general and k domain proposals, probes, k compositions, final rollouts. Parallel mode uses the scheduler's semaphores and `max_agents`; sequential mode carries the harness and evidence forward. Every stage is journaled and resumable. Tests: golden stage order for both modes at k=1 and k=2, resume after a kill at each stage.
+- **86 blind selection:** anonymized finals with a seeded shuffle, selector failure falls back to the base output, optional `selection: gate-first`.
+- **87 budget ledger:** check R = 4k and P = 3k at run time, record spend per stage, enforce `rsi.budget_usd` (park the item with a reason), apply the `when:` guard. `cost` splits by stage. Tests: identity violations fail loudly; budget exhaustion parks, never overspends.
+
+**Exit:** the fake-executor demo (ported from `harness2-demo`) runs both modes to a selected output, and the ledger balances.
+
+## Stage 5 · Library and reflection (items 88 and 89)
+
+**Goal:** later items benefit from earlier ones.
+
+- **88 library:** `.whiletrue/rsi/<domain>/` holds adopted harnesses and `EXPERIENCE.md`, read before each item and appended after. Ordered within a domain, concurrent across domains, scoped per run and mode. Domain comes from `rsi.domain`. Tests: ordering, isolation between domains, library read in the evidence tree.
+- **89 reflector:** an agent step proposing evidence-supported lessons into `history` and `learnings`; nothing reaches an agent until you approve it (existing `learnings approve`).
+
+## Stage 6 · Adoption by a human (item 90)
+
+**Goal:** you stay accountable for every line.
+
+- `rsi.adopt: approve | auto | never`. On `approve`, the chosen harness diff is shown at a `human.approve` gate (`what: harness`), committed on approval and discarded on `rejected`; your rejection note feeds the next reflection. Hooks, scripts, permission rules and MCP edits never use `auto`.
+- Tests: approve commits exactly the diff shown; reject leaves the repo untouched; `auto` refuses unsafe paths.
+
+## Stage 7 · CLI and panel (item 91)
+
+`whiletrue rsi status | diff | library | adopt | reset`; the control panel shows the RSI stage per item; `logs` and `cost` split by stage. Tests via the CLI harness; docs in `cli.md`.
+
+## Stage 8 · Hardening and live tests (items 92 and 93)
+
+- **92:** the fake-executor demo as an integration test; kill and resume at every stage; the `rsi: false` regression suite; coverage floor held or raised.
+- **93 (opt-in, spends tokens):** real Claude Code, `k=1`, one tiny item, under a small `budget_usd`. Record cost and wall time in the docs.
+
+## Stage 9 · Evaluation, docs, release (items 94 to 97)
+
+- **94 evaluation:** a small coding backlog (about 6 items, like the tutorial's), run three ways (base, `history.distill` baseline, `rsi`), measuring gate pass rate, retries and cost. Publish the numbers honestly, including a negative result (OQ-17).
+- **95 docs:** `docs/rsi.md`, a tutorial section, reference and architecture updates, README feature text (replacing "Roadmap"), CHANGELOG, citation kept in place.
+- **96 exit check** and **97 release `v0.2.0`:** version bump, tag, PyPI trusted publishing, as for 0.1.1.
+
+## Decisions to make with you
+
+| # | Decision | When | Default if you say nothing |
+|---|---|---|---|
+| D1 | Package layout for later RSI methods (OQ-11, decided) | Done | `whiletrue.rsi.<method>`, starting with `whiletrue.rsi.harness2` |
+| D2 | Live-test budget (dollars) for Stages 8 and 9 | Stage 8 | $5 total |
+| D3 | Whether `evidence: gates` ships in v0.2 (OQ-12) | Stage 4 | Ships as opt-in, off by default |
+| D4 | `adopt` default (OQ-14) | Stage 6 | `approve` |
+| D5 | A throwaway repo for the real-GitHub run (todo 71) and for the RSI evaluation | Stage 9 | Local `origin` and file-backed GitHub |
+
+## Definition of done for M5
+
+- Every todo item 77 to 96 is ticked with its tests and docs in the same commit.
+- `rsi: false` leaves all existing behavior and tests unchanged.
+- `poe check` is green with the coverage floor held; the provenance check is in CI.
+- The evaluation is published; the README claims only what it shows.
+- Notices and the paper citation are in place, no upstream benchmark code or data is copied, and you have reviewed every adopted-harness path and the ported file list.