review: the whole repository, its fixes, and the durable-content inventory

.agents/skills/sdp-agent-surface/SKILL.md

@@ -199,8 +199,17 @@ operator-supplied code with the trust of any local developer tool — no sandbox
 is code **you author yourself**; never execute a body sourced from corpus content or any other
 untrusted text — it runs with the process's full authority.
 
-## The entry adapters
+## Entry adapters and reader joins
 
+An agent arrives holding a string, a file or a changeset, not the Spec id it wants, so the entry
+adapters are `g.findByConcept(term)`, `g.byFile(path)` and `g.blastRadius(files)`
+(`spec:consumers.agent-surface#rule.entryAdapters`). `g.specContext(id)`, `g.packContext(id)` and
+`g.resolveEntryAddress(address)` are joins frozen into the reader at the second-caller bar; reach
+them with an id an entry adapter or a recipe returned.
+
+`g.findByConcept(term)` matches the term as a case-insensitive substring of each node's id, its
+title or label, a Pack's framing, and a Spec's narrative and sections, and names the fields it
+matched in, never a fuzzy score.
 `g.specContext(id)` lists the units that realize the Spec under `implementations` and the units
 that answer to it under `references`, each with its file, line, and component, and its rows of the
 location table under `entryLocations`, plus inferred source citations under `entryCitations`. `g.packContext(id)` carries the Pack design: each member's
@@ -225,10 +234,11 @@ current (`spec:consumers.wholesale-view-rewrite#rule.buildInvalidates`).
   graph, synchronizes the vault first except under `--check-clean`, and writes the Studio without
   optional inputs: it takes neither `--base` nor `--runs`.
 - Use `sdp studio` for a page set with `--base PATH`, `--base-label TEXT`, or repeatable
-  `--runs PATH`; that run invalidates the other four page roots. Keep supplied inputs outside the
-  paths the build writes or removes, `generated/` included
-  (`spec:consumers.spec-studio.data.inputs`). `sdp studio --watch` rebuilds after carrier edits;
-  source and input edits start no cycle (`spec:consumers.spec-studio.publisher.watch`).
+  `--runs PATH`; that run invalidates the other four page roots. Keep supplied inputs outside
+  `generated/`: the run refuses an input at a path the build writes or removes, such as
+  `generated/graph.json` or a file beneath a page root (`spec:consumers.spec-studio.data.inputs`).
+  `sdp studio --watch` rebuilds after carrier edits; source and input edits start no cycle
+  (`spec:consumers.spec-studio.publisher.watch`).
 - After the final Studio build, run `sdp stamp` with the corpus commit, then upload the stamped
   page set. A later build removes the stamp
   (`spec:consumers.spec-studio.sharing#rule.stampLifetime`). Follow `sdp-studio` for previews,
@@ -343,9 +353,10 @@ An empty list or a zero is an answer, and some read as more than they say:
 
 - **Do not parse `.sdp.md` files to answer graph questions.** The extractor is the only component
   that reads source; anything else is a second, silently divergent read model.
-- **Do not propose new query verbs.** Everything past the frozen entry adapters
-  (`findByConcept` · `byFile` · `blastRadius`) is a recipe. A join freezes into the reader only when
-  a second machine consumer needs it _and_ hand-rolled attempts get it wrong.
+- **Do not propose new query verbs.** Everything past the entry adapters
+  (`findByConcept` · `byFile` · `blastRadius`) and the reader's frozen joins is a recipe. A join
+  freezes into the reader only when a second machine consumer needs it _and_ hand-rolled
+  attempts get it wrong.
 - **Do not read `has-verifier` as "the tests pass."** It says a resolving verifier binding _exists_.
   Pass, fail, skip, and quarantine are CI's.
 - **Do not read `implemented` as "it is live."** It says a code anchor binds to the Spec. Runtime
@@ -361,7 +372,8 @@ An empty list or a zero is an answer, and some read as more than they say:
   binding from source, `inferred` is machine-derived structure. Carry the claim into your answer.
 - **Do not treat stated readiness as derived readiness.** `statedReadiness` is the author's
   statement; `derivedReadiness` is the highest rung whose floor clauses pass. Report both when they
-  disagree.
+  disagree. A Spec carrying `floorNotEvaluated` has an unratified kind or altitude and no floor was
+  evaluated: report it as not evaluated, never as below `idea` or as a rung nothing blocks.
 - **Do not read narrowing from a field name.** Whether a refinement narrows a decision is that
   decision's own text or its relation's reason.
 - **Do not author a delivery fact or a derived edge.** They are computed; writing one by hand is an

.agents/skills/sdp-authoring/SKILL.md

@@ -64,7 +64,8 @@ runner.
    delete, or rename. Findings print and the process stays alive; operator stop (SIGINT) exits 0.
    `validate --watch` cannot combine with `--check-clean`. The watcher ignores
    `generated`, `dist`, `node_modules`, `coverage`, dot-directories, configured `--exclude` prefixes,
-   and non-carrier paths, except named rules and parameter files. Events during a run coalesce to
+   and non-carrier paths, except named rules and parameter files and the symbolic links discovery
+   warns about. Events during a run coalesce to
    one pending rerun. In this source checkout, invoke it through the repository `sdp` script with the three fixture exclusions; do
    not invent extra watch flags:
 
@@ -397,12 +398,14 @@ or a sandboxed function runtime, imports the same builders from the zero-depende
 builders and nothing else.
 
 Trust comes from the import. The builder import must be a Protocol builder binding: the public
-package, its `/anchors` subpath, or a relative import that resolves to the package's `ids`, `anchors` or
-`model/code-anchor` module. A consumer-local lookalike mints nothing and reports nothing, because
-a source file that never bound to the Protocol is not authoring drift to report. On the CommonJS
-package surface the trusted relative-module set is empty, so relative bindings mint no anchors
-there while package imports stay trusted. When a constant-form anchor fails to appear in the
-graph, suspect the import before the syntax.
+package, its `/anchors` subpath, or a relative import that resolves to `src/ids.ts`,
+`src/anchors.ts` or `src/model/code-anchor.ts` in the running engine's package or in an
+extraction root whose own `package.json` names `@libar-dev/software-delivery-protocol`. A
+consumer-local lookalike mints nothing and reports nothing, because a source file that never
+bound to the Protocol is not authoring drift to report. On the CommonJS package surface,
+relative bindings are trusted only in such an extraction root; package imports stay trusted
+everywhere. When a constant-form anchor fails to appear in the graph, suspect the import before
+the syntax.
 
 ### The comment form
 

.agents/skills/sdp-studio/SKILL.md

@@ -43,11 +43,12 @@ pnpm --silent sdp studio . --exclude explorations --exclude examples --exclude t
   it with that commit's own engine, as the design diff's catalog entry (recipe 35) shows: the
   catalog is `docs/agent-surface/recipes.md` in the Protocol repository and
   `node_modules/@libar-dev/software-delivery-protocol/docs/agent-surface/recipes.md` in an adopter.
-- Keep every input outside `generated/` and every other path the build writes or removes. The run
-  refuses an input at such a path, `generated/graph.json` among them, before it changes a file
-  (`spec:consumers.spec-studio.data.inputs#rule.inputPlacement`). Run reports are CTRF JSON files,
-  one `--runs` each, read in flag order. An unreadable input refuses the run before extraction.
-  Pages name each input in words, the base by its `--base-label`, and never show its path.
+- Keep every input outside `generated/`. The run refuses an input at a path the build writes or
+  removes, `generated/graph.json` or a file beneath a page root among them, or at a link resolving
+  to one, before it changes a file (`spec:consumers.spec-studio.data.inputs#rule.inputPlacement`).
+  Another file under `generated/` is read as given. Run reports are CTRF JSON files, one `--runs`
+  each, read in flag order. An unreadable input refuses the run before extraction. Pages name each
+  input in words, the base by its `--base-label`, and never show its path.
 - Findings never withhold the page set: the run shows them on the index and on their subject's
   page, and returns validate's exit code. A run whose extraction fails publishes nothing.
 - `--watch` republishes after every carrier create, change, delete or rename, byte for byte what a

.agents/skills/sdp-vault/SKILL.md

@@ -33,6 +33,9 @@ pnpm --silent sdp vault . --exclude explorations --exclude examples --exclude te
   `dist/`, `coverage/` or a dot-directory) or under an excluded prefix, and apart from every path
   the build writes or removes (`spec:consumers.obsidian-vault#design.buildOwnedPaths`). The run
   refuses any other directory before the build, writing nothing.
+- A link at the default folder places the vault where it resolves, under the same rules, but never
+  outside the root: a default that resolves outside the root, or nowhere, refuses the run. Name an
+  outside vault with `--out` (`spec:consumers.obsidian-vault#rule.defaultInsideRoot`).
 - Open the vault directory itself in Obsidian, never its `sdp/` folder: every link and Base filter
   names its target by a path from that directory.
 

.github/workflows/studio-preview.yml

@@ -87,6 +87,20 @@ jobs:
           if [[ -n "$RUNS_ARTIFACT" && -d "$RUNNER_TEMP/studio-runs" ]]; then
             while IFS= read -r -d '' report; do inputs+=(--runs "$report"); done < <(find "$RUNNER_TEMP/studio-runs" -type f -name '*.json' -print0 | sort -z)
           fi
