Spec Format Governance

Spec-Format Governance — the spec.md structure bar

Universal bar for how a behavioral node's spec.md is structured. The spec-producer self-aligns to it before writing; the spec-judge grades structure backward at the spec gate. The layout law it sits inside — spec types, the four folder kinds, screaming architecture — is sdd:spec-structure-governance; this bar owns one node's spec.md. A descriptive index or reference artifact carries none of the sections below.

The four sections, in order (plus one optional)

## What

The overview: what the capability is, the problem it solves, who has it — plus Non-goals (what it deliberately excludes). One or two short paragraphs; add a Key terms glossary when it leans on jargon. Legible to a non-engineer.

## Use Cases

One entry per distinct way the capability is invoked, each named to its implementation surface (a CLI verb, a public function, an endpoint) and carrying four parts: actor / goal, the entry point (trigger / inputs / outcome), and its extensions. Naming the impl surface keeps the spec, the suite, and the code on one screaming structure: the builder gives each use case its own module, so each change stays local.

A use case answers "who is trying to do what, how do they invoke it, and what else can happen?" — never "given this state, does it do that?" (that is a scenario).

Enumerate by actor, never by entry point. Walking the interface and asking who calls each entry point can only return use cases the interface already implies — it reproduces the surface and calls it a requirement, and it is structurally blind to the use case nobody has built yet. So the section is derived the other way round:

1. List the actors — every person in a role, sibling capability, scheduler, or operator that reaches this capability, plus whoever is affected by its outcome without invoking it (the reviewer, the on-call, the next agent in a chain). The second group are stakeholders rather than actors and are where a missed use case usually hides.
2. Per actor, name the goals they come to this capability with — their result, not the call they make.
3. Then map goals to entry points. A goal with no entry point is the finding this ordering exists to surface: either the capability is missing a way in, or the goal belongs to another node. An entry point serving no listed actor's goal is the mirror finding — it is surface nobody asked for.

The enumeration is checkable both ways: an actor carrying no use case, and a use case whose actor is absent from the list, are each a hole. On backfill the source yields only the served use cases by construction — recover the unserved ones from the request history, the issue tracker, and recurring workarounds, and record where each came from.

• Actor and goal — one line each, not a persona. Name who invokes it (a person in a role, another capability, a scheduler) and the outcome they want, stated as their result rather than the mechanism ("recover the work after a crash", not "calls resume()"). An actor may be an agent or a sibling capability; that is normal, not a degenerate case. Where the goal restates the function name, the use case has not been found yet — it has been renamed.

• Entry point — the trigger, its inputs, and the success outcome. A table is the usual form.

• Extensions — what else can happen, and the instrument that finds it. An extension is any path from this use case's trigger that does not reach its success outcome; state each with its cause and its outcome. That criterion decides membership — the recurring kinds (an error, a refusal, a boundary, a partial result, a contended or absent input) are a prompt to search, not a closed set, so a divergence matching none of them still belongs and a kind that cannot arise here is not owed a row. A use case with no extensions is a claim that nothing can go wrong — state that claim explicitly (extensions: none — <why>) rather than leaving the field off, so a reviewer can disagree with it.

  Extensions are a discovery instrument, not a second specification. They exist to make the CFG complete: a graph drawn from an implementation reproduces what the code already does and can never tell you a branch is missing, whereas asking what can go wrong for this actor finds it. So every extension you find belongs in ## Control Flow as a path, and the scenarios still derive from the CFG alone (## Scenario map, 1:1 on the (path class, edge) pair). Never draw a scenario from the stated list directly: a suite derived from prose is 1:1 with that prose by construction and can no longer surface a hole. A use case is therefore not 1:1 with a scenario — one extension may need several scenarios where several path classes reach it, and several extensions may reconverge onto one.

Every element of the public surface traces to a use case that needs it. List each element the capability exposes — a flag, an option, a parameter, a prop, an event — against the use case requiring it, and name the elements it may not be combined with. An element no use case needs is unjustified: cut it, or name the use case. A pair whose combination is contradictory and unstated is a gap, not a detail. This is the same orphan-detection discipline as ## Scenario map, applied one level up: there, a scenario with no edge is an orphan; here, an element with no use case is an orphan.

Degenerate cases stay cheap. A capability exposing one entry point and no optional elements carries the surface trace in a line, not a table — the obligation is that nothing on the surface is unaccounted for, never that a table exists. A single-actor capability lists one actor; the enumeration is the discipline, not the length.

## Control Flow

The control-flow graph (CFG) the capability runs once invoked, drawn as a fenced Mermaid graph — nodes are decisions, edges are branches. Use cases enter the CFG, and several usually share one (many-to-one). When use cases run genuinely distinct decision logic (common for CLI verbs), section ## Control Flow by sub-graph and have each use case name the one it enters. A single-branch capability may state its decision in a line.

