@intentius/chant 0.91.0 → 0.93.0

package/src/workspace/work-acceptance.test.ts

@@ -0,0 +1,274 @@
+/**
+ * Acceptance criteria on work records (#2772), on a workspace built from the
+ * reference workspace's decision and work kinds in a throwaway git repository.
+ *
+ * - W-001 is done, and passing evidence of each criterion's verification
+ *   meets both of them, the manual one by bob while alice owns the item: met.
+ * - W-002 is done, and its only evidence is a unit test for an e2e
+ *   criterion: unmet.
+ * - W-003 is done, and its manual criterion's verdict is by alice, its owner:
+ *   the verdict does not count, so it is unmet as well.
+ * - W-004 is done and lists no criteria: a legacy item, read as before.
+ * - W-005 is in progress. A steward's Op attaches evidence to it under its
+ *   work lease, and is refused on the manual criterion.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, contract, git, REPO, repo } from "./__fixtures__/contract-repo";
+import { runDeclarationChecks } from "./checks";
+import { listWorkspaceWithKinds } from "./ls";
+import lsSchema from "./ls.schema.json";
+import { queryRecords } from "./records-cli";
+import recordsSchema from "./records.schema.json";
+import { workspaceStatus } from "./status";
+import statusSchema from "./status.schema.json";
+import { attachWorkEvidence } from "./work-evidence";
+import workEvidenceSchema from "./work-evidence.schema.json";
+import { workEvidence } from "../op/builders";
+import { workEvidence as workEvidenceActivity } from "../op/activities";
+import { ACTIVITY_PROFILES } from "../op/activity-profiles";
+import { OpRunFailure, runOpLocally, type OpRunResult } from "../op/local-executor";
+import type { ActivityFn } from "../op/activity-registry";
+import type { OpConfig } from "../op/types";
+import { declareSteward } from "../op/steward";
+import { claimWorkLease, releaseWorkLease } from "../lifecycle/work-lease";
+
+const REF = join(REPO, "reference-workspace");
+const ref = (path: string) => readFileSync(join(REF, path), "utf-8");
+
+function work(id: string, fields: Record<string, unknown>): string {
+  const data = {
+    schema: 1,
+    id,
+    title: `Work ${id}`,
+    state: "done",
+    implements: [],
+    needs: [],
+    constrains: ["member:app"],
+    evidence: [],
+    owner: "alice",
+    opened_on: "2026-09-25",
+    closed_on: "2026-09-25",
+    source: { kind: "workspace", member: "app" },
+    supersedes: [],
+    ...fields,
+  };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+const link = (criterion: string, verification: string, result: string, extra: Record<string, unknown> = {}) => ({
+  title: `${criterion} ${verification}`,
+  url: `https://example.com/${criterion}`,
+  criterion,
+  verification,
+  result,
+  ...extra,
+});
+
+const KIND = "work/work.kind.mjs";
+let root: string;
+
+beforeAll(() => {
+  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 }],
+      },
+      null,
+      2,
+    ),
+    "app/server.mjs": "export const port = 8080;\n",
+    "decisions/decision.kind.mjs": ref("decisions/decision.kind.mjs"),
+    "decisions/decision.schema.json": ref("decisions/decision.schema.json"),
+    "decisions/ref-001-how-the-app-is-deployed.md": ref("decisions/ref-001-how-the-app-is-deployed.md"),
+    [KIND]: ref(KIND),
+    "work/work.schema.json": ref("work/work.schema.json"),
+    "work/W-001-met.md": work("W-001", {
+      acceptance: [
+        { id: "AC-1", text: "The server answers on its port", verification: "unit" },
+        { id: "AC-2", text: "A designer finds the page matches the spec", verification: "manual" },
+      ],
+      evidence: [link("AC-1", "unit", "fail"), link("AC-1", "unit", "pass"), link("AC-2", "manual", "pass", { by: "bob" })],
+    }),
+    "work/W-002-unmet.md": work("W-002", {
+      acceptance: [{ id: "AC-1", text: "The page loads in a browser", verification: "e2e" }],
+      evidence: [link("AC-1", "unit", "pass")],
+    }),
+    "work/W-003-self.md": work("W-003", {
+      acceptance: [{ id: "AC-1", text: "Someone else signs off", verification: "manual" }],
+      evidence: [link("AC-1", "manual", "pass", { by: "Alice" })],
+    }),
+    "work/W-004-legacy.md": work("W-004", { evidence: [{ title: "The review", url: "https://example.com/review" }] }),
+    "work/W-005-leased.md": work("W-005", {
+      state: "in-progress",
+      closed_on: null,
+      acceptance: [
+        { id: "AC-1", text: "The server's test passes", verification: "unit" },
+        { id: "AC-2", text: "A person tries it", verification: "manual" },
+      ],
+    }),
+  });
+  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");
+});
+afterAll(cleanScratch);
+
+const records = contract(recordsSchema);
+
+async function read() {
+  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;
+}
+
+const codes = (r: { warnings: { code: string }[] }) => r.warnings.map((w) => w.code);
+
+describe("acceptance criteria on read (#2772)", () => {
+  test("met: each criterion has passing evidence of its verification, and the manual verdict is someone else's", async () => {
+    const w1 = (await read()).find((r) => r.id === "W-001")!;
+    expect(w1.valid).toBe(true);
+    expect(w1.acceptance).toEqual({
+      met: 2,
+      total: 2,
+      criteria: [
+        { id: "AC-1", verification: "unit", met: true },
+        { id: "AC-2", verification: "manual", met: true },
+      ],
+    });
+    expect(codes(w1)).toEqual([]);
+  });
+
+  test("unmet: evidence of another verification does not count, and the done item is warned", async () => {
+    const w2 = (await read()).find((r) => r.id === "W-002")!;
+    expect(w2.acceptance).toMatchObject({ met: 0, total: 1 });
+    expect(codes(w2)).toEqual(["work-acceptance-unmet"]);
+    expect(w2.warnings[0].message).toMatch(/AC-1 \(e2e\)/);
+  });
+
+  test("manual by the implementer: the verdict is refused, warned, and the criterion stays unmet", async () => {
+    const w3 = (await read()).find((r) => r.id === "W-003")!;
+    expect(w3.acceptance).toMatchObject({ met: 0, total: 1 });
+    expect(codes(w3)).toEqual(["work-acceptance-self-verified", "work-acceptance-unmet"]);
+  });
+
+  test("a legacy item without criteria is valid, reads acceptance null and gets no acceptance warning", async () => {
+    const w4 = (await read()).find((r) => r.id === "W-004")!;
+    expect(w4.valid).toBe(true);
+    expect(w4.acceptance).toBeNull();
+    expect(codes(w4)).toEqual([]);
+  });
+
+  test("an open item with criteria unmet is not warned: only done needs them met", async () => {
+    const w5 = (await read()).find((r) => r.id === "W-005")!;
+    expect(w5.acceptance).toMatchObject({ met: 0, total: 2 });
+    expect(codes(w5)).toEqual([]);
+  });
+
+  test("check fails with WSP117 and the reason code on each done item with a criterion unmet", async () => {
+    const report = await runDeclarationChecks(root);
+    const wsp117 = report.diagnostics.filter((d) => d.ruleId === "WSP117");
+    expect(wsp117.map((d) => [d.file, d.code, d.severity])).toEqual([
+      ["work/W-002-unmet.md", "work-acceptance-unmet", "error"],
+      ["work/W-003-self.md", "work-acceptance-unmet", "error"],
+    ]);
+    expect(report.ok).toBe(false);
+  });
+
+  test("ls --json and status --json count each item's criteria, met of total, in the read contract", async () => {
+    const ls = await listWorkspaceWithKinds({ cwd: root });
+    contract(lsSchema).expectValid(ls);
+    if ("error" in ls) throw new Error(ls.error.message);
+    const kinds = Object.fromEntries(ls.workspace.records.map((r) => [r.path, r.acceptance]));
+    expect(kinds["decisions/decision.kind.mjs"]).toBeNull();
+    expect(kinds[KIND]).toEqual([
+      { item: "W-001", state: "done", met: 2, total: 2 },
+      { item: "W-002", state: "done", met: 0, total: 1 },
+      { item: "W-003", state: "done", met: 0, total: 1 },
+      { item: "W-005", state: "in-progress", met: 0, total: 2 },
+    ]);
+
+    const status = await workspaceStatus({ cwd: root, env: "dev" });
+    contract(statusSchema).expectValid(status);
+    if ("error" in status) throw new Error(status.error.message);
+    expect(status.acceptance.map((a) => [a.member, a.kind, a.item, `${a.met}/${a.total}`])).toEqual([
+      [null, KIND, "W-001", "2/2"],
+      [null, KIND, "W-002", "0/1"],
+      [null, KIND, "W-003", "0/1"],
+      [null, KIND, "W-005", "0/2"],
+    ]);
+  });
+});
+
+describe("a steward Op under workLease attaches evidence to a criterion (#2772)", () => {
+  const evidenceDoc = contract(workEvidenceSchema);
+
+  async function run(config: OpConfig, holder: string): Promise<OpRunResult> {
+    const activities = new Map<string, ActivityFn>([["workEvidence", workEvidenceActivity as unknown as ActivityFn]]);
+    try {
+      return await runOpLocally(config, activities, ACTIVITY_PROFILES, undefined, { cwd: root, ledger: { cwd: root }, work: { holder } });
+    } catch (err) {
+      if (err instanceof OpRunFailure) return err.result;
+      throw err;
+    }
+  }
+
+  const op = (step: ReturnType<typeof workEvidence>): OpConfig => ({
+    name: "verify",
+    overview: "attach the test run to its criterion",
+    workLease: { item: "W-005", kind: KIND },
+    phases: [{ name: "Verify", steps: [step] }],
+  });
+
+  test("the run holding the lease appends passing evidence, and the criterion is met", async () => {
+    const config = op(workEvidence("AC-1", { result: "pass", title: "the server test", url: "https://example.com/ci/1", cwd: root }));
+    expect(declareSteward({ name: "box", ops: [config] }).ops).toHaveLength(1);
+    const result = await run(config, "box/verify@h1");
+    expect(result.status).toBe("ok");
+    expect(result.workLease).toMatchObject({ item: "W-005", released: true });
+    const w5 = (await read()).find((r) => r.id === "W-005")!;
+    expect(w5.acceptance).toMatchObject({ met: 1, total: 2 });
+    expect(w5.data!.evidence).toEqual([
+      expect.objectContaining({ url: "https://example.com/ci/1", criterion: "AC-1", verification: "unit", result: "pass", by: "box/verify@h1" }),
+    ]);
+  });
+
+  test("a manual criterion is refused: the run holding the lease is the implementer", async () => {
+    const result = await run(op(workEvidence("AC-2", { result: "pass", title: "tried it", url: "https://example.com/tried", cwd: root })), "box/verify@h2");
+    expect(result.status).toBe("fail");
+    expect(JSON.stringify(result.records)).toMatch(/work-acceptance-self-verified/);
+    expect((await read()).find((r) => r.id === "W-005")!.acceptance).toMatchObject({ met: 1, total: 2 });
+  });
+
+  test("without the live lease, or with another token or criterion, nothing is written", async () => {
+    const ask = (over: Partial<Parameters<typeof attachWorkEvidence>[0]>) =>
+      attachWorkEvidence({ cwd: root, item: "W-005", holder: "me", token: "t", criterion: "AC-1", result: "pass", title: "x", url: "https://example.com/x", ...over });
+    const unleased = await ask({});
+    evidenceDoc.expectValid(unleased);
+    expect("error" in unleased && unleased.error.code).toBe("lease-not-held");
+
+    const claimed = await claimWorkLease("W-005", "me", { cwd: join(root, "work") });
+    if (!claimed.ok) throw new Error(claimed.message);
+    try {
+      expect(await ask({ token: "other" })).toMatchObject({ error: { code: "lease-token-mismatch" } });
+      expect(await ask({ holder: "you", token: claimed.lease.token })).toMatchObject({ error: { code: "lease-held" } });
+      expect(await ask({ token: claimed.lease.token, criterion: "AC-9" })).toMatchObject({ error: { code: "work-criterion-unknown" } });
+      const ok = await ask({ token: claimed.lease.token, result: "fail" });
+      evidenceDoc.expectValid(ok);
+      expect(ok).toMatchObject({ item: "W-005", kind: KIND, path: "work/W-005-leased.md", acceptance: { met: 1, total: 2 } });
+    } finally {
+      await releaseWorkLease("W-005", "me", { cwd: join(root, "work"), token: claimed.lease.token });
+    }
+    expect(await attachWorkEvidence({ cwd: root, item: "W-004", holder: "me", token: "t", criterion: "AC-1", result: "pass", title: "x", url: "https://example.com/x" })).toMatchObject({
+      error: { code: "work-item-closed" },
+    });
+  });
+});

package/src/workspace/{work-cli.test.ts → work-cli.e2e.test.ts}

@@ -158,7 +158,7 @@ describe("chant workspace work (#2732)", () => {
     expect(json(closed).error.code).toBe("work-item-closed");
     const verb = await chant(root, ["workspace", "work", "grab", "W-001", "--holder", "a"]);
     expect(verb.code).toBe(1);
-    expect(verb.stderr).toContain("claim, renew or release");
+    expect(verb.stderr).toContain("claim, renew, release or history");
     const noHolder = await chant(root, ["workspace", "work", "claim", "W-001"]);
     expect(noHolder.code).toBe(1);
     expect(noHolder.stderr).toContain("--holder");

package/src/workspace/work-cli.ts

@@ -1,6 +1,8 @@
 /**
  * `chant workspace work claim|renew|release <id> --holder <name>` (#2732,
- * ws-055): the work lease, who is working on which work item.
+ * ws-055): the work lease, who is working on which work item. And `chant
+ * workspace work history <id>` (#2785): the item's lease history, each claim
+ * and how it ended, a read-contract output (`work-history.schema.json`).
  *
  * The lease itself is `../lifecycle/work-lease.ts`, the operator lease under
  * the key `work/<id>`. This file finds the work item first: in the work kind
@@ -24,6 +26,9 @@ import type { CommandContext } from "../cli/registry";
 import { parseDuration } from "../op/duration";
 import {
   claimWorkLease,
+  leaseHistoryPath,
+  listWorkLeases,
+  readLeaseHistory,
   releaseWorkLease,
   renewWorkLease,
   workLeaseRef,
@@ -32,11 +37,13 @@ import {
   type WorkLeaseRefusal,
   type WorkLeaseResult,
   type LeaseHistoryWrite,
+  type LeaseHistoryRecord,
+  type WorkLeaseState,
 } from "../lifecycle/work-lease";
 import { resolveMemberLedger } from "../lifecycle/member-ledger";
-import { WorkspaceReadError } from "./declaration";
+import { readerVersion, WorkspaceReadError } from "./declaration";
 import { declaredKindFiles, readRecordsFor } from "./records-cli";
-import { loadRecordKind, RecordReadError, type LoadedRecordKind } from "./records";
+import { loadRecordKind, RecordReadError, type LoadedRecordKind, type RecordEntry } from "./records";
 import { gitRoot } from "./record-source";
 import type { ReasonCode } from "./reason-codes";
 
@@ -48,7 +55,10 @@ export const WORK_LEASE_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/w
 
 export { WORK_LEASE_REFUSALS } from "../lifecycle/work-lease";
 
-const USAGE = "chant workspace work claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <text>] [--note <text>] [--json]";
+const USAGE = [
+  "chant workspace work claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <text>] [--note <text>] [--json]",
+  "chant workspace work history <id> [--kind <kind file>] [--json]",
+].join("\n");
 
 /** Exit code when the lease was refused rather than the command failing. */
 export const EXIT_LEASE_REFUSED = 2;
