nullius CLAUDE.md

nullius

Deterministic checkers for agent-written claims. The thesis is that a model should only ever propose; verification is always code. Keep that boundary — if a change puts a model in the verification path, it is the wrong change.

Commands

pnpm build        # required before any CLI use — dist/ is what the CLIs run
pnpm type-check
pnpm test

pnpm build first, always. The CLIs run from dist/, so an unbuilt tree validates the previous version of the code and reports success on work that does not exist yet.

Known-environmental test failures

src/flagConformance.test.ts fails 6 tests on machines where grep is ugrep (macOS with ugrep installed). This is a real difference between the declared flag table and the local binary, not a regression. Do not chase it, and do not "fix" the table to match — CI runs real GNU grep and ripgrep.

Baseline: everything else passes. If you see 6 failures and they are all in that file, you have not broken anything.

Evidence Anchors — the house rule

Load-bearing claims about existing code carry a citation a checker re-verifies:

**Evidence:** `path/to/file.ts:88@a1b2c3d` — `const result = await retry(...)`

Rev-stamp anchors in openspec/changes/** from the start. Get the hash with git rev-parse --short HEAD when you read the file. A change proposal cites code it is about to modify, so an unstamped anchor there is designed to rot — a design doc quoting a line as the reason to delete it becomes FABRICATED the moment the change lands. With a stamp, the immutable claim stays a hard gate and only the line number goes advisory (STALE).

Never repoint a line number while keeping an old stamp: that turns an advisory STALE into a hard FABRICATED, because the text was not there at that commit.

Squash-merge destroys the commit a stamp names. This repo merges PRs with merge commits for that reason — a squash leaves every anchor stamped against a branch commit unreachable from main, and the checker then fails open with the advisory UNVERIFIABLE-REV: CI stays green while the hard gate silently stops existing. If a PR is squashed anyway, re-pin its anchors to the squash commit.