docs(skills): objectstack-upgrade's late-arrival example starts at the support floor

[objectstack-fleet]

Fixes #22123

Clause-②: no

The published upgrade skill's "several majors late" paragraph examples os migrate meta --from 10. The chain refuses every --from below MIGRATION_SUPPORT_FLOOR = 16 (packages/spec/src/migrations/registry.ts:79) with MigrationFloorError — exit 1, --json error: unsupported_from_major — and the same file's failure-mode row already says so. This PR rewords the paragraph so its point (lateness is the designed-for case) is stated with an example the chain accepts and with the floor in the same breath, within the file's token ceiling. #22120 is landed (PR #22122, same file); this branch cuts from origin/main after it.

What changed (one file: skills/objectstack-upgrade/SKILL.md)

The paragraph under §0 "Establish the FROM major", before:

Arriving several majors late is the designed-for case. `os migrate meta --from 10`
replays every step in order; there is no penalty for lateness and no requirement
to upgrade one major at a time.

after:

Arriving several majors late is the designed-for case: `os migrate meta --from 16`
replays every step in order, with no requirement to upgrade one major at a time —
down to the chain's support floor, 16 today. Below the floor, upgrade to it by
the older route first, then run the chain.

The example is now the floor itself (the chain's lowest accepted --from, and the spelling every other example in the file already uses); the floor's value is stated where the reader decides --from; the below-floor case carries the same remedy the failure-mode row and the CLI's own refusal text give ("Upgrade to protocol 16 by another path first, then re-run"). "There is no penalty for lateness" is dropped as restating "the designed-for case". Nothing else in the file states a --from below 16: grep -rn -F -- '--from 10' skills/objectstack-upgrade/ is now 0 hits (control: --from 16 12 hits in SKILL.md), and references/examples-upgrade.md and evals/protocol-major-upgrade.json never carried the example.

Token ratchet — paid in content, not wrapping

node scripts/check-skills-token-ratchet.mjs (tokens = ceil(utf8 bytes / 4); ceiling for this file 6193):

reading	lines	bytes	tokens	headroom
before (ef1fcb26a2, the file as #22122 left it)	484	24748	6187	6
after (3e842f9fd8)	485	24736	6184	9

Whole package (the ten skills/*/SKILL.md): 4407 → 4408 lines, 52575 → 52572 tokens; the ratchet's authored-bundle total 144050 → 144047 (shipped tree 154836 → 154833). Diff: +6 / −5 lines. Gate line at 3e842f9fd8: ✓ check-skills-token-ratchet: skills/objectstack-upgrade/SKILL.md is 6184 tokens (ceiling 6193; headroom 9).

The paragraph grew by +94 bytes (197 → 291). That is paid by deleting two clauses the same file states beside them — no rule, failure-mode row or command among them, and no line re-wrapped:

1. the trailing comment on mkdir -p .upgrade in §0's "Make the work reviewable" block ("every artifact this skill produces lands here", −57 bytes) — the paragraph directly under the block opens "The .upgrade/ directory is the deliverable's workspace" and lists the artifacts;
2. the clause "which is exactly what the table above points at" closing §2.1's "Not reachable from a consumer project" callout (−49 bytes) — the callout's sentence already names spec-changes.json and the chain's --json output, which are two rows of that table.

Net −12 bytes.

Scope held

• One file, as the claim's file surface allows. No packages/spec/**, no packages/cli/**, no content/docs/**; references/examples-upgrade.md and evals/protocol-major-upgrade.json untouched (neither carries the example; the eval's must_contain is os migrate meta --from 16, which still holds). Frontmatter unchanged: check:skill-docs and check:skill-refs green ("Skill docs in sync", "9 generated files in sync").
• The floor's value is written as "16 today" the way the file already writes --from 16, ^17 and "The 16 → 17 crossing"; the frontmatter's compatibility line keeps the general statement ("the chain replays from the spec's MIGRATION_SUPPORT_FLOOR"), and §2.1's reading prints supportFloor from the installed spec. When the floor moves, this sentence is one of the file's dated numbers, not the only one.

Gates

Derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack on this tree (24 families at ef1fcb26a2 and again at 3e842f9fd8; identical to the PM's path-derived list). All 24 run, exit 0 each, recorded beside the printed command and reconciled with --ran ("24 derived, 24 run, 0 NOT-MEASURED, 0 UNRUN", a derived zero). check:doc-formula-expressions first exited 3 (prerequisite: @objectstack/formula and @objectstack/lint not built) and was re-run green after the prescribed build under the verify lock. Beyond the derived list, also green: check:skill-top-level-keys, check:skill-frame-freshness, check:skill-refs. NOT MEASURED: check:skill-examples (prerequisite: the client SDK dist is not built; outside the derived list, and this diff touches no SDK example).

Acceptance notes

• Observation, not changed and not a card: neither this skill nor the CLI's refusal text names what "the older route" / "another path" is for a project below the floor (install the spec major that still reaches it and run its chain, then continue from 16). The refusal is loud and the remedy's direction is stated; naming the route is a product sentence for the maintainer, not a drift fix. Carrier: none.

维护者速读(草稿)

改了什么:只改一份对外发布的技能文件 skills/objectstack-upgrade/SKILL.md 的一个段落。原文以 os migrate meta --from 10 作为"晚几个大版本再升级也没关系"的示例,但迁移链的支持下限是 16(MIGRATION_SUPPORT_FLOOR = 16),--from 10 会被 CLI 直接拒绝(MigrationFloorError,退出码 1)。现在示例改为链接受的 --from 16,同一句话里说明下限(今天是 16),并告诉低于下限的项目先用旧路线升到 16 再跑链——与同一文件故障表里已有的那一行一致。

为什么改:这份技能随每次 npx skills add 整包进入客户项目的 agent 上下文;一句教人运行会被拒绝的命令的话,是发布面上的错误句子(NORTH-STAR「优先级」第 4 条)。CLI 的拒绝挡住了实际伤害,但文字不改就一直是错的。

风险与代价(含回滚):纯文本改动,无代码、无 changeset、无生成物变化。token 棘轮:6187 → 6184(上限 6193),净减 12 字节,靠删除两处紧邻处已有陈述的重复子句支付(一处代码块尾注,一处收尾从句),未删任何规则、故障行或命令,未折行。回滚即 revert 本 PR 的一个提交。注意:下限值"16"写成了具体数字,与文件里其它写死的 --from 16、^17 同样随下限移动而需要更新;frontmatter 与 §2.1 的读数保留了通用表述。

席位意见:(留空,席位定稿)

你要做的:skills/** 为 Tier H 受管面:请以授权账号 APPROVE 一次,或亲手合入;本 PR 保持 draft,不由 agent 翻 ready。

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 3e842f9fd8f667f2b22066787d69fd1db6b53694
Local-runs: none

Reviewed in-seat by the skills seat 1 (dispatching seat; this session is served at the contract-review tier, read off get_session), 2026-10-08T03:12Z. Face hit: governed rule text (skills/objectstack-upgrade/SKILL.md, Tier H). Read-only shape held: the diff (get_files = 1 file, +6/−5), the card #22123 and its thread, the head's check-runs; nothing built or run locally. Premises re-read on origin/main at ef1fcb26a2, not taken from the report.

① Derived judgments

1. Example os migrate meta --from 10 → --from 16: correct. MIGRATION_SUPPORT_FLOOR = 16 (packages/spec/src/migrations/registry.ts:79); the chain refuses every --from below it (packages/spec/src/migrations/chain.ts:177-178: "Cannot migrate from protocol N: the chain's support floor is 16 (ADR-0087 D3). Upgrade to protocol 16 by another path first, then re-run."; packages/cli/src/commands/migrate/meta.ts:975 emits unsupported_from_major). 16 is the lowest accepted value and the spelling the file's other eleven --from 16 occurrences use; the eval must_contain os migrate meta --from 16 still holds.
2. "down to the chain's support floor, 16 today": correct and consistent with the file's existing dated numbers (--from 16, ^17, "The 16 → 17 crossing"); the frontmatter compatibility line keeps the general statement and §2.1 prints supportFloor from the installed spec. The sentence is one more dated number, not the only one.
3. "Below the floor, upgrade to it by the older route first, then run the chain": correct, the same remedy direction as the failure-mode row at SKILL.md:472 (MigrationFloorError) and the CLI's own refusal text. Neither names the route; that observation is the dev's and stays a note (below).
4. Dropped "there is no penalty for lateness": correct, it restated "the designed-for case" in the same sentence; no rule, command or failure row lost.
5. Ratchet payment, clause 1: the trailing comment on mkdir -p .upgrade ("every artifact this skill produces lands here", −57 bytes). Survives in the paragraph directly under the block (head :115, "The .upgrade/ directory is the deliverable's workspace", listing the artefacts). Nothing lost.
6. Ratchet payment, clause 2: "which is exactly what the table above points at" closing §2.1's "Not reachable from a consumer project" callout (−49 bytes). Survives: the callout's sentence still names spec-changes.json and the chain's --json output (head :247), the two rows the clause pointed at. Nothing lost. No line re-wrapped: the diff is +6/−5 inside three hunks, each a content edit.
7. Ratchet reading pinned to the head: 6187 → 6184 tokens, ceiling 6193, headroom 6 → 9; the PR body quotes the gate line at 3e842f9fd8. The CI reading is the Lint & Repo Gates job on this head (status at this record's clock recorded in the ACCEPT on skills(objectstack-upgrade): the "several majors late" paragraph still examples os migrate meta --from 10, which the chain refuses below MIGRATION_SUPPORT_FLOOR = 16 (MigrationFloorError) #22123; landing waits on it being success either way).
8. The one other --from below 16 in the published skills, SKILL.md:93 (the range example whose lower bound is 15 and upper bound 18, derived to --from 15): not this defect's class, untouched and judged correct as is. The line teaches range arithmetic (take the lower bound, never the upper), not that the chain accepts 15; the reworded paragraph two lines below now gives the below-floor case its remedy. The PR body's sentence "Nothing else in the file states a --from below 16" is therefore over-stated (its grep was --from 10 only); corrected in the ACCEPT, mechanism unaffected.
9. Frontmatter unchanged; references/examples-upgrade.md and evals/protocol-major-upgrade.json untouched (neither carried the example). No packages/spec/**, no packages/cli/**, no content/docs/**.

② Semver level

None. Prose-only edit to a published skill file; no package files[] content, no API, no schema. skip-changeset on the PR is the correct declaration for this repository (docs-only), read back on the PR.

③ Boundary flags

• Dev flag (acceptance note): the "older route" below the floor is unnamed in the skill and in the CLI refusal text. Answered: stays a note, not a card. The refusal is loud and states the remedy's direction; naming the route is a product sentence for the maintainer (raised in the seat-opinion section of the maintainer brief comment on this PR), not a drift fix.
• open_questions: none reported.
• Seat flag: judgment 8 above (the :93 illustration) is put to the maintainer in the maintainer brief comment, not ordered; a same-byte swap of that range example to one starting at 16 is available if they want the illustration to use an accepted value too.

Implemented-by: claude/issue-22123-upgrade-skill-late-arrival-floor
Reviewed-by: session_01CXydFDyiQwNbGFkmwrcRQq

VERDICT: PASS

---

Generated by Claude Code

[objectstack-fleet]

维护者速读(终稿)

席位:skills 席 1,session_01CXydFDyiQwNbGFkmwrcRQq,2026-10-08T03:13Z。对照席位自己读的 diff(head 3e842f9fd8,一个文件 +6/−5)校正 dev 草稿;契约复核记录(PASS)与 ACCEPT 见本 PR 上一条评论与卡片 #22123。

改了什么:只改对外发布的技能文件 skills/objectstack-upgrade/SKILL.md 里 §0 的一个段落。原文以 os migrate meta --from 10 作"晚几个大版本再升级也没关系"的示例;但迁移链的支持下限是 16(MIGRATION_SUPPORT_FLOOR = 16,packages/spec/src/migrations/registry.ts:79),--from 10 会被 CLI 直接拒绝(MigrationFloorError,退出码 1,--json 报 unsupported_from_major)。现在示例改为链接受的 --from 16,同一句话里写明下限"今天是 16",并告诉低于下限的项目先走旧路线升到 16 再跑链——与同文件故障表里已有的那一行(:472)和 CLI 的拒绝文案方向一致。另删了两处紧邻处已有陈述的重复子句(一处代码块尾注、一处收尾从句),用来支付 token 棘轮;席位逐条核过,被删内容在旁边各有一句原样保留(:115、:247),没有丢规则、故障行或命令,也没有折行凑数。

为什么改:这份技能随 npx skills add 整包进入客户项目的 agent 上下文;一句教人运行会被拒绝的命令的话,是发布面上的错误句子(NORTH-STAR「优先级」第 4 条)。CLI 的拒绝挡住了实际伤害,但文字不改就一直是错的。

风险与代价(含回滚):纯文本改动,无代码、无 changeset(skip-changeset,docs-only)、无生成物变化;frontmatter 未动,check:skill-docs/check:skill-refs 在 head 的 Lint & Repo Gates 里已绿。棘轮读数 6187 → 6184(上限 6193,余量 6 → 9),净减 12 字节。回滚即 revert 本 PR 的单个提交。注意:下限值"16"写成了具体数字,与文件里其它写死的 --from 16、^17、"16 → 17" 同样随下限移动而需一并更新;frontmatter 与 §2.1 的读数保留了通用表述,所以它不是唯一一处。

席位意见:同意合入,席内契约复核 PASS。两点留给维护者,均未下令、不阻塞:① 同文件 :93 的范围推导示例(下界 15、上界 18 的区间)取下界得 --from 15,也低于下限;席位判它教的是"取区间下界"的算法而非"链接受 15",且新段落紧随其后已给出低于下限时的做法,故原样保留。若你希望发布面上不再出现任何低于下限的 --from 示例,把区间改成从 16 起是同字节数的一字之换,可让席位补一轮。② 技能与 CLI 拒绝文案都只说"先用旧路线/另一条路升到 16",没有点名那条路是什么(装仍覆盖该版本的 spec 大版本并跑它的链,再从 16 继续);这是产品句子,由你定是否写进技能。

你要做的:用授权账号(os-zhuang 或 hotlong)在本 PR 上 APPROVE 一次,或亲手合入。PR 保持 draft 不由 agent 翻 ready;收到授权 APPROVED 后由本席按落地前检翻 ready、挂 auto-merge 入队并收口 #22123。

---

Generated by Claude Code