Phase 0 — the protocol as typed code

[darko-mijic]

What is this?

This PR is the first buildable foundation of the Libar Software Delivery Protocol — an attempt to treat the whole software-delivery lifecycle (intent, specs, design decisions, constraints, code bindings, verification) as typed code in the repo, derive one graph from it, and generate every other artifact off that graph.

The starting observation: delivery knowledge today is scattered across tickets, wikis, PRDs, and tribal memory — none of it machine-checkable, all of it free to drift from the code. Meanwhile, the consumers of that knowledge are no longer just humans: coding agents, CI, and CLIs all need to read delivery intent. A typed graph of related specs is the shape an LLM already reasons in — so the bet is to make delivery intent authorable as code, checkable like code, and queryable as a graph.

Three ideas anchor the design:

• One authored primitive. Everything you'd recognize as a Use Case, NFR, Decision Record, Epic, or Story is a single Spec type, positioned by three descriptors — kind (what category of truth) × altitude (epic → feature → story) × readiness (idea → scoped → defined → ready) — and enriched in place, never migrated to a different artifact type. The familiar nouns survive as named coordinates, not as a class hierarchy.
• Honesty over gating. The system checks conformance (is this well-formed?) and honesty (is this not pretending? — e.g. you can't state defined with a blocking open question, and you can't hand-author an implemented badge), but it never gates workflow and never judges content quality. We claim "deterministically validated," never "provably correct."
• Authored vs derived, never blurred. Humans assert intent (relations, readiness, decisions) and bindings (anchors pointing code at a Spec ID); machines derive facts (implemented, has-verifier). Every edge carries its epistemic status (declared / anchored / inferred), and the taxonomy is never collapsed.

What's in this PR

The ratified concept base — docs/concept/: a lean ubiquitous-language glossary (the terminology contract), eight principle-led design docs (00–07, from vision and founding principles through the core model, the graph, validation, consumers, and the roadmap), and DECISIONS.md — a why-log of every hard-to-reverse choice (MD-1…MD-16), each with the alternatives that were rejected and why. The JTBD stories in jtbd-stories/ are the functional spec.

Phase 0: the protocol as typed code — src/: the Spec primitive and its descriptors, typed relations, binding-only anchors, the Pack grouping, branded IDs, the graph schema, and the validators. Highlights:

• Floor-bearing sections are closed-typed, so hand-authoring a delivery fact inside a section fails to typecheck — and a runtime check catches what the type system structurally can't.
• The readiness floor is a kind-conditional evidence table that is itself the single source of truth: clause ids are derived from the table via typeof, the evaluator is one generic loop, and promoted child specs count as evidence only when they actually carry it (an empty stub is not a promotion).
• Validation runs on a pre-graph stand-in that is honestly fenced as such — there is one validation path, and it migrates onto the extracted graph in Slice 1/3.

A worked example — examples/checkout-v1: nine specs plus a pack for an Order Management slice, written tracer-bullet-first so the DSL was forced to be usable before it was finished, with real implementation and test anchors.

Tests and tooling — 57 tests across 10 files, including compile-time pins (@ts-expect-error fixtures proving the type-level guarantees) and active should-fail fixtures for the honesty checks. CI runs the full gate: a fail-closed temporal guard (durable artifacts must state invariants and cite decisions, never narrate history — git is the event log) → typecheck (src + examples) → lint → format → tests → build.

How it was reviewed

Beyond the gate, the branch went through several adversarial review passes during development (recorded in reviews/ and folded into DECISIONS.md as MD-7 and MD-16), plus a final five-track internal review before this PR (implementation fidelity, tests/examples, docs conformance, tooling, plan coherence). The final review found no correctness bugs; its three findings (a comment citing a review event instead of the decision, the missing LICENSE file, the missing repository field) are fixed in the closing commits — along with a CI hermeticity bug the first real workflow run exposed (the typecheck was resolving the package's self-import through stale local build output).

What's next

Slice 1: the extractor — read the *.sdp.ts spec files statically (no execution), derive the first real graph, and feed the existing validators from it. The example in this PR becomes its first input. The slice roadmap is docs/concept/07; the live plan lives in plans/.

---

Reading guide for reviewers: start with docs/concept/ubiquitous-language.md (the vocabulary), then docs/concept/README.md → 00–07 for the model, DECISIONS.md for any choice that looks arbitrary, and examples/checkout-v1 to see the DSL in use.