@intentius/chant 0.101.0 → 0.102.0

package/src/op/runtimes/local.test.ts

@@ -81,6 +81,20 @@ describe("the local op runtime", () => {
     expect(status.records?.map((r) => r.fn)).toEqual(["ok"]);
   });
 
+  test("an activity reads --env and the run id the ledger records (#2522)", async () => {
+    const { currentOpRun } = await import("../run-context");
+    let seen: ReturnType<typeof currentOpRun>;
+    loadActivitiesMock.mockResolvedValue(new Map([["ok", vi.fn(async () => { seen = currentOpRun(); })]]));
+    const runtime = createLocalOpRuntime();
+
+    const handle = await runtime.start(op("hello", [{ kind: "activity", fn: "ok", args: {} }]), { env: "staging" });
+    const status = await handle.result();
+
+    expect(seen?.env).toBe("staging");
+    expect(seen?.runId).toBe(handle.runId);
+    expect(status.result?.record?.id).toBe(handle.runId);
+  });
+
   test("the project's configured lexicons decide which appliers load", async () => {
     loadActivitiesMock.mockResolvedValue(new Map([["ok", vi.fn(async () => ({}))]]));
     const runtime = createLocalOpRuntime();

package/src/op/runtimes/local.ts

@@ -152,6 +152,8 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
             startOpts.signal,
             {
               runId,
+              // #2522: `--env` reaches the activities through the run context.
+              ...(startOpts.env !== undefined ? { env: startOpts.env } : {}),
               // The run's outcome is a durable fact (#2118): the executor
               // appends it here, at the one seam every local run passes
               // through, rather than in the CLI handler above it.

package/src/op/steward-beside.ts

@@ -118,6 +118,8 @@ export function inProcessBesideLauncher(
       try {
         const result = await runOpLocally(start.op, activities, profiles, controller.signal, {
           steward: start.steward,
+          // #2522: the same `--env` the spawned launcher passes on the command line.
+          ...(start.env ? { env: start.env } : {}),
           ledger: { cwd: start.cwd },
           work: { holder: start.holder },
         });

package/src/op/types.ts

@@ -91,8 +91,12 @@ export interface OpWorkLease {
   ttl?: string;
   /**
    * How the release records a run that ended `ok`: a reference to a step
-   * output holding a short string (`done`, `not_done`, ...). Default `done`;
-   * a failed run releases `not_done` and a gated one `gated`.
+   * output holding one of the closed list of lease outcomes
+   * (`WORK_LEASE_OUTCOMES` in `../lifecycle/work-lease.ts`, #3147: `done`,
+   * `not_done`, `abandoned`, `gated`, `waiting`, `dropped`, `redraft`,
+   * `ask`). Default `done`; a failed run releases `not_done`, a gated one
+   * `gated` and one waiting on a decision point `waiting`. A word outside
+   * the list is released `not_done`, with a note naming it.
    */
   outcome?: StepOutputRef;
 }
@@ -178,7 +182,8 @@ export interface ActivityStep {
    *
    * `from` is a dot-path into the return value (e.g. `"drifted"` for
    * `{ drifted: boolean }`); when omitted, the whole return value is
-   * recorded.
+   * recorded. An attribute whose path the result does not hold (an optional
+   * field left out) is not recorded, rather than recorded as `undefined`.
    */
   outcomeAttribute?: OutcomeAttribute | OutcomeAttribute[];
 }

package/src/op/work-lease-run.test.ts

@@ -342,4 +342,51 @@ describe("an Op that changes the checkout", () => {
       expect(git(["status", "--porcelain"], dir).stdout).toBe(" M app/index.ts\n");
     });
   });
+
+  test("a run that ends not_done keeps its attempt at refs/chant/kept/<item>/<token>, committed and uncommitted work, and the branch goes back (#3147)", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const head = git(["rev-parse", "HEAD"], dir).stdout.trim();
+      const activities = new Map<string, ActivityFn>([
+        [
+          "build",
+          async (args) => {
+            const worktree = String(args.worktree);
+            writeFileSync(join(worktree, "app", "feature.ts"), "export const feature = true;\n");
+            expect(git(["add", "-A"], worktree).status).toBe(0);
+            expect(git(["commit", "-q", "-m", "half a build"], worktree).status).toBe(0);
+            writeFileSync(join(worktree, "app", "notes.md"), "left uncommitted\n");
+            throw new Error("the check fails");
+          },
+        ],
+      ]);
+      const result = await run(dispatchOp({ workLease: { item: "W-8" }, changesCheckout: true }, [step("build", { worktree: workLeaseOutput("worktree") })]), activities, dir);
+      expect(result.status).toBe("fail");
+      const token = result.workLease!.token!;
+      const kept = `refs/chant/kept/W-8/${token}`;
+      expect(result.workLease).toMatchObject({ item: "W-8", released: true, outcome: "not_done", kept });
+      // Both the commit and the uncommitted file are in the kept attempt; the branch is where the run started.
+      expect(git(["show", `${kept}:app/feature.ts`], dir).stdout).toBe("export const feature = true;\n");
+      expect(git(["show", `${kept}:app/notes.md`], dir).stdout).toBe("left uncommitted\n");
+      expect(git(["rev-parse", "chant/work/W-8"], dir).stdout.trim()).toBe(head);
+      expect(git(["rev-parse", "HEAD"], dir).stdout.trim()).toBe(head);
+    });
+  });
+
+  test("a run whose step names a lease outcome releases it, and keeps nothing when it changed nothing; a word outside the list is not_done (#3147)", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      let word = "dropped";
+      const activities = new Map<string, ActivityFn>([["record", async () => ({ outcome: word })]]);
+      const op = () => dispatchOp({ workLease: { item: "W-9", outcome: stepOutput("record", "outcome") }, changesCheckout: true }, [step("record", {}, { id: "record" })]);
+      const dropped = await run(op(), activities, dir);
+      expect(dropped.workLease).toMatchObject({ released: true, outcome: "dropped", kept: null });
+      word = "skipped";
+      const other = await run(op(), activities, dir);
+      expect(other.workLease).toMatchObject({ released: true, outcome: "not_done", kept: null });
+      const last = (await readLeaseHistory("W-9", { cwd: dir })).records.at(-1);
+      expect(last).toMatchObject({ event: "release", outcome: "not_done" });
+      expect(last?.note).toMatch(/"skipped" is not a work lease outcome/);
+    });
+  });
 });

