@intentius/chant 0.90.0 → 0.93.0

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

@@ -0,0 +1,233 @@
+{
+  "$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`.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/refusal"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "lease": {
+      "type": "object",
+      "required": [
+        "holder",
+        "token",
+        "acquiredAt",
+        "expiresAt"
+      ],
+      "properties": {
+        "holder": {
+          "type": "string",
+          "description": "Who holds the lease, as --holder gave it."
+        },
+        "token": {
+          "type": "string",
+          "description": "The fencing token: new on every claim, kept by every renew."
+        },
+        "acquiredAt": {
+          "type": "string",
+          "description": "When the lease was claimed, ISO 8601."
+        },
+        "expiresAt": {
+          "type": "string",
+          "description": "When the lease expires unless renewed, ISO 8601."
+        }
+      }
+    },
+    "result": {
+      "description": "The lease was written. Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "item",
+        "event",
+        "kind",
+        "ref",
+        "lease",
+        "history"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/work-lease/v1/work-lease.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "item": {
+          "type": "string",
+          "description": "The work item's id."
+        },
+        "event": {
+          "enum": [
+            "claim",
+            "renew",
+            "release"
+          ]
+        },
+        "kind": {
+          "type": "string",
+          "description": "The work kind file, relative to the repository root, with / separators."
+        },
+        "ref": {
+          "type": "string",
+          "description": "The lease ref, in the ledger of the member owning the work kind."
+        },
+        "lease": {
+          "description": "The lease after a claim or renew; the lease that was given back after a release.",
+          "$ref": "#/$defs/lease"
+        },
+        "history": {
+          "type": "object",
+          "required": [
+            "path",
+            "commit",
+            "pushed"
+          ],
+          "properties": {
+            "path": {
+              "type": "string",
+              "description": "The history file on chant/lifecycle, _leases/<id>.jsonl under the member's prefix."
+            },
+            "commit": {
+              "type": "string",
+              "description": "The chant/lifecycle commit that appended the line."
+            },
+            "pushed": {
+              "type": "boolean",
+              "description": "Whether chant/lifecycle reached the remote. False with no remote, and when the remote refused it; the lease stands either way."
+            }
+          }
+        },
+        "refused": false,
+        "error": false
+      }
+    },
+    "refusal": {
+      "description": "The lease was refused. Exit code 2. Nothing was written.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "item",
+        "event",
+        "kind",
+        "ref",
+        "refused"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/work-lease/v1/work-lease.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "item": {
+          "type": "string",
+          "description": "The work item's id."
+        },
+        "event": {
+          "enum": [
+            "claim",
+            "renew",
+            "release"
+          ]
+        },
+        "kind": {
+          "type": "string",
+          "description": "The work kind file, relative to the repository root, with / separators."
+        },
+        "ref": {
+          "type": "string",
+          "description": "The lease ref, in the ledger of the member owning the work kind."
+        },
+        "refused": {
+          "type": "object",
+          "required": [
+            "code",
+            "message",
+            "heldBy"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "lease-held",
+                "lease-not-held",
+                "lease-token-mismatch",
+                "lease-race",
+                "lease-push-rejected"
+              ]
+            },
+            "message": {
+              "type": "string",
+              "description": "Names the holder when someone holds the lease."
+            },
+            "heldBy": {
+              "description": "The live lease, when there is one.",
+              "oneOf": [
+                {
+                  "type": "null"
+                },
+                {
+                  "$ref": "#/$defs/lease"
+                }
+              ]
+            }
+          }
+        },
+        "lease": false,
+        "error": false
+      }
+    },
+    "failure": {
+      "description": "The command could not run. Exit code 1. Nothing was written.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/work-lease/v1/work-lease.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "write-usage-invalid",
+                "kind-unreadable",
+                "work-kind-missing",
+                "work-kind-ambiguous",
+                "work-item-unknown",
+                "work-item-closed",
+                "not-a-git-repository"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "lease": false,
+        "refused": false
+      }
+    }
+  }
+}

