@intentius/chant 0.84.0 → 0.85.0

package/src/workspace/intent-cli.ts

@@ -3,7 +3,9 @@
  * (#2651): the intent graph over one region (`intent.ts`), printed as JSON
  * with `--json` or as a walk, one line per node, in the order of #2650
  * section B: the region, its decisions, their artifacts, the commits, and the
- * findings.
+ * 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).
  */
 
 import { resolve } from "node:path";
@@ -25,6 +27,28 @@ function ofKind<K extends IntentNode["kind"]>(doc: Result, kind: K): Extract<Int
 
 const short = (sha: string | null | undefined) => (sha ? sha.slice(0, 8) : "none");
 
+/** What the walk asks about a commit made inside a decision's window that is not the decision's own work (#2650 B4, step 5). */
+export const IN_WINDOW_QUESTION = "is this drift, a superseding decision nobody wrote down, or the decision being wrong?";
+
+/** The commits inside a decision's window, under its line, then the question once when any is not its own work. */
+function withinLines(doc: Result, d: DecisionNode): string[] {
+  const within = doc.edges.filter((e): e is Extract<IntentEdge, { kind: "within" }> => e.kind === "within" && e.to === d.id);
+  const out: string[] = [];
+  for (const e of within) {
+    const c = doc.nodes.find((n): n is CommitNode => n.kind === "commit" && n.id === e.from);
+    if (!c) continue;
+    const unit = edgesFrom(doc, c.id, "produced-by")
+      .map((p) => doc.nodes.find((n) => n.id === p.to))
+      .map((n) => (n && "ref" in n ? n.ref : undefined))
+      .filter(Boolean);
+    const by = unit.length > 0 ? `unit ${unit.join(", ")}` : "no unit";
+    const label = e.state === "decided" ? "decided " : "within  ";
+    out.push(`  ${label}  ${short(c.sha)} ${c.subject}; ${by}${e.state === "decided" ? `, ${d.record}'s own work` : `, in ${d.record}'s window and not its work`}`);
+  }
+  if (within.some((e) => e.state === "decided-by-window")) out.push(`  ask       ${IN_WINDOW_QUESTION}`);
+  return out;
+}
+
 function decisionLine(d: DecisionNode): string {
   const via = d.constrains.length > 0 ? d.constrains.map((c) => `${c.entry} (${c.granularity})`).join(", ") : "through supersession only";
   const by = d.decided_by ? `, decided by ${d.decided_by}${d.decided_on ? ` on ${d.decided_on}` : ""}` : "";
@@ -63,7 +87,7 @@ 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));
+  for (const d of ofKind(doc, "decision")) out.push(decisionLine(d), ...withinLines(doc, d));
   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")) {

package/src/workspace/intent-joins.ts

@@ -18,9 +18,19 @@
  * 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
  * something only because a kind file said so.
+ *
+ * Two parts of a join's answer carry meaning core acts on (#2656). A unit or
+ * contract may list `decisions`, the ids of the decision records it carries
+ * out; a commit whose unit or contract names a decision is that decision's own
+ * work. The function form may also return `findings`, each a code in the
+ * kind's own namespace (`plugin:<name>:<code>`), a message and the refs it is
+ * 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.
  */
 
 import { z } from "zod";
