@synovitec/trellis 0.0.0-stage → 0.6.0-rc.3

package/src/commands/uninstall.mjs

@@ -0,0 +1,36 @@
+// `trellis uninstall`: takes out what Trellis put in that would break once the package is gone
+// (the agent hooks, its pre-commit hook) and its AGENTS.md block. trellis.config.json and the
+// MCP servers stay: they are the team's configuration now, and removing them is the team's call.
+import { unlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import { planUninstallHooks } from "../agents/install.mjs";
+import { removeBlock } from "../core/agents-block.mjs";
+
+/** @typedef {import("../core/context.mjs").Context} Context */
+
+/**
+ * @param {Context} ctx
+ * @param {{ dryRun?: boolean }} flags
+ * @param {(...lines: string[]) => void} out
+ * @param {(path: string, text: string) => void} write
+ * @returns {number}
+ */
+export function uninstall(ctx, flags, out, write) {
+  const { writes, deletes } = planUninstallHooks(ctx);
+  const agents = removeBlock(ctx.read("AGENTS.md"));
+  if (agents != null) writes.push({ path: "AGENTS.md", text: agents });
+  if (!writes.length && !deletes.length) {
+    out("Nothing to remove: no Trellis hook or block is installed here.");
+    return 0;
+  }
+  for (const w of writes) {
+    if (!flags.dryRun) write(w.path, w.text);
+    out(`${flags.dryRun ? "would update" : "updated"} ${w.path}`);
+  }
+  for (const d of deletes) {
+    if (!flags.dryRun) unlinkSync(resolve(ctx.root, d));
+    out(`${flags.dryRun ? "would delete" : "deleted"} ${d}`);
+  }
+  out("", "Kept: trellis.config.json and the MCP servers in .mcp.json, which are yours to remove.");
+  return 0;
+}

package/src/commands/verify.mjs

@@ -0,0 +1,510 @@
+// The commit checkpoint and the commands that feed its evidence:
+//   trellis verify                  the staged change against the rules (pre-commit)
+//   trellis check tests -- <cmd>    run the tests and record what they ran on
+//   trellis escalate "<why>"        an agent stops and hands the change to a person
+//   trellis approve                 a person approves the change as it is now (interactive only)
+//   trellis checkpoint              after a commit: attests it (./attest.mjs)
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { commitDiff, parentsOf, stagedDiff, treeDiff, treeOf, worktreeDiff, worktreeTree } from "../core/diff.mjs";
+import { appendEvent, readWindow, resetEvidence } from "../core/evidence.mjs";
+import { NOTES_REF, PREDICATE_TYPE, readNotes, trustedKeys, verifyEnvelope } from "../core/attestation.mjs";
+import { agentAtWork, lastVerifyFile } from "./attest.mjs";
+
+export { agentAtWork, commitCheckpoint } from "./attest.mjs";
+import { createHash } from "node:crypto";
+import { VERSION } from "../core/config.mjs";
+import { loadConfig, validateConfig } from "../core/config.mjs";
+import { parseJson } from "../core/context.mjs";
+import { scanChanges, scanCommit as scanCommitSecrets, scanStaged } from "../verify/secrets.mjs";
+import { checkDependencies, dependencyChanges } from "../verify/deps.mjs";
+import { evaluate, localModes } from "../verify/rules.mjs";
+import { isTestCommand, RUNNER_SETTINGS, testCommands, testEnv, testScriptChanges } from "../verify/test-commands.mjs";
+import { matchesAny } from "../agents/glob.mjs";
+import { tmpdir } from "node:os";
+
+/** Runs `fn` with the path of an empty file, removed after. @template T @param {(path: string) => T} fn @returns {T} */
+function withEmptyFile(fn) {
+  const dir = mkdtempSync(join(tmpdir(), "trellis-empty-"));
+  try {
+    writeFileSync(join(dir, "npmrc"), "");
+    writeFileSync(join(dir, "npmrc.global"), "");
+    return fn(join(dir, "npmrc"));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** The files as they are now (work tree and index) that differ from HEAD, with their blobs. @param {string} root */
+function currentChanges(root) {
+  let base;
+  try {
+    base = treeOf(root, "HEAD");
+  } catch {
+    return stagedDiff(root);
+  }
+  return worktreeDiff(root, base);
+}
+
+/**
+ * @typedef {object} VerifyOptions
+ * @property {NodeJS.ProcessEnv} [env]
+ * @property {import("../verify/deps.mjs").Http} [http]
+ * @property {(root: string) => import("../verify/secrets.mjs").SecretScan} [scanSecrets]
+ */
+
+/**
+ * The staged change against the rules. Exit 1 when a blocking rule is not met.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {(...lines: string[]) => void} out
+ * @param {VerifyOptions} [opts]
+ * @returns {Promise<number>}
+ */
+export async function verify(ctx, out, opts = {}) {
+  const env = opts.env ?? process.env;
+  const changes = stagedDiff(ctx.root);
+  if (!changes.length) {
+    // Nothing of its own to judge (a clean merge, an empty commit): it passes, and says so for
+    // the post-commit to attest.
+    recordVerdict(ctx.root, env, { actor: "person", agent: null, preset: "recommended", findings: [], verdict: "pass" });
+    out("trellis verify: nothing staged.");
+    return 0;
+  }
+  const window = readWindow(ctx.root, env);
+  if (window.status === "tampered") {
+    out("✗ evidence-intact: the evidence log or its checkpoint was altered. Nothing in it can be trusted; tell the person.");
+    return 1;
+  }
+  const config = loadConfig(ctx);
+  // A broken config fails closed: rules read from it could be anything, and one that does not
+  // parse is not the absence of one.
+  const raw = ctx.read("trellis.config.json");
+  const errors = raw?.trim() && config == null ? ["trellis.config.json is not valid JSON"] : config ? validateConfig(config) : [];
+  if (errors.length) {
+    out(`✗ config-invalid: ${errors.join("; ")}. Fix trellis.config.json; nothing was checked.`);
+    return 1;
+  }
+  const deps = dependencyChanges(ctx.root, changes);
+  const agent = agentAtWork(window.events, env);
+  const preset = config?.verify?.preset ?? "recommended";
+  const secrets = (opts.scanSecrets ?? scanStaged)(ctx.root);
+  const findings = evaluate({
+    changes,
+    events: window.events,
+    actor: agent ? "agent" : "person",
+    preset,
+    modes: localModes(config, secrets),
+    secrets,
+    deps: deps.length ? await checkDependencies(deps, { http: opts.http }) : { status: "clean", findings: [], unpinned: [], unchecked: [] },
+    depNames: deps.map((d) => d.name),
+    testCommands: testCommands((p) => ctx.read(p)),
+    tree: spawnSync("git", ["write-tree"], { cwd: ctx.root, encoding: "utf8", windowsHide: true }).stdout?.trim() || undefined,
+    testScripts: testScriptChanges(ctx.root, changes),
+  });
+  for (const f of findings) out(`${f.mode === "block" ? "✗" : "!"} ${f.rule}: ${f.message}`);
+  const blocked = findings.filter((f) => f.mode === "block").length;
+  recordVerdict(ctx.root, env, { actor: agent ? "agent" : "person", agent, preset, findings, verdict: blocked ? "fail" : "pass" });
+  out(blocked ? `trellis verify: ${blocked} blocking finding(s); the commit is refused.` : `trellis verify: ok${findings.length ? ` (${findings.length} warning(s))` : ""}.`);
+  return blocked ? 1 : 0;
+}
+
+/**
+ * What the post-commit attests: this verdict, for exactly the tree the index holds now.
+ * @param {string} root @param {NodeJS.ProcessEnv} env @param {object} verdict
+ */
+function recordVerdict(root, env, verdict) {
+  const tree = spawnSync("git", ["write-tree"], { cwd: root, encoding: "utf8", windowsHide: true }).stdout?.trim();
+  if (!tree) return;
+  mkdirSync(dirname(lastVerifyFile(root, env)), { recursive: true });
+  writeFileSync(lastVerifyFile(root, env), JSON.stringify({ tree, ...verdict }));
+}
+
+/**
+ * Runs the test command and records, with its exit code, the content of every changed file it ran
+ * on. Trellis runs it, so a test run the agent only claims counts for nothing.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {string[]} command
+ * @param {(...lines: string[]) => void} out
+ * @param {{ env?: NodeJS.ProcessEnv, run?: (cmd: string[]) => number | null }} [opts]
+ */
+export function checkTests(ctx, command, out, opts = {}) {
+  const env = opts.env ?? process.env;
+  if (!command.length) {
+    out('Usage: trellis check tests -- <test command>   (for example: trellis check tests -- npm test)');
+    return 2;
+  }
+  // Only the project's own tests count: a run of `true` proves nothing.
+  const accepted = testCommands((p) => ctx.read(p));
+  if (!isTestCommand(command.join(" "), accepted)) {
+    out(`trellis check tests: \`${command.join(" ")}\` is not one of this project's test commands (${(accepted ?? []).join(", ")}); nothing recorded. Name others in trellis.config.json, verify.tests.`);
+    return 1;
+  }
+  // A runner setting git ignores is in no tree: present, it would change what runs unseen.
+  const hidden = spawnSync("git", ["ls-files", "--others", "--ignored", "--exclude-standard", "-z"], { cwd: ctx.root, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024 })
+    .stdout.split("\0")
+    .filter((p) => p && !p.includes("node_modules/") && matchesAny(p, RUNNER_SETTINGS));
+  if (hidden.length) {
+    out(`trellis check tests: ${hidden.slice(0, 4).join(", ")} ${hidden.length > 1 ? "are" : "is"} ignored by git but present, and would change what the tests run; nothing recorded. Commit ${hidden.length > 1 ? "them" : "it"}, or remove ${hidden.length > 1 ? "them" : "it"}.`);
+    return 1;
+  }
+  const before = currentChanges(ctx.root);
+  const treeBefore = worktreeTree(ctx.root);
+  // What runs is the accepted command itself, through a shell as a team writes it: never the
+  // tokens that matched it, which could carry `&` or `;` past a shell (`npm test "&" exit 0`).
+  const line = command.join(" ").trim().replace(/\s+/g, " ");
+  const run =
+    opts.run ??
+    ((/** @type {string[]} */ cmd) =>
+      withEmptyFile((empty) => (accepted ? spawnSync(line, { cwd: ctx.root, stdio: "inherit", shell: true, env: testEnv(process.env, empty) }) : spawnSync(cmd[0], cmd.slice(1), { cwd: ctx.root, stdio: "inherit", shell: process.platform === "win32", env: testEnv(process.env, empty) })).status));
+  const code = run(command);
+  // The content tested is the content before and after the run; a file the run itself changed was not tested as it is now.
+  const after = new Map(currentChanges(ctx.root).map((c) => [c.path, c.newBlob]));
+  /** @type {Record<string, string>} */
+  const blobs = {};
+  for (const c of before) if (c.newBlob && after.get(c.path) === c.newBlob) blobs[c.path] = c.newBlob;
+  // The whole tree tested, when the run left it as it found it: a test run counts only for a
+  // commit of exactly that tree (a test loosened for the run, then restored, is not that tree).
+  const tree = worktreeTree(ctx.root) === treeBefore ? treeBefore : null;
+  appendEvent(ctx.root, { kind: "tests", tool: command.join(" ").slice(0, 200), agent: agentAtWork([], env) ?? "person", blobs, ...(tree ? { tree } : {}), result: code ?? -1 }, env);
+  out(`trellis check tests: exit ${code ?? "killed"}, recorded for ${Object.keys(blobs).length} changed file(s).`);
+  return code === 0 ? 0 : 1;
+}
+
+/**
+ * An agent stops and hands the change to a person, with its reason.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {string} reason
+ * @param {(...lines: string[]) => void} out
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts]
+ */
+export function escalate(ctx, reason, out, opts = {}) {
+  const env = opts.env ?? process.env;
+  if (!reason.trim()) {
+    out('Usage: trellis escalate "<why a person must look>"');
+    return 2;
+  }
+  appendEvent(ctx.root, { kind: "escalation", tool: "trellis escalate", agent: agentAtWork([], env) ?? "agent", subject: reason.slice(0, 500) }, env);
+  out("trellis escalate: recorded. The change waits for a person, who reviews it and runs `trellis approve`. Stop here.");
+  return 0;
+}
+
+/**
+ * A person approves the change as it is now: every changed file at its current content, and any
+ * escalation before it. Refused without a terminal: an agent's commands run without one.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {(...lines: string[]) => void} out
+ * @param {{ env?: NodeJS.ProcessEnv, interactive?: boolean }} [opts]
+ */
+export function approve(ctx, out, opts = {}) {
+  const env = opts.env ?? process.env;
+  const interactive = opts.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (!interactive) {
+    out("trellis approve is a person's step: run it yourself, in a terminal.");
+    return 1;
+  }
+  /** @type {Record<string, string>} */
+  const blobs = {};
+  for (const c of currentChanges(ctx.root)) blobs[c.path] = c.newBlob ?? "deleted";
+  appendEvent(ctx.root, { kind: "approval", tool: "trellis approve", agent: "person", blobs }, env);
+  out(`trellis approve: approved ${Object.keys(blobs).length} changed file(s) as they are now.`);
+  return 0;
+}
+
+/**
+ * The tree the pull request lands as: what merging it into the base gives (`git merge-tree`, the
+ * merge a host makes), or null when it does not merge cleanly or git is too old to tell.
+ * @param {string} root @param {string} base @param {string} head
+ */
+function landing(root, base, head) {
+  const r = spawnSync("git", ["merge-tree", "--write-tree", "--no-messages", base, head], { cwd: root, encoding: "utf8", windowsHide: true });
+  const tree = r.stdout.split(/\r?\n/)[0]?.trim();
+  return r.status === 0 && /^[0-9a-f]{40,64}$/.test(tree ?? "") ? tree : null;
+}
+
+/** @param {{ path: string, newBlob: string | null }} c */
+const madeKey = (c) => `${c.path}\0${c.newBlob ?? "deleted"}`;
+
+/**
+ * What lands, as changes against the base: the landed tree's files that differ from the base's,
+ * each with the head's own blob for that path (what a commit of the range had to make).
+ * Without a clean landing, the head against every merge base.
+ * @param {string} root @param {string} base @param {string} head
+ * @returns {Array<import("../core/diff.mjs").Change & { headBlob: string | null }>}
+ */
+function netChanges(root, base, head) {
+  const show = (/** @type {string[]} */ args) => spawnSync("git", args, { cwd: root, encoding: "utf8", windowsHide: true });
+  const at = (/** @type {string} */ rev, /** @type {string} */ path) => show(["rev-parse", "-q", "--verify", `${rev}:${path}`]).stdout.trim() || null;
+  const landed = landing(root, base, head);
+  /** @type {Map<string, import("../core/diff.mjs").Change & { headBlob: string | null }>} */
+  const out = new Map();
+  if (landed) {
+    for (const c of treeDiff(root, base, landed)) out.set(c.path, { ...c, headBlob: at(head, c.path) });
+    return [...out.values()];
+  }
+  // With criss-cross history, content one merge base held while another had moved on is a revert
+  // the landing merge may keep: read against every one.
+  const bases = show(["merge-base", "--all", base, head]).stdout.split(/\r?\n/).filter(Boolean);
+  for (const from of bases.length ? bases : [base]) {
+    for (const c of treeDiff(root, from, head)) {
+      const old = at(base, c.path);
+      if (old === at(head, c.path)) continue; // as the base holds it: lands as nothing
+      out.set(c.path, { ...c, oldBlob: old, status: old ? (c.newBlob ? "M" : "D") : "A", headBlob: c.newBlob });
+    }
+  }
+  return [...out.values()];
+}
+
+/**
+ * The files of the net change whose content no commit of the range produced: each commit's own
+ * change (a merge's own part) is what CI judged, so anything else landed unjudged.
+ * @param {ReturnType<typeof netChanges>} net
+ * @param {Map<string, Set<string>>} madeBy  path and blob -> who made it
+ * @returns {string[]}
+ */
+const unjudgedContent = (net, madeBy) => net.filter((c) => !madeBy.has(madeKey({ path: c.path, newBlob: c.headBlob }))).map((c) => c.path);
+
+/** The rules no evidence can meet for a change no one made as such: off for the net change. */
+const EVIDENCE_RULES = ["tests-run", "graph-before-edit", "docs-looked-up", "ui-verified", "schema-before-change", "review", "plan-before-change", "escalation"];
+
+/**
+ * The blocking findings of the net change, judged as one change against the base under the base's
+ * rules: the deterministic ones over all of it, and the agent rules over the files an agent's
+ * commit made (or no attested person's), with the approvals the range recorded.
+ * @param {string} root
+ * @param {{ net: ReturnType<typeof netChanges>, madeBy: Map<string, Set<string>>, base: string, preset: string, modes: Record<string, any>, tests: string[] | null, events: import("../core/evidence.mjs").Event[], http?: import("../verify/deps.mjs").Http, scan: (root: string, changes: import("../core/diff.mjs").Change[], rulesAt: string) => import("../verify/secrets.mjs").SecretScan }} o
+ */
+async function judgeNetChange(root, o) {
+  const list = o.net.map(({ headBlob: _, ...c }) => c);
+  if (!list.length) return [];
+  const modes = { ...o.modes, ...Object.fromEntries(EVIDENCE_RULES.map((r) => [r, "off"])) };
+  const deps = dependencyChanges(root, list);
+  const clean = { status: /** @type {const} */ ("clean"), findings: [], unpinned: [], unchecked: [] };
+  const common = { events: o.events, preset: o.preset, modes, depNames: deps.map((d) => d.name), testCommands: o.tests };
+  const everything = evaluate({ ...common, changes: list, actor: "person", testScripts: testScriptChanges(root, list), secrets: o.scan(root, list, o.base), deps: deps.length ? await checkDependencies(deps, { http: o.http }) : clean });
+  // Who made each file: a person's own test edit stays a person's, whatever else the range holds.
+  const agents = o.net.filter((c) => [...(o.madeBy.get(madeKey({ path: c.path, newBlob: c.headBlob })) ?? ["agent"])].some((who) => who !== "person")).map(({ headBlob: _, ...c }) => c);
+  const byAgents = agents.length ? evaluate({ ...common, changes: agents, actor: "agent", testScripts: testScriptChanges(root, agents), secrets: { status: "clean" }, deps: clean }) : [];
+  const seen = new Set();
+  return [...everything, ...byAgents].filter((f) => {
+    const id = `${f.rule}\0${f.message}`;
+    if (f.mode !== "block" || seen.has(id)) return false;
+    seen.add(id);
+    return true;
+  });
+}
+
+/**
+ * The attestation CI goes by, among the envelopes a commit's note holds (two developers' notes
+ * merge line by line): the first one signed by a trusted key about exactly this commit and tree,
+ * a checked one before an `unverified` one. Else the reason the best candidate failed.
+ * @param {any[]} envelopes
+ * @param {Map<string, string>} keys
+ * @param {string} commit
+ * @param {string} tree
+ * @returns {{ statement: any, envelope: any, problem: string | null }}
+ */
+function pickAttestation(envelopes, keys, commit, tree) {
+  if (!envelopes.length) return { statement: null, envelope: null, problem: "no attestation: this commit was made without Trellis's hooks" };
+  let problem = "";
+  /** @type {{ statement: any, envelope: any, verdict: string } | null} */
+  let unverified = null;
+  for (const envelope of envelopes) {
+    const v = verifyEnvelope(envelope, keys);
+    if (!v.ok) problem ||= v.reason;
+    else if (v.statement.subject?.[0]?.digest?.gitCommit !== commit || v.statement.subject?.[0]?.digest?.gitTree !== tree) problem ||= "it is about another commit or tree";
+    // Only a checkpoint that passed vouches: `fail` is a commit the checkpoint refused, made anyway.
+    else if (v.statement.predicate?.verdict !== "pass") unverified ??= { statement: v.statement, envelope, verdict: String(v.statement.predicate?.verdict) };
+    else return { statement: v.statement, envelope, problem: null };
+  }
+  if (unverified?.verdict === "unverified") return { statement: unverified.statement, envelope: unverified.envelope, problem: "unverified: the commit skipped the checkpoint (git commit --no-verify, or a tool that skips hooks)" };
+  if (unverified) return { statement: unverified.statement, envelope: unverified.envelope, problem: `the checkpoint refused this commit (verdict ${unverified.verdict}), and it was committed anyway` };
+  return { statement: null, envelope: envelopes[0], problem };
+}
+
+/**
+ * @typedef {object} CiOptions
+ * @property {string} [base]       the commit the range starts after (a PR's base)
+ * @property {string} [head]       the commit the range ends at (a PR's head; default HEAD)
+ * @property {string} [summary]    where to write the SLSA verification summary
+ * @property {string} [checksums]  where to write each commit as `<sha256 of its raw object>  git-commit-<id>`
+ * @property {NodeJS.ProcessEnv} [env]
+ * @property {import("../verify/deps.mjs").Http} [http]
+ * @property {(root: string, commit: string, opts: { base: string }) => import("../verify/secrets.mjs").SecretScan} [scanCommit]
+ * @property {(root: string, changes: import("../core/diff.mjs").Change[], rulesAt: string) => import("../verify/secrets.mjs").SecretScan} [scanChanges]
+ */
+
+/**
+ * The authority: every commit after `base`, judged on another machine. Its attestation must be
+ * there, signed by a key the repository trusts, about exactly that commit and tree; the
+ * deterministic checks are run again here; and the rules are judged again here from the change
+ * and the evidence the attestation carries. The local verdict is read, never believed.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {(...lines: string[]) => void} out
+ * @param {CiOptions} [opts]
+ * @returns {Promise<number>}
+ */
+export async function verifyCi(ctx, out, opts = {}) {
+  const git = (/** @type {string[]} */ args) => spawnSync("git", args, { cwd: ctx.root, encoding: "utf8", windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
+  const base = opts.base ?? "HEAD~1";
+  // A pull request is judged at its head: the merge commit a CI checkout builds was made by no one.
+  const head = opts.head ?? "HEAD";
+  if (git(["rev-parse", "-q", "--verify", `${base}^{commit}`]).status !== 0) {
+    if (git(["rev-parse", "-q", "--verify", `${head}^{commit}`]).status === 0 && !git(["rev-list", "--parents", "-n", "1", head]).stdout.trim().includes(" ")) {
+      // Nothing stood before a repository's first commit: its own keys and rules would vouch for it.
+      out(`! trellis verify --ci: ${head} is the repository's first commit; there is no base to judge it by, so it is not judged.`);
+      return 0;
+    }
+    out(`✗ trellis verify --ci: the base ${base} is not in this clone. Check out the whole history (actions/checkout with fetch-depth: 0), or pass --base.`);
+    return 1;
+  }
+  const list = git(["rev-list", "--reverse", `${base}..${head}`]);
+  if (list.status !== 0) {
+    out(`✗ trellis verify --ci: the range ${base}..${head} could not be read (${(list.stderr || "").trim()}). Fetch the base, with its history.`);
+    return 1;
+  }
+  const commits = list.stdout.split(/\r?\n/).filter(Boolean);
+  // What judges a pull request is what stood before it: the keys and the rules at the base. A key
+  // or a config the range itself adds takes effect once merged, never for its own commits.
+  const keys = trustedKeys(ctx.root, base);
+  const baseText = git(["show", `${base}:trellis.config.json`]).stdout || "";
+  const baseConfig = parseJson(baseText || "null");
+  // A config that does not parse is no reason to fall back to the default preset.
+  if (baseText.trim() && baseConfig == null) {
+    out(`✗ trellis verify --ci: trellis.config.json at ${base} is not valid JSON; nothing was judged.`);
+    return 1;
+  }
+  if (baseConfig && validateConfig(baseConfig).length) {
+    out(`✗ trellis verify --ci: trellis.config.json at ${base} is invalid (${validateConfig(baseConfig).join("; ")}); nothing was judged.`);
+    return 1;
+  }
+  const preset = baseConfig?.verify?.preset ?? "recommended";
+  const modes = baseConfig?.verify?.rules ?? {};
+  const unattested = baseConfig?.verify?.unattested ?? "refuse";
+  // What counts as the tests is the base's too.
+  const tests = testCommands((p) => {
+    const r = git(["show", `${base}:${p}`]);
+    return r.status === 0 ? r.stdout : null;
+  });
+  const keysAdded = git(["diff", "--name-only", "--diff-filter=AM", base, head, "--", ".trellis/keys"]).stdout.trim();
+  if (keysAdded) out(`! keys: this range adds or changes ${keysAdded.split(/\r?\n/).join(", ")}; they are trusted once merged, not for these commits.`);
+  const scan = opts.scanCommit ?? scanCommitSecrets;
+  let failed = 0;
+  /** @type {Array<{ name: string, digest: Record<string, string> }>} */
+  const subjects = [];
+  /** @type {Array<{ uri: string, digest: Record<string, string> }>} */
+  const inputs = [];
+  /** @type {import("../core/evidence.mjs").Event[]} */
+  const rangeEvents = [];
+  /** @type {Map<string, Set<string>>} each file's content, as a commit of the range made it, by who */
+  const madeBy = new Map();
+  for (const commit of commits) {
+    const tree = git(["rev-parse", `${commit}^{tree}`]).stdout.trim();
+    subjects.push({ name: `git commit ${commit.slice(0, 12)}`, digest: { gitCommit: commit, gitTree: tree } });
+    /** @type {string[]} */
+    const problems = [];
+    // Re-judged here: the change itself, Trellis's own scans, and the evidence the attestation carries.
+    const changes = commitDiff(ctx.root, commit);
+    const { statement, envelope, problem } = pickAttestation(readNotes(ctx.root, commit), keys, commit, tree);
+    // A merge with nothing of its own (the host's merge button, a clean merge) vouches for
+    // nothing: each side is judged on its own commits. A squash merge has content, and is not one.
+    if (problem && !changes.length && parentsOf(ctx.root, commit).length > 1) problems.push("warn attestation: a merge with nothing of its own; its sides are judged on their own commits");
+    // verify.unattested "judge" (the base's): a commit made without Trellis (a fork's
+    // contributor, Dependabot, the web editor) is judged on its own, as an agent's, not refused.
+    else if (problem && unattested === "judge" && !statement) problems.push(`warn attestation: ${problem}; judged here on its own, as an agent's (verify.unattested)`);
+    else if (problem) problems.push(`block attestation: ${problem}`);
+    if (envelope) inputs.push({ uri: `git+notes:${NOTES_REF}@${commit}`, digest: { sha256: createHash("sha256").update(JSON.stringify(envelope)).digest("hex") } });
+    const deps = dependencyChanges(ctx.root, changes);
+    const findings = evaluate({
+      changes,
+      events: statement?.predicate?.events ?? [],
+      // Who made it is only known from the attestation, as strong as the developer's key. The
+      // rules are the base's, never the attestation's.
+      actor: statement?.predicate?.actor === "person" ? "person" : "agent",
+      preset,
+      modes,
+      // The allowlist is the base's, like the keys and the rules.
+      secrets: scan(ctx.root, commit, { base }),
+      deps: deps.length ? await checkDependencies(deps, { http: opts.http }) : { status: "clean", findings: [], unpinned: [], unchecked: [] },
+      depNames: deps.map((x) => x.name),
+      testCommands: tests,
+      tree,
+      testScripts: testScriptChanges(ctx.root, changes),
+    });
+    for (const f of findings) problems.push(`${f.mode} ${f.rule}: ${f.message}`);
+    rangeEvents.push(...(statement?.predicate?.events ?? []));
+    const who = statement?.predicate?.actor === "person" ? "person" : "agent";
+    for (const c of changes) {
+      if (!madeBy.has(madeKey(c))) madeBy.set(madeKey(c), new Set());
+      madeBy.get(madeKey(c))?.add(who);
+    }
+    const blocking = problems.filter((p) => p.startsWith("block "));
+    if (blocking.length) failed++;
+    out(`${blocking.length ? "✗" : "✓"} ${commit.slice(0, 12)} ${git(["log", "-1", "--format=%s", commit]).stdout.trim().slice(0, 72)}`);
+    for (const p of problems) out(`    ${p.startsWith("block ") ? "✗" : "!"} ${p.replace(/^(block|warn) /, "")}`);
+  }
+  // What lands is the range's net change, against where it left the base. Each file of it must be
+  // as a commit of the range made it, and was judged as: content a merge took from elsewhere (an
+  // old ancestor, a branch outside the range) was judged by no one.
+  const net = netChanges(ctx.root, base, head);
+  const unjudged = unjudgedContent(net, madeBy);
+  if (unjudged.length) {
+    failed++;
+    out(`✗ net change: ${unjudged.slice(0, 6).join(", ")}${unjudged.length > 6 ? `, and ${unjudged.length - 6} more` : ""} land as no commit of the range made them (a merge took them from elsewhere). Make the change in a commit of its own.`);
+  }
+  // And the net change judged as one change: each commit is judged against its own parent, so a
+  // branch from an old ancestor can "add" a test the base already has, or keep a dependency the
+  // base upgraded, and a merge then lands it with nothing of its own. Against the base, that is
+  // an edit and a downgrade. The deterministic rules and the protected tests hold for it, as an
+  // agent's unless every commit is a person's, with the approvals the range recorded.
+  const netFindings = await judgeNetChange(ctx.root, { net, madeBy, base, preset, modes, tests, events: rangeEvents, http: opts.http, scan: opts.scanChanges ?? scanChanges });
+  if (netFindings.length) {
+    failed++;
+    out("✗ net change, judged as one change against the base:");
+    for (const f of netFindings) out(`    ✗ ${f.rule}: ${f.message}`);
+  }
+  const passed = failed === 0;
+  if (opts.checksums) {
+    // actions/attest takes SHA-256 subjects; a commit's own id is not one. The SHA-256 of its raw
+    // object is, and anyone with the repository recomputes it: git cat-file commit <id> | sha256sum.
+    const lines = commits.map((c) => `${createHash("sha256").update(spawnSync("git", ["cat-file", "commit", c], { cwd: ctx.root, windowsHide: true }).stdout).digest("hex")}  git-commit-${c}`);
+    writeFileSync(opts.checksums, lines.map((l) => `${l}\n`).join(""));
+  }
+  out(`trellis verify --ci: ${commits.length} commit(s), ${failed} refused.`);
+  if (opts.summary) {
+    const vsa = {
+      _type: "https://in-toto.io/Statement/v1",
+      subject: subjects,
+      predicateType: "https://slsa.dev/verification_summary/v1",
+      predicate: {
+        verifier: { id: "https://github.com/Synovitec/trellis", version: { trellis: VERSION } },
+        timeVerified: new Date().toISOString(),
+        resourceUri: `git+${git(["remote", "get-url", "origin"]).stdout.trim() || ctx.root}`,
+        policy: { uri: PREDICATE_TYPE },
+        inputAttestations: inputs,
+        verificationResult: passed ? "PASSED" : "FAILED",
+        verifiedLevels: ["SLSA_BUILD_LEVEL_UNEVALUATED"],
+      },
+    };
+    writeFileSync(opts.summary, `${JSON.stringify(vsa, null, 2)}\n`);
+  }
+  return passed ? 0 : 1;
+}
+
+/**
+ * `trellis evidence reset`: a person sets an unusable evidence log aside and starts a new one.
+ * Refused without a terminal, like approve: an agent's commands run without one.
+ * @param {import("../core/context.mjs").Context} ctx
+ * @param {(...lines: string[]) => void} out
+ * @param {{ env?: NodeJS.ProcessEnv, interactive?: boolean }} [opts]
+ */
+export function evidenceReset(ctx, out, opts = {}) {
+  const interactive = opts.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  if (!interactive) {
+    out("trellis evidence reset is a person's step: run it yourself, in a terminal.");
+    return 1;
+  }
+  const kept = resetEvidence(ctx.root, opts.env ?? process.env);
+  out(kept ? `trellis evidence reset: the old log is kept as ${kept}; a new one starts now. The checks recorded before it no longer count: run them again.` : "trellis evidence reset: there was no log; nothing to set aside.");
+  return 0;
+}

package/src/core/abatty.mjs

@@ -0,0 +1,25 @@
+// The guard engine. `trellis gate`, `trellis explain` and `trellis prove` are abatty's commands,
+// run as they are: Trellis frames the work around the gate, it does not reimplement it.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/** The abatty commands Trellis passes through unchanged. */
+export const PASSTHROUGH = Object.freeze(["gate", "explain", "prove", "ratchet", "status", "rules"]);
+
+/**
+ * Runs `abatty <args>` from the repository, preferring its own installed copy.
+ * @param {string} root
+ * @param {string[]} args
+ * @param {(line: string) => void} out
+ * @returns {number}
+ */
+export function runAbatty(root, args, out) {
+  const local = join(root, "node_modules", "abatty", "bin", "abatty.mjs");
+  if (!existsSync(local)) {
+    out("abatty is not installed in this repository: `npm i -D abatty && npx abatty init` sets up the gate.");
+    return 1;
+  }
+  const r = spawnSync(process.execPath, [local, ...args], { cwd: root, stdio: "inherit" });
+  return r.status ?? 1;
+}

package/src/core/agents-block.mjs

@@ -0,0 +1,65 @@
+// The managed block in AGENTS.md: the tool routing, generated from the config, between two
+// markers. Trellis writes only between its markers; everything else in the file is the team's.
+import { ROLES } from "../tools/roles.mjs";
+
+/** What identifies the opening marker, whatever text follows it in an older version. */
+const START_TAG = "<!-- trellis:start";
+export const START = "<!-- trellis:start (generated by `trellis init`; edit trellis.config.json, not this block) -->";
+export const END = "<!-- trellis:end -->";
+
+/** @typedef {import("../tools/registry.mjs").Tool} Tool */
+
+/**
+ * The block's text for the enabled tools, grouped by role.
+ * @param {Array<{ tool: Tool }>} enabled
+ */
+export function renderBlock(enabled) {
+  const lines = [START, "## Tools (Trellis)", ""];
+  for (const role of ROLES) {
+    const tools = enabled.filter((e) => e.tool.role === role.id);
+    if (!tools.length) continue;
+    lines.push(`**${role.title}** - ${role.question}`, "");
+    for (const { tool } of tools) {
+      lines.push(`- **${tool.name}**: ${tool.use}${tool.rule ? ` ${tool.rule}` : ""}`);
+    }
+    lines.push("");
+  }
+  // What the commit checkpoint counts is what Trellis saw run: say how to be seen, and the way out.
+  lines.push(
+    "**Checks (Trellis)** - each commit is judged on what Trellis saw run, not on what is said.",
+    "",
+    "- Use the `trellis` MCP server's tools when they are offered: `graph_query` before changing code, `run_tests` for the tests, `check_change` to see what the next commit would be refused for.",
+    "- Without them: `npx --no-install @synovitec/trellis check tests -- <the project's test command>`.",
+    '- If a test or the task itself is wrong, do not edit the test: stop with the `escalate` tool, or `npx --no-install @synovitec/trellis escalate "<why>"`, and hand the change to the person.',
+    "",
+  );
+  lines.push("`npx @synovitec/trellis doctor` says which of these is installed and actually wired; `npx @synovitec/trellis guide <tool>` explains one.", END);
+  return lines.join("\n");
+}
+
+/**
+ * The file without the block, or null when it has none.
+ * @param {string | null} existing
+ */
+export function removeBlock(existing) {
+  if (existing == null) return null;
+  const s = existing.indexOf(START_TAG);
+  const e = existing.indexOf(END);
+  if (s === -1 || e < s) return null;
+  return `${existing.slice(0, s).replace(/\s*$/, "")}\n${existing.slice(e + END.length).replace(/^\s*/, "\n")}`.replace(/\n{3,}/g, "\n\n");
+}
+
+/**
+ * The file with the block put in place: replaced between existing markers, else appended.
+ * @param {string | null} existing
+ * @param {string} block
+ * @returns {string}
+ */
+export function upsertBlock(existing, block) {
+  if (existing == null || existing.trim() === "") return `# AGENTS.md\n\n${block}\n`;
+  const s = existing.indexOf(START_TAG);
+  const e = existing.indexOf(END);
+  if (s !== -1 && e > s) return existing.slice(0, s) + block + existing.slice(e + END.length);
+  if (s !== -1 || e !== -1) throw new Error("AGENTS.md has a trellis marker without its pair; restore both or remove both");
+  return `${existing.replace(/\s*$/, "")}\n\n${block}\n`;
+}