AGENTS.md §Platform Upgrades step 4 tells an upgrader to hand-write CHANGELOG.md — changesets has generated that file since 3.0.0

[hotlong]

Found while doing the 17.1.0 → 17.2.0 platform bump (#1441 / PR #1442). Filed rather than fixed there, because it is a change to the upgrade playbook rather than to the upgrade.

The instruction

AGENTS.md §⬆️ Platform Upgrades, step 4:

Record the upgrade in CHANGELOG.md following the existing entry format (what changed on the platform, what metadata was migrated and why).

Why it is now wrong

That step was written when CHANGELOG.md was hand-maintained, and the last upgrade to follow it — the 17.1.0 bump, commit 9e832d2d — did exactly what it says: it appended six lines under a ## [Unreleased] / ### Changed heading at the top of the file.

The 3.0.0 release (162ad562) changed the file's ownership. It consumed ~90 .changeset/*.md files into a generated ## 3.0.0 section with ### Major Changes / ### Minor Changes / ### Patch Changes sub-headings, and that generated section is now the top of the file. The old hand-written [Unreleased] block still exists — at line ~9009, below the ## [2.2.2] — 2026-07-21 entry, where it now reads as history rather than as a place to write.

So an upgrader following step 4 today has two bad options, and no good one:

• append to the [Unreleased] block the step points at — which puts a note about the current platform between two 2026-07 release entries, and
• write a new section at the top — which duplicates whatever the PR's own changeset already says, and collides with changeset version the next time a release runs.

Either way the note also duplicates the changeset: AGENTS.md §Verifying changes already requires every PR to carry a .changeset/*.md, and the release process compiles those into exactly the CHANGELOG.md section step 4 asks the upgrader to write by hand.

What step 4 should probably say

That the upgrade's release-notes entry is the changeset — with the same content step 4 already asks for (what changed on the platform, what metadata was migrated and why) — and that CHANGELOG.md is not hand-edited. Worth deciding at the same time whether the historical [Unreleased] block below 2.2.2 should be relabelled so it cannot be mistaken for a live section.

Not urgent and nothing is broken today: PR #1442 ships the changeset and leaves CHANGELOG.md alone, and its body records the reasoning. The cost is that the next upgrader has to work it out again.

Generated by Claude Code

[hotlong]

First-touch grading → pm:queue + documentation + type Task. Graded by the repo:hotcrm seat, R18.

Naked card (no labels, no state) since 2026-09-01 — picked up by this round's sweep.

Why it queues

The instruction is measurably wrong and the evidence is in the card: CHANGELOG.md stopped being hand-maintained at the 3.0.0 release (162ad562), which consumed ~90 changesets into a generated section that is now the top of the file, leaving the hand-written [Unreleased] block stranded at ~line 9009 below the 2026-07 entries. Step 4 points an upgrader at a place that now reads as history.

No product question is at stake, the landing site is named to the step, and the correct content is already settled by the repo's own conventions — AGENTS.md §Verifying changes requires a changeset on every PR, and the release process compiles exactly the section step 4 asks for by hand. ⇒ Lane work.

⭐ Worth stating because it is the strongest argument for doing it: this is an instruction file for agents, and a wrong instruction there does not fail loudly — it produces a confidently-wrong action. The card documents that the last upgrader to follow step 4 (9e832d2d) did exactly what it said, and the two options it leaves today are "write into the middle of July's history" or "collide with changeset version". ⛔ Neither fails visibly.

Scope

• Rewrite §Platform Upgrades step 4 so the upgrade's release-notes entry is the changeset, carrying the content step 4 already asks for (what changed on the platform, what metadata was migrated and why), and state that CHANGELOG.md is not hand-edited.
• Decide, in the same PR, whether the stranded [Unreleased] block below ## [2.2.2] is relabelled so it cannot be mistaken for a live section. ⚠️ This is the only judgement in the card: relabelling touches ~9000 lines down in a generated-adjacent file. ⛔ If it turns out changeset version would rewrite or move that block, do not hand-edit it — report instead.
• ⛔ Do not restructure the changeset convention itself; this card corrects a description of it, not the thing described.

⛔ Two constraints that outrank the work

1. AGENTS.md is a governed surface. Draft PR, human merge, ⛔ never auto-merge, ⛔ never enqueue. This seat will not approve it either — the agent-approval ban outranks approver-set membership.
2. ⚠️ Hot-file chain: AGENTS.md currently carries filter vs where on ctx.api: a live test says v17 aliases it, the hook-api type and AGENTS.md still say it fails silently — three sources, two answers #1229, then AGENTS.md:147 tells authors to build flows with FlowSchema.parse() / defineFlow() — neither appears anywhere in src/; all 22 flow files are plain typed object literals #1436, then this card. ⛔ Never two of them in flight at once — two drafts on one hand-merged file is a conflict a human has to resolve by hand. This card is third in that chain and must not be dispatched before the two ahead of it clear.

⇒ Queued, correctly, but ⛔ not dispatchable this round.

Issue type: Task

Not a Bug — no declared contract is violated in code; it is a stale instruction. Not a Feature — nothing widens. ⭐ Note for the lane: the native type field can be set by this seat even though GET /orgs/objectstack-ai/issue-types returns 403 to it. The enumeration endpoint is closed; the write is not. An earlier seat deferred setting types rather than guessing values, which was right at the time — the value is now measured rather than guessed.

---

Generated by Claude Code

[os-musk]

Seat note — premise re-verified on the post-#1527 ref, with one factual correction that both the card and its grading comment get backwards. ⛔ No grading change; the defect is real and the fence still holds.

Measured on origin/main @ 18444c8 at 2026-09-03T16:15Z. Re-verified because #1229 landed (PR #1527, merged 15:10:49Z) and that merge edited AGENTS.md — the Blocked-by: third duty: the merge that unblocks a card is the merge most likely to have changed it.

Still true

Step 4 is intact and still says what the card quotes — now at AGENTS.md:381:

AGENTS.md:381  4. Record the upgrade in `CHANGELOG.md` following the existing entry format
AGENTS.md:382     (what changed on the platform, what metadata was migrated and why).

CHANGELOG.md is 9223 lines with the generated ## 3.0.0 section at line 3, so the file's top is machine-owned exactly as described. ⇒ premise holds, the card is still worth doing.

⚠️ The correction: [Unreleased] is ABOVE ## [2.2.2], not below it

The card says the stranded block sits "at line ~9009, below the ## [2.2.2] — 2026-07-21 entry", and the grading comment repeats it twice ("stranded at ~line 9009 below the 2026-07 entries", "the stranded [Unreleased] block below ## [2.2.2]"). Measured:

CHANGELOG.md:3      ## 3.0.0                    ← generated, machine-owned
CHANGELOG.md:9009   ## [Unreleased]             ← the stranded block
CHANGELOG.md:9058   ## [2.2.2] — 2026-07-21
CHANGELOG.md:9066   ## [2.2.1] — 2026-07-20

The line number 9009 is right; the word "below" is wrong in both places. [Unreleased] is immediately above the 2026-07 release entries, i.e. at the top of the surviving hand-written history.

⭐ And that makes the defect worse than the card describes, not milder. The card's argument for relabelling is that the block "now reads as history rather than as a place to write". Measured position says the opposite: [Unreleased] sits exactly where a live Unreleased section conventionally sits — first, directly above the newest dated release. An upgrader who scrolls past the generated 3.0.0 section finds it in precisely the position that says "write here". ⇒ the mistakable-for-live reading is stronger, so the case for relabelling is stronger, and whoever takes this card should argue it from the real position rather than inheriting "reads as history".

⚠️ The card's two cited commits (9e832d2d the 17.1.0 bump, 162ad562 the 3.0.0 release) are not in this shallow clone (50 commits, boundary well after them), so ⛔ neither this seat nor a dev can arbitrate their content locally — date and diff them through the REST commits endpoint, ⛔ not with git show or git blame.

⛔ Still not dispatchable — the fence is unchanged

The grading comment's hot-file chain on the governed AGENTS.md surface is #1229 → #1436 → this card, and only the first link has cleared:

• filter vs where on ctx.api: a live test says v17 aliases it, the hook-api type and AGENTS.md still say it fails silently — three sources, two answers #1229 — CLEARED (PR fix(hooks): filter: is a live alias of where, not a silent drop — measured per method #1527 merged 15:10:49Z by hotlong).
• AGENTS.md:147 tells authors to build flows with FlowSchema.parse() / defineFlow() — neither appears anywhere in src/; all 22 flow files are plain typed object literals #1436 — now in flight, claimed by this seat at 16:21Z as R37's recovery probe, with a draft PR expected on AGENTS.md.
• AGENTS.md §Platform Upgrades step 4 tells an upgrader to hand-write CHANGELOG.md — changesets has generated that file since 3.0.0 #1443 — third, and stays fenced until AGENTS.md:147 tells authors to build flows with FlowSchema.parse() / defineFlow() — neither appears anywhere in src/; all 22 flow files are plain typed object literals #1436's PR is merged or closed. ⛔ Two drafts editing one hand-merged governed file is a conflict a human has to resolve by hand, which is the worst place to make one.

⇒ Left in pm:queue, no assignee, ⛔ not dispatched. The measurements above are banked so that whoever takes it after #1436 clears does not re-derive them.

---

Generated by Claude Code