Spec Studio

A Spec id written in prose is a checked mention

spec:decisions.checked-mentionsDecision Record · featureready floor ready

Packs: pack:adopter-speed-v1, pack:self-hosting-v1

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

Findings: no errors, no warnings

specs/decisions/checked-mentions.sdp.md

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

Intent
outcome
Make a Spec id written in prose resolve, and make one keyed entry of an open section, one keyed open question, one keyed entry of the primary behavior owner, or one keyed Model term addressable, so a reference below the Spec level can be checked.
Decision
context
Specs name other Specs, and single entries of them, in prose. Referential integrity reads edges and Pack references only. A prose id that does not resolve passes validation, a mention that no relation backs hides a dependent from blast radius, and finding every Spec that repeats an entry is a text search. The first adopter corpus carried its design as keyed entries, and most of its prose mentions had no declared relation.
decision
A Spec id in narrative or section text, outside gwt and gwt-vocabulary fences, is a mention. A mention that does not resolve is a conformance error. A mention of another Spec that shares no declared relation with the mentioning Spec, in either direction, is one warning per mentioning Spec and target Spec pair, whatever the number of locations; an address on the mentioning Spec's own id is checked for its entry and never warned. An entry address is a Spec id followed by #, the section name design, ui, question, rule, or term, a dot, and the entry's lower-camel ASCII key, as in spec:<id>#design.<key> or spec:<id>#question.<key>. A design or ui address resolves when the Spec exists and that section holds the key as its own key, other than description; a question address resolves when the Spec exists and one of its open questions carries that key; a term address resolves when the Spec exists and one of its Model terms carries that key. The # sub-part is reserved for the entry address in every namespace: a Spec's own id, a relation target, a Pack member or model reference, an anchor id or target, and the specId and ref builders all refuse it. A mention mints no edge, and the reader gains no join.
rationale
  • The warning asks for a relation that already exists, so linkage keeps one home. A relation in either direction backs a mention because blast radius walks its one hop both ways, so a reverse edge already surfaces the dependent. One warning per pair keeps the report readable where a Spec names one neighbor in many bullets, and the mention audit keeps every location.
  • This applies the content-only sections ruling rather than contradicting it. A mention mints no edge, so no consumer branches on a reference union, and the warning names the double-linkage drift the earlier ruling left legal and silent. The id grammar already parses and formats a # sub-part; this record gives it its only meaning, and the dot inside the sub-part is the one grammar change.
  • The owner ruled that an open question may carry an optional key in its marker, as in - [blocking #aggregateReach] text, addressed as spec:<id>#question.aggregateReach. The key grammar is the Design key grammar, a key is unique among one Spec's open questions, and an unkeyed question stays lawful. A register that cites a question by its position breaks silently when a question above it moves or closes, and the first adopter's register had drifted in such citations; a key breaks loudly where it is renamed.
  • The owner ruled that the address carries the section, because open-section keys are unique within a section and not within a Spec, so spec:<id>#design.shared and spec:<id>#ui.shared stay distinct when one carrier holds both; that # is refused in every identity, because neither this corpus nor the first adopter's carries one, and one meaning per sub-part keeps resolution a lookup instead of a precedence rule; and that one lower-camel key grammar serves every carrier, so an address is typeable from memory and a lawful TypeScript key outside it is simply unaddressable.
  • A Model term carries an authored key in a marker that opens its definition, as a rule carries its own, addressed through the segment term. A key derived from the term would break every address whenever the term is reworded, and the segment names the kind of entry, as question and rule do. The ratified glossary stays a document, so its terms gain no address; a term gains one where a Spec defines it.
alternatives
  • A new edge type for mentions costs the schema, the edge contract, the census, the Mermaid view, and every recipe that filters edges. The warning reaches the same dependents through relations that exist.
  • Leaving the check to each adopter's own lint fixes one corpus and no other.
  • A positional address for an unkeyed bullet, such as the third flow of a Workflow, was refused. Positions move with every edit above them, so such an address would break silently where a key breaks loudly.
  • Refusing a key that appears under both Design and UI would shorten the address and make one section's keys depend on the other's. Refused by the owner.
  • Letting an identity with # outrank an address would retain the earlier identity grammar and make every address resolution a two-step lookup for a case no corpus has. Refused by the owner.
  • Warning only on a missing forward relation would turn a parent's mention of its own child into a finding the child's refines edge already answers. Refused by the owner.
consequences
  • Keyed Design and UI entries, keyed open questions, keyed entries of the primary behavior owner and keyed Model terms are addressable, a rule address resolving when the Spec's behavior.ruleKeys carries the key and a term address when its model.termKeys does. Unkeyed entries have no address; a reference to one stays a Spec-level mention, and a sequence that must be addressed is authored as keyed entries.
  • The key description names the leading prose of a design or ui section and is never an entry there, so a design or ui address ending in .description never resolves. A question key is a value on the question, not a property beside section prose, so description is an ordinary question key. A TypeScript key outside the lower-camel ASCII grammar is lawful and has no address.
  • A renamed or removed open-section key, question key, rule key or term key fails validation in every Spec that addresses it.
  • Blast radius and delta review scope include a mentioning Spec once a declared relation backs its mention.
  • A family pattern written in id form reads as an unresolved mention, so such a pattern is written as plain words.
  • No reference check detects two Specs that restate one shape in their own words. The check narrows that defect class and never closes it.
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.checked-mentions

Arrows: refines (declared).

The diagram as text
  • spec:decisions.checked-mentions: A Spec id written in prose is a checked mention · declared Spec
  • spec:model.stable-ids: Stable IDs are the Protocol's durable join key · declared Spec
  • spec:decisions.checked-mentions refines spec:model.stable-ids · declared
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.checked-mentions
The diagram as text
  • spec:consumers.agent-surface.address-and-cycle-recipes: Address resolution and dependency cycles stay executable graph recipes
  • spec:decisions.checked-mentions: A Spec id written in prose is a checked mention
  • spec:decisions.content-only-sections: Sections carry content while relations carry links
  • spec:model.open-question-keys: An open question may carry a key that addresses it
  • spec:model.rule-keys: A rule or flow entry may carry a key that addresses it
  • spec:model.stable-ids: Stable IDs are the Protocol's durable join key
  • spec:model.term-addresses: A Model term may carry a key that addresses it
  • spec:validation.prose-mentions: Every Spec id written in prose resolves
  • spec:decisions.checked-mentions dependsOn spec:decisions.content-only-sections · declared
  • spec:decisions.checked-mentions refines spec:model.stable-ids · declared
  • spec:model.open-question-keys decidedBy spec:decisions.checked-mentions · declared
  • spec:model.rule-keys decidedBy spec:decisions.checked-mentions · declared — rule addresses join the address law it rules
  • spec:model.stable-ids decidedBy spec:decisions.checked-mentions · declared
  • spec:model.term-addresses decidedBy spec:decisions.checked-mentions · declared — a term address joins the address law that decision rules
  • spec:validation.prose-mentions decidedBy spec:decisions.checked-mentions · declared
  • spec:consumers.agent-surface.address-and-cycle-recipes dependsOn spec:decisions.checked-mentions · 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

Distance 9

Distance 10

Relations

Relation and directionOther endClaimReasonExercised keys
dependsOn · outgoingSections carry content while relations carry links
spec:decisions.content-only-sections · resolves		declaredNoneNone
refines · outgoingStable IDs are the Protocol's durable join key
spec:model.stable-ids · resolves		declaredNoneNone
decidedBy · incomingAn open question may carry a key that addresses it
spec:model.open-question-keys · resolves		declaredNoneNone
decidedBy · incomingA rule or flow entry may carry a key that addresses it
spec:model.rule-keys · resolves		declaredrule addresses join the address law it rulesNone
decidedBy · incomingStable IDs are the Protocol's durable join key
spec:model.stable-ids · resolves		declaredNoneNone
decidedBy · incomingA Model term may carry a key that addresses it
spec:model.term-addresses · resolves		declareda term address joins the address law that decision rulesNone
decidedBy · incomingEvery Spec id written in prose resolves
spec:validation.prose-mentions · resolves		declaredNoneNone
dependsOn · incomingAddress resolution and dependency cycles stay executable graph recipes
spec:consumers.agent-surface.address-and-cycle-recipes · 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.