@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/testing/behavioral/README.md

@@ -0,0 +1,164 @@
+# `testing/behavioral/` — the cross-cutting behavioral-test layer
+
+This directory holds PR4's deliverable: the integration/e2e layer that sits
+ON TOP of each capability PR's own per-noun unit tests. It does not re-test
+per-noun unit behavior — read that in a capability's own `*.test.ts`
+(`src/capabilities/<noun>/*.test.ts`). This directory answers a different
+question: does the WHOLE SYSTEM — CLI, MCP, the process boundary, the shared
+fixture graph — behave consistently across nouns and surfaces?
+
+If you are landing PR5, PR6, or PR7 and wondering where your journey test
+goes, read this file first.
+
+## The non-negotiable rule: parameterize, don't hard-code
+
+Every file in this directory drives its assertions over the LIVE surface —
+`liveReadSurface.ts` (derived from `emitSurface(capabilities)`) or a direct
+`emitSurface(capabilities)` call — never a noun/verb/tool name copied from a
+plan document. When PR5 adds `create`, PR6 adds `config` mutations, or PR7
+adds the capabilities catalog, most of the sweeps in this directory (B1, B3,
+B4, B5, B6, B10) pick the new nouns/tools up AUTOMATICALLY, with zero edits
+here. If a sweep does NOT pick up your new noun and you believe it should,
+that's a bug in the sweep's filter — fix the filter, don't hand-add your noun
+name to a list.
+
+The one test that must NOT auto-grow is `capabilities/surface.test.ts`
+(PR3-owned, not in this directory) — each PR re-snapshots its OWN emitted
+slice there, in its own diff, and `assertConforms` keeps checking `emitted ⊆
+covenant` (never `==`), since the covenant is the frozen FUTURE surface and
+the emitted set legitimately grows PR-by-PR.
+
+## What's here
+
+| File | What it proves |
+|---|---|
+| `liveReadSurface.ts` | The parameterization helper — every other file imports `liveVerbs`/`listVerbs`/`lookupVerbs` from here rather than deriving its own. |
+| `harness.foundation.test.ts` | The framework itself boots (fixture graph, foreign-namespace pack, `runCli`, the golden normalizer). |
+| `firstRun.e2e.test.ts`, `rootCli.e2e.test.ts`, `exitCodes.e2e.test.ts`, `mcpServe.e2e.test.ts`, `autoLlm.e2e.test.ts` | The THIN spawn-e2e layer — the real process boundary, kept to exactly these cases (R7). Everything else in this package runs in-process. |
+| `parity.test.ts` | The uniform CLI-json == MCP-json helper (`helpers/parity.ts`), proven on the stable nouns and swept across every read noun (B5). |
+| `errorMatrix.storeless.test.ts`, `errorMatrix.mcp.test.ts` | The error/recovery render matrix, storeless + fixture-backed halves. |
+| `agentSession.mcp.test.ts` | A multi-step agent MCP session (list → pick → lookup) + the SPARQL escape hatch. |
+| `mcpSurface.test.ts` | Every MCP tool the live catalog exposes is callable and well-formed — the "surface ⊆ covenant, exercised" proof. |
+| `disclosure.test.ts` | The cross-noun disclosure sweep (mechanism itself is PR3's/kernel's protected unit test — this only sweeps the noun SET). |
+| `journeys.cli.test.ts` | The `block list` tier-chain/channel journey (the one hand-written verb). |
+| `completion.test.ts` | The THIN main-line `__complete` candidate contract (§6 — see "Completion" below). |
+
+Plus `testing/eval/` (the eval harness + seed cases) and `testing/PARITY_GAPS.ts`
+(the consolidated accepted-divergence ledger) — siblings of this directory,
+same ownership.
+
+## The shared fixture graph
+
+`testing/fixtures/graph/canonical.ts` is the ONE content graph every
+store-backed behavioral test boots through. It imports PR3's Button/Modal
+fixture (`testing/fixtures/blockGraph.ts`) verbatim and extends it (tier
+chain, a release channel, tokens, code standards) — it does not fork a
+second graph. If your PR needs new entities for its own journey:
+
+- Prefer EXTENDING `canonical.ts` (add a Turtle fragment, concatenate) over
+  creating a new fixture file, so the whole package keeps testing against one
+  graph and existing anchor assertions (Button, `code/function/purity`,
+  `importance`→`primary`, the 4 `ds:Component`s) stay valid.
+- If your noun needs an entirely different ontology/vocabulary (like the
+  `ex:` recipe pack does, `testing/fixtures/packs/recipe.ts`), a new fixture
+  file is fine — that's the "foreign namespace" pattern, not the main graph.
+
+## Booting a store-backed fixture: `bootFixtureRuntime`
+
+```ts
+import { bootFixtureRuntime } from "../helpers/fixtureGraph.js";
+import { CANONICAL_TTL, CANONICAL_CONFIG } from "../fixtures/graph/canonical.js";
+
+const fixture = await bootFixtureRuntime({ ttl: CANONICAL_TTL, config: CANONICAL_CONFIG });
+try {
+  // fixture.cwd carries a REAL pragma.lock.json — bootRuntime(flags, fixture.cwd),
+  // executeVerb(...), projectMcp(modules, fixture.cwd), and (if you must)
+  // runCli(args, { cwd: fixture.cwd }) all resolve the SAME cached pack.
+} finally {
+  await fixture.dispose();
+}
+```
+
+Use `packRuntime.ts#buildFixtureRuntime` (PR3's helper) instead when you only
+need ONE surface (a direct `verb.run()` call) — it's cheaper (no lock file).
+Reach for `bootFixtureRuntime` specifically when you need CLI and MCP (or a
+spawn) to agree on the same store.
+
+## Cross-surface parity: `assertCliMcpParity`
+
+```ts
+import { assertCliMcpParity } from "../helpers/parity.js";
+
+await assertCliMcpParity({
+  modules: capabilities, // or your module array
+  verb: yourVerbSpec,
+  tool: "your_tool_name",
+  cwd: fixture.cwd,
+  params: { name: ["Something"] }, // same bag serves both surfaces
+});
+```
+
+v2's MCP envelope IS the CLI `--format json` envelope — this is structural
+deep-equality, not the old condensed-shape byte comparison. Don't reproduce a
+`condensed`/token-count MCP shape; there isn't one (`PARITY_GAPS`
+`no-condensed-mcp-envelope`).
+
+Two things this helper does NOT handle — check `PARITY_GAPS.ts` before
+assuming a mismatch is a bug:
+- A mutating verb's plan-first preview differs in `meta` shape between a CLI
+  `--dry-run` and an unconfirmed MCP call by design (`plan-first-meta-differs`).
+- `sample` verbs draw an independent random selection per call — never assert
+  content equality on one, only structure.
+
+## Adding your PR's journey
+
+1. **New nouns your PR adds are picked up automatically** by every sweep in
+   this directory that iterates `liveReadSurface.ts`, `emitSurface`, or
+   `capabilities` directly. Run the existing suite after landing your noun —
+   if `mcpSurface.test.ts`/`parity.test.ts` (B4/B5) pass with no edits, you're
+   already covered for the generic contract.
+2. **Your noun's own SPECIFIC journey** (a multi-step flow only your noun
+   makes sense for — e.g. PR5's `create` dry-run → real → byte-equality with
+   summon) is your PR's to add, as a new file here (`journeys.<yourNoun>.test.ts`
+   or similar), following the naming/parameterization conventions above.
+3. **Extend, don't duplicate, the eval seed.** Add a `cases/<yourArea>.ts`
+   file (`EvalCase[]`) under `testing/eval/cases/`, mirroring
+   `cases/readNouns.ts`, and wire it into `eval.test.ts`/`report.ts`'s
+   `allSeedCases` concat.
+4. **Append to `PARITY_GAPS.ts`**, don't start a second ledger, when you find
+   (or design in) an intentional divergence from a naive parity/behavior
+   expectation.
+5. **Keep the spawn layer thin.** Only reach for `runCli` when the PROCESS
+   BOUNDARY itself is what's under test (first-run, `--version`, real exit
+   codes, `mcp` serve boot). Everything else: `executeVerb`/`projectCli`/
+   `projectMcp`/`bootFixtureRuntime`, in-process.
+
+## Extension points this PR left for you, by owner
+
+- **PR5 (`create`)** — `C1` in the port ledger. No journey exists yet for
+  `create component/package/application` dry-run/real/byte-equality. Add
+  `journeys.create.test.ts` here plus its own eval cases.
+- **PR6 (config mutation, info enrichment, doctor, upgrade, setup, `graph
+  query`)** — `C2`/`C3`/`C4` — **BUILT**. Each new verb ships its own
+  in-diff coverage: `config/field.test.ts`, `info/info.test.ts`,
+  `doctor/doctor.test.ts`, `upgrade/upgrade.test.ts`, `setup/setup.test.ts`,
+  `graph/query.test.ts`. `graph query` (tool `graph_query`) is now LIVE
+  (`PARITY_GAPS` `graph-query-deferred` reworded to record its two residual
+  divergences); B2's SPARQL-escape-hatch coverage continues to exercise the
+  shared `PragmaRuntime.query.sparql` facade the live verb delegates to. Future
+  work may re-drive B2 through the tool the way B1-B6 do for the read nouns.
+- **PR7 (capabilities catalog, MCP prompts, budget activation)** — `C5`. The
+  eval harness (`testing/eval/`) is seeded with 14 representative cases across
+  all 4 kinds (tool/content/disclosure/prompt) — populate the full matrix on
+  top, not a parallel harness. `mcpP95Warm` (`testing/perf/mcpP95Warm.seed.test.ts`)
+  and `condensedSDL` (`testing/eval/cases/stable.ts`) are SEEDED (measured,
+  softly checked) — this is where they graduate to enforced, alongside
+  `help`/`complete`/`warmStoreVerb` in `testing/perf/budgets.test.ts`.
+- **PR8 (completion merge, PR-C)** — `R6`. This package's main-line
+  `kernel/completion/complete.ts` is intentionally minimal; PR-C's fuller
+  engine (shell drivers, script goldens, rank/parse/resolve) lands at PR8.
+  `completion.test.ts` documents two gaps the fuller engine may want to close
+  (verb-level candidates aren't sorted; there's no per-verb flag completion at
+  all today) — see `PARITY_GAPS` `completion-verb-level-not-sorted`. Don't
+  double-port the rich suite; this file's thin candidate-format/set contract
+  is all PR4 owns here.

package/src/testing/behavioral/agentSession.mcp.test.ts

@@ -0,0 +1,160 @@
+/**
+ * B1 — a multi-step agent MCP session over the shared canonical fixture graph;
+ * B2 — the SPARQL escape hatch (deterministic bindings over a known graph).
+ *
+ * Every noun/verb driven here comes from `liveReadSurface.ts` (parameterized
+ * over `emitSurface(capabilities)`) — nothing is a noun name copied from the
+ * plan, except the "categories" journey, which is itself found by searching
+ * the live surface for a `categories`-shaped verb (today only `standard`
+ * declares one; the test degrades to a no-op if none exists).
+ *
+ * B2 (R2 — the live surface): `graph query` (tool `graph_query`) is now live as
+ * of PR6, with its own SELECT/ASK/CONSTRUCT + parity coverage in
+ * `capabilities/graph/query.test.ts`. B2 keeps exercising the escape hatch
+ * through `PragmaRuntime.query.sparql` directly — the exact seam the live verb
+ * delegates to (see PARITY_GAPS `graph-query-deferred`).
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { capabilities } from "../../capabilities/index.js";
+import {
+  ALL_VISIBLE_CONFIG,
+  CANONICAL_TTL,
+} from "../fixtures/graph/canonical.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../helpers/fixtureGraph.js";
+import { projectMcp } from "../helpers/projectMcp.js";
+import { listVerbs, liveVerbs, lookupVerbs } from "./liveReadSurface.js";
+
+/** Nouns exposing BOTH a `list` and a `lookup` — the "browse then inspect" pair. */
+const browsableNouns = listVerbs
+  .map((v) => v.noun)
+  .filter((noun) => lookupVerbs.some((v) => v.noun === noun));
+
+/** The one live verb literally named `categories`, if any noun declares one. */
+const categoriesVerb = liveVerbs.find(
+  (v) => v.verb === "categories" && v.tool !== false,
+);
+
+let fixture: FixtureGraph;
+let mcp: Awaited<ReturnType<typeof projectMcp>>;
+
+beforeAll(async () => {
+  fixture = await bootFixtureRuntime({
+    ttl: CANONICAL_TTL,
+    config: ALL_VISIBLE_CONFIG,
+  });
+  mcp = await projectMcp(capabilities, fixture.cwd);
+});
+
+afterAll(async () => {
+  await mcp.cleanup();
+  await fixture.dispose();
+});
+
+describe("agent session — list, pick, lookup (B1)", () => {
+  it.each(
+    browsableNouns,
+  )("%s: list -> pick first -> lookup resolves it", async (noun) => {
+    const list = await mcp.callTool(`${noun}_list`);
+    expect(list.ok).toBe(true);
+    const rows = list.data as { name: string }[];
+    expect(rows.length).toBeGreaterThan(0);
+    const first = rows[0] as { name: string };
+
+    const lookup = await mcp.callTool(`${noun}_lookup`, { name: [first.name] });
+    expect(lookup.ok).toBe(true);
+    const data = lookup.data as {
+      results: { name: string }[];
+      errors: unknown[];
+    };
+    expect(data.errors).toEqual([]);
+    expect(data.results[0]?.name).toBe(first.name);
+  });
+
+  it.each(
+    browsableNouns,
+  )("%s: a BATCH lookup with one hit reports the miss without failing the call", async (noun) => {
+    // `makeLookupRun` (kernel/packs/runBodies.ts) throws on a TOTAL miss (see
+    // the errorMatrix.mcp.test.ts B3 suite) — a partial batch is the "miss
+    // reported, call not failed" shape (an ADAPTATION of the plan's B1/B3
+    // wording, which described a single-name miss; verified against the
+    // live behavior).
+    const list = await mcp.callTool(`${noun}_list`);
+    const rows = list.data as { name: string }[];
+    const known = (rows[0] as { name: string }).name;
+
+    const result = await mcp.callTool(`${noun}_lookup`, {
+      name: [known, "zzz-definitely-not-a-real-entity"],
+    });
+    expect(result.ok).toBe(true);
+    const data = result.data as {
+      results: { name: string }[];
+      errors: { code: string }[];
+    };
+    expect(data.results[0]?.name).toBe(known);
+    expect(data.errors[0]?.code).toBe("ENTITY_NOT_FOUND");
+  });
+});
+
+describe("agent session — the categories journey, if the live surface declares one (B1)", () => {
+  it("categories -> list{category} -> lookup has dos", async () => {
+    if (!categoriesVerb) return; // No noun currently declares `categories` — skip gracefully.
+    const noun = categoriesVerb.noun;
+
+    const categories = await mcp.callTool(`${noun}_categories`);
+    expect(categories.ok).toBe(true);
+    const categoryRows = categories.data as { name: string }[];
+    expect(categoryRows.length).toBeGreaterThan(0);
+
+    // Walk categories -> entries until the sweep finds one with declared
+    // `dos` (a category whose standards happen to have none is not a
+    // failure — the journey just needs ONE positive case to prove the shape).
+    let foundDos: readonly unknown[] | undefined;
+    for (const category of categoryRows) {
+      const filtered = await mcp.callTool(`${noun}_list`, {
+        category: category.name,
+      });
+      const rows = filtered.data as { name: string }[];
+      for (const row of rows) {
+        const lookup = await mcp.callTool(`${noun}_lookup`, {
+          name: [row.name],
+          detail: "standard",
+        });
+        const data = lookup.data as { results: { dos?: unknown[] }[] };
+        const dos = data.results[0]?.dos;
+        if (dos && dos.length > 0) {
+          foundDos = dos;
+          break;
+        }
+      }
+      if (foundDos) break;
+    }
+    expect(foundDos?.length).toBeGreaterThan(0);
+  });
+});
+
+describe("the SPARQL escape hatch — deterministic bindings (B2, adapted)", () => {
+  it("resolves the 4 canonical components, ordered by name", async () => {
+    const result = await fixture.runtime.query.sparql(
+      "SELECT ?name WHERE { ?c a ds:Component ; ds:name ?name } ORDER BY ?name",
+    );
+    expect(result.type).toBe("select");
+    const names =
+      result.type === "select" ? result.bindings.map((b) => b.name) : [];
+    expect(names).toEqual(["Beta Widget", "Button", "LXD Panel", "Modal"]);
+  });
+
+  it("a COUNT aggregate over ds:Component matches the list length", async () => {
+    const countResult = await fixture.runtime.query.sparql(
+      "SELECT (COUNT(*) AS ?c) WHERE { ?comp a ds:Component }",
+    );
+    const count =
+      countResult.type === "select"
+        ? Number(countResult.bindings[0]?.c ?? 0)
+        : 0;
+    expect(count).toBe(4);
+  });
+});

package/src/testing/behavioral/autoLlm.e2e.test.ts

@@ -0,0 +1,44 @@
+/**
+ * A10 — auto-LLM output-mode selection, observed through the real binary.
+ *
+ * `parseGlobalFlags`'s auto-LLM RULE is PR1-protected at the unit level
+ * (`globalFlags.test.ts`, with an injected `OutputEnvironment`). What only a
+ * spawn can prove is the OBSERVABLE consequence: a piped `pragma` process
+ * (the shape an agent captures) really does default to condensed Markdown
+ * with no flag. `runCli`/`spawnSync` always pipes stdout — there is no
+ * practical way to allocate a real TTY in this harness to exercise the
+ * opposite (interactive) branch, which stays a PR1 unit concern
+ * (`isTty: true` injected).
+ */
+
+import { describe, expect, it } from "vitest";
+import { runCli } from "../helpers/runCli.js";
+
+describe("auto-LLM on a piped (non-TTY) stdout (A10, e2e)", () => {
+  it("defaults to condensed Markdown with no flag", () => {
+    const result = runCli(["info"]);
+    expect(result.exitCode).toBe(0);
+    // llm formatters render a Markdown heading; plain does not.
+    expect(result.stdout).toMatch(/^#/);
+  });
+
+  it("--format json disables auto-llm even when piped", () => {
+    const result = runCli(["info", "--format", "json"]);
+    expect(result.exitCode).toBe(0);
+    expect(() => JSON.parse(result.stdout)).not.toThrow();
+    expect(result.stdout.startsWith("#")).toBe(false);
+  });
+
+  it("PRAGMA_NO_AUTO_LLM keeps plain output when piped", () => {
+    const result = runCli(["info"], { env: { PRAGMA_NO_AUTO_LLM: "1" } });
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.startsWith("#")).toBe(false);
+    expect(result.stdout).toContain("pragma v");
+  });
+
+  it("an explicit --llm matches the auto-selected output", () => {
+    const auto = runCli(["info"]);
+    const explicit = runCli(["info", "--llm"]);
+    expect(explicit.stdout).toBe(auto.stdout);
+  });
+});

package/src/testing/behavioral/completion.test.ts

@@ -0,0 +1,132 @@
+/**
+ * B10 — the LIVE `__complete` candidate contract over the live read surface.
+ *
+ * The full completion engine (`kernel/completion`: parse → resolve → rank, the
+ * spec-derived model, the entity seam) owns the unit-level guarantees; this
+ * pins the behaviour end-to-end against the LIVE capabilities and — for the
+ * entity tier — against a REAL built pack index on disk (the locked-pack branch
+ * of the storeless reader, which the engine's own tests exercise only via the
+ * embedded fallback). Parameterized over the live read surface so noun/verb
+ * renames never churn it.
+ *
+ * The engine's `runComplete(words, modules, env)` is async and never throws;
+ * the entity tier is fed by `indexCompletionEnv(cwd)` — a storeless read of the
+ * active pack's `index.json`, never a store boot.
+ */
+
+import { describe, expect, it } from "vitest";
+import { capabilities } from "../../capabilities/index.js";
+import { runComplete } from "../../kernel/completion/complete.js";
+import { indexCompletionEnv } from "../../kernel/completion/entitySource.js";
+import { emitSurface } from "../../kernel/spec/emitSurface.js";
+import {
+  ALL_VISIBLE_CONFIG,
+  CANONICAL_TTL,
+} from "../fixtures/graph/canonical.js";
+import { bootFixtureRuntime } from "../helpers/fixtureGraph.js";
+import { liveVerbs } from "./liveReadSurface.js";
+
+const liveNouns = [...new Set(liveVerbs.map((v) => v.noun))];
+/** noun -> its live verb labels (self-verb nouns get one entry: the noun itself). */
+const verbsByNoun = new Map<string, string[]>();
+for (const v of liveVerbs) {
+  const list = verbsByNoun.get(v.noun) ?? [];
+  if (v.verb !== v.noun) list.push(v.verb);
+  verbsByNoun.set(v.noun, list);
+}
+
+describe("noun-level candidates: sorted, prefix-filtered, program name stripped", () => {
+  it("a live prefix resolves exactly the matching live nouns, sorted", async () => {
+    const expected = liveNouns.filter((n) => n.startsWith("s")).sort();
+    expect(expected.length).toBeGreaterThan(0); // sanity: the sweep covers something
+    await expect(runComplete(["s"], capabilities)).resolves.toEqual(expected);
+  });
+
+  it("an unknown prefix resolves to nothing", async () => {
+    await expect(
+      runComplete(["zzz-not-a-noun"], capabilities),
+    ).resolves.toEqual([]);
+  });
+
+  it("strips a leading program name some shells include", async () => {
+    const expected = liveNouns.filter((n) => n.startsWith("s")).sort();
+    await expect(runComplete(["pragma", "s"], capabilities)).resolves.toEqual(
+      expected,
+    );
+  });
+});
+
+describe("verb-level candidates: the SET matches the live surface", () => {
+  const multiVerbNouns = [...verbsByNoun.entries()].filter(
+    ([, verbs]) => verbs.length > 1,
+  );
+
+  it("has at least one multi-verb noun to sweep", () => {
+    expect(multiVerbNouns.length).toBeGreaterThan(0);
+  });
+
+  it.each(
+    multiVerbNouns,
+  )("%s: candidates == its live verb set", async (noun, verbs) => {
+    const candidates = await runComplete([noun, ""], capabilities);
+    expect([...candidates].sort()).toEqual([...verbs].sort());
+  });
+});
+
+describe("flags are kebab-cased at emission (the live, testable guarantee)", () => {
+  it("every emitted flag is kebab-case, never camelCase", () => {
+    const { nouns } = emitSurface(capabilities);
+    let sawAtLeastOneFlag = false;
+    for (const { verbs } of Object.values(nouns)) {
+      for (const verb of verbs) {
+        for (const flag of verb.flags ?? []) {
+          sawAtLeastOneFlag = true;
+          expect(flag).toMatch(/^--[a-z][a-z0-9-]*$/);
+        }
+      }
+    }
+    expect(sawAtLeastOneFlag).toBe(true);
+  });
+});
+
+describe("entity params resolve from a real built pack index (B10)", () => {
+  it("a lookup's entity positional completes from the built pack index", async () => {
+    const fixture = await bootFixtureRuntime({
+      ttl: CANONICAL_TTL,
+      config: ALL_VISIBLE_CONFIG,
+    });
+    try {
+      // The locked-pack branch of the storeless reader: a real index.json on
+      // disk under the fixture cwd, read without booting the store.
+      const all = await runComplete(
+        ["block", "lookup", ""],
+        capabilities,
+        indexCompletionEnv(fixture.cwd),
+      );
+      expect(all.length).toBeGreaterThan(0);
+
+      const narrowed = await runComplete(
+        ["block", "lookup", "ds:b"],
+        capabilities,
+        indexCompletionEnv(fixture.cwd),
+      );
+      // Every ranked candidate carries the partial (case-insensitive), and the
+      // filter is strictly narrowing — the index tier really ran.
+      expect(
+        narrowed.every((name) => name.toLowerCase().includes("ds:b")),
+      ).toBe(true);
+      expect(narrowed.length).toBeGreaterThan(0);
+      expect(narrowed.length).toBeLessThan(all.length);
+    } finally {
+      await fixture.dispose();
+    }
+  });
+});
+
+describe("global flags complete for a dash prefix, at any position", () => {
+  it("completes global flags regardless of position", async () => {
+    await expect(runComplete(["--l"], capabilities)).resolves.toEqual([
+      "--llm",
+    ]);
+  });
+});

package/src/testing/behavioral/disclosure.test.ts

@@ -0,0 +1,103 @@
+/**
+ * B6 — the cross-noun disclosure SWEEP, de-duplicated against PR3's own unit
+ * coverage.
+ *
+ * PR3 already ships `disclosure — canonical-index gating` / `resolveDetail
+ * precedence` / `MCP detail param` as protected MECHANISM tests
+ * (`kernel/packs/disclosure.test.ts`). PR4's job is different: prove the
+ * mechanism holds across EVERY noun that actually opts into disclosure — not
+ * re-testing precedence or gating, just sweeping the noun SET. Parameterized
+ * over `liveReadSurface.ts`, filtered to verbs whose `VerbSpec.disclosure` is
+ * actually declared (today: `block`, `standard` — `modifier`/`token` declare
+ * no disclosure spec at all, verified against the live pack definitions, so
+ * they are correctly excluded rather than assumed).
+ *
+ * The per-field comparison is CONTENT-AGNOSTIC (key-set growth, not a named
+ * field) so the sweep needs no per-noun knowledge of which field is "the deep
+ * one" — canonical `digest`->`standard` rename (PARITY_GAPS
+ * `digest-renamed-standard`) is exercised implicitly: gating is by canonical
+ * index, and the sweep never names a level string other than the three
+ * canonical ones.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { capabilities } from "../../capabilities/index.js";
+import { DETAIL_LEVELS } from "../../constants.js";
+import {
+  ALL_VISIBLE_CONFIG,
+  CANONICAL_TTL,
+} from "../fixtures/graph/canonical.js";
+import {
+  bootFixtureRuntime,
+  type FixtureGraph,
+} from "../helpers/fixtureGraph.js";
+import { projectMcp } from "../helpers/projectMcp.js";
+import { lookupVerbs } from "./liveReadSurface.js";
+
+const disclosureLookupVerbs = lookupVerbs.filter(
+  (v) => v.spec.disclosure !== undefined,
+);
+
+let fixture: FixtureGraph;
+let mcp: Awaited<ReturnType<typeof projectMcp>>;
+
+beforeAll(async () => {
+  fixture = await bootFixtureRuntime({
+    ttl: CANONICAL_TTL,
+    config: ALL_VISIBLE_CONFIG,
+  });
+  mcp = await projectMcp(capabilities, fixture.cwd);
+});
+
+afterAll(async () => {
+  await mcp.cleanup();
+  await fixture.dispose();
+});
+
+describe("declares its levels within the canonical index (B6)", () => {
+  it.each(disclosureLookupVerbs)("$noun: levels ⊆ the canonical index", (v) => {
+    const levels = v.spec.disclosure?.levels ?? [];
+    for (const level of levels) {
+      expect(DETAIL_LEVELS as readonly string[]).toContain(level);
+    }
+    expect(levels).toContain(v.spec.disclosure?.default);
+  });
+});
+
+describe("detail:summary vs detail:detailed — key-set growth (B6)", () => {
+  it.each(
+    disclosureLookupVerbs,
+  )("%s_lookup: detailed carries every summary key plus at least one more", async (v) => {
+    const noun = v.noun;
+    const list = await mcp.callTool(`${noun}_list`);
+    const rows = list.data as { name: string }[];
+    const name = rows[0]?.name;
+    expect(name).toBeDefined();
+    if (!name) return;
+
+    const summary = await mcp.callTool(`${noun}_lookup`, {
+      name: [name],
+      detail: "summary",
+    });
+    const detailed = await mcp.callTool(`${noun}_lookup`, {
+      name: [name],
+      detail: "detailed",
+    });
+    expect(summary.ok).toBe(true);
+    expect(detailed.ok).toBe(true);
+
+    const summaryEntity = (
+      summary.data as { results: Record<string, unknown>[] }
+    ).results[0] as Record<string, unknown>;
+    const detailedEntity = (
+      detailed.data as { results: Record<string, unknown>[] }
+    ).results[0] as Record<string, unknown>;
+
+    const summaryKeys = new Set(Object.keys(summaryEntity));
+    const detailedKeys = new Set(Object.keys(detailedEntity));
+    for (const key of summaryKeys) {
+      expect(detailedKeys.has(key)).toBe(true);
+    }
+    expect(detailedKeys.size).toBeGreaterThan(summaryKeys.size);
+  });
+});