From df568842d85a49da7840e9228ac25e2af708170d Mon Sep 17 00:00:00 2001 From: Adam Clemens Date: Sat, 29 Aug 2026 22:12:01 +0100 Subject: [PATCH] Fix two stale CLAUDE.md claims the Stage 5 exit audit's own sweep missed Criterion 10 had eight stale claims, not the six recorded in Stage 5's status table. Both misses are the exact class that audit was about, and both are recorded in the files themselves rather than quietly corrected. planning/CLAUDE.md called docs/planning/releases.md "a sustained argument that PyFlow should not have a release process yet" and data/releases.yaml an empty file "correct rather than incomplete". Both stopped being true when reaching the MVP fired that document's own trigger. The audit grepped for "no release process"; this paragraph says "should not have a release process yet" -- the same claim in words the pattern did not match. docs/architecture/CLAUDE.md still anchored sequences.md's checkpointing placeholder to "the specific roadmap task that will build it (TASK-034)". The audit re-anchored sequences.md and did not re-read its companion CLAUDE.md in the same change -- a one-file-deep sweep, immediately after writing a rule against exactly that. TASK-034 landed without building checkpointing, which Stage 5 Criterion 4 explicitly allows, so the placeholder stayed accurate while its anchor pointed at a closed task. Swept every other CLAUDE.md for the same class; nothing further found. Co-Authored-By: Claude Opus 5 --- docs/architecture/CLAUDE.md | 33 ++++++++++++++++++++++++--------- planning/CLAUDE.md | 22 +++++++++++++++++----- 2 files changed, 41 insertions(+), 14 deletions(-) diff --git a/docs/architecture/CLAUDE.md b/docs/architecture/CLAUDE.md index 3f0dfa7..814718e 100644 --- a/docs/architecture/CLAUDE.md +++ b/docs/architecture/CLAUDE.md @@ -32,15 +32,30 @@ anything beyond orientation. **One of its four sections still carries a `Planned` subsection for a mechanism that doesn't exist yet** (checkpointing simulation state, -Section 3) -- anchored to the specific roadmap task that will build it -(TASK-034) rather than left open-ended, per the maintainer's direction -that an unbuilt piece gets a placeholder and a backlog anchor, not -silence or a fabricated mechanism. That task's own `docs/planning/ -roadmap.md` entry carries a matching note asking for `sequences.md` to -be updated in the same change that lands it -- check the note still -agrees with reality whenever that task is touched, the same "a diagram -makes claims too" discipline this directory already applies to -`overview.md`'s system diagram (below). +Section 3), per the maintainer's direction that an unbuilt piece gets a +placeholder and a backlog anchor, not silence or a fabricated mechanism. + +**Its anchor is no longer a task, and how that happened is the useful +part.** This paragraph used to say the subsection was "anchored to the +specific roadmap task that will build it (TASK-034)", with that task's +own roadmap entry carrying a matching note asking for `sequences.md` to +be updated in the same change. **TASK-034 landed on 2026-08-29 and +deliberately did not build checkpointing** -- Stage 5 Completion +Criterion 4 excludes it in as many words -- so the placeholder stayed +accurate while its anchor pointed at a closed task, and the same pass +left `sequences.md` with no sequence for `navier_stokes_step`, which is +what TASK-034 *did* build. A task anchor does not cover "the task landed +but did not build the thing" (`docs/practices.md`, "A checkable trigger +still needs somebody to check it"). The subsection now says plainly that +no task is assigned; whoever writes one re-reads it in the same change. + +Check that note still agrees with reality whenever any task named in +`sequences.md` is touched -- the same "a diagram makes claims too" +discipline this directory already applies to `overview.md`'s system +diagram (below), and **a discipline this file itself failed**: the Stage +5 exit audit re-anchored `sequences.md` and did not re-read this +companion paragraph in the same change, which is the exact +one-file-deep sweep it had just written a rule against. **Section 2's own `Planned` subsection (driving `simulation.step()` from a live render loop) was replaced with the real, built sequence 2026-08-28 diff --git a/planning/CLAUDE.md b/planning/CLAUDE.md index b10fc77..dcb35af 100644 --- a/planning/CLAUDE.md +++ b/planning/CLAUDE.md @@ -54,11 +54,23 @@ each one, so a list in this paragraph would be a second, unchecked copy of it. Whichever are still unpopulated are so on purpose, each with a stated -trigger in `model/entities.yaml` -- `data/releases.yaml` most -explicitly, since -`docs/planning/releases.md` is a sustained argument that PyFlow should -not have a release process yet, and an empty file matching a documented -deliberate absence is correct rather than incomplete. +trigger in `model/entities.yaml`, and an empty file matching a +documented deliberate absence is correct rather than incomplete. + +**`data/releases.yaml` used to be this paragraph's own worked example of +that, and is now the worked example of the trigger firing.** It read +"`data/releases.yaml` most explicitly, since `docs/planning/releases.md` +is a sustained argument that PyFlow should not have a release process +yet". That stopped being true on 2026-08-29, when reaching the MVP fired +one of `releases.md`'s own three recorded triggers, that document was +rewritten with a real process, and this file was populated with PyFlow +0.1.0. Worth keeping rather than smoothing over: the trigger mechanism +worked, and **this sentence was still missed by the Stage 5 exit audit's +own documentation sweep** -- it greps for "no release process" and this +paragraph says "should not have a release process yet", which is the +same claim in words the grep did not match (`docs/practices.md`, "A +stage's documentation sweep is a grep, not a diff review", whose limits +this is an instance of). These files are exempt from the repository's usual "no empty tracked file" rule (`docs/planning/backlog.md` A3) -- they're data, not prose.