From e94c5759fa7bef84727788e1219b266d6403e2b4 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 22 Aug 2026 17:14:59 +0000 Subject: [PATCH] docs(agents): a pin-breaking removal ships with the sibling fix and pin bump MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Encode the C half of the maintainer's 2026-08-22 A+C ruling as Post-Task Checklist item 4: a removal or rename the pinned objectui checkout still imports must land together with the objectui-side fix and the .objectui-sha bump (sdui:manifest second half included), because the Console Pin Gate builds the pinned sibling against current main — merging the removal alone turns main red for every PR in the repo. The ruling that authorizes the removal implicitly authorizes the sibling fix + pin bump in the same landing. Line ratchet payment (AGENTS.md ceilinged at 961, zero headroom): the one added line is paid by deleting the seventeen-phantom-pins incident parenthetical in the Build & Test section — incident case law lives in git history per the ratchet header's own guidance. The optional one-line pre-merge check in the spec-property-retirement SKILL.md checklist is deferred: PR #11092 is in flight touching that file with auto-merge armed. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01MsbKEG4LtERSLaDrbehM3e Fixes #10986 --- AGENTS.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4f225ef262..bf60d5db85 100644 --- a/AGENTS.md +++ b/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 `/test-typecheck-debt.json` (regenerate with `pnpm --filter gen:test-typecheck-debt`); the shared gate is `scripts/check-test-typecheck.mts --package ` — onboard by wiring, never by @@ -950,9 +949,10 @@ new open registry? Add it to `OPEN_CAPABILITY_REGISTRIES` in the same PR that fi ``` 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. ---