Skip to content

Commit aaa4ad2

Browse files
docs(skills): objectstack-upgrade's late-arrival example starts at the support floor (#22145)
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: ```text 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: ```text 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](https://claude.ai/code/session_01CXydFDyiQwNbGFkmwrcRQq)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent dc759f2 commit aaa4ad2

1 file changed

Lines changed: 6 additions & 5 deletions

File tree

‎skills/objectstack-upgrade/SKILL.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -100,15 +100,16 @@ one installed. Three sources, in order of authority:
100100
default to the lower one: a default flip ([3.3](#33-validate)) stamps its
101101
constraint onto a source already past that major.
102102

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

107108
### Make the work reviewable before you change anything
108109

109110
```bash
110111
git checkout -b upgrade/protocol-17
111-
mkdir -p .upgrade # every artifact this skill produces lands here
112+
mkdir -p .upgrade
112113
```
113114

114115
The `.upgrade/` directory is the deliverable's workspace: the machine outputs
@@ -244,7 +245,7 @@ upgrade and again in the report.
244245
> `src/migrations/registry.ts`) and the platform repo's generated upgrade guide
245246
> are **not** in the published package — only `src/**/*.zod.ts` is. Their
246247
> consumer-facing projection is `spec-changes.json` and the chain's own `--json`
247-
> output, which is exactly what the table above points at.
248+
> output.
248249
249250
### 2.2 The three residue classes
250251

0 commit comments

Comments
 (0)