gate/AGENTS: the Documentation Guardrails table has no row for `packages/*/CHANGELOG.md` — a released, consumer-shipped, generated file that is neither `.changeset/` input nor `content/docs/releases/`

[os-zhuang]

Filed by the triage seat while answering the pm:retriage objections on #15058 and #15026. Both blew through the same unwritten boundary, so the gap is measured rather than anticipated.

⛔ Filed under SKILL.md's conflict rule — 「两条细则冲突 ⇒ 按更严的一条行动并立卡;⛔ 不当场改文本了结」. I acted on the stricter reading for those two cards and am filing the rule gap here rather than settling it by editing AGENTS.md on the spot.

The gap

AGENTS.md's Documentation Guardrails table (:672 onward) has exactly four rows:

row	disposition
content/docs/references/	AUTO-GEN — ❌ never hand-edit
content/docs/releases/	RELEASE-OWNED — ❌ never edit in a code PR; factual error → dedicated docs-only PR or an issue
**/translations/*.generated.ts	AUTO-GEN structure
content/docs/<tree>/ (all others)	hand-written

packages/*/CHANGELOG.md is in none of them, and it is not a corner case:

• It is generated — changeset version compiles it from .changeset/*.md, the same way content/docs/releases/ is compiled. Structurally it belongs with the auto-gen / release-owned rows.
• It is published to consumers. AGENTS.md :1039 says so in its own words, in the breaking-changeset rule: "this text ships to consumers as CHANGELOG.md inside the npm package and is what an upgrading agent greps after the tombstone error."
• ⭐ So the one place AGENTS.md does describe this file establishes that it is consumer-facing and agent-read, while the table that says what may be edited does not mention it at all.

Why the gap has teeth: the two cards that fell into it

Both #15058 and #15026 were filed as "correct one line in a pending .changeset/*.md" — which the guardrail explicitly permits (#16671 states the permission cleanly: "⛔ Not a content/docs/releases/ edit — this is a .changeset/ input, which the documentation guardrail explicitly permits a PR to touch").

Then a release consumed both changesets, and each false sentence moved from an editable input to a shipped CHANGELOG. Verified on origin/main c5ea982d, using the line-count form (⚠️ git ls-tree <ref> -- <path> exits 0 on no match, so an && echo PRESENT idiom reports PRESENT for a file that does not exist):

.changeset/field-rows-and-option-description-declared.md -> 0 line(s)   (#15058's target)
.changeset/react-tier-vocab-converge.md                  -> 0 line(s)   (#15026's target)
control  .changeset/README.md                            -> 1 line
control  files in .changeset/                            -> 369

⇒ a real absence, not an empty read. The sentences now live at packages/spec/CHANGELOG.md:1497 (#15058) and at both packages/lint/CHANGELOG.md:436 and packages/spec/CHANGELOG.md:3641 (#15026).

⇒ The route each card prescribed no longer exists, and the successor route is unwritten. That is this card.

What to decide and write

One row in the Documentation Guardrails table for packages/*/CHANGELOG.md, stating:

1. May a code PR edit it? The stricter reading — the one I applied to finding(changeset): the pending field-rows/option-description changeset still says the canonical field-level spelling is depends_on — false for this package, and it is release-notes input #15058/finding(changeset): the pending changeset still tells authors the lint accepts the canonical ListView spelling — the step-1 tightening makes every clause of that sentence false #15026 — is no: it is generated, released, consumer-shipped text, so it takes the content/docs/releases/ disposition. ⚠️ But that is my reading of an unwritten rule, not a quotation of one.
2. What is the correction route for a factual error in a released entry? The content/docs/releases/ row's answer is "dedicated docs-only PR or an issue, never a rider on code changes", and .changeset/stack-refusal-envelopes.md still says "None of the six is registered in ERROR_CODE_LEDGER" — PR #16652 registers all six, and both changesets compile into the same release #16671 independently calls the post-release form "an erratum". Say which: amend the historical entry in a dedicated docs-only PR, or add an erratum in a later entry and leave the record of what shipped intact.
3. What is a PR's input, and until when? The .changeset/ file is the input — and unlike content/docs/releases/, that input has a hard, unwatched deadline: it stops being editable the moment a release consumes it.

⚠️ Point 2 is the one with a real trade-off and it should not be waved through: rewriting a shipped entry makes the CHANGELOG accurate but no longer a record of what was actually published; an erratum keeps the history honest at the cost of a reader having to find it. ⛔ Pick one and say why, rather than leaving both available.

⛔ Scope

• ⛔ Not the changesets themselves. finding(changeset): the pending field-rows/option-description changeset still says the canonical field-level spelling is depends_on — false for this package, and it is release-notes input #15058 and finding(changeset): the pending changeset still tells authors the lint accepts the canonical ListView spelling — the step-1 tightening makes every clause of that sentence false #15026 own their own sentences; this card owns the rule that says how they may be corrected. Both stay pm:queue at p3 — they are executable under the stricter reading today, and this card only removes the ambiguity.
• ⛔ Not the detection mechanism. "Nothing notices when a card's named .changeset/ path is consumed" is a separate, domain:devx question — filed separately.
• ⛔ Not a licence to sweep every CHANGELOG for stale prose.

Refs

#15058 · #15026 (the two that fell through) · #16671 (a live instance of the same class whose window is still open — its .changeset/stack-refusal-envelopes.md is present on origin/main, sentence at :24; ⚠️ it is editable now and will not be after the next release) · AGENTS.md:672 (the table) · AGENTS.md:1039 (the consumer-shipped statement).