# Gate 01 — Every deliverable has an executable specification

**Check:** `checks/spec_check.py` · **Stops the build:** yes

## What this gate asserts

Before work starts on a deliverable, there is a specification for it, written
in Given/When/Then form, and that specification runs.

Two things are checked:

1. **Every deliverable listed in the project's working procedures has a feature
   file**, and the file named in the table actually exists.
2. **Every feature file parses and every scenario runs.** A specification that
   cannot be executed is a document, and documents drift.

## Why it exists

Specifications written after the build describe what was built. They pass
immediately, they never fail, and they provide an auditor with no assurance
whatsoever — the code and the specification agree because one was copied from
the other.

Writing the specification first is an old discipline that was abandoned for a
good reason: by hand, Gherkin costs more to maintain than it returns. Agents
change that arithmetic. They write and update scenarios cheaply, which makes
the requirement affordable again, and what it produces — a single chain from
requirement through test to evidence — is the thing a regulated client's
auditor actually asks for.

## What a client can challenge

- *"Show me the specification for this deliverable, and its last run."*
  Both are in the repository, and the run is in the log.
- *"Has any scenario in this file ever failed?"* If the honest answer is no,
  the scenarios probably describe the implementation rather than the
  requirement. That is a finding, and the remediation is to rewrite them.
- *"Who decided this was the required behaviour?"* Scenarios carry trace
  markers to the decision log where the behaviour was a judgement call.

## How it fails

```
gate-01  FAIL  D2 "Quarterly control report": features/quarterly-report.feature not found
gate-01  FAIL  features/handover.feature:12 scenario "Agent hands over a draft" — no steps
```

## Remediation

1. Write the feature file, in behaviour the client can observe. `Then the
   report shows the figure from the ledger`, not `Then render.py returns 0`.
2. If the deliverable genuinely has no observable behaviour — a static asset,
   say — remove it from the deliverables table rather than writing a hollow
   specification for it. The table drives this gate, so it must stay honest.
3. Re-run `python3 qa-gates/checks/run_gates.py`.

## Configuration

| Setting | Default | Where to change it |
|---|---|---|
| Deliverables table | §2 of the project working procedures | That document |
| Features directory | `features/` | `--features` on the check |