Designs are compared between a base commit and the working tree at entry grain

actor

A reviewer or an agent starting the next design pass over a Pack, holding the commit the last pass read.

problem

A line diff of the carriers shows edits but not which Specs, entries, questions and relations changed, so each pass re-reads the whole Pack to find what moved.

outcome

Show what changed in a design between a base commit and the working tree, down to the Spec, section and keyed entry, so a reviewer reads what changed since the last pass.

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

The design diff compares a base graph with the current graph.

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

A comparison is a catalog recipe that takes the graph sdp build wrote at the base commit as a recipe parameter and compares it with the graph the evaluation derives from the working tree, including uncommitted edits; it adds no verb or binding.

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

The base graph is input the caller holds, derived from the repository alone at the base commit; it never answers in the graph's name, and the comparison writes nothing.

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

The caller always names the base. The recipe reads no record of a design pass and keeps none, and a corpus that notes which commit a pass read keeps that note outside the graph.

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

Two graphs written by different engine versions are compared on what both carry; the result reports each side's schema version, and a difference is a diagnostic in the result, never a refusal.

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

It reports the Specs added and removed, and for a Spec present in both graphs the changes to its title, kind, altitude, stated readiness, relations, narrative and each section.

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

Inside the Design and UI sections, the open questions and other keyed sections apart from rules and flows, it compares keyed entries by key and reports each as added, removed, changed in value or moved in order.

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

Rule and flow entries match first by unchanged text, preferring the same key for repeated wording, then by retained key; remaining unkeyed base entries pair in list order, including an entry reworded while adding a key. An unmatched keyed base entry is removed, and an unmatched head entry is added. Other unkeyed entries have no identity across the two graphs and compare as part of their whole section.

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

A rule or flow with unchanged text whose key was added, removed or changed is one keyed change naming its old and new address, or none; only a text change is changed. An unchanged entry moving between rules and flows is moved; when one graph keeps no order across rules and flows, keyed entries compare by order within each list and a ruleOrder diagnostic names the Spec.

rule line 37 · specs/consumers/design-diff.sdp.md:37

It reports changes to Pack membership, member order and what a Pack's order means, and to the code units, verifiers and delivery facts bound to each Spec, kept apart from the authored changes because they derive from anchors.

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

A comparison states facts about the two graphs and confers nothing. It grants no approval, raises no staleness flag, moves no readiness and never records that a pass happened.

11 unkeyed rules.

diffRecipe line 42 · specs/consumers/design-diff.sdp.md:42

recipe 35, the design diff, takes params.base, the graph object sdp build wrote at the base commit, an optional params.pack that limits the comparison to the Specs that are members of that Pack at either commit, and params.detail; it compares params.base with the graph binding and reads nothing else.

diffShape line 43 · specs/consumers/design-diff.sdp.md:43

{ base: { schemaVersion, specs }, head: { schemaVersion, specs }, diagnostics, totals, specs: { added: [id], removed: [id], changed }, packs, bindings, leftOut }, where totals counts each list and diagnostics lists schema-version differences, parts outside the common schema, a Pack absent from both graphs, and Specs compared without order across rules and flows; base.specs and head.specs count the Specs of the comparison scope present on each side, the scope being every Spec or, with pack, the Pack's members in either graph, while the top-level specs object carries the change lists.

no citation recorded

changedSpecRow line 44 · specs/consumers/design-diff.sdp.md:44

{ id, parts: [part] } in the summary and { id, parts: [{ part, change, from, to }] } with detail: true; change is added, removed, changed, moved or keyed. For keyed, from and to carry the old and new entry addresses, null meaning none; other changes carry the values on each side, a rule or flow value as { list, text }. A text change while adding a key is one changed entry.

no citation recorded

diffParts line 45 · specs/consumers/design-diff.sdp.md:45

