@intentius/chant 0.86.0 → 0.87.0

package/src/workspace/intent-gaps.test.ts

@@ -0,0 +1,217 @@
+/**
+ * The two gaps a work item could not name before #2686, a stale pin and an
+ * open dissent, and `work-done-gap-open` on a records read, on a workspace
+ * built in a throwaway git repository:
+ *
+ * - c1 adds the app, the screen spec `design/screens/home.json`, and dec-001,
+ *   which constrains the spec's path and pins it by hash.
+ * - c2 adds dec-002, which supersedes dec-001, constrains the same path and
+ *   pins the spec at the same hash, so its pin is stale; dec-003, which
+ *   constrains `app/server.mjs` and has one open dissent (bob's), one
+ *   withdrawn and one addressed; and the work items:
+ *   W-001 (open, from intent-pin-stale on the spec), W-002 (open, from
+ *   intent-decision-contested on the server), W-003 (done, from
+ *   intent-decision-contested on the server, which still fires), W-004
+ *   (done, from intent-pin-drifted on the spec, which does not fire) and
+ *   W-005 (open, implements dec-002 and dec-003, no gap source).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { sha256Hex } from "../content-digest";
+import { cleanScratch, contract, git, REPO, repo, writeFiles } from "./__fixtures__/contract-repo";
+import { intentGraph, type FindingNode, type IntentDocument, type WorkNode } from "./intent";
+import intentSchema from "./intent.schema.json";
+import { parseFrontMatter } from "./records";
+import { queryRecords } from "./records-cli";
+import recordsSchema from "./records.schema.json";
+
+const REF = join(REPO, "reference-workspace");
+const BASE = (() => {
+  const fm = parseFrontMatter(readFileSync(join(REF, "decisions", "ref-001-how-the-app-is-deployed.md"), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+})();
+
+const HOME = `${JSON.stringify({ route: "/", regions: ["header"] }, null, 2)}\n`;
+const pin = { title: "The home screen spec", path: "design/screens/home.json", sha256: sha256Hex(Buffer.from(HOME)), as_of: "2026-09-24T12:00:00Z" };
+
+function decision(id: string, fields: Record<string, unknown>): string {
+  const data = { ...BASE, id, title: `Decision ${id}`, state: "decided", supersedes: [], evidence: [], reviews: [], ...fields };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+function work(id: string, fields: Record<string, unknown>): string {
+  const data = { schema: 1, id, title: `Work ${id}`, state: "open", implements: [], needs: [], constrains: ["path:app/server.mjs"], evidence: [], opened_on: "2026-09-24", supersedes: [], ...fields };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n\nWhat the work is.\n`;
+}
+
+const done = { state: "done", closed_on: "2026-09-25", evidence: [{ title: "The review", url: "https://example.com/review" }] };
+const KIND_FILES = {
+  "decisions/decision.kind.mjs": readFileSync(join(REF, "decisions", "decision.kind.mjs"), "utf-8"),
+  "decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
+  "work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
+  "work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
+};
+const DECLARATION = JSON.stringify({
+  name: "studio",
+  schema: 1,
+  members: [
+    { name: "app", dir: "app", kind: "other", because: "a plain Node server" },
+    { name: "design", dir: "design", kind: "other", because: "the screen specs" },
+  ],
+});
+
+const DEC_003 = decision("dec-003", {
+  constrains: ["path:app/server.mjs"],
+  reviews: [
+    { reviewer: "Bob", verdict: "dissent", note: "The port is wrong.", on: "2026-09-24" },
+    { reviewer: "carol", verdict: "dissent", note: "Too early.", on: "2026-09-24", withdrawn_on: "2026-09-25" },
+    { reviewer: "dave", verdict: "dissent", note: "Needs a test.", on: "2026-09-24", addressed_by: "acme/studio#7" },
+    { reviewer: "erin", verdict: "agree", on: "2026-09-24" },
+  ],
+});
+
+let root: string;
+
+function commit(message: string): void {
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", message);
+}
+
+beforeAll(() => {
+  root = repo({
+    "chant.workspace.json": DECLARATION,
+    "app/server.mjs": "export const port = 8080;\n",
+    "design/screens/home.json": HOME,
+    ...KIND_FILES,
+    "decisions/dec-001-spec.md": decision("dec-001", { constrains: ["path:design/screens/home.json"], evidence: [pin] }),
+  });
+  commit("the app, the spec and dec-001");
+  writeFiles(root, {
+    "decisions/dec-002-spec-again.md": decision("dec-002", { constrains: ["path:design/screens/home.json"], evidence: [pin], supersedes: [{ decision: "dec-001" }] }),
+    "decisions/dec-003-server.md": DEC_003,
+    "work/W-001-stale.md": work("W-001", { constrains: ["path:design/screens/home.json"], source: { finding: "intent-pin-stale", region: "design/screens/home.json", decision: "dec-002" } }),
+    "work/W-002-contested.md": work("W-002", { source: { finding: "intent-decision-contested", region: "app/server.mjs", decision: "dec-003" } }),
+    "work/W-003-contested-done.md": work("W-003", { ...done, source: { finding: "intent-decision-contested", region: "app/server.mjs", decision: "dec-003" } }),
+    "work/W-004-drift-done.md": work("W-004", { ...done, constrains: ["path:design/screens/home.json"], source: { finding: "intent-pin-drifted", region: "design/screens/home.json" } }),
+    "work/W-005-carry-out.md": work("W-005", { implements: ["dec-002", "dec-003"] }),
+  });
+  commit("dec-002 supersedes dec-001, dec-003 is contested, and the work");
+});
+afterAll(cleanScratch);
+
+const intent = contract(intentSchema);
+const records = contract(recordsSchema);
+type Result = Exclude<IntentDocument, { error: unknown }>;
+
+async function walk(region: string): Promise<Result> {
+  const { doc } = await intentGraph({ cwd: root, region, kinds: ["decisions/decision.kind.mjs", "work/work.kind.mjs"].map((k) => join(root, k)) });
+  intent.expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+const findingsOf = (doc: Result, code: string) => doc.nodes.filter((n): n is FindingNode => n.kind === "finding" && n.code === code);
+
+describe("intent-pin-stale (#2686)", () => {
+  test("a current decision pinning the artifact at the hash the record it supersedes pinned is stale, beside drifted and missing", async () => {
+    const doc = await walk("design/screens/home.json");
+    expect(doc.nodes.find((n) => n.id === "artifact:design/screens/home.json")).toMatchObject({ pinState: "stale" });
+    const stale = findingsOf(doc, "intent-pin-stale");
+    expect(stale).toHaveLength(1);
+    expect(stale[0].concerns).toEqual(["record:decision/dec-002", "artifact:design/screens/home.json", "record:decision/dec-001"]);
+    expect(stale[0].message).toContain("dec-001");
+    expect(findingsOf(doc, "intent-pin-drifted")).toEqual([]);
+    expect(findingsOf(doc, "intent-pin-missing")).toEqual([]);
+  });
+
+  test("it is addressed by the item that came from it and by the item implementing the decision", async () => {
+    const doc = await walk("design/screens/home.json");
+    const [stale] = findingsOf(doc, "intent-pin-stale");
+    expect(stale).toMatchObject({ addressed: true, addressedBy: [{ id: "W-001", state: "open" }, { id: "W-005", state: "open" }] });
+    expect(doc.edges).toContainEqual({ kind: "addressed-by", from: stale.id, to: "record:work/W-001" });
+    expect(doc.edges).toContainEqual({ kind: "addressed-by", from: stale.id, to: "record:work/W-005" });
+  });
+
+  test("a stale pin on a decision in the graph only through supersession is not raised", async () => {
+    // app/server.mjs brings in no decision pinning the spec.
+    const doc = await walk("app/server.mjs");
+    expect(findingsOf(doc, "intent-pin-stale")).toEqual([]);
+  });
+});
+
+describe("intent-decision-contested (#2686)", () => {
+  test("a current decision constraining the region with a dissent neither addressed nor withdrawn is contested, with the count and principals", async () => {
+    const doc = await walk("app/server.mjs");
+    const contested = findingsOf(doc, "intent-decision-contested");
+    expect(contested).toHaveLength(1);
+    expect(contested[0]).toMatchObject({ concerns: ["record:decision/dec-003", "region:app/server.mjs"], openConcerns: { count: 1, principals: ["bob"] } });
+    expect(contested[0].message).toContain("1 open concern, from Bob");
+  });
+
+  test("it is addressed by the items that came from it, and not through implements", async () => {
+    const doc = await walk("app/server.mjs");
+    const [contested] = findingsOf(doc, "intent-decision-contested");
+    expect(contested.addressedBy).toEqual([
+      { id: "W-002", state: "open" },
+      { id: "W-003", state: "done" },
+    ]);
+    expect(doc.edges).toContainEqual({ kind: "addressed-by", from: contested.id, to: "record:work/W-002" });
+    const w003 = doc.nodes.find((n): n is WorkNode => n.kind === "work" && n.record === "W-003");
+    expect(w003!.warnings.map((w) => w.code)).toEqual(["work-done-gap-open"]);
+  });
+
+  test("a decision whose dissents are all addressed or withdrawn is not contested", async () => {
+    writeFiles(root, { "decisions/dec-003-server.md": DEC_003.replace(`"note": "The port is wrong.",`, `"note": "The port is wrong.", "addressed_by": "acme/studio#8",`) });
+    try {
+      const doc = await walk("app/server.mjs");
+      expect(findingsOf(doc, "intent-decision-contested")).toEqual([]);
+    } finally {
+      writeFiles(root, { "decisions/dec-003-server.md": DEC_003 });
+    }
+  });
+});
+
+describe("work-done-gap-open in records (#2686)", () => {
+  test("records --json warns on a done item whose gap still fires, and not on one whose gap closed", async () => {
+    const doc = await queryRecords({ kind: "work/work.kind.mjs", cwd: root });
+    records.expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    const warned = Object.fromEntries(doc.records.map((r) => [r.id, r.warnings.map((w) => w.code)]));
+    expect(warned).toEqual({ "W-001": [], "W-002": [], "W-003": ["work-done-gap-open"], "W-004": [], "W-005": [] });
+    expect(doc.records.find((r) => r.id === "W-003")!.warnings[0].message).toContain("intent-decision-contested");
+  });
+
+  test("the warning follows the revision read: under --at c1 there is no work, and under --at HEAD W-003 is warned", async () => {
+    const c1 = git(root, "rev-parse", "HEAD~1");
+    const doc = await queryRecords({ kind: "work/work.kind.mjs", cwd: root, at: c1 });
+    records.expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.records).toEqual([]);
+    const head = await queryRecords({ kind: "work/work.kind.mjs", cwd: root, at: "HEAD" });
+    if ("error" in head) throw new Error(head.error.message);
+    expect(head.records.find((r) => r.id === "W-003")!.warnings.map((w) => w.code)).toEqual(["work-done-gap-open"]);
+  });
+
+  test("without a workspace declaration the walk can't be made, so the record is left as it was", async () => {
+    const bare = repo({
+      "app/server.mjs": "export const port = 8080;\n",
+      ...KIND_FILES,
+      "decisions/dec-003-server.md": DEC_003,
+      "work/W-003-contested-done.md": work("W-003", { ...done, source: { finding: "intent-decision-contested", region: "app/server.mjs" } }),
+    });
+    git(bare, "add", "-A");
+    git(bare, "commit", "-q", "-m", "one");
+    const doc = await queryRecords({ kind: "work/work.kind.mjs", cwd: bare });
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.records[0].warnings).toEqual([]);
+  });
+
+  test("the intent graph reads its kinds without asking records for the warning, so it is raised once", async () => {
+    const doc = await walk("app/server.mjs");
+    const w003 = doc.nodes.find((n): n is WorkNode => n.kind === "work" && n.record === "W-003");
+    expect(w003!.warnings.filter((w) => w.code === "work-done-gap-open")).toHaveLength(1);
+  });
+});

package/src/workspace/intent.schema.json

@@ -924,7 +924,7 @@
         },
         "warnings": {
           "type": "array",
-          "description": "The item's work warnings as records reports them, and work-done-gap-open, which only this walk raises: the item is done and the finding in its source still fires on its region.",
+          "description": "The item's work warnings as records reports them, and work-done-gap-open: the item is done and the finding in its source still fires on its region. records raises it too, by walking the source's region with this code (#2686).",
           "items": {
             "type": "object",
             "required": [
@@ -1088,9 +1088,11 @@
                 "intent-commit-bare",
                 "intent-pin-drifted",
                 "intent-pin-missing",
+                "intent-pin-stale",
                 "intent-artifact-unpinned",
                 "intent-decision-superseded-live",
                 "intent-decision-provisional",
+                "intent-decision-contested",
                 "intent-constraint-coarse",
                 "intent-constraint-lost",
                 "intent-evidence-unpinned",
@@ -1129,6 +1131,26 @@
           },
           "description": "For a plugin's finding: the refs as the plugin gave them. Those that name a node in the graph are resolved to its id in concerns, after the commit the finding was returned for."
         },
+        "openConcerns": {
+          "type": "object",
+          "description": "Added by #2686, on intent-decision-contested only: how many open concerns the decision's quorum reports, dissents neither addressed nor withdrawn, and the principals who raised them, normalised as the quorum compares them.",
+          "required": [
+            "count",
+            "principals"
+          ],
+          "properties": {
+            "count": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "principals": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
         "addressed": {
           "type": "boolean",
           "description": "Added by #2683, present when a work kind was read: whether a work item addresses the finding, because the item's source names this finding code on a region that contains or is contained by this one, or because the item implements a decision the finding concerns. A finding with addressed false is work nobody has taken yet."

package/src/workspace/intent.test.ts

@@ -443,6 +443,8 @@ describe("findings the fixture does not raise (#2651)", () => {
         expect(findings(doc).map(([c]) => c)).toEqual([
           "intent-commit-undecided",
           "intent-commit-bare",
+          // dec-002 supersedes dec-001 and pins the spec at the hash dec-001 pinned, unchanged since (#2686).
+          "intent-pin-stale",
           "intent-decision-provisional",
           "intent-constraint-coarse",
           "intent-constraint-lost",

package/src/workspace/intent.ts

@@ -71,12 +71,16 @@ export const INTENT_FINDING_CODES = [
   "intent-pin-drifted",
   /** A pinned artifact does not exist in the tree read. */
   "intent-pin-missing",
