docs(agents): a pin-breaking removal ships with the sibling fix and pin bump

AGENTS.md

@@ -64,9 +64,8 @@ Three principles the ratchet's invariants encode, worth knowing before you fight
   it in the `typecheck` script (the `packages/spec` pattern); the sibling may carry its
   own *module* semantics to match vitest, never its own *strictness*.
 - **A `@ts-expect-error` in a file no tsc program compiles is a phantom check** — it
-  evaluates never, and deleting it leaves every gate just as green (a repo-wide sweep
-  once found seventeen retirement pins in that state in one package alone). Before
-  writing one, check the file is compiled. Test-layer residue lives in the per-file,
+  evaluates never, and deleting it leaves every gate just as green. Before writing
+  one, check the file is compiled. Test-layer residue lives in the per-file,
   shrink-only `<package>/test-typecheck-debt.json` (regenerate with
   `pnpm --filter <package> gen:test-typecheck-debt`); the shared gate is
   `scripts/check-test-typecheck.mts --package <dir>` — onboard by wiring, never by
@@ -950,9 +949,10 @@ new open registry? Add it to `OPEN_CAPABILITY_REGISTRIES` in the same PR that fi
    <!-- adr-0087: not-required (no-migration-prescription) why -->
    ```
    Why it is asked of you at all: the ADR-0087 gates pin ledger ↔ **artifact synchrony**, and the artifacts are a pure projection of the registry — a retirement whose entry was **never written** leaves everything perfectly consistent and every gate green (a removal has shipped that way, caught only by a human comparing by eye). Ledger entries are the sole channel that reaches an upgrader (`objectstack migrate meta`, `spec-changes.json`, the upgrade guide) — for a surface with no spec schema there is no tombstone or schema rejection either. Roughly 1 declared-breaking change in 7 needs an entry, so `not-required` is the ordinary answer and costs one line; the markers are re-verified mechanically, and `no-migration-prescription` is refused when the changeset's own body carries a FROM → TO prescription.
-4. **Added or removed a `packages/spec` export? Run `pnpm --filter @objectstack/spec gen:api-surface` and commit the result.** The `TypeScript Type Check` job diffs spec's built export surface against `api-surface/` (one shard per entry point); a new export makes the snapshot stale and turns the job red. It reads the **built `dist` declarations**, so `OS_SKIP_DTS=1` — the flag you reach for to make local builds fast — skips exactly the artifact the gate inspects, and the check passes locally while failing in CI. Same shape for the other generated-artifact gates in that job (`check:docs`, `check:skill-refs`, `check:react-blocks`), which read `src/` and so do reproduce locally.
-5. Update `CHANGELOG.md` / `ROADMAP.md` if user-facing or architectural.
-6. **Delete temporary artifacts** — screenshots, traces, scratch logs, `.playwright-mcp/`, throwaway `tmp*.ts`, ad-hoc scripts. Repo must look identical to before, minus intended changes.
+4. **A removal that breaks the pinned sibling checkout ships together with the sibling fix and the pin bump — or it does not ship.** The `Console Pin Gate` job builds objectui at the pinned `.objectui-sha` against **current** `main`, so a removal or rename the pinned sibling still imports turns `main` red for every PR in the repo the moment it merges — "retire the surface" and "leave the sibling untouched" cannot both hold. A ruling that authorizes such a removal therefore implicitly authorizes the objectui-side fix and the pin bump as part of the same landing (the bump's `sdui:manifest` second half included — see the Frontend section). Pre-merge check for any removal or rename of an exported surface: does the pinned sibling import what you are removing? `git grep` it in `../objectui` at the pinned SHA before merging.
+5. **Added or removed a `packages/spec` export? Run `pnpm --filter @objectstack/spec gen:api-surface` and commit the result.** The `TypeScript Type Check` job diffs spec's built export surface against `api-surface/` (one shard per entry point); a new export makes the snapshot stale and turns the job red. It reads the **built `dist` declarations**, so `OS_SKIP_DTS=1` — the flag you reach for to make local builds fast — skips exactly the artifact the gate inspects, and the check passes locally while failing in CI. Same shape for the other generated-artifact gates in that job (`check:docs`, `check:skill-refs`, `check:react-blocks`), which read `src/` and so do reproduce locally.
+6. Update `CHANGELOG.md` / `ROADMAP.md` if user-facing or architectural.
+7. **Delete temporary artifacts** — screenshots, traces, scratch logs, `.playwright-mcp/`, throwaway `tmp*.ts`, ad-hoc scripts. Repo must look identical to before, minus intended changes.
 
 ---