a part is title, specKind, altitude, statedReadiness, narrative, relation.<type>:<target>, a keyed entry as design.<key>, ui.<key>, question.<key>, rule.<key> or term.<term>, an unkeyed rule or flow as behavior.rules[<index>] or behavior.flows[<index>], using its head index; a removed unkeyed entry uses its base index with a (base) mark, such as behavior.rules[1] (base), so it cannot share a name with a head entry at that index; an unkeyed question list as intent.openQuestions, and any other section as its name.

movedEntry line 46 · specs/consumers/design-diff.sdp.md:46

a keyed entry whose value is unchanged and whose position among the keyed entries of its section changed is moved; an entry whose value changed is changed whatever its position. For rules and flows, unchanged text with a different key takes keyed precedence, then a list change or relative order change among retained entries is moved; anonymous entries compare order within their list. Adding or removing a key alone moves no other entry.

packRows line 47 · specs/consumers/design-diff.sdp.md:47

packs rows are { id, change, membersAdded, membersRemoved, reordered, orderChanged, orderBefore, orderAfter } for each Pack added, removed or changed in membership, member order or order meaning; orderBefore and orderAfter are "reading" or "priority", null on a side where the Pack is absent, and orderChanged is true when both sides hold the Pack and the two differ. An absent order reads as "reading" in every schema version; a value the head's engine does not know is outside the common schema, listed in diagnostics and not compared; that Pack's membership and member order still compare, its orderChanged is false, and the side holding the unknown value reads null. membersAdded and membersRemoved keep their respective manifest order.

no citation recorded

bindingRows line 48 · specs/consumers/design-diff.sdp.md:48

bindings rows are { id, implementedBy, referencedBy, verifiers, deliveryFacts }, each an { added, removed } pair of ids or fact names, kept apart from specs because they derive from anchors.

no citation recorded

baseRecipe line 49 · specs/consumers/design-diff.sdp.md:49

The catalog shows how to derive the base graph in a worktree at the base commit with the corpus's exclusions. When constant-form anchors use relative engine imports, as in this repository, run the base worktree's own engine, then pass its generated/graph.json as base and remove the worktree.

Verifier bindings

• test:protocol.design-diff-recipe · anchored · test anchor binding present · test/iteration-recipes.test.ts:34

  External run evidence from test/iteration-recipes.test.ts

  Test anchors: test:protocol.context-bundle-recipe, test:protocol.design-diff-recipe, test:protocol.perspective-filter-recipe, test:protocol.proposal-schema-and-recipe. Specs verified by those bindings: spec:consumers.context-bundle, spec:consumers.design-diff, spec:consumers.intent-composition.proposal, spec:consumers.review-perspectives.

  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

  Name	Suite	Result	Duration
  compares keyed values, keyed order and unkeyed sections while keeping bindings apart	iteration loop: design diff	passed	72.53 ms
  compares question fields by key, whole unkeyed questions, envelope fields and other sections	iteration loop: design diff	passed	30.62 ms
  reports added and removed Specs and Packs, filters the union of membership, and ignores source lines	iteration loop: design diff	passed	40.64 ms
  diagnoses required input and schema differences and compares common content	iteration loop: design diff	passed	12.84 ms
  runs the documented base-worktree procedure, preserves constant anchors, and compares HEAD	iteration loop: design diff	passed	24191.88 ms
  compares a keyed rule that becomes a flow at the same address	iteration loop: design diff	passed	40.12 ms
  compares new Design entries across schema versions when the base corpus has none	iteration loop: design diff	passed	20.7 ms
  diagnoses uncertain optional fields at base 0.9.0 and head 0.9.0	iteration loop: design diff	passed	12.31 ms
  diagnoses uncertain optional fields at base 0.9.0 and head 0.10.0	iteration loop: design diff	passed	14.37 ms
  diagnoses uncertain optional fields at base 0.10.0 and head 0.9.0	iteration loop: design diff	passed	25.38 ms
  normalizes legacy rule markers in graphs with comparable rule-key capability	iteration loop: design diff	passed	14.26 ms
  invents no order across rules and flows from a legacy base	iteration loop: design diff	passed	24.92 ms
  compares a legacy base's keyed entries by order within each list	iteration loop: design diff	passed	28.06 ms
  reports proposal scopes outside the common schema as incomparable	iteration loop: design diff	passed	13.58 ms
  lists all authored reasons into and out of the planning subject in type/from/to order	relation reasons in planning recipes	passed	19.97 ms
  keeps dependency reasons in context-bundle footing	relation reasons in planning recipes	passed	9.01 ms
  matches every declared selector, combines requirements, and keeps authored order unless prioritized	iteration loop: perspective filter	passed	55.16 ms
  matches layers and contexts only through named bindings and keeps anchored matches apart	iteration loop: perspective filter	passed	32.84 ms
  reports malformed and unsupported selectors while applying understood ones	iteration loop: perspective filter	passed	33.17 ms
  keeps term addresses, term lines and key maps through the section cut	iteration loop: context bundle	passed	26.54 ms
  keeps questions and declarations in one place and member-example steps only in their member row	iteration loop: context bundle	passed	19.18 ms
  takes the declaration cut last only with addresses and keeps compact pointers and links	iteration loop: context bundle	passed	77.64 ms
  cuts a pinned dotted key to its line when it has no entry address	iteration loop: context bundle	passed	46.93 ms
  composes both scopes, dependency footing, declarations, example bindings and a perspective subset	iteration loop: context bundle	passed	24.38 ms
  takes all six whole-mode cuts in fixed order and counts the complete returned value including Unicode	iteration loop: context bundle	passed	45.42 ms
  keeps a pinned declaration whole through the sixth cut when its key contains a dot	iteration loop: context bundle	passed	18.09 ms
  reports invalid, missing, doubled and unknown scopes without a partial bundle	iteration loop: context bundle	passed	39.62 ms
  accepts term scopes and detects changed definitions through their authored keys	iteration loop: proposal schema and check	passed	27.58 ms
  holds the schema and recipe to the same accepted and refused documents	iteration loop: proposal schema and check	passed	115.66 ms
  checks the complete scope union, resolves both graphs, and reports each change independently	iteration loop: proposal schema and check	passed	18.38 ms
  agrees with recipe 35 on added, removed and changed entry values and on whole-Spec changes	iteration loop: proposal schema and check	passed	28.57 ms
  excludes anchor-only changes and requires the caller's base graph	iteration loop: proposal schema and check	passed	29.83 ms
  compares interleaved keyed rules and flows in their authored order and reports verifier changes apart	iteration loop: comparison and budget edges	passed	31.26 ms
  cuts example text once and preserves compact pointers after the sixth cut	iteration loop: comparison and budget edges	passed	32.28 ms
  reads the base graph and proposal from named JSON files through the real parameter seam	iteration loop: comparison and budget edges	passed	9.74 ms
  requires a test bound directly to an example before the bundle names it enabled	iteration loop: example enablement	passed	15.3 ms
  compares rule order by text and other anonymous collections as a whole	iteration loop: anonymous collection order	passed	25.17 ms
  keeps addresses in each place when narrative, example, question and section text are cut	iteration loop: protected entry addresses	passed	56.27 ms

