@jwilger/pi-development-system 0.5.0 → 0.7.0

package/extensions/development-system.ts

@@ -4,7 +4,9 @@ import { appendContextTail, renderContextTail } from "../src/context/context-tai
 import { renderStatus, renderStatusLine, STATUS_KEY } from "../src/context/status.ts";
 import { applyPromptSection } from "../src/context/system-prompt.ts";
 import { createApprovalStore } from "../src/gates/approvals.ts";
+import { registerCommitGuard } from "../src/gates/commit-guard.ts";
 import { registerGitGuard } from "../src/gates/git-guard.ts";
+import { registerPushGuard } from "../src/gates/push-guard.ts";
 import { createRecordDepartureTool } from "../src/gates/record-departure-tool.ts";
 import { createRequestApprovalTool } from "../src/gates/request-approval-tool.ts";
 import { registerTestGuard } from "../src/gates/test-guard.ts";
@@ -58,6 +60,19 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   });
 
   registerGitGuard({ pi, approvals, jev: (ctx) => jevHolder.forContext(ctx) });
+  registerCommitGuard({
+    pi,
+    state,
+    jev: (ctx) => jevHolder.forContext(ctx),
+    exec: (command, args, options) => pi.exec(command, args, options),
+  });
+  registerPushGuard({
+    pi,
+    state,
+    approvals,
+    jev: (ctx) => jevHolder.forContext(ctx),
+    exec: (command, args, options) => pi.exec(command, args, options),
+  });
   registerTestGuard({ pi, state, approvals, jev: (ctx) => jevHolder.forContext(ctx) });
   pi.registerTool(createRecordDepartureTool({ pi, state }));
   pi.registerTool(createRequestApprovalTool({ pi, approvals }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"

package/src/core/commit-command.ts

@@ -0,0 +1,114 @@
+import { splitLines } from "./git-intent.ts";
+import { parseShell } from "./shell-parse.ts";
+
+export type CommitExtraction =
+  | { readonly kind: "not-commit" }
+  | { readonly kind: "message"; readonly message: string }
+  | { readonly kind: "file"; readonly path: string }
+  | { readonly kind: "unknown" };
+
+const HEREDOC =
+  /<<-?[ \t]*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1[^\n]*\n([\s\S]*?)\n[ \t]*\2[ \t]*(?:\n|$)/g;
+const GLOBAL_WITH_VALUE = new Set(["-c", "-C", "--git-dir", "--work-tree", "--namespace"]);
+
+/** Heredoc bodies are data: take them out so their quotes cannot confuse line splitting. */
+function stripHeredocs(command: string): { rest: string; bodies: string[] } {
+  const bodies: string[] = [];
+  const rest = command.replace(HEREDOC, (_all, _quote, _tag, body: string) => {
+    bodies.push(body);
+    return "\n";
+  });
+  return { rest, bodies };
+}
+
+function segmentsOf(line: string): string[][] {
+  const out: string[][] = [[]];
+  for (const t of parseShell(line, (name) => `$${name}`)) {
+    if (typeof t === "string") out.at(-1)?.push(t);
+    else if ("op" in t && /^[<>]/.test(t.op)) continue;
+    else if (!("comment" in t)) out.push([]);
+  }
+  return out.filter((s) => s.length > 0);
+}
+
+const WRAPPERS = new Set(["command", "sudo", "env", "time", "nohup", "exec", "builtin", "nice"]);
+const isAssignment = (w: string): boolean => /^[A-Za-z_][A-Za-z0-9_]*=/.test(w);
+const isGit = (w: string): boolean => w === "git" || w.endsWith("/git");
+
+/** Index of the word after `git [global options]`, when this segment's command is git. */
+function subcommandIndex(segment: readonly string[]): number | undefined {
+  const start = segment.findIndex((w) => !isAssignment(w) && !WRAPPERS.has(w));
+  if (start === -1 || !isGit(segment[start] ?? "")) return undefined;
+  let skipNext = false;
+  for (let i = start + 1; i < segment.length; i++) {
+    const w = segment[i] ?? "";
+    if (skipNext) skipNext = false;
+    else if (GLOBAL_WITH_VALUE.has(w)) skipNext = true;
+    else if (!w.startsWith("-")) return i;
+  }
+  return undefined;
+}
+
+type Options = {
+  messages: string[];
+  trailers: string[];
+  file: string | undefined;
+  opaque: boolean;
+};
+
+function readOptions(args: readonly string[]): Options {
+  const options: Options = { messages: [], trailers: [], file: undefined, opaque: false };
+  const take = (value: string | undefined) => {
+    if (value === undefined || /\$\(|`/.test(value)) options.opaque = true;
+    else options.messages.push(value);
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i] ?? "";
+    if (a === "-m" || a === "--message") take(args[++i]);
+    else if (a.startsWith("--message=")) take(a.slice("--message=".length));
+    else if (a === "-F" || a === "--file") options.file = args[++i];
+    else if (a.startsWith("--file=")) options.file = a.slice("--file=".length);
+    else if (a === "--trailer") options.trailers.push(args[++i] ?? "");
+    else if (a.startsWith("--trailer=")) options.trailers.push(a.slice("--trailer=".length));
+    else if (/^-[A-Za-z]*m$/.test(a)) take(args[++i]);
+    else if (/^-[A-Za-z]*m./.test(a)) take(a.slice(a.indexOf("m") + 1));
+  }
+  return options;
+}
+
+/** The commit message a `git commit` shell command will use, or why it cannot be known. */
+export function extractCommit(command: string): CommitExtraction {
+  const { rest, bodies } = stripHeredocs(command);
+  const heredoc = bodies[0]?.trim();
+  for (const line of splitLines(rest)) {
+    for (const segment of segmentsOf(line)) {
+      const at = subcommandIndex(segment);
+      if (at === undefined || segment[at] !== "commit") continue;
+      const options = readOptions(segment.slice(at + 1));
+      if (options.file === "-" && heredoc !== undefined)
+        return { kind: "message", message: heredoc };
+      if (options.file !== undefined) return { kind: "file", path: options.file };
+      if (options.opaque) {
+        return heredoc === undefined ? { kind: "unknown" } : { kind: "message", message: heredoc };
+      }
+      if (options.messages.length === 0) return { kind: "unknown" };
+      const trailers = options.trailers.length === 0 ? "" : `\n\n${options.trailers.join("\n")}`;
+      return { kind: "message", message: `${options.messages.join("\n\n")}${trailers}` };
+    }
+  }
+  return { kind: "not-commit" };
+}
+
+export type GitInvocation = { readonly sub: string; readonly args: readonly string[] };
+
+/** Every `git <sub> <args…>` simple command in a shell command string (heredoc bodies excluded). */
+export function gitInvocations(command: string): GitInvocation[] {
+  const { rest } = stripHeredocs(command);
+  return splitLines(rest).flatMap((line) =>
+    segmentsOf(line).flatMap((segment): GitInvocation[] => {
+      const at = subcommandIndex(segment);
+      const sub = at === undefined ? undefined : segment[at];
+      return at === undefined || sub === undefined ? [] : [{ sub, args: segment.slice(at + 1) }];
+    }),
+  );
+}

package/src/core/commit-message.ts

@@ -0,0 +1,105 @@
+import { err, ok, type Result } from "./result.ts";
+import { type ParseError, parseError } from "./types.ts";
+
+type Trailer = { readonly key: string; readonly value: string };
+
+export type ParsedCommit = {
+  readonly type: string;
+  readonly scope: string | undefined;
+  readonly breaking: boolean;
+  readonly subject: string;
+  readonly body: string;
+  readonly trailers: readonly Trailer[];
+};
+
+const SUBJECT = /^([a-z]+)(?:\(([^()\s][^()]*)\))?(!)?: (\S.*)$/;
+const TRAILER = /^([A-Za-z][A-Za-z-]*|BREAKING CHANGE)(?:: | #)(.*)$/;
+
+const withoutComments = (message: string): string =>
+  message
+    .split("\n")
+    .filter((line) => !line.startsWith("#"))
+    .join("\n")
+    .trim();
+
+const paragraphs = (text: string): string[] =>
+  text
+    .split(/\n\s*\n/)
+    .map((p) => p.trim())
+    .filter((p) => p !== "");
+
+const trailerBlock = (parts: readonly string[]): Trailer[] | undefined => {
+  const last = parts.at(-1);
+  if (last === undefined) return undefined;
+  const lines = last.split("\n");
+  const parsed = lines.map((line) => TRAILER.exec(line));
+  if (parsed.some((m) => m === null)) return undefined;
+  return parsed.flatMap((m) =>
+    m === null ? [] : [{ key: m[1] ?? "", value: (m[2] ?? "").trim() }],
+  );
+};
+
+/** Splits a message into subject, body paragraphs and the trailing trailer block. */
+function split(message: string): { subject: string; body: string[]; trailers: Trailer[] } {
+  const parts = paragraphs(withoutComments(message));
+  const subject = parts[0] ?? "";
+  const rest = parts.slice(1);
+  const trailers = trailerBlock(rest);
+  return {
+    subject,
+    body: trailers === undefined ? rest : rest.slice(0, -1),
+    trailers: trailers ?? [],
+  };
+}
+
+export function parseConventionalCommit(message: string): Result<ParsedCommit, ParseError> {
+  const { subject, body, trailers } = split(message);
+  const m = SUBJECT.exec(subject.split("\n")[0] ?? "");
+  if (m === null) {
+    return err(
+      parseError(
+        `"${subject.split("\n")[0] ?? ""}" is not a Conventional Commit subject: type(scope)!: subject`,
+      ),
+    );
+  }
+  return ok({
+    type: m[1] ?? "",
+    scope: m[2],
+    breaking: m[3] === "!" || trailers.some((t) => t.key === "BREAKING CHANGE"),
+    subject: m[4] ?? "",
+    body: body.join("\n\n"),
+    trailers,
+  });
+}
+
+const FORBIDDEN_KEYS = ["co-authored-by", "generated-by"];
+const AI_NAMES = /\b(ai|claude|copilot|codex|gpt|chatgpt|openai|anthropic|gemini|llm)\b/i;
+const GENERATED_BANNER = /generated with/i;
+
+/** Lines of the message that carry an AI attribution trailer (non-negotiable 8). */
+export function findForbiddenTrailers(
+  message: string,
+  extraKeys: readonly string[] = [],
+): string[] {
+  const keys = [...FORBIDDEN_KEYS, ...extraKeys.map((k) => k.toLowerCase())];
+  return withoutComments(message)
+    .split("\n")
+    .filter((line) => {
+      const trimmed = line.trim();
+      const key = /^([A-Za-z][A-Za-z-]*):/.exec(trimmed)?.[1]?.toLowerCase();
+      if (key !== undefined && keys.includes(key)) return true;
+      if (key === "signed-off-by") return AI_NAMES.test(trimmed);
+      return GENERATED_BANNER.test(trimmed) && AI_NAMES.test(trimmed);
+    });
+}
+
+const isBullets = (paragraph: string): boolean =>
+  paragraph.split("\n").every((line) => /^\s*(?:[-*+]|\d+[.)])\s/.test(line));
+
+const wordCount = (text: string): number => text.split(/\s+/).filter((w) => w !== "").length;
+
+/** A body needs at least one prose paragraph (not a file list) that says more than a few words. */
+export function hasRationaleBody(message: string): boolean {
+  const { body } = split(message);
+  return body.some((paragraph) => !isBullets(paragraph) && wordCount(paragraph) >= 5);
+}

package/src/core/exec.ts

@@ -0,0 +1,6 @@
+/** Runs a program; `pi.exec` satisfies this, tests pass a fake. */
+export type Exec = (
+  command: string,
+  args: string[],
+  options?: { cwd?: string; timeout?: number },
+) => Promise<{ code: number; stdout: string; stderr: string }>;

package/src/core/gates.ts

@@ -19,8 +19,8 @@ export const GATES: Readonly<Record<string, GateInfo>> = {
     default: "structural and behavioural changes go in separate commits",
   },
   "commit.forbidden-trailer": { tier: "soft", default: "no Co-Authored-By or AI trailers" },
-  "push.red-trunk": { tier: "soft", default: "do not push unrelated work onto a red trunk" },
-  "push.delivery-mode": { tier: "soft", default: "follow the repository's delivery mode" },
+  "push.red-trunk": { tier: "hard", default: "do not push unrelated work onto a red trunk" },
+  "push.delivery-mode": { tier: "hard", default: "follow the repository's delivery mode" },
   "tdd.red-first": { tier: "soft", default: "write a failing test before changing behaviour" },
   "lints.suppression": { tier: "soft", default: "do not suppress lints without a reasoned note" },
   "review.unsatisfied": { tier: "soft", default: "finish the fresh-context review before release" },

package/src/core/git-intent.ts

@@ -24,7 +24,7 @@ const worst = (a: GitIntent, b: GitIntent): GitIntent =>
   SEVERITY.indexOf(a) <= SEVERITY.indexOf(b) ? a : b;
 
 /** Splits a command string on newlines that are outside quotes; backslash-newline is a continuation. */
-function splitLines(command: string): string[] {
+export function splitLines(command: string): string[] {
   const lines: string[] = [];
   let current = "";
   let quote: "'" | '"' | undefined;

package/src/core/push-command.ts

@@ -0,0 +1,36 @@
+import { gitInvocations } from "./commit-command.ts";
+
+export type PushTarget = {
+  readonly remote: string | undefined;
+  /** Destination branch names named by refspecs; empty means "the current branch's default". */
+  readonly branches: readonly string[];
+  readonly allBranches: boolean;
+};
+
+const VALUE_OPTIONS = new Set(["--repo", "-o", "--push-option", "--receive-pack", "--exec"]);
+
+const destination = (refspec: string): string => {
+  const dst = refspec.includes(":") ? refspec.slice(refspec.lastIndexOf(":") + 1) : refspec;
+  return dst.replace(/^\+/, "").replace(/^refs\/heads\//, "");
+};
+
+/** The remote and branches of every `git push` in a command (empty list when there is no push). */
+export function pushTargets(command: string): PushTarget[] {
+  return gitInvocations(command).flatMap((g): PushTarget[] => {
+    if (g.sub !== "push") return [];
+    const positional: string[] = [];
+    let allBranches = false;
+    for (let i = 0; i < g.args.length; i++) {
+      const a = g.args[i] ?? "";
+      if (VALUE_OPTIONS.has(a)) i++;
+      else if (a === "--all" || a === "--mirror") allBranches = true;
+      else if (!a.startsWith("-")) positional.push(a);
+    }
+    const [remote, ...refspecs] = positional;
+    const branches = refspecs.flatMap((r) => {
+      const b = destination(r);
+      return b === "HEAD" || b === "" ? [] : [b];
+    });
+    return [{ remote, branches, allBranches }];
+  });
+}

package/src/gates/commit-guard.ts

@@ -0,0 +1,136 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  type ExtensionAPI,
+  type ExtensionContext,
+  isToolCallEventType,
+} from "@earendil-works/pi-coding-agent";
+import { extractCommit } from "../core/commit-command.ts";
+import {
+  findForbiddenTrailers,
+  hasRationaleBody,
+  parseConventionalCommit,
+} from "../core/commit-message.ts";
+import type { Exec } from "../core/exec.ts";
+import { type GateId, isParseError, parseGateId } from "../core/types.ts";
+import type { Jev } from "../jev/client.ts";
+import { judgeCommit, MIX_THRESHOLD, RATIONALE_FLOOR } from "../jev/questions/commit.ts";
+import type { SessionState } from "../state/session-state.ts";
+import { departureUse } from "./departure-use.ts";
+
+export type CommitGuardDeps = {
+  pi: ExtensionAPI;
+  state: SessionState;
+  jev: (ctx: ExtensionContext) => Jev;
+  exec: Exec;
+};
+
+type Need = { gate: GateId; why: string };
+
+const gateId = (id: string): GateId => {
+  const parsed = parseGateId(id);
+  if (isParseError(parsed)) throw new Error(parsed.message);
+  return parsed;
+};
+
+const RATIONALE = gateId("commit.rationale");
+const MIXED = gateId("commit.mixed-change");
+
+const readMessageFile = (cwd: string, path: string): string | undefined => {
+  try {
+    return readFileSync(join(cwd, path), "utf8");
+  } catch {
+    return undefined;
+  }
+};
+
+/** Deterministic checks: Conventional subject and a prose rationale body. */
+function messageNeeds(message: string): Need[] {
+  const parsed = parseConventionalCommit(message);
+  if (!parsed.ok) return [{ gate: RATIONALE, why: parsed.error.message }];
+  return hasRationaleBody(message)
+    ? []
+    : [{ gate: RATIONALE, why: "the message has no body explaining why the change was made" }];
+}
+
+/** What is about to be committed, as far as the working tree shows (staged and unstaged tracked changes). */
+async function pendingDiff(
+  exec: Exec,
+  cwd: string,
+): Promise<{ stat: string; diff: string } | undefined> {
+  const [stat, diff] = await Promise.all([
+    exec("git", ["diff", "HEAD", "--stat"], { cwd, timeout: 10_000 }),
+    exec("git", ["diff", "HEAD"], { cwd, timeout: 10_000 }),
+  ]);
+  if (stat.code !== 0 || diff.code !== 0 || diff.stdout.trim() === "") return undefined;
+  return { stat: stat.stdout, diff: diff.stdout };
+}
+
+async function jevNeeds(
+  deps: CommitGuardDeps,
+  ctx: ExtensionContext,
+  message: string,
+  bodyPresent: boolean,
+): Promise<Need[]> {
+  const pending = await pendingDiff(deps.exec, ctx.cwd);
+  if (pending === undefined) return [];
+  const judged = await judgeCommit(deps.jev(ctx), {
+    message,
+    diffStat: pending.stat,
+    diff: pending.diff,
+  });
+  if (!judged.ok) return [];
+  const needs: Need[] = [];
+  if (bodyPresent && judged.value.rationale < RATIONALE_FLOOR) {
+    needs.push({ gate: RATIONALE, why: "Jev reads the body as restating what changed, not why" });
+  }
+  if (judged.value.mixesStructuralAndBehavioural >= MIX_THRESHOLD) {
+    needs.push({
+      gate: MIXED,
+      why: "Jev reads this diff as mixing a structural change with a behavioural one",
+    });
+  }
+  return needs;
+}
+
+const blockReason = (need: Need): string =>
+  `${need.gate}: ${need.why}. Commit messages carry their rationale and structural and behavioural ` +
+  "changes go in separate commits. Fix the commit (split it, or write the why in the body), or if " +
+  `departing is deliberate call devsys_record_departure with gate "${need.gate}", what you are doing ` +
+  "instead, why, and the cost if wrong; then retry.";
+
+/** Soft gates on `git commit`: rationale, Conventional shape, structural/behavioural separation; AI trailers are refused. */
+export function registerCommitGuard(deps: CommitGuardDeps): void {
+  deps.pi.on("tool_call", async (event, ctx) => {
+    if (!isToolCallEventType("bash", event)) return undefined;
+    const extracted = extractCommit(event.input.command);
+    const message =
+      extracted.kind === "message"
+        ? extracted.message
+        : extracted.kind === "file"
+          ? readMessageFile(ctx.cwd, extracted.path)
+          : undefined;
+    if (message === undefined) return undefined;
+
+    const forbidden = findForbiddenTrailers(message);
+    if (forbidden.length > 0) {
+      return {
+        block: true,
+        reason:
+          `commit.forbidden-trailer: this message carries an AI attribution (${forbidden.join("; ")}). ` +
+          "Commits in this repository have no Co-Authored-By or generated-by trailers and this is not " +
+          "something to depart from. Remove the trailer and commit again.",
+      };
+    }
+
+    const needs = messageNeeds(message);
+    const bodyPresent = !needs.some((n) => n.why.startsWith("the message has no body"));
+    const viaJev = await jevNeeds(deps, ctx, message, bodyPresent);
+    const all = [...needs, ...viaJev.filter((n) => !needs.some((m) => m.gate === n.gate))];
+    const uses = all.map((need) => ({ need, use: departureUse(deps.state, need.gate) }));
+    const uncovered = uses.find(({ use }) => !use.hasOpen());
+    if (uncovered !== undefined) return { block: true, reason: blockReason(uncovered.need) };
+    for (const { use } of uses) use.consume();
+    return undefined;
+  });
+}

package/src/gates/departure-use.ts

@@ -0,0 +1,28 @@
+import type { GateId } from "../core/types.ts";
+import type { SessionState } from "../state/session-state.ts";
+
+/** Open recorded departures for one soft gate: whether one applies now, and spending a once-scoped one. */
+export type DepartureUse = { hasOpen(): boolean; consume(): void };
+
+export function departureUse(state: SessionState, gate: GateId): DepartureUse {
+  const applicable = () => {
+    const { openDepartures, activeSlice } = state.get();
+    return openDepartures.filter(
+      (d) => d.gate === gate && (d.scope.kind !== "slice" || d.scope.slice === activeSlice),
+    );
+  };
+  return {
+    hasOpen: () => applicable().length > 0,
+    consume() {
+      const open = applicable();
+      // A broader departure covers the call without being spent; only a lone once-scoped one is used up.
+      if (open.some((d) => d.scope.kind !== "once")) return;
+      const used = open[0];
+      if (used === undefined) return;
+      state.update((s) => ({
+        ...s,
+        openDepartures: s.openDepartures.filter((d) => d.id !== used.id),
+      }));
+    },
+  };
+}

package/src/gates/push-guard.ts

@@ -0,0 +1,168 @@
+import {
+  type ExtensionAPI,
+  type ExtensionContext,
+  isBashToolResult,
+  isToolCallEventType,
+} from "@earendil-works/pi-coding-agent";
+import { parseConventionalCommit } from "../core/commit-message.ts";
+import type { Exec } from "../core/exec.ts";
+import { type PushTarget, pushTargets } from "../core/push-command.ts";
+import { type GateId, isParseError, parseGateId } from "../core/types.ts";
+import type { Jev } from "../jev/client.ts";
+import { FIX_RELATED_THRESHOLD, judgeFixRelated } from "../jev/questions/fix-related.ts";
+import { getFailureLog, getTrunkStatus } from "../state/ci.ts";
+import { type DevsysConfig, loadConfig } from "../state/config.ts";
+import type { SessionState } from "../state/session-state.ts";
+import { type ApprovalStore, requestHardStop } from "./approvals.ts";
+
+export type PushGuardDeps = {
+  pi: ExtensionAPI;
+  state: SessionState;
+  approvals: ApprovalStore;
+  jev: (ctx: ExtensionContext) => Jev;
+  exec: Exec;
+  now?: () => Date;
+};
+
+type Verdict = { readonly block: true; readonly reason: string } | undefined;
+
+const gate = (id: string): GateId => {
+  const parsed = parseGateId(id);
+  if (isParseError(parsed)) throw new Error(parsed.message);
+  return parsed;
+};
+const RED_TRUNK = gate("push.red-trunk");
+const DELIVERY_MODE = gate("push.delivery-mode");
+
+async function currentBranch(exec: Exec, cwd: string): Promise<string | undefined> {
+  const r = await exec("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd, timeout: 5000 });
+  const name = r.code === 0 ? r.stdout.trim() : "";
+  return name === "" || name === "HEAD" ? undefined : name;
+}
+
+async function pushesTrunk(
+  exec: Exec,
+  cwd: string,
+  targets: readonly PushTarget[],
+  trunk: string,
+): Promise<boolean> {
+  for (const t of targets) {
+    if (t.allBranches || t.branches.includes(trunk)) return true;
+    if (t.branches.length === 0 && (await currentBranch(exec, cwd)) === trunk) return true;
+  }
+  return false;
+}
+
+/** Whether the unpushed work is a `fix` commit whose diff Jev reads as only repairing the red build. */
+async function repairsRedTrunk(
+  deps: PushGuardDeps,
+  ctx: ExtensionContext,
+  config: DevsysConfig,
+): Promise<boolean> {
+  const message = await deps.exec("git", ["log", "-1", "--format=%B"], {
+    cwd: ctx.cwd,
+    timeout: 5000,
+  });
+  const parsed = parseConventionalCommit(message.stdout);
+  if (message.code !== 0 || !parsed.ok || parsed.value.type !== "fix") return false;
+  const range = `${config.delivery.remote}/${config.delivery.trunk}..HEAD`;
+  const diff = await deps.exec("git", ["diff", range], { cwd: ctx.cwd, timeout: 10_000 });
+  if (diff.code !== 0 || diff.stdout.trim() === "") return false;
+  const judged = await judgeFixRelated(deps.jev(ctx), {
+    diff: diff.stdout,
+    failingLog: await getFailureLog(deps.exec, ctx.cwd),
+    message: message.stdout,
+  });
+  return judged.ok && judged.value >= FIX_RELATED_THRESHOLD;
+}
+
+type HardStop = {
+  readonly ctx: ExtensionContext;
+  readonly toolCallId: string;
+  readonly command: string;
+  readonly gate: GateId;
+  readonly why: string;
+  readonly costIfWrong: string;
+};
+
+const declinedAdvice = (which: GateId): string =>
+  which === RED_TRUNK ? "fix the red build first" : "open a pull request instead";
+
+async function hardStop(deps: PushGuardDeps, stop: HardStop): Promise<Verdict> {
+  const { gate: which, command } = stop;
+  if (deps.approvals.consume(which, command)) return undefined;
+  const outcome = await requestHardStop({
+    pi: deps.pi,
+    ctx: stop.ctx,
+    gate: which,
+    command,
+    why: stop.why,
+    toolCallId: stop.toolCallId,
+    costIfWrong: stop.costIfWrong,
+    now: deps.now,
+  });
+  if (outcome.kind === "approved") return undefined;
+  if (outcome.kind === "unavailable") {
+    return {
+      block: true,
+      reason: `hard stop ${which}: ${stop.why}. Requires user approval; run interactively`,
+    };
+  }
+  return {
+    block: true,
+    reason: `hard stop ${which}: the user declined this push. Do not retry it; ${declinedAdvice(which)}.`,
+  };
+}
+
+/** Delivery-mode and red-trunk hard stops on `git push`; records when a push last succeeded. */
+export function registerPushGuard(deps: PushGuardDeps): void {
+  deps.pi.on("tool_call", async (event, ctx) => {
+    if (!isToolCallEventType("bash", event)) return undefined;
+    const targets = pushTargets(event.input.command);
+    if (targets.length === 0) return undefined;
+    const loaded = await loadConfig(ctx.cwd);
+    if (!loaded.ok) {
+      return { block: true, reason: `cannot read the delivery policy: ${loaded.error.message}` };
+    }
+    const { mode, trunk } = loaded.value.delivery;
+    if (mode === "local-only") {
+      return {
+        block: true,
+        reason: `delivery.mode is "local-only" in .development-system.toml: nothing is pushed. Change the mode with the user if this should be published.`,
+      };
+    }
+    if (!(await pushesTrunk(deps.exec, ctx.cwd, targets, trunk))) return undefined;
+    const command = event.input.command;
+    if (mode === "pull-request") {
+      return hardStop(deps, {
+        ctx,
+        toolCallId: event.toolCallId,
+        command,
+        gate: DELIVERY_MODE,
+        why: `delivery.mode is "pull-request" but this pushes ${trunk}`,
+        costIfWrong: "unreviewed work lands directly on the trunk",
+      });
+    }
+    const status = await getTrunkStatus(deps.exec, { branch: trunk, cwd: ctx.cwd });
+    if (status.status !== "red") return undefined;
+    if (await repairsRedTrunk(deps, ctx, loaded.value)) return undefined;
+    return hardStop(deps, {
+      ctx,
+      toolCallId: event.toolCallId,
+      command,
+      gate: RED_TRUNK,
+      why: `CI on ${trunk} is red (${status.headSha?.slice(0, 7) ?? "unknown sha"}) and this push is not a recognised fix for it`,
+      costIfWrong: "unrelated work piles onto a broken build and hides the failure",
+    });
+  });
+
+  deps.pi.on("tool_result", (event) => {
+    if (!isBashToolResult(event) || event.isError) return undefined;
+    if (pushTargets(String(event.input.command)).length === 0) return undefined;
+    deps.state.update((s) => ({
+      ...s,
+      lastPushAt: (deps.now ?? (() => new Date()))().toISOString(),
+    }));
+    return undefined;
+  });
+}

package/src/gates/test-guard.ts

@@ -23,6 +23,7 @@ import type { Jev } from "../jev/client.ts";
 import { judgeTestChange, WEAKENS_THRESHOLD } from "../jev/questions/test-change.ts";
 import type { SessionState } from "../state/session-state.ts";
 import { type ApprovalStore, requestHardStop } from "./approvals.ts";
+import { departureUse } from "./departure-use.ts";
 
 export type TestGuardDeps = {
   pi: ExtensionAPI;
@@ -110,27 +111,7 @@ export function registerTestGuard(deps: TestGuardDeps): void {
   })();
   if (gate === undefined) return;
 
-  const hasOpenDeparture = (): boolean => {
-    const { openDepartures, activeSlice } = deps.state.get();
-    return openDepartures.some(
-      (d) => d.gate === gate && (d.scope.kind !== "slice" || d.scope.slice === activeSlice),
-    );
-  };
-
-  const consumeOpenDeparture = (): void => {
-    const { openDepartures, activeSlice } = deps.state.get();
-    const applicable = openDepartures.filter(
-      (d) => d.gate === gate && (d.scope.kind !== "slice" || d.scope.slice === activeSlice),
-    );
-    // A broader departure covers the call without being spent; only a lone once-scoped one is used up.
-    if (applicable.some((d) => d.scope.kind !== "once")) return;
-    const used = applicable[0];
-    if (used === undefined) return;
-    deps.state.update((s) => ({
-      ...s,
-      openDepartures: s.openDepartures.filter((d) => d.id !== used.id),
-    }));
-  };
+  const departure = departureUse(deps.state, gate);
 
   const judge = async (change: Change, ctx: ExtensionContext): Promise<Verdict> => {
     const deleted = change.after === undefined && change.rewritten === undefined;
@@ -225,9 +206,9 @@ export function registerTestGuard(deps: TestGuardDeps): void {
     );
     const first = needing[0];
     if (first === undefined) return undefined;
-    if (hasOpenDeparture()) {
+    if (departure.hasOpen()) {
       // One departure covers every path in this single tool call.
-      consumeOpenDeparture();
+      departure.consume();
       return undefined;
     }
     return {

package/src/jev/questions/commit.ts

@@ -0,0 +1,62 @@
+import type { ClassifierBoolQuestion } from "@earendil-works/pi-ai";
+import { redactSecrets } from "../../core/redact.ts";
+import { err, ok, type Result } from "../../core/result.ts";
+import type { Jev, JevError } from "../client.ts";
+
+/** At or above this, the commit is treated as mixing structural and behavioural change. */
+export const MIX_THRESHOLD = 0.7;
+/** Below this a message that has a body is still treated as not carrying its rationale. */
+export const RATIONALE_FLOOR = 0.3;
+
+export type CommitInput = { message: string; diffStat: string; diff: string };
+export type CommitJudgement = { rationale: number; mixesStructuralAndBehavioural: number };
+
+const DIFF_CLIP = 8000;
+
+export const RATIONALE_QUESTION: ClassifierBoolQuestion = {
+  type: "bool",
+  instructions:
+    "Read the commit `message` in light of the change in `diffStat` and `diff`. Does the message explain WHY the change was made (the problem, constraint, decision or trade-off), rather than only restating WHAT changed?",
+  criteria: {
+    true: "The body gives a reason: the problem solved, the constraint, the alternative rejected or the trade-off accepted",
+    false:
+      "The message only names or lists what changed (file names, 'update X', 'fix bug', bullet list of edits) with no reason",
+  },
+};
+
+export const MIX_QUESTION: ClassifierBoolQuestion = {
+  type: "bool",
+  instructions:
+    "Does the change in `diffStat` and `diff` combine a structural change (rename, move, extract, reformat, dependency or config tidying that does not alter behaviour) with a behavioural change (new or altered logic, fixed bug, new feature) in the same commit?",
+  criteria: {
+    true: "Both a behaviour-preserving restructuring AND a behaviour change are present in the diff",
+    false:
+      "The diff is only structural, or only behavioural (including a behavioural change with its own tests and a minimal necessary signature tweak)",
+  },
+};
+
+const clip = (text: string, max: number): string => redactSecrets(text).slice(0, max);
+
+export async function judgeCommit(
+  jev: Jev,
+  input: CommitInput,
+): Promise<Result<CommitJudgement, JevError>> {
+  const asked = await jev.ask(
+    {
+      message: clip(input.message, 4000),
+      diffStat: clip(input.diffStat, 2000),
+      diff: clip(input.diff, DIFF_CLIP),
+    },
+    { rationale: RATIONALE_QUESTION, mix: MIX_QUESTION },
+  );
+  if (!asked.ok) return asked;
+  const rationale = asked.value.rationale;
+  const mix = asked.value.mix;
+  if (rationale?.type !== "bool" || mix?.type !== "bool") {
+    return err({ kind: "provider", message: "missing commit answers" });
+  }
+  return ok({
+    rationale: rationale.probability,
+    mixesStructuralAndBehavioural: mix.probability,
+  });
+}

package/src/jev/questions/fix-related.ts

@@ -0,0 +1,37 @@
+import type { ClassifierBoolQuestion } from "@earendil-works/pi-ai";
+import { redactSecrets } from "../../core/redact.ts";
+import { err, ok, type Result } from "../../core/result.ts";
+import type { Jev, JevError } from "../client.ts";
+
+/** At or above this, the unpushed change is treated as a fix for the red build. */
+export const FIX_RELATED_THRESHOLD = 0.6;
+
+export const FIX_RELATED_QUESTION: ClassifierBoolQuestion = {
+  type: "bool",
+  instructions:
+    "Is every change in `diff` plausibly part of fixing the failure shown in `failingLog`? Answer false if the diff contains unrelated changes such as new features, refactors or behaviour changes that the failure does not call for.",
+  criteria: {
+    true: "The diff only touches what is needed to repair the failing build or test",
+    false:
+      "The diff includes work the failure does not call for (features, refactors, unrelated fixes)",
+  },
+};
+
+export async function judgeFixRelated(
+  jev: Jev,
+  input: { diff: string; failingLog: string; message: string },
+): Promise<Result<number, JevError>> {
+  const asked = await jev.ask(
+    {
+      failingLog: redactSecrets(input.failingLog).slice(-4000),
+      message: redactSecrets(input.message).slice(0, 2000),
+      diff: redactSecrets(input.diff).slice(0, 8000),
+    },
+    { related: FIX_RELATED_QUESTION },
+  );
+  if (!asked.ok) return asked;
+  const answer = asked.value.related;
+  return answer?.type === "bool"
+    ? ok(answer.probability)
+    : err({ kind: "provider", message: "missing fix-related answer" });
+}

package/src/state/ci.ts

@@ -0,0 +1,71 @@
+import type { Exec } from "../core/exec.ts";
+
+export type TrunkStatus = {
+  readonly status: "green" | "red" | "pending" | "unknown";
+  readonly headSha: string | undefined;
+};
+
+const UNKNOWN: TrunkStatus = { status: "unknown", headSha: undefined };
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+const FAILED = new Set(["failure", "timed_out", "startup_failure", "action_required"]);
+
+/** Parses `gh run list --json status,conclusion,headSha` output for the newest run. */
+export function parseRunList(stdout: string): TrunkStatus {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return UNKNOWN;
+  }
+  const run = Array.isArray(parsed) ? parsed[0] : undefined;
+  if (!isRecord(run)) return UNKNOWN;
+  const headSha = typeof run.headSha === "string" ? run.headSha : undefined;
+  if (run.status !== "completed") return { status: "pending", headSha };
+  if (run.conclusion === "success") return { status: "green", headSha };
+  if (typeof run.conclusion === "string" && FAILED.has(run.conclusion)) {
+    return { status: "red", headSha };
+  }
+  return { status: "unknown", headSha };
+}
+
+/** CI state of the newest run on the trunk branch; `unknown` whenever `gh` cannot say. */
+export async function getTrunkStatus(
+  exec: Exec,
+  where: { branch: string; cwd?: string },
+): Promise<TrunkStatus> {
+  try {
+    const r = await exec(
+      "gh",
+      [
+        "run",
+        "list",
+        "--branch",
+        where.branch,
+        "--limit",
+        "1",
+        "--json",
+        "status,conclusion,headSha",
+      ],
+      { ...(where.cwd !== undefined ? { cwd: where.cwd } : {}), timeout: 15_000 },
+    );
+    return r.code === 0 ? parseRunList(r.stdout) : UNKNOWN;
+  } catch {
+    return UNKNOWN;
+  }
+}
+
+/** The failing log of the newest failed run, clipped; empty when unavailable. */
+export async function getFailureLog(exec: Exec, cwd: string | undefined): Promise<string> {
+  try {
+    const r = await exec("gh", ["run", "view", "--log-failed"], {
+      ...(cwd !== undefined ? { cwd } : {}),
+      timeout: 30_000,
+    });
+    return r.code === 0 ? r.stdout.slice(-6000) : "";
+  } catch {
+    return "";
+  }
+}