Repository navigation
Commit aaa4ad2
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
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
100 | 100 | | |
101 | 101 | | |
102 | 102 | | |
103 | | - | |
104 | | - | |
105 | | - | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
106 | 107 | | |
107 | 108 | | |
108 | 109 | | |
109 | 110 | | |
110 | 111 | | |
111 | | - | |
| 112 | + | |
112 | 113 | | |
113 | 114 | | |
114 | 115 | | |
| |||
244 | 245 | | |
245 | 246 | | |
246 | 247 | | |
247 | | - | |
| 248 | + | |
248 | 249 | | |
249 | 250 | | |
250 | 251 | | |
| |||
0 commit comments