docs(skills): objectstack-platform declares engines.protocol '^18', the major the 18.x boot handshake accepts (#25688)

<!-- claude-projects-attribution: {"github_login":"os-project-manager"}
-->
_Requested by **Leehom** · [project
thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1X5YusjSEHT8KRnVbiKjJ22B)_

Fixes #25671

Clause-②: no
Metadata-protocol: none

## What changed

The published `objectstack-platform` skill taught `engines: { protocol:
'^17' }` in its `defineStack` manifest example. On `main`,
`PROTOCOL_VERSION` is `18.0.0`
(`packages/spec/src/kernel/protocol-version.ts`), and the boot handshake
in `packages/runtime/src/app-plugin.ts` refuses a range that excludes
the runtime major (`OS_PROTOCOL_INCOMPATIBLE`, 422), so a config copied
from the skill failed to boot on 18.x. The scaffold
(`create-objectstack`) and every example app already write `'^18'`.

Landing point — the three sites the card names, plus one sibling line in
the same eval file:

- `skills/objectstack-platform/SKILL.md` L142: `'^17'` → `'^18'`.
- `skills/objectstack-platform/evals/config-plugins-ops.json` L7
(expected output): `'^17'` → `'^18'`; and L6 (the eval prompt) `targets
protocol 17` → `targets protocol 18`, so the eval stays internally
consistent — a prompt asking for 17 with an expected output of `'^18'`
would grade a correct answer wrong. Same file, same byte length, no
extra line.
- `skills/objectstack-upgrade/SKILL.md` L89: the sentence stating what
every scaffold and example writes now says `'^18'`, which is what they
write. The `'^17'` → `--from 17` worked example on L91 is unchanged on
purpose: it demonstrates taking the floor of a range, and `--from 17` is
a real upgrade path.
- `.changeset/25671-skills-protocol-caret.md`: `@objectstack/skills`
patch.

Acceptance check from the card: `git grep -n "protocol: '\^17'" skills/`
at head `401e0bc0` returns only
`skills/objectstack-upgrade/SKILL.md:91`, the worked upgrade example.

## Published-skills readings (lines · tokens as `ceil(utf8 bytes / 4)`,
`origin/main` `b2909fd4` → head `401e0bc0`)

Per changed file, before → after:

- `skills/objectstack-platform/SKILL.md`: 488 lines · 5826 tokens → 488
· 5826
- `skills/objectstack-platform/evals/config-plugins-ops.json`: 65 · 1211
→ 65 · 1211
- `skills/objectstack-upgrade/SKILL.md`: 483 · 6176 → 483 · 6176

Whole bundle (sum of every `skills/*/SKILL.md`): 4389 lines · 52625
tokens → 4389 · 52625. Whole `skills/` tree: 13355 · 157586 → 13355 ·
157586. Net line budget for `skills/**`: 0 added, 0 removed (4 lines
rewritten in place at equal byte length). `check-skills-token-ratchet`
verdict at head: `54 authored bundle file(s) within their ceilings`.

## 维护者速读(草稿)

**改了什么:** 对外发布的 `objectstack-platform` 技能里,`defineStack` 示例的
`engines.protocol` 从 `'^17'` 改为 `'^18'`;同一技能的 eval 用例(提示词与期望输出一起)同步到
18;`objectstack-upgrade` 里「脚手架和示例都写 `'^17'`」这句改为
`'^18'`,与脚手架实际写入一致。`'^17'` → `--from 17` 的升级演算示例保留不动。附一个
`@objectstack/skills` patch changeset。

**为什么改:** 当前运行时协议版本是 18.0.0,启动握手会拒绝排除了 18
的范围(`OS_PROTOCOL_INCOMPATIBLE`)。客户项目从技能文本照抄配置,一启动就失败;脚手架与所有示例早已写
`'^18'`,只有技能文本落后了一个大版本。

**风险与代价(含回滚):** 纯文档与 eval 文本,运行时零改动;四行等长替换,技能包的行数与 token 计数前后完全不变。回滚即
revert 本 PR;唯一代价是客户项目再次拿到会启动失败的示例。

**席位意见:**

**你要做的:** `skills/**` 为 Tier H,本 PR 保持 draft 等待授权审批;审批后由席位落地。

## Acceptance notes

- No gate catches this class today: `check:skill-compatibility` reads
only the frontmatter, and nothing cross-checks a `protocol:` literal in
skill prose against `PROTOCOL_VERSION`. Noted, not filed: a read-only
observation with no reproduced wrong answer beyond this card's; carrier:
none.
- The eval prompt edit (L6) is the one line outside the three the card
names. Omitting it would have left the eval asking for protocol 17 and
expecting `'^18'`.
- `check:doc-formula-expressions` first answered exit 3 (`PREREQUISITE
NOT MET`: `@objectstack/formula` and `@objectstack/lint` unbuilt in a
fresh worktree). After `turbo run build --filter=@objectstack/formula
--filter=@objectstack/lint` under the verify lock it answered exit 0
(`23 record-scoped formula example(s) across 478 files judged clean`).
The 3 was never a finding.

## Gates (local subset at head `401e0bc0`; exit codes captured before
any pipe)

`dispatch-gates --commands --repo objectstack-ai/objectstack` derived 47
families for this diff. 43 ran locally, every one exit 0, among them:
`node scripts/check-skills-token-ratchet.mjs` (and `--self-test`), `pnpm
--filter @objectstack/spec run check:skill-docs` (`Skill docs in sync`),
`pnpm check:skill-frame-sync`, `pnpm check:skill-identifier-liveness`,
`pnpm check:skill-compatibility`, `pnpm check:skill-top-level-keys`,
`pnpm check:pm-skill-id-lint`, `pnpm check:role-word`, `pnpm
check:doc-authoring`, `pnpm check:corpus-claim-drift`, `pnpm
check:nul-bytes`, `pnpm check:merge-driver`, `pnpm
check:published-files`, `pnpm check:pm-governed-merges`,
`check-adr-0087-registration`, `check-changeset-no-major`,
`check-empty-changeset`, `pnpm check:changeset-gate-self-tests`, `pnpm
--filter @objectstack/lint run check:doc-formula-expressions`.

Declared to CI, not run locally (4 of 47, matched only through the
`Build Core` job path filter in `ci.yml`, none of them reads a
`skills/**` file, each needs a full core build): `pnpm
check:dts-closure`, `pnpm check:dual-build-cjs-loads`, `pnpm
check:lean-entry-closure`, `pnpm check:sourcemap-no-sources-content`.
`--ran` reconciliation: `47 derived, 43 run, 0 NOT-MEASURED, 4 UNRUN`
naming exactly those four. `test:repo` and the full lint farm are CI's.

No package build or test closure is owed: the diff touches no workspace
package source.

---
_Generated by [Claude
Code](https://claude.ai/code/session_014FZ3TJucS1L7BdMe5DAzXC)_

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

Author: objectstack-fleet[bot]

.changeset/25671-skills-protocol-caret.md

@@ -0,0 +1,10 @@
+---
+'@objectstack/skills': patch
+---
+
+docs(skills): the objectstack-platform stack-config example declares `engines: { protocol: '^18' }`, the major the 18.x boot handshake accepts
+
+Clause-②: no
+Metadata-protocol: none
+
+`objectstack-platform/SKILL.md` taught `engines: { protocol: '^17' }` in its `defineStack` manifest example while `PROTOCOL_VERSION` is `18.0.0`, so a config copied from the skill was refused at boot (`OS_PROTOCOL_INCOMPATIBLE`). The example, the eval that pins it (`evals/config-plugins-ops.json`, prompt and expected output together) and the `objectstack-upgrade` sentence describing what the scaffold writes now all say `'^18'`, matching `create-objectstack` and every example app. The `'^17'` → `--from 17` worked example in `objectstack-upgrade` is unchanged.

skills/objectstack-platform/SKILL.md

@@ -139,7 +139,7 @@ manifest: {
   type: 'app',                  // app | plugin | driver | module | ...
   name: 'Acme CRM',             // Human-readable display name
   description: 'CRM system',    // Optional description
-  engines: { protocol: '^17' }, // Metadata-protocol major this app targets
+  engines: { protocol: '^18' }, // Metadata-protocol major this app targets
 }
 ```
 

skills/objectstack-platform/evals/config-plugins-ops.json

@@ -3,8 +3,8 @@
   "evals": [
     {
       "id": 1,
-      "prompt": "Write `objectstack.config.ts` for our CRM app: objects, views and flows live under src/, the package namespace is `crm`, and it targets protocol 17.",
-      "expected_output": "A `defineStack` whose `manifest` carries `id`, `version`, `type: 'app'`, `name`, `namespace: 'crm'` and `engines: { protocol: '^17' }`, with barrel imports and `objects: Object.values(objects)` (same for `views` / `flows`). Object names carry the prefix in `name` (`crm_account`) — no object-level `namespace`, no `tableName`. No driver in `plugins:` (the CLI resolves it from the DB URL) and no `workflows` / `approvals` top-level keys (refused at load).",
+      "prompt": "Write `objectstack.config.ts` for our CRM app: objects, views and flows live under src/, the package namespace is `crm`, and it targets protocol 18.",
+      "expected_output": "A `defineStack` whose `manifest` carries `id`, `version`, `type: 'app'`, `name`, `namespace: 'crm'` and `engines: { protocol: '^18' }`, with barrel imports and `objects: Object.values(objects)` (same for `views` / `flows`). Object names carry the prefix in `name` (`crm_account`) — no object-level `namespace`, no `tableName`. No driver in `plugins:` (the CLI resolves it from the DB URL) and no `workflows` / `approvals` top-level keys (refused at load).",
       "files": [],
       "assertions": {
         "must_contain": ["defineStack", "manifest", "engines", "Object.values("],

skills/objectstack-upgrade/SKILL.md

@@ -86,7 +86,7 @@ one installed. Three sources, in order of authority:
 
 1. **`manifest.engines.protocol`** in the stack config — the declared answer,
    checked by the boot handshake. It is a **range**, not a version: every
-   scaffold and example writes the caret form (`engines: { protocol: '^17' }`),
+   scaffold and example writes the caret form (`engines: { protocol: '^18' }`),
    and an exact `'16.0.0'` is only a range of one. Take the major it *targets* —
    the floor: `'^17'` → `--from 17`, `'>=15 <18'` → `--from 15`, never the
    upper bound.