MVP slices 1–5: the full loop — extract, bind, check, read, polish

[darko-mijic]

The MVP loop, end to end: Slices 1–5 on the Phase 0 foundation

What this PR is

Phase 0 (already on main) made the Protocol itself typed code: the Spec primitive, its three
descriptors (kind · altitude · readiness), the relation set, and the validators — plus a worked
example that typechecks. What it could not yet do was anything useful: there was no way to turn
authored specs into a graph, no binding between specs and code, no CI gate over the graph, and nothing
generated to read.

This PR builds the rest of the MVP — all five vertical slices from the roadmap
(docs/concept/07) — so the loop the concept
promises actually runs:

author delivery intent as typed Specs → bind implementing code and tests with anchors →
derive the one graph → check conformance + honesty → read the generated Design Review —
deterministically, gated in CI.

Concretely, from the repo root:

npm run build
node ./dist/cli/sdp.js view examples/checkout-v1 --check-clean

9 specs · 1 packs · 3 anchors → 13 nodes · 25 edges (0 errors, 0 warnings)
specs/orders/create-order-invalid-cart.sdp.ts — [warning] conformance/verifies-linkage —
Example "spec:orders.create-order.invalid-cart" declares verifies → "spec:orders.create-order"
but is not an enabled verifier — no test anchor binds it …
validate: 0 errors · 1 warnings (conformance + honesty over the one graph)
Wrote examples/checkout-v1/generated/design-review (11 pages)

That single warning is deliberate, and it is the project's honesty posture in one line: invalid-cart
declares that it verifies its parent, but no test anchor binds it yet — so the graph says the
spec↔test trace is incomplete instead of pretending. A surfaced absence is informative, never a gate
(the exit code stays 0).

Why it is shaped this way

Two disciplines from the concept docs drove the order of work:

• Thin vertical slices, each end-to-end on the example. No slice landed as infrastructure-only;
  each one had to extract / bind / check / render the real checkout-v1 example before it counted as
  done. The slice roadmap is docs/concept/07 §1; the per-session plans are in plans/.
• Tracer-bullet authoring. The example specs and anchored code came first, so the DSL and the
  extractor were forced to be usable before they were finished. When the example didn't extract, the
  extractor was wrong — not the example.

One structural decision from the decision log shaped the architecture more than any other: one
validation path (MD-14). Validators consume the extractor's output and nothing else — source →
static reification → graph → checks. The Phase-0 AuthoredModel stand-in harness is deleted on this
branch; validateGraph is the sole validation seam. The truth the checks see is what source
statically states, never what it happens to evaluate to on import.

What landed, slice by slice

Slice	Delivers	Where
1	the ts-morph extractor: discovers *.sdp.ts files, statically reifies specs and packs (no execution), derives nodes + declared edges, writes generated/graph.json	src/extract/
2	generic anchors: codeAnchor (impl: / api: / component:) and specTest bindings extracted from implementation and test files → satisfies / verifies edges with claim: "anchored", and the derived delivery facts (implemented / has-verifier)	src/extract/anchors.ts, src/graph/delivery-facts.ts
3	the conformance + honesty checks re-keyed onto the graph, as the CI gate: referential integrity · duplicate IDs · honest readiness against the floor · orphans · verifies linkage · authoring-shape honesty	src/validate/
4	the agent surface: the reader (a thin typed loader — joins and claim decode done once, entry adapters + file-level impact with explicit coverage-unknown items) and the Design Review (a pure, regenerable projection: index + one page per spec/pack)	src/reader/, src/projections/design-review.ts
5	polish: the CLI surface resolved (sdp build · validate · view, each subsuming the previous stage), one diagnostic rendering rule (every finding renders location-first from structured fields, failures stay to one line), the documented example walkthrough, and the clean-repo determinism test	src/cli/sdp.ts, examples/checkout-v1/README.md

The trust model ships whole

The MVP's claim is not "a spec format" — it is that the graph can be trusted. Every piece of that
posture is in this PR:

