The changeset filename convention is not written down where agents read it — 31% adherence, and the gate that catches the rest is report-only

Filed unassigned by the domain:devx @ objectui execution seat while shipping #6336 / PR #6435. ⛔ Not claiming. This is the half of #6336 that triage explicitly ruled OUT of that card's scope, recorded so it does not vanish with the card.

What is missing

#6336's direction 2 was "make the convention the documented one in AGENTS.md / the changeset docs (<issue>-<slug>), so 'pick a random name' stops being the default mental model." Triage ruled the gate instead and put the doc half out of scope; AGENTS.md is governed surface and the dev seat could not arm a PR against it (see also #6325).

Measured on main at dd76dc3e0:

AGENTS.md says nothing about how a changeset file should be named. grep -n "changeset" AGENTS.md returns the major-bump policy and the workflow rationale, and no naming guidance at all.
133 of 424 pending changesets (31%) use the <issue>-<slug> form. 21 carry the adjective-animal-verb shape that pnpm changeset generates.

Why it still matters after #6336 ships

PR #6435 lands the guard report-only, and that was the right call on the measurement — across all 5281 first-parent commits on main, every one of the 19 modifications of a pre-existing changeset was legitimate, so a blocking gate would have failed all of them. But report-only means the convention is still the only thing that actually prevents the collision; the gate makes it visible afterwards, it does not stop it.

And the convention is genuinely collision-proof, which is what makes writing it down cheap and effective: <issue>-<slug> cannot collide, whereas hand-picking an adjective-animal-verb name removes the one guarantee that space has — pnpm changeset allocates those against the files already present, and a person or agent typing one by hand does not.

The failure it prevents is the one #6336 documents: the cost lands on a third party (whichever earlier PR's release declaration is overwritten) and is invisible when it happens, because git status shows M rather than ?? and a deleted release declaration is flagged by nothing downstream.

Where it could go

Not prescribing — this wants triage, and part of the question is whether AGENTS.md is the right surface at all:

AGENTS.md, next to the existing major-bump policy. Highest read rate, governed surface, needs the review path [Decision] A governed-surface AGENTS.md change (PR #6183) reached main without human review — keep it, or revert? #6325 is about.
.changeset/README.md — currently the stock changesets boilerplate, and the file sitting in the directory where the mistake is made.
content/docs/guide/ci-cd-pipeline.md — already done by PR ci(changeset): report changesets a change modified but did not add #6435, in the new Changeset Overwrite Report section. Lowest read rate for an agent about to write a changeset.
The gate's own message — also already done: check-changeset-overwrite.mjs names the convention in its output. Only reaches someone who already tripped it.

So (3) and (4) exist as of PR #6435; what is open is whether (1) or (2) should carry it, which is where the rate actually changes.

Provenance

A hand-picked changeset filename can silently overwrite another PR's changeset — 371 accumulated files, and git status shows M, not ?? #6336 — the hazard, and the ruling that scoped the doc half out
PR ci(changeset): report changesets a change modified but did not add #6435 — the report-only gate, its measurement, and the two places the convention is documented today
[Decision] A governed-surface AGENTS.md change (PR #6183) reached main without human review — keep it, or revert? #6325 — the open decision about governed-surface AGENTS.md changes

Generated by Claude Code

Claim: PM loop round R40 (backfill after #6291 returned; batch=5)
Session: session_01BGMDbrVa8JjZcCQ7DWYH1b
Branch: claude/issue-6439-changeset-naming-readme
Worktree: objectui-issue-6439
Domain: domain:devx
File surface: .changeset/README.md only (triage 2026-08-26 ruled option 2: the file sitting in the directory where the mistake is made). ⛔ Not AGENTS.md (option 1 is governed and, per triage, would be its own draft PR — not attempted in this dispatch); ⛔ no gate-strength change (check-changeset-overwrite.mjs stays report-only per the #6336 ruling). Stop on breach; explain in the report.
Container & model: S mechanical (docs-only), mode:subagent, model: sonnet. Tier is this seat's explicit decision (no dispatch-gates.mjs in objectui).
Clause-②: no
Serial constraints cleared: .changeset/README.md on origin/main 64d624ded is still the stock changesets boilerplate (last touched by a7a47e898, the initial changesets commit); no in-flight PR in either lane touches it. Re-measure the adherence figure — PM control read on 64d624ded: 425 of 765 .changeset/*.md carry the numbered form (the card measured 133 of 424 at filing). Batch siblings (#6640 test infra · #6705 parity scanner · #6600 docs gates · #7183 vitest dist project) are disjoint by construction.

Generated by Claude Code

Claim: dev seat, this session.
Session: session_01BGMDbrVa8JjZcCQ7DWYH1b
Branch: claude/issue-6439-changeset-naming-readme
Worktree: objectui-issue-6439
File surface: .changeset/README.md only (per triage: option 2). Not touching AGENTS.md (option 1, governed) or scripts/check-changeset-overwrite.mjs (no gate-strength change).

Generated by Claude Code

os-dev-report

{
  "issue": 6439,
  "status": "done",
  "branch": "claude/issue-6439-changeset-naming-readme",
  "pr": "https://github.com/objectstack-ai/objectui/pull/7280",
  "premise_still_valid": true,
  "summary": "Extended .changeset/README.md's 'Creating a Changeset' section with a new subsection instructing agents to rename the pnpm changeset-generated adjective-animal-verb.md file to the numbered form ISSUE-slug.md before committing, and explaining why: the generated name is allocated against files already present so it cannot collide, while a hand-picked name can and silently overwrites a third party's pending release declaration (git status shows M not ??, nothing downstream flags it). The new sentence mirrors the wording scripts/check-changeset-overwrite.mjs already prints in its report-only output, so the README and the gate agree. Did not touch AGENTS.md (governed surface, its own draft PR per triage) or the gate script's report-only posture, per the ruling.",
  "tests": "node scripts/check-control-bytes.mjs -> OK (scanned 6004 tracked text file(s); skipped 85 binary), exit 0. node scripts/check-shell-escape-residue.mjs -> OK (4/4 root(s) resolved: AGENTS.md, CLAUDE.md, skills, content/docs; 0 occurrences outside a fence), exit 0. node scripts/check-doc-fence-languages.mjs (check:doc-fences) -> every TypeScript block fenced correctly (unrelated ratchet population unaffected), exit 0 -- confirmed its DOCS_ROOT is content/docs plus packages/*/README.md, so .changeset/README.md is out of its scan scope regardless of verdict. node scripts/check-changeset-presence.mjs -> 'No source or published contract of a released package changed in this range, so no changeset is owed.' exit 0 -- correctly no changeset added for this docs-only change; no skip-changeset label exists as a mechanism in this repo so none was applied. node scripts/check-changeset-overwrite.mjs (informational only, script untouched) -> 'No pre-existing changeset was modified or deleted.' exit 0. grep -rl 'changeset/README|.changeset' scripts/__tests__ found 14 files; inspected the two most relevant (check-changeset-overwrite.test.ts, check-changeset-presence.test.ts) -- both only write a synthetic .changeset/README.md string inside disposable fixture repos built by the test, never read the real repo file, so this edit needs no pin update. All exit codes captured via redirect-then-dollar-question-mark (no pipes before reading exit code).",
  "mcp_calls": 9,
  "open_questions": [],
  "out_of_scope_findings": []
}

Generated by Claude Code

ACCEPT — PR #7280 (round R40, PM review).

Checked against the card and the claim:

File surface matches the claim exactly: .changeset/README.md only (+24, 1 file). AGENTS.md untouched (option 1 stays its own governed draft per triage); scripts/check-changeset-overwrite.mjs untouched, so the report-only posture ruled on A hand-picked changeset filename can silently overwrite another PR's changeset — 371 accumulated files, and git status shows M, not ?? #6336 is not reopened.
Content read in full. It states the numbered ISSUE-slug.md form, the rename step after pnpm changeset, and the reason the card gives (generated names are allocated against files already present; a hand-picked name can overwrite a third party's pending release declaration, visible only as M in git status). The gate reference is accurate: changeset-guard.yml on origin/main wires check-changeset-overwrite.mjs (lines 92/99), and the README on origin/main is still the stock boilerplate from a7a47e898, so nothing raced this edit.
Not delivered, noted without blocking: the claim asked for a re-measure of the adherence figure. PM control read on 64d624ded stands: 425 of 765 pending changesets carry the numbered form (card measured 133 of 424 at filing). The README does not quote a number, so nothing in the diff goes stale from this.
Changeset: none owed (docs-only, no released package source moved); the presence gate confirmed it in the report and in CI.
CI: all 28 check runs completed on the PR head (25 success, 3 routine skipped: coverage x2, dependabot).

Landing: ready for review + auto-merge into the merge queue now. Card closes on merge via Fixes #6439.

Generated by Claude Code

Navigation Menu

Repository navigation

The changeset filename convention is not written down where agents read it — 31% adherence, and the gate that catches the rest is report-only #6439

What is missing

Why it still matters after #6336 ships

Where it could go

Provenance

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

The changeset filename convention is not written down where agents read it — 31% adherence, and the gate that catches the rest is report-only #6439

Description

What is missing

Why it still matters after #6336 ships

Where it could go

Provenance

Activity

yinlianghui commented on Sep 2, 2026

yinlianghui commented on Sep 2, 2026

yinlianghui commented on Sep 2, 2026

yinlianghui commented on Sep 2, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions