Badge and `2119 report`: publishable coverage artifacts from check --json

[tylerwillis]

Why

2119 check produces one bit the outside world can see: an exit code. Everything richer — how many requirements exist, whether every MUST is traced, whether verdicts are fresh — lives in artifacts a reader must know to go dig for. Two audiences want that at a glance:

1. A README visitor. A badge makes gating visible — and, more importantly, makes an ungated repo visibly ungated. 2119: 142 reqs · all verified in green is a trust signal; 3 uncovered in red is social pressure no dashboard provides.
2. Someone accountable to a third party — a consultant presenting to a customer, a platform team reporting to compliance, a maintainer answering "how is this tested?" They need a one-page report they can hand over, where every number is replayable from the repo at a stated commit.

Both fall out of data the tool already computes: check --json carries the full picture today. This is a rendering feature, not new analysis.

Design

Badge (zero-server). One CI step renders check --json into a shields.io endpoint blob, committed (e.g. .2119/badge.json) or published as a workflow artifact/pages file:

{ "schemaVersion": 1, "label": "2119",
  "message": "142 reqs · all verified", "color": "brightgreen" }

![2119](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/<org>/<repo>/main/.2119/badge.json)

Badge states (worst condition wins):

Condition	Message	Color
all covered, all verdicts current	N reqs · all verified	brightgreen
stale reviews only	N reqs · K reviews stale	yellow
any uncovered MUST or failing review	K uncovered / K failing	red

Report (2119 report, or report --html). A static one-pager rendered from the same JSON: totals (requirements, traced, verdicts current, [review]-tagged, [manual]), a per-spec table (req count, coverage, verdict freshness, status), and a footer stating the commit SHA and the command that generated it. The closing property is the whole value: every row is replayable from committed artifacts — spec files, annotated tests, and hash-bound verdict JSON — at that commit. No screenshots of dashboards; an auditor re-runs 2119 check --json at the SHA and gets the same table.

Mockup (illustrative data, both layers): https://gist.github.com/tylerwillis/0b132d45ea73e8ecaa8d9a343cdec38b

Candidate requirements (sketch, for specs/)

1. Badge and report output MUST be derived solely from check --json for the current working tree — no additional scanning, no network.
2. The badge blob MUST degrade to the worst present condition (uncovered/failing > stale > verified) so a green badge can only mean a fully passing gate.
3. The report MUST state the commit SHA and generating command, and MUST NOT include any figure not derivable from committed artifacts at that SHA.
4. Report generation MUST NOT require the judgment layer to be enabled — reviews: false repos get a coverage-only report that says so.
5. The default path MUST stay simple (single command, no config); publishing (pages, gist, artifact) is the adopter's CI concern, documented as recipes.

Non-goals

• No server, queue, or dashboard — the enforcement surface stays "artifacts your forge serves" (consistent with docs/design.md's CI-composition boundary).
• Not an attestation: the badge inherits exactly the trust of the verdicts behind it. Its credibility strengthens when combined with the independent-runner pattern (Executable independent-runner example: CI-identity review dispatch #32) — a green badge over CI-recorded verdicts is a much stronger claim than one over author-recorded verdicts.

Effort

Small: check --json already exists; this is a renderer plus a spec file and annotated tests, per this repo's own process. No new dependencies.

🤖 Generated with Claude Code