@massu/core 2.4.0 → 2.5.1

package/CHANGELOG.md

@@ -10,6 +10,132 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 > redistributed under the **Apache License 2.0**. Full license + NOTICE:
 > `packages/core/assets/embedder/MODEL-LICENSE`.
 
+## [2.5.1] - 2026-08-09
+
+### Fixed
+
+- **Hooks emitted an output field that does not exist, so no hook message ever reached
+  Claude.** Eleven hooks wrote `{"message": …}` to stdout. `message` is not in Claude Code's
+  hook output schema at all — it appears only in `Notification`/`FileChanged` *input* — so
+  every advisory string those hooks produced was discarded. The failure was self-inflicted in
+  an exact way: because `{"message": …}` is valid JSON, `UserPromptSubmit` parsed it as JSON
+  instead of treating it as plain text, so the one event that would have delivered the string
+  as stdout is precisely the event that dropped it. A slightly malformed string would have
+  arrived.
+
+  Replaced by a single chokepoint emitting the documented shape,
+  `{"hookSpecificOutput": {"hookEventName", "additionalContext"}}`. `hookEventName` is
+  REQUIRED, so the helper takes the event as a typed, required argument and the old
+  one-argument form is DELETED rather than deprecated — a regression to the silent shape is
+  now a compile error, not a silent no-op. An unrecognised event emits nothing and says why
+  on stderr. Output is truncated at the spec's 10,000-char cap by us rather than by the
+  runtime.
+
+  **Blocking behaviour is unchanged.** The `PreToolUse` gates deny via `process.exit(2)` plus
+  stderr, which never depended on this path; what was lost was their *advisory* (warn-level)
+  messages, and everything `rule-enforcement-pipeline` emits, since that hook only ever
+  advises.
+
+### Added
+
+- **`scripts/ops/retag-release-to-npm-githead.sh`** — audits every release tag against the
+  commit npm actually published. A release tag is supposed to answer "which commit shipped as
+  X.Y.Z", and two things break that: the tag is created before the post-publish bookkeeping
+  commit and then moved forward, or it is never created at all. npm records `gitHead` with
+  every publish, so the answer is recoverable — this reads THAT and refuses anything else.
+
+  Dry-run by default; reports its denominator; FAILS CLOSED when the registry returns no
+  usable `gitHead` or names a commit absent from the repo, rather than guessing; never
+  force-pushes — it moves the local tag and prints the push command, so publishing a
+  rewritten ref stays deliberate.
+
+  First full audit: `50 tag(s) examined; 6 already correct, 34 drifted, 10 error(s)`. The 2.x
+  series is now 7/7 correct; 1.x is left as-is deliberately.
+
+### Fixed
+
+- **The documented Stage-D release ceremony had no legal ending.** It ordered
+  `bump -> tag -> publish -> .mcp.json pin refresh`, but the pin refresh is a COMMIT, so
+  following it always leaves commits on top of a published-and-tagged release — exactly what
+  CR-64 refuses. Measured during the 2.5.0 release: gate `[11/22]` returned
+  `versionIsPublished:true, tagSha 90c82344, headSha a74648ae`.
+
+  Corrected to **pin -> publish -> tag**, so the published tree, npm's `gitHead`, the tag and
+  HEAD are one commit by construction. Fixed at both sites that state the order. The repo's
+  own history already worked this way — `v2.3.1`, `v2.3.0` and `v2.1.0` each tag their pin
+  commit — so the prose was the outlier, not the practice.
+
+- **The same plan predicted a release does not touch `website/`.** The CHANGELOG is mirrored
+  into `website/`, so every release does; gate `[9/22]` failed on a 29h deploy lag. Replaced
+  the prediction with the measured fact and made `/massu-deploy` an explicit ceremony step.
+
+Incident: `docs/incidents/2026-08-01-release-ceremony-had-no-legal-ending.md`
+
+## [2.5.0] - 2026-08-01
+
+### Fixed
+
+- **`install-hooks` ADDED a hook registration instead of REPLACING it, so every version bump
+  doubled the hooks — and that defect BLOCKED ITS OWN REMEDY.** `mergeHookEntries` deduped by
+  EXACT COMMAND STRING, and the emitted command embeds the version, so
+  `npx -y @massu/core@1.16.2 hook-runner user-prompt` and the `@2.4.0` form were two different
+  strings, two different hooks, BOTH kept. The command was simultaneously the payload and the
+  identity, so any payload change forged a new identity.
+
+  Measured, not theoretical: one workspace carried `1.15.5` x16 **and** `1.15.2` x15 at once,
+  with 15 hook names firing TWICE per event and writing double telemetry indefinitely. Worse,
+  because upgrading duplicated, nobody upgraded — 9 of 10 workspaces on this machine sat on a
+  pre-2.0.0 version whose `better-sqlite3` ABI did not match the running Node, and one had
+  **26,119 `NODE_MODULE_VERSION` hook failures**: a total massu outage. It stayed invisible
+  because a crashing hook still **exits 0**.
+
+  Registration identity is now the `hook-runner` subcommand — a stable CLI contract (`cli.ts`
+  dispatches on exactly that token), invariant under both a version bump and a launch-mechanism
+  change. Non-massu entries keep the historical exact-command semantics, so a customer's own
+  hooks are never touched or collapsed.
+
+  Proof it can fail (CR-72, planted in the real tree, restored byte-identical by sha256):
+  reverting the identity branch to exact-command dedup turns
+  `installer-registration-identity-drift-guard.test.ts` RED — that guard drives the REAL
+  `installHooks()` over a real temp project seeded with an older-version block, a node-direct
+  block and a customer hook.
+
+### Added
+
+- **A version-stable launcher shim, cutting ~0.86s of npm bootstrap off each hook fire.**
+  `npx -y @massu/core@<v> …` spends ~0.86s starting npm before any massu code runs. Measured
+  interleaved, min-of-5: `npx` 0.97s, `npx --offline` 0.88s, `node <cli.js>` 0.11s — so the
+  cost is npm's own startup, NOT the registry, and no npx flag addresses it.
+
+  `install-hooks` now writes `~/.massu/bin/massu-hook` and emits
+  `"~/.massu/bin/massu-hook" <version> hook-runner <name>`. That path is VERSION-STABLE, and
+  the shim re-resolves the runtime AT FIRE TIME, exec'ing npx when it is absent.
+
+  This deliberately does NOT bake a versioned absolute path, which would reintroduce the class
+  P-003 (v1.9.4) eliminated: such a path is "invalidated by cache clears, global-install
+  relocations, or npx upgrades — silently 404-ing the hooks". Probing at emit time says nothing
+  about invalidation after emit. Three fail-safe layers instead — shim missing at emit emits
+  npx; runtime missing at fire execs npx; both present takes the fast path — so no single
+  missing artifact is fatal and a stale registration self-heals.
+
+  Measured after: fast path **0.11s vs npx 1.07s (9.7x)**. The fallback is mutation-proven — a
+  shim with its npx branch removed FAILS the same no-runtime case (exit 27), so the test is not
+  vacuous. `exec` in both branches preserves stdin, stdout and the exit code.
+
+  Semver MINOR: `massuHookIdentity`, `massuShimPath`, `massuShimBody`, `installMassuShim`,
+  `resolveMassuShim`, `massuRuntimeDir`, `massuRuntimeCliPath`, `resolveMassuRuntimeCli` and
+  `materializeMassuRuntime` are new exports. `MASSU_NO_NODE_DIRECT=1` forces the npx form.
+
+### Changed
+
+- **CR-70 Layer 3 amended: installer symmetry is no longer npx-specific.** Both emitters read
+  one resolver and agree on mechanism AND pinned version. The drift-guard previously asserted
+  the literal `'npx'`, which pinned an implementation detail rather than the property — it
+  would go RED on a correct mechanism change and GREEN on a wrong one that used npx on both
+  sides. Three assertions were amended on the same grounds
+  (`init-hook-paths-no-absolute`, `init-mcp-json-pin`, `cli.test.ts`); each keeps its original
+  protection of a visible pinned version and a known launch mechanism.
+
 ## [2.4.0] - 2026-07-31
 
 ### Fixed

