docs(spec): cite the /ai/models picker decision as cloud ADR-0028

[objectstack-fleet]

Fixes #24486

Clause-②: no

What this does

packages/spec cited a bare ADR-0028 beside GET /api/v1/ai/models. A bare number resolves against this repository's registry, where docs/adr/0028-metadata-naming-and-namespace-isolation.md is about metadata naming. The decision these lines mean is cloud's docs/adr/0028-paid-tier-selectable-ai-model.md (read by triage, comment 6262456627). AGENTS.md Prime Directive #13 says a cloud decision is cited from this repo as cloud ADR-NNNN, never as a bare number.

This PR qualifies the three lines, in the same wording PR #24482 used for the client TSDoc and the docs:

• packages/spec/src/api/protocol.zod.ts:3399, JSDoc on AiModelsResponseSchema: "plan-filtered picker list (cloud ADR-0028)".
• packages/spec/src/api/protocol.zod.ts:3402, JSDoc on models: "exposes the cloud ADR-0028 allowlist".
• packages/spec/src/api/protocol.test.ts:375, test comment: "the cloud ADR-0028 allowlist".

JSDoc and comments only. No .describe() string, shape or generated file moves. CHANGELOG.md history is left as written.

A fresh git grep ADR-0028 -- packages/spec (excluding CHANGELOG.md) on origin/main 959ee317b finds one more site, packages/spec/src/kernel/namespace-prefix.ts:4 ("Namespace-prefix rules (ADR-0028 current-state contract)"). That one is correct as written: it means this repository's ADR-0028 (namespace isolation), so it is not changed.

Changeset

.changeset/24486-spec-cloud-adr-0028-citation.md is a patch for @objectstack/spec. The package's files[] ships src/**/*.zod.ts verbatim, and the JSDoc reaches the built .d.ts: after the build, grep -rl "picker list (cloud ADR-0028)" packages/spec/dist hits automation-api.zod-*.d.ts / .d.mts, and the old bare wording has 0 hits. The published surface moves, so skip-changeset does not apply.

Verification

The full run below was on head e27d6d3f60, the fix commit. After that, origin/main 6b42b6bc8a was merged in, giving head c53d4f840e. The diff against main is the same 3 files, and the gate derivation on the new head is byte-identical (86 commands). On c53d4f840e I re-ran the 42 build-free commands: all 37 direct node scripts/... gates, check:nul-bytes, check:changeset-gate-self-tests, check:type-check-coverage, check:issue-citations and check:test-source-alias. All 42 exited 0.

• pnpm --filter @objectstack/spec build: exit 0.
• pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 src/api/protocol.test.ts: 1 file, 186 tests passed.
• pnpm --filter @objectstack/spec run typecheck: exit 0, including check:test-typecheck: OK over the test layer.
• node scripts/check-adr-anchors.mjs: exit 0, "check-adr-anchors: OK (75 anchored file(s), ... 48594 citation(s) across 6480 file(s) resolve ...)". The script recognises cloud ADR-NNNN and skips it.
• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 86 commands. All 86 were run, and --ran with exit codes reconciles them: "86 derived famil(ies) accounted for, 82 run, 4 NOT-MEASURED (4 DERIVED from a recorded exit 3)".
  • Green, among others: check:docs ("227 generated files in sync with packages/spec"), check:api-surface ("public API surface + factory signatures unchanged"), check:authorable-surface, check:nul-bytes, check-changeset-no-major, check-empty-changeset, check:issue-citations. node scripts/check-changeset-fixed.mjs (roster under .changeset) also passed.
  • NOT MEASURED (PREREQUISITE NOT MET, unbuilt sibling packages, left to CI): check:doc-formula-expressions (@objectstack/formula), check:lean-entry-closure (@objectstack/objectql dist), check:dual-build-cjs-loads (whole-workspace build), check:type-check-debt. None of them reads a comment in packages/spec/src/api.

Acceptance notes

• packages/spec/src/kernel/namespace-prefix.ts:4 cites ADR-0028 and correctly means this repository's record. It is noted here, not changed.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/releases/v17/17-0.mdx (via /api/v1/ai/models (route, a path literal in a comment on a changed line))

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

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 143 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 6b42b6bc8a11b58cfaa5054e9edbb86b1898f2e7 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from db396b6c40c486f56b98195e662f5ee5cdaf806a — the merge of head c53d4f840e58fffd8e1fc539c758c961e189527a into base 6b42b6bc8a11b58cfaa5054e9edbb86b1898f2e7, 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 db396b6c40c486f56b98195e662f5ee5cdaf806a && git checkout db396b6c40c486f56b98195e662f5ee5cdaf806a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 6b42b6bc8a11b58cfaa5054e9edbb86b1898f2e7 c53d4f840e58fffd8e1fc539c758c961e189527a && git checkout -B drift-repro 6b42b6bc8a11b58cfaa5054e9edbb86b1898f2e7 && git merge --no-ff c53d4f840e58fffd8e1fc539c758c961e189527a

node scripts/docs-audit/affected-docs.mjs --json 6b42b6bc8a11b58cfaa5054e9edbb86b1898f2e7

⚠️ 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 6b42b6bc8a11b58cfaa5054e9edbb86b1898f2e7 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Review: ACCEPT · PR #24514 @ c53d4f840e58fffd8e1fc539c758c961e189527a · domain:spec seat 3 · 2026-10-19T09:41Z

Session session_01D6F9axfoPzR7t8G1J7Ytzz · baozhoutao. Reviewer of record; checked against GitHub, not the report. Diff re-read three-dot and merge-tested against the CURRENT main tip (clean).

• Shape: draft, Fixes #24486, Clause-②: no; +13/−3, 3 files; NOT governed.
• The change: the three bare ADR-0028 citations beside GET /api/v1/ai/models read cloud ADR-0028 (protocol.zod.ts two JSDoc lines, protocol.test.ts one comment), in PR fix(client,platform-objects,docs): in-system copy says "this system", not "this environment" (cloud#3002 ruling A) #24482's wording. No describe string, shape or generated file moves (check:docs in sync).
• The one other site (kernel/namespace-prefix.ts:4) correctly cites this repo's ADR-0028 (namespace isolation) and stays.
• Changeset: @objectstack/spec patch — the JSDoc reaches the shipped .d.ts (dist grep confirms).
• Gates: check-adr-anchors OK; 82 of 86 run green, 4 NOT MEASURED locally for unbuilt siblings — CI measures them.
• CI on the head: read at this act; the seat lands on green through the merge queue.

---

Generated by Claude Code