@intentius/chant 0.101.0 → 0.102.0

package/src/workspace/work-cli.ts

@@ -4,6 +4,10 @@
  * workspace work history <id>` (#2785): the item's lease history, each claim
  * and how it ended, a read-contract output (`work-history.schema.json`).
  *
+ * And `chant workspace work evidence <id>` (#3159): the `workEvidence`
+ * activity as a command, so a writer outside an Op attaches evidence under
+ * the lease it holds.
+ *
  * 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
  * `--kind` names, or in the one work kind the declaration names that has a
@@ -26,13 +30,18 @@ import type { CommandContext } from "../cli/registry";
 import { parseDuration } from "../op/duration";
 import {
   claimWorkLease,
+  isWorkLeaseOutcome,
   leaseHistoryPath,
+  listKeptAttempts,
   listWorkLeases,
+  outcomeCountsAsAttempt,
   readLeaseHistory,
   releaseWorkLease,
   renewWorkLease,
   workLeaseRef,
   WORK_ITEM_ID_PATTERN,
+  WORK_LEASE_OUTCOMES,
+  type KeptAttempt,
   type WorkLease,
   type WorkLeaseRefusal,
   type WorkLeaseResult,
@@ -53,11 +62,12 @@ export const WORK_LEASE_CONTRACT_VERSION = 1;
 /** `$id` of the JSON Schema for the `--json` output, shipped beside this file. */
 export const WORK_LEASE_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/work-lease/v1/work-lease.schema.json";
 
-export { WORK_LEASE_REFUSALS } from "../lifecycle/work-lease";
+export { WORK_LEASE_REFUSALS, WORK_LEASE_OUTCOMES } 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]",
+  "chant workspace work claim|renew|release <id> --holder <name> [--kind <kind file>] [--ttl <seconds|duration>] [--token <token>] [--outcome <outcome>] [--note <text>] [--json]",
   "chant workspace work history <id> [--kind <kind file>] [--json]",
+  "chant workspace work evidence <id> --holder <name> --token <token> --from <file|-> [--kind <kind file>]",
 ].join("\n");
 
 /** Exit code when the lease was refused rather than the command failing. */
@@ -193,6 +203,9 @@ export async function workLease(req: WorkLeaseRequest): Promise<WorkLeaseDocumen
   const doc = { $schema: WORK_LEASE_OUTPUT_SCHEMA_ID, contract: WORK_LEASE_CONTRACT_VERSION };
   try {
     if (!WORK_ITEM_ID_PATTERN.test(req.id) || req.id.includes("..")) throw new WorkError("write-usage-invalid", `${JSON.stringify(req.id)} is not a work item id`);
+    if (req.outcome !== undefined && !isWorkLeaseOutcome(req.outcome)) {
+      throw new WorkError("write-usage-invalid", `${JSON.stringify(req.outcome)} is not a lease outcome: use one of ${WORK_LEASE_OUTCOMES.join(", ")}`);
+    }
     if (!gitRoot(req.cwd)) throw new WorkError("not-a-git-repository", "a work lease is a git ref, and this directory is not in a git repository");
     const { loaded, state, root } = await findWorkItem(req.id, req.cwd, req.kind);
     if (req.verb === "claim" && state !== null && (loaded.kind.closedStates ?? []).includes(state)) {
@@ -259,6 +272,27 @@ export interface LeaseClaim {
   ended: ClaimEnd;
   /** The release, when it was released. */
   release: { by: string; at: string; outcome: string | null; note: string | null } | null;
+  /**
+   * Whether the claim counts toward the item's attempt limit (#3147): one
+   * released `not_done` or `abandoned`, with no outcome or an outcome from
+   * before the list was closed, or one that expired or was lost unreleased.
+   * Not one that is held, and not one released with any other outcome.
+   */
+  attempt: boolean;
+  /** The ref keeping this claim's unfinished work, `refs/chant/kept/.../<item>/<token>`, or null. */
+  kept: string | null;
+}
+
+/** An item's attempts against its limit (#3147). */
+export interface WorkAttempts {
+  /** The claims that count as attempts. */
+  failed: number;
+  /** The item's limit: its own field, else its kind's default; null when neither declares one. */
+  limit: number | null;
+  /** How many attempts are left, never below 0; null without a limit. */
+  remaining: number | null;
+  /** True once failed reaches the limit: a runner leaves the item to people. */
+  exhausted: boolean;
 }
 
 /** What `work history --json` prints. */
@@ -283,17 +317,21 @@ export type WorkHistoryDocument =
       /** 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> };
+      /** The item's attempts against its limit (#3147). */
+      attempts: WorkAttempts;
+      /** Every kept attempt of the item, by ref (#3147). */
+      kept: KeptAttempt[];
     }
   | { $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[] {
+export function claimsOf(events: LeaseHistoryRecord[], live: Pick<WorkLeaseState, "token" | "state"> | null, kept: readonly KeptAttempt[] = []): 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 };
+      c = { token: e.token, holder: e.holder, acquiredAt: e.acquiredAt, expiresAt: e.expiresAt, renewals: 0, ended: "expired", release: null, attempt: false, kept: null };
       byToken.set(e.token, c);
       order.push(e.token);
     }
@@ -307,10 +345,30 @@ export function claimsOf(events: LeaseHistoryRecord[], live: Pick<WorkLeaseState
     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";
+    c.attempt = c.ended === "released" ? outcomeCountsAsAttempt(c.release?.outcome) : c.ended !== "held";
+    c.kept = kept.find((k) => k.token === token)?.ref ?? null;
     return c;
   });
 }
 
+/**
+ * The attempt limit of a work record (#3147): the integer in the field the
+ * kind's `work.attempts.field` names, else the kind's `work.attempts.max`;
+ * null when the kind declares no attempts.
+ */
+export function attemptLimit(kind: LoadedRecordKind["kind"], data: Record<string, unknown> | null): number | null {
+  const spec = kind.work?.attempts;
+  if (!spec) return null;
+  const own = data?.[spec.field];
+  return typeof own === "number" && Number.isInteger(own) && own >= 1 ? own : spec.max;
+}
+
+/** Count `claims`' attempts against `limit`. */
+export function attemptsOf(claims: readonly LeaseClaim[], limit: number | null): WorkAttempts {
+  const failed = claims.filter((c) => c.attempt).length;
+  return { failed, limit, remaining: limit === null ? null : Math.max(0, limit - failed), exhausted: limit !== null && failed >= limit };
+}
+
 /**
  * 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,
@@ -322,12 +380,13 @@ export async function workHistory(req: { id: string; cwd: string; kind?: string
   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 { loaded, root, record } = await findWorkItem(req.id, req.cwd, req.kind);
     const leaseCwd = dirname(loaded.file);
-    const { prefix } = await resolveMemberLedger(leaseCwd);
+    const { prefix, members } = 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 kept = await listKeptAttempts(req.id, { cwd: leaseCwd, members });
+    const claims = claimsOf(events, live, kept);
     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;
@@ -342,6 +401,8 @@ export async function workHistory(req: { id: string; cwd: string; kind?: string
       events,
       malformed,
       summary: { claims: claims.length, released: count("released"), held: count("held"), expired: count("expired"), lost: count("lost"), outcomes },
+      attempts: attemptsOf(claims, attemptLimit(loaded.kind, record.data)),
+      kept,
     };
   } catch (err) {
     if (err instanceof WorkError) return { ...head, error: { code: err.code as WorkHistoryErrorCode, message: err.message } };
@@ -357,10 +418,73 @@ export function formatWorkHistory(doc: Extract<WorkHistoryDocument, { claims: un
     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");
+  const a = doc.attempts;
+  if (a.limit !== null) lines.push(`  ${a.failed} of ${a.limit} attempt${a.limit === 1 ? "" : "s"} used${a.exhausted ? "; left to people" : ""}`);
+  else if (a.failed > 0) lines.push(`  ${a.failed} attempt${a.failed === 1 ? "" : "s"} counted; the kind declares no limit`);
+  for (const k of doc.kept) lines.push(`  kept: ${k.ref} (${k.commit.slice(0, 12)})`);
   if (doc.malformed > 0) lines.push(`  ${doc.malformed} malformed line${doc.malformed === 1 ? "" : "s"} left out`);
   return lines.join("\n");
 }
 
+/**
+ * `chant workspace work evidence <id> --holder <name> --token <token> --from
+ * <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
+ * work-evidence document; exit 0 when the entry was appended, 1 otherwise.
+ */
+async function runWorkEvidence(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const { attachWorkEvidence, WORK_EVIDENCE_CONTRACT_VERSION, WORK_EVIDENCE_OUTPUT_SCHEMA_ID } = await import("./work-evidence");
+  const print = (doc: unknown, code: number): number => {
+    console.log(JSON.stringify(doc, null, 2));
+    return code;
+  };
+  const fail = (message: string): number =>
+    print({ $schema: WORK_EVIDENCE_OUTPUT_SCHEMA_ID, contract: WORK_EVIDENCE_CONTRACT_VERSION, error: { code: "write-usage-invalid", message: `${message}\n${USAGE}` } }, 1);
+  const id = args.extraPositional2;
+  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");
+  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}`);
+  }
+  let fields: Record<string, unknown>;
+  try {
+    const { readFileSync } = await import("node:fs");
+    const { resolve } = await import("node:path");
+    const text = readFileSync(args.migrateFrom === "-" ? 0 : resolve(process.cwd(), args.migrateFrom), "utf-8");
+    const parsed: unknown = JSON.parse(text);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("the entry is not a JSON object");
+    fields = parsed as Record<string, unknown>;
+  } catch (err) {
+    return print(
+      { $schema: WORK_EVIDENCE_OUTPUT_SCHEMA_ID, contract: WORK_EVIDENCE_CONTRACT_VERSION, error: { code: "write-input-invalid", message: `--from ${args.migrateFrom} could not be read: ${err instanceof Error ? err.message : String(err)}` } },
+      1,
+    );
+  }
+  const known = ["criterion", "result", "title", "url", "path", "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);
+  const doc = await attachWorkEvidence({
+    cwd: process.cwd(),
+    item: id,
+    kind: args.kind,
+    holder: args.holder,
+    token: args.token,
+    criterion: str("criterion") ?? "",
+    result: fields.result as never,
+    title: str("title") ?? "",
+    url: str("url"),
+    path: str("path"),
+    asOf: str("as_of"),
+  });
+  return print(doc, "error" in doc ? 1 : 0);
+}
+
 async function runWorkHistory(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const id = args.extraPositional2;
@@ -385,13 +509,14 @@ export async function runWorkspaceWork(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const verb = args.extraPositional;
   if (verb === "history") return runWorkHistory(ctx);
+  if (verb === "evidence") return runWorkEvidence(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, release or history, not ${verb}` : "chant workspace work needs claim, renew, release or history");
+    return fail(verb ? `chant workspace work takes claim, renew, release, history or evidence, not ${verb}` : "chant workspace work needs claim, renew, release, history or evidence");
   }
   const id = args.extraPositional2;
   if (!id) return fail(`${verb} needs a work item id`);

