@intentius/chant 0.102.0 → 0.104.0

package/src/workspace/intent-patch-id.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Joining a commit to its agent run by patch-id when the trailer is gone (#3036).
+ *
+ * - app/server.ts; s-001 (path:app/server.ts) is decided and W-001 implements it.
+ * - On a side branch, run A (on W-001) records c1, which carries no trailer.
+ *   main cherry-picks it as p1: a new sha, the same patch-id.
+ * - Run B records b1 on the side branch; main then commits the same change
+ *   as p2 with `Chant-Run: run-c`: a trailer join, and content that matches
+ *   another run's recorded commit.
+ * - Run D records d1 and d2 on the side branch; main squashes them into one
+ *   commit, sq, whose patch-id is neither's.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, git, REPO, repo, writeFiles } from "./__fixtures__/contract-repo";
+import { intentGraph, type IntentDocument } from "./intent";
+import { formatIntent } from "./intent-cli";
+import { intentRecord } from "./intent-record";
+import intentRecordSchema from "./intent-record.schema.json";
+import intentSchema from "./intent.schema.json";
+import { parseFrontMatter } from "./records";
+import { runsWrite, workspaceRuns } from "./runs-cli";
+import runsSchema from "./runs.schema.json";
+
+const REF = join(REPO, "reference-workspace");
+const BASE = (() => {
+  const fm = parseFrontMatter(readFileSync(join(REF, "decisions", "ref-001-how-the-app-is-deployed.md"), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+})();
+const decision = (id: string, fields: Record<string, unknown>) => `---\n${JSON.stringify({ ...BASE, id, title: `Decision ${id}`, state: "decided", supersedes: [], evidence: [], reviews: [], ...fields }, null, 2)}\n---\n\n# ${id}\n`;
+const work = (id: string, fields: Record<string, unknown>) =>
+  `---\n${JSON.stringify({ schema: 1, id, title: `Work ${id}`, state: "open", implements: [], needs: [], constrains: [], evidence: [], opened_on: "2026-10-01", supersedes: [], ...fields }, null, 2)}\n---\n\n# ${id}\n\nWhat the work is.\n`;
+
+const LINES = ["// The app server.", "export const a = 0;", "export const b = 0;", "export const c = 0;", "export const d = 0;", "export const e = 0;"];
+const text = (lines: string[]) => `${lines.join("\n")}\n`;
+const edit = (lines: string[], at: number, to: string) => lines.map((l, i) => (i === at - 1 ? to : l));
+
+type Doc = Exclude<IntentDocument, { error: unknown }>;
+
+let root: string;
+const sha: Record<string, string> = {};
+
+function commit(message: string[]): string {
+  git(root, "add", "-A");
+  git(root, "commit", "-q", ...message.flatMap((m) => ["-m", m]));
+  return git(root, "rev-parse", "HEAD");
+}
+async function record(fields: object): Promise<void> {
+  const doc = await runsWrite({ verb: "record", fields: JSON.stringify(fields), cwd: root });
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+}
+async function walk(region: string): Promise<Doc> {
+  const { doc } = await intentGraph({ cwd: root, region });
+  contract(intentSchema).expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+beforeAll(async () => {
+  root = repo({
+    "chant.workspace.json": JSON.stringify({ name: "patch-id", schema: 1, records: [{ kind: "decisions/decision.kind.mjs" }, { kind: "work/work.kind.mjs" }], members: [{ name: "app", dir: "app", kind: "other", because: "the app" }] }),
+    "decisions/decision.kind.mjs": readFileSync(join(REF, "decisions", "decision.kind.mjs"), "utf-8"),
+    "decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
+    "work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
+    "work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
+    "app/server.ts": text(LINES),
+    "decisions/s-001-server.md": decision("s-001", { constrains: ["path:app/server.ts"] }),
+    "work/W-001-server.md": work("W-001", { implements: ["s-001"] }),
+  });
+  sha.c0 = commit(["the workspace"]);
+  const main = git(root, "rev-parse", "--abbrev-ref", "HEAD");
+
+  // The side branch, where the runs made their commits.
+  git(root, "checkout", "-q", "-b", "side");
+  writeFiles(root, { "app/server.ts": text(edit(LINES, 2, "export const a = 1;")) });
+  sha.c1 = commit(["a is 1"]);
+  writeFiles(root, { "app/server.ts": text(edit(edit(LINES, 2, "export const a = 1;"), 3, "export const b = 1;")) });
+  sha.b1 = commit(["b is 1"]);
+  git(root, "checkout", "-q", "-b", "squashed", sha.c0);
+  writeFiles(root, { "app/server.ts": text(edit(LINES, 5, "export const d = 1;")) });
+  sha.d1 = commit(["d is 1"]);
+  writeFiles(root, { "app/server.ts": text(edit(edit(LINES, 5, "export const d = 1;"), 6, "export const e = 1;")) });
+  sha.d2 = commit(["e is 1"]);
+  git(root, "checkout", "-q", main);
+
+  await record({ id: "run-a", harness: "claude-code", model: "claude-opus-5-5", unit: "W-001", startedAt: "2026-10-01T10:00:00Z", commits: [{ sha: sha.c1, hunks: [{ path: "app/server.ts", start: 2, end: 2 }] }] });
+  await record({ id: "run-b", harness: "claude-code", startedAt: "2026-10-01T11:00:00Z", commits: [sha.b1] });
+  await record({ id: "run-c", harness: "other", startedAt: "2026-10-01T11:30:00Z" });
+  await record({ id: "run-d", harness: "claude-code", startedAt: "2026-10-01T12:00:00Z", commits: [sha.d1, sha.d2] });
+
+  // main: a cherry-pick that keeps no trailer, a commit whose trailer names another run, and a squash.
+  git(root, "cherry-pick", sha.c1);
+  sha.p1 = git(root, "rev-parse", "HEAD");
+  writeFiles(root, { "app/server.ts": text(edit(edit(LINES, 2, "export const a = 1;"), 3, "export const b = 1;")) });
+  sha.p2 = commit(["b is 1, again", "Chant-Run: run-c"]);
+  git(root, "merge", "--squash", "-q", "squashed");
+  sha.sq = commit(["d and e (#7)"]);
+}, 60_000);
+afterAll(cleanScratch);
+
+describe("graph --intent joins by patch-id when the trailer is gone", () => {
+  test("a cherry-pick of a recorded commit joins its run by content", async () => {
+    const doc = await walk("app/server.ts:2");
+    expect(sha.p1).not.toBe(sha.c1);
+    expect(doc.edges.filter((e) => e.kind === "made-by" && e.from === `commit:${sha.p1}`)).toEqual([{ kind: "made-by", from: `commit:${sha.p1}`, to: "run:run-a", joinedBy: ["patch-id"], recordedAs: sha.c1 }]);
+    // The run's work item is carried as by any join, so the commit is s-001's own work.
+    expect(doc.edges).toContainEqual({ kind: "carries", from: `commit:${sha.p1}`, to: "record:work/W-001" });
+    expect(doc.edges).toContainEqual({ kind: "within", from: `commit:${sha.p1}`, to: "record:decision/s-001", state: "decided" });
+    // The why block marks the span and the run as joined by content. The recorded hunks are
+    // line numbers in the recorded commit, so a content join is not narrowed by them.
+    expect(doc.why.blame).toEqual([{ start: 2, end: 2, commit: `commit:${sha.p1}`, sha: sha.p1, runs: ["run:run-a"], narrowedBy: null, joinedBy: ["patch-id"] }]);
+    expect(doc.why.runs).toEqual([{ run: "run:run-a", lines: 1, commits: [`commit:${sha.p1}`], unit: { id: "W-001", kind: null, node: "record:work/W-001" }, decisions: ["record:decision/s-001"], joinedBy: ["patch-id"] }]);
+    expect(doc.why.decisions[0]).toMatchObject({ decision: "record:decision/s-001", relevance: "carried", lines: 1 });
+    expect(formatIntent(doc)).toContain(`run-a: claude-code/claude-opus-5-5, unpriced; joined by content, as ${sha.c1.slice(0, 8)}`);
+    expect(formatIntent(doc)).toContain("(joined by content)");
+  });
+
+  test("a trailer join is never overridden, and content that matches another run is a finding", async () => {
+    const doc = await walk("app/server.ts:3");
+    expect(doc.edges.filter((e) => e.kind === "made-by" && e.from === `commit:${sha.p2}`)).toEqual([{ kind: "made-by", from: `commit:${sha.p2}`, to: "run:run-c", joinedBy: ["trailer"] }]);
+    const conflict = doc.nodes.find((n) => n.kind === "finding" && n.code === "intent-commit-join-conflict");
+    expect(conflict).toMatchObject({ concerns: [`commit:${sha.p2}`, "run:run-c"] });
+    expect(conflict && "message" in conflict ? conflict.message : "").toContain(`run-b (${sha.b1.slice(0, 8)})`);
+  });
+
+  test("a squash of several commits has a patch-id of its own and doesn't join by content", async () => {
+    const doc = await walk("app/server.ts:5-6");
+    expect(doc.edges.filter((e) => e.kind === "made-by" && e.from === `commit:${sha.sq}`)).toEqual([]);
+    expect(doc.why.gaps.map((g) => g.code)).toContain("intent-why-no-run");
+  });
+
+  test("graph --intent --record lists the content join on the commit", async () => {
+    const { doc } = await intentRecord({ cwd: root, record: "s-001" });
+    contract(intentRecordSchema).expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.commits.find((c) => c.sha === sha.p1)?.runs).toEqual([
+      { id: "run-a", recorded: true, state: "ended", harness: "claude-code", model: "claude-opus-5-5", provider: null, by: null, agent: null, unit: "W-001", joinedBy: ["patch-id"], recordedAs: sha.c1 },
+    ]);
+  });
+});
+
+describe("runs --json joins by patch-id", () => {
+  test("a run lists the rewritten commit after the one it recorded, with no hunks", async () => {
+    const doc = await workspaceRuns({ cwd: root });
+    contract(runsSchema).expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    const byId = new Map(doc.runs.map((r) => [r.id, r]));
+    const a = byId.get("run-a")!;
+    expect(a.commits).toEqual([
+      { sha: sha.c1, patchId: expect.stringMatching(/^[0-9a-f]{40}$/), joinedBy: ["record"], hunks: [{ path: "app/server.ts", start: 2, end: 2 }] },
+      { sha: sha.p1, patchId: a.commits[0].patchId, joinedBy: ["patch-id"], hunks: null, recordedAs: sha.c1 },
+    ]);
+    // p2 carries Chant-Run: run-c, so it joins run C by trailer and run B not at all.
+    expect(byId.get("run-b")!.commits.map((c) => c.sha)).toEqual([sha.b1]);
+    expect(byId.get("run-c")!.commits).toEqual([{ sha: sha.p2, patchId: expect.any(String), joinedBy: ["trailer"], hunks: null }]);
+    // The squash joins neither of run D's commits.
+    expect(byId.get("run-d")!.commits.map((c) => c.sha)).toEqual([sha.d1, sha.d2]);
+  });
+});

package/src/workspace/intent-record.schema.json

@@ -412,6 +412,9 @@
             "$ref": "#/$defs/runRef"
           },
           "description": "The agent runs that made the commit (#3033). Added within version 1, so an older document may lack it."
+        },
+        "squash": {
+          "$ref": "#/$defs/squash"
         }
       }
     },
