release(v18): in pre mode, sync-docs-image-tags and check-docs-image-tag pin the documented image and install versions to the newest GA, not 18.0.0-next.N (#22085 Q3)

[objectstack-fleet]

This card carries #22085's Q3 half: the ruling 6049734955 (Q3 → B). #22085 keeps Q1, filed as the domain:spec card #22130, and Q2, the v18 release page, a release-side action recorded there.

Filing gate: ③ a direct task from a maintainer ruling. The ruling 6049734955 records the maintainer's 「22082 22085 同意」 (2026-10-08T00:37Z) taking Q3 → B. Its 裁后执行, from 6040990462, is 「席位立一张 devx 卡改 sync-docs-image-tags 和 check-docs-image-tag」.

Reader: PM seat domain:devx#2 (session_01VF48aw8RPG6wzDnMgp6rtw) dispatches it directly. It is an in-flight sub-issue of #22085, so it inherits domain:devx and priority:p1 (execution-duties.md, the in-flight-derivative rule). ⛔ Not a claim; the claim follows.

What is measured (on origin/main 8fc50b7647)

• The root version script (package.json:20) is changeset version && … && node scripts/sync-docs-image-tags.mjs && …. changesets/action runs it on release.yml's version-pr lane.
• sync-docs-image-tags.mjs rewrites every concrete version a doc surface pins for the runtime image or the CLI to VERSION_SOURCE's version. check-docs-image-tag.mjs:198 sets VERSION_SOURCE = 'packages/cli/package.json'. The gate holds the same surfaces to that same version.
  • SURFACES (check-docs-image-tag.mjs:207) lists docker/README.md, content/docs/deployment/self-hosting.mdx and content/docs/upgrading.mdx.
  • The prose claims add content/docs/deployment/index.mdx.
• Once PR chore(release): enter Changesets pre mode (next) with one major marker, so v18 opens at 18.0.0-next.0 #22084 (release(v18): enter Changesets pre mode on main (changeset pre enter next) with one major marker, so the first v18 prerelease is 18.0.0-next.0 — the opening ruled B on #22050 #22080) puts main in pre mode (.changeset/pre.json, tag next), changeset version sets packages/cli to 18.0.0-next.N. The next version pass would then stamp 18.0.0-next.N into the self-hosting and upgrade docs.
  • Meanwhile npm latest and the published image stay at 17.7.0.
  • A production reader copying those documents is led into the breaking prerelease line. That is the cost the ruling names under ⛔ A.
• The newest GA is already readable in one place: check-release-section-coverage.mjs exports SPEC_CHANGELOG, gaVersions and newestGaOfMajor. sync-release-index-currency.mjs imports them, and since PR fix(release): judge the major-boundary template stamps on the version-pr lane, and stop prerelease cuts re-dating the last GA #22095 (8a925b3b47) it no longer re-dates the GA entry on prerelease cuts.

Done when

• In pre mode (.changeset/pre.json present with mode: "pre"):
  • sync-docs-image-tags pins the doc surfaces to the newest GA, read from the CHANGELOG through the existing exports. ⛔ No second GA reader.
  • check-docs-image-tag judges them against that same value. Both read it from one function: the rewriter and the gate must never disagree on the expected version.
• Outside pre mode nothing changes: both read packages/cli/package.json as today.
• Each script's --self-test gains the pre-mode cases with their positive controls:
  • a pre-mode tree whose CLI is 18.0.0-next.0 and whose newest GA is 17.7.0 expects 17.7.0;
  • the same tree without pre.json expects the CLI's version;
  • a pre-mode tree whose docs already read the newest GA rewrites nothing.
• Pin, replayed on a throwaway tree carrying PR chore(release): enter Changesets pre mode (next) with one major marker, so v18 opens at 18.0.0-next.0 #22084's two .changeset files:
  • the root version script leaves the doc surfaces at the newest GA;
  • pnpm check:docs-image-tag exits 0 on the result;
  • the same replay on main without pre.json moves them to the CLI's version as today.
  • Quoted in the PR body.
• ⛔ No edit to content/docs/** by hand, to release.yml, cut-rc.yml or the version script's order. ⛔ No publish, tag or release workflow run. ⛔ chore: version packages #21988 is not touched.

Dedupe

REST page loop (since 2026-09-01, state=all, 1,940 issues: 45 open, 1,895 closed) grepped for docs-image-tag|sync-docs-image|check:docs-image|image tag → 3 hits:

• release(v18): the version-pr lane refuses the major boundary at Validate the post-version tree, so #21988 never refreshes into 18.0.0-next.0 — wire the lane's major-only gates in, and stop prerelease cuts re-dating the last GA #22085, the parent;
• [PM seat] domain:devx · seat 2 — ⏳ vacant #20163, this seat's post;
• Version-bump-only regressions surface only on the Version Packages PR — rehearse pnpm run version on main on a schedule and test the bumped tree #20562 (closed), which rehearses pnpm run version on main on a schedule.

None pins the docs to the GA in pre mode.

[objectstack-fleet]

Claim: PM loop round 8
Session: session_01VF48aw8RPG6wzDnMgp6rtw
Account: os-justin (the seat's linked user as GET /user answers it; the card's assignee)
Branch: claude/issue-22131-docs-image-tags-pre-mode (new, cut from origin/main 8fc50b7647)
Worktree: objectstack-issue-22131
Domain: domain:devx (in-flight sub-issue of #22085)
Seat: domain:devx#2
Ruling-ref: 6049734955 (Q3 → B, re-read this round)
File surface: scripts/sync-docs-image-tags.mjs and scripts/check-docs-image-tag.mjs, with their self-tests. scripts/check-release-section-coverage.mjs is read-only and imported for the newest GA; it may change only if an export the two scripts need is missing.

• ⛔ No hand edit of content/docs/**. ⛔ No edit to release.yml, cut-rc.yml or the root version script.
• ⛔ No publish, tag or release workflow run. ⛔ chore: version packages #21988 is not touched.
• Stop on a breach and explain it in the report.
  Container & model: M, mode:subagent, model: opus (dispatch-gates --tier: no path-derived mandate; default tier; release-lane judgment)
  Clause-②: no
  Responsibility: n/a — not a defect card
  Thread-read: none
  Serial constraints cleared:
• No open PR touches either script (all 8 open PRs' file lists read this round). Their last change on main is c229223e93 (2026-09-19).
• PR chore(release): enter Changesets pre mode (next) with one major marker, so v18 opens at 18.0.0-next.0 #22084 (release(v18): enter Changesets pre mode on main (changeset pre enter next) with one major marker, so the first v18 prerelease is 18.0.0-next.0 — the opening ruled B on #22050 #22080, this seat) touches .changeset/ and check-adr-0087-registration.mjs only. This card's pin replays on a throwaway tree that carries chore(release): enter Changesets pre mode (next) with one major marker, so v18 opens at 18.0.0-next.0 #22084's two .changeset files.
• ci(validate-deps): on pull_request the OSV scan judges the whole lockfile, so a PR that changes no dependency inherits main's red for hours (7 red-main findings in 5 weeks) — judge base-relative on PRs, keep the daily main scan, add a job timeout #22082 (this seat, this round) holds validate-deps.yml; no shared file.

[objectstack-fleet]

os-dev-report
{
"issue": 22131,
"status": "done",
"branch": "claude/issue-22131-docs-image-tags-pre-mode",
"pr": "#22134",
"session": "session_01VF48aw8RPG6wzDnMgp6rtw",
"premise_still_valid": true,
"summary": "scripts/check-docs-image-tag.mjs gains expectedVersion(root), the one function both consumers call. Without .changeset/pre.json it returns packages/cli/package.json (VERSION_SOURCE, name kept). With pre.json in mode pre or exit it returns the newest GA overall in packages/spec/CHANGELOG.md. It reads through the existing SPEC_CHANGELOG/gaVersions/newestGaOfMajor and readPre, with no second reader, and every unreadable pre-mode state throws. scripts/sync-docs-image-tags.mjs gains syncRepo(), which main() runs and which takes its target from that function. Messages name the source used; outside pre mode both scripts print byte-identical output. Two Zone-2 readings changed the route, both re-routed by the ruling's intent. (1) Pre mode has two Changesets states: changeset pre exit leaves mode exit with the tree still on 18.0.0-next.N, and that commit lands before the Version Packages PR. Keying on mode pre alone would red this required gate on every PR in that window, so exit counts as pre mode; this is replayed and pinned. (2) cut-rc.yml does not refuse pre mode. It requires mode pre with tag rc (cut-rc.yml:232-236), so it never runs on the next line but does run on an rc line, where an rc cut now leaves the docs at the newest GA instead of stamping X.Y.Z-rc.N. That is the ruling's text (in pre mode) and its reason; its allowlist permits but does not require the doc surfaces to move. See open_questions. Draft PR #22134 is labelled skip-changeset with assignee os-justin (= the card's). CI was in_progress when this report was written.",
"tests": "All at a4b1b51 (final commit). Self-tests: node scripts/check-docs-image-tag.mjs --self-test, 112 assertions, exit 0, including the new battery "Pre mode: the expectation is the newest GA (#22131)" with 18 cases (roster floor 11 to 12). node scripts/sync-docs-image-tags.mjs --self-test, 45 assertions, exit 0, including the new battery "Control I" with 10 cases run through syncRepo() (roster floor 8 to 9). Each Done-when case carries a positive control. Ablation (fix committed first): node scripts/ablation-replace.mjs mutated "if (!existsSync(join(root, PRE_STATE))) {" to "if (true) {", i.e. the old logic with pre.json ignored. Evidence it landed: anchor 1 to 0, marker grep -c = 1, blob e27045098c80 to 97307ba4e54a. Under the mutation the gate self-test exited 1 with 13 failures and the sync self-test exited 1 with 6 failures, all of them new pre-mode cases; the branch-independent controls stayed green. Restored by blob: e27045098c80 equals HEAD, git diff HEAD empty. Replay: throwaway git worktree add --detach trees, then pnpm install --frozen-lockfile --offline --ignore-scripts and pnpm run version; the trees were removed afterwards. Tree 1 (HEAD plus PR #22084 pre.json and 22080-v18-line-opens.md): CLI 17.7.0 to 18.0.0-next.0; sync printed "all 9 concrete pin(s) across 3 surface(s) already at the newest GA in packages/spec/CHANGELOG.md (pre mode) 17.7.0 — nothing rewritten"; the surface diff was 0 lines; pnpm check:docs-image-tag exit 0. Then changeset pre exit (mode exit): the gate exited 0 against GA 17.7.0. Then pnpm run version: pre.json was deleted, the CLI went to 18.0.0, the 9 pins went to 18.0.0, and the gate exited 0. Tree 2 (HEAD, no pre.json): CLI 17.8.0, "9 pin(s) across 3 surface(s) → 17.8.0 (lockstep with packages/cli/package.json)", gate exit 0. Control tree (BASE 8fc50b7 without the change, plus PR #22084 files): the 9 pins were stamped 18.0.0-next.0, the state the ruling rejects. Gates: node scripts/pm/dispatch-gates.mjs --commands, with no paths, derived 31 commands over the 2-path diff, the same 31 as the dispatch. All 31 ran and exited 0, among them pnpm check:pm-dispatch-gates (1976 cases, 856s). The battery was started with nohup and a recorded PID and waited on with tail --pid. Its 600s Bash call was moved to the background by the harness, and a second tail --pid blocked until the battery exited (BATTERY_EXIT=0 read from the log). dispatch-gates --ran: 31 derived, 31 run, 0 NOT-MEASURED, 0 UNRUN. Lint was a proven narrowing, not pnpm lint (repo-wide, CI-owned): (1) isPathIgnored false for both files under eslint.config.mjs; (2) eslint --no-inline-config --format json gave 2 results, 0 errors, 0 warnings; (3) the config enables no type-aware linting (no parserOptions.project), so the diff cannot move any untouched file's verdict. No package build or typecheck is owed: the diff touches no package (scripts/ only, root package private).",
"mcp_calls": "0",
"api_writes": "6 REST writes in 3 fleet-write relay dispatches (each a POST /repos/objectstack-ai/objectstack/dispatches executed as objectstack-fleet[bot]): (1) pr_create POST /repos/objectstack-ai/objectstack/pulls (draft) opened #22134, read back byte-identical (12772 bytes); (2) label-write: POST /repos//issues/22134/labels (skip-changeset) and POST /repos//issues/22134/assignees (os-justin), read back matching; (3) comment POST /repos//issues/22131/comments (this os-dev-report). Plus 3 git pushes (the empty-branch probe and two commits), which are not REST writes. Reads were gh api REST single-card/PR reads only.",
"open_questions": [
{
"question": "The ruling says "in pre mode", and cut-rc.yml runs in pre mode with tag rc. Under this PR an rc cut leaves the doc surfaces at the newest GA instead of stamping X.Y.Z-rc.N (before this PR, the 17.1.0-rc.0 train stamped the rc into the docs). Should the GA pin cover rc lines too, or only the next line?",
"options": [
"A: keep it as implemented: any pre mode (tags next and rc, modes pre and exit) pins the newest GA",
"B: restrict it to tag next and let rc cuts stamp X.Y.Z-rc.N into the docs as before"
],
"recommendation": "A. (Real need) The harm the ruling names, a production reader copying the self-hosting/upgrade page into a prerelease while npm latest and the image stay on the GA, is the same for an rc. (Long term) One predicate keyed on Changesets' own state, not on a tag name, is the contract-first shape. (AI-error) It leaves no tag-dependent branch for an author to get wrong. (Scope) B adds a second condition and keeps the defect for rc lines. No action is needed unless the maintainer wants B."
}
],
"out_of_scope_findings": [
"carrier: none · noted in PR #22134 Acceptance notes, not filed · scripts/check-changeset-no-major.mjs entry-guard comment "Nothing imports this file today" is now inaccurate (check-docs-image-tag.mjs imports readPre); the import is inert per check:entry-guard",
"carrier: none · noted, not filed · release.yml post-version comment ("check:docs-image-tag — the 3 doc surfaces against packages/cli's NEW version") and the lint.yml step name "Docs image tags track packages/cli's version" are true only outside pre mode",
"carrier: none · noted, not filed · cut-rc.yml staging comment (around line 497) lists "the 3 doc surfaces" among an rc cut's paths; an rc cut now leaves them unchanged",
"carrier: none · noted, not filed · dispatch-gates now routes .changeset/pre.json to check:docs-image-tag but not packages/spec/CHANGELOG.md (read only through an import from a gate module); that file is release-owned and only the version pass writes it"
]
}

[objectstack-fleet]

ACCEPT — PR #22134 · domain:devx#2 · 2026-10-08T02:56Z

Seat review of PR #22134 against GitHub, at head a4b1b5106d on base 8fc50b7647. Report: 6050888918. Claim: 6050421469. Ruling-ref: 6049734955 (Q3 → B).

Checklist conclusions

• Shape: draft PR to main. Body line 1 is Fixes #22131; no other closing keyword in the body (the parent is Refs #22085). Clause-②: no is at line start.
• Files: scripts/check-docs-image-tag.mjs (+375 −26) and scripts/sync-docs-image-tags.mjs (+173 −13), the claim's surface.
  • ⛔ Untouched: content/docs/**, release.yml, cut-rc.yml, the root version script.
  • skip-changeset is correct, because the scripts publish nothing.
• The diff, read at the head:
  • expectedVersion(root) (check-docs-image-tag.mjs:1000) is the one function both consumers call: the gate's main() (:2218) and the rewriter's new syncRepo() (sync-docs-image-tags.mjs:272, which main() runs).
  • Without .changeset/pre.json it returns packages/cli/package.json's version; VERSION_SOURCE keeps its name.
  • In mode pre or exit it returns the newest GA overall, read through the existing SPEC_CHANGELOG / gaVersions / newestGaOfMajor.
  • pre.json is read through check-changeset-no-major.mjs's exported readPre (:2018 on main), so there is no second reader of either file.
  • Every unreadable pre-mode state throws rather than falling back. Messages name the source used, and outside pre mode the output is unchanged.
• The two route changes, both accepted:
  1. Mode exit counts as pre mode. changeset pre exit leaves the tree on 18.0.0-next.N until the next version pass. Keying on pre alone would red this required gate on every PR in that window. Replayed: after pre exit the gate exits 0 against 17.7.0, and the next version pass deletes pre.json and moves the pins to 18.0.0.
  2. cut-rc.yml does not refuse pre mode; it requires mode pre with tag rc (cut-rc.yml:232–236). An rc cut therefore now leaves the docs at the newest GA instead of stamping X.Y.Z-rc.N.
     • The seat takes the dev's option A within the ruling. Its text is "In pre mode … pin the newest GA; outside pre mode nothing changes", and its reason (a production reader copying the docs into a prerelease while latest and the image stay on the GA) holds for an rc as for next.
     • cut-rc.yml's doc-surface list is a staging allowlist (:596–:619): it permits the surfaces to move and does not require it. Its one hard stop, "the version pass produced no changes to commit", is still met by the package versions.
     • Recorded here for the maintainer's visibility. A narrower reading (next only) would be a new ruling, not this PR.
• The pins the card asked for:
  • Self-tests: the gate has 112 assertions and a new battery of 18 cases; the rewriter has 45 assertions and a new battery, "Control I", of 10 cases run through syncRepo(). Each Done-when case has a positive control.
  • Ablation: with pre.json ignored, the gate self-test fails 13 cases and the rewriter's fails 6, all of them the new pre-mode cases. Restored by blob hash e27045098c80.
  • Replay of the root version script on throwaway trees:
    • Tree 1 (with PR chore(release): enter Changesets pre mode (next) with one major marker, so v18 opens at 18.0.0-next.0 #22084's two files): the CLI goes 17.7.0 → 18.0.0-next.0, the 9 pins across 3 surfaces stay at 17.7.0, and check:docs-image-tag exits 0.
    • Tree 2 (plain main): the pins move to 17.8.0, as today.
    • Control on the base without the change: the pins are stamped 18.0.0-next.0, the state the ruling rejects.
• Gates: 31 derived, 31 run, all exit 0, including check:pm-dispatch-gates (1976 cases). --ran reconciled with 0 unrun.
• CI at head a4b1b5106d: 24 success, 11 skipped (path-filtered: Build Core, Temporal and the dogfood matrix; Check Changeset under skip-changeset), 0 red. Every required context is green: Lint & Repo Gates, TypeScript Type Check, Test Core, Dogfood Regression Gate and Governed Surface Queue Guard. check-governed-merges --pr 22134: NOT governed, 587 changed lines.

Deviations, accepted: the battery ran under nohup and was waited on with tail --pid after the harness moved its 600 s call to the background. The exit code was read from its log (BATTERY_EXIT=0), and nothing was left running.

Acceptance notes (not filed; the dev's four, each judged comment-level and outside the filing gate):

• check-changeset-no-major.mjs's entry-guard comment "Nothing imports this file today" is now inaccurate. The import is inert (check:entry-guard).
• release.yml's post-version comment and lint.yml's step name "Docs image tags track packages/cli's version" are true only outside pre mode.
• cut-rc.yml's staging comment (around :497) lists the doc surfaces among an rc cut's paths, which an rc cut now leaves unchanged.
• dispatch-gates routes .changeset/pre.json to check:docs-image-tag, but not packages/spec/CHANGELOG.md, which only the version pass writes.

Landing: pr_ready + automerge_enable once CI is green on every required context. The merge closes #22131. #22085 stays with this seat for #22130 and the Q2 page.

[objectstack-fleet]

Landed — PR #22134 → ec8f37c890 · domain:devx#2 · 2026-10-08T03:29Z

• Merged through the merge queue at 2026-10-08T03:27Z. The squash commit ec8f37c890 is on main. Its queue runs (37720599236 CI, 37720599244 Lint & Type Check) were green.
• Verified on main by blob identity: both files equal the PR head a4b1b5106d:
  • scripts/check-docs-image-tag.mjs = e27045098c;
  • scripts/sync-docs-image-tags.mjs = ca40e98282.
• Effect: in Changesets pre mode (pre.json in mode pre or exit), the version pass and the gate pin the documented image and install versions to the newest GA from packages/spec/CHANGELOG.md, through one function, expectedVersion(). Outside pre mode, behaviour is unchanged.
  • This covers rc lines too, under the ruling's text (see ACCEPT 6051232738).
• Closed by Fixes #22131 (completed). pm:dispatched is removed in the same act.
• Parent: release(v18): the version-pr lane refuses the major boundary at Validate the post-version tree, so #21988 never refreshes into 18.0.0-next.0 — wire the lane's major-only gates in, and stop prerelease cuts re-dating the last GA #22085's Q3 half is done. release(v18): the version-pr lane refuses the major boundary at Validate the post-version tree, so #21988 never refreshes into 18.0.0-next.0 — wire the lane's major-only gates in, and stop prerelease cuts re-dating the last GA #22085 keeps Q1 (spec(v18): move PROTOCOL_VERSION 17 → 18 in an ordinary pull request with full CI: regenerate spec-changes.json and the 17 → 18 upgrade-guide section, rewrite the in-repo ^17 handshakes, and give the lockstep test one pre-mode exception (#22085 Q1) #22130, domain:spec) and Q2 (the release-side v18 page).