skills(upgrade): optimization flight — the stale pinned registry snapshot cut, the rule stated once, --yes and the --stored exit-code contract taught (net −1,134 tokens) (#14465)

* skills(upgrade): cut the stale pinned rc.5 registry snapshot (UPG-D-01, UPG-D-02)

The "v17 prescription set, as of 17.0.0-rc.5" section pinned six readings that
are now wrong against the installed 17.2.0 spec: 45 vs 58 D2 conversions, 29 vs
77 semantic entries, 113-across-32-files vs 179-across-44 retiredKey() sites,
RETIRED_KEYS_BY_MAJOR[17] "3 entries" vs 29, RETIRED_DEFS_BY_MAJOR[17] "1 entry"
vs 53. Nothing in the skill branched on a count, and the section itself told the
reader "the install wins" -- so the pin bought nothing and cost a reader who
trusted it. Its reconciliation rule also pointed the wrong way: it anticipated
only additions, while data/ExternalFieldMapping:transform was REMOVED from the
bucket.

Deleted with it (UPG-D-02): the "why these two tables are short" paragraph,
which narrated the platform's own retirement-registration policy over two files
this same skill declares unreachable from a consumer project.

What survives is the measurement, not the number: the spec-changes.json reading
folded into the 2.1 source table, now deriving the target major from
protocolVersion instead of hardcoding 17, plus a rule against carrying a
remembered count into the report.

Ratchet: 8333 -> 7799 (ceiling 8333).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

* skills(upgrade): state each rule once (UPG-E-04, E-05, D-03..D-08, B-02, B-03, C-01)

Nine findings, all the same shape: a rule the file already states, or prose
re-teaching what the CLI prints for itself.

- E-04/E-05 §3.5 becomes a 3-row outcome -> evidence table; the re-quoted error
  block was already available verbatim from the install. The new probe rule is
  the E-05 fix: `os validate` loads WITHOUT authoredSource (validate.ts:159;
  config.ts:224 "Set by `os migrate meta` only"), so a probe calling `define*`
  throws inside the load and never reaches the gate the recipe is proving.
- D-03 the data-gate table is printed by the run itself (meta.ts:106-141,
  measured: the two `unlocks` strings, the deployment scoping and the dry-run
  sentence are all emitted). Only the non-CLI half survives -- carry each
  printed gate into the report as pending, by name.
- D-07 the three-layers preamble and Layer table; the section headings and the
  pipeline line already are the construct.
- B-02 the Guardrails section: 4 of 6 restated the boundary verbatim and #6
  restated the data-gate rule. The one non-duplicate (one conversionId per
  commit) moves into the boundary; #6 now lives where the gates are printed.
- D-04 the AST-is-lossy rationale, D-05 the 2nd of five statements of
  "replay from the target major", D-06 two bullets restating the paragraph
  above them, D-08 a justification of a template row already in the template,
  B-03 the 3rd copy of the [REMOVED] grep, C-01 routing owned by README and by
  the domain skills' own frontmatter.

B-03 left the .upgrade/ workspace listing a file nothing writes any more; that
list now names retired-names.txt, which 2.6 actually produces.

Ratchet: 7799 -> 6944 (ceiling 8333).

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

* skills(upgrade): teach --yes, the --stored exit contract and the ranged protocol (UPG-E-02, E-03, F-01, F-02, F-03, A-02, G-01)

Five funded additions, each paid by a deletion in the same file, plus the
frontmatter shrink.

- E-02 (falsehood 4) `os migrate meta --stored --apply` was documented as
  "(prompts)". It does not prompt for this skill's reader: meta.ts:501-511
  refuses in any non-TTY -- every agent session -- exiting 1 with
  `confirmation_required`. The CLI's own example list already spells
  `--stored --apply --yes --json`.
- E-03 the ranged `engines.protocol`. The skill's only worked form was an exact
  '16.0.0'; all four real configs (showcase, crm, todo, the blank template)
  write `engines: { protocol: '^17' }`, and template-consistency.test.ts:186
  MECHANICALLY REQUIRES the caret form of every scaffold. Reading rule is the
  range's floor, matching `declaredMajor` ("Major the app's declared
  compatibility range targets", protocol-version-gap.ts) and agreeing with the
  Manifest Reference objectstack-platform's delivered flight teaches.
- F-01 the `--stored` exit contract (meta.ts:577-578, 621; documented at
  :451-453) becomes a 3.6: exit 0 = every row canonical, 1 = work left, which
  is what makes "this deployment is on protocol N" a CI check.
- F-02 the five stable `--json` error codes an agent branches on
  (meta.ts:262, 279, 414, 477, 504).
- F-03 the positional config path (meta.ts:191-193) -- a monorepo with more
  than one stack could not follow the skill as written.
- A-02 drops the two "do not use" clauses that route nowhere a customer can go
  (an internal playbook outside the published catalog, and a body rule restated
  in the trigger) and adds the real one: physical DB drift is platform's job.
- G-01 compatibility becomes one line like the nine domain siblings. The phrase
  "at the TARGET major" is kept verbatim ON PURPOSE: it is the warrant for this
  file's exemption in check-skill-compatibility-version.mjs, whose rationale
  regex dies with the text. The "protocol 10 at the time of writing" hedge is
  gone rather than restated -- after D-01 the frontmatter was the last rottable
  copy of that constant.

Ratchet: 6944 -> 7199 (ceiling 8333). Net for the flight so far: 8333 -> 7199.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

* skills(upgrade): regenerate skills-reference.mdx after the frontmatter shrink

Generator output only (`pnpm --filter @objectstack/spec gen:skill-docs`), forced
by check:skill-docs, which was red on this file and named the command.

skills/README.md regenerated byte-identical -- it does not carry the description
prose -- so this flight's whole file surface is SKILL.md plus this one line.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1

---------

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

Author: os-litant

content/docs/ai/skills-reference.mdx

@@ -205,7 +205,7 @@ Upgrade an ObjectStack metadata project across a protocol major — run the dete
 
 Use when a project is on an older protocol major and must move to the current one, when `@objectstack/spec` was bumped across a major and metadata or code stopped parsing, when a parse or `tsc` error quotes a `[REMOVED]` prescription, or when asked to "upgrade to v17" / "升级到 v17" / "一键升级元数据项目".
 
-Do not use to author new metadata (the domain skills cover that), to design a retirement in the ObjectStack platform repo itself (that is the platform's own internal playbook), or to hand-write a rewrite the conversion chain already applies — running the chain is always the first step, never a fallback.
+Do not use to author new metadata (the domain skills cover that), or to reconcile physical database drift (that is objectstack-platform's `os migrate plan` / `os migrate apply`).
 
 **Tags:** `upgrade`, `migration`, `protocol`, `major`, `retired-keys`, `tombstone`, `conversions`, `validate`, `report`