What to build
A scripts/check-docs.ts check that reads CONTEXT.md's own _Avoid_ lists and fails when a
tracked document uses one of those words for the concept it is listed against.
Today that rule is enforced only by a reviewer's attention.
CODING_STANDARDS.md → Domain language makes it a finding, and docs/agents/workflow.md →
What a merge carries says to prefer an executable check over prose, because "a rule that lives
only in prose is one nobody re-reads at the moment it is broken". The glossary is the largest rule
here still living only in prose.
CAN-75 Write the four missing ADRs and fix the glossary's self-violations
fixed the violations inside CONTEXT.md itself and added the exemption this check needs.
Why it is not a small build
The hard part is per-concept scoping, not matching. _Avoid_ is a list per term, not a banned
word list. "Collection" is forbidden for Catalogue and correct for "a media collection". A check
that flags every occurrence would be noise and would be turned off.
A proper name is exempt, and the exemption is already written. CONTEXT.md → Language records
it: an Ordering called "Broadcast order" is written as it is called, even though order is on the
Ordering list. Any implementation has to honour that or it fails on the glossary's own examples.
Three known violations would make it red on arrival. These were found by the 12–13 August audit
and deliberately left open by CAN-75 Write the four missing ADRs and fix the glossary's self-violations Write the four missing ADRs and fix the glossary's
self-violations, which scoped itself to CONTEXT.md:
- ADR-0012's title uses
works, which is on Story's list.
- ADR-0003 leans on
alias, which is on Merge's list.
- "Canonical" is used in three senses across the ADRs while Validity bans it, worst at ADR-0009's
"broadcast order is the canonical episode set".
A gate that is red on arrival is a gate that gets ignored, which is the reasoning
docs/agents/workflow.md → The gates already gives for pnpm audit's high threshold. So the
three have to be resolved, or explicitly exempted with a recorded reason, in the same change.
Acceptance criteria
Prior art in this repo
Eight checks already follow this shape. The closest is the one CAN-75 Write the four missing ADRs and fix the glossary's self-violations added for CLAUDE.md's line
target: the number is read from the document it gates rather than written into the script, and the
check fails rather than skips because a tracked file is always reachable.
What to build
A
scripts/check-docs.tscheck that readsCONTEXT.md's own_Avoid_lists and fails when atracked document uses one of those words for the concept it is listed against.
Today that rule is enforced only by a reviewer's attention.
CODING_STANDARDS.md→ Domain language makes it a finding, anddocs/agents/workflow.md→What a merge carries says to prefer an executable check over prose, because "a rule that lives
only in prose is one nobody re-reads at the moment it is broken". The glossary is the largest rule
here still living only in prose.
CAN-75 Write the four missing ADRs and fix the glossary's self-violations
fixed the violations inside
CONTEXT.mditself and added the exemption this check needs.Why it is not a small build
The hard part is per-concept scoping, not matching.
_Avoid_is a list per term, not a bannedword list. "Collection" is forbidden for Catalogue and correct for "a media collection". A check
that flags every occurrence would be noise and would be turned off.
A proper name is exempt, and the exemption is already written.
CONTEXT.md→ Language recordsit: an Ordering called "Broadcast order" is written as it is called, even though
orderis on theOrdering list. Any implementation has to honour that or it fails on the glossary's own examples.
Three known violations would make it red on arrival. These were found by the 12–13 August audit
and deliberately left open by CAN-75 Write the four missing ADRs and fix the glossary's self-violations Write the four missing ADRs and fix the glossary's
self-violations, which scoped itself to
CONTEXT.md:works, which is on Story's list.alias, which is on Merge's list."broadcast order is the canonical episode set".
A gate that is red on arrival is a gate that gets ignored, which is the reasoning
docs/agents/workflow.md→ The gates already gives forpnpm audit'shighthreshold. So thethree have to be resolved, or explicitly exempted with a recorded reason, in the same change.
Acceptance criteria
CONTEXT.mdrather than carrying its own copy of the vocabulary, so theglossary keeps one home.
concept it is listed against rather than for another.
CONTEXT.md.exemption lives rather than in the script.
scripts/lib/doc-checks.ts,and one fixture case in
scripts/check-docs.test.tsproving a violating document exitsnon-zero.
docs/agents/workflow.md→ The gates names the new check and where it gates.Prior art in this repo
Eight checks already follow this shape. The closest is the one CAN-75 Write the four missing ADRs and fix the glossary's self-violations added for
CLAUDE.md's linetarget: the number is read from the document it gates rather than written into the script, and the
check fails rather than skips because a tracked file is always reachable.