Design Review renders graph context without becoming a gate

outcome

Give a human a regenerable, contextual view for deciding how to state readiness without recording approval as graph truth.

rule line 25 · specs/consumers/design-review.sdp.md:25

The Design Review renders a Spec or a Pack in context with its readiness, relations, bindings, authored open questions, verifier coverage gaps on Pack pages, and findings, all read from the graph.

rule line 26 · specs/consumers/design-review.sdp.md:26

The review is a pure projection that resolves through ordinary source edits, git, and conformance checks; it stores no findings and writes no canonical source.

rule line 27 · specs/consumers/design-review.sdp.md:27

A human may use the review context when stating readiness, while validators check only the structural readiness floor and never record or require review approval.

rule line 28 · specs/consumers/design-review.sdp.md:28

The view is deterministic generated Markdown with an index and pages for Specs and Packs; richer visual representations remain outside this behavior.

rule line 29 · specs/consumers/design-review.sdp.md:29

The page set is a function of the graph alone — it carries no timestamp, no commit, and no run identity — so two renders of the same corpus are byte-identical.

rule.linkTargets line 30 · specs/consumers/design-review.sdp.md:30

A link target percent-encodes each path segment and keeps directory separators and line fragments.

no example exercises it

rule.fieldEscaping line 31 · specs/consumers/design-review.sdp.md:31

Prose and table fields escape Markdown's structural characters.

no example exercises it

rule.openSectionList line 32 · specs/consumers/design-review.sdp.md:32

Each entry of a design or ui section renders as a list item in authored order with its key as inline code; a structured value renders as fenced JSON under its item.

no example exercises it

rule.inlineCode line 33 · specs/consumers/design-review.sdp.md:33

Inline code uses a backtick delimiter longer than any backtick run inside the value.

no example exercises it

rule line 34 · specs/consumers/design-review.sdp.md:34

An open question that carries a key opens with the key as inline code, #<key>, before its text.

rule line 35 · specs/consumers/design-review.sdp.md:35

A Spec page lists the code units that realize the Spec and, apart, the units that reference it, each with its file and line, its role and, for a component, its layer and context; a reference confers no implementation binding.

rule line 36 · specs/consumers/design-review.sdp.md:36

The renderer reads the reader and returns pages; writing them is the caller's job.

rule.portablePublication line 38 · specs/consumers/design-review.sdp.md:38

A case-insensitive page-path collision refuses the publisher's whole page set, names both ids and paths, removes its stale live and temporary roots when their parents are safe, and exits 1 regardless of validation's exit code. Renderers retain their page names and bytes.

no example exercises it

rule.safeCleanup line 39 · specs/consumers/design-review.sdp.md:39

Publication and failure cleanup recheck the physical output parent before each mutation; an escaping, unresolvable or linked generated/ parent is refused without cleanup through it.

no example exercises it

8 unkeyed rules.

Verifying examples

Given an extraction root holding a Pack, its member Specs, and one member the checks warn about
When the Design Review renders the graph derived from that root
Then the page set holds the index page {indexPage: "index.md"}, one page per Spec, and one page per Pack
Then the page {packPage: "pack/orders-v1.md"} renders its members in context
Then the page {specPage: "spec/orders.create-order.empty-cart.md"} renders the finding {findingId: "conformance/verifies-linkage"} as data
Then a second render from a freshly derived graph is byte-identical: {byteIdentical: true}
Then the render leaves the extraction root byte-identical: {rootUntouched: true}

Example space

Given an extraction root holding a Pack, its member Specs, and one member the checks warn about
When the Design Review renders the graph derived from that root
Then the page set holds the index page {indexPage:string}, one page per Spec, and one page per Pack
Then the page {packPage:string} renders its members in context
Then the page {specPage:string} renders the finding {findingId:string} as data
Then a second render from a freshly derived graph is byte-identical: {byteIdentical:boolean}
Then the render leaves the extraction root byte-identical: {rootUntouched:boolean}

The generated Design Review exposes three page anatomies from the same graph.

specPage line 44 · specs/consumers/design-review.sdp.md:44

A Spec page presents descriptors, the narrative, readiness, bindings, the authored sections, relations and findings in one context.

packPage line 45 · specs/consumers/design-review.sdp.md:45

A Pack page presents the Pack's design as its child spec:consumers.design-review.pack-design-page states.

Cited at

• test/recipes.test.ts:3657

indexPage line 46 · specs/consumers/design-review.sdp.md:46

The index holds one Markdown table of Specs, a linked list of Packs and the findings table, with stable links into each page.

Verifier bindings

