@intentius/chant 0.102.0 → 0.104.0

package/src/op/activities/index.ts

@@ -25,6 +25,8 @@ export type { ReleaseRollbackPlanArgs, ReleaseRollbackPlanResult, ReleaseRollbac
 export type { HttpCheckArgs, HttpFetch } from "./http-check";
 
 export { lifecycleSnapshot, lifecycleDiff } from "./lifecycle";
+export { composeChangeSet, lifecyclePlanChangeSet, readChangeSetPart } from "./change-set";
+export type { ComposeChangeSetArgs, ComposeChangeSetResult, LifecyclePlanChangeSetArgs, ReadChangeSetPartArgs, ChangeSetPartResult } from "./change-set";
 export type { LifecycleSnapshotArgs, LifecycleDiffArgs, LifecycleDiffResult } from "./lifecycle";
 
 export { chantTeardown } from "./teardown";
@@ -181,3 +183,7 @@ export type { ChangeCoverageArgs, ChangeCoverageResult } from "./change-coverage
 // loads the workspace code on first call.
 export { decide } from "./decide";
 export type { DecideArgs, DecideResult } from "./decide";
+
+// The factory reference Op's rules and hooks (#3406, ws-087): `factoryOp` in ../factory.ts declares them.
+export { factoryPick, factoryReady, factoryAsk, factoryBuild, factoryCheck, factoryRecord } from "./factory";
+export type { FactoryAskResult, FactoryBuildResult, FactoryCheckResult, FactoryRecordResult, FactoryPickResult, FactoryLease } from "./factory";

package/src/op/activity-contract.test.ts

@@ -7,7 +7,8 @@
 
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
-import { activity, phase, effect } from "./builders";
+import { activity, decide, phase, effect } from "./builders";
+import { decideContract } from "./activities/activity-contracts";
 import type { OpConfig } from "./types";
 import {
   activityContract,
@@ -118,6 +119,25 @@ describe("validateActivitySteps() — passing Ops", () => {
   });
 });
 
