@intentius/chant 0.100.0 → 0.102.0

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

@@ -402,6 +402,16 @@
             "$ref": "#/$defs/recordRef"
           },
           "description": "Each other decision whose window holds the commit and whose path: entries cover one of the commit's files."
+        },
+        "joins": {
+          "$ref": "#/$defs/trailerJoins"
+        },
+        "runs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/runRef"
+          },
+          "description": "The agent runs that made the commit (#3033). Added within version 1, so an older document may lack it."
         }
       }
     },
@@ -524,6 +534,204 @@
         },
         "commits": false
       }
+    },
+    "trailerJoins": {
+      "type": "object",
+      "description": "What chant's own commit trailers join the commit to (#3149, ws-075). Added within version 1, so an older document may lack it.",
+      "required": [
+        "agent",
+        "lease",
+        "run",
+        "records",
+        "applied"
+      ],
+      "properties": {
+        "agent": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Chant-Agent: the agent session that wrote the commit (ws-067)."
+        },
+        "lease": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "token",
+                "item"
+              ],
+              "properties": {
+                "token": {
+                  "type": "string",
+                  "description": "Chant-Lease: the work lease's fencing token."
+                },
+                "item": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The work item a lease history on the local chant/lifecycle branch names for the token, or null when none does."
+                }
+              }
+            }
+          ]
+        },
+        "run": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Chant-Run: the agent run that made the commit (#3033)."
+        },
+        "records": {
+          "type": "array",
+          "description": "Each well-formed Chant-Record value, <kind>:<id>, in order.",
+          "items": {
+            "type": "object",
+            "required": [
+              "kind",
+              "id",
+              "node"
+            ],
+            "properties": {
+              "kind": {
+                "type": "string",
+                "description": "The record kind's name."
+              },
+              "id": {
+                "type": "string"
+              },
+              "node": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "The id of the record's node, record:<kind>/<id>, when a kind read has the record; null otherwise."
+              }
+            }
+          }
+        },
+        "applied": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "by",
+                "at",
+                "commit"
+              ],
+              "properties": {
+                "by": {
+                  "type": "string",
+                  "description": "Chant-Applied-By: who applied the branch."
+                },
+                "at": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "Chant-Applied-At, ISO 8601, or null when it is missing."
+                },
+                "commit": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "Chant-Applied-Commit: the applied branch's tip, or null when it is missing or not a commit id."
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "runRef": {
+      "type": "object",
+      "description": "An agent run that made the commit (#3033).",
+      "required": [
+        "id",
+        "recorded",
+        "state",
+        "harness",
+        "model",
+        "provider",
+        "by",
+        "agent",
+        "unit",
+        "joinedBy"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "recorded": {
+          "type": "boolean",
+          "description": "Whether the run ledger on the local chant/lifecycle branch has the run. When false, only the id is known."
+        },
+        "state": {
+          "enum": [
+            "running",
+            "ended",
+            null
+          ]
+        },
+        "harness": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "model": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "provider": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "by": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The principal the run worked for."
+        },
+        "agent": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "unit": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The work item it worked on."
+        },
+        "joinedBy": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "enum": [
+              "trailer",
+              "record"
+            ]
+          },
+          "description": "trailer: the commit carries Chant-Run with the run's id. record: the run's end lists the commit."
+        }
+      }
     }
   }
 }

package/src/workspace/intent-record.ts

@@ -17,7 +17,8 @@
  *
  * - `own`: the record's own work, as the region walk judges it: a commit a
  *   plugin joins to a unit whose unit or contract names the record, or that
- *   serves a contract the record constrains.
+ *   serves a contract the record constrains; or a commit whose own trailers
+ *   (#3149) name the record, or a work item that implements it.
  * - `worked`: inside the window of a work item that is not dropped and that
  *   implements the record, or whose `path:` entries cover a file the commit
  *   changed in the record's region.
@@ -52,6 +53,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 { readTrailerJoins, type CommitTrailerJoins } from "./trailer-joins";
 import { joinPath } from "./tree";
 import { locateWorkspace } from "./which-chant";
 import { idList } from "./work";
@@ -91,6 +94,10 @@ export interface RecordCommit {
   pullRequest: number | null;
   /** The unit a plugin joined the commit to, or null. */
   unit: string | null;
+  /** What chant's own trailers join the commit to (#3149), as a commit node in `graph --intent` reports it. */
+  joins: CommitTrailerJoins;
+  /** The agent runs that made the commit (#3033): the one its Chant-Run names, and any whose record lists it. */
+  runs: RunRef[];
   /** 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. */
@@ -299,11 +306,36 @@ async function walk(query: IntentRecordQuery, head: Head): Promise<IntentRecordR
   const failedPlugins = new Set<string>();
   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 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 })),
