Spec Studio

Canonical Gherkin carriers use .sdp.gherkin

spec:decisions.sdp-gherkin-extensionDecision 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/sdp-gherkin-extension.sdp.md

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

Intent
outcome
Keep graph-aware Gherkin Specs discoverable by the Protocol without colliding with default Cucumber runner globs.
Decision
context
The Gherkin carrier option admits a BDD-native surface for behavior and example Specs, but does not settle the file suffix. Bare .feature keeps default editor and Cucumber tooling recognition, yet matches ordinary runner globs and therefore risks treating Protocol carriers as executable Cucumber tests. A compound Protocol suffix mirrors the .sdp.ts collision-safety law and gives discovery a unique, content-free signal.
decision
Canonical graph-aware Gherkin Specs use the .sdp.gherkin suffix. Discovery is suffix-only: .sdp.gherkin files are Gherkin carriers, and bare .feature files are not. Bare .feature remains non-canonical territory for import sources, foreign corpora, and historical lineage, never a second live canonical surface. This ruling does not change which Spec kinds may choose Gherkin, does not flip the default carrier away from Markdown, and does not admit dual-suffix discovery or content sniffing.
rationale
  • Collision safety outranks default editor recognition when choosing a suffix that becomes costly to change after adoption. Compound extensions already identify Markdown and TypeScript carriers without test-glob collisions; applying the same pattern to Gherkin keeps one discovery walk honest. Teams that want highlighting can associate *.sdp.gherkin with Gherkin in the editor, while Cucumber's default *.feature globs stay clear of Protocol carriers.
consequences
  • Extractors, CLI empty-corpus diagnostics, copy rules, fixtures, and authoring guidance treat .sdp.gherkin as the only discovered Gherkin carrier suffix.
  • Ordinary .feature files beside a corpus neither enter the graph nor poison extraction; they stay import-source and foreign-corpus material until an explicit import adapter says otherwise.
  • Default editor and formatter recognition for bare .feature is not inherited; consumers configure a *.sdp.gherkin association when they want Gherkin highlighting or formatting.
alternatives
  • Keeping bare .feature as canonical would preserve stock Gherkin tooling out of the box, but would keep Protocol carriers inside default Cucumber globs and invite false execution of authored intent.
  • Accepting both .feature and .sdp.gherkin would create a dual-suffix window, split discovery, and weaken the one-canonical-surface law the carrier rulings already enforce.
Verification

Verifier bindings

No verifier binding recorded.

Design view

Requirement drawing

  • Declared verifying examples: no declared verifying example.
  • Satisfying or referencing units: no recorded binding.
  • Test or oracle bindings: no recorded binding.
Requirement drawing for spec:decisions.sdp-gherkin-extension

Arrows: refines (declared).

The diagram as text
  • spec:decisions.sdp-gherkin-extension: Canonical Gherkin carriers use .sdp.gherkin · declared Spec
  • spec:decisions.gherkin-carrier-option: Behavior and example Specs may use Gherkin canonically · declared Spec
  • 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 and chosen syntax: requirementDiagram; exact refines, satisfies and verifies, with claim words in nodes and per-edge comments.

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.sdp-gherkin-extension
The diagram as text
  • spec:carrier.gherkin-authoring: Gherkin authoring enters the one graph
  • 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.sdp-ts-extension: Spec extensions identify the carrier without colliding with tests
  • spec:decisions.sdp-gherkin-extension dependsOn spec:decisions.sdp-ts-extension · declared
  • 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
  • spec:carrier.gherkin-authoring decidedBy spec:decisions.sdp-gherkin-extension · declared
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
dependsOn · outgoingSpec extensions identify the carrier without colliding with tests
spec:decisions.sdp-ts-extension · resolves		declaredNoneNone
refines · outgoingBehavior and example Specs may use Gherkin canonically
spec:decisions.gherkin-carrier-option · resolves		declaredfixes the canonical Gherkin suffix as .sdp.gherkin and keeps bare .feature files out of discoveryNone
decidedBy · incomingGherkin authoring enters the one graph
spec:carrier.gherkin-authoring · resolves		declaredNoneNone

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.