@@ -473,7 +476,8 @@
         "code": {
           "enum": [
             "intent-history-shallow",
-            "intent-plugin-failed"
+            "intent-plugin-failed",
+            "squash-unfollowed"
           ]
         },
         "message": {
@@ -726,10 +730,133 @@
           "items": {
             "enum": [
               "trailer",
-              "record"
+              "record",
+              "patch-id",
+              "squash"
             ]
           },
-          "description": "trailer: the commit carries Chant-Run with the run's id. record: the run's end lists the commit."
+          "description": "trailer: the commit carries Chant-Run with the run's id. record: the run's end lists the commit. patch-id: neither holds, and the commit's git patch-id --stable equals a commit's the run's end recorded, as after a rebase or a cherry-pick that dropped the trailer (#3036); never alongside the others. Added within version 1. squash: the commit squashes a pull request whose original commits join the run one of those ways, and the read was asked to follow squashes (#3035); via names them. Added within version 1."
+        },
+        "recordedAs": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{40,64}$",
+          "description": "For a patch-id join (#3036): the commit the run's end recorded with the same patch-id, which this one rewrites. Added within version 1."
+        },
+        "via": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{40,64}$"
+          },
+          "description": "For a squash join (#3035): the pull request's original commits through which the commit joins the run, oldest first. Added within version 1."
+        }
+      }
+    },
+    "squash": {
+      "type": "object",
+      "description": "Present only when the read follows squashes (--follow-squash, #3035) and the commit squashes a pull request: its subject ends with (#<n>), it has one parent, and the pull request's head is not in its history. The commit carries what the original commits' trailers carry and joins their runs. Added within version 1.",
+      "required": [
+        "pullRequest",
+        "forge",
+        "ref",
+        "head",
+        "fetched",
+        "followed",
+        "commits"
+      ],
+      "properties": {
+        "pullRequest": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "forge": {
+          "enum": [
+            "github",
+            "forgejo",
+            null
+          ],
+          "description": "The forge origin points at, from its URL, or null for one chant doesn't know or no origin. Both keep the pull request's head at refs/pull/<n>/head."
+        },
+        "ref": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The local ref the head was read from: refs/chant/pull/<n>/head where a read fetched it, refs/pull/<n>/head, or refs/remotes/origin/pr/<n>. Null when none could be read."
+        },
+        "head": {
+          "oneOf": [
+            {
+              "type": "string",
+              "pattern": "^[0-9a-f]{40,64}$"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The pull request's head commit, or null."
+        },
+        "fetched": {
+          "type": "boolean",
+          "description": "Whether this read fetched the ref from origin."
+        },
+        "followed": {
+          "type": "boolean",
+          "description": "Whether the original commits were read. When false, squash-unfollowed in reasons says why, and commits is empty."
+        },
+        "commits": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "sha",
+              "subject",
+              "author",
+              "date",
+              "trailers",
+              "joins"
+            ],
+            "properties": {
+              "sha": {
+                "type": "string",
+                "pattern": "^[0-9a-f]{40,64}$"
+              },
+              "subject": {
+                "type": "string"
+              },
+              "author": {
+                "type": "object",
+                "required": [
+                  "name",
+                  "email"
+                ],
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  },
+                  "email": {
+                    "type": "string"
+                  }
+                }
+              },
+              "date": {
+                "type": "string"
+              },
+              "trailers": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "joins": {
+                "$ref": "#/$defs/trailerJoins"
+              }
+            }
+          },
+          "description": "The original commits, oldest first: the head's commits the squash's parent doesn't have, merges left out."
         }
       }
     }

