docs: Slice 0 recorded, and the three rules it leaves behind

The stage table in ROADMAP's Post-1.0 section, plus three entries in CLAUDE.md that
are not derivable from the diff:

- a hand-written fixture that matches the documentation while the code does not is
  worse than none, because it makes a test asserting the right thing prove the wrong
  one — which is exactly how the doubled blocker sentence shipped for two milestones
  under a green `PdPreviewDiff.test.tsx`;
- a sentence assembled in Rust is a sentence the other head assembles again, so
  invariant 4 is not only about translation;
- `sed -i` must never touch `tests/fixtures/`: Git Bash rewrites in text mode and
  strips the CRs that `.gitattributes`' `-text` exists to preserve.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-18 09:05:59 +07:00
1 parent b526d1bf81
commit 0057d5c41e
2 files changed
+75

No files matched your search

+19
View File
@@ -182,6 +182,25 @@ Things worth knowing before you change any of it:
run showed *Back to packages* twice and every suite stayed green. Found by a human using the
installed build. When adding a component test, ask what renders it.
- **A hand-written fixture that matches the docs while the code does not is worse than none.**
`fixtures.rs` says so in its own module doc, and `guard_report()` is computed for that reason —
but the plan fixture's blockers were hand-written to the shape `plan::Blocker`'s doc describes
while `graph::blockers_for` had drifted to building an English sentence. So `PdPreviewDiff`
asserted the *right* sentence and proved nothing, the preview shipped reading `scipy requires
scipy 1.11.4 requires numpy <1.28.0,>=1.21.6` from S3 to 1.1.0, and no suite could see it. If a
fixture's value can be computed by the function that produces it in production, compute it.
- **A sentence assembled in Rust is a sentence the other head assembles again.** That was the
mechanism above: the CLI prints `Blocker.constraint` alone, so building the phrase in core made
the *CLI* look right and left the GUI to wrap it in `plan.blocker` a second time. Invariant 4 is
not only about translation — a joined string cannot be un-joined by a catalog. Structured fields,
one composition per head, as `BrokenDependent`/`PdUninstallDialog` have always done.
- **Never `sed -i` anything under `tests/fixtures/`.** Git Bash's sed rewrites in text mode and
strips every CR, which is exactly what `.gitattributes`' `-text` exists to prevent; one command
flattened ten engine fixtures and reported 160 changed lines where one was intended. Use a
binary-mode read/write and assert the CRLF count per file.
- **A parser that is correct for trusted input is a hole for untrusted input.**
`graph::Requirement::parse` splits the name at the first space, so `this is not a requirement`
parses as package `this` with constraint `is not a requirement` — exactly right for
+56
View File
@@ -810,6 +810,62 @@ a different feature wearing the same word. The PRD row now says so rather than r
`capabilities/external-links.json` — DISCLAIMER §4 and SECURITY §6 both say findings link there,
and the allowlist would reject it silently.
### Slice 0 — preflight before the Security tab — **done 2026-08-18**
Three commits. Nothing here is a feature; all three are things `main` was already carrying, found
while surveying what is left of Post-1.0 (P1-1 Security tab, P1-6 dependency graph, P1-7 scheduled
check). Two of the three had to happen before a 39th command could land anyway.
| | What landed |
|---|---|
| **Fixtures** | `redact()` covers pip's `[notice] A new release of pip is available:` version pair; nine pip fixtures re-blessed; one byte re-blessed in uv's `build-backend-failure` |
| **Core + UI** | `plan::Blocker` becomes `by` / `version` / bare requirement; `run.rs` gains `blocker_line`; `PdConflictRow` composes; `fixtures::numpy_blockers` is **computed**; `PdConflictRow.test.tsx` is new |
| **Docs** | ARCHITECTURE §7's five missing rows, a fourth drift test that reads the table, two stale counts |
**The drift gate could not have stayed green.** pip's upgrade notice states the version that is on
PyPI *today*, so it moves with every pip release — and `redact()` stripped the disposable venv path
out of the line *below* it while leaving this one alone. pip 26.2.1 shipped on 2026-08-17 and the
weekly re-capture failed across all nine pip fixtures carrying the line. The same shape as the five
faults in *L2's first runs*: a gate that fires for a reason unrelated to engine behaviour means
nothing, and this one was going to fire every Monday.
**The preview named the dependent twice, and had since S3.** It rendered `scipy requires scipy
1.11.4 requires numpy <1.28.0,>=1.21.6`, because `graph::blockers_for` built an English sentence
into `Blocker.constraint` while also setting `by`, and `PdConflictRow` passed both to
`plan.blocker`, whose template is `{{by}} requires {{constraint}}`. Hard invariant 4 the wrong way
round — and the reason it was written that way is instructive: the **CLI** prints that field alone,
so the one head it looked right in was the one with no catalog. Each head composes now, exactly as
`BrokenDependent` and `PdUninstallDialog` already did.
**Why every suite was green, which is the part worth keeping.** `PdPreviewDiff.test.tsx` *did*
assert this sentence, and asserted the **correct** one — because the fixture's blockers were
hand-written to the shape `Blocker`'s own doc describes, while the producer had drifted away from
it. `fixtures.rs` says in its own module doc that hand-writing the JSON "would defeat the
guarantee", and `guard_report()` is computed for precisely that reason; the plan fixture's blockers
were the single exception, and the bug lived in it. They are computed now — which is also why there
are two of them: `pandas 2.1.4` and `scipy 1.11.4` both exclude 2.5.1, and only one had ever been
written down. **A hand-written fixture that agrees with the documentation while the code disagrees
with both is worse than no fixture**: it makes a test that asserts the right thing prove the wrong
one.
**Three process notes.**
1. **`sed -i` under Git Bash rewrites in text mode and strips CR.** It flattened every CRLF in ten
engine fixtures in one command — exactly the byte-exactness `.gitattributes`' `-text` exists to
protect, and `git diff --stat` reported 160 changed lines where one was intended. Anything
touching `tests/fixtures/**/*.txt` has to go through a binary-mode read/write, asserting the
CRLF count per file.
2. **ARCHITECTURE §7 now has a test.** Its opening sentence has claimed since M2 that a command not
in the table does not exist; the three drift tests never read it, and `every_registered_command_
is_declared`'s failure message claimed §7 coverage it did not have. *A spec sentence is not a
test* — the fourth time this exact lesson has been recorded here, and the first time on a
sentence about the document itself.
3. **A count was called stale that was not.** ROADMAP's screenshot note says "the seven in
`screenshot/` show an eight-entry sidebar". `screenshot/` holds eight files, so a reader counting
files concludes the sentence is wrong. Opening two of the images settles it: seven predate the
About tab and do show eight entries, and `about.png` shows nine. Reworded rather than
"corrected", because correcting it would have introduced the error.
### Four items decomposed, easiest first
Surveyed 2026-08-14 against the real tree. Ordered by how much already exists, not by value — each