docs(modules): record the kit's extra checks and slice 2 #146

wtclaude · 2026-08-12T18:22:13Z

wtclaude commented

2026-08-12 18:22:13 +00:00

The docs half of Phase 5 slice 2 (§2.11.1). The Integration Kit half is Integration-kit#3.

What this fixes

Decision 2 said the kit's CI "checks three things". It runs five. Two were added as the things they guard came into existence, and the pattern is worth naming rather than left as CI archaeology: each exists because a class of claim in that repo had nothing looking at it.

checkRenameSites.js (slice 0) — holds the template's rename checklist against the tree, in both directions.
checkChapterPaths.js (slice 2) — every path a chapter names in backticks must exist. None of those mentions is a markdown link, so the link check never saw them, and none is code, so nothing else did either. Renaming one template file would have left four chapters pointing at nothing, silently.

Its anchor list is stated, not derived from the tree, for the reason API §3.6 already gives about the template's own build guard: a list derived from what exists cannot fail when what exists changes, so a renamed template/ would simply stop being checked at the moment every mention of it became wrong. An anchor that matches nothing fails the build — the same rule §5.2's grandfathering exemptions follow.

The section also now says plainly what none of the five can do: whether a paragraph has become untrue about a file that still exists is a reviewer's obligation, in full at a MODULE_API_VERSION bump.

Progress, and slice 2's verification

Slices 0–2 have landed; only slice 3 (the cold-agent acceptance run of decision 5) is outstanding.

Slice 2's verification is recorded because it is the shape decision 5 scales up. Chapters 1 and 2 quote a tree CI builds, so what remained unproven was the walkthrough — whether following chapter 1 produces what chapter 1 says it produces. It was run against a real core on edge, including the three failures the chapter tells a reader to cause on purpose:

Broken on purpose	What the chapter now says, because it is what core printed
A prefix declared in `mounts` and never registered	stage `register`, "declared public/extra but never registered it" — routes `404`, absent from `/api/v1/public/modules`
A table without the id prefix	stage `schema`, at load time, before anything mounts
A throwing `onBoot`	after mounting, so the route answers `503 Module unavailable` rather than vanishing

A chapter that predicts the wrong debugging heuristic is worse than one that predicts none, and that is exactly the class of error no check in this repo can see.

Checks

Markdown only — no code in this repo. Both link targets in the amended text resolve.

AI-assisted: written with Claude Code (Opus 5), reviewed before opening.

The docs half of **Phase 5 slice 2** (§2.11.1). The Integration Kit half is Integration-kit#3. ## What this fixes **Decision 2 said the kit's CI "checks three things". It runs five.** Two were added as the things they guard came into existence, and the pattern is worth naming rather than left as CI archaeology: **each exists because a class of claim in that repo had nothing looking at it.** - `checkRenameSites.js` (slice 0) — holds the template's rename checklist against the tree, in both directions. - `checkChapterPaths.js` (slice 2) — every path a chapter names in backticks must exist. None of those mentions is a markdown link, so the link check never saw them, and none is code, so nothing else did either. Renaming one template file would have left four chapters pointing at nothing, silently. Its anchor list is **stated, not derived from the tree**, for the reason API §3.6 already gives about the template's own build guard: a list derived from what exists cannot fail when what exists changes, so a renamed `template/` would simply stop being checked at the moment every mention of it became wrong. An anchor that matches nothing fails the build — the same rule §5.2's grandfathering exemptions follow. The section also now says plainly what none of the five can do: whether a paragraph has become untrue about a file that still exists is a reviewer's obligation, in full at a `MODULE_API_VERSION` bump. ## Progress, and slice 2's verification Slices 0–2 have landed; only slice 3 (the cold-agent acceptance run of decision 5) is outstanding. Slice 2's verification is recorded because it is the shape decision 5 scales up. Chapters 1 and 2 quote a tree CI builds, so what remained unproven was the **walkthrough** — whether following chapter 1 produces what chapter 1 says it produces. It was run against a real core on `edge`, including the three failures the chapter tells a reader to cause on purpose: | Broken on purpose | What the chapter now says, because it is what core printed | | --- | --- | | A prefix declared in `mounts` and never registered | stage `register`, *"declared public/extra but never registered it"* — routes `404`, absent from `/api/v1/public/modules` | | A table without the id prefix | stage `schema`, at **load** time, before anything mounts | | A throwing `onBoot` | after mounting, so the route answers `503 Module unavailable` rather than vanishing | **A chapter that predicts the wrong debugging heuristic is worse than one that predicts none**, and that is exactly the class of error no check in this repo can see. ## Checks Markdown only — no code in this repo. Both link targets in the amended text resolve. --- - [x] AI-assisted: written with Claude Code (Opus 5), reviewed before opening.

wtclaude added 1 commit 2026-08-12 18:22:16 +00:00

docs(modules): record the kit's extra checks and slice 2 abd04f04fd

Decision 2 of §2.11.1 still said the kit's CI "checks three things"; it runs five.
Two were added as the things they guard came into existence, and the pattern is
worth naming rather than leaving as CI archaeology: each exists because a class of
claim in that repo had nothing looking at it. checkRenameSites (slice 0) holds the
template's rename checklist against the tree in both directions.
checkChapterPaths (slice 2) requires every path a chapter names in backticks to
exist — not a markdown link, so the link check never saw those, and not code, so
nothing else did.

Its anchor list is STATED, not derived from the tree, for the reason API §3.6 gives
about the template's own build guard: a derived list cannot fail when what it
derives from changes, so a renamed `template/` would stop being checked at the
moment every mention of it became wrong. An anchor matching nothing fails the
build, the same rule §5.2's exemptions follow.

Also records Phase 5 progress (slices 0-2 landed; only the acceptance run is
outstanding) and slice 2's verification, which is the shape decision 5 scales up:
chapter 1's walkthrough was RUN against a real core on `edge`, including the three
failures the chapter tells a reader to cause on purpose, and the chapter now quotes
core's own messages for them.

Integration-kit half: Integration-kit#3.

Co-Authored-By: Claude <noreply@anthropic.com>

whitlocktech merged commit c6f4c2478f into main

2026-08-12 18:36:44 +00:00

whitlocktech referenced this issue from a commit

2026-08-12 18:36:45 +00:00

Merge pull request 'docs(modules): record the kit's extra checks and slice 2' (#146) from docs/module-phase5-slice2 into main

whitlocktech deleted branch docs/module-phase5-slice2

2026-08-12 18:36:46 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#146