From f2a2e07d3f946b07bb2089237191425855c70a2a Mon Sep 17 00:00:00 2001 From: "napkinstack-agent[bot]" <330339777+napkinstack-agent[bot]@users.noreply.github.com> Date: Tue, 22 Sep 2026 11:32:07 +0200 Subject: [PATCH] Spend verification where the money is, and leave a map for the next session MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two things, both written because the work is being interrupted and a session with no memory of it has to pick it up. ADR-0003 answers the decider's point that too many constraints are a real brake. Cycle 02 spent six independent verification rounds on a read-only module that holds no key and places no order, while the `critical` module has not been started. The budget now follows criticality: one round for `high` and below, adversarial rounds without a cap for anything that moves money. Reading the eleven defects by origin is what made the second rule necessary. Four were in the original implementation; three I introduced in later rounds, in changes nobody asked for; nine fixtures of mine proved nothing. The rounds were not finding a module that resisted being fixed, they were finding a fixer who kept changing more than was asked. So: a fix changes only what the finding names, and anything else becomes a follow-up line. It is free, and it would have prevented three of this cycle's blockers. What the ADR does not reduce: the two things a `critical` module must show, and they are tests rather than process — the agent key places orders and nothing else, and revocation works. `docs/project/handover.md` is the map: where the project stands, what is in flight and what it still needs, where every decision lives, what belongs to the decider, the next steps in order, and the working conventions that are not obvious — gh-agent only, never `git config --global`, mutation work with bytecode writing off and the patch verified as applied before its result is read, exit codes measured without a pipe, and gates checked by their own exit status rather than by a command chained after a `tail`. Each of those is there because it has already gone wrong once here. It is indexed in `docs/project/README.md` so it is found rather than remembered, and it says plainly that where it disagrees with the charter, a cycle, an ADR or a PDR, those win. Agent-Session: session_01NGwPYhV6fYZhjrh41GNfJy Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01NGwPYhV6fYZhjrh41GNfJy --- ...3-spend-verification-where-the-money-is.md | 84 +++++++++++++ docs/adr/README.md | 1 + docs/project/README.md | 1 + docs/project/handover.md | 119 ++++++++++++++++++ 4 files changed, 205 insertions(+) create mode 100644 docs/adr/0003-spend-verification-where-the-money-is.md create mode 100644 docs/project/handover.md 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.