docs(devx): the port-pin rationale in check-bash32-floor.mjs described a retired field

[baozhoutao]

Fixes #8385

This is prose with no gate over it — the diff is the evidence

Nothing in this repository reads the text of this section. Measured, with a control in the same class and same run:

$ git grep -n -F "Why this port is not pinned" -- .
scripts/check-bash32-floor.mjs:162: * ## Why this port is not pinned in `scripts/upstream-port-pin.json`
hunt_exit=0                      # one hit, the file itself — nothing quotes it

$ git grep -c -F "check-bash32-floor" -- .       # control: the pattern class does find things
.github/workflows/lint.yml:3
package.json:1
scripts/__tests__/bash32-floor-wiring.test.ts:5
scripts/check-bash32-floor.mjs:13
... 9 files
control_exit=0

scripts/__tests__/bash32-floor-wiring.test.ts uses the file only as a path and a spawn target (GATE, node ${GATE} --self-test, import(GATE)); no pin reads its docblock. So no check can turn red or green on this change — read the diff. What the checks below prove is only that the docblock edit did not break the parse.

What was wrong

The section's whole argument rested on pin.upstream.ref, a single ledger-wide field. objectui#8288 retired it. On origin/main da5e4f69e:

clause in the old prose	tree today
"the ref is a SINGLE GLOBAL field (pin.upstream.ref), one per pin and not one per file"	FALSE. scripts/upstream-port-pin.json → upstream: {repo} only. ref is a required key on each files[] entry (check-upstream-port-parity.mjs: typeof f.ref !== 'string' || !HEX40.test(f.ref) → bad(...)), and validatePin refuses a pin that still carries upstream.ref.
"--resync rewrites it for the whole ledger (pin.upstream.ref = ref;)"	FALSE. resyncedPin maps files and touches only the matching entry: f.ported === portedPath ? { ...f, ref, upstreamSha256 } : f.
"The ledger currently names bf10deb"	FALSE, and already false before objectui#8288 — objectui#7749 had moved the global ref. There is now no ledger-wide ref to name at all.
both enumerated registration options, and the "third option that must not be taken"	all three were consequences of the single global field; none exists as a trade any more.
"objectui#7953 already owns [the single-global-ref limitation] … must not be re-filed"	the limitation is gone; the pointer is kept, its reasoning replaced.

⇒ this was not prose "about to go stale". A reader following it went looking for a field that would be rejected if they wrote it.

⛔ Why the new wording names no revision

This is the load-bearing constraint on the rewrite, and the reason it exists:

That section had already gone stale twice by the same mechanism — objectui#7749 moved the global ref out from under the sentence describing it, then objectui#8288 deleted the field the sentence named. Both times the prose stayed confident and wrong. Restating a SHA now would make it stale a third time, by that exact mechanism, inside the paragraph explaining that mechanism.

So the new text points at scripts/upstream-port-pin.json, where each entry now carries its own ref that --resync keeps correct, and adds a ⛔ note telling the next editor not to write one back in. Verified, hunt and in-class control in one run:

$ grep -conP '\b[0-9a-f]{7,40}\b' <the rewritten section>
0                       hunt_exit=1
$ grep -cnP '\b[0-9a-f]{7,40}\b' scripts/check-bash32-floor.mjs
4                       control_exit=0     # the pattern does find SHAs, elsewhere in the same file

What is kept

Triage flagged one clause as the real reason the section exists, and it survives:

Consequence, stated so it is inherited rather than rediscovered: … this file has NO drift gate.

Kept, with "until that registration lands" added, and the trade-off sentence corrected: that cost was once accepted because paying it meant weakening a gate; it is now simply unpaid.

Scope

Item 1 of objectui#8385 only, as triage narrowed it. Items 2 and 3 are filed and not touched here — they change the pin ledger, which is not a prose fix:

• devx: register scripts/check-bash32-floor.mjs in scripts/upstream-port-pin.json at its own ref — item 2 of objectui#8385, unblocked by objectui#8288 #8694 — register check-bash32-floor.mjs at its own ref.
• devx: re-triage objectui#7953's ported .claude/hooks/** files against the per-file ref, per file rather than as one batch — item 3 of objectui#8385 #8696 — re-triage objectui#7953's ported .claude/hooks/** files per file (governed surface; --resync needs --rewrite-governed-file there).

The pin ledger is unchanged by this PR (scripts/upstream-port-pin.json is not in the diff).

Checks

Run on a1fdcc5d3:

check	exit	verdict line
node scripts/check-bash32-floor.mjs --self-test	0	✓ check-bash32-floor self-test: 160 cases pass. — the parse proof
node scripts/check-bash32-floor.mjs	0	✓ check-bash32-floor: 13 tracked shell file(s) … name no bash 4+ construct …
vitest run scripts/__tests__/bash32-floor-wiring.test.ts	0	Test Files 1 passed (1) · Tests 9 passed (9) (under the shared verify lock, VERDICT command-exit 0)
node scripts/check-upstream-port-parity.mjs	0	✓ … 3 ported file(s) match … each at its own pinned ref (2 distinct: …) — also the live evidence for the new prose
node scripts/check-control-bytes.mjs	0	✅ check-control-bytes: OK (scanned 6881 tracked text file(s))
node scripts/check-changeset-presence.mjs	0	No source or published contract of a released package changed … no changeset is owed
node scripts/check-changeset-no-major.mjs	0	✅ No changeset declares a major bump.
node scripts/check-pre-install-import-graph.mjs	0	✅ … 26 pre-install step(s) … every non-relative leaf a node builtin
node scripts/check-governed-queue-guard.mjs --self-test	0	OK … 132 cases pass
eslint --no-inline-config --format json on the 2 changed files	0	2 files linted, 0 errors (the .md reports "File ignored because no matching configuration was supplied")

Exit codes were captured before any pipe.

Not measured, and why: check:node-esm-load exits 1 in this worktree with ✗ 2 of 37 entries REFUSED — @object-ui/plugin-dashboard and @object-ui/plugin-map, both ERR_UNKNOWN_FILE_EXTENSION on a .css import from node_modules. The gate says in those words that it "does not grade what this tree did not produce": the build leg was not run here. grep -c 'bash32-floor' over its 9k-line output is 0, so the refusal names nothing in this diff. CI runs it after a build.

Changeset

.changeset/8385-bash32-floor-port-rationale.md, empty frontmatter — AGENTS.md §9's first-class "declare once, release nothing" form. Nothing here is published source of a released package and no package.json publish-contract field moved; check-changeset-presence agrees none is owed, and the declaration is added anyway so the reason is on record.

维护者速读(草稿)

改了什么 — scripts/check-bash32-floor.mjs 顶部 docblock 里那一节「为什么这个 port 没有登记进 pin 台账」的散文,约 40 行重写为 53 行。加一个空 frontmatter 的 changeset。⛔ 没有改任何代码、没有改 pin 台账、没有改门禁行为。

为什么改 — 那段论证的整个前提是 pin.upstream.ref 这个全局字段。objectui#8288 已经把它退役,并且 validatePin 现在会主动拒绝还带着它的 pin。所以那段散文不是「将来会过时」,它现在就是错的,而且是最坏的错法:照它去理解的人,会去找一个写进去就会被拒的字段。

风险与代价(含回滚) — 风险接近零:改的是注释,没有任何门禁读它的文本,门禁跑绿只证明 .mjs 没被改坏。回滚 = revert 这一个 commit,不影响任何别的东西。代价是这一节现在不再声称「没有 drift gate 是可接受的」——它现在如实说这笔债是欠着的,并指向 #8694 去还。

席位意见 — (留空,待定稿)

你要做的 — 读 diff 本身(没有门禁能替你读)。特别请确认两件事:① 新措辞里一个 SHA 都没有,是故意的硬约束,因为这一节已经因为写死 SHA 过时过两次;② 拆出去的 #8694 / #8696 是刚被 #8288 解锁的真实工作,不要随本卡一起关掉。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr

---

Generated by Claude Code

[claude]

ACCEPT — objectui#8385 / PR objectui#8697, domain:devx @ objectui PM seat, 2026-09-08T23:05Z

Reviewed against GitHub and origin/main at head a1fdcc5d3, ⛔ not against the report's narrative.

What this seat re-measured

claim	this seat's reading	verdict
prose only	scripts/check-bash32-floor.mjs +41 −30, and every added and removed line is a comment line	✅
⭐ ⛔ no SHA in the new prose	0 SHA-like tokens among the added lines	✅
⭐⭐ and that zero is a READING	in-class control on origin/main: the same pattern finds 11 SHA-carrying lines elsewhere in that very file ⇒ the pattern can match here	✅
scope held to item 1	2 files: the docblock and one changeset. ⛔ The pin ledger is not in the diff	✅
items 2 and 3 filed, ⛔ not done	objectui#8694 and objectui#8696 — both bare: ⛔ no labels, ⛔ no assignees	✅
draft, Fixes #8385	✅	✅

⭐ The card named three false clauses; the dev found EIGHT and enumerated each

Including the one this seat would most likely have let stand: the section's closing claim that "this file has NO drift gate … That is a real cost and it is accepted here rather than paid for by weakening either gate." ⭐ The consequence is still true and was kept; its justification was false. It became: "That cost was once accepted because paying it meant weakening a gate; it is now simply unpaid, and the work to pay it is ordinary."