package/src/op/work-lease-run.ts

@@ -24,9 +24,11 @@
  *   the lease is still this run's, with the same token. Refused, the run is
  *   recorded as failed with `lease-lost`, never as done.
  * - Release. When the run ends, the lease is given back with the run's
- *   outcome (`done`, `not_done`, `gated`, or the Op's own `outcome`), which
- *   lands on `_leases/<id>.jsonl`. A lost lease is not released: it isn't
- *   this run's to give back.
+ *   outcome (`done`, `not_done`, `gated`, `waiting`, or the Op's own
+ *   `outcome`), which lands on `_leases/<id>.jsonl`. Outcomes are a closed
+ *   list (`WORK_LEASE_OUTCOMES`, #3147): an Op's own outcome outside it is
+ *   released `not_done`, with a note naming it. A lost lease is not
+ *   released: it isn't this run's to give back.
  *
  * Steps read the lease through {@link workLeaseOutput}: its item, holder,
  * token and expiry, and for an Op that changes the checkout, the worktree and
@@ -42,6 +44,13 @@
  * worktree is removed when the run ends and the branch keeps whatever the
  * steps committed, for the runner to deliver. The checkout a coding agent is
  * editing, its index and its uncommitted files, are never touched.
+ *
+ * A run that ends `not_done` keeps its attempt aside (#3147): whatever the
+ * steps committed on the branch since the run started, and anything they
+ * left uncommitted in the worktree, is committed to
+ * `refs/chant/kept/[<member>/]<item>/<token>`, and the branch goes back to
+ * where the run started. The next attempt starts clean, and the earlier one
+ * stays readable by its lease token (`chant workspace work history`).
  */
 
 import { existsSync, rmSync } from "node:fs";
@@ -50,6 +59,8 @@ import { getRuntime } from "../runtime-adapter";
 import {
   claimWorkLease,
   DEFAULT_WORK_LEASE_TTL_MS,
+  isWorkLeaseOutcome,
+  keptAttemptRef,
   releaseWorkLease,
   renewWorkLease,
   workLeaseRef,
@@ -97,8 +108,10 @@ export interface WorkLeaseRunResult {
   branch: string | null;
   /** Whether the lease was given back. False when it was lost, or never claimed. */
   released: boolean;
-  /** The outcome the release recorded, or null when there was no release. */
+  /** The outcome the release recorded, one of `WORK_LEASE_OUTCOMES`, or null when there was no release. */
   outcome: string | null;
+  /** For an Op that changes the checkout and ended `not_done`: the ref that keeps the attempt's work, or null when there was nothing to keep. */
+  kept: string | null;
   /** Why the lease was lost, or null when it wasn't. */
   lost: string | null;
   /** Why nothing was claimed, or null when something was. */
@@ -159,6 +172,8 @@ export class RunWorkLease {
   attempted = false;
   lease: WorkLeaseOutput | undefined;
   refusal: string | undefined;
+  /** For an Op that changes the checkout: the branch's commit when the run started, and the members its branch is scoped by. */
+  private start: { base: string; members: readonly string[] } | undefined;
   lost: string | undefined;
 
   private readonly spec: NonNullable<OpConfig["workLease"]>;
@@ -277,6 +292,8 @@ export class RunWorkLease {
       ? await git(["worktree", "add", "--quiet", worktree, branch], cwd)
       : await git(["worktree", "add", "--quiet", "-b", branch, worktree, "HEAD"], cwd);
     if (!add.ok) throw new Error(`Op "${this.config.name}": could not make the worktree for ${id} on ${branch}: ${add.stderr}`);
+    const base = await git(["rev-parse", "HEAD"], worktree);
+    if (base.ok) this.start = { base: base.stdout, members };
     return { worktree, branch };
   }
 
@@ -365,28 +382,73 @@ export class RunWorkLease {
       branch: lease?.branch ?? null,
       released: false,
       outcome: null,
+      kept: null,
       lost: this.lost ?? null,
       refusal: this.refusal ?? null,
     };
     if (!lease) return base;
+    let outcome = status === "ok" ? "done" : status === "gated" || status === "waiting" ? status : "not_done";
+    let note = `op ${this.config.name}`;
+    if (status === "ok" && this.spec.outcome && isStepOutputRef(this.spec.outcome)) {
+      const declared = resolvePath(resultsById.get(this.spec.outcome.step), this.spec.outcome.path);
+      if (typeof declared === "string" && declared.trim() !== "") {
+        const word = declared.trim();
+        if (isWorkLeaseOutcome(word)) outcome = word;
+        else {
+          outcome = "not_done";
+          note = `op ${this.config.name}: its outcome ${JSON.stringify(word.slice(0, 80))} is not a work lease outcome`;
+        }
+      }
+    }
+    let kept: string | null = null;
+    if (lease.worktree && this.lost === undefined && outcome === "not_done") {
+      kept = await this.keepAttempt(lease).catch(() => null);
+    }
     if (lease.worktree) {
       await git(["worktree", "remove", "--force", lease.worktree], this.opts.cwd).catch(() => undefined);
       rmSync(lease.worktree, { recursive: true, force: true });
       await git(["worktree", "prune"], this.opts.cwd).catch(() => undefined);
     }
     if (this.lost !== undefined) return base;
-    let outcome = status === "ok" ? "done" : status === "gated" || status === "waiting" ? status : "not_done";
-    if (status === "ok" && this.spec.outcome && isStepOutputRef(this.spec.outcome)) {
-      const declared = resolvePath(resultsById.get(this.spec.outcome.step), this.spec.outcome.path);
-      if (typeof declared === "string" && declared.trim() !== "") outcome = declared.trim();
-    }
     const released = await releaseWorkLease(lease.item, this.holder, {
       cwd: this.ledgerCwd,
       token: lease.token,
       outcome,
-      note: `op ${this.config.name}`,
+      note,
     }).catch(() => undefined);
-    return { ...base, released: released?.ok === true, outcome: released?.ok ? outcome : null };
+    return { ...base, kept, released: released?.ok === true, outcome: released?.ok ? outcome : null };
+  }
+
+  /**
+   * Keep a `not_done` attempt aside (#3147): commit what the steps left in
+   * the worktree, committed or not, at `refs/chant/kept/.../<item>/<token>`,
+   * and move the branch back to where the run started. Returns the ref, or
+   * null when the attempt changed nothing.
+   */
+  private async keepAttempt(lease: WorkLeaseOutput): Promise<string | null> {
+    const dir = lease.worktree;
+    const start = this.start;
+    if (!dir || !start) return null;
+    const head = await git(["rev-parse", "HEAD"], dir);
+    if (!head.ok) return null;
+    if (!(await git(["add", "-A"], dir)).ok) return null;
+    const tree = await git(["write-tree"], dir);
+    const headTree = await git(["rev-parse", `${head.stdout}^{tree}`], dir);
+    if (!tree.ok || !headTree.ok) return null;
+    let commit = head.stdout;
+    if (tree.stdout !== headTree.stdout) {
+      // An identity only when git has none, so a configured one is kept.
+      const ident = (await git(["var", "GIT_COMMITTER_IDENT"], dir)).ok && (await git(["var", "GIT_AUTHOR_IDENT"], dir)).ok;
+      const who = ident ? [] : ["-c", "user.name=chant", "-c", "user.email=chant@localhost"];
+      const made = await git([...who, "commit-tree", tree.stdout, "-p", head.stdout, "-m", `${lease.item}: not done, kept (lease ${lease.token})`], dir);
+      if (!made.ok) return null;
+      commit = made.stdout;
+    }
+    if (commit === start.base) return null;
+    const ref = keptAttemptRef(lease.item, lease.token, start.members);
+    if (!(await git(["update-ref", ref, commit], dir)).ok) return null;
+    await git(["reset", "-q", "--hard", start.base], dir);
+    return ref;
   }
 }
 

package/src/provenance.ts

@@ -177,6 +177,41 @@ export function originOfPath(
   return best === undefined ? undefined : paths[best];
 }
 
+const INTERPOLATION_FIELDS = Symbol.for("chant.interpolationFields");
+
+/**
+ * For an entity a tagged template built: which of its `props` paths each
+ * interpolation fed, by interpolation index (chant #3212). Element `i` lists
+ * the paths the `i`-th `${...}` landed in, in {@link EntityProvenance.paths}'
+ * grammar (dotted names, no array segments). An interpolation that fed no
+ * field the author typed, such as a reference to another entity, lists none.
+ *
+ * Only the tag can say this. It is the tag that parsed the text, so a
+ * `${props.ttlDays}` inside `TTL ts + INTERVAL ${props.ttlDays} DAY` is known
+ * to have fed `ttl` only there. When a composite factory interpreted at fold
+ * time writes the template, `discovery/fold-import.ts` joins these paths with
+ * the factory parameters each interpolation reads, which is what lets drift on
+ * such a field be reported against the parameter. A tag that never calls this
+ * leaves its fields `unknown`, the honest answer, rather than claiming either.
+ *
+ * Stored like provenance itself: non-enumerable and symbol-keyed, so no
+ * serializer, spread or comparison of the output ever sees it.
+ */
+export function setInterpolationFields(entity: object, fields: ReadonlyArray<readonly string[]>): void {
+  if (!Object.isExtensible(entity)) return;
+  Object.defineProperty(entity, INTERPOLATION_FIELDS, {
+    value: Object.freeze(fields.map((paths) => Object.freeze([...paths]))),
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+}
+
+/** What {@link setInterpolationFields} recorded on an entity, if anything. */
+export function getInterpolationFields(entity: object): ReadonlyArray<readonly string[]> | undefined {
+  return (entity as Record<symbol, unknown>)[INTERPOLATION_FIELDS] as ReadonlyArray<readonly string[]> | undefined;
+}
+
 /** One-line rendering of an origin, for diff output. */
 export function describePathOrigin(origin: PathOrigin): string {
   switch (origin.kind) {

package/src/workspace/__fixtures__/studio-template-84c8b21.json

@@ -2,7 +2,7 @@
  "$comment": "The studio kit's app template, arugula-salad/studio 84c8b21 template/, which is chud's template at jhgaylor/chud 43afcf1 with the chud CLI steps taken out of its prose and delivery/package.json. The fixture for chant workspace upgrade's chud-lexicon-exit migration (INTENTIUS/chant#2737). Data only: nothing here is imported or run by chant's tests, and delivery/ names @intentius/chud-runtime, which chant never installs.",
  "source": "https://github.com/arugula-salad/studio/tree/84c8b21/template",
  "files": {
-  ".github/workflows/ci.yml": "name: ci\n\non:\n  push:\n    branches:\n      - main\n  pull_request: {}\n\npermissions:\n  contents: read\n\nconcurrency:\n  group: ci-${{ github.ref }}\n  cancel-in-progress: '${{ github.event_name == ''pull_request'' }}'\n\njobs:\n  ci:\n    runs-on: ubuntu-latest\n    timeout-minutes: 20\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n      - name: Setup Node.js\n        uses: actions/setup-node@v4\n        with:\n          node-version: '22.x'\n          cache: npm\n          cache-dependency-path: delivery/package-lock.json\n      - name: Read access to @intentius/chud-runtime\n        env:\n          CHUD_RUNTIME_TOKEN: '${{ secrets.CHUD_RUNTIME_TOKEN }}'\n          CHUD_RUNTIME_DEPLOY_KEY: '${{ secrets.CHUD_RUNTIME_DEPLOY_KEY }}'\n        run: |\n          if [ -n \"$CHUD_RUNTIME_TOKEN\" ]; then\n            git config --global url.\"https://x-access-token:${CHUD_RUNTIME_TOKEN}@github.com/\".insteadOf ssh://git@github.com/\n            git config --global --add url.\"https://x-access-token:${CHUD_RUNTIME_TOKEN}@github.com/\".insteadOf git@github.com:\n          elif [ -n \"$CHUD_RUNTIME_DEPLOY_KEY\" ]; then\n            mkdir -p ~/.ssh && chmod 700 ~/.ssh\n            printf '%s\\n' \"$CHUD_RUNTIME_DEPLOY_KEY\" > ~/.ssh/id_ed25519 && chmod 600 ~/.ssh/id_ed25519\n            echo \"github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl\" >> ~/.ssh/known_hosts\n          else\n            echo \"neither CHUD_RUNTIME_TOKEN nor CHUD_RUNTIME_DEPLOY_KEY is set: a private @intentius/chud-runtime will not install\"\n          fi\n      - name: Install\n        run: npm ci\n        working-directory: delivery\n      - name: Workflow YAML is built from ci/ci.ts\n        run: npm run ci:check\n        working-directory: delivery\n      - name: chant workspace check\n        run: npx chant workspace check\n        working-directory: delivery\n      - name: chant build\n        run: npx chant build -o \"$RUNNER_TEMP/chant-build.out\"\n        working-directory: delivery\n      - name: chant lint\n        run: npx chant lint\n        working-directory: delivery\n      - name: App tests and approved contract checks\n        run: npm run check\n        working-directory: delivery\n",
+  ".github/workflows/ci.yml": "name: ci\n\non:\n  push:\n    branches:\n      - main\n  pull_request: {}\n\npermissions:\n  contents: read\n\nconcurrency:\n  group: ci-${{ github.ref }}\n  cancel-in-progress: '${{ github.event_name == ''pull_request'' }}'\n\njobs:\n  ci:\n    runs-on: ubuntu-latest\n    timeout-minutes: 20\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v7\n      - name: Setup Node.js\n        uses: actions/setup-node@v7\n        with:\n          node-version: '22.x'\n          cache: npm\n          cache-dependency-path: delivery/package-lock.json\n      - name: Read access to @intentius/chud-runtime\n        env:\n          CHUD_RUNTIME_TOKEN: '${{ secrets.CHUD_RUNTIME_TOKEN }}'\n          CHUD_RUNTIME_DEPLOY_KEY: '${{ secrets.CHUD_RUNTIME_DEPLOY_KEY }}'\n        run: |\n          if [ -n \"$CHUD_RUNTIME_TOKEN\" ]; then\n            git config --global url.\"https://x-access-token:${CHUD_RUNTIME_TOKEN}@github.com/\".insteadOf ssh://git@github.com/\n            git config --global --add url.\"https://x-access-token:${CHUD_RUNTIME_TOKEN}@github.com/\".insteadOf git@github.com:\n          elif [ -n \"$CHUD_RUNTIME_DEPLOY_KEY\" ]; then\n            mkdir -p ~/.ssh && chmod 700 ~/.ssh\n            printf '%s\\n' \"$CHUD_RUNTIME_DEPLOY_KEY\" > ~/.ssh/id_ed25519 && chmod 600 ~/.ssh/id_ed25519\n            echo \"github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl\" >> ~/.ssh/known_hosts\n          else\n            echo \"neither CHUD_RUNTIME_TOKEN nor CHUD_RUNTIME_DEPLOY_KEY is set: a private @intentius/chud-runtime will not install\"\n          fi\n      - name: Install\n        run: npm ci\n        working-directory: delivery\n      - name: Workflow YAML is built from ci/ci.ts\n        run: npm run ci:check\n        working-directory: delivery\n      - name: chant workspace check\n        run: npx chant workspace check\n        working-directory: delivery\n      - name: chant build\n        run: npx chant build -o \"$RUNNER_TEMP/chant-build.out\"\n        working-directory: delivery\n      - name: chant lint\n        run: npx chant lint\n        working-directory: delivery\n      - name: App tests and approved contract checks\n        run: npm run check\n        working-directory: delivery\n",
   ".gitignore": "node_modules/\n.chud/\n.data/\n.hud/\n# chant build output (the Ops as op.json)\ndist/\n",
   "CLAUDE.md": "# {{chant:name}}: notes for agents\n\nThis repo is a chant workspace made from the studio kit's template\n(`chant init --from <studio>/template`, then the kit's `box/setup-app.mjs`).\nIt holds everything about {{chant:name}}: the app, the contracts it must\nmeet, the decisions made about it, the agents that build it, and the Ops that\nship it. `chant.workspace.json` declares its members, and chant finds\neverything through them.\n\nYou are probably running as hud's agent in the app's page: the app's own\nserver (its `dev` script, `node --watch`) behind hud's proxy. Your working\ndirectory is this one (the workspace root), and your job is to build the app\nin `app/`. See `app/CLAUDE.md`. Decisions and work items are chant records:\nwrite them with `chant workspace records`, and hud shows them.\n\n## Where things are\n\n| Member | Directory | What it holds |\n|---|---|---|\n| app | `app/` | The product. Edited live while its `dev` script runs. |\n| delivery | `delivery/` | The chant project: `chant.config.ts` (this repo's settings as `buildParams`: ports and how to run the app), `ops/` (the release, rollback, upgrade and dispatch Ops), `deploy/` (the app as a chant component and the sites it ships to), `agents/team.ts` (the agents that build the app, as fountain specs), `decisions/` (the decision points and the ship gate's Cedar policy), `ci/ci.ts` (this repo's CI), `.chant/` (the write-scope policy and the contract-sizing lint rules), and `node_modules/`. |\n| design | `design/` | chud's records, written by the design app: `contracts/` (and `contracts/checks/`), `drivers/`, `evidence/`, `sessions/`, `context/`, `proposals/`. Also the design app's overrides and the screen specs in `screens/`. |\n| design-client | `design-client/` | A placeholder for a vendored design client. Nothing here yet. |\n\n`work/` at the root holds the units of work: chant work items\n(`W-NNN-<slug>.md`, `work.kind.mjs` and `work.schema.json` beside them), one\nper agent run or piece of manual work, with chud's fields under `x-chud`.\nchud writes them through `chant workspace records new|amend`; list them with\n`chant workspace records --kind work/work.kind.mjs`.\n\n`decisions/` at the root holds the decision records: chant decision records\n(`decision.kind.mjs` and `decision.schema.json` beside them define the\nformat), the template's `ref-001`, `ref-002` and `chud-001`, and the\n`chud-NNN` records the design app writes. Each cites the issue in\n`chud.decisions.issue` (`delivery/chant.config.ts`) as its source, or\n`chud-001`'s when none is set. List the\ncurrent ones with\n`chant workspace records --kind decisions/decision.kind.mjs --current`.\n\nA decision pins the files it rests on by path and hash: an `evidence` entry\n`{ title, path, sha256, as_of }`, `path` from the workspace root and inside a\nmember (such as `design/screens/home.json`), and `sha256` the hash of the\nfile's bytes, which `chant workspace records pin <path>` prints. What it\ngoverns goes in `constrains` as `member:<name>` or `path:<path>`. `chant\nworkspace records` reports each pin as `pinned`, `drifted` (the file changed\nsince), `missing` or `stale` (a superseding decision pins the file at the\nsame hash, and the file has not changed since). A drifted pin means the file\nmoved away from what was decided: say so, and do not re-pin it yourself. The\ndesign app pins a file by name (`POST /api/decisions` with `{ title, path }`\nin `evidence` hashes it) and re-pins with `PUT /api/decisions/<id>`.\n\nEvidence (`design/evidence/<sha256>.json`) and design sessions\n(`design/sessions/S-NNNN.json`) are chant record kinds too, declared on the\ndesign member in `chant.workspace.json` (`design/evidence/evidence.kind.mjs`,\n`design/sessions/session.kind.mjs`). Read them with\n`chant workspace records --json`, which reads every declared kind. An\nevidence record's id is the sha256 of its bytes; a file whose name is not\nthat hash carries `asset-drift` and is not evidence. A closed session is\nsealed, and an edit to it is `session-seal-mismatch`. Only the design app and\nthe Ops' Check phases write these files, and each write is read back through\nchant before it is committed. Never write or edit one by hand, and never\nrename one.\n\n- Records keep their core fields in YAML front matter (or JSON), validated\n  against the schemas in\n  `delivery/node_modules/@intentius/chud-runtime/schemas/`. Extra fields must\n  start with `x-`.\n- `delivery/node_modules/@intentius/chud-runtime` is the machinery (the design\n  app, the Op steps). It is a versioned dependency: never edit it. Upgrade it\n  with the upgrade Op (`npm run upgrade` in `delivery/`), which stops at a\n  gate for a person.\n- `.chud/`: local state (hud data, staged releases, the local site). Never\n  edit it, and never commit it.\n\nEvery path chud records (a unit's scope, a protected path, a record's `file`)\nis relative to this directory, the git top-level.\n\n## Rules\n\n- Contracts and decisions are written by the design app. Read the ones that\n  touch your work and do not undo them. Never edit `design/contracts/`,\n  `decisions/`, `work/`, `design/evidence/`, `design/drivers/`,\n  `design/context/`, `design/sessions/`, `delivery/decisions/`,\n  `delivery/.chant/`, `delivery/chant.config.ts` or `chant.workspace.json`\n  (or the paths `chud.protectedPaths` in `delivery/chant.config.ts` adds)\n  from the app's page. This is enforced: an agent run's changes there are thrown\n  away, and a release refuses to plan while a commit that changes them lacks\n  the design app's `Chud-Author: design-app` trailer.\n- Never commit, tag or push. Committing, planning and shipping happen in the\n  design app, through the release Op and its gate.\n\n## Why a line is the way it is\n\nThe design app's commits for a unit of work carry trailers that tie the\ncommit to that unit: `Chud-Unit: W-NNN`, `Chud-Contract: C-NNN` (or\n`Chud-Driver: D-NNN` for a split) and one `Chud-Evidence: <sha256>` per\nevidence record the unit cites, beside `Chud-Author: design-app`.\n`decisions/decision.kind.mjs` exports `commitJoins`, which joins a commit\nto its unit from the work item whose `x-chud.result.commit` is the commit\n(chant 0.86's `list` on the hook's context), and from those trailers for the\nunit's other commits, so\n\n```sh\nchant workspace graph --intent app/server.js --json\n```\n\nlists the commits that touched the file (a `path:start-end` region narrows\nit to lines), each joined to the unit that made it (`work/W-NNN-<slug>.md`),\nthe contract it served and the evidence it cited, with the decisions whose\n`constrains` cover the file and what they pin, and the work items whose\nwindow a commit fell in (`worked`). Read it before changing code\na decision governs. The template pins chant 0.86, which has all of this.\nchant marks a commit inside a decision's window `decided-by-window`, and the\nkind adds `plugin:chud:contract-moved` for a unit commit whose contract's\ncriteria differ from those the first unit under that decision served: the\ncontract moved with no decision. Record a decision before you change what a\ncontract asks for.\n",
   "README.md": "# {{chant:name}}\n\nA chant workspace made from the studio kit's template\n([arugula-salad/studio](https://github.com/arugula-salad/studio) `template/`),\nwhich is chant's reference workspace with an app, a delivery project and\nrecords laid onto it. It started as chud's template (jhgaylor/chud 43afcf1)\nand moved into the kit when chud began to retire (arugula-salad/studio#37).\nThe app is built with hud in the page, and releases ship through chant Ops.\n\n```sh\nchant init --from <studio checkout>/template --param name=\"{{chant:name}}\" [--param issue=owner/repo#1] <dir>\nnode <studio checkout>/box/setup-app.mjs <dir>   # free ports, npm install in delivery/, git init, the first commit\ncd <dir>/app && npm run dev                      # the app, restarted on every change (node --watch)\n```\n\nA studio box does both steps in `box/provision-template.sh` and runs the\napp's `dev` script behind hud's proxy. No chud command runs.\n\n[`chant.workspace.json`](chant.workspace.json) declares the members, and\n`chant workspace ls` lists them. The release Op finds everything through them.\n\n| Member | Directory | Kind | What it is |\n|---|---|---|---|\n| app | [`app/`](app) | `other` | the product: a Node HTTP server with SQLite migrations and its own tests |\n| delivery | [`delivery/`](delivery) | `chant` | the chant project, which still runs on chud's runtime package (`@intentius/chud-runtime`) and the chud lexicon until they are split out of chud (INTENTIUS/chant#2713): the release, rollback, upgrade and dispatch Ops, the sites releases ship to, the agents that build the app, the decision points, the write-scope policy and this repo's CI |\n| design-client | [`design-client/`](design-client) | `other`, role `design-app` | a placeholder for a vendored design client (chant's reference workspace, #2524 D18) |\n| design | [`design/`](design) | `other` | the design data: chud's records (contracts, drivers, evidence, sessions, context, proposals), the screen specs, and the design app's overrides |\n\nThe root also holds [`decisions/`](decisions), the decision records. They\nare chant decision records, the format of chant's `docs/design/decisions/`\n(the kind file and schema are beside them): `ref-001` and `ref-002` from\nchant's reference workspace, `chud-001`, and the `chud-NNN` records the design\napp writes as the team decides. Each cites the issue this app's design is\ntracked in (`chud.decisions.issue` in `delivery/chant.config.ts`, the\ntemplate's optional `issue` parameter) as its source, or without one the\nsource of `chud-001`:\n\n```sh\nchant workspace records --kind decisions/decision.kind.mjs --current\n```\n\n[`work/`](work) holds the units of work: every agent run and piece of\nmanual work is a chant work item (`W-NNN-<slug>.md`, chant's work kind with\nchud's fields under `x-chud`), written by chud through `chant workspace\nrecords new` and `records amend`. Both kinds are declared in\n`chant.workspace.json` `records`:\n\n```sh\nchant workspace records --kind work/work.kind.mjs\n```\n\n`.chant/workspace.lock.json`, written by `chant init --from`, records the\ntemplate's lineage: where it came from, at which commit, and the parameters\nit was made with.\n\n## Everyday commands\n\nIn `delivery/`:\n\n```sh\nnpm run release      # chant run release --on chud: check, plan, stop at the ship gate\nchant approve release ship --plan <digest>\nnpm run release      # ship it\nnpm run rollback\nnpm run upgrade      # move to a newer @intentius/chud-runtime, through its gate\nnpm run check        # the app's tests and every approved contract's check (CI runs this)\nnpm run lint         # chant lint agents, with the contract-sizing rules\n```\n\nAt the root:\n\n```sh\nchant workspace check\nchant workspace build\nchant workspace lint\n```\n\n`CLAUDE.md` is the map for agents, and `design/CLAUDE.md` has the rules for\nthe records.\n",

package/src/workspace/agent-cli.ts

@@ -60,6 +60,8 @@ export type AgentDocument =
         members: string[];
         /** Every declared kind in reach: the workspace's own and the member's. */
         records: AgentKindScope[];
+        /** The paths writeScope.agent.protected keeps the session from writing, with the JSON keys each still allows (#3146). */
+        protected: { path: string; except: string[] }[];
       };
       /** The spec, as records --current --json prints it. */
       spec: SpecView;
@@ -77,10 +79,11 @@ export async function agentSession(q: { cwd: string; name: string }): Promise<Ag
       throw new WorkspaceReadError("declaration-missing", "no chant.workspace.json or .jsonc between this directory and the git root, so no agent session is declared");
     }
     const decl = source.declaration;
-    const writer = resolveWriter(decl, source.policy, { agent: q.name });
+    const writer = resolveWriter(decl, source.policy, { agent: q.name }, source.classes);
     const agent = writer.agent!;
     const member = decl.members.find((m) => m.name === agent.member)!;
-    const rules = scopeOf(decl, writer)!.records;
+    const scope = scopeOf(decl, writer)!;
+    const rules = scope.records;
     // The spec query, over every declared kind in the working tree.
     const set = await queryDeclaredRecords(declaredKindFiles(q.cwd), { cwd: q.cwd, current: true });
     const loadedName = new Map(set.kinds.map((k) => [k.declared.path, "error" in k ? null : k.kind.name]));
@@ -94,7 +97,7 @@ export async function agentSession(q: { cwd: string; name: string }): Promise<Ag
       ...head,
       workspace: { name: decl.name, root: source.root ?? ".", scopeFrom: source.from },
       agent: { name: agent.name, member: { name: member.name, dir: member.dir, kind: member.kind }, principals: agent.principals },
-      scope: { members: [member.name], records },
+      scope: { members: [member.name], records, protected: scope.protected.map((p) => ({ path: p.path, except: [...p.except] })) },
       spec: set.spec ?? { kinds: [], records: [] },
       reload: [`chant workspace agent ${agent.name} --json`, "chant workspace records --current --json"],
     };
@@ -126,6 +129,7 @@ export async function runWorkspaceAgent(ctx: CommandContext): Promise<number> {
   const out: string[] = [];
   out.push(`agent     ${doc.agent.name}, bound to member ${doc.agent.member.name} (${doc.agent.member.dir}), scope read from ${doc.workspace.scopeFrom}`);
   for (const r of doc.scope.records) out.push(`records   ${r.name ?? r.kind ?? r.path} (${r.path}): ${r.verbs.length > 0 ? r.verbs.join(", ") : "not writable"}`);
+  for (const p of doc.scope.protected) out.push(`protected ${p.path}${p.except.length > 0 ? ` (except ${p.except.join(", ")})` : ""}`);
   out.push(`spec      ${doc.spec.records.length} current records of ${doc.spec.kinds.length} spec kinds`);
   for (const r of doc.spec.records) out.push(`          ${r.kind}/${r.id ?? "?"} ${r.state ?? ""} ${r.path}`);
   out.push(`reload    ${doc.reload.join("; ")}`);

package/src/workspace/agent.schema.json

@@ -165,6 +165,28 @@
                   }
                 }
               }
+            },
+            "protected": {
+              "type": "array",
+              "description": "Added in contract 1 by #3146. The paths writeScope.agent.protected keeps the session from writing even inside its member, each a glob from the workspace root that also covers everything under a directory it matches, with the top-level keys of a JSON file a write may still change in except. Empty when none is listed. check --changes reports a write to one with write-scope-protected.",
+              "items": {
+                "type": "object",
+                "required": [
+                  "path",
+                  "except"
+                ],
+                "properties": {
+                  "path": {
+                    "type": "string"
+                  },
+                  "except": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
             }
           }
         },