fix(kit): everything the acceptance run found — Phase 5 slice 3 #4

wtclaude · 2026-08-12T19:40:34Z

wtclaude commented

2026-08-12 19:40:34 +00:00

Phase 5 slice 3 (MODULE_SYSTEM.md §2.11.1), the phase's last slice. Third of four PRs — website#148 is merged (this pins to it); docs#147 carries the record this references.

A cold agent was given this repo and the documents it links to and nothing else — no core source, no module-uo — and asked to build a module for a second game. It did, in one pass, without opening three of the four normative documents. Verdict yes, with caveats; the full record is docs/modules/kit-acceptance.md. This is the repair list.

The one it could not find

It had no core to render against. A module page built exactly as this kit teaches renders outside the site: PublicLayout is the chrome, not the body, and the wrapper core's own pages write by hand is two class names that appear in no contract. Core grew an opt-in shell prop for it (MODULE_API_VERSION 1.5.0, website#148). The template passes shell="narrow", and chapter 2 explains why you name a width and never a class.

Fixed


F1	The worst of them, because it lands in the first twenty minutes. `npm run check:swagger` failed on a pristine template on Windows — the check compares the committed fragment byte-for-byte, a default Windows clone is CRLF, the generator writes LF — and the message blamed "the routes or their annotations". Now `template/.gitattributes` pins `eol=lf` and the comparison normalises line endings anyway. A check may only fail for the reason it names, and this one names a diagnosis.
F3	`.gitea/workflows/release.yml` carries `gitea.example.com` and `your-org/your-module` under a literal `# CHANGE THESE`, was not in the rename checklist, and `checkRenameSites.js` could not match it — CI silent by construction. Row added, pattern widened.
F4	The release bundle's include list was hardcoded, so adding `server/utils/` would silently drop it from every release while the bundle check stayed green — the module dying later as a `startup_failed` row on an operator's box. Inverted to an exclusion list in both flavours.
F5	The annotation-quoting warning was wrong in both directions. See below.
F6	`template/.gitignore`, so a copied template that is `git init`ed inherits ignore rules rather than nothing.
F7	The UI kit is eight exports across five rows, not seven. The contract said seven and this kit had faithfully carried the miscount out of it — the never-re-specify rule working as designed on a wrong input.

One correction to the report itself: the agent said both workflow flavours carry placeholders. Only the Gitea one does — GitHub supplies GITHUB_REPOSITORY and friends. Recorded in kit-acceptance.md.

F5, measured rather than reasoned

A backtick is harmless — the template's own description has two Markdown spans and they survive verbatim into the fragment. A " is not, and it does not throw:

// #swagger.summary = 'A "quoted" world status'
//   →  "summary": "A \""      and swagger-autogen still prints Success

Nothing throws, so the generator's error capture has nothing to capture. The only signal is check:swagger calling the fragment stale, with a message blaming your routes. Both the template comment and chapter 2 now say that, and say to look for a quote first when that happens.

Adopted — recommendations, not defects

Chapter 1 now says to run every check on the untouched copy first. That is what found F1; without a baseline, the first failure is ambiguous forever — is this my mistake, or was it already like this?
The template ships the §2.7 self-check the agent wrote for itself. The rule has no CI in general — an outbound socket is not statically detectable — but a module can make a decidable claim about its own tree. Ported from its code, with a header explaining how to narrow it when a sidecar client arrives (talking to your sidecar is the expected shape and is not what §2.7 forbids) rather than delete it. It carries a positive control and a comment-stripping pass, because this is the third boundary check in this project to risk failing on the prose explaining it.

The pin

Moves to website edge 4ad8b2b, the 1.5.0 bump; template/module.json declares ^1.5.0. checkCoreApi's equality assertion holds, and the template now uses a member that exists only at that ref and later.

Verification

32 server + 18 client template tests (+3), 21 kit-script tests (+here), and all four checks green: checkLinks 58 links, checkRenameSites 22 entries, checkChapterPaths 34 paths, check:swagger current — the last one run on this CRLF working tree, which is the one that reproduced F1. checkCoreApi verified against a local checkout at the pinned ref. The bundle loop was run by hand with a server/utils/ present, since a release workflow never executes in CI.

AI-assisted: written with Claude Code (Claude Opus 5); commits carry a Co-Authored-By trailer.

