From 53804437546c7bdccb9e1e7742b07a4ede3702f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Darko=20Miji=C4=87?= Date: Wed, 4 Nov 2026 08:52:25 +0100 Subject: [PATCH] docs(articles): re-pin the series to f990bded and refresh it for the design pass The owner's working rules: refresh the article series by its playbook so everything is ready for the first UX/UI design pass, carrying out the owner's ruling that the first refresh after PR #40 re-pins the articles. Commits, push and the pull request are authorized. Base: main at f990bded (the merge of PR #34, after PR #40). No arc Pack: the refresh changes no Spec carrier, readiness statement or decision row. - Move the pin from b5e0a8be to f990bded: the playbook baseline, every commit-pinned link (all 33 paths exist at the pin), every checkout command and footer. - Regenerate the 11 evidence blocks at the pin (3 changed: both census tables and byFile). - Part 2: the composing panel's per-intent line and `Preview memo`; the `floor not evaluated` state; the AI-assisted reading capture and its owner question, whose trigger is this design pass. - Part 5: the same capture, its provisional answer and trigger. - Part 1: the CLI's Node range is ^20.19.0 || >=22.12.0. - Playbook: Article 08 states the unspecified rule without the closed L1-02 exception; house rule 9 names what the link gate checks. Co-Authored-By: Claude Opus 5.5 --- ...01-the-spec-is-the-prompt-is-the-design.md | 26 +++++------ docs/articles/02-one-graph-many-views.md | 26 ++++++----- .../03-walkthrough-intent-to-verified-code.md | 12 ++--- ...p-building-verb-walls-for-coding-agents.md | 16 +++---- docs/articles/05-ai-can-shape-the-reading.md | 10 ++--- docs/articles/README.md | 44 +++++++++---------- 6 files changed, 68 insertions(+), 66 deletions(-) diff --git a/docs/articles/01-the-spec-is-the-prompt-is-the-design.md b/docs/articles/01-the-spec-is-the-prompt-is-the-design.md index b4ad8c16f..7b9a2aa2c 100644 --- a/docs/articles/01-the-spec-is-the-prompt-is-the-design.md +++ b/docs/articles/01-the-spec-is-the-prompt-is-the-design.md @@ -6,7 +6,7 @@ At the start of a project, intent is sharp. You write an architecture document, An AI coding agent inherits that fragmentation. It can write a function quickly, but it cannot tell an early idea from a settled contract, an implementation shortcut from a ratified decision, or a verifier binding from a passing test. It reads raw files and stale prose, then guesses at the missing structure. -[Libar Software Delivery Protocol](https://github.com/libar-dev/software-delivery-protocol/tree/b5e0a8bea1e3bedd48c616f96c9928e955792753) (`@libar-dev/software-delivery-protocol`, CLI `sdp`) addresses that missing structure. It is an executable, self-validating meta-model of the software-delivery process. +[Libar Software Delivery Protocol](https://github.com/libar-dev/software-delivery-protocol/tree/f990bded1d7ca86f19f5746ef412613f8e908be3) (`@libar-dev/software-delivery-protocol`, CLI `sdp`) addresses that missing structure. It is an executable, self-validating meta-model of the software-delivery process. Its premise has four parts: @@ -18,7 +18,7 @@ This article explains those parts and what they make possible. Delivery tools often make an idea change artifact types as it matures. A note becomes a requirement, then a design document, then tickets, then acceptance criteria. Each migration loses context and breaks traceability. -The Protocol has one authored truth-primitive, `Spec`. A Spec keeps its stable, namespaced identity, such as `spec:orders.create-order`, from its first capture through implementation. You enrich it with typed sections or refine it into child Specs. You do not convert it into a different artifact ([`spec:model.core-model`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/model/core-model.sdp.md)). +The Protocol has one authored truth-primitive, `Spec`. A Spec keeps its stable, namespaced identity, such as `spec:orders.create-order`, from its first capture through implementation. You enrich it with typed sections or refine it into child Specs. You do not convert it into a different artifact ([`spec:model.core-model`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/model/core-model.sdp.md)). Three independent descriptors position every Spec: @@ -44,7 +44,7 @@ That only works when authors avoid padding. The Protocol's readiness floor is a ## The graph is derived -Nobody authors the graph. `sdp build` reads the carriers and source anchors and derives one flat, typed, deterministic document: nodes, edges and a location table. Validators, recipes and projections consume that one read model rather than parsing source into private alternatives ([`spec:extraction.derive-graph`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/extraction/derive-graph.sdp.md)). +Nobody authors the graph. `sdp build` reads the carriers and source anchors and derives one flat, typed, deterministic document: nodes, edges and a location table. Validators, recipes and projections consume that one read model rather than parsing source into private alternatives ([`spec:extraction.derive-graph`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/extraction/derive-graph.sdp.md)). Edges that touch the same Spec can carry different claims: @@ -66,7 +66,7 @@ Every node and edge has one of three claims: | `anchored` | Human-authored source or test anchor | Authoritative binding, no intent | | `inferred` | Mechanical analysis | Advisory structure, never silently promoted | -The current curated graph contains declared and anchored content. File-level imports supplied through `sdp build --imports` remain separate inferred input for curation advice. They do not mint curated edges or delivery facts ([`spec:extraction.claim-taxonomy`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/extraction/claim-taxonomy.sdp.md)). +The current curated graph contains declared and anchored content. File-level imports supplied through `sdp build --imports` remain separate inferred input for curation advice. They do not mint curated edges or delivery facts ([`spec:extraction.claim-taxonomy`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/extraction/claim-taxonomy.sdp.md)). Readiness and realization stay independent too: @@ -120,17 +120,17 @@ The Spec Studio makes the human side concrete. A reviewer can explore a Pack, in ## The Protocol measures itself -The Protocol has no separate PRD. It authors its own rules as Specs, binds its engine and tests to them, derives its own graph and checks that graph in CI ([`spec:protocol.self-hosting`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/protocol/self-hosting.sdp.md)). +The Protocol has no separate PRD. It authors its own rules as Specs, binds its engine and tests to them, derives its own graph and checks that graph in CI ([`spec:protocol.self-hosting`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/protocol/self-hosting.sdp.md)). -Measured at commit `b5e0a8bea1e3bedd48c616f96c9928e955792753`: +Measured at commit `f990bded1d7ca86f19f5746ef412613f8e908be3`: | Measure | Value | |---|---| -| Authored Specs | 456: 447 `ready`, 4 `scoped`, 5 `idea` | +| Authored Specs | 459: 447 `ready`, 4 `scoped`, 8 `idea` | | Packs | 9 | -| Source and test bindings | 241 CodeNodes and 366 Anchors | -| Graph | 1,072 nodes, 2,978 edges, 3,120 locations | +| Source and test bindings | 241 CodeNodes and 370 Anchors | +| Graph | 1,079 nodes, 2,996 edges, 3,157 locations | | Delivery facts | 166 `implemented`, 397 `has-verifier`, 0 `observed` | | Operational build backlog | 2 | | Drift alarm | 0 | @@ -149,18 +149,18 @@ It is not an embedded permissions system. Approval belongs in git and CI. It does not infer intent. Mechanical structure can assist curation, but a person authors intent and bindings. -The aim is to connect adjacent tools rather than replace them. Today the Studio reads supplied CTRF test reports as run evidence. An interface and API reference remains an [idea-stage capture](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/consumers/reference-projection.sdp.md). Dedicated integrations with issue trackers and design tools are not designed yet; generic Design and UI prose can mention them without providing that experience. +The aim is to connect adjacent tools rather than replace them. Today the Studio reads supplied CTRF test reports as run evidence. An interface and API reference remains an [idea-stage capture](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/reference-projection.sdp.md). Dedicated integrations with issue trackers and design tools are not designed yet; generic Design and UI prose can mention them without providing that experience. At the pinned commit, installation is from a reviewed git commit rather than an npm release. The package version is `0.0.0`; `sdp --version` names the build commit. ## Try it -For this source checkout, use Node `^20.19.0 || ^22.12.0 || >=24.0.0`, where the ranges declared by the installed test toolchain (Vitest, Vite and Rolldown) overlap. The installed CLI separately declares Node `>=20`: +For this source checkout, use Node `^20.19.0 || ^22.12.0 || >=24.0.0`, where the ranges declared by the installed test toolchain (Vitest, Vite and Rolldown) overlap. The installed CLI separately declares Node `^20.19.0 || >=22.12.0` in its `engines` field: ```sh git clone https://github.com/libar-dev/software-delivery-protocol.git cd software-delivery-protocol -git checkout b5e0a8bea1e3bedd48c616f96c9928e955792753 +git checkout f990bded1d7ca86f19f5746ef412613f8e908be3 npm ci npm run --silent sdp -- validate . \ @@ -181,4 +181,4 @@ Open `generated/spec-studio/index.html`. The `sdp:q` script supplies the reposit --- -*About this article: Part 1 in a series introducing the [Libar Software Delivery Protocol](https://github.com/libar-dev/software-delivery-protocol/tree/b5e0a8bea1e3bedd48c616f96c9928e955792753). Repository links and measurements are pinned to commit `b5e0a8be`; re-run the commands rather than quoting the numbers at a later commit.* +*About this article: Part 1 in a series introducing the [Libar Software Delivery Protocol](https://github.com/libar-dev/software-delivery-protocol/tree/f990bded1d7ca86f19f5746ef412613f8e908be3). Repository links and measurements are pinned to commit `f990bded`; re-run the commands rather than quoting the numbers at a later commit.* diff --git a/docs/articles/02-one-graph-many-views.md b/docs/articles/02-one-graph-many-views.md index cb7c541e3..68fa2026f 100644 --- a/docs/articles/02-one-graph-many-views.md +++ b/docs/articles/02-one-graph-many-views.md @@ -12,7 +12,7 @@ That freedom is the subject of this article. ## The seed was a workbench, not a documentation page -The original design, written before the implementation, described a generated HTML Spec Studio where people could explore Specs, architecture, tests and evidence. Its central scenario was not "read a requirement online." It was a person understanding a system, finding gaps, proposing a change and returning that change to the repository ([the seed vision](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/docs/lineage/v0-design/00-vision-and-product.md), [the seed Studio design](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/docs/lineage/v0-design/07-spec-studio-and-projections.md)). +The original design, written before the implementation, described a generated HTML Spec Studio where people could explore Specs, architecture, tests and evidence. Its central scenario was not "read a requirement online." It was a person understanding a system, finding gaps, proposing a change and returning that change to the repository ([the seed vision](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/docs/lineage/v0-design/00-vision-and-product.md), [the seed Studio design](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/docs/lineage/v0-design/07-spec-studio-and-projections.md)). Some representations in that design have since been rejected. TypeScript is no longer the default carrier. JSON patches and codemods have given way to scoped intent and ordinary source edits. Test verdicts no longer enter the graph as readiness. The vocabulary has been ratified and narrowed. @@ -22,7 +22,7 @@ The current Studio is an early realization of that idea, not its final visual de ## One record, several readings -The repository holds authored Specs, Packs and source anchors. The extractor derives one graph. Validators and consumers read that graph. A projection turns it into an artifact for a particular consumer ([`spec:consumers.projections-model`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/consumers/projections-model.sdp.md)). +The repository holds authored Specs, Packs and source anchors. The extractor derives one graph. Validators and consumers read that graph. A projection turns it into an artifact for a particular consumer ([`spec:consumers.projections-model`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/projections-model.sdp.md)). At the pinned commit, the package publishes five projection roots: @@ -36,7 +36,7 @@ At the pinned commit, the package publishes five projection roots: The graph also serves `sdp q`, CLI answers and typed contracts. An Obsidian vault provides generated notes and Bases beside a person's own notes. These are different readings, not competing repositories of delivery status. -This breadth is intentional, but not every form is open. The [shipped-projections decision](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/decisions/shipped-projections-frozen.sdp.md) (MD-32) settles Design Review, census, Mermaid and Gherkin as read models. The Studio and any new reading are where we learn which forms earn their place. +This breadth is intentional, but not every form is open. The [shipped-projections decision](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/decisions/shipped-projections-frozen.sdp.md) (MD-32) settles Design Review, census, Mermaid and Gherkin as read models. The Studio and any new reading are where we learn which forms earn their place. The article's diagram evidence comes from the same mechanism. This Mermaid source is emitted by `sdp mermaid` from the checkout roadmap Pack, not redrawn for publication: @@ -55,11 +55,11 @@ The rule that matters is not "everything must look the same." It is "no view may ## What the current Studio already does -`sdp studio` publishes a static page set that works from `file://` or a static host. It needs no application server. Every join, delivery fact, readiness floor and finding is computed during the build. The browser does not assemble a second graph ([`spec:consumers.spec-studio`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/consumers/spec-studio.sdp.md)). +`sdp studio` publishes a static page set that works from `file://` or a static host. It needs no application server. Every join, delivery fact, readiness floor and finding is computed during the build. The browser does not assemble a second graph ([`spec:consumers.spec-studio`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/spec-studio.sdp.md)). A reader can move through five lenses: Packs, capabilities, architecture, tests and evidence. Other pages collect the roadmap, the owner queue, open questions, decisions, declarations, the design backlog and the glossary. A build can also include a design diff from a supplied base graph and run evidence from supplied CTRF reports. A Pack can be exported as one self-contained HTML file. -For a pull-request reviewer, the important detail is the stamp. Publishing metadata names the corpus commit and engine after the page set is built. The page set itself remains a deterministic function of its graph and named inputs ([`spec:consumers.spec-studio.sharing`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/consumers/spec-studio.sharing.sdp.md)). +For a pull-request reviewer, the important detail is the stamp. Publishing metadata names the corpus commit and engine after the page set is built. The page set itself remains a deterministic function of its graph and named inputs ([`spec:consumers.spec-studio.sharing`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/spec-studio.sharing.sdp.md)). This is already enough to test a real review workflow. It is not evidence that five lenses, the current navigation or today's information density are the right long-term answers. Those are UX questions. @@ -73,7 +73,7 @@ A flexible interface still has obligations to the model. The important ones are **Readiness and realization are independent.** An author states readiness. The graph derives the highest structural floor reached and the delivery facts. A useful review page lets a person see all three without turning them into a single progress score. -**Absence needs words.** An example-space value no example binds, a slot whose coverage is not measurable, a missing verifier and an evidence lens with no tracked observations say different things. `coverage-unknown` names a separate file-impact blind spot: a changed file the graph records nothing at. An empty panel with no explanation forces the reader to guess which absence the system means. +**Absence needs words.** An example-space value no example binds, a slot whose coverage is not measurable, a missing verifier and an evidence lens with no tracked observations say different things. `coverage-unknown` names a separate file-impact blind spot: a changed file the graph records nothing at. An empty panel with no explanation forces the reader to guess which absence the system means. The same holds for a readiness floor the system did not evaluate: a Spec whose kind or altitude is unratified, which only a graph from another producer can hold, shows `floor not evaluated` rather than a floor below `idea`. **A drawing needs a text equivalent.** Studio diagrams retain words that state every box and edge. When a drawing exceeds its bound, it folds and the text remains. This is an accessibility rule and an honesty rule: visual compression must not remove meaning. @@ -83,7 +83,7 @@ These constraints leave many visual choices open. They rule out interface shortc The seed design used a patch panel. The current design has a composing panel instead. -A person can gather requests while reading, scoped to a Spec, an entry, a Pack or an open question. The panel produces a change proposal and its Markdown memo when it has a base and a reason. Anything the proposal contract cannot carry stays as scoped-intent text. The page sends nothing over the network and opens no pull request ([`spec:consumers.spec-studio.intent-panel`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/consumers/spec-studio.intent-panel.sdp.md)). +A person can gather requests while reading, scoped to a Spec, an entry, a Pack or an open question. The panel produces a change proposal and its Markdown memo when it has a base and a reason. Each gathered intent shows on one line naming its scope and the change it asks for. Before the memo leaves, a closed `Preview memo` disclosure shows exactly the text that `Copy memo` copies and `Save memo` saves. Anything the proposal contract cannot carry stays as scoped-intent text. The page sends nothing over the network and opens no pull request ([`spec:consumers.spec-studio.intent-panel`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/spec-studio.intent-panel.sdp.md)). An agent receives that hand-off and edits ordinary source. Git records the result. The same checks apply to that edit as to one typed directly into a carrier. @@ -97,7 +97,7 @@ The fixed ground: - The repository is canonical and the graph is the sole read model. - A projection is disposable and regenerable. No interface state becomes delivery truth. -- The [shipped-projections decision](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/decisions/shipped-projections-frozen.sdp.md) (MD-32) freezes Design Review, census, Mermaid and Gherkin. Reshaping one needs a refining or superseding decision. The Studio can evolve under its own Specs. +- The [shipped-projections decision](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/decisions/shipped-projections-frozen.sdp.md) (MD-32) freezes Design Review, census, Mermaid and Gherkin. Reshaping one needs a refining or superseding decision. The Studio can evolve under its own Specs. - Claims, stated readiness, derived readiness and delivery facts stay distinct. - Outside inputs and their commits stay named wherever they appear. - Unknowns and missing evidence remain visible. @@ -112,9 +112,9 @@ The open design space: - How a person moves between a Pack overview, one Spec, an entry and its source. - How desktop and phone review differ. - How much information belongs in the first reading and what belongs behind disclosure. -- How a future AI assistant can steer a reading without obscuring its basis. +- How a future AI assistant can steer a reading without obscuring its basis. [`spec:consumers.ai-assisted-reading`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/ai-assisted-reading.sdp.md) records that boundary as an `idea`-stage capture; see below. -Start from the Studio's [manual acceptance tasks](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/consumers/spec-studio.sdp.md#verification--manual) and test prototypes against them. These are specified acceptance criteria, not evidence that a person has completed them. +Start from the Studio's [manual acceptance tasks](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/spec-studio.sdp.md#verification--manual) and test prototypes against them. These are specified acceptance criteria, not evidence that a person has completed them. The first design pass should answer these questions with prototypes: @@ -128,6 +128,8 @@ The first design pass should answer these questions with prototypes: The deliverable should be a small set of task-based experiences, not a comprehensive design system for every page the generator can emit. +The pass also carries one open product question. The AI-assisted reading capture, [`spec:consumers.ai-assisted-reading`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/ai-assisted-reading.sdp.md), holds a blocking question for the owner: what contract would keep an assistant's own explanations or arrangements distinct from graph claims and reviewable? Its provisional answer is that an assistant selects existing deterministic readings only, and any generated text stays outside the Studio and the frozen projections, labelled as assistant output with its source commit and scope. The question reopens when this design pass measures that assistant selection, or a generated explanation, helps a named review task. A prototype that tests either belongs in the pass; shipping one does not. + ## Try the material From a checkout at the pinned commit: @@ -135,7 +137,7 @@ From a checkout at the pinned commit: ```sh git clone https://github.com/libar-dev/software-delivery-protocol.git cd software-delivery-protocol -git checkout b5e0a8bea1e3bedd48c616f96c9928e955792753 +git checkout f990bded1d7ca86f19f5746ef412613f8e908be3 npm ci npm run --silent sdp -- generate . \ @@ -150,4 +152,4 @@ Part 3, [From rough idea to verified code](./03-walkthrough-intent-to-verified-c --- -*About this article: Part 2 in a series introducing the [Libar Software Delivery Protocol](https://github.com/libar-dev/software-delivery-protocol/tree/b5e0a8bea1e3bedd48c616f96c9928e955792753). Repository links are pinned to commit `b5e0a8be`. The seed documents explain the original product experience; current Specs and source determine what is built now.* +*About this article: Part 2 in a series introducing the [Libar Software Delivery Protocol](https://github.com/libar-dev/software-delivery-protocol/tree/f990bded1d7ca86f19f5746ef412613f8e908be3). Repository links are pinned to commit `f990bded`. The seed documents explain the original product experience; current Specs and source determine what is built now.* diff --git a/docs/articles/03-walkthrough-intent-to-verified-code.md b/docs/articles/03-walkthrough-intent-to-verified-code.md index faddd2efd..d849cf532 100644 --- a/docs/articles/03-walkthrough-intent-to-verified-code.md +++ b/docs/articles/03-walkthrough-intent-to-verified-code.md @@ -4,7 +4,7 @@ [Part 1](./01-the-spec-is-the-prompt-is-the-design.md) introduced one enrichable `Spec`, source anchors and the derived graph. [Part 2](./02-one-graph-many-views.md) showed how people read that graph through regenerable projections. -This article follows the engineering loop in a text editor and a terminal. We will use Order Management in [`examples/checkout-v1`](https://github.com/libar-dev/software-delivery-protocol/tree/b5e0a8bea1e3bedd48c616f96c9928e955792753/examples/checkout-v1), then inspect a comment-form binding in the Protocol's own engine. +This article follows the engineering loop in a text editor and a terminal. We will use Order Management in [`examples/checkout-v1`](https://github.com/libar-dev/software-delivery-protocol/tree/f990bded1d7ca86f19f5746ef412613f8e908be3/examples/checkout-v1), then inspect a comment-form binding in the Protocol's own engine. ## Setup @@ -13,7 +13,7 @@ Every command runs from a checkout at the pinned commit. Use Node `^20.19.0 || ^ ```sh git clone https://github.com/libar-dev/software-delivery-protocol.git cd software-delivery-protocol -git checkout b5e0a8bea1e3bedd48c616f96c9928e955792753 +git checkout f990bded1d7ca86f19f5746ef412613f8e908be3 npm ci ``` @@ -99,7 +99,7 @@ The Specs listed by the generated drift answer have implementation bindings and ## Author the parent and its example space -Open [`create-order.sdp.md`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/examples/checkout-v1/specs/orders/create-order.sdp.md): +Open [`create-order.sdp.md`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/examples/checkout-v1/specs/orders/create-order.sdp.md): ````markdown @@ -143,7 +143,7 @@ The `gwt-vocabulary` fence declares the typed example space its child examples s ### Bind one point -The child example [`create-order-valid-cart.sdp.md`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/examples/checkout-v1/specs/orders/create-order-valid-cart.sdp.md) refines and verifies its parent: +The child example [`create-order-valid-cart.sdp.md`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/examples/checkout-v1/specs/orders/create-order-valid-cart.sdp.md) refines and verifies its parent: ````markdown @@ -203,7 +203,7 @@ export const createOrderUseCaseAnchor = codeAnchor({ ``` -The comment form needs no runtime import. This anchor comes from the Protocol's own [`src/projections/census.ts`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/src/projections/census.ts): +The comment form needs no runtime import. This anchor comes from the Protocol's own [`src/projections/census.ts`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/src/projections/census.ts): ```ts @@ -293,4 +293,4 @@ These experiments show the boundary between extraction, conformance, honesty and --- -*About this article: Part 3 in a series introducing the [Libar Software Delivery Protocol](https://github.com/libar-dev/software-delivery-protocol/tree/b5e0a8bea1e3bedd48c616f96c9928e955792753). Repository links and command outputs are pinned to commit `b5e0a8be`; re-run the commands rather than quoting the outputs at a later commit.* +*About this article: Part 3 in a series introducing the [Libar Software Delivery Protocol](https://github.com/libar-dev/software-delivery-protocol/tree/f990bded1d7ca86f19f5746ef412613f8e908be3). Repository links and command outputs are pinned to commit `f990bded`; re-run the commands rather than quoting the outputs at a later commit.* diff --git a/docs/articles/04-stop-building-verb-walls-for-coding-agents.md b/docs/articles/04-stop-building-verb-walls-for-coding-agents.md index cd83ffebb..34bf1e199 100644 --- a/docs/articles/04-stop-building-verb-walls-for-coding-agents.md +++ b/docs/articles/04-stop-building-verb-walls-for-coding-agents.md @@ -6,13 +6,13 @@ A CLI gains `list-specs`. Then it gains a readiness filter, a command for verifi The agent makes a sequence of calls, receives more output than its context can hold and joins the results in scratch space. The tool has exposed many operations and little of the underlying model. -The Libar Software Delivery Protocol takes another path ([the agent front door, MD-22](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/decisions/agent-front-door.sdp.md)): +The Libar Software Delivery Protocol takes another path ([the agent front door, MD-22](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/decisions/agent-front-door.sdp.md)): > Give coding agents a visible, typed graph and one evaluation sink they can script. ## Start with what the agent holds -Before designing [`spec:consumers.agent-surface`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/consumers/agent-surface.sdp.md), we asked what an agent has when a session starts. Usually it does not have the Spec ID it needs. It has one of three things, the demand map: +Before designing [`spec:consumers.agent-surface`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/agent-surface.sdp.md), we asked what an agent has when a session starts. Usually it does not have the Spec ID it needs. It has one of three things, the demand map: 1. A concept string from a prompt, such as "where do we enforce the readiness floor?" 2. A file path it is about to read or edit. @@ -54,7 +54,7 @@ At the pinned commit, that returns: { "id": "impl:protocol.census-page", "nodeType": "CodeNode", - "line": 21 + "line": 22 } ], "specs": [ @@ -70,7 +70,7 @@ The body is code, and `sdp q` runs it with the local process's full authority. N ## Grow by recipe, not by verb -A recurring question becomes a recipe in [`docs/agent-surface/recipes.md`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/docs/agent-surface/recipes.md). Every recipe is executed as written by the test suite and shipped under `dist/recipes/`. The [generated baseline metrics](./README.md#step-3-re-derive-corpus-metrics) carry the recipe count at the pin. +A recurring question becomes a recipe in [`docs/agent-surface/recipes.md`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/docs/agent-surface/recipes.md). Every recipe is executed as written by the test suite and shipped under `dist/recipes/`. The [generated baseline metrics](./README.md#step-3-re-derive-corpus-metrics) carry the recipe count at the pin. A recipe takes documented parameters through `--params`. An unknown parameter returns `{ unknownParams, accepts }` rather than silently changing the question. A caller can also wrap a recipe in its own body and filter the answer, without editing the shipped body. @@ -80,7 +80,7 @@ A join moves into the reader only at the second-caller bar: a second machine con Some questions need more than a small answer. A design pass over a Pack may need member sections, open questions, dependency footing, declarations, examples and the Pack boundary. -The context bundle, recipe 36, composes that reading on demand within a budget counted in UTF-16 code units. It states what it left out and never saves a second reading of the graph. When the whole scope cannot fit one budget, `part` returns ordered parts whose members together cover the scope. An oversized item is named rather than silently dropped ([`spec:consumers.context-bundle`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/consumers/context-bundle.sdp.md)). +The context bundle, recipe 36, composes that reading on demand within a budget counted in UTF-16 code units. It states what it left out and never saves a second reading of the graph. When the whole scope cannot fit one budget, `part` returns ordered parts whose members together cover the scope. An oversized item is named rather than silently dropped ([`spec:consumers.context-bundle`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/context-bundle.sdp.md)). The design slice, recipe 54, answers a different question. It reads a Pack or selected Specs as one design: internal relations, touched components, decisions, open questions and what each member needs next. It is a reading composed on each invocation, not a saved planning artifact. @@ -96,7 +96,7 @@ That is the useful feedback loop. The graph remains stable while the on-ramps an ## Repository-owned skills teach the workflow -A capable surface still needs an on-ramp. The package ships repository-owned skills, counted in the [generated baseline metrics](./README.md#step-3-re-derive-corpus-metrics), under [`.agents/skills/`](https://github.com/libar-dev/software-delivery-protocol/tree/b5e0a8bea1e3bedd48c616f96c9928e955792753/.agents/skills): +A capable surface still needs an on-ramp. The package ships repository-owned skills, counted in the [generated baseline metrics](./README.md#step-3-re-derive-corpus-metrics), under [`.agents/skills/`](https://github.com/libar-dev/software-delivery-protocol/tree/f990bded1d7ca86f19f5746ef412613f8e908be3/.agents/skills): - `sdp-agent-surface` teaches graph reading and the task-to-recipe map. - `sdp-authoring` teaches the carriers, readiness floors, relations and bindings. @@ -121,7 +121,7 @@ From a checkout at the pinned commit: ```sh git clone https://github.com/libar-dev/software-delivery-protocol.git cd software-delivery-protocol -git checkout b5e0a8bea1e3bedd48c616f96c9928e955792753 +git checkout f990bded1d7ca86f19f5746ef412613f8e908be3 npm ci # Find a concept. @@ -145,4 +145,4 @@ In this source checkout, `npm run --silent sdp:q --` supplies the corpus's fixtu --- -*About this article: Part 4 in a series introducing the [Libar Software Delivery Protocol](https://github.com/libar-dev/software-delivery-protocol/tree/b5e0a8bea1e3bedd48c616f96c9928e955792753). Repository links and command outputs are pinned to commit `b5e0a8be`; re-run the commands rather than quoting them at a later commit.* +*About this article: Part 4 in a series introducing the [Libar Software Delivery Protocol](https://github.com/libar-dev/software-delivery-protocol/tree/f990bded1d7ca86f19f5746ef412613f8e908be3). Repository links and command outputs are pinned to commit `f990bded`; re-run the commands rather than quoting them at a later commit.* diff --git a/docs/articles/05-ai-can-shape-the-reading.md b/docs/articles/05-ai-can-shape-the-reading.md index 5a4812891..83bee0ad8 100644 --- a/docs/articles/05-ai-can-shape-the-reading.md +++ b/docs/articles/05-ai-can-shape-the-reading.md @@ -30,7 +30,7 @@ It could compose a new deterministic projection through code. An agent proposes It could produce explanatory prose or a bespoke arrangement beside a deterministic projection. A summary might explain why two Specs conflict or translate a readiness floor failure into plainer language. This is where the fine-tuning and presentation finesse become valuable, and where the current guarantees need careful extension. -All three patterns are options to explore. None is a ratified product design today. +All three patterns are options to explore. None is a ratified product design today. The boundary has a carrying Spec, [`spec:consumers.ai-assisted-reading`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/ai-assisted-reading.sdp.md), at `idea`. Its one blocking question asks what contract the second and third patterns would need. Its provisional answer, which the owner has yet to decide, allows only the first: select existing deterministic readings, and keep any generated text outside the Studio and the frozen projections, labelled as assistant output with its source commit and scope. ## The determinism question cannot be waved away @@ -59,7 +59,7 @@ These rules do not guarantee that a summary is good. They make its claims inspec ## A better goal than "AI-generated UI" -The seed design treated AI context as a first-class projection and the Studio as a place to explore and refine a living model ([the seed projection design](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/docs/lineage/v0-design/07-spec-studio-and-projections.md)). The current system has made the graph, agent surface, Studio and intent hand-off real. +The seed design treated AI context as a first-class projection and the Studio as a place to explore and refine a living model ([the seed projection design](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/docs/lineage/v0-design/07-spec-studio-and-projections.md)). The current system has made the graph, agent surface, Studio and intent hand-off real. The next useful step is not a button that generates an entire dashboard. It is a set of measured experiments: @@ -69,9 +69,9 @@ The next useful step is not a button that generates an entire dashboard. It is a 4. Which generated artifacts need a model, prompt and source-commit record to remain reviewable? 5. When does adaptive presentation save effort, and when does a stable page structure make review easier? -The first UX/UI design pass can explore these questions without committing the product to AI-rendered pages. The deterministic Studio remains a baseline and a fallback. +The first UX/UI design pass can explore these questions without committing the product to AI-rendered pages. Its measurements are also the capture's named trigger: the boundary question reopens when the pass shows that assistant selection or a generated explanation helps a named review task. The deterministic Studio remains a baseline and a fallback. -The strategic value is flexibility within explicit contracts. We can test additional readings and explore AI assistance while preserving the current deterministic surfaces. Reshaping Design Review, census, Mermaid or Gherkin requires a decision that refines or supersedes the [shipped-projections decision](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/decisions/shipped-projections-frozen.sdp.md) (MD-32); Studio changes follow its own carrying Specs. The interface can keep changing. The record does not change with it. +The strategic value is flexibility within explicit contracts. We can test additional readings and explore AI assistance while preserving the current deterministic surfaces. Reshaping Design Review, census, Mermaid or Gherkin requires a decision that refines or supersedes the [shipped-projections decision](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/decisions/shipped-projections-frozen.sdp.md) (MD-32); Studio changes follow its own carrying Specs. The interface can keep changing. The record does not change with it. ## Up next @@ -79,4 +79,4 @@ Part 6, *Shared language is a performance feature*, returns to the construction --- -*About this article: Part 5 in a series introducing the [Libar Software Delivery Protocol](https://github.com/libar-dev/software-delivery-protocol/tree/b5e0a8bea1e3bedd48c616f96c9928e955792753). Repository links are pinned to commit `b5e0a8be`. Current capabilities are distinguished from design options throughout; the AI presentation direction is not shipped functionality.* +*About this article: Part 5 in a series introducing the [Libar Software Delivery Protocol](https://github.com/libar-dev/software-delivery-protocol/tree/f990bded1d7ca86f19f5746ef412613f8e908be3). Repository links are pinned to commit `f990bded`. Current capabilities are distinguished from design options throughout; the AI presentation direction is not shipped functionality.* diff --git a/docs/articles/README.md b/docs/articles/README.md index 77db802a5..ea09d3b1e 100644 --- a/docs/articles/README.md +++ b/docs/articles/README.md @@ -1,6 +1,6 @@ # Media plan and living series playbook -> **Pinned source baseline:** commit [`b5e0a8be`](https://github.com/libar-dev/software-delivery-protocol/tree/b5e0a8bea1e3bedd48c616f96c9928e955792753), the merge of [PR #36](https://github.com/libar-dev/software-delivery-protocol/pull/36). +> **Pinned source baseline:** commit [`f990bded`](https://github.com/libar-dev/software-delivery-protocol/tree/f990bded1d7ca86f19f5746ef412613f8e908be3), the merge of [PR #34](https://github.com/libar-dev/software-delivery-protocol/pull/34), after [PR #40](https://github.com/libar-dev/software-delivery-protocol/pull/40). The previous pin was `b5e0a8be`, the merge of [PR #36](https://github.com/libar-dev/software-delivery-protocol/pull/36). > **Posture:** This directory is maintained on `main` through focused refresh PRs as the Protocol advances. The opening arc used a standing PR for review, but no permanent media diff is needed. Current behavior, seed-design intent and future directions must read as three different things. Re-run Protocol-corpus measurements at a new pin rather than inheriting them; adopter and historical counts keep their cited measurement sources. Evidence verification always uses a separate checkout of the exact source pin, so manuscript commits cannot change the answers being verified. The sync creates and removes that disposable checkout in both local and CI runs; its writes are described in Step 4. ## 1. The series argument @@ -15,10 +15,10 @@ The series has to carry four consequences, not just the engine behind them: 1. **One Spec, enriched in place.** Eight kinds, three altitudes and four stated readiness rungs cover delivery intent without migrating an idea through artifact types. 2. **Authored intent and derived facts stay separate.** `declared`, `anchored` and `inferred` claims are never collapsed. `implemented` and `has-verifier` are derived from bindings; `observed` remains deferred. -3. **Projections are regenerable readings.** Markdown, Mermaid, Gherkin, HTML, CLI answers and generated notes are readings, not competing stores. Reshaping Design Review, census, Mermaid or Gherkin requires a decision that refines or supersedes the [shipped-projections decision](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/decisions/shipped-projections-frozen.sdp.md) (MD-32). The Studio can evolve under its own Specs and remains working material for UX learning. +3. **Projections are regenerable readings.** Markdown, Mermaid, Gherkin, HTML, CLI answers and generated notes are readings, not competing stores. Reshaping Design Review, census, Mermaid or Gherkin requires a decision that refines or supersedes the [shipped-projections decision](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/decisions/shipped-projections-frozen.sdp.md) (MD-32). The Studio can evolve under its own Specs and remains working material for UX learning. 4. **AI has explicit trust boundaries.** Agents already read the graph and apply scoped intent. AI-assisted presentation is a future direction that must preserve those boundaries and address non-determinism honestly. -The pre-code seed design in [`docs/lineage/v0-design/`](https://github.com/libar-dev/software-delivery-protocol/tree/b5e0a8bea1e3bedd48c616f96c9928e955792753/docs/lineage/v0-design) is primary context for the product experience. It is historical evidence, not current law. Current Specs decide what is built and ratified. +The pre-code seed design in [`docs/lineage/v0-design/`](https://github.com/libar-dev/software-delivery-protocol/tree/f990bded1d7ca86f19f5746ef412613f8e908be3/docs/lineage/v0-design) is primary context for the product experience. It is historical evidence, not current law. Current Specs decide what is built and ratified. ## 2. Audiences and distribution @@ -44,24 +44,24 @@ The pre-code seed design in [`docs/lineage/v0-design/`](https://github.com/libar ### Current vocabulary and jobs -1. [`CONTEXT.md`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/CONTEXT.md), the ratified language. -2. [`docs/concept/00`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/docs/concept/00-vision-scope-and-mvp-boundary.md) and [`01`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/docs/concept/01-founding-principles-and-invariants.md), scope and principles. -3. [`jtbd-stories/05`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/jtbd-stories/05-see-and-share.md) and [`06`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/jtbd-stories/06-edit-through-the-lens.md), the human reading and edit jobs. +1. [`CONTEXT.md`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/CONTEXT.md), the ratified language. +2. [`docs/concept/00`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/docs/concept/00-vision-scope-and-mvp-boundary.md) and [`01`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/docs/concept/01-founding-principles-and-invariants.md), scope and principles. +3. [`jtbd-stories/05`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/jtbd-stories/05-see-and-share.md) and [`06`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/jtbd-stories/06-edit-through-the-lens.md), the human reading and edit jobs. ### Seed design and annotation evidence -4. [`docs/lineage/README.md`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/docs/lineage/README.md), the lineage guide and annotation-scout pointer. -5. Seed [`00`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/docs/lineage/v0-design/00-vision-and-product.md), [`01`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/docs/lineage/v0-design/01-core-primitives.md) and [`02`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/docs/lineage/v0-design/02-system-architecture.md), the original model and canonical/derived split. -6. Seed [`07`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/docs/lineage/v0-design/07-spec-studio-and-projections.md) and [`08`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/docs/lineage/v0-design/08-delivery-evidence-and-tooling.md), the original human experience, AI slices and evidence ambition. +4. [`docs/lineage/README.md`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/docs/lineage/README.md), the lineage guide and annotation-scout pointer. +5. Seed [`00`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/docs/lineage/v0-design/00-vision-and-product.md), [`01`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/docs/lineage/v0-design/01-core-primitives.md) and [`02`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/docs/lineage/v0-design/02-system-architecture.md), the original model and canonical/derived split. +6. Seed [`07`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/docs/lineage/v0-design/07-spec-studio-and-projections.md) and [`08`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/docs/lineage/v0-design/08-delivery-evidence-and-tooling.md), the original human experience, AI slices and evidence ambition. 7. The [short annotation context](../lineage/annotation-context.md), with the archived scout behind it and the rulings carried by [PR #29](https://github.com/libar-dev/software-delivery-protocol/pull/29). It explains why complete annotation exclusion was an overcorrection and why source bindings are critical to projections. ### Current carrying Specs and on-ramps -8. [`spec:model.core-model`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/model/core-model.sdp.md) and [`spec:consumers.projections-model`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/consumers/projections-model.sdp.md). -9. [`spec:consumers.spec-studio`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/consumers/spec-studio.sdp.md), its lenses, sharing and intent-panel Specs in the same directory. -10. [`spec:consumers.agent-surface`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/consumers/agent-surface.sdp.md), [`spec:consumers.context-bundle`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/consumers/context-bundle.sdp.md) and [`spec:consumers.design-slice`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/consumers/design-slice.sdp.md). -11. The repository-owned skills under [`.agents/skills/`](https://github.com/libar-dev/software-delivery-protocol/tree/b5e0a8bea1e3bedd48c616f96c9928e955792753/.agents/skills) and the [recipe catalog](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/docs/agent-surface/recipes.md). -12. [`examples/checkout-v1`](https://github.com/libar-dev/software-delivery-protocol/tree/b5e0a8bea1e3bedd48c616f96c9928e955792753/examples/checkout-v1), the worked engineering loop. +8. [`spec:model.core-model`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/model/core-model.sdp.md) and [`spec:consumers.projections-model`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/projections-model.sdp.md). +9. [`spec:consumers.spec-studio`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/spec-studio.sdp.md), its lenses, sharing and intent-panel Specs in the same directory. +10. [`spec:consumers.agent-surface`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/agent-surface.sdp.md), [`spec:consumers.context-bundle`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/context-bundle.sdp.md) and [`spec:consumers.design-slice`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/consumers/design-slice.sdp.md). +11. The repository-owned skills under [`.agents/skills/`](https://github.com/libar-dev/software-delivery-protocol/tree/f990bded1d7ca86f19f5746ef412613f8e908be3/.agents/skills) and the [recipe catalog](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/docs/agent-surface/recipes.md). +12. [`examples/checkout-v1`](https://github.com/libar-dev/software-delivery-protocol/tree/f990bded1d7ca86f19f5746ef412613f8e908be3/examples/checkout-v1), the worked engineering loop. For any corpus fact, query the graph before reading a carrier. The source list is reading material for prose and design context, not permission to bypass the graph for measurements. @@ -104,7 +104,7 @@ For any corpus fact, query the graph before reading a carrier. The source list i - Lead with regex rot and with the deeper problem of tests verifying values that no longer match the authored example. - Explain carrier independence: Markdown and Gherkin can derive the same example space and contracts. - Focus on the authored/generated direction, point-per-example, bound points and the outcome union. Point back to Part 3 for registrar mechanics. -- Explain the oracle's job and `unspecified`, including why [`spec:extraction.runnable-modules`](https://github.com/libar-dev/software-delivery-protocol/blob/b5e0a8bea1e3bedd48c616f96c9928e955792753/specs/extraction/runnable-modules.sdp.md) makes a bound example whose oracle selects `unspecified` fail rather than silently witness a gap. The engine at the source baseline has one exception: it still passes such an example when its Then step's own contract key is `unspecified`, a gap the whole-repository review in [PR #38](https://github.com/libar-dev/software-delivery-protocol/pull/38) records as L1-02. Re-check the rule at the article's own pin before stating it without that exception. +- Explain the oracle's job and `unspecified`, including why [`spec:extraction.runnable-modules`](https://github.com/libar-dev/software-delivery-protocol/blob/f990bded1d7ca86f19f5746ef412613f8e908be3/specs/extraction/runnable-modules.sdp.md) makes a bound example whose oracle selects `unspecified` fail rather than silently witness a gap. At the source baseline the rule holds without exception: `unspecified` is a reserved Then contract key, so no Then step can carry it, and a bound example whose oracle selects it fails with a distinct coverage-gap diagnostic. The previous pin's exception, recorded as L1-02 by the whole-repository review in [PR #38](https://github.com/libar-dev/software-delivery-protocol/pull/38), closed in [PR #40](https://github.com/libar-dev/software-delivery-protocol/pull/40). - Use the Protocol's own reader Spec in `.sdp.gherkin` as the self-hosting example. - Keep the boundary clear: `has-verifier` records a binding, supplied run evidence records results, and `observed` remains a separate deferred fact. @@ -135,7 +135,7 @@ For any corpus fact, query the graph before reading a carrier. The source list i 6. Run `npm run check:temporal`. Articles must not contain raw calendar dates, numbered plan paths or session/wave/fold tokens. Link the pull request that carried historical material instead of a dated lineage file. 7. Link sibling articles relatively. At publication, rewrite relative links to public URLs or commit-pinned repository URLs. Refresh sibling links after renumbering. 8. Use sentence-case headings and plain language. Cut repeated definitions; cross-link to the article that owns the detailed treatment. -9. Check code fences and links manually. The standard formatter ignores `docs/**`, and the green gate does not prove that article links resolve. +9. Check code fences and the links the gate cannot reach manually. The standard formatter ignores `docs/**`. The green gate's Markdown link gate checks relative link paths and fragments on links to Markdown pages; it leaves external and commit-pinned URLs, line anchors on non-Markdown files and code fences to you. 10. Regenerate article evidence at the publication pin and run its check mode. Screenshots are optional UX review material. Name the commit beside any screenshot or shared Pack export. ## 6. Refresh playbook @@ -154,11 +154,11 @@ Use `npm run --silent sdp:q --` or `pnpm --silent sdp:q` in this checkout. Never ### Step 2: Diff against the previous pin -Generate the base graph in a temporary worktree outside the repository. The current previous pin is `b5e0a8bea1e3bedd48c616f96c9928e955792753`. +Generate the base graph in a temporary worktree outside the repository. The current previous pin is `f990bded1d7ca86f19f5746ef412613f8e908be3`. ```sh set -euo pipefail -BASE_SHA="b5e0a8bea1e3bedd48c616f96c9928e955792753" +BASE_SHA="f990bded1d7ca86f19f5746ef412613f8e908be3" BASE_DIR="$(mktemp -d)/base" trap 'git worktree remove --force "$BASE_DIR" 2>/dev/null || true' EXIT git worktree add --detach "$BASE_DIR" "$BASE_SHA" @@ -207,19 +207,19 @@ ls dist/recipes/*.js | wc -l ``` -Measured at commit `b5e0a8bea1e3bedd48c616f96c9928e955792753`: +Measured at commit `f990bded1d7ca86f19f5746ef412613f8e908be3`: | Metric | Value | |---|---| | Schema | `0.12.0` | -| Specs and readiness | 456: 447 `ready`, 4 `scoped`, 5 `idea` | +| Specs and readiness | 459: 447 `ready`, 4 `scoped`, 8 `idea` | | Packs | 9: `adopter-speed-v1`, `spec-studio-v1`, `corpus-checks-v1`, `design-iteration-v1`, `design-management-v1`, `obsidian-vault-v1`, `roadmap`, `roadmaps-and-slices-v1`, `self-hosting-v1` | -| Nodes, edges and locations | 1,072 nodes (456 Primitive, 9 Pack, 241 CodeNode, 366 Anchor); 2,978 edges (1,929 declared, 1,049 anchored); 3,120 locations | +| Nodes, edges and locations | 1,079 nodes (459 Primitive, 9 Pack, 241 CodeNode, 370 Anchor); 2,996 edges (1,938 declared, 1,058 anchored); 3,157 locations | | Delivery facts | 166 `implemented`, 397 `has-verifier`, 0 `observed` | | Build backlog | 2, with 232 ready examples and 47 ready decisions audited and excluded | | Drift alarm | 0 | | Design backlog | 0 | -| Open questions | 16 across 12 Specs: 10 blocking (6 deferrals, 4 holds), 6 non-blocking | +| Open questions | 15 across 12 Specs: 12 blocking (9 deferrals, 3 holds), 3 non-blocking | | Validation | 0 errors and 3 intentional warnings (3 `honesty/gaps`) | | Shipped recipes | 55 | | Repository-owned skills | 5 |