From 796501faa9c97c776edb444e7b132ae97f9e22b3 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 3 Sep 2026 01:30:07 +0000 Subject: [PATCH] docs(agents): a released-package bug fix takes a patch changeset, never none AGENTS.md told authors "Pure bug fixes do not require a changeset", which contradicts every enforced text: Check Changeset (pr-automation.yml) reds a PR that adds zero changesets and carries no skip-changeset label, and that label is for a diff publishing nothing from any released package. A bug fix in a released package therefore had no green path if it followed the sentence. The sentence predates enforcement. It landed 2026-05-30 (43625fbd6c) when the step only emitted ::warning:: and could not fail; the check became blocking on 2026-06-11 (a1251e4737), and started counting changesets added BY THE PR on 2026-07-21 (8ff9210947) -- the form that actually reds a zero-changeset bug fix. Paid same-file, AGENTS.md being at its line ceiling: the ADR-0087 rationale paragraph is re-derived from check-adr-0087-registration.mjs's own failure output, so it collapses to a one-line citation in the file's established idiom. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1 --- AGENTS.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8b8cf792b0..dd7a93e23d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1113,8 +1113,10 @@ registry? Add it to `OPEN_CAPABILITY_REGISTRIES` in the same PR that fixes it. surface** (Prime Directive #14 names them — more than ADRs): push it, open the PR, and stop there, landing it is the maintainer's, by hand. For that class, a finished task = a PR left visibly awaiting a human merge. -3. **Add a changeset for feature work.** When the change is a feature or functional improvement, run `pnpm changeset` - (or add a `.changeset/*.md` entry) describing it before committing. Pure bug fixes do **not** require a changeset. +3. **Add a changeset for anything that publishes.** Feature, functional improvement or fix — run `pnpm changeset` + (or add a `.changeset/*.md` entry) describing it before committing. A bug fix in a released package takes a + **`patch`** changeset — never none, and ⛔ never `skip-changeset`: that label is for a diff that publishes + nothing from any released package. **Breaking changesets must carry their migration.** If the change removes or renames anything an author can write (a spec key, an export, a config field), the changeset body must state the FROM → TO mapping and the one-line fix — this text ships to consumers as `CHANGELOG.md` inside the npm package and is what an upgrading agent greps after the @@ -1133,14 +1135,7 @@ registry? Add it to `OPEN_CAPABILITY_REGISTRIES` in the same PR that fixes it. ``` - 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. + Why it is asked of you at all: the gate prints the argument when it fails — that output is the authority. 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