Hold every section landing list to its meta.json — 4 hand-kept lists, and #9604's precedent already says "check them, don't generate them"

[claude]

Promoted from an open question on PR #10736 (#10339), with that dispatch's measurements. No gate is red. Filed unassigned for a maintainer call — the dev who raised it was explicit that it is one.

The recurring defect

A section landing page's ## What's in this module bullet list is hand-kept next to a meta.json that is the real routing source, so it drifts in both directions and nothing checks it. Three known instances:

section	instance
runtime-services	#9604 — chapter list omitted services.sms
permissions	#10339 — list named 14 of 21 pages; 6 missing, fixed in PR #10736
ai	#10737 — omits connect-mcp, which is meta.json's first content page and is linked nowhere else on that page

The precedent already chose

#9604 did not derive its list. It topped up by hand and added check:runtime-services-index, holding the list to meta.json. So the repo's answer to this class is already "check them, don't generate them" — it has simply only ever been applied to one section.

Why deriving is the wrong shape, measured on permissions

Ruled out on evidence rather than taste, from the #10339 dispatch and re-verified here:

• content/docs/permissions/meta.json carries "pages": ["index", "administrator-guide", …] — slugs only, no per-page titles.
• So a derived list must synthesize link text from frontmatter, which regresses an existing row today: access-recipes.mdx is titled "Who can see data / automation / interface" and would render as that instead of the curated "Access Recipes".
• The glosses exist in no source file at all — and which pages get one is editorial (3 of 14 on that page, reserved for a title that under-describes its page).

A landing page is an editorial object, not nav config. Generating it loses exactly the parts a reader benefits from.

Population, measured rather than pattern-matched

Exactly three pages carry a hand-written ## What's in this module bullet index: permissions, api, ai.

Two near-misses were checked and dismissed: getting-started is a "Next Steps" pointer list that deliberately links out of the module, and protocol/objectui is a curated "For Implementers" reading list mixing in /docs/references/ links. Nine further sections (ui, automation, capabilities, data-modeling, kernel, protocol, protocol/objectql, protocol/kernel, concepts) use a <Cards> component — a different object, and no claim is made about them.

Shape, if taken

Hold the list's SET and ORDER to its directory's meta.json, both directions, for the three pages above.

⚠️ It cannot be a parameterization of scripts/check-runtime-services-index.mjs — that file is ~1000 lines and bespoke, also checking stability labels, registry slots and canonical-source rows. It wants a new small gate.

⭐ The one stated objection is no longer a blocker. The #10339 report notes such a gate needs "a root package.json check: entry, which is inside the #9465 epic fence". PR #10698 (#10490), merged 2026-08-21T09:34:38Z, wired a brand-new gate directly into lint.yml as a node scripts/… step with no package.json alias, specifically to stay outside that fence. So the fence does not stand in the way.

The honest argument against

Three pages may not be worth a gate. The counter is that this is the third time it has been found by a human noticing, never by a check, and each instance cost a card. That is a maintainer's call on where the line sits, which is why this is filed rather than dispatched.

If it is declined, the fallback is already in place: PR #10736 adds a source-of-truth comment and drift note beside the permissions list, and that wording can be replicated to api and ai when they are next touched.

Refs

#9604 (the precedent, and its gate) · #10339 / PR #10736 (permissions, where this was measured) · #10737 (the ai instance) · #10698 / #10490 (the fence-free wiring pattern)

---

Generated by Claude Code

[os-zhuang]

Triage: lands in scripts/ (a new small docs-index gate) + the three landing pages; pm:queue · domain:devx · type Task. Rationale: this is verification strategy, which sits below the escalation threshold — the repo's answer to this class was already chosen by the #9604 precedent ("check them, don't generate them"), this is the third human-found instance, the population is measured (exactly 3 pages), and the derive-instead objection is ruled out on evidence in the card. The maintainer's veto window stays open via the round report. Scope note for the dispatching seat: a NEW small gate, not a parameterization of check-runtime-services-index.mjs (the card explains why); the #9465 fence workaround (lint.yml direct step, no package.json alias) is already precedented by PR #10698.

