@tech-leads-club/harness-toolkit 0.2.1

package/src/core/floor/floor.service.ts

@@ -0,0 +1,306 @@
+import type { Decision } from "../../contracts/decision.ts";
+import { isInside, isScratch, isSecretPath, resolveTarget } from "./floor.paths.ts";
+import { checkPolicySurface } from "./floor.policy-surface.ts";
+import { type ShellSegment, type ShellWord, tokenizeShell } from "./floor.tokenize.ts";
+import { verbOf } from "./floor.verb.ts";
+
+export type FloorRule =
+  | "machine-control"
+  | "secret-access"
+  | "unprovable-destruction"
+  | "history-rewrite"
+  | "outside-project-destruction"
+  | "policy-surface-write"
+  | "unprovable-execution";
+
+export type FloorInput = {
+  projectDir: string;
+  toolName?: string | undefined;
+  filePath?: string | undefined;
+  command?: string | undefined;
+  isReadEvent?: boolean | undefined;
+};
+
+const DESTRUCTIVE_VERBS = new Set(["dd", "rm", "rmdir", "shred", "truncate"]);
+const MACHINE_VERBS = new Set(["halt", "poweroff", "reboot", "shutdown"]);
+const READER_VERBS = new Set(["base64", "cat", "head", "less", "more", "od", "strings", "tail", "xxd"]);
+const READING_TOOLS = new Set(["Read", "Edit", "MultiEdit", "NotebookEdit"]);
+const EXPANDING_VERBS = new Set([".", "eval", "source"]);
+const SHELLS = new Set(["ash", "bash", "dash", "fish", "ksh", "sh", "zsh"]);
+
+/**
+ * why: a verb whose job is to bring bytes from the network. The set is the reason the rule can be stated at all —
+ * a program that arrives over the wire does not exist when the decision is made
+ * ([/decisions/ad-074.md](/decisions/ad-074.md)).
+ */
+const FETCH_VERBS = new Set(["aria2c", "curl", "fetch", "http", "httpie", "https", "wget"]);
+
+/**
+ * The link-local services that hand out cloud credentials over HTTP.
+ *
+ * why: `secret-access` matched by path, so `~/.aws/credentials` was refused while the address returning the same
+ * credential was allowed. A credential is not always a file.
+ */
+const METADATA_HOSTS = ["169.254.169.254", "169.254.170.2", "100.100.100.200", "metadata.google.internal"];
+
+/**
+ * invariant: verbs that speak to the network, and nothing else. `grep -rn 169.254.169.254 .` searches this
+ * repository for a literal string and stays allowed — scoping to the verb is what keeps it that way.
+ */
+const NETWORK_VERBS = new Set([...FETCH_VERBS, "nc", "ncat", "socat", "telnet", "lwp-request"]);
+
+function namesFetcher(text: string): boolean {
+  return [...FETCH_VERBS].some((verb) => new RegExp(`\\b${verb}\\b`).test(text));
+}
+
+/**
+ * A program assembled from a network fetch and handed to a shell.
+ *
+ * hazard: measured against the floor before this existed, all four spellings were allowed — and each one hands
+ * the shell a payload that satisfies every other floor rule by containing nothing the gate can see. The wrapper
+ * deletes nothing, reads nothing and forces nothing; whatever arrives does
+ * ([/decisions/ad-074.md](/decisions/ad-074.md)).
+ */
+function fetchedProgramReachesShell(command: string, segments: readonly ShellSegment[]): boolean {
+  // hazard: the tokenizer splits on `;`, `|` and `&` alike, so carrying a flag across segments treated
+  // `curl --version && bash ./scripts/deploy.sh` as a download piped to a shell. Requiring a literal pipe keeps
+  // every real `curl … | bash` and drops a sequence that merely mentions a fetcher — a false positive is
+  // expensive in a rule with no switch ([/decisions/ad-034.md](/decisions/ad-034.md)).
+  const piped = command.includes("|");
+  let upstreamFetches = false;
+  for (const segment of segments) {
+    const head = verbOf(segment.words);
+    if (!head) {
+      continue;
+    }
+    const { verb, args } = head;
+
+    // 1. a pipeline whose upstream fetched and whose downstream is a shell
+    if (piped && upstreamFetches && SHELLS.has(verb)) {
+      return true;
+    }
+
+    if (SHELLS.has(verb) || EXPANDING_VERBS.has(verb)) {
+      for (const word of args) {
+        // 2. process substitution: `bash <(curl …)`
+        // 3. and 4. an unresolved word that names a fetcher — `sh -c "$(curl …)"`, `eval "$(curl …)"`
+        const substitution = word.text.includes("<(") || word.unresolved;
+        if (substitution && namesFetcher(word.text)) {
+          return true;
+        }
+      }
+    }
+
+    upstreamFetches = FETCH_VERBS.has(verb);
+  }
+  return false;
+}
+
+// why: `bash script.sh` runs a file this gate cannot see, which is a coverage limit rather than evasion.
+// `bash -c "..."` carries the command inline, which is the case worth refusing.
+function buildsCommandAtRuntime(verb: string, args: ShellWord[]): boolean {
+  return EXPANDING_VERBS.has(verb) || (SHELLS.has(verb) && args.some((word) => word.text === "-c"));
+}
+
+function reason(rule: FloorRule, detail: string): string {
+  return [
+    `FLOOR: ${detail}`,
+    "This is a floor rule — it has no config switch, because a limit an agent can turn off is not a limit.",
+    "Restate what you need and let the operator decide; do not work around this.",
+    `rule=${rule}`,
+  ].join("\n");
+}
+
+// why: the rule was already written into the reason prose as `rule=<name>`. Carrying it structurally as well is
+// what lets a refusal be counted and attributed without parsing English
+// ([/decisions/ad-027.md](/decisions/ad-027.md)).
+function denial(rule: FloorRule, detail: string, note: string): Decision {
+  return {
+    kind: "deny",
+    reason: reason(rule, detail),
+    userNote: `Floor rule ${rule}: ${note}`,
+    rule,
+  };
+}
+
+function isMkfs(verb: string): boolean {
+  return verb === "mkfs" || verb.startsWith("mkfs.");
+}
+
+function isDangerousVerb(token: string): boolean {
+  const verb = token.split("/").pop() ?? token;
+  return DESTRUCTIVE_VERBS.has(verb) || MACHINE_VERBS.has(verb) || isMkfs(verb);
+}
+
+function hidesDestructiveVerb(segment: ShellSegment): boolean {
+  return segment.words.some((word) => word.text.split(/\s+/).some(isDangerousVerb));
+}
+
+function pathArgs(args: ShellWord[]): ShellWord[] {
+  return args.filter((word) => !word.text.startsWith("-") && word.text !== "");
+}
+
+function checkShell(input: FloorInput): Decision {
+  const command = input.command;
+  if (!command) {
+    return { kind: "allow" };
+  }
+
+  const segments = tokenizeShell(command);
+
+  // invariant: asked before the rest. A fetched program satisfies every other rule by containing nothing this
+  // gate can read, so checking the wrapper first and the payload never is the order that let it through.
+  if (fetchedProgramReachesShell(command, segments)) {
+    return denial(
+      "unprovable-execution",
+      "This runs a program fetched over the network, which does not exist for this gate to check. Download it to a file, read it, then run that file.",
+      "fetched program piped to a shell",
+    );
+  }
+
+  for (const segment of segments) {
+    const head = verbOf(segment.words);
+    if (!head) {
+      continue;
+    }
+    const { verb, args } = head;
+
+    // hazard: `eval "rm -rf /"` and `bash -c "rm -rf /"` build their command at runtime, so the head
+    // word does not describe what will run. Reasoning about the nested quoting is the weak-parser
+    // trap — refuse the segment instead of interpreting it. Scanning words is only sound here: doing
+    // it for any opaque segment flags an `rm` quoted as data somewhere in a long script.
+    if (buildsCommandAtRuntime(verb, args) && hidesDestructiveVerb(segment)) {
+      return denial(
+        "unprovable-destruction",
+        "A destructive verb appears inside a command this gate cannot expand, so its target cannot be established. Run it directly with a literal path instead.",
+        "hidden destructive verb",
+      );
+    }
+
+    if (MACHINE_VERBS.has(verb)) {
+      return denial("machine-control", `\`${verb}\` controls the machine, not the project.`, verb);
+    }
+
+    if (verb === "git" && args.some((word) => word.text === "push")) {
+      const forced = args.some((word) => word.text === "--force" || word.text === "-f");
+      if (forced) {
+        return denial(
+          "history-rewrite",
+          "`git push --force` discards remote commits that are not in your history. Use --force-with-lease, which refuses when the remote moved.",
+          "force push",
+        );
+      }
+    }
+
+    const destructive = DESTRUCTIVE_VERBS.has(verb) || isMkfs(verb);
+    if (!destructive) {
+      continue;
+    }
+
+    const targets = pathArgs(args);
+
+    // hazard: an opaque segment or an unresolved word means the target is unknown. The floor must
+    // prove the target is safe, not prove it is dangerous, so unknown resolves to denied.
+    if (segment.opaque || targets.some((word) => word.unresolved) || targets.length === 0) {
+      return denial(
+        "unprovable-destruction",
+        `\`${verb}\` was called with a target this gate cannot resolve, so its safety cannot be established. Re-run it with a literal path inside the project.`,
+        `unresolvable ${verb}`,
+      );
+    }
+
+    for (const word of targets) {
+      const resolved = resolveTarget(input.projectDir, word.text);
+      if (!isInside(input.projectDir, resolved) && !isScratch(resolved)) {
+        return denial(
+          "outside-project-destruction",
+          `\`${verb}\` targets ${resolved}, which is outside the project and outside scratch space.`,
+          `${verb} outside project`,
+        );
+      }
+    }
+  }
+
+  // hazard: the guard that used to defend this surface keyed off tool names, so a single shell line went
+  // around it. The rule belongs here, where the decision is made before any policy is read.
+  const surface = checkPolicySurface(input.projectDir, command, segments);
+  if (surface.kind === "deny") {
+    // invariant: the remedy comes from the branch that denied, so a read refusal names how to read and a write
+    // refusal names who may write. One fixed tail on both handed write advice to an agent trying to read
+    // ([/decisions/ad-047.md](/decisions/ad-047.md)).
+    const remedy =
+      surface.remedy ??
+      "Set a gate command with `tlc harness gate test-command` or `gate lint-command`, and run policy changes from your own terminal rather than from inside this session.";
+    return denial("policy-surface-write", `${surface.detail} ${remedy}`, surface.note);
+  }
+
+  return checkShellSecrets(segments, input.projectDir);
+}
+
+function checkShellSecrets(segments: ShellSegment[], projectDir: string): Decision {
+  for (const segment of segments) {
+    const head = verbOf(segment.words);
+    if (!head) {
+      continue;
+    }
+    if (NETWORK_VERBS.has(head.verb)) {
+      const target = head.args.map((word) => word.text).join(" ");
+      const endpoint = METADATA_HOSTS.find((host) => target.includes(host));
+      if (endpoint !== undefined) {
+        return denial(
+          "secret-access",
+          `${endpoint} is the instance metadata service, and \`${head.verb}\` would copy the credentials it returns into the transcript.`,
+          `read of ${endpoint}`,
+        );
+      }
+    }
+    if (!READER_VERBS.has(head.verb)) {
+      continue;
+    }
+    for (const word of pathArgs(head.args)) {
+      if (word.unresolved) {
+        continue;
+      }
+      const resolved = resolveTarget(projectDir, word.text);
+      if (isSecretPath(resolved)) {
+        return denial(
+          "secret-access",
+          `\`${head.verb}\` would read ${resolved} into the transcript. Credentials do not belong in an agent's context.`,
+          `read of ${resolved}`,
+        );
+      }
+    }
+  }
+  return { kind: "allow" };
+}
+
+function checkFile(input: FloorInput): Decision {
+  const filePath = input.filePath;
+  if (!filePath) {
+    return { kind: "allow" };
+  }
+  const reads =
+    input.isReadEvent === true || (input.toolName !== undefined && READING_TOOLS.has(input.toolName));
+  if (!reads) {
+    return { kind: "allow" };
+  }
+  const resolved = resolveTarget(input.projectDir, filePath);
+  if (!isSecretPath(resolved)) {
+    return { kind: "allow" };
+  }
+  return denial(
+    "secret-access",
+    `${resolved} holds credentials, and reading it would copy them into the transcript.`,
+    `read of ${resolved}`,
+  );
+}
+
+// invariant: this function takes no policy. Adding a config parameter here would turn the floor into
+// a guardrail, which is the one thing it must not be.
+export function evaluateFloor(input: FloorInput): Decision {
+  const file = checkFile(input);
+  if (file.kind !== "allow") {
+    return file;
+  }
+  return checkShell(input);
+}

