The assay office for your specs
Know what the code promises. Before you own it.
SpecAssay writes what the business promised into the repo, then checks every change against it. The receipt lands in the pull request.
See a Thread Report in one sitting.
A real Thread Report, posted by CI on a pull request.
No new workflow
It is a CI check and a PR comment. Setup is a paste.
Already have a codebase? Dig it.
An as-built map of the code you already have. No guesswork about what to write down. Read the archaeology spec →
AI writes the code. Somebody still has to keep the promises.
Every pull request, sorted into three piles
A diff tool shows you hunks. SpecAssay reads the same diff against the Golden Thread and sorts it into exactly one pile:
On the thread
Pre-explained
The change serves a named statement of intent, and the test that answers for it is one click away. Read the criterion, open the proof, judge it yourself. Honest approval gets cheap. The Thread Report →
Off the thread
No story yet
The change carries no mark and moves no intent. Not an accusation; plumbing and refactors live here too. But nobody has vouched for it, so this is where you look first. The spotlight →
Moves the thread
The wording itself changed
The durable ID holds, so a restatement shows as a diff on a known row, and merging needs the signature of a person who owns the words. An agent can reword a spec; it cannot merge one. PR for Intent →
Three legs, one thread
Every honest piece of work stands on three legs: the intent (why we're doing it), the build (the code that does it), and the proof (a test that answers for it). Kick out any leg and it topples. SpecAssay is a small overlay on GitHub's Spec Kit that tests all three are present and tied together: it adds durable IDs to your templates, runs one deterministic check, the Gate, on every push, and strikes what it finds into a small file, the trace-manifest, that you can read raw or in Loupe. No fork, no daemon, no second system to keep in sync; the thread lives in the repo.
Intent
Minted once, durable
The why, minted as a stable ID (US-, FR-, NFR-, AC-) in the registry. Named at intent, never inferred from code later, never renumbered.
Build
Marked where it lives
Code that serves an intent leaves a one-line @covers ID mark. Greppable, author-written. The Gate reads it; it never invents one for you.
Proof
Named to what it answers for
The test that answers for an acceptance criterion encodes the AC's ID in its name. A named artifact you can open, not "the tests passed once."
A passing Gate does not mean "everything is done." It means no acceptance criterion is quietly unfinished. Loupe paints each state:
Merging the PR is the attestation. This is the briefing that makes it safe to.
What it adds to Spec Kit
| Spec Kit alone | With SpecAssay | |
|---|---|---|
| Spec drift | Unchecked after implementation starts | Gate fails the build on any silent gap |
| Requirement identity | Prose in spec.md |
Durable ID in a versioned registry |
| PR review | Diff plus spec in another tab | Thread Report in the PR: asked, built, proven, moved |
| Coverage | A feeling | A computed row state from marks and named proofs |
| The check | Human reading | Deterministic script; passes or fails, shows its work |
| Navigation | By folder and grep | By intent, via the trace-manifest |
What SpecAssay is not: Not contract or API verification. Not architecture enforcement. Not a code-quality opinion. One question, answered with proof a script can check: does the work still answer for what was promised?
What it costs on a Monday
The practice is three small habits, and none of them is a new kind of work: a mark (@covers AC-… where the code lands), a name (the test encodes the criterion it answers for), and a TODO (Carries: on an open task while a proof is still owed, so the work rides as visible debt instead of a silent gap). Everything else happens on push: the Gate assays, the hallmark is struck, the briefing posts to the PR.
SpecAssay's contribution is economic: the tracing that only regulated work could once afford now costs a mark, a name, and a TODO. That makes honesty cheaper than hiding, and work that cannot hide cannot be gilt.
The assay office has a word for it: gilt, base metal dressed to gleam like the real thing. In a codebase, gilt is a silent gap: an acceptance criterion with no proof and no admitted debt, gilded to pass as done. AI makes gilt cheap. SpecAssay strips the gilding: the Gate refuses, and the Golden Thread frays exactly there. See it in the field guide →
Traceability: the discipline avionics and medical devices run on.