@intentius/chant 0.83.0 → 0.85.0

package/src/workspace/member-commands.ts

@@ -333,9 +333,12 @@ export function parseMemberRunOutput(stdout: string): { chant: string; results:
   return header ? { chant: header.chant, results, stray: stray.join("\n") } : undefined;
 }
 
-async function runGroup(verb: WorkspaceVerb, group: ToolchainGroup, root: string, args: ParsedArgs): Promise<UnitResult[]> {
+/** A command line to run in each member instead of the verb's own, such as `graph --components` (#2662). */
+export type MemberArgv = (unit: RunUnit) => string[];
+
+async function runGroup(verb: WorkspaceVerb, group: ToolchainGroup, root: string, args: ParsedArgs, argvFor?: MemberArgv): Promise<UnitResult[]> {
   const { toolchain, units } = group;
-  const argvs = new Map(units.map((u) => [u.id, memberArgv(verb, u, args)]));
+  const argvs = new Map(units.map((u) => [u.id, argvFor ? argvFor(u) : memberArgv(verb, u, args)]));
   for (const u of units) {
     const o = argvs.get(u.id)!;
     const i = o.indexOf("--output");
@@ -365,9 +368,12 @@ async function runGroup(verb: WorkspaceVerb, group: ToolchainGroup, root: string
   return out;
 }
 
-/** Run every group of the plan, one process per toolchain at a time each, and return the results in plan order. */
-export async function executePlan(plan: MemberPlan, args: ParsedArgs): Promise<UnitResult[]> {
-  const perGroup = await Promise.all(plan.groups.map((g) => runGroup(plan.verb, g, plan.workspace.root, args)));
+/**
+ * Run every group of the plan, one process per toolchain at a time each, and
+ * return the results in plan order. `argvFor` replaces the verb's command line.
+ */
+export async function executePlan(plan: MemberPlan, args: ParsedArgs, argvFor?: MemberArgv): Promise<UnitResult[]> {
+  const perGroup = await Promise.all(plan.groups.map((g) => runGroup(plan.verb, g, plan.workspace.root, args, argvFor)));
   const byId = new Map(perGroup.flat().map((r) => [r.id, r]));
   const order = plan.groups.flatMap((g) => g.units);
   return order.map((u) => byId.get(u.id)!);

package/src/workspace/read-contract.test.ts

@@ -6,8 +6,9 @@
  * `chant` member (`delivery`), three `other` members and decision records.
  * Each read-contract command reads it here, and its output must validate
  * against the command's schema: `ls`, `graph` (running delivery's real
- * `chant graph`), `check`, `status` and `records`, in the working tree and,
- * for `ls`, `graph` and `check`, at `HEAD` through `--at`.
+ * `chant graph`), `graph --composites`, `check`, `status` and `records`, in
+ * the working tree and, for `ls`, `graph` and `check`, at `HEAD` through
+ * `--at`.
  *
  * The schemas themselves are checked here too: each is a draft 2020-12
  * document under `https://intentius.io/chant/schemas/workspace/<command>/v1/`,
@@ -20,8 +21,12 @@ import { pathToFileURL } from "node:url";
 import { describe, expect, test } from "vitest";
 import { contract, git, REPO, validSchema } from "./__fixtures__/contract-repo";
 import checkSchema from "./check.schema.json";
+import { workspaceComposites } from "./composites";
+import compositesSchema from "./composites.schema.json";
 import { workspaceGraph } from "./graph-cli";
 import graphSchema from "./graph.schema.json";
+import { intentGraph } from "./intent";
+import intentSchema from "./intent.schema.json";
 import { runChecks } from "./lineage-check";
 import { listWorkspace } from "./ls";
 import lsSchema from "./ls.schema.json";
@@ -35,7 +40,7 @@ import statusSchema from "./status.schema.json";
 const FIXTURE = join(REPO, "reference-workspace");
 const TIMEOUT = 240_000;
 
-const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema };
+const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, intent: intentSchema, composites: compositesSchema };
 
 /** This checkout's chant, started the way the CLI starts it, for members with no toolchain of their own. */
 const reader: Toolchain = {
@@ -116,6 +121,44 @@ describe("every schema against the reference workspace (#2543)", () => {
     expect(doc.members.map((m) => m.name)).toEqual(["app", "delivery", "design-client", "design"]);
   });
 
+  test("graph --intent, in the working tree and at HEAD (#2651)", async () => {
+    const { expectValid } = contract(intentSchema);
+    for (const at of [undefined, "HEAD"]) {
+      const { doc, failed } = await intentGraph({ cwd: FIXTURE, region: "app/src/server.mjs:19", at, kinds: ["decisions/decision.kind.mjs"] });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(failed).toBe(false);
+      expect(doc.workspace).toEqual({ name: "reference", root: "reference-workspace" });
+      expect(doc.at).toBe(at ? head : null);
+      expect(doc.region).toBe("region:app/src/server.mjs:19");
+    }
+  });
+
+  test(
+    "graph --composites runs delivery's own component graph, and says why the list is empty (#2662)",
+    async () => {
+      const { expectValid } = contract(compositesSchema);
+      for (const at of [undefined, "HEAD"]) {
+        const { doc, failed } = await workspaceComposites({ cwd: FIXTURE, at, reader });
+        expectValid(doc);
+        if ("error" in doc) throw new Error(doc.error.message);
+        expect(failed, JSON.stringify(doc.members)).toBe(false);
+        expect(doc.at).toBe(at ? head : null);
+        expect(doc.members.map((m) => [m.name, m.status])).toEqual([
+          ["app", "skipped"],
+          ["delivery", "read"],
+          ["design-client", "skipped"],
+          ["design", "skipped"],
+        ]);
+        // delivery has a docker Service and no composite or component.
+        expect(doc.composites).toEqual([]);
+        expect(doc.components).toEqual([]);
+        expect(doc.reasons.map((r) => r.code)).toEqual(["composites-none-declared", "composites-no-component"]);
+      }
+    },
+    TIMEOUT,
+  );
+
   test("records, in the working tree and at HEAD", async () => {
     const { expectValid } = contract(recordsSchema);
     for (const at of [undefined, "HEAD"]) {

package/src/workspace/reason-codes.test.ts

@@ -10,11 +10,15 @@ import { join } from "node:path";
 import { describe, expect, test } from "vitest";
 import { REPO } from "./__fixtures__/contract-repo";
 import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
+import { COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES } from "./composites";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { GRAPH_ERROR_CODES } from "./graph-cli";
+import { INTENT_ERROR_CODES, INTENT_FINDING_CODES, INTENT_REASON_CODES } from "./intent";
 import { CHECK_CODES, CHECK_ERROR_CODES } from "./lineage-check";
 import { GROUP_REASON_CODES, MEMBER_REASON_CODES } from "./ls";
-import { isReasonCode, REASON_CODES, REASONS } from "./reason-codes";
+import intentSchema from "./intent.schema.json";
+import { isPluginCode, isReasonCode, REASON_CODES, REASONS } from "./reason-codes";
+import { contract } from "./__fixtures__/contract-repo";
 import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES } from "./records";
 import { STATUS_ERROR_CODES, STATUS_REASON_CODES } from "./status";
 
@@ -33,6 +37,11 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   RECORD_REASON_CODES,
   RECORD_WARNING_CODES,
   READ_ERROR_CODES,
+  INTENT_ERROR_CODES,
+  INTENT_FINDING_CODES,
+  INTENT_REASON_CODES,
+  COMPOSITES_ERROR_CODES,
+  COMPOSITES_REASON_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */
@@ -94,7 +103,7 @@ describe("the closed list of reason codes", () => {
   });
 
   test("no source file emits a code outside the list", () => {
-    const emitted = /(?:\bcode:\s*|(?:WorkspaceReadError|RecordReadError|StatusError)\(\s*)"([a-z0-9-]+)"/g;
+    const emitted = /(?:\bcode:\s*|(?:WorkspaceReadError|RecordReadError|StatusError|IntentError)\(\s*)"([a-z0-9-]+)"/g;
     let seen = 0;
     for (const file of sourceFiles(HERE)) {
       const text = readFileSync(file, "utf-8");
@@ -107,6 +116,34 @@ describe("the closed list of reason codes", () => {
     expect(seen).toBeGreaterThan(30);
   });
 
+  test("a plugin's finding codes are in its own namespace, outside the list, and the intent schema accepts them (#2656)", () => {
+    expect(isPluginCode("plugin:chud:contract-criteria-changed")).toBe(true);
+    expect(isPluginCode("plugin:chud:contract-criteria-changed", "chud")).toBe(true);
+    expect(isPluginCode("plugin:chud:contract-criteria-changed", "units")).toBe(false);
+    for (const bad of ["plugin:chud", "plugin::x", "plugin:chud:Upper", "plugin:chud:a:b", "intent-commit-bare", 7]) expect(isPluginCode(bad), String(bad)).toBe(false);
+    expect(isReasonCode("plugin:chud:contract-criteria-changed")).toBe(false);
+    const { validate } = contract(intentSchema);
+    const finding = (code: string) => ({ id: `finding:${code}:1`, kind: "finding", code, message: "m", concerns: [] });
+    const doc = (code: string) => ({
+      $schema: intentSchema.$id,
+      contract: 1,
+      chant: "0.0.0",
+      at: null,
+      workspace: { name: "w", root: "." },
+      region: "region:.",
+      history: { rev: null, follows: "directory", shallow: false },
+      kinds: [],
+      nodes: [finding(code)],
+      edges: [],
+      reasons: [],
+      summary: { commits: 0, decisions: 0, artifacts: 0, findings: 1 },
+    });
+    expect(validate(doc("plugin:chud:contract-criteria-changed"))).toBe(true);
+    expect(validate(doc("intent-commit-bare"))).toBe(true);
+    expect(validate(doc("plugin:chud:Nope"))).toBe(false);
+    expect(validate(doc("made-up-code"))).toBe(false);
+  });
+
   test("the read-contract page documents every code", () => {
     const page = readFileSync(join(REPO, "docs", "src", "content", "docs", "reference", "workspace-read-contract.mdx"), "utf-8");
     for (const c of REASON_CODES) expect(page, c).toContain(`| \`${c}\` |`);

package/src/workspace/reason-codes.ts

@@ -64,6 +64,7 @@ export const REASONS = {
   "asset-missing": "A file the record pins by hash does not exist in the tree read.",
   "asset-stale": "A file the record pins is unchanged at the hash a record it supersedes pinned: the decision changed and the artifact did not follow.",
   "record-supersedes-pending": "A supersedes link from a record whose state is weaker than the record it names, so the link has no effect yet.",
+  "record-no-evidence": "The record's evidence list is empty: it cites nothing and pins no file. Information for a reviewer, never an error.",
   // A records read that fails (records).
   "kind-unreadable": "The record kind file is missing or could not be imported.",
   "kind-invalid": "The record kind file exports no recordKind, or its shape is wrong.",
@@ -71,6 +72,28 @@ export const REASONS = {
   "schema-id-mismatch": "The schema's $id differs from the id the record kind names.",
   "schema-invalid": "The record schema itself does not compile.",
   "location-missing": "The records directory does not exist, in the tree or at the revision.",
+  // The intent graph (graph --intent, #2651): a read that fails.
+  "intent-region-invalid": "The region's path, or its line range, does not exist in the tree read.",
+  // The intent graph: part of the walk that can't be read. The document is still printed.
+  "intent-history-shallow": "The repository is a shallow clone, so the region's history stops at the clone's boundary.",
+  "intent-plugin-failed": "A kind file's commitJoins, which joins commits to units, contracts and evidence, failed for a commit.",
+  // The intent graph: findings, each a node in the graph.
+  "intent-commit-undecided": "A commit changed the region when no decision constrained it at path granularity.",
+  "intent-commit-bare": "A commit names no unit, no pull request and no decision covering the region at its time.",
+  "intent-pin-drifted": "A decision's pinned artifact no longer hashes to the pin.",
+  "intent-pin-missing": "A decision's pinned artifact does not exist in the tree read.",
+  "intent-artifact-unpinned": "An artifact decisions in the graph pinned, which no current decision pins.",
+  "intent-decision-superseded-live": "Every decision constraining the region is superseded.",
+  "intent-decision-provisional": "The current decisions constraining the region are all in states their kind does not close, such as decided.",
+  "intent-constraint-coarse": "The region is constrained only through its member, not by path.",
+  "intent-constraint-lost": "A decision's path constraint names a path that does not exist in the tree read.",
+  "intent-evidence-unpinned": "A decision's evidence has no hash: a URL, or a path with no sha256.",
+  "intent-trailer-unverified": "A commit carries a trailer a plugin says claims authorship, and the commit is not attested.",
+  "intent-region-unconstrained": "No decision constrains the region at any granularity.",
+  // Composite instances joined to components (graph --composites, #2662): why the list is empty or has no component.
+  "composites-no-chant-member": "No member of kind chant was read, so nothing declares a composite instance or a component.",
+  "composites-none-declared": "The members read declare no composite instance.",
+  "composites-no-component": "The members read declare no component, so no composite instance has one.",
   // The lineage lock (check).
   "lock-invalid": "The lineage lock can't be read.",
   "manual-step-open": "A scope in the lineage lock has an open manual step.",
@@ -84,3 +107,20 @@ export const REASON_CODES = Object.keys(REASONS) as ReasonCode[];
 export function isReasonCode(value: unknown): value is ReasonCode {
   return typeof value === "string" && Object.prototype.hasOwnProperty.call(REASONS, value);
 }
+
+/**
+ * A finding code a plugin contributes to the intent graph through its
+ * `commitJoins` (#2656): `plugin:<name>:<code>`, where `<name>` is the kind's
+ * name and `<code>` is lower case words joined by dashes. These are outside the
+ * closed list: the plugin owns its namespace, and core only carries them.
+ */
+export type PluginCode = `plugin:${string}:${string}`;
+
+export const PLUGIN_CODE = /^plugin:([^:\s]+):([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
+/** Whether `value` is a plugin code, and, given `name`, one in that kind's namespace. */
+export function isPluginCode(value: unknown, name?: string): value is PluginCode {
+  if (typeof value !== "string") return false;
+  const m = value.match(PLUGIN_CODE);
+  return !!m && (name === undefined || m[1] === name);
+}

package/src/workspace/records-contract.test.ts

@@ -5,13 +5,13 @@
  * doesn't exist yet, so the chant repo's own decision files stand in for it.
  */
 
-import { cpSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import Ajv2020 from "ajv/dist/2020";
 import { afterAll, describe, expect, test } from "vitest";
 import { queryRecords, RECORDS_CONTRACT_VERSION, RECORDS_OUTPUT_SCHEMA_ID, type RecordsDocument } from "./records-cli";
-import { READ_ERROR_CODES, RECORD_REASON_CODES } from "./records";
+import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES } from "./records";
 import schema from "./records.schema.json";
 import { PROVENANCE_LEVELS } from "./trust/attestor";
 
@@ -77,6 +77,26 @@ describe("records output schema", () => {
     expect(doc.summary.invalid).toBe(2);
   });
 
+  test("a workspace-sourced decision with no evidence validates, with its warning (#2654)", async () => {
+    const root = copyDecisions();
+    const dir = join(root, "docs", "design", "decisions");
+    const text = readFileSync(join(dir, "ws-003-seal-scope.md"), "utf-8")
+      .replace(/^id: .*$/m, 'id: "ws-900"')
+      .replace(/^source:\n(?:  .*\n)*/m, 'source:\n  kind: "workspace"\n  member: "app"\n')
+      .replace(/^evidence:\n(?:  .*\n)*/m, "evidence: []\n");
+    writeFileSync(join(dir, "ws-900-extra.md"), text);
+    const doc = await queryRecords({ kind: KIND, current: true, cwd: root });
+    expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    const r = doc.records.find((x) => x.id === "ws-900");
+    expect(r?.valid).toBe(true);
+    expect(r?.warnings?.map((w) => w.code)).toEqual(["record-no-evidence"]);
+  });
+
+  test("lists exactly the warning codes the code can return", () => {
+    expect(schema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES]);
+  });
+
   test("every failure validates with its code", async () => {
     const root = copyDecisions();
     const docs = [

package/src/workspace/records.schema.json

@@ -74,7 +74,7 @@
           "items": { "$ref": "#/$defs/asset" }
         },
         "warnings": {
-          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, or a supersedes link that has no effect yet. valid and --current do not look at them.",
+          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, or (added by #2654) an evidence list that is empty. valid and --current do not look at them.",
           "type": "array",
           "items": { "$ref": "#/$defs/warning" }
         }
@@ -101,7 +101,7 @@
       "type": "object",
       "required": ["code", "message"],
       "properties": {
-        "code": { "enum": ["asset-drift", "asset-missing", "asset-stale", "record-supersedes-pending"] },
+        "code": { "enum": ["asset-drift", "asset-missing", "asset-stale", "record-supersedes-pending", "record-no-evidence"] },
         "message": { "type": "string" }
       }
     },

package/src/workspace/records.test.ts

@@ -93,6 +93,49 @@ describe("readRecords", () => {
     expect(r.data).not.toBeNull();
   });
 
+  describe("a dissent needs a reason (#2652)", () => {
+    const withReviews = (reviews: string) => decision("ws-001").replace(/^reviews: \[\]$/m, `reviews:\n${reviews}`);
+    const review = (verdict: string, extra = "") => `  - reviewer: "ana"\n    verdict: "${verdict}"\n    on: "2026-09-24"\n${extra}`;
+
+    for (const [label, note] of [
+      ["null", "    note: null\n"],
+      ["empty", '    note: ""\n'],
+      ["blank", '    note: "  "\n'],
+      ["missing", ""],
+    ] as const) {
+      test(`a dissent with a ${label} note is record-schema-invalid, naming the reviewer`, async () => {
+        write("ws-001-a.md", withReviews(review("dissent", note)));
+        const [r] = (await read()).records;
+        expect(r.valid).toBe(false);
+        expect(codes(r)).toEqual(["record-schema-invalid"]);
+        expect(r.reasons[0].message).toBe("/reviews/0 A dissent needs a reason: the dissent by ana has no note.");
+      });
+    }
+
+    test("a dissent with a note is valid, and so are agree and abstain without one", async () => {
+      write(
+        "ws-001-a.md",
+        withReviews(
+          review("dissent", '    note: "the seal should cover the lockfile too"\n') +
+            review("agree") +
+            review("abstain", "    note: null\n"),
+        ),
+      );
+      const [r] = (await read()).records;
+      expect(r.reasons).toEqual([]);
+      expect(r.valid).toBe(true);
+    });
+
+    test("a dissent carries its concern's lifecycle; another verdict cannot", async () => {
+      write("ws-001-a.md", withReviews(review("dissent", '    note: "why"\n    addressed_by: "INTENTIUS/chant#2652"\n    withdrawn_on: "2026-09-25"\n')));
+      expect((await read()).records[0].valid).toBe(true);
+      write("ws-001-a.md", withReviews(review("agree", '    addressed_by: "ws-002"\n')));
+      const [r] = (await read()).records;
+      expect(codes(r)).toEqual(["record-schema-invalid"]);
+      expect(r.reasons[0].message).toBe("/reviews/0 Only a dissent is a concern: the agree by ana cannot carry addressed_by or withdrawn_on.");
+    });
+  });
+
   test("a supersedes link to a missing id is record-supersedes-unknown", async () => {
     write("ws-002-b.md", decision("ws-002", "decided", ["ws-404"]));
     const [r] = (await read()).records;
@@ -199,6 +242,56 @@ describe("readRecords", () => {
   });
 });
 
+/**
+ * A decision made in the workspace (#2654): the workspace source form with no
+ * issue, and no evidence. `constrains` replaces ws-003's.
+ */
+function workspaceDecision(id: string, constrains: string[] = ["member:app"]): string {
+  const list = constrains.length === 0 ? "constrains: []\n" : `constrains:\n${constrains.map((c) => `  - "${c}"\n`).join("")}`;
+  return decision(id)
+    .replace(/^source:\n(?:  .*\n)*/m, 'source:\n  kind: "workspace"\n  member: "app"\n')
+    .replace(/^evidence:\n(?:  .*\n)*/m, "evidence: []\n")
+    .replace(/^constrains:\n(?:  .*\n)*/m, list);
+}
+
+describe("a decision that originates in the workspace (#2654)", () => {
+  test("validates with no issue and no evidence, is current, and carries record-no-evidence", async () => {
+    write("ws-001-a.md", workspaceDecision("ws-001"));
+    const current = await read({ current: true });
+    expect(current.records.map((r) => [r.id, r.valid, r.reasons, r.warnings.map((w) => w.code)])).toEqual([
+      ["ws-001", true, [], ["record-no-evidence"]],
+    ]);
+    expect(current.records[0].data?.source).toEqual({ kind: "workspace", member: "app" });
+  });
+
+  test("takes a session and an issue, and nothing else", async () => {
+    const base = workspaceDecision("ws-001");
+    write("ws-001-a.md", base.replace('  member: "app"\n', '  member: "app"\n  session: "S-0001"\n  issue: "jhgaylor/chud#77"\n'));
+    write("ws-002-b.md", base.replace('id: "ws-001"', 'id: "ws-002"').replace('  member: "app"\n', '  member: "app"\n  session: null\n'));
+    write("ws-003-c.md", base.replace('id: "ws-001"', 'id: "ws-003"').replace('  member: "app"\n', '  member: "app"\n  row: "Sort order"\n'));
+    write("ws-004-d.md", base.replace('id: "ws-001"', 'id: "ws-004"').replace('  member: "app"\n', ""));
+    const records = (await read()).records;
+    expect(records.map((r) => [r.id, codes(r)])).toEqual([
+      ["ws-001", []],
+      ["ws-002", []],
+      ["ws-003", ["record-schema-invalid"]],
+      ["ws-004", ["record-schema-invalid"]],
+    ]);
+  });
+
+  test("a record with evidence carries no record-no-evidence warning", async () => {
+    write("ws-001-a.md", decision("ws-001"));
+    expect((await read()).records[0].warnings).toEqual([]);
+  });
+
+  test("a record that constrains nothing is refused", async () => {
+    write("ws-001-a.md", workspaceDecision("ws-001", []));
+    const [r] = (await read()).records;
+    expect(codes(r)).toEqual(["record-schema-invalid"]);
+    expect(r.reasons[0].message).toMatch(/constrains/);
+  });
+});
+
 describe("loadRecordKind", () => {
   const load = () => loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));
 

package/src/workspace/records.ts

@@ -62,6 +62,12 @@ export const RECORD_WARNING_CODES = [
   "asset-stale",
   /** A supersedes link from a record whose state is weaker than the one it names, so it has no effect yet (#2524 D4). */
   "record-supersedes-pending",
+  /**
+   * The kind's pins field is an empty list: the record cites no evidence and
+   * pins no file. Information for a reviewer, such as a decision made in a
+   * product's own design flow with nothing to cite (#2654).
+   */
+  "record-no-evidence",
 ] as const satisfies readonly ReasonCode[];
 export type RecordWarningCode = (typeof RECORD_WARNING_CODES)[number];
 
@@ -187,7 +193,7 @@ export interface LoadedRecordKind {
  * The kind is registered under a name no lexicon package can have (npm names
  * hold no `:`), imported and unregistered again, so no lexicon lookup sees it.
  */
-async function importKindModule(path: string): Promise<Record<string, unknown>> {
+export async function importKindModule(path: string): Promise<Record<string, unknown>> {
   const name = `record-kind:${path}`;
   registerLexiconDeclarations([{ name, module: path }], dirname(path));
   try {
@@ -344,22 +350,54 @@ export interface ReadRecordsResult {
 
 type Validator = (data: unknown) => { ok: true } | { ok: false; errors: string[] };
 
+/** One ajv error, compiled with `verbose` so the failing schema and data come with it. */
+interface SchemaError {
+  instancePath: string;
+  schemaPath: string;
+  keyword: string;
+  message?: string;
+  params?: { failingKeyword?: string };
+  parentSchema?: Record<string, unknown>;
+  data?: unknown;
+}
+
+/**
+ * ajv's errors as `<path> <message>` lines. A failed `if` whose `then` or
+ * `else` branch has a `description` is reported by that description alone, in
+ * place of the branch's own errors, with each `{field}` filled from the value
+ * the branch checked. The decision schema words its dissent rule this way, so
+ * the message names the reviewer (#2652). The schema stays plain JSON Schema,
+ * with no keyword a strict validator would refuse.
+ */
+function renderSchemaErrors(errors: readonly SchemaError[]): string[] {
+  const replaced: string[] = [];
+  const described = new Map<SchemaError, string>();
+  for (const e of errors) {
+    const branch = e.keyword === "if" ? e.params?.failingKeyword : undefined;
+    const text = branch ? (e.parentSchema?.[branch] as { description?: unknown } | undefined)?.description : undefined;
+    if (!branch || typeof text !== "string") continue;
+    const at = e.data !== null && typeof e.data === "object" ? (e.data as Record<string, unknown>) : {};
+    described.set(e, text.replace(/\{([A-Za-z0-9_]+)\}/g, (all, key: string) => (typeof at[key] === "string" ? (at[key] as string) : all)));
+    replaced.push(`${e.schemaPath.replace(/\/if$/, "")}/${branch}/`);
+  }
+  return errors
+    .filter((e) => described.has(e) || !replaced.some((prefix) => e.schemaPath.startsWith(prefix)))
+    .map((e) => `${e.instancePath || "/"} ${described.get(e) ?? e.message ?? "is invalid"}`);
+}
+
 async function compileSchema(schema: Record<string, unknown>): Promise<Validator> {
   const mod = (await import("ajv")) as unknown as { default: unknown };
   // ajv is CommonJS; its class is the default export, or that export's own default.
   const Ajv = ((mod.default as { default?: unknown }).default ?? mod.default) as new (opts: object) => {
-    compile(s: object): ((d: unknown) => boolean) & { errors?: Array<{ instancePath: string; message?: string }> | null };
+    compile(s: object): ((d: unknown) => boolean) & { errors?: SchemaError[] | null };
   };
   let validate: ReturnType<InstanceType<typeof Ajv>["compile"]>;
   try {
-    validate = new Ajv({ allErrors: true, strict: false }).compile(schema);
+    validate = new Ajv({ allErrors: true, strict: false, verbose: true }).compile(schema);
   } catch (err) {
     throw new RecordReadError("schema-invalid", `the kind's schema does not compile: ${message(err)}`);
   }
-  return (data) =>
-    validate(data)
-      ? { ok: true }
-      : { ok: false, errors: (validate.errors ?? []).map((e) => `${e.instancePath || "/"} ${e.message ?? "is invalid"}`) };
+  return (data) => (validate(data) ? { ok: true } : { ok: false, errors: renderSchemaErrors(validate.errors ?? []) });
 }
 
 /** Read every record `loaded` locates, through `options.source`. */
@@ -392,10 +430,16 @@ export async function readRecords(loaded: LoadedRecordKind, options: ReadRecords
     if (!result.ok) {
       entry.reasons.push({ code: "record-schema-invalid", message: result.errors.join("; ") });
     }
-    if (kind.pins && options.assets) {
-      const checked = checkPins(pinEntries(fm.value, kind.pins.field), options.assets);
-      entry.assets = checked.assets;
-      entry.warnings = checked.warnings;
+    if (kind.pins) {
+      const cited = fm.value[kind.pins.field];
+      if (Array.isArray(cited) && cited.length === 0) {
+        entry.warnings.push({ code: "record-no-evidence", message: `${kind.pins.field} is empty: the record cites nothing and pins no file` });
+      }
+      if (options.assets) {
+        const checked = checkPins(pinEntries(fm.value, kind.pins.field), options.assets);
+        entry.assets = checked.assets;
+        entry.warnings.push(...checked.warnings);
+      }
     }
   }