Reduce .reference.yaml to one exemption mechanism and make enforcement claims match the code

Andrew Dunnrequested to merge
exemptions/single-mechanism into main

Standard

conformance-config, renovate, presentation, design. Prose-only edits to license, llms-txt, pipeline, posture-claims and the agents-md template.

Change type

  • Modify existing standard (prose only)
  • Modify existing standard's check.sh (add, remove, or change an assertion)
  • Modify existing standard's templates

What does this MR do and why?

An exemption in .reference.yaml is now standard plus reason, with an optional assertion id, and it means one thing: this standard does not apply to this project. until, owner, resolution, applicable_standards and adoption_phase are removed, along with scripts/audit-expiry.sh, the reference's second register compliance/exemptions.yaml and the script that read it. Two things remain: applies_when_file, which SKIPs where the tree fails a precondition, and exemptions:, for what the code cannot see. The reference's own .reference.yaml is its register, read the same way every consumer's is.

Nothing enforced the date. The one comparator scanned two files whose only until: was 2099-01-01, and the script that acted on the second register never read a date. A date also puts scheduled work in the wrong place: a gap the project intends to close is an issue, and standards/conformance-config/SKILL.md now says so once.

applicable_standards and adoption_phase each had one reader, this standard's own check asserting the key was present. The check recipe runs every standard it finds, no script branches on a phase, and severity comes from the standard's tier. A consumer that wants a FAIL to hold a merge wires a conformance job into its own pipeline.

The mechanism carried five names across route, page, nav label, schema key and register. Exemption is the name, because the schema key and the issue label already used it.

Claims about machinery that does not exist are removed: a pipeline component that checks every run, a reference-check component, a cutover flip on a CHANGELOG date, a draft merge request the reference opens against consumers, and enforcing-status standards blocking merges. standards/registry.yaml is the single source for the Mandatory and Conditional split, and renovate, pipeline and agents-md move to the group their own check.sh puts them in.

Failure mode this addresses

just check REPO=. exited 1 on a conformant repository, and it is the form the README tells a new project to run: each standard runs from inside its own directory, so a relative REPO resolved there. renovate gated on a recursive search for renovate.json and then read the repository root, so a project keeping the file at .gitlab/renovate.json passed the gate and was told the file was missing; the same absent file SKIPped in check_json_key and FAILed in check_file_lacks; and its top-level allowlist omitted dependencyDashboard, a documented per-repository option. presentation rejected every group README carrying its display name (# Public Sector), accepted only the literal alt text hero on the hero embed, and demanded one verbatim tagline across two surfaces with different character budgets. standards/design chose chrome by page shape, and its lab starter used three class names its chrome does not ship, one of which rendered as a stray visible link above the hero.

Assertion deltas

- REMOVE: file-contains:.reference.yaml   regex ^applicable_standards:
- REMOVE: file-contains:.reference.yaml   regex ^adoption_phase: *(report|cutover|enforce)
- MODIFY: file-contains:README.md         H1 regex ^# [a-z0-9][a-z0-9._-]*$  ->  ^# [A-Za-z0-9][A-Za-z0-9 ._-]*$
- MODIFY: file-contains:README.md         hero regex ^!\[hero\]\(hero\.svg\)$  ->  ^!\[.*\]\(hero\.svg\)$
- MODIFY: renovate's three assertions read the path applies_when_file matched, not a literal renovate.json at the repository root
- MODIFY: renovate's top-level allowlist accepts dependencyDashboard

Two changes in _lib.sh, both for renovate: applies_when_file publishes the matched path as $SUBJECT (shallowest match, and the declared glob in describe mode so the generated ## Verify block is stable), and check_json_key and check_toml_key FAIL an absent subject file, as require_file already defines a missing subject. Every standard was run against seven consumer repositories before and after; summaries are identical outside renovate and presentation.

Consumer impact

Breaking for the schema, and no consumer's .reference.yaml needs editing: the removed assertions were presence checks, and nothing forbids an extra key, so a file still carrying until:, owner:, applicable_standards or adoption_phase keeps passing. A consumer holding a dated exemption for a gap it means to close should convert it to an issue.

Against exhibits/the-foundry/anvil, exhibits/the-foundry/gitlab-profile and the namespace gitlab-profile, the H1, hero-embed and renovate findings clear and nothing outside renovate and presentation moves.

Status transition

None.

Test plan

  • just guard passes (assertions use only closed primitives)
  • just check-one STANDARD=<name> passes against this repo for conformance-config, renovate, presentation and design
  • just check REPO=. exits 0 (the command this MR repairs)
  • just validate, just validate-templates, just build and just ship pass
  • Every standard run against seven consumer repositories; the four not under exemption pressure are identical before and after
  • CHANGELOG updated

Reviewer checklist

  • SKILL.md frontmatter is valid YAML (name, description, status, [enforced_since])
  • check.sh sources ../../_lib.sh correctly
  • check.sh calls report at the end
  • Templates/ directory present where applicable
  • Standard appears in README's contracts table
  • Standard appears in the rendered site's /standards/ index

Closes #5 (closed)

Merge request reports