@intentius/chant 0.101.0 → 0.104.0

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": [

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

@@ -0,0 +1,77 @@
+/**
+ * The slice-tier point's sizes and the understand point (#3150): chant
+ * measures a work item the same way for every orchestrator, the decide
+ * activity reads the sizes with the item, and the reference workspace
+ * declares understand.
+ */
+
+import { cpSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { readInputs } from "../op/decide-read-inputs";
+import { cleanScratch, git, REPO, scratchDir } from "./__fixtures__/contract-repo";
+import { parsePoints } from "./points";
+import { DEFAULT_TIER_LIMITS, fitsTier, measureWorkItem, sizeFields } from "./work-size";
+
+afterAll(cleanScratch);
+
+const SIZES = ["work-item.criteria", "work-item.files", "work-item.words", "work-item.fits_small", "work-item.fits_medium"];
+
+describe("measuring a work item (#3150)", () => {
+  test("criteria, backticked paths and words from the ask, the body without headings and the criteria", () => {
+    const data = {
+      source: { ask: { said: "Make `app/server.ts` answer on `/healthz` and note it in `README.md`.", by: "alice" } },
+      acceptance: [{ id: "AC-1", text: "`app/server.ts` answers 200" }, { id: "AC-2", text: "the README says so" }],
+    };
+    const body = "# Heading words are not counted\n\nThe body names `app/server.ts` again and `docs/`.\n";
+    const size = measureWorkItem(data, body);
+    // `docs/` and `/healthz` have no part on both sides of a slash, so they are not paths.
+    expect(size).toEqual({ criteria: 2, files: 2, words: 24 });
+    expect(measureWorkItem({ source: { intent: { answer: "a garden planner" } } }, "")).toEqual({ criteria: 0, files: 0, words: 3 });
+    expect(measureWorkItem(null, "")).toEqual({ criteria: 0, files: 0, words: 0 });
+  });
+
+  test("fits_<tier> for each tier with limits, against the defaults or the kind's own", () => {
+    expect(sizeFields({ criteria: 11, files: 2, words: 40 })).toEqual({ criteria: 11, files: 2, words: 40, fits_small: false, fits_medium: true });
+    expect(sizeFields({ criteria: 1, files: 1, words: 400 })).toMatchObject({ fits_small: false, fits_medium: false });
+    expect(sizeFields({ criteria: 1, files: 1, words: 40 }, { tiny: { words: 30 } })).toEqual({ criteria: 1, files: 1, words: 40, fits_tiny: false });
+    expect(fitsTier({ criteria: 10, files: 5, words: 150 }, DEFAULT_TIER_LIMITS.small)).toBe(true);
+    expect(fitsTier({ criteria: 0, files: 0, words: 0 }, undefined)).toBe(false);
+  });
+});
+
+describe("the reference workspace (#3150)", () => {
+  const ref = join(REPO, "reference-workspace");
+
+  test("declares understand: four answers, a table that proceeds on an open item, then people", () => {
+    const points = parsePoints(readFileSync(join(ref, "decisions", "points.json"), "utf-8"), "points.json");
+    const u = points.understand;
+    expect(Object.keys(u.question.criteria ?? {})).toEqual(["proceed", "redraft", "ask", "refuse"]);
+    expect(Object.keys(u.inputs)).toEqual(["work-item.state", "work-item.title", "work-item.source.ask.said", "work-item.source.ask.by", "work-item.source.ask.via", "work-item.acceptance"]);
+    expect(u.deciders.map((d) => d.kind)).toEqual(["table", "quorum"]);
+  });
+
+  test("the decide activity reads a work item's sizes with it, and the work kind's limits win", async () => {
+    const copy = (): string => {
+      const root = scratchDir("chant-work-size-");
+      cpSync(ref, root, { recursive: true, filter: (src) => !/[\\/](node_modules|dist)$/.test(src) });
+      git(root, "init", "-q");
+      git(root, "add", "-A");
+      git(root, "commit", "-q", "-m", "the workspace");
+      return root;
+    };
+    let root = copy();
+    const read = await readInputs(SIZES, { "work-item": "W-001" }, root);
+    expect(read.missing).toEqual([]);
+    expect(read.inputs).toMatchObject({ "work-item.criteria": 2, "work-item.fits_small": true, "work-item.fits_medium": true });
+    expect(typeof read.inputs["work-item.words"]).toBe("number");
+
+    // A fresh copy: a kind file is loaded once per path.
+    root = copy();
+    const kind = join(root, "work", "work.kind.mjs");
+    writeFileSync(kind, readFileSync(kind, "utf-8").replace('tier: { field: "tier", tiers: ["small", "medium", "large"] }', 'tier: { field: "tier", tiers: ["small", "medium", "large"], limits: { small: { criteria: 1 } } }'));
+    const narrow = await readInputs(SIZES, { "work-item": "W-001" }, root);
+    expect(narrow.inputs["work-item.fits_small"]).toBe(false);
+    expect(narrow.missing).toEqual(["work-item.fits_medium"]);
+  });
+});

package/src/workspace/work-size.ts

@@ -0,0 +1,93 @@
+/**
+ * How much a work item holds, for the `slice-tier` decision point (#3150).
+ *
+ * The point picks the smallest builder tier that can build an item, from five
+ * inputs every orchestrator must compute the same way, so chant computes
+ * them. They are read through the `work-item` output like any other field:
+ *
+ *   work-item.criteria      the item's acceptance criteria, counted
+ *   work-item.files         distinct paths the item names in backticks
+ *   work-item.words         words in the item's text
+ *   work-item.fits_<tier>   whether criteria, files and words are each within
+ *                           that tier's limits (`fits_small`, `fits_medium`)
+ *
+ * The item's text is what a person asked (`source.ask.said`, or the answer
+ * to the box's intent, `source.intent.answer`), the record's Markdown body
+ * with its heading lines left out, and each acceptance criterion's text. A
+ * path is a backticked token with a `/` between two parts, such as
+ * `app/server.ts` or `design/screens/`, or a file name with an extension of
+ * one to five letters, such as `README.md`. Words are runs of non-blank
+ * characters.
+ *
+ * The limits are the work kind's `work.tier.limits`, else
+ * {@link DEFAULT_TIER_LIMITS}: small holds at most 10 criteria, 5 files and
+ * 150 words, medium 20, 10 and 300. A tier with no limits, such as large,
+ * has no `fits_` input; an item that fits neither small nor medium is large.
+ * These are the sizing defaults studio's factory used (arugula-salad/studio
+ * `queue.mjs` `sizing()`), so a point's answers keep their meaning.
+ */
+
+/** A field of `value` by dotted path, or undefined. */
+function fieldOf(value: unknown, path: string): unknown {
+  let at: unknown = value;
+  for (const part of path.split(".")) {
+    if (at === null || typeof at !== "object" || !Object.prototype.hasOwnProperty.call(at, part)) return undefined;
+    at = (at as Record<string, unknown>)[part];
+  }
+  return at;
+}
+
+/** What one tier may hold. A limit left out is not checked. */
+export interface TierLimit {
+  criteria?: number;
+  files?: number;
+  words?: number;
+}
+
+/** The limits when the work kind declares none. */
+export const DEFAULT_TIER_LIMITS: Readonly<Record<string, TierLimit>> = Object.freeze({
+  small: { criteria: 10, files: 5, words: 150 },
+  medium: { criteria: 20, files: 10, words: 300 },
+});
+
+export interface WorkItemSize {
+  criteria: number;
+  files: number;
+  words: number;
+}
+
+const HEADING = /^\s*#/;
+const PATH_LIKE = /^[\w@.-]+(\/[\w@.*-]+)+\/?$|^[\w@-][\w@.-]*\.[a-z]{1,5}$/i;
+const str = (v: unknown): string => (typeof v === "string" ? v : "");
+
+/**
+ * Measure a work item from its front matter (`data`) and Markdown body.
+ * `acceptanceField` is the work kind's `work.acceptance.field`, `acceptance`
+ * when it names none.
+ */
+export function measureWorkItem(data: Record<string, unknown> | null, body: string, acceptanceField = "acceptance"): WorkItemSize {
+  const d = data ?? {};
+  const acceptance = Array.isArray(d[acceptanceField]) ? (d[acceptanceField] as unknown[]) : [];
+  const said = str(fieldOf(d, "source.ask.said")) || str(fieldOf(d, "source.intent.answer"));
+  const bodyLines = body.split("\n").filter((l) => !HEADING.test(l));
+  const criteriaText = acceptance.map((c) => (typeof c === "string" ? c : str((c as { text?: unknown } | null)?.text)));
+  const text = [said, ...bodyLines, ...criteriaText].join("\n");
+  const files = new Set([...text.matchAll(/`([^`\s]+)`/g)].map((m) => m[1]).filter((t) => PATH_LIKE.test(t)));
+  return { criteria: acceptance.length, files: files.size, words: text.split(/\s+/).filter(Boolean).length };
+}
+
+/** Whether `size` is within `limit`: each limit given is at least the measure. */
+export function fitsTier(size: WorkItemSize, limit: TierLimit | undefined): boolean {
+  if (!limit) return false;
+  return (["criteria", "files", "words"] as const).every((k) => limit[k] === undefined || size[k] <= limit[k]!);
+}
+
+/**
+ * The slice-tier inputs' fields for a measured item: `criteria`, `files`,
+ * `words` and `fits_<tier>` for each tier `limits` names.
+ */
+export function sizeFields(size: WorkItemSize, limits: Readonly<Record<string, TierLimit>> = DEFAULT_TIER_LIMITS): Record<string, number | boolean> {
+  const out: Record<string, number | boolean> = { criteria: size.criteria, files: size.files, words: size.words };
+  for (const [tier, limit] of Object.entries(limits)) out[`fits_${tier}`] = fitsTier(size, limit);
+  return out;
+}

package/src/workspace/work.ts

@@ -17,6 +17,9 @@
  * - `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;
+ * - `contract`, for a kind with a contract link (#3147): the contract record
+ *   the item builds, with its state, read from the contract kind at the same
+ *   revision;
  *
  * and each decision `implementedBy`, the work records naming it. The
  * warnings are closed codes. `work-done-gap-open` is not raised here: it
@@ -48,6 +51,12 @@ export const WORK_WARNING_CODES = [
   "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",
+  /** The record names a contract no record of the kind's contract kind has (#3147). */
+  "work-contract-unknown",
+  /** The record names a contract whose state is not approved, such as a draft (#3147). */
+  "work-contract-undecided",
+  /** The record names a builder tier its kind's `work.tier.tiers` does not list (#3147). */
+  "work-tier-unknown",
 ] as const satisfies readonly ReasonCode[];
 export type WorkWarningCode = (typeof WORK_WARNING_CODES)[number];
 
@@ -58,6 +67,49 @@ export interface WorkLink {
   state: string | null;
 }
 
+/**
+ * One decision-point answer about a work item (#3147), as `records --json`
+ * joins it from the answer kind the work kind names: the answer records whose
+ * `constrains` names the item's id. The item never copies them.
+ */
+export interface WorkAnswer {
+  /** The answer record's id, such as understand-0123456789ab. */
+  id: string;
+  /** The decision point it answers. */
+  point: string | null;
+  /** escalated, proposed or answered. */
+  state: string | null;
+  /** The answer, or null while there is none. */
+  answer: string | boolean | null;
+  /** The people who answered or confirmed it, empty when a table or model did. */
+  answeredBy: string[];
+}
+
+/**
+ * The answers about each work item: every answer record whose `constrains`
+ * names the item's id, in path order, by item id.
+ */
+export function workAnswers(answerRecords: readonly RecordEntry[], ids: Iterable<string>): Map<string, WorkAnswer[]> {
+  const out = new Map<string, WorkAnswer[]>();
+  for (const id of ids) out.set(id, []);
+  for (const a of answerRecords) {
+    if (a.id === null || a.data === null) continue;
+    for (const target of idList(a.data, "constrains")) {
+      const list = out.get(target);
+      if (!list || list.some((x) => x.id === a.id)) continue;
+      const answer = a.data.answer;
+      list.push({
+        id: a.id,
+        point: typeof a.data.point === "string" ? a.data.point : null,
+        state: a.state,
+        answer: typeof answer === "string" || typeof answer === "boolean" ? answer : null,
+        answeredBy: idList(a.data, "answered_by"),
+      });
+    }
+  }
+  return out;
+}
+
 /** A decision as a work read lists it: its state and the work records implementing it. */
 export interface DecisionWork {
   id: string;
@@ -174,6 +226,16 @@ export async function applyWork(loaded: LoadedRecordKind, entries: RecordEntry[]
   for (const e of entries) if (e.id !== null && !byId.has(e.id)) byId.set(e.id, e);
   const closed = new Set(kind.closedStates);
 
+  // The contract kind a work item names its contract in (#3147), read at the same revision.
+  let contracts: { kind: LoadedRecordKind; byId: Map<string, RecordEntry> } | undefined;
+  if (work.contract) {
+    const contractKind = await loadRecordKind(work.contract.kind, dirname(loaded.file));
+    const contractRead = await readRecords(contractKind, { root: options.root, source: options.source });
+    const contractById = new Map<string, RecordEntry>();
+    for (const c of contractRead.records) if (c.id !== null && !contractById.has(c.id)) contractById.set(c.id, c);
+    contracts = { kind: contractKind, byId: contractById };
+  }
+
   // Records in a needs cycle: those that reach themselves.
   const inCycle = new Set<string>();
   for (const start of byId.keys()) {
@@ -242,6 +304,26 @@ export async function applyWork(loaded: LoadedRecordKind, entries: RecordEntry[]
         });
       }
     }
+    if (contracts && work.contract) {
+      const named = e.data[work.contract.field];
+      if (typeof named === "string" && named !== "") {
+        const c = contracts.byId.get(named);
+        e.contract = { id: named, state: c?.state ?? null };
+        if (!c) {
+          e.warnings.push({ code: "work-contract-unknown", message: `names the contract ${named}, which no record in ${work.contract.kind} has` });
+        } else if (!isDecided(contracts.kind.kind, c.state)) {
+          e.warnings.push({ code: "work-contract-undecided", message: `names the contract ${named}, which is ${c.state ?? "in no state"}: the work may build a contract nobody approved` });
+        }
+      } else {
+        e.contract = null;
+      }
+    }
+    if (work.tier) {
+      const tier = e.data[work.tier.field];
+      if (typeof tier === "string" && !work.tier.tiers.includes(tier)) {
+        e.warnings.push({ code: "work-tier-unknown", message: `names the builder tier ${tier}, which the kind's tiers (${work.tier.tiers.join(", ")}) do not list` });
+      }
+    }
     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}` });
     }

package/src/workspace/workspace-kinds.schema.json

@@ -75,6 +75,9 @@
         },
         "graph": {
           "$ref": "#/$defs/graph"
+        },
+        "fields": {
+          "$ref": "#/$defs/fields"
         }
       },
       "patternProperties": {
@@ -123,6 +126,34 @@
             }
           },
           "additionalProperties": false
+        },
+        "anyJsonKey": {
+          "type": "object",
+          "description": "The directory passes when a file directly in it, whose name matches one of in, parses as JSON and has a value at one of pointers, each a JSON Pointer such as /scripts/start (#3151). A file that is not JSON is no evidence either way. Added by chant 0.103.0.",
+          "required": [
+            "in",
+            "pointers"
+          ],
+          "properties": {
+            "in": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/fileName"
+              }
+            },
+            "pointers": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "pattern": "^(/[^/]+)+$"
+              }
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -154,6 +185,97 @@
         "^x-": true
       },
       "additionalProperties": false
+    },
+    "fields": {
+      "type": "object",
+      "description": "The fields a member entry of this kind may set under its own fields block, each with a type and, optionally, a default (#3151). chant workspace check fails a member whose fields name one the kind doesn't declare or give a value of the wrong type (WSP005), and chant workspace status --json prints every declared field with the defaults filled in. Added by chant 0.103.0; an older chant can't read a kinds file that uses it.",
+      "minProperties": 1,
+      "propertyNames": {
+        "$ref": "#/$defs/fieldName"
+      },
+      "additionalProperties": {
+        "oneOf": [
+          {
+            "$ref": "#/$defs/scalarField"
+          },
+          {
+            "$ref": "#/$defs/objectField"
+          }
+        ]
+      }
+    },
+    "fieldName": {
+      "type": "string",
+      "pattern": "^[a-z][A-Za-z0-9]{0,39}$"
+    },
+    "scalarField": {
+      "type": "object",
+      "required": [
+        "type",
+        "description"
+      ],
+      "properties": {
+        "type": {
+          "enum": [
+            "string",
+            "integer",
+            "boolean"
+          ]
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        },
+        "default": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "integer"
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "The value a member that doesn't set the field gets. Its type is the field's. Without it the field reads as null when unset."
+        },
+        "pattern": {
+          "type": "string",
+          "minLength": 1,
+          "description": "For a string field: a regular expression the value must match."
+        }
+      },
+      "additionalProperties": false
+    },
+    "objectField": {
+      "type": "object",
+      "required": [
+        "type",
+        "description",
+        "properties"
+      ],
+      "properties": {
+        "type": {
+          "const": "object"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        },
+        "properties": {
+          "type": "object",
+          "minProperties": 1,
+          "propertyNames": {
+            "$ref": "#/$defs/fieldName"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/scalarField"
+          },
+          "description": "The object's own fields, each a string, integer or boolean field. A member sets any of them; the rest take their defaults."
+        }
+      },
+      "additionalProperties": false
     }
   }
 }