test(docs): gate the zh-Hant justification on the reason AGENTS.md sanctions

[os-sales]

Fixes #1553

The zh-Hant navigation convention's reason was corrected by #1368 and written into
AGENTS.md:343-345. Reaching the reader took four PRs across two rounds — #1537, #1546,
#1549, #1554 — and the sentence ended up corrected in nine places. Nothing went red at
any point, because nothing in CI reads prose. This adds the gate.

Where the guard lives, and how it avoids the SELF blind spot

New file: test/docs-zh-hant-justification.test.ts. Five tests, no edits to any existing
file.

docs-setup-navigation-names.test.ts scans test/ but filters out SELF, because its
rule 1 bans retired vocabulary and would otherwise fire on its own ledger. That
exemption is why the stale reason survived in it for three days. This file takes no
exemption of any kind — it scans itself — and stays green structurally rather than by
permission:

1. It matches the assertion, not the vocabulary. A passage is judged only when it
   states the convention, and it passes by stating the sanctioned reason. A passage
   quoting the retired form in order to forbid it is therefore either not judged at all, or
   is judged and passes on its merits.
2. Its retired-reason ledger is escaped, following the split
   docs-object-term-consistency.test.ts already uses (live spellings literal, retired
   ones as backslash-u escapes). Measured: the six Chinese retired phrasings appear
   0 times literally in the new file.

The rule pins the claim, not the punctuation: markers are matched wrap-insensitively
over de-commented, emphasis-stripped text, grouped into blocks of adjacent non-empty lines.
All three measured register variants pass unchanged — full stop inside the parens (3
sites), outside it (3 sites), and the short reference/glossary.zh-Hant.mdx form that drops
the trailing clause entirely.

Reverse verification: replayed over the drift's real history

The rule was run over content/docs + src + test + docs at each commit of the
history it exists to catch. It is red for the whole window the drift was invisible, and
green only from #1554:

commit	convention passages	RED
05f867e1^ (before #1537)	7	7
05f867e1 (#1537)	7	7
30f2500e (#1546)	8	7
1efcaaa5^ (before #1549)	8	7
1efcaaa5 (#1549)	9	1
18f523fb^ (before #1554)	9	1
18f523fb (#1554)	9	0
5bfaa8a6 (this branch)	9	0

The last red is the one that matters: at 18f523fb^ the only violation left was the
navigation guard's own file header — the site the SELF filter hid.

Derived vs pinned

The English half is derived. rulebookReason() parses the AGENTS.md bullet and the
first test asserts the English markers are substrings of it, so the rulebook and this file
cannot disagree silently — the next correction to that bullet goes red here, which is
precisely the event this card is about. The derived clause on this tree:

the console falls back to Simplified, so a Traditional page labels platform navigation in
English rather than ship mixed Simplified/Traditional script

The Chinese half cannot be derived: AGENTS.md is English and carries no Traditional
rendering, so those markers are pinned constants citing it. That is the weaker form the
card anticipated, and it is weaker only in the direction of translation — the claim is
still tied to the rulebook through the English markers beside it.

Ablations

All four legs ran commit-first; every restore is proven by state (git diff HEAD
empty and blob hash back to the HEAD value), never by exit code, and every mutation was
confirmed on disk before the rule was read.

• (a) retired sentence reintroduced on a docs page (an insertion, so anchored on the
  injected text and the moved blob hash, never on an unchanged removed-count) — RED:
  a docs page asserts the reason #1368 measured false: content/docs/administration/setup.zh-Hant.mdx carries "介面顯示英文"
• (b) a corrected parenthetical altered so it no longer states the fallback — RED:
  a passage names platform navigation in English without giving the reason AGENTS.md sanctions — the console falls back to Simplified: content/docs/administration/profiles.zh-Hant.mdx :: ...
• (c) the deliberate negation stays GREEN. Proven in two directions rather than
  asserted. Removing only the sanctioned-reason marker from that same comment block,
  leaving the negation byte-identical, turns it RED and names the block — so the rule
  demonstrably reads and judges it. Untouched, with the negation present verbatim, all
  five tests pass. For contrast: a naive vocabulary ban over test/ hits that line (and
  five more occurrences in the new guard's own ledger and header); this rule hits none.
• (d) vacuity. Pointing the scan at a tree that does not exist reds
  the scanned trees read no files — SCANNED_DIRS is wrong: expected 1 to be greater than 400
  while the convention rule itself went green on one file — exactly the "passing by
  reading nothing" state the guard exists for. Detuning the markers instead reds three
  tests, the rulebook anchor first.

Verify

pnpm verify green in full on 5bfaa8a6 — validate, typecheck, lint, lint:i18n-gate,
hygiene, hygiene:tokens, build, test. 160 test files, 3368 passed, 1 skipped. Source
hygiene clean; token ratchet clean (the new file is under test/, outside the ratchet's
src/ surface).

Notes for review

• Roster ledger. The seven pages carrying the note are declared and checked in both
  directions, so a page gaining or losing it reds by name. Four more zh-Hant sites name the Setup app in Chinese with no arrow — a shape all three rules of the navigation guard are structurally unable to see #1538 is in flight on
  content/docs zh-Hant admin/reference pages; if it adds or removes a note, this roster
  wants the matching one-line move.
• Declared limit, stated rather than hidden. The retired-reason sweep reads
  content/docs only — the surface where a hand-written new page is the hazard and where
  nothing ever quotes-to-forbid. Widening it to test/ would need a negation
  discriminator, a heuristic this file deliberately does not carry.
• Out of scope, reported not fixed: six further zh-Hant pages spell English navigation
  paths and carry no justification note at all (18 such paths on
  reference/security-and-compliance.zh-Hant.mdx alone). Whether the convention obliges
  them is a docs question nobody has ruled, so the roster pins what is there rather than
  asserting what ought to be.

🤖 Generated with Claude Code

https://claude.ai/code/session_019hUuCQStzXGMFSX4dzww5t

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
hotcrm	Ignored		Sep 3, 2026 12:15pm UTC