docs(spec): redirect the contributes.routes recommendation to the imperative http.server mount

[claude]

Part of #10726

This lands the doc-correction half only, per the ruling's own sequencing. The
contributes.routes schema tombstone is #10724's, which is pm:blocked on the #10812
cloud census — no schema key is added, removed or re-typed here, and no plugin-manifest
zod file is touched. #10726 stays open until that tombstone lands.

Ruling being executed

Maintainer ruling 2026-08-22 (decision-inbox batch, verbatim 「接受所有」), Option B:

remove contributes.routes, and redirect the docs. The key is tombstoned with #10724,
and the author-facing materials that recommend it (the objectstack-api skill's decision
table, the HttpDispatcher protocol doc, ADR-0088:40, and app.mdx:83) are corrected to
point at the imperative http.server mount — the form that actually works today. Per the
accepted recommendation, the doc corrections land immediately and are not held for the
removal.

Why the correction is needed

contributes.routes has zero readers monorepo-wide: the only non-test read of
manifest.contributes anywhere reads kinds, not routes
(packages/objectql/src/engine.ts:4499). An author — human or AI — following the shipped
skill writes a contributes.routes entry, gets a clean parse, and serves nothing.

The replacement was verified live before it was written

A redirect to a second dead form would be the same defect again, so http.server was
confirmed on today's main first:

• Registered:packages/plugins/plugin-hono-server/src/hono-plugin.ts:271
  (ctx.registerService('http.server', this.server)), declared at :228
  (providesServices = ['http.server', 'http-server']).
• Real in-tree usage, in exactly the case the skill's table describes — a plugin
  serving a code-handler endpoint:
  examples/app-showcase/src/system/server/recalc-endpoint.ts:52 resolves the service and
  mounts POST /api/v1/showcase/recalc on kernel:ready.
• Further consumers:plugin-approvals, plugin-sharing, cloud-connection
  (runtime-config-plugin.ts, marketplace-*), packages/metadata/src/plugin.ts, and the
  CLI's serve all resolve the same service.

The four sites

#	Ruling's lead	Actual site on today's main
1	the objectstack-api skill's decision table	skills/objectstack-api/SKILL.md:159-164
2	the HttpDispatcher protocol doc	packages/spec/src/api/dispatcher.zod.ts:16
3	ADR-0088:40	docs/adr/0088-metadata-kind-admission-and-retirement.md:40
4	app.mdx:83	packages/spec/src/ui/app.zod.ts:1462

Two of the ruling's leads named generated artifacts.content/docs/references/api/dispatcher.mdx
and content/docs/references/ui/app.mdx both carry
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. */}; their real
sources are the two .zod.ts files above. Editing the .mdx would have been reverted by
the next regeneration and would have failed check:docs. The two .mdx files in this diff
are the regenerated projection of the two .zod.ts edits
(pnpm --filter @objectstack/spec gen:docs), not hand edits — check:docs confirms:
✅ 229 generated files in sync with packages/spec. The regeneration touched exactly those
two files and nothing else, so no unrelated drift rode along.

