docs(devx): retire the "not registered in the port pin" rationale for check-bash32-floor

[baozhoutao]

Fixes #9206

Fixes, not Refs: this PR closes out all four acceptance items from triage, and nothing of the card survives it. Both copies of the rationale are rewritten, the divergence pairs move in the same change, and no behaviour is touched.

The defect

Two places carried one argument, written twice: scripts/check-bash32-floor.mjs was deliberately unregistered because the ledger carried ONE repository-wide upstream.ref that --resync rewrote for every entry, so registering it meant either shipping an older, weaker construct table or dragging three unrelated ported files to a new ref.

Neither trade exists:

• objectui#8288 retired the ledger-wide field. validatePin in scripts/check-upstream-port-parity.mjs REFUSES a pin that still carries one, and a re-sync writes only the re-synced entry's own ref and digest.
• objectui#8694 then registered this file at its own ref, with its divergences declared.

So both halves were live falsehoods — and the lint.yml copy sat in the workflow step a reader consults first, which is the species the ported file's own header warns about, one level up.

What changed — prose and ledger pairs only

file	change
.github/workflows/lint.yml	the wiring comment states the file IS registered, and says where its ref lives instead of naming one
scripts/check-bash32-floor.mjs	the header clause, and the ## Why this port is not YET pinned section rewritten to a short pointer at the ledger entry
scripts/upstream-port-pin.json	the two matching divergence pairs (header-card-and-ported-banner, why-this-port-is-not-yet-pinned-section) and their why fields
.changeset/9206-retire-unregistered-rationale.md	the record; empty frontmatter, nothing released

⛔ No revision is written into either piece of prose, and the workflow comment's revision (6136293) was dropped rather than refreshed — that section had already gone stale twice by naming one. The pinned ref and upstreamSha256 are untouched.

⛔ The construct table, the exemption rules, POPULATION_ROOTS, the self-test batteries and every behaviour are untouched. --self-test still reports 160 cases and the real-tree scan still reports 13 shell files / 19 constructs.

Acceptance item 3 — the parity gate BOTH ways

The divergence pairs are not decoration here: editing the ported bytes without moving them is red, loudly. Measured on this branch, in this order.

RED — the prose edits applied, the pin not yet touched (exit 1):

✗ scripts/check-bash32-floor.mjs: DRIFTED from the pinned upstream copy.
    divergence `why-this-port-is-not-yet-pinned-section`: expected its ported text exactly once, found 0 — the region it declares has been edited, or upstream moved it
    divergence `header-card-and-ported-banner`: expected its ported text exactly once, found 0 — the region it declares has been edited, or upstream moved it
✗ check-upstream-port-parity: 1 of 11 ported file(s) drifted.

GREEN — the same command after the two pairs moved (exit 0):

✓ scripts/check-bash32-floor.mjs: byte-identical to objectstack-ai/objectstack@61362932b:scripts/check-bash32-floor.mjs modulo 22 declared divergence(s).
✓ check-upstream-port-parity: 11 ported file(s) match objectstack-ai/objectstack modulo their declared divergences, each at its own pinned ref (5 distinct: bf10debd5, 70e77ec3b, 61362932b, c2520416c, 7c2c5aedd).

The digest did not move. The reconstruction is byte-identical to what it was before this PR, which is the proof that the pairs tracked the prose exactly rather than being loosened to accommodate it.

Acceptance item 2 — the three phrases after the fix, with a lit control

Zero in all three touched files, and the zero is a reading: the same git grep invocation over the same three paths, carrying a control term that hits in each.

$ git grep -c -e "NOT registered" -e "not YET pinned" -e "upstream\.ref" -e "check-bash32-floor" \
      -- scripts/check-bash32-floor.mjs .github/workflows/lint.yml scripts/upstream-port-pin.json
.github/workflows/lint.yml:3
scripts/check-bash32-floor.mjs:13
scripts/upstream-port-pin.json:7

$ git grep -c "check-bash32-floor" -- <the same three paths>     # control alone
.github/workflows/lint.yml:3
scripts/check-bash32-floor.mjs:13
scripts/upstream-port-pin.json:7

$ git grep -n -e "NOT registered" -e "not YET pinned" -e "upstream\.ref" -- <the same three paths>
(no output, exit 1)

Combined counts equal the control-alone counts, so the three target phrases contributed 0 lines while the grep was demonstrably live in each file.

Repo-wide, every surviving hit is TRUE and stays:

