@intentius/chant 0.101.0 → 0.104.0

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/gate-approval.test.ts

@@ -191,6 +191,80 @@ describe("gate approval — policy decisions (#2508)", () => {
     expect(check.satisfied).toBe(false);
   });
 
+  test("log-only then enforce: a permit recorded under log-only does not pass the enforced gate (#2512)", async () => {
+    const logOnly: ResolvedGateApproval = { policy: POLICY, mode: "log-only", context: { risk: "low" } };
+    const enforce: ResolvedGateApproval = { ...logOnly, mode: "enforce" };
+    // The pending fact was recorded while the gate was log-only, and the agent's allow was recorded against it.
+    const port = memoryGateLedgerPort({
+      resolutions: [approval({ resolvedBy: "release-bot", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "agent" }, policyDecision: allow("log-only") })],
+      pending: [{ ...PENDING, approval: logOnly }],
+    });
+    const check = await evaluateGate(port, { op: "release", gate: "ship", planDigest: PLAN_A, approval: enforce, now: NOW });
+    expect(check.satisfied).toBe(false);
+
+    const tally = tallyGateApprovals(
+      [approval({ resolvedBy: "release-bot", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "agent" }, policyDecision: allow("log-only") })],
+      "ship", PENDING.timestamp, PLAN_A, enforce,
+    );
+    expect(tally.permit).toBeUndefined();
+  });
+
+  test("log-only then enforce: a human's approval recorded under log-only still counts toward the quorum (#2512)", async () => {
+    const logOnly: ResolvedGateApproval = { quorum: { count: 1 }, policy: POLICY, mode: "log-only" };
+    const enforce: ResolvedGateApproval = { ...logOnly, mode: "enforce" };
+    const port = memoryGateLedgerPort({
+      resolutions: [approval({ resolvedBy: "alex", timestamp: "2026-09-01T01:00:00.000Z", policyDecision: allow("log-only") })],
+      pending: [{ ...PENDING, approval: logOnly }],
+    });
+    const check = await evaluateGate(port, { op: "release", gate: "ship", planDigest: PLAN_A, approval: enforce, now: NOW });
+    expect(check.satisfied).toBe(true);
+    if (!check.satisfied) return;
+    expect(check.via).toBe("quorum");
+    expect(check.resolution.resolvedBy).toBe("alex");
+  });
+
+  test("log-only then enforce: the gated run re-records the pending fact under enforce, and only a fresh permit passes (#2512)", async () => {
+    const logOnly: ResolvedGateApproval = { policy: POLICY, mode: "log-only", context: { risk: "low" } };
+    const enforce: ResolvedGateApproval = { ...logOnly, mode: "enforce" };
+    const stale = approval({ resolvedBy: "release-bot", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "agent" }, policyDecision: allow("log-only") });
+    const port = memoryGateLedgerPort({ resolutions: [stale], pending: [{ ...PENDING, approval: logOnly }] });
+
+    const first = await evaluateGate(port, { op: "release", gate: "ship", planDigest: PLAN_A, approval: enforce, now: NOW });
+    expect(first.satisfied).toBe(false);
+    if (first.satisfied) return;
+    // The standing fact described the log-only gate, so a fresh one carries
+    // enforce, and `chant approve` evaluates the next agent approval under it.
+    expect(first.recorded).toBe(true);
+    expect(first.pending.approval?.mode).toBe("enforce");
+
+    // Re-running without a new approval still waits: the stale permit predates the new pending fact as well.
+    const again = await evaluateGate(port, { op: "release", gate: "ship", planDigest: PLAN_A, approval: enforce, now: "2026-09-01T12:30:00.000Z" });
+    expect(again.satisfied).toBe(false);
+
+    const fresh = approval({ resolvedBy: "release-bot", timestamp: "2026-09-01T13:00:00.000Z", approver: { kind: "agent" }, policyDecision: allow("enforce") });
+    const after = await evaluateGate(
+      memoryGateLedgerPort({ resolutions: [stale, fresh], pending: [first.pending] }),
+      { op: "release", gate: "ship", planDigest: PLAN_A, approval: enforce, now: "2026-09-01T14:00:00.000Z" },
+    );
+    expect(after.satisfied).toBe(true);
+    if (!after.satisfied) return;
+    expect(after.via).toBe("policy");
+    expect(after.resolution.timestamp).toBe(fresh.timestamp);
+  });
+
+  test("enforce: a recorded decision with no mode does not pass the gate (#2512)", async () => {
+    const block: ResolvedGateApproval = { policy: POLICY, mode: "enforce" };
+    const { mode: _mode, ...noMode } = allow()!;
+    const { check } = await decide(
+      [approval({
+        resolvedBy: "release-bot", timestamp: "2026-09-01T01:00:00.000Z", approver: { kind: "agent" },
+        policyDecision: noMode as GateResolutionRecord["policyDecision"],
+      })],
+      block,
+    );
+    expect(check.satisfied).toBe(false);
+  });
+
   test("enforce: a deny-by-default policy keeps the old behaviour, where only a human's approval counts", async () => {
     const block: ResolvedGateApproval = { policy: POLICY, mode: "enforce" };
     const deny = { ...allow()!, decision: "deny" as const, determining: ["floor"] };

package/src/op/gate-approval.ts

@@ -119,7 +119,11 @@ export interface GatePolicyAnswer {
 export interface GatePolicyDecision extends GatePolicyAnswer {
   policy: string;
   version: string;
-  /** The gate's mode when the decision was recorded. A run reads the gate's current mode, not this. */
+  /**
+   * The gate's mode when the decision was recorded. A permit passes a gate
+   * only when both this and the gate's current mode are `enforce` (#2512), so
+   * an allow recorded under `log-only` never binds after a switch.
+   */
   mode: GateApprovalMode;
 }
 

package/src/op/gate.ts

@@ -74,6 +74,19 @@ export interface PendingGatePush {
 export interface GateLedgerPort {
   read(op: string): Promise<{ resolutions: GateResolutionRecord[]; pending: PendingGateRecord[] }>;
   appendPending(input: PendingGateInput): Promise<PendingGatePush>;
+  /**
+   * The rule a workspace sets for approvals of `gate` (#3163, ws-080), or
+   * null when none applies: the declaration's `identity.gates`, read at base.
+   * Absent, every approval is judged as before.
+   */
+  approvalRule?(gate: string): Promise<GateApprovalRule | null>;
+}
+
+/** A workspace's rule for which approvals of a gate count (#3163): a signed approval, from a class when it names one. */
+export interface GateApprovalRule {
+  requirement: { gate: string; class: string | null };
+  /** Why `approval` doesn't count, or null when it does. */
+  refuses(approval: GateResolutionRecord): string | null;
 }
 
 /**
@@ -102,6 +115,11 @@ export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
       const { resolutions, pending } = await readGateLedger(op, opts);
       return { resolutions, pending };
     },
+    async approvalRule(gate) {
+      // Loaded on demand: the rule lives in the workspace modules, which import the Op modules.
+      const { gateAdmission } = await import("../workspace/identity");
+      return gateAdmission(opts?.cwd ?? process.cwd(), gate);
+    },
     async appendPending(input) {
       const { record } = await appendPendingGate(input, opts);
       try {
@@ -288,7 +306,7 @@ export interface GateTally {
   counted: GateResolutionRecord[];
   /** The quorum's count, 1 when the gate declares none. */
   need: number;
-  /** The newest approval whose recorded permit passes the gate on its own. Only in `enforce` mode, and only under the gate's current policy version. */
+  /** The newest approval whose recorded permit passes the gate on its own. Only in `enforce` mode, only for a permit recorded under `enforce`, and only under the gate's current policy version. */
   permit?: GateResolutionRecord;
   /** The newest approval of this gate for a different plan, when the gate binds one. */
   mismatched?: GateResolutionRecord;
@@ -305,8 +323,9 @@ export interface GateTally {
  * Of those, only a human's counts toward the quorum, once per `resolvedBy`,
  * and only with one of the quorum's roles when it names any. An agent counts
  * only through a recorded `allow` in `enforce` mode, evaluated under the
- * policy version the gate declares now. A `log-only` decision never changes
- * the outcome, and a `deny` never removes a human's approval: a policy can add
+ * policy version the gate declares now and recorded while the gate was in
+ * `enforce` (#2512). A `log-only` decision never changes the outcome, even
+ * after the gate switches to `enforce`, and a `deny` never removes a human's approval: a policy can add
  * a way through the gate but cannot take one away.
  */
 export function tallyGateApprovals(
@@ -331,8 +350,12 @@ export function tallyGateApprovals(
     }
 
     const decision = r.policyDecision;
+    // #2512: the decision must also have been recorded under `enforce`. An
+    // allow recorded while the gate was log-only was never binding, and a
+    // later switch to enforce does not make it binding.
     if (
       approval.mode === "enforce" && approval.policy && decision?.decision === "allow" &&
+      decision.mode === "enforce" &&
       decision.version === approval.policy.version && (!permit || at(r) >= at(permit))
     ) {
       permit = r;
@@ -394,10 +417,13 @@ export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput):
   // a mismatch with a message instead of silently not counting.
   const env = input.environment;
   const pending = env === undefined ? ledger.pending : ledger.pending.filter((p) => p.environment === env);
-  const resolutions =
+  // #3163: a gate the workspace's identity.gates names counts only signed approvals from its class.
+  const rule = (await port.approvalRule?.(input.gate)) ?? null;
+  const resolutions = (
     env === undefined
       ? ledger.resolutions
-      : ledger.resolutions.filter((r) => r.environment === undefined || r.environment === env);
+      : ledger.resolutions.filter((r) => r.environment === undefined || r.environment === env)
+  ).filter((r) => rule === null || r.gate !== input.gate || rule.refuses(r) === null);
 
   const standing = latestPendingGate(pending, input.gate);
   const since = standing?.timestamp ?? EPOCH;

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,
@@ -60,6 +60,8 @@ export type { ActivityProfile, ActivityProfileName } from "./activity-profiles";
 export { NonRetryableActivityError, nonRetryableFailure } from "./activity-failure";
 export { runOpLocally, parseDuration, OpRunFailure } from "./local-executor";
 export type { StepRecord, OpRunResult, RunOpOptions } from "./local-executor";
+export { currentOpRun, withOpRunContext } from "./run-context";
+export type { OpRunContext, PassedGate } from "./run-context";
 export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand, describeGateMismatch } from "./gate";
 export type { GateLedgerPort, GateCheck, GateCheckInput, PendingGatePush, GateDigestMismatch, GateQuorumProgress, GateTally } from "./gate";
 export { tallyGateApprovals, approverOf } from "./gate";
@@ -147,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/local-executor.test.ts

@@ -232,6 +232,21 @@ describe("runOpLocally — outcomeAttribute", () => {
     expect(result.records[0].outcome).toEqual({ name: "Drift", value: true });
   });
 
+  test("an attribute whose path the result does not hold is left off, not recorded as undefined", async () => {
+    const done: ActivityFn = async () => ({ state: "done", switched: false });
+    const config = op({
+      phases: [{ name: "Switch", steps: [
+        { kind: "activity", fn: "migrationSwitch", outcomeAttribute: [{ name: "OldColumn", from: "oldColumn" }, { name: "State", from: "state" }] },
+        { kind: "activity", fn: "migrationRetain", outcomeAttribute: { name: "RetainUntil", from: "retainUntil" } },
+      ] }],
+    });
+    const result = await runOpLocally(config, new Map([["migrationSwitch", done], ["migrationRetain", done]]), PROFILES);
+    expect(result.records[0].outcomes).toEqual([{ name: "State", value: "done" }]);
+    expect(result.records[0].outcome).toEqual({ name: "State", value: "done" });
+    expect(result.records[1].outcomes).toBeUndefined();
+    expect(result.records[1].outcome).toBeUndefined();
+  });
+
   test("a step with no attribute leaves both fields absent", async () => {
     const noop: ActivityFn = async () => ({ ok: true });
     const config = op({ phases: [{ name: "Plan", steps: [{ kind: "activity", fn: "noop" }] }] });