@canonical/pragma-cli 0.36.0 → 0.37.0

package/src/capabilities/setup/setup.test.ts

@@ -101,6 +101,14 @@ const stubPath = (): string => {
   return dir;
 };
 
+/**
+ * The machine's real PATH, captured before the suite isolates it. A stub
+ * editor script that has to run a real utility (`rm`) restores this INSIDE
+ * itself — hardcoding `/bin:/usr/bin` breaks on hosts that keep coreutils
+ * elsewhere, and the isolated PATH the tests run under has no `rm`.
+ */
+const HOST_PATH = process.env.PATH ?? "";
+
 let prevHome: string | undefined;
 let prevPath: string | undefined;
 beforeEach(() => {
@@ -835,12 +843,16 @@ describe("setup lsp — the removal contract the other four rows implement", ()
   it("end to end: `setup lsp --undo` reports `Undid 1 step(s)` against a STUB cli", async () => {
     // The reported symptom was `Undid 0 step(s).` at exit 0. The stub is a
     // marker-writing script — never a real editor: an undo test must not be
-    // able to mutate the machine running it.
+    // able to mutate the machine running it. It DOES delete the seeded
+    // extension entry (inside this test's temp HOME), because the removal now
+    // asserts its own goal against the extensions directory: a stub that
+    // exits 0 leaving the entry behind is the LYING-editor case, pinned as a
+    // failure below.
     const marker = join(tmp("pragma-lsp-undo-"), "uninstalled");
     const dir = stubPath();
     writeFileSync(
       join(dir, "code"),
-      `#!/bin/sh\nprintf '%s\\n' "$@" > ${marker}\n`,
+      `#!/bin/sh\nprintf '%s\\n' "$@" > ${marker}\nPATH='${HOST_PATH}' rm -rf "$HOME/.vscode/extensions/canonical.terrazzo-lsp-extension-"*\n`,
       { mode: 0o755 },
     );
     process.env.PATH = dir;
@@ -872,6 +884,205 @@ describe("setup lsp — the removal contract the other four rows implement", ()
     expect(all.some((e) => e._tag === "DeleteFile")).toBe(false);
     expect(all.some((e) => e._tag === "DeleteDirectory")).toBe(false);
   });
+
+  /** Drive `setup lsp --undo` capturing stderr (where the row lines land). */
+  const undoLspCapturing = async (): Promise<{
+    chunks: string[];
+    outcome?: { stdout?: string; stderr?: string; exitCode: number };
+    thrown?: unknown;
+  }> => {
+    const chunks: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: unknown): boolean => {
+        chunks.push(String(chunk));
+        return true;
+      });
+    try {
+      const outcome = await executeVerb(
+        verbOf("lsp"),
+        {},
+        UNDO,
+        bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      );
+      return { chunks, outcome };
+    } catch (thrown) {
+      return { chunks, thrown };
+    } finally {
+      spy.mockRestore();
+    }
+  };
+
+  it("HEADLINE: an uninstall that exits 0 leaving the extension on disk reports FAILED, never `✓ removed`", async () => {
+    // The observed field defect: VS Code-family CLIs can exit 0 while
+    // deferring or skipping the deletion. The reversal's success criterion
+    // was that exit code; detection's criterion is the extensions DIRECTORY.
+    // The two disagreed permanently and the run printed `✓ … removed` over an
+    // extension that was still installed. The removal now asserts its own
+    // goal in-task — probe the owned entries after the uninstall — and the
+    // run reports the survival as a failure with a manual remedy.
+    const dir = stubPath();
+    writeFileSync(join(dir, "code"), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+    process.env.PATH = dir;
+    seedExtension(".vscode", "1.2.3");
+    const survivor = join(
+      process.env.HOME ?? "",
+      ".vscode",
+      "extensions",
+      "canonical.terrazzo-lsp-extension-1.2.3",
+    );
+
+    const { chunks, outcome, thrown } = await undoLspCapturing();
+    const stderrText = chunks.join("");
+
+    // The world: the artifact survived, and the run must not claim otherwise.
+    expect(existsSync(survivor)).toBe(true);
+    expect(stderrText).not.toContain("— removed");
+    expect(outcome).toBeUndefined();
+    expect(thrown).toBeDefined();
+    const err = asPragmaError(thrown);
+    expect(err.code).toBe("UNSUPPORTED");
+    expect(err.message).toContain("lsp");
+    expect(err.message).toContain("still present after the undo ran");
+    // The remedy names the surviving path as DATA for a manual deletion —
+    // not the CLI command that has just demonstrably done nothing while
+    // reporting success, and not a synthesized shell line (the entry names
+    // come off the filesystem, so no quoting is trustworthy, and one command
+    // cannot be right for every supported platform).
+    expect(err.recovery?.message ?? "").toContain(survivor);
+    expect(err.recovery?.message ?? "").not.toContain("rm -rf");
+    expect(err.recovery?.message ?? "").not.toContain("--uninstall-extension");
+    // The truthful row is reported (stderr), naming the survival.
+    expect(stderrText).toContain("still present after the undo ran");
+  });
+
+  it("a DANGLING matching symlink still counts as a survivor — the probe uses detection's criterion", async () => {
+    // Detection calls an entry present when `readdirSync` lists it. A probe
+    // built on default `exists` (`fs.access`) FOLLOWS symlinks, so a dangling
+    // matching symlink would be "installed" to detection and "absent" to the
+    // probe: an editor that exits 0 without removing it would report
+    // `undone`, and the next detection would find it again — the exact
+    // "reports success it did not achieve" this fix exists to close, rebuilt
+    // inside the fix. The probe therefore asks about the entry itself
+    // (lstat semantics), the same question the directory listing answers.
+    const dir = stubPath();
+    writeFileSync(join(dir, "code"), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+    process.env.PATH = dir;
+    const extensionsDir = join(process.env.HOME ?? "", ".vscode", "extensions");
+    mkdirSync(extensionsDir, { recursive: true });
+    const entry = join(extensionsDir, "canonical.terrazzo-lsp-extension-1.2.3");
+    symlinkSync(join(extensionsDir, "no-such-target"), entry);
+
+    const { chunks, outcome, thrown } = await undoLspCapturing();
+
+    expect(lstatSync(entry).isSymbolicLink()).toBe(true); // still there
+    expect(chunks.join("")).not.toContain("— removed");
+    expect(outcome).toBeUndefined();
+    const err = asPragmaError(thrown);
+    expect(err.message).toContain("still present after the undo ran");
+    expect(err.recovery?.message ?? "").toContain(entry);
+  });
+
+  it("a truthful uninstall reports its `removed` row from the executed reversal", async () => {
+    // The positive half of the headline: when the editor really deletes the
+    // entry, the in-task postcondition passes, the reversal's outcome comes
+    // back `undone`, and the row reports `removed` — same sentence as before
+    // the fix, now derived from what ran instead of from the plan.
+    const dir = stubPath();
+    writeFileSync(
+      join(dir, "code"),
+      `#!/bin/sh\nPATH='${HOST_PATH}' rm -rf "$HOME/.vscode/extensions/canonical.terrazzo-lsp-extension-"*\n`,
+      { mode: 0o755 },
+    );
+    process.env.PATH = dir;
+    seedExtension(".vscode", "1.2.3");
+
+    const { chunks, outcome, thrown } = await undoLspCapturing();
+    expect(thrown).toBeUndefined();
+    expect(outcome?.exitCode).toBe(0);
+    expect(outcome?.stdout).toBe("Undid 1 step(s).\n");
+    expect(chunks.join("")).toContain("— removed");
+  });
+
+  it("the `✓ … removed` rows cannot be produced by the collection walk alone", async () => {
+    // The collection walk mocks every exec to exit 0 and every prompt to its
+    // default — under the old code that was enough to print the whole green
+    // recap before one real process had spawned. With an uninstall that
+    // GENUINELY fails (exit 1), the executed reversal fails; if any `removed`
+    // row still appeared on stderr, it could only have come from the mocked
+    // walk.
+    const dir = stubPath();
+    writeFileSync(join(dir, "code"), "#!/bin/sh\nexit 1\n", { mode: 0o755 });
+    process.env.PATH = dir;
+    seedExtension(".vscode", "1.2.3");
+
+    const { chunks, outcome, thrown } = await undoLspCapturing();
+    expect(chunks.join("")).not.toContain("— removed");
+    expect(outcome).toBeUndefined();
+    expect(thrown).toBeDefined();
+    const err = asPragmaError(thrown);
+    expect(err.message).toContain("--uninstall-extension");
+    expect(err.message).toContain("exited with code 1");
+  });
+
+  it("appliedUndo grades rows from the outcomes — one model, both directions", async () => {
+    // The projection unit: the sink the FORWARD run fills is fed by the undo
+    // interpreter's outcomes instead, and the same `outcomeFor` reads it
+    // back. A failed outcome keyed to the row fails the row (carrying the
+    // reversal's own remedy); an actionable row that no reversal reported
+    // back for cannot claim `removed`; a run with clean outcomes reports
+    // `removed`.
+    seedExtension(".vscode", "1.2.3");
+    const run = await buildSetupRun(
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      "lsp",
+      "global",
+      true,
+    );
+
+    const clean = run.appliedUndo([{ key: "global:lsp", status: "undone" }]);
+    expect(clean.rows.find((r) => r.target === "lsp")?.outcome).toMatchObject({
+      status: "removed",
+      note: "removed",
+    });
+
+    const failed = run.appliedUndo([
+      {
+        key: "global:lsp",
+        status: "failed",
+        error: { code: "UNSUPPORTED", message: "still there" },
+      },
+    ]);
+    expect(failed.rows.find((r) => r.target === "lsp")?.outcome).toMatchObject({
+      status: "failed",
+      note: "still there",
+    });
+
+    // No reversal reported back at all for an actionable row: never `removed`.
+    const silent = run.appliedUndo([]);
+    expect(silent.rows.find((r) => r.target === "lsp")?.outcome).toMatchObject({
+      status: "failed",
+      note: "no reversal was executed for this target",
+    });
+  });
+
+  it("a removal row with nothing owned reports `kept`, not a green noop", async () => {
+    // The `kept` status was declared in the vocabulary and counted by
+    // `planTally` but no producer ever emitted it. On a removal, a `none`
+    // row IS the kept case: the run owned nothing here and deliberately left
+    // the machine's state standing — standing aside (○), not work done (✓).
+    const run = await buildSetupRun(
+      bootRuntime(FLAGS, tmp("pragma-setup-proj-")),
+      "lsp",
+      "global",
+      true,
+    );
+    expect(run.plan.rows.find((r) => r.target === "lsp")?.action).toBe("none");
+    const kept = run.appliedUndo([]);
+    expect(kept.rows.find((r) => r.target === "lsp")?.outcome).toEqual({
+      status: "kept",
+    });
+  });
 });
 
 describe("setup (run-all wizard) — scope threading", () => {
@@ -1296,6 +1507,40 @@ describe("setup skills", () => {
     expect(() => lstatSync(linkPath)).toThrow();
   });
 
+  it("the removal plan's children are the FOLDERS the links live in, deduped", async () => {
+    // `dirs` mapped `a.linkPath` — one path per LINK — so the `new Set(…)`
+    // deduped nothing and the removal preview printed an N-path wall where
+    // the forward plan says `N skills → M folders`. The folders are the
+    // links' parent directories.
+    const cwd = tmp("pragma-setup-proj-");
+    const linkDir = join(cwd, ".agents", "skills");
+    mkdirSync(linkDir, { recursive: true });
+    for (const name of ["s1", "s2"]) {
+      const skillDir = join(cwd, ".pragma", "skills", name);
+      mkdirSync(skillDir, { recursive: true });
+      writeFileSync(
+        join(skillDir, "SKILL.md"),
+        `---\nname: ${name}\ndescription: A test skill.\n---\n`,
+      );
+      symlinkSync(skillDir, join(linkDir, name));
+    }
+    const detected = await detectSkills(bootRuntime(FLAGS, cwd), "project");
+    expect(ownedSkillLinks(detected)).toHaveLength(2);
+
+    const { findTarget } = await import("./targets.js");
+    const draft = findTarget("skills")?.removalPlan(
+      detected as never,
+      "project",
+      { global: process.env.HOME ?? "", project: cwd },
+    );
+    expect(draft?.action).toBe("remove");
+    expect(draft?.detail).toBe("2 links");
+    // TWO links, ONE folder: the children name the folder once, not each link.
+    expect(draft?.children?.map((c) => c.label)).toEqual([
+      `.${sep}${join(".agents", "skills")}`,
+    ]);
+  });
+
   it("owns a RELATIVE link into the skill root, resolved against the link dir", async () => {
     // `readlink` reports the raw target, which may be relative — resolving it
     // against the link's own directory is what makes the containment test

package/src/capabilities/setup/setup.verb.ts

@@ -209,6 +209,31 @@ async function runSetup(
   // to know which of the two it is.
   const previewing = interactionMode === "batch-dry-run";
 
+  // The undo truth channel. A real `--undo` interprets this verb's task ONLY
+  // as the undo interpreter's mocked collection walk — every exec exits 0,
+  // every prompt answers its default, and the OutcomeSink is never written —
+  // so nothing the task body could report describes what the collected
+  // reversals later did. The body therefore says NOTHING on the undo path
+  // (see the guard in the gen body below); the kernel calls this seam after
+  // the reversals actually ran, handing over the interpreter's per-undo
+  // outcomes, and `appliedUndo` projects them onto the rows through the SAME
+  // sink + `applied` path the forward run reports through. One outcome
+  // model, both directions.
+  if (!previewing && input.undo) {
+    rt.undoReport = (outcomes) => {
+      const applied = run.appliedUndo(outcomes);
+      const width = Math.max(...applied.rows.map((row) => row.target.length));
+      for (const row of applied.rows) {
+        if (row.outcome === undefined) continue;
+        rt.report?.(renderProgressLine(row, width));
+      }
+      if (planExitFailed(applied)) {
+        rt.report?.(renderRecap(applied, "Removed"));
+        raiseFailedRows(applied, true);
+      }
+    };
+  }
+
   // A CONVERGED machine has no question to ask. Every row is `none` or `skip`,
   // so nothing composes an effect — and the wizard's confirm gate then mounted
   // Ink to render summon-core's "No operations planned." above a "Proceed?"
@@ -313,6 +338,16 @@ async function runSetup(
     const result = yield* $(task);
     const applied = run.applied(result.answers);
 
+    // A real `--undo` only ever drives this body under the undo
+    // interpreter's COLLECTION walk, with every effect mocked. `applied` is
+    // then a projection of the mocked walk (`removed` rows for reversals
+    // that have not run yet), so reporting it here printed green checks
+    // before anything happened. Say nothing; the kernel hands the executed
+    // reversals' outcomes to `rt.undoReport` afterwards, and `appliedUndo`
+    // grades the rows from those. (`--undo --dry-run` stays on the shared
+    // preview path below, where the same suppressions already apply.)
+    if (input.undo && !previewing) return applied;
+
     // Progress: one line per row on stderr for an unattended run (the Ink
     // session already draws them for the wizard). stdout stays the data stream.
     //
@@ -333,45 +368,58 @@ async function runSetup(
     // stdout on a failing run.
     if (planExitFailed(applied)) {
       rt.report?.(renderRecap(applied));
-      const failed = applied.rows.filter(
-        (row) => row.outcome?.status === "failed",
-      );
-
-      // ONE failure reports itself. The row already carries the cause it was
-      // given ("`bun` is not found on your PATH") and a remedy that runs on
-      // this machine; replacing them with a count would throw away the only
-      // two sentences that say what is wrong and what to do about it.
-      const only = failed.length === 1 ? failed[0] : undefined;
-      if (only?.outcome !== undefined) {
-        throw new PragmaError({
-          code: "UNSUPPORTED",
-          message: `${only.target}: ${only.outcome.note ?? "the step did not complete"}`,
-          ...(only.outcome.remedy === undefined
-            ? {}
-            : { recovery: { message: only.outcome.remedy } }),
-        });
-      }
+      raiseFailedRows(applied);
+    }
+    return applied;
+  });
+}
 
-      // Several failures: name every one with its own cause, then point at the
-      // recap above. A bare list of target names would make the reader re-run
-      // each one to find out why it failed.
-      const named = failed
+/**
+ * Raise the run's failure from its rows — shared by the forward run's recap
+ * and the post-undo truth report, so the two paths name a shortfall in the
+ * same words. `undo` only re-words the multi-failure recovery line: the
+ * command that retries a removal is `setup <target> --undo`, not the
+ * installer.
+ *
+ * @param applied - The plan with outcomes filled in (at least one `failed`).
+ * @param undo - Whether the failed run was a removal.
+ * @throws PragmaError naming the failed row(s), always.
+ */
+function raiseFailedRows(applied: SetupPlan, undo = false): never {
+  const failed = applied.rows.filter((row) => row.outcome?.status === "failed");
+
+  // ONE failure reports itself. The row already carries the cause it was
+  // given ("`bun` is not found on your PATH") and a remedy that runs on
+  // this machine; replacing them with a count would throw away the only
+  // two sentences that say what is wrong and what to do about it.
+  const only = failed.length === 1 ? failed[0] : undefined;
+  if (only?.outcome !== undefined) {
+    throw new PragmaError({
+      code: "UNSUPPORTED",
+      message: `${only.target}: ${only.outcome.note ?? "the step did not complete"}`,
+      ...(only.outcome.remedy === undefined
+        ? {}
+        : { recovery: { message: only.outcome.remedy } }),
+    });
+  }
+
+  // Several failures: name every one with its own cause, then point at the
+  // recap above. A bare list of target names would make the reader re-run
+  // each one to find out why it failed.
+  const named = failed
+    .map((row) => `${row.target} (${row.outcome?.note ?? "no cause recorded"})`)
+    .join("; ");
+  throw new PragmaError({
+    code: "UNSUPPORTED",
+    message: `${failed.length} of ${planTally(applied).accountable} targets did not complete: ${named}.`,
+    recovery: {
+      message: `The other targets are ${undo ? "removed" : "configured"}. Re-run the ones that did not complete: ${failed
         .map(
           (row) =>
-            `${row.target} (${row.outcome?.note ?? "no cause recorded"})`,
+            `\`${BIN_NAME} setup ${row.target}${undo ? " --undo" : ""}\``,
         )
-        .join("; ");
-      throw new PragmaError({
-        code: "UNSUPPORTED",
-        message: `${failed.length} of ${planTally(applied).accountable} targets did not complete: ${named}.`,
-        recovery: {
-          message: `The other targets are configured. Re-run the ones that did not complete: ${failed
-            .map((row) => `\`${BIN_NAME} setup ${row.target}\``)
-            .join(", ")}.`,
-        },
-      });
-    }
-    return applied;
+        .join(", ")}.`,
+    },
   });
 }
 

package/src/capabilities/setup/targets.ts

@@ -24,6 +24,7 @@
  * doctor's), so nothing here lands on the `--help`/`__complete` fast path.
  */
 
+import { dirname } from "node:path";
 import type { Task } from "@canonical/task";
 import { BIN_NAME } from "../../constants.js";
 import type { PragmaRuntime } from "../../kernel/runtime/index.js";
@@ -112,8 +113,12 @@ export interface TargetDefinition<D> {
    * paths); a row without children ignores it.
    */
   compose(detection: D, chosen?: readonly string[]): Task<void>;
-  /** The removal effects: forward re-assertion carrying the reversal as `undo`. */
-  composeRemoval(detection: D): Task<void>;
+  /**
+   * The removal effects: forward re-assertion carrying the reversal as
+   * `undo`. `undoKey` (the row's identity) is stamped on every reversal so
+   * the undo interpreter's outcomes can be read back per row.
+   */
+  composeRemoval(detection: D, undoKey?: string): Task<void>;
 }
 
 /** A table row with its detection type erased — how every consumer holds one. */
@@ -150,7 +155,7 @@ const configTarget = defineTarget<ConfigDetection>({
     return { action: "remove", detail: path };
   },
   compose: (d) => composeConfigFile(d),
-  composeRemoval: (d) => composeConfigRemoval(d),
+  composeRemoval: (d, undoKey) => composeConfigRemoval(d, undoKey),
 });
 
 const completionsTarget = defineTarget<CompletionsDetection>({
@@ -207,7 +212,7 @@ const completionsTarget = defineTarget<CompletionsDetection>({
     return { action: "remove", detail: shortenPath(d.path, roots) };
   },
   compose: (d) => composeCompletions(d),
-  composeRemoval: (d) => composeCompletionsRemoval(d),
+  composeRemoval: (d, undoKey) => composeCompletionsRemoval(d, undoKey),
 });
 
 const lspTarget = defineTarget<LspDetection>({
@@ -283,7 +288,7 @@ const lspTarget = defineTarget<LspDetection>({
     };
   },
   compose: (d, chosen) => composeLsp(d, chosen),
-  composeRemoval: (d) => composeLspRemoval(d),
+  composeRemoval: (d, undoKey) => composeLspRemoval(d, undoKey),
 });
 
 /**
@@ -356,7 +361,7 @@ const mcpTarget = defineTarget<McpDetection>({
   },
   compose: (d, chosen) =>
     composeMcp(d, chosen ? selectedGroups(d, chosen) : d.groups),
-  composeRemoval: (d) => composeMcpRemoval(d),
+  composeRemoval: (d, undoKey) => composeMcpRemoval(d, undoKey),
 });
 
 const skillsTarget = defineTarget<SkillsDetection>({
@@ -402,7 +407,12 @@ const skillsTarget = defineTarget<SkillsDetection>({
     if (owned.length === 0) {
       return { action: "none", detail: "no link to remove" };
     }
-    const dirs = [...new Set(owned.map((a) => shortenPath(a.linkPath, roots)))];
+    // Dedupe to the FOLDERS the links live in — `linkPath` itself is one path
+    // per link, so a Set over it deduped nothing and the removal preview
+    // printed an 18-path wall where the forward plan says `… → 2 folders`.
+    const dirs = [
+      ...new Set(owned.map((a) => shortenPath(dirname(a.linkPath), roots))),
+    ];
     return {
       action: "remove",
       detail: `${owned.length} ${owned.length === 1 ? "link" : "links"}`,
@@ -414,7 +424,7 @@ const skillsTarget = defineTarget<SkillsDetection>({
     };
   },
   compose: (d) => composeSkills(d),
-  composeRemoval: (d) => composeSkillsRemoval(d),
+  composeRemoval: (d, undoKey) => composeSkillsRemoval(d, undoKey),
 });
 
 /** THE table, in display order. */

package/src/capabilities/shared/index.ts

@@ -25,6 +25,7 @@
 export {
   assertExecOk,
   checkExecOk,
+  failPragma,
   guardMissingBinary,
 } from "./assertExecOk.js";
 export type {

package/src/capabilities/surface.test.ts

@@ -192,10 +192,18 @@ describe("surface conformance — capabilities ⊆ covenant (PROTECTED)", () =>
       {
         v: "application",
         args: ["[app-path]"],
-        // ssr/router are GONE: always-on facts, not prompts — the pair had no
-        // reachable explicit form (only `--no-` spellings the generator's own
-        // guard rejected), so the projection no longer carries them.
-        flags: ["--no-forms", "--intl", "--relay", "--no-run-install"],
+        // router is GONE: an always-on fact, not a prompt — it had no
+        // reachable explicit form (only a `--no-` spelling the generator's own
+        // guard rejected), so the projection no longer carries it. `rendering`
+        // is the SSR axis' replacement (L-CIS-3): a select, so it is spelled as
+        // a value and never as a negation.
+        flags: [
+          "--no-forms",
+          "--intl",
+          "--rendering",
+          "--relay",
+          "--no-run-install",
+        ],
         mutates: true,
         mcp: "create_application",
       },

package/src/constants.ts

@@ -41,6 +41,13 @@ const ISSUES_URL = identity.issuesUrl;
 /** Semver version string read from package.json. */
 const VERSION: string = pkg.version;
 
+/**
+ * The Node.js range this distribution supports, read from `engines.node` in
+ * package.json so the manifest stays the single statement of the floor. The
+ * doctor check quotes it, and `isSupportedNodeVersion` is pinned to it by test.
+ */
+const SUPPORTED_NODE_RANGE: string = pkg.engines.node;
+
 /**
  * The project config filename the walker looks for and every surface that
  * quotes it — diagnostics, the onboarding note, the generated reference, the
@@ -116,5 +123,6 @@ export {
   PROGRAM_LOGO,
   PROJECT_CONFIG_FILENAME,
   RECOVERY_CLI_PREFIX,
+  SUPPORTED_NODE_RANGE,
   VERSION,
 };

package/src/kernel/config/defaults.test.ts

@@ -44,7 +44,12 @@ describe("defaults — the validated distribution config (pragma.conf.ts)", () =
     expect(defaults.colophon?.summary?.length).toBeLessThan(400);
   });
 
-  it("ships the four canonical default packs (git+https sources)", () => {
+  // Five packs, and ONE carries a subdirectory. That is load-bearing, not
+  // decoration: `@canonical/token-ontology` lives inside a monorepo, and a
+  // git source names a repository — without `:packages/token-ontology` the
+  // clone would succeed against a root that has no `definitions/` or `data/`
+  // and the pack would contribute nothing, silently.
+  it("ships the five canonical default packs (all git+https)", () => {
     expect(
       defaults.packs?.map((pack) =>
         typeof pack === "string"
@@ -60,6 +65,11 @@ describe("defaults — the validated distribution config (pragma.conf.ts)", () =
         name: "@canonical/anatomy-dsl",
         source: "git+https://github.com/canonical/anatomy-dsl.git#main",
       },
+      {
+        name: "@canonical/token-ontology",
+        source:
+          "git+https://github.com/canonical/design-tokens.git#main:packages/token-ontology",
+      },
       {
         name: "@canonical/code-standards",
         source:
@@ -79,7 +89,7 @@ describe("defaults — the validated distribution config (pragma.conf.ts)", () =
     const storyCounts = defaults.packs?.map((pack) =>
       typeof pack === "string" ? 0 : (pack.stories?.length ?? 0),
     );
-    expect(storyCounts).toEqual([5, 0, 1, 1]);
+    expect(storyCounts).toEqual([5, 0, 0, 1, 1]);
   });
 
   it("declares no removed field — the validator would refuse to load one", () => {
@@ -98,6 +108,11 @@ describe("defaults — the validated distribution config (pragma.conf.ts)", () =
     // can expand — `cs:` is here for that reader.
     expect(defaults.prefixes).toEqual({
       ds: "https://ds.canonical.com/",
+      dt: "https://dt.canonical.com/",
+      // Nested under `dt:`, and bound separately because `compactUri` takes the
+      // longest match — with only the parent bound, every term of this
+      // vocabulary would render as `dt:w3c-tokens/…`.
+      "w3c-tokens": "https://dt.canonical.com/w3c-tokens/",
       cs: "http://pragma.canonical.com/codestandards#",
     });
   });

package/src/kernel/config/readConfig.test.ts

@@ -59,7 +59,7 @@ describe("readConfig — layering + provenance", () => {
     expect(config.tier).toBe("core");
     expect(config.channel).toBe("experimental");
     expect(config.detail).toBe("detailed");
-    expect(config.packs).toHaveLength(4); // from defaults
+    expect(config.packs).toHaveLength(5); // from defaults
 
     expect(origins).toMatchObject({
       tier: "project",

package/src/kernel/packs/sparql/buildLookupQuery.ts

@@ -121,13 +121,17 @@ const DERIVED_NAME = 'REPLACE(REPLACE(STR(?uri), "^.*[#/]", ""), "\\\\.", "/")';
  *
  * A story whose `list` SYNTHESIZES a name instead of reading one declares
  * `nameFallback: "iri"`, and then the triple becomes OPTIONAL with
- * {@link DERIVED_NAME} behind it. `standard` is the case that exists: 22 of the
- * 156 live code standards carry a `cs:name`, and the code-standards ontology
- * says so deliberately — it is "an optional human-readable display title" that
- * "never participates in identity". `standard list` published
- * `react/component/tsdoc` while `standard lookup react/component/tsdoc`
- * answered ENTITY_NOT_FOUND with empty suggestions, because the only
- * addressable population was the ~13% carrying an asserted name.
+ * {@link DERIVED_NAME} behind it. `standard` is the case that exists. When the
+ * defect was measured, 22 of the then-156 live code standards carried a
+ * `cs:name`, and the code-standards ontology said so deliberately — "an
+ * optional human-readable display title" that "never participates in
+ * identity". `standard list` published `react/component/tsdoc` while
+ * `standard lookup react/component/tsdoc` answered ENTITY_NOT_FOUND with
+ * empty suggestions, because the only addressable population was the ~13%
+ * carrying an asserted name. (Upstream has since retired `cs:name` for
+ * `rdfs:label`, which every standard carries; the fallback stays because a
+ * pack is data, and a dropped label must degrade to the derived name rather
+ * than become unaddressable.)
  *
  * INFERRING the fallback from the mere PRESENCE of a class constraint is what
  * this option replaced, and it was over-reach in both directions of the same