Spec Studio

Specs declare typed directed relations

spec:model.relationsDomain Model · featureready floor ready

Packs: pack:self-hosting-v1

Design: no design entries · no pinned declarations · 1 decision

Findings: no errors, no warnings

specs/model/relations.sdp.md

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

Intent
outcome
Preserve the explicit intent links that make a delivery model navigable and queryable.
Model
authored relation line 18 · specs/model/relations.sdp.md:18
A declared, directed Spec-to-Spec edge that records human intent.
refines line 19 · specs/model/relations.sdp.md:19
A more precise child points to its parent; refinement is how altitude descends, and a decision that narrows one part of another decision refines it.
dependsOn line 20 · specs/model/relations.sdp.md:20
A dependent Spec points to the Spec it needs.
constrainedBy line 21 · specs/model/relations.sdp.md:21
A bounded Spec points to its rule, constraint, or policy Spec.
decidedBy line 22 · specs/model/relations.sdp.md:22
A shaped Spec points to its Decision Record.
typed dependency distinction line 23 · specs/model/relations.sdp.md:23
constrainedBy and decidedBy preserve separately queryable intents that a generic dependsOn edge would flatten.
verifies line 24 · specs/model/relations.sdp.md:24
A verifier points to the Spec it verifies; an example declares it, a test anchor's binding derives it, and the two claims are never collapsed.
supersedes line 25 · specs/model/relations.sdp.md:25
A newer Decision Record points to the older record it replaces whole; the older record and the edge stay only while its text explains something a reader still needs.
Verification

Verifier bindings

  • test:protocol.relation-builders · relation builder tests verify the six declared, directed Spec relations · anchored · test anchor binding present · test/builders.test.ts:32

    External run evidence from test/builders.test.ts

    Test anchors: test:protocol.core-model, test:protocol.pack-builder, test:protocol.relation-builders. Specs verified by those bindings: spec:model.core-model, spec:model.pack-aggregate, spec:model.relations.

    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

    NameSuiteResultDuration
    enriches one Spec envelope while keeping all three coordinates independentbuilderspassed37.1 ms
    derives delivery facts directly without propagating realization through refinementbuilderspassed1.44 ms
    builds plain serializable specs with declared relationsbuilderspassed3.7 ms
    builds packs as plain manifests with no authored truth fieldsbuilderspassed0.47 ms
    builds identity-only anchors as plain serializable objectsbuilderspassed0.36 ms
Design view

Requirement drawing

  • Declared verifying examples: no declared verifying example.
Requirement drawing for spec:model.relations
Requirement drawing for spec:model.relationssatisfies · anchoredsatisfies · anchoredsatisfies · anchoredrefines · declaredrefines · declaredrefines · declaredrefines · declaredrefines · declaredverifies · anchoredverifies · anchoredverifies · anchoredIntended Specsspec:decisions.planning-truths-placementPlanning truths live inruled graph homes…decisions.planning-truths-placementdeclared Specspec:model.relation-reasonsAn authored relation maycarry its reason…model.relation-reasonsdeclared Specspec:model.relationsSpecs declare typeddirected relations…model.relationsdeclared SpecSatisfying or referencingunitsimpl:protocol.authoring-grammar-recipesasserts the authoringgrammar's realization indocs/agent-surface/recipes.mdimpl:protocol.authoring-grammar-recipesanchored codeimpl:protocol.authoring-normalizationnormalizes rule markers andquestion fields aftercarrier reification…protocol.authoring-normalizationanchored codeimpl:protocol.spec-relationsdeclared Spec relationbuilders…protocol.spec-relationsanchored codeTest or oracle bindingstest:protocol.authoring-grammarchecks rule keys, questionfields and relation reasonsacross the carriers…protocol.authoring-grammaranchored test binding ·binding presenttest:protocol.authoring-grammar-recipesexecutes the shippedquestion, mention, entry,address and rule coveragerecipestest:protocol.authoring-grammar-recipesanchored test binding ·binding presenttest:protocol.relation-buildersrelation builder testsverify the six declared,directed Spec relations…protocol.relation-buildersanchored test binding ·binding presentOutside the selected setspec:decisions.roadmap-over-plansPlan and review files stopcarrying the deliveryrecord once the roadmap andthe pull request do…decisions.roadmap-over-plansdeclared Specspec:decisions.roadmap-priorityA roadmap states advisorypriority in the graph…decisions.roadmap-prioritydeclared Specspec:model.core-modelThe Protocol modelsdelivery with oneenrichable Spec…model.core-modeldeclared Spec
The diagram as text
  • spec:model.relations: Specs declare typed directed relations · declared Spec
  • spec:decisions.planning-truths-placement: Planning truths live in ruled graph homes · declared Spec
  • spec:model.relation-reasons: An authored relation may carry its reason · declared Spec
  • spec:decisions.roadmap-over-plans: Plan and review files stop carrying the delivery record once the roadmap and the pull request do · declared Spec
  • spec:decisions.roadmap-priority: A roadmap states advisory priority in the graph · declared Spec
  • spec:model.core-model: The Protocol models delivery with one enrichable Spec · declared Spec
  • impl:protocol.authoring-grammar-recipes: asserts the authoring grammar's realization in docs/agent-surface/recipes.md · anchored code · test/recipes.test.ts:6597
  • impl:protocol.authoring-normalization: normalizes rule markers and question fields after carrier reification · anchored code · src/extract/authoring-normalization.ts:8
  • impl:protocol.spec-relations: declared Spec relation builders · anchored code · src/model/relations.ts:81
  • test:protocol.authoring-grammar: checks rule keys, question fields and relation reasons across the carriers · anchored test binding · binding present · test/authoring-grammar.test.ts:24
  • test:protocol.authoring-grammar-recipes: executes the shipped question, mention, entry, address and rule coverage recipes · anchored test binding · binding present · test/recipes.test.ts:6587
  • test:protocol.relation-builders: relation builder tests verify the six declared, directed Spec relations · anchored test binding · binding present · test/builders.test.ts:32
  • spec:decisions.planning-truths-placement refines spec:model.relations · declared
  • spec:decisions.roadmap-over-plans refines spec:decisions.planning-truths-placement · declared — narrows what a plan file may still carry once a roadmap holds priority
  • 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
  • spec:model.relation-reasons refines spec:model.relations · declared
  • spec:model.relations refines spec:model.core-model · declared
  • impl:protocol.authoring-grammar-recipes satisfies spec:model.relation-reasons · anchored
  • impl:protocol.authoring-normalization satisfies spec:model.relation-reasons · anchored
  • impl:protocol.spec-relations satisfies spec:model.relations · anchored
  • test:protocol.authoring-grammar verifies spec:model.relation-reasons · anchored
  • test:protocol.authoring-grammar-recipes verifies spec:model.relation-reasons · anchored
  • test:protocol.relation-builders verifies spec:model.relations · anchored
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

  • Planning truths live in ruled graph homes

    Each planning-truth type lives in its ruled home. Work-item dependency truth rides dependsOn edges, with independence as absence of the edge and scheduling phrases never authored. Decision gates live on decision-kind Specs, linked by decidedBy. Do-not-reopen rows split by what they carry: a tradeoff refusal becomes a decision-kind Spec, which a later decision that supersedes it replaces whole and a later decision that refines it narrows for one case, either under the ADR three-part test; a row that restates a behavior guarantee already homed on a carrying Spec stays on that Spec and changes by ordinary Spec revision; a hold stays a blocking open question on its own Spec and is never minted as a decision. A lawful non-decision stays in the plan record as evidence. A deferral carries its re-entry trigger in the trigger field of its own blocking open question, and declares dependsOn separately when a true precondition exists. Exclusive ownership is one Spec identity per deliverable with consumers depending on it. Selection-pressure heuristics are advisory only, carried as behavior rules on the graph-first planning Spec or in recipes. Session law splits separately, across behavior rules on the graph-first planning Spec, the delivery-session on-ramp's handoff rule, and the plan file. The briefs index shape is retired as a carrier of law.