• spec:consumers.design-review.pure-projection · The view is the graph read twice, and the corpus is untouched by reading it · declared · example enabled · specs/consumers/design-review.pure-projection.sdp.md

  External run evidence from test/self-hosting-projections.test.ts

  Test anchors: test:protocol.binding-language-views.bound-spec-page, test:protocol.binding-language-views.pack-member-table, test:protocol.derived-readiness-banner.dishonest-divergence, test:protocol.derived-readiness-banner.honest-headroom, test:protocol.derived-readiness-banner.idea-floor-unmet, test:protocol.design-review.pure-projection, test:protocol.diagnostic-rendering.composed-location, test:protocol.diagnostic-rendering.table-cell-location, test:protocol.wholesale-view-rewrite.build-invalidates-view, test:protocol.wholesale-view-rewrite.failed-run-view-removed, test:protocol.wholesale-view-rewrite.late-stale-page, test:protocol.wholesale-view-rewrite.stale-page-removed. Specs verified by those bindings: spec:consumers.binding-language-views, spec:consumers.binding-language-views.bound-spec-page, spec:consumers.binding-language-views.pack-member-table, spec:consumers.derived-readiness-banner, spec:consumers.derived-readiness-banner.dishonest-divergence, spec:consumers.derived-readiness-banner.honest-headroom, spec:consumers.design-review, spec:consumers.design-review.pure-projection, spec:consumers.wholesale-view-rewrite, spec:consumers.wholesale-view-rewrite.build-invalidates-view, spec:consumers.wholesale-view-rewrite.failed-run-view-removed, spec:consumers.wholesale-view-rewrite.late-stale-page, spec:consumers.wholesale-view-rewrite.stale-page-removed, spec:validation.diagnostic-rendering, spec:validation.diagnostic-rendering.composed-location, spec:validation.diagnostic-rendering.table-cell-location.

  Run 1: external run evidence from vitest 4.1.10

  Build: CI 433 · Branch: fix/second-review-pass · Commit: 6375b6e431a7cf885a49befec76d7876cd3e538c · Start: 2026-11-04T07:12:23.076Z · Stop: 2026-11-04T07:15:49.695Z

  Name	Suite	Result	Duration
  executes the bound example against a fresh world	The view is the graph read twice, and the corpus is untouched by reading it (spec:consumers.design-review.pure-projection)	passed	141.87 ms
  executes the bound example against a fresh world	An overstated rung raises the banner and names the clause that refused (spec:consumers.derived-readiness-banner.dishonest-divergence)	passed	3.19 ms
  executes the bound example against a fresh world	A rung the structure overshoots renders as information, not as a banner (spec:consumers.derived-readiness-banner.honest-headroom)	passed	1.81 ms
  renders a Spec whose idea floor is unmet with no rung and a below-idea banner	not recorded	passed	1.26 ms
  executes the bound example against a fresh world	A fully bound Spec renders binding language on the page and in the index (spec:consumers.binding-language-views.bound-spec-page)	passed	2.81 ms
  executes the bound example against a fresh world	The Pack member table speaks the page's binding language, not a shorthand (spec:consumers.binding-language-views.pack-member-table)	passed	2.98 ms
  executes the bound example against a fresh world	A page from an earlier run does not survive the next one (spec:consumers.wholesale-view-rewrite.stale-page-removed)	passed	17.79 ms
  executes the bound example against a fresh world	A page the build's invalidation never saw still does not survive the swap (spec:consumers.wholesale-view-rewrite.late-stale-page)	passed	10.96 ms
  executes the bound example against a fresh world	A run that cannot produce a current view leaves no view at all (spec:consumers.wholesale-view-rewrite.failed-run-view-removed)	passed	6.92 ms
  executes the bound example against a fresh world	A build that never renders still takes the old view down (spec:consumers.wholesale-view-rewrite.build-invalidates-view)	passed	9.25 ms
  executes the bound example against a fresh world	One finding, three location shapes, one composition rule (spec:validation.diagnostic-rendering.composed-location)	passed	1.13 ms
  executes the bound example against a fresh world	The same three location shapes, rendered as table cells (spec:validation.diagnostic-rendering.table-cell-location)	passed	0.73 ms

