Skip to content

docs: fix ASVS vocabulary in CLAUDE.md -- name the subject, not the filing cabinet - #354

Merged
wshallwshall merged 1 commit into
mainfrom
claude/asvs-vocabulary-rule
Aug 12, 2026
Merged

docs: fix ASVS vocabulary in CLAUDE.md -- name the subject, not the filing cabinet#354
wshallwshall merged 1 commit into
mainfrom
claude/asvs-vocabulary-rule

Conversation

@wshallwshall

Copy link
Copy Markdown
Collaborator

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:

  • "vault" names where the RECORD is filed; the SUBJECT being graded is the engine. In practice it sent a reader to look at the vault -- where nothing was wrong -- for a defect living 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 is running.
  • Three stacked nouns, 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, which already existed

Measured before writing, not invented:

term where
ASVS cell 26 vault files, plus public docs/BACKLOG.md and two ADRs; the scorecard TOML is literally [[cell]]
anchor 185 files -- a citation from a cell to a line of engine code
verifier scripts/asvs/scorecard.py, the INSTRUMENT

And 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.md and 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".

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.
@wshallwshall
wshallwshall enabled auto-merge (squash) August 12, 2026 21:23
@wshallwshall
wshallwshall merged commit 9d98f33 into main Aug 12, 2026
32 of 33 checks passed
@wshallwshall
wshallwshall deleted the claude/asvs-vocabulary-rule branch August 12, 2026 21:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant