Summary
.codex/workflows/changelog-fragment.md lines 26-27 and changelog.d/README.md lines 43-44 both state that non-issue fragments must "omit the issues field entirely" and explicitly warn against writing issues: null or issues: []. However, there is no validation or tooling documented to enforce this constraint. Agents following the fragment template may accidentally write issues: null believing the validation pipeline will catch it, but the documentation does not reference the validation command or tool that would catch such errors.
Where
.codex/workflows/changelog-fragment.md:26-27
changelog.d/README.md:43-44
.codex/workflows/release-changelog.md:25-26 (references validation but no detail)
tools/CodeIndex.Changelog/ (no validation detail documented)
Suggested approach
- Document the changelog fragment validation command explicitly in .codex/workflows/release-changelog.md
- Add a pre-commit check in .codex/workflows/precommit.md that validates changelog fragments before commit
- Include example error messages that agents would see if they write
issues: null
- Add a "Validation" section to changelog-fragment.md explaining how to test fragments locally
- Reference the validation tool in both the fragment template and README
- Consider adding a CI check that blocks PRs with malformed fragments (if not already present)
Summary
.codex/workflows/changelog-fragment.md lines 26-27 and changelog.d/README.md lines 43-44 both state that non-issue fragments must "omit the
issuesfield entirely" and explicitly warn against writingissues: nullorissues: []. However, there is no validation or tooling documented to enforce this constraint. Agents following the fragment template may accidentally writeissues: nullbelieving the validation pipeline will catch it, but the documentation does not reference the validation command or tool that would catch such errors.Where
.codex/workflows/changelog-fragment.md:26-27changelog.d/README.md:43-44.codex/workflows/release-changelog.md:25-26(references validation but no detail)tools/CodeIndex.Changelog/(no validation detail documented)Suggested approach
issues: null