Glossary
Two orders, the same entries. The default is by first need: the thread first, then the parts, then the machinery, then the borrowed words. Every link into a term resolves in either.
Plain-language definitions for the words that keep showing up in the field notes. If a term on this site made you stall, it should be here. If it isn't, tell me.
Golden Thread
One unbroken line from why the work exists to proof that it works. Objective, intent, build, proof, each link pointing at the next by name. The term is older than software: UK program management used it to connect a vision to project outputs, and the building industry adopted it for safety records after Grenfell. I picked it up from Zsolt Berend and Jon Smart of Sooner Safer Happier. It feels right that a word about tracking has an audit trail.
Objective, Intent, Build, Proof
The four links of the thread. The objective is the business reason. The intent is the specific promise, written down and given an ID. The build is the code that keeps the promise. The proof is the test that shows it kept. Kick out any link and the thread frays there.
Durable ID
A short label, like AC-SYNC-05, that a statement of intent gets the moment it is written and never gives back. Code and tests refer to it by name. Rename the feature, refactor the code, reorganize the team; the ID survives, so the history stays attached.
PRD (Product Requirements Document)
The document that says what a product must do, in plain statements. In this practice the PRD is law: every intent lives there first, with its ID, before anyone builds anything. It lives in the repo and changes the way code changes, by pull request, so the law has a history.
Acceptance Criterion (AC)
One testable sentence describing what "done" means for one piece of intent. "Managers can edit manager-visible content and cannot touch owner-only content" is an acceptance criterion. Each one gets an ID and, eventually, a named test.
Spec-Driven Development (SDD)
Write the intent down, structured and reviewable, before the code gets written. GitHub's Spec Kit is the workflow this practice runs on: specify, clarify, plan, tasks, implement.
Prompt-Driven Development
The alternative most teams are living in. Prompt the AI, eyeball the result, merge, repeat. Governance is whatever you typed into the chat window last. It scales exactly as far as one person's attention.
Spec Kit
GitHub's open-source toolkit for spec-driven development. SpecAssay is an extension bundle for it, not a fork.
The Gate
A check that runs on every push and refuses the build when the thread is broken. Not a warning. A refusal. In HomesFlow there are three: Gate 0 checks craft (static analysis), Gate 1 checks that specs, plans, and tasks agree with the PRD, and Gate 2 checks traceability: every acceptance criterion has a named test or an openly tracked gap. When this site says "the Gate" without a number, it means Gate 2.
Mark
A one-line note in the code saying which intent it serves: @covers AC-SYNC-05. Written by the author, read by the Gate. The Gate never invents one for you.
Named Proof
A test whose name carries the ID of the criterion it answers for: test_AC_SYNC_05_terminal_status_never_regresses. Anyone can open it and see what it proves. "The tests passed once" is not proof; a named artifact you can click is.
Tracked Debt
Unfinished work that is written down. A criterion with no proof yet rides on an open task with a Carries: line, visible to everyone. Debt is fine. Silent debt is not.
Silent Gap
A criterion with no proof and no admitted debt. The work looks done and nothing vouches for it. This is what the Gate exists to refuse.
Gilt
The assay office's word for base metal dressed to gleam like gold. In a codebase, gilt is a silent gap: work polished to pass as finished. AI makes gilt cheap. The assay strips the gilding.
Assay, Hallmark
For seven hundred years England has tested precious metal and struck a mark on it so anyone can read its provenance later. SpecAssay does the same for a codebase: test the thread on every push, strike a record of what it found.
trace-manifest
The record the Gate strikes: a plain file in the repo listing every intent and its state. Proven, tracked debt, backlog, or gap. A public data format; any tool can read it.
Loupe
The viewer for a trace-manifest, named for the jeweler's glass. Green is proven, amber is admitted debt, blue is backlog, red is a gap.
Thread Report
A comment SpecAssay posts on every pull request, sorting the change into three piles: on the thread and pre-explained, off the thread with no story yet, or moving the thread by changing the wording of intent. A reviewer reads the briefing instead of hunting through the diff.
Bang
The way a newcomer gets from a bare Mac to a working project in one go. Three steps on specassay.com/bang: install Claude Code, sign in, and one paste that hands the rest to the agent. It ends with a board open in your browser, a small ready-made project on it, and every check on this site already running. The paste does nothing you cannot read first: the file it carries out, BANG.md, is the whole instruction, written for the developer to read before the agent does.
First Light
The first card through the board after Bang: one small change, dragged from idea to done, with the thread lit end to end in Loupe. Bang gives you the telescope; First Light is the first thing you see through it. Named for the astronomer's word for a new telescope's first image.
CASE
The plain-words document a project starts from: what is the problem, who has it, what are you promising, how would you know it is working, what are you assuming. Written before any spec, in language a customer could read. A CASE describes the problem and never holds anyone's real records; those live in the application's own data, outside every repository. The template is CASE-TEMPLATE.md.
Potato Cannon
A kanban board where the columns are worked by AI agents and the drags are done by a person. A card moves from Ideas to Spec to Build to Review to Done; the agent writes the spec, builds and tests, and stops at Review for a human. Dragging to Done runs the check and records the result. Open source, by crathgeb (github.com/crathgeb/potato-cannon); this practice runs a fork with a few patches while they are offered upstream.
Born threaded
A project that has carried its thread since its first commit: the intent written and given an ID before the code, the proof named, the check running, from day one. The opposite of threading a codebase afterward. Bang produces a born-threaded project; the name is also the practice's name for doing it this way.
Pull Request (PR)
The standard way code changes are proposed, reviewed, and merged. A bundle of changes plus a conversation about them. The Thread Report lives here.
PR for Intent
The same pull-request mechanism, pointed upward. When the code reveals the spec was wrong or incomplete, you open a request against the spec, not a patch around it. Evidence from below, a decision from above, then the thread reconciles forward.
Bidirectional Traceability
The thread has to carry news upward as well as orders downward. Avionics and medical devices have required this for decades. What's new is that a build can check it.
CI (Continuous Integration)
The automated pipeline that runs checks every time code is pushed. The Gate lives here, which is why it never gets tired, never forgets, and never feels the deadline.
Suppression (and Unmapped Suppression)
A suppression tells a code checker to ignore a flagged problem. "Unmapped" means nobody wrote down why. Turning off a fire alarm can be fine and is sometimes necessary. Cutting the wire in secret is not.
Poka-yoke
Japanese for "mistake-proofing," from Lean manufacturing. Design the process so the error can't happen, rather than hoping to catch it later. The Gate is poka-yoke in shell script.
Tacit Knowledge
The stuff everyone on the team knows but nobody wrote down. It used to travel by apprenticeship, slowly. An AI agent can't learn that way; it can only be handed things written down where it can read them. Specs are how tacit knowledge travels now.
Design Controls
The regulated-industry discipline (medical devices, avionics, rail) where every design output must trace to a design input and every claim needs evidence. The ancestor of everything on this site. It never spread because it cost too much. AI just changed the price.