memento-mori-jester 0.1.73 → 0.1.75

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to Memento Mori Jester are tracked here.
 
 ## Unreleased
 
+## 0.1.75
+
+- Added `npm run fixtures:report -- --markdown` for paste-ready fixture coverage snapshots.
+- Added Markdown tables for totals, counts, rule-family slices, preset slices, gaps, quiet-pass coverage, curation-next guidance, and next commands.
+- Updated maintainer docs, release docs, and production-readiness checks for the Markdown fixture report export.
+
+## 0.1.74
+
+- Added six API quiet-pass fixtures, growing the corpus to 208 fixtures.
+- Strengthened safe near-miss evidence for schema parsing, query-builder filters, enabled rate limiting, read-only Prisma migration diffs, signed-webhook docs, and OpenAPI schema docs.
+- Refreshed demo, roadmap, fixture docs, and release notes for the API curation batch.
+
 ## 0.1.73
 
 - Added six web and AI quiet-pass fixtures, growing the corpus to 202 fixtures.

package/README.md

@@ -501,7 +501,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.
+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.
 
 For vulnerabilities, private code exposure, or credential-handling concerns, follow [SECURITY.md](SECURITY.md) instead of opening a public issue with sensitive details.
 

package/ROADMAP.md

@@ -6,6 +6,8 @@ Memento Mori Jester is usable today as a CLI, MCP server, GitHub Action, and git
 
 ## Recently Shipped
 
+- Markdown fixture report export in v0.1.75 for paste-ready coverage snapshots in release notes, GitHub issues, and maintainer updates.
+- API fixture curation in v0.1.74, adding six quiet-pass examples for schema parsing, query-builder filters, enabled rate limiting, read-only Prisma migration diffs, signed-webhook docs, and OpenAPI schema docs.
 - Web/AI fixture curation in v0.1.73, adding six quiet-pass examples for safe text rendering, allowlisted target paths, public analytics IDs, model-check commands, tool allowlist checks, and public model-name config.
 - Python/security fixture curation in v0.1.72, adding six quiet-pass examples for Bandit, pip-audit, coverage/pytest, Trivy, npm audit, and TLS verification-enabled diffs.
 - Node preset fixture curation in v0.1.71, adding six quiet-pass examples for npm audit/outdated/ci, development-mode Node commands, package export maps, and workspace test scripts, plus a repo-local X demo video asset.
@@ -62,9 +64,9 @@ Memento Mori Jester is usable today as a CLI, MCP server, GitHub Action, and git
 
 ## Product Ideas
 
-- Collect real-world reports for the next lowest-count preset slices: API, python, security, then web.
+- Collect real-world reports for the next lowest-count preset slices: python, security, web, then AI.
 - Add more framework-specific false-positive examples from real reports so tuning guidance keeps getting sharper.
-- Add a Markdown export for fixture reports so maintainers can paste coverage snapshots into issues or release notes.
+- Add a promo/share kit with X post copy, still images, and a simple sharing checklist.
 
 ## Quality And Safety
 

package/docs/DEMO.md

@@ -192,8 +192,8 @@ Project config: none loaded
 Fixture tuning evidence:
 Support: limited
 Confidence: medium
-Total fixtures checked: 202
-Weighted fixtures checked: 389.9
+Total fixtures checked: 208
+Weighted fixtures checked: 399.2
 Matching fixtures: 11
 Weighted matches: 23
 Expected-match weight: 18
@@ -202,7 +202,7 @@ Edge-case matches: 0
 Quiet-pass fixtures: 5
 Quiet-pass weight: 3.6
 By kind: command 0, plan 5, diff 5, final 1
-Fixture coverage: 11/202 (5.9% weighted)
+Fixture coverage: 11/208 (5.8% weighted)
 By verdict: pass 0, caution 3, block 8
 Matched fixture samples:
   infra-public-ingress-block: Public ingress should block in low-risk-tolerance infra repos.