@@ -94,7 +104,8 @@ export type WorkLeaseDocument = DocHead &
   | { error: { code: WorkErrorCode; message: string } }
   );
 
-class WorkError extends Error {
+/** Why a work command could not run, with its code. */
+export class WorkError extends Error {
   constructor(
     readonly code: WorkErrorCode,
     message: string,
@@ -103,8 +114,19 @@ class WorkError extends Error {
   }
 }
 
-/** The work kind holding `id`: the one `kind` names, or the one declared work kind with a record `id`. */
-async function findWorkItem(id: string, cwd: string, kind: string | undefined): Promise<{ loaded: LoadedRecordKind; state: string | null; root: string }> {
+/** A work item found by id: its kind, its state, its record, and the repository root its path is from. */
+export interface FoundWorkItem {
+  loaded: LoadedRecordKind;
+  state: string | null;
+  record: RecordEntry;
+  root: string;
+}
+
+/**
+ * The work kind holding `id`: the one `kind` names, or the one declared work
+ * kind with a record `id`. Throws a {@link WorkError}.
+ */
+export async function findWorkItem(id: string, cwd: string, kind: string | undefined): Promise<FoundWorkItem> {
   let candidates: string[];
   if (kind !== undefined) {
     candidates = [kind];
@@ -116,7 +138,7 @@ async function findWorkItem(id: string, cwd: string, kind: string | undefined):
       throw new WorkError("work-kind-missing", `${err.code}: ${err.describe()}; without --kind, the declaration names the work kind`);
     }
   }
-  const found: { loaded: LoadedRecordKind; state: string | null; root: string }[] = [];
+  const found: FoundWorkItem[] = [];
   let workKinds = 0;
   for (const file of candidates) {
     let loaded: LoadedRecordKind;
@@ -140,7 +162,7 @@ async function findWorkItem(id: string, cwd: string, kind: string | undefined):
       throw err;
     }
     const record = read.result.records.find((r) => r.id === id);
-    if (record) found.push({ loaded, state: record.state, root: read.root });
+    if (record) found.push({ loaded, state: record.state, record, root: read.root });
   }
   if (workKinds === 0) throw new WorkError("work-kind-missing", "the declaration names no work kind; pass --kind <kind file>");
   if (found.length === 0) throw new WorkError("work-item-unknown", `no work record has the id ${id}`);
@@ -199,16 +221,177 @@ function strip(l: WorkLease): Omit<WorkLease, "item"> {
   return { holder: l.holder, token: l.token, acquiredAt: l.acquiredAt, expiresAt: l.expiresAt };
 }
 
+// ── work history (#2785) ────────────────────────────────────────────────────
+
+/** The version of the `work history` output this chant writes: read contract 1. */
+export const WORK_HISTORY_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for `work history --json`, shipped beside this file. */
+export const WORK_HISTORY_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/work-history/v1/work-history.schema.json";
+
+/** Why `work history` read nothing. Closed. */
+export const WORK_HISTORY_ERROR_CODES = [
+  "kind-unreadable",
+  "work-kind-missing",
+  "work-kind-ambiguous",
+  "work-item-unknown",
+  "not-a-git-repository",
+] as const satisfies readonly ReasonCode[];
+export type WorkHistoryErrorCode = (typeof WORK_HISTORY_ERROR_CODES)[number];
+
+/**
+ * How a claim ended. `released`: its holder, or someone closing out an
+ * expired lease, gave it back, with an outcome when one was given. `held`: it
+ * is the live lease now. `expired`: it ran out and nobody released it or
+ * claimed the item since. `lost`: it ran out unreleased and another claim
+ * took the item.
+ */
+export type ClaimEnd = "released" | "held" | "expired" | "lost";
+
+/** One claim of a work item: one fencing token, from its claim to how it ended. */
+export interface LeaseClaim {
+  token: string;
+  holder: string;
+  acquiredAt: string;
+  /** The expiry its last claim or renew set. */
+  expiresAt: string;
+  renewals: number;
+  ended: ClaimEnd;
+  /** The release, when it was released. */
+  release: { by: string; at: string; outcome: string | null; note: string | null } | null;
+}
+
+/** What `work history --json` prints. */
+export type WorkHistoryDocument =
+  | {
+      $schema: string;
+      contract: number;
+      chant: string;
+      item: string;
+      /** The work kind file, from the repository root. */
+      kind: string;
+      /** The lease ref. */
+      ref: string;
+      /** The history file on the branch, under the member's prefix when the kind's member has one. */
+      ledger: { branch: string; path: string };
+      /** The lease ref's record now, live or expired, or null when there is none. Read from local refs, without fetching. */
+      lease: (Omit<WorkLease, "item"> & { state: "active" | "expired" }) | null;
+      /** Each claim, oldest first. */
+      claims: LeaseClaim[];
+      /** Every line of the history, oldest first. */
+      events: LeaseHistoryRecord[];
+      /** Lines of the history that are not lease events, left out. */
+      malformed: number;
+      summary: { claims: number; released: number; held: number; expired: number; lost: number; outcomes: Record<string, number> };
+    }
+  | { $schema: string; contract: number; chant: string; error: { code: WorkHistoryErrorCode; message: string } };
+
+/** Fold a history into its claims: one per token, in the order they were first seen. */
+export function claimsOf(events: LeaseHistoryRecord[], live: Pick<WorkLeaseState, "token" | "state"> | null): LeaseClaim[] {
+  const byToken = new Map<string, LeaseClaim>();
+  const order: string[] = [];
+  for (const e of events) {
+    let c = byToken.get(e.token);
+    if (!c) {
+      c = { token: e.token, holder: e.holder, acquiredAt: e.acquiredAt, expiresAt: e.expiresAt, renewals: 0, ended: "expired", release: null };
+      byToken.set(e.token, c);
+      order.push(e.token);
+    }
+    if (e.event === "renew") c.renewals++;
+    if (e.event !== "release") c.expiresAt = e.expiresAt;
+    if (e.event === "release") c.release = { by: e.by, at: e.timestamp, outcome: e.outcome ?? null, note: e.note ?? null };
+  }
+  return order.map((token, i) => {
+    const c = byToken.get(token)!;
+    if (c.release) c.ended = "released";
+    else if (live && live.token === token) c.ended = live.state === "active" ? "held" : "expired";
+    else if (i < order.length - 1) c.ended = "lost";
+    else c.ended = "expired";
+    return c;
+  });
+}
+
+/**
+ * Read work item `id`'s lease history (#2785): every claim, renew and release
+ * on `_leases/<id>.jsonl` in the ledger of the member owning the work kind,
+ * folded into claims. Read from the local `chant/lifecycle` branch and lease
+ * refs; it never fetches, like the other read-contract reads.
+ */
+export async function workHistory(req: { id: string; cwd: string; kind?: string }): Promise<WorkHistoryDocument> {
+  const head = { $schema: WORK_HISTORY_OUTPUT_SCHEMA_ID, contract: WORK_HISTORY_CONTRACT_VERSION, chant: readerVersion() };
+  try {
+    if (!WORK_ITEM_ID_PATTERN.test(req.id) || req.id.includes("..")) throw new WorkError("work-item-unknown", `${JSON.stringify(req.id)} is not a work item id`);
+    if (!gitRoot(req.cwd)) throw new WorkError("not-a-git-repository", "a work lease's history is on the chant/lifecycle branch, and this directory is not in a git repository");
+    const { loaded, root } = await findWorkItem(req.id, req.cwd, req.kind);
+    const leaseCwd = dirname(loaded.file);
+    const { prefix } = await resolveMemberLedger(leaseCwd);
+    const { records: events, malformed } = await readLeaseHistory(req.id, { cwd: leaseCwd });
+    const live = (await listWorkLeases({ cwd: leaseCwd, memberPrefix: prefix })).find((l) => l.item === req.id) ?? null;
+    const claims = claimsOf(events, live);
+    const count = (end: ClaimEnd) => claims.filter((c) => c.ended === end).length;
+    const outcomes: Record<string, number> = {};
+    for (const c of claims) if (c.release?.outcome) outcomes[c.release.outcome] = (outcomes[c.release.outcome] ?? 0) + 1;
+    return {
+      ...head,
+      item: req.id,
+      kind: relative(root, loaded.file).split("\\").join("/"),
+      ref: workLeaseRef(req.id, prefix),
+      ledger: { branch: "chant/lifecycle", path: leaseHistoryPath(req.id, prefix) },
+      lease: live ? { holder: live.holder, token: live.token, acquiredAt: live.acquiredAt, expiresAt: live.expiresAt, state: live.state } : null,
+      claims,
+      events,
+      malformed,
+      summary: { claims: claims.length, released: count("released"), held: count("held"), expired: count("expired"), lost: count("lost"), outcomes },
+    };
+  } catch (err) {
+    if (err instanceof WorkError) return { ...head, error: { code: err.code as WorkHistoryErrorCode, message: err.message } };
+    throw err;
+  }
+}
+
+/** The history as lines for a person. */
+export function formatWorkHistory(doc: Extract<WorkHistoryDocument, { claims: unknown }>): string {
+  const lines = [`${doc.item}: ${doc.ledger.branch}:${doc.ledger.path}`];
+  for (const c of doc.claims) {
+    const how = c.release ? `released${c.release.outcome ? ` ${c.release.outcome}` : ""} by ${c.release.by} at ${c.release.at}` : c.ended === "held" ? `held until ${c.expiresAt}` : `${c.ended}, never released (expired ${c.expiresAt})`;
+    lines.push(`  ${c.acquiredAt}  ${c.holder}  token ${c.token}  ${c.renewals} renewal${c.renewals === 1 ? "" : "s"}  ${how}`);
+  }
+  if (doc.claims.length === 0) lines.push("  never claimed");
+  if (doc.malformed > 0) lines.push(`  ${doc.malformed} malformed line${doc.malformed === 1 ? "" : "s"} left out`);
+  return lines.join("\n");
+}
+
+async function runWorkHistory(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const id = args.extraPositional2;
+  if (!id) {
+    console.error(formatError({ message: "history needs a work item id", hint: USAGE }));
+    return 1;
+  }
+  for (const [flag, v] of [["--holder", args.holder], ["--ttl", args.ttl], ["--token", args.token], ["--outcome", args.outcome], ["--note", args.note]] as const) {
+    if (v !== undefined) {
+      console.error(formatError({ message: `history is a read and takes no ${flag}`, hint: USAGE }));
+      return 1;
+    }
+  }
+  const doc = await workHistory({ id, cwd: process.cwd(), kind: args.kind });
+  if (args.json) console.log(JSON.stringify(doc, null, 2));
+  else if ("error" in doc) console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+  else console.log(formatWorkHistory(doc));
+  return "error" in doc ? 1 : 0;
+}
+
 export async function runWorkspaceWork(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const verb = args.extraPositional;
+  if (verb === "history") return runWorkHistory(ctx);
   const fail = (message: string): number => {
     if (args.json) console.log(JSON.stringify({ $schema: WORK_LEASE_OUTPUT_SCHEMA_ID, contract: WORK_LEASE_CONTRACT_VERSION, error: { code: "write-usage-invalid", message } }, null, 2));
     else console.error(formatError({ message, hint: USAGE }));
     return 1;
   };
   if (verb !== "claim" && verb !== "renew" && verb !== "release") {
-    return fail(verb ? `chant workspace work takes claim, renew or release, not ${verb}` : "chant workspace work needs claim, renew or release");
+    return fail(verb ? `chant workspace work takes claim, renew, release or history, not ${verb}` : "chant workspace work needs claim, renew, release or history");
   }
   const id = args.extraPositional2;
   if (!id) return fail(`${verb} needs a work item id`);