# @massu/core

AI Engineering Governance MCP Server — session memory, feature registry, code intelligence, and rule enforcement for AI coding assistants.

## Quick Start

```bash
npx massu init
```

This sets up the MCP server, configuration, and lifecycle hooks in one command.

## What is Massu?

Massu is a source-available [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that adds governance capabilities to AI coding assistants like Claude Code. It provides:

- **73 MCP Tools** — quality analytics, cost tracking, security scoring, dependency analysis, and more
- **15 Lifecycle Hooks** — pre-commit gates, security scanning, intent suggestion, session management, and auto-learning pipeline
- **3-Database Architecture** — code graph (read-only), data (imports/mappings), and memory (sessions/analytics)
- **Config-Driven** — all project-specific data lives in `massu.config.yaml`

## Usage

After `npx massu init`, your AI assistant gains access to all governance tools automatically via the MCP protocol.

```bash
# Health check
npx massu doctor

# Validate configuration
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).

## License

[BSL 1.1](https://github.com/massu-ai/massu/blob/main/LICENSE) — source-available. Free to use, modify, and distribute. See LICENSE for full terms.
