From cd668cfd4b5d6db982d9343c8cb798221bc88eb2 Mon Sep 17 00:00:00 2001 From: wshallwshall Date: Wed, 12 Aug 2026 16:22:00 -0500 Subject: [PATCH] docs: fix ASVS vocabulary -- name the subject, not the filing cabinet I coined "vault gate cell" in conversation on 2026-08-12 and it was wrong on every axis, so this records the correct terms beside the "shard" rule it structurally matches. Both are the same defect: an unqualified compound that sends a reader to the wrong thing. Why that phrase failed: - "vault" names where the RECORD is filed; the SUBJECT being graded is the engine. It sent a reader to look at the vault, where nothing was wrong, for a defect in engine code. - "gate" is the CI job. Fusing it with "cell" implies a cell is a gate-thing; cells exist whether or not any job runs. - three stacked nouns with no relation marked -- a cell of the vault-gate, or a gate-cell in the vault? Unparseable without someone standing there explaining it. - it invents a CATEGORY for what is only a STATE. A failing cell is an ordinary cell whose anchor went stale. The correct terms are the project's own, measured before writing: "ASVS cell" appears in 26 vault files and publicly in docs/BACKLOG.md and two ADRs; "anchor" in 185; the scorecard TOML is literally [[cell]]. Also recorded: verifier-drift and stale-anchors are different failures with adjacent names, and the distinction is load-bearing -- instrument drift once made the gate not run at all on every matching PR. SAFE TO STATE PUBLICLY, checked rather than assumed: ASVS appears 516 times in the public docs/BACKLOG.md and in 397 public files, "ASVS cell" is already public, and ADR 0156 is public. The vocabulary is not the secret; the coverage map is, and this adds none of it. --- CLAUDE.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index a627b8af..c342c43c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -533,6 +533,24 @@ harness process only.) ([ADR 0039](docs/adr/0039-database-tier-sharding-l5.md), L5 — **shelved**). The two axes are different (e.g. "cross-shard reads span K stores" is true only of *database* shards; *engine* shards share one store), and conflating them causes real errors. +- **ASVS vocabulary: the SUBJECT is the engine, and the record lives elsewhere — never let the storage + location name the thing.** An **ASVS cell** is one requirement's graded row (verdict + reasoning + + citations; the scorecard is literally `[[cell]]`). An **anchor** is a citation from a cell to a line + of engine code. The **verifier** is `scripts/asvs/scorecard.py` — the INSTRUMENT, not the record. + When a cell's anchor points at code that has moved or gone, say **"the cell has a stale anchor"**: + the engine is not insecure and the vault is not broken, the *evidence* went stale — usually + **because the code got better and the fix deleted the line the anchor quoted**. + - **Never say "vault cell", "gate cell", or "vault gate cell".** All three name the filing cabinet + instead of the subject, and the third also fuses the checker with the checked — a cell exists + whether or not any job is running. Measured 2026-08-12: that phrasing sent a reader looking at the + vault, where nothing was wrong, for a defect that lived in engine code. + - **Keep "verifier" and "verification" apart.** *Verifier drift* = a copy of the tool differs from + the engine's. *Stale anchors* = the evidence moved. Different failures with adjacent names; the + gate's own comment says the two "are easy to confuse", and instrument drift once made the gate + **not run at all** on every matching pull request. + - **The VOCABULARY is public; the CONTENT is not.** Cell ids, coverage and gaps stay vaulted — a + path-to-cell map enumerates what IS covered over a closed public domain, so it hands out what is + NOT by subtraction. Naming the terms discloses nothing; pasting the scorecard does. **Don't** - Don't manipulate HL7 with raw string slicing.