docs(sdui): declare the declaration-parity ratchet an on-demand gate triggered by the objectui pin bump (#5960) (#6421)

Maintainer ruling 2026-08-07, option D. `sdui.manifest.json` changes only when
`.objectui-sha` moves, so the pin-update flow is the ratchet's trigger — and the
measured answer was that nothing triggered it at all. Producing the manifest in
this repo's CI (option A) is rejected; objectui publishing it as a release
artefact (option B) is deferred.

The procedure line now lives where a pin-bumping operator actually meets it:

- scripts/bump-objectui.sh prints the `pnpm sdui:manifest` NEXT STEP on both
  successful exits (--no-commit moved the pin too). A reminder, not a hard gate:
  a machine without Playwright must still be able to move the pin.
- scripts/build-console.sh's closing line names the trigger, not just the
  command — `pnpm objectui:refresh` runs bump-then-build, so that output is the
  last thing an operator sees.
- docs/releases-maintenance.md gains "After the pin moves", and the
  pin-freshness "fix when it fires" step gains the run.
- AGENTS.md's frontend section gains the step, and its `check:generated` note
  stops calling the manifest's provenance an open question.
- scripts/objectui-changeset-digest.mjs --self-test (CI: check:objectui-changeset)
  pins the reminder, so the procedure line cannot be deleted in silence.

Rider from the ruling: ADR-0082's Consumers row, TL;DR 4, decision 4, the chain
diagram and one Consequences bullet all pointed at scripts/build-console.sh —
#4472 moved the ratchet to scripts/gen-sdui-manifest.sh and the ADR was never
updated, so a reader following it opened a file that deliberately dumps no
manifest. Corrected in place plus a new addendum 2;
docs/audits/2026-06-react-blocks-conformance.md carried the same stale pointer
and is corrected with it.

Releases nothing: scripts/, docs/ and AGENTS.md ship in no package.

Fixes #5960


Claude-Session: https://claude.ai/code/session_01AZgRyPVwi1jLb1mNNuUQ9o

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-project-manager

AGENTS.md

@@ -93,6 +93,8 @@ This repo ships **backend only**. All Studio/Console UI work happens in `../obje
 
 Other scripts: `objectui:bump` (pull only), `objectui:build`, `objectui:clean`. ⚠️ Never hand-edit `packages/console/dist/` or `.cache/objectui-*/` — regenerated.
 
+**Moving the pin has a second half: `pnpm sdui:manifest`.** ADR-0082 D4's spec↔registry declaration-parity ratchet reads objectui's `sdui.manifest.json`, which changes only when `.objectui-sha` moves — so the pin bump is the ratchet's trigger, and its only one. It is an **on-demand gate by decision** (#5960), never a CI job; `objectui:bump` and `objectui:refresh` both print the reminder. Needs Playwright chromium. Full procedure: `docs/releases-maintenance.md` → "After the pin moves".
+
 **Fast iteration on `../objectui` src (no commit/refresh loop):** run objectui's own console dev server — `cd ../objectui && pnpm --filter @object-ui/console dev` (Vite on **:5180**, HMR). Its `/api` proxy targets `DEV_PROXY_TARGET || http://localhost:3000`, so **run the backend you're testing on :3000** (`PORT=3000 pnpm dev` for showcase) and browse `:5180`. Note `:3001/_console` (or whatever the backend serves) is the **published** console, not your `../objectui` src — only `:5180` reflects local UI edits. See `../objectui/AGENTS.md` for the app-id / localStorage / auth gotchas.
 
 ---
@@ -555,9 +557,16 @@ unavailable` and **exited 0**, so no path existed on which this gate could go re
 **exits 1** when it has no usable manifest, because "could not run" is a failure, not a
 skip (Route & surface ownership §3, *Absence must be loud*). Run it the one way that
 works: `pnpm sdui:manifest` (or `OBJECTUI_ROOT=../objectui pnpm objectui:build` first),
-which dumps the manifest and runs the ratchet against it. Where the manifest *should* come
-from in CI is an open provenance question, tracked separately — do not "fix" the red by
-re-adding a skip.
+which dumps the manifest and runs the ratchet against it. Where the manifest comes from is
+**settled** (#5960, maintainer ruling 2026-08-07): **not from CI**. It is an on-demand
+gate whose trigger is the **objectui pin bump** — `.objectui-sha` is the only thing that
+moves the manifest, so `scripts/bump-objectui.sh` and `scripts/build-console.sh` print the
+`pnpm sdui:manifest` step and `docs/releases-maintenance.md` carries the procedure.
+Producing it here was rejected outright: the sole producer drives Playwright chromium over
+objectui's built console, so a CI-side dump means a full objectui build plus a browser
+download on every matching PR. So: do not "fix" the red by re-adding a skip, and do not
+"fix" it by wiring the gate into a workflow either — run it where it belongs, at the pin
+bump.
 
 `check:exported-any` is the one of those that also reads the built `dist/*.d.ts`, so the
 stale-`dist` caveat above applies to it too. It asks the other half of the

docs/adr/0082-react-component-contract-governance.md

@@ -72,6 +72,10 @@ something this audit measured.)* So:
    **frontend-only** props (e.g. `object-form` formType/drawer*/modal*) to the
    spec so the protocol covers what the component accepts; and run this check in
    CI (with a console manifest dump) as a ratchet so new divergence is caught.
+   *(⚠️ The last clause was **rejected** on 2026-08-07, #5960: a console manifest dump
+   in this repo's CI means a full objectui build plus Playwright/chromium on every
+   matching PR. The ratchet is on-demand, triggered by the objectui pin bump — see
+   the correction under "Ratchet (implemented)" below.)*
 3. The `record:*` blocks declaring **zero inputs** means the visual designer can't
    configure them — likely a real gap to close.
 
@@ -85,10 +89,22 @@ MANIFEST=/path/to/sdui.manifest.json pnpm --filter @objectstack/spec check:react
 
 ## Ratchet (implemented)
 
-Running this on every framework PR isn't worth it — the manifest only exists at
-console-build time. So the conformance check is wired in as a **baseline ratchet**
-at the one place the manifest is produced for free: `scripts/build-console.sh`,
-right after it dumps `sdui.manifest.json` from the freshly-built console registry.
+Running this on every framework PR isn't worth it — the manifest only exists once a
+real browser has enumerated the built console registry. So the conformance check is
+wired in as a **baseline ratchet** at the one place the manifest is produced for free:
+`scripts/gen-sdui-manifest.sh` (`pnpm sdui:manifest`), right after it dumps
+`sdui.manifest.json` from the freshly-built console registry.
+
+> **Corrected 2026-08-07 (#5960).** This paragraph named `scripts/build-console.sh`,
+> which is where the ratchet shipped and, since #4472, no longer where it lives —
+> `build-console.sh` deliberately dumps no manifest, because the console build must not
+> drag in a browser dependency. ADR-0082 carried the same stale pointer and is corrected
+> with it. #5960 also settled *when* the ratchet runs: it is an **on-demand gate**, and
+> its trigger is the **objectui pin bump** (`scripts/bump-objectui.sh` prints the step;
+> `docs/releases-maintenance.md` carries the procedure). Producing the manifest in this
+> repo's CI was rejected — a full objectui build plus a Playwright/chromium download on
+> every matching PR — and since #4690 a missing manifest exits 1 rather than skipping, so
+> the residual risk is "unrun", never "falsely green". See ADR-0082 addendum 2.
 
 - The accepted state lives in `packages/spec/react-declaration-parity.baseline.json`
   (per block: the registry-only input set + whether the block is missing).

docs/audits/2026-06-react-blocks-conformance.md

@@ -50,6 +50,34 @@ CONSOLE_BUMP=patch scripts/bump-objectui.sh   # force the bump type
 scripts/bump-objectui.sh --no-changeset       # opt out (rarely)
 ```
 
+#### After the pin moves: run the declaration-parity ratchet (#5960)
+
+The bump has a second half, and it is not optional:
+
+```bash
+pnpm sdui:manifest    # rebuild objectui at the new pin, dump sdui.manifest.json, run the ratchet
+```
+
+`sdui.manifest.json` is objectui's registry-inputs dump — the right-hand side of
+ADR-0082 D4's spec↔registry **declaration-parity ratchet** (`scripts/gen-sdui-manifest.sh`
+produces it and runs the ratchet against it; note it is *not* `scripts/build-console.sh`,
+which the ADR named until #5960 corrected it). That file changes when — and only when —
+this pin moves, so **the pin bump is the ratchet's trigger, and its only one.**
+
+This is an **on-demand gate by decision** (maintainer ruling, 2026-08-07). No workflow
+produces the manifest and none should: the only producer drives a Playwright chromium
+over objectui's built console and reads `window.__MANIFEST`, so wiring it into this
+repo's CI would put a full objectui build plus a browser download on every matching PR.
+The trade is deliberate — honest on-demand coverage over expensive full coverage —
+and it is safe because the gate has no unearned green: since #4690 a missing, unreadable,
+malformed or empty manifest **exits 1** rather than skipping. The one failure mode left is
+that nobody runs it, which is what this step exists to close. `scripts/bump-objectui.sh`
+and `scripts/build-console.sh` both print the reminder when they finish.
+
+Needs a Playwright browser (`pnpm exec playwright install chromium-headless-shell`). When
+the ratchet fires, the fix is a spec/overlay edit or an explicit `--update` to re-accept
+the baseline — see ADR-0082 D4 and its addendum 2.
+
 ## 3. Platform layer — `content/docs/releases/vN.mdx` (curated)
 
 The curated, developer-facing "big picture", written for third parties building on
@@ -134,8 +162,10 @@ node scripts/check-objectui-pin-fresh.mjs --ref v17.0.0 --json
   down without turning red into green — the degradation is printed, not swallowed. An
   unreachable remote is reported as `unreadable` and exits non-zero.
 - **Fix when it fires:** `scripts/bump-objectui.sh` to move the pin (which writes the
-  `@objectstack/console` changeset for the crossed range), then re-source the Console
-  section with `scripts/objectui-range.mjs`.
+  `@objectstack/console` changeset for the crossed range), then `pnpm sdui:manifest` to
+  run the declaration-parity ratchet at the new pin (see "After the pin moves" above —
+  the bump is that ratchet's only trigger), then re-source the Console section with
+  `scripts/objectui-range.mjs`.
 
 ## Drift guard
 

docs/releases-maintenance.md

@@ -190,5 +190,12 @@ echo "✓ @objectstack/console dist ready (${BYTES} KB) from objectui@${PINNED_S
 # real browser (Playwright) to enumerate the console registry, and the console
 # build must not drag in a browser dependency. Regenerate them on demand instead:
 #   pnpm sdui:manifest        (see scripts/gen-sdui-manifest.sh)
+#
+# The reminder names the TRIGGER, not just the command (#5960): `pnpm objectui:refresh`
+# runs bump-objectui.sh and then this script, so this is the last output an operator
+# sees while moving the pin — and the pin bump is the ratchet's only trigger, by
+# decision. bump-objectui.sh prints the same step; this repeats it because that one
+# has scrolled past a whole console build by now.
 echo "ℹ SDUI manifest + declaration-parity ratchet are decoupled from the console build."
-echo "  Run 'pnpm sdui:manifest' on demand to regenerate (requires Playwright)."
+echo "  Run 'pnpm sdui:manifest' whenever you move the objectui pin — that is the"
+echo "  ratchet's only trigger, on demand by decision (#5960). Requires Playwright."

scripts/build-console.sh

@@ -7,6 +7,13 @@
 #   scripts/bump-objectui.sh --no-commit    # update files only, don't commit
 #   scripts/bump-objectui.sh --no-changeset # skip the @objectstack/console changeset
 #
+# After the bump — the second half of the pin-update procedure (#5960):
+#   pnpm sdui:manifest        # dump objectui's sdui.manifest.json and run the
+#                             # spec↔registry declaration-parity ratchet (ADR-0082 D4).
+#                             # The pin bump is that ratchet's ONLY trigger; it is an
+#                             # on-demand gate by decision, never a CI job. Needs
+#                             # Playwright chromium. This script prints the reminder.
+#
 # Env:
 #   CONSOLE_BUMP=major|minor|patch  # force the changeset bump type (default: auto —
 #                             # the HIGHEST level objectui itself declared in the
@@ -56,7 +63,10 @@ for arg in "$@"; do
     --no-commit) NO_COMMIT=1 ;;
     --no-changeset) NO_CHANGESET=1 ;;
     -h|--help)
-      sed -n '2,19p' "$0" | sed 's/^# \{0,1\}//'
+      # NOTE: this line range is coupled to the header block above (usage → env →
+      # sibling layout, ending at "run from here"). Editing the header means moving
+      # it — #5960 added the pin-update step and had to.
+      sed -n '2,26p' "$0" | sed 's/^# \{0,1\}//'
       exit 0
       ;;
     *) EXPLICIT_SHA="$arg" ;;
@@ -157,8 +167,36 @@ EOF
   echo "→ wrote changeset $(basename "$CS_FILE") (@objectstack/console: ${BUMP})"
 fi
 
+# --- The other half of the pin-update procedure (#5960) ----------------------
+# ADR-0082 D4's spec↔registry declaration-parity ratchet reads objectui's
+# `sdui.manifest.json`, and that file changes when — and only when — this pin
+# moves. So the pin bump is the ratchet's trigger, and it is the ONLY one:
+# measured on origin/main, no workflow runs `pnpm sdui:manifest`, no workflow
+# installs Playwright for it, `packages/console/dist/` is gitignored and the
+# published @objectstack/console tarball ships no manifest. Producing it in this
+# repo's CI was considered and REJECTED (#5960) — it would put a full objectui
+# build plus a chromium download on every matching PR.
+#
+# Deliberately a REMINDER, not a hard gate: a machine without Playwright must
+# still be able to move the pin, and hard-failing here would be the rejected
+# CI cost wearing a local disguise. The gate itself cannot go falsely green —
+# since #4690 a missing or unusable manifest exits 1 instead of skipping — so
+# the only failure mode left is "nobody ran it", which is what this prints to
+# prevent. Printed on BOTH exits below: --no-commit still moved the pin.
+print_sdui_next_step() {
+  echo
+  echo "→ NEXT STEP — run the declaration-parity ratchet (ADR-0082 D4):"
+  echo "      pnpm sdui:manifest"
+  echo "  It rebuilds objectui at the new pin, dumps packages/console/dist/sdui.manifest.json"
+  echo "  and ratchets spec↔registry declaration parity. A pin bump is its only trigger:"
+  echo "  it is an on-demand gate by decision (#5960), never a CI job."
+  echo "  Needs a Playwright browser — 'pnpm exec playwright install chromium-headless-shell'."
+  echo "  Procedure: docs/releases-maintenance.md → 'After the pin moves'."
+}
+
 if [[ "$NO_COMMIT" -eq 1 ]]; then
   echo "→ --no-commit: leaving files unstaged."
+  print_sdui_next_step
   exit 0
 fi
 
@@ -170,3 +208,4 @@ ${SUBJECT_LINE}
 
 objectui@${NEW_SHA}" -- .objectui-sha ${CS_FILE:+"$CS_FILE"}
 echo "✓ Committed. Push with: git push"
+print_sdui_next_step

scripts/bump-objectui.sh

@@ -1226,10 +1226,25 @@ function selfTest() {
     for (const f of ['bump-objectui.sh', 'objectui-changeset-digest.mjs']) {
       writeFileSync(join(fwRun, 'scripts', f), readFileSync(join(__dirname, f), 'utf8'));
     }
-    execFileSync('bash', [join(fwRun, 'scripts', 'bump-objectui.sh'), '--no-commit', head], {
-      encoding: 'utf8',
-      env: { ...process.env, OBJECTUI_ROOT: ui },
-    });
+    const bumpStdout = execFileSync(
+      'bash',
+      [join(fwRun, 'scripts', 'bump-objectui.sh'), '--no-commit', head],
+      {
+        encoding: 'utf8',
+        env: { ...process.env, OBJECTUI_ROOT: ui },
+      },
+    );
+    // #5960: the pin bump is the ONLY trigger of ADR-0082 D4's declaration-parity
+    // ratchet — no workflow produces `sdui.manifest.json`, by ruling — so the
+    // procedure's second half lives in this script's output. Prose alone is
+    // deletable in silence; pinning it here is what makes "the procedure gained a
+    // line" a fact a gate can lose. Asserted on the `--no-commit` path on purpose:
+    // that path moved the pin too, and it is the one that returns early.
+    check(
+      '#5960 a bump prints the `pnpm sdui:manifest` step (the ratchet has no other trigger)',
+      bumpStdout.includes('pnpm sdui:manifest') && bumpStdout.includes('NEXT STEP'),
+      bumpStdout,
+    );
     const written = join(fwRun, '.changeset', `console-${head.slice(0, 12)}.md`);
     const body = existsSync(written) ? readFileSync(written, 'utf8') : '';
     check('bump-objectui.sh writes the digest-derived changeset', body.length > 0);