From 13c985ce298f3fc9d49f9f1c5cccfc3c2bf665c0 Mon Sep 17 00:00:00 2001 From: sprooty Date: Thu, 6 Aug 2026 02:32:01 +0000 Subject: [PATCH] docs: centralise on DESIGN and STATUS, band what they replace Fifteen documents, ~7,500 lines, several describing the same thing at different dates and disagreeing about the current state. A reader had no way to tell which was true. Ten are banded as superseded rather than deleted: their reasoning and evidence are not reproduced anywhere, and this repository keeps the argument even when the conclusion changes. Each banner names what replaced it and says plainly that where the document and the code disagree, the code is right. COORDINATION-PLANE.md is banded carefully, because it is only half superseded: the typed work graph is built and moves to DESIGN.md, but the message ledger, rooms and oversight actor remain proposed and not built, and that document is still the only place they are specified. The README's index is rewritten around two documents and three groups: how to use it, the record, and what is superseded. Co-Authored-By: Claude Opus 5 (1M context) --- README.md | 91 ++++++++++++--------- docs/ARCHITECTURE.md | 9 ++ docs/AUDIT-PLAN.md | 13 +++ docs/COORDINATION-PLANE.md | 9 ++ docs/FIT-FOR-PURPOSE-STATUS.md | 13 +++ docs/HARNESS-PLAN.md | 13 +++ docs/INTERNALS.md | 9 ++ docs/MULTI-PROJECT-PLAN.md | 13 +++ docs/PROPOSAL-2026-08-agent-interaction.md | 13 +++ docs/PROPOSAL-2026-08-finish-then-extend.md | 13 +++ docs/PROPOSAL-2026-08-fit-for-purpose.md | 13 +++ 11 files changed, 172 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 6498a69..c68011d 100644 --- a/README.md +++ b/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 diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index c650484..82e76e5 100644 --- a/docs/ARCHITECTURE.md +++ b/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. diff --git a/docs/AUDIT-PLAN.md b/docs/AUDIT-PLAN.md index cbc17e8..7838863 100644 --- a/docs/AUDIT-PLAN.md +++ b/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 diff --git a/docs/COORDINATION-PLANE.md b/docs/COORDINATION-PLANE.md index c2919a6..c11c938 100644 --- a/docs/COORDINATION-PLANE.md +++ b/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 | diff --git a/docs/FIT-FOR-PURPOSE-STATUS.md b/docs/FIT-FOR-PURPOSE-STATUS.md index c80129f..e83eb61 100644 --- a/docs/FIT-FOR-PURPOSE-STATUS.md +++ b/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.** diff --git a/docs/HARNESS-PLAN.md b/docs/HARNESS-PLAN.md index 2c25947..cedcdef 100644 --- a/docs/HARNESS-PLAN.md +++ b/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 diff --git a/docs/INTERNALS.md b/docs/INTERNALS.md index 81598fc..22729af 100644 --- a/docs/INTERNALS.md +++ b/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 diff --git a/docs/MULTI-PROJECT-PLAN.md b/docs/MULTI-PROJECT-PLAN.md index 9f53005..cac5048 100644 --- a/docs/MULTI-PROJECT-PLAN.md +++ b/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 | diff --git a/docs/PROPOSAL-2026-08-agent-interaction.md b/docs/PROPOSAL-2026-08-agent-interaction.md index 20d398c..c6c1bbb 100644 --- a/docs/PROPOSAL-2026-08-agent-interaction.md +++ b/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. diff --git a/docs/PROPOSAL-2026-08-finish-then-extend.md b/docs/PROPOSAL-2026-08-finish-then-extend.md index 0657b28..c24a357 100644 --- a/docs/PROPOSAL-2026-08-finish-then-extend.md +++ b/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), diff --git a/docs/PROPOSAL-2026-08-fit-for-purpose.md b/docs/PROPOSAL-2026-08-fit-for-purpose.md index a744163..9494052 100644 --- a/docs/PROPOSAL-2026-08-fit-for-purpose.md +++ b/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.