⇒ ⭐ that is the difference between a prose fix and a prose repair: the sentence that was true-by-accident got a true reason instead of being deleted or left alone.

⭐ And the heading moved ## Why this port is not pinned … → ## Why this port is not **YET** pinned …, which is the whole finding in one word.

⭐ The blocker question, answered without touching the ledger

The brief asked whether the structural blocker is in fact gone, ⛔ while forbidding any pin. Answer: yes, on four independent readings — the global field is gone; resyncedPin leaves non-matching entries structurally untouched; two distinct refs already coexist in the ledger; and scripts/** is not governed, so --resync needs no flag there. ⚠️ For the .claude/hooks/** half the blocker is likewise gone, with one residual cost, ⛔ not a blocker: .claude/** is governed, so --resync refuses without --rewrite-governed-file.

⇒ ⛔ nothing was pinned, and both ledger-changing items left as bare cards. ⭐ Exactly the boundary the dispatch drew.

⭐⭐ A new trap, and it applies to every dev in this fleet

A zero-reading came back contaminated: hunting a build log with the alternation bash32-floor|8385 returned 56 hits — every one the literal 8385 inside the worktree PATH /home/user/objectui-issue-8385/. Re-run with bash32-floor alone: 0. The first reading was discarded.

⚠️ ⇒ every worktree in this fleet is named /home/user/objectui-issue-<N>, so any pattern containing the issue number matches its own working directory. ⭐ That is a false-positive twin of the docblock trap, and this seat is adding it to the standing corrections — found by the dev, on itself.

⭐ It also discarded a TAB control as invalid, on the grounds that \x09 is deliberately outside the hunted class — the second dev today to refuse a control that was not in the class being controlled.

⭐ And a red it refused to read as a red

check:node-esm-load exits 1 in the worktree — "2 of 37 entries REFUSED … the load leg does not grade what this tree did not produce", both ERR_UNKNOWN_FILE_EXTENSION on a node_modules .css import with the build leg unrun. ⇒ reported as NOT MEASURED, ⛔ not red, and checked: grep -c 'bash32-floor' over its 9k-line output is 0, so it names nothing in this diff.

⚠️ And it answered the brief's standing invitation honestly

"brief_corrections: None" — every coordinate this brief gave was re-measured and found accurate. ⭐ That is the right answer when the brief happens to be right, and it is only worth anything because two devs this shift said the opposite and were correct.

Next

ci-wait on a1fdcc5d3, then flip, post-flip guard, arm SQUASH, enqueue from the timeline event.

Landing probe, scoped now: on a re-fetched origin/main, the section heading reads not YET pinned; the section contains 0 SHA-like tokens; ⭐ firing control — the same pattern still finds SHA-carrying lines elsewhere in that file (it was 11), so the 0 stays a reading, ⛔ not a dead pattern; scripts/upstream-port-pin.json is unchanged; nonsense control exits 1.

---

Generated by Claude Code

[claude]

Armed — objectui#8697, 2026-09-08T23:29Z

step	reading
CI on a1fdcc5d3	29 success, 3 skipped, 0 pending, 0 failures
flipped ready	ready_for_review@2026-09-08T23:29:14Z
⚠️ post-flip guard	the flip spawned a new Governed Surface Queue Guard; the post-flip run is completed/success@2026-09-08T23:29:30Z
armed	enable_pr_auto_merge SQUASH
⭐ enqueue	added_to_merge_queue@2026-09-08T23:29:36Z, from the timeline event, ⛔ not the auto_merge field

Landing probe, restated before the merge:

• the section heading reads not YET pinned;
• ⭐ 0 SHA-like tokens inside that section — and the firing control is what makes that a reading: the same pattern must still find SHA-carrying lines elsewhere in the same file (it found 11 on the pre-merge tree), or the zero is a dead pattern rather than a fact;
• scripts/upstream-port-pin.json is unchanged — ⛔ this card fixes prose, it does not pin;
• nonsense control exits 1.

---

Generated by Claude Code

[claude]

Queue status at 2026-09-09T00:35Z — ⛔ this PR's delay is not its own diff

Enqueued at 23:29Z, still unmerged 66 minutes later. Establishing why, so the next reader does not re-derive it:

• origin/main has taken zero merges since 22:07Z (da5e4f69e). 14 PRs are enqueued.
• The built group is the top max_entries_to_build: 5 — test(core): pin the page list-view residual, and report the usage census objectui#8429's grade is blocked on #8684, fix(plugin-detail): a masked row offers no copy affordance #8685, test(core): widen the record-title step-numbering pin to its sibling test file #8656, i18n(metadata-admin): delete four dead ENGINE_STRINGS keys #8687, fix(plugin-form,types): resolve form.sections[].group through the single field-group assembler, and bound the section loop that blanked the form #8644 — and it has been re-formed three times (22:32Z, 23:23Z, 00:24Z) with no entry evicted (not one removed_from_merge_queue event in 100 minutes).
• pr-8684's group branch went fully green on all nine required contexts twice — last check completing 22:48:18Z and 23:39:32Z — and merged neither time. Read job-by-job. ⇒ this is ⛔ not objectui#8099's mode (every required context did report, well inside the 60-minute timeout).
• The longer prefixes go red on one single required check, Test (shard 2/4), with the same assertion each time: packages/permissions/src/__tests__/providerCtxIdentity.discarded.test.tsx:619, 695 of 697 files passing. That is objectui#8688 — a guaranteed ordering violation, not a flake — whose fix is PR test(permissions): wait on the array the assertion reads (objectui#8688) #8689, itself enqueued at position 6 behind the entries its fix would turn green.
• Under grouping_strategy: ALLGREEN the group merges only if every built entry is green, so one red entry discards the green ones and re-forms.

Control: this PR's 2 files touch nothing under packages/permissions/, and neither do the other twelve enqueued PRs — only #8689 does, which is the fix itself. The same query returning a hit on #8689 is the firing control, so the zero is a measurement.

⇒ nothing to fix here and ⛔ nothing to re-run — a re-run buys one more coin flip and another ~50 minutes of shared queue time. This PR stays enqueued. The queue-level exposure is filed as objectui#8715; the test defect is objectui#8688.

---

Generated by Claude Code

[claude]

⭐ LANDED — objectui#8385 / PR #8697, merged 6621cf39b at 2026-09-09T00:57:39Z

Probe run verbatim from the Armed note (5593333583) against a re-fetched origin/main (5ece49bbc), 01:20Z. ⛔ Not re-invented, ⛔ not read off the dev's report.

leg	reading	verdict
heading reads not YET pinned	:162 — ## Why this port is not YET pinned in \scripts/upstream-port-pin.json``	✅
⭐ 0 SHA-like tokens inside that section	section spans :162–:214 (next heading ## Population at :215); the file's 4 remaining SHA-carrying lines are at :8, :41, :223, :1382 — all outside it	✅
⭐ firing control	the same pattern on the pre-merge blob (6621cf39b^) finds 11 SHA-carrying lines — exactly the number the Armed note recorded — and still finds 4 elsewhere in the post-merge file	✅ the zero is a reading, not a dead pattern
scripts/upstream-port-pin.json unchanged	git diff 6621cf39b^ 6621cf39b -- scripts/upstream-port-pin.json → 0 lines; the commit's own stat carries exactly 2 files (the changeset and the script)	✅ ⛔ this card fixed prose, it did not pin
nonsense control	exits 1, no match	✅

⭐ And the section now carries its own recurrence guard, which is more than the card asked for: :191 reads "⛔ Do not write a revision into this prose. A port's ref lives on that port's entry in scripts/upstream-port-pin.json; read it from there." — followed by the two occasions it went stale before (objectui#7749 moved the global ref out from under the sentence; objectui#8288 deleted the field the sentence named). That is the defect's cause written down where the next author will hit it, not just the instance repaired.

---

Generated by Claude Code

[claude]

⛔ Correction to my queue-status note above — the mechanism I gave was wrong

domain:devx seat, 01:33Z. The note I posted at 00:35Z said this PR's delay came from grouping_strategy: ALLGREEN discarding green head entries because of a flaking Test (shard 2/4). That was wrong. Its conclusion — "this PR's delay is not its own diff" — was right, but for a different reason, and I am not leaving a wrong mechanism standing on the record.

PR #8683 (chore(deps): Bump next from 16.3.1 to 16.3.3) sat at the head of the merge queue from 22:24Z to 00:24Z with ⭐ zero merge_group runs ever dispatched for it. A merge queue is strictly ordered, so everything behind it built green and could not merge. That is objectui#7010's documented wedge, and this repository's Merge Queue Head Patrol detected it correctly on seven consecutive runs, naming #8683 each time.

The Test (shard 2/4) failures (objectui#8688) were real but incidental — a flake ejects and re-forms a group; it does not hold main static for 2h34m.

⭐ My method error, since it is the reusable part: GraphQL mergeQueue is 403 for this token, so I could not enumerate the queue — and instead of saying so, I reasoned about the set of PRs carrying merge_group runs as though it were the queue. By construction that cannot see a wedged entry, because zero merge_group runs is the defect. #8683 was invisible to every reading I took.

Full account on objectui#7010 (5594362159). The card I filed on the wrong mechanism, objectui#8715, is closed as a duplicate.

---

Generated by Claude Code