@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/capabilities/create/shippedCreate.subprocess.test.ts

@@ -0,0 +1,164 @@
+/**
+ * PROTECTED — the shipped-entry `create` guard.
+ *
+ * Spawns the EMITTED entry the published package points at
+ * (`node dist/src/bin.js`) and asserts every `create` noun writes a tree
+ * BYTE-IDENTICAL to a source run of the same generator (`bun src/bin.ts …`).
+ * The source run is the reference: it reads the `.ejs` templates from disk with
+ * no indirection.
+ *
+ * WHAT THIS REPLACES. Until the distribution stopped shipping a
+ * `bun build --compile` executable, this guard covered `create component` only,
+ * and its sibling describe pinned the REFUSAL of `create package` /
+ * `create application`: those generators call `template({ source })`, summon-core
+ * fell through to `readFile(options.source)`, and inside the binary's virtual
+ * filesystem that died with `ENOENT … /$bunfs/templates/package.json.ejs` after
+ * `mkdir` had already run — a half-made package on the user's disk. The gate
+ * existed to turn that crash into a clean refusal.
+ *
+ * There is no virtual filesystem now. Every generator's templates are real
+ * files under its own package, so all three nouns run from the shipped entry and
+ * all three are asserted here. THE REFUSAL CASES ARE GONE ON PURPOSE: a test
+ * asserting `create package` refuses would now be asserting a defect.
+ *
+ * The svelte + lit cases stay load-bearing: `types.ts.ejs` / `index.ts.ejs` /
+ * `styles.css.ejs` / `stories.ts.ejs` exist in react/, svelte/ AND lit/, so a
+ * basename-matching regression could emit the WRONG framework's file. A wrong
+ * file differs from the source run → red here.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, readdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, "../../../../../..");
+const cliNextDir = join(repoRoot, "packages/cli/pragma");
+const sourceEntry = join(cliNextDir, "src/bin.ts");
+const shippedEntry = join(cliNextDir, "dist/src/bin.js");
+const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-shipped-"));
+
+// `dist/` is provisioned by `testing/perf/globalSetup.ts`, which re-emits it
+// whenever it is missing or older than `src/**`, `scripts/**`, `pragma.conf.ts`
+// or `package.json` — so these tests exercise the current emit without a second
+// `beforeAll` writing `dist/` in place while another worker is spawning it.
+
+/** Read a directory tree into a sorted map of relative path → contents. */
+function snapshot(dir: string): Map<string, string> {
+  const out = new Map<string, string>();
+  const walk = (d: string, base: string): void => {
+    for (const entry of readdirSync(d, { withFileTypes: true }).sort((a, b) =>
+      a.name.localeCompare(b.name),
+    )) {
+      const rel = base ? `${base}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(join(d, entry.name), rel);
+      else out.set(rel, readFileSync(join(d, entry.name), "utf-8"));
+    }
+  };
+  walk(dir, "");
+  return out;
+}
+
+/**
+ * The create invocations under guard — a LITERAL table, deliberately not derived
+ * from `create`'s own declaration, so dropping a noun from the surface turns
+ * this red rather than silently shrinking the guard.
+ *
+ * No case installs dependencies (`runInstall` defaults false), so every tree is
+ * generator output alone and byte-comparable.
+ */
+const CASES: ReadonlyArray<{ label: string; args: readonly string[] }> = [
+  ...(["react", "svelte", "lit"] as const).map((framework) => ({
+    label: `component ${framework}`,
+    // The framework is a PATH SEGMENT, not a flag — `create` mirrors summon's
+    // own tree (`summon component react <path>`), so the two CLIs take the
+    // same argv.
+    args: ["create", "component", framework, "src/components/Widget", "--yes"],
+  })),
+  {
+    label: "package",
+    args: ["create", "package", "--name", "@canonical/probe", "--yes"],
+  },
+  {
+    label: "application",
+    // `react` is a path segment here too — the declared binding is
+    // `application/react`, and the tree mirrors summon's.
+    args: ["create", "application", "react", "probeapp", "--yes"],
+  },
+];
+
+/** Run one create invocation in its own cwd and snapshot what it wrote. */
+function create(
+  command: string,
+  prefix: readonly string[],
+  args: readonly string[],
+): Map<string, string> {
+  const dir = freshCwd();
+  execFileSync(command, [...prefix, ...args], { cwd: dir, stdio: "pipe" });
+  return snapshot(dir);
+}
+
+describe("shipped pragma create (PROTECTED)", () => {
+  for (const { label, args } of CASES) {
+    it(`${label}: shipped entry ≡ source run, byte-for-byte`, () => {
+      // (1) The shipped entry, exactly as a consumer's `pragma` runs it.
+      const shipped = create(process.execPath, [shippedEntry], args);
+      // (2) A source run — the reference output.
+      const source = create("bun", [sourceEntry], args);
+
+      // Wrote something. Before the distribution stopped shipping a compiled
+      // binary, `package` and `application` wrote NOTHING here — they refused.
+      expect(shipped.size).toBeGreaterThan(0);
+      // Same file set …
+      expect([...shipped.keys()].sort()).toEqual([...source.keys()].sort());
+      // … and byte-identical contents.
+      for (const [path, content] of shipped) {
+        expect(source.get(path), `content of ${path}`).toBe(content);
+      }
+    }, 180_000);
+  }
+});
+
+/**
+ * PROTECTED — the shipped-entry READ guard (U1-orig).
+ *
+ * A READ command (`block list`, `--help`) never calls a generator's
+ * `generate()`, so — with the generators loading their templates LAZILY on first
+ * `generate()` rather than at module-eval — it must never touch a `.ejs` at all.
+ * This is the exact gap the create-only smoke above missed: the component
+ * generators used to load templates via a top-level `await`, so a READ crashed
+ * with `Template not found`. The lazy load makes a READ template-free, and this
+ * pins it at the process boundary where an eager load would resurface.
+ */
+describe("shipped pragma READ smoke (PROTECTED)", () => {
+  // A cold store cleanly reports STORE_UNAVAILABLE (exit 3); `--help` never needs
+  // a store (exit 0). Both fully exercise startup + dispatch — the phase where an
+  // eager generator template load would have crashed — without a store or writes.
+  const READS: ReadonlyArray<{
+    args: readonly string[];
+    okExit: readonly number[];
+  }> = [
+    { args: ["block", "list"], okExit: [0, 3] },
+    { args: ["--help"], okExit: [0] },
+  ];
+
+  for (const { args, okExit } of READS) {
+    it(`\`${args.join(" ")}\` runs without a Template-not-found crash`, () => {
+      const result = spawnSync(process.execPath, [shippedEntry, ...args], {
+        cwd: freshCwd(),
+        stdio: "pipe",
+        encoding: "utf-8",
+      });
+      const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+      // The exact crash the lazy-template fix closes.
+      expect(output).not.toMatch(/Template not found/);
+      // Nor does it collapse to the internal-bug path (the crash's other tell).
+      expect(output).not.toMatch(/Internal error/);
+      // It reaches a clean dispatch outcome, not an uncaught startup crash.
+      expect(okExit).toContain(result.status);
+    }, 30_000);
+  }
+});

