Topic · Executable requirements
How do I make requirements executable so they're checked automatically?
Write the shall so a compiler can reject it. Then put proof audit --fail-level warn on the merge. A missing witness is a red build, not a slide in a PDF.
proof audit --fail-level warnCucumber and SpecFlow still own Given-When-Then. That glue runs a scenario. It does not ask whether an approved shall still has a witness.
01 · The job
Executable means the build can fail it.
A requirement that only lives in a document is a wish. A requirement that can fail CI is a bar.
Two different questions get packed into “executable requirements.” One is authoring: can a machine parse the sentence? That is the FRETish compiler. The other is the gate: after the sentence is in the graph, does every merge re-check it? This page is the gate.
Proof’s loop-close is one command. proof audit --fail-level warn runs the checks that matter, with no persistent workflow state. A testable shall without an acceptance witness is red (or staged as counted warning debt). A citation that disagrees with the child’s satisfies back-link is a different check, same exit.
proof validate --preflight
proof audit --fail-level warn
proof audit --check acceptance_criteria_witnessedThe first command is the compiler. The second is the gate you put on the merge. The third is the witness check by name when you want that row alone. Cucumber is not in this list. It never read the shall.
02 · The exhibit
A green scenario is not a green shall.
Same English intent. Two runtimes. Only one of them fails the build because the requirement itself is missing a witness.
| Job | Cucumber / SpecFlow | Proof |
|---|---|---|
| What executes | Gherkin steps bound to glue code. | Approved shalls in the graph. |
| Green means | The scenario’s steps ran. | The shall has a witness at its own level, or the miss is counted debt. |
| Fails the merge | A red step. | proof audit --fail-level warn |
| Language | Given-When-Then. | FRETish. 288 templates, not arbitrary English. |
| Who still wins | Product-readable scenarios. Keep them. | The requirement gate. Not a second Gherkin runner. |
| What a 100% pass still misses | A promise nobody wrote as a scenario. | A promise nobody wrote as a shall. |
Drawn for this page from the two runtimes, not from a Cucumber bake-off we did not run. SpecFlow is the same Gherkin job on .NET. It sits on this URL. There is no twin.
# Gherkin: the scenario ran bundle exec cucumber # the shall itself is in CI proof audit --fail-level warn
If the shall is “imports 100,000 records,” a Cucumber scenario that clicks through the happy path does not witness it. The acceptance test that actually imports 100,000 records does, and it has to be annotated to that shall. The Gherkin report can still print green either way.
03 · The honest loss
Cucumber keeps Gherkin. Jama still authors the programme.
We have not run Cucumber or SpecFlow on a frozen corpus. Keep the scenarios. Proof will not replace them.
FRETish is 288 templates. Nested sequencing and arbitrary formulas stay with TLA+, Alloy, and Dafny on the FRETish page. A green proof audit --fail-level warn means the checks in that project’s bar passed at warn. It does not mean every promise a salesperson made is in the graph.
Jama still wins at programme authoring. SpecFlow still wins when the team’s language is Gherkin on .NET. Proof does not compile Given-When-Then. The commercial install is the audit, not a second BDD tool.
04 · Nearby questions
What people type next.
How do I write FRETish requirements a compiler can check? That is authoring. Five slots, 288 templates. The compiler page.
What's the difference between test coverage and requirements coverage? A line report asks whether code ran. This gate asks whether the shall has a witness. Two denominators.
Can it re-run on every release instead of a one-time report? After week four the gate is in your CI. The engagement can stop. The bar does not. That install is the audit.