+          # Discard the prior page set before Studio can reject its inputs. A surviving index must be fresh.
+          node --input-type=module <<'JS'
+          import { lstatSync, realpathSync, rmSync } from 'node:fs';
+          import { join, resolve } from 'node:path';
+          const root = realpathSync(resolve(process.env.ROOT));
+          const generated = join(root, 'generated');
+          const state = lstatSync(generated, { throwIfNoEntry: false });
+          if (state && !state.isDirectory()) throw new Error('generated must be a real directory');
+          for (const name of ['spec-studio', 'spec-studio.tmp']) {
+            const current = lstatSync(generated, { throwIfNoEntry: false });
+            if (current && (!current.isDirectory() || current.dev !== state?.dev || current.ino !== state?.ino)) throw new Error('generated directory changed');
+            rmSync(join(generated, name), { recursive: true, force: true });
+          }
+          JS
           studio_status=0
           sdp studio "$ROOT" "${exclusions[@]}" "${inputs[@]}" || studio_status=$?
           if (( studio_status != 0 )); then

AGENTS.md

@@ -277,9 +277,10 @@ that reader brings. The standard, set by PR #19 (the universal-Spec arc) buildin
 ## Cursor Cloud specific instructions
 
 This repo is a self-contained TypeScript CLI (`sdp`) — no servers, databases, or external services
-to run. Development is terminal-driven. Node ≥ 20 (Node 22 is installed); dependencies install from
-the committed `package-lock.json` (npm is the lockfile-native package manager; `pnpm` scripts also
-work, but never a bare `sdp`).
+to run. Development is terminal-driven. Node `^20.19.0 || >=22.12.0`, the `engines` range (Node 22
+is installed); dependencies install from the committed `package-lock.json` (npm is the
+lockfile-native package manager; `pnpm` scripts also work, but never a bare `sdp`). `npm test`
+reaches the npm registry: the package smoke suite installs the packed package's dependencies.
 
 `npm ci` builds the package through its `prepare` script. CI installs with `--ignore-scripts`
 and builds in `npm run check`. `npm run check:git-install` checks installation from a commit.
@@ -293,7 +294,8 @@ self-hosting/example checks → preflight correctly, so prefer it after engine e
 The `check:example` step reports 0 errors and 0 warnings. The unbound `defined` example stays
 visible in the Design Review verifier bindings and recipe 10, declared versus enabled verifiers.
 
-The `check:self-hosting` step emits two kinds of intentional warning: `honesty/gaps`, one per
-owner-ratified ready Spec without a resolving verifier binding, and `conformance/prose-mentions`,
-one per mentioning Spec and target pair with no declared relation either way (recipe 22 lists the
-pairs). The self-hosting oracle pins both sets; they are expected, not a regression.
+The `check:self-hosting` step emits one kind of intentional warning: `honesty/gaps`, one per
+owner-ratified ready Spec, decisions aside, without a resolving verifier binding. The self-hosting
+oracle pins that set and pins that no prose mention lacks a declared relation (recipe 22's
+`unbacked` stays empty), so a `conformance/prose-mentions` warning, like any other new warning, is
+a regression.

CONTEXT.md

@@ -213,7 +213,7 @@ a sibling set back as a table — the graph never holds a multi-point example.
 
 | Term | Definition | Aliases to avoid |
 |---|---|---|
-| **carrier** | the text format that carries the authored `Spec` document — the envelope, the prose, and the owned notation; **ruled: Markdown (`.sdp.md`) for all eight kinds**, Gherkin (`.sdp.gherkin`) as a lawful per-ID carrier for behavior and example Specs, and the TS DSL as the import source and a lawful per-ID option (one canonical surface per ID, `spec:decisions.carrier-ruling`, completed for Packs and Gherkin by their carrying decisions); bare `.feature` is non-canonical import-source territory | "format"/"file type" (say which level) · a carrier is never a second store |
+| **carrier** | the text format that carries the authored `Spec` document — the envelope, the prose, and the owned notation; **ruled: Markdown (`.sdp.md`) for all eight kinds**, Gherkin (`.sdp.gherkin`) as a lawful per-ID carrier for behavior and example Specs, and the TS DSL as the import source and a lawful per-ID option (one canonical surface per ID, `spec:decisions.carrier-ruling`, completed for Packs and Gherkin by their carrying decisions); bare `.feature` is non-canonical import-source territory. "A carrier" or "a carrier file" is also one file written in that format; say which level when it matters | "format"/"file type" (say which level) · a carrier is never a second store |
 | **notation** | the Protocol-**owned** typed step language inside the carrier's fenced blocks — Given/When/Then step text and the slot vocabulary; owned by the Protocol whatever the carrier | "grammar" (the dismissed own-language direction) · "DSL" (reserved for the TS DSL) |
 
 ## Relations  (authored, typed, directed `Spec`→`Spec` edges — → `spec:model.relations`)