package/src/workspace/work-evidence.schema.json

@@ -184,7 +184,9 @@
                 "ratify-quorum-not-met",
                 "write-scope-member",
                 "write-scope-kind",
+                "write-scope-class-unknown",
                 "agent-unknown",
+                "principal-unidentified",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",

package/src/workspace/work-history.schema.json

@@ -65,7 +65,7 @@
         },
         "outcome": {
           "type": "string",
-          "description": "How the work ended, on a release. Free text such as done, not_done, gated or waiting."
+          "description": "How the work ended, on a release: one of the closed list in work-lease.schema.json's $defs/outcome (#3147), done, not_done, abandoned, gated, waiting, dropped, redraft or ask. A line written before #3147 may hold other free text."
         },
         "note": {
           "type": "string"
@@ -146,6 +146,17 @@
               }
             }
           ]
+        },
+        "attempt": {
+          "type": "boolean",
+          "description": "Added in contract 1 by #3147. Whether the claim counts toward the item's attempt limit: released not_done or abandoned, released with no outcome or with free text from before the outcomes were closed, or ended expired or lost. Never one that is held, and never one released done, gated, waiting, dropped, redraft or ask."
+        },
+        "kept": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Added in contract 1 by #3147. The ref keeping the claim's unfinished work, refs/chant/kept/[<member>/]<item>/<token>, written when a run that changes the checkout ended not_done; null when there is none."
         }
       }
     },
