@intentius/chant 0.91.0 → 0.94.0

package/src/workspace/records-sessions-write.test.ts

@@ -5,13 +5,12 @@
  * is not open and appends the verdict to the session too, and
  * `records --since <session id>` compares the session's own revisions. The
  * fixture is a copy of the reference workspace's decisions and design
- * member with a declaration naming both kinds.
+ * member with a declaration naming both kinds. The CLI run of close and
+ * --since is in records-sessions-write.e2e.test.ts (#2817).
  */
 
-import { spawnSync } from "node:child_process";
 import { cpSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { pathToFileURL } from "node:url";
 import { afterAll, describe, expect, test } from "vitest";
 import { cleanScratch, commitAll, contract, git, REPO, scratchDir } from "./__fixtures__/contract-repo";
 import { declareSessions, DECISIONS_KIND, newSessionFields, sessionsRepo, SESSIONS_KIND } from "./__fixtures__/sessions";
@@ -240,35 +239,4 @@ describe("records --since <session id> (#2693)", () => {
     git(root, "tag", "v-1");
     expect((await sinceDoc({ kind: DECISIONS_KIND, since: "v-1", cwd: root })).session).toBeUndefined();
   });
-
-  test(
-    "through the CLI: close with the declared session kind, and --since <session id> without --kind",
-    async () => {
-      const root = declared();
-      await opened(root);
-      const run = (...args: string[]) =>
-        spawnSync(process.execPath, ["--import", pathToFileURL(join(REPO, "node_modules/tsx/dist/loader.mjs")).href, join(REPO, "packages/core/src/cli/main.ts"), "workspace", "records", ...args], {
-          cwd: root,
-          encoding: "utf-8",
-          env: { ...process.env, NO_COLOR: "1" },
-          timeout: 60_000,
-        });
-      const closed = run("close", "S-0002");
-      expect(closed.status, closed.stderr).toBe(0);
-      close.expectValid(JSON.parse(closed.stdout));
-      const again = run("close", "S-0002");
-      expect(again.status).toBe(1);
-      expect(JSON.parse(again.stdout).error.code).toBe("record-closed");
-      commitAll(root, "close");
-      const set = run("--since", "S-0002", "--json");
-      expect(set.status, set.stderr).toBe(0);
-      const kinds = JSON.parse(set.stdout).kinds as RecordsSinceDocument[];
-      for (const k of kinds) since.expectValid(k);
-      expect(kinds.map((k) => ("session" in k ? k.session?.id : null))).toEqual(["S-0002", "S-0002"]);
-      const text = run("--kind", SESSIONS_KIND, "--since", "S-0002");
-      expect(text.stdout).toContain("session S-0002 (closed)");
-      expect(text.stdout).toContain("S-0002  new, closed");
-    },
-    120_000,
-  );
 });

package/src/workspace/records-since.test.ts

@@ -3,7 +3,8 @@
  * and the comparison. The fixture is a repository with commits for a review
  * session's open and close: between them the session closes with two
  * verdicts, ref-001 gains the two reviews that name it and is ratified,