package/commands/massu-bearings.md

@@ -41,7 +41,7 @@ Read these in parallel where possible:
 | 10 | `.claude/metrics/command-invocations.jsonl` | Command usage frequency — top/least used in last 7 days |
 | 11 | `.claude/metrics/bearings-history.jsonl` | Previous bearings runs — show trends |
 | 12 | `.claude/commands/` (ls -d */`) | Detect folder-based skills (directories vs flat files) |
-| 13 | `bash scripts/memory-contradiction-check.sh` | Contradiction count, consolidation candidates |
+| 13 | `~/.claude/bin/memory-contradiction-check . --baseline .claude/memory-contradiction-baseline.json` | Unresolved pairs + denominator; exit 2 = could-not-look, a FINDING |
 | 14 | `massu_cost_session` + `massu_cost_trend` MCP tools | Token spend this session, cost trend over time |
 | 15 | `session-state/deferred-verifications.md` | Pending production verifications from previous deploys |
 

package/commands/massu-recap.md

@@ -104,12 +104,15 @@ If no significant work: skip this section.
 Run the memory contradiction scanner:
 
 ```bash
-bash scripts/memory-contradiction-check.sh
+~/.claude/bin/memory-contradiction-check . --baseline .claude/memory-contradiction-baseline.json
 ```
 
-Parse the output:
-- **CONTRADICTION_COUNT: 0** — Memory is clean. Proceed.
-- **CONTRADICTION_COUNT: N** — Display each contradiction to the user:
+Read the EXIT CODE, and read the denominator it prints — a
+verdict with no `memory files read` line means it aborted before reporting:
+- **exit 0** — no unresolved contradictions. Quote `unresolved pairs : 0` as the evidence.
+- **exit 1** — unresolved pairs, or a STALE baseline entry. Display each to the user:
+- **exit 2** — it COULD NOT LOOK (missing corpus, unreadable file, bad baseline). This is
+  a FINDING, never a clean run. Report it as such and do not proceed as though clean.
 
 ```
 MEMORY HEALTH
@@ -122,7 +125,15 @@ MEMORY HEALTH
 
 **Do NOT auto-resolve contradictions.** Surface them so the user can decide which memory is stale.
 
-If the script is missing or fails, note: "Memory contradiction check unavailable — run `bash scripts/memory-contradiction-check.sh` manually."
+**If the checker is missing, report that as a FAILED check — never as a benign note.**
+This step was unrunnable in this repo from the day it was written until 2026-08-02: it
+named `scripts/memory-contradiction-check.sh`, which never existed here (0 tracked
+matches, 0 commits ever touching the path — it was copied from another repo's protocol).
+The instruction to "note it as unavailable" is what let a mandatory check report nothing
+for months, because "could not look" and "looked and found nothing" read identically.
+The checker is now version-controlled at `~/.claude/bin/memory-contradiction-check`, has a
+caller in `npm test` (`memory-contradiction-check-caller.test.ts`), a fixture suite, and a
+live-fire attack — so its absence is itself a red test.
 
 ### Step 3: Update Session State