• test:protocol.roadmap-priority · checks Pack priority extraction, comparison and Studio change notes · anchored · test anchor binding present · test/roadmap-priority.test.ts:44

  External run evidence from test/roadmap-priority.test.ts

  Test anchors: test:protocol.roadmap-priority. Specs verified by those bindings: spec:carrier.markdown-pack-authoring, spec:consumers.design-diff, spec:consumers.spec-studio.diff-page, spec:consumers.spec-studio.pack-page, spec:extraction.pack-member-order, spec:model.pack-aggregate.

  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

  Name	Suite	Result	Duration
  derives equal Markdown and TypeScript Pack nodes and edges, serializes order last, and exposes it through the reader	roadmap priority manifest	passed	47.3 ms
  refuses the invalid Markdown value reading	roadmap priority manifest	passed	1.58 ms
  refuses the invalid Markdown value arbitrary	roadmap priority manifest	passed	1.33 ms
  refuses the invalid Markdown value true	roadmap priority manifest	passed	1.28 ms
  refuses the invalid Markdown value null	roadmap priority manifest	passed	1.65 ms
  refuses the invalid Markdown value []	roadmap priority manifest	passed	1.21 ms
  refuses the invalid Markdown value {}	roadmap priority manifest	passed	1.24 ms
  refuses the invalid TypeScript value "reading"	roadmap priority manifest	passed	3.6 ms
  refuses the invalid TypeScript value "arbitrary"	roadmap priority manifest	passed	2.76 ms
  refuses the invalid TypeScript value true	roadmap priority manifest	passed	3.43 ms
  refuses the invalid TypeScript value null	roadmap priority manifest	passed	3.5 ms
  refuses the invalid TypeScript value []	roadmap priority manifest	passed	2.87 ms
  refuses the invalid TypeScript value {}	roadmap priority manifest	passed	3.83 ms
  refuses the invalid TypeScript value undefined	roadmap priority manifest	passed	2.78 ms
  refuses the invalid TypeScript value chosenOrder	roadmap priority manifest	passed	3.35 ms
  names a removed Pack by its order meaning (priority true)	roadmap priority design diff	passed	14.29 ms
  names a removed Pack by its order meaning (priority false)	roadmap priority design diff	passed	12.82 ms
  names an added roadmap and preserves manifest order in its member delta	roadmap priority design diff	passed	17.33 ms
  labels Pack membership by its order meaning (priority true)	roadmap priority design diff	passed	8.11 ms
  labels Pack membership by its order meaning (priority false)	roadmap priority design diff	passed	5.46 ms
  states order values when a change is not a known roadmap transition	roadmap priority design diff	passed	4.7 ms
  documents the order comparison fields, default and diagnostic in the recipe contract	roadmap priority design diff	passed	1.09 ms
  compares a priority transition to true without a membership edit	roadmap priority design diff	passed	3.05 ms
  compares a priority transition to false without a membership edit	roadmap priority design diff	passed	2.22 ms
  reads an absent order as reading order in a base schema that predates the field	roadmap priority design diff	passed	7.31 ms
  marks the absent side of an added or removed roadmap as null (true)	roadmap priority design diff	passed	2.44 ms
  marks the absent side of an added or removed roadmap as null (false)	roadmap priority design diff	passed	2.06 ms
  diagnoses an unknown order at the base without reporting an order change	roadmap priority design diff	passed	1.69 ms
  diagnoses an unknown order at the head without reporting an order change	roadmap priority design diff	passed	1.71 ms
  still compares membership and member order when the base order is unknown	roadmap priority design diff	passed	2.58 ms
  still compares membership and member order when the head order is unknown	roadmap priority design diff	passed	6.34 ms
  keeps an order-only change in the selected Pack's comparison scope	roadmap priority design diff	passed	3.01 ms
  shows no roadmap transition for a membership-only change (priority true)	roadmap priority design diff	passed	7.93 ms
  shows no roadmap transition for a membership-only change (priority false)	roadmap priority design diff	passed	6.63 ms
  shows the roadmap transition to true on the diff and Pack pages	roadmap priority design diff	passed	8.43 ms
  shows the roadmap transition to false on the diff and Pack pages	roadmap priority design diff	passed	6.96 ms

Requirement drawing

• Declared verifying examples: no declared verifying example.

Decisions

• A roadmap states advisory priority in the graph

  A roadmap is a Pack whose manifest states order: priority; its members' authored order is the corpus's advisory priority, first entry first. order is an optional manifest field whose one lawful value is priority, and a Pack without it keeps the reading order every Pack has. Priority is preference among bodies of work and nothing more: it carries no date, no dependency, no status and no gate, and no check, recipe or page treats a place on a roadmap as permission, obligation or sequence. Everything a roadmap shows about an entry, what it still needs and what holds it, is read from the graph each time. A corpus may keep several roadmaps, and a Spec may be listed on any number of them.

• impl:protocol.design-diff-recipe · realizes the design diff in the shipped recipe catalog · test/iteration-recipes.test.ts:27

  Uses

  None.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.