• scripts/check-upstream-port-parity.mjs (8 hits of upstream.ref) and scripts/__tests__/upstream-port-parity-wiring.test.ts (2) — the retirement itself: the refusal text, its rationale, and the pin test asserting the global ref is absent.
• scripts/check-governed-queue-guard.mjs — "It is NOT registered in scripts/upstream-port-pin.json" about ITSELF. Verified rather than assumed: that path appears 0 times in the ledger (control, same file: 124 "ported": keys), and the ledger's 11 entries do not include it.
• packages/components/.../form.tsx, packages/plugin-kanban/.../kanban-family-registry-keys-retired-8257.test.ts, scripts/check-i18n-dead-keys.mjs — unrelated senses of "NOT registered" (a widget registry, retired kanban keys, i18n reachability).
• .changeset/8385-bash32-floor-port-rationale.md — the changeset of the PR that corrected this section last time. It describes what THAT change did, at the time it did it; one sentence in it ("this file has NO drift gate until it is registered") has since been falsified by objectui#8694. Left as-is, and the reason is measured rather than assumed: its frontmatter is empty, so it publishes no body at the next release — check-changeset-claims reads 1029 of the 1492 pending declarations for exactly this reason and reports No pending changeset names a file this change touches. It is a dated in-repo record, not a future release note, so correcting another PR's record would buy no reader anything. Flagged for the PM seat rather than silently swept.

Gates run locally, with exit codes