## Scenario map

The explicit maintained table binding the CFG to the suite, grouped by use case, with three columns — | Edge | Path (Given) | Scenario |. The unit is the (path class, edge) pair, not the edge alone: a scenario's Given is the path reaching the edge, its When is the edge under test (sdd:suite-format-governance).

• 1:1 scenario↔row — every scenario has exactly one row, every row one scenario.
• Name the scenario in backticks. The Scenario cell holds the scenario's title backtick-wrapped (`send text types literal text and presses no Enter`). This is how check-suite tells a data row from the header and separator: a data row whose Scenario cell is not backtick-wrapped is reported as an unparseable row, not silently skipped — a map that reads complete but binds nothing is the exact gap the map exists to prevent.
• An edge may carry several rows. That is permutation coverage, not duplication — legitimate when each row's path class yields a different outcome. Same edge and same path class twice is a duplicate.
• Collapse reconverged paths. Where the outcome does not depend on which upstream branch was taken, one row covers them all; write the path as the reconvergence point (or any), never the route. Naming state the outcome does not depend on manufactures a false permutation.
• An edge with no row is a coverage hole; a scenario with no nameable edge is not acceptance and does not belong in the suite.

Three columns make the shape legible at a glance: a Path column reading any is a convergence claim (the outcome does not vary), and an edge repeated with different paths shows exactly which distinctions the contract cares about. The grouping keeps coverage visible per use case — an uncovered surface is a hole, not a silent gap in prose. check-suite lints it. A @pinned behavior the CFG did not reach enters as a seed the agent grows the CFG around, adding the discovered edges to the map.

On backfill — draw the CFG and the scenario map, don't stop at Use Cases

When the implementation already exists (a backfill), the four sections are still mandatory. Read the source, then draw the ## Control Flow CFG from the code and its 1:1 ## Scenario map — a spec that stops at ## Use Cases has named its entry points but neither the decisions the capability takes nor their coverage. The suite is re-derived from that CFG, not patched from the standing one (sdd:suite-format-governance). check-spec-structure's incomplete-node flags a behavioral leaf that skips a required section.

## References (optional — any spec-type)

Where a decision in this node rests on research or an external standard, cite it here: the source and what it backs. Not a bibliography — a line earns its place only by carrying a decision that would otherwise read as taste.

• Cite the claim, not the topic. "Vague steps produce defensive step definitions carrying flags, so a Given must be buildable — [source]" beats "see [source] on BDD".
• External sources only. A sibling spec, a design/ model doc, or a governance is a normal in-body reference, not a research citation.
• Optional and rare. Most nodes decide from the domain and cite nothing. An empty section is omitted, never stubbed.
• Not the design record. A chosen-vs-rejected design fork belongs in the unit's <unit>.solution.md; ## References records the evidence consulted, which outlives the fork.

It is the last section, after ## Scenario map (or after ## Subject on a reference artifact). Reason: a reader wants the contract first and the provenance only when they question it.

Plain language — a gate requirement, not a nicety

spec.md is reviewed at the gate, so plain language is a bar it must clear. Write so a smart reader with no domain context follows it on the first read:

• Simplify the writing, never the domain. Domain concepts are essential — define each in plain words, never drop one to sound simpler. Jargon, long sentences, and unexplained acronyms are accidental — drive them to zero.
• Lead with the plain word, keep the specialized term as a parenthetical ("safe to repeat (idempotent)"); carry a Key terms glossary when the spec leans on several.
• Short sentences, concrete over abstract. Draw a diagram wherever it beats prose; format with headings, tables, and callouts for the load-bearing decisions.

The same bar binds the suite's scenarios — plain Given/When/Then the same reader can follow. Enrichment (diagrams, formatting) is spec.md only; the suite stays plain Gherkin.

Key points (read-check)

1. Four sections in order — ## What (overview + non-goals), ## Use Cases, ## Control Flow, ## Scenario map — plus an optional ## References last, citing research that backs a decision (the claim it supports, not the topic).
2. A use case is actor + goal + entry point + extensions, named to its impl surface (CLI verb / function / endpoint) — spec, suite, and code share one screaming structure. No extensions is a claim, stated explicitly. Every surface element traces to a use case that needs it, with its forbidden combinations named; an element no use case needs is an orphan — cut it or justify it.
3. The CFG is shared — use cases enter it (many-to-one); section by sub-graph only when the decision logic genuinely differs.
4. The scenario map is 1:1 and grouped by use case — coverage visible per use case; check-suite lints it.
5. A @pinned behavior enters as a seed the agent grows the CFG around.
6. Plain language is a gate bar — a reader with no domain context follows the spec (and its suite) on first read; define every term, simplify the writing not the domain.