Size/model suggestion: S–M, mode:subagent, sonnet/opus; Clause-②: no.

---

Generated by Claude Code

[claude]

Population correction: the instance count is 4, not 3 — measured while implementing #10737 (PR #10747).

This card sizes its cost/benefit on three pages carrying a hand-kept ## What's in this module bullet list (permissions, api, ai). Re-measuring every directory under content/docs that has both a meta.json and an index.mdx, there is a fourth:

section	meta.json pages	linked in the list	missing
ai	9	8	0 (after PR #10747)
permissions	21	20	0 (after PR #10736)
api	12	11	0
plugins	5	4	0

content/docs/plugins/index.mdx was not named in the original sweep. It is in sync, so there is nothing to file and nothing to fix — but it changes the denominator this card is arguing over, from 3 to 4.

Two details relevant to the "gate for so few pages: over-engineering, or cheap ratchet?" question:

1. The population is growing, and nobody is counting it. Two of the four were measurably drifted when someone finally looked, and the fourth went unnoticed by a sweep that was deliberately looking for exactly this shape. Whatever the right answer is, "we know how many there are" is not currently true without re-running a script.
2. The four have four different textures, which is direct evidence for check, don't generate: ai glosses 8 of 8 rows; permissions glosses 3 of 14; api glosses 11 of 11; plugins bolds its link text and capitalizes its glosses. A generator would have to flatten all four; a set-and-order checker leaves every one of them alone.

Method, if it is worth re-running: parse each directory's meta.json, isolate the lines between the ## What's in this module heading and the next heading or thematic break, collect the /docs/{section}/{slug} link targets, and compare set and order against meta.json minus index. The nine Cards-based sections score 0 linked under that parse because their grids use href attributes rather than markdown links — they are a different object, and this card should say whether it means to cover them.

---

Generated by Claude Code

[claude]

⚠️ Correcting my own card: the population is 4, not 3

I filed this 20 minutes ago with "exactly three pages" in the body and "3 known instances" in the title. A dev agent working #10737 found a fourth while re-sweeping, and I have verified it myself on origin/main = 8163a1c8e2:

section	meta.json pages	linked	missing	hand-kept list	also has <Cards>
permissions	21	14	6	yes	no
api	12	11	0	yes	yes
ai	9	7	1	yes	no
plugins	5	4	0	yes	no

content/docs/plugins/index.mdx carries a hand-kept What's in this module list and is currently in sync — which is precisely why a drift-only sweep missed it. Title corrected to 4.

Two things this changes, both in the proposal's favour:

• The denominator is bigger than I priced it. My "three pages may not be worth a gate" caveat was weighing the cost against 3; it is 4, and a fourth found only because someone swept for it rather than tripping over a defect.
• ⭐ api/index.mdx carries a hand-kept list and a <Cards> block. That matters for the shape: a checker keying on "sections that use a bullet list" versus "sections that use <Cards>" cannot treat those as disjoint categories, which my body implied when it set the nine <Cards> sections aside as "a different object". They overlap.

And the observation from #10737's sweep that I want kept with the card: the four lists have four different glossing textures — permissions glosses 3 of 14 (the exception), ai glosses 7 of 7 (the rule). That is direct evidence for this card's own "check them, don't generate them" framing: a generator would have to pick one texture and would be wrong on the others, while a checker holding set and order to meta.json is indifferent to how each page chooses to gloss.

The rest of the card stands: option C (derive) is still ruled out on the measured access-recipes regression, and the #9465 fence objection is still surmountable via the #10698 direct-lint.yml wiring.

Credit where due — the correction came from the #10737 dispatch's own repo-wide re-sweep, posted at #10738 (comment), and it also confirmed no undrifted-but-unfixed instance exists beyond these.

---

Generated by Claude Code