+  /** A current decision's pin is unchanged at the hash a record it supersedes pinned: the decision moved on and the artifact did not (#2686). */
+  "intent-pin-stale",
   /** An artifact that decisions in the graph pinned, and that no current decision pins. */
   "intent-artifact-unpinned",
   /** Every decision constraining the region is superseded. */
   "intent-decision-superseded-live",
   /** The current decisions constraining the region are all in states their kind does not close, such as decided and not ratified. */
   "intent-decision-provisional",
+  /** A current decision constraining the region has an open concern: a dissent neither addressed nor withdrawn (#2686). */
+  "intent-decision-contested",
   /** The region is constrained only at member granularity. */
   "intent-constraint-coarse",
   /** A decision's path constraint names a path that does not exist. */
@@ -269,6 +273,8 @@ export interface FindingNode {
   plugin?: string;
   /** For a plugin's finding: the refs as the plugin gave them. The ones that name a node in the graph are in concerns. */
   refs?: string[];
+  /** For intent-decision-contested (#2686): how many open concerns the decision has, and whose, as its quorum reports them. */
+  openConcerns?: { count: number; principals: string[] };
   /** With a work kind read (#2683): whether a work item addresses the finding. */
   addressed?: boolean;
   /** With a work kind read: the work items addressing the finding, each with its state. */
@@ -618,7 +624,7 @@ async function loadKinds(query: IntentQuery, top: string): Promise<LoadedKind[]>
     if (typeof joins === "string") throw new IntentError("kind-invalid", `kind file ${k} has a commitJoins export that can't be read: ${joins}`);
     const kind: LoadedKind = { file, display, name: joins?.name ?? basename(file).replace(/(?:\.kind)?\.[cm]?[jt]s$/, ""), ...(joins ? { joins } : {}) };
     if (mod.recordKind !== undefined) {
-      const doc = await queryRecords({ kind: file, at: query.at, cwd: query.cwd });
+      const doc = await queryRecords({ kind: file, at: query.at, cwd: query.cwd, workGaps: false });
       if ("error" in doc) throw new IntentError(doc.error.code, doc.error.message);
       try {
         kind.records = { loaded: await loadRecordKind(file), views: doc.records, workspaceRoot: doc.workspaceRoot };
@@ -951,6 +957,18 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
       edges.push({ kind: "pins", from: p.decision.id, to: aid, pinnedSha256: p.sha256, pinState: p.state });
       if (p.state === "drifted") find("intent-pin-drifted", `${path} changed after ${p.decision.record} pinned it: sha256 ${p.sha256?.slice(0, 12)} is pinned, the file hashes to ${p.actual?.slice(0, 12)}`, [p.decision.id, aid]);
       if (p.state === "missing") find("intent-pin-missing", `${p.decision.record} pins ${path}, which does not exist${located.tree.label}`, [p.decision.id, aid]);
+      // Stale against a current decision constraining the region (#2686): the
+      // record it supersedes pinned the same hash, and the file has not
+      // changed since. A decision in the graph only through supersession
+      // does not govern the region, so its stale pin is not raised here.
+      if (p.state === "stale" && p.decision.supersededBy === null && p.decision.constrains.length > 0) {
+        const old = pins.find((o) => o.decision.supersededBy === p.decision.record && o.decision.recordKind === p.decision.recordKind && o.sha256 === p.sha256);
+        find(
+          "intent-pin-stale",
+          `${path} is pinned by ${p.decision.record} at sha256 ${p.sha256?.slice(0, 12)}, the hash ${old ? old.decision.record : "the record it supersedes"} pinned, and it has not changed since: the decision moved on and the artifact did not`,
+          [p.decision.id, aid, ...(old ? [old.decision.id] : [])],
+        );
+      }
     }
     if (!worst && pins.some((p) => p.state !== "unpinned")) {
       find("intent-artifact-unpinned", `${path} was pinned by ${[...new Set(pins.map((p) => p.decision.record))].join(", ")}, and no current decision pins it`, [aid, ...new Set(pins.map((p) => p.decision.id))]);
@@ -1143,6 +1161,20 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     } else if (current.every((c) => !c.node.closed)) {
       find("intent-decision-provisional", `the decisions constraining ${region.path} are ${[...new Set(current.map((c) => c.node.state ?? "stateless"))].join(" or ")}, and none is in a closed state`, [rid, ...current.map((c) => c.node.id)]);
     }
+    // A current decision with a dissent nobody addressed or withdrew (#2686), from its quorum.
+    for (const c of current) {
+      const open = c.view.quorum?.openConcerns ?? [];
+      if (open.length === 0) continue;
+      const principals = [...new Set(open.map((o) => o.principal))];
+      findings.push({
+        id: `finding:intent-decision-contested:${findings.filter((f) => f.code === "intent-decision-contested").length + 1}`,
+        kind: "finding",
+        code: "intent-decision-contested",
+        message: `${c.node.record} constrains ${region.path} and has ${open.length} open ${open.length === 1 ? "concern" : "concerns"}, from ${open.map((o) => o.reviewer).join(", ")}: a dissent neither addressed nor withdrawn`,
+        concerns: [c.node.id, rid],
+        openConcerns: { count: open.length, principals },
+      });
+    }
     const granularities = new Set(covering.flatMap((c) => c.node.constrains.map((x) => x.granularity)));
     if (covering.length > 0 && !granularities.has("path") && granularities.has("member")) {
       find("intent-constraint-coarse", `${region.path} is constrained only through its member, ${member}`, [rid, ...covering.map((c) => c.node.id)]);
@@ -1222,7 +1254,7 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     findings.push({ id: `finding:${code}:${findings.filter((f) => f.code === code).length + 1}`, kind: "finding", code, message: finding.message, concerns, plugin, refs });
   }
   // A finding a work item addresses (#2683): the item came from that gap on
-  // this region, or it implements the decision a drifted or missing pin, or a
+  // this region, or it implements the decision a drifted, missing or stale pin, or a
   // plugin's finding, is about. A done item whose gap still fires here gets
   // work-done-gap-open.
   if (readsWork) {
@@ -1230,7 +1262,7 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     // artifacts, not gaps in the decision record itself (its review, its
     // granularity, its evidence), so only these findings, and a plugin's,
     // count as addressed through implements.
-    const CLOSED_BY_IMPLEMENTING = new Set<string>(["intent-pin-drifted", "intent-pin-missing"]);
+    const CLOSED_BY_IMPLEMENTING = new Set<string>(["intent-pin-drifted", "intent-pin-missing", "intent-pin-stale"]);
     const fromGap = (h: WorkHit, code: string): boolean => {
       const src = gapSource(h.view.data);
       if (src === null || src.finding !== code) return false;

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

@@ -19,7 +19,7 @@ import { GROUP_REASON_CODES, MEMBER_REASON_CODES } from "./ls";
 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, REVIEW_REASON_CODES } from "./records";
+import { READ_ERROR_CODES, RECORD_REASON_CODES, RECORD_WARNING_CODES, REVIEW_REASON_CODES, SEAL_REASON_CODES } from "./records";
 import { AMEND_ERROR_CODES, NEW_ERROR_CODES, REVIEW_ERROR_CODES } from "./records-write";
 import { RECORDS_SINCE_ERROR_CODES } from "./records-since";
 import { STATUS_ERROR_CODES, STATUS_GATE_REASON_CODES, STATUS_REASON_CODES } from "./status";
@@ -41,6 +41,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   RECORD_REASON_CODES,
   RECORD_WARNING_CODES,
   REVIEW_REASON_CODES,
+  SEAL_REASON_CODES,
   WORK_WARNING_CODES,
   READ_ERROR_CODES,
   NEW_ERROR_CODES,

package/src/workspace/reason-codes.ts

@@ -80,13 +80,18 @@ export const REASONS = {
   "work-implements-undecided": "A work record implements a decision whose state is not approved, such as proposed.",
   "work-done-unpinned": "A work record is done and its evidence list is empty: nothing shows the work was done.",
   "work-closed-without-date": "A work record is done or dropped and has no closing date.",
-  "work-done-gap-open": "A work record is done, and the finding it came from still fires on its region. Only graph --intent raises it.",
+  "work-done-gap-open": "A work record is done, and the finding it came from still fires on its region. graph --intent raises it, and records does by walking that region.",
   // A verdict the quorum does not count (records, #2671, #2672).
   "review-decider": "The verdict is the decider's own, and the quorum counts verdicts besides the decider's.",
   "review-agent": "The reviewer holds the agent role in the trust policy at base.",
   "review-duplicate": "A later verdict by the same principal replaces this one. Names are compared after NFKC, trimming and lower-casing.",
   "review-older-digest": "The verdict names a digest other than the record's text now: the record changed after the verdict.",
-  "review-unattested": "An attestation policy is active at base, and the verdict carries no seal.",
+  "review-unattested": "An attestation policy is active at base, and the verdict carries no seal that verifies for its reviewer.",
+  // A verdict's seal that is not attested (records, #2687). Every verdict reports one of these in its attestation, unless its seal verified.
+  "seal-missing": "The verdict carries no seal.",
+  "seal-signer-unlisted": "The reviewer has no key in the signers file at base, so the seal can't count.",
+  "seal-signature-invalid": "The seal is malformed, names a signer other than the reviewer, or its signature does not verify over the verdict.",
+  "seal-unverifiable": "Nothing here can say whose seal it is: there is no signers file at base, or ssh-keygen is not installed.",
   // 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.",
@@ -106,6 +111,7 @@ export const REASONS = {
   "amend-supersede-instead": "The record is approved, and the amendment changes a field the approval rule does not let change in place; a new record supersedes it instead.",
   "review-unsupported": "The kind's schema has no reviews field, so its records take no review.",
   "review-note-required": "A dissent was given with no note: a dissent needs a reason.",
+  "review-sign-failed": "--sign was given and no seal could be made: the key can't be read or used, git names no ssh signing key, or ssh-keygen is not installed.",
   // records --since that fails (#2673).
   "since-rev-unknown": "--since names no commit.",
   // The intent graph (graph --intent, #2651): a read that fails.
@@ -118,9 +124,11 @@ export const REASONS = {
   "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-pin-stale": "A current decision pins an artifact at the hash a record it supersedes pinned, and the artifact has not changed since: the decision moved on and the artifact did not.",
   "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-decision-contested": "A current decision constraining the region has an open concern: a dissent neither addressed nor withdrawn.",
   "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.",

package/src/workspace/record-assets.test.ts

@@ -169,8 +169,8 @@ describe("chant workspace records checks each pin", () => {
   });
 
   test("the schema lists exactly the warning codes", () => {
-    // A work kind's records carry the work warnings too, except work-done-gap-open, which only graph --intent raises (#2683).
-    expect(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES.filter((c) => c !== "work-done-gap-open")]);
+    // A work kind's records carry the work warnings too (#2683), work-done-gap-open included since records walks a done item's region (#2686).
+    expect(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES]);
   });
 
   test("records pin <path> prints the entry's path from the workspace root and the file's hash", () => {

package/src/workspace/records-cli.ts

@@ -42,6 +42,7 @@ import {
   type RecordEntry,
   type RecordFormat,
   type RecordHistory,
+  type SealInput,
 } from "./records";
 import { gitTree, workingTree, type WorkspaceTree } from "./tree";
 import type { DecisionWork } from "./work";
@@ -68,6 +69,12 @@ export interface RecordsQuery {
   base?: string;
   /** Where `kind` is resolved from and the repository is found. */
   cwd: string;
+  /**
+   * For a work kind: walk the region of each done item's `source` and raise
+   * `work-done-gap-open` when its finding still fires (#2686). On unless
+   * false; the intent graph passes false, since it raises the warning itself.
+   */
+  workGaps?: boolean;
 }
 
 /**
@@ -266,15 +273,24 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       paths: result.records.map((r) => r.path),
       attestors: policy.active ? await activeAttestors() : [],
     });
-    // The quorum: the need from the declaration in the tree read, agents and
-    // whether verdicts need a seal from the policy at base (#2671).
-    const quorumOptions = loaded.kind.reviews
+    // The quorum: the need from the declaration in the tree read, agents,
+    // whether verdicts need a seal, and the keys a seal verifies against,
+    // all from the policy at base (#2671, #2687).
+    const checkVerdictSeal = loaded.kind.reviews ? (await import("./trust/seal")).checkVerdictSeal : undefined;
+    const quorumOptions = checkVerdictSeal
       ? {
           ...declaredQuorum(tree),
           agents: new Set((policy.roles[AGENT_ROLE] ?? []).map(normalisePrincipal)),
           attestation: policy.active,
+          verifySeal: (v: SealInput) => checkVerdictSeal(policy, v),
         }
       : undefined;
+    const records: RecordView[] = result.records.map((r) => ({
+      ...r,
+      provenance: provenance.get(r.path)!,
+      ...(quorumOptions ? { quorum: computeQuorum(loaded.kind, r, quorumOptions) } : {}),
+    }));
+    if (loaded.kind.work && query.workGaps !== false && top) await raiseWorkGaps(loaded, records, { root, workspaceRoot, at: query.at });
     return {
       $schema: RECORDS_OUTPUT_SCHEMA_ID,
       contract: RECORDS_CONTRACT_VERSION,
@@ -288,11 +304,7 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       workspaceRoot,
       current: !!query.current,
       trust: { base: base.commit, baseFrom: base.from, active: policy.active, signersPath: policy.signersPath, problems: policy.problems },
-      records: result.records.map((r) => ({
-        ...r,
-        provenance: provenance.get(r.path)!,
-        ...(quorumOptions ? { quorum: computeQuorum(loaded.kind, r, quorumOptions) } : {}),
-      })),
+      records,
       summary: result.summary,
       ...(result.decisions ? { decisions: result.decisions } : {}),
     };
@@ -302,6 +314,56 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
   }
 }
 
+/**
+ * `work-done-gap-open` on a records read (#2686): for each done work record
+ * whose `source` names a finding and a region, walk that region with the
+ * intent graph, at the same revision, and copy the warning the walk raises
+ * on the record. One walk per region, and only a region some done item names.
+ * The walk reads the record kinds the declaration names, and the work kind
+ * and its decision kind if it names neither. It needs git and a workspace
+ * declaration; when the walk can't be made, for one without them or a region
+ * that no longer exists, the record is left as it was.
+ */
+async function raiseWorkGaps(loaded: LoadedRecordKind, records: RecordView[], opts: { root: string; workspaceRoot: string; at: string | undefined }): Promise<void> {
+  const work = loaded.kind.work!;
+  const byRegion = new Map<string, RecordView[]>();
+  for (const r of records) {
+    if (r.id === null || r.state !== work.done) continue;
+    const src = r.data?.source;
+    if (src === null || typeof src !== "object" || Array.isArray(src)) continue;
+    const { finding, region } = src as Record<string, unknown>;
+    if (typeof finding !== "string" || typeof region !== "string") continue;
+    byRegion.set(region, [...(byRegion.get(region) ?? []), r]);
+  }
+  if (byRegion.size === 0) return;
+  const cwd = opts.workspaceRoot === "." ? opts.root : join(opts.root, ...opts.workspaceRoot.split("/"));
+  let declared: string[];
+  try {
+    declared = declaredKindFiles(cwd, opts.at).map((k) => k.file);
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) return;
+    throw err;
+  }
+  const kinds: string[] = [];
+  const seen = new Set<string>();
+  for (const file of [...declared, resolve(dirname(loaded.file), work.decisions), loaded.file]) {
+    const real = realpathOr(file);
+    if (seen.has(real)) continue;
+    seen.add(real);
+    kinds.push(file);
+  }
+  const { intentGraph } = await import("./intent");
+  for (const [region, items] of byRegion) {
+    const { doc } = await intentGraph({ cwd, region, at: opts.at, kinds });
+    if ("error" in doc) continue;
+    for (const r of items) {
+      const node = doc.nodes.find((n) => n.kind === "work" && n.id === `record:${loaded.kind.name}/${r.id}`);
+      const warning = node?.kind === "work" ? node.warnings.find((w) => w.code === "work-done-gap-open") : undefined;
+      if (warning && !r.warnings.some((w) => w.code === warning.code)) r.warnings.push(warning);
+    }
+  }
+}
+
 /**
  * `chant workspace records pin <path>`: the `{path, sha256}` a decision's
  * evidence entry holds for a file, with the path from the workspace root

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

@@ -148,8 +148,8 @@ describe("records output schema", () => {
   });
 
   test("lists exactly the warning codes the code can return", () => {
-    // A work kind's records carry the work warnings too, except work-done-gap-open, which only graph --intent raises (#2683).
-    expect(schema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES.filter((c) => c !== "work-done-gap-open")]);
+    // A work kind's records carry the work warnings too (#2683), work-done-gap-open included since records walks a done item's region (#2686).
+    expect(schema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES]);
   });
 
   test("every failure validates with its code", async () => {

package/src/workspace/records-review.schema.json

@@ -75,7 +75,7 @@
             "reviewer": {
               "type": "string",
               "minLength": 1,
-              "description": "The principal given with --by, as given. chant does not check who it is; attestation of the commit that carries the review does (#2547)."
+              "description": "The principal given with --by, as given. The write does not check who it is. With --sign, the seal lets chant workspace records check it against the signers file at base (#2687)."
             },
             "verdict": {
               "enum": [
@@ -102,6 +102,30 @@
               "type": "string",
               "minLength": 1,
               "description": "The session given with --session. Absent when none was given."
+            },
+            "seal": {
+              "type": "object",
+              "description": "Added in contract 1 by #2687. With --sign only: an ssh signature by the key given (or git's user.signingkey) over <id>\\n<digest>\\n<verdict>\\n<reviewer>\\n<on>, in the ssh-keygen namespace chant-review. The write does not check the key against the signers file; chant workspace records reports whether the seal counts.",
+              "required": [
+                "signer",
+                "key",
+                "signature"
+              ],
+              "properties": {
+                "signer": {
+                  "type": "string",
+                  "description": "The reviewer given with --by."
+                },
+                "key": {
+                  "type": "string",
+                  "pattern": "^SHA256:[A-Za-z0-9+/]+=*$",
+                  "description": "The fingerprint of the key that signed, read back from the signature."
+                },
+                "signature": {
+                  "type": "string",
+                  "description": "The armored ssh signature."
+                }
+              }
             }
           }
         },
@@ -180,6 +204,7 @@
                 "review-unsupported",
                 "record-closed",
                 "review-note-required",
+                "review-sign-failed",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",