+  );
+  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;
+  };
   for (const sha of shas) {
     const c = details.get(sha);
     if (!c) continue;
     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;
+    }
     for (const k of kinds) {
       if (!k.joins) continue;
       let result;
@@ -334,6 +366,8 @@ async function walk(query: IntentRecordQuery, head: Head): Promise<IntentRecordR
       trailers: c.trailers,
       pullRequest: pr ? Number(pr[1]) : null,
       unit,
+      joins,
+      runs: runJoins.refs.get(sha) ?? [],
       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-why.test.ts

@@ -0,0 +1,274 @@
+/**
+ * From a line or a symbol to the decision and the agent run behind it (#3034).
+ *
+ * - app/server.ts declares createApp and a class Server with listen and close.
+ * - s-001 (path:app/server.ts), s-002 (member:app) and s-003 (path:app) are
+ *   decided; W-001 implements s-001.
+ * - c1 changes createApp's body, made by run A on W-001 (Chant-Run trailer).
+ * - c2 changes listen's and close's bodies; runs B and C both list it, B
+ *   with the hunk in listen and C with the hunk in close.
+ * - c3 changes the first line; runs D and E both list it, with no hunks.
+ * - docs/notes.ts is in no member and no decision covers it.
+ */
+
+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, type RegionNode, type RunNode } from "./intent";
+import { formatIntent } from "./intent-cli";
+import intentSchema from "./intent.schema.json";
+import { parseFrontMatter } from "./records";
+import { runsWrite, workspaceRuns } from "./runs-cli";
+import runsSchema from "./runs.schema.json";
+import runsWriteSchema from "./runs-write.schema.json";
+import { resolveSymbol } from "./symbols";
+
+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 SERVER = [
+  "// The app server.",
+  "export function createApp() {",
+  "  return 0;",
+  "}",
+  "",
+  "export class Server {",
+  "  /** Listens. */",
+  "  listen(port: number) {",
+  "    return port;",
+  "  }",
+  "",
+  "  close() {",
+  "    return 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));
+
+const intent = contract(intentSchema);
+type Doc = Exclude<IntentDocument, { error: unknown }>;
+
+let root: string;
+const sha: Record<string, string> = {};
+const run: 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<string> {
+  const doc = await runsWrite({ verb: "record", fields: JSON.stringify(fields), cwd: root });
+  contract(runsWriteSchema).expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc.run.id;
+}
+async function walk(region: string, at?: string): Promise<Doc> {
+  const { doc } = await intentGraph({ cwd: root, region, at });
+  intent.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: "why", 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(SERVER),
+    "app/tool.py": "def run():\n    return 0\n",
+    "app/twice.ts": "class A {\n  run() {}\n}\nclass B {\n  run() {}\n}\n",
+    "docs/notes.ts": "export const notes = [];\n",
+    "decisions/s-001-server.md": decision("s-001", { constrains: ["path:app/server.ts"] }),
+    "decisions/s-002-app.md": decision("s-002", { constrains: ["member:app"] }),
+    "decisions/s-003-app-dir.md": decision("s-003", { constrains: ["path:app"] }),
+    "work/W-001-server.md": work("W-001", { implements: ["s-001"] }),
+  });
+  sha.c0 = commit(["the workspace"]);
+
+  run.a = await record({ id: "run-a", harness: "claude-code", model: "claude-opus-5-5", by: "alice", unit: "W-001", instruction: { sha256: "a".repeat(64), excerpt: "Make createApp return 1." }, startedAt: "2026-10-01T10:00:00Z", endedAt: "2026-10-01T10:05:00Z" });
+  writeFiles(root, { "app/server.ts": text(edit(SERVER, 3, "  return 1;")) });
+  sha.c1 = commit(["createApp returns 1", `Chant-Run: ${run.a}`]);
+
+  const v2 = edit(edit(edit(SERVER, 3, "  return 1;"), 9, "    return port + 1;"), 13, "    return 1;");
+  writeFiles(root, { "app/server.ts": text(v2) });
+  sha.c2 = commit(["listen and close"]);
+  run.b = await record({ id: "run-b", harness: "claude-code", model: "claude-sonnet", startedAt: "2026-10-01T11:00:00Z", commits: [{ sha: sha.c2, hunks: [{ path: "app/server.ts", start: 9, end: 9 }] }] });
+  run.c = await record({ id: "run-c", harness: "claude-code", model: "claude-haiku", startedAt: "2026-10-01T11:01:00Z", commits: [{ sha: sha.c2, hunks: [{ path: "app/server.ts", start: 13, end: 13 }] }] });
+
+  writeFiles(root, { "app/server.ts": text(edit(v2, 1, "// The app server, v2.")) });
+  sha.c3 = commit(["the header"]);
+  run.d = await record({ id: "run-d", harness: "x", startedAt: "2026-10-01T12:00:00Z", commits: [sha.c3] });
+  run.e = await record({ id: "run-e", harness: "y", startedAt: "2026-10-01T12:01:00Z", commits: [sha.c3] });
+});
+afterAll(cleanScratch);
+
+describe("symbols resolve to their current lines", () => {
+  test("functions, methods, classes and constants in TypeScript and JavaScript", () => {
+    const src = text(SERVER);
+    expect(resolveSymbol("a.ts", src, "createApp")).toEqual({ ok: true, declaration: { qualified: "createApp", kind: "function", lines: { start: 2, end: 4 } } });
+    expect(resolveSymbol("a.ts", src, "Server")).toMatchObject({ ok: true, declaration: { kind: "class", lines: { start: 6, end: 15 } } });
+    // A bare member name finds the one method it names; the doc comment is in its lines.
+    expect(resolveSymbol("a.ts", src, "listen")).toEqual({ ok: true, declaration: { qualified: "Server.listen", kind: "method", lines: { start: 7, end: 10 } } });
+    expect(resolveSymbol("a.ts", src, "Server.close")).toMatchObject({ ok: true, declaration: { lines: { start: 12, end: 14 } } });
+    const js = "/** The handlers. */\nexport const handlers = {\n  get(req) {\n    return 1;\n  },\n};\nmodule.exports = handlers;\n";
+    expect(resolveSymbol("h.mjs", js, "handlers")).toMatchObject({ ok: true, declaration: { kind: "variable", lines: { start: 1, end: 6 } } });
+    expect(resolveSymbol("h.mjs", js, "handlers.get")).toMatchObject({ ok: true, declaration: { kind: "method", lines: { start: 3, end: 5 } } });
+  });
+
+  test("says why when it can't: no resolver, no such symbol, or more than one", () => {
+    expect(resolveSymbol("a.py", "def f(): pass\n", "f")).toMatchObject({ ok: false, reason: "unsupported" });
+    const unknown = resolveSymbol("a.ts", text(SERVER), "nope");
+    expect(unknown).toMatchObject({ ok: false, reason: "unknown", candidates: ["createApp", "Server"] });
+    expect(resolveSymbol("t.ts", "class A {\n  run() {}\n}\nclass B {\n  run() {}\n}\n", "run")).toMatchObject({ ok: false, reason: "ambiguous", candidates: ["A.run", "B.run"] });
+  });
+});
+
+describe("graph --intent path#symbol", () => {
+  test("walks the symbol's current lines as a line range", async () => {
+    const doc = await walk("app/server.ts#createApp");
+    const region = doc.nodes.find((n) => n.id === doc.region) as RegionNode;
+    expect(doc.region).toBe("region:app/server.ts#createApp");
+    expect(region).toMatchObject({ path: "app/server.ts", lines: { start: 2, end: 4 }, symbol: { name: "createApp", qualified: "createApp", kind: "function" } });
+    expect(doc.history.follows).toBe("line-range");
+    const commits = doc.nodes.filter((n) => n.kind === "commit").map((n) => (n as { sha: string }).sha);
+    expect(commits).toContain(sha.c1);
+    expect(commits).not.toContain(sha.c3);
+  });
+
+  test("refuses a symbol it can't resolve, with a code for each reason", async () => {
+    for (const [region, code] of [
+      ["app/server.ts#nope", "intent-symbol-unknown"],
+      ["app/tool.py#run", "intent-symbol-unsupported"],
+      ["app/twice.ts#run", "intent-symbol-ambiguous"],
+      ["app#run", "intent-region-invalid"],
+      ["app/missing.ts#run", "intent-region-invalid"],
+    ]) {
+      const { doc, failed } = await intentGraph({ cwd: root, region });
+      intent.expectValid(doc);
+      expect(failed).toBe(true);
+      expect(doc, region).toMatchObject({ error: { code } });
+    }
+    const { doc } = await intentGraph({ cwd: root, region: "app/server.ts#nope" });
+    expect("error" in doc && doc.error.message).toContain("createApp, Server");
+    expect((await walk("app/twice.ts#B.run")).nodes.find((n) => n.kind === "region")).toMatchObject({ lines: { start: 5, end: 5 } });
+  });
+});
+
+describe("why the region is like this", () => {
+  test("names the run that last wrote each line, with its work item, and the decision it carried out first", async () => {
+    const doc = await walk("app/server.ts#createApp");
+    expect(doc.why.lines).toEqual({ start: 2, end: 4 });
+    expect(doc.why.blame).toEqual([
+      { start: 2, end: 2, commit: `commit:${sha.c0}`, sha: sha.c0, runs: [], narrowedBy: null },
+      { start: 3, end: 3, commit: `commit:${sha.c1}`, sha: sha.c1, runs: ["run:run-a"], narrowedBy: null },
+      { start: 4, end: 4, commit: `commit:${sha.c0}`, sha: sha.c0, runs: [], narrowedBy: null },
+    ]);
+    expect(doc.why.runs).toEqual([{ run: "run:run-a", lines: 1, commits: [`commit:${sha.c1}`], unit: { id: "W-001", kind: null, node: "record:work/W-001" }, decisions: ["record:decision/s-001"] }]);
+    expect(doc.why.decisions.map((d) => [d.decision, d.relevance, d.lines])).toEqual([
+      ["record:decision/s-001", "carried", 1],
+      ["record:decision/s-003", "path", 0],
+      ["record:decision/s-002", "member", 0],
+    ]);
+    expect(doc.why.explained).toBe(true);
+    expect(doc.why.gaps).toEqual([]);
+    // The run's work item is carried by the commit it made, and the run points at it.
+    expect(doc.edges).toEqual(expect.arrayContaining([{ kind: "carries", from: `commit:${sha.c1}`, to: "record:work/W-001" }, { kind: "worked-on", from: "run:run-a", to: "record:work/W-001" }]));
+    expect(doc.nodes.find((n) => n.id === "run:run-a") as RunNode).toMatchObject({ instruction: { sha256: "a".repeat(64), excerpt: "Make createApp return 1." }, lease: null });
+  });
+
+  test("a run's recorded hunks pick which of the runs sharing a commit wrote the lines", async () => {
+    const listen = await walk("app/server.ts#listen");
+    expect(listen.why.blame.find((b) => b.sha === sha.c2)).toMatchObject({ start: 9, end: 9, runs: ["run:run-b"], narrowedBy: "hunks" });
+    expect(listen.why.runs.map((r) => r.run)).toEqual(["run:run-b"]);
+    const close = await walk("app/server.ts#Server.close");
+    expect(close.why.blame.find((b) => b.sha === sha.c2)).toMatchObject({ start: 13, end: 13, runs: ["run:run-c"], narrowedBy: "hunks" });
+    expect(close.why.gaps.map((g) => g.code)).not.toContain("intent-why-run-ambiguous");
+  });
+
+  test("without hunks, a commit several runs made is ambiguous, and says so", async () => {
+    const doc = await walk("app/server.ts:1");
+    expect(doc.why.blame).toEqual([{ start: 1, end: 1, commit: `commit:${sha.c3}`, sha: sha.c3, runs: ["run:run-d", "run:run-e"], narrowedBy: null }]);
+    expect(doc.why.gaps).toEqual([{ code: "intent-why-run-ambiguous", message: expect.any(String), lines: [{ start: 1, end: 1 }] }]);
+  });
+
+  test("a whole file is blamed line by line, and runs are ordered by the lines they wrote", async () => {
+    const doc = await walk("app/server.ts");
+    expect(doc.why.lines).toEqual({ start: 1, end: SERVER.length });
+    expect(doc.why.blame.map((b) => [b.start, b.end])[0]).toEqual([1, 1]);
+    expect(doc.why.blame[doc.why.blame.length - 1].end).toBe(SERVER.length);
+    expect(doc.why.runs.map((r) => r.run).sort()).toEqual(["run:run-a", "run:run-b", "run:run-c", "run:run-d", "run:run-e"]);
+  });
+
+  test("lines not committed yet have no commit, and say so", async () => {
+    writeFiles(root, { "app/server.ts": text(edit(edit(edit(edit(SERVER, 1, "// The app server, v2."), 3, "  return 2;"), 9, "    return port + 1;"), 13, "    return 1;")) });
+    try {
+      const doc = await walk("app/server.ts#createApp");
+      expect(doc.why.blame.find((b) => b.start === 3)).toMatchObject({ commit: null, sha: null, runs: [] });
+      expect(doc.why.gaps.find((g) => g.code === "intent-why-uncommitted")).toMatchObject({ lines: [{ start: 3, end: 3 }] });
+      // The revision read is blamed, not the working tree.
+      const at = await walk("app/server.ts#createApp", sha.c3);
+      expect(at.why.blame.find((b) => b.start === 3)).toMatchObject({ sha: sha.c1, runs: ["run:run-a"] });
+    } finally {
+      git(root, "checkout", "--", "app/server.ts");
+    }
+  });
+
+  test("a region nothing accounts for is unexplained, with its gaps", async () => {
+    const doc = await walk("docs/notes.ts#notes");
+    expect(doc.why.explained).toBe(false);
+    expect(doc.why.decisions).toEqual([]);
+    expect(doc.why.runs).toEqual([]);
+    expect(doc.why.gaps.map((g) => g.code)).toEqual(["intent-why-no-decision", "intent-why-no-run"]);
+    expect(formatIntent(doc)).toContain("why       unexplained, lines 1");
+  });
+
+  test("a directory is not blamed, and lists every run in the walk", async () => {
+    const doc = await walk("app");
+    expect(doc.why.lines).toBeNull();
+    expect(doc.why.blame).toEqual([]);
+    expect(doc.why.runs.map((r) => r.run)).toEqual(["run:run-e", "run:run-d", "run:run-c", "run:run-b", "run:run-a"]);
+    expect(doc.why.decisions[0]).toMatchObject({ decision: "record:decision/s-001", relevance: "carried" });
+    expect(doc.why.explained).toBe(true);
+  });
+
+  test("prints the answer after the walk", async () => {
+    const out = formatIntent(await walk("app/server.ts#createApp"));
+    expect(out).toContain("region    app/server.ts#createApp (function createApp, lines 2-4)");
+    expect(out).toContain("why       explained, lines 2-4");
+    expect(out).toContain("  decision  s-001 carried, 1 line");
+    expect(out).toContain(`  lines     3 ${sha.c1.slice(0, 8)}; run-a (claude-code/claude-opus-5-5) on W-001`);
+  });
+});
+
+describe("the run record keeps hunks and the instruction's excerpt", () => {
+  test("runs --json lists each commit's hunks, or null", 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]));
+    expect(byId.get("run-b")!.commits).toEqual([{ sha: sha.c2, patchId: expect.any(String), joinedBy: ["record"], hunks: [{ path: "app/server.ts", start: 9, end: 9 }] }]);
+    expect(byId.get("run-d")!.commits[0].hunks).toBeNull();
+    expect(byId.get("run-a")!.instruction).toEqual({ sha256: "a".repeat(64), bytes: null, ref: null, excerpt: "Make createApp return 1." });
+  });
+
+  test("refuses a hunk that isn't one", async () => {
+    for (const hunks of [[{ path: "/abs", start: 1, end: 1 }], [{ path: "a", start: 3, end: 2 }], [{ path: "../a", start: 1, end: 1 }], []]) {
+      const doc = await runsWrite({ verb: "record", fields: JSON.stringify({ harness: "x", commits: [{ sha: sha.c0, hunks }] }), cwd: root });
+      expect(doc).toMatchObject({ error: { code: "write-input-invalid" } });
+    }
+    const long = await runsWrite({ verb: "record", fields: JSON.stringify({ harness: "x", instruction: { sha256: "b".repeat(64), excerpt: "x".repeat(501) } }), cwd: root });
+    expect(long).toMatchObject({ error: { code: "write-input-invalid" } });
+  });
+});