package/src/core/floor/floor.tokenize.ts

@@ -0,0 +1,179 @@
+export type ShellWord = {
+  text: string;
+  /** True when the word carries a `$var`, `$(...)` or backtick — its value is not knowable here. */
+  unresolved: boolean;
+  /**
+   * True when the word opened with a quote, so every operator inside it is literal text. A caller looking
+   * for redirects must skip these: `'{"cmd":"x > cfg"}'` is one quoted argument, not a redirect.
+   * Only the opening matters — `>"$f"` starts unquoted and is a real redirect.
+   */
+  quotedStart: boolean;
+};
+
+export type ShellSegment = {
+  words: ShellWord[];
+  /**
+   * True when the segment could not be split with confidence. Which *verbs* defeat inspection is a
+   * policy question and belongs to the caller — this only reports failures of splitting.
+   */
+  opaque: boolean;
+};
+
+const SEPARATORS = new Set([";", "|", "&", "\n"]);
+const ESCAPABLE = new Set([" ", "\t", '"', "'", "$", "`", "\\", ";", "|", "&", "(", ")"]);
+
+function isExpansion(text: string): boolean {
+  return text.includes("$") || text.includes("`");
+}
+
+// hazard: a heredoc body is data being written, not a command list. Tokenizing it invents segments whose
+// head verb never runs, and its quotes make the whole command look unbalanced. It is separated here rather
+// than discarded, because `python3 - <<PY` makes that body the program — a caller that never sees it cannot
+// tell a document from a script.
+/**
+ * A heredoc body, paired with the command text that preceded its `<<TAG` marker. The prefix is what
+ * identifies the verb the body is fed to — without it, a body can only be attributed to the command as a
+ * whole, which mistakes `cat <<EOF ... ; node x` for a program handed to node.
+ */
+export type HeredocChunk = { body: string; prefix: string };
+
+export function splitHeredocs(command: string): { stripped: string; heredocs: HeredocChunk[] } {
+  const heredoc = /<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/;
+  const heredocs: HeredocChunk[] = [];
+  let rest = command;
+  let stripped = "";
+  for (;;) {
+    const match = heredoc.exec(rest);
+    if (!match) {
+      stripped += rest;
+      break;
+    }
+    const bodyStart = rest.indexOf("\n", match.index + match[0].length);
+    const prefix = stripped + rest.slice(0, match.index);
+    stripped += rest.slice(0, match.index);
+    if (bodyStart === -1) {
+      break;
+    }
+    const terminator = new RegExp(`^\\s*${match[2] as string}\\s*$`, "m");
+    const body = rest.slice(bodyStart + 1);
+    const end = terminator.exec(body);
+    if (!end) {
+      heredocs.push({ body, prefix });
+      break;
+    }
+    heredocs.push({ body: body.slice(0, end.index), prefix });
+    rest = body.slice(end.index + end[0].length);
+  }
+  return { stripped, heredocs };
+}
+
+export function heredocChunks(command: string): HeredocChunk[] {
+  return splitHeredocs(command).heredocs;
+}
+
+// invariant: this splits words, it does not evaluate them. Anything it cannot split with confidence
+// is reported as opaque so callers can refuse rather than guess — a wrong split must never read as
+// a safe command.
+export function tokenizeShell(command: string): ShellSegment[] {
+  const segments: ShellSegment[] = [];
+  let words: ShellWord[] = [];
+  let current = "";
+  let currentHadQuote = false;
+  let currentStartedQuoted = false;
+  let quote: '"' | "'" | null = null;
+  let unbalanced = false;
+  let depth = 0;
+
+  function pushWord(): void {
+    if (current !== "" || currentHadQuote) {
+      words.push({
+        text: current,
+        unresolved: isExpansion(current),
+        quotedStart: currentStartedQuoted,
+      });
+    }
+    current = "";
+    currentHadQuote = false;
+    currentStartedQuoted = false;
+  }
+
+  function pushSegment(): void {
+    pushWord();
+    if (words.length > 0) {
+      segments.push({ words, opaque: unbalanced });
+    }
+    words = [];
+  }
+
+  const { stripped } = splitHeredocs(command);
+
+  for (let index = 0; index < stripped.length; index += 1) {
+    const char = stripped[index] as string;
+
+    if (quote !== null) {
+      if (char === quote) {
+        quote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+
+    // hazard: treating every backslash as an escape turned `C:\Users\me\.ssh\id_rsa` into
+    // `C:Usersme.sshid_rsa`, so no Windows path resolved and the secret rule silently passed it.
+    // A backslash only escapes what actually needs escaping; anything else is part of the path.
+    if (char === "\\") {
+      const next = stripped[index + 1];
+      if (next !== undefined && ESCAPABLE.has(next)) {
+        current += next;
+        index += 1;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      quote = char;
+      if (current === "" && !currentHadQuote) {
+        currentStartedQuoted = true;
+      }
+      currentHadQuote = true;
+      continue;
+    }
+
+    // hazard: a separator inside $( ) or ${ } belongs to the substitution, not to the command list.
+    // Splitting there would hand a fragment to the rules and lose the real verb.
+    if (char === "$" && (stripped[index + 1] === "(" || stripped[index + 1] === "{")) {
+      depth += 1;
+      current += char;
+      continue;
+    }
+    if (depth > 0 && (char === ")" || char === "}")) {
+      depth -= 1;
+      current += char;
+      continue;
+    }
+
+    if (depth === 0 && SEPARATORS.has(char)) {
+      pushSegment();
+      continue;
+    }
+
+    if (depth === 0 && (char === " " || char === "\t")) {
+      pushWord();
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (quote !== null || depth > 0) {
+    unbalanced = true;
+  }
+  pushSegment();
+
+  // why: an unbalanced quote is only detectable at the end, so segments split before it were judged
+  // under the wrong assumption. Re-mark the whole list rather than trust those splits.
+  return unbalanced ? segments.map((segment) => ({ ...segment, opaque: true })) : segments;
+}

package/src/core/floor/floor.verb.ts

@@ -0,0 +1,28 @@
+import type { ShellWord } from "./floor.tokenize.ts";
+
+export const WRAPPERS = new Set(["command", "doas", "env", "nice", "nohup", "sudo", "time", "xargs"]);
+
+export type SegmentHead = { verb: string; args: ShellWord[] };
+
+// why: `env FOO=bar cmd` and `sudo -n cmd` both delay the real verb; flags and assignments are skipped.
+export function verbOf(words: ShellWord[]): SegmentHead | null {
+  let index = 0;
+  while (index < words.length) {
+    const word = words[index];
+    if (!word) {
+      return null;
+    }
+    if (WRAPPERS.has(word.text) || word.text.startsWith("-") || word.text.includes("=")) {
+      index += 1;
+      continue;
+    }
+    return { verb: word.text.split("/").pop() ?? word.text, args: words.slice(index + 1) };
+  }
+  return null;
+}
+
+// why: two floor rules need the head verb, and a second copy of the wrapper list would drift from this one
+// the first time a wrapper is added.
+export function firstOperand(args: ShellWord[]): ShellWord | null {
+  return args.find((word) => !word.text.startsWith("-") && word.text !== "") ?? null;
+}

package/src/core/floor/index.ts

@@ -0,0 +1 @@
+export { evaluateFloor, type FloorInput, type FloorRule } from "./floor.service.ts";

package/src/core/gate/gate.artifact.ts

@@ -0,0 +1,157 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { setProjectScopedEnv } from "../../platform/env-scope.ts";
+import { projectStateDir } from "../../platform/paths.ts";
+import { findingsFromLines } from "./gate.findings.ts";
+import { GATE_SCHEMA, type GateFinding, type LastGateArtifact } from "./gate.types.ts";
+
+export const OUTPUT_TAIL_MAX = 8000;
+export const FINDINGS_MAX = 8;
+
+const FAIL_HINT =
+  /(?:\bFAIL(?:ED)?\b|\bERROR\b|Error:|error\[|AssertionError|\bpanic:|✗|×|✕|✖|failures?\s*[:=]\s*[1-9])/i;
+
+export function lastGatePath(root: string): string {
+  return join(projectStateDir(root), "last-gate.json");
+}
+
+export function gateReportPath(root: string): string {
+  return join(projectStateDir(root), "gate-report.json");
+}
+
+export function trimOutputTail(combined: string, max = OUTPUT_TAIL_MAX): string {
+  const text = combined.trim();
+  if (!text) {
+    return "";
+  }
+  return text.length <= max ? text : text.slice(-max);
+}
+
+export function clearGateReport(root: string): void {
+  const path = gateReportPath(root);
+  if (existsSync(path)) {
+    try {
+      unlinkSync(path);
+    } catch {}
+  }
+}
+
+function readJson<T>(path: string): T | null {
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+export function readReportFindings(reportPath: string): GateFinding[] | null {
+  const raw = readJson<unknown>(reportPath);
+  if (!raw || typeof raw !== "object") {
+    return null;
+  }
+  const findings = (raw as { findings?: unknown }).findings;
+  if (!Array.isArray(findings)) {
+    return null;
+  }
+  const out: GateFinding[] = [];
+  for (const item of findings) {
+    if (!item || typeof item !== "object") {
+      continue;
+    }
+    const summary = (item as { summary?: unknown }).summary;
+    if (typeof summary !== "string" || !summary.trim()) {
+      continue;
+    }
+    const detail = (item as { detail?: unknown }).detail;
+    const id = (item as { id?: unknown }).id;
+    out.push({
+      summary: summary.trim().slice(0, 200),
+      detail: typeof detail === "string" ? detail.slice(0, 500) : undefined,
+      id: typeof id === "string" ? id : undefined,
+    });
+    if (out.length >= FINDINGS_MAX) {
+      break;
+    }
+  }
+  return out.length > 0 ? out : null;
+}
+
+// hazard: this used to emit one finding per matched line, so a single failing test arrived as three problems
+// to fix — the assertion header, the test name and the tally `1 fail`. The consumer instructs an agent to fix
+// every item, so grouping is not cosmetic. Matching stays as permissive as before; only what happens to the
+// matched lines changed.
+export function extractFindingsFromOutput(
+  outputTail: string,
+  exitCode: number,
+  max = FINDINGS_MAX,
+): GateFinding[] {
+  const lines = outputTail
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith(">"));
+  const hits = lines.filter((line) => FAIL_HINT.test(line));
+  const picked = hits.length > 0 ? hits : lines.slice(-max);
+  return findingsFromLines(picked, exitCode, max);
+}
+
+export function writeLastGate(args: {
+  root: string;
+  gate: string;
+  exitCode: number;
+  command: string[];
+  files: string[];
+  durationMs: number;
+  output: string;
+  reportPath?: string;
+  inputsHash?: string;
+}): LastGateArtifact {
+  const outputTail = trimOutputTail(args.output);
+  const fromReport = args.reportPath ? readReportFindings(args.reportPath) : null;
+  const emptyOutput = !outputTail || outputTail === "(no output captured)";
+  const findings =
+    fromReport ??
+    (args.exitCode === 0
+      ? []
+      : emptyOutput
+        ? [{ summary: `gate exited with code ${args.exitCode}` }]
+        : extractFindingsFromOutput(outputTail, args.exitCode));
+  const artifact: LastGateArtifact = {
+    schema: GATE_SCHEMA,
+    gate: args.gate,
+    exitCode: args.exitCode,
+    passed: args.exitCode === 0,
+    command: args.command,
+    files: [...args.files],
+    durationMs: args.durationMs,
+    ts: new Date().toISOString(),
+    outputTail,
+    findings,
+    // invariant: read here rather than passed in, so every gate records it and a gate added later cannot forget.
+    // Core never spells a variable name — `platform/env-scope.ts` owns the list, because `check-boundaries`
+    // forbids a vendor identifier under `core/` ([/decisions/ad-060.md](/decisions/ad-060.md)).
+    scopedEnv: setProjectScopedEnv(),
+    ...(args.inputsHash ? { inputsHash: args.inputsHash } : {}),
+  };
+  const path = lastGatePath(args.root);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(artifact, null, 2)}\n`, "utf8");
+  return artifact;
+}
+
+export function readLastGate(root: string): LastGateArtifact | null {
+  return readJson<LastGateArtifact>(lastGatePath(root));
+}
+
+export function computeGateFingerprint(artifact: LastGateArtifact): string {
+  const raw = JSON.stringify({
+    gate: artifact.gate,
+    exitCode: artifact.exitCode,
+    files: [...artifact.files].sort(),
+    findings: artifact.findings.map((f) => f.summary).sort(),
+  });
+  return createHash("sha256").update(raw).digest("hex").slice(0, 16);
+}