• The claim taxonomy is never collapsed. Every edge carries declared (human intent),
  anchored (a human binding from code), or inferred (machine-derived — designed-in, decoded by
  every consumer, deliberately shipping empty until the impact graph produces it). An example's own
  verifies is declared; the test anchor's is anchored; consumers can always tell which is which.
• Delivery facts are derived, never authored. implemented and has-verifier are computed from
  resolving anchor edges. Hand-authoring one is rejected twice: the closed section types refuse it at
  tsc time, and the authoring-shape honesty check refuses it at validate time even when smuggled
  past the types.
• Readiness is stated, then checked. The author states a rung; the readiness floor verifies it is
  structurally earned (kind-conditional evidence, blocking open questions, resolution clauses). The
  Design Review renders stated beside derived and the banner fires only in the dishonest direction.
• Binding, never liveness. The views render "Implementation binding: present · Verifier binding:
  present · Runtime observation: not tracked" — the graph records that a binding exists, never that
  code is live or tests passed. Pass/fail belongs to CI; liveness belongs to the deferred observed
  fact.
• Determinism is checked, not promised. --check-clean runs the full pipeline twice independently
  and fails on a single divergent byte; deleting generated/ and rebuilding is byte-identical; so is
  the pipeline run from a copy at a different absolute path. All three are pinned in the test suite,
  and npm run check:example gates CI on the first.

Hardened, not just landed

The commit history reads slice → adversarial review pass → hardening, five times over. A few of the
catches worth knowing about, because they show what the reviews were for:

• The branded-ID flavor layering was unsound. Stacking a second __brand key with disjoint unit
  types reduces the intersection to never — so tsc was enforcing nothing for the flavored anchor
  ids. Rebuilt as a proper two-layer brand, with cross-flavor assignment pins so it cannot silently
  regress.
• Parse-broken spec files now fail loudly on both surfaces (extraction summary and validate),
  instead of being silently skipped — a missing file must never look like a clean graph.
• Shadowed and default-import bindings resolve honestly in anchor extraction, so a local variable
  named like the builder cannot mint a binding.
• The example-verifier decode fails closed: one shared predicate decides "enabled verifier" for
  both the reader's decode and the derived facts, so the two surfaces cannot drift apart.
• The floor's evidence clauses are mutation-tested: fixtures pin that each clause actually flips
  the verdict, not merely that green inputs stay green.

The should-fail fixture corpus grew accordingly: test/fixtures/extract/ now covers ~25 invalid or
edge-case repos (dangling refs, duplicate IDs, hand-authored delivery facts, non-static envelopes,
wrong builders, misplaced anchors, namespace imports, parse errors, …), each pinned to its exact
diagnostic.

Docs kept in lock-step

Two repair commits keep the concept docs honest against the landed surface: the DSL fragments, the
graph-schema sample, and the acceptance criteria in docs/concept/ now match the code that exists,
and the JTBD stories were re-aligned to the ratified language (readiness is stated, never promoted;
the cut list is named by the MVP boundary). The worked example gained a full walkthrough —
examples/checkout-v1/README.md — including a "break it on
purpose" section that trips each check deliberately.

Verification

• npm run check (the full CI gate) is green: temporal-language check → typecheck (src + examples) →
  lint → format → tests → build → example determinism.
• 187 tests across 14 files, including the golden correctness oracle
  (test/fixtures/checkout-v1/expected-graph.json + the golden Design Review tree) kept distinct from
  the determinism self-checks.
• The acceptance criteria of record (docs/concept/07 §6) are each pinned by a named test: the
  blocking-open-question honesty failure, drops-no-sections extraction, the api: anchor extraction,
  and coverage-unknown as acceptance.

Deliberately not in this PR

The cut list (docs/concept/07 §3) stands: no runtime observation or test-result ingestion (verification
in the graph is structural — a linked, enabled verifier exists), no Gherkin surface, no patch-back
loop (the edit path is intent → agent → git → checks), no MCP surface, no symbol-level impact graph,
no incremental builds. Each is recorded with rationale and a designed-in seam, so none requires
refactoring the core when it earns its way in.