@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/kernel/spec/types.ts

@@ -0,0 +1,233 @@
+/**
+ * The one grammar. Every capability is described by this vocabulary and
+ * nothing else: the CLI projector, the MCP projector, the surface emitter,
+ * and the completion resolver all read these shapes. Do NOT add fields — a
+ * new projection need is a signal to reshape an existing field, not to grow
+ * the grammar, so the surface covenant stays the single source of truth.
+ *
+ * Naming rule: `[noun]` -> CLI `pragma <noun>`, tool `<noun>`;
+ * `[noun, verb]` -> CLI `pragma <noun> <verb>`, tool `<noun>_<verb>`.
+ * Positionals are params with `positional: true`, in declared order; every
+ * other param is a kebab-cased flag.
+ */
+
+import type { Task } from "@canonical/task";
+import type { PragmaRuntime } from "../runtime/types.js";
+
+/** MCP tool annotations mirrored onto exposed verbs. */
+export type McpAnnotations = {
+  readOnlyHint: boolean;
+  destructiveHint?: boolean;
+  openWorldHint: boolean;
+};
+
+/**
+ * Effect + exposure profile of a verb. `mutates` is the discriminator for the
+ * effect seam: reads are plain async, mutations return a `Task`. `mcp` decides
+ * whether the verb is projected as a tool (and why not, when withheld).
+ */
+export type Capability = {
+  needsStore: boolean;
+  mutates: boolean;
+  destructive?: boolean;
+  needsNetwork?: boolean;
+  interactive?: boolean;
+  mcp:
+    | { expose: true; annotations?: McpAnnotations }
+    | { expose: false; reason: string };
+};
+
+/**
+ * A storeless name source the completion engine resolves candidates against.
+ * `__complete` never boots the graph, so every source is disk-readable: the
+ * precomputed pack index, the filesystem, or the prefix table.
+ */
+export type CompletionFrom =
+  | "index"
+  | "skills"
+  | "tiers"
+  | "prompts"
+  | "prefixes";
+
+/** A reference to one name source (with an optional prefixed type filter). */
+export interface CompletionSourceRef {
+  /** Which storeless source to read candidate names from. */
+  readonly from: CompletionFrom;
+  /** Prefixed type filter — meaningful only for `from: "index"` (empty = any). */
+  readonly type?: string;
+}
+
+/** How a partial word is matched against candidate names. */
+export type CompletionMatch = "prefix" | "substring" | "fuzzy";
+
+/**
+ * The declared autocomplete policy the engine executes generically — the
+ * "name-source" mode of {@link ParamComplete}. Derive-by-default, tune-by-field.
+ */
+export interface AutocompleteHeuristic {
+  /** Where the completable names come from. */
+  readonly source: CompletionSourceRef;
+  /** Match strategy against the partial (default `"substring"`). */
+  readonly match?: CompletionMatch;
+  /**
+   * Minimum typed chars before the generated shell script execs `__complete`
+   * for this source (default 2). Enforced at emit time; see `emitScripts`.
+   */
+  readonly minChars?: number;
+  /** Match case-sensitively (default `false` — loose match, canonical emit). */
+  readonly caseSensitive?: boolean;
+  /** Opt-out knob — `false` disables completion for the param (default `true`). */
+  readonly enabled?: boolean;
+}
+
+/**
+ * How a param's values are completed by the static/dynamic completion tiers.
+ * The `names` arm carries the {@link AutocompleteHeuristic}; `values`/`files`/
+ * `none` are unchanged. (Was `{ kind: "entity"; type }` — generalized so every
+ * object family, not only graph-backed reads, completes at the cursor.)
+ */
+export type ParamComplete =
+  | { kind: "values" }
+  | { kind: "files" }
+  | { kind: "none" }
+  | ({ kind: "names" } & AutocompleteHeuristic);
+
+/** A single parameter of a verb — a positional or a kebab-cased flag. */
+export type ParamSpec =
+  | {
+      kind: "string" | "boolean" | "number";
+      name: string;
+      doc: string;
+      required?: boolean;
+      default?: unknown;
+      positional?: boolean;
+      complete?: ParamComplete;
+    }
+  | {
+      kind: "enum";
+      name: string;
+      doc: string;
+      values: readonly string[];
+      required?: boolean;
+      default?: string;
+      positional?: boolean;
+      complete?: ParamComplete;
+    }
+  | {
+      kind: "string[]";
+      name: string;
+      doc: string;
+      required?: boolean;
+      positional?: boolean;
+      complete?: ParamComplete;
+    };
+
+/** The three output modes every verb must render. */
+export interface Formatters<T> {
+  readonly plain: (d: T) => string;
+  readonly llm: (d: T) => string;
+  readonly json: (d: T) => string;
+}
+
+/** A usage example shown in verb help. */
+export interface Example {
+  readonly cmd: string;
+  readonly note?: string;
+}
+
+/** Progressive-disclosure levels a verb honours, and its default. */
+export interface DisclosureSpec {
+  readonly levels: readonly string[];
+  readonly default: string;
+}
+
+/** A documented error a verb may raise, for help and the covenant. */
+export interface ErrorSpec {
+  readonly code: string;
+  readonly when: string;
+}
+
+/**
+ * A single verb: the atom the projectors consume.
+ *
+ * `run` is the effect seam — a read returns `Promise<R>`; a mutation returns a
+ * `Task<R>` the dispatcher interprets under the node / dry-run interpreters. A
+ * mutation that needs async setup before its effects are known (e.g.
+ * `sources update` resolves and builds before locking) actually returns a
+ * `Promise<Task<R>>`, which the dispatcher and MCP handler both `await` into a
+ * `Task<R>` before interpreting. That third shape is presented through the
+ * `Task<R>` arm by a cast at the one call site (`update.verb.ts`): adding a
+ * literal `Promise<Task<R>>` arm here poisons the contextual inference of every
+ * async read verb (they widen to `Promise<R | Task<R>>`), so the union is kept
+ * at two arms and the async-setup case carries an honest, commented cast.
+ */
+export interface VerbSpec<P = Record<string, unknown>, R = unknown> {
+  readonly path: readonly [noun: string, verb?: string];
+  readonly summary: string;
+  readonly doc?: string;
+  readonly params: readonly ParamSpec[];
+  readonly output: { schema?: unknown; formatters: Formatters<R> };
+  readonly examples?: readonly Example[];
+  readonly disclosure?: DisclosureSpec;
+  readonly capability: Capability;
+  readonly run: (p: P, rt: PragmaRuntime) => Promise<R> | Task<R>;
+  readonly errors?: readonly ErrorSpec[];
+  readonly hidden?: boolean;
+}
+
+/**
+ * An MCP resource provider — the ONE non-tool projection a module may add.
+ *
+ * `register` installs a `{+uri}` resource template on the server (listing +
+ * autocomplete are storeless over the pack index; a read is store-backed and
+ * shares the CLI's entity reader). Resources are NOT tools, so they never enter
+ * the emitted tool surface; the projector calls this per module that declares it.
+ */
+export interface McpResourceProvider {
+  readonly register: (
+    server: import("@modelcontextprotocol/sdk/server/mcp.js").McpServer,
+    rt: PragmaRuntime,
+  ) => void;
+  /**
+   * A static declaration of the resource template ids this provider installs
+   * (e.g. `["pragma:{+uri}"]`). The surface emitter projects it into
+   * `mcpSurface.resources` so the covenant freezes the non-tool surface without
+   * booting a server — the single authoring point, so the id cannot drift.
+   */
+  readonly surface?: { readonly templates: readonly string[] };
+}
+
+/**
+ * An MCP prompt provider — a module's native `prompts/*` surface.
+ *
+ * Parallel to {@link McpResourceProvider}: `register` installs the server's
+ * `prompts/list` + `prompts/get` handlers (and advertises the `prompts`
+ * capability). Listing is storeless over the pack index; a get is store-backed.
+ * Prompts are NOT tools, so they never enter the emitted tool surface; the
+ * projector calls this per module that declares it. Async because it
+ * dynamic-imports the SDK request schemas (kept off the fast path).
+ */
+export interface McpPromptProvider {
+  readonly register: (
+    server: import("@modelcontextprotocol/sdk/server/mcp.js").McpServer,
+    rt: PragmaRuntime,
+  ) => Promise<void> | void;
+}
+
+/** A capability module: a named bundle of verbs with optional boot/resources/prompts hooks. */
+export interface CapabilityModule {
+  readonly name: string;
+  readonly verbs: readonly VerbSpec[];
+  /**
+   * Optional Markdown narrating how this module's domain is made — surfaced by
+   * `pragma colophon`. Module-level metadata (like `boot`/`mcpResources`/
+   * `mcpPrompts`), NOT a `VerbSpec` field, so `emitSurface` never reads it and
+   * it has zero covenant impact.
+   */
+  readonly colophon?: string;
+  readonly boot?: (rt: PragmaRuntime) => void;
+  /** An optional MCP resource surface (NOT a VerbSpec field — a module hook). */
+  readonly mcpResources?: McpResourceProvider;
+  /** An optional MCP prompt surface (NOT a VerbSpec field — a module hook). */
+  readonly mcpPrompts?: McpPromptProvider;
+}

package/src/kernel/spec/validate.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from "vitest";
+import { fixtureModule } from "../../testing/fixtures/fixtureCapability.js";
+import type { CapabilityModule } from "./types.js";
+import { validateModule } from "./validate.js";
+
+describe("validateModule", () => {
+  it("accepts a well-formed module", () => {
+    expect(() => validateModule(fixtureModule)).not.toThrow();
+  });
+
+  it("rejects a verb with a bad param kind", () => {
+    const bad = {
+      name: "bad",
+      verbs: [
+        {
+          path: ["x", "y"],
+          summary: "x",
+          params: [{ kind: "float", name: "n", doc: "d" }],
+          output: {
+            formatters: { plain: () => "", llm: () => "", json: () => "" },
+          },
+          capability: {
+            needsStore: false,
+            mutates: false,
+            mcp: { expose: true },
+          },
+          run: async () => null,
+        },
+      ],
+    } as unknown as CapabilityModule;
+    expect(() => validateModule(bad)).toThrow(
+      /invalid capability module "bad"/,
+    );
+  });
+
+  it("rejects an expose:false verb missing its reason", () => {
+    const bad = {
+      name: "noreason",
+      verbs: [
+        {
+          path: ["x"],
+          summary: "x",
+          params: [],
+          output: {
+            formatters: { plain: () => "", llm: () => "", json: () => "" },
+          },
+          capability: {
+            needsStore: false,
+            mutates: false,
+            mcp: { expose: false },
+          },
+          run: async () => null,
+        },
+      ],
+    } as unknown as CapabilityModule;
+    expect(() => validateModule(bad)).toThrow();
+  });
+
+  it("rejects a run that is not a function", () => {
+    const bad = {
+      name: "notfn",
+      verbs: [
+        {
+          path: ["x"],
+          summary: "x",
+          params: [],
+          output: {
+            formatters: { plain: () => "", llm: () => "", json: () => "" },
+          },
+          capability: {
+            needsStore: false,
+            mutates: false,
+            mcp: { expose: true },
+          },
+          run: "nope",
+        },
+      ],
+    } as unknown as CapabilityModule;
+    expect(() => validateModule(bad)).toThrow();
+  });
+});

package/src/kernel/spec/validate.ts

@@ -0,0 +1,125 @@
+/**
+ * Runtime validation of capability modules against the grammar.
+ *
+ * zod lives here (and only in the few registration seams the conventions
+ * name) so it never reaches the `--help`/`__complete` fast path: this module
+ * is imported lazily, at boot/registration, to fail fast on a malformed spec.
+ * It validates the *data* shape of the grammar — paths, params, capability,
+ * MCP exposure — and asserts the function-valued fields are functions.
+ */
+
+import { z } from "zod";
+import type { CapabilityModule } from "./types.js";
+
+const fn = z.custom<(...args: unknown[]) => unknown>(
+  (value) => typeof value === "function",
+  { message: "expected a function" },
+);
+
+const completionSourceRefSchema = z.object({
+  from: z.enum(["index", "skills", "tiers", "prompts", "prefixes"]),
+  type: z.string().optional(),
+});
+
+const paramCompleteSchema = z.union([
+  z.object({ kind: z.literal("values") }),
+  z.object({ kind: z.literal("files") }),
+  z.object({ kind: z.literal("none") }),
+  z.object({
+    kind: z.literal("names"),
+    source: completionSourceRefSchema,
+    match: z.enum(["prefix", "substring", "fuzzy"]).optional(),
+    minChars: z.number().int().min(0).optional(),
+    caseSensitive: z.boolean().optional(),
+    enabled: z.boolean().optional(),
+  }),
+]);
+
+const positionalFields = {
+  name: z.string().min(1),
+  doc: z.string(),
+  required: z.boolean().optional(),
+  positional: z.boolean().optional(),
+  complete: paramCompleteSchema.optional(),
+};
+
+const paramSpecSchema = z.union([
+  z.object({
+    ...positionalFields,
+    kind: z.enum(["string", "boolean", "number"]),
+    default: z.unknown().optional(),
+  }),
+  z.object({
+    ...positionalFields,
+    kind: z.literal("enum"),
+    values: z.array(z.string()).min(1),
+    default: z.string().optional(),
+  }),
+  z.object({ ...positionalFields, kind: z.literal("string[]") }),
+]);
+
+const mcpAnnotationsSchema = z.object({
+  readOnlyHint: z.boolean(),
+  destructiveHint: z.boolean().optional(),
+  openWorldHint: z.boolean(),
+});
+
+const capabilitySchema = z.object({
+  needsStore: z.boolean(),
+  mutates: z.boolean(),
+  destructive: z.boolean().optional(),
+  needsNetwork: z.boolean().optional(),
+  interactive: z.boolean().optional(),
+  mcp: z.union([
+    z.object({
+      expose: z.literal(true),
+      annotations: mcpAnnotationsSchema.optional(),
+    }),
+    z.object({ expose: z.literal(false), reason: z.string().min(1) }),
+  ]),
+});
+
+const verbSpecSchema = z.object({
+  path: z.tuple([z.string().min(1)]).rest(z.string()),
+  summary: z.string().min(1),
+  doc: z.string().optional(),
+  params: z.array(paramSpecSchema),
+  output: z.object({
+    schema: z.unknown().optional(),
+    formatters: z.object({ plain: fn, llm: fn, json: fn }),
+  }),
+  examples: z
+    .array(z.object({ cmd: z.string(), note: z.string().optional() }))
+    .optional(),
+  disclosure: z
+    .object({ levels: z.array(z.string()), default: z.string() })
+    .optional(),
+  capability: capabilitySchema,
+  run: fn,
+  errors: z.array(z.object({ code: z.string(), when: z.string() })).optional(),
+  hidden: z.boolean().optional(),
+});
+
+const moduleSchema = z.object({
+  name: z.string().min(1),
+  verbs: z.array(verbSpecSchema).min(1),
+  boot: fn.optional(),
+});
+
+/**
+ * Validate a capability module against the grammar, throwing on the first
+ * malformation.
+ *
+ * @param module - The capability module to validate.
+ * @throws Error describing the first schema violation.
+ */
+export function validateModule(module: CapabilityModule): void {
+  const result = moduleSchema.safeParse(module);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    const path = issue?.path.join(".") ?? "<root>";
+    throw new Error(
+      `invalid capability module "${module?.name ?? "?"}" at ${path}: ${issue?.message ?? "unknown error"}`,
+    );
+  }
+}

package/src/testing/PARITY_GAPS.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { PARITY_GAPS } from "./PARITY_GAPS.js";
+
+/**
+ * The ledger itself (R9): every accepted divergence is recorded as one
+ * distinct, non-empty entry — mirroring the old `standardParity` suite's
+ * "records every accepted divergence as a distinct entry" guarantee.
+ */
+describe("PARITY_GAPS ledger (PROTECTED)", () => {
+  it("is non-empty", () => {
+    expect(PARITY_GAPS.length).toBeGreaterThan(0);
+  });
+
+  it("every entry has a distinct id", () => {
+    const ids = PARITY_GAPS.map((entry) => entry.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it("every entry has a non-empty area and description", () => {
+    for (const entry of PARITY_GAPS) {
+      expect(entry.id.length).toBeGreaterThan(0);
+      expect(entry.area.length).toBeGreaterThan(0);
+      expect(entry.description.length).toBeGreaterThan(20);
+    }
+  });
+
+  it("ids are kebab-case", () => {
+    for (const entry of PARITY_GAPS) {
+      expect(entry.id).toMatch(/^[a-z][a-z0-9-]*$/);
+    }
+  });
+});

package/src/testing/PARITY_GAPS.ts

@@ -0,0 +1,179 @@
+/**
+ * The consolidated, living record of every INTENTIONAL divergence from the old
+ * shell's behavior (or from a naive byte-exact-parity expectation).
+ *
+ * PORTS the CONCEPT of the old `testing/standardParityFixtures.ts#PARITY_GAPS`
+ * — each entry names one accepted divergence, so a reviewer (or a future PR)
+ * can tell "this is different on purpose" from "this regressed." PR4 owns this
+ * CONSOLIDATED file: at PR4 impl time no other PR had started a per-noun gaps
+ * list (grepped the tree — no `PARITY_GAP`/"disposition table" precedent
+ * existed), so this is the ledger every later PR appends its own accepted
+ * divergences to, rather than scattering ad hoc comments.
+ *
+ * The `PARITY_GAPS.test.ts` ledger test asserts every entry is distinct and
+ * non-empty — the same shape `standardParity`'s old ledger test enforced.
+ */
+
+/** One accepted, intentional divergence from a naive parity expectation. */
+export interface ParityGapEntry {
+  /** A short, stable, kebab-case identifier for the gap. */
+  readonly id: string;
+  /** Which area of the surface the gap applies to. */
+  readonly area: string;
+  /** Why the divergence is intentional, and where it's decided in code. */
+  readonly description: string;
+}
+
+/** The consolidated ledger. Append here; do not delete a still-true entry. */
+export const PARITY_GAPS: readonly ParityGapEntry[] = [
+  {
+    id: "no-condensed-mcp-envelope",
+    area: "mcp/envelope",
+    description:
+      "v2's MCP tool result IS the CLI `--format json` envelope (`{ok,data,meta}` / `{ok,error}`), built by the SAME `successEnvelope`/`errorEnvelope` (kernel/render/envelope.ts). There is no separate condensed/text/token-count MCP shape to reproduce, so parity is asserted as structural data-equality (helpers/parity.ts), not a byte-exact `condensed === fmt.llm(...)` comparison.",
+  },
+  {
+    id: "pack-lists-single-level",
+    area: "pack list",
+    description:
+      "Every bundled/dynamic pack's `list` returns the full row set in one response — no pagination/cursor/page-size flags. A noun with a large population relies on `--search`/declared filters (or `sample` for shape discovery) to narrow it, not paging.",
+  },
+  {
+    id: "read-meta-always-empty",
+    area: "envelope",
+    description:
+      "`dispatch.ts#executeVerb`'s read branch always renders with `meta: {}` — there is no `meta.count`/`meta.total` field on a list/lookup envelope (verified empirically). An empty (possibly filtered) list is `{ok:true, data:[], meta:{}}`; the only way to know it's empty is `data.length === 0`, not a meta field.",
+  },
+  {
+    id: "no-empty-hook-on-free-filter",
+    area: "pack list / empty-state",
+    description:
+      "A zero-row pack list — whether narrowed by a declared filter, an unmatched `--search`, or unconditionally empty — returns `ok:true, data:[], meta:{}` at exit 0 with a calm `emptyMessage`/`emptyHint`; pragma v2 never raises a typed EMPTY_RESULTS error for an empty list. (U5 removed the former enum-filter-only `buildListEmptyError` hook, making the empty-state uniform across every list verb.)",
+  },
+  {
+    id: "raw-iri-in-data",
+    area: "pack lookup / disclosure",
+    description:
+      "An IRI-valued field (e.g. `cs:extends`) stays the full, uncompacted IRI in `data` (`--format json` / MCP). Compaction to `prefix:local` (`kernel/render/compactUri.ts`) is applied only by the plain/llm renderers at display time — the JSON payload is never display-shaped.",
+  },
+  {
+    id: "all-string-pack-records",
+    area: "pack list / lookup",
+    description:
+      "Every pack row/entity is a flat `Record<string,string>` (list rows: `PackRow`; lookup/expand: `PackEntity`/`PackChildRow`), typed and rendered generically by column/field/section METADATA the pack declares — never a per-noun bespoke record class or hand-authored template.",
+  },
+  {
+    id: "sample-is-nondeterministic-across-calls",
+    area: "sample verb",
+    description:
+      "`kernel/packs/sample.ts#pickRandom` draws an independent random selection on EVERY call. Two separate invocations of the same `<noun> sample` — even back-to-back, even CLI vs MCP — are not expected to return identical entities. Content-equality parity (`helpers/parity.ts`) is scoped to deterministic verbs; sample's STRUCTURE (population size, requested count, envelope shape) is what B4's callable-envelope sweep checks instead.",
+  },
+  {
+    id: "positional-sample-count",
+    area: "sample verb",
+    description:
+      "`<noun> sample [count]` takes `count` as an optional POSITIONAL (`pragma standard sample 3`), not an old-style `--count` flag. Omitted, it falls back to the pack's declared default (or the built-in default of 2).",
+  },
+  {
+    id: "generic-renderers-not-bespoke-templates",
+    area: "render",
+    description:
+      "Every noun's plain/llm output — including the one hand-written verb, `block list` — renders through the SAME generic list/lookup renderer (`kernel/render/renderers.ts`), driven by declarative column/field/section metadata. There are no per-noun hand-authored render templates left to keep in parity.",
+  },
+  {
+    id: "block-lookup-not-tier-scoped",
+    area: "block",
+    description:
+      "`block lookup` resolves by `ds:name` GLOBALLY, with no tier or channel filtering — only the hand-written `block list` is tier/channel-aware (PR3 Risk5, `capabilities/block/tierChain.ts`). A same-named block declared at two tiers cannot be disambiguated by `block lookup` alone (the old shell's tier-scoped lookup disambiguation has no v2 equivalent).",
+  },
+  {
+    id: "graph-query-deferred",
+    area: "graph",
+    description:
+      "CLOSED by PR6: `graph query` (arbitrary SPARQL, tool `graph_query`) is now live (`capabilities/graph/query.verb.ts`), with its own SELECT/ASK/CONSTRUCT + parity coverage. Two residual divergences remain recorded: a query failure raises INVALID_INPUT (exit 2) with an `ontology list` recovery, NOT the retired v1 `STORE_ERROR`; and B2/the eval seed (`agentSession.mcp.test.ts`, `eval/cases/stable.ts`) still exercise the shared `PragmaRuntime.query.sparql` facade directly — the exact seam the live verb delegates to — rather than re-driving through the tool.",
+  },
+  {
+    id: "config-field-query-via-show",
+    area: "config setters",
+    description:
+      "The covenant gives each `config <field>` setter exactly ONE required positional, so the old per-verb QUERY mode (`pragma config tier` with no arg → print current) is impossible without breaking conformance. Reading a field is `config show` (which reports every field + provenance). Set-only setters (`config/fields.ts`).",
+  },
+  {
+    id: "config-field-reset-sentinel",
+    area: "config setters",
+    description:
+      "No `--reset` flag exists (a flag would emit `flags:[...]` and break the covenant). `tier` (a free string with a meaningful 'no value') resets via a reserved sentinel (`none`/`default`/`-` → removes the field, `writeConfigField(field, undefined)`); `channel`/`detail` reset by setting their default (`normal`/`standard`). `config/runField.ts`.",
+  },
+  {
+    id: "config-global-write-only",
+    area: "config setters",
+    description:
+      "v2 `writeConfigField` writes the GLOBAL layer only ('project configs are authored by hand'), so the old `--scope`/`--local` selectors are dropped. A setter never edits a project `pragma.config.ts`. `kernel/config/writeConfigField.ts`.",
+  },
+  {
+    id: "config-tier-no-ontology-validation",
+    area: "config setters",
+    description:
+      "The covenant `config_tier` has no `needsStore`, so it is storeless — the old store-backed `validateTier` (which queried the ontology for valid tier paths) is DROPPED. `config tier <anything>` writes the value verbatim; an unknown tier simply yields empty scoped reads later. `config/fields.ts`.",
+  },
+  {
+    id: "doctor-exit-zero-with-failures",
+    area: "doctor",
+    description:
+      "The old `doctor` set `process.exitCode = 1` when checks failed. v2 `doctor` is a read (`mutates:false`) and ALWAYS exits 0 — failures live in the `{ failed }` count of the envelope (agents read the data; CI greps `failed`). The dispatcher only maps `PragmaError` codes to non-zero exits, and doctor raises none. `capabilities/doctor/doctor.verb.ts`.",
+  },
+  {
+    id: "info-entitycount-storeless-not-triplecount",
+    area: "info",
+    description:
+      "`info`'s entity total comes from the storeless pack index (`readPackIndex` → sum of `instanceCountByType`), NEVER a store boot — so the storeless invariant (`store.booted === false`) holds. The old `collectStoreSummary`'s SPARQL triple-count is DROPPED (`sources status` owns the per-source breakdown; info shows one total). `capabilities/info/collectInfo.ts`.",
+  },
+  {
+    id: "setup-skills-undo-recompute",
+    area: "setup",
+    description:
+      "Setup ops recompute their plan against real fs each run (preview-accuracy), so `setup skills --undo` AFTER a real `setup skills` sees the now-correct symlink as 'skipped' and emits no symlink effect — there is nothing left to reverse. Writes that always re-emit their undo (`setup completions`' file write) DO reverse cleanly under `--undo`. The symlink effect itself carries a `deleteFile` undo (asserted structurally). `capabilities/setup/operations/setupSkills.ts`.",
+  },
+  {
+    id: "digest-renamed-standard",
+    area: "disclosure",
+    description:
+      "The old `digest` disclosure level is named `standard` in v2's canonical three-level index (`summary < standard < detailed`, `constants.DETAIL_LEVELS`). Gating is by canonical INDEX, not by a pack-declared level name matching a fixed string.",
+  },
+  {
+    id: "completion-verb-level-not-sorted",
+    area: "completion",
+    description:
+      "The pr4-base main-line `kernel/completion/complete.ts` sorts NOUN-level candidates (`buildCompletionModel`) and ENTITY-param candidates (`createIndexEntityReader`), but VERB-level candidates are in AUTHORING order (`model.verbs[noun]` is never sorted) — verified empirically (`standard` completes as `[list, categories, lookup, sample]`, not alphabetical). It also offers NO per-verb flag completion at all (a `-`-prefixed partial always resolves against the global flags only). B10 (`completion.test.ts`) asserts verb candidates as a SET, not an order, and pins kebab-casing at the emission layer rather than a nonexistent completion-time flag offer. PR-C's fuller engine (merging at PR8) may close both gaps — flagged here for that review, not fixed by PR4 (R6: completion engine work is PR-C's).",
+  },
+  {
+    id: "skill-noun-storeless",
+    area: "skill",
+    description:
+      "`skill list`/`skill lookup` are pure filesystem discovery (`needsStore: false`) — they never touch the knowledge-graph store. Every other read noun in this ledger's scope is store-backed; `skill` is the one deliberate exception.",
+  },
+  {
+    id: "single-lookup-miss-fails-batch-partial-reports",
+    area: "pack lookup",
+    description:
+      "`kernel/packs/runBodies.ts#makeLookupRun` throws (the call fails, `ok:false`) on a TOTAL miss — a single unresolved name, or a batch where EVERY name misses. Only a PARTIAL batch (at least one name resolves) reports the miss in `data.errors` while returning `ok:true` with the hits in `data.results`. Verified empirically (`agentSession.mcp.test.ts` / `errorMatrix.mcp.test.ts`) — a single-name miss is a failed call, not a reported one.",
+  },
+  {
+    id: "plan-first-meta-differs",
+    area: "mutation plan-first",
+    description:
+      "A CLI `--dry-run` and an unconfirmed MCP call describe the SAME effects (`data.plan`), but under intentionally DIFFERENT `meta` shapes: `{dryRun:true}` (dispatch.ts#renderPlan) vs `{planOnly:true,confirmRequired:true}` (registerVerb.ts#mutateHandler). They are different REQUESTS — one an explicit preview, one an implicit not-yet-confirmed call — so the envelope names the mode differently rather than forcing one vocabulary onto both.",
+  },
+  {
+    id: "index-fields-trimmed",
+    area: "pack index",
+    description:
+      "`index.json` (PackIndex v2) does not carry `category`/`primaryType`/`primaryTypeLabel` — dropped at the pr3-fold review as zero-consumer fields. Completion and the MCP resource browser read only `{name,type,uri,prefixed,types,label,box,description}` plus `instanceCountByType`.",
+  },
+  {
+    id: "mcp-prompts-empty-without-project-prompts",
+    area: "mcp/prompts",
+    description:
+      "The native MCP `prompts/list` (and the `prompt_list`/`prompt_lookup` content tools) project `ds:Prompt` KG entities read from the ACTIVE pack index (`kernel/project/mcp/prompts/source.ts#listPromptSummaries`) — project-supplied data, NOT shipped in the embedded/bundled pack. A bare install (no project-authored `ds:Prompt`) advertises the prompts capability but lists ZERO prompts, never booting the store on the list path. Non-empty listings are exercised only against the seeded fixture graph (`testing/fixtures/graph/canonical.ts`); the storeless empty-by-default case is pinned by `prompts.test.ts` ('lists zero prompts … when no prompt entities exist').",
+  },
+] as const;