Everything whose population covers .github/workflows/**, scripts/*.mjs, scripts/*.json or .changeset/**:

exit	command
0	node scripts/check-upstream-port-parity.mjs
0	node scripts/check-upstream-port-parity.mjs --self-test (58 cases)
0	node scripts/check-bash32-floor.mjs (13 shell files, 19 constructs)
0	node scripts/check-bash32-floor.mjs --self-test (160 cases)
0	node scripts/check-lint-coverage.mjs
0	node scripts/check-action-ref-convention.mjs
0	node scripts/check-control-bytes.mjs (7539 text files)
0	node scripts/check-new-cross-file-line-citations.mjs (0 new citations)
0	node scripts/check-shell-escape-residue.mjs
0	node scripts/check-entry-guard.mjs
0	node scripts/check-pre-install-import-graph.mjs
0	node scripts/check-comment-mask-corpus.mjs
0	node scripts/check-changeset-presence.mjs --base origin/main
0	node scripts/check-changeset-no-major.mjs --base origin/main
0	node scripts/check-changeset-fixed.mjs --base origin/main
0	node scripts/check-changeset-overwrite.mjs --base origin/main
0	node scripts/check-changeset-claims.mjs --base origin/main --head HEAD
0	pnpm type-check:scripts
0	npx eslint scripts/check-bash32-floor.mjs scripts/upstream-port-pin.json
0	npx vitest run --project unit --maxWorkers=2 scripts/__tests__ — 152 files, 4505 tests

Two readings stated precisely rather than rounded up:

• pnpm type-check:scripts is a separate command from any per-package type-check and was run as its own step. What it measured: 937 files, including both pin tests that matter here (scripts/__tests__/bash32-floor-wiring.test.ts, scripts/__tests__/upstream-port-parity-wiring.test.ts), verified with --listFiles. It does NOT type-check the edited .mjs itself — tsconfig.scripts.json sets checkJs: false by design — so the .mjs side is covered by the gate's own --self-test and by eslint, not by this command.
• The one eslint warning on scripts/upstream-port-pin.json is File ignored because no matching configuration was supplied, and it is identical on the same file at origin/main. eslint does not lint JSON here.

Route: node scripts/check-governed-queue-guard.mjs --test on all four paths answers NOT GOVERNED — 4 path(s) checked against 5 governed surface(s); none matched. An ordinary pull request. Left as a draft; the PM seat drives the queue.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr

---

Generated by Claude Code

[claude]

Probe ARMED — 10 legs, ⛔ posted BEFORE any flip, to be re-run verbatim on the ACTUAL merge parent

PM seat domain:devx @ objectui, session session_01FhBNJcLRZLe8M87VcUgpKr, 2026-09-13T09:40Z. Card objectui#9206.

Counted on base = 852437297bf9fd722cff2237f8280baa49e4457a (origin/main at 08:42Z) and head = 087ce5a9d690c697d370f6229fa0cb211fef1b14.
⚠️ Per errata 62b, every pre-value is re-confirmed against <merge>^ at merge time — ⛔ not against this base. main moving is not the question; this diff's four files are.

c(){ git grep -c -F "$2" "$1" -- $3 | awk -F: '{s+=$NF} END{print s+0}'; }

#	leg	kind	pre	post
1	deliberately NOT registered in .github/workflows/lint.yml	must-LEAVE	1	0
2	Deliberately NOT registered in in scripts/check-bash32-floor.mjs	must-LEAVE	1	0
3	Deliberately NOT registered in scripts/upstream-port-pin.json	must-LEAVE	2	0
4	It is still NOT registered in scripts/check-bash32-floor.mjs	must-LEAVE	1	0
5	Why this port is not YET pinned in scripts/check-bash32-floor.mjs	must-LEAVE	1	0
6	⭐ Why this port is not YET pinned in .changeset/8385-bash32-floor-port-rationale.md	must-STAY	1	1
7	pin entry ref + upstreamSha256 + len(divergences)	must-STAY-UNCHANGED	61362932… / 0da45049… / 22	identical
8	non-comment changed lines in check-bash32-floor.mjs	must-STAY-UNCHANGED	70 changed lines	0 after the code-only reader
9	control check-bash32-floor in lint.yml / in the pin	control, known direction, HITS	3 / 7	3 / 7
10	nonsense control chek-bash32-floor, tree-wide · + leg 1 run twice	control + determinism	0	0 / 0, stable

⭐ Leg 6 is the one that carries the information, and it nearly was not written

A tree-wide census of Why this port is not YET pinned returns three sites, ⛔ not one:

.changeset/8385-bash32-floor-port-rationale.md:4
scripts/check-bash32-floor.mjs:162
scripts/upstream-port-pin.json:202          (inside the "ported" divergence snapshot)

⇒ A naive tree-wide must-LEAVE leg would demand 3 → 0 and fail a correct merge. The changeset is landed history describing a past change — ⛔ editing it is a defect, not a fix. So the leg is inverted deliberately: it must STAY at 1, and it is what distinguishes 「the stale claim was corrected」 from 「the string was swept」. ⚠️ This is this seat's own standing rule applied to itself: survivors are not gaps until you read WHY they survive.

⭐ The pin edit is FORCED by the pin's own text — ⛔ it is not scope widening

scripts/upstream-port-pin.json carries, in the why of this very entry:

⚠️ Its "Deliberately NOT registered" clause is stale the moment this entry lands — correcting it edits the ported file and is a follow-up card, not a silent fix here.

⇒ This PR is that follow-up card, named in advance by the thing it edits. And the ported divergence snapshots at :172 / :202 mirror the .mjs docblock verbatim, so check-upstream-port-parity reds if the docblock moves and the snapshot does not. ⇒ the pin's +4/−4 (two why sides + two ported sides) is the minimum consistent edit, ⛔ not an extra.

⭐ And the replacement text obeys the constraint the file itself set

The old header ruled: 「⛔ Do not write a revision into this prose. A port's ref lives on that port's entry…this section has already gone stale TWICE by naming one.」 The new lint.yml comment does not name a ref, and says why:

⛔ The ref this copy was taken at is deliberately not named in this comment: it lives on that file's ledger entry, beside the digest it was taken with, where --resync keeps it correct.

⇒ the fix does not re-arm the failure mode it is repairing. Legs 7 + 8 are what hold that: ref/digest untouched (⛔ this is not a re-pin) and 0 non-comment changed lines (⛔ this is not a behaviour change).

Sequence from here — ⛔ nothing is skipped

1. CI green on 087ce5a9d6 — at 09:31Z: 28 success · 3 skipped · 4 Test shards in flight · ⛔ 0 red.
2. ⚠️ Then draft→ready, which ADDS Governed Surface Queue Guard (verified 5/5 this shift) ⇒ ⛔ the pre-flip green is stale; re-wait for every check.
3. Enqueue, and confirm the added_to_merge_queue timeline event — ⛔ enable_pr_auto_merge's echo is not a signal.
4. ⭐ Re-count all ten legs on the actual <merge>^ <merge>, ⛔ not on this base, and publish the result whichever way it reads.

⚠️ Earlier red on this PR was inherited, and that was established twice — diff ∩ failing files = NONE, and the gate was red on main's own commits. objectui#9369's fix has since merged (852437297b). ⛔ This seat declined to port that fix: a semantic rewrite owned by another card.

---

Generated by Claude Code