@intentius/chant 0.124.24 → 0.124.25

package/src/workspace/points.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/points/v1/points.schema.json",
   "title": "chant workspace points output",
-  "description": "What `chant workspace points --json` prints (ws-058, #2739): the decision points each declared answer kind's points file declares, and the questions asked of them, each an answer record. A question is open while it is escalated to people, or proposed by a model and not yet confirmed; it carries any model's answer with its confidence and threshold, so a reader can prompt a person. With --open only open questions are listed. chant never calls a model to print this. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists, each in the one closed list of `reason-codes.ts`. Contract version 1 is written by chant 0.81.0 and newer, and this document was added to it by #2739; a chant without it refuses the command.",
+  "description": "What `chant workspace points --json` prints (ws-058, #2739): the decision points each declared answer kind's points file declares, and the questions asked of them, each an answer record. A question is open while it is escalated to people, or proposed by a model and not yet confirmed, and not withdrawn (#2888); it carries any model's answer with its confidence and threshold, so a reader can prompt a person. With --open only open questions are listed. chant never calls a model to print this. Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists, each in the one closed list of `reason-codes.ts`. Contract version 1 is written by chant 0.81.0 and newer, and this document was added to it by #2739; a chant without it refuses the command.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -95,7 +95,8 @@
             "open",
             "escalated",
             "proposed",
-            "answered"
+            "answered",
+            "withdrawn"
           ],
           "properties": {
             "points": {
@@ -121,6 +122,11 @@
             "answered": {
               "type": "integer",
               "minimum": 0
+            },
+            "withdrawn": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Questions withdrawn because they no longer apply (#2888), whatever their state; none of them is open."
             }
           }
         }
@@ -765,6 +771,38 @@
             }
           }
         },