• test:protocol.cli-write-boundaries · anchored · test anchor binding present · test/cli-write-boundaries.test.ts:292

  External run evidence from test/cli-write-boundaries.test.ts

  Test anchors: test:protocol.cli-write-boundaries. Specs verified by those bindings: spec:consumers.design-review, spec:consumers.gherkin-view, spec:consumers.mermaid-view, spec:consumers.projections-model, spec:consumers.wholesale-view-rewrite, spec:extraction.build-pipeline.

  Run 1: external run evidence from vitest 4.1.10

  Build: CI 433 · Branch: fix/second-review-pass · Commit: 6375b6e431a7cf885a49befec76d7876cd3e538c · Start: 2026-11-04T07:12:23.076Z · Stop: 2026-11-04T07:15:49.695Z

  Name	Suite	Result	Duration
  replaces a stale 'symbolic' link at 'graph.json' without touching its target	build write boundaries	passed	67.45 ms
  replaces a stale 'hard' link at 'graph.json' without touching its target	build write boundaries	passed	13.17 ms
  replaces a stale 'symbolic' link at 'imports.json' without touching its target	build write boundaries	passed	18.95 ms
  replaces a stale 'hard' link at 'imports.json' without touching its target	build write boundaries	passed	10.38 ms
  replaces a stale 'symbolic' link at 'registrars.json' without touching its target	build write boundaries	passed	19.24 ms
  replaces a stale 'hard' link at 'registrars.json' without touching its target	build write boundaries	passed	12.84 ms
  routes a successful build's ordinary removals and writes through the filesystem hooks	build write boundaries	passed	19.14 ms
  names an unresolvable output parent when generated is a dangling link	build write boundaries	passed	1.24 ms
  refuses a staging link planted after stale removal	build write boundaries	passed	4.94 ms
  build refuses an escaping generated parent before writing or cleanup	build write boundaries	passed	5.03 ms
  view refuses an escaping generated parent before writing or cleanup	build write boundaries	passed	4.29 ms
  census refuses an escaping generated parent before writing or cleanup	build write boundaries	passed	4.86 ms
  mermaid refuses an escaping generated parent before writing or cleanup	build write boundaries	passed	4.19 ms
  gherkin refuses an escaping generated parent before writing or cleanup	build write boundaries	passed	6.19 ms
  studio refuses an escaping generated parent before writing or cleanup	build write boundaries	passed	4.04 ms
  generate refuses an escaping generated parent before writing or cleanup	build write boundaries	passed	3.87 ms
  vault refuses an escaping generated parent before writing or cleanup	build write boundaries	passed	5.04 ms
  stamp refuses an escaping generated parent before writing or cleanup	build write boundaries	passed	11.13 ms
  keeps the named root in ordinary command output	explicit symlinked watch root	passed	5.6 ms
  validate starts and reruns through the named root	explicit symlinked watch root	passed	17.86 ms
  studio starts and reruns through the named root	explicit symlinked watch root	passed	88.19 ms
  vault starts and reruns through the named root	explicit symlinked watch root	passed	35.65 ms
  view refuses case-colliding pages and removes stale output	portable projection publication	passed	10.23 ms
  mermaid refuses case-colliding pages and removes stale output	portable projection publication	passed	7.15 ms
  gherkin refuses case-colliding pages and removes stale output	portable projection publication	passed	10.32 ms
  stamp replaces a symbolic link without modifying its target	publication boundary regressions	passed	4.1 ms
  stamp replaces a hard link without modifying its target	publication boundary regressions	passed	3.74 ms
  a stamp that fails after staging leaves no staging file in the page set	publication boundary regressions	passed	1.83 ms
  view recovery preserves outside output after a parent swap	publication boundary regressions	passed	6.23 ms
  census recovery preserves outside output after a parent swap	publication boundary regressions	passed	6.21 ms
  mermaid recovery preserves outside output after a parent swap	publication boundary regressions	passed	5.59 ms
  gherkin recovery preserves outside output after a parent swap	publication boundary regressions	passed	5.64 ms
  studio recovery preserves outside output after a parent swap	publication boundary regressions	passed	5.11 ms
  vault recovery preserves outside output after a parent swap	publication boundary regressions	passed	5 ms
  generate recovery preserves outside output after a parent swap	publication boundary regressions	passed	6.75 ms
  build refuses inside-link generated identity	publication boundary regressions	passed	2.93 ms
  build refuses replaced-directory generated identity	publication boundary regressions	passed	2.58 ms
  vault refuses a default vault linked outside the root but allows an explicit outside vault	publication boundary regressions	passed	9.03 ms
  generate refuses a default vault linked outside the root but allows an explicit outside vault	publication boundary regressions	passed	23.26 ms
  vault holds a default vault linked inside the root to the placement rules where it resolves	publication boundary regressions	passed	11.29 ms
  generate holds a default vault linked inside the root to the placement rules where it resolves	publication boundary regressions	passed	28.31 ms
  projection suite refuses a linked generated parent (check-clean: false)	publication boundary regressions	passed	65.78 ms
  projection suite refuses a linked generated parent (check-clean: true)	publication boundary regressions	passed	47.87 ms
  package artifacts unlink stale staging links and refuse linked recipe directories	publication boundary regressions	passed	1.5 ms
  package artifacts refuse a linked recipe directory before stale cleanup	not recorded	passed	0.78 ms
  watch leaves outside bytes unchanged after direct-empty parent swap	not recorded	passed	12.49 ms
  watch leaves outside bytes unchanged after direct-managed parent swap	not recorded	passed	15.69 ms
  watch leaves outside bytes unchanged after checkout-empty parent swap	not recorded	passed	77.25 ms
  watch leaves outside bytes unchanged after checkout-managed parent swap	not recorded	passed	117.05 ms
  watch leaves outside bytes unchanged after studio-direct parent swap	not recorded	passed	12.8 ms

