@massu/core 1.2.1 → 1.4.0-soak.0

package/README.md

@@ -0,0 +1,40 @@
+# @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
+```
+
+## 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.

package/commands/README.md

@@ -0,0 +1,137 @@
+# Massu Slash-Command Templates
+
+This directory ships the slash commands installed into a consumer project's `<claudeDirName>/commands/` (default `.claude/commands/`) when the consumer runs `npx @massu/core install-commands` (or `npx @massu/core init`, which calls install-commands as part of its flow).
+
+As of `@massu/core@1.3.0`, command files are **stack-aware**: a template can ship one or more language-specific variants alongside the default, and the installer picks the variant that matches the consumer's `massu.config.yaml`. Local edits are preserved across reinstalls via a manifest written to `<claudeDirName>/.massu/install-manifest.json`.
+
+This README covers:
+
+1. The variant filename convention.
+2. The variant-resolution algorithm (priority order + tie-break).
+3. The local-edit-protection manifest.
+4. The `npx @massu/core show-template <name>` debugging command.
+
+## 1. Variant filename convention
+
+```
+<base>.md                        # default — used when no variant matches
+<base>.python.md                 # FastAPI / Django / generic Python (one-axis)
+<base>.python-fastapi.md         # Python + FastAPI (two-axis: lang + sub-framework)
+<base>.python-django.md          # Python + Django (two-axis: lang + sub-framework)
+<base>.swift.md                  # SwiftUI / iOS / visionOS
+<base>.rust.md                   # axum / actix / generic Rust
+<base>.typescript.md             # reserved for future use; currently no variants ship
+```
+
+The two-axis form (`<base>.<lang>-<framework>.md`) is tried BEFORE the one-axis (`<base>.<lang>.md`) form. It is selected when the consumer's config declares `framework.languages.<lang>.framework = "<sub-framework>"` (e.g. `fastapi` or `django`).
+
+The variant convention applies **only at the top level** of `packages/core/commands/`. Files inside subdirectories (e.g., `_shared-references/`, `massu-loop/references/`) are copied recursively as-is — no variant resolution, no dot-skip filtering. Future authors can use dotted filenames in nested dirs without losing them to the variant filter.
+
+The variant convention is **opt-in**: a template that does NOT ship any `<base>.<variant>.md` siblings is variant-agnostic and the unsuffixed `<base>.md` is used everywhere.
+
+## 2. Variant-resolution algorithm
+
+Given a base template name `B` and the consumer's `framework` config from `massu.config.yaml`:
+
+1. **Build the candidate list `V`** in priority order:
+   1. `framework.primary` (or `framework.type` if `primary` is undefined). Skipped if the value is `"multi"`.
+   2. Each declared `framework.languages.<lang>` entry whose `framework` field is a non-empty string, in **YAML declaration order** (first-declared wins on ties).
+   3. **Passthrough fallback**: well-known top-level `framework.<lang>` blocks (typescript / javascript / python / swift / rust / go) with a non-empty `framework` field, in fixed order, excluding any language already covered. This is what lets a project that declares `framework.swift` at the top level (alongside `framework.languages.python`) still pick up the `.swift.md` variant when the languages block doesn't contain swift.
+   4. The unsuffixed default (`""`) as the last fallback.
+2. **Probe disk** in order: for each candidate `c`, check whether `<base>.<c>.md` exists in the bundled commands directory.
+3. **Return**:
+   - First hit → copy that file.
+   - No hit AND `framework.type === "multi"` AND `framework.primary` is undefined → write a one-line warning to stderr and copy the unsuffixed default.
+   - No hit otherwise → skip the file (this only happens if the base template was deleted and only orphan variants remain, which the Phase 0 audit prevents).
+
+The target filename in the consumer dir is always the BASE name (`<base>.md`) — variant suffixes are an internal package detail.
+
+### Tie-break — which variant wins?
+
+If a consumer declares both `python` and `swift` in `framework.languages` AND a template ships both `.python.md` and `.swift.md`, the variant declared FIRST in `framework.languages` wins. Consumers control this by reordering keys in `massu.config.yaml`. Passthrough-fallback entries (rule 1.3) are appended AFTER all `framework.languages` entries.
+
+There is no per-template override mechanism. If you need one, file an issue.
+
+## 3. Local-edit protection — the manifest
+
+`@massu/core@1.3.0` introduces a manifest at:
+
+```
+<consumer-root>/<claudeDirName>/.massu/install-manifest.json
+```
+
+(where `claudeDirName` is the value of `conventions.claudeDirName` in `massu.config.yaml`, defaulting to `.claude`).
+
+Each entry maps an asset-relative path (e.g., `commands/massu-scaffold-router.md`) to the SHA-256 of its content at the last successful install.
+
+### What the installer does on each run
+
+For each file `<asset>` to be installed, three hashes are computed:
+
+| Hash | What it represents |
+|------|--------------------|
+| `sourceHash` | The bundled upstream content NOW. |
+| `existingHash` | The current consumer file content. `undefined` if missing. |
+| `lastInstalledHash` | The hash recorded in the manifest. `undefined` on first install. |
+
+Decision matrix:
+
+| Condition | Action | Counter |
+|-----------|--------|---------|
+| target missing | write upstream, record `sourceHash` in manifest | `installed` |
+| `existingHash === sourceHash` | already in sync; record `sourceHash` (covers manifest healing) | `skipped` |
+| `lastInstalledHash` undefined AND `existingHash !== sourceHash` | first-install heuristic: keep the consumer file, record `existingHash`, print a one-line notice | `kept` |
+| `existingHash !== lastInstalledHash` (consumer edited it) | preserve, print `kept your version` notice + diff hint | `kept` |
+| `existingHash === lastInstalledHash` AND `sourceHash !== lastInstalledHash` (clean upstream upgrade) | write upstream, record `sourceHash` | `updated` |
+
+The manifest is written **atomically** (`tempfile + renameSync`) so a crash mid-install never leaves a partially-written manifest.
+
+### What this means for you
+
+- Edit your `<claudeDirName>/commands/*.md` freely. The installer will not stomp your edits.
+- To accept the upstream version of a file you've edited: delete it and rerun `install-commands`.
+- To diff your version against upstream:
+  ```bash
+  diff .claude/commands/massu-scaffold-router.md \
+       <(npx @massu/core show-template massu-scaffold-router)
+  ```
+
+## 4. `npx @massu/core show-template <name>`
+
+Prints the resolved template content (post-variant-resolution) to stdout. Used in the diff one-liner above. Accepts both `massu-scaffold-router` and `massu-scaffold-router.md`. Exits 1 on unknown names.
+
+## 5. Currently shipped variants
+
+| Base | Variants |
+|------|----------|
+| `massu-scaffold-router` | `.python-fastapi.md` (FastAPI — two-axis), `.python-django.md` (Django — two-axis) |
+| `massu-scaffold-page` | `.swift.md` (SwiftUI), regenerated default with embedded Next.js / FastAPI / SwiftUI / Rust examples |
+| `massu-deploy` | `.python-launchd.md`, `.python-systemd.md`, `.python-docker.md`, `.python-fly.md` (all two-axis) |
+
+All other top-level templates ship as variant-agnostic defaults (one `<base>.md`).
+
+### Template variable substitution
+
+As of `@massu/core@1.3.0`, template files may contain `{{variable.path}}` and `{{variable.path | default("fallback")}}` placeholders. These are rendered against the consumer's `massu.config.yaml` (all `framework.*`, `paths.*`, and `config.*` fields) plus the `detected.*` block written by the codebase introspector (e.g. `detected.python.auth_dep`, `detected.swift.api_client_class`).
+
+Rules:
+- Every `{{detected.*}}` reference MUST include a `| default("...")` fallback — introspection may return nothing.
+- Use `\{{` to emit a literal `{{` in the rendered output (e.g. Go/Docker format strings).
+- A render error on a single file causes that file to be skipped (stderr message only); the rest of the install continues.
+
+Pass `--skip-commands` to `massu init` or `massu refresh` to suppress command installation entirely.
+
+## 6. Adding a new variant
+
+1. Create `<base>.<lang>.md` in this directory using the same frontmatter shape as the default.
+2. The default `<base>.md` should remain generic (or be regenerated if it was previously stack-specific — see `massu-scaffold-page.md` for the pattern of an embedded multi-stack default).
+3. Add a row to the table in section 5.
+4. Add a test case to `packages/core/src/__tests__/install-commands.test.ts` that exercises the new variant against a fixture config.
+5. Update `docs/internal/2026-04-26-template-variant-audit.md` (the audit doc) with the new label.
+
+## 7. Reference
+
+- Plan: `/Users/ekoultra/hedge/docs/plans/2026-04-26-massu-stack-aware-command-templates.md`
+- Audit: `docs/internal/2026-04-26-template-variant-audit.md`
+- Implementation: `packages/core/src/commands/install-commands.ts`
+- Tests: `packages/core/src/__tests__/install-commands.test.ts` and `show-template.test.ts`

package/commands/massu-deploy.python-docker.md

@@ -0,0 +1,170 @@
+---
+name: massu-deploy
+description: "Deploy a containerized Python service via docker compose — force-recreate the service container, health-check poll, diff before/after, rollback if unhealthy"
+allowed-tools: Bash(*), Read(*), Grep(*), Glob(*)
+---
+
+# Massu Deploy: Python Service — Docker Compose
+
+Force-recreates the Docker container for a Python service using `docker compose`. Use this variant when your service is containerized and `massu.config.yaml` declares `config.python.service_label` matching the compose service name.
+
+## Workflow Position
+
+```
+/massu-push -> /massu-deploy (docker variant)
+```
+
+This command redeploys a running container. **If the service handles financial, transactional, or consequential state, real data is at risk** — pre-flight checks are mandatory.
+
+---
+
+## NON-NEGOTIABLE RULES
+
+- **Never deploy with uncommitted changes** — push first via `/massu-push`
+- **Never deploy with failing tests** — test suite must be green before this runs
+- **Always restart-and-probe** — `docker compose up` ≠ the new image is healthy
+- **Never stop containers without identifying them first** — confirm the compose service name before running any destructive command
+
+---
+
+## Pre-flight
+
+```bash
+# 1. Branch + working tree clean
+test -z "$(git status --porcelain)" || { echo "DIRTY — commit/stash first"; exit 1; }
+
+# 2. Tests green
+pytest -x 2>&1 | tail -10
+
+# 3. Confirm the service is running
+docker compose ps {{config.python.service_label | default("<service-label>")}}
+
+# 4. Capture current health for diff
+curl -sS http://localhost:8000/health | python3 -m json.tool \
+  > /tmp/{{config.python.service_label | default("service")}}-health-before.json
+```
+
+---
+
+## Build (if image needs rebuilding)
+
+```bash
+# Rebuild the image for this service only (skip if using a pre-built registry image)
+docker compose build {{config.python.service_label | default("<service-label>")}}
+```
+
+---
+
+## Approval Gate
+
+```
+===============================================================================
+APPROVAL REQUIRED — DOCKER COMPOSE REDEPLOY
+===============================================================================
+
+Compose service : {{config.python.service_label | default("<service-label>")}}
+Supervisor      : docker compose
+Pre-flight      : PASS
+
+This will:
+  1. docker compose up -d --force-recreate {{config.python.service_label | default("<service-label>")}}
+  2. Poll /health every 2s against the container (max 60s) until 200
+  3. Smoke /health + any critical endpoint
+  4. Diff before/after health JSON
+  5. On failure: print rollback command
+
+Reply "approve" or "abort".
+===============================================================================
+```
+
+---
+
+## Redeploy
+
+```bash
+docker compose up -d --force-recreate {{config.python.service_label | default("<service-label>")}}
+```
+
+`--force-recreate` ensures the container is replaced even if the image tag didn't change. Omit if you only want `up` to no-op on unchanged images.
+
+---
+
+## Poll Container Health
+
+```bash
+for i in $(seq 1 30); do
+  sleep 2
+  status=$(curl -sS -o /dev/null -w "%{http_code}" http://localhost:8000/health || echo "000")
+  [ "$status" = "200" ] && { echo "READY after ${i} polls"; break; }
+  echo "poll ${i}: ${status}"
+done
+```
+
+If the compose file declares a `HEALTHCHECK` directive, you can also poll the Docker health state:
+
+```bash
+for i in $(seq 1 30); do
+  sleep 2
+  state=$(docker inspect --format='\{{.State.Health.Status}}' \
+    "$(docker compose ps -q {{config.python.service_label | default("<service-label>")}})") 2>/dev/null || state="unknown"
+  [ "$state" = "healthy" ] && { echo "Container healthy after ${i} polls"; break; }
+  echo "poll ${i}: $state"
+done
+```
+
+---
+
+## Smoke + Diff
+
+```bash
+curl -sS http://localhost:8000/health | python3 -m json.tool \
+  > /tmp/{{config.python.service_label | default("service")}}-health-after.json
+
+diff \
+  /tmp/{{config.python.service_label | default("service")}}-health-before.json \
+  /tmp/{{config.python.service_label | default("service")}}-health-after.json \
+  | head -50
+```
+
+---
+
+## Tail Container Logs
+
+```bash
+# Last 100 lines, filtered for errors
+docker compose logs {{config.python.service_label | default("<service-label>")}} \
+  --tail=100 --no-log-prefix | grep -iE "error|warn" | head -20
+
+# Follow live (Ctrl-C to stop)
+docker compose logs -f {{config.python.service_label | default("<service-label>")}} --no-log-prefix
+```
+
+---
+
+## Rollback
+
+If `/health` does not return 200 within 60s, or any smoke check fails:
+
+```bash
+# Option A: revert code + redeploy
+git revert HEAD --no-edit
+docker compose build {{config.python.service_label | default("<service-label>")}}
+docker compose up -d --force-recreate {{config.python.service_label | default("<service-label>")}}
+
+# Option B: roll back to the previous image tag (if using a registry)
+# docker compose pull {{config.python.service_label | default("<service-label>")}}:<prev-tag>
+# docker compose up -d --force-recreate {{config.python.service_label | default("<service-label>")}}
+```
+
+Then page yourself or your on-call — an unhealthy production container is an incident.
+
+---
+
+## Audit Log
+
+```bash
+echo "$(date -u +%FT%TZ) deploy surface=docker sha=$(git rev-parse HEAD) service={{config.python.service_label | default("<service-label>")}} actor=$(whoami)" \
+  >> data/audit/deploys.log
+```
+
+Done. Report: compose service name, image digest or sha, restart time, health status, any warnings.

package/commands/massu-deploy.python-fly.md

@@ -0,0 +1,189 @@
+---
+name: massu-deploy
+description: "Deploy a Python service to Fly.io — flyctl deploy, status check, log tail, rollback if unhealthy"
+allowed-tools: Bash(*), Read(*), Grep(*), Glob(*)
+---
+
+# Massu Deploy: Python Service — Fly.io
+
+Deploys a Python service to Fly.io using `flyctl deploy`. Use this variant when your project targets Fly.io and has a `fly.toml` in the repository root. The app name comes from `fly.toml` (or `config.python.service_label` as a fallback).
+
+## Workflow Position
+
+```
+/massu-push -> /massu-deploy (fly variant)
+```
+
+This command deploys to a live Fly.io app. **If the app handles financial, transactional, or otherwise consequential state, real data is at risk** — pre-flight checks are mandatory.
+
+---
+
+## NON-NEGOTIABLE RULES
+
+- **Never deploy with uncommitted changes** — push first via `/massu-push`
+- **Never deploy with failing tests** — test suite must be green before this runs
+- **Always check status after deploy** — `flyctl deploy` success ≠ the new release is healthy
+- **Never force a deploy to fix a broken deploy** — diagnose first, then decide
+
+---
+
+## Pre-flight
+
+```bash
+# 1. Branch + working tree clean
+test -z "$(git status --porcelain)" || { echo "DIRTY — commit/stash first"; exit 1; }
+
+# 2. Tests green
+pytest -x 2>&1 | tail -10
+
+# 3. Confirm flyctl is authenticated and the app exists
+flyctl status --app {{config.python.service_label | default("<app-name>")}} 2>&1 | head -20
+
+# 4. Note the current release number for rollback reference
+flyctl releases --app {{config.python.service_label | default("<app-name>")}} --limit 3
+```
+
+---
+
+## `fly.toml` — Key Fields to Verify
+
+Before deploying, confirm these sections exist in `fly.toml`:
+
+```toml
+app = "{{config.python.service_label | default("<app-name>")}}"
+primary_region = "<region>"  # e.g. "ord", "lax", "iad"
+
+[build]
+  # Dockerfile or builder block
+
+[http_service]
+  internal_port = 8000
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+
+[[vm]]
+  memory = "512mb"
+  cpu_kind = "shared"
+  cpus = 1
+
+[checks]
+  [checks.health]
+    grace_period = "10s"
+    interval = "30s"
+    method = "GET"
+    path = "/health"
+    protocol = "https"
+    timeout = "10s"
+```
+
+Missing a `[checks.health]` block means Fly.io won't automatically detect an unhealthy release.
+
+---
+
+## Approval Gate
+
+```
+===============================================================================
+APPROVAL REQUIRED — FLY.IO DEPLOY
+===============================================================================
+
+App name   : {{config.python.service_label | default("<app-name>")}}
+Platform   : Fly.io
+Pre-flight : PASS
+
+This will:
+  1. flyctl deploy --app {{config.python.service_label | default("<app-name>")}}
+  2. Wait for Fly.io health checks to pass (built-in to flyctl)
+  3. flyctl status to confirm all instances are running
+  4. Smoke /health endpoint
+  5. On failure: print rollback command
+
+Reply "approve" or "abort".
+===============================================================================
+```
+
+---
+
+## Deploy
+
+```bash
+flyctl deploy --app {{config.python.service_label | default("<app-name>")}}
+```
+
+`flyctl deploy` builds the image (or reuses a cached layer), pushes to the Fly.io registry, creates a new release, and waits for health checks. Pass `--strategy rolling` or `--strategy bluegreen` if your app supports it.
+
+---
+
+## Post-Deploy Status
+
+```bash
+# Confirm all machines are healthy
+flyctl status --app {{config.python.service_label | default("<app-name>")}}
+
+# Show the new release
+flyctl releases --app {{config.python.service_label | default("<app-name>")}} --limit 1
+```
+
+---
+
+## Smoke
+
+```bash
+# Hit the public health endpoint (replace with your actual hostname)
+APP_HOST=$(flyctl info --app {{config.python.service_label | default("<app-name>")}} --hostname 2>/dev/null | head -1 || echo "{{config.python.service_label | default("<app-name>")}}.fly.dev")
+curl -sS "https://${APP_HOST}/health" | python3 -m json.tool
+```
+
+---
+
+## Tail Logs
+
+```bash
+# Live log stream (Ctrl-C to stop)
+flyctl logs --app {{config.python.service_label | default("<app-name>")}}
+
+# Filter for errors in recent output
+flyctl logs --app {{config.python.service_label | default("<app-name>")}} 2>&1 | grep -iE "error|warn|exception" | head -30
+```
+
+---
+
+## Rollback
+
+If health checks fail or the smoke check returns non-200:
+
+```bash
+# Roll back to the previous release
+flyctl releases --app {{config.python.service_label | default("<app-name>")}} --limit 5
+flyctl deploy --image <previous-image-ref> --app {{config.python.service_label | default("<app-name>")}}
+```
+
+Or use the Fly dashboard's "Rollback" button if the release number is known.
+
+Then page yourself or your on-call — an unhealthy Fly.io release is an incident.
+
+---
+
+## Secrets Management
+
+Do NOT hard-code secrets in `fly.toml`. Use Fly secrets:
+
+```bash
+# Set a secret (prompts for value if omitted)
+flyctl secrets set MY_SECRET_KEY=<value> --app {{config.python.service_label | default("<app-name>")}}
+
+# List current secret names (values are redacted)
+flyctl secrets list --app {{config.python.service_label | default("<app-name>")}}
+```
+
+---
+
+## Audit Log
+
+```bash
+echo "$(date -u +%FT%TZ) deploy surface=fly sha=$(git rev-parse HEAD) app={{config.python.service_label | default("<app-name>")}} actor=$(whoami)" \
+  >> data/audit/deploys.log
+```
+
+Done. Report: app name, release number, deploy time, health status, any warnings.

package/commands/massu-deploy.python-launchd.md

@@ -0,0 +1,144 @@
+---
+name: massu-deploy
+description: "Deploy a Python service supervised by launchd (macOS) — restart the launchd agent, poll health, diff before/after, rollback if unhealthy"
+allowed-tools: Bash(*), Read(*), Grep(*), Glob(*)
+---
+
+# Massu Deploy: Python Service — launchd (macOS)
+
+Restarts a Python service running under `launchd` on macOS. Use this variant when your `massu.config.yaml` declares `config.python.service_label` and your host is macOS.
+
+## Workflow Position
+
+```
+/massu-push -> /massu-deploy (launchd variant)
+```
+
+This command restarts a production service. **If the service handles financial, transactional, or otherwise consequential state, real data is at risk** — pre-flight checks are mandatory.
+
+---
+
+## NON-NEGOTIABLE RULES
+
+- **Never deploy with uncommitted changes** — push first via `/massu-push`
+- **Never deploy with failing tests** — test suite must be green before this runs
+- **Always restart-and-probe** — file-saved ≠ process-running-the-fix
+- **Never kill processes without identifying them first** — confirm the label before sending any signal
+
+---
+
+## Pre-flight
+
+```bash
+# 1. Branch + working tree clean
+test -z "$(git status --porcelain)" || { echo "DIRTY — commit/stash first"; exit 1; }
+
+# 2. Tests green
+pytest -x 2>&1 | tail -10
+
+# 3. Confirm the launchd agent is registered
+launchctl list | grep {{config.python.service_label | default("<service-label>")}}
+
+# 4. Capture current health for diff
+curl -sS http://localhost:8000/health | python3 -m json.tool \
+  > /tmp/{{config.python.service_label | default("service")}}-health-before.json
+```
+
+---
+
+## Approval Gate
+
+```
+===============================================================================
+APPROVAL REQUIRED — LAUNCHD RESTART
+===============================================================================
+
+Service label : {{config.python.service_label | default("<service-label>")}}
+Supervisor    : launchd (macOS)
+Pre-flight    : PASS
+
+This will:
+  1. launchctl kickstart -k gui/$(id -u)/{{config.python.service_label | default("<service-label>")}}
+  2. Poll /health every 2s (max 60s) until 200
+  3. Smoke /health + any critical endpoint
+  4. Diff before/after health JSON
+  5. On failure: print rollback command
+
+Reply "approve" or "abort".
+===============================================================================
+```
+
+---
+
+## Restart
+
+```bash
+launchctl kickstart -k gui/$(id -u)/{{config.python.service_label | default("<service-label>")}}
+```
+
+The `-k` flag kills the existing process before relaunching — equivalent to a clean restart. If you need to stop without restart, use `launchctl kill SIGTERM gui/$(id -u)/{{config.python.service_label | default("<service-label>")}}` instead.
+
+---
+
+## Poll Health
+
+```bash
+for i in $(seq 1 30); do
+  sleep 2
+  status=$(curl -sS -o /dev/null -w "%{http_code}" http://localhost:8000/health || echo "000")
+  [ "$status" = "200" ] && { echo "READY after ${i} polls"; break; }
+  echo "poll ${i}: ${status}"
+done
+```
+
+---
+
+## Smoke + Diff
+
+```bash
+curl -sS http://localhost:8000/health | python3 -m json.tool \
+  > /tmp/{{config.python.service_label | default("service")}}-health-after.json
+
+diff \
+  /tmp/{{config.python.service_label | default("service")}}-health-before.json \
+  /tmp/{{config.python.service_label | default("service")}}-health-after.json \
+  | head -50
+```
+
+---
+
+## Tail Startup Logs
+
+```bash
+# Unified log (most reliable for launchd-managed services)
+log show \
+  --predicate 'subsystem == "{{config.python.service_label | default("<service-label>")}}"' \
+  --last 2m --info 2>/dev/null | grep -iE "error|warn" | head -20
+
+# Alternative: stderr from the plist's StandardErrorPath
+# cat ~/Library/Logs/{{config.python.service_label | default("<service-label>")}}/stderr.log | tail -40
+```
+
+---
+
+## Rollback
+
+If `/health` does not return 200 within 60s, or any smoke check fails:
+
+```bash
+git revert HEAD --no-edit
+launchctl kickstart -k gui/$(id -u)/{{config.python.service_label | default("<service-label>")}}
+```
+
+Then page yourself or your on-call — an unhealthy production service is an incident.
+
+---
+
+## Audit Log
+
+```bash
+echo "$(date -u +%FT%TZ) deploy surface=launchd sha=$(git rev-parse HEAD) label={{config.python.service_label | default("<service-label>")}} actor=$(whoami)" \
+  >> data/audit/deploys.log
+```
+
+Done. Report: label, sha, restart time, health status, any warnings.