@@ -353,9 +353,9 @@ Preset packs:
 
 ## 13. Review Fixtures
 
-The fixture suite in `examples/fixtures/preset-review-cases.json` captures small real-usage examples with expected `pass`, `caution`, or `block` verdicts. It also includes matched-pass examples for low-severity rules, quiet-pass `absentRuleIds` examples that prove noisy rules stay silent for safe near-misses, stack-specific coverage for every built-in preset, quiet-pass boundaries across built-in, structural, custom, and preset/config-derived rules, second firing examples for preset blocked-command rules, second examples for AI/API, framework custom, built-in, and configured sensitive-domain rules, AI tool-dispatch examples with safe allowlist/schema boundaries, and real-world low-count preset examples across node, python, web, infra, AI, and security slices. Recent quiet-pass examples cover typechecks, prebuild scripts, mypy, dataclass parsing, CodeQL, Dependabot limits, form validation, accessibility copy, read-only Kubernetes inspection, Docker disk usage, Terraform linting, public-IP hardening changes, npm audit/outdated/ci, development-mode Node commands, package export maps, workspace test scripts, Bandit, pip-audit, coverage/pytest, Trivy filesystem scans, npm audit, TLS verification-enabled diffs, safe text rendering, allowlisted target paths, public analytics IDs, model-check commands, tool allowlist checks, and public model-name config. These examples are run by `npm test`, so preset tuning changes stay visible.
+The fixture suite in `examples/fixtures/preset-review-cases.json` captures small real-usage examples with expected `pass`, `caution`, or `block` verdicts. It also includes matched-pass examples for low-severity rules, quiet-pass `absentRuleIds` examples that prove noisy rules stay silent for safe near-misses, stack-specific coverage for every built-in preset, quiet-pass boundaries across built-in, structural, custom, and preset/config-derived rules, second firing examples for preset blocked-command rules, second examples for AI/API, framework custom, built-in, and configured sensitive-domain rules, AI tool-dispatch examples with safe allowlist/schema boundaries, and real-world low-count preset examples across node, python, web, infra, AI, and security slices. Recent quiet-pass examples cover typechecks, prebuild scripts, mypy, dataclass parsing, CodeQL, Dependabot limits, form validation, accessibility copy, read-only Kubernetes inspection, Docker disk usage, Terraform linting, public-IP hardening changes, npm audit/outdated/ci, development-mode Node commands, package export maps, workspace test scripts, Bandit, pip-audit, coverage/pytest, Trivy filesystem scans, npm audit, TLS verification-enabled diffs, safe text rendering, allowlisted target paths, public analytics IDs, model-check commands, tool allowlist checks, public model-name config, API schema parsing, query-builder filters, enabled rate limiting, read-only Prisma migration diffs, signed-webhook docs, and OpenAPI schema docs. These examples are run by `npm test`, so preset tuning changes stay visible.
 
-Maintainers can run `npm run fixtures:report` to see coverage by verdict, kind, preset, rule family, and preset slice. The report also includes a `Curation next` section that points at the next useful fixture batch, such as thin rules, feasible pass-case evidence, rule-family gaps, or lower-count presets.
+Maintainers can run `npm run fixtures:report` to see coverage by verdict, kind, preset, rule family, and preset slice. The report also includes a `Curation next` section that points at the next useful fixture batch, such as thin rules, feasible pass-case evidence, rule-family gaps, or lower-count presets. Use `npm run fixtures:report -- --markdown` for a paste-ready version of the same snapshot.
 
 Maintainers can use `docs/MAINTAINER_TRIAGE.md` to turn useful false-positive reports into redacted fixture cases.
 

package/docs/MAINTAINER_TRIAGE.md

@@ -77,13 +77,14 @@ npm.cmd test
 npm.cmd run fixtures:check
 npm.cmd run fixtures:report
 npm.cmd run fixtures:report -- --json
