Skills optimization flight — skills/objectstack-upgrade: DIET (≈ −1,808 tok, −22%) — a stale pinned `17.0.0-rc.5` registry snapshot (drift 29–165%), one rule stated five times, and a `--stored --apply` command that exits 1 for every agent reader because it omits `--yes`

[os-litant]

Member card of the skills catalog optimization program #14292 (maintainer mandate 2026-09-02, verbatim: 「审核所有的 skills，进行全面的优化。」). Filed by the skills lane seat (session session_01LraLgQVGq8egUwfYZpbYt1). Read-only audit at objectstack origin/main a59f78d. Full findings table = audit record: the dev posts audit/objectstack-upgrade/findings.md (seat scratchpad) verbatim as the first comment at claim time.

Audit summary

One file, 693 lines, 8,333 tokens, headroom 0 (4.4% of the bundle). Command surface verified accurate against packages/cli/src/commands/migrate/meta.ts (every flag, printed line, --json shape, MIGRATION_SUPPORT_FLOOR = 10, both applyConversionsToStoredItem seams). One TS fence, marked, symbols live — zero rot. Eight decision-changing surfaces at ≈1,040 tok each for a job run once per major. Verdict DIET: structure sound; oversized by a stale pinned registry snapshot, a triple-stated rule set, and prose re-teaching what the CLI already prints.

Top findings

#	id · span · proposal	Δtok
1	UPG-D-01 · SKILL.md:554-617 · DELETE the pinned "v17 prescription set" + refresh block; keep the two re-measure commands in §2.1	−600
2	UPG-E-04 · :509-553 · REWRITE-AS-CONSTRUCT — 3-row outcome→evidence table replaces §3.5's prose	−280
3	UPG-D-07 · :33-47 · DELETE the "upgrade agent"/three-layers preamble + Layer table; keep the pipeline line at L38	−190
4	UPG-D-03 · :214-227 · REWRITE-AS-CONSTRUCT — the CLI prints this itself (meta.ts:106-124, 137-141)	−180
5	UPG-B-02 · :669-683 → :49-70 · MERGE — 4 of 6 Guardrails restate the ⛔ Boundary (keep all six rules in the target)	−170
6	UPG-D-05 · :182-183, :543-547 · DELETE — "validate green ≠ done" is stated 5×	−120
7	UPG-D-04 · :169-174 · DELETE the AST-is-lossy rationale; keep "--out is the oracle"	−110
8	UPG-C-01 · :684-693 · MERGE-INTO skills/README.md:94-110 (delete here)	−70
9	UPG-B-03 · :88, :608 · DELETE — the same [REMOVED] grep appears 4×	−60
10	UPG-D-06 · :194-199 · DELETE the two "what that does and does not mean" bullets	−60
11	UPG-A-02 · :12-17 · REWRITE — frontmatter is 390 tok, largest of all 11 packages	−60
12	UPG-D-08 · :505-508 · DELETE "Section 5 earns its place…"	−43
13	UPG-G-01 · :19-24 · REWRITE compatibility to one line like the nine domain siblings	−40
14	UPG-F-02 · :656-668 · ADD a --json error column to the failure-modes table (meta.ts:262, 279, 414, 477, 504)	+50
15	UPG-F-01 · absent · ADD the --stored exit-code contract (meta.ts:449-454, 577-578, 621) to §3 acceptance	+40

Net −1,808 on 8,333 = −21.7% (−1,983 / +175).

Incidental falsehoods (fix in this flight)