Runtime
  • component:protocol.model · the authored contracts and stable ids · src/model/anchors.ts:100 · layer domain · context protocol

    Uses

    None.

  • impl:protocol.spec-relations · declared Spec relation builders · src/model/relations.ts:81

    Component: component:protocol.model · the authored contracts and stable ids · src/model/anchors.ts:100 · layer domain · context protocol

    Uses

    None.

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:model.relations
The diagram as text
  • spec:decisions.planning-truths-placement: Planning truths live in ruled graph homes
  • spec:extraction.derive-graph: Carrier reification derives the one graph
  • spec:model.core-model: The Protocol models delivery with one enrichable Spec
  • spec:model.relation-reasons: An authored relation may carry its reason
  • spec:model.relations: Specs declare typed directed relations
  • spec:validation.superseded-decision-signal: A Spec shaped by a superseded decision warns
  • spec:validation.typed-dependency-floor: A ready Spec rests only on settled dependencies
  • spec:model.relations decidedBy spec:decisions.planning-truths-placement · declared — planning truths ride these six relation types, and new relation types were refused
  • spec:model.relations refines spec:model.core-model · declared
  • spec:extraction.derive-graph dependsOn spec:model.relations · declared — the relations Spec owns the kind restrictions on authored relations
  • spec:validation.superseded-decision-signal dependsOn spec:model.relations · declared — its supersedes term keeps a replaced record only while a reader still needs its text, so the edges the signal reads are records a corpus chose to keep
  • spec:validation.typed-dependency-floor dependsOn spec:model.relations · declared
  • spec:decisions.planning-truths-placement refines spec:model.relations · declared
  • spec:model.relation-reasons refines spec:model.relations · 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

Relations

Relation and directionOther endClaimReasonExercised keys
decidedBy · outgoingPlanning truths live in ruled graph homes
spec:decisions.planning-truths-placement · resolves		declaredplanning truths ride these six relation types, and new relation types were refusedNone
refines · outgoingThe Protocol models delivery with one enrichable Spec
spec:model.core-model · resolves		declaredNoneNone
dependsOn · incomingCarrier reification derives the one graph
spec:extraction.derive-graph · resolves		declaredthe relations Spec owns the kind restrictions on authored relationsNone
dependsOn · incomingA Spec shaped by a superseded decision warns
spec:validation.superseded-decision-signal · resolves		declaredits supersedes term keeps a replaced record only while a reader still needs its text, so the edges the signal reads are records a corpus chose to keepNone
dependsOn · incomingA ready Spec rests only on settled dependencies
spec:validation.typed-dependency-floor · resolves		declaredNoneNone
refines · incomingPlanning truths live in ruled graph homes
spec:decisions.planning-truths-placement · resolves		declaredNoneNone
refines · incomingAn authored relation may carry its reason
spec:model.relation-reasons · resolves		declaredNoneNone

Bindings

Implementation binding: present

  • impl:protocol.spec-relations · declared Spec relation builders · src/model/relations.ts:81 · role contract · component component:protocol.model · layer domain · context protocol

Design reference: none

Verifier binding: present

  • test:protocol.relation-builders · relation builder tests verify the six declared, directed Spec relations · anchored · test/builders.test.ts:32 · test anchor

Expected-outcome oracle: none

Runtime observation: not tracked.

Run results: not recorded in the graph.

Findings

None.

Composing (0)

Composing needs the script.