diff --git a/docs/project/charter.md b/docs/project/charter.md index df8bf77..5516173 100644 --- a/docs/project/charter.md +++ b/docs/project/charter.md @@ -34,20 +34,44 @@ Karim's 500-member server is the first one, not the product. ## Success criteria -**1. Twenty members still copying at day 30, on 2026-12-31.** This is the decider's own -stopping rule, and it tests the one claim two independent challenges failed to refute: that a -member copies because someone they know vouched, not because a ranking said so. It is observed -from the members' public addresses on the venue. - -**Recorded honestly, because it is written in the discovery and must not be lost here:** this -criterion decides **interest, not viability**. Twenty copiers produce between 41 € and 671 € a -month at the measured turnover. The decider chose it deliberately over a revenue condition: -the first proof sought is use. - -**2. More than 500 € of commission in a calendar month, before 2027-03-21.** *(framer, to -confirm — it is the restatement proposed for PDR-0001, whose current criterion is unreachable -at the measured turnover.)* This is the one that tests viability. It needs roughly 98,000 € of -member capital under copy. Observed from the builder fee credited on-chain. +**Revised on 2026-09-22 by [PDR-0003](../pdr/0003-prove-the-machine-on-a-few-before-opening-the-tap.md)**, +which replaced a count with evidence of quality and moved the commission criterion behind a +gate. This section states what that decision says; where the two disagree, the PDR wins. It is +written out here because the PDR was merged with this section left as it was, and the open +questions below claimed a revision the criteria above did not carry. + +**Phase 1 — a closed pilot, 5 to 8 members and 2 to 3 traders, before 2026-12-31.** Five +criteria, every one observed rather than asserted: + +1. **Zero unchosen divergence** between the member's position and the vouched trader's: the copy + is faithful, or it refuses and says so. It is the product's whole promise — if it drifts + silently, nothing else counts. +2. **Zero key incident.** The agent key can place orders and nothing else, throughout. A decider + no-go, verified rather than asserted. +3. **Every member revokes at least once, deliberately, and it works.** An exit that has never + been used is not an exit. +4. **At least 60% of members choose to continue past day 14.** The only desire signal a pilot can + honestly produce. +5. **`screening`'s predictions confronted with reality** — fees actually incurred, share of + orders refused, slippage between the trader's fill and the member's. The most valuable of the + five, and only a small pilot produces it: it makes falsifiable everything that module has been + asserting. + +**Why the count went.** The earlier criterion — twenty members still copying at day 30 — was not +excused, it was arithmetically out of reach at pilot size: this project's own binomial model +showed five invitations returning *refuted* **47% of the time while the product was exactly as +good as forecast**. A criterion that fires on noise is worse than none, because it will be +believed. PDR-0003 carries the model. + +**Phase 2 — the acquisition funnel, gated on two conditions**, not one: the written legal opinion +received *and acted on*, **and** every phase-1 criterion met. The funnel may be built meanwhile — +a landing page and a waiting list cost nothing and expose nothing. The tap does not open. + +**The commission criterion lives there now**: more than 500 € in a calendar month, testing +viability, needing roughly 98,000 € of member capital under copy, observed from the builder fee +credited on-chain. **Its date is owed by the decider** — PDR-0003 moved it to phase 2 "with a +later date" and named none, so the old *before 2027-03-21* is not restated here as though it had +survived. See the open questions. ## Constraints @@ -173,6 +197,10 @@ The pilot size is a **launch** parameter. It gates no deliverable and no module. **Previously blocking, answered when this charter was accepted:** the **criticality** (`critical`) and **success criterion 2** (the 500 € restatement proposed for PDR-0001). +**Owed by the decider, since 2026-09-22:** the **date** on the phase-2 commission criterion. +PDR-0003 moved it there "with a later date" and named none. Until it has one, the project has a +viability criterion with no deadline, which is a criterion that cannot fail. + **Not blocking:** - The written legal opinion, requested and pending. diff --git a/docs/project/cycles/02-make-the-answer-trustworthy.md b/docs/project/cycles/02-make-the-answer-trustworthy.md index 74939d2..590bf39 100644 --- a/docs/project/cycles/02-make-the-answer-trustworthy.md +++ b/docs/project/cycles/02-make-the-answer-trustworthy.md @@ -1,6 +1,6 @@ --- goal: "Find out whether vouching moves anyone, and make the screening answer one an administrator can act on" -status: accepted +status: closed appetite_weeks: 3 start: 2026-09-21 end: 2026-10-12 @@ -26,7 +26,7 @@ deliverables: - id: D3 title: "Three verdicts instead of two, so the headline cannot say yes to a trader the answer is warning about" module: screening - state: ready + state: accepted acceptance: - "Given a trader who clears the floor and trips no reservation, when the command runs, then the verdict is COPYABLE and the exit code is 0" - "Given a trader who clears the floor with a fee burden above the alert, when the command runs, then the verdict is COPYABLE WITH RESERVATIONS, the fee reservation is named on the first line, and the exit code is 1" @@ -34,6 +34,8 @@ deliverables: - "Given a trader who clears the floor whose volume landed on a third or less of the days, when the command runs, then the verdict is COPYABLE WITH RESERVATIONS and the concentration reservation is named" - "Given a trader who does not clear the floor, when the command runs, then the verdict is NOT COPYABLE and the exit code is 2, whatever the reservations say" - "Given the venue cannot be read, when the command runs, then the verdict is NO VERDICT and the exit code is 3" +outcome: shipped +ended_on: 2026-09-23 --- # Cycle 02 — Make the answer trustworthy @@ -151,4 +153,107 @@ copy a trader, and that this was a decision rather than an oversight. ## Closure - +**Closed on 2026-09-23, on day 3 of a 21-day appetite, with two deliverables accepted and one +never started.** + +`shipped`, not `completed`: `completed` would claim every deliverable was accepted, and D1 was +not. Nor is this the circuit breaker — the end date was 19 days away. The decider closed early +because everything this cycle could do with engineering was done, and the one thing left is not +engineering. + +## What was delivered + +**D2 — the window read. Accepted (#20).** The venue answers ascending and caps a page, so paging +forward from thirty days back spent the budget on the oldest fills and died before reaching the +present: live, it returned a window ending eleven days before the question. The read now walks +backwards from now, sized from one cheap probe. The window ends at the moment of the run — +measured at 0 ms — and a sparse trader costs zero heavy reads where a dense one costs 20 of a +20 budget. This is the S8 failure that stopped cycle 01, closed. + +**D3 — three verdicts. Accepted (#26).** `COPYABLE` / `COPYABLE WITH RESERVATIONS (…)` / +`NOT COPYABLE (…)` / no verdict, exit codes 0/1/2/3 by severity, four reservations named in the +headline, and a ceiling that refuses to answer at all past 30× rather than printing an inference +as a fact. Its six acceptance criteria were verified at the head commit by a delegated session +that had refused the branch five times. + +**D1 — five private invitations. Deferred, for the second cycle running.** Nobody has been asked. +Ten traders and twenty members are *reported* as wanting to test the bot; that is private, +declarative, and nobody has acted. The cost of this deliverable is five messages and fourteen +days of waiting, and it has now not been paid twice. + +**Not in the deliverables, and worth more than one of them:** ADR-0002 (a delegated session may +verify and signs as itself), ADR-0003 (the verification budget follows criticality; no unasked +change inside a fix), PDR-0002 accepted with four amendments, PDR-0003 (a closed pilot before any +funnel), and `handover.md`, which is why a session with no memory could pick this up at all. + +## Which success criteria moved + +**Neither. Not one.** + +The charter's criteria, as PDR-0003 revised them, are five phase-1 conditions about a closed +pilot: faithful copying, zero key incident, revocation that works, 60% continuing past day 14, and +`screening`'s predictions confronted with reality. **Every one of them needs the copying module, +which does not exist.** The fifth is the only one this cycle touched, and only by making it +possible: the module now states a fee burden, a refused share and a reproducible share precisely +enough to be *wrong*. Nothing has confronted them with a member's actual fills, because no member +has any. + +**The sentence this closure owes, promised in advance when the cycle was framed:** 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. It was offered one week on D1 alone, two on D1 and the window +fix, or three on everything; it chose three on everything, and was told at the time that the third +option had the same shape as cycle 01. It did not repeat cycle 01 — both engineering deliverables +landed, in three days. It repeated the other half: **the deliverable that was somebody else's +calendar did not move, and 19 days of appetite are unspent because the appetite was sized for work +cycle 01 had already done.** + +## What this cycle cost, measured + +D3 alone took **six adversarial rounds and six confirmation runs**. Eleven real defects in the +rounds; **five refusals** in the confirmations, every one correct. The distribution is the finding: + +| Origin | Count | +|---|---| +| Defects in the original implementation | 4 | +| Defects the author introduced in later rounds, in changes nobody asked for | 3 | +| Refusals over a **sentence** in the decision record rather than over code | 3 | + +The first blocker survived six rounds for a reason that should be read twice: **all 20 `main(...)` +calls in the suite passed `client=`**, so the one line an administrator's own invocation runs was +exercised by no test. Seventy-five green tests were green on a path nobody takes. + +What ended the sequence was not another fix. The guarantees in PDR-0002 gained one sentence above +all three — *they speak about what the command chooses to write* — which closed a family instead of +an instance, and the verifier then bounded it: two write sites, enumerated statically and +confirmed by instrumenting 18 paths. **A per-instance clause produces one refusal per round; a +class-level one ends the round.** That is the transferable lesson of this cycle and it belongs in +the next one. + +## What was deferred, and why + +- **D1**, unchanged and now urgent rather than merely owed. It gates the charter's whole phase 1. +- **Ten follow-ups on `screening`**, listed in #26. The ones that matter: input validation is now + load-bearing for two of PDR-0002's caveats, and the thresholds' calibration — a headline saying + `COPYABLE` over a body warning that 20% of orders cannot be placed — belongs with the PDR's own + success-criterion review. +- **Observability**, carried from cycle 01 for the second time: no retry-rate metric, the 429 + deviation unrecorded, and a 60-second budget that is per call where one invocation makes several. +- **The phase-2 date** on the commission criterion, owed by the decider since PDR-0003 moved it + "with a later date" and named none. Recorded in the charter's open questions. +- **`.claude/` project settings and hooks**, untracked and deliberately not gitignored. They are + masked as character devices inside the agent's sandbox, so no agent can read them or commit what + it has not read. A human has to add them. + +## Where the next framing starts + +**With the copying module, and with the honest reading above rather than with this backlog.** + +It is `critical`: it holds a key and moves a member's money. Two things are not negotiable there +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. + +And D1 belongs on day one again, for the third time, because the alternative is to build a +`critical` module for a demand nobody has observed. Cycle 01 was told this. Cycle 02 was told this +and chose otherwise, with the reason recorded. If cycle 03 defers it again, that is the project's +answer about what it is really doing, and it should be written down as plainly as this. diff --git a/docs/project/handover.md b/docs/project/handover.md index 0867ca2..8e2d137 100644 --- a/docs/project/handover.md +++ b/docs/project/handover.md @@ -1,6 +1,6 @@ --- title: "Handover — where the project stands and how to resume" -updated_on: 2026-09-22 +updated_on: 2026-09-23 --- # Handover — where the project stands and how to resume @@ -11,41 +11,41 @@ updated_on: 2026-09-22 ## 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. +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 closed `shipped` on +2026-09-23** with D2 and D3 accepted and D1 never started. The `screening` module answers whether +a trader is copyable, in three verdicts with four exit codes, and it is merged. **The module that +matters most — `copying` — does not exist, no member has been asked whether they want any of this, +and neither of the charter's success criteria has moved.** That is the honest headline, and the +closure of cycle 02 says it at more length. ## 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 | +| `main` | `8277dca` — D2 (#20), ADR-0002 (#22), the pilot FAQ and declared demand (#23), PDR-0003 and the revised criterion (#24), ADR-0003 and this file (#25), D3 (#26) | +| In flight | **nothing.** No open pull request, no branch awaiting a sheet | +| `screening` | 81 tests, `nstack check` 0, `nstack fitness` compliant, verified on `main` | -Older branches are merged or superseded and can be ignored. `nstack doctor` reports compliant; -`nstack plan` and `nstack fitness` are compliant. +Older branches are merged or superseded and can be ignored. `nstack doctor` reports 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: +## Next, in order -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. +1. **Frame cycle 03 around the `copying` module** — the closure of cycle 02 says where the framing + starts. 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` are framed *with* the module, not around it: the notice shown **before** a member + acts, and revocation as a first-class path. Framing is `playbooks/framing.md`, with the decider; + a cycle is `proposed` until the decider accepts it in its own pull request. +2. **D1 on day one, for the third time.** Five private messages and a fourteen-day clock. It has + been deferred by two cycles, it gates every phase-1 criterion in the charter, and the + alternative is building a `critical` module for a demand nobody has observed. +3. **Upgrade NapkinStack at this cycle boundary, before cycle 03 is accepted.** 0.6.1 exists; the + project is recorded at 0.6.0. Sequence, and only in this order: `uv tool install napkinstack + --force`, then `nstack update` (it makes the branch `nstack/update-vX.Y.Z`), then `nstack + doctor`. Upgrading the CLI without `nstack update` turns doctor's L1 red. **The framework moved + 0.3.0 to 0.6.1 in three days: re-check at every boundary rather than when someone remembers.** ## Decisions taken, and where they live @@ -55,65 +55,71 @@ re-check was done by the author**. What it still needs: | 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` | +| Three verdicts, four reservations, the extrapolation ceiling — and four amendments | `docs/pdr/0002` | +| A closed pilot of 5–8 before any funnel; the count criterion replaced | `docs/pdr/0003` | | The read is sized from one probe, and the trade that forces | `modules/screening/docs/adr/0003` | +**If the hook's "ADR-0004" confuses you, read `docs/adr/0001` before assuming it is missing.** The +hook that refuses a direct GitHub CLI call cites **NapkinStack's** ADR-0004, not this project's; +`docs/adr/` here stops at 0003 and that is correct. This project's ADR-0001 names it, explains the +mechanism it enforces — a token minted per call, one hour, never on disk — and builds on it. The +session that wrote this line briefly recorded it as a missing decision, which it is not. + ## 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. +- **The five DMs.** Ten traders and twenty members are *reported* as wanting to test the bot — + private, declarative, nobody has acted. D1 stays `deferred`. +- **The phase-2 date** on the commission criterion. PDR-0003 moved it there "with a later date" and + named none, so the project currently has a viability criterion that cannot fail. In the charter's + open questions. +- **`.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.** ## 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. +- **GitHub:** the agent CLI wrapper only — a project hook refuses the direct one. 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. **A push dismisses an existing approval** + (the ruleset says so), while editing a pull request's description re-runs the description checks + on the same head and leaves the approval standing — so put the test sheet in last. +- **That hook matches the command text, not the process invoked.** A heredoc that merely mentions + the forbidden command name is refused too. Write such a file with an editing tool instead of a + shell redirection. - **`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. + `workspace/flet/.gitconfig`, which is workspace-scoped on purpose. +- **Reading a CI log needs a writable cache**: `XDG_CACHE_HOME="$TMPDIR"`, or it fails on a + read-only `~/.cache`. +- **Check gates by their own exit status**, never by a command chained after a `tail`, and never + read an exit code through a pipe — `cmd >log 2>&1; echo $?`. Both mistakes have shipped a failing + commit here, and one of them recurred in the session that wrote this line. +- **A live venue run** needs `allowed_domains` including `api.hyperliquid.xyz`. Watch which side of + that you are on: with egress denied the command takes its no-verdict path, which is a different + measurement from a real answer, and confusing the two has already produced a wrong reading. - **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. + verify each patch actually applied before reading its result. +- **T4 costs a re-measurement.** Every sheet row carries the head commit, so any commit — including + one that touches no module file — invalidates the whole sheet. Three of cycle 02's six + confirmation runs were spent re-measuring 30-odd rows after a documentation-only commit. Land the + prose before asking for the sheet. ## 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. +**Six adversarial rounds and six confirmation runs on one read-only module produced eleven real +defects and five refusals.** Three of the defects the author introduced in later rounds, inside +changes nobody had asked for. Three of the refusals were not about code at all: they were sentences +in a decision record asserting more than the code does. + +Two things came out of that and they are worth carrying rather than re-deriving: + +1. **A class closes; an instance does not.** Four refusals were spent on clauses that fixed the + case just found. The one sentence that ended the sequence generalised — *the guarantees speak + about what the command chooses to write* — and the verifier then bounded it by enumerating the + two write sites. Write the general form first. +2. **A delegated verifier has no session identifier of its own.** `CLAUDE_CODE_SESSION_ID` in its + shell is the parent's — the same value every `Agent-Session` trailer carries — so T2 cannot + detect that a verifier is a child of the session that wrote the code. Each run established its + identity from the harness's subagent records and said so unprompted. ADR-0002 records this as + owed; the mitigation is social, and it worked here only because the briefs asked for failure and + the verifier refused five heads.