@intentius/chant 0.86.0 → 0.88.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/read-contract.test.ts

@@ -160,6 +160,9 @@ describe("every schema against the reference workspace (#2543)", () => {
         // #2674: the reference config's lexicons host no component runs, so local is the only runtime, read at HEAD too.
         expect(doc.components[0].runtimes).toEqual([{ name: "local", lexicon: null, default: true, command: "chant run --components app" }]);
         expect(doc.members.find((m) => m.name === "delivery")!.runtimeReasons).toEqual([]);
+        // #2695: the reference config declares no environments, so the app deploys to local only.
+        expect(doc.components[0].environments).toEqual([{ name: "local", default: true, source: "builtin", command: "chant run --components app" }]);
+        expect(doc.members.find((m) => m.name === "delivery")!.environmentReasons.map((r) => r.code)).toEqual(["environments-none-declared"]);
         expect(doc.reasons).toEqual([]);
       }
     },

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

@@ -10,7 +10,7 @@ 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, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
+import { COMPOSITES_ENVIRONMENT_REASON_CODES, COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_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";
@@ -19,9 +19,10 @@ 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, SEAL_WARNING_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 { CLOSE_ERROR_CODES } from "./records-close";
+import { RECORDS_SINCE_ERROR_CODES, RECORDS_SINCE_REASON_CODES } from "./records-since";
 import { STATUS_ERROR_CODES, STATUS_GATE_REASON_CODES, STATUS_REASON_CODES } from "./status";
 import { WORK_WARNING_CODES } from "./work";
 
@@ -41,18 +42,23 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   RECORD_REASON_CODES,
   RECORD_WARNING_CODES,
   REVIEW_REASON_CODES,
+  SEAL_REASON_CODES,
+  SEAL_WARNING_CODES,
   WORK_WARNING_CODES,
   READ_ERROR_CODES,
   NEW_ERROR_CODES,
   AMEND_ERROR_CODES,
   REVIEW_ERROR_CODES,
+  CLOSE_ERROR_CODES,
   RECORDS_SINCE_ERROR_CODES,
+  RECORDS_SINCE_REASON_CODES,
   INTENT_ERROR_CODES,
   INTENT_FINDING_CODES,
   INTENT_REASON_CODES,
   COMPOSITES_ERROR_CODES,
   COMPOSITES_REASON_CODES,
   COMPOSITES_RUNTIME_REASON_CODES,
+  COMPOSITES_ENVIRONMENT_REASON_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */

package/src/workspace/reason-codes.ts

@@ -80,13 +80,20 @@ 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 seal that is not attested (records): a verdict's (#2687) or a record's author seal (#2688). Each reports one of these in its attestation, unless its seal verified.
+  "seal-missing": "The verdict, or the record, carries no seal.",
+  "seal-signer-unlisted": "The reviewer, or the record's author, 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 author, or its signature does not verify over the verdict or record.",
+  "seal-unverifiable": "Nothing here can say whose seal it is: there is no signers file at base, or ssh-keygen is not installed.",
+  // A record whose author seal is not attested under a signers file at base (records, #2688). A warning: the record is still read.
+  "record-unattested": "A signers file is active at base, and the record names an author whose seal does not verify: it has none, the author has no key in the file, or the signature fails.",
   // 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,8 +113,15 @@ 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.",
+  "record-sign-failed": "--sign was given and no author seal could be made: the record names no author, the key can't be read or used, git names no ssh signing key, or ssh-keygen is not installed.",
+  // A review given in a session (records review --session, #2693).
+  "session-unknown": "--session names no session of a session kind whose subjects are the record's kind.",
+  "session-not-open": "--session names a session in a closed state, which takes no more verdicts.",
   // records --since that fails (#2673).
-  "since-rev-unknown": "--since names no commit.",
+  "since-rev-unknown": "--since names no commit, or a session with no opening revision and no commit that added it.",
+  "since-session-unknown": "--since has the shape of a session id and names no commit, and no session the kind or the declaration reads has that id.",
+  "since-session-open": "--since names a session that is still open, so the comparison runs to the working tree.",
   // 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.
@@ -118,9 +132,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.",
@@ -134,8 +150,12 @@ export const REASONS = {
   "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 runtimes a member's components can deploy on (graph --composites, #2674).
-  "runtimes-config-unreadable": "The member's chant.config.ts could not be read, so only the built-in local runtime is listed.",
+  "runtimes-config-unreadable": "The member's chant.config.ts could not be read, so only the built-in local runtime is listed, and no environment from the config.",
   "runtimes-lexicon-unreadable": "A lexicon the member's config lists could not be loaded, so it is not listed as a runtime.",
+  // The environments a member's components may deploy to (graph --composites, #2695).
+  "environments-none-declared": "The member's chant.config.ts declares no environments, so only local and the environments in its ledger are listed.",
+  "environments-ledger-undeclared": "The member's ledger has releases in an environment its config's environments don't cover, so chant run --env would refuse it and it is not listed.",
+  "environments-ledger-unreadable": "The chant/lifecycle branch exists and the member's ledger environments could not be listed.",
   // 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.",

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

@@ -16,7 +16,7 @@ import { cleanScratch, commitAll, contract, declaration, repo, REPO } from "./__
 import { runChecks } from "./lineage-check";
 import { constraintCovers, isWorkspacePath, memberHolding, WORKSPACE_PATH_PATTERN } from "./record-assets";
 import { pinFile, queryRecords, type RecordsDocument } from "./records-cli";
-import { parseFrontMatter, RECORD_WARNING_CODES } from "./records";
+import { parseFrontMatter, RECORD_WARNING_CODES, SEAL_WARNING_CODES } from "./records";
 import { WORK_WARNING_CODES } from "./work";
 import { workspaceGraph } from "./graph-cli";
 import graphSchema from "./graph.schema.json";
@@ -169,8 +169,9 @@ 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),
+    // and records adds record-unattested for an author seal under a signers file at base (#2688).
+    expect(recordsSchema.$defs.warning.properties.code.enum).toEqual([...RECORD_WARNING_CODES, ...WORK_WARNING_CODES, ...SEAL_WARNING_CODES]);
   });
 
   test("records pin <path> prints the entry's path from the workspace root and the file's hash", () => {

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

@@ -67,7 +67,35 @@
           "items": {
             "type": "string"
           },
-          "description": "The top-level fields whose value differs from the record as it was, in the record's order. Empty when the fields set change nothing, and then nothing is written."
+          "description": "The top-level fields whose value differs from the record as it was, in the record's order, with seal last when the author seal was written or removed (#2688). Empty when the fields set change nothing, and then nothing is written."
+        },
+        "seal": {
+          "type": "object",
+          "description": "Added in contract 1 by #2688. With --sign only: the author seal written into the record's top-level seal field, an ssh signature by the key given (or git's user.signingkey) over <id>\\n<digest>\\n<author>\\n<state>, in the ssh-keygen namespace chant-record. The author is the kind's reviews.decider field (decided_by for decisions), and the digest is the record's digest by the digest rule, which leaves the seal field out. The write does not check the key against the signers file; chant workspace records reports whether the seal verifies.",
+          "required": [
+            "signer",
+            "key",
+            "signature"
+          ],
+          "properties": {
+            "signer": {
+              "type": "string",
+              "description": "The record's author, as its reviews.decider field names them."
+            },
+            "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."
+            }
+          }
+        },
+        "sealDropped": {
+          "type": "string",
+          "description": "Added in contract 1 by #2688. Present when the record carried an author seal, the amendment moved its digest and --sign was not given: the seal no longer covers the text, so it was removed, and this says so. changed then lists seal."
         },
         "dryRun": {
           "type": "boolean",
@@ -145,6 +173,7 @@
                 "amend-id-immutable",
                 "record-closed",
                 "amend-supersede-instead",
+                "record-sign-failed",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",