+describe("validateActivitySteps() — a whole-value reference in a record-typed arg (#3299)", () => {
+  const contracts = new Map([["decide", decideContract]]);
+
+  it("accepts decide's `inputs: step.out.json` without throwing", () => {
+    const fetch = activity("fetchInputs", {}, { id: "fetch" });
+    const ask = decide("dispatch-tier", { inputs: fetch.out.json as unknown as Record<string, unknown> });
+    const config = opWith({ phases: [phase("Fetch", [fetch]), phase("Decide", [ask])] });
+    expect(validateActivitySteps(config, contracts)).toEqual([]);
+  });
+
+  it("reports a symbol key in a record-typed arg as a finding instead of throwing", () => {
+    const step = activity("decide", { point: "dispatch-tier", inputs: { [Symbol("odd")]: 1 } });
+    const config = opWith({ phases: [phase("Decide", [step])] });
+    const issues = validateActivitySteps(config, contracts);
+    expect(issues.length).toBeGreaterThan(0);
+    expect(issues[0].message).toContain("args.inputs.Symbol(odd)");
+  });
+});
+
 describe("validateActivitySteps() — the four failure classes from #1288", () => {
   it("flags an unknown profile — e.g. kubectlApply(..., { profile: \"longInfa\" })", () => {
     const step = activity("kubectlApply", { manifest: "dist/k8s.yaml" }, "longInfa" as never);

package/src/op/activity-contract.ts

@@ -150,14 +150,22 @@ function isStepOutputRefValue(value: unknown): boolean {
   return typeof value === "object" && value !== null && (value as Record<symbol, unknown>)[STEP_OUTPUT_REF_BRAND] === true;
 }
 
-/** The value at `path` (a zod issue's `.path`) inside `obj`, or `undefined` if any segment doesn't resolve. */
-function valueAtPath(obj: unknown, path: ReadonlyArray<PropertyKey>): unknown {
+/**
+ * Does any prefix of `path` (a zod issue's `.path`) inside `obj` land on a
+ * step-output reference? A reference stands in for the whole value at its
+ * position, so an issue at or below it describes the placeholder, not the
+ * value it resolves to. "Below" matters for a whole-value reference in a
+ * record-typed arg (`inputs: step.out.json`, #3299): zod walks the
+ * reference's own keys, brand symbol included, and reports issues inside it.
+ */
+function pathCrossesStepOutputRef(obj: unknown, path: ReadonlyArray<PropertyKey>): boolean {
   let current = obj;
   for (const segment of path) {
-    if (current === null || typeof current !== "object") return undefined;
+    if (current === null || typeof current !== "object") return false;
     current = (current as Record<PropertyKey, unknown>)[segment];
+    if (isStepOutputRefValue(current)) return true;
   }
-  return current;
+  return false;
 }
 
 /** Unwrap `ZodOptional`/`ZodNullable`/`ZodDefault` (and similar) down to the schema they wrap. */
@@ -270,16 +278,18 @@ export function validateActivitySteps(
       const parsed = contract.args.safeParse(step.args ?? {});
       if (!parsed.success) {
         for (const issue of parsed.error.issues) {
-          // A step-output reference (#1290) sitting at this path is a
-          // placeholder object at build time, not the value it will
-          // resolve to — so an args-schema type mismatch here is a false
+          // A step-output reference (#1290) sitting at this path, or above
+          // it, is a placeholder object at build time, not the value it
+          // will resolve to — so an args-schema issue there is a false
           // positive; OPS013 (`validateStepOutputRefs`) is what validates
           // a reference, against the *producer's* declared return schema.
           // An unrecognized-key issue's path is the parent object (`[]`
           // for a top-level extra key), which is never itself a reference,
           // so a genuinely misspelled key is still caught either way.
-          if (isStepOutputRefValue(valueAtPath(step.args, issue.path))) continue;
-          const path = issue.path.length > 0 ? issue.path.join(".") : "(args)";
+          if (pathCrossesStepOutputRef(step.args, issue.path)) continue;
+          // String(), not join(): a zod path can hold a symbol key, and
+          // join() throws converting one (#3299).
+          const path = issue.path.length > 0 ? issue.path.map((segment) => String(segment)).join(".") : "(args)";
           issues.push({ opName: config.name, phase: phase.name, fn: step.fn, message: `args.${path}: ${issue.message}` });
         }
       }

package/src/op/builders.ts

@@ -18,6 +18,7 @@ import type { PolicyGateArgs } from "./activities/policy";
 import type { GuardValidateArgs } from "./activities/guard-validate";
 import type { WorkEvidenceArgs } from "./activities/work-evidence";
 import type { DecideArgs } from "./activities/decide";
+import type { ComposeChangeSetArgs, LifecyclePlanChangeSetArgs, ReadChangeSetPartArgs } from "./activities/change-set";
 import { isValidCronExpression, cronSyntaxMessage } from "./cron";
 
 /** An `activity()` result — the plain `ActivityStep` shape plus the `.out` reference sugar (#1290). */
@@ -398,6 +399,28 @@ export const releasePlan = (args: WithStepRefs<ReleasePlanArgs> & StepOpts): Nam
   return activity("releasePlan", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
 };
 
+/**
+ * Join members' change-set parts into one document (#3181). Its `digest` is
+ * what a combined run's gate binds: `gate("approve", { plan:
+ * changeSet.out.digest })`. Defaults to the `fastIdempotent` profile.
+ */
+export const composeChangeSet = (args: WithStepRefs<ComposeChangeSetArgs> & StepOpts): NamedActivityStep => {
+  const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
+  return activity("composeChangeSet", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+
+/** A chant member's change-set part, from `chant lifecycle plan <env> --json` (#3181). Its `part` feeds {@link composeChangeSet}. */
+export const lifecyclePlanChangeSet = (args: WithStepRefs<LifecyclePlanChangeSetArgs> & StepOpts): NamedActivityStep => {
+  const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
+  return activity("lifecyclePlanChangeSet", rest, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+
+/** A member's change-set part from a plan file a chant or warden run wrote (#3181). Its `part` feeds {@link composeChangeSet}. */
+export const readChangeSetPart = (args: WithStepRefs<ReadChangeSetPartArgs> & StepOpts): NamedActivityStep => {
+  const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
+  return activity("readChangeSetPart", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+
 /**
  * Record a release in the release ledger with its plan (#2782, ws-055), once:
  * a retry whose release the ledger already names records nothing. Defaults to

package/src/op/decide-backend.ts

@@ -6,9 +6,13 @@
  * POST <url>/v1/systemone          Authorization: Bearer <key>
  * { "model": "jev-1.13.0", "state": {...}, "questions": { "<name>": { "type": "noul" | "choice" | "score", "instructions": ..., "criteria": ... } } }
  *
- * { "model": "jev-1.13.0", "answers": { "<name>": { "type": "noul", "noul": 0.22 } | { "type": "choice", "choice": ..., "probabilities": {...}, "confidence": ... } | { "type": "score", ... } } }
+ * { "model": "jev-1.13.0", "answers": { "<name>": { "type": "noul", "noul": 0.22, "reason"?: ... } | { "type": "choice", "choice": ..., "probabilities": {...}, "confidence": ..., "reason"?: ... } | { "type": "score", ..., "reason"?: ... } } }
  * ```
  *
+ * `reason` is optional: the model's own explanation of its answer (#3345).
+ * Core keeps it in the answer record beside a proposal, or as `model_reason`
+ * in the escalation entry of an answer below the threshold.
+ *
  * {@link backendAsk} turns a set of backends into core's `ModelAsk`, the
  * model call `askPoint` takes (`../workspace/points.ts`). This file
  * only speaks the wire format: whether an answer is observed, proposed or

package/src/op/decide-read-inputs.ts

@@ -10,10 +10,12 @@
  *
  * Read by id or name here:
  *
- *   record, decision, work-item   a record, by id, from the declared record kinds (`records --json`)
+ *   record, decision, work-item   a record, by id, from the declared record kinds (`records --json`);
+ *                                 a work item also has its size, `criteria`, `files`, `words` and
+ *                                 `fits_<tier>`, for the slice-tier point (`../workspace/work-size.ts`, #3150)
  *   member                        a member, by name (`ls --json`)
  *
- * The other outputs a point may name (finding, region, commit, gate, release,
+ * The other outputs a point may name (finding, region, commit, node, gate, release,
  * environment, component) are passed in `inputs`, as the output printed them.
  * These reads never call a model, and never write. The module loads code
  * under `workspace/`, so the `decide` activity imports it on first call.
@@ -22,6 +24,11 @@
 import { declaredKindFiles, queryDeclaredRecords } from "../workspace/records-cli";
 import { listWorkspace } from "../workspace/ls";
 import { inputOutput } from "../workspace/points";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { bodyText, loadRecordKind } from "../workspace/records";
+import { locateWorkspace } from "../workspace/which-chant";
+import { DEFAULT_TIER_LIMITS, measureWorkItem, sizeFields } from "../workspace/work-size";
 
 /** The outputs {@link readInputs} reads by id or name. */
 export const READABLE_OUTPUTS = ["record", "decision", "work-item", "member"] as const;
@@ -45,19 +52,40 @@ export function fieldOf(value: unknown, path: string): unknown {
 }
 
 async function readRecord(id: string, cwd: string, output: string): Promise<Record<string, unknown>> {
-  const set = await queryDeclaredRecords(declaredKindFiles(cwd), { cwd });
+  const files = declaredKindFiles(cwd);
+  const set = await queryDeclaredRecords(files, { cwd });
   const unread: string[] = [];
-  for (const doc of set.kinds) {
+  for (const [i, doc] of set.kinds.entries()) {
     if ("error" in doc) {
       unread.push(`${doc.declared.path}: ${doc.error.code}`);
       continue;
     }
     const found = doc.records.find((r) => r.id === id);
-    if (found) return found as unknown as Record<string, unknown>;
+    if (found) {
+      const record = found as unknown as Record<string, unknown>;
+      // A work item's size, for the slice-tier point (#3150): criteria, files, words and fits_<tier>.
+      return output === "work-item" ? { ...record, ...(await workItemSizeFields(files[i].file, found.path, found.data, cwd)) } : record;
+    }
   }
   throw new InputReadError(`no declared record kind holds a record with id ${id} (read for ${output})${unread.length ? `; not read: ${unread.join(", ")}` : ""}`);
 }
 
+/** The size fields of a work item of the kind at `kindFile`, measured from its record file. Empty for a kind with no work block. */
+async function workItemSizeFields(kindFile: string, path: string, data: Record<string, unknown> | null, cwd: string): Promise<Record<string, unknown>> {
+  const loaded = await loadRecordKind(kindFile, cwd);
+  const work = loaded.kind.work;
+  if (!work) return {};
+  const located = locateWorkspace(cwd);
+  let body = "";
+  try {
+    body = bodyText(readFileSync(join(located.top ?? located.rootOnDisk, ...path.split("/")), "utf-8"));
+  } catch {
+    // A record that can't be read again is measured from its front matter alone.
+  }
+  const size = measureWorkItem(data, body, work.acceptance?.field ?? "acceptance");
+  return sizeFields(size, work.tier?.limits ?? DEFAULT_TIER_LIMITS);
+}
+
 function readMember(name: string, cwd: string): Record<string, unknown> {
   const doc = listWorkspace({ cwd });
   if ("error" in doc) throw new InputReadError(`the workspace can't be listed: ${doc.error.code}: ${doc.error.message}`);

package/src/op/factory.e2e.test.ts

@@ -0,0 +1,232 @@
+/**
+ * The factory reference Op (#3406, ws-087), run through the local executor
+ * with stub hooks on a small workspace that carries the reference
+ * workspace's decision, work and answer kinds and its points: one item from
+ * pick to done, one retry after a failed build, and one ask the understand
+ * point refuses. The rules themselves are tested in
+ * ../workspace/factory-rules.test.ts.
+ */
+
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import * as coreActivities from "./activities";
+import type { ActivityFn } from "./activity-registry";
+import { ACTIVITY_PROFILES } from "./activity-profiles";
+import { factoryOpConfig } from "./factory";
+import { OpRunFailure, runOpLocally, type OpRunResult } from "./local-executor";
+import { answerPoint } from "../workspace/decide";
+import { workspacePoints } from "../workspace/points-cli";
+import { amendRecord } from "../workspace/records-write";
+import { parseFrontMatter } from "../workspace/records";
+
+const REF = join(import.meta.dirname, "..", "..", "..", "..", "reference-workspace");
+
+const activities = new Map<string, ActivityFn>(Object.entries(coreActivities).filter(([, v]) => typeof v === "function") as [string, ActivityFn][]);
+
+function git(args: string[], cwd: string): string {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+const item = (id: string, fields: Record<string, unknown>, body = "") =>
+  `---\n${JSON.stringify({ schema: 1, id, title: `Item ${id}`, state: "open", implements: [], needs: [], constrains: ["member:app"], evidence: [], opened_on: "2026-10-01", source: { kind: "workspace", member: "app" }, supersedes: [], ...fields }, null, 2)}\n---\n\n# Item ${id}\n${body}`;
+
+/**
+ * The builder stub: writes app/<item>.txt, and fails while .fail-<item> exists in the checkout
+ * the test controls (FACTORY_FAIL_DIR), so a retry can succeed.
+ */
+const BUILDER = `
+const fs = require("node:fs");
+const item = process.env.FACTORY_ITEM;
+if (fs.existsSync(require("node:path").join(process.env.FACTORY_FAIL_DIR, ".fail-" + item))) { console.error("the build broke"); process.exit(1); }
+fs.mkdirSync("app", { recursive: true });
+fs.writeFileSync("app/" + item + ".txt", "built at tier " + process.env.FACTORY_TIER + "\\n");
+`;
+const CHECK = `const fs = require("node:fs"); process.exit(fs.existsSync("app/" + process.env.FACTORY_ITEM + ".txt") ? 0 : 1);`;
+
+function workspace(dir: string): void {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "t@chant.dev"], dir);
+  git(["config", "user.name", "T"], dir);
+  git(["config", "commit.gpgsign", "false"], dir);
+  for (const d of ["decisions", "work", "answers"]) mkdirSync(join(dir, d), { recursive: true });
+  for (const f of ["decisions/decision.kind.mjs", "decisions/decision.schema.json", "decisions/points.json", "work/work.kind.mjs", "work/work.schema.json", "answers/answer.kind.mjs", "answers/answer.schema.json"]) {
+    cpSync(join(REF, f), join(dir, f));
+  }
+  writeFileSync(
+    join(dir, "chant.workspace.json"),
+    JSON.stringify({
+      name: "factory",
+      schema: 1,
+      records: [{ kind: "decisions/decision.kind.mjs" }, { kind: "work/work.kind.mjs" }, { kind: "answers/answer.kind.mjs" }],
+      members: [{ name: "app", dir: "app", kind: "other", because: "the app" }],
+    }),
+  );
+  mkdirSync(join(dir, "app"), { recursive: true });
+  writeFileSync(join(dir, "app", "README.md"), "# app\n");
+  mkdirSync(join(dir, "hooks"), { recursive: true });
+  writeFileSync(join(dir, "hooks", "builder.cjs"), BUILDER);
+  writeFileSync(join(dir, "hooks", "check.cjs"), CHECK);
+  writeFileSync(join(dir, "work", "W-101-the-feature.md"), item("W-101", { acceptance: [{ id: "AC-1", text: "app/W-101.txt exists", verification: "unit" }] }));
+  writeFileSync(join(dir, "work", "W-102-the-retried-one.md"), item("W-102", { acceptance: [{ id: "AC-1", text: "app/W-102.txt exists", verification: "unit" }] }));
+  writeFileSync(join(dir, "work", "W-103-an-ask.md"), item("W-103", { state: "proposed", source: { ask: { said: "Make the page purple.", by: "alice", via: "hud" } } }));
+  git(["add", "-A"], dir);
+  git(["commit", "-q", "-m", "the workspace"], dir);
+}
+
+async function run(dir: string, work?: string, extra: Partial<Parameters<typeof factoryOpConfig>[0]> = {}): Promise<OpRunResult> {
+  const config = factoryOpConfig({ cwd: dir, backends: { systemone: { url: "http://127.0.0.1:9", timeoutMs: 200 } }, builder: `${process.execPath} hooks/builder.cjs`, check: `${process.execPath} hooks/check.cjs`, ...extra });
+  const prev = process.env.FACTORY_FAIL_DIR;
+  process.env.FACTORY_FAIL_DIR = dir;
+  try {
+    return await runOpLocally(config, activities, ACTIVITY_PROFILES, undefined, { cwd: dir, ledger: { cwd: dir }, ...(work ? { work: { item: work } } : {}) });
+  } catch (err) {
+    if (err instanceof OpRunFailure) return err.result;
+    throw err;
+  } finally {
+    if (prev === undefined) delete process.env.FACTORY_FAIL_DIR;
+    else process.env.FACTORY_FAIL_DIR = prev;
+  }
+}
+
+const onBranch = (dir: string, id: string, path: string) => {
+  const fm = parseFrontMatter(git(["show", `chant/work/${id}:${path}`], dir));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+};
+
+describe("the factory reference Op (#3406)", () => {
+  test("builds an item from pick to done, retries a failed build only on a person's request, and drops an ask understand refuses", async () => {
+    await withTestDir(async (dir) => {
+      workspace(dir);
+      writeFileSync(join(dir, ".fail-W-102"), "");
+
+      // W-101: picked first, tier from slice-tier's table, built, checked, recorded done on its branch.
+      const first = await run(dir);
+      expect(first.workLease).toMatchObject({ item: "W-101", released: true, outcome: "done" });
+      const w101 = onBranch(dir, "W-101", "work/W-101-the-feature.md");
+      expect(w101).toMatchObject({ state: "done", result: { lease: first.workLease!.token } });
+      expect(git(["show", "chant/work/W-101:app/W-101.txt"], dir)).toBe("built at tier small");
+      const msg = git(["log", "-1", "--format=%B", "chant/work/W-101"], dir);
+      expect(msg).toContain("Chant-Record: work:W-101");
+      expect(msg).toContain(`Chant-Lease: ${first.workLease!.token}`);
+
+      // W-101 waits to be applied, so W-102 is next; its builder fails, and the attempt is kept.
+      const second = await run(dir);
+      expect(second.workLease).toMatchObject({ item: "W-102", outcome: "not_done" });
+      const failed = second.workLease!.token!;
+
+      // Neither W-101 (built, not applied) nor W-102 (failed, no retry) is picked; W-103 is an ask,
+      // and understand escalates it to people, so the run waits on the question.
+      const third = await run(dir);
+      expect(third.workLease).toMatchObject({ item: "W-103", outcome: "waiting" });
+
+      // A person asks for W-102 again, naming the failed build; the next run builds it.
+      const retry = await amendRecord({ kind: join(dir, "work", "work.kind.mjs"), id: "W-102", fields: JSON.stringify({ retry: { after: failed, by: "alice", at: "2026-10-03T10:00:00Z" } }), cwd: dir });
+      expect("error" in retry).toBe(false);
+      git(["add", "-A"], dir);
+      git(["commit", "-q", "-m", "retry W-102"], dir);
+      unlinkSync(join(dir, ".fail-W-102"));
+      const fourth = await run(dir, "W-102");
+      expect(fourth.workLease).toMatchObject({ item: "W-102", outcome: "done" });
+
+      // The understand question about W-103 is answered refuse; the next run drops it on its branch.
+      const points = await workspacePoints({ cwd: dir });
+      if ("error" in points) throw new Error(points.error.message);
+      const open = points.questions.find((q) => q.point === "understand" && q.open);
+      expect(open).toBeDefined();
+      const answered = await answerPoint({ cwd: dir, id: open!.id, answer: "refuse", by: ["alice"] });
+      expect("error" in answered).toBe(false);
+      git(["add", "-A"], dir);
+      git(["commit", "-q", "-m", "refuse W-103"], dir);
+      const fifth = await run(dir, "W-103");
+      expect(fifth.workLease).toMatchObject({ item: "W-103", outcome: "dropped" });
+      expect(onBranch(dir, "W-103", "work/W-103-an-ask.md")).toMatchObject({ state: "dropped" });
+      expect(existsSync(join(dir, "app", "W-103.txt"))).toBe(false);
+      expect(readFileSync(join(dir, "work", "W-101-the-feature.md"), "utf-8")).toContain('"state": "open"');
+    });
+  }, 120_000);
+});
+
+describe("the factory Op's seams for an orchestrator (studio#382)", () => {
+  test("prepare runs before Pick, an uncommitted item is carried into the worktree, the reports pass through, the check ticks each criterion by its own result, and after sees the outcome", async () => {
+    await withTestDir(async (dir) => {
+      workspace(dir);
+      // A builder that reports a run and a check that reports per criterion.
+      writeFileSync(join(dir, "hooks", "builder2.cjs"), `${BUILDER}\nconsole.log(JSON.stringify({ ok: true, run: { id: "run-7" }, agent: "builder-small", chantAgent: "factory", records: ["contract:C-1"] }));\n`);
+      writeFileSync(join(dir, "hooks", "check2.cjs"), `console.log(JSON.stringify({ criteria: { "AC-1": "pass", "AC-2": "fail" }, built: JSON.parse(process.env.FACTORY_BUILD).agent }));`);
+      writeFileSync(join(dir, "hooks", "after.cjs"), `require("node:fs").writeFileSync(require("node:path").join(process.env.FACTORY_FAIL_DIR, "after.json"), JSON.stringify({ outcome: process.env.FACTORY_OUTCOME, commit: process.env.FACTORY_COMMIT, reason: process.env.FACTORY_REASON, check: JSON.parse(process.env.FACTORY_CHECK) }));`);
+      // The prepare hook writes W-110 in the checkout and leaves it uncommitted; the others are taken out of the way.
+      writeFileSync(
+        join(dir, "hooks", "prepare.cjs"),
+        `require("node:fs").writeFileSync("work/W-110-prepared.md", ${JSON.stringify(item("W-110", { acceptance: [{ id: "AC-1", text: "one", verification: "unit" }, { id: "AC-2", text: "two", verification: "unit" }] }))});`,
+      );
+      for (const id of ["W-101", "W-102"]) writeFileSync(join(dir, ".fail-" + id), "");
+      git(["add", "-A"], dir);
+      git(["commit", "-q", "-m", "hooks"], dir);
+      const result = await run(dir, "W-110", {
+        kind: "./work/work.kind.mjs",
+        prepare: `${process.execPath} hooks/prepare.cjs`,
+        builder: `${process.execPath} hooks/builder2.cjs`,
+        check: `${process.execPath} hooks/check2.cjs`,
+        after: `${process.execPath} hooks/after.cjs`,
+      });
+      // AC-2 failed its own check, so the item is not done, though the check exited 0.
+      expect(result.workLease).toMatchObject({ item: "W-110", outcome: "not_done" });
+      const after = JSON.parse(readFileSync(join(dir, "after.json"), "utf-8"));
+      expect(after).toMatchObject({ outcome: "not_done", reason: "criteria AC-2 have no passing evidence", check: { built: "builder-small" } });
+      // The attempt was committed with why, and the run kept that commit.
+      expect(after.commit).toMatch(/^[0-9a-f]{40}$/);
+      // The kept attempt holds the carried item with AC-1 ticked and AC-2 failed.
+      const kept = git(["for-each-ref", "--format=%(refname)", "refs/chant/kept/"], dir).split("\n").find((r) => r.includes("W-110"))!;
+      expect(git(["rev-parse", kept], dir)).toBe(after.commit);
+      expect(git(["log", "-1", "--format=%B", kept], dir)).toMatch(/^W-110: not done\n\nNot done: criteria AC-2 have no passing evidence\n\nChant-Agent: factory\nChant-Lease: /);
+      const fm = parseFrontMatter(git(["show", `${kept}:work/W-110-prepared.md`], dir));
+      if (!fm.ok) throw new Error(fm.message);
+      const results = Object.fromEntries((fm.value.evidence as { criterion: string; result: string }[]).map((e) => [e.criterion, e.result]));
+      expect(results).toEqual({ "AC-1": "pass", "AC-2": "fail" });
+
+      // With both criteria passing, the item is done and its commit carries the builder's run.
+      writeFileSync(join(dir, "hooks", "check2.cjs"), `console.log(JSON.stringify({ criteria: { "AC-1": "pass", "AC-2": "pass" } }));`);
+      git(["add", "-A"], dir);
+      git(["commit", "-q", "-m", "a passing check"], dir);
+      const { readLeaseHistory } = await import("../lifecycle/work-lease");
+      const failed = (await readLeaseHistory("W-110", { cwd: dir })).records.filter((r) => r.event === "claim").at(-1) as { token: string };
+      const amended = await amendRecord({ kind: join(dir, "work", "work.kind.mjs"), id: "W-110", fields: JSON.stringify({ retry: { after: failed.token, by: "alice" } }), cwd: dir });
+      expect("error" in amended).toBe(false);
+      const done = await run(dir, "W-110", { builder: `${process.execPath} hooks/builder2.cjs`, check: `${process.execPath} hooks/check2.cjs`, after: `${process.execPath} hooks/after.cjs` });
+      expect(done.workLease).toMatchObject({ item: "W-110", outcome: "done" });
+      const body = git(["log", "-1", "--format=%B", "chant/work/W-110"], dir);
+      expect(body).toContain("Chant-Run: run-7");
+      expect(body).toContain("Chant-Agent: factory");
+      expect(body).toContain("Chant-Record: work:W-110\nChant-Record: contract:C-1");
+      expect(JSON.parse(readFileSync(join(dir, "after.json"), "utf-8")).outcome).toBe("done");
+    });
+  }, 120_000);
+});
+
+describe("an ask's item is the builder's only for its plan (studio#382)", () => {
+  test("a builder that changes an open ask beyond its acceptance criteria has the item put back, and the build is not done", async () => {
+    await withTestDir(async (dir) => {
+      workspace(dir);
+      for (const id of ["W-101", "W-102"]) writeFileSync(join(dir, ".fail-" + id), "");
+      writeFileSync(join(dir, "work", "W-120-an-open-ask.md"), item("W-120", { source: { ask: { said: "Add a page.", by: "alice", via: "hud" } } }));
+      writeFileSync(
+        join(dir, "hooks", "rewrite.cjs"),
+        `const fs = require("node:fs"); const f = "work/W-120-an-open-ask.md"; fs.writeFileSync(f, fs.readFileSync(f, "utf8").replace('"title": "Item W-120"', '"title": "Renamed"')); fs.writeFileSync("app/W-120.txt", "the page\\n");`,
+      );
+      git(["add", "-A"], dir);
+      git(["commit", "-q", "-m", "an open ask"], dir);
+      const result = await run(dir, "W-120", { builder: `${process.execPath} hooks/rewrite.cjs` });
+      expect(result.workLease).toMatchObject({ item: "W-120", outcome: "not_done" });
+      const kept = git(["for-each-ref", "--format=%(refname)", "refs/chant/kept/W-120/"], dir);
+      expect(git(["show", `${kept}:work/W-120-an-open-ask.md`], dir)).toContain('"title": "Item W-120"');
+      expect(git(["log", "-1", "--format=%B", kept], dir)).toContain("the guard put back what the builder changed out of scope: work/W-120-an-open-ask.md (it changed title, and only acceptance is the builder's)");
+    });
+  }, 120_000);
+});
+

package/src/op/factory.ts

@@ -0,0 +1,118 @@
+/**
+ * The factory reference Op (#3406, ws-087): the factory's rules declared in
+ * core, and an orchestrator's execution plugged in through hooks.
+ *
+ * ```ts
+ * // ops/factory.op.ts
+ * export default factoryOp({
+ *   builder: "node box/ops/factory/builder.mjs",
+ * });
+ * ```
+ *
+ * One run is one build of one work item, under that item's lease, in a
+ * worktree on `chant/work/<item>`:
+ *
+ *   Pick        factoryPick: the buildable items, in order; the lease claims the first nobody holds
+ *   Ask         factoryAsk: the tier (the item's own, or the slice-tier point) and, for an ask, the
+ *               understand point; an open question stops the run waiting
+ *   Build       factoryBuild: the `builder` hook, unless understand said not to build
+ *   Check       factoryCheck: the `check` hook, or the box's `factory.check`, with its evidence
+ *   Record      factoryRecord: done, dropped, redraft, ask or not_done, which the lease's release
+ *               takes; a not_done attempt is kept at refs/chant/kept/<item>/<token> by the run
+ *
+ * The hooks are commands, run with no shell in the worktree:
+ *
+ * - `builder` (required): how a builder runs, such as Claude Code in the box
+ *   or a `fountainRun` wrapper. It gets FACTORY_ITEM, FACTORY_TIER,
+ *   FACTORY_TOKEN, FACTORY_HOLDER, FACTORY_WORKTREE and FACTORY_CONTEXT, edits
+ *   the worktree, and exits 0 when it finished. It may print a last JSON line
+ *   `{ "reverted": [paths] }` when its guard put changes back.
+ * - `context` (optional): passed to the builder as FACTORY_CONTEXT, the prompt
+ *   and context bundle the orchestrator assembles.
+ * - `check` (optional): the verdict command; the box block's `factory.check`
+ *   when left out. An infra profile names a plan or `chant lint` here.
+ *
+ * Publishing a done item is the box's publisher (ws-088), run later by a
+ * person or a surface with `chant workspace box publish`; it is not a step.
+ */
+
+import { Op, phase, activity, shell, type NamedActivityStep } from "./builders";
+import { stepOutput } from "./step-output-ref";
+import { workLeaseOutput } from "./work-lease-run";
+import type { OpConfig } from "./types";
+
+export interface FactoryOpOptions {
+  /** The Op's name. `factory` by default. */
+  name?: string;
+  /** The builder hook: a command run in the run's worktree. */
+  builder: string;
+  /** The context hook: what the builder receives as FACTORY_CONTEXT. */
+  context?: string;
+  /** The check hook; the box's `factory.check` when left out. It may print `{ "criteria": { "<id>": "pass" | "fail" } }` as its last line to tick each criterion by its own result. */
+  check?: string;
+  /** The prepare hook: a command run in the workspace before Pick, such as opening the first build's item once the box's intent is decided. */
+  prepare?: string;
+  /** The after hook: a command run in the worktree once the outcome is recorded, with FACTORY_OUTCOME and FACTORY_COMMIT, such as ending the build's run record. */
+  after?: string;
+  /** The work kind file, when the declaration names several. */
+  kind?: string;
+  /** How long a lease is held without a renewal, such as 15m. The lease's default otherwise. */
+  ttl?: string;
+  /** How long the builder may run. 2h by default. */
+  buildTimeout?: string;
+  schedule?: OpConfig["schedule"];
+  /** Where the workspace is read; the run's working directory when left out. */
+  cwd?: string;
+  /** Backends for the points' model deciders, in place of `decide.backends` in chant.config. */
+  backends?: Record<string, { url: string; key?: unknown; timeoutMs?: number }>;
+}
+
+/** The Op's configuration, for a steward that lists it or a test that runs it. */
+export function factoryOpConfig(options: FactoryOpOptions): OpConfig {
+  if (!options || typeof options.builder !== "string" || options.builder.trim() === "") {
+    throw new Error("factoryOp needs a builder: the command that runs a builder in the run's worktree");
+  }
+  const lease = workLeaseOutput();
+  const kind = options.kind !== undefined ? { kind: options.kind } : {};
+  const at = options.cwd !== undefined ? { cwd: options.cwd } : {};
+  return {
+    name: options.name ?? "factory",
+    overview: "Build the next buildable work item under its lease: pick, ask, build, check and record, by the factory's rules (#3406, ws-087)",
+    workLease: {
+      item: stepOutput("pick", "candidates"),
+      outcome: stepOutput("record", "outcome"),
+      ...kind,
+      ...(options.ttl !== undefined ? { ttl: options.ttl } : {}),
+    },
+    changesCheckout: true,
+    ...(options.schedule ? { schedule: options.schedule } : {}),
+    phases: [
+      ...(options.prepare !== undefined ? [phase("Prepare", [shell(options.prepare, { ...(options.cwd !== undefined ? { cwd: options.cwd } : {}), id: "prepare" })])] : []),
+      phase("Pick", [activity("factoryPick", { ...kind, ...at }, { profile: "fastIdempotent", id: "pick" })]),
+      phase("Ask", [activity("factoryAsk", { lease, ...kind, ...at, ...(options.backends ? { backends: options.backends } : {}) }, { profile: "fastIdempotent", id: "ask" })]),
+      phase("Build", [
+        activity(
+          "factoryBuild",
+          { lease, ...at, ask: stepOutput("ask"), builder: options.builder, ...(options.context !== undefined ? { context: options.context } : {}) },
+          { profile: "atMostOnce", id: "build", timeout: options.buildTimeout ?? "2h" },
+        ),
+      ]),
+      phase("Check", [activity("factoryCheck", { lease, ...at, build: stepOutput("build"), ...(options.check !== undefined ? { check: options.check } : {}) }, { profile: "atMostOnce", id: "check" })]),
+      phase("Record", [activity("factoryRecord", { lease, ...at, ask: stepOutput("ask"), build: stepOutput("build"), check: stepOutput("check"), ...(options.after !== undefined ? { after: options.after } : {}) }, { profile: "atMostOnce", id: "record" })]),
+    ],
+  } as OpConfig;
+}
+
+/** The factory reference Op, as an `*.op.ts` file exports it. */
+export function factoryOp(options: FactoryOpOptions): ReturnType<typeof Op> {
+  return Op(factoryOpConfig(options));
+}
+
+/**
+ * The steward's ready step for the factory Op (#382): the keys of the work buildable now, for
+ * `declareSteward({ beside: [{ op: factory, ready: factoryReady({ cwd }) }] })`. `also` names a
+ * command printing a JSON list of more keys, for work the pick can't see yet.
+ */
+export function factoryReady(options: { cwd?: string; kind?: string; also?: string } = {}): NamedActivityStep {
+  return activity("factoryReady", { ...options }, { profile: "fastIdempotent" });
+}

package/src/op/index.ts

@@ -1,5 +1,5 @@
 export { Op, phase, activity, gate, effect, build, kubectlApply, helmInstall, helmInstallPinned, waitForStack, waitForReady,
-         gitlabPipeline, lifecycleSnapshot, shell, sourceArchive, releasePlan, releaseRecord, releaseRollbackPlan, releaseRollbackRecord, decide, ensureSecret, teardown, envTeardown, k3dUp, k3dDown,
+         gitlabPipeline, lifecycleSnapshot, shell, sourceArchive, releasePlan, releaseRecord, composeChangeSet, lifecyclePlanChangeSet, readChangeSetPart, releaseRollbackPlan, releaseRollbackRecord, decide, ensureSecret, teardown, envTeardown, k3dUp, k3dDown,
          k3sInstall, k3sUninstall, flociUp, flociDown,
          flociAzUp, flociAzDown, flociGcpUp, flociGcpDown, httpCheck,
          azGroupEnsure, azGroupDelete, azApply, azDelete, awsApply, awsDelete, gcpApply, gcpDelete, policyGate,
@@ -149,3 +149,11 @@ export type { ChangeSignalGate, ChangeSignalGateOptions, WakeReason } from "./ch
 export { classifyOpVerbClass, isGated } from "./op-verb-class";
 export type { OpVerbClass } from "./op-verb-class";
 export { takeProfileAndId } from "./builders";
+
+// The factory reference Op (#3406, ws-087).
+export { factoryOp, factoryOpConfig, factoryReady } from "./factory";
+// The factory's rules themselves (#3406) are values in workspace code, which no level 0 command may load (#2526), so only their
+// types are re-exported here. An orchestrator's own tools, such as a retry command a UI runs, import the values from
+// `@intentius/chant/workspace/factory-rules`.
+export type { FactoryItem, FactoryContext, FactoryClaim, FactoryHold, RetryState } from "../workspace/factory-rules";
+export type { FactoryOpOptions } from "./factory";

package/src/op/op-ir.test.ts

@@ -325,3 +325,12 @@ describe("op.json IR", () => {
     expect("path" in (deployStep.args.context as object)).toBe(false);
   });
 });
+
+describe("neverOverMcp (chant#3447)", () => {
+  it("survives the IR round trip, and is absent when not declared", () => {
+    const base = { name: "tf-apply", overview: "apply", phases: [] };
+    expect(buildOpIR({ ...base, neverOverMcp: true }).neverOverMcp).toBe(true);
+    expect(buildOpIR(base)).not.toHaveProperty("neverOverMcp");
+    expect(opConfigFromIR(buildOpIR({ ...base, neverOverMcp: true })).neverOverMcp).toBe(true);
+  });
+});