package/src/workspace/work-readiness-chud.test.ts

@@ -0,0 +1,145 @@
+/**
+ * The work kind's `ready`/`blockedBy` against chud's ready queue (ws-055,
+ * #2734).
+ *
+ * chud's `readyQueue` (packages/runtime/src/ready.mjs at jhgaylor/chud
+ * 43afcf1) puts a contract in the ready set once it is approved and in
+ * force, every `depends_on` id is `met` (drivers.mjs's `memberState`), and no
+ * unit is open against it; a contract that is itself met leaves the queue.
+ *
+ * Of those rules, the work kind's `ready` and `blockedBy` (work.ts) can
+ * express two directly, with no new field:
+ *
+ * - dependencies closed: a work item's `needs` id counts as closed once its
+ *   `state` is the kind's `done` state, same as `depends_on` counts a
+ *   dependency closed once it is `met`. A `needs` id that never reaches
+ *   `done` (here, one that is `dropped`) blocks forever, the same way a
+ *   retired contract does.
+ * - a record that is itself already `done` (or `dropped`, or merely
+ *   `in-progress`) is not `ready`: `ready` requires `state === "open"`, the
+ *   same "already met/already running leaves the queue" rule ready.mjs
+ *   states for a contract that is itself met.
+ *
+ * The rules ready.mjs adds on top -- approval before a dependency counts
+ * (memberState's draft/failing cases), re-checking that a `met` dependency's
+ * newest evidence still passes, and refusing a contract while a unit is open
+ * against it -- have no equivalent in a `needs` link. The full table of
+ * every ready.mjs rule and its home (a `needs` link, the runner, or "not
+ * applicable") is on INTENTIUS/chant#2734.
+ *
+ * This fixture mirrors a small chud contract graph as work items and checks
+ * `queryRecords`'s `ready`/`blockedBy` against a minimal, local
+ * re-implementation of the expressible subset of ready.mjs's rule (met
+ * depends_on, self not already met), so a regression in either the work
+ * kind's readiness formula or this reading of ready.mjs's rule shows up as a
+ * mismatch.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, REPO, repo } from "./__fixtures__/contract-repo";
+import { queryRecords } from "./records-cli";
+
+const REF = join(REPO, "reference-workspace");
+const WORK = "work/work.kind.mjs";
+
+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-09-24",
+    source: { kind: "workspace", member: "app" },
+    supersedes: [],
+    ...fields,
+  };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+/**
+ * The expressible subset of ready.mjs's rule, on a graph shaped like
+ * `depends_on`: ready once the item is `open` (not already met, not already
+ * running) and every dependency is `done` (chud's "met"). A dependency that
+ * is `dropped` never becomes done, so it blocks forever -- the same effect
+ * ready.mjs gets from a retired dependency.
+ */
+function chudReadyIsh(items: { id: string; state: string; needs: string[] }[]): { ready: Set<string>; blockedBy: Map<string, string[]> } {
+  const stateOf = new Map(items.map((i) => [i.id, i.state]));
+  const ready = new Set<string>();
+  const blockedBy = new Map<string, string[]>();
+  for (const item of items) {
+    const unmet = item.needs.filter((id) => stateOf.get(id) !== "done");
+    blockedBy.set(item.id, unmet);
+    if (item.state === "open" && unmet.length === 0) ready.add(item.id);
+  }
+  return { ready, blockedBy };
+}
+
+let root: string;
+
+beforeAll(() => {
+  root = repo({
+    "chant.workspace.json": JSON.stringify({ name: "w", schema: 1, members: [] }, null, 2),
+    "decisions/decision.kind.mjs": readFileSync(join(REF, "decisions", "decision.kind.mjs"), "utf-8"),
+    "decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
+    "work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
+    "work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
+    // W-001: already done, so it leaves the ready queue -- ready.mjs's "a
+    // contract that is itself met is done, not ready".
+    "work/W-001-base.md": work("W-001", { state: "done", closed_on: "2026-09-24", evidence: [{ title: "shipped", url: "https://example.com/w1" }] }),
+    // W-002: needs W-001, which is done -- both rules agree this is ready.
+    "work/W-002-after-base.md": work("W-002", { needs: ["W-001"] }),
+    // W-003: needs W-004, which is dropped and so never turns done -- blocked
+    // forever, the same as a retired dependency in ready.mjs.
+    "work/W-003-needs-dropped.md": work("W-003", { needs: ["W-004"] }),
+    "work/W-004-dropped.md": work("W-004", { state: "dropped", closed_on: "2026-09-24" }),
+    // W-005: needs W-002, which is open (not done yet) -- blocked.
+    "work/W-005-needs-open.md": work("W-005", { needs: ["W-002"] }),
+    // W-006: already in-progress -- not ready, the same "already running"
+    // leaves-the-queue rule as a met contract with an open unit does not
+    // apply here in the same way, but "not open, so not ready" is shared.
+    "work/W-006-in-progress.md": work("W-006", { state: "in-progress" }),
+    // W-007: needs W-006, which is in-progress, not done -- blocked.
+    "work/W-007-needs-in-progress.md": work("W-007", { needs: ["W-006"] }),
+  });
+});
+afterAll(cleanScratch);
+
+describe("work kind ready/blockedBy vs. chud's ready queue, expressible rules (#2734)", () => {
+  test("matches on every item, for the rules a needs link can express", async () => {
+    const doc = await queryRecords({ kind: WORK, cwd: root });
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.summary).toEqual({ total: 7, valid: 7, invalid: 0, superseded: 0 });
+
+    const items = doc.records.map((r) => ({ id: r.id!, state: r.state!, needs: (r.data as { needs?: string[] }).needs ?? [] }));
+    const chud = chudReadyIsh(items);
+
+    for (const r of doc.records) {
+      const id = r.id!;
+      expect(r.ready, `${id}.ready`).toBe(chud.ready.has(id));
+      expect(
+        (r.blockedBy ?? []).map((b) => b.id),
+        `${id}.blockedBy`,
+      ).toEqual(chud.blockedBy.get(id));
+    }
+  });
+
+  test("individually: done leaves the queue, a dropped need blocks forever, an in-progress need still blocks", async () => {
+    const doc = await queryRecords({ kind: WORK, cwd: root });
+    if ("error" in doc) throw new Error(doc.error.message);
+    const by = Object.fromEntries(doc.records.map((r) => [r.id, r]));
+
+    expect(by["W-001"]).toMatchObject({ ready: false, blockedBy: [] }); // done: no longer ready
+    expect(by["W-002"]).toMatchObject({ ready: true, blockedBy: [] }); // needs W-001, which is done
+    expect(by["W-003"]).toMatchObject({ ready: false, blockedBy: [{ id: "W-004", state: "dropped" }] }); // needs a dropped item: blocked forever
+    expect(by["W-005"]).toMatchObject({ ready: false, blockedBy: [{ id: "W-002", state: "open" }] }); // needs an open (not yet done) item
+    expect(by["W-006"]).toMatchObject({ ready: false, blockedBy: [] }); // in-progress: not ready, but not "blocked" either
+    expect(by["W-007"]).toMatchObject({ ready: false, blockedBy: [{ id: "W-006", state: "in-progress" }] });
+  });
+});