+import { isPluginCode } from "./reason-codes";
 
 /** A commit as the hook sees it. */
 export interface IntentCommit {
@@ -41,12 +51,25 @@ export interface CommitJoinContext {
   at: string | null;
 }
 
-/** A plugin's unit, contract or evidence: an id and whatever fields the plugin records. */
+/**
+ * A plugin's unit, contract or evidence: an id and whatever fields the plugin
+ * records. On a unit or contract, `decisions`, a list of record ids, names the
+ * decisions it carries out (#2656).
+ */
 export interface JoinedEntity {
   id: string;
   [field: string]: unknown;
 }
 
+/** A finding a plugin contributes for one commit (#2656). */
+export interface PluginFinding {
+  /** `plugin:<name>:<code>`, where `<name>` is 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. */
+  refs?: string[];
+}
+
 /** What a join says about one commit. Every part is optional. */
 export interface CommitJoin {
   /** The unit of work that produced the commit. */
@@ -57,6 +80,8 @@ export interface CommitJoin {
   evidence?: JoinedEntity | JoinedEntity[];
   /** Trailer keys on this commit that claim who wrote it, which the plugin vouches for. */
   authorship?: string[];
+  /** Findings about this commit, in the kind's own code namespace. Function form only. */
+  findings?: PluginFinding[];
 }
 
 export type CommitJoinsFunction = (commit: IntentCommit, context: CommitJoinContext) => CommitJoin | null | undefined | Promise<CommitJoin | null | undefined>;
@@ -135,8 +160,17 @@ export function joinByData(data: CommitJoinsData, commit: IntentCommit, context:
   return out;
 }
 
-/** Run a kind's joins for one commit, checking what a function returns. */
-export async function runCommitJoins(joins: CommitJoins, commit: IntentCommit, context: CommitJoinContext): Promise<CommitJoin> {
+/** The record ids a unit or contract says it carries out: its `decisions` field, when that is a list of strings. */
+export function entityDecisions(entity: JoinedEntity | undefined): string[] {
+  const list = entity?.decisions;
+  return Array.isArray(list) ? list.filter((d): d is string => typeof d === "string" && d !== "") : [];
+}
+
+/**
+ * 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.
+ */
+export async function runCommitJoins(joins: CommitJoins, commit: IntentCommit, context: CommitJoinContext, name: string): Promise<CommitJoin> {
   if (joins.form === "data") return joinByData(joins.data, commit, context);
   const result = await joins.join(commit, context);
   if (result === null || result === undefined) return {};
@@ -161,5 +195,16 @@ export async function runCommitJoins(joins: CommitJoins, commit: IntentCommit, c
     if (!Array.isArray(result.authorship) || !result.authorship.every((k) => typeof k === "string")) throw new Error("commitJoins returned authorship that is not a list of trailer keys");
     out.authorship = result.authorship;
   }
+  if (result.findings !== undefined && result.findings !== null) {
+    if (!Array.isArray(result.findings)) throw new Error("commitJoins returned findings that are not a list");
+    out.findings = result.findings.map((f: unknown) => {
+      if (f === null || typeof f !== "object" || Array.isArray(f)) throw new Error("commitJoins returned a finding that is not an object");
+      const { code, message, refs } = f as Record<string, unknown>;
+      if (!isPluginCode(code, name)) throw new Error(`commitJoins returned the finding code ${JSON.stringify(code)}, and a plugin's codes are plugin:${name}:<code>, with <code> in lower case words joined by dashes`);
+      if (typeof message !== "string" || message === "") throw new Error(`commitJoins returned the finding ${code} with no message`);
+      if (refs !== undefined && (!Array.isArray(refs) || !refs.every((r) => typeof r === "string"))) throw new Error(`commitJoins returned the finding ${code} with refs that are not a list of strings`);
+      return { code, message, refs: (refs as string[] | undefined) ?? [] };
+    });
+  }
   return out;
 }

package/src/workspace/intent.schema.json

@@ -101,7 +101,7 @@
         "error": false,
         "kinds": {
           "type": "array",
-          "description": "Each --kind file, in order: the record kind it reads, if any, and the form of its commitJoins export, if any.",
+          "description": "Each --kind file, in order: its name, the record kind it reads, if any, and the form of its commitJoins export, if any.",
           "items": {
             "type": "object",
             "required": [
@@ -114,6 +114,10 @@
                 "type": "string",
                 "description": "From the repository root."
               },
+              "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."
+              },
               "records": {
                 "type": [
                   "string",
@@ -364,7 +368,7 @@
       }
     },
     "commit": {
-      "description": "A commit that touched the region. Linked from the region by a touched-by edge.",
+      "description": "A commit that touched the region. Linked from the region by a touched-by edge, and to each decision whose path window it falls in by a within edge.",
       "type": "object",
       "required": [
         "id",
@@ -466,6 +470,15 @@
             }
           ],
           "description": "For a line-range region, the ranges the commit changed within it, numbered in the commit's own version of the file. Null otherwise."
+        },
+        "state": {
+          "enum": [
+            "decided",
+            "decided-by-window",
+            "undecided",
+            null
+          ],
+          "description": "How the decisions constraining the region by path relate to the commit (#2656). decided: it falls inside a decision's window and that decision's own unit made it. decided-by-window: it falls inside a window, and it is not the decision's own work, so the person judges it. undecided: outside every window, with the finding intent-commit-undecided. null: no record kind was read. Added within version 1, so an older document may lack it."
         }
       }
     },
@@ -812,7 +825,7 @@
       }
     },
     "finding": {
-      "description": "A gap the walk found. Findings are nodes so a reader can draw them and a test can assert them; the tool asks, and never answers.",
+      "description": "A gap the walk found. Findings are nodes so a reader can draw them and a test can assert them; the tool asks, and never answers. A plugin's commitJoins may add findings of its own, with a code in its namespace (#2656).",
       "type": "object",
       "required": [
         "id",
@@ -830,19 +843,28 @@
           "const": "finding"
         },
         "code": {
-          "enum": [
-            "intent-commit-undecided",
-            "intent-commit-bare",
-            "intent-pin-drifted",
-            "intent-pin-missing",
-            "intent-artifact-unpinned",
-            "intent-decision-superseded-live",
-            "intent-decision-provisional",
-            "intent-constraint-coarse",
-            "intent-constraint-lost",
-            "intent-evidence-unpinned",
-            "intent-trailer-unverified",
-            "intent-region-unconstrained"
+          "anyOf": [
+            {
+              "enum": [
+                "intent-commit-undecided",
+                "intent-commit-bare",
+                "intent-pin-drifted",
+                "intent-pin-missing",
+                "intent-artifact-unpinned",
+                "intent-decision-superseded-live",
+                "intent-decision-provisional",
+                "intent-constraint-coarse",
+                "intent-constraint-lost",
+                "intent-evidence-unpinned",
+                "intent-trailer-unverified",
+                "intent-region-unconstrained"
+              ]
+            },
+            {
+              "type": "string",
+              "pattern": "^plugin:[^:\\s]+:[a-z0-9]+(-[a-z0-9]+)*$",
+              "description": "A plugin's own code, plugin:<name>:<code>, where <name> is the kind's name in kinds. Outside the closed list: the plugin owns its namespace."
+            }
           ]
         },
         "message": {
@@ -854,11 +876,22 @@
             "type": "string"
           },
           "description": "The ids of the nodes the finding is about."
+        },
+        "plugin": {
+          "type": "string",
+          "description": "For a plugin's finding: the kind file that returned it, as in kinds."
+        },
+        "refs": {
+          "type": "array",
+          "items": {
+            "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."
         }
       }
     },
     "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.",
