audit: changelog - Review governance, links, and automation #1009

Audit Summary

Audit the changelog governance stack for verbosity, missing GitHub issue/PR references, placeholder content, and any unnecessary self-referential links at the bottom of CHANGELOG.md. Confirm whether branding/footer/badge automation is expected to affect the changelog, and verify the surrounding release, template-enforcement, frontmatter, and changelog scripts/workflows still behave correctly.

The working assumption is that the changelog should become more concise, with each meaningful entry reduced to a short summary plus linked issue and PR references where available. Any deeper context should live in the linked issue or PR rather than the changelog body.

Audit Checklist / Scope

• Review CHANGELOG.md for verbosity, missing issue/PR links, placeholder text, and self-referential bottom links.
• Review changelog-related agents and helpers: scripts/agents/release.agent.js, scripts/agents/includes/changelogBuilder.js, scripts/agents/includes/releaseNotesFormatter.js, scripts/agents/includes/changelogUtils.cjs, and scripts/workflows/changelog/*.
• Review changelog policy and release docs: docs/VERSIONING.md, docs/RELEASE_PROCESS.md, instructions/release.instructions.md, docs/AUTOMATION.md, and any changelog-related saved replies or prompts.
• Review template enforcement and related workflows: .github/workflows/template-enforcement.yml, .github/workflows/changelog-validate.yml, and .github/workflows/changelog-auto-update.yml.
• Confirm whether branding/footer/badge automation should apply to CHANGELOG.md, and whether missing footer/badges is a defect or an intentional exception.
• Check changelog-related scripts and workflows for test coverage, with the target that any related scripts maintain at least 80% coverage.
• Verify tests and linting workflows cover the relevant changelog and template-enforcement behaviour.

Findings / Risks

• CHANGELOG.md currently contains multiple placeholder entries ([placeholder]) in older release sections.
• Many changelog entries are still verbose and embed file paths/details that would be better represented by short summaries plus issue/PR links.
• The bottom ## Reference section creates self-referential links back to changelog and adjacent docs, which risks circular navigation and weakens the changelog as a standalone release record.
• The current automation uses permissive changelog extraction/merging logic, so any rewrite needs to avoid breaking release note generation or duplicate detection.
• It is not yet clear that CHANGELOG.md is supposed to receive branding footers or badges; that needs explicit policy confirmation before treating the absence as a defect.

Remediation Actions

• Condense historical changelog entries where possible without losing decision value.
• Remove placeholder lines and replace them with real release notes or delete the empty sections if they are no longer needed.
• Strip self-referential reference links from the bottom of CHANGELOG.md if they are not required by policy.
• Tighten changelog formatting guidance so future entries are concise and include issue/PR links where available.
• Review and, if needed, harden changelog validation and merge scripts so concise entries still pass reliably.
• Update tests to cover the revised formatting and any new validation rules.

Acceptance Criteria

• Changelog entries are concise and consistently linked to GitHub issues and PRs where available.
• Placeholder text is removed from CHANGELOG.md.
• Self-referential links at the bottom of CHANGELOG.md are removed or explicitly justified by policy.
• Branding/footer/badge expectations for CHANGELOG.md are confirmed and documented.
• Relevant changelog and template-enforcement scripts/workflows are audited and updated if needed.
• Related tests are updated and coverage remains at or above the required threshold.
• Issue fields and template enforcement pass for this issue before implementation starts.

Additional Context

Related areas to inspect first:

• CHANGELOG.md
• docs/VERSIONING.md
• docs/RELEASE_PROCESS.md
• instructions/release.instructions.md
• docs/FOOTER_REMEDIATION_GUIDE.md
• docs/BRANDING_AGENT_USAGE.md
• scripts/workflows/changelog/extract-pr-entries.cjs
• scripts/workflows/changelog/merge-entries.cjs
• scripts/agents/includes/changelogBuilder.js
• scripts/agents/includes/releaseNotesFormatter.js
• scripts/agents/includes/changelogUtils.cjs
• .github/workflows/template-enforcement.yml
• .github/workflows/changelog-validate.yml
• .github/workflows/changelog-auto-update.yml

Definition of Ready (DoR)

• Scope, risk areas, and target files are confirmed.
• We agree whether branding/footer/badges belong in CHANGELOG.md.
• The template enforcement workflow has been verified on the issue body.
• Audit scope, checklist, and goals defined
• Areas/components listed
• Dependencies and standards mapped

Definition of Done (DoD)

• Audit findings are documented with concrete examples.
• Any approved changelog simplification is implemented.
• Template enforcement and changelog automation continue to pass.
• Tests and coverage are updated for any changed scripts.
• The changelog is concise, policy-compliant, and ready for ongoing maintenance.