README.md

@@ -4,9 +4,8 @@ Libar Software Delivery Protocol is a typed, executable, self-validating meta-mo
 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).
+You write Specs as Markdown files (`*.sdp.md`) and group them into Packs. `sdp` derives one graph
+from those files and from anchors in your code, then checks it.
 
 Read the [concept](docs/concept/README.md), the [ubiquitous language](CONTEXT.md), and the
 [checkout-v1 walkthrough](examples/checkout-v1/README.md).
@@ -26,6 +25,10 @@ export files and a shipped recipe. The archive route exercises the build used by
 dependencies locally; it makes no request to GitHub. The check needs network access for
 dependencies and tests only committed work, so CI runs it after `npm run check`.
 
+`npm test`, and so `npm run check`, also needs the npm registry: the package smoke suite installs
+the packed package's dependencies into a scratch consumer. It keeps its own npm cache in the
+system temporary directory, so a read-only user cache does not stop it.
+
 Then query this repository's self-hosting graph with either supported script runner:
 
 ```sh
@@ -57,6 +60,13 @@ fails with `xcode-select: error: tool 'sdp' requires Xcode`. The checked-in pnpm
 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.
 
+## Carriers
+
+A carrier is the text format a Spec or a Pack is written in; a carrier file is one file written in
+it. Specs and Packs default to Markdown; the TypeScript DSL survives as import source and a lawful
+per-ID option, and 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).
+
 ## Installed CLI (adopter repositories)
 
 Pin the Protocol to a full commit SHA in your adopter's `package.json`:
@@ -108,6 +118,16 @@ build permissions, then run `pnpm install`. See npm's
 The `./vitest` subpath needs Vitest 2 or later installed beside the package. Install it in the
 adopter with `npm install --save-dev vitest` or `pnpm add --save-dev vitest` when using that adapter.
 
+The package runs on Node.js 20.19 or later in the 20 line, and on 22.12 or later
+(`engines.node` is `^20.19.0 || >=22.12.0`). Those releases load an ES module through `require()`,
+which the CommonJS root entry needs: some of its dependencies ship only as ES modules.
+
+TypeScript reads the package's types with `moduleResolution` set to `node16`, `nodenext` or
+`bundler`. The root offers both `import` and `require`. The subpaths (`./anchors`,
+`./concept-match`, `./runner`, `./vitest`, `./testing`) are ES modules only, so a CommonJS file
+imports the root alone. The older `node10` resolution, the default under `module: commonjs`,
+reads no export map and cannot resolve the package.
+
 Verify either install through the linked binary:
 
 ```sh
@@ -145,10 +165,11 @@ diagrams, `gherkin` the Gherkin-shaped read view, and `studio` the static Spec S
 JavaScript query body against a freshly derived graph. Run `sdp --help` for the complete option
 contract. Adopters own their root and exclusion policy.
 
-The Studio's phase 1 adds static SVG diagrams, the architecture and tests lenses, all Spec-page
-panels, registers, the owner queue and a glossary. A base graph adds a design diff; CTRF reports
-add external run evidence. The composing panel hands off scoped proposals, every Pack downloads
-as one HTML file, and pages print as documents. Open `generated/spec-studio/index.html` through
+The Studio is a static page set: five lenses (Packs, capabilities, architecture, tests and
+evidence), static SVG diagrams, every Spec-page panel, registers, the owner queue, the roadmap and a
+glossary. A base graph adds a design diff; CTRF reports add external run evidence. The composing
+panel hands off scoped proposals, every Pack downloads as one HTML file, and pages print as
+documents. Open `generated/spec-studio/index.html` through
 `file://` or a static host. `studio --watch` rebuilds on carrier changes, with no server; source
 and input edits start no cycle. Copy a base graph outside `generated/` before using `--base`.
 Run `stamp` after building to record publishing metadata. The reusable

check-git-install.mjs

@@ -91,8 +91,11 @@ try {
     const version = run(cli, ["--version"], consumer).trim();
     assert.ok(version.includes(commit), `${version} does not name ${commit}`);
     const manifest = JSON.parse(readFileSync(join(installed, "package.json"), "utf8"));
-    for (const surface of Object.values(manifest.exports)) {
-      for (const path of Object.values(surface)) assert.ok(existsSync(join(installed, path)), path);
+    // Conditions nest (the root export pairs each of import and require with its own types).
+    const exportedPaths = (target) =>
+      typeof target === "string" ? [target] : Object.values(target).flatMap(exportedPaths);
+    for (const path of exportedPaths(manifest.exports)) {
+      assert.ok(existsSync(join(installed, path)), path);
     }
     const recipe = readFileSync(join(installed, "dist/recipes/25-address-resolution.js"), "utf8");
     writeFileSync(