spec citations: five named sections their SPECs do not have, and a check so they cannot return #238

Merged

dcharlot merged 2 commits from dcharlot/spec-citations-resolve into main 2026-10-13 09:36:22 -04:00 AGit

Conversation 0 Commits 2 Files changed 8 +216 -5

dcharlot commented 2026-10-13 03:07:25 -04:00

Owner

Copy link

Checked every SPEC citation in the tree against the headings of the SPEC.md beside it: 1454 citations across 15 standards, five dangling. None of the rules was missing - aac's is §3 item 3 / §3.1, sandbox's two are in spec/receipts.md and spec/build.md - so the citations now point where the rules are. Second commit adds scripts/check-spec-refs.py with a self-test asserting it can fail four ways, and an unfiltered workflow. Same family as #190. Both workspaces check clean.

Checked every SPEC citation in the tree against the headings of the SPEC.md beside it: 1454 citations across 15 standards, five dangling. None of the rules was missing - aac's is §3 item 3 / §3.1, sandbox's two are in spec/receipts.md and spec/build.md - so the citations now point where the rules are. Second commit adds scripts/check-spec-refs.py with a self-test asserting it can fail four ways, and an unfiltered workflow. Same family as #190. Both workspaces check clean.

dcharlot added 2 commits 2026-10-13 03:07:25 -04:00

aac, sandbox: five citations named sections their SPECs do not have ... 560c3e58fa

Code cites normative text to say which rule it enforces. These five cited
sections that do not exist, so the citation read as authority it did not have.
None of the rules was missing — every one is written down, just not where the
code said:

  aac §3.3 (3 sites)  the rule is §3 item 3 ("rendering its cell as visually
                      inactive **in place**") and §3.1 item 3 ("MUST keep its
                      position and MUST be rendered as visually inactive and
                      not selectable"). aac/SPEC.md has §3 and §3.1 and no
                      §3.2 or §3.3, and the SPEC's own cross-references
                      already use the form this commit adopts — line 54 reads
                      "(§3 item 3, §3.1)".

  sandbox §6.5        the receipt's storage line is `spec/receipts.md`:
                      "Storage activity is its own line … it does **not** enter
                      the per-device-class energy sum of §6.2". §6 has 6.1-6.4.

  sandbox §12.1       the deterministic-first cascade is `spec/build.md`, under
                      "## Deterministic-first (the cascade)". §12 exists and
                      records the tier in the build receipt, but has no
                      subsections.

So each citation now points where the rule actually is. Sections of a
`spec/*.md` subfile are not sections of `SPEC.md`, and are cited by file name.

Found by checking every `SPEC §N` in the tree against the headings of the
SPEC.md beside it — 1454 citations across 15 standards, and these five were
the only ones that did not resolve. The commit after this one makes that a
check, because all three were written long before anyone read them. The same
family as #190, where `jcp-runtime` cited `SPEC §4.10` in six places and
§4.10 did not exist.

Both workspaces check clean with `--all-targets`.

Co-Authored-By: Claude Opus 5 <[email protected]>

ci: a citation to a section that does not exist is now a failure ... 4b05fd80e1

The commit before this fixed five of them. They were written long before
anyone read them, and the one in #190 — `jcp-runtime` citing `SPEC §4.10` in
six places, with no §4.10 — survived a gate-enforcing, tested mechanism for
months. Reading the tree once finds these; reading it every time is a check.

`scripts/check-spec-refs.py` resolves every `SPEC §N` in a standard's `*.rs`
against the numbered headings of the `SPEC.md` beside it. 1454 citations
across 15 standards resolve today.

Three decisions worth stating, because each is a way the check could have been
written to find nothing:

  - Parents are not synthesised. A cited `§4` needs its own `§4` heading; a
    `§4.10` heading does not satisfy it. Otherwise a standard citing a section
    it never wrote is excused by a child it happens to have.
  - A citation resolves against the SPEC.md of its own directory. Every
    cross-standard citation in the tree today is a self-reference that names
    its standard for the reader ("JouleClaw SPEC §1.3", inside jouleclaw/), so
    this is right for all of them; the header says what to do instead if that
    ever stops being true, rather than loosening the check.
  - Sections of a `spec/*.md` subfile are not sections of `SPEC.md`.

The self-test asserts the check can fail, in the four ways that matter: an
unresolvable citation fails, both heading spellings (`## 4.` and `## §4`) are
accepted, a child heading does not satisfy its parent, and one standard's
section does not excuse another's citation. A regex that quietly stops matching
would otherwise find nothing and exit 0 — the failure mode this repo has
already met in gated and skipped tests.

The workflow carries no `paths:` filter, deliberately. The check is a second of
Python with no toolchain, and a correct filter would have to name every
standard's `**/*.rs` and every `SPEC.md`; `standards-build.yml` records that
`**`-prefixed globs do not match on this forge and that a gate which quietly
fails to fire is worse than none, since it reports nothing and that reads as
green.

This is `check-wai-section-refs.py`'s complement, not a duplicate: that one
checks WAI markdown against WAI markdown, this one checks every standard's
code against its spec.

Co-Authored-By: Claude Opus 5 <[email protected]>

dcharlot merged commit e1be07c28a into main 2026-10-13 09:36:22 -04:00

dcharlot referenced this pull request from a commit 2026-10-13 09:36:24 -04:00

Merge pull request 'spec citations: five named sections their SPECs do not have, and a check so they cannot return' (#238) from dcharlot/spec-citations-resolve into main

dcharlot referenced this pull request from a commit 2026-10-13 22:40:05 -04:00

Merge origin/main (at 1ec8f447, with #233, #234, #236, #238, #239, #240) into wai/d2c-decoders-on-ops

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Transaction-Science/open-standards!238

No description provided.