truthmark/docs/standards/change-notes.md

status, doc_type, last_reviewed, source_of_truth

status	doc_type	last_reviewed	source_of_truth
active	standard	2026-05-16	versioning.md pre-completion-checklist.md

Change Notes

Trigger

Use this standard when a change needs PR text, release text, or a package version decision.

Required triggers:

• package.json version changes
• root package entries in package-lock.json change because the package version changed
• the user asks for PR, release, changelog, or handoff text
• the working change alters published package behavior

Optional trigger:

• internal-only maintenance that would benefit from a reusable PR summary

Folder

Write change notes under changes/.

Use one file per cohesive working change:

changes/YYYY-MM-DD-short-slug.md

Use dates from the current local session date. Keep slugs short, lowercase, and grep-friendly.

Required Shape

Each change note must use this structure when Version action is none:

# Short Change Title

Version action: none

## PR Summary

- Concise maintainer-facing summary.

## Release Note

- User-facing release text, or `None; internal-only change.`

## Verification

- Command run, or skipped check with reason.

Each change note must use this structure when Version action is patch, minor, or major:

# Short Change Title

Previous version: MAJOR.MINOR.PATCH
New version: MAJOR.MINOR.PATCH
Diff basis: release/MAJOR.MINOR.PATCH..HEAD plus working tree
Version action: patch|minor|major
SemVer rationale: One sentence explaining why the pending release payload requires this bump.

Release payload:
- Concise maintainer-facing summary of an actual release-worthy change.

User-facing release text:
- User-visible release note.

Verification:
- Command run, or skipped check with reason.

Rules

• Version action must match versioning.md.
• If Version action is patch, minor, or major, the package version must change in the same working change.
• If the package version changes, a matching change note for the new version is required because Truthmark releases whenever the package version changes.
• Versioned change notes must describe all release-worthy pending changes since the previous release tag, not only the package metadata edit or generated-surface refresh.
• Versioned change notes must name the previous version, new version, diff basis, SemVer rationale, release payload, user-facing release text, and verification.
• Verification entries should report final useful checks only; do not include red-test scaffolding, agent mistakes, or process chatter in release-facing change notes.
• Internal-only repository standards may use Version action: none.
• Release notes describe published package behavior, not private repo maintenance.
• Keep notes compact; they are source material for PR and release descriptions, not canonical product truth.

Agent Output

When reporting change-note work, state only:

• change note path
• version action
• whether release text is present or intentionally None