@@ -300,6 +311,67 @@
               "description": "How many released claims gave each outcome."
             }
           }
+        },
+        "attempts": {
+          "type": "object",
+          "description": "Added in contract 1 by #3147. The item's attempts against its limit. limit is the item's own field named by the kind's work.attempts.field, else the kind's work.attempts.max, else null. A runner leaves an exhausted item to people.",
+          "required": [
+            "failed",
+            "limit",
+            "remaining",
+            "exhausted"
+          ],
+          "properties": {
+            "failed": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "The claims whose attempt is true."
+            },
+            "limit": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 1
+            },
+            "remaining": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0,
+              "description": "limit minus failed, never below 0; null without a limit."
+            },
+            "exhausted": {
+              "type": "boolean",
+              "description": "True once failed reaches the limit; false without one."
+            }
+          }
+        },
+        "kept": {
+          "type": "array",
+          "description": "Added in contract 1 by #3147. Every kept attempt of the item, from the local refs under refs/chant/kept/[<member>/]<item>/, sorted by ref.",
+          "items": {
+            "type": "object",
+            "required": [
+              "token",
+              "ref",
+              "commit"
+            ],
+            "properties": {
+              "token": {
+                "type": "string",
+                "description": "The lease token the attempt ran under."
+              },
+              "ref": {
+                "type": "string"
+              },
+              "commit": {
+                "type": "string",
+                "description": "The commit the ref points at."
+              }
+            }
+          }
         }
       }
     },

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

