feat(skills): derive the compatibility majors and metadata.version from the workspace version (#22692)

Fixes #22658
Clause-②: no

Ruling A on #22649 (record 6096124407, maintainer 「22649 同意 A」): the
`compatibility:` line and each skill's `metadata.version` derive from
the package version instead of being kept by hand. This is PR 2 of the
two the card allows — the derivation and the ten regenerated
frontmatters (Tier H: `skills/**`). PR 1
(`claude/issue-22658-skills-package`) adds the `@objectstack/skills`
package; this PR does not depend on it merging (see the version source
below). No `skills/**` path moves; no skill's teaching changes — the ten
diffs are one `version:` line each.

## What changes

- `scripts/check-skill-compatibility-version.mjs` — the gate that
already reconciled every `@objectstack/PKG N.x` pin against the
workspace manifests now also reconciles `metadata.version`: every
`SKILL.md` must carry exactly the fixed group's version, read off
`@objectstack/spec`'s manifest (`CATALOG_VERSION_PACKAGE`); an absent
stamp is red, a stale one is red naming file / declared / actual / fix,
and a workspace without that package is red rather than "nothing to
derive". A new `--fix` leg is the one writer: it rewrites each pin's
major to the cited package's current workspace major (an inline scalar
or a folded block scalar) and `metadata.version` to that version, writes
only the files that moved, then runs the check; it invents no structure
(a file with no `version:` key comes back unchanged and is named). Every
prescription that used to say "edit the line" now names `--fix`; the
header and the report footer say the line ships inside
`@objectstack/skills` and from `main` as the `next` channel. The
self-test grows from 18 to 27 pinned batteries: R9 stale stamp, R10
absent stamp, R11 the exempt (unpinned) upgrade skill is stamped too,
R12 the anchor package missing, and five `--fix` derivation cases (both
lines rewritten with every other byte kept, no-op on a derived file, a
folded-block pin, no invented structure, an unknown package left for the
check). R1's prescription regex moved with the text.
- `package.json` (root) — the `version` script runs `node
scripts/check-skill-compatibility-version.mjs --fix` after `changeset
version`, beside `sync-protocol-version.mjs` and
`sync-template-versions.mjs`: the Version Packages PR carries the
restamped frontmatters, so `main` never sits red here between a bump and
a hand edit, and the maintainer's own merge of that PR is the Tier H act
for `skills/**`.
- `scripts/regen-artifacts.mjs` — a `NOT_DRIVER_MANAGED` row
(`skills/*/SKILL.md`, `gen: version`, root owner): the `--fix` makes the
root `version` script a generator in `git-merge-regen`'s population, and
the recorded answer to "discard both sides and re-run" is no — two
derived lines inside hand-written prose; a text conflict stays a
human's, the two lines re-stamp on the next `--fix`. `pnpm
check:merge-driver`: `all 43 generator(s) across 81 manifest(s) have a
recorded disposition`.
- `skills/*/SKILL.md` (10 files) — regenerated by `--fix`, never by
hand: `metadata.version` `"1.0"` / `"1.2"` / `"1.3"` ×4 / `"1.4"` ×3 /
`"4.4"` → `"17.7.0"`; 10 insertions, 10 deletions, nothing else. Every
`compatibility:` pin was already at the workspace major (`17.x`), so
those lines are byte-identical. `skills/README.md`'s generated block
does not carry the version; it is unchanged (`check:skill-docs` green).

## The version source, measured

The PM's mechanism assumption named two possible sources and asked which
exists on `main`: `packages/skills/package.json` does not exist at this
branch's base (`243dd3c62`); `packages/spec/package.json` does. The
derivation reads `@objectstack/spec` — the fixed group's anchor, the
package every published skill's `compatibility:` line cites — and
`@objectstack/skills` carries the identical version by the `fixed` group
(`check-changeset-fixed` holds the membership). So this PR is green on
its own and stays correct whichever of the two PRs lands first; the
alternative (read `packages/skills/package.json`) would red
`check:skill-compatibility` on this branch until PR 1 is on `main`, and
red `main` if this PR landed first. The constant is one line to change
if the maintainer prefers the literal package.

The gate had no hand-maintained version constant to replace: it already
reconciled pins against the workspace manifests. What was hand-kept was
the frontmatter itself; that is what `--fix` and the `version` script
now own.

## Reverse verification on the live tree (restored, proven)

On `skills/objectstack-query/SKILL.md` (HEAD blob `5e7ca000…`), with a
trap restoring through `git checkout HEAD -- PATH`:

- leg 1, the `version:` line deleted →
`check-skill-compatibility-version` exit 1: `cannot read
metadata.version: frontmatter metadata: map has no version: key`, naming
the file and `--fix`;
- leg 2, the stamp set to `"4.4"` → exit 1: `declared: metadata.version
"4.4"` / `actual: @objectstack/spec 17.7.0 (packages/spec/package.json)`
/ `fix: run … --fix`;
- leg 3, `--fix` → `1 of 10 SKILL.md file(s) rewritten`, exit 0;
- restored: blob equal to HEAD, `git diff HEAD` empty, `git status`
clean; the gate green again (`10 metadata.version stamp(s) all equal
@objectstack/spec 17.7.0`).

## Gates run (exit codes captured before any pipe)

Derived on the changed set and reconciled with `--ran`: 51 derived, 51
run, 0 UNRUN; every family exit 0. Named by the card and all green:
`check:skill-compatibility` (self-test 22 check cases + 5 derivation
cases + 6 declaration cases; run: 10 files, 11 pins, 10 stamps),
`check-skills-token-ratchet` (+ self-test), `check:skill-docs`,
`check:skill-refs`, `check:skill-examples` (262 prose examples
type-check, on the built tree), `check:skill-identifier-liveness`,
`check:skill-frame-sync`, `check:skill-frame-freshness`,
`check:skill-top-level-keys`, `check:pm-governed-merges` (+
`pm-governed-prose`), `check:merge-driver`, `check:doc-authoring`,
`check:nul-bytes`, `check:corpus-claim-drift`, `check:role-word`,
`check:self-test-wired`, `check:ratchet-remedy-authority`,
`check:dts-closure` / `check:dual-build-cjs-loads` /
`check:sourcemap-no-sources-content` / `check:lean-entry-closure` on a
full build under the verify lock (72 tasks, `VERDICT command-exit 0`,
held 463s), `check:pm-dispatch-gates` (fast tier; its reading is in the
report comment). Lint at `5567d606c`: eslint `--format json` over the
two JavaScript files touched — 2 files, 0 errors, 0 warnings; the config
enables no type-aware linting, so no untouched file's verdict moves.

Token ratchet reading, before → after (`check-skills-token-ratchet`, all
within ceilings, exit 0): `objectstack-data/SKILL.md` 6127 → 6128 of
6128 (headroom 1 → 0), `objectstack-automation` 5783 → 5783 (headroom
2), `objectstack-platform` 5830 → 5831 (headroom 2), `objectstack-ui`
3847 → 3848 (headroom 8), `objectstack-upgrade` 6184 → 6185 (headroom
8); the other five gain one token with wide headroom. No ceiling was
touched. A future bump that lengthens the version string (`17.10.0`) may
cost one more token on `objectstack-data`; that would be the `version`
script's run, and the ceiling is the maintainer's to move.

## Acceptance notes

- The maintainer named no new standalone gate and none is added: the
derivation lives inside the existing gate as its `--fix` leg, and the
self-test rides the existing `check:skill-compatibility` alias.
- `skip-changeset`: nothing publishes from this PR (`skills/**` reaches
npm only through `@objectstack/skills`'s build, whose changeset is PR
1's; the gate and the ledger are repo tooling; the root manifest is
private).
- Landing order is free, but the stamps are the ones a consumer reads:
the first release after both PRs publishes `metadata.version: "17.x.y"`
inside `@objectstack/skills`.

## 维护者速读(草稿)

- 改了什么:十个 `SKILL.md` 里的 `metadata.version` 不再手写,由
`check-skill-compatibility-version.mjs --fix` 从工作区版本派生(本次全部变成
`"17.7.0"`;`compatibility:` 的 `17.x` 已与工作区一致,一字未动);门禁同时校验这一行,发版时 `pnpm
run version` 自动重打。
- 为什么改:裁决 A 要求技能目录随版本发运,版本号就不能靠人记——以前每个技能各写一个 `"1.3"`、`"4.4"`,与任何真实版本无关。
- 风险与代价(含回滚):十个受管文件各改一行;每次发版的 Version Packages PR 会多出这十行(由你手合)。回滚 =
还原这三个脚本改动,十行自动回到旧值。
- 席位意见:(留空)
- 你要做的:在这张 PR 上给一个 APPROVED review(Tier H:`skills/**`);之后由席位落地。

## Claim

This branch, `claude/issue-22658-compat-line-derived`, is named on the
`Branch:` line of the claim extension 6098607178 on #22658 (the round-2
claim `6096391379` names PR 1's branch); contract review 6098612738 on
this PR.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01RdnZdPZH9ByduzPRWuH9tN)_

---------

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

Author: objectstack-fleet[bot]

package.json

@@ -17,7 +17,7 @@
     "setup": "pnpm install && pnpm --filter @objectstack/spec build",
     "prepare": "node scripts/setup-git-hooks.mjs",
     "check:merge-driver": "node scripts/git-env.mjs --self-test && node scripts/git-merge-regen.mjs --self-test && node scripts/check-regen-pending.mjs --self-test",
-    "version": "changeset version && node scripts/sync-protocol-version.mjs && node scripts/sync-template-versions.mjs && node scripts/sync-docs-image-tags.mjs && node scripts/sync-release-index-currency.mjs",
+    "version": "changeset version && node scripts/sync-protocol-version.mjs && node scripts/sync-template-versions.mjs && node scripts/sync-docs-image-tags.mjs && node scripts/sync-release-index-currency.mjs && node scripts/check-skill-compatibility-version.mjs --fix",
     "release": "pnpm run build && bash scripts/build-console.sh && bash scripts/release-publish.sh",
     "docs:dev": "pnpm --filter @objectstack/docs dev",
     "docs:build": "pnpm --filter @objectstack/docs build",

scripts/check-skill-compatibility-version.mjs

@@ -445,6 +445,20 @@ export const REGEN_ARTIFACTS = Object.freeze([
  *     reason expires and a real disposition is owed.
  */
 export const NOT_DRIVER_MANAGED = Object.freeze([
+  {
+    path: 'skills/*/SKILL.md',
+    gen: 'version',
+    owner: ROOT_OWNER,
+    why:
+      'hand-written skill prose carrying two DERIVED lines — the `compatibility:` majors and '
+      + '`metadata.version`, which `scripts/check-skill-compatibility-version.mjs --fix` writes from '
+      + 'the workspace manifests and the root `version` script re-stamps after every `changeset '
+      + 'version`. That `--fix` is what makes the `version` script a generator here, and the answer '
+      + 'to "discard both sides and re-run" is NO: a regeneration would restore the two lines and '
+      + 'lose every prose edit around them. A text conflict in a SKILL.md stays a human\'s; the two '
+      + 'derived lines re-stamp themselves on the next `--fix`, and `check:skill-compatibility` reds '
+      + 'until they do.',
+  },
   {
     path: 'packages/spec/docs-import-surface.baseline.json',
     why:

scripts/regen-artifacts.mjs

@@ -12,7 +12,7 @@ license: Apache-2.0
 compatibility: Requires @objectstack/spec 17.x (Zod v4 schemas)
 metadata:
   author: objectstack-ai
-  version: "1.4"
+  version: "17.7.0"
   domain: ai
   tags: agent, tool, skill, knowledge, llm, embedding, mcp
 ---

skills/objectstack-ai/SKILL.md

@@ -14,7 +14,7 @@ license: Apache-2.0
 compatibility: Requires @objectstack/spec 17.x (Zod v4 schemas)
 metadata:
   author: objectstack-ai
-  version: "1.4"
+  version: "17.7.0"
   domain: api
   tags: rest, endpoint, auth, realtime, server
 ---

skills/objectstack-api/SKILL.md

@@ -13,7 +13,7 @@ license: Apache-2.0
 compatibility: Requires @objectstack/spec 17.x (Zod v4 schemas)
 metadata:
   author: objectstack-ai
-  version: "1.3"
+  version: "17.7.0"
   domain: automation
   tags: flow, workflow, trigger, approval, state-machine, scheduled, webhook
 ---

skills/objectstack-automation/SKILL.md

@@ -15,7 +15,7 @@ license: Apache-2.0
 compatibility: Requires @objectstack/spec 17.x (Zod v4 schemas)
 metadata:
   author: objectstack-ai
-  version: "4.4"
+  version: "17.7.0"
   domain: data
   tags: object, field, validation, index, relationship, hook, schema, permission, rls, security, seed, fixture
 ---

skills/objectstack-data/SKILL.md

@@ -13,7 +13,7 @@ license: Apache-2.0
 compatibility: Requires @objectstack/spec 17.x and @objectstack/formula 17.x (CEL)
 metadata:
   author: objectstack-ai
-  version: "1.2"
+  version: "17.7.0"
   domain: expression
   tags: cel, formula, predicate, condition, validation, visibility, seed-dynamic
 ---

skills/objectstack-formula/SKILL.md

@@ -13,7 +13,7 @@ license: Apache-2.0
 compatibility: Requires @objectstack/spec 17.x (Zod v4 schemas)
 metadata:
   author: objectstack-ai
-  version: "1.3"
+  version: "17.7.0"
   domain: i18n
   tags: i18n, translation, locale, l10n, bundle, coverage
 ---

skills/objectstack-i18n/SKILL.md

@@ -17,7 +17,7 @@ license: Apache-2.0
 compatibility: Requires @objectstack/spec 17.x and @objectstack/core 17.x (Zod v4 schemas), Node 22+
 metadata:
   author: objectstack-ai
-  version: "1.3"
+  version: "17.7.0"
   domain: platform
   tags: project, defineStack, driver, hono, plugin, kernel, service, requires, capability, DI, lifecycle, cli, deploy, ops
 ---