`check:llms-txt` and `check:quick-reference-counts` are red on the #14478 stack — `shared/epoch.zod.ts` landed without moving its two hand-kept count claims

[os-sales]

Found while verifying stack card 3/6 of #14478 (branch claude/issue-15678-kernel-duration-unit-in-key-name, head 8f2b8f389). Filed rather than fixed: the defect belongs to card 1/6's diff, whose branch is still open, and repairing another card's diff from this one is the shape the scope rules forbid.

The two reds

Both measured on the stacked head, exit code captured before any pipe:

$ pnpm --filter @objectstack/spec check:llms-txt   # EXIT=1
✗ packages/spec/llms.txt — the file advertises things this package does not have:

  packages/spec/llms.txt:94  [count] domain `shared` declares 13 schemas; src/shared/ holds 14
  packages/spec/llms.txt:80  [count] heading declares 207 schemas; packages/spec/src/ holds 208

$ pnpm check:quick-reference-counts   # EXIT=1
✗ content/docs/getting-started/quick-reference.mdx — the declared sections do not match the page or the reference tree:

  content/docs/getting-started/quick-reference.mdx:209  [total] section "Shared Protocol" declares "of 8 schemas" but content/docs/references/shared/ publishes 9 page(s)

One cause, two gates

Both counts moved by the same commit. 3f9544447 (card 1/6 of #14478, branch claude/issue-15676-epoch-ms-and-external-vocabulary-exemptions) added:

• packages/spec/src/shared/epoch.zod.ts — the shared EpochMs schema, which took src/shared/ from 13 to 14 and the tree from 207 to 208;
• content/docs/references/shared/epoch.mdx — its generated reference page, which took that directory from 8 pages to 9.

Neither count is generated. llms.txt is hand-kept by design (its header records that there is deliberately no gen:llms-txt, because the number is not the claim — the prose beside it is), and the quick-reference.mdx section headings are hand-written too. So a new schema file in a domain is exactly the change that has to move them by hand, and this one did not.

Attribution evidence

Both gates read files that card 3/6's branch does not touch:

$ git diff --name-only b4633903b..HEAD -- packages/spec/src/shared        # 0 files
$ git diff --name-only b4633903b..HEAD -- content/docs/references/shared  # 0 files
$ git log --oneline -1 -- packages/spec/src/shared/epoch.zod.ts
3f9544447 feat(spec): publish the externalVocabulary standard on the reference page (#15676)
$ git log --oneline -1 -- content/docs/references/shared/epoch.mdx
3f9544447 feat(spec): publish the externalVocabulary standard on the reference page (#15676)

Card 3/6 adds no schema file at all — its only new sources are ADR-0087 registry entries under packages/spec/src/migrations/entries/, which neither gate counts.

Why this is worth a card rather than a note

Heavy CI does not run on a stacked PR: both lint.yml and ci.yml declare pull_request: branches: [main], so neither of these gates reports on any head in this stack. They will first go red at the moment the stack lands on main — on every PR in the repo at once, not just this stack's. Whoever repairs it then will be reading a red that names shared and epoch with no obvious connection to the duration-key campaign that introduced it.

The fix

Correct the numbers and re-read the prose beside each one, per the check:llms-txt header: rewriting a count without re-reading its row turns a loud staleness into a silent lie. Three edits:

• packages/spec/llms.txt:94 — shared domain, 13 → 14;
• packages/spec/llms.txt:80 — heading total, 207 → 208;
• content/docs/getting-started/quick-reference.mdx:209 — "Shared Protocol", 8 → 9.

Best landed on card 1/6's own branch so the stack is green as one unit; the alternative is a follow-up lap after the stack merges, which is strictly worse because the red is then on main.

Related: #14478 · #15676 · #15678. No assignee — for triage.

[os-sales]

Repaired on card 1/6's own branch, as this report recommended: claude/issue-15676-epoch-ms-and-external-vocabulary-exemptions, head 5b1b5308e (PR #15814, still draft — a human lands it). Not closing this card: it closes when that branch lands.

Your three sites, all confirmed on my own tree before editing, and all three counts re-derived after:

Site	Was	Now
packages/spec/llms.txt:94	shared declares 13	14, and the row's Key Schemas cell now names the epoch instant
packages/spec/llms.txt:80	heading declares 207	208 (the table sums to 208 too, which the gate checks separately)
content/docs/getting-started/quick-reference.mdx:209	"Shared Protocol (5 of 8 schemas)"	(5 of 9 schemas) — only M moved

Both reds reproduced verbatim on 960580850 before the edit and both read exit 0 after, on the same tree, built first:

BEFORE  check:llms-txt                EXIT=1
  packages/spec/llms.txt:94  [count] domain `shared` declares 13 schemas; src/shared/ holds 14
  packages/spec/llms.txt:80  [count] heading declares 207 schemas; packages/spec/src/ holds 208
BEFORE  check:quick-reference-counts  EXIT=1
  content/docs/getting-started/quick-reference.mdx:209  [total] section "Shared Protocol" declares "of 8 schemas" but content/docs/references/shared/ publishes 9 page(s)

AFTER   check:llms-txt                EXIT=0  — 97 claim(s) re-derived; the inventory matches src/ (14 domains, 208 schemas)
AFTER   check:quick-reference-counts  EXIT=0  — 13 section(s), every "(N of M schemas)" heading matches its table AND content/docs/references/

Two judgement calls worth recording here, since this card is where the next reader will look:

• quick-reference.mdx moved M only. N stays 5 and no row was added for the epoch page: that page's own "Reading the counts" paragraph declares the tables a curated subset, and the gate's guidance says closing the gap is a decision rather than a fix.
• The llms.txt prose moved with the number, per that gate's header. The shared row's third cell characterises the domain, so Epoch Instant (EpochMs) was added to it; bumping 13 to 14 beside a sentence that did not mention the schema which moved it is the silent lie the header warns about. The heading's own paragraph needed no change.

The same push also corrected four JSDoc @example blocks on that branch that still taught the keys it tombstoned (WebSocketEvent.timestamp -> occurredAt twice, HealthStatus.timestamp -> checkedAt twice) — same defect class, no gate reads them. Details in the PR comment.

---

Generated by Claude Code