- * a new decision supersedes ref-002, and ref-002's pin moves. Every document
+ * a new decision (ref-004, after the reference workspace's own ref-003)
+ * supersedes ref-002, and ref-002's pin moves. Every document
  * validates against records-since.schema.json.
  */
 
@@ -56,8 +57,8 @@ function sessionHistory(): { root: string; before: string; open: string; close:
   const text = readFileSync(ref002, "utf-8");
   writeFileSync(ref002, text.replace(/sha256: "[0-9a-f]{64}"/, `sha256: "${"a".repeat(64)}"`));
   writeFileSync(
-    join(root, "decisions", "ref-003-a-successor.md"),
-    text.replace(/^id: .*$/m, 'id: "ref-003"').replace(/^supersedes: \[\]$/m, 'supersedes:\n  - decision: "ref-002"'),
+    join(root, "decisions", "ref-004-a-successor.md"),
+    text.replace(/^id: .*$/m, 'id: "ref-004"').replace(/^supersedes: \[\]$/m, 'supersedes:\n  - decision: "ref-002"'),
   );
   const close = commitAll(root, "close S-0002");
   return { root, before, open, close };
@@ -85,11 +86,11 @@ describe("records --since (#2673)", () => {
     expect(doc.at).toBe(h.close);
     expect(doc.kind).toEqual({ name: "decision", schema: "urn:intentius:chant:decision:1", file: "decisions/decision.kind.mjs" });
     expect(doc.changes).toEqual([
-      { change: "new", id: "ref-003", path: "decisions/ref-003-a-successor.md", state: "decided" },
+      { change: "new", id: "ref-004", path: "decisions/ref-004-a-successor.md", state: "decided" },
       { change: "state", id: "ref-001", from: "decided", to: "ratified" },
       { change: "verdict", id: "ref-001", principal: "alice", verdict: "agree", index: 0, session: "S-0002" },
       { change: "verdict", id: "ref-001", principal: "bob", verdict: "agree", index: 1, session: "S-0002" },
-      { change: "supersession", id: "ref-003", supersedes: "ref-002" },
+      { change: "supersession", id: "ref-004", supersedes: "ref-002" },
       { change: "pin", id: "ref-002", path: "design/screens/home.json", from: expect.stringMatching(/^[0-9a-f]{64}$/), to: "a".repeat(64) },
     ]);
     expect(doc.summary).toEqual({ new: 1, removed: 0, state: 1, verdict: 2, supersession: 1, pin: 1 });
@@ -105,11 +106,11 @@ describe("records --since (#2673)", () => {
   });
 
   test("without --at it compares with the working tree, and a record deleted there is removed", async () => {
-    rmSync(join(h.root, "decisions", "ref-003-a-successor.md"));
+    rmSync(join(h.root, "decisions", "ref-004-a-successor.md"));
     try {
       const doc = ok(await since({ kind: DECISIONS_KIND, since: h.close, cwd: h.root }));
       expect(doc.at).toBeNull();
-      expect(doc.changes).toEqual([{ change: "removed", id: "ref-003", path: "decisions/ref-003-a-successor.md", state: "decided" }]);
+      expect(doc.changes).toEqual([{ change: "removed", id: "ref-004", path: "decisions/ref-004-a-successor.md", state: "decided" }]);
     } finally {
       git(h.root, "checkout", "--", "decisions");
     }

package/src/workspace/records-write.e2e.test.ts

@@ -0,0 +1,108 @@
+/**
+ * `chant workspace records new|amend|review` (#2670) through the command
+ * line: standard input, exit codes and the refusal document, from the CLI a
+ * user runs. Each test spawns the CLI several times, which put them near 20s
+ * on CI, over the unit shards' per-test budget, so they run in the test-e2e
+ * job (#2817). The commands' own behaviour is covered in records-write.test.ts.
+ */
+
+import { execFileSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { parseFrontMatter } from "./records";
+import { renderRecord } from "./records-write";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..");
+const DECISIONS = join(REPO, "docs", "design", "decisions");
+const KIND = "decisions/decision.kind.mjs";
+
+type Data = Record<string, unknown>;
+
+const SAMPLE = (() => {
+  const fm = parseFrontMatter(readFileSync(join(DECISIONS, "ws-003-seal-scope.md"), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+})();
+
+/** A decided decision like ws-003, with `over` laid on top. */
+function decision(over: Data = {}): Data {
+  return { ...structuredClone(SAMPLE), ...over };
+}
+
+/** A proposed decision: no choice, nobody decided. */
+function proposal(over: Data = {}): Data {
+  return decision({ state: "proposed", choice: null, decided_by: null, decided_on: null, ...over });
+}
+
+let dir: string;
+beforeEach(() => {
+  dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-records-write-")));
+  mkdirSync(join(dir, "decisions"));
+  cpSync(join(DECISIONS, "decision.kind.mjs"), join(dir, "decisions", "decision.kind.mjs"));
+  cpSync(join(DECISIONS, "decision.schema.json"), join(dir, "decisions", "decision.schema.json"));
+  put("ws-001-one.md", decision({ id: "ws-001", title: "One" }));
+  put("ws-002-two.md", proposal({ id: "ws-002", title: "Two" }));
+  put("ws-003-three.md", decision({ id: "ws-003", title: "Three", state: "ratified" }));
+});
+afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+function put(name: string, data: Data): void {
+  writeFileSync(join(dir, "decisions", name), renderRecord(data, `\n# ${String(data.title)}\n`));
+}
+
+describe("the command line", () => {
+  const cli = (args: string[], input?: string) => {
+    const loader = pathToFileURL(join(REPO, "node_modules", "tsx", "dist", "loader.mjs")).href;
+    try {
+      const out = execFileSync(process.execPath, ["--import", loader, join(REPO, "packages", "core", "src", "cli", "main.ts"), "workspace", "records", ...args], {
+        cwd: dir,
+        input,
+        encoding: "utf-8",
+        env: { ...process.env, TSX_DISABLE_CACHE: "1" },
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      return { status: 0, doc: JSON.parse(out) };
+    } catch (err) {
+      const e = err as { status: number; stdout: string };
+      return { status: e.status, doc: JSON.parse(e.stdout) };
+    }
+  };
+
+  test(
+    "new reads fields from standard input, review appends, and a refusal exits 1 with its code",
+    () => {
+      const { id: _id, ...rest } = decision({ title: "From stdin" });
+      const made = cli(["new", KIND, "--from", "-"], JSON.stringify(rest));
+      expect(made).toMatchObject({ status: 0, doc: { id: "ws-004", path: "decisions/ws-004-from-stdin.md" } });
+      expect(existsSync(join(dir, "decisions", "ws-004-from-stdin.md"))).toBe(true);
+      const reviewed = cli(["review", "ws-004", "--kind", KIND, "--verdict", "agree", "--by", "alice"]);
+      expect(reviewed).toMatchObject({ status: 0, doc: { review: { reviewer: "alice", verdict: "agree" } } });
+      const refused = cli(["review", "ws-004", "--kind", KIND, "--verdict", "dissent", "--by", "bob"]);
+      expect(refused).toMatchObject({ status: 1, doc: { error: { code: "review-note-required" } } });
+      writeFileSync(join(dir, "patch.json"), JSON.stringify({ title: "Changed" }));
+      expect(cli(["amend", "ws-004", "--kind", KIND, "--set", "patch.json"])).toMatchObject({ status: 1, doc: { error: { code: "amend-supersede-instead" } } });
+      expect(cli(["amend", "ws-004", "--set", "patch.json"])).toMatchObject({ status: 1, doc: { error: { code: "write-usage-invalid" } } });
+    },
+    120_000,
+  );
+
+  test(
+    "new --by writes the proposer, not the decider, and amend --by is refused rather than dropped (#2756)",
+    () => {
+      const { id: _id, ...rest } = decision({ title: "Kept by a session", state: "proposed", choice: null, decided_by: null, decided_on: null });
+      const made = cli(["new", KIND, "--from", "-", "--by", "hud-session"], JSON.stringify(rest));
+      expect(made).toMatchObject({ status: 0, doc: { id: "ws-004" } });
+      const fm = parseFrontMatter(readFileSync(join(dir, "decisions", "ws-004-kept-by-a-session.md"), "utf-8"));
+      if (!fm.ok) throw new Error(fm.message);
+      expect(fm.value).toMatchObject({ proposed_by: "hud-session", decided_by: null });
+
+      writeFileSync(join(dir, "patch.json"), JSON.stringify({ title: "Changed" }));
+      const refused = cli(["amend", "ws-004", "--kind", KIND, "--set", "patch.json", "--by", "alice"]);
+      expect(refused).toMatchObject({ status: 1, doc: { error: { code: "write-usage-invalid", message: expect.stringContaining("--by is not taken by amend") } } });
+    },
+    120_000,
+  );
+});

package/src/workspace/records-write.test.ts

@@ -2,14 +2,13 @@
  * `chant workspace records new|amend|review` (#2670): each command validates
  * before it writes, writes exactly one file or none, and refuses with a closed
  * code. Run in a directory outside git holding a copy of the decision kind.
+ * The same commands through the CLI are in records-write.e2e.test.ts (#2817).
  */
 
-import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { pathToFileURL } from "node:url";
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
 import { parseFrontMatter, recordTextDigest } from "./records";
 import { allocateId, amendRecord, newRecord, renderRecord, reviewRecord, toYaml } from "./records-write";
@@ -187,7 +186,7 @@ describe("records new", () => {
   });
 
   test("keeps the width of the ids it follows", () => {
-    const entry = (id: string) => ({ id, path: `d/${id}-x.md`, state: null, valid: true, reasons: [], supersededBy: null, data: {}, digest: "", assets: [], warnings: [] });
+    const entry = (id: string) => ({ id, path: `d/${id}-x.md`, state: null, valid: true, reasons: [], supersededBy: null, remediatedBy: [], data: {}, digest: "", assets: [], warnings: [] });
     expect(allocateId([entry("s-0009"), entry("s-0010")], undefined, "k")).toBe("s-0011");
     expect(allocateId([entry("s-999")], undefined, "k")).toBe("s-1000");
     // Case and padding come from the records (#2683).
@@ -225,6 +224,35 @@ describe("records new", () => {
   test("a kind that can't be read is its read error", async () => {
     expect(code(await newRecord({ kind: "missing.kind.mjs", fields: fields(fresh()), cwd: dir }))).toBe("kind-unreadable");
   });
+
+  test("--by names the proposer of a record that opens proposed, apart from decided_by (#2756)", async () => {
+    const { id: _id, ...freshProposal } = proposal({ title: "Filed by someone" });
+    const proposed = await newRecord({ kind: KIND, fields: fields(freshProposal), by: "carol", cwd: dir });
+    expect(code(proposed)).toBe("ok");
+    const proposedPath = (proposed as { path: string }).path.replace("decisions/", "");
+    expect(data(proposedPath)).toMatchObject({ proposed_by: "carol", decided_by: null });
+
+    // A conflicting proposed_by given in the fields is refused, same as a conflicting decided_by is today.
+    const conflict = await newRecord({ kind: KIND, fields: fields({ ...freshProposal, title: "Two proposers", proposed_by: "dave" }), by: "carol", cwd: dir });
+    expect(code(conflict)).toBe("write-input-invalid");
+  });
+
+  test("--by names the decider when a new record opens straight into a later state", async () => {
+    const { id: _id, decided_by: _db, ...freshDecided } = decision({ title: "Decided at once" });
+    const decidedDoc = await newRecord({ kind: KIND, fields: fields({ ...freshDecided, decided_by: null }), by: "dana", cwd: dir });
+    expect(code(decidedDoc)).toBe("ok");
+    const decidedPath = (decidedDoc as { path: string }).path.replace("decisions/", "");
+    expect(data(decidedPath)).toMatchObject({ decided_by: "dana" });
+    expect(data(decidedPath)).not.toHaveProperty("proposed_by");
+  });
+
+  test("--by is refused for a kind whose new record opens decided and declares no reviews", async () => {
+    const kindFile = join(dir, "decisions", "decision.kind.mjs");
+    writeFileSync(kindFile, readFileSync(kindFile, "utf-8").replace(/^\s*reviews: \{[^}]*\},?\n/m, ""));
+    const { id: _id, decided_by: _db, ...freshDecided } = decision({ title: "No reviews declared" });
+    const doc = await newRecord({ kind: KIND, fields: fields({ ...freshDecided, decided_by: null }), by: "erin", cwd: dir });
+    expect(code(doc)).toBe("write-usage-invalid");
+  });
 });
 
 describe("records amend", () => {
@@ -336,40 +364,3 @@ describe("records review", () => {
     expect(code(await reviewRecord({ kind: KIND, id: "ws-001", verdict: "agree", by: "a", cwd: dir }))).toBe("review-unsupported");
   });
 });
-
-describe("the command line", () => {
-  const cli = (args: string[], input?: string) => {
-    const loader = pathToFileURL(join(REPO, "node_modules", "tsx", "dist", "loader.mjs")).href;
-    try {
-      const out = execFileSync(process.execPath, ["--import", loader, join(REPO, "packages", "core", "src", "cli", "main.ts"), "workspace", "records", ...args], {
-        cwd: dir,
-        input,
-        encoding: "utf-8",
-        env: { ...process.env, TSX_DISABLE_CACHE: "1" },
-        stdio: ["pipe", "pipe", "pipe"],
-      });
-      return { status: 0, doc: JSON.parse(out) };
-    } catch (err) {
-      const e = err as { status: number; stdout: string };
-      return { status: e.status, doc: JSON.parse(e.stdout) };
-    }
-  };
-
-  test(
-    "new reads fields from standard input, review appends, and a refusal exits 1 with its code",
-    () => {
-      const { id: _id, ...rest } = decision({ title: "From stdin" });
-      const made = cli(["new", KIND, "--from", "-"], JSON.stringify(rest));
-      expect(made).toMatchObject({ status: 0, doc: { id: "ws-004", path: "decisions/ws-004-from-stdin.md" } });
-      expect(existsSync(join(dir, "decisions", "ws-004-from-stdin.md"))).toBe(true);
-      const reviewed = cli(["review", "ws-004", "--kind", KIND, "--verdict", "agree", "--by", "alice"]);
-      expect(reviewed).toMatchObject({ status: 0, doc: { review: { reviewer: "alice", verdict: "agree" } } });
-      const refused = cli(["review", "ws-004", "--kind", KIND, "--verdict", "dissent", "--by", "bob"]);
-      expect(refused).toMatchObject({ status: 1, doc: { error: { code: "review-note-required" } } });
-      writeFileSync(join(dir, "patch.json"), JSON.stringify({ title: "Changed" }));
-      expect(cli(["amend", "ws-004", "--kind", KIND, "--set", "patch.json"])).toMatchObject({ status: 1, doc: { error: { code: "amend-supersede-instead" } } });
-      expect(cli(["amend", "ws-004", "--set", "patch.json"])).toMatchObject({ status: 1, doc: { error: { code: "write-usage-invalid" } } });
-    },
-    120_000,
-  );
-});

package/src/workspace/records-write.ts

@@ -629,9 +629,15 @@ export interface WriteChannel {
   opensInitial?: boolean;
 }
 
-/** What a channel's write adds to the command line's: who the author is, and how it came. */
+/** What a channel's write adds to the command line's: who named the author, and how it came. */
 export interface ChannelOptions {
-  /** The record's author, written to the kind's `reviews.decider` field: the person or agent that decided. */
+  /**
+   * Who the caller names as the record's author (#2756). Written to the
+   * kind's `proposedBy` field when the kind declares one and the record
+   * opens (or stays) in its first state — a proposal naming its proposer.
+   * Otherwise written to `reviews.decider`, as before: a record opening (or
+   * moving) straight to another state names who decided it.
+   */
   by?: string;
   through?: WriteChannel;
 }
@@ -640,18 +646,8 @@ export interface ChannelOptions {
 function applyChannel(o: Opened, fields: Record<string, unknown>, opts: ChannelOptions, isNew: boolean, flag: string): Record<string, unknown> {
   const { kind } = o.loaded;
   const out = { ...fields };
-  if (opts.by !== undefined) {
-    if (!kind.reviews) throw new RecordWriteError("write-usage-invalid", `by names a record's author, the kind's reviews.decider field, and the ${kind.name} kind declares no reviews`);
-    if (opts.by.trim() === "") throw new RecordWriteError("write-usage-invalid", "by needs the name of the person or agent that decided");
-    const f = kind.reviews.decider;
-    if (out[f] !== undefined && out[f] !== null && out[f] !== opts.by) {
-      throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} set ${f} to ${JSON.stringify(out[f])}, and by names ${JSON.stringify(opts.by)}: give one author`);
-    }
-    out[f] = opts.by;
-  }
   const through = opts.through;
-  if (!through) return out;
-  if (isNew && through.opensInitial && kind.states && kind.stateField !== undefined) {
+  if (isNew && through?.opensInitial && kind.states && kind.stateField !== undefined) {
     const first = kind.states[0];
     const state = out[kind.stateField];
     if (state === undefined) out[kind.stateField] = first;
@@ -662,6 +658,27 @@ function applyChannel(o: Opened, fields: Record<string, unknown>, opts: ChannelO
       );
     }
   }
+  if (opts.by !== undefined) {
+    if (opts.by.trim() === "") throw new RecordWriteError("write-usage-invalid", "by needs the name of the person or agent that proposed or decided");
+    // A new record that opens in the kind's first state is a proposal, when the kind opts in with proposedBy (#2756):
+    // by names the proposer, kept apart from reviews.decider, which stays null until the record is decided.
+    const opensInitial = isNew && !!kind.states && kind.stateField !== undefined && (out[kind.stateField] === undefined || out[kind.stateField] === kind.states[0]);
+    if (kind.proposedBy && opensInitial) {
+      const f = kind.proposedBy.field;
+      if (out[f] !== undefined && out[f] !== null && out[f] !== opts.by) {
+        throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} set ${f} to ${JSON.stringify(out[f])}, and by names ${JSON.stringify(opts.by)}: give one proposer`);
+      }
+      out[f] = opts.by;
+    } else {
+      if (!kind.reviews) throw new RecordWriteError("write-usage-invalid", `by names a record's author, the kind's reviews.decider field, and the ${kind.name} kind declares no reviews`);
+      const f = kind.reviews.decider;
+      if (out[f] !== undefined && out[f] !== null && out[f] !== opts.by) {
+        throw new RecordWriteError("write-input-invalid", `the fields given with ${flag} set ${f} to ${JSON.stringify(out[f])}, and by names ${JSON.stringify(opts.by)}: give one author`);
+      }
+      out[f] = opts.by;
+    }
+  }
+  if (!through) return out;
   if (kind.source && (isNew || kind.source.field in out)) {
     const f = kind.source.field;
     const block = out[f];
@@ -984,7 +1001,7 @@ async function seal(sign: string | true, cwd: string, v: { record: string; diges
 // ── The command ──────────────────────────────────────────────────────────────
 
 export const WRITE_USAGE = [
-  "chant workspace records new [<kind file or declared kind>] --from <file|-> [--prefix <prefix>] [--sign [<key file>]] [--dry-run]",
+  "chant workspace records new [<kind file or declared kind>] --from <file|-> [--prefix <prefix>] [--by <name>] [--sign [<key file>]] [--dry-run]",
   "chant workspace records amend <id> [--kind <kind file>] --set <file|-> [--sign [<key file>]] [--dry-run]",
   "chant workspace records review <id> [--kind <kind file>] --verdict agree|dissent|abstain --by <principal> [--note <text>] [--session <id>] [--sign [<key file>]] [--dry-run]",
   "chant workspace records close <session id> [--kind <session kind file>] [--dry-run]",
@@ -1087,7 +1104,7 @@ export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
     if (typeof kind !== "string") return print(kind);
     const input = readInput(RECORDS_NEW_SCHEMA_ID, "--from", args.migrateFrom, cwd);
     if (typeof input !== "string") return print(input);
-    return print(await newRecord({ kind, fields: input, prefix: args.prefix, sign: args.sign, dryRun: args.dryRun, cwd }));
+    return print(await newRecord({ kind, fields: input, prefix: args.prefix, by: args.by, sign: args.sign, dryRun: args.dryRun, cwd }));
   }
   const schema = verb === "amend" ? RECORDS_AMEND_SCHEMA_ID : RECORDS_REVIEW_SCHEMA_ID;
   const id = args.extraPositional2;
@@ -1095,6 +1112,7 @@ export async function runRecordsWrite(ctx: CommandContext): Promise<number> {
   const kind = args.kind !== undefined ? resolveWriteKind(args.kind, cwd) : declaredWriteKind(schema, cwd, "--kind <kind file> is required");
   if (typeof kind !== "string") return print(kind);
   if (verb === "amend") {
+    if (args.by !== undefined) return print(usage(schema, "--by is not taken by amend: set decided_by, or a kind's proposedBy field, with --set"));
     const input = readInput(schema, "--set", args.set, cwd);
     if (typeof input !== "string") return print(input);
     return print(await amendRecord({ kind, id, fields: input, sign: args.sign, dryRun: args.dryRun, cwd }));

package/src/workspace/records.schema.json

@@ -116,7 +116,7 @@
     },
     "record": {
       "type": "object",
-      "required": ["id", "path", "state", "valid", "reasons", "supersededBy", "data"],
+      "required": ["id", "path", "state", "valid", "reasons", "supersededBy", "remediatedBy", "data"],
       "properties": {
         "id": { "type": ["string", "null"], "description": "Null when the record could not be parsed or has no string id. For a content-addressed kind (idFrom sha256, added by #2664), the lowercase hex SHA-256 of the file's bytes, the same string a pin of the file carries." },
         "path": { "type": "string", "description": "From the repository root, with / separators." },
@@ -127,6 +127,11 @@
           "type": ["string", "null"],
           "description": "The id of the closed record whose supersedes link replaces this one. Derived from that record's link, never from this record's own fields."
         },
+        "remediatedBy": {
+          "description": "Added in contract 1 by #2774. The ids of records whose remediates link names this one, in path order. Unlike supersededBy, several records may remediate the same one, and a remediation never changes this record's state or supersededBy: it stays exactly as current as it was.",
+          "type": "array",
+          "items": { "type": "string" }
+        },
         "data": {
           "type": ["object", "null"],
           "description": "The record's structured core as JSON: the front matter, or for a kind of format json the whole file (#2664). It follows the kind's schema when valid is true. Null when it could not be parsed."
@@ -138,7 +143,7 @@
           "items": { "$ref": "#/$defs/asset" }
         },
         "warnings": {
-          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, (added by #2654) an evidence list that is empty, (added by #2672) a verdict that names no digest, or (added by #2683) a work record's links and dates, or (added by #2688) a record whose author seal is not attested under a signers file at base. A work record never carries record-no-evidence; a done one with no evidence carries work-done-unpinned. valid and --current do not look at them.",
+          "description": "Added in contract 1 by #2549. Findings that leave the record valid: a pinned file that changed, went missing or did not follow a superseding decision, a supersedes link that has no effect yet, (added by #2654) an evidence list that is empty, (added by #2672) a verdict that names no digest, or (added by #2683) a work record's links and dates, or (added by #2688) a record whose author seal is not attested under a signers file at base, or (added by #2772) a work record's acceptance criteria unmet when it is done, or met by a manual verdict from its implementer. A work record never carries record-no-evidence; a done one with no evidence carries work-done-unpinned. valid and --current do not look at them.",
           "type": "array",
           "items": { "$ref": "#/$defs/warning" }
         },
@@ -178,6 +183,10 @@
           "type": "array",
           "items": { "$ref": "#/$defs/workLink" }
         },
+        "acceptance": {
+          "description": "Added in contract 1 by #2772, on every parsed record of a work kind whose work block names acceptance criteria. How many of the record's criteria passing evidence meets: evidence naming the criterion, with result pass and the criterion's verification, and for a manual criterion a by other than the implementer. Null when the record lists no criteria, so a record without them reads as before.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workAcceptance" }]
+        },
         "lease": {
           "description": "Added in contract 1 by #2732, on every record of a work kind with an id, read in the working tree (absent under --at). The item's active work lease (chant workspace work claim), or null when nobody holds one live. Read from the local lease refs, refs/chant/lease/[_members/<member>/]work/<id> and the remote's as last fetched, of the ledger owning the work kind file; records never fetches.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workLease" }]
@@ -191,6 +200,27 @@
         }
       ]
     },
+    "workAcceptance": {
+      "type": "object",
+      "required": ["met", "total", "criteria"],
+      "properties": {
+        "met": { "type": "integer", "minimum": 0, "description": "How many criteria passing evidence meets." },
+        "total": { "type": "integer", "minimum": 0, "description": "How many criteria the record lists." },
+        "criteria": {
+          "type": "array",
+          "description": "Each criterion, in the record's order.",
+          "items": {
+            "type": "object",
+            "required": ["id", "verification", "met"],
+            "properties": {
+              "id": { "type": "string" },
+              "verification": { "enum": ["unit", "integration", "e2e", "runtime", "manual"], "description": "The verification the criterion expects." },
+              "met": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    },
     "workLease": {
       "type": "object",
       "required": ["holder", "token", "acquiredAt", "expiresAt"],
@@ -231,6 +261,8 @@
             "work-done-unpinned",
             "work-closed-without-date",
             "work-done-gap-open",
+            "work-acceptance-unmet",
+            "work-acceptance-self-verified",
             "answer-points-unreadable",
             "answer-point-unknown",
             "answer-point-changed",
@@ -372,6 +404,8 @@
             "record-id-duplicate",
             "record-supersedes-unknown",
             "record-supersedes-conflict",
+            "record-remediates-unknown",
+            "record-remediates-not-closed",
             "session-seal-mismatch",
             "session-verdict-unknown-record"
           ]

package/src/workspace/records.test.ts

@@ -11,12 +11,17 @@ const REPO = join(import.meta.dirname, "..", "..", "..", "..");
 const DECISIONS = join(REPO, "docs", "design", "decisions");
 const SAMPLE = readFileSync(join(DECISIONS, "ws-003-seal-scope.md"), "utf-8");
 
-/** A copy of a real decision with its id, state and supersedes links replaced. */
-function decision(id: string, state = "decided", supersedes: string[] = []): string {
+/** A copy of a real decision with its id, state, supersedes and remediates links replaced. */
+function decision(id: string, state = "decided", supersedes: string[] = [], remediates: string[] = []): string {
   const links = supersedes.length === 0 ? "supersedes: []" : `supersedes:\n${supersedes.map((d) => `  - decision: "${d}"`).join("\n")}`;
-  return SAMPLE.replace(/^id: .*$/m, `id: "${id}"`)
+  let text = SAMPLE.replace(/^id: .*$/m, `id: "${id}"`)
     .replace(/^state: .*$/m, `state: "${state}"`)
     .replace(/^supersedes:(?: \[\])?\n(?:  .*\n)*/m, `${links}\n`);
+  if (remediates.length > 0) {
+    const block = `remediates:\n${remediates.map((d) => `  - decision: "${d}"`).join("\n")}\n`;
+    text = text.replace(/^evidence:/m, `${block}evidence:`);
+  }
+  return text;
 }
 
 let dir: string;
@@ -235,6 +240,46 @@ describe("readRecords", () => {
     expect(codes(records[2])).toEqual(["record-supersedes-conflict"]);
   });
 
+  test("a remediates link to a missing id is record-remediates-unknown", async () => {
+    write("ws-002-b.md", decision("ws-002", "decided", [], ["ws-404"]));
+    const [r] = (await read()).records;
+    expect(codes(r)).toEqual(["record-remediates-unknown"]);
+  });
+
+  test("a remediates link to an open record is record-remediates-not-closed: a record still open is amended instead", async () => {
+    write("ws-001-a.md", decision("ws-001", "decided"));
+    write("ws-002-b.md", decision("ws-002", "ratified", [], ["ws-001"]));
+    const [ws001, ws002] = (await read()).records;
+    expect(codes(ws002)).toEqual(["record-remediates-not-closed"]);
+    expect(ws001.remediatedBy).toEqual([]);
+  });
+
+  test("remediation leaves the target current and its state unchanged, and several records may remediate the same one (#2774)", async () => {
+    write("ws-001-a.md", decision("ws-001", "ratified"));
+    write("ws-002-b.md", decision("ws-002", "ratified", [], ["ws-001"]));
+    write("ws-003-c.md", decision("ws-003", "ratified", [], ["ws-001"]));
+    const all = await read();
+    const [ws001] = all.records;
+    expect(ws001.state).toBe("ratified");
+    expect(ws001.supersededBy).toBeNull();
+    expect(ws001.remediatedBy).toEqual(["ws-002", "ws-003"]);
+    expect(all.summary.superseded).toBe(0);
+    const current = await read({ current: true });
+    expect(current.records.map((r) => r.id)).toEqual(["ws-001", "ws-002", "ws-003"]);
+  });
+
+  test("remediates and supersedes are independent links, and a record may carry both to different targets (#2774)", async () => {
+    write("ws-001-a.md", decision("ws-001", "ratified"));
+    write("ws-002-b.md", decision("ws-002", "ratified"));
+    write("ws-003-c.md", decision("ws-003", "ratified", ["ws-002"], ["ws-001"]));
+    const all = await read();
+    expect(all.records.map((r) => [r.id, r.supersededBy, r.remediatedBy])).toEqual([
+      ["ws-001", null, ["ws-003"]],
+      ["ws-002", "ws-003", []],
+      ["ws-003", null, []],
+    ]);
+  });
+
   test("a missing records directory is location-missing", async () => {
     const loaded = await loadRecordKind(join(dir, "decisions", "decision.kind.mjs"));
     const moved: LoadedRecordKind = { ...loaded, dir: join(dir, "nowhere") };
@@ -266,7 +311,7 @@ describe("a decision that originates in the workspace (#2654)", () => {
 
   test("takes a session and an issue, and nothing else", async () => {
     const base = workspaceDecision("ws-001");
-    write("ws-001-a.md", base.replace('  member: "app"\n', '  member: "app"\n  session: "S-0001"\n  issue: "jhgaylor/chud#77"\n'));
+    write("ws-001-a.md", base.replace('  member: "app"\n', '  member: "app"\n  session: "S-0001"\n  issue: "acme/example#77"\n'));
     write("ws-002-b.md", base.replace('id: "ws-001"', 'id: "ws-002"').replace('  member: "app"\n', '  member: "app"\n  session: null\n'));
     write("ws-003-c.md", base.replace('id: "ws-001"', 'id: "ws-003"').replace('  member: "app"\n', '  member: "app"\n  row: "Sort order"\n'));
     write("ws-004-d.md", base.replace('id: "ws-001"', 'id: "ws-004"').replace('  member: "app"\n', ""));