package/src/workspace/intent-record.ts

@@ -29,12 +29,16 @@
  * `workedBy` and `alsoWithin` list every work item and other decision that
  * matched, whatever the bucket. `issue` and `contract` entries are listed and
  * not walked: they name no path. Git is read through a local `git`
- * subprocess only: no fetch, no network.
+ * subprocess only: no fetch, no network, unless the walk is asked to follow
+ * squashes (#3035). Then a squash commit lists its pull request's original
+ * commits, joins their runs and counts as the record's own work when one of
+ * them carries it, and a pull request ref the clone lacks is fetched from
+ * `origin`.
  */
 
 import { declaredRecordKinds, readDeclaration, readerVersion, WorkspaceReadError } from "./declaration";
 import { declaredKindFile } from "./declared-kinds";
-import { entityDecisions, runCommitJoins } from "./intent-joins";
+import { entityDecisions, runCommitJoins, type IntentCommit } from "./intent-joins";
 import {
   addingCommit,
   closingCommit,
@@ -53,7 +57,8 @@ import { constraintCovers, isWorkspacePath, memberHolding } from "./record-asset
 import type { DecidedIn } from "./record-decided";
 import { RecordReadError } from "./records";
 import type { RecordView } from "./records-cli";
-import { runsForCommits, type RunRef } from "./runs";
+import { addSquashRuns, runsForCommits, type RunRef } from "./runs";
+import { followSquashes, type Forge, type SquashFollow } from "./squash";
 import { readTrailerJoins, type CommitTrailerJoins } from "./trailer-joins";
 import { joinPath } from "./tree";
 import { locateWorkspace } from "./which-chant";
@@ -98,6 +103,16 @@ export interface RecordCommit {
   joins: CommitTrailerJoins;
   /** The agent runs that made the commit (#3033): the one its Chant-Run names, and any whose record lists it. */
   runs: RunRef[];
+  /** Only when the walk follows squashes (#3035) and the commit squashes a pull request: its original commits and what their trailers join. */
+  squash?: {
+    pullRequest: number;
+    forge: Forge | null;
+    ref: string | null;
+    head: string | null;
+    fetched: boolean;
+    followed: boolean;
+    commits: { sha: string; subject: string; author: { name: string; email: string }; date: string; trailers: Record<string, string[]>; joins: CommitTrailerJoins }[];
+  };
   /** The record's constrains entries whose history listed the commit. */
   entries: string[];
   /** The files the commit changed in the record's region, from the workspace root. Empty when git lists none, as for a merge that changed nothing against its first parent there. */
@@ -146,6 +161,8 @@ export interface IntentRecordQuery {
   record: string;
   at?: string;
   kinds?: string[];
+  /** Follow squash merges to their pull requests' original commits, fetching a missing pull request ref from `origin` (#3035). */
+  followSquash?: boolean;
 }
 
 export interface IntentRecordResult {
@@ -248,6 +265,13 @@ async function walk(query: IntentRecordQuery, head: Head): Promise<IntentRecordR
   const own = decisionWindow(hit.kind, view);
   const shas = [...listed.keys()].filter((sha) => inWindow(own, sha));
   const details = commitDetails(top, shas);
+  // Squash merges, followed to the pull request's original commits when asked (#3035).
+  const follows = query.followSquash ? followSquashes(top, [...details.values()], { fetchMissing: true }) : new Map<string, SquashFollow>();
+  for (const f of follows.values()) {
+    if (f.problem) reasons.push({ code: "squash-unfollowed", message: `${f.sha.slice(0, 8)} squashes pull request #${f.pullRequest}, and ${f.problem}, so its original commits are not followed` });
+  }
+  const originalDetails = commitDetails(top, [...new Set([...follows.values()].flatMap((f) => f.commits))]);
+  const originalsOf = (sha: string): IntentCommit[] => (follows.get(sha)?.commits ?? []).map((o) => originalDetails.get(o)).filter((x): x is IntentCommit => x !== undefined);
   // Newest first by commit date, as git log lists them.
   const order = (shas.length > 0 ? tryGit(top, ["rev-list", "--no-walk=sorted", "--stdin"], `${shas.join("\n")}\n`) : "")?.split("\n").map((s) => s.trim()).filter(Boolean) ?? shas;
   shas.sort((a, b) => order.indexOf(a) - order.indexOf(b));
@@ -307,14 +331,15 @@ async function walk(query: IntentRecordQuery, head: Head): Promise<IntentRecordR
   const constrainedContracts = constrains.filter((c) => c.granularity === "contract").map((c) => c.entry);
   const commits: RecordCommit[] = [];
   // chant's own trailers (#3149): the record named outright, or a work item that implements it.
-  const trailerJoins = readTrailerJoins(top, [...details.values()]);
+  const trailerJoins = readTrailerJoins(top, [...details.values(), ...originalDetails.values()]);
   const recordKinds = new Map(kinds.filter((k) => k.records).map((k) => [k.records!.loaded.kind.name, k]));
   const workKinds = kinds.filter((k) => k.records?.loaded.kind.work);
   const runJoins = await runsForCommits(
     top,
     located.rootOnDisk,
-    shas.map((sha) => ({ sha, run: trailerJoins.get(sha)?.joins.run ?? null })),
+    [...new Set([...shas, ...originalDetails.keys()])].map((sha) => ({ sha, run: trailerJoins.get(sha)?.joins.run ?? null })),
   );
+  addSquashRuns(runJoins.refs, follows);
   const workImplements = (k: LoadedKind, id: string): boolean | undefined => {
     const v = k.records!.views.find((x) => x.id === id);
     return v ? idList(v.data, k.records!.loaded.kind.work!.implements).includes(view.id!) : undefined;
@@ -325,34 +350,42 @@ async function walk(query: IntentRecordQuery, head: Head): Promise<IntentRecordR
     let unit: string | null = null;
     let isOwn = false;
     const joins = trailerJoins.get(sha)!.joins;
-    for (const r of joins.records) {
-      const k = recordKinds.get(r.kind);
-      if (!k || !k.records!.views.some((v) => v.id === r.id)) continue;
-      r.node = `record:${r.kind}/${r.id}`;
-      if (k.records!.loaded.kind.work ? workImplements(k, r.id) : r.kind === kind.name && r.id === view.id) isOwn = true;
-    }
-    const item = joins.lease?.item;
-    if (item) {
-      const holding = workKinds.filter((k) => k.records!.views.some((v) => v.id === item));
-      if (holding.length === 1 && workImplements(holding[0], item)) isOwn = true;
+    const originals = originalsOf(sha);
+    // The commit's own trailers, and a followed squash's original commits' (#3035).
+    for (const j of [joins, ...originals.map((o) => trailerJoins.get(o.sha)!.joins)]) {
+      for (const r of j.records) {
+        const k = recordKinds.get(r.kind);
+        if (!k || !k.records!.views.some((v) => v.id === r.id)) continue;
+        r.node = `record:${r.kind}/${r.id}`;
+        if (k.records!.loaded.kind.work ? workImplements(k, r.id) : r.kind === kind.name && r.id === view.id) isOwn = true;
+      }
+      const item = j.lease?.item;
+      if (item) {
+        const holding = workKinds.filter((k) => k.records!.views.some((v) => v.id === item));
+        if (holding.length === 1 && workImplements(holding[0], item)) isOwn = true;
+      }
     }
+    const subjects: IntentCommit[] = [c, ...originals];
     for (const k of kinds) {
       if (!k.joins) continue;
-      let result;
-      try {
-        result = await runCommitJoins(k.joins, c, { read: readAt, list: listAt, at: located.at }, k.name);
-      } catch (err) {
-        const message = `${k.display}: commitJoins failed for ${sha.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`;
-        if (!failedPlugins.has(message)) reasons.push({ code: "intent-plugin-failed", message });
-        failedPlugins.add(message);
-        continue;
+      for (const subject of subjects) {
+        let result;
+        try {
+          result = await runCommitJoins(k.joins, subject, { read: readAt, list: listAt, at: located.at }, k.name);
+        } catch (err) {
+          const message = `${k.display}: commitJoins failed for ${subject.sha.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`;
+          if (!failedPlugins.has(message)) reasons.push({ code: "intent-plugin-failed", message });
+          failedPlugins.add(message);
+          continue;
+        }
+        if (!result.unit) continue;
+        unit ??= result.unit.id;
+        const named = [...entityDecisions(result.unit), ...entityDecisions(result.contract)];
+        if (named.some((x) => x === view.id || x === `${kind.name}/${view.id}`)) isOwn = true;
+        if (result.contract && constrainedContracts.includes(result.contract.id)) isOwn = true;
       }
-      if (!result.unit) continue;
-      unit ??= result.unit.id;
-      const named = [...entityDecisions(result.unit), ...entityDecisions(result.contract)];
-      if (named.some((x) => x === view.id || x === `${kind.name}/${view.id}`)) isOwn = true;
-      if (result.contract && constrainedContracts.includes(result.contract.id)) isOwn = true;
     }
+    const f = follows.get(sha);
     const changed = (files.get(sha) ?? []).map((f) => joinPath(workspacePrefix, f));
     const covers = (paths: string[]) => paths.some((p) => changed.some((f) => constraintCovers(p, f)));
     const workedBy = works.filter((w) => inWindow(w.window, sha) && (w.implementsRecord || covers(w.paths))).map((w) => w.ref);
@@ -368,6 +401,19 @@ async function walk(query: IntentRecordQuery, head: Head): Promise<IntentRecordR
       unit,
       joins,
       runs: runJoins.refs.get(sha) ?? [],
+      ...(f
+        ? {
+            squash: {
+              pullRequest: f.pullRequest,
+              forge: f.forge,
+              ref: f.ref,
+              head: f.head,
+              fetched: f.fetched,
+              followed: f.followed,
+              commits: originals.map((o) => ({ sha: o.sha, subject: o.subject, author: o.author, date: o.date, trailers: o.trailers, joins: trailerJoins.get(o.sha)!.joins })),
+            },
+          }
+        : {}),
       entries: listed.get(sha)!,
       files: files.get(sha) ?? [],
       bucket: isOwn ? "own" : workedBy.length > 0 ? "worked" : alsoWithin.length > 0 ? "within-other" : "unexplained",

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

@@ -0,0 +1,76 @@
+/**
+ * From a commit back to the review that asked for it (#3154, E21 in
+ * arugula-salad/hud#823): a review session's comments[].follow_ups name a
+ * work item, a builder's commit carries that item with `Chant-Record:
+ * work:<id>`, and `graph --intent` lists the session on the work node.
+ *
+ * The workspace is a copy of the reference workspace, where W-001
+ * constrains design/screens/home.json, with one open review session added.
+ */
+
+import { cpSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, git, REPO, scratchDir } from "./__fixtures__/contract-repo";
+import { intentGraph, type CommitNode, type WorkNode } from "./intent";
+import intentSchema from "./intent.schema.json";
+
+afterAll(cleanScratch);
+
+const intent = contract(intentSchema);
+
+const SESSION = `---
+${JSON.stringify(
+  {
+    schema: 1,
+    id: "S-0002",
+    title: "Review of the home page",
+    state: "open",
+    agenda: [{ text: "The home page as built" }],
+    attendance: [{ principal: "alice", class: "person" }],
+    opened: "2026-10-03T10:00:00Z",
+    closed: null,
+    verdicts: [],
+    comments: [
+      { text: "The header is cut off." },
+      { text: "The hero image should follow the spec.", follow_ups: ["work:W-001"] },
+      { text: "Same for the footer.", follow_ups: ["work:W-001", "work:W-404"] },
+    ],
+  },
+  null,
+  2,
+)}
+---
+
+# Review of the home page
+`;
+
+function workspace(): string {
+  const root = scratchDir("chant-intent-reviews-");
+  cpSync(join(REPO, "reference-workspace"), root, { recursive: true, filter: (src) => !/[\\/](node_modules|dist)$/.test(src) });
+  writeFileSync(join(root, "design", "sessions", "S-0002-review-of-the-home-page.md"), SESSION);
+  const g = (...a: string[]) => git(root, ...a);
+  g("init", "-q");
+  g("add", "-A");
+  g("commit", "-q", "-m", "the workspace");
+  g("branch", "-M", "main");
+  writeFileSync(join(root, "design", "screens", "home.json"), `${JSON.stringify({ regions: ["header", "hero", "footer"] }, null, 2)}\n`);
+  g("add", "-A");
+  g("commit", "-q", "-m", "the hero follows the spec", "-m", "Chant-Record: work:W-001");
+  return root;
+}
+
+describe("graph --intent joins a work item back to the review that asked for it (#3154, E21)", () => {
+  test("the work node lists the session and the comments whose follow_ups name it, and the builder's commit carries the item", async () => {
+    const root = workspace();
+    const head = git(root, "rev-parse", "HEAD");
+    const { doc } = await intentGraph({ cwd: root, region: "design/screens/home.json" });
+    intent.expectValid(doc);
+    if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+    const w = doc.nodes.find((n) => n.id === "record:work/W-001") as WorkNode;
+    expect(w.reviews).toEqual([{ id: "record:session/S-0002", recordKind: "session", record: "S-0002", path: "design/sessions/S-0002-review-of-the-home-page.md", state: "open", comments: [2, 3] }]);
+    const c = doc.nodes.find((n) => n.id === `commit:${head}`) as CommitNode;
+    expect(c).toBeDefined();
+    expect(doc.edges).toContainEqual({ kind: "carries", from: c.id, to: w.id });
+  });
+});