Ensure version publishes always carry release notes (#46)

Added a standing release-note requirement to the repository agent contract,
propagated the same rule to the install template and contributor guide,
and created missing v5 release notes in README.

A metadata test now enforces that README release notes include the
current package version heading, so future version bumps cannot skip
documenting release changes.

Constraint: Keep release-note policy lightweight and dependency-free
Rejected: Add a release-notes generator dependency | unnecessary maintenance overhead
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: When bumping package.json version, add matching README release note heading in the same change
Tested: npm test; node --check bin/multiagent-safety.js; npm pack --dry-run
Not-tested: GitHub release body automation

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>

Author: NagyVikt

AGENTS.md

@@ -28,6 +28,7 @@ This AGENTS.md is the top-level operating contract for this repository.
 - Prefer deletion over addition.
 - Reuse existing patterns before introducing new abstractions.
 - No new dependencies without explicit request.
+- When publishing or bumping a version, update release notes in the same change (`README.md` release notes section and the release body when tagging).
 - Keep diffs small, reviewable, and reversible.
 - Run lint/typecheck/tests/static analysis after changes.
 - Final reports must include: changed files, simplifications made, and remaining risks.

CONTRIBUTING.md

@@ -23,3 +23,4 @@ npm pack --dry-run
 - Keep `main` green (CI passing)
 - Prefer trusted publishing (`npm publish --provenance`)
 - Use a clean working tree and tag-based releases when possible
+- When version changes, update `README.md` release notes in the same PR/commit

README.md

@@ -208,6 +208,20 @@ npm pack --dry-run
 
 ## Release notes
 
+### v5.0.2
+
+- Auto-closes Codex sandbox branches through PR workflow and keeps merged branch/worktree sandboxes for explicit cleanup via `gx cleanup`.
+- Runs `gx doctor` repairs from a sandbox when `main` is protected.
+- Allows tightly guarded Codex-only commits for `AGENTS.md` / `.gitignore` on protected branches.
+- Advanced package version to keep npm publishing unblocked.
+
+### v5.0.0
+
+- Rebranded the CLI to **GuardeX** with `gx`-first command UX.
+- Published under scoped package name `@imdeadpool/guardex` to avoid npm name collisions.
+- Enforced a repeatable per-message agent branch lifecycle in setup/init flows.
+- Added codex-auth-aware sandbox branch naming support.
+
 ### v0.4.6
 
 - Added repository metadata (`repository`, `bugs`, `homepage`, `funding`) in package manifest.

templates/AGENTS.multiagent-safety.md

@@ -18,6 +18,7 @@
 - If merge/rebase conflicts block auto-finish, run a conflict-resolution review pass in that sandbox branch, then rerun `agent-branch-finish.sh --via-pr` until merged.
 - Completion is not valid until these are true: commit exists on the agent branch, branch is pushed to `origin`, and PR/merge status is produced by `agent-branch-finish.sh` or `codex-agent`.
 - Per-message loop is mandatory: for every new user message/task, start a fresh agent branch/worktree, claim ownership locks, implement and verify, finish via PR/merge cleanup, then repeat for the next message/task.
+- If the change publishes or bumps a version, the same change must also update release notes/changelog entries.
 
 1. Explicit ownership before edits
 

test/metadata.test.js

@@ -5,6 +5,11 @@ const path = require('node:path');
 
 const repoRoot = path.resolve(__dirname, '..');
 const packageJsonPath = path.join(repoRoot, 'package.json');
+const readmePath = path.join(repoRoot, 'README.md');
+
+function escapeRegexLiteral(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
 
 test('package manifest includes repository and support metadata', () => {
   const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
@@ -26,6 +31,17 @@ test('release workflow publishes with provenance in CI', () => {
   assert.match(workflow, /npm publish --provenance --access public/);
 });
 
+test('README release notes include current package version', () => {
+  const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  const readme = fs.readFileSync(readmePath, 'utf8');
+  const headingPattern = new RegExp(`^###\\s+v${escapeRegexLiteral(pkg.version)}\\b`, 'm');
+  assert.match(
+    readme,
+    headingPattern,
+    `README release notes must include heading for v${pkg.version}`,
+  );
+});
+
 test('security workflows are present and use pinned GitHub Actions SHAs', () => {
   const workflowDir = path.join(repoRoot, '.github', 'workflows');
   const expected = ['ci.yml', 'release.yml', 'scorecard.yml', 'codeql.yml'];