@intentius/chant 0.85.0 → 0.86.0

package/src/workspace/intent.test.ts

@@ -564,3 +564,100 @@ describe("reads that fail, and parts that can't be read (#2651)", () => {
     expect(parseRegion("a/b.ts:0")).toHaveProperty("error");
   });
 });
+
+describe("commitJoins lists records and names its findings (#2663)", () => {
+  test("a plugin joins commits by listing its records, with no trailer at all (#2663)", async () => {
+    const SCAN = `
+export function commitJoins(commit, context) {
+  const walk = (dir) => (context.list(dir) ?? []).flatMap((p) => (p.endsWith("/") ? walk(p) : [p]));
+  for (const path of walk("unit-records")) {
+    const id = path.split("/").at(-1).replace(/\\.(json|md)$/, "");
+    const text = context.read(path);
+    if (path.endsWith(".json")) {
+      const record = JSON.parse(text);
+      if (record.result?.commit !== commit.sha) continue;
+      const probe = { missing: context.list("nope"), escape: context.list(".."), file: context.list(path), root: context.list(".").includes("unit-records/") };
+      return { unit: { id, path, probe }, contract: { id: record.contract } };
+    }
+    if (text.includes(commit.sha)) return { unit: { id, path } };
+  }
+  return undefined;
+}
+`;
+    writeFiles(root, {
+      "plugins/scan.kind.mjs": SCAN,
+      "unit-records/U-0100.json": JSON.stringify({ contract: "C-100", result: { commit: sha.c2 } }),
+      "unit-records/archive/U-0104.md": `---\nid: U-0104\n---\n\nLanded as ${sha.c4}.\n`,
+    });
+    commit(["record the units after their commits"]);
+    try {
+      const doc = await walk("app/server.mjs", { kinds: [KIND, "plugins/scan.kind.mjs"] });
+      // c4 carries no trailer; the markdown record in a subdirectory names it.
+      expect(node(doc, `commit:${sha.c4}`)).toMatchObject({ trailers: {} });
+      expect(doc.edges).toContainEqual({ kind: "produced-by", from: `commit:${sha.c4}`, to: "unit:U-0104" });
+      expect(node(doc, "unit:U-0104")).toMatchObject({ data: { path: "unit-records/archive/U-0104.md" } });
+      expect(doc.edges).toContainEqual({ kind: "produced-by", from: `commit:${sha.c2}`, to: "unit:U-0100" });
+      expect(doc.edges).toContainEqual({ kind: "serves", from: "unit:U-0100", to: "contract:C-100" });
+      expect(node(doc, "unit:U-0100")).toMatchObject({ data: { path: "unit-records/U-0100.json", probe: { root: true } } });
+      // Not a directory there, or outside the workspace: undefined.
+      expect((node(doc, "unit:U-0100") as { data: unknown }).data).toMatchObject({ probe: { missing: undefined, escape: undefined, file: undefined, root: true } });
+      expect(node(doc, `commit:${sha.c2b}`) && doc.edges.some((e) => e.kind === "produced-by" && e.from === `commit:${sha.c2b}`)).toBe(false);
+      expect(doc.reasons).toEqual([]);
+
+      // At c4 the records were not written yet: list answers from the tree read, so nothing joins.
+      const before = await walk("app/server.mjs", { kinds: [KIND, "plugins/scan.kind.mjs"], at: sha.c4 });
+      expect(before.nodes.filter((n) => n.kind === "unit")).toEqual([]);
+      expect(before.reasons).toEqual([]);
+    } finally {
+      git(root, "reset", "-q", "--hard", sha.c4);
+    }
+  });
+
+  test("commitJoinsName names a plugin's findings apart from its record kind's name (#2663)", async () => {
+    const NAMED = (name: string) => `
+export { recordKind } from "./decision.kind.mjs";
+export const commitJoinsName = ${JSON.stringify(name)};
+export function commitJoins(commit) {
+  if (commit.trailers["Unit"]?.[0] !== "U-0002") return undefined;
+  return { findings: [{ code: "plugin:studio:contract-moved", message: "moved", refs: [commit.sha] }] };
+}
+`;
+    writeFiles(root, { "decisions/studio.kind.mjs": NAMED("studio"), "decisions/other.kind.mjs": NAMED("other") });
+    commit(["name the findings"]);
+    try {
+      const doc = await walk("app/server.mjs", { kinds: ["decisions/studio.kind.mjs"] });
+      expect(doc.kinds).toEqual([{ file: "decisions/studio.kind.mjs", name: "studio", records: "decision", joins: "function" }]);
+      expect(doc.reasons).toEqual([]);
+      expect(doc.nodes).toContainEqual(expect.objectContaining({ kind: "finding", code: "plugin:studio:contract-moved", concerns: [`commit:${sha.c2b}`] }));
+      // The decisions still come from the record kind called decision.
+      expect(node(doc, "record:decision/dec-001")).toBeDefined();
+
+      // Under another name, the same code is outside the namespace, and the record kind's name is no longer it either.
+      const { doc: other, failed } = await intentGraph({ cwd: root, region: "app/server.mjs", kinds: [join(root, "decisions/other.kind.mjs")] });
+      expectValid(other);
+      if ("error" in other) throw new Error(other.error.message);
+      expect(failed).toBe(true);
+      expect(other.reasons).toEqual([{ code: "intent-plugin-failed", message: expect.stringContaining("plugin:other:<code>") }]);
+    } finally {
+      git(root, "reset", "-q", "--hard", sha.c4);
+    }
+  });
+
+  test("a malformed commitJoinsName is kind-invalid (#2663)", async () => {
+    writeFiles(root, { "plugins/badname.kind.mjs": `export const commitJoinsName = "a:b";\nexport function commitJoins() {}\n`, "plugins/nameonly.kind.mjs": `export const commitJoinsName = "x";\n` });
+    commit(["malformed names"]);
+    try {
+      for (const [file, text] of [
+        ["plugins/badname.kind.mjs", "no colon or space"],
+        ["plugins/nameonly.kind.mjs", "no commitJoins"],
+      ]) {
+        const { doc } = await intentGraph({ cwd: root, region: "app/server.mjs", kinds: [join(root, file)] });
+        expectValid(doc);
+        expect("error" in doc && doc.error.code).toBe("kind-invalid");
+        expect("error" in doc && doc.error.message).toContain(text);
+      }
+    } finally {
+      git(root, "reset", "-q", "--hard", sha.c4);
+    }
+  });
+});