package/src/capabilities/create/types.ts

@@ -1,8 +1,32 @@
+import type { CREATE_GENERATORS } from "./constants.js";
+
 /**
- * Create-capability types with NO summon-core / generator import, so a module
- * that only needs `CreateKind` (e.g. `create.verb`) does not drag
- * `pickGenerator` — and its heavy generator imports — into the static graph.
+ * The `create` nouns — one per declared generator binding (path capped at two
+ * segments). Derived from {@link CREATE_GENERATORS} so the union cannot drift
+ * from the bindings.
+ *
+ * Deliberately free of any summon-core / generator import, so a module that only
+ * needs this type (e.g. `create.verb`) does not drag `pickGenerator` — and its
+ * heavy generator imports — into the static graph.
  */
+export type CreateKind = keyof typeof CREATE_GENERATORS;
 
-/** The three `create` nouns (path capped at two segments). */
-export type CreateKind = "component" | "package" | "application";
+/**
+ * The REGISTERED CLI spelling of one generator prompt, baked into
+ * `createSurface.generated.ts` at build time (the build derives it with the
+ * same summon-core helpers the mount registers through). Consumers that need
+ * only the spelling — completion tokens, the reference's usage lines — read
+ * this baked record instead of calling the projection, which keeps the
+ * `--help`/`__complete` fast paths free of the registration machinery.
+ */
+export interface PromptCliSyntax {
+  /**
+   * The registered flag token (`--component-path`; a default-true confirm
+   * registers ONLY its `--no-<kebab>` form).
+   */
+  readonly flag: string;
+  /** Whether the registered flag takes a value (`--styles` does not). */
+  readonly takesValue: boolean;
+  /** The prompt name's kebab-case CLI spelling (`componentPath` → `component-path`). */
+  readonly kebabName: string;
+}

package/src/capabilities/{standard/parity.test.ts → distribution.parity.test.ts}

@@ -1,6 +1,6 @@
 /**
- * Standard-noun semantic parity (PROTECTED) — the bundled `standard` pack over a
- * code-standards fixture graph.
+ * Standard-noun semantic parity (PROTECTED) — the `standard` story
+ * `pragma.conf.ts` declares, over a code-standards fixture graph.
  *
  * The hand-written standard domain is gone, so parity is asserted directly
  * against the graph: every standard is reachable through list/lookup/categories/
@@ -10,16 +10,22 @@
  */
 
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { compilePack } from "../../kernel/packs/compile.js";
-import type { LookupOutput } from "../../kernel/packs/resolveEntity.js";
-import { parsePackDefinition } from "../../kernel/packs/schema.js";
-import type { PackRow } from "../../kernel/packs/types.js";
-import { verbKey } from "../../kernel/packs/uniqueness.js";
-import { DEFAULT_PREFIX_MAP } from "../../kernel/render/prefixes.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
-import type { VerbSpec } from "../../kernel/spec/types.js";
-import { buildFixtureRuntime } from "../../testing/helpers/packRuntime.js";
-import { standardPack } from "./pack.js";
+import { compilePack } from "../kernel/packs/compile.js";
+import type { LookupOutput } from "../kernel/packs/resolveEntity.js";
+import { parsePackDefinition } from "../kernel/packs/schema.js";
+import type { PackRow } from "../kernel/packs/types.js";
+import { distributionSource } from "../kernel/packs/types.js";
+import { verbKey } from "../kernel/packs/uniqueness.js";
+import { DEFAULT_PREFIX_MAP } from "../kernel/render/prefixes.js";
+import type { PragmaRuntime } from "../kernel/runtime/types.js";
+import type { VerbSpec } from "../kernel/spec/types.js";
+import { buildFixtureRuntime } from "../testing/helpers/packRuntime.js";
+import { declaredStories } from "./distribution.js";
+
+const standardPack = declaredStories.get("standard");
+if (!standardPack) {
+  throw new Error('pragma.conf.ts declares no story for "standard"');
+}
 
 const CS = "http://pragma.canonical.com/codestandards#";
 const PREFIXES = {
@@ -72,7 +78,11 @@ cs:code.function.purity a cs:CodeStandard ;
 `;
 
 const verbs = () =>
-  compilePack(standardPack, "bundled:standard", DEFAULT_PREFIX_MAP);
+  compilePack(
+    standardPack,
+    distributionSource("pragma.conf.ts"),
+    DEFAULT_PREFIX_MAP,
+  );
 const verb = (label: string) =>
   verbs().find((v) => verbKey(v.path) === `standard ${label}`) as VerbSpec;
 
@@ -98,7 +108,7 @@ async function lookupAt(
   return out.results.at(0) as Record<string, unknown>;
 }
 
-describe("standard pack definition (PROTECTED)", () => {
+describe("standard story definition (PROTECTED)", () => {
   it("round-trips as declarative JSON and validates", () => {
     expect(
       parsePackDefinition(JSON.parse(JSON.stringify(standardPack)), "t"),

package/src/capabilities/distribution.test.ts

@@ -0,0 +1,122 @@
+/**
+ * The distribution's own declared read stories (PROTECTED).
+ *
+ * `pragma.conf.ts` is hand-authored data that the TypeScript compiler checks
+ * against `PackDefinition`; `kernel/packs/schema.ts` is an independently written
+ * zod grammar that every config- and package-declared story must pass. Nothing
+ * forced the two to agree until the distribution started coming through the same
+ * door — and the first thing that comparison found was `sample.fixedCount`,
+ * documented and used by three of these five stories yet missing from the
+ * `.strict()` sample schema, which made any third-party story declaring it die
+ * with a fatal CONFIG_ERROR. Round-tripping ALL five is what keeps that shut.
+ */
+
+import { describe, expect, it } from "vitest";
+import { compilePack } from "../kernel/packs/compile.js";
+import { parsePackDefinition } from "../kernel/packs/schema.js";
+import { DEFAULT_PREFIX_MAP } from "../kernel/render/prefixes.js";
+import type { VerbSpec } from "../kernel/spec/types.js";
+import { VOCABULARY } from "../kernel/vocabulary.js";
+import { declaredStories, storyModules } from "./distribution.js";
+import { capabilities } from "./index.js";
+
+/** A verb's DECLARED shape — everything but the closures a compile mints fresh. */
+function declaredShape(verb: VerbSpec): Record<string, unknown> {
+  return {
+    path: verb.path.join(" "),
+    summary: verb.summary,
+    doc: verb.doc,
+    params: verb.params,
+    capability: verb.capability,
+    examples: verb.examples,
+  };
+}
+
+describe("the distribution's declared stories (PROTECTED)", () => {
+  it("declares exactly the seven domain nouns", () => {
+    // Every domain noun is now nothing BUT its story (L-OPEN-9), so a renamed
+    // or dropped noun deletes a whole command rather than shrinking one — it
+    // must fail HERE.
+    expect([...declaredStories.keys()].sort()).toEqual([
+      "block",
+      "concept",
+      "implementation",
+      "modifier",
+      "standard",
+      "tier",
+      "token",
+    ]);
+  });
+
+  it.each([
+    ...declaredStories.keys(),
+  ])("the %s story validates against the pack grammar, unchanged", (noun) => {
+    const story = declaredStories.get(noun);
+    expect(
+      parsePackDefinition(JSON.parse(JSON.stringify(story)), "pragma.conf.ts"),
+    ).toEqual(story);
+  });
+
+  it("every declared noun reaches the registry as an overridable module", () => {
+    for (const noun of declaredStories.keys()) {
+      const module = capabilities.find((entry) => entry.name === noun);
+      expect(module, `no capability module for "${noun}"`).toBeDefined();
+      // `story: true` is what lets a project's own story REPLACE it at
+      // dispatch; without it the noun would be treated as authored CLI.
+      expect(module?.story).toBe(true);
+      expect(module?.verbs.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("ZERO hand-written data commands: a registered noun IS its compiled story", () => {
+    // The machine form of L-OPEN-9's end state — "a fork defines its entire
+    // read surface in pragma.conf.ts". Prose can go stale; this cannot. Every
+    // declared noun's REGISTERED module (what the CLI, the MCP server and the
+    // generated reference all project) must be verb-for-verb what recompiling
+    // its story alone produces. Re-introducing a composite — an authored module
+    // that prepends or appends a hand-written verb beside the story, which is
+    // exactly how `block`, `token` and `tier` used to be built — fails here,
+    // whatever the docblocks say.
+    for (const [noun, story] of declaredStories) {
+      const registered = capabilities.find((entry) => entry.name === noun);
+      const compiled = compilePack(story, "pragma.conf.ts", DEFAULT_PREFIX_MAP);
+      // Two halves, because a spec carries closures a fresh compile cannot
+      // reproduce by identity. (1) SHAPE: recompiling the story alone must
+      // yield the same verbs, declared the same way — an extra verb or an extra
+      // flag beside the story fails here.
+      expect(
+        registered?.verbs.map(declaredShape),
+        `"${noun}" registers verbs its story does not declare`,
+      ).toEqual(compiled.map(declaredShape));
+      // (2) IDENTITY: each registered verb must BE the compiled story's verb
+      // object, not a look-alike. A composite module — the `[...story.verbs,
+      // handWrittenVerb]` shape `block`, `token` and `tier` used to be built
+      // with — constructs new objects, so it cannot pass this even if its
+      // shapes happen to match.
+      const fromStory = storyModules.get(noun)?.verbs ?? [];
+      expect(registered?.verbs.length).toBe(fromStory.length);
+      registered?.verbs.forEach((verb, index) => {
+        expect(verb, `"${noun}" verb ${index} is not the story's`).toBe(
+          fromStory[index],
+        );
+      });
+    }
+  });
+
+  it("the tier story is internally coherent, and coherent with the vocabulary", () => {
+    // Both tier verbs are declared data now (L-OPEN-9), so the noun can no
+    // longer disagree with ITSELF in code — but the list query spells its
+    // class and property literally (`pragma.conf.ts` is inert data and imports
+    // nothing) while the lookup declares them as fields, and the vocabulary
+    // declares the addressing property once more for the index builder. This
+    // holds all three to one class and one property, so a candidate that
+    // completes still resolves and the index projects the names the lookup
+    // matches.
+    const story = declaredStories.get("tier");
+    const query = story?.list?.query ?? "";
+    expect(story?.lookup?.type).toBe("ds:Tier");
+    expect(query).toContain(`a ${story?.lookup?.type}`);
+    expect(story?.lookup?.by).toBe(VOCABULARY.altName);
+    expect(query).toContain(`${VOCABULARY.altName} ?name`);
+  });
+});

package/src/capabilities/distribution.ts

@@ -0,0 +1,54 @@
+/**
+ * The distribution's own read stories, compiled at module load.
+ *
+ * `pragma.conf.ts` declares them on the packs that supply them; this is the ONE
+ * place those declarations become capabilities. They come through the SAME door
+ * a third-party story does — {@link compileStoryModule} — so the mechanism the CLI
+ * offers forks is the mechanism the CLI itself runs on.
+ *
+ * They are compiled STATICALLY rather than merged at dispatch on purpose: the
+ * `--help` / `__complete` fast paths read the static capability set, and
+ * `surface/surface.v2.json` freezes the emitted surface, so a noun that only
+ * arrived at dispatch would vanish from help and completion on a fresh install.
+ * That is affordable because this module is zod-free and pure — `pragma.conf.ts`
+ * is inert data and the compiler builds specs without touching the store.
+ *
+ * Config- and package-declared stories still OVERRIDE these at dispatch; the
+ * `story` marker on each module is what tells `assembleEffectiveModules` which
+ * modules may be replaced.
+ */
+
+import conf from "../../pragma.conf.js";
+import { compileStoryModule } from "../kernel/packs/compile.js";
+import {
+  distributionSource,
+  type PackDefinition,
+} from "../kernel/packs/types.js";
+import { DEFAULT_PREFIX_MAP } from "../kernel/render/index.js";
+import type { CapabilityModule } from "../kernel/spec/index.js";
+
+/** The read stories `pragma.conf.ts` declares on its packs, by noun. */
+export const declaredStories: ReadonlyMap<string, PackDefinition> = new Map(
+  conf.packs
+    .flatMap((pack) => pack.stories ?? [])
+    .map((story): readonly [string, PackDefinition] => [story.noun, story]),
+);
+
+/**
+ * Those stories compiled to capability modules, by noun.
+ *
+ * `capabilities/index.ts` appends every module no authored one claims — and
+ * since L-OPEN-9 that is every one of them: no data noun is authored, so a
+ * declared story IS the whole noun. `distribution.test.ts` holds that shut by
+ * asserting each registered module's verbs deep-equal its compiled story's.
+ */
+export const storyModules: ReadonlyMap<string, CapabilityModule> = new Map(
+  [...declaredStories].map(([noun, story]) => [
+    noun,
+    compileStoryModule(
+      story,
+      distributionSource("pragma.conf.ts"),
+      DEFAULT_PREFIX_MAP,
+    ),
+  ]),
+);

