@intentius/chant 0.124.46 → 0.124.49

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);

package/src/workspace/work-evidence-ops.test.ts

@@ -0,0 +1,176 @@
+/**
+ * Work evidence that cites an ops result (#3171), on a workspace built from
+ * the reference workspace's work kind in a throwaway git repository.
+ *
+ * W-010 is in progress with a runtime criterion, "the web component runs
+ * green in staging". The staging run ledger of `deploy-web` holds an `ok`
+ * run, a `fail` run and a gated one. The run holding W-010's lease cites the
+ * ok run, the citation verifies against the ledger, and the criterion is met.
+ * The others, and citations the ledger does not hold, are refused and
+ * nothing is written.
+ */
+
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { readFileSync } from "node:fs";
+import { cleanScratch, contract, git, REPO, repo } from "./__fixtures__/contract-repo";
+import { queryRecords } from "./records-cli";
+import recordsSchema from "./records.schema.json";
+import { attachWorkEvidence } from "./work-evidence";
+import workEvidenceSchema from "./work-evidence.schema.json";
+import { appendRunRecord } from "../lifecycle/run-ledger";
+import { appendGateResolution } from "../lifecycle/gate-ledger";
+import { persistReleasePlan } from "../lifecycle/plan-ledger";
+import { claimWorkLease, releaseWorkLease } from "../lifecycle/work-lease";
+import type { OpRunRecordInput } from "../op/runtime";
+
+const REF = join(REPO, "reference-workspace");
+const KIND = "work/work.kind.mjs";
+
+function work(id: string, fields: Record<string, unknown>): string {
+  const data = {
+    schema: 1,
+    id,
+    title: `Work ${id}`,
+    state: "in-progress",
+    implements: [],
+    needs: [],
+    constrains: ["member:app"],
+    evidence: [],
+    owner: "alice",
+    opened_on: "2026-10-23",
+    closed_on: null,
+    source: { kind: "workspace", member: "app" },
+    supersedes: [],
+    ...fields,
+  };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+const run = (id: string, status: OpRunRecordInput["status"]): OpRunRecordInput => ({
+  id,
+  op: "deploy-web",
+  env: "staging",
+  started: "2026-10-23T10:00:00.000Z",
+  ended: "2026-10-23T10:05:00.000Z",
+  status,
+  labels: { Env: "staging" },
+  outcomes: {},
+  phases: [{ name: "Apply", status: status === "fail" ? "fail" : "ok", steps: [] }],
+});
+
+let root: string;
+let token: string;
+const evidenceDoc = contract(workEvidenceSchema);
+const records = contract(recordsSchema);
+
+beforeAll(async () => {
+  root = repo({
+    "chant.workspace.json": JSON.stringify({
+      name: "studio",
+      schema: 1,
+      members: [{ name: "app", dir: "app", kind: "other", because: "a plain Node server" }],
+      records: [{ kind: "decisions/decision.kind.mjs" }, { kind: KIND }],
+    }),
+    "app/server.mjs": "export const port = 8080;\n",
+    "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"),
+    [KIND]: readFileSync(join(REF, KIND), "utf-8"),
+    "work/work.schema.json": readFileSync(join(REF, "work/work.schema.json"), "utf-8"),
+    "work/W-010-staging.md": work("W-010", {
+      acceptance: [
+        { id: "AC-1", text: "The web component runs green in staging", verification: "runtime" },
+        { id: "AC-2", text: "The release plan for staging has no deletes", verification: "runtime" },
+      ],
+    }),
+  });
+  git(root, "config", "user.name", "t");
+  git(root, "config", "user.email", "t@example.com");
+  git(root, "config", "commit.gpgsign", "false");
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", "the work");
+  for (const [id, status] of [["r-ok", "ok"], ["r-fail", "fail"], ["r-gated", "gated"]] as const) await appendRunRecord(run(id, status), { cwd: root });
+  await appendGateResolution({ op: "deploy-web", gate: "promote", resolvedBy: "bob", timestamp: "2026-10-23T09:00:00.000Z" }, { cwd: root });
+  await persistReleasePlan({ digest: "sha256:abc", deletes: [] }, { cwd: root });
+  const claimed = await claimWorkLease("W-010", "box/verify@h1", { cwd: join(root, "work") });
+  if (!claimed.ok) throw new Error(claimed.message);
+  token = claimed.lease.token;
+});
+
+afterAll(async () => {
+  await releaseWorkLease("W-010", "box/verify@h1", { cwd: join(root, "work"), token });
+  cleanScratch();
+});
+
+const cite = (over: Partial<Parameters<typeof attachWorkEvidence>[0]>) =>
+  attachWorkEvidence({ cwd: root, item: "W-010", holder: "box/verify@h1", token, criterion: "AC-1", result: "pass", title: "staging run", ...over });
+
+async function w10() {
+  const doc = await queryRecords({ kind: join(root, KIND), cwd: root, workGaps: false });
+  records.expectValid(doc);
+  if ("error" in doc || !("records" in doc)) throw new Error(JSON.stringify(doc));
+  return doc.records.find((r) => r.id === "W-010")!;
+}
+
+describe("work evidence cites an ops result (#3171)", () => {
+  test("refusals write nothing: a run the ledger lacks, a failed run as a pass, a gated run, a wrong hash, two kinds of evidence", async () => {
+    const refused = async (over: Partial<Parameters<typeof attachWorkEvidence>[0]>, code: string) => {
+      const doc = await cite(over);
+      evidenceDoc.expectValid(doc);
+      expect(doc).toMatchObject({ error: { code } });
+    };
+    await refused({ ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-nope" } }, "work-evidence-ops-missing");
+    await refused({ ops: { ledger: "run", env: "prod", op: "deploy-web", id: "r-ok" } }, "work-evidence-ops-missing");
+    await refused({ ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-fail" } }, "work-evidence-ops-mismatch");
+    await refused({ ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-gated" } }, "work-evidence-ops-unfinished");
+    await refused({ ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-ok", sha256: "0".repeat(64) } }, "work-evidence-ops-mismatch");
+    await refused({ ops: { ledger: "run", env: "../x", op: "deploy-web", id: "r-ok" } as never }, "write-input-invalid");
+    await refused({ ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-ok" }, url: "https://example.com/x" }, "write-usage-invalid");
+    expect((await w10()).acceptance).toMatchObject({ met: 0, total: 2 });
+  });
+
+  test("a failed run cited as failing evidence is written, and does not meet the criterion", async () => {
+    const doc = await cite({ result: "fail", ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-fail" } });
+    evidenceDoc.expectValid(doc);
+    expect(doc).toMatchObject({ evidence: { ops: { ledger: "run", outcome: "fail" }, result: "fail" }, acceptance: { met: 0 } });
+  });
+
+  test("an ok run in staging ticks the runtime criterion, and the entry names the ledger line by its hash", async () => {
+    const doc = await cite({ ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-ok" } });
+    evidenceDoc.expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    const line = git(root, "show", "chant/lifecycle:staging/runs__deploy-web.jsonl")
+      .split("\n")
+      .find((l) => l.includes('"r-ok"'))!
+      .trim();
+    const { createHash } = await import("node:crypto");
+    expect(doc.evidence).toMatchObject({
+      criterion: "AC-1",
+      verification: "runtime",
+      result: "pass",
+      by: "box/verify@h1",
+      ops: { ledger: "run", ref: "chant/lifecycle:staging/runs__deploy-web.jsonl", field: "id", value: "r-ok", env: "staging", outcome: "ok", sha256: createHash("sha256").update(line).digest("hex") },
+    });
+    expect(doc.acceptance).toMatchObject({ met: 1, total: 2 });
+    // The record still validates against the reference work schema with the ops entry in it.
+    const rec = await w10();
+    expect(rec.valid).toBe(true);
+    expect(rec.acceptance).toMatchObject({ met: 1, total: 2 });
+
+    // Citing it again with the hash it was given verifies too.
+    const again = await cite({ ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-ok", sha256: (doc.evidence.ops as { sha256: string }).sha256 } });
+    expect("error" in again).toBe(false);
+  });
+
+  test("a release plan and a gate answer can be cited, and a plan or gate the branch lacks is refused", async () => {
+    const plan = await cite({ criterion: "AC-2", title: "the staging plan", ops: { ledger: "plan", digest: "sha256:abc" } });
+    evidenceDoc.expectValid(plan);
+    expect(plan).toMatchObject({ evidence: { ops: { ledger: "plan", ref: "chant/lifecycle:_plans/sha256_abc.json", field: "digest", value: "sha256:abc" } }, acceptance: { met: 2, total: 2 } });
+    const gate = await cite({ criterion: "AC-2", title: "promote approved", ops: { ledger: "gate", op: "deploy-web", gate: "promote", at: "2026-10-23T09:00:00.000Z" } });
+    expect(gate).toMatchObject({ evidence: { ops: { ledger: "gate", ref: "chant/lifecycle:_gates/deploy-web.jsonl", field: "timestamp" } } });
+    expect(await cite({ ops: { ledger: "plan", digest: "sha256:nope" } })).toMatchObject({ error: { code: "work-evidence-ops-missing" } });
+    expect(await cite({ ops: { ledger: "gate", op: "deploy-web", gate: "promote", at: "2026-01-01T00:00:00.000Z" } })).toMatchObject({ error: { code: "work-evidence-ops-missing" } });
+    expect(await cite({ ops: { ledger: "deploy", env: "staging", runId: "r-ok" } })).toMatchObject({ error: { code: "work-evidence-ops-missing" } });
+    expect((await w10()).valid).toBe(true);
+  });
+});