package/src/workspace/work.test.ts

@@ -32,6 +32,7 @@ import { queryRecords } from "./records-cli";
 import { amendRecord, newRecord, resolveWriteKind, reviewRecord } from "./records-write";
 import recordsSchema from "./records.schema.json";
 import { WORK_WARNING_CODES } from "./work";
+import { CHANGES_FINDING_CODES } from "./changes";
 
 const REF = join(REPO, "reference-workspace");
 const DECISION = (() => {
@@ -227,9 +228,9 @@ describe("work records on read (#2683)", () => {
     expect("error" in doc && doc.error.code).toBe("kind-invalid");
   });
 
-  test("the reference work schema's finding codes are the intent graph's", () => {
+  test("the reference work schema's finding codes are the intent graph's and the change check's (#2773)", () => {
     const schema = JSON.parse(readFileSync(join(REF, "work", "work.schema.json"), "utf-8")) as { definitions: { sourceGap: { properties: { finding: { anyOf: [{ enum: string[] }] } } } } };
-    expect(schema.definitions.sourceGap.properties.finding.anyOf[0].enum).toEqual([...INTENT_FINDING_CODES]);
+    expect(schema.definitions.sourceGap.properties.finding.anyOf[0].enum).toEqual([...INTENT_FINDING_CODES, ...CHANGES_FINDING_CODES]);
   });
 });
 

package/src/workspace/work.ts

@@ -15,6 +15,8 @@
  *   record is valid and not superseded;
  * - `blockedBy`: each need that is not done, with its state;
  * - `implements`: each decision it names, with that decision's state;
+ * - `acceptance`, for a kind with acceptance criteria (#2772): how many of the
+ *   record's criteria passing evidence of the expected verification meets;
  *
  * and each decision `implementedBy`, the work records naming it. The
  * warnings are closed codes. `work-done-gap-open` is not raised here: it
@@ -24,7 +26,7 @@
 
 import { dirname } from "node:path";
 import type { ReasonCode } from "./reason-codes";
-import { loadRecordKind, readRecords, type LoadedRecordKind, type ReadRecordsOptions, type RecordEntry } from "./records";
+import { loadRecordKind, normalisePrincipal, readRecords, type LoadedRecordKind, type ReadRecordsOptions, type RecordEntry } from "./records";
 
 /** Why a work record carries a warning. Closed, like the record warning codes. */
 export const WORK_WARNING_CODES = [
@@ -42,6 +44,10 @@ export const WORK_WARNING_CODES = [
   "work-closed-without-date",
   /** The record is done, and the finding it came from (`source.finding`) still fires on its region. Raised by `graph --intent`, and by `records` through a walk of that region (#2686). */
   "work-done-gap-open",
+  /** The record is done, and an acceptance criterion has no passing evidence of the verification it expects (#2772). `check` fails on it (WSP117). */
+  "work-acceptance-unmet",
+  /** A passing `manual` verdict on a criterion names the record's implementer, so it does not count: a manual verdict comes from someone else (#2772). */
+  "work-acceptance-self-verified",
 ] as const satisfies readonly ReasonCode[];
 export type WorkWarningCode = (typeof WORK_WARNING_CODES)[number];
 
@@ -61,6 +67,82 @@ export interface DecisionWork {
   implementedBy: WorkLink[];
 }
 
+/** How a criterion is to be verified (#2772): by a unit, integration or end-to-end test, by the running system, or by a person. */
+export const VERIFICATION_TYPES = ["unit", "integration", "e2e", "runtime", "manual"] as const;
+export type VerificationType = (typeof VERIFICATION_TYPES)[number];
+
+/** The results a piece of evidence for a criterion can carry. */
+export const EVIDENCE_RESULTS = ["pass", "fail"] as const;
+export type EvidenceResult = (typeof EVIDENCE_RESULTS)[number];
+
+/** One acceptance criterion as a work record states it. */
+export interface Criterion {
+  id: string;
+  text: string;
+  verification: VerificationType;
+}
+
+/** One criterion on read: whether passing evidence of its verification meets it. */
+export interface CriterionState {
+  id: string;
+  verification: VerificationType;
+  met: boolean;
+}
+
+/** A work record's acceptance criteria on read (#2772): how many are met, of how many. */
+export interface WorkAcceptance {
+  met: number;
+  total: number;
+  criteria: CriterionState[];
+}
+
+/** The acceptance criteria a record lists in `field`, leaving out entries without a string id and a known verification (the schema reports those). */
+export function acceptanceCriteria(data: Record<string, unknown> | null, field: string): Criterion[] {
+  const v = data?.[field];
+  if (!Array.isArray(v)) return [];
+  return v.filter(
+    (c): c is Criterion =>
+      c !== null && typeof c === "object" && typeof c.id === "string" && typeof c.text === "string" && (VERIFICATION_TYPES as readonly string[]).includes(c.verification),
+  );
+}
+
+/**
+ * Which of a record's criteria its evidence meets. Evidence meets a criterion
+ * when it names the criterion, its result is `pass` and its verification is
+ * the criterion's. A `manual` verdict also names who gave it in `by`, and
+ * counts only when that is not the record's implementer; one that is lands in
+ * `selfVerified`. `acceptance` is null when the record lists no criteria.
+ */
+export function workAcceptance(
+  data: Record<string, unknown> | null,
+  spec: { field: string; implementer: string },
+  pinsField: string,
+): { acceptance: WorkAcceptance | null; selfVerified: string[] } {
+  if (!Array.isArray(data?.[spec.field])) return { acceptance: null, selfVerified: [] };
+  const criteria = acceptanceCriteria(data, spec.field);
+  const implementer = typeof data?.[spec.implementer] === "string" ? normalisePrincipal(data[spec.implementer] as string) : null;
+  const evidence = Array.isArray(data?.[pinsField]) ? (data![pinsField] as unknown[]) : [];
+  const selfVerified: string[] = [];
+  const states = criteria.map((c): CriterionState => {
+    let met = false;
+    for (const e of evidence) {
+      if (e === null || typeof e !== "object") continue;
+      const ev = e as Record<string, unknown>;
+      if (ev.criterion !== c.id || ev.result !== "pass" || ev.verification !== c.verification) continue;
+      if (c.verification === "manual") {
+        if (typeof ev.by !== "string") continue;
+        if (implementer !== null && normalisePrincipal(ev.by) === implementer) {
+          if (!selfVerified.includes(c.id)) selfVerified.push(c.id);
+          continue;
+        }
+      }
+      met = true;
+    }
+    return { id: c.id, verification: c.verification, met };
+  });
+  return { acceptance: { met: states.filter((c) => c.met).length, total: states.length, criteria: states }, selfVerified };
+}
+
 /** The strings of a front-matter list, or none. */
 export function idList(data: Record<string, unknown> | null, field: string): string[] {
   const v = data?.[field];
@@ -143,6 +225,23 @@ export async function applyWork(loaded: LoadedRecordKind, entries: RecordEntry[]
     if (e.state === work.done && kind.pins && !(Array.isArray(evidence) && evidence.length > 0)) {
       e.warnings.push({ code: "work-done-unpinned", message: `${e.id ?? e.path} is ${work.done} and ${kind.pins.field} is empty or missing: nothing shows the work was done` });
     }
+    if (work.acceptance && kind.pins) {
+      const { acceptance, selfVerified } = workAcceptance(e.data, work.acceptance, kind.pins.field);
+      e.acceptance = acceptance;
+      if (selfVerified.length > 0) {
+        e.warnings.push({
+          code: "work-acceptance-self-verified",
+          message: `the manual verdict on ${selfVerified.join(", ")} is by ${String(e.data[work.acceptance.implementer])}, the implementer, so it does not count: a manual verdict comes from someone else`,
+        });
+      }
+      const unmet = acceptance?.criteria.filter((c) => !c.met) ?? [];
+      if (e.state === work.done && unmet.length > 0) {
+        e.warnings.push({
+          code: "work-acceptance-unmet",
+          message: `${e.id ?? e.path} is ${work.done}, and no passing evidence meets ${unmet.map((c) => `${c.id} (${c.verification})`).join(", ")}`,
+        });
+      }
+    }
     if (e.state !== null && closed.has(e.state) && typeof e.data[work.closedOn] !== "string") {
       e.warnings.push({ code: "work-closed-without-date", message: `${e.id ?? e.path} is ${e.state} and has no ${work.closedOn}` });
     }