speccheck

speccheck

A spec is only as good as the work that actually answers it. Requirements get written, issues get filed, pull requests get merged, code lands — and somewhere in that pile the mapping between "what the spec asked for" and "what claims to have done it" quietly rots. speccheck audits that mapping. You supply the spec's requirements and the claims made against them, and it reports which requirements are covered, which are not, which claims point at requirements that do not exist, and how many claims each requirement collected.

Nothing is fetched. A requirement counts as covered the moment at least one claim names its id; the claiming source can be an issue, a pull request, or a code reference, and duplicate claims each count — three issues claiming the same requirement is a fact worth seeing in the count, not noise to deduplicate. A claim naming an id that no requirement has is dangling: it is echoed back in full, in the order the claims arrived, and it counts nowhere — not toward coverage, not toward any requirement's total. It usually means a renamed requirement or a typo, and either way it is the spec owner's problem to see, not the tool's to guess at.

The verdict compresses the report into one word. If every requirement is claimed, the spec is fully_covered. Otherwise the coverage percentage — covered over total, rounded to the nearest integer — decides: 80 or above is mostly_covered, 50 or above is partial, and anything lower is sparse. The counts always travel with the verdict, so the word never has to be taken on faith.

Malformed input is a validation error naming the offending path, with no partial result: requirements must be a non-empty array of objects each carrying a non-empty id and text, requirement ids must be unique (a duplicate is an error naming the id), and claims must be an array — possibly empty — of objects each carrying a non-empty requirement_id and source_ref plus a source_kind of issue, pr, or code. Unknown extra fields are ignored. The computation is pure and local: no network, no configuration, and no repository is read or touched.

CLI

npx @reneturcios/speccheck check --input args.json
npx @reneturcios/speccheck --version

args.json contains the full arguments object:

{
  "requirements": [
    { "id": "REQ-1", "text": "Users can sign in with a passkey" },
    { "id": "REQ-2", "text": "Sessions expire after 24 hours" },
    { "id": "REQ-3", "text": "Admins can revoke any session" }
  ],
  "claims": [
    { "requirement_id": "REQ-1", "source_kind": "pr", "source_ref": "PR #412" },
    { "requirement_id": "REQ-1", "source_kind": "issue", "source_ref": "issue #388" },
    { "requirement_id": "REQ-2", "source_kind": "code", "source_ref": "src/session.ts" },
    { "requirement_id": "REQ-9", "source_kind": "issue", "source_ref": "issue #401" }
  ]
}

The result is printed as JSON:

{
  "covered": ["REQ-1", "REQ-2"],
  "uncovered": ["REQ-3"],
  "dangling_claims": [
    { "requirement_id": "REQ-9", "source_kind": "issue", "source_ref": "issue #401" }
  ],
  "claim_counts": { "REQ-1": 2, "REQ-2": 1, "REQ-3": 0 },
  "coverage_percent": 67,
  "verdict": "partial",
  "requirement_count": 3,
  "claim_count": 4
}

claim_counts carries an entry for every requirement, including zeros, with keys in the order the requirements were supplied. Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/speccheck mcp

MCP client config:

{
  "mcpServers": {
    "speccheck": {
      "command": "npx",
      "args": ["-y", "@reneturcios/speccheck", "mcp"]
    }
  }
}

Tools

• check_spec_coverage — Verify a spec's requirements are claimed by issues, pull requests, or code, from caller-supplied requirement and claim facts.

  • requirements (array, required, at least 1 item) — the spec's requirements; each item is an object with a non-empty id and text, and ids must be unique
  • claims (array, required, may be empty) — claims that an issue, pull request, or code reference addresses a requirement; each item is an object with a non-empty requirement_id, a source_kind of issue, pr, or code, and a non-empty source_ref

  Returns {covered, uncovered, dangling_claims, claim_counts, coverage_percent, verdict, requirement_count, claim_count}.

Docker

docker run -i ghcr.io/cloudcorprecords/speccheck
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/speccheck check --input /w/args.json

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios