fix(live-e2e): derive the showcase-app commit from the release tag at boot instead of pinning it

[claude]

Fixes #7964

Implements the maintainer ruling on that card verbatim. Final head cdf8ffd57, base b6f821a8b.

The ruling

Ruling. e2e/live/ci/backend.env keeps one pin, OBJECTSTACK_VERSION (checked against pnpm-lock.yaml by the #7689 test). OBJECTSTACK_REF is no longer a hand-moved sha: start-backend.sh resolves it at boot from the release tag @objectstack/cli@${OBJECTSTACK_VERSION} (git ls-remote --tags or the API, with the token the lane already has) and refuses to start when the tag does not resolve. The pair the file's header describes then cannot disagree by construction; the sparse-checkout of examples/app-showcase and the installed packages always come from the same release. Route 1 (a check inside an informational lane) buys a red nobody reads; route 3 leaves a drift no eye can spot.

Execution notes. #7689 has landed, so this file is free to edit. Remove the OBJECTSTACK_REF line and its header MUST; document the derivation in the header; the unit-lane test keeps the version half. Record on this card the resolved sha for the current OBJECTSTACK_VERSION as the first proof the derivation works. Whether the live-e2e lane should stay informational is a separate question — file it as its own card with the evidence of what the lane proves once this lands, not as a rider here.

The proof the ruling asks for

git ls-remote --tags https://github.com/objectstack-ai/objectstack.git 'refs/tags/@objectstack/cli@17.2.0' 'refs/tags/@objectstack/cli@17.2.0^{}'

2b59e70449fc168cb18793955c08f415c7abc015	refs/tags/@objectstack/cli@17.2.0
e7d2cc67fdef7fee9d2c6d65d7363fe1c78ce6a4	refs/tags/@objectstack/cli@17.2.0^{}

Annotated tag. The peeled ^{} line is the commit; the first line is the tag object and is not a commit — taking it would break the fetch. Running the resolution block extracted byte-for-byte from the committed script:

[live-backend] resolved @objectstack/cli@17.2.0 -> e7d2cc67fdef7fee9d2c6d65d7363fe1c78ce6a4

Resolved sha e7d2cc67fdef7fee9d2c6d65d7363fe1c78ce6a4 is byte-identical to the OBJECTSTACK_REF this PR deletes. The derivation reproduces the hand-moved value exactly — no drift to report, and the removal changes no behaviour on the current version.

End-to-end, the derived sha is fetchable the way start-backend.sh fetches it:

git init -q probe && git -C probe remote add origin https://github.com/objectstack-ai/objectstack.git
git -C probe sparse-checkout set examples/app-showcase
git -C probe fetch -q --depth 1 origin e7d2cc67fdef7fee9d2c6d65d7363fe1c78ce6a4   # exit 0
git -C probe checkout -q FETCH_HEAD                                              # exit 0
# probe/examples/app-showcase/ -> objectstack.config.ts, src/, package.json, ...

The change

e2e/live/ci/backend.env — the OBJECTSTACK_REF= line is gone, and with it the header MUST that nothing could check ("Always the commit the release tag points at ... NOT machine-checked, and deliberately so"). Its paragraph is replaced by one that documents the derivation, says why the old reasoning was wrong (the unit lane cannot reach objectstack; the live lane clones it anyway), and states one consequence rather than papering over it: the fixture cache key is hashFiles(backend.env) and the sha is no longer in the file, so a re-pointed release tag would still be served a stale Actions-cache fixture until OBJECTSTACK_VERSION moves. A reused scratch dir is covered, because the resolved sha is in the stamp.

e2e/live/ci/start-backend.sh — resolves @objectstack/cli@$OBJECTSTACK_VERSION at boot, takes the peeled sha when present and the tag's own otherwise (lightweight tags do not peel), and refuses to start, naming the tag, when the result is not 40 hex characters. Three details that are load-bearing rather than stylistic:

• Both patterns are passed to ls-remote. Asking for refs/tags/TAG alone does not return the peeled line — measured, not assumed.
• git ls-remote reports a missing tag as empty output and exit 0. The shape check is therefore the real guard; an exit-code check alone would carry an empty ref into git fetch --depth 1 origin "".
• The shape check is [[ ... =~ ... ]], not printf | grep -q. Under the script's set -o pipefail a pipeline whose reader exits early can report failure for a value that matched.
• GIT_TERMINAL_PROMPT=0, so an unreachable or private remote fails in seconds with a named message instead of blocking the job on a credential prompt.

No fallback to a hard-coded sha, no override key, no second path. The lane clones from the same anonymous URL three steps later, so no token is needed — verified, and the workflow injects none.

WANT_STAMP now carries the resolved sha, so a re-pointed tag invalidates a reused fixture (A4).

scripts/__tests__/ci-cd-pipeline-doc.test.ts — see below.

Prose that described a two-pin pair — content/docs/guide/ci-cd-pipeline.md (which called BETTER_AUTH_VERSION "a third pin" and warned against repairing "the two pins above"), e2e/live/ci/better-auth-pin.mjs, and the header comment of e2e/live/saved-view-filter.spec.ts. Leaving those would have reproduced this card's own defect one file over. The sentence PIN_RULE_SENTENCE pins is untouched.

Pins retired and added, deliberately

Retired: keeps OBJECTSTACK_REF in the one shape start-backend.sh can fetch. It asserted that a hand-moved sha was 40 hex characters — the only half of the pin a network-less lane could read. There is no hand-moved sha any more, so it has nothing to hold. The file says so at the retirement site, with a standing prohibition on restoring the key.

Added, all three in the same describe:

Test	Holds
declares no OBJECTSTACK_REF — the commit is derived, not pinned	the pin stays retired; a restored key reopens the drift
derives the commit from the @objectstack/cli release tag in start-backend.sh	git ls-remote --tags is still there, the tag is still built from OBJECTSTACK_VERSION, and the refuse-to-start shape check is still there
documents the derivation in backend.env, where the pin used to be	the absence stays legible as a decision, so nobody "restores" it

Either of the first two alone would be vacuous: an absent key is a design only while something derives the value, and a derivation is load-bearing only while no pin overrides it. The header block of the describe says this in full.

The version pin's failure message no longer instructs the reader to hand-move a second value.

Ablations — each new pin proven able to fail

Mutation applied to the committed tree, landing proven on disk (anchor grep -c before/after and git hash-object compared to the HEAD blob), test run, then restored with git checkout HEAD -- PATH and git diff HEAD proven empty. Under trap ... EXIT INT TERM with absolute paths.

#	Mutation	Result
M1	re-add OBJECTSTACK_REF=e7d2cc67… to backend.env	exit 1 — 2 failed / 44 passed
M2	replace git ls-remote --tags with a non-resolution	exit 1 — 1 failed / 45 passed
M3	hard-code the tag as @objectstack/cli@17.2.0 instead of deriving from $OBJECTSTACK_VERSION	exit 1 — 1 failed / 45 passed
M4	delete the refuse-to-start shape guard	exit 1 — 1 failed / 45 passed
M5	delete the header note explaining the absence	exit 1 — 1 failed / 45 passed

All five turned red (the predicted direction). Tree byte-identical to cdf8ffd57 afterwards; the suite is green again at 46 passed.

The refusal path was also exercised directly, on the resolution block extracted byte-for-byte from the committed script:

OVERRIDE_VERSION=0.0.0-no-such-release   -> exit 1, "release tag '@objectstack/cli@0.0.0-no-such-release' does not resolve to a commit in ..."
OBJECTSTACK_REPO_URL=UNREACHABLE_REPO    -> exit 1, "cannot reach ... to resolve the release tag" / "terminal prompts disabled"

Gates — exit codes captured by redirect, never through a pipe

Run in the worktree at cdf8ffd57, working tree clean.

Command	Exit	Verdict line
pnpm exec vitest run scripts/__tests__/ci-cd-pipeline-doc.test.ts (on the base, before edits)	0	Tests 44 passed (44)
pnpm exec vitest run scripts/__tests__/ci-cd-pipeline-doc.test.ts	0	Tests 46 passed (46)
pnpm exec vitest run scripts/__tests__ --maxWorkers=2	0	Test Files 115 passed (115) / Tests 3417 passed (3417)
bash -n e2e/live/ci/start-backend.sh	0	—
pnpm lint:root	0	32 problems (0 errors, 32 warnings) — all pre-existing, none in the changed files
pnpm check:control-bytes	0	check-control-bytes: OK (scanned 6580 tracked text file(s))
pnpm check:entry-guard	0	70 scripts/ file(s) — no entry guard outside the baseline
node scripts/check-changeset-presence.mjs	0	No source or published contract of a released package changed in this range, so no changeset is owed.
node scripts/check-governed-queue-guard.mjs --test (all 6 changed paths)	0	NOT GOVERNED — 6 path(s) checked against 5 governed surface(s); none matched.
grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' over the 6 changed files	1	no control bytes

shellcheck is not installed in this container, so it is declared to CI rather than claimed here. bash -n is green and the script is unchanged in structure.

No changeset, on the gate's own verdict: 6 files changed, 0 of them published source of a released package, 0 a manifest whose published contract moved. The skip-changeset label is deliberately not applied — in this repo it reads nothing and exempts nothing.

The live lane itself was not run locally and cannot be: it installs from npm, builds the console and boots a backend behind a 300s readiness gate. What was proven locally is every step the change touches — tag resolution, the refusal, and the fetch of the resolved sha.

Not in this PR

The ruling's last sentence, filed as its own card: #8275 — whether the lane should stay informational, with the evidence of what it proves once this lands and the counter-evidence (#7990, the lane red on main from an upstream float, not an objectui diff). Label finding, unassigned. .github/workflows/live-e2e.yml is untouched here on purpose; removing the OBJECTSTACK_REF line does change its hashFiles(backend.env) fixture cache key, which is expected and desired — the next run rebuilds the fixture once.

---

Generated by Claude Code

[claude]

ACCEPT (#7964, route 2) — reviewed on the tree at head cdf8ffd57 against origin/main b6f821a8b, read 2026-09-07T07:41Z; domain:devx @ objectui seat, PM session session_01FhBNJcLRZLe8M87VcUgpKr.

Verified from the diff, not the report:

• backend.env declares one @objectstack pin (OBJECTSTACK_VERSION=17.2.0); the OBJECTSTACK_REF= line and its MUST are gone; the header documents the derivation and states the one cache-key consequence (a re-pointed tag served stale until the version moves) instead of hiding it.
• start-backend.sh resolves @objectstack/cli@$OBJECTSTACK_VERSION with git ls-remote --tags passing both the tag and its ^{} pattern, prefers the peeled sha, refuses with a message naming the tag when the result is not 40 hex (the empty-output/exit-0 case of a missing tag is the guard's reason), sets GIT_TERMINAL_PROMPT=0, and carries the RESOLVED sha in WANT_STAMP; the fetch and log lines use the derived value; REPO_URL is the pre-existing variable.
• Test: the REF shape pin is retired at its site with a prohibition on restoring the key; three content pins replace it (no OBJECTSTACK_REF= key; ls-remote + tag built from $OBJECTSTACK_VERSION + the 40-hex refusal present; the header note present). The version pin's message no longer instructs a hand move.
• Prose sites that described a two-pin pair (ci-cd-pipeline.md, better-auth-pin.mjs, saved-view-filter.spec.ts) now describe the single pin plus derivation; the residual OBJECTSTACK_REF mentions on the head are all historical ("used to be"). PIN_RULE_SENTENCE untouched.
• First proof recorded on the card: the tag peels to e7d2cc67fdef7fee9d2c6d65d7363fe1c78ce6a4, byte-identical to the deleted pin — so this PR changes no behaviour at 17.2.0.
• Six files, none governed; no published src moved, no changeset owed. Fixes #7964 on the first line. Commit trailer carries no model identifier, per this seat's standing rule.
• Follow-up filed as finding(ci): with both live-e2e pins now machine-held, re-decide whether the lane stays informational — and on what evidence #8275 (finding, unassigned, Blocked-by: #7964) for the informational question, as the ruling required; nearest neighbour ci(live-e2e): Live E2E (informational) is red on main and every branch since the backend pin moved to 17.2.0 — the published plugin-auth float (objectstack#16186), not an objectui diff #7990 is about the lane being red, a different question.

Not measured here: shellcheck (absent in the container) and the live lane itself — CI's Lint and the informational Live E2E run on this head are the judges of both.

Next: CI convergence → flip ready → post-flip guard → auto-merge SQUASH → queue confirmation → landing probe (OBJECTSTACK_REF= absent from backend.env on re-fetched origin/main, git ls-remote --tags present in start-backend.sh; control: OBJECTSTACK_VERSION=17.2.0 still present).

---

Generated by Claude Code

[claude]

Hold on the arming of PR #8276 — domain:devx @ objectui seat, PM session session_01FhBNJcLRZLe8M87VcUgpKr, 2026-09-07T08:07Z.

Three readings after the flip to ready (07:54:37Z, head cdf8ffd57, CI converged all green incl. Live E2E at 07:54:23Z):

1. No post-flip Governed Surface Queue Guard run fired on the ready_for_review event in two 240 s windows (read 07:59Z and 08:04Z); the workflow declares that trigger and every earlier flip this shift re-ran it within 15 s. The 07:39Z pull_request run on this head is success and the refusing leg (merge_group) still runs in the queue; the six paths are verified non-governed by check-governed-queue-guard.mjs --test and by this seat's read. Treated as a lost platform event, not a red.
2. Auto-merge was recorded with method merge although SQUASH was requested (REST auto_merge.merge_method read 08:05Z); disabled at 08:07Z. It will be re-enabled with SQUASH and read back before the queue is confirmed.
3. mergeable_state: dirty: PR chore(deps): resolve @objectstack/spec at 17.3.0 in the lockfile #7685 merged at 07:31:44Z (639114c4d) and moved e2e/live/ci/backend.env to OBJECTSTACK_VERSION=17.3.0 / OBJECTSTACK_REF=8a1bad8b8…, which conflicts with this PR's removal of the REF line. The finding(ci): the live-e2e lane's OTHER pin — OBJECTSTACK_REF — states a MUST that nothing can check, and it fails silently in the same way objectui#7689 did #7964 dev has been asked to merge origin/main (fc32921aa) into the branch — merge commit, never a rebase — resolve to 17.3.0 with no REF line, re-prove the derivation for the 17.3.0 tag against the sha chore(deps): resolve @objectstack/spec at 17.3.0 in the lockfile #7685 wrote by hand (both shas reported, whatever the answer), re-run the gates, and push.

Arming resumes after that push: CI convergence on the new head → post-flip guard (already ready, so a synchronize run) → auto-merge SQUASH with read-back → added_to_merge_queue.

---

Generated by Claude Code

[claude]

Merged origin/main at fc32921aa — new head 3c234af3d

Conflict in e2e/live/ci/backend.env only. objectui#7685 (639114c4d) moved the lockfile to @objectstack/spec@17.3.0 and hand-moved both pins with it. This branch had already deleted the second key, so the two sides disagreed about whether it exists.

Resolved to this branch's shape carrying main's value: OBJECTSTACK_VERSION=17.3.0, no OBJECTSTACK_REF key, this branch's rewritten header kept. BETTER_AUTH_VERSION=1.7.2 and its paragraph are byte-identical to what #7685 left — whether 17.3.0 makes that pin retirable is a different question and not this branch's to answer. A merge commit, not a rebase; nothing force-pushed.

The second A2 measurement — and it is the better one

The bump arrived from a PR that had never seen this branch, on a version this branch had never seen. That makes it a cleaner test of the derivation than the original 17.2.0 reading, which merely reproduced a value already sitting in the file.

$ git ls-remote --tags https://github.com/objectstack-ai/objectstack.git \
    'refs/tags/@objectstack/cli@17.3.0' 'refs/tags/@objectstack/cli@17.3.0^{}'
1177d3ee591f72e3b8c828fbec46f4e113ff5c4a	refs/tags/@objectstack/cli@17.3.0
8a1bad8b8ee7189a54229368400b5b427e3ad5e2	refs/tags/@objectstack/cli@17.3.0^{}

Running the resolution block extracted byte-for-byte from the committed script, against the merged backend.env:

[live-backend] resolved @objectstack/cli@17.3.0 -> 8a1bad8b8ee7189a54229368400b5b427e3ad5e2

	sha
derived by start-backend.sh	8a1bad8b8ee7189a54229368400b5b427e3ad5e2
written by hand in #7685	8a1bad8b8ee7189a54229368400b5b427e3ad5e2
	EQUAL

Two for two. The derivation reproduces the hand move on both versions — and the hand move is the step that is no longer needed. Note the tag object (1177d3ee…) is not the commit; taking the unpeeled line would have broken the fetch, which is why the script prefers the peeled one.

End-to-end, the derived sha fetches the way the script fetches it: git fetch -q --depth 1 origin 8a1bad8b… exit 0, checkout FETCH_HEAD exit 0, HEAD = 8a1bad8b…, examples/app-showcase/ present.

Gates on the merged head 3c234af3d

Exit codes captured by redirect, never through a pipe. Working tree clean; pnpm install --frozen-lockfile exit 0 against the 17.3.0 lockfile.

Command	Exit	Verdict
pnpm exec vitest run scripts/__tests__/ci-cd-pipeline-doc.test.ts	0	Tests 46 passed (46) — the version pin now holds 17.3.0 against a 17.3.0 lockfile
bash -n e2e/live/ci/start-backend.sh	0	—
pnpm lint:root	0	32 problems (0 errors, 32 warnings), all pre-existing
pnpm check:control-bytes	0	OK (scanned 6594 tracked text file(s))
node scripts/check-changeset-presence.mjs	0	6 file(s) changed, 0 of them published source … no changeset is owed (vs merge-base fc32921aa)
node scripts/check-governed-queue-guard.mjs --test (6 changed paths)	0	NOT GOVERNED — 6 path(s) checked against 5 governed surface(s)
resolution block, positive (17.3.0)	0	see above
resolution block, missing tag	1	refusal names the tag

All five ablations re-run on the merged head, each with on-disk landing proof and a verified restore: M1 re-add the pin -> exit 1, 2 failed/44; M2 remove ls-remote -> 1 failed/45; M3 hard-code the tag -> 1 failed/45; M4 delete the shape guard -> 1 failed/45; M5 delete the header note -> 1 failed/45. Tree byte-identical to 3c234af3d afterwards, suite green at 46.

One thing worth a maintainer's eye

This merge is the defect the card describes, caught in the act. #7685 had to move a second value by hand and get it right, on a rule no check could enforce — it did get it right, and the branch it collided with is the one that removes the opportunity to get it wrong. That is the argument for the change, made by the tree rather than by the PR body.

---

Generated by Claude Code

[claude]

Armed: PR #8276 on the merged head 3c234af3d (merge of origin/main fc32921aa; 17.3.0 resolution 8a1bad8b8… equal to the hand-written pin, second independent match). CI converged all green (28 checks, read 08:25:21Z); the Governed Surface Queue Guard ran on this head at 08:09:44Z–08:09:55Z (success) while the PR was already ready — the post-flip reading the 07:54Z flip never got; auto-merge SQUASH re-enabled at 08:25Z (the earlier merge-method record was disabled at 08:07Z); added_to_merge_queue at 08:25:39Z (read 08:25:46Z). Landing stroke follows the merge: probe on re-fetched origin/main — no OBJECTSTACK_REF= line in backend.env, git ls-remote --tags present in start-backend.sh, control OBJECTSTACK_VERSION=17.3.0 present; the merge commit's parent count is read to confirm the squash. — domain:devx @ objectui seat, PM session session_01FhBNJcLRZLe8M87VcUgpKr.

---

Generated by Claude Code

[claude]

LANDED: merged at 2026-09-07T09:36:54Z as 272ea0302 (squash — one parent, via the merge queue). Content probe on re-fetched origin/main at 272ea0302 (read 09:37Z): no OBJECTSTACK_REF= line in e2e/live/ci/backend.env (0), control OBJECTSTACK_VERSION=17.3.0 present (1); git ls-remote --tags and the 40-hex refusal present in start-backend.sh (1 / 1). The derived commit for 17.3.0 equals the sha PR #7685 wrote by hand, so this merge changes no behaviour in the lane today and removes the second value for good.

Queue note, for the record. This entry sat green-but-unmerged from 08:41Z to 09:36Z (every required context success on the merge-group head, no removal event). At 09:32Z this seat disabled auto-merge and at 09:33:38Z converted the PR to draft as the only dequeue path without GraphQL; the queue then merged the ORIGINAL group at 09:36:53–54Z regardless, and the seat's 09:37:12Z ready-for-review flip landed on an already-closed PR. Both strokes were no-ops on the outcome and are recorded here so the timeline reads correctly. Whether the 55-minute stall was the queue waiting on something this seat cannot read, or a platform delay, is not knowable from REST; noted as a platform reading, not a defect of this PR.

Card #7964 closes via Fixes; its pm:dispatched label is stripped in the same stroke. — domain:devx @ objectui seat, PM session session_01FhBNJcLRZLe8M87VcUgpKr.

---

Generated by Claude Code