1 Commits

Author SHA1 Message Date
12bd24a973 docs(teams): queue the integration kit as phase 11, last before the cutover
The kit is the instruction book for putting a different game on this platform,
written for an audience outside this org. Teams expands the contract that book
teaches against, so the book is the last thing the bet owes before `edge` becomes
`main` (org lead, 2026-08-18).

One sentence in it is already wrong rather than merely incomplete.
`book/02-website-module.md` tells a reader that core declares a slot and a module
may only fill one. Phase 3 inverted exactly that, and by phase 6 module-uo declares
three — a new game's module cannot implement Teams at all without the inverted
direction.

Two shapes are genuinely new and worth teaching: the inverted slot, and
`registerTeamProvider` as the first registration where core calls the module and
waits — with the asymmetry that every call fails stale except `projectRoster`,
which fails closed, because for a visibility question "keep what you have" means
serving the roster unprojected.

The phase explicitly does NOT enumerate the contract. The kit already teaches four
members and has never mentioned notification streams, announce legs or post hooks,
all of which predate Teams. MODULE_API.md is normative; the kit teaches one path
and links out.

Its ordering is awkward and is stated rather than smoothed over: it is written
before the cutover and can only merge after it, because CI clones the pinned sha
and checks the template against that core's MODULE_API_VERSION — and 1.6.0 does
not reach `main` until the cutover lands.

Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-18 18:17:26 -05:00

View File

@@ -2165,6 +2165,11 @@ makes §0.1's roster possible:
Every phase is independently shippable and leaves the site working. Phases 1 and 2 are the only hard
serial dependency in the list.
**Phase 11 is the exception to "independently shippable", and it is last on purpose** (org lead,
2026-08-18). The integration kit teaches an outside audience to build against this contract; Teams
expands the contract, so the book is the last thing owed before `edge` becomes `main`. It is also the
only phase that cannot merge until the cutover exists — see its own note.
### Phase 0 — a one-guild roster spike (`servuo-plugins` + `link`, throwaway)
**Not a deliverable — insurance on the phase that gates everything else.** `servuo-plugins` has no CI
@@ -2505,6 +2510,56 @@ rendering the admin UI from the declaration rather than from a hardcoded "Discor
purpose: extracting a capability surface from one working implementation is honest; designing it before
one exists is speculation.
### Phase 11 — the integration kit (`integration-kit`) — **the last phase before the cutover**
The kit is the instruction book for putting a *different* game on this platform, written for an
audience outside this org. Teams expands the contract that book teaches against, so the book is the
last thing this bet owes before `edge` becomes `main`.
**One sentence in it is already wrong.** `book/02-website-module.md` states, of extension slots,
"**core declares a slot; a module may only fill one**". Phase 3 inverted exactly that: with
`declareModuleSlot` a MODULE declares a place on its own page and CORE fills it, and by phase 6
`module-uo` declares three. A new game's module cannot implement Teams at all without the inverted
direction, so this is not a stale detail — it is the shape the reader needs and does not have.
**Two genuinely new shapes to teach, and only two:**
- **The inverted slot** (§3.7a) — a module declaring a place for core, why the name is namespaced under
the module's own id, and why a module wants *separate* slots rather than one (it decides where each
of core's contributions sits on a page it owns).
- **`registerTeamProvider`** — the first registration where **core calls the module and waits**. Every
other one is the module claiming a mount or core notifying it. The envelope, the 10-second budget,
and the asymmetry that matters: every call fails **stale** (core keeps what it has) except
`projectRoster`, which fails **closed**, because for a visibility question "keep what you have"
means serving the roster unprojected.
`pageUrlTemplate` is a footnote beside those — one optional string, and the reader meets it while
reading the provider.
**What this phase explicitly does NOT do: enumerate the contract.** The kit already teaches only four
members and has never mentioned `registerNotificationStreams`, `registerAnnounceLeg` or
`registerPostHook`, all of which predate Teams. That is the design, not a gap:
[`MODULE_API.md`](MODULE_API.md) is normative and the kit teaches one path end to end and links out.
The question this phase answers is "did the teaching path change", and the answer is yes in two
places and no everywhere else.
**Then the two mechanical lines:** `ci/core-ref.json`'s sha moves to the cutover commit and
`template/module.json`'s `coreApi` becomes `^1.6.0`, which puts `scripts/checkCoreApi.js` back to
green. That check is an **equality**, and its going red is the mechanism rather than a bug — a
contract bump is meant to turn that repo red until someone has re-read the chapters. Moving the pin is
that person saying they have.
> **Ordering, stated because it is genuinely awkward.** This phase is written *before* the cutover and
> can only *merge after* it. CI clones the pinned sha and checks the template against that core's
> `MODULE_API_VERSION` — and 1.6.0 does not exist on `main` until the cutover lands, so there is no sha
> to pin and no core for the template to build against until then. Write the chapters last, open the
> PR once the cutover merge exists, and put the pin move in it.
**Checks that gate it** (all dependency-free Node scripts, run from the repo root — which is also how a
reader runs them): `checkLinks`, `checkRenameSites`, `checkChapterPaths`, `checkCoreApi --core .core`,
plus the template's own `npm ci` / `check:imports` / `build` / `check:externals` / `npm test` on both
halves. Build the client **before** the client tests; two of them read the built chunk.
### Cross-cutting, every phase that touches the server
`npm run swagger` regenerated and committed · `npm run routes:manifest -- --check` zero-line diff ·