The ruling also pointed at content/docs/protocol/** for site 2; the protocol doc actually
lives in the spec source and its generated page under content/docs/references/api/.

ADR-0088: one dangling antecedent fixed

The router row's delivered-form cell no longer credits contributes.routes. The existing
#4936, 2026-08-04 correction is kept verbatim except for one phrase: it said "its
delivered forms are the two above, both code contributions", an antecedent that no
longer resolves once one of the two is struck. The new correction is appended after it,
chronologically, and names the surviving forms. The ADR is otherwise unrestructured.

Published-skill budget

The dispatch budget was ≤ +5 net lines for the whole skills/ touch. Delivered at
0 net lines — file and package both 610 → 610; the published-skills bundle 10506 →
10506 lines.

Tokens are the binding constraint, and skills/objectstack-api/SKILL.md had zero
headroom (6346 tokens against a 6348 ceiling; the ratchet is shrink-only and loosening it
is marked ⛔ MAINTAINER-ONLY). A first draft came in +44 tokens over and was rejected by
check-skills-token-ratchet; the correction was tightened to fit rather than the ceiling
loosened. Final: 6348 / 6348, bundle total 117922 / 117949 (-27).

Gates

Derived from the actual diff with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
(re-derived after the changeset was added). Verified at cb9aa12dd; the ratchet families
were re-run after the final commit.

Green: check:skills-token-ratchet · check:skill-compatibility · check:skill-frame-sync ·
check:doc-authoring · check:role-word · check:adr-anchors · check:doc-anchors ·
check-adr-links · check:pm-governed-merges · check:docs-redirects ·
check:docs-audit-scope · check-doc-frontmatter · check-section-landing-index ·
check:quick-reference-counts · check:published-readme-links · check:doc-formula-expressions ·
check:doc-security-posture · check:merge-driver · check:published-files ·
check:spec-parsed-alias · check:slot-lookup · check:test-source-alias ·
check:type-source-resolution · check:cross-package-test-inputs · check-ci-filter-parity ·
check-plugin-teardown-shape · check-affected-docs · check:empty-state · check:liveness ·
check:strictness-ledger · check:variant-docs · check:changeset-gate-self-tests ·
check:objectui-changeset · check-adr-0087-registration · check-changeset-no-major ·
check-empty-changeset · check:nul-bytes · check:docs.

pnpm --filter @objectstack/spec typecheck green (incl. check:scripts-typecheck and
check:test-typecheck). pnpm --filter @objectstack/spec test green — 418 test files,
11128 tests passed.

check:doc-formula-expressions and check:doc-security-posture were initially red with
ERR_MODULE_NOT_FOUND on packages/lint/dist/ — an unbuilt dependency closure, not this
diff. Both green after pnpm --filter '@objectstack/lint^...' --filter @objectstack/lint build.

check-dev-prereqs is red and it is not this diff: it reports "The workspace is not
built — 1 unmet precondition", naming 63 of 67 packages (@objectstack/cli,
@objectstack/client, …) whose dist/ entry points are absent in this worktree. None is
touched here and this diff changes no entry point or package.json. CI builds the
workspace.

Declared narrowing — repo-wide pnpm lint was not run locally (it is CI-owned); the
targeted run is a measurement, not a skip:

1. Population came from eslint's own config resolution, not a guess about which files count.
2. --format json reported 2 files linted, 0 errors, 0 warnings — the two changed
   .ts files.
3. Invariance for untouched files: eslint.config.mjs:327-329 states this repo "runs one
   eslint.config.mjs, which never enables type-aware linting (no parserOptions.project,
   no typed @typescript-eslint rules) for ANY file", so this diff cannot move the verdict
   on any file it does not contain.

Landing note

Touches governed faces (docs/adr/**, skills/**) — stays draft for human merge.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 1 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/getting-started/quick-reference.mdx(via AppSchema (symbol))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v14.mdx(via AppSchema (symbol))
• content/docs/releases/v17.mdx(via AppSchema (symbol))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/src/api/dispatcher.zod.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 45 of 221 client-bound route-ledger rows — the other 176 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run: node scripts/docs-audit/affected-docs.mjs --bridge-coverage

Coarse fallback — 126 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 8113ba37ae066c1eb6dd82d47742983b44ac60ea → packageMentionDocs.

Which tree this was computed on

This run read content/docs from e664598ab462cc45eff5de7db70a70047410cb37 — the merge of head cb9aa12dddd5d6dc8144556c0ff9e82aa526932a into base 8113ba37ae066c1eb6dd82d47742983b44ac60ea, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin e664598ab462cc45eff5de7db70a70047410cb37 && git checkout e664598ab462cc45eff5de7db70a70047410cb37
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 8113ba37ae066c1eb6dd82d47742983b44ac60ea cb9aa12dddd5d6dc8144556c0ff9e82aa526932a && git checkout -B drift-repro 8113ba37ae066c1eb6dd82d47742983b44ac60ea && git merge --no-ff cb9aa12dddd5d6dc8144556c0ff9e82aa526932a
node scripts/docs-audit/affected-docs.mjs --json 8113ba37ae066c1eb6dd82d47742983b44ac60ea

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 8113ba37ae066c1eb6dd82d47742983b44ac60ea → pass the list as
args.docs, on the commit named under Which tree this was computed on.