package/src/capabilities/doctor/checks/checkKeStore.ts

@@ -1,9 +1,12 @@
+import { BIN_NAME } from "../../../constants.js";
 import { entityTotal } from "../../../kernel/completion/entitySource.js";
-import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
+import type { PragmaRuntime } from "../../../kernel/runtime/index.js";
 import type { CheckResult } from "../types.js";
 
 /**
- * Check that the ke store boots, reporting the entity total and boot time.
+ * Check that the local store boots, reporting the entity total and boot time.
+ * The check is NAMED "store" in the report — the same word every other surface
+ * uses for it; the ke library it boots through is an implementation detail.
  *
  * This is the ONE check that touches the store — it boots the shared lazy store
  * inside a try/catch, so doctor stays storeless-by-default at the dispatch level
@@ -23,17 +26,16 @@ export async function checkKeStore(rt: PragmaRuntime): Promise<CheckResult> {
     const total = entityTotal(session.index);
     const elapsed = Math.round(performance.now() - start);
     return {
-      name: "ke store",
+      name: "store",
       status: "pass",
       detail: `${total.toLocaleString()} entities in ${elapsed}ms`,
     };
   } catch {
     return {
-      name: "ke store",
+      name: "store",
       status: "fail",
-      detail: "failed to boot",
-      remedy:
-        "Ensure design-system packages are installed and run `pragma sources update`.",
+      detail: "cannot boot",
+      remedy: `Ensure design-system packs are configured and run \`${BIN_NAME} sources update\`.`,
     };
   }
 }

package/src/capabilities/doctor/checks/checkPackageRefs.ts

@@ -1,73 +1,109 @@
 /**
- * Doctor check: report how each configured semantic package resolves.
+ * Doctor check: report which pack answers this project's reads.
  *
- * ADAPTED for v2: the old local>git>bundled loader chain is retired — resolution
- * now flows through `sources update` into `pragma.lock.json` + the cached pack.
- * This check reads the lock (which packages resolved) and the storeless pack
- * index (the entity total), never booting the store. An absent lock with
- * configured packages is the "run `sources update`" case.
+ * It switches on the ONE boot decision ({@link resolveSources}) rather than
+ * re-deriving it from config, so doctor can never call an install healthy that
+ * every read would fail. That is the whole point of the check: a project that
+ * configured its own packs and never built them reports `fail` with the update
+ * remedy — not a pass listing the distribution's packs it is not reading.
+ * Storeless throughout: the pointer, the manifest, and the entity index are
+ * read off disk, never through a store session.
+ *
+ * It also names every read story that pack carries but cannot use. Those are
+ * DROPPED at dispatch rather than thrown (a third-party story must never break
+ * a command), so doctor is where the user finds out — and it goes through the
+ * same `validateStories` the dispatch path uses, so the two can never disagree.
  */
 
