@intentius/chant 0.91.0 → 0.93.0

package/src/workspace/points-write.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/points-write/v1/points-write.schema.json",
   "title": "chant workspace points ask and answer output",
-  "description": "What `chant workspace points ask` and `points answer` print (ws-058, #2739): the answer record asked for or written, as `points --json` lists a question. ask returns the record that is there when the same point, declaration and inputs were answered or proposed before (reused), and otherwise writes one: answered from a table, proposed from a model at or above its threshold, escalated to people below it. answer records people's answer to an open question once the point's quorum is met. Nothing is committed, and nothing is written on a refusal or with --dry-run. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Written at contract version 1 of the write documents.",
+  "description": "What `chant workspace points ask` and `points answer` print (ws-058, #2739): the answer record asked for or written, as `points --json` lists a question. ask returns the record that is there when the same point, declaration and inputs were answered or proposed before (reused), and otherwise writes one: answered from a table, proposed from a model at or above its threshold, escalated to people below it. answer records people's answer to an open question once the point's quorum is met. Nothing is committed to the working branch, and nothing is written on a refusal or with --dry-run. In a steward's turn a new record goes on the lifecycle ledger instead of the working tree (#2786), as a commit on chant/lifecycle, and a record already held there is rewritten there. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Written at contract version 1 of the write documents.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -372,6 +372,13 @@
             "type": "string"
           }
         },
+        "ledger": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Where the record is held when it is on the lifecycle ledger rather than in the working tree (#2786): chant/lifecycle:<path>, which git show reads. A question asked in a steward's turn is held there, since a steward never writes the checkout; people's answer to it is written there too. null for a record in the working tree. path is where the record reads as being either way."
+        },
         "askedOn": {
           "type": [
             "string",
@@ -465,6 +472,7 @@
                 "point-decider-failed",
                 "answer-not-candidate",
                 "quorum-not-met",
+                "answer-in-steward-turn",
                 "record-not-found",
                 "record-closed",
                 "record-id-taken",
@@ -473,6 +481,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/points.schema.json

@@ -583,6 +583,39 @@
             "type": "string"
           }
         },
