@intentius/chant 0.85.0 → 0.87.0

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;
@@ -67,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. */
@@ -83,6 +91,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 +273,55 @@ 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. */
+  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 +329,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 +363,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 +467,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 +552,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 +603,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 +622,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 });
+      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 };
-        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 +688,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 +733,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 +771,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 +814,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 +823,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 +836,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) {
@@ -849,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))]);
@@ -885,6 +1005,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 +1135,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]);
     }
@@ -927,12 +1161,57 @@ 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)]);
     }
   }
 
+  // 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 +1253,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, 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) {
+    // 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", "intent-pin-stale"]);
+    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 {

package/src/workspace/ls.schema.json

@@ -43,6 +43,11 @@
                   "integrity": { "type": ["string", "null"] }
                 }
               }
+            },
+            "records": {
+              "description": "Added in contract 1 by #2680. The workspace's own record kinds, from the declaration's top-level records, in file order.",
+              "type": "array",
+              "items": { "$ref": "#/$defs/recordKind" }
             }
           }
         },
@@ -89,6 +94,11 @@
         "upstream": { "type": ["string", "null"] },
         "because": { "type": ["string", "null"] },
         "readable": { "type": "boolean", "description": "True exactly when reason is null." },
+        "records": {
+          "description": "Added in contract 1 by #2680. The record kinds the member declares, in file order. A kind that can't be loaded does not make the member unreadable.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/recordKind" }
+        },
         "reason": {
           "oneOf": [
             { "type": "null" },
@@ -107,6 +117,30 @@
       "then": { "type": "object", "properties": { "reason": { "type": "null" } } },
       "else": { "type": "object", "properties": { "reason": { "type": "object" } } }
     },
+    "recordKind": {
+      "description": "A record kind the declaration names (#2680). chant workspace records and graph --intent read every one of them when --kind is not given.",
+      "type": "object",
+      "required": ["name", "path", "kind", "reason"],
+      "properties": {
+        "name": { "type": ["string", "null"], "description": "The name the declaration gives the kind, else the kind file's own recordKind.name, else null when the file can't be loaded." },
+        "path": { "type": "string", "description": "The kind file, relative to the workspace root, with / separators." },
+        "kind": { "type": ["string", "null"], "description": "The kind file's recordKind.name, or null when it can't be loaded." },
+        "reason": {
+          "description": "Why the kind file can't be loaded, or null. The file is looked for in the tree read, the revision under --at, and loaded from the working tree.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["code", "message"],
+              "properties": {
+                "code": { "enum": ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch"] },
+                "message": { "type": "string" }
+              }
+            }
+          ]
+        }
+      }
+    },
     "group": {
       "type": "object",
       "required": ["name", "kind", "glob", "matches", "skipped", "reason"],