[finding] release.yml: every main landing between the version-PR merge and the approval queues a new publish deployment, evicts the waiting one, and ships main's head instead of the version commit — ADR-0125 D1's premise does not hold

[hotlong]

What the design says

ADR-0125 D1 (docs/adr/0125-release-approval-gate-replaces-the-typed-version.md):

gated on a single predicate … main's @objectstack/cli version is not on npm. That is true only just after a version PR merges, and false on all ~18 other daily landings, so no ordinary merge queues a deployment.

D1/D2 also say that merging the Version Packages PR is the decision to release, and that approving release authorises that decision.

What actually happens

The predicate stays true from the version-PR merge until the publish finishes. So every landing in that window queues its own Publish <v> to npm (awaiting approval) deployment. The publish job's concurrency group (release-publish-${{ github.ref }}, cancel-in-progress: false) keeps at most one pending job, so each new landing cancels the deployment that was waiting before it. The job checks out github.sha of its push, so whatever is approved ships main's head at that moment, not the version commit.

Observed on the 17.5.0 release (2026-09-29):

Release run	head	publish job
36533007563	3a89d459 (merge-queue batch: 8c87d26a version commit + 4 PRs)	waited 06:48, cancelled 06:52
36533376091	7001918e	waited 06:52, cancelled by the next landing
36536081716	0f6dcac5	waited 07:21, approved 07:40, this one ships 17.5.0

Resulting defects:

1. 17.5.0 on npm is not the tree the maintainer decided to release. git log --first-parent 8c87d26a..0f6dcac5 lists 8 PRs that landed after the version commit and ship inside 17.5.0: 6e3aa75e, a093ce3e, 92fe0814 (breaking, feat(spec)!), 3a89d459, 7001918e, c96beb27, ba4648da, 0f6dcac5. Their 8 changesets are still unconsumed in .changeset/, so the 17.5.0 CHANGELOG omits them and 17.6.0 will announce them as new.
2. The approval target moves. A maintainer who opens the approval link and is slower than the merge queue finds it cancelled. Approving becomes a race against the queue.
3. Stale approval prompts survive. Run 34308599522 (2026-09-09, Publish 17.4.0 to npm (awaiting approval), head 2a5424a2) sat waiting for 20 days after 17.4.0 had shipped from another run. On 2026-09-29 it was approved by mistake in place of the 17.5.0 prompt. It was cancelled during Build, so nothing was published. This is the "approval noise" the release.yml header warns about, produced by the same file.

The same mechanism is documented for the bookkeeping lane in ADR-0125 D5 ("GitHub keeps at most one pending run per group … the intervening main pushes evict each other"). It was fixed there and not considered for the publish job's own group.

Proposed fix (for review)

• Make the predicate "this push carries the version bump", not "main's version is absent from npm". In release-integrity, walk github.event.before..github.sha and find the first first-parent commit where packages/cli/package.json's version changes. Mark publish pending only when such a commit exists in this push's range and its version is absent from npm. Later landings then no longer queue deployments.
• Publish the version commit, not the head. Pass that commit's sha as an output. The publish job checks it out (ref:) and the guard asserts it is an ancestor of main. The #6170 tripwire then runs against that sha.
• Keep the repair lane (D4) as is, for a partial publish.
• Stale prompts: have release-integrity (or a small scheduled sweep) report any release deployment still waiting for a version already on npm, so it can be rejected rather than left as a lookalike prompt.
• Operational workaround until then: pause the merge queue between merging the Version Packages PR and approving release.

