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

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](https://claude.ai/code/session_01D6F9axfoPzR7t8G1J7Ytzz)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/24486-spec-cloud-adr-0028-citation.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/spec': patch
+---
+
+Clause-②: no
+
+docs(spec): the `GET /api/v1/ai/models` response JSDoc cites `cloud ADR-0028`, not a bare `ADR-0028`
+
+- **What changed.** The JSDoc on `AiModelsResponseSchema` and on its `models` field now cites `cloud ADR-0028` (the plan-filtered AI model picker decision) where it cited a bare `ADR-0028`. This repository's own ADR-0028 is about metadata naming and namespace isolation; the AI service that serves this list is a cloud package. The client SDK TSDoc and the docs already cite it this way.
+- **Unchanged.** Every schema shape, `.describe()` string, generated JSON Schema and behaviour.

packages/spec/src/api/protocol.test.ts

@@ -372,7 +372,7 @@ describe('ObjectStack Protocol', () => {
     expect(AiCompleteRequestSchema.safeParse({ prompt: 'Summarise:', options: { maxTokens: 64 } }).success).toBe(true);
     expect(AiCompleteRequestSchema.safeParse({}).success).toBe(false);
 
-    // models — both live shapes: the ADR-0028 allowlist and the bare-id fallback
+    // models — both live shapes: the cloud ADR-0028 allowlist and the bare-id fallback
     expect(AiModelsResponseSchema.safeParse({
       models: [{ id: 'gpt-4o-mini', label: 'GPT-4o mini', default: true }], defaultModel: 'gpt-4o-mini',
     }).success).toBe(true);

packages/spec/src/api/protocol.zod.ts

@@ -3396,10 +3396,10 @@ export const AiCompleteRequestSchema = lazySchema(() => z.object({
   options: z.record(z.string(), z.unknown()).optional().describe('Request options (model, temperature, maxTokens, …)'),
 }));
 
-/** `GET /api/v1/ai/models` — the environment's plan-filtered picker list (ADR-0028). */
+/** `GET /api/v1/ai/models` — the environment's plan-filtered picker list (cloud ADR-0028). */
 export const AiModelsResponseSchema = lazySchema(() => z.object({
   /**
-   * Objects when the service exposes the ADR-0028 allowlist; bare ids when it
+   * Objects when the service exposes the cloud ADR-0028 allowlist; bare ids when it
    * falls back to the adapter's `listModels()`. Both shapes are live, so both
    * are declared rather than one being asserted and the other 404-by-parse.
    */