@massu/core 1.7.0 → 1.9.0

package/README.md

@@ -31,6 +31,95 @@ npx massu doctor
 npx massu validate-config
 ```
 
+### Permission Seeding
+
+To skip the per-tool MCP permission dialog on a fresh install, `npx massu install-commands` automatically seeds the canonical glob `mcp__massu__*` into `.claude/settings.local.json`'s `permissions.allow` array. It also propagates the user-global `defaultMode` (from `~/.claude/settings.json`) into the project-local file (see "Permissions trap" below).
+
+Three lifecycle subcommands for managing the allowlist:
+
+```bash
+# Seed the canonical entry + propagate global defaultMode (idempotent)
+npx massu permissions install
+
+# Read-only check — exit 0 if all canonical entries present
+npx massu permissions verify
+
+# Extended diagnostic — surfaces 4 drift kinds with severity-mapped exit codes
+npx massu permissions check-drift
+```
+
+To opt out of automatic permission seeding during `install-commands` (e.g., when permissions are managed centrally by enterprise policy):
+
+```bash
+npx massu install-commands --skip-permissions
+```
+
+`defaultMode` validity reference (per [Claude Code docs](https://code.claude.com/docs/en/permission-modes)):
+
+| Mode | Activatable from settings file alone | Requires launch flag |
+|---|---|---|
+| `default` | ✓ | — |
+| `acceptEdits` | ✓ | — |
+| `plan` | ✓ | — |
+| `bypassPermissions` | — | `--permission-mode bypassPermissions` or `--dangerously-skip-permissions` |
+| `auto` | — | `--permission-mode auto` (plus plan/admin/model preconditions) |
+| `dontAsk` | — | `--permission-mode dontAsk` |
+
+`permissions check-drift` warns when a launch-flag-required value is set in settings without the corresponding flag (these settings are silently inert without the launch flag).
+
+### Permissions trap (settings merge)
+
+Empirically observed in Claude Code 2.1.x: a project-local `.claude/settings.local.json` that has a `permissions` object **without** a `defaultMode` key silently STRIPS the user-global `defaultMode` from `~/.claude/settings.json` during settings merge. The merge unit appears to be the entire `permissions` object's top-level keys, not individual keys within it — undocumented at `code.claude.com/docs/en/permissions`.
+
+**Before** (trap state):
+```jsonc
+// ~/.claude/settings.json (global)
+{ "permissions": { "defaultMode": "auto" } }
+
+// .claude/settings.local.json (project)
+{ "permissions": { "allow": ["mcp__massu__*"] } }
+// Effective defaultMode in this project: NONE (global "auto" silently stripped)
+```
+
+**After** (correct state, what `massu permissions install` writes):
+```jsonc
+// .claude/settings.local.json (project)
+{ "permissions": {
+    "allow": ["mcp__massu__*"],
+    "defaultMode": "auto"
+} }
+```
+
+The install writer:
+1. Reads global `~/.claude/settings.json`
+2. Reads project-local `.claude/settings.local.json`
+3. Computes merged state: `allow` = union with canonical entries; `defaultMode` = local override OR global value OR omit; `deny`/`ask` preserved from local
+4. Atomic-writes the complete merged block
+5. Post-write fail-loud assertion: re-reads disk and confirms the merge survived
+
+To audit any project for the trap (or any other permission drift):
+```bash
+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 "")