memento-mori-jester 0.1.46 → 0.1.48

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to Memento Mori Jester are tracked here.
 
 ## Unreleased
 
+## 0.1.48
+
+- Added `docs/PRODUCTION_READINESS.md` to define the current production-grade bar across npm packaging, GitHub Action usage, MCP setup, git hooks, docs, release automation, and support.
+- Added `npm run production:check`, a static readiness guard for version/release-note coverage, package metadata, public package files, workflow runtime expectations, and onboarding docs.
+- Wired the production readiness check into `npm test` so CI catches readiness drift alongside the existing build, unit tests, and package dry run.
+
+## 0.1.47
+
+- Reworked the README Start Here section into a clearer four-step path: try without writing files, add a recommended preset, connect an agent, then add hooks or CI.
+- Updated Getting Started to mirror the same onboarding order and mention playground sample buttons.
+- Kept this as a docs-only onboarding release; no CLI, MCP, config, review, playground runtime, or release workflow behavior changed.
+
 ## 0.1.46
 
 - Added one-click sample buttons to the local playground for command, plan, diff, and final-answer reviews.

package/README.md

@@ -16,7 +16,7 @@ See the full [demo transcript](docs/DEMO.md).
 
 ## Start Here
 
-No install needed:
+### 1. Try It Without Writing Files
 
 ```powershell
 npx -y memento-mori-jester@latest start
@@ -25,11 +25,13 @@ npx -y memento-mori-jester@latest command "git reset --hard"
 npx -y memento-mori-jester@latest playground
 ```
 
-Add it to a project:
+`start` prints the guided checklist. `playground` opens the local browser UI with sample buttons for commands, plans, diffs, and final answers.
+
+### 2. Add It To A Project
 
 ```powershell
 npx -y memento-mori-jester@latest config recommend
-npx -y memento-mori-jester@latest bootstrap --preset node
+npx -y memento-mori-jester@latest bootstrap --preset <recommended-preset>
 ```
 
 That writes:
@@ -38,6 +40,25 @@ That writes:
 - `memento-mori.mcp.json`
 - `MEMENTO_MORI.md`
 
+Common presets are `node`, `python`, `web`, `api`, `infra`, `ai`, and `security`.
+
+### 3. Connect Your Agent
+
+```powershell
+npx -y memento-mori-jester@latest setup
+npx -y memento-mori-jester@latest setup --agent codex
+npx -y memento-mori-jester@latest setup --agent claude
+```
+
+Use the generated MCP snippet and agent instruction in Codex, Claude Code, or another MCP-capable client.
+
+### 4. Add Hooks Or CI When Ready
+
+```powershell
+npx -y memento-mori-jester@latest bootstrap --preset <recommended-preset> --hook pre-commit
+npx -y memento-mori-jester@latest bootstrap --preset <recommended-preset> --hook pre-commit --hook pre-push
+```
+
 Add it to GitHub code scanning:
 
 ```powershell
@@ -474,6 +495,7 @@ Release checklist:
 
 ```powershell
 npm.cmd test
+npm.cmd run production:check
 npm.cmd run pack:dry
 git tag -a v0.1.x -m "Memento Mori Jester v0.1.x"
 git push origin main
@@ -482,6 +504,8 @@ git push origin v0.1.x
 
 Pushing a `v*` tag creates the GitHub Release and publishes the matching package version to npm through trusted publishing.
 
+The production readiness bar is documented in [docs/PRODUCTION_READINESS.md](docs/PRODUCTION_READINESS.md).
+
 GitHub: <https://github.com/Martin123132/Memento-Mori>
 
 See [docs/RELEASE.md](docs/RELEASE.md).

package/ROADMAP.md

@@ -6,6 +6,8 @@ Memento Mori Jester is usable today as a CLI, MCP server, GitHub Action, and git
 
 ## Recently Shipped
 
+- Production readiness checklist and static guard in v0.1.48 for package, workflow, docs, release, and support drift.
+- README onboarding polish in v0.1.47 around the shortest path from `npx` to playground, agent setup, hooks, and CI.
 - Playground sample buttons in v0.1.46 for trying command, plan, diff, and final-answer reviews from the first screen.
 - Fixture curation pass in v0.1.45 that moved all built-in and structural rule evidence to medium-or-better confidence.
 - Additional precision pass for fixture-driven tuning signals (scoped to high-signal rule families first).
@@ -35,7 +37,7 @@ Memento Mori Jester is usable today as a CLI, MCP server, GitHub Action, and git
 
 ## Product Ideas
 
-- Polish README onboarding around the shortest path from `npx` to playground, agent setup, and hooks.
+- Add `doctor --json` and support templates so diagnostics and bug reports are easier to collect.
 
 ## Quality And Safety
 

package/docs/GETTING_STARTED.md

@@ -2,7 +2,7 @@
 
 This is the shortest path for a normal project.
 
-## 1. Check It Runs
+## 1. Try It Without Writing Files
 
 For a guided checklist:
 
@@ -18,8 +18,6 @@ npx -y memento-mori-jester@latest doctor
 
 You should see four `PASS` lines.
 
-## 2. See The Point
-
 ```powershell
 npx -y memento-mori-jester@latest command "git reset --hard"
 ```
@@ -38,19 +36,21 @@ For the local browser version:
 npx -y memento-mori-jester@latest playground
 ```
 
+The playground starts on `127.0.0.1` and includes sample buttons for command, plan, diff, and final-answer reviews.
+
 If a rule feels noisy, ask for tuning advice before disabling it:
 
 ```powershell
 npx -y memento-mori-jester@latest tune risky-domain
 ```
 
-## 3. Add It To A Project
+## 2. Add It To A Project
 
 Run this from the folder of the project you want protected:
 
 ```powershell
 npx -y memento-mori-jester@latest config recommend
-npx -y memento-mori-jester@latest bootstrap --preset node
+npx -y memento-mori-jester@latest bootstrap --preset <recommended-preset>
 ```
 
 Use `--preset ai` for LLM, MCP, and agent apps, `--preset api` for backend APIs, `--preset web` for frontend/browser apps, `--preset infra` for deployment or cloud infrastructure repos, or `--preset security` for a stricter general policy.
@@ -65,32 +65,34 @@ That creates:
 
 Existing files are kept. Add `--force` only when you want to overwrite the starter files.
 
-## 4. Optional Git Hooks
+## 3. Agent Instruction
 
-To make git call the Jester before commits:
+For exact Codex, Claude Code, or generic MCP snippets:
 
 ```powershell
-npx -y memento-mori-jester@latest bootstrap --preset node --hook pre-commit
+npx -y memento-mori-jester@latest setup
+npx -y memento-mori-jester@latest setup --agent codex
+npx -y memento-mori-jester@latest setup --agent claude
 ```
 
-To also check before pushing:
+Put this in your agent rules or custom instructions:
 
-```powershell
-npx -y memento-mori-jester@latest bootstrap --preset node --hook pre-commit --hook pre-push
+```text
+Before risky commands, final answers, commits, or large edits, call the Memento Mori Jester. Treat BLOCK as requiring a changed plan, and CAUTION as requiring at least one concrete verification step.
 ```
 
-## 5. Agent Instruction
+## 4. Optional Git Hooks
 
-For exact Codex, Claude Code, or generic MCP snippets:
+To make git call the Jester before commits:
 
 ```powershell
-npx -y memento-mori-jester@latest setup
+npx -y memento-mori-jester@latest bootstrap --preset <recommended-preset> --hook pre-commit
 ```
 
-Put this in your agent rules or custom instructions:
+To also check before pushing:
 
-```text
-Before risky commands, final answers, commits, or large edits, call the Memento Mori Jester. Treat BLOCK as requiring a changed plan, and CAUTION as requiring at least one concrete verification step.
+```powershell
+npx -y memento-mori-jester@latest bootstrap --preset <recommended-preset> --hook pre-commit --hook pre-push
 ```
 
 ## What To Share With Someone Else

package/docs/PRODUCTION_READINESS.md

@@ -0,0 +1,68 @@
+# Production Readiness
+
+This checklist defines what "production grade" means for Memento Mori Jester right now. It is intentionally practical: the project is a local CLI, MCP server, GitHub Action, and hook helper, so production readiness means users can install it, understand it, wire it in, recover from failures, and verify releases without guesswork.
+
+## Current Bar
+
+- The npm package installs with `npx -y memento-mori-jester@latest` and exposes the CLI plus MCP server binaries.
+- The default path is local and deterministic: reviews run on user-provided text, diffs, commands, plans, and final answers without sending project code to a hosted API.
+- GitHub Releases and npm publishing are automated from annotated `v*` tags through GitHub Actions trusted publishing.
+- CI runs tests and a package dry run on every push to `main` and pull request.
+- The local playground, GitHub Action, MCP setup snippets, preset examples, fixtures, and release notes ship in the npm package.
+
+## npm Package
+
+- `package.json` includes repository, homepage, bugs, binaries, exports, public package files, and public publish access.
+- `package-lock.json` version matches `package.json`.
+- `npm run pack:dry` confirms the package includes `dist`, `docs`, `examples`, `scripts`, `README.md`, `CHANGELOG.md`, `ROADMAP.md`, and `LICENSE`.
+- `prepublishOnly` runs tests and a package dry run for local publish attempts.
+
+## GitHub Action
+
+- `action.yml` builds with Node 24 through `actions/setup-node@v6`.
+- Action inputs cover `fail-on`, `subject`, `config`, `no-config`, `format`, `output-file`, and `summary`.
+- SARIF output and GitHub step summaries remain separate so users can enable readable summaries without new GitHub write permissions.
+- Example workflows in `examples/` and `examples/ci/` stay aligned with the action shape.
+
+## MCP And Agent Setup
+
+- `jester setup`, `jester mcp-config`, and `jester bootstrap` provide copy-paste setup for Codex, Claude Code, and generic MCP clients.
+- `memento-mori-jester-mcp` is published as a package binary.
+- `jester doctor` verifies the MCP server file exists and that the review engine blocks a known destructive command.
+
+## Git Hooks
+
+- `jester bootstrap --hook pre-commit` and `--hook pre-push` install managed hooks only when requested.
+- Hooks use the same deterministic local review engine as CLI and MCP calls.
+- `jester hook-status` lets users inspect managed hook state.
+
+## Documentation
+
+- `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.
+- Every public release has matching `CHANGELOG.md` notes and `docs/RELEASE_NOTES_vX.Y.Z.md`.
+
+## Support And Recovery
+
+- Package metadata points bug reports at the GitHub issues page.
+- `jester doctor`, `jester config validate`, and `jester rules` are the first troubleshooting commands.
+- `jester tune`, `jester tune coverage`, and the fixture suite give maintainers a way to inspect noisy rules before changing defaults.
+- npm publish has a manual workflow fallback, but the normal release path is tag-driven trusted publishing.
+
+## Static Guard
+
+`npm run production:check` validates the production-readiness contract:
+
+- current version release notes and changelog section exist,
+- package metadata and public package files are present,
+- CI, release, publish, and composite action workflows use the expected runtime and steps,
+- onboarding docs mention the important adoption paths,
+- production readiness documentation covers package, GitHub Action, MCP, git hooks, docs, and support.
+
+`npm test` runs this check after the TypeScript build and unit tests.
+
+## Known Next Gaps
+
+- Add `SECURITY.md` and issue templates for clearer support intake.
+- Add `doctor --json` for easier automated diagnostics.
+- Continue expanding pass-case fixtures from real-world usage so false-positive tuning remains evidence-based.

package/docs/RELEASE.md

@@ -7,11 +7,12 @@ This project publishes GitHub Releases and npm packages from `v*` tags.
 ```powershell
 npm.cmd version 0.1.x --no-git-tag-version
 npm.cmd test
+npm.cmd run production:check
 npm.cmd run pack:dry
 git diff --check
 ```
 
-Move the current changelog bullets into a matching version section and add `docs/RELEASE_NOTES_v0.1.x.md` before committing.
+Move the current changelog bullets into a matching version section and add `docs/RELEASE_NOTES_v0.1.x.md` before committing. Keep `docs/PRODUCTION_READINESS.md` and `npm run production:check` aligned when package, workflow, docs, or support expectations change.
 
 ## 2. Tag And Push
 

package/docs/RELEASE_NOTES_v0.1.47.md

@@ -0,0 +1,25 @@
+# v0.1.47 Release Notes
+
+This is a docs-only onboarding release. It makes the first README path clearer without changing CLI behavior, review behavior, MCP tools, config, playground runtime, GitHub Actions, or release automation.
+
+## Changed
+
+- Reworked README Start Here into four steps:
+  - try Jester without writing files,
+  - add it to a project with the recommended preset,
+  - connect Codex, Claude Code, or a generic MCP client,
+  - add hooks or GitHub code scanning when ready.
+- Updated Getting Started to follow the same order and mention the playground sample buttons.
+- Updated the roadmap with the shipped README polish and the next demo/onboarding idea.
+
+## Release Validation
+
+```powershell
+npm.cmd test
+npm.cmd run demo:svg:check
+npm.cmd run pack:dry
+git diff --check
+node .\dist\cli.js start
+node .\dist\cli.js config recommend
+git diff | node .\dist\cli.js diff --fail-on block --subject "v0.1.47 README onboarding polish"
+```

package/docs/RELEASE_NOTES_v0.1.48.md

@@ -0,0 +1,31 @@
+# v0.1.48 Release Notes
+
+This release adds a production-readiness bar and a static guard to keep the public package, workflows, docs, and release metadata aligned as the project grows.
+
+## Added
+
+- `docs/PRODUCTION_READINESS.md`, covering:
+  - npm package expectations,
+  - GitHub Action behavior,
+  - MCP and agent setup,
+  - git hooks,
+  - documentation and release metadata,
+  - support and recovery paths.
+- `npm run production:check`, which validates version/release-note coverage, package metadata, public package files, workflow runtime expectations, action summary support, and onboarding docs.
+
+## Changed
+
+- `npm test` now runs the production readiness check after the TypeScript build and unit suite.
+- README and release docs now mention the production readiness check.
+
+## Release Validation
+
+```powershell
+npm.cmd test
+npm.cmd run production:check
+npm.cmd run demo:svg:check
+npm.cmd run pack:dry
+git diff --check
+node .\dist\cli.js doctor
+git diff | node .\dist\cli.js diff --fail-on block --subject "v0.1.48 production readiness audit"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memento-mori-jester",
-  "version": "0.1.46",
+  "version": "0.1.48",
   "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": {
@@ -39,10 +39,11 @@
     "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",
+    "test": "npm run build && node scripts/run-tests.mjs && 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",
+    "production:check": "node scripts/check-production-readiness.mjs",
     "pack:dry": "npm pack --dry-run",
     "prepare": "npm run build",
     "prepublishOnly": "npm test && npm run pack:dry"

package/scripts/check-production-readiness.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const root = process.cwd();
+const failures = [];
+
+function read(path) {
+  return readFileSync(join(root, path), "utf8");
+}
+
+function readJson(path) {
+  return JSON.parse(read(path));
+}
+
+function requireFile(path) {
+  if (!existsSync(join(root, path))) {
+    failures.push(`${path} is missing.`);
+  }
+}
+
+function requireText(path, pattern, description) {
+  const content = read(path);
+  if (!pattern.test(content)) {
+    failures.push(`${path} should include ${description}.`);
+  }
+}
+
+function requirePackageFile(packageJson, value) {
+  if (!Array.isArray(packageJson.files) || !packageJson.files.includes(value)) {
+    failures.push(`package.json files should include ${value}.`);
+  }
+}
+
+const packageJson = readJson("package.json");
+const packageLock = readJson("package-lock.json");
+const version = packageJson.version;
+const tag = `v${version}`;
+
+if (!/^\d+\.\d+\.\d+$/.test(version)) {
+  failures.push(`package.json version should be plain semver. Saw ${version}.`);
+}
+
+if (packageLock.version !== version || packageLock.packages?.[""]?.version !== version) {
+  failures.push("package-lock.json version should match package.json.");
+}
+
+for (const path of [
+  "README.md",
+  "CHANGELOG.md",
+  "ROADMAP.md",
+  "LICENSE",
+  "docs/RELEASE.md",
+  "docs/TRUSTED_PUBLISHING.md",
+  "docs/PRODUCTION_READINESS.md",
+  `docs/RELEASE_NOTES_${tag}.md`,
+  "action.yml",
+  ".github/workflows/ci.yml",
+  ".github/workflows/npm-publish.yml",
+  ".github/workflows/release.yml",
+  "examples/github-action.yml",
+  "examples/github-code-scanning.yml",
+  "examples/ci/README.md",
+  "examples/presets/README.md",
+  "examples/fixtures/preset-review-cases.json"
+]) {
+  requireFile(path);
+}
+
+requireText("CHANGELOG.md", new RegExp(`## ${version.replaceAll(".", "\\.")}`), `a ${version} section`);
+requireText(`docs/RELEASE_NOTES_${tag}.md`, /## Release Validation/, "release validation commands");
+requireText("README.md", /## Start Here/, "Start Here onboarding");
+requireText("README.md", /config recommend/, "preset recommendation onboarding");
+requireText("README.md", /setup --agent codex/, "Codex setup onboarding");
+requireText("README.md", /github-action --write/, "GitHub Action onboarding");
+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");
+requireText("docs/PRODUCTION_READINESS.md", /MCP/i, "MCP readiness");
+requireText("docs/PRODUCTION_READINESS.md", /git hooks/i, "git hook readiness");
+requireText("docs/PRODUCTION_READINESS.md", /support/i, "support readiness");
+
+for (const publicFile of ["dist", "docs", "examples", "scripts", "CHANGELOG.md", "LICENSE", "README.md", "ROADMAP.md"]) {
+  requirePackageFile(packageJson, publicFile);
+}
+
+for (const binName of ["jester", "memento-mori-jester", "memento-mori-jester-mcp"]) {
+  if (!packageJson.bin?.[binName]) {
+    failures.push(`package.json bin should include ${binName}.`);
+  }
+}
+
+if (packageJson.license !== "SEE LICENSE IN LICENSE") {
+  failures.push("package.json license should point to LICENSE.");
+}
+
+if (packageJson.publishConfig?.access !== "public") {
+  failures.push("package.json publishConfig.access should be public.");
+}
+
+requireText(".github/workflows/ci.yml", /actions\/checkout@v6/, "checkout@v6");
+requireText(".github/workflows/ci.yml", /actions\/setup-node@v6/, "setup-node@v6");
+requireText(".github/workflows/ci.yml", /node-version:\s*24/, "Node 24");
+requireText(".github/workflows/ci.yml", /npm test/, "npm test");
+requireText(".github/workflows/ci.yml", /npm run pack:dry/, "package dry run");
+
+requireText(".github/workflows/npm-publish.yml", /tags:\s*\n\s*-\s*"v\*"/, "tag-triggered publishing");
+requireText(".github/workflows/npm-publish.yml", /workflow_dispatch/, "manual publish fallback");
+requireText(".github/workflows/npm-publish.yml", /id-token:\s*write/, "trusted publishing id-token permission");
+requireText(".github/workflows/npm-publish.yml", /Verify tag matches package version/, "tag/package version guard");
+requireText(".github/workflows/npm-publish.yml", /npm run pack:dry/, "package dry run before publish");
+requireText(".github/workflows/npm-publish.yml", /npm publish/, "npm publish step");
+
+requireText(".github/workflows/release.yml", /tags:\s*\n\s*-\s*"v\*"/, "tag-triggered GitHub Releases");
+requireText(".github/workflows/release.yml", /docs\/RELEASE_NOTES_\$\{TAG\}\.md/, "release notes lookup");
+requireText(".github/workflows/release.yml", /gh release create/, "GitHub Release creation");
+
+requireText("action.yml", /summary:/, "summary input");
+requireText("action.yml", /GITHUB_STEP_SUMMARY/, "GitHub step summary output");
+requireText("action.yml", /actions\/setup-node@v6/, "setup-node@v6");
+requireText("action.yml", /node-version:\s*24/, "Node 24");
+
+if (failures.length > 0) {
+  console.error("Production readiness check failed:");
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log(`Production readiness check passed for ${tag}.`);