# The scorecard

`truewire score` is the definition of *finished*, run as a command. One table, one exit
code, no partial credit and no adjectives.

```
$ truewire score
bit2me                                            python  typescript  rust
  coverage     every documented endpoint is specified     147/147
  recorded     every endpoint has a recording or reason   147/147
  check        the spec satisfies the authoring rules     pass
  generated    codegen is current and has no orphans      pass    pass        pass
  surface      every endpoint is reachable as a method    pass    pass        pass
  tests        the suite passes against the mock          pass    pass        FAIL  3 failed
  lint         format, lint and type-check                pass    pass        pass
  standards    docstrings, schemas, secrets, coverage     pass
  docs         required pages, every snippet type-checks  pass
  published    the current version is on every registry   pass    pass        pass
  conform      a dated report from the last run           unchecked
  stranger     a newcomer completed the quickstart        2026-10-12
  9 pass, 1 fail, 1 unchecked -> not done
```

## The rows

**S1. coverage** — every endpoint the upstream documentation describes appears in the
spec. The denominator comes from the inventory that `truewire-discovery` produced and a
person approved; a spec cannot mark itself complete against its own opinion of the API.
The inventory is [`spec/inventory.json`](/docs/spec/authoring#endpoint-inventory): each
entry names a spec endpoint by dotted directory id, gives an exclusion reason, or carries
neither when the documented operation is not yet specified. Approval confirms the full
upstream list, and can precede a complete spec. Missing, malformed or unapproved
inventories fail, as do unresolved entries. The score shows the resolved/total ratio
(including explicit exclusions), for example `22/69 endpoints; 47 unspecified`, whether
approved or not; unapproved inventories also say `inventory not approved`. `--verbose`
lists the unspecified operations. A complete approved inventory passes with `N/N endpoints`. Spec endpoints
absent from the inventory appear as warnings, since the inventory is the denominator.

**S2. recorded** — every endpoint carries a recorded pair, or an `unverified` block with a
reason from the closed set. `truewire examples --require-verified`.

**S3. check** — `truewire check`.

**S4. generated** — `truewire generate --check` for every declared language: the tree
matches the spec and the manifest has no orphans.

**S5. surface** — `truewire surface`: every endpoint in the spec is reachable as a method
on the generated client, per language.

**S6. tests** — `truewire test`: every declared package's suite passes against
`truewire mock`.

**S7. lint** — `truewire lint`: formatter, linter and type checker clean, per package.

**S8. standards** — `truewire standards`: docstrings present, no duplicated schema, no
leaked secret, every router covered, and the layout `truewire init` writes:
[A7–A9](/docs/shape/agents#wiring) (`AGENTS.md`, `CLAUDE.md` as `@AGENTS.md`, `.claude/` linked into
`.agents/`), the `$schema` of [W10](/docs/shape/workspace#documentation) and the `#:schema` line of
[W13](/docs/shape/workspace#configuration), and a codegen manifest per declared language that is not
git-ignored ([W16](/docs/shape/workspace#generated-state)). One finding per broken clause, named by its id.

**S9. docs** — `truewire docs check`, plus the presence of the pages
[W11](/docs/shape/workspace#documentation) requires: an index, an api-keys page, at least one
how-to, and a reference section. A page that still carries the stub marker `truewire init`
writes counts as absent: a skeleton is not documentation.

**S10. published** — the version in each package's manifest is present on that language's
registry. A project whose packages are built but unpublished is not finished; a caller
cannot install a build.

The checker reads Python's `pyproject.toml` `[project]`, TypeScript's `package.json`,
and Rust's `Cargo.toml` `[package]` from the package directory. It checks the exact name
and version on PyPI, npm, or crates.io. HTTP 200 passes and 404 fails. Each lookup makes
one request with a five-second timeout; network errors and server errors leave the cell
`unchecked`, as do missing or unreadable package metadata and unexpected HTTP responses.

**S11. conform** — a conformance report exists from the last scheduled run, its findings
are dated, and none is older than its triage window ([ADR 0012](/docs/adr/0012-conformance-runs)).

**S12. stranger** — a developer who has never seen the project completed the quickstart
using only the published package and the public docs, and the date they did it. This row
is a date, not a check, and it is the only one a machine does not produce.

## Rules

**S13.** A row whose checker does not exist prints `unchecked`, never `pass`. A scorecard
that turns green by not looking is the one failure mode that would make the whole document
worthless.

**S14.** A row is `n/a` only for a language the project does not declare. There is no
`n/a` for a row a project finds inconvenient.

**S15.** `truewire score` exits zero only when every row is `pass`, every language column
included, `stranger` carries a date, and nothing is `unchecked`.

**S16.** The scorecard is per project. A toolchain release is judged by the scorecards of
the projects it can produce, and `bluesky`, `weather-gov` and `kraken` are run against
every release.

**S17.** Scores are recorded over time, one line per run, so that a change that improves
one row and quietly breaks another is visible. The history lives with the project, not in
anyone's memory.