feat(cli)!: rename the --json payload key specVersionGap to protocolVersionGap - #17240

Fixes #14261

Clause-②: no

Renames the published --json payload key specVersionGap to protocolVersionGap in one
stroke — no alias, no dual-key window, value shape unchanged.

Why this is a correctness change, not a tidy-up

Because ManifestSchema is not .strict() and silently drops unknown keys (#14192), a
reader who infers a writable manifest.specVersion from the key's old name does not get an
error — they get 「一份看起来正常、而那一行从未生效的 manifest」. The output-side breadcrumb
is the same ghost-key mechanism that caused the parent card #13860; this removes it.

Which option was ruled, and by whom (history, not a question)

Maintainer, 2026-09-02, comment 5507416523, verbatim:

14361 你不处理；14261 现在就改，定位为 minor；其他同意

Option B, now, graded minor. Option C (dual keys for a transition window) stays refused,
consistent with the 2026-08-27 ruling 「项目在创业阶段…短期不考虑渐进」.

The occurrence set, re-derived rather than inherited

specVersionGap on origin/main at bccf311100, measured with a control (protocolGap,
which fires 5/4/5 in compile.ts / doctor.ts / validate.ts):

os doctor is NOT a third emitter, measured. The parent card touched three commands, so
this was checked rather than assumed: doctor.ts calls checkProtocolVersionGap() and prints
a human-readable line; it has no --json face at all. Two emitters, not three.

There is no pending changeset naming the old key — the one the 2026-09-02 ruling asked to move
has since been released into packages/cli/CHANGELOG.md, which is history and stays as written.

⚠️ Per-PR CI does not run the pins that protect this rename

All three suites carry *.e2e.test.*, which test-nightly-tiers.yml moved to the nightly
tier (#16455). ci.yml's Test Core and the merge queue run under OS_TEST_TIERS=queue, which
excludes them. So a reviewer reading a green merge queue has not seen these pins pass. They
were driven by hand here, under OS_TEST_TIERS=nightly:

OS_TEST_TIERS=nightly pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 \
  test/build-json-advisory-parity.e2e.test.ts \
  test/build-json-undeclared-key-parity.e2e.test.ts \
  test/validate-json-warning-parity.e2e.test.ts

Test Files 3 passed (3) · Tests 17 passed (17) · lock VERDICT command-exit 0.

Ablation — prediction recorded BEFORE any leg ran

For a rename the interesting leg is the one proving the pins bind the new name. Predicted,
in writing, before the first mutation: restoring specVersionGap at the two emit sites reddens
all three suites by three distinct mechanisms — exact key-set equality in the two build-parity
suites, and expect(payload.protocolVersionGap).toBeNull() reading undefined in the third
(toBeNull() rejects undefined, which is what makes that pin non-vacuous).

Observed: exactly that, all three mechanisms. Test Files 3 failed (3) · Tests 4 failed | 13 passed:

- "protocolVersionGap",
+ "specVersionGap",              (both build-parity suites, key-set equality)
AssertionError: fixture must raise no protocol-version gap: expected undefined to be null

On-disk proof of the mutation, and of the restore, under trap ... EXIT INT TERM with absolute
paths:

Anchor counts moved 1→0 (new name) and 0→1 (old name) per file and back. Restore was
git checkout HEAD -- ABSPATH, never bare; git diff HEAD empty, git status --porcelain empty.
No dist leg: these suites spawn bin/run-dev.js under tsx, which reads src/.

Verification

Every exit code captured by redirect-then-$?, never through a pipe.

Two of the 60 returned exit 3 = PREREQUISITE NOT MET, which is ⛔ not a pass and ⛔ not a
finding — check:dual-build-cjs-loads and check:i18n-coverage both need a full-repo pnpm build
(they name absent dist/ in studio, client-react, the connectors and several plugins — none of
them a surface this diff touches). Declared as NOT MEASURED locally and left to CI, which builds
the repo fresh.

check-adr-0087-registration initially reported a real problem against this diff — a
declared-breaking changeset with no ledger disposition — and is now green with
not-required (no-migration-prescription): the renamed member is an output key on an inline
object literal, with no Zod schema, no packages/spec declaration and no stored representation,
so objectstack migrate meta has nothing to reach.

Docs-drift round, on the final head

check-affected-docs and check-drift-comment both exit 0. Because a published --json key is
the kind of thing a page states by its output, this was also swept by hand rather than left to
the emitter-only tool: no page under content/docs/ or docs/ prints or enumerates either
payload's key set, and the prose-class sweep over pages naming os validate --json /
os build --json found only flag lists. docs/ is outside the tool's walk, so it was grepped
directly. No release page is wrong, so there is nothing to hand back as a docs-only PR.

Single-writer

Measured from the open PR list (26 open PRs, 359 (PR, file) rows), each PR against its own
merge base via pulls/{n}/files, never remote branches. None of the five faces is held by any
open PR. Control fired: packages/cli/test/i18n-walk-output-parity.test.ts matched on PR #17223,
so the exact-path matcher was live.

⚠️ The claim-time control named at 5607961637 — packages/cli/src/commands/generate.ts held by
#17230 — did not fire on re-measure. Reason established rather than assumed: #17230 merged at
2026-09-09T20:45:29Z, during this run. Reported as observed; a replacement control was used.

验收备注

• packages/cli/CHANGELOG.md carries three historical rows naming specVersionGap. Left exactly
  as written — they record what shipped under that name and rewriting release history would make
  them false. Not a finding.
• scripts/pm/check-half-states.mjs:22779 uses this card's own title as row H54's anchor fixture.
  Deliberately untouched: it is a fixture about a title string, not a consumer of the key.
• The source comments at both emit sites previously asserted that the key keeps its published name
  because renaming it is "a break nobody asked for". They are rewritten, not deleted — a stale
  comment asserting the opposite of the code is worse than none.

Generated by Claude Code