docs: fix ASVS vocabulary in CLAUDE.md -- name the subject, not the filing cabinet - #354
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs-only, 18 lines added to CLAUDE.md section 12, beside the
"shard"rule it structurally matches. Both are the same defect: an unqualified compound that sends the reader to the wrong thing.What prompted it
I coined "vault gate cell" in conversation on 2026-08-12. It was wrong on every axis:
The correct terms, which already existed
Measured before writing, not invented:
docs/BACKLOG.mdand two ADRs; the scorecard TOML is literally[[cell]]scripts/asvs/scorecard.py, the INSTRUMENTAnd the phrasing for the failure: "the cell has a stale anchor" -- because the engine is not insecure and the vault is not broken; the evidence moved, usually because the code got better and the fix deleted the line the anchor quoted.
Also recorded: two adjacent names that are different failures
Verifier drift (a copy of the tool differs from the engine's) and stale anchors (the evidence moved) are distinct, and the distinction is load-bearing -- 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 PR.
Public-safety, checked rather than assumed
ASVS appears 516 times in the public
docs/BACKLOG.mdand in 397 public files; "ASVS cell" is already public; ADR 0156 is public. The vocabulary is not the secret -- the coverage map is, and this adds none of it. The rule says so explicitly, so nobody later reads "ASVS terms are fine in public" as "the scorecard is fine in public".