+        "withdrawn": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "description": "Who withdrew the question, when and why (points withdraw, #2888): an open question that no longer applies, such as one about a work item its author changed. A withdrawn question keeps its state and is not open. null when it was not withdrawn, and absent from a chant before it.",
+          "required": [
+            "by",
+            "on",
+            "note"
+          ],
+          "properties": {
+            "by": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "on": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "note": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        },
         "asked": {
           "description": "An ad-hoc point's question as its ask gave it (points ask --candidates, #3403): the question's text, and its criteria, what each candidate means, in the point's question type's shape. People's answer is one of the candidates. null for a declared point's question, and absent from a chant before it.",
           "oneOf": [
@@ -825,7 +863,8 @@
                   "answer-points-unreadable",
                   "answer-point-unknown",
                   "answer-point-changed",
-                  "record-unattested"
+                  "record-unattested",
+                  "record-ratified-below-quorum"
                 ]
               },
               "message": {

package/src/workspace/reason-codes.ts

@@ -112,6 +112,7 @@ export const REASONS = {
   "seal-unverifiable": "Nothing here can say whose seal it is: there is no signers file at base, ssh-keygen is not installed, or the record came back in a return sealed by a signer no admission lists yet.",
   // A record whose author seal is not attested under a signers file at base (records, #2688). A warning: the record is still read.
   "record-unattested": "A signers file is active at base, and the record names an author whose seal does not verify: it has none, the author has no key in the file, or the signature fails.",
+  "record-ratified-below-quorum": "The record is in its kind's ratified state (reviews.ratified), and its quorum is not met: it was written to that state by hand, past the check of records new and amend. It is still read, and stays valid.",
   // A records read that fails (records).
   "kind-unreadable": "The record kind file is missing or could not be imported.",
   "kind-invalid": "The record kind file exports no recordKind, or its shape is wrong.",
@@ -161,7 +162,7 @@ export const REASONS = {
   "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.",
   "answer-never-over-mcp": "The answer or retraction came over MCP or ACP, or from a process a session on one started, and the question constrains a gate that is never resolved there: a person answers it at a shell or through hud (#3817).",
   "answer-not-answered": "points retract names a question that has no answer to retract: it is escalated or proposed, and people answer it instead (#3351).",
-  "answer-field-unsupported": "The answer kind's copy of point-answer.schema.json predates a field the write needs, a note, a relay, a retraction or an ad-hoc question's asked: copy the schema anew to turn it on (#3351, #3402, #3403).",
+  "answer-field-unsupported": "The answer kind's copy of point-answer.schema.json predates a field the write needs, a note, a relay, a retraction, an ad-hoc question's asked or a withdrawal: copy the schema anew to turn it on (#3351, #3402, #3403, #2888).",
   "point-candidates-invalid": "points ask names an ad-hoc point without --candidates, a declared point with them, or candidates that are not a question and criteria of the point's question type (#3403).",
   // 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.",

package/src/workspace/record-assets.test.ts

@@ -181,6 +181,20 @@ describe("chant workspace records checks each pin", () => {
     expect(pinFile("ws/design/screens/home.png", root)).toEqual({ path: "design/screens/home.png", sha256: sha(PNG) });
     expect(pinFile("design", join(root, "ws"))).toEqual({ error: "design is not a file" });
   });
+
+  test("records pin takes the workspace above the current directory or the kind file, not the nested one above the file (#3038)", () => {
+    const root = repo({
+      "chant.workspace.json": declaration([{ name: "template", dir: "template", kind: "other", because: "a template" }]),
+      "template/chant.workspace.json": declaration([{ name: "box", dir: "box", kind: "other", because: "the box" }]),
+      "template/box/builder.mjs": "export {};\n",
+      "decisions/decision.kind.mjs": KIND,
+    });
+    const hash = sha("export {};\n");
+    expect(pinFile("template/box/builder.mjs", root)).toEqual({ path: "template/box/builder.mjs", sha256: hash });
+    expect(pinFile("box/builder.mjs", join(root, "template"))).toEqual({ path: "box/builder.mjs", sha256: hash });
+    expect(pinFile("box/builder.mjs", join(root, "template"), "../decisions/decision.kind.mjs")).toEqual({ path: "template/box/builder.mjs", sha256: hash });
+    expect(pinFile("chant.workspace.json", root, "template/box/builder.mjs")).toMatchObject({ error: expect.stringContaining("not a file path inside the workspace") });
+  });
 });
 
 describe("chant workspace graph --kind", () => {

package/src/workspace/records-cli.ts

@@ -78,7 +78,7 @@ export const RECORDS_CONTRACT_VERSION = 1;
 export const RECORDS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json";
 
 const USAGE =
-  "chant workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--json] | chant workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json] | chant workspace records pin <path> | chant workspace records new|amend|review|close (#2670, #2693)";
+  "chant workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--json] | chant workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json] | chant workspace records pin <path> [--kind <kind file>] | chant workspace records new|amend|review|close (#2670, #2693)";
 
 /** Exit code when the read worked and a record falls below `--require`. */
 export const EXIT_BELOW_REQUIRED = 2;
@@ -336,6 +336,16 @@ export async function quorumOptionsFor(loaded: LoadedRecordKind, tree: Workspace
   };
 }
 
+/**
+ * What a quorum that is not met lacks, for `ratify-quorum-not-met` and
+ * `record-ratified-below-quorum` (#2873, #2878): the need, the agreeing
+ * verdicts that count, and each verdict that does not count, with why.
+ */
+export function quorumShortfall(q: Quorum): string {
+  const notCounted = q.notCounted.length > 0 ? ` (not counted: ${q.notCounted.map((v) => `${v.reviewer}, ${v.reason!.code}`).join("; ")})` : "";
+  return `its quorum needs ${q.need} agreeing verdicts that count, and it has ${q.agreed}${notCounted}`;
+}
+
 /**
  * Where a kind's pinned paths resolve: the workspace whose declaration sits
  * nearest above the kind file, when it is inside the repository, or else the
@@ -446,10 +456,16 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       // Returned work (#2552): its seals verify against the signers admitted for its return too.
       const recordPolicy = p.returned ? returnedPolicy(policy, p.returned.id) : policy;
       const options = p.returned ? await quorumOptionsFor(loaded, tree, recordPolicy) : quorumOptions;
+      const quorum = options ? computeQuorum(loaded.kind, r, options) : null;
+      const ratified = loaded.kind.reviews?.ratified;
+      if (quorum && !quorum.met && ratified !== undefined && r.state === ratified) {
+        // Written to the ratified state by hand, past the check of records new and amend (#2878).
+        r.warnings.push({ code: "record-ratified-below-quorum", message: `${r.id ?? r.path} is ${ratified}, and ${quorumShortfall(quorum)}` });
+      }
       records.push({
         ...r,
         provenance: p,
-        ...(options ? { quorum: computeQuorum(loaded.kind, r, options) } : {}),
+        ...(options ? { quorum } : {}),
         ...(seals ? authorSeal(loaded.kind, r, recordPolicy, seals.checkRecordSeal) : {}),
       });
     }
@@ -635,12 +651,17 @@ async function raiseWorkGaps(loaded: LoadedRecordKind, records: RecordView[], op
 /**
  * `chant workspace records pin <path>`: the `{path, sha256}` a decision's
  * evidence entry holds for a file, with the path from the workspace root
- * (the nearest declaration above the file, or the repository root).
+ * records resolve pins in. With `kind`, that is the declaration nearest above
+ * the kind file, or the repository root, as {@link pinRoot} has it. Without,
+ * it is the declaration nearest above `cwd`, and only when there is none the
+ * one nearest above the file, so a workspace nested inside the current one is
+ * never taken for it (#3038).
  */
-export function pinFile(file: string, cwd: string): { path: string; sha256: string } | { error: string } {
+export function pinFile(file: string, cwd: string, kind?: string): { path: string; sha256: string } | { error: string } {
   const abs = realpathOr(resolve(cwd, file));
-  const top = gitRoot(dirname(abs));
-  const ws = findWorkspaceRoot(dirname(abs));
+  const from = kind === undefined ? dirname(abs) : dirname(resolve(cwd, kind));
+  const ws = kind === undefined ? (findWorkspaceRoot(cwd) ?? findWorkspaceRoot(from)) : findWorkspaceRoot(from);
+  const top = gitRoot(from);
   const base = ws ? realpathOr(ws.dir) : top ? realpathOr(top) : realpathOr(cwd);
   const path = relative(base, abs).split(sep).join("/");
   if (path.startsWith("..") || !isWorkspacePath(path)) return { error: `${file} is not a file path inside the workspace at ${base}` };
@@ -659,7 +680,7 @@ export async function runWorkspaceRecords(ctx: CommandContext): Promise<number>
       console.error(formatError({ message: "pin needs the path of a file", hint: USAGE }));
       return 1;
     }
-    const pin = pinFile(args.extraPositional2, process.cwd());
+    const pin = pinFile(args.extraPositional2, process.cwd(), args.kind);
     if ("error" in pin) {
       console.error(formatError({ message: pin.error, hint: USAGE }));
       return 1;

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

@@ -419,6 +419,38 @@ describe("ratifying against the quorum (#2873)", () => {
     expect(code(doc)).toBe("ratify-quorum-not-met");
   });
 
+  test("a record edited by hand to ratified below its quorum reads with record-ratified-below-quorum, and stays valid (#2878)", async () => {
+    const read = async (id: string, kind = KIND) => {
+      const doc = await queryRecords({ kind, cwd: dir });
+      if ("error" in doc) throw new Error(doc.error.message);
+      return doc.records.find((r) => r.id === id)!;
+    };
+    const warned = (r: { warnings: { code: string }[] }) => r.warnings.some((w) => w.code === "record-ratified-below-quorum");
+    // A decided record below its quorum is not warned about.
+    await agree("alice");
+    await agree("lex00");
+    expect(warned(await read("ws-001"))).toBe(false);
+    writeFileSync(join(dir, "decisions", "ws-001-one.md"), text("ws-001-one.md").replace('state: "decided"', 'state: "ratified"'));
+    const r = await read("ws-001");
+    expect(r).toMatchObject({ state: "ratified", valid: true, reasons: [] });
+    expect(r.quorum).toMatchObject({ need: 2, agreed: 1, met: false });
+    expect(r.warnings.find((w) => w.code === "record-ratified-below-quorum")!.message).toBe(
+      "ws-001 is ratified, and its quorum needs 2 agreeing verdicts that count, and it has 1 (not counted: lex00, review-decider)",
+    );
+    // A record ratified through amend at its quorum carries no such warning.
+    put("ws-006-six.md", decision({ id: "ws-006", title: "Six" }));
+    await agree("alice", "ws-006");
+    await agree("bob", "ws-006");
+    expect(await ratify("ws-006")).toMatchObject({ changed: ["state", "closed_digest"] });
+    expect(warned(await read("ws-006"))).toBe(false);
+    // A kind without reviews.ratified never warns: ws-003 opened ratified with no verdicts.
+    expect(warned(await read("ws-003"))).toBe(true);
+    // A kind module is cached by its path, so the kind without it is a second file.
+    const kindFile = join(dir, "decisions", "decision.kind.mjs");
+    writeFileSync(join(dir, "decisions", "plain.kind.mjs"), readFileSync(kindFile, "utf-8").replace(', ratified: "ratified" }', " }"));
+    expect(warned(await read("ws-003", "decisions/plain.kind.mjs"))).toBe(false);
+  });
+
   test("records new refuses a record that opens ratified below its quorum", async () => {
     const fresh = decision({ title: "Straight in", state: "ratified" });
     delete fresh.id;

package/src/workspace/records-write.ts

@@ -61,7 +61,7 @@ import {
   type RecordEntry,
   type RecordWarning,
 } from "./records";
-import { declaredKindFiles, pinRoot, quorumOptionsFor, realpathOr } from "./records-cli";
+import { declaredKindFiles, pinRoot, quorumOptionsFor, quorumShortfall, realpathOr } from "./records-cli";
 import { policyAtBase, resolveBase } from "./trust/provenance";
 import { WorkspaceReadError } from "./declaration";
 import { findSessionKinds, headCommit, sessionKindsFor } from "./session-kinds";
@@ -516,10 +516,9 @@ async function refuseRatifyBelowQuorum(o: Opened, written: RecordEntry, id: stri
   const options = await quorumOptionsFor(o.loaded, tree, policy);
   const q = options ? computeQuorum(o.loaded.kind, written, options) : null;
   if (q === null || q.met) return;
-  const notCounted = q.notCounted.length > 0 ? ` (not counted: ${q.notCounted.map((v) => `${v.reviewer}, ${v.reason!.code}`).join("; ")})` : "";
   throw new RecordWriteError(
     "ratify-quorum-not-met",
-    `${id} can't be ${ratified} yet: its quorum needs ${q.need} agreeing verdicts that count, and it has ${q.agreed}${notCounted}. Add verdicts with chant workspace records review ${id} --verdict agree --by <reviewer>, then set ${o.loaded.kind.stateField} to ${ratified} again`,
+    `${id} can't be ${ratified} yet: ${quorumShortfall(q)}. Add verdicts with chant workspace records review ${id} --verdict agree --by <reviewer>, then set ${o.loaded.kind.stateField} to ${ratified} again`,
   );
 }
 

package/src/workspace/records.schema.json

@@ -413,7 +413,8 @@
             "answer-points-unreadable",
             "answer-point-unknown",
             "answer-point-changed",
-            "record-unattested"
+            "record-unattested",
+            "record-ratified-below-quorum"
           ]
         },
         "message": { "type": "string" }

package/src/workspace/records.ts

@@ -147,8 +147,9 @@ export const SEAL_REASON_CODES = [
 export type SealCode = (typeof SEAL_REASON_CODES)[number];
 
 /**
- * A warning about a record's own seal (#2688), raised by `records` with the
- * policy at base, never by a write. Closed, like the reason codes.
+ * A warning `records` raises with the policy at base, never by a write: about
+ * a record's own seal (#2688), or a ratified record's quorum (#2878). Closed,
+ * like the reason codes.
  */
 export const SEAL_WARNING_CODES = [
   /**
@@ -158,6 +159,13 @@ export const SEAL_WARNING_CODES = [
    * fails. The record is still read, and still valid.
    */
   "record-unattested",
+  /**
+   * The record is in its kind's ratified state (`reviews.ratified`, #2873),
+   * and its quorum, computed as `records` computes it, is not met: it was
+   * written to that state by hand, past the check of `records new` and
+   * `amend`. The record is still read, and still valid (#2878).
+   */
+  "record-ratified-below-quorum",
 ] as const satisfies readonly ReasonCode[];
 export type SealWarningCode = (typeof SEAL_WARNING_CODES)[number];
 
@@ -201,7 +209,7 @@ export interface VerdictAttestation {
 }
 
 export interface RecordWarning {
-  /** A work kind's records also carry the codes of `WORK_WARNING_CODES` (#2683), an answer kind's those of `ANSWER_WARNING_CODES` (#2739), and `records` adds `SEAL_WARNING_CODES` (#2688). */
+  /** A work kind's records also carry the codes of `WORK_WARNING_CODES` (#2683), an answer kind's those of `ANSWER_WARNING_CODES` (#2739), and `records` adds `SEAL_WARNING_CODES` (#2688, #2878). */
   code: RecordWarningCode | WorkWarningCode | SealWarningCode | AnswerWarningCode;
   message: string;
 }
@@ -618,12 +626,17 @@ export interface LoadedRecordKind {
  * Import the kind file at `path` through the path loader lexicons use (#2520).
  * The kind is registered under a name no lexicon package can have (npm names
  * hold no `:`), imported and unregistered again, so no lexicon lookup sees it.
+ *
+ * A kind file is a data-only ES module, so a `.mjs`, `.cjs` or `.js` one loads
+ * with plain node and only a TypeScript one registers tsx (#3276). That keeps
+ * `workspace ls`, `status` and `records` from paying for tsx's loader thread
+ * on every read.
  */
 export async function importKindModule(path: string): Promise<Record<string, unknown>> {
   const name = `record-kind:${path}`;
   registerLexiconDeclarations([{ name, module: path }], dirname(path));
   try {
-    const mod = await importLexiconModule(name);
+    const mod = await importLexiconModule(name, { typeScript: !/\.[cm]?js$/.test(path) });
     if (!mod) throw new Error(`${path} was not registered`);
     return mod;
   } finally {

package/src/workspace/trust/trust.test.ts

@@ -8,6 +8,7 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { join } from "node:path";
 import Ajv2020 from "ajv/dist/2020";
 import schema from "../records.schema.json";
 import { afterEach, describe, expect, test } from "vitest";
@@ -357,6 +358,110 @@ describe.skipIf(!hasSshKeygen)("the ssh-commit attestor, against the policy at b
   });
 });
 
+describe.skipIf(!hasSshKeygen)("writeScope and agents in the declaration are protected (#3079)", () => {
+  const scoped = (over: Record<string, unknown> = {}) =>
+    JSON.stringify(
+      {
+        name: "ws",
+        schema: 1,
+        members: [{ name: "app", dir: "app", kind: "other", because: "plain files" }],
+        writeScope: { agent: { records: {} } },
+        agents: [{ name: "app-agent", member: "app" }],
+        ...over,
+      },
+      null,
+      2,
+    );
+
+  /** main: alice and bob sign, alice is admin when `admin`; the declaration at base restricts agents. */
+  function baseline(label: string, opts: { admin?: boolean; declaration?: string; dir?: string } = {}) {
+    const r = repo(label);
+    const alice = r.key("alice");
+    const bob = r.key("bob");
+    r.write(".chant/allowed_signers", signers(["alice@example.test", alice], ["bob@example.test", bob]));
+    if (opts.admin) r.write(".chant/trust.json", JSON.stringify({ schema: 1, roles: { admin: ["alice@example.test"] } }));
+    r.commit("policy", alice);
+    r.write(`${opts.dir ? `${opts.dir}/` : ""}chant.workspace.json`, opts.declaration ?? scoped());
+    r.commit("declaration", alice);
+    r.git(["checkout", "-q", "-b", "change"]);
+    return { r, alice, bob };
+  }
+
+  test("an unsigned commit that widens writeScope is a refused protected write", async () => {
+    const { r } = baseline("scope-unsigned");
+    r.write("chant.workspace.json", scoped({ writeScope: { agent: { records: { decision: ["new", "amend"] } } } }));
+    const c = r.commit("let agents amend");
+    const report = await verify(r);
+    expect(report.ok).toBe(false);
+    expect(report.protectedWrites).toEqual([expect.objectContaining({ commit: c, paths: ["chant.workspace.json"], allowed: false })]);
+    expect(report.failures.join("\n")).toMatch(/chant\.workspace\.json \(writeScope\) is protected/);
+  });
+
+  test("a change to agents is a protected write, allowed when a signer at base signs it", async () => {
+    const { r, alice } = baseline("agents-signed");
+    r.write("chant.workspace.json", scoped({ agents: [{ name: "app-agent", member: "app" }, { name: "other", member: "app" }] }));
+    r.commit("add a session", alice);
+    const report = await verify(r);
+    expect(report.protectedWrites).toEqual([expect.objectContaining({ allowed: true, principal: "alice@example.test", blocks: ["agents"] })]);
+    expect(report.ok).toBe(true);
+  });
+
+  test("with an admin role granted, a signer who is not an admin may not change writeScope", async () => {
+    const { r, bob } = baseline("scope-admin", { admin: true });
+    r.write("chant.workspace.json", scoped({ writeScope: {} }));
+    r.commit("drop the scope", bob);
+    const report = await verify(r);
+    expect(report.protectedWrites[0]).toMatchObject({ allowed: false, principal: "bob@example.test", blocks: ["writeScope"] });
+    expect(report.ok).toBe(false);
+  });
+
+  test("deleting the declaration drops the scope, and is a protected write", async () => {
+    const { r } = baseline("scope-deleted");
+    r.git(["rm", "-q", "chant.workspace.json"]);
+    r.commit("no more workspace");
+    const report = await verify(r);
+    expect(report.protectedWrites[0]).toMatchObject({ allowed: false, blocks: ["writeScope", "agents"] });
+    expect(report.ok).toBe(false);
+  });
+
+  test("other edits to the declaration are not protected", async () => {
+    const { r } = baseline("scope-other");
+    r.write("chant.workspace.json", scoped({ name: "renamed" }));
+    r.commit("rename");
+    const report = await verify(r);
+    expect(report.protectedWrites).toEqual([]);
+    expect(report.declaration).toEqual({ path: "chant.workspace.json", blocks: ["writeScope", "agents"], changed: [] });
+    expect(report.ok).toBe(true);
+  });
+
+  test("a scope the change adds, where the declaration at base has none, is not protected", async () => {
+    const { r } = baseline("scope-none", { declaration: JSON.stringify({ name: "ws", schema: 1, members: [] }) });
+    r.write("chant.workspace.json", scoped());
+    r.commit("restrict agents");
+    const report = await verify(r);
+    expect(report.protectedWrites).toEqual([]);
+    expect(report.declaration).toBeNull();
+  });
+
+  test("a change and its revert inside the range leave nothing to protect", async () => {
+    const { r } = baseline("scope-revert");
+    r.write("chant.workspace.json", scoped({ writeScope: {} }));
+    r.commit("drop");
+    r.write("chant.workspace.json", scoped());
+    r.commit("restore");
+    const report = await verify(r);
+    expect(report.protectedWrites).toEqual([]);
+  });
+
+  test("the declaration is found from cwd, as check --changes finds it", async () => {
+    const { r } = baseline("scope-nested", { dir: "ws" });
+    r.write("ws/chant.workspace.json", scoped({ writeScope: {} }));
+    r.commit("drop");
+    const report = await verifyChange({ repo: r.dir, cwd: join(r.dir, "ws"), base: "main", attestors: await activeAttestors() });
+    expect(report.protectedWrites).toEqual([expect.objectContaining({ paths: ["ws/chant.workspace.json"], allowed: false })]);
+  });
+});
+
 describe("attestation is opt-in", () => {
   test("without a signers file at base nothing is verified, and every record is unattested", async () => {
     const r = repo("off");

package/src/workspace/trust/verify-cli.ts

@@ -26,6 +26,7 @@ export async function runWorkspaceVerify(ctx: CommandContext): Promise<number> {
   }
   const report = verifyChange({
     repo,
+    cwd: process.cwd(),
     base: args.base,
     head: args.head,
     require: args.require === "attested" || args.require === "attested-runs" ? args.require : undefined,
@@ -49,7 +50,7 @@ function printReport(r: ChangeReport): void {
     lines.push(`  ${c.commit.slice(0, 8)}  ${c.level}${who}  ${c.subject}${note}`);
   }
   for (const c of r.runs.commits) lines.push(`  ${c.commit.slice(0, 8)}  agent run ${c.runs.join(", ") || c.run}: ${c.attested ? "attested" : "not attested"}, ${c.reason}`);
-  for (const w of r.protectedWrites) lines.push(`  protected write ${w.commit.slice(0, 8)} ${w.paths.join(", ")}: ${w.allowed ? "allowed" : "refused"}, ${w.reason}`);
+  for (const w of r.protectedWrites) lines.push(`  protected write ${w.commit.slice(0, 8)} ${w.paths.join(", ")}${w.blocks ? ` (${w.blocks.join(", ")})` : ""}: ${w.allowed ? "allowed" : "refused"}, ${w.reason}`);
   if (r.rotation && "to" in r.rotation) lines.push(`  signer set: version ${r.rotation.from} to ${r.rotation.to}, signed by ${r.rotation.signedBy.join(", ")}`);
   for (const n of r.notes) lines.push(n);
   console.log(lines.join("\n"));

package/src/workspace/trust/verify.ts

@@ -8,6 +8,12 @@
  * that touches those files must be attested by a signer the base policy
  * trusts, and by an admin when the base policy grants the admin role.
  *
+ * The write scope is policy too (#3079): when the workspace declaration at
+ * base has a `writeScope` or `agents` block, a commit that changes either
+ * block, or removes the declaration, is a protected write on the same terms.
+ * Other edits to the declaration are not. The declaration is found from
+ * `cwd`, as `chant workspace check --changes` finds it.
+ *
  * Attestation is opt-in (#2525 rule 6). Without a signers file at base the
  * check passes and says so, unless `--require attested` asks for more.
  *
@@ -22,6 +28,11 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { posix } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { DECLARATION_FILES, WorkspaceReadError } from "../declaration";
+import { parseJsonText } from "../jsonc";
+import { locateWorkspace } from "../which-chant";
 import { type CommitAttestor, type ProvenanceLevel } from "./attestor";
 import { policyAtBase, commitProvenance, resolveBase, type BaseSource, type RecordProvenance } from "./provenance";
 import { policyWriters, protectedPaths, type ExcludedSigner, type TrustPolicy } from "./policy";
@@ -41,6 +52,8 @@ export interface CommitVerdict extends RecordProvenance {
 export interface ProtectedWrite {
   commit: string;
   paths: string[];
+  /** For a declaration write (#3079): the scope blocks the commit changes. */
+  blocks?: ScopeBlock[];
   level: ProvenanceLevel;
   principal?: string;
   allowed: boolean;
@@ -67,6 +80,12 @@ export interface ChangeReport {
   /** Protected paths whose content differs between the merge base and head. */
   protectedChanged: string[];
   protectedWrites: ProtectedWrite[];
+  /**
+   * The workspace declaration at base, when it has a scope block (#3079): its
+   * path from the repository root, the blocks it has, and the blocks that
+   * differ between the merge base and head.
+   */
+  declaration: { path: string; blocks: ScopeBlock[]; changed: ScopeBlock[] } | null;
   /**
    * When the change edits the signer set (#2553): the version it proposes and
    * who signed it, or, when the new set is refused, the version it had to
@@ -80,6 +99,8 @@ export interface ChangeReport {
 
 export interface VerifyOptions {
   repo: string;
+  /** Where to look for the workspace declaration, as `check --changes` does; the repository root by default. */
+  cwd?: string;
   base?: string;
   head?: string;
   require?: VerifyRequirement;
@@ -106,6 +127,51 @@ export function commitsTouching(repo: string, range: string, paths: string[]): M
   return out;
 }
 
+/** The declaration blocks whose change is a protected write (#3079). */
+export type ScopeBlock = "writeScope" | "agents";
+const SCOPE_BLOCKS: readonly ScopeBlock[] = ["writeScope", "agents"];
+
+/** The scope blocks of the declaration in `dir` at `rev`: absent ones undefined, or the text when it can't be read. */
+type ScopeState = { blocks: Partial<Record<ScopeBlock, unknown>> } | { unreadable: string };
+
+function scopeState(repo: string, rev: string, dir: string): ScopeState {
+  const present = DECLARATION_FILES.map((name) => ({ name, text: fileAt(repo, rev, posix.join(dir, name)) })).filter((f) => f.text !== undefined);
+  if (present.length === 0) return { blocks: {} };
+  if (present.length > 1) return { unreadable: present.map((f) => f.text).join("\0") };
+  const parsed = parseJsonText(present[0].text!, { jsonc: present[0].name.endsWith(".jsonc") });
+  if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null || Array.isArray(parsed.value)) return { unreadable: present[0].text! };
+  const obj = parsed.value as Record<string, unknown>;
+  return { blocks: Object.fromEntries(SCOPE_BLOCKS.filter((b) => obj[b] !== undefined).map((b) => [b, obj[b]])) };
+}
+
+/** The scope blocks that differ between two states; all of them when either can't be read and the texts differ. */
+function changedBlocks(a: ScopeState, b: ScopeState): ScopeBlock[] {
+  if ("unreadable" in a || "unreadable" in b) {
+    return "unreadable" in a && "unreadable" in b && a.unreadable === b.unreadable ? [] : [...SCOPE_BLOCKS];
+  }
+  return SCOPE_BLOCKS.filter((k) => !isDeepStrictEqual(a.blocks[k], b.blocks[k]));
+}
+
+/**
+ * The directory, from the repository root, of the declaration found from
+ * `cwd` at `base`, with the scope blocks it has there. Null when there is no
+ * declaration, or one with neither block: then nothing in it is protected. A
+ * declaration that can't be read at base counts as having both.
+ */
+function scopedDeclarationAt(repo: string, cwd: string, base: string): { dir: string; blocks: ScopeBlock[] } | null {
+  let dir: string;
+  try {
+    const root = locateWorkspace(cwd, base).root;
+    dir = root === "." ? "" : root;
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) return null;
+    throw err;
+  }
+  const state = scopeState(repo, base, dir);
+  const blocks = "unreadable" in state ? [...SCOPE_BLOCKS] : SCOPE_BLOCKS.filter((b) => b in state.blocks);
+  return blocks.length > 0 ? { dir, blocks } : null;
+}
+
 /** Whether a merge commit changes nothing beyond what its parents bring. */
 function mergeWithoutOwnChanges(repo: string, commit: string, parents: number): boolean {
   if (parents < 2) return false;
@@ -134,6 +200,7 @@ export function verifyChange(opts: VerifyOptions): ChangeReport {
     protectedPaths: protectedPaths(policy),
     protectedChanged: [],
     protectedWrites: [],
+    declaration: null,
     rotation: null,
     notes: [],
     failures: [],
@@ -157,7 +224,8 @@ export function verifyChange(opts: VerifyOptions): ChangeReport {
 
   // Every commit in the change, oldest first, with its parents.
   const listing = git(repo, ["rev-list", "--reverse", "--parents", `${base.commit}..${head}`]).split("\n").filter(Boolean);
-  const parentsOf = new Map(listing.map((l) => { const [c, ...p] = l.split(" "); return [c, p.length] as const; }));
+  const parentList = new Map(listing.map((l) => { const [c, ...p] = l.split(" "); return [c, p] as const; }));
+  const parentsOf = new Map([...parentList].map(([c, p]) => [c, p.length] as const));
   report.runs = changeRuns(repo, [...parentsOf.keys()], policy.runners);
   if (opts.require === "attested-runs") {
     if (policy.runners.length === 0 && report.runs.commits.length > 0) {
@@ -204,23 +272,48 @@ export function verifyChange(opts: VerifyOptions): ChangeReport {
   }
 
   // Protected writes: every commit that touches the policy needs a writer's signature.
+  const writers = policyWriters(policy);
+  const judge = (commit: string, paths: string[], blocks?: ScopeBlock[]) => {
+    const v = verdicts.get(commit) ?? { ...commitProvenance(repo, policy, commit, opts.attestors), commit, subject: "" };
+    const allowed = v.level === "attested" && v.principal !== undefined && writers.has(v.principal);
+    const who = policy.roles.admin?.length ? "an admin the policy at base names" : "a signer the policy at base lists";
+    const what = blocks ? `${paths.join(", ")} (${blocks.join(", ")})` : paths.join(", ");
+    const reason = allowed
+      ? `signed by ${v.principal}, ${who.replace(/^an? /, "")}`
+      : v.level === "attested"
+        ? `signed by ${v.principal}, who is not ${who}`
+        : `${what} is protected and needs a signature by ${who}: ${v.reason}`;
+    report.protectedWrites.push({ commit, paths, ...(blocks ? { blocks } : {}), level: v.level, ...(v.principal ? { principal: v.principal } : {}), allowed, reason });
+    if (!allowed) report.failures.push(`${commit.slice(0, 8)} changes ${what}: ${reason}`);
+  };
   if (changedPaths.length > 0) {
-    const writers = policyWriters(policy);
     const touching = commitsTouching(repo, `${base.commit}..${head}`, report.protectedPaths);
     if (touching.size === 0) {
       report.failures.push(`the policy files ${changedPaths.join(", ")} differ from base, and no commit in the change accounts for it`);
     }
-    for (const [commit, paths] of touching) {
-      const v = verdicts.get(commit) ?? { ...commitProvenance(repo, policy, commit, opts.attestors), commit, subject: "" };
-      const allowed = v.level === "attested" && v.principal !== undefined && writers.has(v.principal);
-      const who = policy.roles.admin?.length ? "an admin the policy at base names" : "a signer the policy at base lists";
-      const reason = allowed
-        ? `signed by ${v.principal}, ${who.replace(/^an? /, "")}`
-        : v.level === "attested"
-          ? `signed by ${v.principal}, who is not ${who}`
-          : `${paths.join(", ")} is protected and needs a signature by ${who}: ${v.reason}`;
-      report.protectedWrites.push({ commit, paths, level: v.level, ...(v.principal ? { principal: v.principal } : {}), allowed, reason });
-      if (!allowed) report.failures.push(`${commit.slice(0, 8)} changes ${paths.join(", ")}: ${reason}`);
+    for (const [commit, paths] of touching) judge(commit, paths);
+  }
+
+  // The write scope in the declaration at base (#3079): a commit that changes writeScope or agents.
+  const scoped = scopedDeclarationAt(repo, opts.cwd ?? repo, base.commit);
+  if (scoped) {
+    const files = DECLARATION_FILES.map((name) => posix.join(scoped.dir, name));
+    const changed = changedBlocks(scopeState(repo, mergeBase, scoped.dir), scopeState(repo, head, scoped.dir));
+    report.declaration = { path: files.find((f) => fileAt(repo, base.commit!, f) !== undefined) ?? files[0], blocks: scoped.blocks, changed };
+    if (changed.length > 0) {
+      let accounted = false;
+      for (const [commit, paths] of commitsTouching(repo, `${base.commit}..${head}`, files)) {
+        const after = scopeState(repo, commit, scoped.dir);
+        // A merge changes a block only when it differs from every parent.
+        const per = (parentList.get(commit) ?? []).map((p) => new Set(changedBlocks(scopeState(repo, p, scoped.dir), after)));
+        const blocks = SCOPE_BLOCKS.filter((b) => per.length > 0 && per.every((s) => s.has(b)));
+        if (blocks.length === 0) continue;
+        accounted = true;
+        judge(commit, paths, blocks);
+      }
+      if (!accounted) {
+        report.failures.push(`${changed.join(" and ")} in ${report.declaration.path} differ from base, and no commit in the change accounts for it`);
+      }
     }
   }