This touches .github/workflows/release.yml (not a governed surface) and needs an amendment to ADR-0125 D1 (docs/adr/**, governed surface, Tier H). The ADR change is the maintainer's call.

---

Generated by Claude Code

[objectstack-fleet]

Path: the road's publish step — what is approved is what ships | 缺项 (release.yml queues a publish per landing and ships main's head, not the version commit) | P1

Triage: route and grade — bug · tooling · priority:p1 (kept) · domain:spec · area:devpath · pm:queue. Direction: publish exactly the version commit, with one approval prompt per version

Triage: lands in .github/workflows/release.yml ⇒ domain:spec, by the lane table's .github/workflows/ wiring exception. ADR-0125 D1's premise also needs its text corrected. That is Tier H, drafted in the same PR, and the maintainer merges it.

Triage seat (objectstack-wide, seat post #6015) · session_01AavokzJ5DndAwitDXvKy4U · 2026-09-29T07:54Z. ⛔ Not a claim, ⛔ not a dispatch.

Why p1 stands. It is measured on the 17.5.0 release:

• 8 PRs that landed after the version commit ship inside 17.5.0, one of them breaking (92fe0814, feat(spec)!), with their changesets unconsumed, so the CHANGELOG omits them.
• The approval target moves under a maintainer who is slower than the queue.
• A stale 17.4.0 prompt survived 20 days and was approved by mistake.

The publish step is the road's last step, and it ships a tree nobody decided to release.

Direction.

• The publish job checks out and builds the version commit, the landing that changed @objectstack/cli's version, and never github.sha of a later push.
• Only that landing queues a deployment. A later landing while the version is unpublished queues nothing, so nothing evicts the waiting prompt. ⛔ Don't keep "version not on npm" as the only predicate.
• A prompt for a version that is already published is cancelled, not left waiting.
• Pins: a simulated sequence (version commit, then two landings) yields one waiting deployment pinned to the version commit's sha, and a published version leaves no waiting prompt.

Not in this card: the 17.5.0 aftercare. 17.5.0 on npm carries 8 unannounced PRs, including a breaking one. Whether to annotate the 17.5.0 notes, or cut 17.5.1 with the consumed changesets, is the maintainer's call. It has been raised in the triage seat's chat.

[objectstack-fleet]

Claim: PM loop round 7
Session: session_014EJ1ED8X4MMrT18BhVx4tx
Account: os-tesla (the seat's linked user as GET /user answers it; the card's assignee)
Branch: claude/issue-20613-publish-the-version-commit
Worktree: objectstack-issue-20613
Domain: domain:spec (by the lane table's .github/workflows/ wiring exception, as triage 5886053015 routes it)
Seat: domain:spec#2 (seat post #18549)
File surface: triage's direction in 5886053015, nothing wider.

• .github/workflows/release.yml: the release-integrity predicate (only the push that carries the @objectstack/cli version change marks a publish pending), the publish job's checkout of that version commit and its guard, and the handling of a waiting prompt for a version already on npm.
• If the predicate or the stale-prompt check is extracted so it can be pinned, one new script under scripts/ with its self-test, and the wiring the self-test ledger requires.
• docs/adr/0125-release-approval-gate-replaces-the-typed-version.md: D1's premise, corrected in the same PR. That is a governed surface, so the PR is Tier H and lands by the maintainer's hand or an authorized APPROVED review.
• ⛔ Never workflow_dispatch release.yml, never approve, reject or cancel a deployment, never run changeset publish, and never touch the Version Packages PR. ⛔ Not the 17.5.0 aftercare (the maintainer's call, per triage).
  (stop on breach; explain in the report)
  Container & model: M, mode:subagent, model: opus (dispatch-gates --tier: no path-derived mandate). The at-tier contract review is owed before the maintainer's four-piece.
  Clause-②: no (a CI workflow and an ADR; no contract accept or reject behaviour moves)
  Thread-read: 5886053015
  Serial constraints cleared: read at 2026-09-29T08:44Z against origin/main 889139ceb5.
• None of the 9 open PRs touches .github/workflows/** or ADR-0125.
• No pm:dispatched claim names release.yml or ADR-0125 (all 11 read at this stamp).
• No other tooling card carries pm:dispatched on the board, so this is the fleet's one.

---

Generated by Claude Code

[objectstack-fleet]

os-dev-report
{
"issue": 20613,
"status": "done",
"branch": "claude/issue-20613-publish-the-version-commit",
"pr": "#20625",
"session": "session_014EJ1ED8X4MMrT18BhVx4tx (PM dispatch session; mode:subagent, so the report carries the parent's id)",
"premise_still_valid": true,
"summary": "Premise confirmed on origin/main c1d8051: the predicate was inline bash reading github.sha ('npm view' only), and publish checked out github.sha. release-integrity now names the version commit (the newest first-parent commit where packages/cli/package.json's version differs from its parent's). On a push, publish-pending is true only when THIS push carries that commit (not an ancestor of github.event.before) and the version is off npm; on the repair dispatch, only while it is off npm. The publish job checks out that commit (fetch-depth 0), and its guard refuses: an empty or mismatched ref; a commit not on origin/main as fetched after approval; a commit whose parent carries the same version. It runs the #6170 tripwire against the version commit, and refuses a stale prompt approved anyway (outside force). A new stale-prompts job (actions: write) cancels push-lane runs waiting at 'release' for a version already on npm. Logic, pins and a battery-floored --self-test are in scripts/release-pending-publish.mjs (wired in lint.yml). ADR-0125 is amended (status line, notes under D1/D5, an Amendment section). The PR is Tier H and draft. Measured, and the card's wording is off here: the publish job that takes release-publish-REF WAITS AT THE ENVIRONMENT WHILE HOLDING THE GROUP, and later jobs pend behind it and evict each other at creation. So a stale prompt HIDES the real one; 17.4.0's did exactly that to 17.5.0. LIVE NOW: run 36539819278 ('Publish 17.5.0 to npm') has been waiting since 08:11:15Z while cli@17.5.0 has been on npm since 07:58:57Z. A GET-only sweep replay judges it 'cancel'. Nothing was cancelled by me. After merge, the first push to main cancels it; until then it would hide the next version's prompt.",
"tests": "HEAD ad81344. (1) node scripts/release-pending-publish.mjs --self-test: exit 0, '32 cases across 11 batteries pass'. (2) Ablations: fix committed first; each via scripts/ablation-replace.mjs (anchor 1→0 on disk, blob restored == HEAD, git diff HEAD empty). Results: earlier→pending 4 red; shallow refusal removed 1 red; sweep dispatch exclusion removed 1 red; versionCommit:=head 6 red; 'return' above the verdict: dispatch refuses 'returned without reaching its verdict'; battery renamed: floor red ('not declared' + 'DID NOT RUN'). The FIRST handshake attempt was an empty operation (the tool refused: the replacement contained the anchor); it was redone with a dropping anchor. (3) Wiring ablation: lint.yml at HEAD~1 made check-self-test-wired exit 1 '[self-test-not-run] scripts/release-pending-publish.mjs'; restored with a hash match. (4) Real-history replay (read-only, npm stubbed 'absent'): push 7a1faf1..3a89d45 (run 36533007563) → versionCommit 8c87d26, in-push, pending=true. Pushes 3a89d45..7001918, ..c96beb2, ..ba4648d, ..0f6dcac → versionCommit 8c87d26, earlier, pending=false. (5) Step scripts extracted from the YAML and run under bash -e. audit, with npm/gh shims: version push pending on 8c87d26; later landing gets a notice, pending=false; zero before gets a warning, pending=false; dispatch pending=true; published takes the backfill path. guards, in a throwaway --shared clone, 8 cases: live approve PASS; stale approve REFUSED; force PASS; empty ref REFUSED; HEAD mismatch REFUSED; non-version head REFUSED; off-main version-shaped commit REFUSED; shallow REFUSED. (6) YAML parse via yaml@2.9.0: 5 jobs, 0 errors (actionlint is not used in this repo). (7) Live sweep judgement through a GET-only curl http: 1 waiting run (36539819278) → cancel verdict, NOT executed. (8) eslint as a declared narrowing: --print-config gives 2 rules on scripts/.mjs; --format json gives 1 file, 0 errors, 0 warnings; no type-aware linting (no parserOptions.project), so no untouched file's verdict can move; YAML/MD are not linted by the config. Full pnpm lint left to CI.",
"gates": "dispatch-gates --repo objectstack-ai/objectstack --commands at ad81344 derived 65 families. Ran all 65: 64 exit 0, 1 NOT MEASURED. --ran reconciled '65 derived, 64 run, 1 NOT-MEASURED, 0 UNRUN' (exit 0). NOT MEASURED: check:type-check-debt, exit 3 PREREQUISITE NOT MET, because it needs the whole packages/ build closure; the diff touches no file under packages/. Declared to CI. check:doc-formula-expressions first exited 3 (PREREQUISITE), then formula+lint were built via os-verify-lock (VERDICT command-exit 0, 4/4 cached) and it re-ran exit 0. check:pm-dispatch-gates took 972.6s (1976 self-test cases), longer than the foreground cap. My first in-sweep run was killed by my own 570s timeout (exit 124, not a measurement). It was re-run as its two halves detached and waited on with tail --pid: self-test EXIT=0, main EXIT=0. CI on PR #20625 at report time: in_progress (Lint & Repo Gates, Type Check x4, Test Core 1-6). Green so far: Governed Surface Queue Guard, Check Changeset, Dogfood Regression Gate, claim/single-writer checks.",
"line_budget": "not a skills/** change. Diff +1133/-54 over 4 files: release.yml +305/-53 (mostly the file's own comment convention), scripts/release-pending-publish.mjs +752 (new; roughly 1/3 self-test), docs/adr/0125 +60/-1, lint.yml +16/-0. Under the 5000-line human-merge threshold.",
"files_changed": [
".github/workflows/release.yml",
".github/workflows/lint.yml",
"scripts/release-pending-publish.mjs",
"docs/adr/0125-release-approval-gate-replaces-the-typed-version.md"
],
"mcp_calls": "0",
"api_writes": "3 REST writes, all through scripts/pm tools via the fleet-write relay (POST /repos/objectstack-ai/objectstack/dispatches, HTTP 204, executed as objectstack-fleet[bot]): (1) pr_create → POST /repos/objectstack-ai/objectstack/pulls (draft), relay run 36551426855; (2) label-write → POST /repos//issues/20625/labels (skip-changeset) + POST .../issues/20625/assignees (os-tesla), relay run 36551527955, read-back MATCHES; (3) this os-dev-report comment → POST /repos//issues/20613/comments. Plus git push to the branch (not REST). The PR body was not edited after create.",
"deviations": [
"Hypothesis 3 partly falsified: the eviction is not 'each new landing cancels the waiting deployment'. The measured behaviour is that the job holding the release-publish group waits at the environment WHILE HOLDING it, and pending jobs evict each other. The fix still stops the eviction (one publish job per version), and it makes the stale-holder cancel necessary, not optional.",
"The label-write call added skip-changeset together with the PR assignee, in the ONE budgeted call. AGENTS.md's criterion applies (all paths are in the private root package or docs/adr, and no files[] ships them). The dispatch named only the assignee; the os-dev contract makes skip-changeset the default under that criterion.",
"The publish guard inlines the npm present/absent/unknown reading instead of calling the script. This is deliberate: the guard executes nothing from the tree it guards, and the version commit may predate the script. It is documented in the YAML.",
"Commit trailers use AGENTS.md's model-free pair, not the harness reminder's model-named Co-Authored-By. The PR footer uses AGENTS.md's session-URL form, not the harness's form. AGENTS.md and the os-dev contract take precedence.",
"check:type-check-debt NOT MEASURED, and the full eslint run was narrowed to the one changed .mjs; both are declared above. check:pm-dispatch-gates ran outside the foreground cap, detached and waited on with tail --pid.",
"The worktree was removed after the PR opened (clean, no --force). The branch tip on origin is ad81344."
],
"open_questions": [
{
"question": "Hypothesis 4, confirm or downgrade: the release workflow gains a job holding actions: write that auto-cancels push-lane runs waiting at 'release' for a version already on npm (implemented; triage 5886053015 said 'cancelled'). Keep it?",
"options": [
"A: keep cancel (as implemented). Needs actions: write on one small job. Never touches a dispatch run or a started job. Backed by the publish-guard refusal. A stale prompt is gone at the next landing and can no longer hide a real one.",
"B: report-only. Needs actions: read. The job emits a warning and a summary line, and the guard refusal stays. The prompt stays waiting AND keeps holding release-publish-REF, so the next version's prompt stays hidden behind it (the measured 17.4.0 to 17.5.0 failure).",
"C: guard refusal only. No new job and no new permission. Approving a lookalike publishes nothing and says so, but the lookalike still hides the real prompt."
],
"recommendation": "A. Real business need, measured: the stale holder hid 17.5.0's prompt and was approved by mistake, and 36539819278 is the same shape today. Long-term: the fix is contract-first, a push lane that can only cancel what could never publish; B and C leave the queue blocked. Preventing AI or human error: approval noise is how an approval stops being read, and A removes the lookalike instead of teaching care. Startup focus: one job, no new gate. Its cost is the actions: write grant; dropping the job reverts to C in one hunk."
}
],
"out_of_scope_findings": [
"carrier: none · noted, not filed. release-github-releases.mjs reads GITHUB_SHA for the CHANGELOG permalink and target_commitish. In publish, GITHUB_SHA is now the queuing head, not the version commit. target_commitish is unused because the tags already exist at the version commit, and the permalink still resolves. PR Acceptance notes. dedupe words: release-github-releases GITHUB_SHA permalink target_commitish",
"carrier: none · noted, not filed. The release-integrity backfill (Releases, spec-changes.json --prepare/--attach for an already-published version) still runs on github.sha's workspace, not the version commit's. Same class (acts on github.sha), no-mint repair lane, outside the claim's surface. No reach measured. dedupe words: release-integrity backfill spec-changes version commit github.sha",
"carrier: none · noted, not filed. Run 36540562567 (push 7510663, 08:05Z) is red on main. Its Docker job 109315667024 failed at 08:09Z after release-integrity took the backfill branch while 36536081716 was mid-publish (cli canary on npm 07:58:57Z; publish ended 08:11:15Z). Cause NOT MEASURED: job logs answer 403 through the container proxy. Possible defect: 'cli on npm' is read as 'published' during an in-flight publish. The seat should judge whether to file. dedupe words: release-integrity in-flight publish docker image canary backfill race",
"carrier: none · noted, not filed. The release-verify-npm.mjs header says the workspace was 'proved [to match] github.sha'; it is now the version commit. Comment drift, outside the surface.",
"carrier: none · noted, not filed. ADR-0125 has no scripts/adr-anchors/ entry (before or after this PR); the implementing files name it in comments."
]
}

---

Generated by Claude Code

[objectstack-fleet]

ACCEPT (Tier H) — PR #20625 at head ad8134464d · domain:spec seat 2 (session_014EJ1ED8X4MMrT18BhVx4tx) · 2026-09-29T10:09Z

The seat reviewed the dev report on this card against GitHub and the diff. The PR amends ADR-0125, a governed surface, so it lands by the maintainer's hand or on an authorized APPROVED review. It stays draft; the seat hands it over with the maintainer's quick-read on the PR.

• PR shape: draft, base main, first line Fixes #20613, Clause-②: no, skip-changeset, assignee os-tesla. 4 files (+1133 / −54):
  • .github/workflows/release.yml (+305 / −53);
  • scripts/release-pending-publish.mjs (new, +752: the selection logic, the stale-prompt judgement, and a --self-test of 32 cases in 11 batteries);
  • .github/workflows/lint.yml (+16: that self-test, in Lint & Repo Gates);
  • docs/adr/0125-release-approval-gate-replaces-the-typed-version.md (+60 / −1: an amendment to D1's premise).
  • check-governed-merges --pr 20625: GOVERNED, Tier H; 1,187 changed lines, under the 5,000 threshold.
• What it does:
  • release-integrity names the version commit: the newest first-parent commit where packages/cli/package.json's version differs from its parent's. On a push, a publish is pending only when this push carries that commit and the version is off npm. On the repair dispatch, it is pending only while the version is off npm.
  • publish checks out that commit. Its guard refuses an empty or mismatched ref, a commit not on origin/main after approval, a commit whose parent carries the same version, and a stale prompt approved outside force. The #6170 tripwire runs against the version commit.
  • A new stale-prompts job (actions: write) cancels push-lane runs waiting at release for a version already on npm. It never touches a dispatch run or a started job.
• Evidence (dev):
  • The self-test passes, and six ablations each turn it red.
  • A read-only replay of the real 17.5.0 pushes: the batch carrying 8c87d26a5d is pending; the four later landings are not.
  • The step scripts were extracted and run under shims. The guard ran 8 cases in a throwaway clone.
  • 65 derived gate families: 64 exit 0, and check:type-check-debt is NOT MEASURED (it needs the whole packages/* closure; the diff touches nothing under packages/).
  • The seat checked the dev's transcript: no Actions write call of any kind; its live sweep ran through a GET-only client.
• At-tier contract review: 5888029963 on the PR, at CONTRACT_REVIEW_TIER, on this head — PASS.
  • The predicate is right on every edge case read from the code: a batch, a later landing, a zero, missing or non-ancestor before, a non-linear range, a bump then a revert, two bumps, and a shallow checkout. It was confirmed against origin/main's own history.
  • Every later GITHUB_SHA read in publish is harmless; the tripwire holds because the checkout is asserted to be the version commit first.
  • The dev's correction of hypothesis 3 is right on the runs. The job holding release-publish-main waits at the environment while holding the group; later jobs pend behind it and evict each other. The fix keeps "never cancel a publish mid-flight".
  • The ADR amendment follows the repo's idiom and changes nothing else. lint.yml moves one step. skip-changeset and Clause-②: no are right.
  • Nothing in the diff performs, triggers or approves a release act.
  • The seat checked its transcript: served at tier, read-only, one write (that comment).
• The dev's open question, answered by the seat: keep A (cancel). It is triage's direction (5886053015: "cancelled, not left waiting"), and the review found it sound on the code. It is a permission boundary, so it goes to the maintainer in the quick-read, with B (report only) and C (guard only) as one-hunk fallbacks.
• Findings:
  • Live now: run 36539819278 ("Publish 17.5.0 to npm") has waited at release since 08:11Z, and @objectstack/cli@17.5.0 has been on npm since 07:58Z. It holds the publish group, so it would hide 17.6.0's prompt. ⛔ No seat rejects or cancels it (AGENTS.md PD Add missing Field.phone() helper and factory methods for Action/Dashboard/Report #15). It is raised to the maintainer in this seat's chat and in the quick-read. The first push after this PR merges cancels it.
  • The docker backfill in run 36540562567 went red at 08:09Z. Its audit read cli@17.5.0 on npm while run 36536081716 was still publishing (until 08:11Z): "cli on npm" was read as "publish complete". Measured: @objectstack/spec@17.5.0 reached npm at 08:09:33Z, one second after the backfill's build failed. Outside this card's surface → filed [finding] release.yml: release-integrity reads "cli on npm" as "the publish is complete", so a landing during a publish starts the docker backfill before the fixed group is on npm, and it goes red #20627.
  • release-github-releases.mjs and release-verify-npm.mjs still name GITHUB_SHA in a permalink, a target_commitish and a header comment. All are harmless (the tags exist at the version commit) → Acceptance notes.
  • The release-integrity backfill still acts on github.sha's workspace. It is the no-mint repair lane, outside the claim, and no reach was measured → Acceptance notes.
  • release-integrity now fetches full history (fetch-depth: 0) on every push to main, which lengthens the audit. NOT MEASURED → the seat reads the first post-merge push's audit duration; if it is minutes, filter: blob:none is the cheap fix.
  • ADR-0125 has no scripts/adr-anchors/ entry, before or after → Acceptance notes.
• Landing: needs-user-decision goes on the PR in this act. The seat's quick-read is posted on the PR, and os-zhuang and hotlong are requested as reviewers. On an authorized APPROVED review, this seat runs the pre-landing checks, clears the label, flips it ready and arms auto-merge; or the maintainer merges it by hand.

---

Generated by Claude Code