memento-mori-jester 0.1.87 → 0.1.88

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to Memento Mori Jester are tracked here.
 
 ## Unreleased
 
+## 0.1.88
+
+- Added `examples/reports`, a small checked report gallery for fresh `doctor`, destructive-command `summary`, and full blocked-command review output.
+- Added `npm run reports:check`, which installs the package into a temporary consumer project and verifies every gallery command against stable output fragments.
+- Updated README, getting-started docs, maintainer triage docs, release docs, production-readiness docs, roadmap, and release notes for the report gallery.
+
 ## 0.1.87
 
 - Fixed `npm run consumer:quickstart:check -- --package memento-mori-jester@latest` so registry package specs install through `npm install --save-dev <spec>` in the temporary consumer project.

package/README.md

@@ -72,6 +72,8 @@ For a first read-only CI smoke, copy [examples/ci/adoption-smoke.yml](examples/c
 
 Maintainers can prove that fresh-project path with [examples/consumer-quickstart](examples/consumer-quickstart) and `npm run consumer:quickstart:check`, which installs the package into a temporary project and runs the same quickstart commands from there.
 
+For trust-building output examples, see [examples/reports](examples/reports). `npm run reports:check` installs the package into a temporary project and proves the gallery's `doctor`, `summary`, and blocked-command reports stay current.
+
 Expected vibe:
 
 ```text
@@ -442,6 +444,7 @@ More setup examples:
 - [Framework CI Examples](examples/ci)
 - [Adoption Smoke CI](examples/ci/adoption-smoke.yml)
 - [Consumer Quickstart Smoke](examples/consumer-quickstart)
+- [Real-World Report Gallery](examples/reports)
 - [Security Policy](SECURITY.md)
 - [Maintainer Triage](docs/MAINTAINER_TRIAGE.md)
 - [Changelog](CHANGELOG.md)
@@ -461,6 +464,7 @@ Framework CI examples:
 
 - [Adoption Smoke CI](examples/ci/adoption-smoke.yml)
 - [Consumer Quickstart Smoke](examples/consumer-quickstart)
+- [Real-World Report Gallery](examples/reports)
 - [Next.js CI](examples/ci/nextjs.yml)
 - [Vite React CI](examples/ci/vite-react.yml)
 - [Express API CI](examples/ci/express-api.yml)
@@ -516,6 +520,7 @@ Use the false-positive template for noisy cautions or blocks. Include `jester su
 Maintainers can use [docs/MAINTAINER_TRIAGE.md](docs/MAINTAINER_TRIAGE.md) to turn useful false-positive reports into redacted fixtures.
 Run `npm run fixtures:check` before merging fixture changes; it catches duplicate IDs, missing rule metadata, weak descriptions, unsafe-looking content, and duplicate content.
 Run `npm run fixtures:report` to see fixture coverage by rule, rule family, preset slice, kind, verdict, quiet-pass boundaries, feasible pass-case gaps, and curation-next guidance before choosing the next fixture. Use `npm run fixtures:report -- --markdown` when you want a paste-ready summary for release notes or GitHub issues.
+Run `npm run reports:check` after editing [examples/reports](examples/reports); it verifies the public report gallery against an installed package in a temporary consumer project.
 Run `npm run promo:card` to regenerate the repo-local social preview card after changing its copy or design.
 Run `npm run promo:check` after editing promo assets; it checks the current demo video, stills, docs, and fixture evidence numbers stay in sync.
 Run `npm run site:check` after editing the repo-local landing page; it verifies the start command, demo links, social card, repo, release, and npm links.
@@ -529,6 +534,7 @@ Release checklist:
 ```powershell
 npm.cmd test
 npm.cmd run consumer:quickstart:check
+npm.cmd run reports:check
 npm.cmd run promo:check
 npm.cmd run production:check
 npm.cmd run pack:dry

package/ROADMAP.md

@@ -6,6 +6,7 @@ Memento Mori Jester is usable today as a CLI, MCP server, GitHub Action, and git
 
 ## Recently Shipped
 
+- Checked report gallery in v0.1.88, proving fresh `doctor`, destructive-command `summary`, and blocked-command reports from an installed consumer project.
 - Consumer quickstart registry-mode fix in v0.1.87, proving the same smoke against `memento-mori-jester@latest` after publish.
 - Consumer quickstart smoke in v0.1.86, proving the first installed-project commands from a minimal repo before release.
 - Adoption smoke CI example in v0.1.85, giving real repos a read-only workflow for `doctor`, `summary`, and packaged framework tuning checks.

package/docs/GETTING_STARTED.md

@@ -106,7 +106,7 @@ npx -y memento-mori-jester@latest bootstrap --preset node
 
 Then tell them to open `MEMENTO_MORI.md`.
 
-For copy-paste agent and hook examples, see [examples](../examples). For stack-specific config examples, see [preset example packs](../examples/presets) for Next.js, Vite React, Express API, FastAPI, Terraform/Kubernetes, and AI MCP repos. For copy-paste CI workflows, see [framework CI examples](../examples/ci). For concrete pass, caution, and block cases, see [review fixtures](../examples/fixtures). For stack-shaped noisy-rule reports, see [framework tuning examples](FRAMEWORK_TUNING.md) and the checked [framework tuning cookbook](../examples/tuning).
+For copy-paste agent and hook examples, see [examples](../examples). For stack-specific config examples, see [preset example packs](../examples/presets) for Next.js, Vite React, Express API, FastAPI, Terraform/Kubernetes, and AI MCP repos. For copy-paste CI workflows, see [framework CI examples](../examples/ci). For concrete pass, caution, and block cases, see [review fixtures](../examples/fixtures). For first trustworthy output examples, see the checked [report gallery](../examples/reports). For stack-shaped noisy-rule reports, see [framework tuning examples](FRAMEWORK_TUNING.md) and the checked [framework tuning cookbook](../examples/tuning).
 
 ## Need Help?
 

package/docs/MAINTAINER_TRIAGE.md

@@ -17,6 +17,8 @@ npx -y memento-mori-jester@latest summary --kind <command|plan|diff|final> "<min
 npx -y memento-mori-jester@latest tune <rule-id> --json
 ```
 
+For users who just need to understand what a healthy report looks like, point them at the checked [report gallery](../examples/reports). Maintainers can run `npm run reports:check` to prove those examples still match the current package output.
+
 Do not ask users to paste secrets, private code, customer data, live credentials, complete CI logs, or unredacted SARIF. If the report involves credential exposure, command execution, unexpected network access, private code disclosure, package publishing, or MCP data exposure, route it through [SECURITY.md](../SECURITY.md).
 
 ## Triage Labels

package/docs/PRODUCTION_READINESS.md

@@ -46,6 +46,7 @@ This checklist defines what "production grade" means for Memento Mori Jester rig
 
 - `README.md` leads with a no-write first run, project bootstrap, agent setup, and optional hooks/CI.
 - `docs/GETTING_STARTED.md`, `docs/CLI.md`, `docs/RELEASE.md`, and `docs/TRUSTED_PUBLISHING.md` cover the core adoption and release paths.
+- `examples/reports` provides checked, public-safe report examples for fresh install diagnostics, summary output, and blocked command reviews.
 - `site/index.html` gives maintainers a static one-page share surface that reuses the demo, social card, start command, and public links.
 - Every public release has matching `CHANGELOG.md` notes and `docs/RELEASE_NOTES_vX.Y.Z.md`.
 
@@ -63,6 +64,7 @@ This checklist defines what "production grade" means for Memento Mori Jester rig
 - `npm run framework:tuning:check` keeps the framework tuning guide, cookbook JSON, cookbook README, and fixture IDs aligned.
 - `npm run framework:tuning:doctor` runs the cookbook tune commands through the built CLI with temporary preset configs, so package consumers do not inherit stale recipes.
 - `npm run consumer:quickstart:check` installs the package into a temporary minimal project and runs `doctor`, `summary`, and packaged framework tuning checks from that consumer side.
+- `npm run reports:check` installs the package into a temporary minimal project and runs the report gallery's `doctor`, `summary`, and blocked-command examples through that consumer side.
 - `npm run promo:card` regenerates the deterministic social preview card, and `npm run promo:check` verifies current repo-local promo assets against the current fixture evidence before maintainers post or refresh the demo.
 - `npm run site:check` verifies the static landing page before maintainers post or host it.
 - npm publish has a manual workflow fallback, but the normal release path is tag-driven trusted publishing.
@@ -84,6 +86,7 @@ This checklist defines what "production grade" means for Memento Mori Jester rig
 - framework tuning cookbook doctor checks are wired into `npm test`.
 - CI adoption example checks are wired into `npm test`.
 - consumer quickstart smoke checks are wired into `npm test`.
+- report gallery checks are wired into `npm test`.
 - promo freshness checks are wired into `npm test`.
 - site checks are wired into `npm test`.
 

package/docs/RELEASE.md

@@ -16,6 +16,7 @@ npm.cmd run framework:tuning:check
 npm.cmd run framework:tuning:doctor
 npm.cmd run ci:adoption:check
 npm.cmd run consumer:quickstart:check
+npm.cmd run reports:check
 npm.cmd run promo:card:check
 npm.cmd run promo:check
 npm.cmd run site:check
@@ -28,7 +29,7 @@ Move the current changelog bullets into a matching version section and add `docs
 ## 2. Tag And Push
 
 ```powershell
-git add package.json package-lock.json CHANGELOG.md docs/RELEASE_NOTES_v0.1.x.md docs/PRODUCTION_READINESS.md docs/MAINTAINER_TRIAGE.md docs/FRAMEWORK_TUNING.md docs/GITHUB_ACTIONS.md examples/ci examples/consumer-quickstart examples/tuning scripts/check-ci-adoption.mjs scripts/check-consumer-quickstart.mjs scripts/check-framework-tuning.mjs scripts/doctor-framework-tuning.mjs SECURITY.md .github/ISSUE_TEMPLATE
+git add package.json package-lock.json CHANGELOG.md docs/RELEASE_NOTES_v0.1.x.md docs/PRODUCTION_READINESS.md docs/MAINTAINER_TRIAGE.md docs/FRAMEWORK_TUNING.md docs/GITHUB_ACTIONS.md examples/ci examples/consumer-quickstart examples/reports examples/tuning scripts/check-ci-adoption.mjs scripts/check-consumer-quickstart.mjs scripts/check-report-gallery.mjs scripts/check-framework-tuning.mjs scripts/doctor-framework-tuning.mjs SECURITY.md .github/ISSUE_TEMPLATE
 git commit -m "Release v0.1.x"
 git tag -a v0.1.x -m "Memento Mori Jester v0.1.x"
 git push origin main
@@ -85,6 +86,7 @@ npx.cmd -y memento-mori-jester@latest config validate --config jester-ai.config.
 npx.cmd -y memento-mori-jester@latest config init --preset security --path jester-security.config.json
 npx.cmd -y memento-mori-jester@latest config validate --config jester-security.config.json
 npm.cmd run consumer:quickstart:check -- --package memento-mori-jester@latest
+npm.cmd run reports:check -- --package memento-mori-jester@latest
 ```
 
 ## 4. MCP Copy-Paste

package/docs/RELEASE_NOTES_v0.1.88.md

@@ -0,0 +1,62 @@
+# Memento Mori Jester v0.1.88
+
+## Summary
+
+This release adds a small checked report gallery. The goal is to make the project easier to trust from concrete public examples without changing rule behavior: a fresh `doctor` report, a destructive-command `summary`, and a full blocked command review.
+
+## What Changed
+
+- Added `examples/reports/report-gallery.json`.
+- Added `examples/reports/README.md`.
+- Added `scripts/check-report-gallery.mjs`.
+- Added `npm run reports:check`.
+- Wired the report gallery checker into `npm test` and production-readiness checks.
+- Updated README, getting-started docs, maintainer triage docs, release docs, production-readiness docs, roadmap, and changelog.
+
+## Public Interface
+
+- No CLI command changes.
+- No MCP tool changes.
+- No config schema changes.
+- No review rule, scoring, matching, or verdict behavior changes.
+- No GitHub Action input changes.
+- New maintainer/package script: `npm run reports:check`.
+- New checked example gallery: `examples/reports`.
+
+## Release Validation
+
+```powershell
+npm.cmd test
+npm.cmd run reports:check
+npm.cmd run reports:check -- --package memento-mori-jester@latest
+npm.cmd run demo:svg:check
+npm.cmd run promo:card:check
+npm.cmd run promo:check
+npm.cmd run fixtures:report
+npm.cmd run fixtures:report -- --json
+npm.cmd run fixtures:report -- --markdown
+npm.cmd run pack:dry
+git diff --check
+node .\dist\cli.js doctor
+node .\dist\cli.js summary --kind command "git reset --hard"
+node .\dist\cli.js command "git reset --hard"
+git diff | node .\dist\cli.js diff --fail-on block --subject "v0.1.88 checked report gallery"
+```
+
+Expected:
+
+- `reports:check` installs the package into a temporary minimal project,
+- `fresh-install-doctor` passes against installed `jester doctor`,
+- `destructive-command-summary` passes against installed `jester summary --kind command "git reset --hard"`,
+- `blocked-command-review` passes against installed `jester command "git reset --hard"`,
+- fixture report still shows `Fixtures: 222`,
+- GitHub Release and npm Publish complete from the `v0.1.88` tag.
+
+After publish:
+
+```powershell
+npm.cmd view memento-mori-jester version --silent
+npx.cmd -y memento-mori-jester@latest doctor
+npx.cmd -y memento-mori-jester@latest summary --kind command "git reset --hard"
+npm.cmd run reports:check -- --package memento-mori-jester@latest
+```

package/examples/reports/README.md

@@ -0,0 +1,25 @@
+# Real-World Report Gallery
+
+These small examples show the first reports people tend to trust when trying Memento Mori Jester in a fresh project. They are public, synthetic, and intentionally boring: no private code, no tokens, no customer data, and no full CI logs.
+
+The machine-readable source is [report-gallery.json](report-gallery.json). It is checked by `npm run reports:check`, which installs Memento Mori Jester into a temporary consumer project and runs each command through that installed package.
+
+| ID | Report | Command | What It Proves |
+| --- | --- | --- | --- |
+| `fresh-install-doctor` | Fresh install health check | `jester doctor` | The package, runtime, MCP file, review engine, config, hook, and workflow diagnostics are visible. |
+| `destructive-command-summary` | Readable summary for a destructive command | `jester summary --kind command "git reset --hard"` | A compact report shows the block verdict, rule hit, and next tuning commands. |
+| `blocked-command-review` | Full blocked command review | `jester command "git reset --hard"` | The full command review blocks the risky operation and explains the safer check. |
+
+Run the checker from the repo root:
+
+```powershell
+npm run reports:check
+```
+
+After publishing, verify the same gallery against the public package:
+
+```powershell
+npm run reports:check -- --package memento-mori-jester@latest
+```
+
+When turning a real issue into a gallery entry, keep the example minimal and redacted. If the report needs private context, route it through [SECURITY.md](../../SECURITY.md) or keep it out of the public repo.

package/examples/reports/report-gallery.json

@@ -0,0 +1,47 @@
+[
+  {
+    "id": "fresh-install-doctor",
+    "title": "Fresh install health check",
+    "scenario": "A new repo wants to confirm the package, Node runtime, MCP server file, review engine, config discovery, hooks, and generated workflow checks are visible.",
+    "command": "jester doctor",
+    "args": ["doctor"],
+    "expected": {
+      "includes": [
+        "Memento Mori Jester doctor",
+        "PASS package-version",
+        "PASS review-engine: Dangerous git command is blocked.",
+        "The fool is fit for court."
+      ]
+    }
+  },
+  {
+    "id": "destructive-command-summary",
+    "title": "Readable summary for a destructive command",
+    "scenario": "A team wants a compact CI-friendly report showing which rule fired before enabling stricter workflow failure behavior.",
+    "command": "jester summary --kind command \"git reset --hard\"",
+    "args": ["summary", "--kind", "command", "git reset --hard"],
+    "expected": {
+      "includes": [
+        "Memento Mori Jester summary",
+        "Verdict: BLOCK",
+        "destructive-git-history",
+        "Suggested next:"
+      ]
+    }
+  },
+  {
+    "id": "blocked-command-review",
+    "title": "Full blocked command review",
+    "scenario": "A developer or agent is about to run a destructive git command and needs the full review text before proceeding.",
+    "command": "jester command \"git reset --hard\"",
+    "args": ["command", "git reset --hard"],
+    "expected": {
+      "includes": [
+        "Jester verdict: BLOCK",
+        "Destructive git operation",
+        "git reset --hard",
+        "Inspect `git status`"
+      ]
+    }
+  }
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memento-mori-jester",
-  "version": "0.1.87",
+  "version": "0.1.88",
   "description": "A local court-jester sidecar for AI coding agents: review plans, commands, diffs, and final claims before they get too pleased with themselves.",
   "type": "module",
   "repository": {
@@ -40,7 +40,7 @@
     "build": "tsc -p tsconfig.json",
     "start": "node dist/server.js",
     "start:mcp": "node dist/server.js",
-    "test": "npm run build && node scripts/run-tests.mjs && npm run fixtures:check && npm run fixtures:report && npm run framework:tuning:check && npm run framework:tuning:doctor && npm run ci:adoption:check && npm run consumer:quickstart:check && npm run promo:check && npm run site:check && npm run production:check",
+    "test": "npm run build && node scripts/run-tests.mjs && npm run fixtures:check && npm run fixtures:report && npm run framework:tuning:check && npm run framework:tuning:doctor && npm run ci:adoption:check && npm run consumer:quickstart:check && npm run reports:check && npm run promo:check && npm run site:check && npm run production:check",
     "doctor": "node dist/cli.js doctor",
     "demo:svg": "node scripts/render-demo-svg.mjs",
     "demo:svg:check": "node scripts/render-demo-svg.mjs --check",
@@ -50,6 +50,7 @@
     "framework:tuning:doctor": "node scripts/doctor-framework-tuning.mjs",
     "ci:adoption:check": "node scripts/check-ci-adoption.mjs",
     "consumer:quickstart:check": "node scripts/check-consumer-quickstart.mjs",
+    "reports:check": "node scripts/check-report-gallery.mjs",
     "promo:card": "node scripts/render-social-card.mjs",
     "promo:card:check": "node scripts/render-social-card.mjs --check",
     "promo:check": "node scripts/check-promo-freshness.mjs",

package/scripts/check-production-readiness.mjs

@@ -72,6 +72,7 @@ for (const path of [
   "scripts/doctor-framework-tuning.mjs",
   "scripts/check-ci-adoption.mjs",
   "scripts/check-consumer-quickstart.mjs",
+  "scripts/check-report-gallery.mjs",
   "scripts/check-fixtures.mjs",
   "scripts/report-fixtures.mjs",
   ".github/ISSUE_TEMPLATE/bug_report.yml",
@@ -87,6 +88,8 @@ for (const path of [
   "examples/ci/adoption-smoke.yml",
   "examples/consumer-quickstart/README.md",
   "examples/consumer-quickstart/package.json",
+  "examples/reports/README.md",
+  "examples/reports/report-gallery.json",
   "examples/presets/README.md",
   "examples/tuning/README.md",
   "examples/tuning/framework-tuning-cookbook.json",
@@ -113,6 +116,7 @@ requireText("README.md", /FRAMEWORK_TUNING\.md/, "framework tuning guide link");
 requireText("README.md", /examples\/tuning/, "framework tuning cookbook link");
 requireText("README.md", /adoption-smoke\.yml/, "adoption smoke CI link");
 requireText("README.md", /consumer-quickstart/, "consumer quickstart smoke link");
+requireText("README.md", /examples\/reports/, "report gallery link");
 requireText("README.md", /License: PolyForm Noncommercial/, "the noncommercial license badge");
 requireText("docs/PRODUCTION_READINESS.md", /npm package/i, "npm package readiness");
 requireText("docs/PRODUCTION_READINESS.md", /GitHub Action/i, "GitHub Action readiness");
@@ -130,6 +134,7 @@ requireText("docs/PRODUCTION_READINESS.md", /framework:tuning:check/, "framework
 requireText("docs/PRODUCTION_READINESS.md", /framework:tuning:doctor/, "framework tuning cookbook doctor readiness");
 requireText("docs/PRODUCTION_READINESS.md", /adoption-smoke\.yml/, "adoption smoke CI readiness");
 requireText("docs/PRODUCTION_READINESS.md", /consumer:quickstart:check/, "consumer quickstart smoke readiness");
+requireText("docs/PRODUCTION_READINESS.md", /reports:check/, "report gallery readiness");
 requireText("docs/PRODUCTION_READINESS.md", /quiet-pass/, "quiet-pass fixture readiness");
 requireText("docs/CLI.md", /jester doctor --json/, "doctor JSON CLI docs");
 requireText("docs/CLI.md", /quiet-pass fixture/, "quiet-pass fixture CLI docs");
@@ -164,6 +169,11 @@ requireText("examples/ci/adoption-smoke.yml", /framework:tuning:doctor/, "adopti
 requireText("examples/consumer-quickstart/README.md", /npm run consumer:quickstart:check/, "consumer quickstart check command");
 requireText("examples/consumer-quickstart/package.json", /jester:summary/, "consumer quickstart summary script");
 requireText("examples/consumer-quickstart/package.json", /framework:tuning:doctor/, "consumer quickstart tuning doctor script");
+requireText("examples/reports/README.md", /report-gallery\.json/, "report gallery JSON link");
+requireText("examples/reports/README.md", /npm run reports:check/, "report gallery check command");
+requireText("examples/reports/report-gallery.json", /fresh-install-doctor/, "fresh install doctor report");
+requireText("examples/reports/report-gallery.json", /destructive-command-summary/, "destructive command summary report");
+requireText("examples/reports/report-gallery.json", /blocked-command-review/, "blocked command review report");
 requireText("examples/tuning/README.md", /framework-tuning-cookbook\.json/, "framework tuning cookbook JSON link");
 requireText("examples/tuning/README.md", /framework:tuning:doctor/, "framework tuning doctor guidance");
 requireText("examples/tuning/README.md", /jester tune <rule-id> --json|jester tune [a-z0-9-]+ --json/, "framework tuning command guidance");
@@ -191,12 +201,16 @@ requireText("scripts/check-ci-adoption.mjs", /framework:tuning:doctor/, "adoptio
 requireText("scripts/check-consumer-quickstart.mjs", /consumer-quickstart/, "consumer quickstart checker target");
 requireText("scripts/check-consumer-quickstart.mjs", /memento-mori-jester@latest/, "consumer quickstart registry verification option");
 requireText("scripts/check-consumer-quickstart.mjs", /framework:tuning:doctor/, "consumer quickstart tuning doctor guard");
+requireText("scripts/check-report-gallery.mjs", /report-gallery\.json/, "report gallery checker target");
+requireText("scripts/check-report-gallery.mjs", /memento-mori-jester@latest/, "report gallery registry verification option");
+requireText("scripts/check-report-gallery.mjs", /destructive-command-summary/, "report gallery summary guard");
 requireText("package.json", /"fixtures:check": "node scripts\/check-fixtures\.mjs"/, "fixture authoring check script");
 requireText("package.json", /"fixtures:report": "node scripts\/report-fixtures\.mjs"/, "fixture coverage report script");
 requireText("package.json", /"framework:tuning:check": "node scripts\/check-framework-tuning\.mjs"/, "framework tuning cookbook check script");
 requireText("package.json", /"framework:tuning:doctor": "node scripts\/doctor-framework-tuning\.mjs"/, "framework tuning cookbook doctor script");
 requireText("package.json", /"ci:adoption:check": "node scripts\/check-ci-adoption\.mjs"/, "CI adoption check script");
 requireText("package.json", /"consumer:quickstart:check": "node scripts\/check-consumer-quickstart\.mjs"/, "consumer quickstart check script");
+requireText("package.json", /"reports:check": "node scripts\/check-report-gallery\.mjs"/, "report gallery check script");
 requireText("package.json", /"promo:card": "node scripts\/render-social-card\.mjs"/, "social card render script");
 requireText("package.json", /"promo:card:check": "node scripts\/render-social-card\.mjs --check"/, "social card stale check script");
 requireText("package.json", /"promo:check": "node scripts\/check-promo-freshness\.mjs"/, "promo freshness check script");
@@ -207,6 +221,7 @@ requireText("package.json", /npm run framework:tuning:check/, "framework tuning
 requireText("package.json", /npm run framework:tuning:doctor/, "framework tuning cookbook doctor in npm test");
 requireText("package.json", /npm run ci:adoption:check/, "CI adoption check in npm test");
 requireText("package.json", /npm run consumer:quickstart:check/, "consumer quickstart check in npm test");
+requireText("package.json", /npm run reports:check/, "report gallery check in npm test");
 requireText("package.json", /npm run promo:check/, "promo freshness check in npm test");
 requireText("package.json", /npm run site:check/, "site check in npm test");
 requireText("scripts/check-promo-freshness.mjs", /--require-package-version/, "optional strict package-version promo check");

package/scripts/check-report-gallery.mjs

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const root = join(scriptDir, "..");
+const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+const npmExecPath = process.env.npm_execpath;
+const galleryPath = join(root, "examples", "reports", "report-gallery.json");
+const readmePath = join(root, "examples", "reports", "README.md");
+const args = process.argv.slice(2);
+
+process.on("uncaughtException", (error) => {
+  console.error("Report gallery check failed:");
+  console.error(`- ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});
+
+let requestedPackageSpec = null;
+let keepTemp = false;
+
+for (let index = 0; index < args.length; index += 1) {
+  const arg = args[index];
+  if (arg === "--package" || arg === "--package-spec") {
+    requestedPackageSpec = args[index + 1];
+    index += 1;
+  } else if (arg === "--registry-latest") {
+    requestedPackageSpec = "memento-mori-jester@latest";
+  } else if (arg === "--keep-temp") {
+    keepTemp = true;
+  } else {
+    fail(`Unknown option: ${arg}`);
+  }
+}
+
+if (requestedPackageSpec === "") {
+  fail("--package requires a non-empty npm package spec.");
+}
+
+const unsafeContentPatterns = [
+  { name: "private key block", pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+  { name: "OpenAI-looking secret key", pattern: /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}\b/ },
+  { name: "Anthropic-looking secret key", pattern: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/ },
+  { name: "GitHub-looking token", pattern: /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/ },
+  { name: "AWS access key id", pattern: /\bAKIA[0-9A-Z]{16}\b/ },
+  { name: "Slack-looking token", pattern: /\bxox[baprs]-[A-Za-z0-9-]{20,}\b/ },
+  { name: "absolute Unix home path", pattern: /(?:^|[\s"'`])\/(?:Users|home)\/[A-Za-z0-9._-]+/ },
+  { name: "absolute Windows user path", pattern: /[A-Za-z]:\\Users\\[A-Za-z0-9._-]+\\/ }
+];
+
+const gallery = readGallery();
+checkReadme(gallery);
+
+const tempRoot = mkdtempSync(join(tmpdir(), "jester-report-gallery-"));
+let packageSpec = requestedPackageSpec;
+const packageLabel = requestedPackageSpec ?? "local packed package";
+
+try {
+  if (!packageSpec) {
+    packageSpec = packLocalPackage(tempRoot);
+  }
+} catch (error) {
+  rmSync(tempRoot, { recursive: true, force: true });
+  throw error;
+}
+
+try {
+  const consumerDir = join(tempRoot, "consumer-project");
+  prepareConsumerProject(consumerDir, packageSpec);
+
+  const results = [];
+  for (const report of gallery) {
+    const output = runNpm(["exec", "--", "jester", ...report.args], { cwd: consumerDir });
+    for (const expected of report.expected.includes) {
+      if (!output.includes(expected)) {
+        fail(`${report.id} output should include ${expected}. Output was:\n${output}`);
+      }
+    }
+    results.push(report.id);
+  }
+
+  console.log("Report gallery check");
+  console.log(`PASS installed ${packageLabel}`);
+  for (const id of results) {
+    console.log(`PASS ${id}`);
+  }
+} finally {
+  if (keepTemp) {
+    console.log(`Kept temp project at ${tempRoot}`);
+  } else {
+    rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+function readGallery() {
+  if (!existsSync(galleryPath)) {
+    fail("examples/reports/report-gallery.json is missing.");
+  }
+
+  if (!existsSync(readmePath)) {
+    fail("examples/reports/README.md is missing.");
+  }
+
+  const galleryRaw = readFileSync(galleryPath, "utf8");
+  const readme = readFileSync(readmePath, "utf8");
+
+  for (const [path, content] of [
+    ["examples/reports/report-gallery.json", galleryRaw],
+    ["examples/reports/README.md", readme]
+  ]) {
+    for (const unsafe of unsafeContentPatterns) {
+      if (unsafe.pattern.test(content)) {
+        fail(`${path} appears to contain ${unsafe.name}; report examples should stay public and redacted.`);
+      }
+    }
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(galleryRaw);
+  } catch (error) {
+    fail(`examples/reports/report-gallery.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  if (!Array.isArray(parsed) || parsed.length !== 3) {
+    fail("examples/reports/report-gallery.json should contain exactly three report examples.");
+  }
+
+  const expectedIds = ["fresh-install-doctor", "destructive-command-summary", "blocked-command-review"];
+  const seenIds = new Set();
+
+  for (const [index, report] of parsed.entries()) {
+    const expectedId = expectedIds[index];
+    if (report?.id !== expectedId) {
+      fail(`Report ${index + 1} should have id ${expectedId}.`);
+    }
+
+    if (seenIds.has(report.id)) {
+      fail(`Duplicate report id: ${report.id}.`);
+    }
+    seenIds.add(report.id);
+
+    for (const field of ["title", "scenario", "command"]) {
+      if (typeof report[field] !== "string" || report[field].trim().length < 10) {
+        fail(`${report.id}.${field} should be a useful string.`);
+      }
+    }
+
+    if (!Array.isArray(report.args) || report.args.length === 0 || report.args.some((arg) => typeof arg !== "string")) {
+      fail(`${report.id}.args should be a non-empty string array.`);
+    }
+
+    if (!Array.isArray(report.expected?.includes) || report.expected.includes.length < 3) {
+      fail(`${report.id}.expected.includes should contain at least three stable output fragments.`);
+    }
+  }
+
+  return parsed;
+}
+
+function checkReadme(gallery) {
+  const readme = readFileSync(readmePath, "utf8");
+
+  for (const report of gallery) {
+    for (const expected of [report.id, report.command]) {
+      if (!readme.includes(expected)) {
+        fail(`examples/reports/README.md should include ${expected}.`);
+      }
+    }
+  }
+
+  for (const expected of [
+    "npm run reports:check",
+    "memento-mori-jester@latest",
+    "SECURITY.md"
+  ]) {
+    if (!readme.includes(expected)) {
+      fail(`examples/reports/README.md should include ${expected}.`);
+    }
+  }
+}
+
+function packLocalPackage(destination) {
+  const cliPath = join(root, "dist", "cli.js");
+  if (!existsSync(cliPath)) {
+    fail(`${cliPath} is missing. Run npm run build before npm run reports:check.`);
+  }
+
+  const output = runNpm(["pack", "--ignore-scripts", "--pack-destination", destination, "--silent"], { cwd: root });
+  const filename = output.trim().split(/\r?\n/).filter(Boolean).at(-1);
+  if (!filename) {
+    fail("npm pack did not return a tarball filename.");
+  }
+
+  return isAbsolute(filename) ? filename : resolve(destination, filename);
+}
+
+function prepareConsumerProject(consumerDir, spec) {
+  rmSync(consumerDir, { recursive: true, force: true });
+  mkdirSync(consumerDir, { recursive: true });
+  writeFileSync(
+    join(consumerDir, "package.json"),
+    `${JSON.stringify({ name: "jester-report-gallery-consumer", version: "0.0.0", private: true }, null, 2)}\n`
+  );
+  runNpm(["install", "--save-dev", spec, "--ignore-scripts", "--no-audit", "--no-fund"], { cwd: consumerDir });
+}
+
+function runNpm(commandArgs, options = {}) {
+  if (npmExecPath) {
+    return run(process.execPath, [npmExecPath, ...commandArgs], options);
+  }
+
+  return run(npmCommand, commandArgs, options);
+}
+
+function run(command, commandArgs, options = {}) {
+  const result = spawnSync(command, commandArgs, {
+    cwd: options.cwd ?? root,
+    encoding: "utf8",
+    maxBuffer: 20 * 1024 * 1024,
+    env: {
+      ...process.env,
+      npm_config_audit: "false",
+      npm_config_fund: "false"
+    }
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    const detail = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+    fail(`${command} ${commandArgs.join(" ")} failed${detail ? `:\n${detail}` : "."}`);
+  }
+
+  return result.stdout;
+}
+
+function fail(message) {
+  throw new Error(message);
+}