1. :565-567 — counts pinned at 17.0.0-rc.5 ("45 D2 conversions", "29 D3", "113 tombstones across 32 files") vs measured at 17.2.0: 58 converted / 77 migrated (spec-changes.json), 179 retiredKey( sites across 44 files.
2. :570-577 — "RETIRED_KEYS_BY_MAJOR[17] (3 entries)": registry.ts:7961-8195 holds 29, and one of the three listed is gone; the reconciliation rule (:612-613) points the wrong direction for a removal.
3. :579-582 — "RETIRED_DEFS_BY_MAJOR[17] (1 entry)": registry.ts:9370-9510 holds 53.
4. :205 — os migrate meta --stored --apply # rewrite the rows (prompts): meta.ts:500-511 exits 1 with confirmation_required in any non-TTY (every agent session); the CLI's own example is --stored --apply --yes --json.
5. :517-535 — the reverse-check recipe is illustrated as producing the clean schema-gate refusal, but os validate loads without authoredSource (validate.ts:159; config.ts:220-228 "Set by os migrate meta only"): a config calling define* throws inside the load; the probe must be a plain data literal.

Boundary leak: :570-591 explains the platform's own registration policy for the two registries a customer cannot read (.claude/skills/spec-property-retirement territory) — delete with UPG-D-01.

Three funded additions

1. --yes on :205 (UPG-E-02, +8, paid by UPG-D-08) — the one durable-rehydration command currently fails for every reader of this skill.
2. --stored exit-code contract (UPG-F-01, +40, paid by UPG-D-04) — "my metadata is on protocol N" becomes a CI check instead of a belief.
3. The ranged engines.protocol case (UPG-E-03, +30, paid by UPG-D-06) — every real config writes engines: { protocol: '^17' } (showcase/crm/todo) while the skill's only worked form is an exact '16.0.0'.

Flight scope

IMPLEMENT (same-file, shrink-only): rows 1–15 and the findings file at HIGH or MED; falsehoods 1–5; the boundary-leak deletion; UPG-A-02 / UPG-G-01 frontmatter shrink (regenerate the README index only if a drift gate requires it).

DEFER: UPG-H-01 (new evals file, #14296 item 2); UPG-A-01 (edits to skills/objectstack-platform/SKILL.md description and skills/README.md routing — record under "follow-up for" in the PR body; the platform flight #14299 owns that file).

Flight constraints (binding)

• ONE draft PR, first line Fixes #<this card>; governed ⇒ stays draft; review requests are the seat's step.
• Token ratchet: SKILL.md may not grow; additions paid by deletions in the same file; ⛔ re-wrap is not payment; ⛔ no ceiling raise; ⛔ no new files; ⛔ do not touch the ratchet script.
• ⛔ Never edit another package's files or the internal playbook .claude/skills/spec-property-retirement/SKILL.md (read it only for the boundary).
• Gates: node scripts/check-skills-token-ratchet.mjs, pnpm --filter @objectstack/spec check:skill-examples, pnpm check:skill-compatibility, pnpm check:skill-identifier-liveness, plus node scripts/pm/dispatch-gates.mjs --commands <changed paths>; record the head sha.
• PR body: per-item 落点 | before | after keyed by finding id; token delta; needs:contract-review on both carriers (the exit-code contract and the --yes semantics are CLI contract claims).

Refs: #14292 · #14296 · #13658.

[os-litant]

Claim: PM loop round 3
Session: session_01LraLgQVGq8egUwfYZpbYt1
Branch: claude/issue-14307-skills-upgrade-optimization
Worktree: objectstack-issue-14307
Domain: domain:skills
File surface: skills/objectstack-upgrade/SKILL.md ONLY (shrink-only; ceiling 8,333, headroom 0); no file deleted ⇒ ⛔ no edit to scripts/check-skills-token-ratchet.mjs; skills/README.md + content/docs/ai/skills-reference.mdx regenerated only because the drift gate demands it after the UPG-A-02 / UPG-G-01 frontmatter shrink; ⛔ skills/objectstack-platform/SKILL.md and skills/README.md prose untouched (UPG-A-01 deferred → PR-body follow-up); ⛔ .claude/skills/spec-property-retirement/SKILL.md read-only (the boundary oracle); ⛔ no other package (stop on breach; explain in the report)
Container & model: S/M (one 8,333-token file, 693 lines; five falsehoods against the CLI + registry at 17.2.0), mode:subagent, model: opus — --tier reads no path-derived mandate (floor sonnet · default opus · ceiling fable); the content limb applies, compensated by the seat's in-seat review at CONTRACT_REVIEW_TIER (served model read claude-fable-5-1)
Clause-②: yes — the --stored exit-code contract, --yes non-TTY semantics (confirmation_required), the --json error column and the ranged engines.protocol case are CLI / manifest contract claims ⇒ needs:contract-review on both carriers at PR creation; in-seat review before any human review request
Serial constraints cleared: objectstack-platform's delivered flight (PR #14351) teaches manifest.engines.protocol in its Manifest Reference — the ranged case taught here must agree with that row (verify on origin/claude/issue-14299-skills-platform-optimization); skills/objectstack-upgrade/** byte-identical between a59f78d and origin/main a98b61b3 (seat-measured 07:3xZ); no open PR touches this package; in flight alongside #14305 (ai) and #14308 (automation) on disjoint directories, with #14302 (query) in its patch round

Decision re-read: no maintainer ruling on this card; binding inputs = the mandate, the value gate, the ratchet discipline, and #14296 (item 2 deferred: UPG-H-01 new evals file). Landing form: first line Part of #14307 (the deferred evals file keeps the card open).

---

Generated by Claude Code

[os-litant]

Claim (dev): starting implementation.

Session: session_01LraLgQVGq8egUwfYZpbYt1 (the harness hands this dev seat the same session id the PM claim carries — noting it rather than inventing a different one)
Branch: claude/issue-14307-skills-upgrade-optimization (pushed empty at claim time; base origin/main a98b61b)
Worktree: ../objectstack-issue-14307
Assignee: untouched (PM owns it).

File surface I will edit: skills/objectstack-upgrade/SKILL.md only, plus skills/README.md and content/docs/ai/skills-reference.mdx strictly as generator output from pnpm --filter @objectstack/spec gen:skill-docs after the UPG-A-02 / UPG-G-01 frontmatter shrink. Read-only: .claude/skills/spec-property-retirement/SKILL.md (boundary oracle), skills/objectstack-platform/SKILL.md (UPG-A-01 deferred to a PR-body follow-up), scripts/check-skills-token-ratchet.mjs.

Landing form: ONE draft PR against main, first line Part of #14307 — the dispatch ruling overrides the card body's "first line Fixes" line, because UPG-H-01 (the evals/ file) is deferred to #14296 item 2 and the card must stay open. needs:contract-review on both carriers at PR creation.

Next comment on this card: the full read-only audit record verbatim, first line audit-record — skills/objectstack-upgrade (read-only audit at a59f78d).

---

Generated by Claude Code

[os-litant]

audit-record — skills/objectstack-upgrade (read-only audit at a59f78d)

Transliteration key. The GitHub body sanitizer is measured to eat angle-bracket-shaped
fragments (even inside backticks), so the 3 such spans in the source file are respelled
below. Read them back as:

• PROBE → the placeholder spelled probe wrapped in angle brackets (in os validate PROBE)
• N in --from N → the placeholder spelled N wrapped in angle brackets
• OS-CHECK-MARKER → the HTML comment whose content is os:check (comment-open, os:check, comment-close)

Everything else below is the audit file verbatim.

---

Audit — skills/objectstack-upgrade/ (published)

Pinned ref: objectstack origin/main = a59f78d. (Working checkout HEAD is a39b02a;
git diff --stat a39b02a a59f78d -- skills/ packages/cli packages/spec is empty, so every
span below is identical at the pinned ref.)

Package: 1 file, SKILL.md, 693 lines / 33,331 bytes.
Ratchet: skills/objectstack-upgrade/SKILL.md is 8333 tokens (ceiling 8333; headroom 0) —
4.4% of the bundle total (whole shipped tree) 187854.
No rules/, no references/, no evals/, no contracts/.

---

Findings

id	dim	file:span	evidence (measured / quoted)	proposal	Δtok	gate ① decision-changing? ② deletion instead? ③ construct?	conf	human-floor
UPG-D-01	D	skills/objectstack-upgrade/SKILL.md:554-617 (707 tok)	"The v17 prescription set, as of 17.0.0-rc.5" + "How this table is refreshed". Every number is now measurably wrong against the pinned tree: table says D2 conversions for major 17 45 — packages/spec/spec-changes.json perMajor[to=17].converted.length = 58; D3 semantic entries 29 — .migrated.length = 77; retiredKey() tombstones 113, across 32 files — grep -rho "retiredKey(" packages/spec/src --include='*.zod.ts' | wc -l = 179 across 44 files; RETIRED_KEYS_BY_MAJOR[17] "3 entries" — packages/spec/src/migrations/registry.ts:7961-8195 holds 29 (and data/ExternalFieldMapping:transform, one of the three the skill lists, is gone: registry.ts:7957 "Two of the three remain: data/ExternalFieldMapping:transform left"); RETIRED_DEFS_BY_MAJOR[17] "1 entry" — registry.ts:9370-9510 holds 53. Nothing in the skill reads any of these numbers to make a decision, and SKILL.md:611-615 itself says "the install wins".	DELETE §554-591; keep only the two re-measure commands (SKILL.md:597-609) folded into the §2.1 source table row at SKILL.md:245	−600	① no — no step branches on a count ② yes, deletion IS the fix ③ the surviving construct is §2.1's source table	HIGH	yes
UPG-D-02	D / boundary	SKILL.md:584-591 (134 tok)	"Why these two tables are short and the counts above are not. They record retirements registered under the exact-key gates that created them, which are newer than most of protocol 17's work; they are explicitly not a backfill of every retirement ever." This narrates the platform's own registration policy over two files the skill itself declares unreachable — SKILL.md:258-264: "Not reachable from a consumer project, so do not send anyone there: the conversion and migration registries (src/conversions/registry.ts, src/migrations/registry.ts) … are not in the published package" (confirmed: packages/spec/package.json files = dist, json-schema, liveness, prompts, llms.txt, README.md, src/**/*.zod.ts, CHANGELOG.md, api-surface, spec-changes.json). The same obligation is the internal playbook's §3 (.claude/skills/spec-property-retirement/SKILL.md:164-190, "一条 RETIRED_KEYS_BY_MAJOR 条目,在 packages/spec/src/migrations/registry.ts"). Platform-internal retirement policy in a customer package.	DELETE (subsumed by UPG-D-01)	−134	① no ② yes ③ n/a	HIGH	yes
UPG-E-04	E	SKILL.md:509-553 (407 tok)	§3.5 "Prove the gate is real" spends 407 tok on one recipe plus a 3-outcome list. The decision-changing content is exactly the 3 outcomes ("Record which one you actually got") and the mapping outcome→evidence; the rest is a re-quoted error block already available verbatim from the install (packages/spec/src/shared/mapping.zod.ts:93-105) and restated prose.	REWRITE-AS-CONSTRUCT: 3-row table (outcome · what it means · what your acceptance evidence is) + the one os validate PROBE line	−280	① yes, the outcome table does ② partially ③ yes — table replaces prose	HIGH	no
UPG-D-03	D	SKILL.md:214-227 (235 tok)	"Data migrations are not metadata migrations" re-teaches what the CLI prints for you at the end of every crossing run. packages/cli/src/commands/migrate/meta.ts:106-124 emits the same two unlocks strings ("Until it passes here, media values only warn and released files are kept forever." / "Until it passes here, a malformed value only warns."), and meta.ts:137-141 prints "Both are dry-run by default and report what they would do; --apply is the only writing mode. Not running them is safe — enforcement simply stays off here." — near-verbatim to SKILL.md:223-226. Also gated the same way the skill says (meta.ts:89-103 only lists a gate when the metadata declares the field class).	REWRITE-AS-CONSTRUCT: keep the single non-CLI decision — "carry each printed gate into the report as pending, by name"	−180	① only the report line ② yes for the rest ③ yes	HIGH	no
UPG-B-02	B	SKILL.md:49-70 (304 tok) vs SKILL.md:669-683 (202 tok)	The same four rules stated twice. Boundary "Never hand-write a rewrite the chain already applies" ↔ Guardrail 1 "Run the chain first, always."; "Never add a tolerant read" ↔ Guardrail 3 "No tolerant reads, ever"; "Never resolve a residue item by guessing the owner's intent" ↔ Guardrail 4 "Ask about intent, decide about mechanics"; "Never report 'upgraded' without the acceptance artifacts" ↔ Guardrail 5 "The report is a deliverable… No report, not done." Guardrail 6 is a third statement of SKILL.md:226-227 ("a gate nobody was told about is not served by nobody" / "is served by nobody").	MERGE-INTO SKILL.md:49-70 (the pre-first-command placement is the decision-changing one); fold Guardrails 2 and 6 in; DELETE the "Guardrails (binding)" section	−170	① yes (once) ② yes ③ keeps the ⛔ bullet construct	HIGH	yes (removes published rule text)
UPG-D-05	D	SKILL.md:90-93, 179-183, 421-455, 543-547, 663	"validate green is necessary, not sufficient — replay from the target major" is stated five times: quickstart comment (--from 17 # must say "Nothing to migrate"), L182-183 "the cheapest possible proof that the port is complete", the 35-line ⚠ callout L423-455, reverse-check outcome 3 L543-547, failure-modes row L663.	DELETE L182-183 and L543-547; keep the §3.3 callout + the failure-modes row	−120	① yes, once ② yes ③ the failure-modes table is the construct	HIGH	no
UPG-D-04	D	SKILL.md:169-174 (117 tok) + 182-183	"This is deliberate: rewriting a TypeScript config through an AST is lossy — it drops comments, reorders keys, and cannot see values that come from imports or expressions." Pure rationale: the agent's action is identical with or without it, and the action is already in the code block (L176-180) and failure-modes row 1 (L659, "Working as designed — the command writes nothing but --out"). The --out-is-an-oracle rule is the only decision.	DELETE the rationale sentence; keep "use --out as the oracle you diff against, never as the file you ship"	−110	① no ② yes ③ n/a	HIGH	no
UPG-D-07	D	SKILL.md:33-47 (259 tok)	"This skill turns one session into an upgrade agent working on somebody else's metadata project… The upgrade is deliberately split into three layers, and the split is the whole design. Two of them are not yours." + a 3-row Layer table whose rows are restated by the ## 1 · Mechanical / ## 2 · Semantic residue / ## 3 · Acceptance headings and by the > preflight → mechanical chain → semantic residue → acceptance report line at L38.	DELETE L33-36 and L40-47; keep L38	−190	① no ② yes ③ L38 is already the construct	MED	no
UPG-C-01	C	SKILL.md:684-693 (135 tok)	"Cross-skill routing" restates skills/README.md:94-110 ("Any CEL expression — load objectstack-formula alongside the host skill") and every domain skill's own frontmatter ("CEL expressions in flow conditions / edge guards: load objectstack-formula alongside" — objectstack-automation/SKILL.md:9-10; same clause in data, api, formula). The last bullet ("Designing one inside the ObjectStack platform repo … is not this one") is a third statement of the frontmatter clause and UPG-D-02.	MERGE-INTO skills/README.md:94-110 (add one upgrade-vs-platform row there); keep only the "load the domain skill for the shape you are fixing" line	−70	① one row does ② yes ③ README owns the routing table	MED	no
UPG-B-03	B	SKILL.md:88, 252, 385, 608	grep -rho '\[REMOVED\][^"]*' node_modules/@objectstack/spec/json-schema/ | sort -u appears four times — byte-identical at L88, L252 and L608 (L608 adds | wc -l), and a sed-variant at L385.	DELETE L88 and L608; keep L252 (§2.1, the anchor) and L385 (the name-only variant the prose sweep needs)	−60	① no ② yes ③ n/a	HIGH	no
UPG-D-06	D	SKILL.md:194-199 (~85 tok)	"What that does and does not mean:" — bullet 1 ("You do not hand-edit sys_metadata. Ever. A row at rest has no author to ask") and bullet 2 ("The rows on disk stay in their old shape … Rehydration is a read-time projection") restate L187-192, which already says the rows rehydrate "without anybody editing it".	DELETE bullets 1-2	−60	① no ② yes ③ n/a	MED	no
UPG-A-02	A	SKILL.md:12-17 (97 tok of a 256-tok description; the frontmatter is 390 tok, the largest of all 11 packages — median 220, next largest pm-dispatch 365)	Two of the four "do not use" clauses are not routing: "to design a retirement in the ObjectStack platform repo itself (that is the platform's own internal playbook)" routes to .claude/skills/spec-property-retirement/ which no customer receives (it lives outside the published skills/ catalog boundary — skills/README.md:12-13), and "or to hand-write a rewrite the conversion chain already applies — running the chain is always the first step, never a fallback" is body rule Boundary #1 / Guardrail 1 restated in the trigger.	REWRITE-AS-CONSTRUCT: keep the two real negative routes (author new metadata → domain skills; DB drift → platform)	−60	① no (a description routes; it does not teach) ② yes ③ yes	MED	no
UPG-D-08	D	SKILL.md:505-508 (43 tok)	"Section 5 earns its place: 'we looked and it was not there' is a finding, and without it the next reader cannot tell a surface that was checked from one that was missed." — justification of a template row that is already in the template.	DELETE	−43	① no ② yes ③ n/a	HIGH	no
UPG-G-01	G	SKILL.md:19-24 (82 tok)	compatibility is a 5-line paragraph; all nine domain siblings use one line (objectstack-data/SKILL.md: "Requires @objectstack/spec 17.x (Zod v4 schemas)"). It also hedges a pinned constant — "protocol 10 at the time of writing" — where packages/spec/src/migrations/registry.ts:48 is export const MIGRATION_SUPPORT_FLOOR = 10 with a CI-checked projection (packages/spec/spec-changes.json supportFloor: 10, migrateCommand: "objectstack migrate meta --from N (N >= 10)").	REWRITE-AS-CONSTRUCT: one line, floor stated flat	−40	① no ② yes ③ yes	MED	no
UPG-E-02	E	SKILL.md:205	os migrate meta --stored --apply # rewrite the rows (prompts). In any non-TTY — i.e. every agent session — packages/cli/src/commands/migrate/meta.ts:500-511 refuses: if (apply && !flags.yes) { if (flags.json || !process.stdin.isTTY) { … emitJson({ error: 'confirmation_required', hint: 'pass --yes' }) … this.exit(1). The CLI's own example list is '$ os migrate meta --stored --apply --yes --json' (meta.ts:187).	ADD --yes to L205 (+ 1 clause), paid by UPG-D-08	+8	① yes — the command as written always fails for the reader ② no ③ n/a	HIGH	no
UPG-E-03	E	SKILL.md:107-108	"manifest.engines.protocol in the stack config ('16.0.0' → --from 16)". The field is a range, not a version: packages/spec/src/kernel/manifest.zod.ts:70-71 — protocol: z.string().optional().describe('Runtime/metadata protocol range, checked first (ADR §3.10 #3)'). All 3 real configs in the repo write the caret form: examples/app-showcase/objectstack.config.ts:89, examples/app-crm/objectstack.config.ts:48, examples/app-todo/objectstack.config.ts:48 — engines: { protocol: '^17' }. The skill gives no rule for the only form that actually occurs.	ADD one clause ("a range declares compatibility, not authorship — '^17' means runs on 17, so fall to source (2)"), paid by UPG-D-06	+30	① yes — source (1) is the first preflight decision ② no ③ n/a	HIGH	no
UPG-E-05	E	SKILL.md:511-535	The reverse-check recipe is os validate .upgrade/residue-probe.config.mjs, illustrated as producing the clean schema-gate refusal at L527-535. But os validate calls loadConfig(args.config) with no authoredSource (packages/cli/src/commands/validate.ts:159), and packages/cli/src/utils/config.ts:220-228 says that option is "Set by os migrate meta only". packages/cli/src/commands/migrate/meta.ts:294-305 documents exactly the failure this causes: "os init scaffolds export default defineStack({ … }), and every define* helper is a Schema.parse(). So the refusal used to happen while the config module was being EVALUATED, inside the load, before this command reached its first conversion". validate.ts:138 confirms the frame: "a run that throws in loadConfig — above it". A probe written the way a real config is written throws inside the load, not at the gate the skill is asking the reader to prove.	ADD one clause: the probe must be a plain data literal (no define* call) or the throw lands in the load, not the schema pass	+35	① yes — the recipe as written can produce a different error than illustrated ② no ③ n/a	HIGH	no
UPG-F-01	F	absent (§1 "Stored rows", SKILL.md:185-211; §3 "Acceptance", SKILL.md:396-455)	--stored has a CI-assertable exit contract the skill never mentions: packages/cli/src/commands/migrate/meta.ts:577-578 (const clean = storedMigrationClean(report); if (!clean) exitCode = 1;) and meta.ts:621 (if (exitCode !== 0) this.exit(exitCode)), documented at meta.ts:449-454: "A second pass reporting every row canonical exits 0; a deployment with work left exits 1, so 'my metadata is on protocol N' becomes a CI check instead of a belief." That is precisely the §3 acceptance question, for the stored half.	ADD one row to §3's acceptance list, paid by UPG-D-04	+40	① yes — it converts an assertion into a gate ② no ③ n/a	HIGH	no
UPG-F-02	F	SKILL.md:656-668 (failure-modes table)	The table names two of the machine-readable failures in prose only ("--apply refused / stored-only flag rejected", "MigrationFloorError") and omits the --json error codes an agent scripting the run branches on: stored_only_flag (meta.ts:262), missing_from_major (meta.ts:279), unsupported_from_major (meta.ts:414), confirmation_required (meta.ts:504), database_busy (meta.ts:477).	ADD a third column --json error to the existing table (construct already exists), paid by UPG-D-05	+50	① yes — an agent branches on the code, not the prose ② no ③ yes, extends a table	MED	no
UPG-F-03	F	absent (SKILL.md:138-148 flag list)	os migrate meta takes a positional config path — packages/cli/src/commands/migrate/meta.ts:191-193, config: Args.string({ description: 'Path to the stack config (defaults to auto-detected).' }). Never shown; a monorepo with more than one stack cannot follow the skill as written.	ADD one line to the flag block, paid by UPG-B-03	+12	① yes for multi-stack repos ② no ③ extends the existing block	MED	no
UPG-F-04	F	SKILL.md:126-134, 517-520	Speculative surface, disclosed: grep -rn "\.upgrade/" --include='*.ts' --include='*.md' --include='*.json' --include='*.yml' . | grep -v node_modules | grep -v skills/objectstack-upgrade → 0; same grep for residue-probe → 0. The .upgrade/ workspace and the probe file are conventions this skill invents. For a process skill aimed at customer repos that is defensible (zero in-repo usage is evidence, not proof), but it argues against spending 515 tok on the report template (SKILL.md:456-508) plus 407 on the probe.	note only — no removal proposed	0	—	MED	no
UPG-A-01	A	skills/objectstack-platform/SKILL.md:3-13 + skills/README.md:94-110	Routing hole into this package. Platform's description claims "operations (CLI commands, migrations, deployment…)" and "Use when the user is … running os CLI commands", with a "Do not use for" list naming only data and query. Its body's migration table (objectstack-platform/SKILL.md:1196-1203) lists only os migrate plan / os migrate apply — os migrate meta, files-to-references and value-shapes appear nowhere in it. A customer agent asked "run the migrations for the new spec" loads platform and gets physical-DB drift reconciliation. skills/README.md:94-110 "Cross-skill routing" lists four decision points, none upgrade-vs-platform.	ADD one clause to platform's description ("Do not use for a protocol-major metadata upgrade — see objectstack-upgrade") + one README.md routing bullet; each paid inside its own file	+30 (in sibling files, not this one)	① yes — it decides which package loads ② no ③ extends the README table	HIGH	yes (changes two sibling ceilings)
UPG-H-01	H	package has no evals/	skills/README.md:60-61 lists evals/ in skill anatomy; 7 of 11 packages ship one (objectstack-{ai,api,automation,data,i18n,platform,query}/evals/README.md, 143–546 tok). Both process packages (objectstack-upgrade, objectstack-pm-dispatch) ship none, so this is a class-level gap rather than a package outlier — and skills/README.md:64-66 explicitly sanctions it: "A process skill … carries SKILL.md alone" (though the stated reason is gen:skill-refs/references/, not evals). The decisions worth grading are exactly the two the skill calls load-bearing: decide-alone-vs-ask (SKILL.md:317-352) and validate-green-is-not-sufficient (SKILL.md:421-455).	ADD evals/README.md (new file, its own ceiling — does not consume SKILL.md's)	+200 (new file)	① yes — grades the two decisions the package exists to change ② no ③ yes, rubric rows	LOW (README sanctions SKILL.md-alone for process)	yes (adds a ratcheted file)
UPG-I-01	I	ratchet row	skills/objectstack-upgrade/SKILL.md 8333 / 8333 (+0) — zero headroom, so any addition above must be paid inside this file. Distinct decision-changing surfaces the package actually teaches: preflight --from derivation, the chain invocation + --out port loop, the stored pass, the pending data gates, the three residue classes, the decide-vs-ask rule, the four acceptance gates, the report. Eight. 8,333 tok / 8 ≈ 1,040 tok per decision surface, against 693 lines for a customer who runs this once per major.	see verdict	—	—	HIGH	no

Incidental falsehoods (by-product, not the job)

#	span	claim	measured truth
1	SKILL.md:561-568	D2 conversions for major 17 = 45; D3 semantic entries = 29; retiredKey() tombstones = 113, across 32 files	packages/spec/spec-changes.json perMajor[to=17]: 58 converted, 77 migrated. grep -rho "retiredKey(" packages/spec/src --include='*.zod.ts' | wc -l = 179, across 44 files. The section self-labels as a 17.0.0-rc.5 pin and tells the reader "the install wins" (SKILL.md:611-615), so this is stale-by-design rather than a false claim — but the installed spec is now 17.2.0 (packages/spec/package.json) and the drift is 29–165%.
2	SKILL.md:570-576	RETIRED_KEYS_BY_MAJOR[17] — "(3 entries…)" listing data/ExternalFieldMapping:transform, integration/ConnectorFieldMapping:transform, shared/FieldMapping:transform	packages/spec/src/migrations/registry.ts bucket 17 now holds 29 literals, and data/ExternalFieldMapping:transform was removed — registry.ts:7957-7959: "Two of the three remain: data/ExternalFieldMapping:transform left when #8075 retired the whole external-lookup family". The pinned framing only anticipates additions ("post-rc.5 registrations are expected to add entries", SKILL.md:612-613); it does not cover removal, so a reader reconciling the delta is told the wrong direction.
3	SKILL.md:578-582	RETIRED_DEFS_BY_MAJOR[17] — "(1 entry)"	registry.ts bucket 17 holds 53 literals (shared/FieldMappingTransform is still one of them, registry.ts:9451).
4	SKILL.md:205	os migrate meta --stored --apply # rewrite the rows (prompts)	It does not prompt for the reader of this skill. packages/cli/src/commands/migrate/meta.ts:500-511: non-TTY (every agent session) exits 1 with confirmation_required / "Re-run with --yes to confirm". See UPG-E-02.
5	SKILL.md:517-535	the reverse-check recipe yields the illustrated schema-gate refusal	Only if the probe is a plain literal. os validate loads without authoredSource (packages/cli/src/commands/validate.ts:159; packages/cli/src/utils/config.ts:220-228 "Set by os migrate meta only"), and meta.ts:294-305 records that a define*-calling config throws inside the load. See UPG-E-05.

Clean dimensions (measured, no finding)

• E, type-check gate. packages/spec/scripts/check-skill-examples.ts:17-23 — a checkable block is marked by OS-CHECK-MARKER on the line above the fence. The package has exactly one TypeScript fence (SKILL.md:626-652) and it is marked (SKILL.md:625). Zero unmarked TS fences, so nothing in this package can rot past the gate. Symbols spot-checked live: ObjectSchema (packages/spec/src/data/object.zod.ts:2709), defineAgent (packages/spec/src/ai/agent.zod.ts:399), requiredWhen (packages/spec/src/data/field.zod.ts:801), storage.notNull (field.zod.ts:921).
• G, retired-spelling residue. grep -n "silently\|ignored\|dropped\| legacy\|deprecat\|M9\|v5\.0\|OLD\|NEW" SKILL.md → 7 hits (L54, 210, 335, 417, 537, 558, 662), all legitimate behavioural descriptions; L537 uses "deprecation label" only to say what the error is not. No project-as-workspace misuse — SKILL.md:161,187,214,224,494,681 correctly say "deployment".
• Command/flag/output verification (the E/F reframe). Every documented flag exists as documented in packages/cli/src/commands/migrate/meta.ts:195-240: --from/--to/--step/--out (all exclusive: ['stored']), --stored, --database-url, --apply, --yes, --force, --type (multiple: true), --json. Stored-only-flag refusal meta.ts:47-66, 250-263 matches SKILL.md:209-210. Printed lines match: Applied N mechanical change(s) (meta.ts:367), N manual change(s) require your judgment (meta.ts:386), Migrated stack is schema-valid (meta.ts:403), Nothing to migrate (meta.ts:357). --json shape carries specChanges, todos[].surface, applied, schemaValid, dataMigrations (meta.ts:328-347) — SKILL.md:243, 359-363 correct. Floor: MIGRATION_SUPPORT_FLOOR = 10 (packages/spec/src/migrations/registry.ts:48), MigrationFloorError thrown at chain.ts:73-74 — SKILL.md:24, 563, 668 correct. os validate [config] --strict --json — packages/cli/src/commands/validate.ts:43-50 — correct. applyConversionsToStoredItem is reached from both seams the skill names: packages/metadata/src/loaders/database-loader.ts:708 and packages/objectql/src/plugin.ts:2000. spec-changes.json ships (packages/spec/package.json files) with protocolVersion, supportFloor, perMajor[].converted/.migrated — SKILL.md:245, 597-606 correct. Both bins exist (packages/cli/package.json bin: objectstack, os).

Totals

Deletions (non-overlapping; UPG-D-02 is subsumed by UPG-D-01 and not counted twice):
D-01 −600 · E-04 −280 · D-07 −190 · D-03 −180 · B-02 −170 · D-05 −120 · D-04 −110 ·
C-01 −70 · B-03 −60 · D-06 −60 · A-02 −60 · D-08 −43 · G-01 −40 → −1,983 tok

Additions into SKILL.md (each paid by a deletion above): E-02 +8 · E-03 +30 · E-05 +35 ·
F-01 +40 · F-02 +50 · F-03 +12 → +175 tok

Net: −1,808 tok on 8,333 = −21.7%. Verdict: DIET.
UPG-A-01 (+30) and UPG-H-01 (+200) land in sibling files / a new file and are paid there.

---

Generated by Claude Code