Every verb answers --help, and one verb writes every projection root

actor

An adopter, or an agent working for one, at the command line or in CI.

problem

A verb refuses --help instead of explaining itself, and no public verb publishes every projection root at once, so an adopter runs the publishers one by one and is left with only the last one's root.

outcome

Let every verb explain itself through --help, and let one verb write every projection root from one graph in one run.

rule.verbHelp line 31 · specs/consumers/command-line.sdp.md:31

Every verb answers --help: when --help is among a verb's arguments, the verb prints its help on standard output and exits 0, reading no other argument, deriving no graph and touching no file, a projection root included.

spec:consumers.command-line.verb-help-touches-nothing · enabled

rule.oneHelpText line 32 · specs/consumers/command-line.sdp.md:32

A verb's help opens with its usage and its paragraph from the top-level help, the same text, so a verb's help and sdp --help never disagree; only the scaffolder's help, for sdp new and sdp new spec, adds a paragraph of its own after that text.

spec:consumers.command-line.verb-help-touches-nothing · enabled

rule.generateVerb line 33 · specs/consumers/command-line.sdp.md:33

sdp generate [root] [--exclude PATH]... [--vault DIR] [--check-clean] enters the shared build once, validates the graph, synchronizes the vault, and writes all five projection roots from that one graph: the Design Review, the census, the Mermaid diagrams, the Gherkin-shaped view and the Studio.

spec:consumers.command-line.generate-writes-every-root · enabled

rule.sameBytes line 34 · specs/consumers/command-line.sdp.md:34

Each root the verb writes holds the bytes its own publisher writes from the same graph, written wholesale through its temporary sibling as that publisher writes it.

spec:consumers.command-line.generate-writes-every-root · enabled

rule.generateExit line 35 · specs/consumers/command-line.sdp.md:35

Findings never withhold a root: the verb writes all five and exits with the validation exit code, and a graph that does not derive writes no root and exits 1.

spec:consumers.command-line.generate-writes-every-root · enabled

rule.generateCheck line 36 · specs/consumers/command-line.sdp.md:36

With --check-clean, the verb applies to each root the check its publisher applies under --check-clean, to renders of the one graph; a root that fails its check is removed, the others are written, and the run exits 1.

spec:consumers.command-line.generate-check-failure · enabled

0 unkeyed rules.

Verifying examples

Given an extraction root holding two authored Specs and {roots: "five current projection roots, one stale page planted in the census root"}
When the command {command: "sdp generate --check-clean"} runs at that root
Then the command exits {exitCode: 1}
Then the stale pages survive: {staleSurvive: false}
Then the roots holding the current pages for those Specs are {currentRoots: "design-review, mermaid, gherkin, spec-studio"}
Then the absent projection roots are {absentRoots: "census"}

Given an extraction root holding two authored Specs and {roots: "a stale page in each of the five projection roots"}
When the command {command: "sdp generate"} runs at that root
Then the command exits {exitCode: 0}
Then the stale pages survive: {staleSurvive: false}
Then the roots holding the current pages for those Specs are {currentRoots: "design-review, census, mermaid, gherkin, spec-studio"}
Then the absent projection roots are {absentRoots: ""}

Given an extraction root holding two authored Specs and {roots: "a stale page in each of the five projection roots"}
When the command {command: "sdp view --help"} runs at that root
Then the command exits {exitCode: 0}
Then the stale pages survive: {staleSurvive: true}
Then the roots holding the current pages for those Specs are {currentRoots: ""}
Then the absent projection roots are {absentRoots: ""}
Then standard output opens with the line {firstLine: "Usage:"}

Example space

Given an extraction root holding two authored Specs and {roots:"a stale page in each of the five projection roots"|"five current projection roots, one stale page planted in the census root"}
When the command {command:"sdp generate"|"sdp generate --check-clean"|"sdp view --help"} runs at that root
Then the command exits {exitCode:number}
Then the stale pages survive: {staleSurvive:boolean}
Then the roots holding the current pages for those Specs are {currentRoots:string}
Then the absent projection roots are {absentRoots:string}
Then standard output opens with the line {firstLine:string}

helpVerbs line 39 · specs/consumers/command-line.sdp.md:39

build, validate, view, census, mermaid, gherkin, studio, vault, stamp, generate, import, new and q answer --help.

no citation recorded

verbHelpText line 40 · specs/consumers/command-line.sdp.md:40

Usage: on its own line, then the verb's usage lines as sdp --help writes them, a blank line and the verb's paragraph from the Commands: list of sdp --help; sdp new --help and sdp new spec --help then add a blank line and the scaffolder's own paragraph on what PATH takes and what the scaffold writes.

no citation recorded

generateRoots line 41 · specs/consumers/command-line.sdp.md:41

in this order, generated/design-review/, generated/census/, generated/mermaid/, generated/gherkin/ and generated/spec-studio/.

generateOutput line 42 · specs/consumers/command-line.sdp.md:42

