@intentius/chant 0.124.45 → 0.124.48

package/src/workspace/status-contract.test.ts

@@ -7,7 +7,7 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { cpSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import Ajv2020 from "ajv/dist/2020";
@@ -26,6 +26,8 @@ import {
   type StatusDocument,
 } from "./status";
 import schema from "./status.schema.json";
+import { REPO } from "./__fixtures__/contract-repo";
+import { parseFrontMatter } from "./records";
 import { appendRunRecord } from "../lifecycle/run-ledger";
 import { acquireStewardLease } from "../op/operator";
 import { stewardWorkHolder } from "../op/work-lease-run";
@@ -525,6 +527,8 @@ describe("gate state in chant workspace status --json (#2674)", () => {
         approvals: [{ principal: "alice", channel: "cli", relayedBy: null, at: "2026-09-20T01:00:00.000Z" }],
         needed: 1,
         signed: null,
+        // No record kind is declared, so no decision covers web.
+        decisions: [],
         approve: `chant approve web deploy --env staging --plan ${D("1")}`,
       },
       {
@@ -538,6 +542,7 @@ describe("gate state in chant workspace status --json (#2674)", () => {
         approvals: [],
         needed: 1,
         signed: null,
+        decisions: [],
         approve: `chant approve web deploy --env prod --plan ${D("2")}`,
       },
       {
@@ -552,6 +557,7 @@ describe("gate state in chant workspace status --json (#2674)", () => {
         approvals: [{ principal: "bob", channel: "cli", relayedBy: null, at: "2026-09-20T02:00:00.000Z" }],
         needed: 2,
         signed: null,
+        decisions: [],
         approve: `chant approve web review --env staging --plan ${D("4")}`,
       },
     ]);
@@ -629,6 +635,45 @@ describe("gate state in chant workspace status --json (#2674)", () => {
   });
 });
 
+describe("the decisions covering a gate's member (#3616)", () => {
+  test("each gate names the current decisions covering its member, ranked as why ranks them", async () => {
+    const ref = join(REPO, "reference-workspace", "decisions");
+    const fm = parseFrontMatter(readFileSync(join(ref, "ref-001-how-the-app-is-deployed.md"), "utf-8"));
+    if (!fm.ok) throw new Error(fm.message);
+    const base = 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 root = repo({
+      "chant.workspace.json": JSON.stringify({
+        name: "acme",
+        schema: 1,
+        records: [{ kind: "decisions/decision.kind.mjs" }],
+        members: [
+          { name: "web", dir: "apps/web", kind: "other", because: "the app" },
+          { name: "api", dir: "apps/api", kind: "other", because: "the api" },
+        ],
+      }),
+      "decisions/decision.kind.mjs": readFileSync(join(ref, "decision.kind.mjs"), "utf-8"),
+      "decisions/decision.schema.json": readFileSync(join(ref, "decision.schema.json"), "utf-8"),
+      "apps/web/server.ts": "export {};\n",
+      "decisions/s-001-d.md": decision("s-001", { constrains: ["member:web"] }),
+      "decisions/s-002-d.md": decision("s-002", { constrains: ["path:apps"] }),
+      "decisions/s-003-d.md": decision("s-003", { constrains: ["path:apps/web/server.ts"] }),
+      "decisions/s-004-d.md": decision("s-004", { constrains: ["path:apps/web"] }),
+      "decisions/s-005-d.md": decision("s-005", { constrains: ["path:elsewhere"], supersedes: [{ decision: "s-004" }] }),
+      "decisions/s-006-d.md": decision("s-006", { constrains: ["member:api"] }),
+    });
+    lifecycle(root, { "_members/web/_gates/web.jsonl": jsonl(pending("web", "deploy", "2026-09-20T00:00:00.000Z", { environment: "staging", planDigest: D("1") })) });
+    const doc = result(await workspaceStatus({ cwd: root, env: "staging", now: NOW }));
+    expectValid(doc);
+    const [web, api] = doc.members;
+    // s-002 by a path above, s-001 by member, s-003 by a path inside; s-004 stands for s-005, which supersedes it.
+    expect(web.gates.map((g) => g.decisions)).toEqual([["decision/s-002", "decision/s-001", "decision/s-003", "decision/s-005"]]);
+    // A member with no gate reads no decisions.
+    expect(api.gates).toEqual([]);
+  });
+});
+
 describe("stewards in chant workspace status --json (#2731)", () => {
   const op = (name: string, cron?: string) => ({
     name,

package/src/workspace/status-decisions.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "vitest";
+import type { Declaration } from "./declaration";
+import type { LoadedRecordKind, RecordEntry } from "./records";
+import { memberDecisionsReader, type DecisionKindReader } from "./status-decisions";
+
+const members = [
+  { name: "root", dir: "." },
+  { name: "api", dir: "services/api" },
+  { name: "edge", dir: "services/api/edge" },
+  { name: "web", dir: "web" },
+];
+
+function declaration(kinds: string[]): Declaration {
+  return {
+    records: kinds.map((path) => ({ kind: path, path, name: null, member: null, pointer: "/records/0" })),
+    members: members.map((m) => ({ ...m, records: [] })),
+  } as unknown as Declaration;
+}
+
+function kind(name: string, extra: Record<string, unknown> = {}): LoadedRecordKind {
+  return { kind: { name, constrains: { field: "constrains" }, closedStates: ["accepted"], ...extra } } as unknown as LoadedRecordKind;
+}
+
+function record(id: string, constrains: string[], state = "proposed", supersededBy: string | null = null): RecordEntry {
+  return { id, path: `decisions/${id}.md`, state, supersededBy, data: { constrains } } as unknown as RecordEntry;
+}
+
+function reader(kinds: Record<string, { loaded: LoadedRecordKind; records: RecordEntry[]; workspaceRoot?: string } | Error>): DecisionKindReader {
+  return async (file) => {
+    const k = Object.entries(kinds).find(([path]) => file.endsWith(path))?.[1];
+    if (!k) throw new Error(`no kind ${file}`);
+    if (k instanceof Error) throw k;
+    return { loaded: k.loaded, top: undefined, workspaceRoot: k.workspaceRoot ?? ".", records: k.records };
+  };
+}
+
+describe("the decisions covering a gate's member (#3616)", () => {
+  test("path above, member and path inside, ranked as why ranks them", async () => {
+    const read = reader({
+      "decision.kind.mjs": {
+        loaded: kind("decision"),
+        records: [
+          record("d-inside", ["path:services/api/src/handler.ts"]),
+          record("d-member", ["member:api"]),
+          record("d-services", ["path:services"]),
+          record("d-api", ["path:services/api"], "accepted"),
+          record("d-api-open", ["path:services/api"]),
+          record("d-web", ["path:web", "member:web"]),
+          record("d-edge-only", ["path:services/api/edge/x.ts"]),
+        ],
+      },
+    });
+    const covering = await memberDecisionsReader(declaration(["decision.kind.mjs"]), "/repo", "", read);
+    // Closed before open at one path; a longer path before a shorter one; then member; then inside.
+    expect(covering(members[1])).toEqual(["decision/d-api", "decision/d-api-open", "decision/d-services", "decision/d-member", "decision/d-inside"]);
+    // A path inside a nested member is the nested member's, and the path above covers it too.
+    expect(covering(members[2])).toEqual(["decision/d-api", "decision/d-api-open", "decision/d-services", "decision/d-edge-only"]);
+    expect(covering(members[3])).toEqual(["decision/d-web"]);
+    // The root member holds services itself, and no path another member holds.
+    expect(covering(members[0])).toEqual(["decision/d-services"]);
+  });
+
+  test("a superseded covering decision stands for the current one at the end of its chain", async () => {
+    const read = reader({
+      "decision.kind.mjs": {
+        loaded: kind("decision"),
+        records: [record("old", ["member:web"], "superseded", "mid"), record("mid", [], "superseded", "new"), record("new", ["path:elsewhere"], "accepted"), record("gone", ["member:web"], "superseded", "missing")],
+      },
+    });
+    const covering = await memberDecisionsReader(declaration(["decision.kind.mjs"]), "/repo", "", read);
+    expect(covering(members[3])).toEqual(["decision/new"]);
+  });
+
+  test("path entries resolve from the kind's workspace root, and a member's dir from the workspace's", async () => {
+    const read = reader({
+      "decision.kind.mjs": { loaded: kind("decision"), workspaceRoot: "ws", records: [record("d", ["path:web"])] },
+    });
+    const covering = await memberDecisionsReader(declaration(["decision.kind.mjs"]), "/repo/ws", "ws", read);
+    expect(covering(members[3])).toEqual(["decision/d"]);
+    expect(covering(members[1])).toEqual([]);
+  });
+
+  test("work kinds, kinds without constrains and unreadable kinds cover nothing", async () => {
+    const read = reader({
+      "work.kind.mjs": { loaded: kind("work", { work: {} }), records: [record("w", ["member:web"])] },
+      "note.kind.mjs": { loaded: kind("note", { constrains: undefined }), records: [record("n", ["member:web"])] },
+      "broken.kind.mjs": new Error("kind-unreadable"),
+      "adr.kind.mjs": { loaded: kind("adr"), records: [record("a", ["member:web"])] },
+    });
+    const covering = await memberDecisionsReader(declaration(["work.kind.mjs", "note.kind.mjs", "broken.kind.mjs", "adr.kind.mjs"]), "/repo", "", read);
+    expect(covering(members[3])).toEqual(["adr/a"]);
+  });
+
+  test("no declared record kind reads nothing", async () => {
+    const covering = await memberDecisionsReader(declaration([]), "/repo", "", async () => {
+      throw new Error("not read");
+    });
+    expect(covering(members[3])).toEqual([]);
+  });
+});

package/src/workspace/status-decisions.ts

@@ -0,0 +1,151 @@
+/**
+ * The decisions covering each member, for the gates in `chant workspace
+ * status --json` (#3616): a reader showing a gate to the person about to
+ * approve it names the decision the gate enforces without a
+ * `graph --intent` walk of its own.
+ *
+ * This is the part of the intent walk (`intent.ts`) that reads only records.
+ * A decision covers a member when one of its `constrains` entries is
+ * `member:<name>`, or a `path:` that is the member's directory, a directory
+ * above it, or a path inside it that the member holds (not a member nested
+ * in it). A superseded covering decision stands for the decision that
+ * supersedes it, at the end of its chain. Only current decisions are listed,
+ * as `<kind>/<id>`, ranked as `why.decisions` ranks them
+ * (`decision-rank.ts`). `carried` needs the member's history, so it never
+ * applies, and neither do `issue` or `contract`, which need commits. Every
+ * declared record kind other than a work kind is read, as the intent walk
+ * reads them; a kind that can't be read is left out.
+ */
+
+import { declaredRecordKinds, type Declaration } from "./declaration";
+import { declaredKindFile } from "./declared-kinds";
+import { compareDecisionRank, type DecisionRankKey, type WhyRelevance } from "./decision-rank";
+import { decidedCommits } from "./record-decided";
+import { constraintCovers, isWorkspacePath, memberHolding } from "./record-assets";
+import type { LoadedRecordKind, RecordEntry } from "./records";
+import { joinPath } from "./tree";
+
+interface ReadKind {
+  loaded: LoadedRecordKind;
+  top: string | undefined;
+  /** Where the kind's `path:` entries resolve, from the git top. */
+  prefix: string;
+  records: RecordEntry[];
+  byId: Map<string, RecordEntry>;
+}
+
+/** Reads one kind's records, current and superseded; `readRecordsFor` in the working tree unless a test swaps it. */
+export type DecisionKindReader = (file: string, root: string) => Promise<{ loaded: LoadedRecordKind; top: string | undefined; workspaceRoot: string; records: RecordEntry[] }>;
+
+const defaultReader: DecisionKindReader = async (file, root) => {
+  const { readRecordsFor } = await import("./records-cli");
+  const read = await readRecordsFor({ kind: file, cwd: root });
+  return { loaded: read.loaded, top: read.top, workspaceRoot: read.workspaceRoot, records: read.result.records };
+};
+
+/**
+ * Read the declared decision kinds once and return the covering decisions of
+ * a member. `root` is the workspace root on disk and `rootDir` the same from
+ * the git top (`""` at the top).
+ */
+export async function memberDecisionsReader(
+  declaration: Declaration,
+  root: string,
+  rootDir: string,
+  read: DecisionKindReader = defaultReader,
+): Promise<(member: { name: string; dir: string }) => string[]> {
+  const kinds: ReadKind[] = [];
+  for (const d of declaredRecordKinds(declaration)) {
+    try {
+      const r = await read(declaredKindFile(d, root), root);
+      if (r.loaded.kind.work) continue;
+      const byId = new Map<string, RecordEntry>();
+      for (const v of r.records) if (v.id !== null) byId.set(v.id, v);
+      kinds.push({ loaded: r.loaded, top: r.top, prefix: r.workspaceRoot === "." ? "" : r.workspaceRoot, records: r.records, byId });
+    } catch {
+      // A kind that can't be read covers nothing here; workspace check and records report why.
+    }
+  }
+  // When each current decision was decided, read once per kind on first need.
+  const decidedOn = new Map<ReadKind, Map<string, string | null>>();
+  const decidedDate = (k: ReadKind, v: RecordEntry): string | null => {
+    if (!k.loaded.kind.approval || !k.top) return null;
+    let dates = decidedOn.get(k);
+    if (!dates) {
+      const current = k.records.filter((r) => r.id !== null && r.supersededBy === null).map((r) => r.path);
+      const decided = decidedCommits(k.top, "HEAD", current, k.loaded.kind);
+      dates = new Map(current.map((p) => [p, decided.get(p)?.date ?? null]));
+      decidedOn.set(k, dates);
+    }
+    return dates.get(v.path) ?? null;
+  };
+
+  return (member) => {
+    const memberFull = joinPath(rootDir, member.dir);
+    const ranked: { key: DecisionRankKey; label: string }[] = [];
+    for (const k of kinds) {
+      const field = k.loaded.kind.constrains?.field;
+      if (!field) continue;
+      const name = k.loaded.kind.name;
+      /** How each record covers the member: the relevance and the longest covering path entry. */
+      const covers = (v: RecordEntry): { relevance: WhyRelevance; specificity: number } | null => {
+        const list = v.data?.[field];
+        if (!Array.isArray(list)) return null;
+        let path = 0;
+        let byMember = false;
+        let inside = false;
+        for (const entry of list) {
+          if (typeof entry !== "string") continue;
+          if (entry.startsWith("member:")) {
+            if (entry.slice("member:".length) === member.name) byMember = true;
+          } else if (entry.startsWith("path:")) {
+            const p = entry.slice("path:".length);
+            if (!isWorkspacePath(p)) continue;
+            const full = joinPath(k.prefix, p);
+            if (memberFull !== "" && constraintCovers(full, memberFull)) path = Math.max(path, entry.length);
+            else if (memberFull === "" || full.startsWith(`${memberFull}/`)) {
+              // Inside the member's directory, and not in a member nested in it.
+              const inWorkspace = rootDir === "" ? full : full.startsWith(`${rootDir}/`) ? full.slice(rootDir.length + 1) : null;
+              if (inWorkspace !== null && memberHolding(inWorkspace, declaration.members) === member.name) inside = true;
+            }
+          }
+        }
+        if (path > 0) return { relevance: "path", specificity: path };
+        if (byMember) return { relevance: "member", specificity: 0 };
+        return inside ? { relevance: "related", specificity: 0 } : null;
+      };
+      // Each covering record, and the current record at the end of its supersession chain.
+      const current = new Set<string>();
+      for (const v of k.records) {
+        if (v.id === null || covers(v) === null) continue;
+        let at: RecordEntry = v;
+        const seen = new Set<string>();
+        while (at.supersededBy !== null && !seen.has(at.id!)) {
+          seen.add(at.id!);
+          const next = k.byId.get(at.supersededBy);
+          if (!next) break;
+          at = next;
+        }
+        if (at.supersededBy === null && at.id !== null) current.add(at.id);
+      }
+      for (const id of current) {
+        const v = k.byId.get(id)!;
+        // A decision in the list only through the chain is related, as in why.
+        const c = covers(v) ?? { relevance: "related" as const, specificity: 0 };
+        ranked.push({
+          label: `${name}/${id}`,
+          key: {
+            id: `record:${name}/${id}`,
+            current: true,
+            relevance: c.relevance,
+            lines: 0,
+            closed: v.state !== null && (k.loaded.kind.closedStates ?? []).includes(v.state),
+            specificity: c.specificity,
+            decidedOn: decidedDate(k, v),
+          },
+        });
+      }
+    }
+    return ranked.sort((a, b) => compareDecisionRank(a.key, b.key)).map((r) => r.label);
+  };
+}

package/src/workspace/status-gates.ts

@@ -82,6 +82,15 @@ export interface StatusGate {
    * `release-revoked`. Added by `workspace status`; absent otherwise.
    */
   revoked?: ReleaseRevocation;
+  /**
+   * The current decisions covering the gate's member (#3616), as
+   * `<kind>/<id>`, most relevant first: by a `path:` at or above the
+   * member's directory, by `member:`, then by a path inside it or through
+   * supersession, ranked as the intent graph's `why.decisions`. Read from
+   * the records only, without history. Added by `workspace status`; absent
+   * otherwise.
+   */
+  decisions?: string[];
   /** When the run recorded the pending fact the state is read against. */
   recordedAt: string;
   /** The commit the run reached the gate at (#4020), from the pending fact. Absent on a fact written before chant 0.124.28. */

package/src/workspace/status.schema.json

@@ -104,6 +104,7 @@
           "required": ["name", "root", "file"],
           "properties": {
             "name": { "type": "string" },
+            "repo": { "type": ["string", "null"], "description": "Added in contract 1 by #3168. The repository the document came from: the URL of the remote origin of the git repository that holds the workspace, with any user name or password removed, or null when there is no origin or the workspace is outside git. With name, root and the revision, it says which repository's workspace a document describes, so a reader that gathers several repositories' documents, such as an org workspace's repo members, tells them apart." },
             "root": { "type": "string", "description": "The workspace root relative to the git root, with / separators, \".\" for the git root itself." },
             "file": { "enum": ["chant.workspace.json", "chant.workspace.jsonc"] }
           }
@@ -987,6 +988,11 @@
         "changeSet": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "Added in contract 1 by #4022, written by chant 0.124.28 and newer. The change set the gate binds: planDigest, when a change-set document is stored under it in the member's _change-sets/ on chant/lifecycle, as a pull-request gate's apply and a release gate (#4045) store it. chant change-set show <changeSet> --json prints it, each entry with its graph node. Absent when none is stored, as for a component gate, which binds a lifecycle-plan digest." },
         "releaseDigest": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "Added in contract 1 by #4045, written by chant 0.124.28 and newer. The release the gate binds, from the pending fact: set on a release gate, the gate chant components promote --release passes for an environment, whose component is the op release. An approval counts toward it only when it was recorded for this release, environment and planDigest. Absent on every other gate." },
         "revoked": { "$ref": "#/$defs/revocation", "description": "Added in contract 1 by #4033 (ws-105), written by chant 0.124.29 and newer. Set on a release gate whose release was cut from a commit with a ci/revoked/<sha> tag, judged as release cut judges it: the tag. The gate's state is then superseded, or expired when its pending fact has expired. Absent otherwise." },
+        "decisions": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[^/]+/.+$" },
+          "description": "Added in contract 1 by #3616, written by chant 0.124.47 and newer. The current decisions covering the gate's member, as <kind>/<id>, most relevant first, so a reader names the decision a gate enforces without a graph --intent walk. A decision covers the member by a path: constraint that is the member's directory or a directory above it, by member:<name>, or by a path: inside the directory that the member holds; a superseded covering decision stands for the current one at the end of its chain. Ranked as the intent graph's why.decisions ranks them (path, then member, then the rest; then closed, longer path, newest decided, id), without carried, issue or contract, which need history. Read from every declared record kind but work kinds, in the working tree; a kind that can't be read is left out. The same list on every gate of a member, and empty when nothing covers it. Absent from an older chant."
+        },
         "expiresAt": { "type": "string" },
         "approvals": {
           "description": "The approvals that count toward the gate for its plan, oldest first.",

package/src/workspace/status.ts

@@ -50,6 +50,7 @@ import { findWorkspaceRoot } from "../project-root";
 import { resolveBoxes, type ResolvedIsolation } from "./box-isolation";
 import { resolveBoxIntents, unresolvedIntent, type BoxIntent } from "./box-intent";
 import { loadKindRegistry, resolveMemberFields, type MemberFields } from "./kinds";
+import { repoIdentity } from "./repo-ref";
 import { factoryView, listingView, plantability, treeBytes, type FactoryView, type ListingView, type Plantable } from "./box-factory";
 import { declaredRecordKinds, extensionsAt, readDeclaration, readerVersion, WorkspaceReadError, type Declaration, type ErrorLocation, type Member } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
@@ -63,6 +64,7 @@ import { scopeSource } from "./write-scope";
 import { GATE_REASON_CODES, readMemberGates, type GateLedgerReader, type StatusGate, type StatusGateLedger } from "./status-gates";
 import { trustQuorumJudge } from "../op/gate-quorum";
 import { STEWARD_REASON_CODES, readMemberStewards, type StatusSteward, type StewardReasonCode } from "./status-stewards";
+import { memberDecisionsReader, type DecisionKindReader } from "./status-decisions";
 import { gitTop, workingTree } from "./tree";
 import { handToRootChant } from "./which-chant";
 
@@ -387,7 +389,7 @@ export type StatusDocument =
       lifecycle: { ref: string; commit: string | null };
       /** The branch, head and base of the checkout read (#3160). `records --uncommitted` lists the records it holds uncommitted. */
       checkout: CheckoutHead;
-      workspace: { name: string; root: string; file: string };
+      workspace: { name: string; root: string; file: string; repo: string | null };
       /** Whether a host can plant the workspace as one box (#3146): exactly one member's box block declares services. */
       plantable: Plantable;
       members: StatusMember[];
@@ -433,6 +435,8 @@ export interface StatusQuery {
   readStewards?: typeof readMemberStewards;
   /** Reads one member's promotion order from its directory; its chant.config.ts unless a test swaps it. */
   readPromotionOrder?: (dir: string) => Promise<PromotionStep[] | null>;
+  /** Reads one record kind for the decisions covering each gate's member (#3616); the working tree unless a test swaps it. */
+  readDecisionKind?: DecisionKindReader;
 }
 
 /** A factory view with the declaration's x- keys on it and on its check, publish and tiers (#3595). */
@@ -727,6 +731,9 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
     const revoked = () => (revokedCommits ??= revokedCommitsAt(top, ruleSource.declaration?.ci?.green ?? null).catch(() => new Map()));
     // #4024: the flag records, read once for every member. Unreadable records list as null.
     const flags = await readStatusFlags(declaration, found.dir);
+    // #3616: the decisions covering each member, read from the records once and only when a gate is met.
+    let coveringReader: ReturnType<typeof memberDecisionsReader> | undefined;
+    const covering = () => (coveringReader ??= memberDecisionsReader(declaration, found.dir, rootDir, query.readDecisionKind));
     const members: StatusMember[] = [];
     for (const m of declaration.members) {
       const revokedOf = revokedReleaseLookup(resolve(found.dir, m.dir), revoked);
@@ -748,7 +755,7 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
         compare: query.compareTo === undefined ? null : compareEnvironments(environments[0], environments[environments.length - 1]),
         readable: environments.every((e) => e.reason === null),
         gateLedger: gates.ledger,
-        gates: await supersedeRevokedGates(gates.gates, revokedOf),
+        gates: await withDecisions(await supersedeRevokedGates(gates.gates, revokedOf), m, covering),
         box:
           m.box === null
             ? null
@@ -807,7 +814,7 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
       compareTo: query.compareTo ?? null,
       lifecycle: { ref: LIFECYCLE_REF, commit },
       checkout: readCheckoutHead(top),
-      workspace: { name: declaration.name, root: rootDir === "" ? "." : rootDir, file: declaration.file },
+      workspace: { name: declaration.name, root: rootDir === "" ? "." : rootDir, file: declaration.file, repo: repoIdentity(found.dir) },
       plantable: plantability(declaration),
       members,
       leases,
@@ -889,6 +896,13 @@ async function readStatusFlags(declaration: Declaration, root: string): Promise<
   }
 }
 
+/** Each gate with the current decisions covering its member (#3616), when the member has gates. */
+async function withDecisions(gates: StatusGate[], m: { name: string; dir: string }, covering: () => ReturnType<typeof memberDecisionsReader>): Promise<StatusGate[]> {
+  if (gates.length === 0) return gates;
+  const decisions = (await covering())(m);
+  return gates.map((g) => ({ ...g, decisions: [...decisions] }));
+}
+
 /** The overlap report (#4025); null when no work kind is declared or it can't be read. */
 async function readStatusOverlap(declaration: Declaration, root: string, top: string, changeSets: OverlapChangeSetRef[]): Promise<OverlapReport | null> {
   if (declaredRecordKinds(declaration).length === 0) return null;

package/src/workspace/where-filters.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { parseArgs } from "../cli/main";
+import { matchesWhere, parseWhere } from "../read-filter";
+import { filterRecordsDocument, RECORD_FILTER_FIELDS, type RecordsDocument } from "./records-cli";
+import { RUN_FILTER_FIELDS, RunsFilterError, workspaceRuns } from "./runs-cli";
+
+describe("--where on records and runs (#4363)", () => {
+  it("parses --where as a repeatable flag", () => {
+    expect(parseArgs(["ledger", "gates", "--where", "op=tf-apply", "--where", "kind=pending"]).where).toEqual(["op=tf-apply", "kind=pending"]);
+    expect(() => parseArgs(["ledger", "gates", "--where"])).toThrow(/--where needs a clause/);
+  });
+
+  it("filters the records a read lists and counts summary over them", () => {
+    const rec = (id: string, state: string, valid: boolean, data: Record<string, unknown>) => ({ id, path: `d/${id}.md`, state, valid, data, supersededBy: null, provenance: { level: "unattested" } });
+    const doc = {
+      $schema: "x",
+      contract: 1,
+      records: [rec("D-1", "accepted", true, { owner: "ops" }), rec("D-2", "proposed", true, { owner: "dev" }), rec("D-3", "accepted", false, { owner: "dev" })],
+      summary: { total: 3, valid: 2, invalid: 1, superseded: 4 },
+    } as unknown as RecordsDocument;
+    const where = ["state=accepted", "data.owner=dev"];
+    const out = filterRecordsDocument(doc, parseWhere(where, RECORD_FILTER_FIELDS), where);
+    if ("error" in out) throw new Error("failed");
+    expect(out.records.map((r) => r.id)).toEqual(["D-3"]);
+    expect(out.summary).toEqual({ total: 1, valid: 0, invalid: 1, superseded: 4 });
+    expect(out.where).toEqual(where);
+    expect(filterRecordsDocument(doc, [], [])).toBe(doc);
+  });
+
+  it("filters runs on their typed fields", () => {
+    const run = { id: "r1", state: "ended", startedAt: "2026-10-22T00:00:00.000Z", model: "opus", unit: { id: "W-1", kind: "work" }, cost: { amount: 1.5, currency: "USD" } };
+    expect(matchesWhere(run, parseWhere(["cost.amount>1", "unit.id=W-1", "startedAt>=2026-10-21"], RUN_FILTER_FIELDS))).toBe(true);
+    expect(matchesWhere(run, parseWhere(["model!=opus"], RUN_FILTER_FIELDS))).toBe(false);
+  });
+
+  it("refuses a runs --where it can't apply before reading anything", async () => {
+    await expect(workspaceRuns({ cwd: "/nonexistent", where: ["tokens>5"] })).rejects.toThrow(RunsFilterError);
+  });
+});

package/src/workspace/work-cli.ts

@@ -436,7 +436,8 @@ export function formatWorkHistory(doc: Extract<WorkHistoryDocument, { claims: un
  * <file|->` (#3159): the `workEvidence` activity (#2772) as a command, so a
  * writer that is not an Op, such as hud, attaches evidence through chant under
  * the lease it holds. `--from` gives the entry as JSON: criterion, result,
- * title, a url or a path, and optionally as_of. It always prints the
+ * title, a url, a path or an ops result to cite (#3171), and optionally
+ * as_of. It always prints the
  * work-evidence document; exit 0 when the entry was appended, 1 otherwise.
  */
 async function runWorkEvidence(ctx: CommandContext): Promise<number> {
@@ -452,7 +453,7 @@ async function runWorkEvidence(ctx: CommandContext): Promise<number> {
   if (!id) return fail("evidence needs a work item id");
   if (!args.holder) return fail("evidence needs --holder <name>: the lease's holder");
   if (!args.token) return fail("evidence needs --token <token>: the lease's fencing token, as its claim printed it");
-  if (args.migrateFrom === undefined) return fail("evidence needs --from <file|->: the entry as JSON, with criterion, result, title and a url or a path");
+  if (args.migrateFrom === undefined) return fail("evidence needs --from <file|->: the entry as JSON, with criterion, result, title and a url, a path or an ops result");
   for (const [flag, v] of [["--ttl", args.ttl], ["--outcome", args.outcome], ["--note", args.note]] as const) {
     if (v !== undefined) return fail(`evidence takes no ${flag}`);
   }
@@ -470,7 +471,7 @@ async function runWorkEvidence(ctx: CommandContext): Promise<number> {
       1,
     );
   }
-  const known = ["criterion", "result", "title", "url", "path", "as_of"];
+  const known = ["criterion", "result", "title", "url", "path", "ops", "as_of"];
   const unknown = Object.keys(fields).filter((k) => !known.includes(k));
   if (unknown.length > 0) return fail(`the entry takes ${known.join(", ")}, not ${unknown.join(", ")}`);
   const str = (k: string): string | undefined => (typeof fields[k] === "string" ? (fields[k] as string) : undefined);
@@ -485,6 +486,7 @@ async function runWorkEvidence(ctx: CommandContext): Promise<number> {
     title: str("title") ?? "",
     url: str("url"),
     path: str("path"),
+    ops: fields.ops as never,
     asOf: str("as_of"),
   });
   return print(doc, "error" in doc ? 1 : 0);