Requirement drawing

Decisions

• Bindings are optional, plural, and may reference a design

  On a code anchor, satisfies is optional and plural; on a test anchor, verifies is plural and non-empty. The constant form accepts one ref(…) or a fresh array literal of them. Each resolving target confers its fact, and implemented stays a whole-Spec fact. An anchored edge references runs from a CodeNode to a Spec, from references?: readonly SpecId[] on a code anchor; it may target any Spec, decisions included, confers no delivery fact, moves no readiness floor, and the drift alarm ignores it. It says this code answers to that design without claiming to realize it: the unit follows the design without realizing any of its promises, or realizes part of a Spec whose remaining promises no unit yet realizes, so a change to the design asks the code to follow. A design that builds on existing code states that by a typed relation to the Spec the code satisfies, never by a reference from the code. A target named in both satisfies and references is an error. An identity-only code anchor, with no satisfies and no references, is lawful: it mints a CodeNode for structure and for byFile, and nothing else.

• Architectural significance is annotated where it is realized

  Architectural significance is annotated on the anchor of the unit that realizes it. A code anchor may carry role, the architectural pattern the unit plays; a component: anchor may additionally carry layer, one of edge, application, domain, adapter, or infrastructure, and context, its bounded context. The component: anchor is anchored architecture: it is the declared component, and there is no separate architecture file, because the anchor sits where the component is realized. It is not the original design's declared Component that could exist before code; an unrealized component lives in Specs and never as an invented CodeNode. A role is a free, corpus-owned vocabulary whose taxonomy the census renders with counts from the graph; service, decider, projection, read-model, codec, contract, barrel, and utility are the lineage set, not a closed list. layer is a closed set, and a value outside it is an envelope error; layer or context on a non-component anchor is an envelope error. All three attributes are optional, and omission is lawful.

• The Design Review renders open-section entries as a list

  The Design Review renders each entry of a design or ui section as a list item in authored order, its key as inline code. A string value renders as Markdown text through the prose escaping rule; a number or boolean renders as inline code; an array or object renders as a fenced JSON block nested under its item, so a structured value the TypeScript carrier admits survives without loss. The fenced-JSON rule of the Design Review stops covering an open section as a whole and keeps covering a structured value inside one entry. The freeze on the four shipped projections stands for everything else.

• The Design Review shows an open question's key

  The Design Review renders an open question that carries a key with the key as inline code, #<key>, at the start of its item, before the question's text; a question without a key renders as its text. The freeze on the four shipped projections stands for everything else.

• The shipped projections stay frozen

  Re-specifying the shipped Design Review, census, Mermaid, or Gherkin projection is refused. These four projections are the ruled read surfaces over the one graph. A later decision Spec that supersedes this one replaces the ruling whole; a decision Spec that refines this one narrows it for one projection or one rendering and leaves the rest frozen. Either passes the ADR three-part test.

• component:protocol.projections · read-only output, layout and owned publication · src/projections/design-review.ts:29 · layer edge · context protocol

  Uses

  • component:protocol.extract · the carrier and source pipeline · src/extract/index.ts:197 · layer application · context protocol
  • component:protocol.graph · the one graph and its semantic decisions · src/graph/schema.ts:34 · layer domain · context protocol
  • component:protocol.model · the authored contracts and stable ids · src/model/anchors.ts:100 · layer domain · context protocol
  • component:protocol.notation · the leaf step codec · src/notation/slots.ts:263 · layer domain · context protocol
  • component:protocol.reader · the typed graph contract and body evaluator · src/reader/reader.ts:697 · layer application · context protocol
  • component:protocol.validate · one finding currency and ordered checks · src/validate/validators.ts:76 · layer domain · context protocol
• impl:protocol.design-review · renders the contextual Design Review projection · src/projections/design-review.ts:44

  Component: component:protocol.projections · read-only output, layout and owned publication · src/projections/design-review.ts:29 · layer edge · context protocol

  Uses

  None.

• impl:protocol.design-review-codec · shared Design Review Markdown paths and links · src/projections/design-review-markdown.ts:3

  Component: component:protocol.projections · read-only output, layout and owned publication · src/projections/design-review.ts:29 · layer edge · context protocol

  Uses

  None.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.