@massu/core 1.8.0 → 1.9.0

package/README.md

@@ -103,6 +103,23 @@ npx massu permissions check-drift
 # Exit 4 + stderr "drift[strips-global-defaultmode]: ..." if the trap is present
 ```
 
+### Changelog Generation
+
+Release-boundary CHANGELOG entries are auto-drafted by `npx massu changelog generate` (shipped 1.9.0+). The generator reads commit subjects since the last git tag, groups them by `(plan-<token>)` paren-notation (the same convention enforced by CR-40), and pulls each plan file's `## Changelog Summary` section verbatim into a Keep-a-Changelog 1.1.0-compliant entry. Goal: "fewer changelog entries, more meaningful" — one entry per release, structured by plan-token, instead of per-commit noise.
+
+```bash
+# Auto-draft entry for commits since the last tag
+npx massu changelog generate > /tmp/draft-entry.md
+
+# Read-only verify that the latest CHANGELOG entry references every plan-token
+# in the commit range since the last tag
+npx massu changelog verify
+```
+
+**Plan-file `## Changelog Summary` contract**: any plan whose Status is in the shipped subset (SHIPPED, IMPLEMENTED, COMPLETE, SUPERSEDED, APPROVED) MUST contain a `## Changelog Summary` section. The plan-status validator (`scripts/massu-plan-status-validator.sh`) enforces this — plans missing the section fail validation. The release generator reads this section to produce the CHANGELOG entry body, so plan authors describe shipped behavior once (in the plan file) and the generator propagates it.
+
+**Pre-tag gate**: `scripts/pre-push-light.sh` step `[11/11] Plan-Token Changelog Currency` fires when `packages/core/package.json#version` drifts from the latest git tag (i.e., a release is in progress). The gate BLOCKS the push if CHANGELOG.md doesn't have a `## [X.Y.Z]` heading matching the new version AND doesn't reference every plan-token in the commit range since the last tag. The CI workflow at `.github/workflows/ci.yml` mirrors this check (3-layer enforcement: pre-push + CI + drift-guard vitest).
+
 ## Documentation
 
 Full documentation at [massu.ai](https://massu.ai).

package/commands/massu-release.md

@@ -179,7 +179,29 @@ fi
 
 ## STEP 3: CHANGELOG GENERATION
 
-### 3.1 Parse Conventional Commits
+### 3.0 Auto-Generate Draft Entry (PREFERRED, plan-1.9.0+)
+
+The `npx massu changelog generate` subcommand auto-drafts an entry by reading
+commit subjects since the last tag, grouping by `(plan-<token>)` paren-notation,
+and pulling the prose from each plan file's `## Changelog Summary` section. This
+makes "fewer changelog entries, more meaningful" the default workflow.
+
+```bash
+# Generate draft into a tmp file for operator review
+npx massu changelog generate > /tmp/draft-changelog-entry.md
+cat /tmp/draft-changelog-entry.md
+
+# Operator reviews; edit inline if needed; then prepend to CHANGELOG.md.
+# Stage D pre-tag gate (scripts/pre-push-light.sh step 11) BLOCKS the push
+# if package.json#version drifts from the last tag but CHANGELOG.md does
+# not have a matching `## [X.Y.Z]` heading AND references every plan-token
+# in the commit range since the last tag.
+
+# Sanity-check completeness post-edit
+npx massu changelog verify  # exit 0 = all plan-tokens referenced
+```
+
+### 3.1 Parse Conventional Commits (legacy / fallback when no plan-token paren-notation)
 
 ```bash
 LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")