The flowchart's WITHDRAW node (E1) stated that a withdrawal cannot happen
together with a bet in progress. The code only serializes the two *builds*
through the per-user lock: a withdrawal is accepted while a bet is still
unconfirmed, as long as confirmed, unspent UTXOs cover it.
CLAUDE.md makes every node of the diagrams binding, so one of the two had
to move, and it is the diagram. The hazard the node was reaching for is
the two transactions picking the same UTXO, and that is already excluded
twice: app/tx/locks.py keeps the builds from overlapping, and select_utxos
skips anything already marked spent_txid. What the node forbade on top of
that is spending untouched, confirmed money — so implementing it as
written would freeze a user's whole balance for a block after every bet
and protect nothing. E1 now describes the real rule, and CLAUDE.md's
per-user-lock paragraph states it is the only exclusion between the two.
Regenerated the A4/A3 PDFs (gitignored, so not in this commit).
The regression test is behavioural, not a wording check: it funds a user
with two confirmed UTXOs, bets (taking the larger), and asserts the
withdrawal goes through on the other one with the bet still unconfirmed
and neither transaction spending the other's input. A second test keeps
the diagram from drifting back.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
- app/tx/reconcile.py called the payout retry "a future payout-retry
routine — still an open gap". It shipped as B-26: clearing payout_txid
leaves the round in exactly the state _retry_payout_if_due picks up, so
an abandoned payout rebuilds itself and the log line next to it is an
alert, not the recovery path. Reading it the old way, an operator would
go hand-fix a round the scheduler was already retrying.
- app/db/base.py sized the SQLite busy timeout against "five concurrent
background tasks" and then listed only the non-listener ones; the
lifespan starts six.
- The third item (app/auth/routes.py citing B-31 where it meant B-33) was
already correct in the tree; the test pins it so it stays that way.
tests/unit/test_code_comments.py derives the task count from the lifespan's
own create_task calls rather than restating it, so the comment fails the
next time a task is added or removed instead of quietly going stale again.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
CLAUDE.md and README still asserted a state the code had moved past:
- JWT "no revocation (B-34)" — token_version implements exactly that
revocation, and the tv-claim behaviour (including why the deploy did not
log everyone out) is worth stating instead of denying;
- /report-bug "a placeholder" — it shipped fully implemented and
translated, with an admin triage section, a reporter-side status view and
its own audit event; only /guida is still a stub, and /admin has six
sections now, not five;
- three stale test counts (CLAUDE.md twice, README once);
- a code map missing app/auth/rate_limit.py, app/api/client_ip.py and
app/api/routes/bug_reports.py;
- README linking flowchart.mmd (the diagrams live in flowchart/), the
anchor CLAUDE.md#tech-stack-mvp (gone), and describing
docs/running-the-server.md as "local venv vs. Docker" after B-44 made
Docker the only supported way to run the server.
The rate-limiting bullet the audit also flagged already reads correctly.
tests/unit/test_docs_current.py pins all of it: the documented counts must
equal what the suite actually collects, the retired claims must stay
retired, the code map must name those modules, and every relative README
link and CLAUDE.md anchor must resolve. None of this is catchable by
reading the code, which is how it drifted in the first place.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
CLAUDE.md declares the server always runs via Docker (dev and prod
alike) with no supported bare-uvicorn workflow, but README's Quick
start and docs/running-the-server.md's "Locale / venv" section still
documented running uvicorn directly — a leftover from before that
policy was adopted. Rewrite both to a single Docker-only path and
update CLAUDE.md's own note about it.
Verified docker compose run --rm app python scripts/generate_master_key.py
against a real build/run to confirm the Quick start's Docker commands
actually work as documented.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
They enumerate the entire API surface, admin endpoints included, to
anyone who requests them. Gate them behind a new ENABLE_API_DOCS
setting (off by default) and update README/docs and BUGS.md/CLAUDE.md
open-bug counts accordingly.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
CLAUDE.md: bumped the stale test count (54 -> 76), added "Balance display"
and "Real-time updates (SSE)" sections, and rewrote the DRAW section's
frontend-reveal paragraph to describe the actual current behavior (dual
status/result boxes gated by user_played, closes_at-anchored reveal delay,
localStorage persistence, the last-round-result backstop) instead of the
older single-box design. Refined the "no history endpoints" known gap now
that GET /users/me/last-round-result exists (still not general history).
README.md: same test count fix, expanded coverage list.
docs/: fixed a pre-existing broken link in setup.md (admin-guide.md ->
guida-admin.md), added a note in running-the-server.md that editing the
bind-mounted Caddyfile needs an explicit `docker compose restart caddy`
(discovered while adding the SSE Caddy config in a prior change), and
rewrote guida-utente.md's draw/reveal section plus the balance/withdrawal
sections to match what the UI actually does now. guida-admin.md was
reviewed but needed no changes.
app/static/style.css: dropped `.toast.info`, dead since the toast-based
loss notification it styled was replaced by the persistent result box.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Project overview, quick start (local venv and Docker+Caddy), and a
documentation index pointing to CLAUDE.md, flowchart.mmd and docs/ —
none of that existed as an entry point before this.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
davideandClaude Opus 5