docs: centralise on DESIGN and STATUS, band what they replace

README.md

@@ -119,44 +119,61 @@ If all seven hold, v1 is done regardless of what remains unimplemented.
 
 ## Documentation
 
-- **[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — how it fits together.**
-  Diagrams: the whole system, what an agent actually is, the components, the
-  life of a work item, failure classification, the audit layer, and project
-  isolation.
-- **[`docs/INTERNALS.md`](docs/INTERNALS.md) — a layer deeper.** What actually happens
-  inside: backlog building, triage and claiming, model routing, the retry ladder,
-  completion, review, and merge/revert reconciliation.
-- **[`docs/USAGE.md`](docs/USAGE.md) — start here.** A worked example end to end, with
-  real output. Its **"Which way in?"** table routes you by where you are starting from:
-  a demo with no credentials, a new project from a paragraph, a plan you already wrote,
-  or a project already half-built that you want to take on. Then: sync it, execute it,
-  resume it, drive it from the API, and read the failures.
-- **[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) — running it as a service.** The two
-  `serve` modes, what a supervised deployment must provide, and a non-destructive smoke
-  test that distinguishes "healthy" from "able to run anything".
+Two documents carry the current state. Everything else is a how-to, an
+operational runbook, or history.
+
+- **[`docs/DESIGN.md`](docs/DESIGN.md) — how the harness works, and why it is
+  shaped that way.** The execution pipeline, the invariants and the failure
+  each one came from, model routing and failure classification, the dependency
+  graph, durability, and the extension points. Start here to understand it.
+- **[`docs/STATUS.md`](docs/STATUS.md) — where it stands, and everything
+  outstanding.** What is proven, observed and merely tested; the open work in
+  the order it can be done; and how to run the harness against **rdpapp**, the
+  first application it is being tested against.
+
+### How to use it
+
+- **[`docs/USAGE.md`](docs/USAGE.md) — a worked example, end to end, with real
+  output.** Its **"Which way in?"** table routes you by where you are starting
+  from: a demo needing no credentials, a new project from a paragraph, a plan
+  you already wrote, or a project already half-built.
 - [`examples/PLAN.md`](examples/PLAN.md) — the sample plan that walkthrough uses.
-- [`docs/HARNESS-PLAN.md`](docs/HARNESS-PLAN.md) — the original plan. **Superseded in
-  part:** it was written assuming one specific consumer, and the harness is now generic.
-  Read it for the evidence and the reasoning, not the phase order, and see §0.1 for what
-  changed.
-- [`docs/MULTI-PROJECT-PLAN.md`](docs/MULTI-PROJECT-PLAN.md) — project scoping, the GUI
-  that scoping makes possible, and project inception. Phases 0-2 are built.
-- [`docs/AUDIT-PLAN.md`](docs/AUDIT-PLAN.md) — the durable audit layer: what is worth
-  measuring and the rules that keep the numbers defensible.
-- [`docs/backlog-seed-2026-08-02.json`](docs/backlog-seed-2026-08-02.json) — the manifest
-  that seeded the GitHub issues on that date, plus the decision records `D1`–`D10`. It is
-  a historical artefact: it has no state field and is not kept in sync. GitHub is the
-  tracker (D1); this file cannot tell you whether anything is open.
-- [`docs/COORDINATION-PLANE.md`](docs/COORDINATION-PLANE.md) — the typed work graph (§8,
-  built) and the message ledger, rooms and oversight actor (**proposed, not built**).
-- [`docs/MIGRATION-graph.md`](docs/MIGRATION-graph.md) — backing up, exporting, rebuilding
-  and rolling back the queue's schema.
-- [`docs/evidence/`](docs/evidence/) — append-only evidence packages, one per stage, each
-  with a blind-spots section saying which of its own claims are untested.
-  [`2026-08-04-programme-report.md`](docs/evidence/2026-08-04-programme-report.md) is the
-  summary over all of them.
-- [`AGENTS.md`](AGENTS.md) — binding rules of engagement for anyone, human or agent,
-  working in this repository.
+- **[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) — running it as a service.** The
+  two `serve` modes, what a supervised deployment must provide, and a
+  non-destructive smoke test that distinguishes "healthy" from "able to run
+  anything".
+- [`docs/MIGRATION-graph.md`](docs/MIGRATION-graph.md) — backing up, exporting,
+  rebuilding and rolling back the queue's schema.
+
+### The record
+
+- [`docs/evidence/`](docs/evidence/) — append-only evidence packages, each with
+  a blind-spots section saying which of its own claims are untested.
+  [`2026-08-04-programme-report.md`](docs/evidence/2026-08-04-programme-report.md)
+  summarises the stage programme;
+  [`2026-08-05-06-rdpapp-m2-status.md`](docs/evidence/2026-08-05-06-rdpapp-m2-status.md)
+  is the running record of the first real workload.
+- [`AGENTS.md`](AGENTS.md) — binding rules of engagement for anyone, human or
+  agent, working in this repository. Includes the decisions that are settled
+  and must not be re-litigated, and the one that was reopened.
+
+### Superseded
+
+Kept for their reasoning and evidence. Each carries a banner saying what
+replaced it. **Do not follow their plans, phase orders, or statements of
+current state.**
+
+[`HARNESS-PLAN.md`](docs/HARNESS-PLAN.md) ·
+[`MULTI-PROJECT-PLAN.md`](docs/MULTI-PROJECT-PLAN.md) ·
+[`AUDIT-PLAN.md`](docs/AUDIT-PLAN.md) ·
+[`FIT-FOR-PURPOSE-STATUS.md`](docs/FIT-FOR-PURPOSE-STATUS.md) ·
+[`COORDINATION-PLANE.md`](docs/COORDINATION-PLANE.md) ·
+[`ARCHITECTURE.md`](docs/ARCHITECTURE.md) ·
+[`INTERNALS.md`](docs/INTERNALS.md) ·
+[`PROPOSAL-2026-08-*.md`](docs/) ·
+[`backlog-seed-2026-08-02.json`](docs/backlog-seed-2026-08-02.json) — the
+manifest that seeded the issues on that date, plus decision records `D1`–`D10`.
+It has no state field and is not kept in sync; GitHub is the tracker (D1).
 
 ## Using it
 

docs/ARCHITECTURE.md

@@ -1,5 +1,14 @@
 # Architecture
 
+> # Superseded — 2026-08-06
+>
+> Consolidated into `DESIGN.md`, which carries the diagrams that earned their place and drops those that only restated a list.
+>
+> **Current documentation:** [`docs/DESIGN.md`](DESIGN.md) — how the harness
+> works and why. [`docs/STATUS.md`](STATUS.md) — where it stands.
+>
+> Where this document and the code disagree, the code is right.
+
 How AIDevEnv and agent-harness fit together, and what happens inside the
 harness when work runs.
 

docs/AUDIT-PLAN.md

@@ -1,5 +1,18 @@
 # A durable audit layer
 
+> # Superseded — 2026-08-06
+>
+> The durable audit layer, which is built. What survives is in `DESIGN.md`; the plan itself is history.
+>
+> **Current documentation:**
+> [`docs/DESIGN.md`](DESIGN.md) — how the harness works and why.
+> [`docs/STATUS.md`](STATUS.md) — where it stands and what is left to do.
+>
+> Kept for the reasoning and the evidence, which are not reproduced elsewhere.
+> **Do not follow its plan, its phase order, or its statements of current
+> state** — all three are out of date. Where this document and the code
+> disagree, the code is right.
+
 Status: proposed, not started. Written 2026-08-02.
 
 Tracking whether the harness is getting better or worse, over months, across

docs/COORDINATION-PLANE.md

@@ -1,5 +1,14 @@
 # Agent coordination and oversight
 
+> # Superseded — 2026-08-06
+>
+> **Half superseded, half still the only record.** The typed work graph (§8) is built and is described in `DESIGN.md`. The message ledger, rooms and oversight actor remain **proposed and not built**, and this document is still the only place they are specified — that part is not replaced by anything.
+>
+> **Current documentation:** [`docs/DESIGN.md`](DESIGN.md) — how the harness
+> works and why. [`docs/STATUS.md`](STATUS.md) — where it stands.
+>
+> Where this document and the code disagree, the code is right.
+
 Status: written 2026-08-03. **Partly implemented — updated 2026-08-04.**
 
 | Section | State |

docs/FIT-FOR-PURPOSE-STATUS.md

@@ -1,5 +1,18 @@
 # Fit-for-purpose programme — status and handoff
 
+> # Superseded — 2026-08-06
+>
+> Frozen at 2026-08-04 by its own header, and superseded on 2026-08-06 by `docs/STATUS.md`. Its stage-by-stage record is still the account of how each stage was verified in isolation.
+>
+> **Current documentation:**
+> [`docs/DESIGN.md`](DESIGN.md) — how the harness works and why.
+> [`docs/STATUS.md`](STATUS.md) — where it stands and what is left to do.
+>
+> Kept for the reasoning and the evidence, which are not reproduced elsewhere.
+> **Do not follow its plan, its phase order, or its statements of current
+> state** — all three are out of date. Where this document and the code
+> disagree, the code is right.
+
 **Frozen:** 2026-08-04. **Rewritten 2026-08-04 after stages F, D, K, H, L, J and M.**
 **Read this before doing any work on the proposal.**
 

docs/HARNESS-PLAN.md

@@ -1,5 +1,18 @@
 # agent-harness: Comprehensive Plan
 
+> # Superseded — 2026-08-06
+>
+> The original design document. It assumes one named consumer throughout, and the harness is generic — an owner ruling recorded in `AGENTS.md`. Its phase order was overtaken and its §0.1 already said so.
+>
+> **Current documentation:**
+> [`docs/DESIGN.md`](DESIGN.md) — how the harness works and why.
+> [`docs/STATUS.md`](STATUS.md) — where it stands and what is left to do.
+>
+> Kept for the reasoning and the evidence, which are not reproduced elsewhere.
+> **Do not follow its plan, its phase order, or its statements of current
+> state** — all three are out of date. Where this document and the code
+> disagree, the code is right.
+
 **Status (2026-08-02).** P0 complete. P1's code is written and under review as
 `swack-tools/oxidex#417`; its *deliverable* — the 72-hour measurement — has not been run.
 P2's code is merged and the dashboard runs, but it has never seen live traffic, is not

docs/INTERNALS.md

@@ -1,5 +1,14 @@
 # Internals
 
+> # Superseded — 2026-08-06
+>
+> Consolidated into `DESIGN.md`. It described the direct executor's single-shot implementer in detail; #195 reframes that as the defect rather than the design, so read it as history.
+>
+> **Current documentation:** [`docs/DESIGN.md`](DESIGN.md) — how the harness
+> works and why. [`docs/STATUS.md`](STATUS.md) — where it stands.
+>
+> Where this document and the code disagree, the code is right.
+
 A layer below [`ARCHITECTURE.md`](ARCHITECTURE.md). That one says what the
 pieces are; this says what actually happens inside them — how a backlog gets
 built, how work is triaged and claimed, where a model call goes and what

docs/MULTI-PROJECT-PLAN.md

@@ -1,5 +1,18 @@
 # Multi-project harness and a real Work GUI
 
+> # Superseded — 2026-08-06
+>
+> Project scoping, inception and the GUI that scoping was to make possible. Phases 0–2 are built and are described in `DESIGN.md`; the rest is not a current plan.
+>
+> **Current documentation:**
+> [`docs/DESIGN.md`](DESIGN.md) — how the harness works and why.
+> [`docs/STATUS.md`](STATUS.md) — where it stands and what is left to do.
+>
+> Kept for the reasoning and the evidence, which are not reproduced elsewhere.
+> **Do not follow its plan, its phase order, or its statements of current
+> state** — all three are out of date. Where this document and the code
+> disagree, the code is right.
+
 Status: written 2026-08-02. **Partly implemented — updated 2026-08-04.**
 
 | Phase | State |

docs/PROPOSAL-2026-08-agent-interaction.md

@@ -1,5 +1,18 @@
 # Proposal — make the coordination plane worth having
 
+> # Superseded — 2026-08-06
+>
+> A proposal about how the harness talks to an agent. Overtaken by #195, which reframes the problem: the single-shot model call is the defect, and every role that answers questions about a repository must be a loop.
+>
+> **Current documentation:**
+> [`docs/DESIGN.md`](DESIGN.md) — how the harness works and why.
+> [`docs/STATUS.md`](STATUS.md) — where it stands and what is left to do.
+>
+> Kept for the reasoning and the evidence, which are not reproduced elsewhere.
+> **Do not follow its plan, its phase order, or its statements of current
+> state** — all three are out of date. Where this document and the code
+> disagree, the code is right.
+
 **Status:** proposal, not accepted. Written 2026-08-04, after connecting the
 oversight actor to a real fleet and running it against a real model.
 

docs/PROPOSAL-2026-08-finish-then-extend.md

@@ -1,5 +1,18 @@
 # Proposal — finish the fit-for-purpose programme, then extend it
 
+> # Superseded — 2026-08-06
+>
+> A sequencing proposal. Its decisions D11–D14 are recorded in `AGENTS.md` and remain in force; the sequencing itself is spent.
+>
+> **Current documentation:**
+> [`docs/DESIGN.md`](DESIGN.md) — how the harness works and why.
+> [`docs/STATUS.md`](STATUS.md) — where it stands and what is left to do.
+>
+> Kept for the reasoning and the evidence, which are not reproduced elsewhere.
+> **Do not follow its plan, its phase order, or its statements of current
+> state** — all three are out of date. Where this document and the code
+> disagree, the code is right.
+
 **Status:** proposal, not accepted. Written 2026-08-04, after a review of five
 comparable systems: [Conductor](https://github.com/conductor-oss/conductor),
 [agentspan](https://github.com/agentspan-ai/agentspan),

docs/PROPOSAL-2026-08-fit-for-purpose.md

@@ -1,5 +1,18 @@
 # Proposal — making agent-harness fit for purpose
 
+> # Superseded — 2026-08-06
+>
+> The proposal the fit-for-purpose programme ran against. The programme finished; its report is in `docs/evidence/2026-08-04-programme-report.md`.
+>
+> **Current documentation:**
+> [`docs/DESIGN.md`](DESIGN.md) — how the harness works and why.
+> [`docs/STATUS.md`](STATUS.md) — where it stands and what is left to do.
+>
+> Kept for the reasoning and the evidence, which are not reproduced elsewhere.
+> **Do not follow its plan, its phase order, or its statements of current
+> state** — all three are out of date. Where this document and the code
+> disagree, the code is right.
+
 **Status:** proposal, not accepted. Revised 2026-08-04 after the first
 sustained attempt to run a real workload through the harness.