package/src/workspace/intent.ts

@@ -26,28 +26,32 @@
  * inside a decision's window is not taken as that decision's work: unless
  * the decision's own unit made it, it is `decided-by-window`, shown for the
  * person to judge (#2656). A plugin's `commitJoins` may add findings of its
- * own, in its own code namespace. chant emits the
+ * own, in its own code namespace. Without `kinds`, the walk reads every
+ * record kind the declaration names (#2680), and each one's `commitJoins`
+ * runs for every commit in that order. chant emits the
  * graph and hud renders it (#2524 D8, D15). Git is read through a local
  * `git` subprocess only: no fetch, no network.
  */
 
 import { execFileSync } from "node:child_process";
 import { realpathSync } from "node:fs";
-import { basename, relative, resolve, sep } from "node:path";
-import { readDeclaration, readerVersion, resolveGroups, WORKSPACE_ERROR_CODES, WorkspaceReadError, type Declaration } from "./declaration";
+import { basename, dirname, relative, resolve, sep } from "node:path";
+import { declaredRecordKinds, readDeclaration, readerVersion, resolveGroups, WORKSPACE_ERROR_CODES, WorkspaceReadError, type Declaration } from "./declaration";
+import { declaredKindFile } from "./declared-kinds";
 import { classifyFile, declaredFilesUnder } from "./generated-files";
 import { entityDecisions, hasTrailer, readCommitJoins, runCommitJoins, type CommitJoins, type IntentCommit, type JoinedEntity, type PluginFinding } from "./intent-joins";
 import { loadKindRegistry } from "./kinds";
 import { resolveLinks, type LinkTableRow } from "./links";
 import { sourceMemberHandles } from "./member-handles";
 import { constraintCovers, isWorkspacePath, memberHolding } from "./record-assets";
-import { importKindModule, loadRecordKind, RecordReadError, type LoadedRecordKind } from "./records";
+import { importKindModule, loadRecordKind, parseFrontMatter, RecordReadError, supersedesTargets, type LoadedRecordKind } from "./records";
 import { queryRecords, type RecordView } from "./records-cli";
-import type { PluginCode, ReasonCode } from "./reason-codes";
+import { isPluginCode, type PluginCode, type ReasonCode } from "./reason-codes";
 import { joinPath, skippedDir, type WorkspaceTree } from "./tree";
 import { activeAttestors, type ProvenanceLevel } from "./trust/attestor";
 import { commitProvenance, policyAtBase, resolveBase } from "./trust/provenance";
 import { locateWorkspace, type LocatedWorkspace } from "./which-chant";
+import { idList, isDecided, WORK_WARNING_CODES, type WorkLink, type WorkWarningCode } from "./work";
 
 /** The version of the `intent` document this chant writes. */
 export const INTENT_CONTRACT_VERSION = 1;
@@ -83,6 +87,12 @@ export const INTENT_FINDING_CODES = [
   "intent-trailer-unverified",
   /** No decision constrains the region at any granularity. */
   "intent-region-unconstrained",
+  /** A decided decision constrains the region, no work item that is not dropped implements it, and no commit falls in its window (#2683). Only with a work kind read. */
+  "intent-decision-unimplemented",
+  /** A work item constraining the region has commits in its window while its blockedBy is not empty (#2683). */
+  "intent-work-blocked",
+  /** Commits in the region are a decision's own work while the work item implementing it is still open: the code says done and the queue says not (#2683). */
+  "intent-work-open-decided-code",
 ] as const satisfies readonly ReasonCode[];
 export type IntentFindingCode = (typeof INTENT_FINDING_CODES)[number];
 
@@ -259,9 +269,53 @@ 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[];
+  /** 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. */
+  addressedBy?: WorkLink[];
 }
 
-export type IntentNode = RegionNode | FileNode | MemberNode | CommitNode | JoinedNode | EvidenceEntryNode | DecisionNode | ArtifactNode | LinkNode | FindingNode;
+/** Where a work item says it came from: the gap the intent graph reported (#2683). */
+export interface WorkGapSource {
+  finding: string;
+  region: string;
+  decision?: string;
+  artifact?: string;
+}
+
+export interface WorkNode {
+  id: string;
+  kind: "work";
+  recordKind: string;
+  record: string;
+  /** The record file, from the repository root. */
+  path: string;
+  title: string | null;
+  state: string | null;
+  /** Whether the kind counts the state as closed, such as done or dropped. */
+  closed: boolean;
+  valid: boolean;
+  reasons: RecordView["reasons"];
+  provenance: { level: ProvenanceLevel; commit: string | null; reason: string };
+  owner: string | null;
+  /** As records reports it: open, and every need done. */
+  ready: boolean;
+  /** Each need that is not done, with its state. */
+  blockedBy: WorkLink[];
+  /** Each decision the item implements, with its state. */
+  implements: WorkLink[];
+  /** The ids the item's needs list names. */
+  needs: string[];
+  /** The gap the item came from, when its source names one. */
+  source: WorkGapSource | null;
+  supersededBy: string | null;
+  /** The constrains entries that cover the region, with their granularity. Empty for an item in the graph only through a link. */
+  constrains: { entry: string; granularity: Granularity }[];
+  /** The item's work warnings, as records reports them, and work-done-gap-open. */
+  warnings: { code: WorkWarningCode; message: string }[];
+}
+
+export type IntentNode = RegionNode | FileNode | MemberNode | CommitNode | JoinedNode | EvidenceEntryNode | DecisionNode | WorkNode | ArtifactNode | LinkNode | FindingNode;
 
 export type Granularity = "path" | "member" | "contract" | "issue";
 
@@ -269,8 +323,8 @@ export type IntentEdge =
   | { kind: "constrains"; from: string; to: string; granularity: Granularity; entry: string }
   | { kind: "pins"; from: string; to: string; pinnedSha256: string | null; pinState: PinState }
   | { kind: "touched-by"; from: string; to: string; lines: LineRange[] | null }
-  | { kind: "within"; from: string; to: string; state: "decided" | "decided-by-window" }
-  | { kind: "produced-by" | "serves" | "cites-evidence" | "supersedes" | "links"; from: string; to: string };
+  | { kind: "within"; from: string; to: string; state: "decided" | "decided-by-window" | "worked" }
+  | { kind: "produced-by" | "serves" | "cites-evidence" | "supersedes" | "links" | "implements" | "needs" | "addressed-by"; from: string; to: string };
 
 export interface IntentReason {
   code: IntentReasonCode;
@@ -303,7 +357,11 @@ export interface IntentQuery {
   /** `path`, `path:line` or `path:start-end`, or a graph node id `<member>/<id>`. */
   region: string;
   at?: string;
-  /** Kind files: record kinds, plugins with `commitJoins`, or both. Relative to `cwd`. */
+  /**
+   * Kind files: record kinds, plugins with `commitJoins`, or both. Relative to
+   * `cwd`. Left out, every record kind the declaration names, in its order
+   * (#2680); an empty list reads none.
+   */
   kinds?: string[];
   /**
    * Resolve a graph node id to its source location, for a region given as a
@@ -403,6 +461,25 @@ function addingCommit(top: string, rev: string, path: string): string | null {
   return out?.trim() || null;
 }
 
+/**
+ * The commit reachable from `rev` that moved the record at `path` into a
+ * closed state and kept it there, or null when the record is not closed at
+ * `rev` (#2683). A record added in a closed state closes in the commit that
+ * added it.
+ */
+function closingCommit(top: string, rev: string, path: string, stateField: string, closed: readonly string[]): string | null {
+  const out = tryGit(top, ["log", "--format=%H", rev, "--", path]);
+  let closing: string | null = null;
+  for (const sha of (out ?? "").split("\n").map((l) => l.trim()).filter(Boolean)) {
+    const text = tryGit(top, ["show", `${sha}:${path}`]);
+    const fm = text === undefined ? undefined : parseFrontMatter(text);
+    const state = fm?.ok ? fm.value[stateField] : undefined;
+    if (typeof state !== "string" || !closed.includes(state)) break;
+    closing = sha;
+  }
+  return closing;
+}
+
 /** `commit` and every commit between it and `rev` that has it as an ancestor. */
 function descendants(top: string, commit: string, rev: string): Set<string> {
   const out = new Set<string>([commit]);
@@ -469,6 +546,20 @@ function stringOr(v: unknown): string | null {
   return typeof v === "string" ? v : null;
 }
 
+/** A work record's `source` when it names the gap it came from (#2683), or null. */
+function gapSource(data: Record<string, unknown> | null): WorkGapSource | null {
+  const src = data?.source;
+  if (src === null || typeof src !== "object" || Array.isArray(src)) return null;
+  const s = src as Record<string, unknown>;
+  if (typeof s.finding !== "string" || typeof s.region !== "string") return null;
+  return {
+    finding: s.finding,
+    region: s.region,
+    ...(typeof s.decision === "string" ? { decision: s.decision } : {}),
+    ...(typeof s.artifact === "string" ? { artifact: s.artifact } : {}),
+  };
+}
+
 function reviewSummary(data: Record<string, unknown> | null): DecisionNode["reviews"] {
   const out = { agree: 0, dissent: 0, abstain: 0, openConcerns: 0 };
   const list = data?.reviews;
@@ -506,7 +597,7 @@ interface LoadedKind {
   file: string;
   /** Relative to the repository root, for the document. */
   display: string;
-  /** The record kind's name, or the file's name without `.kind.mjs`: the namespace of its plugin findings. */
+  /** The namespace of its plugin findings: its `commitJoinsName`, the record kind's name, or the file's name without `.kind.mjs`. */
   name: string;
   records?: { loaded: LoadedRecordKind; views: RecordView[]; workspaceRoot: string };
   joins?: CommitJoins;
@@ -525,13 +616,13 @@ async function loadKinds(query: IntentQuery, top: string): Promise<LoadedKind[]>
     }
     const joins = readCommitJoins(mod);
     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: basename(file).replace(/(?:\.kind)?\.[cm]?[jt]s$/, ""), ...(joins ? { 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 });
       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 };
-        kind.name = kind.records.loaded.kind.name;
+        kind.name = joins?.name ?? kind.records.loaded.kind.name;
       } catch (err) {
         if (err instanceof RecordReadError) throw new IntentError(err.code as IntentErrorCode, err.message);
         throw err;
@@ -591,7 +682,9 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     const count = located.tree.read(region.path).replace(/\n$/, "").split("\n").length;
     if (region.lines.end > count) throw new IntentError("intent-region-invalid", `${region.path} has ${count} lines${located.tree.label}, so ${region.lines.start}-${region.lines.end} is not in it`);
   }
-  const kinds = await loadKinds(query, top);
+  // Without --kind, the declared record kinds, read from the working tree as a --kind file is (#2680).
+  const kindFiles = query.kinds ?? declaredRecordKinds(declaration).map((d) => declaredKindFile(d, located.rootOnDisk));
+  const kinds = await loadKinds({ ...query, kinds: kindFiles }, top);
 
   const nodes = new Map<string, IntentNode>();
   const edges: IntentEdge[] = [];
@@ -634,6 +727,13 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     if (!isWorkspacePath(path) || located.tree.stat(path) !== "file") return undefined;
     return located.tree.read(path);
   };
+  // The same tree as readAt (#2663): entries directly inside dir, from the workspace root, a directory's with a trailing slash.
+  const listAt = (dir: string): string[] | undefined => {
+    const d = dir === "." ? "" : dir.replace(/\/+$/, "");
+    if (d !== "" && (!isWorkspacePath(d) || located.tree.stat(d) !== "dir")) return undefined;
+    const entries = located.tree.list(d);
+    return entries?.map((e) => `${joinPath(d, e.name)}${e.type === "dir" ? "/" : ""}`).sort();
+  };
   interface Joined {
     unit?: string;
     contracts: string[];
@@ -665,7 +765,7 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
       if (!k.joins) continue;
       let result;
       try {
-        result = await runCommitJoins(k.joins, c, { read: readAt, at: located.at }, k.name);
+        result = await runCommitJoins(k.joins, c, { read: readAt, list: listAt, at: located.at }, k.name);
       } catch (err) {
         const message = `${k.display}: commitJoins failed for ${c.sha.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`;
         if (!failedPlugins.has(message)) reasons.push({ code: "intent-plugin-failed", message });
@@ -708,10 +808,7 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
   const decisionId = (k: LoadedKind, id: string) => `record:${k.records!.loaded.kind.name}/${id}`;
   const decisionNode = (k: LoadedKind, v: RecordView): DecisionNode => {
     const kind = k.records!.loaded.kind;
-    const links = v.data?.[kind.supersedes.field];
-    const supersedes = Array.isArray(links)
-      ? links.map((l) => (l && typeof l === "object" ? (l as Record<string, unknown>)[kind.supersedes.key] : undefined)).filter((x): x is string => typeof x === "string")
-      : [];
+    const supersedes = supersedesTargets(kind, v.data);
     return add<DecisionNode>({
       id: decisionId(k, v.id!),
       kind: "decision",
@@ -720,7 +817,7 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
       path: v.path,
       title: stringOr(v.data?.title),
       state: v.state,
-      closed: v.state !== null && kind.closedStates.includes(v.state),
+      closed: v.state !== null && (kind.closedStates ?? []).includes(v.state),
       valid: v.valid,
       reasons: v.reasons,
       provenance: { level: v.provenance.level, commit: v.provenance.commit, reason: v.provenance.reason },
@@ -733,36 +830,41 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     });
   };
   const fileNodesUnder = (full: string) => files.filter((f) => constraintCovers(full, joinPath(workspacePrefix, f)));
+  /** The constrains entries of a record that cover the region or a file under it. Decisions and work items match the same way (#2683). */
+  const matchConstrains = (k: LoadedKind, v: RecordView): { entry: string; granularity: Granularity; to: string }[] => {
+    const field = k.records!.loaded.kind.constrains?.field;
+    const kindPrefix = k.records!.workspaceRoot === "." ? "" : k.records!.workspaceRoot;
+    const list = field ? v.data?.[field] : undefined;
+    const matched: { entry: string; granularity: Granularity; to: string }[] = [];
+    if (!Array.isArray(list)) return matched;
+    for (const entry of list) {
+      if (typeof entry !== "string") continue;
+      if (entry.startsWith("path:")) {
+        const p = entry.slice("path:".length);
+        if (!isWorkspacePath(p)) continue;
+        const full = joinPath(kindPrefix, p);
+        if (regionFull !== "" && constraintCovers(full, regionFull)) {
+          matched.push({ entry, granularity: "path", to: rid });
+        } else if (type === "dir" && full !== regionFull && (regionFull === "" || full.startsWith(`${regionFull}/`))) {
+          // A path below a directory region constrains the files under it, not the whole region.
+          for (const f of fileNodesUnder(full)) matched.push({ entry, granularity: "path", to: `file:${f}` });
+        }
+      } else if (entry.startsWith("member:")) {
+        if (member !== null && entry.slice("member:".length) === member) matched.push({ entry, granularity: "member", to: rid });
+      } else {
+        const issue = entry.match(ISSUE);
+        if (issue && origin !== null && issue[1].toLowerCase() === origin && commitRefs.has(issue[2])) matched.push({ entry, granularity: "issue", to: rid });
+        else if (contractIds.has(entry)) matched.push({ entry, granularity: "contract", to: `contract:${entry}` });
+      }
+    }
+    return matched;
+  };
   for (const k of kinds) {
-    if (!k.records) continue;
-    const field = k.records.loaded.kind.constrains?.field;
-    const kindPrefix = k.records.workspaceRoot === "." ? "" : k.records.workspaceRoot;
+    if (!k.records || k.records.loaded.kind.work) continue;
     for (const v of k.records.views) {
       if (v.id === null) continue;
       decisionById.set(`${k.records.loaded.kind.name}/${v.id}`, { view: v, kind: k });
-      const list = field ? v.data?.[field] : undefined;
-      if (!Array.isArray(list)) continue;
-      const matched: { entry: string; granularity: Granularity; to: string }[] = [];
-      for (const entry of list) {
-        if (typeof entry !== "string") continue;
-        if (entry.startsWith("path:")) {
-          const p = entry.slice("path:".length);
-          if (!isWorkspacePath(p)) continue;
-          const full = joinPath(kindPrefix, p);
-          if (regionFull !== "" && constraintCovers(full, regionFull)) {
-            matched.push({ entry, granularity: "path", to: rid });
-          } else if (type === "dir" && full !== regionFull && (regionFull === "" || full.startsWith(`${regionFull}/`))) {
-            // A path below a directory region constrains the files under it, not the whole region.
-            for (const f of fileNodesUnder(full)) matched.push({ entry, granularity: "path", to: `file:${f}` });
-          }
-        } else if (entry.startsWith("member:")) {
-          if (member !== null && entry.slice("member:".length) === member) matched.push({ entry, granularity: "member", to: rid });
-        } else {
-          const issue = entry.match(ISSUE);
-          if (issue && origin !== null && issue[1].toLowerCase() === origin && commitRefs.has(issue[2])) matched.push({ entry, granularity: "issue", to: rid });
-          else if (contractIds.has(entry)) matched.push({ entry, granularity: "contract", to: `contract:${entry}` });
-        }
-      }
+      const matched = matchConstrains(k, v);
       if (matched.length === 0) continue;
       const node = decisionNode(k, v);
       for (const m of matched) {
@@ -885,6 +987,116 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
       windows.set(c.node.id, { from: added ? descendants(top, added, rev) : new Set(), until: replaced ? descendants(top, replaced, rev) : null });
     }
   }
+  // Work items (#2683): the records of each work kind whose constrains cover
+  // the region, the decisions they implement and the items they need, one hop
+  // each, and each covering 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.
+  interface WorkHit {
+    view: RecordView;
+    kind: LoadedKind;
+    node?: WorkNode;
+  }
+  const workKinds = kinds.filter((k) => k.records?.loaded.kind.work);
+  const readsWork = workKinds.length > 0;
+  const workAll: WorkHit[] = [];
+  const workByKey = new Map<string, WorkHit>();
+  for (const k of workKinds) {
+    for (const v of k.records!.views) {
+      if (v.id === null) continue;
+      const hit: WorkHit = { view: v, kind: k };
+      workAll.push(hit);
+      const key = `${k.records!.loaded.kind.name}/${v.id}`;
+      if (!workByKey.has(key)) workByKey.set(key, hit);
+    }
+  }
+  const workSpec = (h: WorkHit) => h.kind.records!.loaded.kind.work!;
+  const workNode = (h: WorkHit): WorkNode => {
+    if (h.node) return h.node;
+    const kind = h.kind.records!.loaded.kind;
+    const v = h.view;
+    h.node = add<WorkNode>({
+      id: `record:${kind.name}/${v.id!}`,
+      kind: "work",
+      recordKind: kind.name,
+      record: v.id!,
+      path: v.path,
+      title: stringOr(v.data?.title),
+      state: v.state,
+      closed: v.state !== null && (kind.closedStates ?? []).includes(v.state),
+      valid: v.valid,
+      reasons: v.reasons,
+      provenance: { level: v.provenance.level, commit: v.provenance.commit, reason: v.provenance.reason },
+      owner: stringOr(v.data?.owner),
+      ready: v.ready ?? false,
+      blockedBy: v.blockedBy ?? [],
+      implements: v.implements ?? [],
+      needs: idList(v.data, kind.work!.needs),
+      source: gapSource(v.data),
+      supersededBy: v.supersededBy,
+      constrains: [],
+      warnings: v.warnings.filter((w): w is { code: WorkWarningCode; message: string } => (WORK_WARNING_CODES as readonly string[]).includes(w.code)),
+    });
+    return h.node;
+  };
+  /** The decision kind a work kind names, when it is among the kinds read. */
+  const decisionKindOf = (k: LoadedKind): LoadedKind | undefined => {
+    const file = realpathOr(resolve(dirname(k.records!.loaded.file), k.records!.loaded.kind.work!.decisions));
+    return kinds.find((x) => x.records && !x.records.loaded.kind.work && realpathOr(x.records.loaded.file) === file);
+  };
+  /** The node ids of the decisions a work item implements, among the decisions read. */
+  const implementedIds = (h: WorkHit): string[] => {
+    const dk = decisionKindOf(h.kind);
+    if (!dk) return [];
+    return idList(h.view.data, workSpec(h).implements)
+      .map((d) => decisionById.get(`${dk.records!.loaded.kind.name}/${d}`))
+      .filter((x): x is { view: RecordView; kind: LoadedKind } => x !== undefined)
+      .map((x) => decisionId(x.kind, x.view.id!));
+  };
+  /** The work items implementing a decision, leaving out dropped ones: a closed state other than done. */
+  const implementersOf = (d: DecisionNode): WorkHit[] =>
+    workAll.filter((h) => {
+      const kind = h.kind.records!.loaded.kind;
+      const dropped = h.view.state !== null && h.view.state !== kind.work!.done && (kind.closedStates ?? []).includes(h.view.state);
+      return !dropped && implementedIds(h).includes(d.id);
+    });
+  const workCovering: WorkHit[] = [];
+  for (const h of workAll) {
+    const matched = matchConstrains(h.kind, h.view);
+    if (matched.length === 0) continue;
+    const node = workNode(h);
+    for (const m of matched) {
+      edges.push({ kind: "constrains", from: node.id, to: m.to, granularity: m.granularity, entry: m.entry });
+      if (m.to === rid || m.granularity === "contract") node.constrains.push({ entry: m.entry, granularity: m.granularity });
+    }
+    if (node.constrains.length > 0) workCovering.push(h);
+  }
+  for (const h of workAll.filter((x) => x.node)) {
+    for (const id of implementedIds(h)) {
+      const hit = decisionById.get(id.slice("record:".length))!;
+      edges.push({ kind: "implements", from: h.node!.id, to: decisionNode(hit.kind, hit.view).id });
+    }
+    for (const n of idList(h.view.data, workSpec(h).needs)) {
+      const hit = workByKey.get(`${h.kind.records!.loaded.kind.name}/${n}`);
+      if (hit) edges.push({ kind: "needs", from: h.node!.id, to: workNode(hit).id });
+    }
+  }
+  const workWindows = new Map<string, { from: Set<string>; until: Set<string> | null }>();
+  if (rev) {
+    for (const h of workCovering) {
+      const kind = h.kind.records!.loaded.kind;
+      const added = addingCommit(top, rev, h.view.path);
+      const closing = kind.stateField ? closingCommit(top, rev, h.view.path, kind.stateField, kind.closedStates ?? []) : null;
+      const until = closing ? descendants(top, closing, rev) : null;
+      if (closing) until!.delete(closing);
+      workWindows.set(h.node!.id, { from: added ? descendants(top, added, rev) : new Set(), until });
+    }
+  }
+  const inWorkWindow = (h: WorkHit, sha: string) => {
+    const w = workWindows.get(h.node!.id);
+    return !!w && w.from.has(sha) && !w.until?.has(sha);
+  };
+
   const coveredAt = (sha: string, granularities: Granularity[]) =>
     covering.filter((c) => {
       if (!c.node.constrains.some((x) => granularities.includes(x.granularity))) return false;
@@ -905,6 +1117,10 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
       for (const w of inWindow) edges.push({ kind: "within", from: c.id, to: w.node.id, state: ownWork(j, w.node) ? "decided" : "decided-by-window" });
       c.state = inWindow.length === 0 ? "undecided" : inWindow.some((w) => ownWork(j, w.node)) ? "decided" : "decided-by-window";
     }
+    // A commit in a work item's window is worked; its own state still comes from decisions (#2683).
+    for (const h of workCovering) {
+      if (h.node!.constrains.some((x) => x.granularity === "path") && inWorkWindow(h, t.sha)) edges.push({ kind: "within", from: c.id, to: h.node!.id, state: "worked" });
+    }
     if (readsRecords && c.state === "undecided") {
       find("intent-commit-undecided", `${t.sha.slice(0, 8)} changed the region when no decision constrained ${region.path} by path`, [c.id, rid]);
     }
@@ -933,6 +1149,37 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     }
   }
 
+  // Findings about work items (#2683).
+  if (readsWork) {
+    for (const c of covering) {
+      if (c.node.supersededBy !== null || !isDecided(c.kind.records!.loaded.kind, c.node.state)) continue;
+      if (implementersOf(c.node).length > 0) continue;
+      const w = windows.get(c.node.id);
+      if (w && touched.some((t) => w.from.has(t.sha) && !w.until?.has(t.sha))) continue;
+      find("intent-decision-unimplemented", `${c.node.record} is ${c.node.state} and constrains ${region.path}, and no work item that is not dropped implements it, and no commit changed the region in its window`, [c.node.id, rid]);
+    }
+    for (const h of workCovering) {
+      const node = h.node!;
+      if (node.blockedBy.length === 0) continue;
+      const worked = touched.filter((t) => inWorkWindow(h, t.sha));
+      if (worked.length === 0) continue;
+      const waiting = node.blockedBy.map((b) => `${b.id} (${b.state ?? "unknown"})`).join(", ");
+      const blockers = node.blockedBy.map((b) => workByKey.get(`${node.recordKind}/${b.id}`)).filter((x): x is WorkHit => x !== undefined).map((x) => workNode(x).id);
+      find("intent-work-blocked", `${node.record} has ${worked.length} ${worked.length === 1 ? "commit" : "commits"} in its window while it waits on ${waiting}`, [node.id, ...worked.map((t) => `commit:${t.sha}`), ...blockers]);
+    }
+    for (const d of [...nodes.values()].filter((n): n is DecisionNode => n.kind === "decision")) {
+      const own = edges.filter((e) => e.kind === "within" && e.to === d.id && e.state === "decided").map((e) => e.from);
+      if (own.length === 0) continue;
+      const impl = implementersOf(d);
+      if (impl.length === 0 || impl.some((h) => h.view.state === workSpec(h).done)) continue;
+      find(
+        "intent-work-open-decided-code",
+        `${own.length} ${own.length === 1 ? "commit" : "commits"} in ${region.path} ${own.length === 1 ? "is" : "are"} ${d.record}'s own work, and ${impl.map((h) => `${h.view.id} is ${h.view.state ?? "stateless"}`).join(", ")}: the code says done and the queue says not`,
+        [d.id, ...own, ...impl.map((h) => workNode(h).id)],
+      );
+    }
+  }
+
   // 5. Links: the declared member links that touch the region's member, read in source.
   if (member) {
     let rows: LinkTableRow[] = [];
@@ -974,6 +1221,46 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     const concerns = [...new Set([commit, ...refs.map(resolveRef).filter((x): x is string => x !== undefined)])];
     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
+  // plugin's finding, is about. A done item whose gap still fires here gets
+  // work-done-gap-open.
+  if (readsWork) {
+    // Implementing a decision closes the gaps between it and the code or its
+    // 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 fromGap = (h: WorkHit, code: string): boolean => {
+      const src = gapSource(h.view.data);
+      if (src === null || src.finding !== code) return false;
+      const parsed = parseRegion(src.region);
+      if ("error" in parsed) return false;
+      const kindPrefix = h.kind.records!.workspaceRoot === "." ? "" : h.kind.records!.workspaceRoot;
+      const full = joinPath(kindPrefix, parsed.path);
+      const contains = (a: string, b: string) => a === b || a === "" || b.startsWith(`${a}/`);
+      if (!contains(full, regionFull) && !contains(regionFull, full)) return false;
+      if (full === regionFull && parsed.lines && region.lines) return parsed.lines.start <= region.lines.end && region.lines.start <= parsed.lines.end;
+      return true;
+    };
+    for (const f of findings) {
+      const by: WorkHit[] = [];
+      for (const h of workAll) {
+        const gap = fromGap(h, f.code);
+        const viaDecision = (CLOSED_BY_IMPLEMENTING.has(f.code) || isPluginCode(f.code)) && implementedIds(h).some((id) => f.concerns.includes(id));
+        if (gap || viaDecision) by.push(h);
+        if (gap && h.view.state === workSpec(h).done) {
+          const node = workNode(h);
+          if (!node.warnings.some((w) => w.code === "work-done-gap-open")) {
+            node.warnings.push({ code: "work-done-gap-open", message: `${node.record} is ${h.view.state}, and ${f.code}, the gap it came from, still fires on ${region.path}` });
+          }
+        }
+      }
+      f.addressed = by.length > 0;
+      f.addressedBy = by.map((h) => ({ id: h.view.id!, state: h.view.state }));
+      for (const h of by) edges.push({ kind: "addressed-by", from: f.id, to: workNode(h).id });
+    }
+  }
   for (const f of findings) nodes.set(f.id, f);
   const all = [...nodes.values()];
   return {