feat(bin): release-report, a second opinion on what a deploy box served and for how long

bin/release-report.mjs reads commitwork.release-evidence/1 documents (--evidence, or --fetch
over ssh from the private monitor/private/releases.json, kept under ~/.commitwork/releases),
validates them fail-closed, re-judges every finding under the document's own policy with the
local KEV catalogue, EPSS cache and advisory CVSS index, and writes a self-contained
reports/releases/<product>/index.html plus report.json: serving release, rollback-eligible
releases, blocked/refused/failed/removed history, serving timeline, exposure after the first
blocked evidence and after the KEV date added, disagreements with the box, and what the check
does not cover. Exit 0 ok, 1 serving release blocked or a disagreement, 2 input error,
4 evidence over 26 h old or KEV stale (no agreement is claimed).

Adds schema/release-evidence.schema.json, schema/release-sources.schema.json (bound as a
validator, so the applied-schema floor in schema-required goes 28 to 29),
monitor/releases.example.json, fixtures and tests.

Author: Portll

bin/README.md

@@ -256,6 +256,7 @@ Exposure view runs the same code.
 | `graph.mjs` | Builds the relation store (node:sqlite, `nodes` and `edges`) that joins findings to the lane that found them, their repository and area, the weakness classes each lane covers (`monitor/approach-taxonomy.json`), the lanes that ran on each repository (area rollups) and the opaque sessions that claimed them; `query neighbours` and `query path` answer from it, rebuilding first when an input changed. An edge kind whose input is absent is recorded as not built with the reason. The store holds fleet data, so it lives at `<reports root>/graph/graph.db` (`CW_GRAPH_DB`). Served as `GET /api/graph/neighbours` and the `graph_neighbours` MCP tool. |
 | `build-security-data.mjs` | `rollup.json` → machine-generated counts injected into report md — counts cannot drift from the scan of record. |
 | `render-report.mjs` | Zero-dep Markdown → self-contained themed HTML (prints cleanly to PDF). |
+| `release-report.mjs` | Reports what a deploy box served and whether it should have. Reads `commitwork.release-evidence/1` documents (`--evidence <file>`, or `--fetch` over ssh from the private `monitor/private/releases.json`, shape in `monitor/releases.example.json`; fetched documents are kept under `~/.commitwork/releases/<product>/`), refuses an invalid one without writing anything, re-judges every finding under the document's own policy with commitwork's KEV catalogue, EPSS cache and advisory CVSS index, and writes `reports/releases/<product>/index.html` and `report.json`: serving release and verdict, rollback-eligible releases, blocked/refused/failed/removed history, the serving timeline, exposure (serving time after the first blocked evidence and after the KEV date added), disagreements with the box, and what the check does not cover. Exit 0 ok, 1 the serving release is blocked or the two disagree, 2 input error, 4 evidence over 26 h old or KEV stale (no agreement is claimed). Schema at `schema/release-evidence.schema.json`. |
 | `md-view.mjs` | `md-view.mjs <file.md> [--out <file.html>] [--no-open]`: renders any Markdown file as one self-contained HTML page in the house palette and opens it. The page has a contents rail and a light/dark toggle, and draws the design values the document states. Colours become swatches. `--tokens` declared in a Dark/Light table resolve wherever they are named, and each contrast ratio gets its WCAG grade. Shadows, font stacks, type sizes, weights, tracking, radii, padding, spacing steps, durations, opacities, line heights and measures render as what they describe. A column or section heading decides what a bare number means. A ```lockup fence holds panel markup, which is sanitised against an allowlist and drawn twice, dark and light, with the panel's own stylesheets scoped under each container (`CW_MD_VIEW_ADMIN_DIR`). Fonts and local images are inlined; remote images are never fetched. Every drawn value is a generated class in one hashed `<style>`, so the page runs under a CSP with no `'unsafe-inline'`. Written to `reports/md-view/<path>.html` (`CW_REPORTS_DIR`). The parser is its own (`lib/md-view.mjs`): `lib/render-markdown.mjs` ends a list item at its first wrapped line and is held to docsite parity, so it was not widened. |
 | `parse-runtime.mjs` | One parser for DAST/BOLA reports feeding both the rollup and `runtime.html`. |
 | `mainline-data.mjs`, `slices.mjs` | Sitemap history harvesters (git-graph DAG; versioned state slices). |

bin/release-report.mjs

@@ -290,7 +290,7 @@ test('every shipped example of a private record validates against its schema', (
 
 test('the count of applied schemas may not fall', () => {
   // Raise only after a consumer is proven to reject an invalid document through the schema.
-  const FLOOR = 28; // monitor/release-terms.example.json's schema: compileTerms in bin/lib/release-terms.mjs refuses an invalid list (bin/test/release-terms.test.mjs)
+  const FLOOR = 29; // monitor/private/releases.json's schema: loadSources in bin/release-report.mjs refuses an invalid list (bin/test/release-report.test.mjs); before it, monitor/release-terms.example.json's: compileTerms in bin/lib/release-terms.mjs (bin/test/release-terms.test.mjs)
   const applied = inv().entries.filter((e) => e.binding === 'validator').length;
   assert.ok(applied >= FLOOR, `${applied} schemas are applied at runtime, floor is ${FLOOR}`);
   assert.equal(applied, FLOOR,

bin/test/release-report.test.mjs

@@ -8,7 +8,7 @@ nothing about exit status; `prose` means it does, in a shape the extractor does
 Neither is a claim about what the command returns. What may change between releases is in
 [STABILITY.md](STABILITY.md).
 
-344 commands: 147 declared, 12 prose, 185 undeclared. Of the declared, 116 use only codes 0–13, the range Node itself exits with (1 on an uncaught exception), and 31 declare a code of 20 or above.
+345 commands: 148 declared, 12 prose, 185 undeclared. Of the declared, 117 use only codes 0–13, the range Node itself exits with (1 on an uncaught exception), and 31 declare a code of 20 or above.
 
 ## `commitwork` subcommands
 
@@ -715,6 +715,15 @@ Undeclared: `list`, `run`, `scan`, `brief`, `sarif`, `reindex`, `doctor`, `hook`
 | 1 | blocked |
 | 2 | incomplete (a gate could not run, or was skipped) |
 
+### `bin/release-report.mjs`
+
+| Exit | Meaning |
+|---:|---|
+| 0 | ok |
+| 1 | the serving release is blocked, or commitwork and the box disagree on a finding |
+| 2 | usage, unreadable or invalid input, or a failed fetch (invalid input writes nothing) |
+| 4 | evidence older than 26 h, or the KEV catalogue stale or undated (no agreement is claimed) |
+
 ### `bin/release-tag.mjs`
 
 | Exit | Meaning |

bin/test/schema-required.test.mjs

@@ -10,9 +10,9 @@ verified against the code. Check definitions are indexed in [MANIFEST-MAP.md](MA
 
 | Surface | Total | Documented | Undocumented |
 |---|---:|---:|---:|
-| Commands (a usage line in the header) | 331 | 269 | 62 |
-| Exit codes (declared in the header) | 344 | 147 | 197 |
-| `CW_*` environment variables (described in an `env` header) | 876 | 191 | 685 |
+| Commands (a usage line in the header) | 332 | 270 | 62 |
+| Exit codes (declared in the header) | 345 | 148 | 197 |
+| `CW_*` environment variables (described in an `env` header) | 878 | 191 | 687 |
 | Lane manifest check keys in use (described in the schema) | 44 | 42 | 2 |
 
 Commands are the population of `bin/exit-codes.mjs`: top-level `bin/`, `monitor/` and `cra/`
@@ -1277,6 +1277,17 @@ release-names-reseed.mjs — lower the release-names HEAD floor as cleanups land
 - Usage: `node bin/release-names-reseed.mjs [--write] (default is a dry run)`
 - Exit: undeclared
 
+### `bin/release-report.mjs`
+
+bin/release-report.mjs — what a deploy box served, whether it should have, and for how long.
+
+- Usage: `node bin/release-report.mjs --evidence <file> [--evidence <file> ...] [--fetch]`
+- Option: `--evidence <file> a saved document; repeatable`
+- Option: `--fetch pull each source of monitor/private/releases.json over ssh and keep the documents`
+- Option: `--out <dir> base directory for the reports, default <reports>/releases; one <product>/ each`
+- Option: `--json print the report JSON (an array when several products) to stdout`
+- Exit: 0 ok · 1 the serving release is blocked, or commitwork and the box disagree on a finding · 2 usage, unreadable or invalid input, or a failed fetch (invalid input writes nothing) · 4 evidence older than 26 h, or the KEV catalogue stale or undated (no agreement is claimed)
+
 ### `bin/release-tag.mjs`
 
 - Usage: `release-tag.mjs [--ref <rev>] [--tag] [--json]`
@@ -2638,8 +2649,8 @@ cra/watch.mjs — exploited-vulnerability watch with CRA Art.
 
 ## Environment variables
 
-876 `CW_*` names read by tracked non-test sources: 756 by name, and
-120 indirect (quoted in a file that reads the environment by a computed key, so the read
+878 `CW_*` names read by tracked non-test sources: 760 by name, and
+118 indirect (quoted in a file that reads the environment by a computed key, so the read
 is likely but not shown). At most 6 readers are listed per name. A description is taken from
 a reader's `env` header section when one has it, otherwise from another file's, which is named.
 
@@ -2948,7 +2959,7 @@ a reader's `env` header section when one has it, otherwise from another file's,
 | `CW_EOL_API` | direct | `bin/eol-snapshot.mjs` | base URL |
 | `CW_EOL_SNAPSHOT` | direct | `bin/eol-snapshot.mjs` | output path |
 | `CW_EPHEMERAL_MIN` | direct | `monitor/listeners.mjs` | undocumented |
-| `CW_EPSS` | indirect | `cra/lib.mjs` | undocumented |
+| `CW_EPSS` | direct | `bin/release-report.mjs` | undocumented |
 | `CW_EPSS_DETAIL` | indirect | `bin/test-run.mjs`, `cra/lib.mjs`, `monitor/store-paths.mjs` | undocumented |
 | `CW_EPSS_PATH` | direct | `monitor/dep-findings.mjs` | undocumented |
 | `CW_ESCALATE` | direct | `cra/watch.mjs` | undocumented |
@@ -3056,7 +3067,7 @@ a reader's `env` header section when one has it, otherwise from another file's,
 | `CW_JVM_KEEP_SCRATCH` | direct | `bin/jvm-resolve.sh` | undocumented |
 | `CW_JVM_TIMEOUT` | direct | `bin/jvm-resolve.sh` | undocumented |
 | `CW_KEEP_REPORTS` | direct | `mcp/server.mjs` | undocumented |
-| `CW_KEV` | indirect | `cra/lib.mjs` | undocumented |
+| `CW_KEV` | direct | `bin/release-report.mjs` | undocumented |
 | `CW_KEV_PATH` | direct | `monitor/dep-findings.mjs` | undocumented |
 | `CW_KEV_STALE_DAYS` | direct | `cra/lib.mjs` | undocumented |
 | `CW_LANES` | indirect | `bin/lane-staleness.mjs` | undocumented |
@@ -3266,6 +3277,7 @@ a reader's `env` header section when one has it, otherwise from another file's,
 | `CW_REFUTATIONS` | direct | `monitor/store-paths.mjs` | undocumented |
 | `CW_REGISTRY` | direct | `bin/hermetic-test.mjs`, `monitor/history-chain.mjs`, `monitor/registry.mjs`, `monitor/store-paths.mjs` | registry, and through it the reports root (`monitor/defect-signature.mjs`) |
 | `CW_REGISTRY_REQUIRE_REAL` | indirect | `monitor/registry.mjs` | undocumented |
+| `CW_RELEASES_DIR` | direct | `bin/release-report.mjs` | undocumented |
 | `CW_RELEASES_OUT` | direct | `bin/releases-atom.mjs` | undocumented |
 | `CW_RELEASES_PATTERN` | direct | `bin/releases-atom.mjs` | undocumented |
 | `CW_RELEASES_SELF` | direct | `bin/releases-atom.mjs` | undocumented |
@@ -3277,6 +3289,7 @@ a reader's `env` header section when one has it, otherwise from another file's,
 | `CW_RELEASE_REVIEWS_SCHEMA` | direct | `bin/lib/release-reviews.mjs` | undocumented |
 | `CW_RELEASE_SCRATCH` | direct | `bin/release-candidate.mjs` | the directory the tests gate makes its scratch HOME in (default ~/.cache/commitwork/release-candidate), read at call time |
 | `CW_RELEASE_SOURCE` | direct | `bin/release-candidate.mjs`, `bin/web-roadmap.mjs` | the repository --work reads commits from; default this checkout |
+| `CW_RELEASE_SOURCES` | direct | `bin/release-report.mjs` | undocumented |
 | `CW_RELEASE_TAG_PREFIX` | direct | `bin/release-tag.mjs` | the release tag prefix, default v (`bin/changelog.mjs`) |
 | `CW_RELEASE_TERMS` | direct | `bin/lib/release-terms.mjs` | a list file; overrides the sidecar |
 | `CW_REMEDIATION_INPUT` | indirect | `monitor/remediation-pr.mjs` | undocumented |

docs/EXIT-CODES.md

@@ -0,0 +1,154 @@
+{
+  "schema": "commitwork.release-evidence/1",
+  "product": "audiencedirect-site",
+  "generated_at": "2026-10-22T10:00:00Z",
+  "source": "ad-site-deploy@0123456789ab",
+  "policy": {
+    "name": "ad-release-gate",
+    "kev": true,
+    "critical": true,
+    "high_epss_min": 0.1,
+    "runtime_only": true,
+    "keep_days": 90,
+    "keep_min": 3,
+    "verdict_max_age_hours": 48
+  },
+  "serving": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "releases": [
+    {
+      "sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "built_at": "2026-10-21T08:00:00Z",
+      "state": "serving",
+      "verdict": {
+        "checked_at": "2026-10-22T09:00:00Z",
+        "status": "clean",
+        "blocking": [],
+        "findings": [
+          {
+            "id": "GHSA-xxxx-0000-0001",
+            "cves": [
+              "CVE-2099-0001"
+            ],
+            "package": "left-pad",
+            "version": "1.0.0",
+            "runtime": true,
+            "severity": "medium",
+            "cvss": 5.3,
+            "epss": 0.01,
+            "kev": false,
+            "blocking": false,
+            "reason": "no policy rule fires"
+          }
+        ],
+        "unchecked": {
+          "jsr": 3,
+          "remote_hosts": [
+            "esm.sh"
+          ]
+        },
+        "kev_catalog": "2026.10.20"
+      },
+      "verdict_at": "2026-10-22T09:00:00Z",
+      "inventory": {
+        "npm": [
+          {
+            "name": "left-pad",
+            "version": "1.0.0",
+            "runtime": true,
+            "source": "lock"
+          }
+        ],
+        "jsr": [
+          "@std/assert"
+        ],
+        "unchecked_remote": [
+          "esm.sh"
+        ]
+      }
+    },
+    {
+      "sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "built_at": "2026-10-20T08:00:00Z",
+      "state": "kept",
+      "verdict": {
+        "checked_at": "2026-10-22T09:00:00Z",
+        "status": "clean",
+        "blocking": [],
+        "findings": [],
+        "unchecked": {
+          "jsr": 3,
+          "remote_hosts": [
+            "esm.sh"
+          ]
+        },
+        "kev_catalog": "2026.10.20"
+      },
+      "verdict_at": "2026-10-22T09:00:00Z",
+      "inventory": {
+        "npm": [
+          {
+            "name": "left-pad",
+            "version": "1.0.0",
+            "runtime": true,
+            "source": "lock"
+          }
+        ],
+        "jsr": [
+          "@std/assert"
+        ],
+        "unchecked_remote": [
+          "esm.sh"
+        ]
+      }
+    },
+    {
+      "sha": "cccccccccccccccccccccccccccccccccccccccc",
+      "built_at": "2026-10-10T08:00:00Z",
+      "state": "kept",
+      "verdict": {
+        "checked_at": "2026-10-10T09:00:00Z",
+        "status": "clean",
+        "blocking": [],
+        "findings": [],
+        "unchecked": {
+          "jsr": 3,
+          "remote_hosts": [
+            "esm.sh"
+          ]
+        },
+        "kev_catalog": "2026.10.20"
+      },
+      "verdict_at": "2026-10-10T09:00:00Z",
+      "inventory": {
+        "npm": [
+          {
+            "name": "left-pad",
+            "version": "1.0.0",
+            "runtime": true,
+            "source": "lock"
+          }
+        ],
+        "jsr": [
+          "@std/assert"
+        ],
+        "unchecked_remote": [
+          "esm.sh"
+        ]
+      }
+    }
+  ],
+  "events": [
+    {
+      "at": "2026-10-20T08:30:00Z",
+      "event": "serving",
+      "sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+      "detail": null
+    },
+    {
+      "at": "2026-10-21T08:30:00Z",
+      "event": "serving",
+      "sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "detail": null
+    }
+  ]
+}

docs/REFERENCE.md

@@ -0,0 +1,78 @@
+{
+  "schema": "commitwork.release-evidence/1",
+  "product": "audiencedirect-site",
+  "generated_at": "2026-10-22T10:00:00Z",
+  "source": "ad-site-deploy@0123456789ab",
+  "policy": {
+    "name": "ad-release-gate",
+    "kev": true,
+    "critical": true,
+    "high_epss_min": 0.1,
+    "runtime_only": true,
+    "keep_days": 90,
+    "keep_min": 3,
+    "verdict_max_age_hours": 48
+  },
+  "serving": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "releases": [
+    {
+      "sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "built_at": "2026-10-21T08:00:00Z",
+      "state": "serving",
+      "verdict": {
+        "checked_at": "2026-10-22T09:00:00Z",
+        "status": "clean",
+        "blocking": [],
+        "findings": [
+          {
+            "id": "GHSA-kev-0000-0002",
+            "cves": [
+              "CVE-2099-0002"
+            ],
+            "package": "quiet-lib",
+            "version": "1.0.0",
+            "runtime": true,
+            "severity": "medium",
+            "cvss": 6.1,
+            "epss": null,
+            "kev": false,
+            "blocking": false,
+            "reason": "no policy rule fires"
+          }
+        ],
+        "unchecked": {
+          "jsr": 3,
+          "remote_hosts": [
+            "esm.sh"
+          ]
+        },
+        "kev_catalog": "2026.10.20"
+      },
+      "verdict_at": "2026-10-22T09:00:00Z",
+      "inventory": {
+        "npm": [
+          {
+            "name": "left-pad",
+            "version": "1.0.0",
+            "runtime": true,
+            "source": "lock"
+          }
+        ],
+        "jsr": [
+          "@std/assert"
+        ],
+        "unchecked_remote": [
+          "esm.sh"
+        ]
+      }
+    }
+  ],
+  "events": [
+    {
+      "at": "2026-10-21T08:30:00Z",
+      "event": "serving",
+      "sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+      "detail": null
+    }
+  ]
+}

fixtures/release-evidence/clean.json

@@ -0,0 +1,3 @@
+{
+  "CVE-2099-0100": 0.9
+}