the build and validation summary lines once, then the vault's Wrote <out>/sdp (…) line unless --check-clean, then the line each publisher prints for its root, in the order of the roots.

vaultRoot line 43 · specs/consumers/command-line.sdp.md:43

the verb never removes a vault with the five roots; before it publishes any root it synchronizes the vault at the folder sdp vault uses for the same root, or at --vault DIR, resolved against the working directory, through the vault's own directory checks and guard, and a refusal there writes no root and exits 1; under --check-clean it leaves the vault alone, since the vault has no check mode and its tests hold its determinism.

Verifier bindings

• spec:consumers.command-line.generate-check-failure · A root that fails its check is removed while sdp generate writes the others · declared · example enabled · specs/consumers/command-line.generate-check-failure.sdp.md

  External run evidence from test/self-hosting-command-line.test.ts

  Test anchors: test:protocol.command-line.generate-check-failure, test:protocol.command-line.generate-writes-every-root, test:protocol.command-line.verb-help-touches-nothing. Specs verified by those bindings: spec:consumers.command-line, spec:consumers.command-line.generate-check-failure, spec:consumers.command-line.generate-writes-every-root, spec:consumers.command-line.verb-help-touches-nothing.

  Run 1: external run evidence from vitest 4.1.10

  Build: CI 380 · Branch: feature/roadmap-and-slices-v0 · Commit: 34909918bf0be0e849959644401797191cae379f · Start: 2026-10-22T17:40:31.456Z · Stop: 2026-10-22T17:42:16.171Z

  Name	Suite	Result	Duration
  executes the bound example against a fresh world	One run of sdp generate leaves all five roots current (spec:consumers.command-line.generate-writes-every-root)	passed	101.27 ms
  executes the bound example against a fresh world	A root that fails its check is removed while sdp generate writes the others (spec:consumers.command-line.generate-check-failure)	passed	68 ms
  executes the bound example against a fresh world	A publisher's --help prints its help and touches no root (spec:consumers.command-line.verb-help-touches-nothing)	passed	1.61 ms

• spec:consumers.command-line.generate-writes-every-root · One run of sdp generate leaves all five roots current · declared · example enabled · specs/consumers/command-line.generate-writes-every-root.sdp.md
• spec:consumers.command-line.verb-help-touches-nothing · A publisher's --help prints its help and touches no root · declared · example enabled · specs/consumers/command-line.verb-help-touches-nothing.sdp.md

Requirement drawing

Decisions

• The shipped projections stay frozen

  Re-specifying the shipped Design Review, census, Mermaid, or Gherkin projection is refused. These four projections are the ruled read surfaces over the one graph. A later decision Spec that supersedes this one replaces the ruling whole; a decision Spec that refines this one narrows it for one projection or one rendering and leaves the rest frozen. Either passes the ADR three-part test.

• component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:32 · layer edge · context protocol

  Uses

  • component:protocol.adapters · external runtime and source adapters · src/adapters/vitest.ts:23 · layer adapter · context protocol
  • component:protocol.codegen · contracts and registrar output · src/codegen/contracts.ts:633 · layer application · context protocol
  • component:protocol.extract · the carrier and source pipeline · src/extract/index.ts:192 · layer application · context protocol
  • component:protocol.graph · the one graph and its semantic decisions · src/graph/schema.ts:34 · layer domain · context protocol
  • component:protocol.import · canonical conversion with a fidelity boundary · src/import/import.ts:45 · layer application · context protocol
  • component:protocol.model · the authored contracts and stable ids · src/model/anchors.ts:100 · layer domain · context protocol
  • component:protocol.projections · read-only output, layout and owned publication · src/projections/design-review.ts:29 · layer edge · context protocol
  • component:protocol.reader · the typed graph contract and body evaluator · src/reader/reader.ts:671 · layer application · context protocol
  • component:protocol.validate · one finding currency and ordered checks · src/validate/validators.ts:72 · layer domain · context protocol
• impl:protocol.adopter-help · SDP_HELP_TEXT indexes the shipped skills, recipe catalog, schema, walkthrough, glossary and specs/ by package-relative path · src/cli/help.ts:167

  Component: component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:32 · layer edge · context protocol

  Uses

  None.

• impl:protocol.agent-surface-cli · CLI verb dispatcher and agent-surface front of the package CLI · src/cli/sdp.ts:94

  Component: component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:32 · layer edge · context protocol

  Uses

  None.

• impl:protocol.build-args · shared build arguments and corpus-rule inputs · src/cli/build-args.ts:11

  Component: component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:32 · layer edge · context protocol

  Uses

  None.

• impl:protocol.generate-command · prepares all prior roots before one shared build and publishes with each verb's checks · src/cli/generate-command.ts:34

  Component: component:protocol.cli · entry points, shared build and publication · src/cli/build-command.ts:32 · layer edge · context protocol

  Uses

  None.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.