Why
A guarded pull request currently writes four shared files, three of them on the same line, so two PRs against one Plugin always conflict. A Change Note is one new file per change, so two PRs write two different files and never collide.
Design and rationale: ADR-0035. Vocabulary: root CONTEXT.md.
What to build
The Change Note format
<issue#>-<slug>.md, frontmatter plus prose:
---
level: minor
section: Added
---
`/setup` installs the Archon artefacts from a named install set.
- Plugin notes live in
apps/claude-code/<plugin>/.changes/ and require level (patch|minor|major).
- Repository notes live in the root
.changes/ and must not carry level — nothing there is versioned. The parser rejects one.
section is Breaking, Added or Fixed in both.
- The prose is the CHANGELOG bullet, used verbatim at release time. No transformation.
The gate
Replaces verify:changelog. It asserts that a Plugin whose files changed has at least one Change Note in that pull request.
Invert the guarded-path list to a deny-list. The current allow-list (packages/release-tools/scripts/lib/changelog-gate.mjs:5-12) omits lib/**, so a change confined there — where unic-archon-dlc keeps its implementation — is ungated today. An allow-list fails silently every time a Plugin grows a directory.
Deny-list starts at: test/**, **/*.test.mjs, CONTEXT.md, docs/**, .changes/**.
Acceptance criteria
Out of scope
- Consuming notes and bumping versions — that is the
/release ticket.
- Removing
## [Unreleased] from the Plugin CHANGELOGs — same, because bump-version is reworked there.
Why
A guarded pull request currently writes four shared files, three of them on the same line, so two PRs against one Plugin always conflict. A Change Note is one new file per change, so two PRs write two different files and never collide.
Design and rationale: ADR-0035. Vocabulary: root
CONTEXT.md.What to build
The Change Note format
<issue#>-<slug>.md, frontmatter plus prose:apps/claude-code/<plugin>/.changes/and requirelevel(patch|minor|major)..changes/and must not carrylevel— nothing there is versioned. The parser rejects one.sectionisBreaking,AddedorFixedin both.The gate
Replaces
verify:changelog. It asserts that a Plugin whose files changed has at least one Change Note in that pull request.Invert the guarded-path list to a deny-list. The current allow-list (
packages/release-tools/scripts/lib/changelog-gate.mjs:5-12) omitslib/**, so a change confined there — whereunic-archon-dlckeeps its implementation — is ungated today. An allow-list fails silently every time a Plugin grows a directory.Deny-list starts at:
test/**,**/*.test.mjs,CONTEXT.md,docs/**,.changes/**.Acceptance criteria
packages/release-toolsreads a Change Note and returns its level, section and prose. It rejects unknown frontmatter keys.levelis an error naming the file. A repository note withlevelis an error naming the file.sectionoutsideBreaking|Added|Fixedis an error naming the file and listing the valid values.lib/**requires a note. A test asserts this specifically — it is the hole this ticket closes.verify:changelogis removed, along withchangelog-gate.mjs. The six Pluginpackage.jsonfiles point at the new command. CI wires it in place of the old step.pnpm --filter @unic/release-tools test,pnpm typecheckandpnpm ci:checkpass.Out of scope
/releaseticket.## [Unreleased]from the Plugin CHANGELOGs — same, becausebump-versionis reworked there.