+npm.cmd run fixtures:report -- --markdown
 node .\dist\cli.js tune <rule-id>
 node .\dist\cli.js tune <rule-id> --json
 node .\dist\cli.js tune coverage
 ```
 
 5. Fix any duplicate IDs, missing expected rule metadata, weak descriptions, unsafe content, or duplicate content reported by `fixtures:check`.
-6. Use `fixtures:report` to check whether the change improves feasible pass-case, quiet-pass, preset, kind, rule-family, or verdict coverage. Start with the report's `Curation next` section when deciding which fixture batch to add first.
+6. Use `fixtures:report` to check whether the change improves feasible pass-case, quiet-pass, preset, kind, rule-family, or verdict coverage. Start with the report's `Curation next` section when deciding which fixture batch to add first, and use `fixtures:report -- --markdown` when you need a paste-ready snapshot for an issue or release note.
 7. Check whether support/confidence changed in the expected direction.
 8. If the fixture changes verdict behavior, mention the exact rule impact in `CHANGELOG.md`.
 

package/docs/PRODUCTION_READINESS.md

@@ -53,7 +53,7 @@ This checklist defines what "production grade" means for Memento Mori Jester rig
 - `SECURITY.md` routes vulnerability reports away from public issues and asks for redacted diagnostics.
 - `docs/MAINTAINER_TRIAGE.md` explains how to turn useful false-positive reports into fixture coverage before changing rule logic.
 - `npm run fixtures:check` validates fixture IDs, metadata, unsafe-looking content, duplicate content, and explicit expected/absent rule intent.
-- `npm run fixtures:report` shows fixture coverage by rule, rule family, preset slice, kind, verdict, quiet-pass rule boundaries, and feasible pass-case gaps so maintainers can pick the next fixture target.
+- `npm run fixtures:report` shows fixture coverage by rule, rule family, preset slice, kind, verdict, quiet-pass rule boundaries, and feasible pass-case gaps so maintainers can pick the next fixture target; `npm run fixtures:report -- --markdown` produces a paste-ready maintainer snapshot.
 - npm publish has a manual workflow fallback, but the normal release path is tag-driven trusted publishing.
 
 ## Static Guard

package/docs/RELEASE.md

@@ -11,6 +11,7 @@ npm.cmd run production:check
 npm.cmd run fixtures: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
 ```

package/docs/RELEASE_NOTES_v0.1.74.md

@@ -0,0 +1,37 @@
+# Memento Mori Jester v0.1.74
+
+This release follows the fixture report's API curation guidance. It adds practical quiet-pass examples only; review behavior is unchanged.
+
+## What Changed
+
+- Added 6 fixture cases, growing the corpus from 202 to 208 fixtures.
+- Added API quiet-pass examples for:
+  - schema parsing request bodies.
+  - query-builder filters with validated IDs.
+  - enabled rate limiting.
+  - read-only Prisma migration diffs.
+  - signed-webhook documentation.
+  - OpenAPI schema documentation.
+- Raised the API preset slice from 16 to 22 fixtures.
+- Kept thin rule coverage, quiet-pass gaps, feasible pass-case gaps, and preset/kind gaps at zero.
+
+## Public Interface
+
+- No CLI command changes.
+- No config schema changes.
+- No rule matching, scoring, or verdict behavior changes.
+- No MCP, playground, GitHub Action, or npm publishing changes.
+
+## Release Validation
+
+```powershell
+npm.cmd test
+npm.cmd run demo:svg:check
+npm.cmd run fixtures:report
+npm.cmd run fixtures:report -- --json
+npm.cmd run pack:dry
+git diff --check
+node .\dist\cli.js tune coverage --no-config
+node .\dist\cli.js tune risky-domain --json --no-config
+git diff | node .\dist\cli.js diff --fail-on block --subject "v0.1.74 API quiet-pass curation"
+```

package/docs/RELEASE_NOTES_v0.1.75.md

@@ -0,0 +1,42 @@
+# Memento Mori Jester v0.1.75
+
+This release adds a Markdown export for the fixture coverage report so maintainers can paste stable quality snapshots into release notes, GitHub issues, and project updates. Review behavior is unchanged.
+
+## What Changed
+
+- Added `npm run fixtures:report -- --markdown`.
+- Added Markdown sections for:
+  - summary totals.
+  - verdict, kind, and preset counts.
+  - rule-family slices.
+  - preset slices.
+  - gap sections.
+  - quiet-pass rule coverage.
+  - quiet-pass fixture samples.
+  - curation-next guidance.
+  - next commands.
+- Added a guard that rejects combining `--json` and `--markdown`.
+- Updated maintainer docs, release docs, demo docs, README support notes, and production-readiness checks.
+
+## Public Interface
+
+- New maintainer script mode: `npm run fixtures:report -- --markdown`.
+- No CLI command changes.
+- No config schema changes.
+- No rule matching, scoring, or verdict behavior changes.
+- No MCP, playground, GitHub Action, or npm publishing changes.
+
+## Release Validation
+
+```powershell
+npm.cmd test
+npm.cmd run demo:svg: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 tune coverage --no-config
+node .\dist\cli.js tune risky-domain --json --no-config
+git diff | node .\dist\cli.js diff --fail-on block --subject "v0.1.75 markdown fixture report export"
+```

package/examples/fixtures/README.md

@@ -28,6 +28,7 @@ Maintainer triage guidance lives in [docs/MAINTAINER_TRIAGE.md](../../docs/MAINT
 - Quiet-pass examples for npm audit/outdated/ci, development-mode Node commands, package export maps, and workspace test scripts.
 - Quiet-pass examples for Bandit, pip-audit, coverage/pytest, Trivy filesystem scans, npm audit, and TLS verification-enabled diffs.
 - Quiet-pass examples for safe text rendering, allowlisted target paths, public analytics IDs, model-check commands, tool allowlist checks, and public model-name config.
+- Quiet-pass examples for API schema parsing, query-builder filters, enabled rate limiting, read-only Prisma migration diffs, signed-webhook docs, and OpenAPI schema docs.
 - Fixture metadata like `weight` and `edgeCase` to support precision-weighted tuning evidence.
 
 ## Local Check
@@ -37,6 +38,7 @@ npm.cmd test
 npm.cmd run fixtures:check
 npm.cmd run fixtures:report
 npm.cmd run fixtures:report -- --json
+npm.cmd run fixtures:report -- --markdown
 ```
 
 For one-off manual review, paste a fixture `content` value into:
@@ -62,4 +64,4 @@ Do not add secrets, private code, customer data, complete logs, or machine-speci
 
 `npm run fixtures:report` summarizes coverage by rule, rule family, preset slice, review kind, verdict, and quiet-pass rule boundaries. Use it to find rules without pass-case coverage, pass-eligible rules without pass-case coverage, rules without quiet-pass coverage, thin rule coverage, preset/kind gaps, quiet pass fixtures, and the next curation target.
 
-The `Curation next` section is a maintainer shortcut: start there when deciding whether the next fixture batch should focus on thin rules, feasible pass-case evidence, a specific rule family, or lower-count presets. The `--json` output includes the same `ruleFamilySlices`, `presetSlices`, `passEligibleRulesWithoutPassCases`, and `curationNext` fields for scripts.
+The `Curation next` section is a maintainer shortcut: start there when deciding whether the next fixture batch should focus on thin rules, feasible pass-case evidence, a specific rule family, or lower-count presets. The `--json` output includes the same `ruleFamilySlices`, `presetSlices`, `passEligibleRulesWithoutPassCases`, and `curationNext` fields for scripts. The `--markdown` output renders the same snapshot as paste-ready Markdown tables for release notes, GitHub issues, or maintainer updates.

package/examples/fixtures/preset-review-cases.json

@@ -2653,5 +2653,89 @@
       "custom-ai-public-provider-key",
       "secret-material"
     ]
+  },
+  {
+    "id": "api-schema-parse-diff-pass",
+    "preset": "api",
+    "kind": "diff",
+    "description": "Schema parsing request bodies should stay quiet around raw SQL and auth-bypass checks.",
+    "content": "diff --git a/src/routes/users.ts b/src/routes/users.ts\n--- a/src/routes/users.ts\n+++ b/src/routes/users.ts\n@@ -1 +1,2 @@\n+const input = CreateUserSchema.parse(req.body);\n",
+    "expectedVerdict": "pass",
+    "weight": 2,
+    "expectedRuleIds": [],
+    "absentRuleIds": [
+      "custom-api-auth-bypass",
+      "custom-api-raw-sql-user-input"
+    ]
+  },
+  {
+    "id": "api-query-builder-diff-pass",
+    "preset": "api",
+    "kind": "diff",
+    "description": "Query-builder filters with validated identifiers should not trip raw request SQL checks.",
+    "content": "diff --git a/src/routes/users.ts b/src/routes/users.ts\n--- a/src/routes/users.ts\n+++ b/src/routes/users.ts\n@@ -1 +1,2 @@\n+const user = await db.user.findUnique({ where: { id: validatedUserId } });\n",
+    "expectedVerdict": "pass",
+    "weight": 2,
+    "expectedRuleIds": [],
+    "absentRuleIds": [
+      "custom-api-raw-sql-user-input"
+    ]
+  },
+  {
+    "id": "api-rate-limit-enabled-diff-pass",
+    "preset": "api",
+    "kind": "diff",
+    "description": "Enabled API throttles should not look like rate-limit disabling.",
+    "content": "diff --git a/src/middleware/limits.ts b/src/middleware/limits.ts\n--- a/src/middleware/limits.ts\n+++ b/src/middleware/limits.ts\n@@ -1 +1,2 @@\n+export const apiLimiter = rateLimit({ windowMs: 60000, max: 100 });\n",
+    "expectedVerdict": "pass",
+    "weight": 2,
+    "expectedRuleIds": [],
+    "absentRuleIds": [
+      "custom-api-rate-limit-disabled",
+      "configured-sensitive-domain-rate-limit"
+    ]
+  },
+  {
+    "id": "api-prisma-migrate-diff-command-pass",
+    "preset": "api",
+    "kind": "command",
+    "description": "Read-only Prisma migration diff commands should not be mistaken for destructive resets.",
+    "content": "prisma migrate diff --from-empty --to-schema-datamodel prisma/schema.prisma --script",
+    "expectedVerdict": "pass",
+    "weight": 2,
+    "expectedRuleIds": [],
+    "absentRuleIds": [
+      "blocked-command-prisma-migrate-reset-force",
+      "custom-api-destructive-migration"
+    ]
+  },
+  {
+    "id": "api-webhook-signature-docs-pass",
+    "preset": "api",
+    "kind": "diff",
+    "description": "Docs about requiring signed webhooks should stay quiet around disabled-webhook checks.",
+    "content": "diff --git a/docs/WEBHOOKS.md b/docs/WEBHOOKS.md\n--- a/docs/WEBHOOKS.md\n+++ b/docs/WEBHOOKS.md\n@@ -1 +1,2 @@\n+Require provider webhook signature verification before accepting event payloads.\n",
+    "expectedVerdict": "pass",
+    "edgeCase": true,
+    "weight": 1,
+    "expectedRuleIds": [],
+    "absentRuleIds": [
+      "custom-api-webhook-signature-disabled",
+      "configured-sensitive-domain-webhook"
+    ]
+  },
+  {
+    "id": "api-openapi-schema-docs-pass",
+    "preset": "api",
+    "kind": "diff",
+    "description": "Docs about OpenAPI schema validation should not trip broad API sensitive-domain noise.",
+    "content": "diff --git a/docs/API_SCHEMA.md b/docs/API_SCHEMA.md\n--- a/docs/API_SCHEMA.md\n+++ b/docs/API_SCHEMA.md\n@@ -1 +1,2 @@\n+Document OpenAPI request schemas and validation examples for client integrations.\n",
+    "expectedVerdict": "pass",
+    "edgeCase": true,
+    "weight": 1,
+    "expectedRuleIds": [],
+    "absentRuleIds": [
+      "configured-sensitive-domain-openapi"
+    ]
   }
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memento-mori-jester",
-  "version": "0.1.73",
+  "version": "0.1.75",
   "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": {

package/scripts/check-production-readiness.mjs

@@ -94,6 +94,7 @@ requireText("README.md", /false-positive/i, "false-positive support guidance");
 requireText("README.md", /MAINTAINER_TRIAGE\.md/, "maintainer triage guide link");
 requireText("README.md", /fixtures:check/, "fixture authoring check guidance");
 requireText("README.md", /fixtures:report/, "fixture coverage report guidance");
+requireText("README.md", /fixtures:report -- --markdown/, "Markdown fixture report guidance");
 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");
@@ -106,6 +107,7 @@ requireText("docs/PRODUCTION_READINESS.md", /issue templates/i, "issue template
 requireText("docs/PRODUCTION_READINESS.md", /MAINTAINER_TRIAGE\.md/, "maintainer triage readiness");
 requireText("docs/PRODUCTION_READINESS.md", /fixtures:check/, "fixture authoring check readiness");
 requireText("docs/PRODUCTION_READINESS.md", /fixtures:report/, "fixture coverage report readiness");
+requireText("docs/PRODUCTION_READINESS.md", /fixtures:report -- --markdown/, "Markdown fixture report 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");
@@ -118,6 +120,7 @@ requireText("examples/fixtures/README.md", /MAINTAINER_TRIAGE\.md/, "maintainer
 requireText("examples/fixtures/README.md", /Adding A Fixture From A Report/, "fixture report conversion guidance");
 requireText("examples/fixtures/README.md", /fixtures:check/, "fixture authoring check guidance");
 requireText("examples/fixtures/README.md", /fixtures:report/, "fixture coverage report guidance");
+requireText("examples/fixtures/README.md", /fixtures:report -- --markdown/, "Markdown fixture report guidance");
 requireText("scripts/check-fixtures.mjs", /duplicated/, "duplicate fixture id check");
 requireText("scripts/check-fixtures.mjs", /unsafeContentPatterns/, "unsafe fixture content checks");
 forbidText("scripts/check-fixtures.mjs", /src\/config\.ts|src\/types\.ts/, "source-only fixture validator dependencies");
@@ -125,6 +128,7 @@ requireText("scripts/report-fixtures.mjs", /rulesWithoutPassCases/, "rules witho
 requireText("scripts/report-fixtures.mjs", /rulesWithoutQuietPassCoverage/, "rules without quiet-pass coverage report");
 requireText("scripts/report-fixtures.mjs", /quietPassRuleCoverage/, "quiet-pass rule coverage report");
 requireText("scripts/report-fixtures.mjs", /presetKindGaps/, "preset and kind gap report");
+requireText("scripts/report-fixtures.mjs", /--markdown/, "Markdown fixture report output");
 forbidText("scripts/report-fixtures.mjs", /src\/config\.ts|src\/types\.ts/, "source-only fixture report dependencies");
 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");

package/scripts/report-fixtures.mjs

@@ -33,6 +33,12 @@ const ruleFamilyOrder = [
 
 const args = new Set(process.argv.slice(2));
 const json = args.has("--json");
+const markdown = args.has("--markdown");
+
+if (json && markdown) {
+  process.stderr.write("Use only one output format: --json or --markdown.\n");
+  process.exit(1);
+}
 
 function read(path) {
   return readFileSync(join(root, path), "utf8");
@@ -55,6 +61,8 @@ const report = buildFixtureReport(fixtures);
 
 if (json) {
   process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+} else if (markdown) {
+  process.stdout.write(renderFixtureReportMarkdown(report));
 } else {
   process.stdout.write(renderFixtureReport(report));
 }
@@ -271,6 +279,91 @@ function renderFixtureReport(report) {
   return `${lines.join("\n")}\n`;
 }
 
+function renderFixtureReportMarkdown(report) {
+  const lines = [
+    "# Fixture Coverage Report",
+    "",
+    "Generated from `examples/fixtures/preset-review-cases.json`.",
+    "",
+    "## Summary",
+    "",
+    "| Metric | Value |",
+    "| --- | ---: |",
+    `| Fixtures | ${report.totalFixtures} |`,
+    `| Weighted fixtures | ${report.totalWeight} |`,
+    `| Edge-case fixtures | ${report.edgeCaseFixtures} |`,
+    `| Rules covered by expectedRuleIds | ${report.rules.length} |`,
+    "",
+    "## Counts",
+    "",
+    "### By Verdict",
+    "",
+    ...formatMarkdownCountTable("Verdict", report.byVerdict),
+    "",
+    "### By Kind",
+    "",
+    ...formatMarkdownCountTable("Kind", report.byKind),
+    "",
+    "### By Preset",
+    "",
+    ...formatMarkdownCountTable("Preset", report.byPreset),
+    "",
+    "## Rule Family Slices",
+    "",
+    ...formatMarkdownRuleFamilyTable(report.ruleFamilySlices),
+    "",
+    "## Preset Slices",
+    "",
+    ...formatMarkdownPresetTable(report.presetSlices),
+    "",
+    "## Gaps",
+    "",
+    "### Rules Without Pass-Case Coverage",
+    "",
+    ...formatMarkdownRuleGapList(report.gaps.rulesWithoutPassCases),
+    "",
+    "### Pass-Eligible Rules Without Pass-Case Coverage",
+    "",
+    ...formatMarkdownRuleGapList(report.gaps.passEligibleRulesWithoutPassCases),
+    "",
+    "### Rules Without Quiet-Pass Coverage",
+    "",
+    ...formatMarkdownRuleGapList(report.gaps.rulesWithoutQuietPassCoverage),
+    "",
+    "### Thin Rule Coverage",
+    "",
+    ...formatMarkdownRuleGapList(report.gaps.thinRuleCoverage),
+    "",
+    "### Preset/Kind Gaps",
+    "",
+    ...formatMarkdownPresetKindGaps(report.gaps.presetKindGaps),
+    "",
+    "## Quiet-Pass Rule Coverage",
+    "",
+    ...formatMarkdownQuietPassTable(report.gaps.quietPassRuleCoverage),
+    "",
+    "## Quiet-Pass Fixture Samples",
+    "",
+    ...formatMarkdownFixtureSamples(report.gaps.quietPassFixtures),
+    "",
+    "## Curation Next",
+    "",
+    ...formatMarkdownCurationNext(report.curationNext),
+    "",
+    "## Next Commands",
+    "",
+    "```powershell",
+    "npm run fixtures:check",
+    "npm run fixtures:report",
+    "npm run fixtures:report -- --json",
+    "npm run fixtures:report -- --markdown",
+    "node .\\dist\\cli.js tune coverage",
+    "```"
+  ];
+
+  return `${lines.join("\n")}\n`;
+}
+
 function createRuleEntry(ruleId) {
   return {
     ruleId,
@@ -575,6 +668,141 @@ function formatCounts(counts) {
     .join(", ");
 }
 
+function formatMarkdownCountTable(label, counts) {
+  return [
+    `| ${label} | Count |`,
+    "| --- | ---: |",
+    ...Object.entries(counts).map(([key, value]) => `| ${markdownCell(key)} | ${value} |`)
+  ];
+}
+
+function formatMarkdownRuleFamilyTable(entries) {
+  if (entries.length === 0) {
+    return ["None."];
+  }
+
+  return [
+    "| Family | Rules | Fixture Refs | Pass | Caution | Block | Quiet Pass | Thin |",
+    "| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |",
+    ...entries.map((entry) =>
+      [
+        markdownCell(entry.family),
+        entry.ruleCount,
+        entry.fixtureReferences,
+        entry.passCases,
+        entry.cautionCases,
+        entry.blockCases,
+        entry.quietPassCases,
+        entry.thinRules.length
+      ].join(" | ")
+    ).map((row) => `| ${row} |`)
+  ];
+}
+
+function formatMarkdownPresetTable(entries) {
+  if (entries.length === 0) {
+    return ["None."];
+  }
+
+  return [
+    "| Preset | Fixtures | Weight | Pass | Caution | Block | Quiet Pass | Rule Refs | Absent Refs |",
+    "| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |",
+    ...entries.map((entry) =>
+      [
+        markdownCell(entry.preset),
+        entry.total,
+        entry.weight,
+        entry.byVerdict.pass ?? 0,
+        entry.byVerdict.caution ?? 0,
+        entry.byVerdict.block ?? 0,
+        entry.quietPassFixtures,
+        entry.expectedRuleReferences,
+        entry.quietPassRuleReferences
+      ].join(" | ")
+    ).map((row) => `| ${row} |`)
+  ];
+}
+
+function formatMarkdownRuleGapList(entries) {
+  if (entries.length === 0) {
+    return ["None."];
+  }
+
+  return entries
+    .slice(0, 12)
+    .map((entry) => `- \`${entry.ruleId}\`: ${entry.total} fixture(s), pass ${entry.passCases}, caution ${entry.cautionCases}, block ${entry.blockCases}, quiet-pass ${entry.quietPassCases}`);
+}
+
+function formatMarkdownPresetKindGaps(entries) {
+  if (entries.length === 0) {
+    return ["None."];
+  }
+
+  return entries.map((entry) => `- \`${entry.preset}\`: ${entry.missingKinds.map((kind) => `\`${kind}\``).join(", ")}`);
+}
+
+function formatMarkdownQuietPassTable(entries) {
+  if (entries.length === 0) {
+    return ["None."];
+  }
+
+  return [
+    "| Rule | Quiet-Pass Fixtures | Weight |",
+    "| --- | ---: | ---: |",
+    ...entries
+      .slice(0, 12)
+      .map((entry) => `| \`${markdownCell(entry.ruleId)}\` | ${entry.total} | ${entry.weight} |`)
+  ];
+}
+
+function formatMarkdownFixtureSamples(entries) {
+  if (entries.length === 0) {
+    return ["None."];
+  }
+
+  return entries
+    .slice(0, 8)
+    .map((entry) => `- \`${entry.id}\`: ${markdownCell(entry.description)}`);
+}
+
+function formatMarkdownCurationNext(entries) {
+  if (entries.length === 0) {
+    return ["None."];
+  }
+
+  return [
+    "| Priority | Area | Count | Details |",
+    "| --- | --- | ---: | --- |",
+    ...entries.map((entry) =>
+      `| ${markdownCell(entry.priority)} | ${markdownCell(entry.area)} | ${entry.count} | ${markdownCell(markdownCurationDetails(entry))} |`
+    )
+  ];
+}
+
+function markdownCurationDetails(entry) {
+  if (Array.isArray(entry.ruleIds) && entry.ruleIds.length > 0) {
+    return entry.ruleIds.join(", ");
+  }
+
+  if (Array.isArray(entry.details) && entry.details.length > 0) {
+    return entry.details.join("; ");
+  }
+
+  if (Array.isArray(entry.families) && entry.families.length > 0) {
+    return entry.families.map((family) => `${family.family} ${family.thinRules}`).join(", ");
+  }
+
+  if (Array.isArray(entry.presets) && entry.presets.length > 0) {
+    return entry.presets.map((preset) => `${preset.preset} ${preset.total}`).join(", ");
+  }
+
+  return "";
+}
+
+function markdownCell(value) {
+  return String(value).replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+
 function formatRuleGaps(entries) {
   if (entries.length === 0) {
     return ["- none"];