@@ -9,14 +9,14 @@ import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { cleanScratch, contract, git, REPO, repo } from "./__fixtures__/contract-repo";
 import { claimWorkLease, releaseWorkLease, renewWorkLease, type LeaseHistoryRecord } from "../lifecycle/work-lease";
-import { claimsOf, formatWorkHistory, workHistory, type WorkHistoryDocument } from "./work-cli";
+import { claimsOf, formatWorkHistory, workHistory, workLease, type WorkHistoryDocument } from "./work-cli";
 import historySchema from "./work-history.schema.json";
 
 const REF = join(REPO, "reference-workspace");
 const { expectValid } = contract(historySchema);
 
-function work(id: string): string {
-  const data = { schema: 1, id, title: `Work ${id}`, state: "open", implements: [], needs: [], constrains: ["path:app/server.mjs"], evidence: [], opened_on: "2026-09-25", source: { kind: "workspace", member: "app" }, supersedes: [] };
+function work(id: string, extra: Record<string, unknown> = {}): string {
+  const data = { schema: 1, id, title: `Work ${id}`, state: "open", implements: [], needs: [], constrains: ["path:app/server.mjs"], evidence: [], opened_on: "2026-09-25", source: { kind: "workspace", member: "app" }, supersedes: [], ...extra };
   return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
 }
 
@@ -46,6 +46,7 @@ beforeAll(() => {
     "design/work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
     "design/work/W-001-one.md": work("W-001"),
     "design/work/W-002-two.md": work("W-002"),
+    "design/work/W-004-four.md": work("W-004", { max_attempts: 2 }),
   });
   git(root, "config", "user.name", "History Test");
   git(root, "config", "user.email", "history@example.com");
@@ -88,6 +89,10 @@ describe("workspace work history (#2785)", () => {
     ]);
     expect(doc.events.map((e) => e.event)).toEqual(["claim", "renew", "release", "claim", "claim"]);
     expect(doc.summary).toEqual({ claims: 3, released: 1, held: 0, expired: 1, lost: 1, outcomes: { not_done: 1 } });
+    // Each of the three counts as an attempt (#3147): not_done, lost and expired, against the kind's default of 3.
+    expect(doc.claims.map((c) => c.attempt)).toEqual([true, true, true]);
+    expect(doc.attempts).toEqual({ failed: 3, limit: 3, remaining: 0, exhausted: true });
+    expect(formatWorkHistory(doc)).toContain("3 of 3 attempts used; left to people");
     // The history file is where git would find it, under the member's prefix.
     expect(git(root, "show", `chant/lifecycle:${doc.ledger.path}`).split("\n")).toHaveLength(5);
     expect(formatWorkHistory(doc)).toContain("released not_done by steward/dispatch@1");
@@ -107,6 +112,37 @@ describe("workspace work history (#2785)", () => {
     expect(doc.claims.map((c) => c.ended)).toEqual(["released", "held"]);
     expect(doc.lease).toMatchObject({ holder: "worker-b", token: live.lease.token, state: "active" });
     expect(doc.summary.outcomes).toEqual({ done: 1 });
+    expect(doc.attempts).toEqual({ failed: 0, limit: 3, remaining: 3, exhausted: false });
+  });
+
+  test("outcomes that built nothing don't count as attempts, the item's max_attempts overrides the kind's, and kept attempts are listed (#3147)", async () => {
+    const now = () => new Date();
+    const tokens: string[] = [];
+    for (const outcome of ["dropped", "redraft", "ask", "waiting", "gated", "not_done"]) {
+      const c = await claimWorkLease("W-004", "worker-a", { cwd: kindDir, now });
+      if (!c.ok) throw new Error(c.message);
+      tokens.push(c.lease.token);
+      await releaseWorkLease("W-004", "worker-a", { cwd: kindDir, now, token: c.lease.token, outcome });
+    }
+    // The not_done attempt's work, kept the way a run that changes the checkout keeps it.
+    const kept = `refs/chant/kept/design/W-004/${tokens[5]}`;
+    git(root, "update-ref", kept, "HEAD");
+
+    const doc = await workHistory({ id: "W-004", cwd: root });
+    expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.claims.map((c) => c.attempt)).toEqual([false, false, false, false, false, true]);
+    expect(doc.attempts).toEqual({ failed: 1, limit: 2, remaining: 1, exhausted: false });
+    expect(doc.claims.map((c) => c.kept)).toEqual([null, null, null, null, null, kept]);
+    expect(doc.kept).toEqual([{ token: tokens[5], ref: kept, commit: git(root, "rev-parse", "HEAD").trim() }]);
+    expect(formatWorkHistory(doc)).toContain(`kept: ${kept}`);
+  });
+
+  test("a release outside the closed list of outcomes is refused (#3147)", async () => {
+    await expect(releaseWorkLease("W-002", "worker-b", { cwd: kindDir, outcome: "skipped" })).rejects.toThrow(/not a work lease outcome/);
+    const doc = await workLease({ verb: "release", id: "W-002", holder: "worker-b", cwd: root, outcome: "skipped" });
+    expect(doc).toMatchObject({ error: { code: "write-usage-invalid" } });
+    expect((doc as { error: { message: string } }).error.message).toMatch(/done, not_done, abandoned, gated, waiting, dropped, redraft, ask/);
   });
 
   test("an item never claimed has no claims; an unknown item is an error", async () => {
@@ -142,12 +178,19 @@ describe("claimsOf", () => {
   });
 
   test("a release by someone closing out an expired lease keeps the holder and records who released it", () => {
-    const claims = claimsOf([e("claim", "a"), e("release", "a", { by: "janitor", outcome: "expired" })], null);
+    const claims = claimsOf([e("claim", "a"), e("release", "a", { by: "janitor", outcome: "abandoned" })], null);
     expect(claims).toEqual([
-      { token: "a", holder: "h-a", acquiredAt: "2026-09-25T00:00:00.000Z", expiresAt: "2026-09-25T00:10:00.000Z", renewals: 0, ended: "released", release: { by: "janitor", at: "2026-09-25T00:00:00.000Z", outcome: "expired", note: null } },
+      { token: "a", holder: "h-a", acquiredAt: "2026-09-25T00:00:00.000Z", expiresAt: "2026-09-25T00:10:00.000Z", renewals: 0, ended: "released", release: { by: "janitor", at: "2026-09-25T00:00:00.000Z", outcome: "abandoned", note: null }, attempt: true, kept: null },
     ]);
   });
 
+  test("a release with free text from before the outcomes were closed counts as an attempt, and one with no outcome too", () => {
+    expect(claimsOf([e("claim", "a"), e("release", "a", { outcome: "skipped" })], null)[0].attempt).toBe(true);
+    expect(claimsOf([e("claim", "a"), e("release", "a")], null)[0].attempt).toBe(true);
+    expect(claimsOf([e("claim", "a"), e("release", "a", { outcome: "done" })], null)[0].attempt).toBe(false);
+    expect(claimsOf([e("claim", "a")], { token: "a", state: "active" })[0].attempt).toBe(false);
+  });
+
   test("the live ref decides between held and expired for the newest claim", () => {
     expect(claimsOf([e("claim", "a")], { token: "a", state: "active" })[0].ended).toBe("held");
     expect(claimsOf([e("claim", "a")], { token: "a", state: "expired" })[0].ended).toBe("expired");

package/src/workspace/work-kind-fields.test.ts

@@ -0,0 +1,154 @@
+/**
+ * #3147 — the work kind's fields that replace studio's x-factory on work
+ * items: a contract link read with the contract's state, a builder tier from
+ * the tiers the kind declares, decision-point answers joined by the item's id
+ * (from the tree, and from the lifecycle ledger where a steward asked them),
+ * the box's intent as a source, an attempt limit, and result.lease.
+ */
+
+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 { writeBlobToPath } from "../lifecycle/git";
+import { answersLedgerDir } from "./answers-ledger";
+import { parseFrontMatter } from "./records";
+import { queryRecords } from "./records-cli";
+import { newRecord } from "./records-write";
+import recordsSchema from "./records.schema.json";
+
+const REF = join(REPO, "reference-workspace");
+const ref = (path: string) => readFileSync(join(REF, path), "utf-8");
+const records = contract(recordsSchema);
+
+const DECISION = (() => {
+  const fm = parseFrontMatter(ref("decisions/ref-001-how-the-app-is-deployed.md"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+})();
+
+function decision(id: string, state = "decided"): string {
+  const proposed = state === "proposed";
+  const data = { ...DECISION, id, title: `Record ${id}`, state, supersedes: [], evidence: [], constrains: ["member:app"], ...(proposed ? { choice: null, decided_by: null, decided_on: null } : {}) };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+function work(id: string, fields: Record<string, unknown> = {}): string {
+  const data = { schema: 1, id, title: `Work ${id}`, state: "open", implements: [], needs: [], constrains: ["member:app"], evidence: [], opened_on: "2026-10-03", source: { kind: "workspace", member: "app" }, supersedes: [], ...fields };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+/** The reference slice-tier answer, about `item`, under the id `id`. */
+function answer(id: string, item: string, extra: Record<string, unknown> = {}): string {
+  const fm = parseFrontMatter(ref("answers/slice-tier-01eb5382958d.md"));
+  if (!fm.ok) throw new Error(fm.message);
+  const data = { ...fm.value, id, constrains: [item], ...extra };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+// The reference work kind, with a contract kind: here the decision kind's shape, kept in contracts/.
+const KIND = ref("work/work.kind.mjs").replace(
+  '    answers: "../answers/answer.kind.mjs",\n',
+  '    answers: "../answers/answer.kind.mjs",\n    contract: { field: "contract", kind: "../contracts/decision.kind.mjs" },\n',
+);
+
+let root: string;
+
+beforeAll(async () => {
+  expect(KIND).toContain("../contracts/decision.kind.mjs");
+  root = repo({
+    "chant.workspace.json": JSON.stringify({ name: "box", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "the app" }] }),
+    "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/points.json": ref("decisions/points.json"),
+    "decisions/intent-001-what-to-build.md": decision("intent-001"),
+    "contracts/decision.kind.mjs": ref("decisions/decision.kind.mjs"),
+    "contracts/decision.schema.json": ref("decisions/decision.schema.json"),
+    "contracts/con-001-notes.md": decision("con-001"),
+    "contracts/con-002-draft.md": decision("con-002", "proposed"),
+    "answers/answer.kind.mjs": ref("answers/answer.kind.mjs"),
+    "answers/answer.schema.json": ref("answers/answer.schema.json"),
+    "answers/slice-tier-0123456789ab.md": answer("slice-tier-0123456789ab", "W-001"),
+    "work/work.kind.mjs": KIND,
+    "work/work.schema.json": ref("work/work.schema.json"),
+    "work/W-001-built.md": work("W-001", { contract: "con-001", tier: "small", max_attempts: 5, result: { lease: "6f0c11aa" } }),
+    "work/W-002-draft.md": work("W-002", { contract: "con-002", tier: "huge" }),
+    "work/W-003-missing.md": work("W-003", { contract: "con-404" }),
+    "work/W-004-plain.md": work("W-004"),
+    "work/W-005-intent.md": work("W-005", {
+      implements: ["intent-001"],
+      source: { intent: { decision: "intent-001", question: "What should the box build?", answer: "A notes app", by: "morgan", at: "2026-10-03T09:00:00Z" } },
+    }),
+  });
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", "the box");
+  // A question a steward asked in its turn sits on the lifecycle ledger, never in the checkout (#2786).
+  await writeBlobToPath(answersLedgerDir("answer"), "understand-0123456789ab.md", answer("understand-0123456789ab", "W-001", { point: "understand", answer: "proceed", answered_by: ["morgan"] }), "ask understand", { cwd: join(root, "answers") });
+});
+afterAll(cleanScratch);
+
+describe("the work kind's fields (#3147)", () => {
+  test("contract links with the contract's state, tier and contract warnings, and answers joined by id from the tree and the ledger", async () => {
+    const doc = await queryRecords({ kind: "work/work.kind.mjs", cwd: root });
+    records.expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.summary).toMatchObject({ total: 5, valid: 5, invalid: 0 });
+    const by = Object.fromEntries(doc.records.map((r) => [r.id, r]));
+    const codes = (id: string) => by[id].warnings.map((w: { code: string }) => w.code);
+
+    expect(by["W-001"].contract).toEqual({ id: "con-001", state: "decided" });
+    expect(codes("W-001")).toEqual([]);
+    expect(by["W-002"].contract).toEqual({ id: "con-002", state: "proposed" });
+    expect(codes("W-002")).toEqual(["work-contract-undecided", "work-tier-unknown"]);
+    expect(by["W-003"].contract).toEqual({ id: "con-404", state: null });
+    expect(codes("W-003")).toEqual(["work-contract-unknown"]);
+    expect(by["W-004"].contract).toBeNull();
+
+    // The item carries neither answer; the read joins both by its id.
+    expect(by["W-001"].answers).toEqual([
+      { id: "slice-tier-0123456789ab", point: "slice-tier", state: "answered", answer: "small", answeredBy: [] },
+      { id: "understand-0123456789ab", point: "understand", state: "answered", answer: "proceed", answeredBy: ["morgan"] },
+    ]);
+    expect(by["W-002"].answers).toEqual([]);
+    expect(by["W-005"].data).toMatchObject({ source: { intent: { decision: "intent-001", answer: "A notes app", by: "morgan" } } });
+  });
+
+  test("at a revision, answers come from that tree only: the ledger is not part of it", async () => {
+    const doc = await queryRecords({ kind: "work/work.kind.mjs", cwd: root, at: "HEAD" });
+    records.expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.records.find((r) => r.id === "W-001")!.answers!.map((a) => a.id)).toEqual(["slice-tier-0123456789ab"]);
+  });
+
+  test("the schema keeps only the lease under result, and an intent source needs its decision, answer and who decided", async () => {
+    const fields = (over: Record<string, unknown>) =>
+      JSON.stringify({ schema: 1, title: "More", state: "open", implements: [], needs: [], constrains: ["member:app"], evidence: [], opened_on: "2026-10-03", source: { kind: "workspace", member: "app" }, supersedes: [], ...over });
+    const kind = "work/work.kind.mjs";
+    const ok = await newRecord({ kind, fields: fields({ result: { lease: "6f0c" }, max_attempts: 2, tier: "large", contract: "con-001" }), dryRun: true, cwd: root });
+    expect("error" in ok ? ok.error : null).toBeNull();
+    for (const over of [
+      { result: { lease: "6f0c", agent: "builder" } },
+      { max_attempts: 0 },
+      { source: { intent: { decision: "intent-001", answer: "A notes app" } } },
+      { source: { intent: { decision: "intent-001", by: "morgan" } } },
+    ]) {
+      const doc = await newRecord({ kind, fields: fields(over), dryRun: true, cwd: root });
+      expect("error" in doc && doc.error.code, JSON.stringify(over)).toBe("record-schema-invalid");
+    }
+  });
+
+  test("a kind that lists a tier twice, or names an attempt limit below one, is kind-invalid", async () => {
+    for (const [from, to] of [
+      ['tiers: ["small", "medium", "large"]', 'tiers: ["small", "small"]'],
+      ['max: 3', 'max: 0'],
+    ]) {
+      const dir = repo({
+        "work/work.kind.mjs": ref("work/work.kind.mjs").replace(from, to),
+        "work/work.schema.json": ref("work/work.schema.json"),
+      });
+      const doc = await queryRecords({ kind: "work/work.kind.mjs", cwd: dir });
+      expect("error" in doc && doc.error.code, to).toBe("kind-invalid");
+    }
+  });
+});

package/src/workspace/work-lease.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/work-lease/v1/work-lease.schema.json",
   "title": "chant workspace work output",
-  "description": "What `chant workspace work claim|renew|release <id> --holder <name> --json` prints (#2732, ws-055): the work lease it wrote, the reason it was refused, or the reason the command could not run. Version 1 of the write contract for work leases. The lease is the ref refs/chant/lease/[_members/<member>/]work/<id>; each write also appends to _leases/<id>.jsonl on chant/lifecycle. Readers ignore fields they do not know; a field is only ever added within a version. The refusal and error codes are closed lists, each in the one closed list of `reason-codes.ts`.",
+  "description": "What `chant workspace work claim|renew|release <id> --holder <name> --json` prints (#2732, ws-055): the work lease it wrote, the reason it was refused, or the reason the command could not run. Version 1 of the write contract for work leases. The lease is the ref refs/chant/lease/[_members/<member>/]work/<id>; each write also appends to _leases/<id>.jsonl on chant/lifecycle. Readers ignore fields they do not know; a field is only ever added within a version. The refusal and error codes are closed lists, each in the one closed list of `reason-codes.ts`. A release's --outcome is one of the closed list `$defs/outcome` (#3147); any other value is refused with write-usage-invalid.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -15,6 +15,19 @@
     }
   ],
   "$defs": {
+    "outcome": {
+      "description": "How a work lease ended, as a release records it on _leases/<id>.jsonl (#3147). Closed: a new outcome is a contract change. done: the work was finished. not_done: a build ran and did not finish, or the run failed; counts as an attempt. abandoned: an expired lease closed out by someone other than its holder; counts as an attempt. gated: the run stopped at a gate. waiting: the run stopped on a decision point's open question. dropped: the item was dropped, such as by a refuse at the understand point. redraft and ask: the understand point sent the item back to its author. Only not_done and abandoned count toward an item's attempt limit.",
+      "enum": [
+        "done",
+        "not_done",
+        "abandoned",
+        "gated",
+        "waiting",
+        "dropped",
+        "redraft",
+        "ask"
+      ]
+    },
     "lease": {
       "type": "object",
       "required": [