+import { BIN_NAME } from "../../../constants.js";
 import {
   entityTotal,
   readPackIndex,
 } from "../../../kernel/completion/entitySource.js";
-import type { PackageEntry } from "../../../kernel/config/types.js";
-import { readLock } from "../../../kernel/runtime/lock.js";
-import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
+import { validateStories } from "../../../kernel/packs/index.js";
+import {
+  embeddedManifest,
+  readManifest,
+} from "../../../kernel/runtime/graphpack/index.js";
+import { activeStories } from "../../../kernel/runtime/graphpack/stories.js";
+import type { PragmaRuntime } from "../../../kernel/runtime/index.js";
+import type { SourcesDecision } from "../../../kernel/runtime/resolveSources.js";
+import { resolveSources } from "../../../kernel/runtime/resolveSources.js";
 import type { CheckItem, CheckResult } from "../types.js";
 
-const entryName = (entry: PackageEntry): string =>
-  typeof entry === "string" ? entry : entry.name;
+/**
+ * The stories the answering pack carries but cannot use, as check items.
+ *
+ * The registry is reached through a RUNTIME dynamic import (as
+ * `collectColophon` does) so the static `capabilities/index → doctorModule →
+ * checkPackageRefs → capabilities/index` cycle can never form.
+ *
+ * @param decision - The boot decision the check already resolved.
+ * @returns One failing item per ignored story, in declaration order.
+ * @note Impure — reads the answering pack's `stories.json`.
+ */
+async function ignoredStoryItems(
+  decision: SourcesDecision,
+): Promise<CheckItem[]> {
+  const { capabilities } = await import("../../index.js");
+  const { problems } = validateStories(activeStories(decision), capabilities);
+  return problems.map((problem) => ({
+    label: problem.source,
+    detail: problem.message,
+    status: "fail" as const,
+  }));
+}
+
+/** ` · N story/ies ignored` for a headline, or nothing when all are usable. */
+function ignoredSuffix(items: readonly CheckItem[]): string {
+  if (items.length === 0) return "";
+  return ` · ${items.length} ${items.length === 1 ? "story" : "stories"} ignored`;
+}
 
 /**
- * Report package resolution status against the lock and the entity total.
+ * Report which pack answers reads, its provenance, and its entity total.
  *
  * @param rt - The per-invocation runtime.
- * @returns A CheckResult with a per-package breakdown.
- * @note Impure — reads config, the lock, and the pack index from disk.
+ * @returns A CheckResult naming the answering pack, or the failure to build one.
+ * @note Impure — reads config, the active-pack pointer, and the pack index.
  */
 export async function checkPackageRefs(
   rt: PragmaRuntime,
 ): Promise<CheckResult> {
-  const entries = (await rt.loadConfig()).config.packages ?? [];
-  const lock = readLock(rt.cwd);
-  const index = readPackIndex(rt.cwd);
-  const totalEntities = index ? entityTotal(index) : 0;
+  const decision = resolveSources(await rt.loadConfig(), rt.cwd);
+  // The display says "packs" (config declarations); the file/function keep
+  // "Package" (npm/git resolution vocabulary).
+  const name = "pack refs";
 
-  if (entries.length === 0) {
+  if (decision.kind === "unavailable") {
     return {
-      name: "package refs",
-      status: "pass",
-      detail: `no packages configured — the embedded pack answers reads (${totalEntities.toLocaleString()} entities)`,
+      name,
+      status: "fail",
+      detail: decision.reason,
+      remedy: `${BIN_NAME} sources update`,
     };
   }
 
-  const items: CheckItem[] = [];
-  let unresolved = 0;
-  for (const entry of entries) {
-    const name = entryName(entry);
-    const packEntry = lock?.packs.find((pack) => pack.name === name);
-    if (packEntry) {
-      items.push({
-        label: name,
-        status: "pass",
-        detail: `resolved ${packEntry.resolved}`,
-      });
-    } else {
-      items.push({ label: name, status: "fail", detail: "not in the lock" });
-      unresolved += 1;
-    }
+  const index = readPackIndex(decision);
+  const entities = (index ? entityTotal(index) : 0).toLocaleString();
+  // The pack DOES answer reads, so the check itself passes; the ignored stories
+  // are failing sub-items under it. (A `warn` status would ripple through the
+  // renderer and the DoctorData counts to buy an icon.)
+  const items = await ignoredStoryItems(decision);
+  const suffix = ignoredSuffix(items);
+  if (decision.kind === "embedded") {
+    return {
+      name,
+      status: "pass",
+      detail: `embedded snapshot @ ${embeddedManifest().sourceRef} — ${entities} entities${suffix} · \`${BIN_NAME} sources update\` to build from the configured packs`,
+      ...(items.length > 0 ? { items } : {}),
+    };
   }
-
-  const ok = lock !== undefined && unresolved === 0;
+  const manifest = readManifest(decision.dir);
   return {
-    name: "package refs",
-    status: ok ? "pass" : "fail",
-    detail: ok
-      ? `${entries.length} package(s) resolved · ${totalEntities.toLocaleString()} entities`
-      : `${unresolved} of ${entries.length} package(s) not resolved`,
-    items,
-    ...(ok ? {} : { remedy: "pragma sources update" }),
+    name,
+    status: "pass",
+    detail: `${manifest?.sourceRef ?? decision.contentHash.slice(0, 12)} — ${entities} entities, built ${manifest?.createdAt ?? "?"}${suffix}`,
+    ...(items.length > 0 ? { items } : {}),
   };
 }