diff --git a/docs/adr/0003-spend-verification-where-the-money-is.md b/docs/adr/0003-spend-verification-where-the-money-is.md new file mode 100644 index 0000000..b5c059d --- /dev/null +++ b/docs/adr/0003-spend-verification-where-the-money-is.md @@ -0,0 +1,84 @@ +# ADR-0003 — Spend verification where the money is, and stop tidying inside fixes + +- **Status**: Accepted +- **Date**: 2026-09-22 +- **Complements** [ADR-0002](./0002-a-delegated-session-may-verify-and-signs-as-itself.md) + +## Context + +Cycle 02 spent **six independent verification rounds** on `screening`'s window read. The +module is `high`, read-only, holds no key and places no order. The rounds were not wasted — +they found eleven real defects — but the decider named the cost plainly: *too many constraints +become a real brake on progress*, and the project is at half-time against a 2026-12-31 kill +date with the `critical` module not yet started. + +Reading the eleven defects by origin tells a second story: + +| Origin | Count | +|---|---| +| Defects in the original implementation | 4 | +| Defects the author **introduced in a later round**, in changes nobody asked for | 3 | +| Fixtures of the author's that proved nothing | 9 across the cycle | + +Three of the round-six blockers did not exist before round five. Each came from tidying +inside a fix: a guard removed as "unreachable" on a reason that was false, an assertion +deleted while rewriting the test around it, a reorder made because the code read better that +way. The verification rounds were not finding a module that resisted being fixed; they were +finding a fixer who kept changing more than was asked. + +## Decision + +**Two rules, one about where to spend and one about what not to do.** + +### 1. The verification budget follows criticality + +| Criticality | Budget | +|---|---| +| `high` or below, read-only | **One round.** Blockers are fixed; everything else becomes a recorded follow-up. No second adversarial round — a confirmation run at the head for T4 is not a round | +| `critical` — holds a key, places an order, moves money | **Adversarial rounds without a cap**, until the verifier signs | + +The module's criticality is already declared in its MANIFEST, so this needs no new field and +no judgement in the moment. + +### 2. A fix changes only what the finding names + +No unasked change inside a correction. Something that looks worth cleaning becomes a line in +the follow-up list, not an edit in the same commit. This is free, and it would have prevented +three of cycle 02's blockers. + +## Consequences + +**Accepted.** Less verification on read-only modules means some defects ship there. That is +the trade, taken deliberately: a wrong figure in a screening report is visible to an +administrator who can re-run it, while a wrong order in the copying module is a member's +money. + +**Accepted.** "No unasked change" will sometimes leave code the author knows is untidy. The +follow-up list is where that goes, and a follow-up list nobody reads is the failure mode to +watch. + +**Not accepted.** This does not reduce what a `critical` module must show. Two things are not +negotiable there and they are tests, not process: the agent key can place orders and nothing +else, and revocation works. They cost an hour; not having them costs the project. + +## Success criterion + +By **2026-12-31**: no deliverable of a `high` module has taken more than one adversarial +verification round, and no blocker on any module has been traced to a change the finding did +not name. If either happens, the rules did not bind and this ADR needs teeth rather than +restating. + +## Removal condition + +If a `high` module ships a defect that reaches a member's money, the first rule is wrong and +the budget goes back up. That is the event to watch for, and it is worth more than any +argument about proportion. + +## Alternatives considered + +- **Keep the same depth everywhere.** What cycle 02 did. It produced a well-tested read + function and no copying module, which is the wrong artefact to have polished. +- **Cap rounds by count on every module.** A cap on `critical` work is a promise to stop + looking before the answer arrives, on the code that holds the key. +- **Drop independent verification on `high` modules entirely.** Four of the eleven defects + were in the first round. The first round is the one that pays. diff --git a/docs/adr/README.md b/docs/adr/README.md index ebd59bc..6abe80a 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -24,3 +24,4 @@ See `docs/os/06-decisions.md`. |---|---|---|---| | [0001](./0001-split-the-agent-github-identity-in-two.md) | Split the agent's forge identity in two: the App commits, the administration token configures | Accepted | 2027-03-20 | | [0002](./0002-a-delegated-session-may-verify-and-signs-as-itself.md) | A delegated session may verify, and signs under its own identifier | Accepted | +| [0003](./0003-spend-verification-where-the-money-is.md) | Spend verification where the money is, and stop tidying inside fixes | Accepted | diff --git a/docs/project/README.md b/docs/project/README.md index b7a0a25..86290f5 100644 --- a/docs/project/README.md +++ b/docs/project/README.md @@ -9,6 +9,7 @@ cycle before working (`AGENTS.md` §4). | `discovery.md` | An idea tested: evidence, value hypothesis, challenge, decision | The framer, then the challenger (`playbooks/discovery.md`) | The decider | | `charter.md` | Users, problem, constraints, risks, success criteria, out of scope | The framer (`playbooks/framing.md`) | The decider | | `cycles/NN-.md` | One goal, a finite list of deliverables, an appetite, an end date, the closure | The framer | The decider | +| `handover.md` | **Start here after a break**: where the work stands, what is in flight, and how to work in this repository | The framer, at each interruption | — | | `_DISCOVERY_TEMPLATE.md`, `_CHARTER_TEMPLATE.md`, `cycles/_TEMPLATE.md` | The templates | — | — | ```mermaid diff --git a/docs/project/handover.md b/docs/project/handover.md new file mode 100644 index 0000000..0867ca2 --- /dev/null +++ b/docs/project/handover.md @@ -0,0 +1,119 @@ +--- +title: "Handover — where the project stands and how to resume" +updated_on: 2026-09-22 +--- + +# Handover — where the project stands and how to resume + +> Written so a session with no memory of the work can pick it up. Everything below is +> reconstructible from the repository; this file is the map, not the source. Where it +> disagrees with the charter, a cycle, an ADR or a PDR, **those win**. + +## Where the project is, in one paragraph + +flet is a bot that lets a community's administrator offer curated copy trading to its members +on Hyperliquid, taking a flat commission on routed volume and never custody. The discovery is +done and challenged (`go`). Cycle 01 was stopped and reframed. **Cycle 02 runs 2026-09-21 to +2026-10-12**: D1 is `deferred`, D2 is `accepted` and merged, D3 is built and in verification. +The module that matters most — copying — **does not exist yet**, and that is the honest +headline. + +## Repository state + +| | | +|---|---| +| `main` | `9f1135c` — D2 merged (#20), ADR-0002 (#22), pilot FAQ and declared demand (#23) | +| `d3/three-verdicts` | `b41e6f6` — 75 tests, `nstack check` green, **no PR open yet** | +| `pdr/revise-the-pilot-criterion` | `11e1905` — pushed, PR to open | +| `ops/how-we-verify` | this branch — ADR-0003 and this file | + +Older branches are merged or superseded and can be ignored. `nstack doctor` reports compliant; +`nstack plan` and `nstack fitness` are compliant. + +## What is in flight + +**D3 — three verdicts.** `COPYABLE` / `COPYABLE WITH RESERVATIONS (…)` / `NOT COPYABLE (…)`, +exit codes 0/1/2/3 by severity, four reservations (fees, reproducibility, concentration, +extrapolation) and a ceiling past 30× that refuses to answer at all. + +It has been through **six verification rounds**. The last one returned `failed` with three +blockers; all three are fixed at `b41e6f6` and five mutants re-checked as caught, **but that +re-check was done by the author**. What it still needs: + +1. A **confirmation run** by a delegated verifier at the head — not a seventh adversarial + round (ADR-0003 caps `high` modules at one, and this module is long past it). T4 requires + the sheet to be dated at the head commit, and it has refused that argument before. +2. The PR opened with that sheet, signed under the verifier's own agent identifier + (ADR-0002), and the over-budget label with its justification: ~700 lines, indivisible + because every intermediate point is an exit-code scheme that means two things at once. + +## Decisions taken, and where they live + +| Decision | Where | +|---|---| +| Two GitHub identities: the App commits, the token configures | `docs/adr/0001` | +| A delegated session may verify, signing as itself | `docs/adr/0002` | +| Verification budget follows criticality; no unasked change inside a fix | `docs/adr/0003` | +| Commission on routed volume, never a share of gains | `docs/pdr/0001` | +| Three verdicts, four reservations, the extrapolation ceiling | `docs/pdr/0002` + its amendment | +| Closed pilot of 5–8 before any funnel; criterion 1 replaced | `docs/pdr/0003` | +| The read is sized from one probe, and the trade that forces | `modules/screening/docs/adr/0003` | + +## Open, and belonging to the decider + +- **The legal opinion.** Requested, pending. Phase 2 is gated on it. +- **The five (or fifteen) DMs.** Ten traders and twenty members have said they want to test + the bot — *reported*, private, not observed. Nobody has acted. D1 stays `deferred`. +- **`.claude/` project settings and hooks** are untracked and deliberately not gitignored: the + team is meant to share them. They are masked as character devices inside the agent's + sandbox, so the agent cannot read them and will not commit what it has not read. **A human + needs to add them.** + +## Next, in order + +1. Confirmation run on `d3/three-verdicts` → open its PR → merge. +2. Open and merge `pdr/revise-the-pilot-criterion` and `ops/how-we-verify`. +3. **Close cycle 02.** Its closure owes one sentence, already promised: *the project built a + tool for choosing traders with no evidence that any member wants to copy one, and that was + a decision rather than an oversight.* +4. **Upgrade the framework at the cycle boundary, not before.** NapkinStack 0.6.1 exists; + it changes only two `nstack init` error messages and no template file, so it cannot affect + this project mid-cycle. Upgrading the CLI without `nstack update` would turn doctor's L1 + red. Sequence: `uv tool install napkinstack --force`, then `nstack update`, then + `nstack doctor`. **The framework moved 0.3.0 → 0.6.1 in three days: re-check this at every + cycle boundary rather than when someone remembers.** +5. **Frame cycle 03 around the copying module.** It is `critical`. Two things are not + negotiable and they are tests, not process: the agent key can place orders and nothing + else, and revocation works. Two commitments from `pilot-faq.md` must be framed *with* the + module rather than around it: the notice shown **before** a member acts, and revocation as + a first-class path. + +## How to work in this repository + +- **GitHub:** `gh-agent` only — a project hook refuses the direct CLI. The App commits and + pushes; the fine-grained token configures the repository and cannot push. Merging requires + the decider's approval; the agent cannot self-approve. +- **`git config`, remotes:** never `--global`. `GIT_CONFIG_GLOBAL` already points at + `workspace/flet/.gitconfig`, which is workspace-scoped on purpose; `~/.gitconfig` is + untouched and shared with other projects. +- **Mutation testing:** `PYTHONDONTWRITEBYTECODE=1`, clear `__pycache__` between mutants, and + **verify each patch actually applied before reading its result** — a `sed` that silently + matched nothing has already been read as "survived". +- **Exit codes:** measure without a pipe (`cmd >/dev/null 2>&1; echo $?`). A pipe reports the + last command's status and has misled in this project. +- **Live runs** need `allowed_domains` including `api.hyperliquid.xyz`; the venue answers 429 + under repeated hammering, which is itself a scenario. +- **Check gates by their own exit status**, not by a command chained after a `tail`. A gate + whose output is printed and not read is the same as no gate, and that has shipped a failing + commit once. + +## What this project has learned about itself + +Six verification rounds on one read-only function produced eleven real defects. **Three of +them the author introduced in later rounds**, in changes nobody had asked for, and **nine +fixtures written by the author proved nothing** — one of them passing against the very commit +it was written to fail against. + +That is why ADR-0002 exists, why ADR-0003 exists, and why the copying module gets adversarial +verification without a cap while `screening` gets one round. It is not ceremony. It is the +measured behaviour of the thing writing the code.