Libar Software Delivery Protocol

Libar Software Delivery Protocol is a typed, executable, self-validating meta-model of software delivery: author Spec documents in the repository, derive one graph, and check conformance and honesty.

Carrier rule: Specs and Packs default to Markdown; the TS DSL survives as import source and a lawful per-ID option, while behavior and example Specs may use Gherkin canonically per ID (the carrier ruling, MD-18, the Pack syntax ruling, MD-25, and the Gherkin carrier option, MD-27).

Read the concept, the ubiquitous language, and the checkout-v1 walkthrough.

Source-checkout quick start

Install from the committed lockfile and build the CLI:

npm ci
npm run build

Then query this repository's self-hosting graph with either supported script runner:

npm run --silent sdp:q -- 'return g.specs().length'
pnpm --silent sdp:q 'return g.specs().length'

The sdp:q script supplies this repository's required fixture exclusions. Use the nineteen graph-first recipes for backlog, drift, verifier, impact, Pack, readiness, and promotion queries.

The architecture walkthrough follows shared policy, runner and adapter responsibilities, and the one read model through the graph.

The full CLI is available in the checkout through the sdp script; graph-deriving verbs at this root need the same three fixture exclusions the sdp:q script supplies:

pnpm --silent sdp --help
npm run --silent sdp -- --help
pnpm --silent sdp validate . --exclude explorations --exclude examples --exclude test/fixtures/import/parity

Do not use pnpm exec sdp (or npx sdp) in the Protocol's own checkout. pnpm exec resolves dependency binaries, but a package does not install or link itself into its own node_modules/.bin; on macOS the unresolved name selects Apple's unrelated /usr/bin/sdp, which fails with xcode-select: error: tool 'sdp' requires Xcode. The checked-in pnpm setting also disables pnpm 11's dependency auto-reconciliation for repository scripts, so the supported pnpm sdp / pnpm sdp:q forms do not rewrite an npm-installed dependency tree.

Installed CLI (adopter repositories)

In an adopter repository where the Protocol is installed as a dependency, its binary is linked into node_modules/.bin, so the package runner resolves it:

pnpm exec sdp --help
pnpm exec sdp build .
pnpm exec sdp validate .
pnpm exec sdp view .
pnpm exec sdp q 'return g.specs().map((spec) => spec.id)'

build derives the graph and executable contracts, validate adds conformance and honesty checks, view generates the Design Review, import converts TypeScript Spec carriers to Markdown, and q evaluates a local JavaScript query body against a freshly derived graph. Run sdp --help for the complete option contract. Adopters own their root and exclusion policy.

Gherkin carrier

Behavior and example Specs may use a .sdp.gherkin file as their one canonical surface. Bare .feature is not discovered. It stays ordinary Cucumber / import-source territory.

@spec.orders.submit
@altitude.feature
@readiness.defined
Feature: Submit an order

  @example-space
  Scenario: Vocabulary
    Given an order {orderId:string}
    When the order is submitted
    Then the order is accepted

  @spec.orders.submit.accepted
  @altitude.story
  @readiness.defined
  Scenario: A valid order is accepted
    Given an order {orderId: "order-42"}
    When the order is submitted
    Then the order is accepted

Build the graph and generated contracts:

pnpm exec sdp build .

Bind the generated step contract to code-side handlers and a resolving test anchor:

import { ref, specTest, testAnchorId } from "@libar-dev/software-delivery-protocol";
import { bindExample } from "@libar-dev/software-delivery-protocol/vitest";
import { acceptedContract } from "../generated/contracts/orders.submit.accepted.contract.js";

const acceptedAnchor = specTest({
  id: testAnchorId("test:orders.submit.accepted"),
  label: "valid order acceptance",
  verifies: ref(acceptedContract.spec),
});
void acceptedAnchor;

bindExample(acceptedContract, createWorld, handlers);

Cucumber execution is not part of the design. Generated contracts and anchored code-side handlers remain the execution boundary.

Editors do not recognize *.sdp.gherkin as Gherkin by default. Associate the suffix with Gherkin (often the cucumber language id) for highlighting and formatting. This repository ships the VS Code mapping:

{
  "files.associations": {
    "*.sdp.gherkin": "cucumber"
  }
}

Copy the same files.associations entry into an adopter .vscode/settings.json, or apply the equivalent association in another editor.

Extraction always loads the pinned Cucumber parser stack as ordinary runtime dependencies of @libar-dev/software-delivery-protocol, even when a corpus is Markdown-only:

• @cucumber/gherkin 42.0.1
• @cucumber/messages 34.2.1

Install the Protocol package once; do not add a parallel Gherkin parser or re-pin those packages for carrier support.

The package installs three agent on-ramps as SKILL.md files under node_modules/@libar-dev/software-delivery-protocol/.agents/skills/. Use sdp-agent-surface to read the graph, sdp-authoring to author intent, and sdp-sessions for advisory delivery-session routing. The same package includes the nineteen recipe bodies at docs/agent-surface/recipes.md.