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.