Spec Studio

Packs have a Markdown manifest carrier

spec:decisions.pack-markdown-carrierDecision 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/pack-markdown-carrier.sdp.md

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

Intent
outcome
Give every Pack one readable canonical authoring surface without losing the TypeScript manifest as a lawful per-ID option.
Decision
context
The carrier ruling left Packs on TypeScript until a real need forced a syntax ruling; the authored Pack manifests supplied that need, and a second suffix or a body-list membership would invent a second discovery walk or a second membership owner.
decision
A Pack's Markdown carrier is a .sdp.md file routed by the pack: envelope id namespace, closed to id · specs · modelRefs, with the H1 as title and remaining prose as framing; the TypeScript pack() builder stays a lawful per-ID option and the import source.
rationale
  • Discovery already walks .sdp.md, so routing by namespace reuses the one walk instead of minting a .pack.md suffix. Closing the envelope to the same fields the TypeScript manifest already owns keeps one Pack node shape. Refusing ## headings preserves the no-section-tier law. Membership as a YAML list keeps the manifest the sole owner of belongsTo rather than promoting body prose into identity.
consequences
  • Markdown and TypeScript manifests of the same Pack derive the identical Pack node, the file field aside, and identical belongsTo edges.
  • The same Pack id authored in both carriers remains the standing duplicate-id refusal.
  • sdp import stays Spec-only and does not convert Pack manifests.
alternatives
  • A distinct .pack.md suffix would split discovery and pretend the carrier ruling had already chosen a Pack surface.
  • Membership as a body list would give Packs a section tier the TypeScript shape does not have and would split identity between envelope and prose.
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.pack-markdown-carrier
The diagram as text
  • spec:decisions.pack-markdown-carrier: Packs have a Markdown manifest carrier · declared Spec
  • spec:decisions.roadmap-priority: A roadmap states advisory priority in the graph · declared Spec
  • spec:decisions.carrier-ruling: Markdown is the default Spec carrier · declared Spec
  • spec:decisions.planning-truths-placement: Planning truths live in ruled graph homes · declared Spec
  • impl:protocol.pack-aggregate: Pack aggregate and model references · anchored code · src/model/pack.ts:23
  • impl:protocol.pack-member-order: keeps manifest member order on the Pack node · anchored code · src/extract/derive.ts:153
  • 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.roadmap-priority refines spec:decisions.planning-truths-placement · declared — narrows the refusal of recorded work order for one case, the advisory priority of a roadmap
  • impl:protocol.pack-aggregate references spec:decisions.roadmap-priority · anchored
  • impl:protocol.pack-member-order references spec:decisions.roadmap-priority · 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.pack-markdown-carrier
The diagram as text
  • spec:carrier.gherkin-authoring: Gherkin authoring enters the one graph
  • spec:carrier.markdown-pack-authoring: A Pack has a Markdown manifest carrier
  • spec:decisions.carrier-ruling: Markdown is the default Spec carrier
  • spec:decisions.carrier-universality: Carrier universality is bounded by honest kind structure
  • spec:decisions.pack-markdown-carrier: Packs have a Markdown manifest carrier
  • spec:decisions.roadmap-priority: A roadmap states advisory priority in the graph
  • 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:carrier.gherkin-authoring decidedBy spec:decisions.pack-markdown-carrier · declared
  • spec:carrier.markdown-pack-authoring decidedBy spec:decisions.pack-markdown-carrier · declared
  • spec:decisions.carrier-universality dependsOn spec:decisions.pack-markdown-carrier · declared — leaves the Pack carrier to its separate syntax ruling
  • spec:decisions.roadmap-priority refines spec:decisions.pack-markdown-carrier · declared — opens the closed Pack manifest envelope to one optional field, `order`
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

Relations

Relation and directionOther endClaimReasonExercised keys
refines · outgoingMarkdown is the default Spec carrier
spec:decisions.carrier-ruling · resolves		declaredextends the Markdown carrier to Packs and keeps the TypeScript builder as a per-ID optionNone
decidedBy · incomingGherkin authoring enters the one graph
spec:carrier.gherkin-authoring · resolves		declaredNoneNone
decidedBy · incomingA Pack has a Markdown manifest carrier
spec:carrier.markdown-pack-authoring · resolves		declaredNoneNone
dependsOn · incomingCarrier universality is bounded by honest kind structure
spec:decisions.carrier-universality · resolves		declaredleaves the Pack carrier to its separate syntax rulingNone
refines · incomingA roadmap states advisory priority in the graph
spec:decisions.roadmap-priority · resolves		declaredopens the closed Pack manifest envelope to one optional field, orderNone

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.