Phase 5 slice 3 (`MODULE_SYSTEM.md` §2.11.1), the phase's last slice. **Third of four PRs** — `website#148` is merged (this pins to it); `docs#147` carries the record this references. A cold agent was given this repo and the documents it links to and **nothing else** — no core source, no `module-uo` — and asked to build a module for a second game. It did, in one pass, without opening three of the four normative documents. Verdict **yes, with caveats**; the full record is [`docs/modules/kit-acceptance.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/kit-acceptance.md). This is the repair list. ## The one it could not find It had no core to render against. A module page built exactly as this kit teaches renders **outside the site**: `PublicLayout` is the chrome, not the body, and the wrapper core's own pages write by hand is two class names that appear in no contract. Core grew an opt-in `shell` prop for it (`MODULE_API_VERSION` **1.5.0**, website#148). The template passes `shell="narrow"`, and chapter 2 explains why you name a *width* and never a class. ## Fixed | | | | --- | --- | | **F1** | **The worst of them, because it lands in the first twenty minutes.** `npm run check:swagger` failed on a **pristine** template on Windows — the check compares the committed fragment byte-for-byte, a default Windows clone is CRLF, the generator writes LF — and the message blamed *"the routes or their annotations"*. Now `template/.gitattributes` pins `eol=lf` **and** the comparison normalises line endings anyway. A check may only fail for the reason it names, and this one names a diagnosis. | | **F3** | `.gitea/workflows/release.yml` carries `gitea.example.com` and `your-org/your-module` under a literal `# CHANGE THESE`, was not in the rename checklist, and `checkRenameSites.js` **could not match it** — CI silent by construction. Row added, pattern widened. | | **F4** | The release bundle's include list was hardcoded, so adding `server/utils/` would silently drop it from every release while the bundle check stayed green — the module dying later as a `startup_failed` row on an operator's box. Inverted to an **exclusion** list in both flavours. | | **F5** | The annotation-quoting warning was wrong in both directions. See below. | | **F6** | `template/.gitignore`, so a copied template that is `git init`ed inherits ignore rules rather than nothing. | | **F7** | The UI kit is **eight exports across five rows**, not seven. The contract said seven and this kit had faithfully carried the miscount *out* of it — the never-re-specify rule working as designed on a wrong input. | **One correction to the report itself:** the agent said both workflow flavours carry placeholders. Only the Gitea one does — GitHub supplies `GITHUB_REPOSITORY` and friends. Recorded in `kit-acceptance.md`. ### F5, measured rather than reasoned A backtick is harmless — the template's own description has two Markdown spans and they survive verbatim into the fragment. A `"` is not, and **it does not throw**: ```js // #swagger.summary = 'A "quoted" world status' // → "summary": "A \"" and swagger-autogen still prints Success ``` Nothing throws, so the generator's error capture has nothing to capture. The only signal is `check:swagger` calling the fragment stale, with a message blaming your routes. Both the template comment and chapter 2 now say that, and say to look for a quote first when that happens. ## Adopted — recommendations, not defects - **Chapter 1 now says to run every check on the untouched copy first.** That is what found F1; without a baseline, the first failure is ambiguous forever — *is this my mistake, or was it already like this?* - **The template ships the §2.7 self-check the agent wrote for itself.** The rule has no CI *in general* — an outbound socket is not statically detectable — but a module can make a decidable claim about **its own tree**. Ported from its code, with a header explaining how to **narrow** it when a sidecar client arrives (talking to your sidecar is the expected shape and is not what §2.7 forbids) rather than delete it. It carries a positive control and a comment-stripping pass, because this is the third boundary check in this project to risk failing on the prose explaining it. ## The pin Moves to website `edge` **4ad8b2b**, the 1.5.0 bump; `template/module.json` declares `^1.5.0`. `checkCoreApi`'s equality assertion holds, and the template now uses a member that exists only at that ref and later. ## Verification **32 server + 18 client** template tests (+3), **21** kit-script tests (+here), and all four checks green: `checkLinks` 58 links, `checkRenameSites` 22 entries, `checkChapterPaths` 34 paths, `check:swagger` current — the last one run on **this CRLF working tree**, which is the one that reproduced F1. `checkCoreApi` verified against a local checkout at the pinned ref. The bundle loop was run by hand with a `server/utils/` present, since a release workflow never executes in CI. --- - [x] AI-assisted: written with Claude Code (Claude Opus 5); commits carry a `Co-Authored-By` trailer.

wtclaude added 1 commit 2026-08-12 19:40:35 +00:00

fix(kit): everything the acceptance run found — Phase 5 slice 3

PR Checks / prose (pull_request) Successful in -38s

Details

PR Checks / template (pull_request) Successful in 29s

Details

f8f7014d53

A cold agent was given this repo and the documents it links to, and nothing
else — no core source, no module-uo — and asked to build a module for a second
game. It did, in one pass. The record is docs/modules/kit-acceptance.md; this is
the repair list, plus the two things it recommended that were not defects.

The one it could not find, because it had no core to render against: a module
page built exactly as this kit teaches renders OUTSIDE the site. PublicLayout is
the chrome, not the body. Core grew an opt-in `shell` prop for it
(MODULE_API_VERSION 1.5.0, website#148); the template passes shell="narrow" and
chapter 2 explains why you name a width and never a class.

Fixed:

- **F1, and the worst of them, because it lands in the first twenty minutes.**
  `npm run check:swagger` failed on a PRISTINE template on Windows: the check
  compared the committed fragment byte-for-byte and a default Windows clone is
  CRLF while the generator writes LF. The message blamed "the routes or their
  annotations". Now `template/.gitattributes` pins `eol=lf` and the comparison
  normalises line endings anyway — a check may only fail for the reason it names,
  and this one names a diagnosis.
- **F3** — `.gitea/workflows/release.yml` carries `gitea.example.com` and
  `your-org/your-module` under a literal `# CHANGE THESE`, was not in the rename
  checklist, and `checkRenameSites.js` could not match it, so CI was silent by
  construction. Row added, pattern widened. (The agent reported both workflow
  flavours; only the Gitea one is affected — GitHub supplies its own variables.
  Corrected in the record.) The near-miss is kept in the check's comments and its
  suite: the obvious widening is `example\.com`, which fires on a fixture URL in
  checkImports.test.js. Every alternative has to be a string that cannot occur by
  accident, which is the same rule that made the id `examplegame`.
- **F4** — the release bundle's include list was hardcoded, so adding
  `server/utils/` would have silently dropped it from every release while the
  bundle check stayed green. Inverted to an exclusion list, in both flavours, and
  run by hand because a release workflow never executes in CI.
- **F5** — the annotation-quoting warning was wrong in both directions, and the
  correction is measured rather than reasoned. A backtick is harmless (the
  template's own description has two spans and they survive). A `"` is not, and
  it does not throw: `'A "quoted" status'` is silently TRUNCATED to `A "` while
  swagger-autogen prints Success and the error capture sees nothing. The only
  signal is check:swagger blaming your routes.
- **F6** — `template/.gitignore`, so a copied template that is `git init`ed
  inherits ignore rules instead of nothing.
- **F7** — the UI kit is eight exports across five rows, not seven. The contract
  said seven and this kit had faithfully carried the miscount out of it.

Adopted, not defects:

- Chapter 1 now says to run every check on the untouched copy first. That is what
  found F1; without a baseline the first failure is ambiguous forever.
- The template ships the §2.7 self-check the agent wrote for itself. The rule has
  no CI in general — an outbound socket is not statically detectable — but a
  module can make a decidable claim about its own tree. Ported from its code with
  a header explaining how to NARROW it when a sidecar client arrives, since
  talking to your sidecar is the expected shape and is not what §2.7 forbids.

The pin moves to website edge 4ad8b2b, the 1.5.0 bump, and template/module.json
declares ^1.5.0 — so checkCoreApi's equality assertion still holds and the
template uses a member that exists only at that ref and later.

32 server + 18 client template tests, 21 kit-script tests, all four checks green.

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

whitlocktech merged commit abf9344189 into main

2026-08-12 22:42:51 +00:00

whitlocktech deleted branch fix/acceptance-findings

2026-08-12 22:42:51 +00:00

whitlocktech referenced this issue from a commit

2026-08-12 22:42:52 +00:00

Merge pull request 'fix(kit): everything the acceptance run found — Phase 5 slice 3' (#4) from fix/acceptance-findings into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/Integration-kit#4