docs(deployment): spell the tag scheme with metavariables, and teach check:docs-image-tag to see prose

[os-zhuang]

Fixes#10229

The 17.1.0 publish moved all eight anchored image pins and left the prose behind. check:docs-image-tag was green throughout, because it asserts the anchored pins agree with packages/cli — which 17.1.0 proved is not the same statement as the docs agree with packages/cli.

The census is five claims in three files, not three in two

The card called its list "a floor, not a census" and it was right. Sweeping the two prose shapes across the repo found two more, both in content/docs/upgrading.mdx — a file the gate already enumerates as a surface, and reads on every run:

Site	Claim	In SURFACES?
self-hosting.mdx:59	tag-scheme sentence	yes
self-hosting.mdx:60	the false rolling-tag sentence	yes
index.mdx:14	release train (17.0.0)	no
index.mdx:42	tag-scheme sentence	no
upgrading.mdx:11	release train (17.0.0)	yes — found here
upgrading.mdx:36	tag-scheme sentence	yes — found here

docker/README.md was swept too and is clean — see below, that turns out to be the whole design.

The two upgrading.mdx claims are repaired in this PR under the bounded in-place-fix exemption: same defect class (verbatim-identical sentences), correct form pinned by the sibling repairs landing here, no competing claim on the file across all 15 open PRs, and the same gate family with no new verification surface. They are also coupled — the new gate limb reddens on them, so the fix could not have been deferred without landing a red gate.

The false claim is reworded, not bumped

self-hosting.mdx:60 said the rolling 17.0 / 17 / latest tags "move with every stable publish". 17.0 froze on 2026-08-20. Bumping the number reproduces the defect at 17.2.0, because the sentence names which tags roll and that set changes shape at every minor. It now reads:

Image tags mirror @objectstack/cli versions: a stable publish pushes that exact version as X.Y.Z and moves latest and the matching X.Y / X tags onto it, while a prerelease gets only its exact tag. […] Only the exact tag is immutable — a rolling tag stops moving as soon as no later publish matches it, so X.Y freezes when the next minor ships and X when the next major does.

Verified against .github/workflows/docker-publish.yml's docker/metadata-action tag list ({{version}}, {{major}}.{{minor}}, {{major}}, and latest gated on !contains(version, '-')). It names no rolling tag whose identity changes, so it stays true at 17.2.0 and after.

Why metavariables, and why that is the gate design too

docker/README.md's tag table has documented this same scheme as X.Y.Z / X.Y, X / latest all along, and it is the one tag-scheme surface in this corpus that has never drifted — it is already this gate's LIVE_CONTROL for exactly that metavariable. The three sentences that drifted are the three that spelled the scheme with a concrete example. So the repair is to adopt the spelling that already works, and the new limb asserts that absence.

That choice is what makes the limb free: it demands prose carry no concrete version, so a publish cannot redden it — only an author reintroducing a literal can.

Why not the rule the card suggested

The card proposed keying on "a version literal in the same file as an anchored pin, disagreeing with it", on the reasoning that the historical sentences "live in files with no anchored pin". That reasoning has two counterexamples in the corpus today, both in files that do carry anchored pins:

• content/docs/upgrading.mdx's upgrade-checklist table — seven rows, v17.0.0 … v9.0.0 — in the same file as the pin on line 41.
• self-hosting.mdx's hotcrm-2.2.2.json artifact URL and index.mdx's com.acme.crm@1.2.0: the reader's own app version, which by construction never tracks ours.

The structural objection is worse than the false positives: a rule demanding prose literals track the CLI version turns the gate red on prose at every publish, and sync-docs-image-tags.mjs cannot fix prose — its rewrite is safe only because a PATTERNS match ends with its tag, which a sentence does not. That is this same drift rescheduled as a standing hand-fix, not removed. The gate's header now carries this argument.

Evidence

Harm reproduced, on the corpus origin/main carries today:

check-docs-image-tag: OK (3/3 enumerated surface(s) read, 8 concrete pin(s) compared
against packages/cli/package.json 17.1.0, ...) ← exit 0, five stale claims present

Red after, reverse-verified by restoring the three files to origin/main on top of the new gate — exit 1, five PROSE-VERSION findings at exactly self-hosting.mdx:59, index.mdx:42, index.mdx:14, upgrading.mdx:36, upgrading.mdx:11, with the pin limb still green. Files restored and confirmed byte-clean afterwards.

Anti-vacuity — the leg that matters. Two live ablations, each confirmed on disk before and after:

1. A historical removed in @objectstack/spec 17.0.0 sentence in content/docs/references/ui/view.mdx mutated to 99.98.97;
2. upgrading.mdx's | v17.0.0 | checklist row mutated to | v99.98.97 | — inside an enumerated surface.

Gate stayed green, exit 0 on both. It does not track historical facts. The 92 removed in @objectstack/spec … sentences in content/docs/references/** (95 across content/docs/**, in 22 files) are untouched.

The --self-test grows from 44 to 70 assertions: positive controls for PROSE-VERSION (including the wrapped-continuation spelling that a single-line span would miss), PROSE-ANCHOR-LOST, UNKNOWN-ANCHOR and MISSING-SURFACE, each paired with a clean fixture carrying all four legitimate literal shapes; plus a live control asserting every enumerated claim still matches its anchor in the real corpus.

Two defects found in the gate while testing it and fixed here:

• the scope line printed read as version-free under a failing run, contradicting the findings listed directly above it — it now states what was scanned, with an assertion pinning that;
• the header argued from "~30" historical sentences; re-measured, it is 92. The error runs in the reassuring direction (the hazard grew), but a gate that argues from a number should not argue from a stale one.

Gates

node scripts/pm/dispatch-gates.mjs (no path args, derived from the real diff) named 12 families. All 12 run green at b881249c, the final commit:

check:cross-package-test-inputs · check:doc-anchors · check:docs-audit-scope · check:docs-image-tag · check:docs-redirects · check:published-readme-links · check:role-word · spec check:empty-state · spec check:liveness · spec check:strictness-ledger · spec check:variant-docs · node scripts/check-cross-package-test-inputs.mjs

Also ran check:docs-image-tag-sync (35 assertions, green) — the rewriter imports this gate's exports, and the prose limb is deliberately additive so its PATTERNS contract is untouched.

No changeset: docs and a root scripts/ gate only, no published package changes — skip-changeset.

content/docs/releases/** is untouched; its 17.1.0 gap is #10232 and is not addressed here.

---

Generated by Claude Code