Spec Studio

Behavior and example Specs may use Gherkin canonically

spec:decisions.gherkin-carrier-optionDecision Record · featureready floor ready

Packs: pack:self-hosting-v1

Design: no design entries · no pinned declarations · no decisions

Findings: no errors, no warnings

specs/decisions/gherkin-carrier-option.sdp.md

No open questions and no blocking questions; implementation binding none, verifier binding none, and expected-outcome oracle none.

Intent
outcome
Admit stakeholder-readable BDD authoring without creating a second graph truth or moving execution into authored intent.
Decision
context
Markdown remains a complete default carrier, but executable behavior and example Specs repeat their Given/When/Then structure in code-side handlers; the restored v0 design and gen-1 production record show that a Gherkin surface improves stakeholder readability while still requiring separate executing code.
decision
A behavior or example Spec ID may select a graph-aware Gherkin carrier as a lawful canonical per-ID option. Markdown remains the default, each ID has exactly one canonical surface with no mixing, and Gherkin derives the existing graph shape and executes only through generated contracts plus anchored code-side handlers. Its syntax maps onto the existing envelope, sections, relations, and notation; it creates no parallel lifecycle status or tag registry.
rationale
  • BDD-native readability is worth one bounded carrier pipeline when the one-graph boundary, generated-contract execution path, and binding-only verifier trace remain unchanged; restricting the option to behavior and example Specs avoids pretending Gherkin is a natural carrier for every kind.
consequences
  • The Gherkin pipeline parses deterministically, keeps physical source locations, derives the graph a Markdown carrier of the same Spec would, lints its vocabulary, and fails loudly.
  • A Gherkin scenario does not confer has-verifier; only the existing resolving anchored verifies trace enables it, and runner pass state remains outside the graph.
  • Gen-1 value-transfer deletion, authored completion status, and an independent tag taxonomy are explicitly not imported.
  • The canonical discovered suffix is settled separately as .sdp.gherkin (MD-28); this option does not itself choose a file extension, flip the default carrier, or extend kind coverage.
alternatives
  • Keeping Markdown as the only default authoring path avoids a second parser but retains the stakeholder-readable duplication established by the executable-verification review.
  • Deriving more of the test wrapper can reduce mechanical code independently, but does not provide a BDD-native canonical artifact.
Verification

Verifier bindings

No verifier binding recorded.

Design view

Requirement drawing

  • Declared verifying examples: no declared verifying example.
  • Test or oracle bindings: no recorded binding.
Requirement drawing for spec:decisions.gherkin-carrier-option
The diagram as text
  • spec:decisions.gherkin-carrier-option: Behavior and example Specs may use Gherkin canonically · declared Spec
  • spec:decisions.carrier-universality: Carrier universality is bounded by honest kind structure · declared Spec
  • spec:decisions.sdp-gherkin-extension: Canonical Gherkin carriers use .sdp.gherkin · declared Spec
  • spec:decisions.carrier-ruling: Markdown is the default Spec carrier · declared Spec
  • impl:protocol.gherkin-kind-policy: shared Gherkin kind-refusal and loss explanations · anchored code · src/extract/gherkin-kind-honesty.ts:6
  • spec:decisions.carrier-universality refines spec:decisions.gherkin-carrier-option · declared — settles the admitted description prose and the meaning of universality as a generated read projection, while reaffirming the behavior and example kind bound
  • spec:decisions.gherkin-carrier-option refines spec:decisions.carrier-ruling · declared — admits Gherkin as a canonical per-ID carrier for behavior and example Specs beside the Markdown default
  • spec:decisions.sdp-gherkin-extension refines spec:decisions.gherkin-carrier-option · declared — fixes the canonical Gherkin suffix as .sdp.gherkin and keeps bare .feature files out of discovery
  • impl:protocol.gherkin-kind-policy references spec:decisions.carrier-universality · anchored
Mermaid source

Copyable source; the Studio draws static SVG.

Preferred syntax: requirementDiagram. Chosen syntax: flowchart TB because references require exact labels unavailable in requirement syntax.

Decisions

No decision record named.

Runtime

No implementation neighborhood recorded.

Runtime observation: not tracked.

Evidence

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

Impact
Relations of spec:decisions.gherkin-carrier-option
The diagram as text
  • spec:carrier.gherkin-authoring: Gherkin authoring enters the one graph
  • spec:decisions.carrier-ruling: Markdown is the default Spec carrier
  • spec:decisions.carrier-universality: Carrier universality is bounded by honest kind structure
  • spec:decisions.gherkin-carrier-option: Behavior and example Specs may use Gherkin canonically
  • spec:decisions.sdp-gherkin-extension: Canonical Gherkin carriers use .sdp.gherkin
  • spec:decisions.gherkin-carrier-option refines spec:decisions.carrier-ruling · declared — admits Gherkin as a canonical per-ID carrier for behavior and example Specs beside the Markdown default
  • spec:carrier.gherkin-authoring decidedBy spec:decisions.gherkin-carrier-option · declared
  • spec:decisions.carrier-universality refines spec:decisions.gherkin-carrier-option · declared — settles the admitted description prose and the meaning of universality as a generated read projection, while reaffirming the behavior and example kind bound
  • spec:decisions.sdp-gherkin-extension refines spec:decisions.gherkin-carrier-option · declared — fixes the canonical Gherkin suffix as .sdp.gherkin and keeps bare .feature files out of discovery
Mermaid source

Copyable source; the Studio draws static SVG.

Preferred syntax: flowchart. Chosen syntax: labelled flowchart, preserving exact relations, claims and folds.

Rests on

Rested on by

Distance 1

Distance 2

Distance 3

Distance 4

Distance 5

Distance 6

Distance 7

Distance 8

Relations

Relation and directionOther endClaimReasonExercised keys
refines · outgoingMarkdown is the default Spec carrier
spec:decisions.carrier-ruling · resolves		declaredadmits Gherkin as a canonical per-ID carrier for behavior and example Specs beside the Markdown defaultNone
decidedBy · incomingGherkin authoring enters the one graph
spec:carrier.gherkin-authoring · resolves		declaredNoneNone
refines · incomingCarrier universality is bounded by honest kind structure
spec:decisions.carrier-universality · resolves		declaredsettles the admitted description prose and the meaning of universality as a generated read projection, while reaffirming the behavior and example kind boundNone
refines · incomingCanonical Gherkin carriers use .sdp.gherkin
spec:decisions.sdp-gherkin-extension · resolves		declaredfixes the canonical Gherkin suffix as .sdp.gherkin and keeps bare .feature files out of discoveryNone

Bindings

Implementation binding: none

Design reference: none

Verifier binding: none

Expected-outcome oracle: none

Runtime observation: not tracked.

Run results: not recorded in the graph.

Findings

None.

Composing (0)

Composing needs the script.