+        "askedBy": {
+          "description": "The steward whose turn asked the question (#2749), and the run it was in, or null. The steward waits on the question and never answers it: a person does.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "steward",
+                "run"
+              ],
+              "properties": {
+                "steward": {
+                  "type": "string"
+                },
+                "run": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              }
+            }
+          ]
+        },
+        "ledger": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Where the record is held when it is on the lifecycle ledger rather than in the working tree (#2786): chant/lifecycle:<path>, which git show reads. A question asked in a steward's turn is held there, since a steward never writes the checkout; people's answer to it is written there too. null for a record in the working tree. path is where the record reads as being either way."
+        },
         "askedOn": {
           "type": [
             "string",

package/src/workspace/points.test.ts

@@ -142,7 +142,7 @@ describe("the decision points schema (#2738)", () => {
 
   test("the reference workspace's points validate", () => {
     const points = parsePoints(readFileSync(join(REPO, "reference-workspace", "decisions", "points.json"), "utf-8"), "decisions/points.json");
-    expect(Object.keys(points)).toEqual(["slice-tier", "ship-skip"]);
+    expect(Object.keys(points)).toEqual(["slice-tier", "ship-skip", "finding-triage", "needs-a-decision"]);
   });
 
   test("a point whose chain does not end in a quorum is refused", () => {

package/src/workspace/points.ts

@@ -48,7 +48,7 @@ export const POINT_INPUT_OUTPUTS = {
   record: { schema: "records", def: "record", description: "a record of any kind, as records --json lists it" },
   decision: { schema: "records", def: "record", description: "a decision record, as records --json lists it" },
   "work-item": { schema: "records", def: "record", description: "a work item record, as records --json lists it (#2683)" },
-  finding: { schema: "intent", def: "finding", description: "a finding of graph --intent" },
+  finding: { schema: "intent", def: "finding", description: "a finding of graph --intent, or of check --changes (#2794)" },
   region: { schema: "intent", def: "region", description: "the region an intent graph covers" },
   commit: { schema: "intent", def: "commit", description: "a commit in an intent graph's window" },
   member: { schema: "ls", def: "member", description: "a member, as ls lists it" },

package/src/workspace/read-contract.test.ts

@@ -192,7 +192,7 @@ describe("every schema against the reference workspace (#2543)", () => {
       const doc = await workspacePoints({ cwd: FIXTURE, at });
       expectValid(doc);
       if ("error" in doc) throw new Error(doc.error.message);
-      expect(doc.points.map((p) => p.name)).toEqual(["slice-tier", "ship-skip"]);
+      expect(doc.points.map((p) => p.name)).toEqual(["slice-tier", "ship-skip", "finding-triage", "needs-a-decision"]);
     }
     const open = await workspacePoints({ cwd: FIXTURE, open: true });
     expectValid(open);

package/src/workspace/reason-codes.test.ts

@@ -9,6 +9,7 @@ import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { describe, expect, test } from "vitest";
 import { REPO } from "./__fixtures__/contract-repo";
+import { CHANGES_ERROR_CODES, CHANGES_FINDING_CODES } from "./changes";
 import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
 import { COMPOSITES_ENVIRONMENT_REASON_CODES, COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
@@ -26,7 +27,10 @@ import { RECORDS_SINCE_ERROR_CODES, RECORDS_SINCE_REASON_CODES } from "./records
 import { STATUS_ERROR_CODES, STATUS_GATE_REASON_CODES, STATUS_REASON_CODES, STATUS_STEWARD_REASON_CODES } from "./status";
 import { WORK_WARNING_CODES } from "./work";
 import { BOX_FINDING_CODES } from "./checks/boxes";
-import { WORK_ERROR_CODES, WORK_LEASE_REFUSALS } from "./work-cli";
+import { DIAGRAM_FINDING_CODES } from "./checks/diagrams";
+import { WORK_ERROR_CODES, WORK_HISTORY_ERROR_CODES, WORK_LEASE_REFUSALS } from "./work-cli";
+import { WORK_EVIDENCE_ERROR_CODES } from "./work-evidence";
+import { RECORD_FINDING_CODES } from "./checks/records";
 import { ANSWER_WARNING_CODES } from "./points";
 import { POINTS_ERROR_CODES, POINTS_SOURCE_REASON_CODES } from "./points-cli";
 import { POINTS_WRITE_ERROR_CODES } from "./decide";
@@ -42,6 +46,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   CHECK_CODES,
   CHECK_ERROR_CODES,
   BOX_FINDING_CODES,
+  DIAGRAM_FINDING_CODES,
   STATUS_REASON_CODES,
   STATUS_ERROR_CODES,
   STATUS_GATE_REASON_CODES,
@@ -62,12 +67,17 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   INTENT_ERROR_CODES,
   INTENT_FINDING_CODES,
   INTENT_REASON_CODES,
+  CHANGES_FINDING_CODES,
+  CHANGES_ERROR_CODES,
   COMPOSITES_ERROR_CODES,
   COMPOSITES_REASON_CODES,
   COMPOSITES_RUNTIME_REASON_CODES,
   COMPOSITES_ENVIRONMENT_REASON_CODES,
   WORK_ERROR_CODES,
+  WORK_HISTORY_ERROR_CODES,
   WORK_LEASE_REFUSALS,
+  WORK_EVIDENCE_ERROR_CODES,
+  RECORD_FINDING_CODES,
   ANSWER_WARNING_CODES,
   POINTS_ERROR_CODES,
   POINTS_SOURCE_REASON_CODES,

package/src/workspace/reason-codes.ts

@@ -60,13 +60,15 @@ export const REASONS = {
   // A member's stewards status can't fully list (status, #2731).
   "stewards-unreadable": "An *.op.ts file could not be imported, so a steward it declares may be missing.",
   "stewards-conflict": "A steward was dropped: its name, or an Op it lists, belongs to another steward.",
-  "steward-runs-unreadable": "Reading an Op's run ledger failed, so its last run is null.",
+  "steward-runs-unreadable": "Reading an Op's run ledger, or a ConvergeOp's converge ledger, failed, so its last run or last tick is null.",
   // A record that isn't valid (records).
   "record-unparseable": "No front matter, a YAML error or a value outside the JSON subset of YAML, or for a JSON kind a file that is not one object or repeats a member name.",
   "record-schema-invalid": "The record's front matter, or its JSON object, does not match the kind's schema.",
   "record-id-duplicate": "Another record earlier in path order has the same id.",
   "record-supersedes-unknown": "A supersedes link names an id no record has.",
   "record-supersedes-conflict": "A second closed record supersedes a record another one already superseded.",
+  "record-remediates-unknown": "A remediates link names an id no record has.",
+  "record-remediates-not-closed": "A remediates link names a record that isn't closed; a record still open is amended instead.",
   // A review session that isn't valid (records, #2673).
   "session-seal-mismatch": "A closed session's seal is not the digest of its text: the session changed after it closed.",
   "session-verdict-unknown-record": "A session's verdict names a record that none of the session kind's subject records has.",
@@ -86,6 +88,8 @@ export const REASONS = {
   "work-done-unpinned": "A work record is done and its evidence list is empty: nothing shows the work was done.",
   "work-closed-without-date": "A work record is done or dropped and has no closing date.",
   "work-done-gap-open": "A work record is done, and the finding it came from still fires on its region. graph --intent raises it, and records does by walking that region.",
+  "work-acceptance-unmet": "A work record is done, and one of its acceptance criteria has no passing evidence of the verification it expects. check fails on it (WSP117).",
+  "work-acceptance-self-verified": "A passing manual verdict on a work record's criterion names the record's implementer, so it does not count: a manual verdict comes from someone else.",
   // An answer to a decision point that is valid but warned about (records, points, ws-058, #2739).
   "answer-points-unreadable": "The points file the answer kind names can't be read, or is not valid.",
   "answer-point-unknown": "The answer's point is not declared in the points file the answer kind names.",
@@ -136,7 +140,8 @@ export const REASONS = {
   "point-inputs-invalid": "The inputs given to an ask are not a JSON object of the point's declared inputs.",
   "point-decider-failed": "A model decider that fails closed (unreachable: fail) could not answer, so the ask wrote nothing.",
   "answer-not-candidate": "The people's answer is not one of the question's candidates.",
-  "quorum-not-met": "Too few of the people who answered count toward the point's quorum: distinct, not holding the agent role, and holding one of its roles when it names any.",
+  "quorum-not-met": "Too few of the people who answered count toward the point's quorum: distinct, not holding the agent role, not the steward that asked, and holding one of its roles when it names any.",
+  "answer-in-steward-turn": "The answer was given during a steward's turn, or by a process it started: a steward never answers a decision point, and a person answers it through hud or at a shell.",
   // records --since that fails (#2673).
   "since-rev-unknown": "--since names no commit, or a session with no opening revision and no commit that added it.",
   "since-session-unknown": "--since has the shape of a session id and names no commit, and no session the kind or the declaration reads has that id.",
@@ -164,6 +169,9 @@ export const REASONS = {
   "intent-decision-unimplemented": "A decided decision constrains the region, no work item that is not dropped implements it, and no commit falls in its window.",
   "intent-work-blocked": "A work item constraining the region has commits in its window while a work item it needs is not done.",
   "intent-work-open-decided-code": "Commits in the region are a decision's own work while the work item implementing that decision is still open.",
+  // The forward coverage check (check --changes, #2773): findings, one per changed path.
+  "change-uncovered": "A path the diff changes is covered by no current decided record and no open work item, by path or by its member.",
+  "change-out-of-scope": "A record in hand for the change, such as the work item it is for or a decision that item implements, lists a path the diff changes in its out_of_scope.",
   // Composite instances joined to components (graph --composites, #2662): why the list is empty or has no component.
   "composites-no-chant-member": "No member of kind chant was read, so nothing declares a composite instance or a component.",
   "composites-none-declared": "The members read declare no composite instance.",
@@ -175,14 +183,22 @@ export const REASONS = {
   "environments-none-declared": "The member's chant.config.ts declares no environments, so only local and the environments in its ledger are listed.",
   "environments-ledger-undeclared": "The member's ledger has releases in an environment its config's environments don't cover, so chant run --env would refuse it and it is not listed.",
   "environments-ledger-unreadable": "The chant/lifecycle branch exists and the member's ledger environments could not be listed.",
+  // A declared diagram's source or render (check, #2764). Each is also a WSP finding.
+  "diagram-source-missing": "A declared diagram's source file does not exist in the tree read.",
+  "diagram-render-missing": "A declared diagram's render file does not exist in the tree read.",
+  "diagram-render-drift": "A declared diagram records a sourceHash, and the source's bytes now hash to something else: the render is stale for its source.",
   // A box that holds a credential (check, #2726). Each is also a WSP finding.
   "box-credential-declared": "A file in a box member's directory carries a literal secret: a credential's shape, or a literal where a credential goes. A variable or secret-manager reference is not one.",
   "box-capability-unbrokered": "A capability in a member's box block names no broker, so the box would hold its credential.",
+  // The credential fountain itself hands a persistent box (check, #2780). Also a WSP finding.
+  "box-fountain-callback-undeclared": "A box member builds a fountain Box, whose persistent sandbox fountain gives a callback token scoped to its owner, and the member's box block does not declare the fountain-callback capability brokered by fountain with scope owner.",
   // The work lease (chant workspace work claim|renew|release, #2732): why the command could not run.
   "work-kind-missing": "No work kind to find the item in: --kind names a kind with no work block, or the declaration names no work kind.",
   "work-kind-ambiguous": "More than one declared work kind has a record with the id, so --kind must name one.",
   "work-item-unknown": "No work record has the id, so there is nothing to lease.",
   "work-item-closed": "A claim on a work item in a closed state, such as done or dropped: there is no work left to claim.",
+  // Evidence attached to a criterion under the run's work lease (#2772): why it was refused. Nothing is written.
+  "work-criterion-unknown": "The work record lists no acceptance criterion with the id the evidence names, or its kind has no acceptance criteria.",
   // The work lease: why a claim, renew or release was refused (exit 2).
   "lease-held": "Someone holds a live lease on the work item: another worker, or, for a claim, the same one.",
   "lease-not-held": "Nobody holds a live lease on the work item: it expired, was released or was never claimed.",

package/src/workspace/records-amend.schema.json

@@ -180,6 +180,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-cli.ts

@@ -24,7 +24,7 @@ import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
 import { findWorkspaceRoot } from "../project-root";
 import { fileDigest, isWorkspacePath } from "./record-assets";
-import { gitRevisionSource, gitRoot, resolveRevision, workingTreeSource } from "./record-source";
+import { gitRevisionSource, gitRoot, resolveRevision, workingTreeSource, type RecordSource } from "./record-source";
 import { declaredRecordKinds, readDeclaration, WorkspaceReadError, type RecordKindDeclaration } from "./declaration";
 import { declaredKindFile } from "./declared-kinds";
 import { locateWorkspace } from "./which-chant";
@@ -249,7 +249,15 @@ function gitHistory(top: string, rev: string, prefix: string): RecordHistory {
  * with each pin checked in the same tree. Throws a {@link RecordReadError}.
  * `chant workspace graph` and `check` read records through this too.
  */
-export async function readRecordsFor(query: Omit<RecordsQuery, "base">): Promise<RecordsRead> {
+export async function readRecordsFor(
+  query: Omit<RecordsQuery, "base"> & {
+    /**
+     * Lay more records over a working-tree read, such as the answer records a
+     * steward keeps on the lifecycle ledger (#2786). Not called with `at`.
+     */
+    overlay?: (source: RecordSource, kind: { loaded: LoadedRecordKind; root: string }) => Promise<RecordSource>;
+  },
+): Promise<RecordsRead> {
   // git reports its top through symlinks resolved (/var is /private/var on
   // macOS), so the directory has to be too, or record paths leave the repository.
   const cwd = realpathOr(query.cwd);
@@ -266,6 +274,7 @@ export async function readRecordsFor(query: Omit<RecordsQuery, "base">): Promise
     source = gitRevisionSource(top, at);
     assets = gitTree(top, at, workspaceRoot === "." ? "" : workspaceRoot);
   }
+  if (at === null && query.overlay) source = await query.overlay(source, { loaded, root });
   const history = top ? gitHistory(top, at ?? "HEAD", workspaceRoot) : undefined;
   // A session kind's verdicts name records of another kind, read from the same tree (#2673).
   let subjects: { records: RecordEntry[]; reviews: string } | undefined;
@@ -602,9 +611,10 @@ function formatRecords(records: RecordView[], summary: { total: number; valid: n
     const title = typeof r.data?.title === "string" ? r.data.title : r.path;
     const flag = r.valid ? "" : "  INVALID";
     const superseded = r.supersededBy ? `  superseded by ${r.supersededBy}` : "";
+    const remediated = r.remediatedBy.length > 0 ? `  remediated by ${r.remediatedBy.join(", ")}` : "";
     const attested = r.provenance.level === "attested" ? `  attested by ${r.provenance.principal}` : "";
     const sealed = r.attested === true ? `  sealed by ${(r.data?.[RECORD_SEAL_FIELD] as { signer: string }).signer}` : "";
-    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${attested}${sealed}${flag}`);
+    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${remediated}${attested}${sealed}${flag}`);
     if (r.ready !== undefined) {
       const blocked = (r.blockedBy ?? []).map((b) => `${b.id} (${b.state ?? "unknown"})`).join(", ");
       const implemented = (r.implements ?? []).map((d) => `${d.id} (${d.state ?? "unknown"})`).join(", ");

package/src/workspace/records-close.schema.json

@@ -176,6 +176,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-new.schema.json

@@ -169,6 +169,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-review.schema.json

@@ -264,6 +264,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-sessions-write.e2e.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Sessions from a UI (#2693), through the command line: `records close` with
+ * the declared session kind, and `records --since <session id>` without
+ * --kind. Four CLI spawns put it near 13s on CI, close to the unit shards'
+ * per-test budget, so it runs in the test-e2e job (#2817). The rest of #2693
+ * is in records-sessions-write.test.ts.
+ */
+
+import { spawnSync } from "node:child_process";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterAll, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, contract, git, REPO } from "./__fixtures__/contract-repo";
+import { declareSessions, newSessionFields, sessionsRepo, SESSIONS_KIND } from "./__fixtures__/sessions";
+import closeSchema from "./records-close.schema.json";
+import { type RecordsSinceDocument } from "./records-since";
+import sinceSchema from "./records-since.schema.json";
+import { newRecord } from "./records-write";
+import newSchema from "./records-new.schema.json";
+
+afterAll(cleanScratch);
+
+const close = contract(closeSchema);
+const since = contract(sinceSchema);
+const created = contract(newSchema);
+
+/** The reference fixture with a declaration, committed. */
+function declared(): string {
+  const root = sessionsRepo();
+  declareSessions(root);
+  commitAll(root, "declare");
+  return root;
+}
+
+/** Open S-0002 through records new, and commit it. */
+async function opened(root: string): Promise<{ path: string; head: string }> {
+  const head = git(root, "rev-parse", "HEAD");
+  const doc = await newRecord({ kind: SESSIONS_KIND, fields: newSessionFields(), cwd: root });
+  created.expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  expect(doc.id).toBe("S-0002");
+  commitAll(root, "open S-0002");
+  return { path: doc.path, head };
+}
+
+describe("records --since <session id> (#2693)", () => {
+  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-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-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,
+  );
+});