+      "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.",
       "oneOf": [
         {
           "$ref": "#/$defs/constrainsEdge"
@@ -869,6 +902,9 @@
         {
           "$ref": "#/$defs/touchedEdge"
         },
+        {
+          "$ref": "#/$defs/withinEdge"
+        },
         {
           "$ref": "#/$defs/plainEdge"
         }
@@ -1073,6 +1109,33 @@
           ]
         }
       }
+    },
+    "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.",
+      "type": "object",
+      "required": [
+        "kind",
+        "from",
+        "to",
+        "state"
+      ],
+      "properties": {
+        "from": {
+          "type": "string"
+        },
+        "to": {
+          "type": "string"
+        },
+        "kind": {
+          "const": "within"
+        },
+        "state": {
+          "enum": [
+            "decided",
+            "decided-by-window"
+          ]
+        }
+      }
     }
   }
 }

package/src/workspace/intent.test.ts

@@ -7,7 +7,12 @@
  *   `path:app/server.mjs` and pins the spec by hash.
  * - c2 adds `app/server.mjs` inside dec-001's window, with a `Unit: U-0001`
  *   trailer that the fixture plugin maps to a unit, a contract and evidence,
- *   and a `Made-By` trailer the plugin says claims authorship.
+ *   and a `Made-By` trailer the plugin says claims authorship. U-0001's
+ *   record names dec-001, so c2 is dec-001's own work.
+ * - c2b edits `app/server.mjs` inside dec-001's window too, from unit
+ *   U-0002, whose record names no decision and which changed its contract's
+ *   criteria. It is decided by the window only (#2656), and the plugin
+ *   returns a finding for it in its own namespace, `plugin:units:`.
  * - c3 adds dec-002, which supersedes dec-001, pins the spec at the same hash
  *   and constrains `member:design` only.
  * - c4 edits `app/server.mjs` after that, with no decision covering it.
@@ -59,11 +64,15 @@ export function commitJoins(commit, context) {
   if (!id) return undefined;
   if (id === "U-BROKEN") throw new Error("no such unit");
   const unit = JSON.parse(context.read(\`units/\${id}.json\`));
+  if (unit.badCode) return { findings: [{ code: "plugin:other:x", message: "wrong namespace" }] };
   return {
-    unit: { id, role: unit.role, outcome: unit.outcome },
+    unit: { id, role: unit.role, outcome: unit.outcome, ...(unit.decisions ? { decisions: unit.decisions } : {}) },
     contract: { id: unit.contract, status: "closed" },
     evidence: [{ id: "E-1", ok: true }],
     authorship: commit.trailers["Made-By"] ? ["Made-By"] : [],
+    findings: unit.criteriaChanged
+      ? [{ code: "plugin:units:criteria-changed-undecided", message: \`\${unit.contract} changed its criteria in this commit with no decision\`, refs: [commit.sha, unit.contract, "dec-001", "no-such-thing"] }]
+      : [],
   };
 }
 `;
@@ -72,7 +81,8 @@ export function commitJoins(commit, context) {
 const DATA_PLUGIN = `export const commitJoins = { trailers: { unit: "Unit" }, records: { unit: "units/{id}.json" }, authorship: ["Made-By"] };\n`;
 
 const SERVER_1 = "// the app\nexport const status = 'Running.';\nexport const port = 8080;\n";
-const SERVER_2 = "// the app\nexport const status = 'Up.';\nexport const port = 8080;\n";
+const SERVER_1B = "// the app\nexport const status = 'Running.';\nexport const port = 9090;\n";
+const SERVER_2 = "// the app\nexport const status = 'Up.';\nexport const port = 9090;\n";
 
 let root: string;
 const sha: Record<string, string> = {};
@@ -106,11 +116,15 @@ beforeAll(() => {
     "plugins/units.kind.mjs": PLUGIN,
     "plugins/units-data.kind.mjs": DATA_PLUGIN,
     "plugins/empty.kind.mjs": "export const nothing = 1;\n",
-    "units/U-0001.json": JSON.stringify({ role: "implement", contract: "C-001", outcome: "done" }),
+    "units/U-0001.json": JSON.stringify({ role: "implement", contract: "C-001", outcome: "done", decisions: ["dec-001"] }),
+    "units/U-0002.json": JSON.stringify({ role: "implement", contract: "ctr-002", outcome: "done", criteriaChanged: true }),
+    "units/U-BAD.json": JSON.stringify({ badCode: true }),
   });
   sha.c1 = commit(["decide the server"]);
   writeFiles(root, { "app/server.mjs": SERVER_1 });
   sha.c2 = commit(["add the server", "Unit: U-0001\nMade-By: agent"]);
+  writeFiles(root, { "app/server.mjs": SERVER_1B });
+  sha.c2b = commit(["move the port", "Unit: U-0002"]);
   writeFiles(root, { "decisions/dec-002-design.md": decision("dec-002", { constrains: ["member:design"], evidence: [pin], supersedes: ["dec-001"] }) });
   sha.c3 = commit(["move the decision to the design member"]);
   writeFiles(root, { "app/server.mjs": SERVER_2 });
@@ -139,8 +153,8 @@ describe("the intent graph of app/server.mjs (#2651)", () => {
     expect(doc).toMatchObject({ contract: 1, at: null, workspace: { name: "studio", root: "." }, region: "region:app/server.mjs" });
     expect(doc.history).toEqual({ rev: sha.c4, follows: "file", shallow: false });
     expect(doc.kinds).toEqual([
-      { file: KIND, records: "decision", joins: null },
-      { file: "plugins/units.kind.mjs", records: null, joins: "function" },
+      { file: KIND, name: "decision", records: "decision", joins: null },
+      { file: "plugins/units.kind.mjs", name: "units", records: null, joins: "function" },
     ]);
     expect(doc.reasons).toEqual([]);
 
@@ -148,10 +162,13 @@ describe("the intent graph of app/server.mjs (#2651)", () => {
       "region:app/server.mjs",
       "member:app",
       `commit:${sha.c4}`,
+      `commit:${sha.c2b}`,
+      "unit:U-0002",
+      "contract:ctr-002",
+      "evidence:E-1",
       `commit:${sha.c2}`,
       "unit:U-0001",
       "contract:C-001",
-      "evidence:E-1",
       "record:decision/dec-001",
       "record:decision/dec-002",
       "artifact:design/screens/home.json",
@@ -159,6 +176,7 @@ describe("the intent graph of app/server.mjs (#2651)", () => {
       "finding:intent-commit-bare:1",
       "finding:intent-decision-superseded-live:1",
       "finding:intent-trailer-unverified:1",
+      "finding:plugin:units:criteria-changed-undecided:1",
     ]);
 
     expect(node(doc, "region:app/server.mjs")).toEqual({ id: "region:app/server.mjs", kind: "region", path: "app/server.mjs", lines: null, member: "app", at: null, type: "file", generated: false, node: null });
@@ -172,9 +190,13 @@ describe("the intent graph of app/server.mjs (#2651)", () => {
       pullRequest: null,
       signature: { level: "unattested" },
       lines: null,
+      // U-0001's record names dec-001: the decision's own work.
+      state: "decided",
     });
-    expect(node(doc, `commit:${sha.c4}`)).toMatchObject({ subject: "tweak the status line", trailers: {} });
-    expect(node(doc, "unit:U-0001")).toEqual({ id: "unit:U-0001", kind: "unit", ref: "U-0001", plugin: "plugins/units.kind.mjs", data: { role: "implement", outcome: "done" } });
+    // Inside dec-001's window, from a unit that names no decision (#2656).
+    expect(node(doc, `commit:${sha.c2b}`)).toMatchObject({ subject: "move the port", state: "decided-by-window" });
+    expect(node(doc, `commit:${sha.c4}`)).toMatchObject({ subject: "tweak the status line", trailers: {}, state: "undecided" });
+    expect(node(doc, "unit:U-0001")).toEqual({ id: "unit:U-0001", kind: "unit", ref: "U-0001", plugin: "plugins/units.kind.mjs", data: { role: "implement", outcome: "done", decisions: ["dec-001"] } });
     expect(node(doc, "contract:C-001")).toMatchObject({ kind: "contract", ref: "C-001", data: { status: "closed" } });
     expect(node(doc, "evidence:E-1")).toMatchObject({ kind: "evidence", ref: "E-1", data: { ok: true } });
     expect(node(doc, "record:decision/dec-001")).toMatchObject({
@@ -206,6 +228,10 @@ describe("the intent graph of app/server.mjs (#2651)", () => {
 
     expect(edges(doc)).toEqual([
       `touched-by region:app/server.mjs -> commit:${sha.c4}`,
+      `touched-by region:app/server.mjs -> commit:${sha.c2b}`,
+      `produced-by commit:${sha.c2b} -> unit:U-0002`,
+      "serves unit:U-0002 -> contract:ctr-002",
+      "cites-evidence unit:U-0002 -> evidence:E-1",
       `touched-by region:app/server.mjs -> commit:${sha.c2}`,
       `produced-by commit:${sha.c2} -> unit:U-0001`,
       "serves unit:U-0001 -> contract:C-001",
@@ -214,28 +240,82 @@ describe("the intent graph of app/server.mjs (#2651)", () => {
       "supersedes record:decision/dec-002 -> record:decision/dec-001",
       "pins record:decision/dec-001 -> artifact:design/screens/home.json (pinned)",
       "pins record:decision/dec-002 -> artifact:design/screens/home.json (stale)",
+      `within commit:${sha.c2b} -> record:decision/dec-001`,
+      `within commit:${sha.c2} -> record:decision/dec-001`,
+    ]);
+    expect(doc.edges.filter((e) => e.kind === "within")).toEqual([
+      { kind: "within", from: `commit:${sha.c2b}`, to: "record:decision/dec-001", state: "decided-by-window" },
+      { kind: "within", from: `commit:${sha.c2}`, to: "record:decision/dec-001", state: "decided" },
     ]);
 
-    // c2 falls inside dec-001's window (from c1 until c3); c4 comes after it.
+    // c2 and c2b fall inside dec-001's window (from c1 until c3), so neither is
+    // intent-commit-undecided; c4 comes after it. The plugin's finding is about
+    // c2b, and its refs resolve to the nodes they name, except the one that
+    // names nothing in the graph.
     expect(findings(doc)).toEqual([
       ["intent-commit-undecided", [`commit:${sha.c4}`, "region:app/server.mjs"]],
       ["intent-commit-bare", [`commit:${sha.c4}`]],
       ["intent-decision-superseded-live", ["region:app/server.mjs", "record:decision/dec-001"]],
       ["intent-trailer-unverified", [`commit:${sha.c2}`]],
+      ["plugin:units:criteria-changed-undecided", [`commit:${sha.c2b}`, "contract:ctr-002", "record:decision/dec-001"]],
     ]);
-    expect(doc.summary).toEqual({ commits: 2, decisions: 2, artifacts: 1, findings: 4 });
+    expect(node(doc, "finding:plugin:units:criteria-changed-undecided:1")).toEqual({
+      id: "finding:plugin:units:criteria-changed-undecided:1",
+      kind: "finding",
+      code: "plugin:units:criteria-changed-undecided",
+      message: "ctr-002 changed its criteria in this commit with no decision",
+      concerns: [`commit:${sha.c2b}`, "contract:ctr-002", "record:decision/dec-001"],
+      plugin: "plugins/units.kind.mjs",
+      refs: [sha.c2b, "ctr-002", "dec-001", "no-such-thing"],
+    });
+    expect(doc.summary).toEqual({ commits: 3, decisions: 2, artifacts: 1, findings: 5 });
   });
 
-  test("the text walk runs region, decisions, artifacts, commits, findings, one line each", async () => {
+  test("the text walk runs region, decisions with their in-window commits, artifacts, commits, findings, one line each", async () => {
     const text = formatIntent(await walk("app/server.mjs"));
     const lines = text.split("\n");
-    expect(lines.map((l) => l.trim().split(/\s+/)[0])).toEqual(["region", "decision", "decision", "artifact", "commit", "commit", "unit", "contract", "evidence", "finding", "finding", "finding", "finding", "2"]);
+    expect(lines.map((l) => l.trim().split(/\s+/)[0])).toEqual([
+      "region",
+      "decision",
+      "within",
+      "decided",
+      "ask",
+      "decision",
+      "artifact",
+      "commit",
+      "commit",
+      "unit",
+      "contract",
+      "evidence",
+      "commit",
+      "unit",
+      "contract",
+      "evidence",
+      "finding",
+      "finding",
+      "finding",
+      "finding",
+      "finding",
+      "3",
+    ]);
     expect(lines[0]).toBe("region    app/server.mjs (file, member app) in the working tree");
     expect(lines[1]).toContain("dec-001 decided, superseded by dec-002");
     expect(lines[1]).toContain("path:app/server.mjs (path)");
-    expect(lines[3]).toBe(`artifact  design/screens/home.json stale; pinned by dec-001 at ${HOME_SHA.slice(0, 8)} (pinned), dec-002 at ${HOME_SHA.slice(0, 8)} (stale); now ${HOME_SHA.slice(0, 8)}`);
-    expect(lines[4]).toContain(`${sha.c4.slice(0, 8)} `);
-    expect(lines.at(-1)).toBe("2 commits, 2 decisions, 1 artifacts, 4 findings");
+    // The in-window commits under their decision, and the question once (#2656, #2650 B).
+    expect(lines[2]).toBe(`  within    ${sha.c2b.slice(0, 8)} move the port; unit U-0002, in dec-001's window and not its work`);
+    expect(lines[3]).toBe(`  decided   ${sha.c2.slice(0, 8)} add the server; unit U-0001, dec-001's own work`);
+    expect(lines[4]).toBe("  ask       is this drift, a superseding decision nobody wrote down, or the decision being wrong?");
+    expect(lines[6]).toBe(`artifact  design/screens/home.json stale; pinned by dec-001 at ${HOME_SHA.slice(0, 8)} (pinned), dec-002 at ${HOME_SHA.slice(0, 8)} (stale); now ${HOME_SHA.slice(0, 8)}`);
+    expect(lines[7]).toContain(`${sha.c4.slice(0, 8)} `);
+    expect(lines.at(-2)).toBe("finding   plugin:units:criteria-changed-undecided: ctr-002 changed its criteria in this commit with no decision");
+    expect(lines.at(-1)).toBe("3 commits, 2 decisions, 1 artifacts, 5 findings");
+  });
+
+  test("a decision whose in-window commits are all its own work asks nothing", async () => {
+    const doc = await walk("app/server.mjs", { at: sha.c2 });
+    const text = formatIntent(doc);
+    expect(text).toContain(`  decided   ${sha.c2.slice(0, 8)} add the server`);
+    expect(text).not.toContain("  ask ");
   });
 
   test("a line range follows the lines with git log -L, and names the lines each commit changed", async () => {
@@ -250,15 +330,27 @@ describe("the intent graph of app/server.mjs (#2651)", () => {
 
   test("the data form of commitJoins joins the same unit, with no plugin code", async () => {
     const doc = await walk("app/server.mjs", { kinds: [KIND, "plugins/units-data.kind.mjs"] });
-    expect(doc.kinds[1]).toEqual({ file: "plugins/units-data.kind.mjs", records: null, joins: "data" });
-    expect(node(doc, "unit:U-0001")).toEqual({ id: "unit:U-0001", kind: "unit", ref: "U-0001", plugin: "plugins/units-data.kind.mjs", data: { role: "implement", contract: "C-001", outcome: "done" } });
+    expect(doc.kinds[1]).toEqual({ file: "plugins/units-data.kind.mjs", name: "units-data", records: null, joins: "data" });
+    expect(node(doc, "unit:U-0001")).toEqual({
+      id: "unit:U-0001",
+      kind: "unit",
+      ref: "U-0001",
+      plugin: "plugins/units-data.kind.mjs",
+      data: { role: "implement", contract: "C-001", outcome: "done", decisions: ["dec-001"] },
+    });
     expect(doc.edges).toContainEqual({ kind: "produced-by", from: `commit:${sha.c2}`, to: "unit:U-0001" });
+    // The unit record's decisions field makes c2 dec-001's own work in the data form too.
+    expect(node(doc, `commit:${sha.c2}`)).toMatchObject({ state: "decided" });
+    expect(node(doc, `commit:${sha.c2b}`)).toMatchObject({ state: "decided-by-window" });
+    expect(findings(doc).map(([c]) => c)).not.toContain("plugin:units:criteria-changed-undecided");
     expect(findings(doc).map(([c]) => c)).toContain("intent-trailer-unverified");
   });
 
   test("without --kind there are no decisions, so no decision findings", async () => {
     const doc = await walk("app/server.mjs", { kinds: [] });
-    expect(doc.nodes.map((n) => n.kind)).toEqual(["region", "member", "commit", "commit"]);
+    expect(doc.nodes.map((n) => n.kind)).toEqual(["region", "member", "commit", "commit", "commit"]);
+    expect(doc.nodes.filter((n) => n.kind === "commit").map((n) => n.kind === "commit" && n.state)).toEqual([null, null, null]);
+    expect(doc.edges.filter((e) => e.kind === "within")).toEqual([]);
     expect(findings(doc)).toEqual([]);
   });
 
@@ -360,6 +452,17 @@ describe("findings the fixture does not raise (#2651)", () => {
     ),
   );
 
+  test(
+    "a commit whose unit serves a contract the decision constrains is the decision's own work (#2656)",
+    withFile("decisions/dec-001-server.md", decision("dec-001", { constrains: ["path:app/server.mjs", "ctr-002"], evidence: [pin] }), async () => {
+      const doc = await walk("app/server.mjs");
+      expect(doc.edges).toContainEqual({ kind: "constrains", from: "record:decision/dec-001", to: "contract:ctr-002", granularity: "contract", entry: "ctr-002" });
+      expect(node(doc, `commit:${sha.c2b}`)).toMatchObject({ state: "decided" });
+      expect(doc.edges).toContainEqual({ kind: "within", from: `commit:${sha.c2b}`, to: "record:decision/dec-001", state: "decided" });
+      expect(formatIntent(doc)).not.toContain("  ask ");
+    }),
+  );
+
   test(
     "a decision constraining an issue the region's commits name covers it at issue granularity",
     withFile("decisions/dec-003-issue.md", decision("dec-003", { constrains: ["acme/studio#12"] }), async () => {
@@ -406,7 +509,22 @@ describe("reads that fail, and parts that can't be read (#2651)", () => {
       if ("error" in doc) throw new Error(doc.error.message);
       expect(failed).toBe(true);
       expect(doc.reasons).toEqual([{ code: "intent-plugin-failed", message: expect.stringContaining("no such unit") }]);
-      expect(doc.summary.commits).toBe(3);
+      expect(doc.summary.commits).toBe(4);
+    } finally {
+      git(root, "reset", "-q", "--hard", sha.c4);
+    }
+  });
+
+  test("a plugin finding outside the kind's namespace is intent-plugin-failed (#2656)", async () => {
+    writeFiles(root, { "app/server.mjs": `${SERVER_2}// bad code\n` });
+    commit(["a finding in someone else's namespace", "Unit: U-BAD"]);
+    try {
+      const { doc, failed } = await intentGraph({ cwd: root, region: "app/server.mjs", kinds: [join(root, KIND), join(root, "plugins/units.kind.mjs")] });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(failed).toBe(true);
+      expect(doc.reasons).toEqual([{ code: "intent-plugin-failed", message: expect.stringContaining("plugin:units:<code>") }]);
+      expect(doc.nodes.some((n) => n.kind === "finding" && n.code === "plugin:other:x")).toBe(false);
     } finally {
       git(root, "reset", "-q", "--hard", sha.c4);
     }