Spec Studio

Markdown is the default Spec carrier

spec:decisions.carrier-rulingDecision 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/carrier-ruling.sdp.md

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

Intent
outcome
Give every Spec kind one readable canonical authoring surface without losing a lawful escape hatch.
Decision
context
The carrier must express all Spec kinds without creating an unbounded tooling obligation or a dual-source truth path.
decision
Specs default to Markdown; Packs remain TS until a Pack syntax ruling; the TS DSL survives as import source and a lawful per-ID option. Later refinements keep this default and the one-surface law without repealing them: the Pack syntax ruling completes Pack Markdown, and the Gherkin carrier option admits graph-aware Gherkin as a lawful per-ID option for behavior and example Specs only, with the canonical suffix settled as .sdp.gherkin.
rationale
  • An owned grammar and a permanent kind split both add surface cost without a demonstrated expressive gain, while retiring the DSL removes a useful bounded option. Bounding Gherkin to behavior and example Specs preserves the same trade-off — a second parser only where BDD-native readability earns it — rather than pretending every kind has a natural Gherkin shape.
consequences
  • Each ID has one canonical surface, and Markdown tooling is the default path for authored Specs.
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.carrier-ruling

Arrows: refines (declared).

The diagram as text
  • spec:decisions.carrier-ruling: Markdown is the default Spec carrier · declared Spec
  • spec:decisions.gherkin-carrier-option: Behavior and example Specs may use Gherkin canonically · declared Spec
  • spec:decisions.pack-markdown-carrier: Packs have a Markdown manifest carrier · declared Spec
  • spec:carrier.markdown-authoring: Markdown authoring enters the one graph · declared Spec
  • spec:decisions.carrier-universality: Carrier universality is bounded by honest kind structure · declared Spec
  • spec:decisions.roadmap-priority: A roadmap states advisory priority in the graph · declared Spec
  • spec:decisions.sdp-gherkin-extension: Canonical Gherkin carriers use .sdp.gherkin · declared Spec
  • spec:decisions.carrier-ruling refines spec:carrier.markdown-authoring · 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.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.pack-markdown-carrier refines spec:decisions.carrier-ruling · declared — extends the Markdown carrier to Packs and keeps the TypeScript builder as a per-ID option
  • spec:decisions.roadmap-priority refines spec:decisions.pack-markdown-carrier · declared — opens the closed Pack manifest envelope to one optional field, `order`
  • 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.carrier-ruling
The diagram as text
  • spec:carrier.markdown-authoring: Markdown authoring enters the one graph
  • spec:carrier.markdown-body-grammar: The Markdown body accepts one closed form per section
  • spec:carrier.markdown-pack-authoring: A Pack has a Markdown manifest carrier
  • spec:carrier.sdp-import: A TypeScript-carried Spec can be converted to Markdown
  • spec:decisions.carrier-ruling: Markdown is the default Spec carrier
  • spec:decisions.gherkin-carrier-option: Behavior and example Specs may use Gherkin canonically
  • spec:decisions.pack-markdown-carrier: Packs have a Markdown manifest carrier
  • spec:decisions.carrier-ruling refines spec:carrier.markdown-authoring · declared
  • spec:carrier.markdown-authoring decidedBy spec:decisions.carrier-ruling · declared
  • spec:carrier.markdown-body-grammar decidedBy spec:decisions.carrier-ruling · declared
  • spec:carrier.sdp-import decidedBy spec:decisions.carrier-ruling · declared
  • spec:carrier.markdown-pack-authoring dependsOn spec:decisions.carrier-ruling · declared
  • 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.pack-markdown-carrier refines spec:decisions.carrier-ruling · declared — extends the Markdown carrier to Packs and keeps the TypeScript builder as a per-ID option
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

Relations

Relation and directionOther endClaimReasonExercised keys
refines · outgoingMarkdown authoring enters the one graph
spec:carrier.markdown-authoring · resolves		declaredNoneNone
decidedBy · incomingMarkdown authoring enters the one graph
spec:carrier.markdown-authoring · resolves		declaredNoneNone
decidedBy · incomingThe Markdown body accepts one closed form per section
spec:carrier.markdown-body-grammar · resolves		declaredNoneNone
decidedBy · incomingA TypeScript-carried Spec can be converted to Markdown
spec:carrier.sdp-import · resolves		declaredNoneNone
dependsOn · incomingA Pack has a Markdown manifest carrier
spec:carrier.markdown-pack-authoring · resolves		declaredNoneNone
refines · incomingBehavior and example Specs may use Gherkin canonically
spec:decisions.gherkin-carrier-option · resolves		declaredadmits Gherkin as a canonical per-ID carrier for behavior and example Specs beside the Markdown defaultNone
refines · incomingPacks have a Markdown manifest carrier
spec:decisions.pack-markdown-carrier · resolves		declaredextends the Markdown carrier to Packs and keeps the TypeScript builder as a per-ID optionNone

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.