Skip to content

Enforce the glossary's _Avoid_ lists with a check, instead of a reviewer's attention #197

Description

@jacobdrees

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.mdDomain 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.mdLanguage 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.mdThe 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

  • The check parses CONTEXT.md rather than carrying its own copy of the vocabulary, so the
    glossary keeps one home.
  • It is scoped per concept, and the design note says how it decides a word is used for the
    concept it is listed against rather than for another.
  • Proper names of Orderings pass, per the exemption already in CONTEXT.md.
  • The three known violations above are fixed, or exempted with the reason recorded where the
    exemption lives rather than in the script.
  • Tested at both seams the repo already uses: the pure functions in scripts/lib/doc-checks.ts,
    and one fixture case in scripts/check-docs.test.ts proving a violating document exits
    non-zero.
  • docs/agents/workflow.mdThe gates names the new check and where it gates.
  • The check runs green on the tree as it stands.

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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions