DOCS · START HERE

Glossary

Every term specd uses, defined once, in the order you will meet them.

On this page

If a word on another page is unfamiliar, it is defined here. Nothing here assumes you have read anything else.

The core objects

Project: One unit of work in specd: a set of repositories, a model credential, an optional tracker, a board and a knowledge base. Everything is scoped to a project.
Knowledge base (knowledge/): Plain markdown in your repository — architecture, conventions, decisions, runbooks, delivered specs. Git is the source of truth; specd keeps a derived index it can rebuild from scratch.
AGENTS.md: The working agreements installed into your repo at grounding: read knowledge/ first, cite what you relied on, update the docs in the same pull request. CLAUDE.md imports it, so Claude Code picks it up automatically.
Spec: The reviewable unit of change: EARS requirements, a cited design, and tasks each sized to one pull request. Versions are append-only.
The gate: The approval step at station 04. A named human approves a specific version of a spec; nothing downstream runs without it.
As-built spec: The verbatim record of what was approved, filed into knowledge/specs/ by the last task of every spec. It is a historical record — never rewritten, only appended to with a "Deviations" section if reality diverged.

Station: One of the six fixed steps: Connect, Ground, Spec, the human gate, Build, Learn. They cannot be added, reordered, skipped or removed.
Connect: Registering a repository, a model credential and (optionally) a tracker. The only station that takes configuration.
Ground / onboarding: The read-only scan that produces your first knowledge base and opens the setup pull request.
Adoption: Merging the setup branch. The merge is the signal — there is no separate button in the hosted path.
Build station: The agent run that implements an approved spec, one commit per task, on the spec's own branch.
Learn: What happens on merge: the as-built spec is filed and the index refreshes, so the next spec starts better grounded.

Citation: A pointer from a design claim to the passage that supports it, written as a CITE-AS string a reviewer can look up and a tool can verify.
supported: Verdict: the cited passage exists and says what the claim says it says.
unsupported: Verdict: checked, and wrong — no such document, or no such section.
unknown: Verdict: the corpus could not answer. The document never reached the prompt, holds no indexed content, or was cut for budget. Deliberately distinct from unsupported: "I found no evidence" and "no evidence exists" are different answers.
stale: Verdict: the passage is real, but it describes code that has changed since the doc was last touched.
UNVERIFIED: A marker on a claim the agent could not ground at all. It is a question for a human, never a licence to fill the gap in from guesswork.
EARS: Easy Approach to Requirements Syntax — the "when ‹trigger›, the system shall ‹response›" shape specd writes acceptance criteria in. It exists to make a requirement testable by construction.

Index run: One atomic pass that chunks, embeds and links documents. Queued as a row and woken by Postgres LISTEN/NOTIFY — there is no broker.
Chunk: A document split on headings. The unit that is embedded, retrieved and cited.
Link kinds: The five deterministic edge types extracted by parser rules: citation, wikilink, symbolref, mdlink, coderef. No model runs at index time — a hallucinated edge would poison retrieval invisibly.
RRF (Reciprocal Rank Fusion): How the two retrieval arms are combined: vector similarity over pgvector and full-text search over Postgres tsvector, merged by rank rather than by score.
Graph expansion: The one hop taken from the retrieved seed documents across resolved links. Every added chunk carries the edge that pulled it in.
Code node: A declaration extracted from your source — a function, class or method — so a doc citing Service.method() can resolve to real code and serve it as a citable excerpt.
Coupling: Doc↔code drift mined from a bounded window of git history: "6 commits touched this directory since this doc last moved with it". Measured against the code, not against a 90-day timer.
Shrink guard: The refusal to commit an index run that would gut the index — an empty listing against a non-empty index is rejected at any size.
Health: The scored count of broken links, dangling anchors, orphans and stale code references in a knowledge base.

Runner: A machine paired to a project that claims and executes jobs — spec, onboard, build — using its own local Claude Code and its own git credentials.
Lease: The window a claimed job is held for. A runner that stops heartbeating loses the job back to the queue (180s; builds 900s), and after three reclaims the job is failed as repeatedly abandoned.
Subscription runner mode: SPECD_AI_MODE=subscription_runner — specd drives the Claude Code CLI already signed in on the machine. It never sees, stores or proxies the credential, which is also why a hosted specd could not offer this mode.
MCP: Model Context Protocol. specd mcp serve puts the retrieval engine behind it, so an agent in Claude Code, Cursor or Windsurf can ask the knowledge base instead of grepping. Read-only by construction.