@intentius/chant 0.85.0 → 0.86.0

package/src/workspace/intent-cli.ts

@@ -5,13 +5,14 @@
  * section B: the region, its decisions, their artifacts, the commits, and the
  * findings. Under each decision come the commits made inside its window, and
  * when any of them is not the decision's own work, the question #2650 B puts
- * to the person about it (#2656).
+ * to the person about it (#2656). Without `--kind`, the walk reads every
+ * record kind the declaration names (#2680).
  */
 
 import { resolve } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
-import { intentGraph, type ArtifactNode, type CommitNode, type DecisionNode, type IntentDocument, type IntentEdge, type IntentNode } from "./intent";
+import { intentGraph, type ArtifactNode, type CommitNode, type DecisionNode, type IntentDocument, type IntentEdge, type IntentNode, type WorkNode } from "./intent";
 
 const USAGE = "chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]";
 
@@ -57,6 +58,22 @@ function decisionLine(d: DecisionNode): string {
   return `decision  ${d.record} ${d.state ?? "stateless"}${superseded}: ${d.title ?? d.path}; constrains ${via}${by}; ${reviews}; ${d.provenance.level}${d.valid ? "" : `; invalid: ${d.reasons.map((r) => r.code).join(", ")}`}`;
 }
 
+/** A work item, then the commits made inside its window (#2683). */
+function workLines(doc: Result, w: WorkNode): string[] {
+  const via = w.constrains.length > 0 ? w.constrains.map((c) => `${c.entry} (${c.granularity})`).join(", ") : "through a link only";
+  const implemented = w.implements.length > 0 ? `; implements ${w.implements.map((d) => `${d.id} (${d.state ?? "unknown"})`).join(", ")}` : "";
+  const readiness = w.ready ? "; ready" : w.blockedBy.length > 0 ? `; blocked by ${w.blockedBy.map((b) => `${b.id} (${b.state ?? "unknown"})`).join(", ")}` : "";
+  const owner = w.owner ? `, owned by ${w.owner}` : "";
+  const from = w.source ? `; from ${w.source.finding} on ${w.source.region}` : "";
+  const out = [`work      ${w.record} ${w.state ?? "stateless"}${owner}: ${w.title ?? w.path}; constrains ${via}${implemented}${readiness}${from}`];
+  for (const e of doc.edges.filter((x) => x.kind === "within" && x.to === w.id)) {
+    const c = doc.nodes.find((n): n is CommitNode => n.kind === "commit" && n.id === e.from);
+    if (c) out.push(`  worked    ${short(c.sha)} ${c.subject}; in ${w.record}'s window`);
+  }
+  for (const x of w.warnings) out.push(`  warning   ${x.code}: ${x.message}`);
+  return out;
+}
+
 function artifactLine(doc: Result, a: ArtifactNode): string {
   const by = doc.edges
     .filter((e): e is Extract<IntentEdge, { kind: "pins" }> => e.kind === "pins" && e.to === a.id)
@@ -88,16 +105,21 @@ export function formatIntent(doc: Result): string {
   const files = ofKind(doc, "file");
   if (files.length > 0) out.push(`files     ${files.length} under the region, ${files.filter((f) => f.generated).length} generated`);
   for (const d of ofKind(doc, "decision")) out.push(decisionLine(d), ...withinLines(doc, d));
+  for (const w of ofKind(doc, "work")) out.push(...workLines(doc, w));
   for (const a of ofKind(doc, "artifact")) out.push(artifactLine(doc, a));
   for (const c of ofKind(doc, "commit")) out.push(...commitLine(doc, c));
   for (const l of ofKind(doc, "link")) {
     const r = l.row;
     out.push(`link      ${r.consumer} reads ${"producer" in r ? `${r.producer} ${r.output}` : r.input} (${r.status})`);
   }
-  for (const f of ofKind(doc, "finding")) out.push(`finding   ${f.code}: ${f.message}`);
+  for (const f of ofKind(doc, "finding")) {
+    const by = f.addressedBy && f.addressedBy.length > 0 ? `; addressed by ${f.addressedBy.map((w) => `${w.id} (${w.state ?? "unknown"})`).join(", ")}` : "";
+    out.push(`finding   ${f.code}: ${f.message}${by}`);
+  }
   for (const r of doc.reasons) out.push(`reason    ${r.code}: ${r.message}`);
   const kinds = doc.kinds.length === 0 ? "; no --kind, so no decisions were read" : "";
-  out.push(`${doc.summary.commits} commits, ${doc.summary.decisions} decisions, ${doc.summary.artifacts} artifacts, ${doc.summary.findings} findings${kinds}`);
+  const work = ofKind(doc, "work").length;
+  out.push(`${doc.summary.commits} commits, ${doc.summary.decisions} decisions, ${work > 0 ? `${work} work ${work === 1 ? "item" : "items"}, ` : ""}${doc.summary.artifacts} artifacts, ${doc.summary.findings} findings${kinds}`);
   return out.join("\n");
 }
 
@@ -107,8 +129,9 @@ export async function runWorkspaceIntent(ctx: CommandContext, cwd: string): Prom
     console.error(formatError({ message: "--intent needs a region: a path, path:line or path:start-end", hint: USAGE }));
     return 1;
   }
-  const kinds = args.kinds ?? (args.kind !== undefined ? [args.kind] : []);
-  const { doc, failed } = await intentGraph({ cwd, region: args.intent, at: args.at, kinds: kinds.map((k) => resolve(k)) });
+  // No --kind: undefined, so the walk reads the kinds the declaration names (#2680).
+  const kinds = args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined);
+  const { doc, failed } = await intentGraph({ cwd, region: args.intent, at: args.at, kinds: kinds?.map((k) => resolve(k)) });
   if (args.json) console.log(JSON.stringify(doc, null, 2));
   if ("error" in doc) {
     console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));

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

@@ -0,0 +1,60 @@
+/**
+ * The commit-join hook's data form and its export checks, with no git
+ * (#2651, #2663).
+ */
+
+import { describe, expect, test } from "vitest";
+import { joinByData, readCommitJoins, trailerValue, trailerValues, type CommitJoinContext, type IntentCommit } from "./intent-joins";
+
+const commit = (trailers: Record<string, string[]>): IntentCommit => ({ sha: "a".repeat(40), subject: "s", body: "", author: { name: "t", email: "t@example.com" }, date: "2026-09-24T00:00:00Z", trailers });
+
+const files: Record<string, string> = {
+  "evidence/E-1.json": JSON.stringify({ id: "ignored", kind: "test-run" }),
+  "evidence/E-3.json": JSON.stringify({ kind: "review" }),
+  "units/U-1.json": JSON.stringify({ role: "implement" }),
+};
+const context: CommitJoinContext = { read: (p) => files[p], list: () => undefined, at: null };
+
+describe("the data form reads every trailer value (#2663)", () => {
+  test("each value of the evidence trailer, under any case of its key, is one piece of evidence", () => {
+    const data = { trailers: { unit: "Unit", evidence: "Evidence" }, records: { unit: "units/{id}.json", evidence: "evidence/{id}.json" } };
+    const out = joinByData(data, commit({ Unit: ["U-1"], Evidence: ["E-1", " E-2 ", "E-1"], evidence: ["E-3", ""] }), context);
+    expect(out).toEqual({
+      unit: { id: "U-1", role: "implement" },
+      evidence: [
+        { id: "E-1", kind: "test-run" },
+        { id: "E-2" },
+        { id: "E-3", kind: "review" },
+      ],
+    });
+  });
+
+  test("a unit or contract trailer gives its first value, since a commit has one of each", () => {
+    const out = joinByData({ trailers: { unit: "Unit", contract: "Contract" } }, commit({ Unit: ["U-1", "U-2"], contract: ["C-1"], Contract: ["C-2"] }), context);
+    expect(out.unit).toEqual({ id: "U-1" });
+    expect(out.contract?.id).toBe(trailerValue({ contract: ["C-1"], Contract: ["C-2"] }, "Contract"));
+  });
+
+  test("trailerValues keeps git's order, trims, and drops empty values and repeats", () => {
+    expect(trailerValues({ "Chud-Evidence": ["h1", "h2"], "chud-evidence": ["h2", " h3", "  "] }, "CHUD-EVIDENCE")).toEqual(["h1", "h2", "h3"]);
+    expect(trailerValues({}, "X")).toEqual([]);
+    expect(trailerValue({ X: ["  "] }, "x")).toBeUndefined();
+  });
+});
+
+describe("commitJoinsName (#2663)", () => {
+  test("names the findings of either form, and leaves the data form's own keys alone", () => {
+    const join = () => undefined;
+    expect(readCommitJoins({ commitJoins: join, commitJoinsName: "chud" })).toEqual({ form: "function", join, name: "chud" });
+    expect(readCommitJoins({ commitJoins: { trailers: { unit: "Unit" } }, commitJoinsName: "chud" })).toEqual({ form: "data", data: { trailers: { unit: "Unit" } }, name: "chud" });
+    expect(readCommitJoins({ commitJoins: join })).toEqual({ form: "function", join });
+    // A name inside the data form is still a key the data form does not have.
+    expect(readCommitJoins({ commitJoins: { name: "chud", trailers: {} } })).toMatch(/Unrecognized key/);
+  });
+
+  test("a name that can't be a plugin:<name>: segment, or one with no joins, is refused", () => {
+    for (const bad of ["a:b", "a b", "", 7]) expect(readCommitJoins({ commitJoins: () => undefined, commitJoinsName: bad }), String(bad)).toMatch(/^commitJoinsName:/);
+    expect(readCommitJoins({ commitJoinsName: "chud" })).toMatch(/no commitJoins/);
+    expect(readCommitJoins({})).toBeUndefined();
+  });
+});

package/src/workspace/intent-joins.ts

@@ -9,11 +9,16 @@
  *
  * - A function `commitJoins(commit, context)` that returns the unit, contract
  *   and evidence for one commit, or nothing. It is given the commit's sha,
- *   subject, body, author, date and trailers, and a `read` function for files
- *   at the revision read.
+ *   subject, body, author, date and trailers, and a context whose `read(path)`
+ *   returns a file and whose `list(dir)` lists a directory, both in the tree
+ *   read (#2663). With `list` a plugin can find the record that names a
+ *   commit, such as a unit record whose `result.commit` is the commit's sha,
+ *   so the commit needs no trailer at all.
  * - Data, which core interprets with no plugin code: the trailer keys that
  *   name a unit, a contract or evidence, the record paths to read for each
- *   (`units/{id}.json`), and the trailer keys that claim authorship.
+ *   (`units/{id}.json`), and the trailer keys that claim authorship. Every
+ *   value of the evidence trailer is read; a unit or contract trailer gives
+ *   its first value, since a commit has one unit and one contract.
  *
  * Either way core never parses a plugin's own trailer or record format: it
  * reads the trailers git reports and hands them over, and a key means
@@ -27,6 +32,14 @@
  * about, which the graph carries as finding nodes. That is how a plugin says
  * what it knows and core does not, such as a contract whose criteria changed
  * in a commit that names no decision.
+ *
+ * `<name>` is the kind's name by default: its record kind's name, or the
+ * file's name without `.kind.mjs`. A kind file may name its findings itself
+ * with a sibling export, `commitJoinsName` (#2663), so joins that live beside
+ * a record kind called `decision` can still report `plugin:chud:<code>`. It is
+ * a sibling export rather than a property because the data form is a closed
+ * object whose keys are all joins, and a function's `name` property is
+ * already its own name.
  */
 
 import { z } from "zod";
@@ -47,6 +60,18 @@ export interface IntentCommit {
 export interface CommitJoinContext {
   /** The text of a file from the workspace root, in the tree read; undefined when it is not a file there. */
   read(path: string): string | undefined;
+  /**
+   * The entries directly inside directory `dir`, in the same tree as `read`
+   * (#2663): paths from the workspace root, sorted, a directory's with a
+   * trailing `/`. `""` or `"."` is the workspace root. Undefined when `dir` is
+   * not a directory there.
+   *
+   * The tree is the one the graph reads, the commit `--at` names or the
+   * working tree, and not each joined commit's own tree: a record that names
+   * a commit's sha was written after that commit, so it is only in a later
+   * tree.
+   */
+  list(dir: string): string[] | undefined;
   /** The full commit id read with `--at`, or null for the working tree. */
   at: string | null;
 }
@@ -63,7 +88,7 @@ export interface JoinedEntity {
 
 /** A finding a plugin contributes for one commit (#2656). */
 export interface PluginFinding {
-  /** `plugin:<name>:<code>`, where `<name>` is the kind's name. */
+  /** `plugin:<name>:<code>`, where `<name>` is the kind file's `commitJoinsName`, or else the kind's name. */
   code: string;
   message: string;
   /** What the finding is about: node ids, commit shas, record ids, unit, contract or evidence ids, or paths. */
@@ -103,24 +128,49 @@ export const commitJoinsDataSchema = z
 
 export type CommitJoinsData = z.infer<typeof commitJoinsDataSchema>;
 
-/** A kind file's `commitJoins` export, checked: a function, or data. */
-export type CommitJoins = { form: "function"; join: CommitJoinsFunction } | { form: "data"; data: CommitJoinsData };
+/**
+ * A kind file's `commitJoins` export, checked: a function, or data. `name` is
+ * its `commitJoinsName` export, when it has one: the namespace of its findings.
+ */
+export type CommitJoins = ({ form: "function"; join: CommitJoinsFunction } | { form: "data"; data: CommitJoinsData }) & { name?: string };
+
+/** What a `commitJoinsName` may be: the `<name>` of `plugin:<name>:<code>`. */
+const JOINS_NAME = /^[^:\s]+$/;
 
-/** Read a kind module's `commitJoins` export. Undefined when it has none; a string when it is malformed. */
+/**
+ * Read a kind module's `commitJoins` export and its `commitJoinsName`.
+ * Undefined when it has no `commitJoins`; a string when either is malformed,
+ * or when it names findings it has no joins for.
+ */
 export function readCommitJoins(mod: Record<string, unknown>): CommitJoins | string | undefined {
   const value = mod.commitJoins;
-  if (value === undefined) return undefined;
-  if (typeof value === "function") return { form: "function", join: value as CommitJoinsFunction };
+  const name = mod.commitJoinsName;
+  if (value === undefined) return name === undefined ? undefined : "commitJoinsName: a kind file with no commitJoins has no findings to name";
+  if (name !== undefined && (typeof name !== "string" || !JOINS_NAME.test(name))) return "commitJoinsName: a string with no colon or space, the <name> of plugin:<name>:<code>";
+  const named = name === undefined ? {} : { name: name as string };
+  if (typeof value === "function") return { form: "function", join: value as CommitJoinsFunction, ...named };
   const parsed = commitJoinsDataSchema.safeParse(value);
   if (!parsed.success) return parsed.error.issues.map((i) => `commitJoins${i.path.length ? `.${i.path.join(".")}` : ""}: ${i.message}`).join("; ");
-  return { form: "data", data: parsed.data };
+  return { form: "data", data: parsed.data, ...named };
+}
+
+/** Every value of trailer `key`, trimmed, without empty ones or repeats, compared without case as git does. */
+export function trailerValues(trailers: Record<string, string[]>, key: string): string[] {
+  const want = key.toLowerCase();
+  const out: string[] = [];
+  for (const [k, values] of Object.entries(trailers)) {
+    if (k.toLowerCase() !== want) continue;
+    for (const v of values) {
+      const t = v.trim();
+      if (t && !out.includes(t)) out.push(t);
+    }
+  }
+  return out;
 }
 
 /** The first value of trailer `key`, compared without case as git does. */
 export function trailerValue(trailers: Record<string, string[]>, key: string): string | undefined {
-  const want = key.toLowerCase();
-  for (const [k, values] of Object.entries(trailers)) if (k.toLowerCase() === want && values.length > 0) return values[0].trim() || undefined;
-  return undefined;
+  return trailerValues(trailers, key)[0];
 }
 
 /** Whether the commit carries trailer `key`. */
@@ -147,14 +197,15 @@ function recordFields(template: string | undefined, id: string, context: CommitJ
 /** Interpret the data form for one commit. Throws when a named record can't be read as JSON. */
 export function joinByData(data: CommitJoinsData, commit: IntentCommit, context: CommitJoinContext): CommitJoin {
   const out: CommitJoin = {};
-  for (const part of ["unit", "contract", "evidence"] as const) {
+  const entity = (part: "unit" | "contract" | "evidence", id: string): JoinedEntity => ({ ...recordFields(data.records?.[part], id, context), id });
+  for (const part of ["unit", "contract"] as const) {
     const key = data.trailers[part];
     const id = key ? trailerValue(commit.trailers, key) : undefined;
-    if (!id) continue;
-    const entity: JoinedEntity = { ...recordFields(data.records?.[part], id, context), id };
-    if (part === "evidence") out.evidence = entity;
-    else out[part] = entity;
+    if (id) out[part] = entity(part, id);
   }
+  // Each value of the evidence trailer is one piece of evidence (#2663).
+  const evidence = data.trailers.evidence ? trailerValues(commit.trailers, data.trailers.evidence) : [];
+  if (evidence.length > 0) out.evidence = evidence.map((id) => entity("evidence", id));
   const claimed = (data.authorship ?? []).filter((k) => hasTrailer(commit.trailers, k));
   if (claimed.length > 0) out.authorship = claimed;
   return out;
@@ -168,7 +219,8 @@ export function entityDecisions(entity: JoinedEntity | undefined): string[] {
 
 /**
  * Run a kind's joins for one commit, checking what a function returns.
- * `name` is the kind's name, the namespace its findings' codes must use.
+ * `name` is the namespace its findings' codes must use: the kind file's
+ * `commitJoinsName`, or else the kind's name.
  */
 export async function runCommitJoins(joins: CommitJoins, commit: IntentCommit, context: CommitJoinContext, name: string): Promise<CommitJoin> {
   if (joins.form === "data") return joinByData(joins.data, commit, context);

package/src/workspace/intent.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/intent/v1/intent.schema.json",
   "title": "chant workspace graph --intent output",
-  "description": "What `chant workspace graph --intent <region> --json` prints: the intent graph over one region of a workspace (#2651, #2650 section C1, #2524 D8 and D15). The region, the commits that touched it, the decisions whose constrains cover it and their supersession chains, the artifacts those decisions pin, the units, contracts and evidence a plugin joins to the commits, the member links of the region's member, and findings as nodes with closed codes. chant emits it and a reader such as hud draws it. Readers ignore fields and node or edge kinds they do not know; a field is only ever added within a version. The finding, reason and error codes are closed lists. Contract version 1 is written by chant 0.81.0 and newer, and this document was added to it by #2651; a chant without --intent refuses the flag. Every code is in the one closed list of `reason-codes.ts`.",
+  "description": "What `chant workspace graph --intent <region> --json` prints: the intent graph over one region of a workspace (#2651, #2650 section C1, #2524 D8 and D15). The region, the commits that touched it, the decisions whose constrains cover it and their supersession chains, the work items whose constrains cover it (#2683), the artifacts those decisions pin, the units, contracts and evidence a plugin joins to the commits, the member links of the region's member, and findings as nodes with closed codes. chant emits it and a reader such as hud draws it. Readers ignore fields and node or edge kinds they do not know; a field is only ever added within a version. The finding, reason and error codes are closed lists. Contract version 1 is written by chant 0.81.0 and newer, and this document was added to it by #2651; a chant without --intent refuses the flag. Every code is in the one closed list of `reason-codes.ts`.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -116,7 +116,7 @@
               },
               "name": {
                 "type": "string",
-                "description": "The kind's name: the record kind's name, or the file's name without .kind.mjs for a plugin with no records. A plugin's findings use it as their namespace, plugin:<name>:<code> (#2656). Added within version 1, so an older document may lack it."
+                "description": "The kind's name: the file's commitJoinsName export when it has one (#2663), else the record kind's name, or the file's name without .kind.mjs for a plugin with no records. A plugin's findings use it as their namespace, plugin:<name>:<code> (#2656). Added within version 1, so an older document may lack it."
               },
               "records": {
                 "type": [
@@ -126,6 +126,7 @@
                 "description": "The record kind's name, or null for a plugin with no records."
               },
               "joins": {
+                "description": "The form of the file's commitJoins export: a function commitJoins(commit, context), whose context has read(path) for a file and list(dir) for a directory's entries, both from the workspace root in the tree read (#2663); data, naming the trailers and record paths core reads, with every value of the evidence trailer read; or null when it has none.",
                 "enum": [
                   "function",
                   "data",
@@ -204,6 +205,9 @@
         {
           "$ref": "#/$defs/decision"
         },
+        {
+          "$ref": "#/$defs/work"
+        },
         {
           "$ref": "#/$defs/artifact"
         },
@@ -713,6 +717,240 @@
         }
       }
     },
+    "work": {
+      "description": "A work item (#2683), a record of a kind with a work block: in the graph when its constrains cover the region as a decision's would, or when a work item there implements, needs or addresses it. Read only when a work kind is passed with --kind.",
+      "type": "object",
+      "required": [
+        "id",
+        "kind",
+        "recordKind",
+        "record",
+        "path",
+        "title",
+        "state",
+        "closed",
+        "valid",
+        "reasons",
+        "provenance",
+        "owner",
+        "ready",
+        "blockedBy",
+        "implements",
+        "needs",
+        "source",
+        "supersededBy",
+        "constrains",
+        "warnings"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^record:"
+        },
+        "kind": {
+          "const": "work"
+        },
+        "recordKind": {
+          "type": "string"
+        },
+        "record": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "description": "The record file, from the repository root."
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "state": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "closed": {
+          "type": "boolean",
+          "description": "Whether the kind counts the state as closed, such as done or dropped."
+        },
+        "valid": {
+          "type": "boolean"
+        },
+        "reasons": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "code",
+              "message"
+            ],
+            "properties": {
+              "code": {
+                "enum": [
+                  "record-unparseable",
+                  "record-schema-invalid",
+                  "record-id-duplicate",
+                  "record-supersedes-unknown",
+                  "record-supersedes-conflict"
+                ]
+              },
+              "message": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "provenance": {
+          "type": "object",
+          "required": [
+            "level",
+            "commit",
+            "reason"
+          ],
+          "properties": {
+            "level": {
+              "enum": [
+                "attested",
+                "attested-unverifiable-here",
+                "adopted",
+                "unattested"
+              ]
+            },
+            "commit": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "pattern": "^[0-9a-f]{40,64}$"
+            },
+            "reason": {
+              "type": "string"
+            }
+          }
+        },
+        "owner": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The principal the record names as its owner, or null."
+        },
+        "ready": {
+          "type": "boolean",
+          "description": "As records reports it: valid, not superseded, in the kind's open state, and every need done."
+        },
+        "blockedBy": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/workLink"
+          },
+          "description": "Each need that is not done, with its state."
+        },
+        "implements": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/workLink"
+          },
+          "description": "Each decision the item implements, with its state."
+        },
+        "needs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The work ids the item's needs list names."
+        },
+        "source": {
+          "description": "The gap the item came from, when its source names one: a finding code, the region it fired on, and optionally the decision and artifact it concerned. Null for an item whose source is an issue or the workspace.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "finding",
+                "region"
+              ],
+              "properties": {
+                "finding": {
+                  "type": "string"
+                },
+                "region": {
+                  "type": "string"
+                },
+                "decision": {
+                  "type": "string"
+                },
+                "artifact": {
+                  "type": "string"
+                }
+              }
+            }
+          ]
+        },
+        "supersededBy": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "constrains": {
+          "type": "array",
+          "description": "The entries that cover the region, with their granularity, matched as a decision's are. Empty for an item in the graph only through a link.",
+          "items": {
+            "type": "object",
+            "required": [
+              "entry",
+              "granularity"
+            ],
+            "properties": {
+              "entry": {
+                "type": "string"
+              },
+              "granularity": {
+                "enum": [
+                  "path",
+                  "member",
+                  "contract",
+                  "issue"
+                ]
+              }
+            }
+          }
+        },
+        "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.",
+          "items": {
+            "type": "object",
+            "required": [
+              "code",
+              "message"
+            ],
+            "properties": {
+              "code": {
+                "enum": [
+                  "work-needs-unknown",
+                  "work-implements-unknown",
+                  "work-needs-cycle",
+                  "work-implements-undecided",
+                  "work-done-unpinned",
+                  "work-closed-without-date",
+                  "work-done-gap-open"
+                ]
+              },
+              "message": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
     "artifact": {
       "description": "A workspace file a decision in the graph pins. Artifacts reach the region only through decisions (#2549).",
       "type": "object",
@@ -857,7 +1095,10 @@
                 "intent-constraint-lost",
                 "intent-evidence-unpinned",
                 "intent-trailer-unverified",
-                "intent-region-unconstrained"
+                "intent-region-unconstrained",
+                "intent-decision-unimplemented",
+                "intent-work-blocked",
+                "intent-work-open-decided-code"
               ]
             },
             {
@@ -887,11 +1128,22 @@
             "type": "string"
           },
           "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."
+        },
+        "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."
+        },
+        "addressedBy": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/workLink"
+          },
+          "description": "Added by #2683, present when a work kind was read: the work items addressing the finding, each with its state. Each has an addressed-by edge from the finding."
         }
       }
     },
     "edge": {
-      "description": "constrains: decision to region, file or contract. pins: decision to artifact. touched-by: region to commit. produced-by: commit to unit. serves: unit to contract. supersedes: the newer decision to the one it replaces. cites-evidence: unit, contract or decision to evidence. links: consumer member to producer member. within: commit to a decision whose path window it falls in.",
+      "description": "constrains: decision or work item to region, file or contract. pins: decision to artifact. touched-by: region to commit. produced-by: commit to unit. serves: unit to contract. supersedes: the newer decision to the one it replaces. cites-evidence: unit, contract or decision to evidence. links: consumer member to producer member. within: commit to a decision whose path window it falls in, or to a work item whose window it falls in. implements: work item to the decision it carries out. needs: work item to a work item it waits on. addressed-by: finding to a work item that addresses it.",
       "oneOf": [
         {
           "$ref": "#/$defs/constrainsEdge"
@@ -1105,13 +1357,16 @@
             "serves",
             "supersedes",
             "cites-evidence",
-            "links"
+            "links",
+            "implements",
+            "needs",
+            "addressed-by"
           ]
         }
       }
     },
     "withinEdge": {
-      "description": "A commit made inside a decision's window, from the commit that added the decision's record until the one that added its successor (#2656). state is decided when the decision's own unit made the commit, and decided-by-window otherwise.",
+      "description": "A commit made inside a decision's window, from the commit that added the decision's record until the one that added its successor (#2656). state is decided when the decision's own unit made the commit, and decided-by-window otherwise. Added by #2683: a commit made inside a work item's window, from the commit that added the record to the commit that closed it, that commit included, or to the revision read while it is open, has state worked. A worked edge leaves the commit's own state as the decisions set it.",
       "type": "object",
       "required": [
         "kind",
@@ -1132,10 +1387,30 @@
         "state": {
           "enum": [
             "decided",
-            "decided-by-window"
+            "decided-by-window",
+            "worked"
           ]
         }
       }
+    },
+    "workLink": {
+      "type": "object",
+      "required": [
+        "id",
+        "state"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "state": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The linked record's state, or null when no record has the id."
+        }
+      }
     }
   }
 }