@jwilger/pi-development-system 0.90.0 → 0.91.0

package/README.md

@@ -124,6 +124,19 @@ What the tiers do not cover, so you can decide what to trust:
 - **A departure is the agent's own call.** `devsys_record_departure` waives a soft gate (also with no
   UI) and is written to the decision log; it is never available for a hard stop.
 - **Gating starts at `devsys_intake`.** With no slice open, the review and red-first gates are off.
+- **Command shape is read, not run.** The git guards classify the command text: aliases and
+  `git config` that redirect a later command, shells reading stdin, and `python -c` or `node -e`
+  that mention git are all treated as unclassifiable, so the user decides (headless: refused). A
+  command the classifier cannot see into at all (a script file, another tool) is not covered.
+  Commit messages are checked again at push time against what the remote lacks, so a commit made by
+  `-C`, `--fixup`, `commit-tree` or an alias cannot carry an AI trailer or skip the rationale; a push
+  in the same call as such a commit is refused, because the commit does not exist yet when it is checked.
+- **A push source the shell builds is checked loosely.** `git push origin "$(cat sha)":refs/heads/x`
+  checks every local branch for AI trailers, not the unnamed commit the expression may name (one made
+  with `commit-tree` and on no branch). The unclassified-command prompt is the only stop there.
+- **A push after a ref moves in the same call is checked against the refs as they were.**
+  `git merge --ff-only feature && git push origin main` publishes commits on `feature` that the
+  push check read before the call ran. Make the merge, switch or reset in one call and push in the next.
 - **Editing gate configuration is not guarded** (`biome.json`, hooks, CI files); review catches it.
 
 ## Decision log

package/extensions/development-system.ts

@@ -17,6 +17,7 @@ import { type Exec, timeoutAsFailure } from "../src/core/exec.ts";
 import { defaultMatrix } from "../src/core/models.ts";
 import { createApprovalStore } from "../src/gates/approvals.ts";
 import { registerCommitGuard } from "../src/gates/commit-guard.ts";
+import { createExcusedMessages } from "../src/gates/excused-messages.ts";
 import { declareWithoutCodemode } from "../src/gates/exposure.ts";
 import { registerGitGuard } from "../src/gates/git-guard.ts";
 import { registerLintSuppressionGuard } from "../src/gates/lint-suppression-guard.ts";
@@ -124,11 +125,13 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   const exec: Exec = async (command, args, options) =>
     timeoutAsFailure(await pi.exec(command, args, options));
   registerGitGuard({ pi, approvals, jev: (ctx) => jevHolder.forContext(ctx) });
+  const excused = createExcusedMessages();
   registerCommitGuard({
     pi,
     state,
     jev: (ctx) => jevHolder.forContext(ctx),
     exec,
+    excused,
   });
   registerCiCommand({
     pi,
@@ -141,6 +144,7 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
     approvals,
     jev: (ctx) => jevHolder.forContext(ctx),
     exec,
+    excused,
   });
   registerTestGuard({ pi, state, approvals, jev: (ctx) => jevHolder.forContext(ctx) });
   registerTestEvidence({ pi, state });

package/package.json

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

package/src/core/git-intent.ts

@@ -117,7 +117,7 @@ export const DATA_ONLY = new Set([
   "head",
   "tail",
 ]);
-export const SHELLS = new Set(["bash", "sh", "zsh", "dash", "ksh"]);
+export const SHELLS = new Set(["bash", "sh", "zsh", "dash", "ksh", "fish", "csh", "tcsh"]);
 export const OPAQUE = new Set(["xargs", "ssh", "find", "parallel", "watch"]);
 export const GLOBAL_WITH_VALUE = new Set([
   "-c",
@@ -128,7 +128,72 @@ export const GLOBAL_WITH_VALUE = new Set([
   "--config-env",
   "--super-prefix",
 ]);
-const HOOK_SKIP_ENV = new Set(["LEFTHOOK=0", "HUSKY=0"]);
+
+/** Assignments that switch git hooks off (lefthook, husky), however the value is spelled. */
+const skipsHooks = (word: string): boolean =>
+  /^(LEFTHOOK|HUSKY)=(0|false|no|off)$/i.test(word) ||
+  /^(LEFTHOOK_EXCLUDE|HUSKY_SKIP_HOOKS)=.+/i.test(word);
+/** Assignments that feed git configuration (aliases, hooks path, push targets) from the environment. */
+const setsGitConfig = (word: string): boolean =>
+  /^GIT_CONFIG_[A-Z_0-9]*=/.test(word) ||
+  /^(HOME|XDG_CONFIG_HOME)=/.test(word) || // git reads its global config from there
+  (/^(GIT_(SSH|SSH_COMMAND|EDITOR|SEQUENCE_EDITOR|PAGER|ASKPASS|EXTERNAL_DIFF|PROXY_COMMAND|EXEC_PATH)|EDITOR|VISUAL|PAGER)=/.test(
+    word,
+  ) &&
+    !isBenignProgram(word.slice(word.indexOf("=") + 1)));
+/** A bare program name (`true`, `cat`, `less`) that is neither git, a shell nor an interpreter: it cannot run a push. */
+const isBenignProgram = (value: string): boolean =>
+  /^[\w.+-]+$/.test(value) && !isCommandWord(value);
+/** Builtins that set variables for the commands after them. */
+const ENV_SETTERS = new Set(["export", "declare", "typeset", "readonly", "local"]);
+/** Commands that run another command (or a shell script) given as their arguments. */
+const RUNNERS = new Set([
+  "timeout",
+  "script",
+  "busybox",
+  "setsid",
+  "stdbuf",
+  "ionice",
+  "flock",
+  "doas",
+  "su",
+  "runuser",
+  "xvfb-run",
+  "unbuffer",
+  "strace",
+  "ltrace",
+  "taskset",
+  "chrt",
+  "nsenter",
+  "chroot",
+  "bwrap",
+  "firejail",
+]);
+const INTERPRETERS = /^(python[\d.]*|node(js)?|ruby|perl|php|deno|bun|lua|tclsh|osascript)$/;
+const INLINE_CODE_FLAG = /^(-[A-Za-z]*[cepEr]|--eval|--print|eval)$/;
+/** Paths a program reads its standard input through. */
+const STDIN_PATH = /^(-|\/dev\/stdin|\/dev\/fd\/\d+|\/proc\/(self|\d+)\/fd\/\d+)$/;
+const INFO_FLAG = /^(-[Vh]|--version|--help)$/;
+/** `node -v`, `ruby -v`, `perl -v` print a version; for python `-v` is verbose and still reads stdin. */
+const VERSION_FLAG = /^-v$/;
+
+/** Every subcommand git itself provides; any other word is an alias or an external `git-<word>`. */
+export const GIT_SUBCOMMANDS = new Set(
+  `add am annotate apply archive bisect blame branch bundle cat-file check-attr check-ignore
+  check-ref-format checkout checkout-index cherry cherry-pick citool clean clone column commit
+  commit-graph commit-tree config count-objects credential describe diff diff-files diff-index
+  diff-tree difftool fast-export fast-import fetch fetch-pack filter-branch filter-repo
+  for-each-ref for-each-repo format-patch fsck gc gitk grep gui hash-object help hook index-pack
+  init instaweb interpret-trailers lfs log ls-files ls-remote ls-tree maintenance merge
+  merge-base merge-file merge-index merge-tree mergetool mktag mktree mv name-rev notes pack-objects
+  pack-refs patch-id prune prune-packed pull push range-diff read-tree rebase reflog remote repack
+  replace request-pull rerere reset restore rev-list rev-parse revert rm scalar send-email
+  shortlog show show-branch show-index show-ref sparse-checkout stash status stripspace submodule
+  switch symbolic-ref tag unpack-file unpack-objects update-index update-ref update-server-info
+  var verify-commit verify-pack verify-tag version whatchanged worktree write-tree bugreport diagnose
+  multi-pack-index refs repo mailinfo mailsplit upload-pack receive-pack upload-archive daemon
+  get-tar-commit-id difftool--helper maintenance backfill`.split(/\s+/),
+);
 
 export const basename = (path: string): string => path.slice(path.lastIndexOf("/") + 1);
 export const isAssignment = (t: string): boolean => /^[A-Za-z_][A-Za-z0-9_]*=/.test(t);
@@ -139,9 +204,76 @@ const isLong = (arg: string, ...names: string[]): boolean => {
   return key.length >= 4 && key.startsWith("--") && names.some((n) => n.startsWith(key));
 };
 
+/** Keys whose value git runs as a command: setting one makes a later, harmless-looking command run anything. */
+const RUNS_COMMAND =
+  /^(core\.(sshcommand|editor|pager|fsmonitor|askpass)|diff\.external|sequence\.editor|credential(\..+)?\.helper|gpg(\..+)?\.program|filter\..+\.(clean|smudge|process)|diff\..+\.(textconv|command)|merge\..+\.driver|(merge|diff)tool\..+\.cmd|pager\..+|uploadpack\.packobjectshook|url\..+\.(insteadof|pushinsteadof))$/;
+
+/** What setting this configuration key can do to a later git command. */
+function configKeyIntent(key: string, value?: string): GitIntent {
+  const k = key.toLowerCase();
+  if (k === "core.hookspath") return "no-verify";
+  const runsCommand = RUNS_COMMAND.test(k) && !(value !== undefined && isBenignProgram(value));
+  const redirects =
+    k.startsWith("alias.") ||
+    k.startsWith("include.") ||
+    k.startsWith("includeif.") ||
+    runsCommand ||
+    /^remote\..+\.(push|mirror|pushurl)$/.test(k) ||
+    k === "push.default";
+  return redirects ? "unknown" : "ordinary";
+}
+
+const READS_CONFIG = /^--(get|get-all|get-regexp|list|unset|unset-all)$|^-l$/;
+
+/** `git config` options that take a value: `--comment --get` is a comment, not a lookup. */
+const CONFIG_VALUE_OPTIONS = new Set([
+  "--comment",
+  "-f",
+  "--file",
+  "--blob",
+  "--type",
+  "--default",
+  "--value",
+]);
+
+/** The words with each value-taking option's value removed. */
+const withoutOptionValues = (args: string[]): string[] =>
+  args.filter((_, k) => !CONFIG_VALUE_OPTIONS.has(args[k - 1] ?? ""));
+
+function classifyConfig(args: string[]): GitIntent {
+  // `git config get|list|unset ...` (newer spelling) never sets a value.
+  if (["get", "list", "unset"].includes(args[0] ?? "")) return "ordinary";
+  // git stops reading options at the first plain word: `config k v --get` still writes k.
+  const options = args.slice(
+    0,
+    Math.max(
+      0,
+      args.findIndex((a) => !a.startsWith("-")),
+    ),
+  );
+  const leading = args.findIndex((a) => !a.startsWith("-")) < 0 ? args : options;
+  if (withoutOptionValues(leading).some((a) => READS_CONFIG.test(a))) return "ordinary";
+  const plain = withoutOptionValues(args).filter((a) => !a.startsWith("-"));
+  // A key with no value is a lookup (`git config core.hooksPath`), not a write.
+  if (plain.length < 2) return "ordinary";
+  return plain.reduce<GitIntent>(
+    (acc, a, k) => worst(acc, configKeyIntent(a, plain[k + 1])),
+    "ordinary",
+  );
+}
+
 function classifyGitArgs(globals: string[], sub: string | undefined, args: string[]): GitIntent {
   let intent: GitIntent = "ordinary";
-  if (globals.some((g) => /^core\.hookspath=/i.test(g))) intent = worst(intent, "no-verify");
+  for (const g of globals) {
+    const eq = g.indexOf("=");
+    intent = worst(
+      intent,
+      configKeyIntent(eq < 0 ? g : g.slice(0, eq), eq < 0 ? undefined : g.slice(eq + 1)),
+    );
+  }
+  if (sub !== undefined && !sub.startsWith("$") && !GIT_SUBCOMMANDS.has(sub)) {
+    intent = worst(intent, "unknown");
+  }
   if (args.some((a) => isLong(a, "--no-verify"))) intent = worst(intent, "no-verify");
   switch (sub) {
     case "push": {
@@ -156,7 +288,7 @@ function classifyGitArgs(globals: string[], sub: string | undefined, args: strin
         return worst(intent, "force-push");
       }
       if (
-        args.some((a) => isLong(a, "--delete")) ||
+        args.some((a) => isLong(a, "--delete", "--prune")) ||
         shortFlags.includes("-d") ||
         args.some((a) => /^:\S/.test(a))
       ) {
@@ -172,6 +304,11 @@ function classifyGitArgs(globals: string[], sub: string | undefined, args: strin
       return args.some((a) => ["--abort", "--continue", "--skip", "--quit"].includes(a))
         ? intent
         : worst(intent, "history-rewrite");
+    case "config":
+      return worst(intent, classifyConfig(args));
+    case "remote":
+      // `remote add --mirror=push` / `set-url --push` make a later plain push mirror or redirect.
+      return args.some((a) => /^--(mirror|push)/.test(a)) ? worst(intent, "unknown") : intent;
     case "filter-branch":
     case "filter-repo":
       return worst(intent, "history-rewrite");
@@ -183,21 +320,27 @@ function classifyGitArgs(globals: string[], sub: string | undefined, args: strin
 }
 
 /** Skips leading `NAME=value` words, wrappers and shell keywords; `index` is the command word (-1: none). */
-function skipPrefix(tokens: string[]): { index: number; hookSkip: boolean } {
-  let hookSkip = false;
+function skipPrefix(tokens: string[]): { index: number; env: GitIntent } {
+  let env: GitIntent = "ordinary";
   let index = 0;
   for (;;) {
     const t = tokens[index];
-    if (t === undefined) return { index: -1, hookSkip };
-    if (isAssignment(t)) {
-      if (HOOK_SKIP_ENV.has(t)) hookSkip = true;
-    } else if (!(WRAPPERS.has(t) || KEYWORDS.has(t))) {
-      return { index, hookSkip };
-    }
+    if (t === undefined) return { index: -1, env };
+    if (isAssignment(t)) env = worst(env, assignmentIntent(t));
+    else if (!(WRAPPERS.has(t) || KEYWORDS.has(t))) return { index, env };
     index++;
   }
 }
 
+/** What one `NAME=value` word does to the git commands that run with it. */
+function assignmentIntent(word: string): GitIntent {
+  if (skipsHooks(word)) return "no-verify";
+  return setsGitConfig(word) ? "unknown" : "ordinary";
+}
+
+/** `--config-env=key=VAR`: the value is a variable's name, whatever that variable holds; only the key is known. */
+const envConfigKey = (pair: string): string => pair.split("=")[0] ?? "";
+
 /** Git's global options (`-c k=v`, `-C dir`, flags) before the subcommand. */
 function splitGlobals(rest: string[]): {
   globals: string[];
@@ -208,8 +351,12 @@ function splitGlobals(rest: string[]): {
   let j = 0;
   while (j < rest.length && (rest[j] ?? "").startsWith("-")) {
     const opt = rest[j] ?? "";
-    if (GLOBAL_WITH_VALUE.has(opt)) {
-      globals.push(rest[j + 1] ?? "");
+    if (opt.startsWith("--config-env=")) {
+      globals.push(envConfigKey(opt.slice("--config-env=".length)));
+      j++;
+    } else if (GLOBAL_WITH_VALUE.has(opt)) {
+      const value = rest[j + 1] ?? "";
+      globals.push(opt === "--config-env" ? envConfigKey(value) : value);
       j += 2;
     } else {
       j++;
@@ -218,28 +365,132 @@ function splitGlobals(rest: string[]): {
   return { globals, sub: rest[j], args: rest.slice(j + 1) };
 }
 
+/** A shell started without a script to run reads its commands from stdin, which cannot be seen. */
+function classifyShell(rest: string[]): GitIntent {
+  const c = rest.findIndex((t) => /^-[A-Za-z]*c[A-Za-z]*$/.test(t));
+  const script = c >= 0 ? rest[c + 1] : undefined;
+  if (script !== undefined) return classifyGitCommand(script);
+  return readsStdin(rest) ? "unknown" : "ordinary";
+}
+
+/** No script file among the arguments (or `-s`, or a stdin path): the program reads its code from stdin. */
+const readsStdin = (rest: string[]): boolean =>
+  rest.includes("-s") ||
+  rest.some((t) => STDIN_PATH.test(t)) ||
+  rest.every((t) => t.startsWith("-"));
+
+/** A word that starts a command worth reading: git, a shell, or an interpreter that may run either. */
+const isCommandWord = (word: string): boolean => {
+  const base = basename(word);
+  return base === "git" || SHELLS.has(base) || INTERPRETERS.test(base);
+};
+
+/** `timeout 5 bash -c '…'`, `script -qc '…'`: the wrapped command is a later word or a script string. */
+function classifyRunner(rest: string[]): GitIntent {
+  let intent: GitIntent = "ordinary";
+  for (const [k, word] of rest.entries()) {
+    // Everything after the command word is that command's own arguments, not more commands.
+    if (isCommandWord(word)) {
+      return worst(intent, classifySegment(rest.slice(k)));
+    }
+    if (isAssignment(word)) intent = worst(intent, assignmentIntent(word));
+    else if (/\s/.test(word)) intent = worst(intent, classifyGitCommand(word));
+  }
+  return intent;
+}
+
+/** `python3 -c '…git…'`: code that may run git by any means cannot be read. */
+const interpreterRunsGit = (rest: string[], isPython: boolean): boolean => {
+  const inline = rest.some((t) => INLINE_CODE_FLAG.test(t));
+  // Inline code that mentions git, or a script read from stdin (pipe, heredoc): either can run any git.
+  if (inline) return rest.some((t) => /\bgit\b/.test(t) && !t.startsWith("-"));
+  if (rest.some((t) => INFO_FLAG.test(t) || (VERSION_FLAG.test(t) && !isPython))) return false;
+  // `node --test` is a runner, not stdin; flags alone (`python3 -u`) still read it, so does a stdin path.
+  const runs = rest.some((t) => /^--(test|run|check|watch)\b/.test(t));
+  return !runs && (rest.every((t) => t.startsWith("-")) || rest.some((t) => STDIN_PATH.test(t)));
+};
+
+/** `export LEFTHOOK=0`: the assignment outlives the command, so the commands after it skip hooks. */
+const classifyExport = (rest: string[]): GitIntent =>
+  rest.reduce<GitIntent>(
+    (acc, t) => worst(acc, isAssignment(t) ? assignmentIntent(t) : "ordinary"),
+    "ordinary",
+  );
+
+/** The command line `env -S` / `--split-string` carries, if there is one. */
+function splitStringValue(rest: string[]): string | undefined {
+  for (const [k, t] of rest.entries()) {
+    if (t === "-S" || t === "--split-string") return rest[k + 1];
+    if (t.startsWith("--split-string=")) return t.slice("--split-string=".length);
+    if (/^-S./.test(t)) return t.slice(2);
+  }
+  return undefined;
+}
+
+/** A command that is not git, a shell or an assignment: it may still wrap or script a git command. */
+function classifyOtherCommand(base: string, rest: string[]): GitIntent {
+  if (DATA_ONLY.has(base)) return "ordinary";
+  if (RUNNERS.has(base)) return classifyRunner(rest);
+  if (INTERPRETERS.test(base) && interpreterRunsGit(rest, base.startsWith("python")))
+    return "unknown";
+  // `env -S "git push -f"` splits its value into a command line.
+  const split = splitStringValue([base, ...rest]);
+  if (split !== undefined) return classifyGitCommand(split);
+  // Wrapper with options (`sudo -E bash -c ...`, `env -i git ...`): classify from the git or shell token.
+  // Only an option-shaped head means a skipped wrapper's options (`command -v node` is a lookup);
+  // otherwise just a literal `git` among the words counts (`brew install node` runs nothing).
+  const wrapperOptions = base.startsWith("-") && !/^-[vV]$/.test(base);
+  const at = wrapperOptions
+    ? rest.findIndex(isCommandWord)
+    : rest.findIndex((t) => basename(t) === "git");
+  if (at < 0) return "ordinary";
+  // `apt install git curl`, `brew install git gh`: a `git` argument followed by another package name is data.
+  const after = rest[at + 1];
+  if (!wrapperOptions && after !== undefined && !/^[-$]/.test(after) && !GIT_SUBCOMMANDS.has(after))
+    return "ordinary";
+  // `env -i LEFTHOOK=0 git commit`: assignments among the wrapper's own words reach the command too.
+  const env = rest
+    .slice(0, at)
+    .reduce<GitIntent>(
+      (acc, t) => worst(acc, isAssignment(t) ? assignmentIntent(t) : "ordinary"),
+      "ordinary",
+    );
+  return worst(env, classifySegment(rest.slice(at)));
+}
+
+/** Whether a command can start git itself (a runner, an interpreter, a wrapper's options, or a git/shell word). */
+const runsCommands = (base: string, rest: string[]): boolean =>
+  RUNNERS.has(base) ||
+  INTERPRETERS.test(base) ||
+  base.startsWith("-") ||
+  rest.some((t) => basename(t) === "git" || SHELLS.has(basename(t)));
+
 // pi-lens-ignore: high-fan-out -- the classifier dispatches one git word to many small predicates; it is a table, not coordination
 function classifySegment(tokens: string[]): GitIntent {
-  const { index: i, hookSkip } = skipPrefix(tokens);
-  if (i < 0) return "ordinary";
+  const { index: i, env } = skipPrefix(tokens);
+  if (i < 0) return env;
   const head = tokens[i] ?? "";
   const rest = tokens.slice(i + 1);
   const base = basename(head);
-  const withHookSkip = (found: GitIntent): GitIntent =>
-    hookSkip ? worst(found, "no-verify") : found;
-  if (head.startsWith("$") || base === "$GIT") return "unknown";
-  if (SHELLS.has(base)) {
-    const c = rest.findIndex((t) => /^-[A-Za-z]*c[A-Za-z]*$/.test(t));
-    const script = c >= 0 ? rest[c + 1] : undefined;
-    return script !== undefined ? classifyGitCommand(script) : "ordinary";
+  const withEnv = (found: GitIntent): GitIntent => worst(found, env);
+  if (head.startsWith("$") || head.includes("`") || base === "$GIT") return "unknown";
+  if (SHELLS.has(base)) return withEnv(classifyShell(rest));
+  if (base === "eval") return withEnv(classifyGitCommand(rest.join(" ")));
+  if (ENV_SETTERS.has(base)) return withEnv(classifyExport(rest));
+  if (OPAQUE.has(base)) {
+    return rest.some((t) => isCommandWord(t) || (/\s/.test(t) && /\bgit\b/.test(t)))
+      ? "unknown"
+      : "ordinary";
+  }
+  // `source /dev/stdin <<< '…'`: sourcing standard input runs code that cannot be read.
+  if ((base === "source" || base === ".") && rest.some((t) => STDIN_PATH.test(t))) return "unknown";
+  if (base.startsWith("git-") && GIT_SUBCOMMANDS.has(base.slice(4))) {
+    return withEnv(classifyGitArgs([], base.slice(4), rest));
   }
-  if (base === "eval") return classifyGitCommand(rest.join(" "));
-  if (OPAQUE.has(base)) return rest.some((t) => basename(t) === "git") ? "unknown" : "ordinary";
   if (base !== "git") {
-    if (DATA_ONLY.has(base)) return "ordinary";
-    // Wrapper with options (`sudo -E git ...`, `timeout 5 git ...`): classify from the git token.
-    const at = rest.findIndex((t) => basename(t) === "git");
-    return at >= 0 ? withHookSkip(classifySegment(rest.slice(at))) : "ordinary";
+    const found = classifyOtherCommand(base, rest);
+    // `HUSKY=0 npm ci` skips a hook installer, not a commit hook: the assignment counts only for commands that can run git.
+    return runsCommands(base, rest) ? withEnv(found) : found;
   }
   const { globals, sub, args } = splitGlobals(rest);
   const dynamic =
@@ -247,7 +498,7 @@ function classifySegment(tokens: string[]): GitIntent {
     (["push", "reset", "rebase"].includes(sub ?? "") &&
       args.some((t) => t.startsWith("$") || t.includes("`")));
   const intent = classifyGitArgs(globals, sub, args);
-  return withHookSkip(dynamic ? worst(intent, "unknown") : intent);
+  return withEnv(dynamic ? worst(intent, "unknown") : intent);
 }
 
 /**
@@ -316,19 +567,52 @@ export function heredocDelimiter(line: string): string | undefined {
   return undefined;
 }
 
-/** Classifies the most severe git intent in a shell command (deterministic fast path). */
+/** The body of the heredoc that `delimiter` opened on line `from` of `lines` (empty when unterminated). */
+function heredocBody(lines: readonly string[], from: number, delimiter: string): string {
+  const body: string[] = [];
+  for (const line of lines.slice(from + 1)) {
+    if (line.trim() === delimiter) break;
+    body.push(line);
+  }
+  return body.join("\n");
+}
+
+/**
+ * Whether a script read from a heredoc cannot run git. An interpreter's body only has to avoid the word;
+ * a shell's must also be plain words, because `g\it`, `gi""t` and `${G}t` build it without spelling it.
+ */
+const scriptCannotRunGit = (body: string, shell: boolean): boolean =>
+  !/git/i.test(body) && (!shell || /^[\w\s./=:,@%+-]*$/.test(body));
+
+/**
+ * Classifies the most severe git intent in a shell command (deterministic fast path).
+ * A script fed by a heredoc (`python3 - <<'EOF'`) is unreadable only if it may run git: when neither
+ * the command line nor the body mentions git at all, it is not held for the user.
+ */
 export function classifyGitCommand(command: string): GitIntent {
   let intent: GitIntent = "ordinary";
   let heredocEnd: string | undefined;
-  for (const line of splitLines(command)) {
+  const lines = splitLines(command);
+  for (const [index, line] of lines.entries()) {
     if (heredocEnd !== undefined) {
       if (line.trim() === heredocEnd) heredocEnd = undefined;
       continue;
     }
-    for (const segment of segments(line)) intent = worst(intent, classifySegment(segment));
+    const delimiter = heredocDelimiter(line);
+    let lineIntent: GitIntent = "ordinary";
+    for (const segment of segments(line)) lineIntent = worst(lineIntent, classifySegment(segment));
     for (const body of substitutions(live(line, false)))
-      intent = worst(intent, classifyGitCommand(body));
-    heredocEnd = heredocDelimiter(line) ?? heredocEnd;
+      lineIntent = worst(lineIntent, classifyGitCommand(body));
+    const gitFree =
+      delimiter !== undefined &&
+      !/git/i.test(line) &&
+      !/[$`]/.test(line) && // `$CMD <<EOF` runs whatever the variable holds
+      scriptCannotRunGit(
+        heredocBody(lines, index, delimiter),
+        segments(line).some((seg) => seg.some((t) => SHELLS.has(basename(t)))),
+      );
+    intent = worst(intent, lineIntent === "unknown" && gitFree ? "ordinary" : lineIntent);
+    heredocEnd = delimiter ?? heredocEnd;
   }
   return intent;
 }

package/src/core/git-invocations.ts

@@ -1,6 +1,7 @@
 import {
   basename,
   DATA_ONLY,
+  GIT_SUBCOMMANDS,
   GLOBAL_WITH_VALUE,
   heredocDelimiter,
   isAssignment,
@@ -95,13 +96,33 @@ function visitSegment(tokens: readonly string[], into: Collector): void {
   else if (OPAQUE.has(base)) {
     if (gitIndex(rest) >= 0) into.opaque.push(...rest);
   } else if (base === "git") visitGit(rest, into);
+  else if (/^git-[a-z]/.test(base))
+    visitGit([base.slice(4), ...rest], into); // /usr/lib/git-core/git-push
   else visitWrapped(base, rest, into);
 }
 
-/** Wrapper with options (`sudo -E git …`, `timeout 5 git …`): resolve from the git token. */
+/**
+ * Wrapper with options (`sudo -E git …`, `timeout 5 git …`, `timeout 5 bash -c '…'`): resolve from the
+ * git or shell token; `env -S 'git push'` carries its command line as one string and is read too.
+ */
 function visitWrapped(base: string, rest: readonly string[], into: Collector): void {
-  const at = gitIndex(rest);
-  if (!DATA_ONLY.has(base) && at >= 0) visitSegment(rest.slice(at), into);
+  if (DATA_ONLY.has(base)) return;
+  const at = rest.findIndex((t) => basename(t) === "git" || SHELLS.has(basename(t)));
+  if (at >= 0) visitSegment(rest.slice(at), into);
+  else {
+    const split = splitString([base, ...rest]);
+    if (split !== undefined) merge(into, resolveGit(split));
+  }
+}
+
+/** The command line `env -S 'git push'` / `--split-string` carries, if there is one. */
+function splitString(rest: readonly string[]): string | undefined {
+  for (const [k, t] of rest.entries()) {
+    if (t === "-S" || t === "--split-string") return rest[k + 1];
+    if (t.startsWith("--split-string=")) return t.slice("--split-string=".length);
+    if (/^-S./.test(t)) return t.slice(2);
+  }
+  return undefined;
 }
 
 function merge(into: Collector, other: GitResolution): void {
@@ -131,6 +152,14 @@ export function resolveGit(command: string): GitResolution {
   return into;
 }
 
+/**
+ * An alias defined in this very command (`git -c alias.p=push p`) and then run: it may be any command,
+ * a push or a commit included. An alias from the user's own configuration is not this command's doing.
+ */
+export const runsDefinedAlias = (command: string, resolution: GitResolution): boolean =>
+  /\balias\./i.test(command) &&
+  resolution.invocations.some((g) => !(g.sub.startsWith("$") || GIT_SUBCOMMANDS.has(g.sub)));
+
 /** Whether something unreadable in the command may be running `git <subcommand>`. */
 export const opaqueMentions = (resolution: GitResolution, subcommand: string): boolean =>
   resolution.opaque.includes(subcommand);

package/src/core/message-problem.ts

@@ -0,0 +1,10 @@
+import { hasRationaleBody, parseConventionalCommit } from "./commit-message.ts";
+
+/** Why a commit message fails the repository's rule (Conventional subject, a body saying why), or undefined. */
+export function messageProblem(message: string): string | undefined {
+  const parsed = parseConventionalCommit(message);
+  if (!parsed.ok) return parsed.error.message;
+  return hasRationaleBody(message)
+    ? undefined
+    : "the message has no body explaining why the change was made";
+}

package/src/core/push-command.ts

@@ -1,14 +1,20 @@
-import { opaqueMentions, resolveGit } from "./git-invocations.ts";
+import { opaqueMentions, resolveGit, runsDefinedAlias } from "./git-invocations.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[];
+  /** Local refs the refspecs push (`HEAD` in `HEAD:feature`); empty means the current branch. */
+  readonly sources: readonly string[];
   readonly allBranches: boolean;
   /** The refspecs name `HEAD`, so the current branch is pushed too. */
   readonly usesHead: boolean;
   /** `--tags` with no refspec: only tags are pushed, no branch. */
   readonly tagsOnly: boolean;
+  /** `--tags` beside named refspecs: every tag goes too, and a tag may sit on a commit no named branch has. */
+  readonly withTags?: boolean;
+  /** Every refspec deletes a ref (`--delete`, `:branch`): nothing is sent, so no commit is published. */
+  readonly deleteOnly: boolean;
   /** Where the push runs when `cd`/`git -C` moved it away from the session's directory. */
   readonly dir?: string | undefined;
 };
@@ -20,6 +26,11 @@ const isDynamic = (refspec: string): boolean => /[$`*?[]/.test(refspec);
 const isDryRun = (args: readonly string[]): boolean =>
   args.some((a) => a === "--dry-run" || a === "-n" || /^-[a-zA-Z]*n[a-zA-Z]*$/.test(a));
 
+const source = (refspec: string): string =>
+  refspec.includes(":")
+    ? refspec.slice(0, refspec.indexOf(":")).replace(/^\+/, "")
+    : refspec.replace(/^\+/, "");
+
 const destination = (refspec: string): string => {
   const dst = refspec.includes(":") ? refspec.slice(refspec.lastIndexOf(":") + 1) : refspec;
   return dst.replace(/^\+/, "").replace(/^(?:refs\/)?heads\//, "");
@@ -29,6 +40,7 @@ type ParsedArgs = {
   positional: string[];
   all: boolean;
   tags: boolean;
+  deleting: boolean;
   repo: string | undefined;
 };
 
@@ -38,11 +50,18 @@ function applyFlag(parsed: ParsedArgs, a: string): void {
   if (a.startsWith(VALUE_PREFIX)) parsed.repo = a.slice(VALUE_PREFIX.length);
   else if (a === "--all" || a === "--mirror") parsed.all = true;
   else if (a === "--tags") parsed.tags = true;
+  else if (a === "--delete" || a === "-d") parsed.deleting = true;
   else if (!a.startsWith("-")) parsed.positional.push(a);
 }
 
 function positionalArgs(args: readonly string[]): ParsedArgs {
-  const parsed: ParsedArgs = { positional: [], all: false, tags: false, repo: undefined };
+  const parsed: ParsedArgs = {
+    positional: [],
+    all: false,
+    tags: false,
+    deleting: false,
+    repo: undefined,
+  };
   let valueFor: "repo" | "skip" | undefined;
   for (const a of args) {
     if (valueFor !== undefined) {
@@ -56,7 +75,7 @@ function positionalArgs(args: readonly string[]): ParsedArgs {
 }
 
 const toTarget = (args: readonly string[], dir: string | undefined): PushTarget => {
-  const { positional, all, tags, repo } = positionalArgs(args);
+  const { positional, all, tags, deleting, repo } = positionalArgs(args);
   // With --repo, every positional argument is a refspec.
   const [remote, ...refspecs] = repo === undefined ? positional : [repo, ...positional];
   const destinations = refspecs.map(destination);
@@ -64,9 +83,23 @@ const toTarget = (args: readonly string[], dir: string | undefined): PushTarget
   return {
     remote,
     branches: destinations.filter(named),
-    allBranches: all || destinations.some(isDynamic),
+    // A source that starts with "-" would be read as an option by `git log`; it is never a ref name.
+    sources: refspecs.map(source).filter((r) => r !== "" && !isDynamic(r) && !r.startsWith("-")),
+    // A destination or a source built by the shell (`$SHA:refs/heads/x`) could be any ref: check them all.
+    // `:` and `+:` push every branch that exists on both sides (the "matching" refspec).
+    allBranches:
+      all ||
+      destinations.some(isDynamic) ||
+      refspecs.map(source).some(isDynamic) ||
+      refspecs.some((r) => r.replace(/^\+/, "") === ":"),
     usesHead: destinations.includes("HEAD"),
     tagsOnly: tags && refspecs.length === 0 && !all,
+    // `--tags` sends every tag as well, so a push with it deletes nothing only.
+    deleteOnly:
+      refspecs.length > 0 &&
+      !tags &&
+      (deleting || refspecs.every((r) => r.startsWith(":") && r !== ":")),
+    ...(tags && refspecs.length > 0 && !all ? { withTags: true } : {}),
     ...(dir === undefined ? {} : { dir }),
   };
 };
@@ -77,17 +110,19 @@ export function pushTargets(command: string): PushTarget[] {
   const targets = resolution.invocations.flatMap((g) =>
     g.sub === "push" && !isDryRun(g.args) ? [toTarget(g.args, g.dir)] : [],
   );
-  // git run through something opaque (xargs, `$CMD`): a push cannot be ruled out, so assume the worst.
-  const opaquePush = opaqueMentions(resolution, "push");
+  // git run through something opaque (xargs, `$CMD`, an alias): a push cannot be ruled out, so assume the worst.
+  const opaquePush = opaqueMentions(resolution, "push") || runsDefinedAlias(command, resolution);
   return opaquePush
     ? [
         ...targets,
         {
           remote: undefined,
           branches: [],
+          sources: [],
           allBranches: true,
           usesHead: false,
           tagsOnly: false,
+          deleteOnly: false,
           dir: undefined,
         },
       ]

package/src/gates/commit-guard.ts

@@ -6,14 +6,10 @@ import {
   isToolCallEventType,
 } from "@earendil-works/pi-coding-agent";
 import { type CommitExtraction, extractCommits } from "../core/commit-command.ts";
-import {
-  findForbiddenTrailerKeys,
-  findForbiddenTrailers,
-  hasRationaleBody,
-  parseConventionalCommit,
-} from "../core/commit-message.ts";
+import { findForbiddenTrailerKeys, findForbiddenTrailers } from "../core/commit-message.ts";
 import type { Exec } from "../core/exec.ts";
 import { resolveGit } from "../core/git-invocations.ts";
+import { messageProblem } from "../core/message-problem.ts";
 import { DECISION_LOG, reviewGap } from "../core/review-flow.ts";
 import { type GateId, isParseError, parseGateId } from "../core/types.ts";
 import type { Jev } from "../jev/client.ts";
@@ -22,12 +18,15 @@ import { judgeCommit, MIX_THRESHOLD, RATIONALE_FLOOR } from "../jev/questions/co
 import { snapshotDiff } from "../review/digest.ts";
 import type { SessionState } from "../state/session-state.ts";
 import { departureUse } from "./departure-use.ts";
+import type { ExcusedMessages } from "./excused-messages.ts";
 
 export type CommitGuardDeps = {
   pi: ExtensionAPI;
   state: SessionState;
   jev: (ctx: ExtensionContext) => Jev;
   exec: Exec;
+  /** Messages whose missing rationale a departure excused here, so the push does not ask again. */
+  excused?: ExcusedMessages | undefined;
 };
 
 type Need = { gate: GateId; why: string };
@@ -66,11 +65,8 @@ const messageOf = (extracted: CommitExtraction, cwd: string): string | 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" }];
+  const problem = messageProblem(message);
+  return problem === undefined ? [] : [{ gate: RATIONALE, why: problem }];
 }
 
 /** `-a`/`--all`, or a `git add` in the same command, widen the commit beyond what is staged. */
@@ -361,6 +357,12 @@ async function needsOf(
   return [...needs, ...viaJev.filter((n) => !needs.some((m) => m.gate === n.gate))];
 }
 
+/** A message let through under a rationale departure is remembered, so its push is not asked again. */
+function rememberExcused(deps: CommitGuardDeps, needs: readonly Need[], messages: string[]): void {
+  if (!needs.some((n) => n.gate === RATIONALE)) return;
+  for (const message of messages) deps.excused?.add(message);
+}
+
 /** 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) => {
@@ -397,6 +399,7 @@ export function registerCommitGuard(deps: CommitGuardDeps): void {
     const uncovered = uses.find(({ use }) => !use.hasOpen());
     if (uncovered !== undefined) return { block: true, reason: blockReason(uncovered.need) };
     for (const { use } of uses) use.consume();
+    rememberExcused(deps, all, known);
     return undefined;
   });
 }

package/src/gates/excused-messages.ts

@@ -0,0 +1,21 @@
+/**
+ * Commit messages whose missing rationale a recorded departure already excused at `git commit`, so the
+ * push that publishes them does not ask for a second departure. In memory: a restart asks again, which
+ * only costs a repeat departure.
+ */
+export type ExcusedMessages = {
+  add(message: string): void;
+  has(message: string): boolean;
+};
+
+const key = (message: string): string => message.trim();
+
+export function createExcusedMessages(): ExcusedMessages {
+  const seen = new Set<string>();
+  return {
+    add: (message) => {
+      seen.add(key(message));
+    },
+    has: (message) => seen.has(key(message)),
+  };
+}

package/src/gates/push-guard.ts

@@ -8,6 +8,7 @@ import {
 import { extractCommits } from "../core/commit-command.ts";
 import { parseConventionalCommit } from "../core/commit-message.ts";
 import type { Exec } from "../core/exec.ts";
+import { resolveGit, runsDefinedAlias } from "../core/git-invocations.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";
@@ -16,6 +17,9 @@ 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";
+import { departureUse } from "./departure-use.ts";
+import type { ExcusedMessages } from "./excused-messages.ts";
+import { type PushMessageFindings, pushMessageFindings } from "./push-messages.ts";
 
 export type PushGuardDeps = {
   pi: ExtensionAPI;
@@ -24,6 +28,8 @@ export type PushGuardDeps = {
   jev: (ctx: ExtensionContext) => Jev;
   exec: Exec;
   now?: () => Date;
+  /** Messages `git commit` already excused by a departure; shared with the commit guard. */
+  excused?: ExcusedMessages | undefined;
 };
 
 type Verdict = { readonly block: true; readonly reason: string } | undefined;
@@ -36,6 +42,75 @@ const gate = (id: string): GateId => {
 const FIX_DIFF_LIMIT = 8000;
 const RED_TRUNK = gate("push.red-trunk");
 const DELIVERY_MODE = gate("push.delivery-mode");
+const RATIONALE = gate("commit.rationale");
+
+const COMMIT_MAKERS = new Set(["cherry-pick", "merge", "revert", "am", "commit-tree"]);
+
+/** Flags that stop a commit-maker from writing a commit: a fast-forward, a staged-only result, or an abandoned run. */
+const NO_COMMIT_FLAGS: Readonly<Record<string, readonly string[]>> = {
+  merge: ["--ff-only", "--abort", "--quit", "--squash", "--no-commit"],
+  "cherry-pick": ["--abort", "--quit", "-n", "--no-commit"],
+  revert: ["--abort", "--quit", "-n", "--no-commit"],
+  am: ["--abort", "--quit"],
+};
+const makesNoCommit = (g: { readonly sub: string; readonly args: readonly string[] }): boolean =>
+  g.args.some((a) => NO_COMMIT_FLAGS[g.sub]?.includes(a) === true);
+
+/** A push in the same call as commits whose messages the commit guard never reads (`commit -C`, `cherry-pick`). */
+const createsUnseenCommits = (command: string): boolean => {
+  const { invocations } = resolveGit(command);
+  return (
+    invocations.some((g) => COMMIT_MAKERS.has(g.sub) && !makesNoCommit(g)) ||
+    runsDefinedAlias(command, resolveGit(command)) ||
+    invocations.some(
+      (g) =>
+        g.sub === "commit" &&
+        g.args.some((a) => expandsAtRunTime(a) && !command.includes(`'${a}'`)),
+    ) ||
+    extractCommits(command).some((e) => commitIsUnseen(command, e))
+  );
+};
+
+/** `$(cat <<'EOF' …)` is the message itself (its body is read); any other `$(…)`, backtick or variable is only known once the call runs. */
+const expandsAtRunTime = (arg: string): boolean =>
+  /\$\(|`|\$\{?\w/.test(
+    arg.replace(/\$\(\s*cat\s+#HD\d+\s*\)/g, "").replace(/\\[\s\S]/g, ""), // an escaped `\`` or `\$` is literal text
+  );
+
+/** A commit whose message the guard read before the call ran may still change: a `-F` file the same call writes. */
+const commitIsUnseen = (command: string, e: ReturnType<typeof extractCommits>[number]): boolean => {
+  if (e.kind === "unknown") return true;
+  if (e.kind !== "file") return false;
+  // Stdin, or a path the shell expands (`~/msg`), is a message the commit guard never read.
+  if (e.path === "-" || /^~|[$`]/.test(e.path)) return true;
+  return command.split(e.path).length > 2;
+};
+
+const forbiddenVerdict = (found: PushMessageFindings): Verdict =>
+  found.forbidden.length === 0
+    ? undefined
+    : {
+        block: true,
+        reason:
+          `commit.forbidden-trailer: this push would publish a commit that carries an AI attribution (${found.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 from the unpushed commit, then push again.",
+      };
+
+/**
+ * A commit with no rationale needs the departure `git commit` would have asked for. Checked before any
+ * approval is asked (a refusal after the user approved would ask them again); spent only once the push
+ * is otherwise allowed.
+ */
+const rationaleOwed = (deps: PushGuardDeps, found: PushMessageFindings): boolean =>
+  found.unexplained !== undefined && !departureUse(deps.state, RATIONALE).hasOpen();
+
+const rationaleRefusal = (found: PushMessageFindings): Verdict => ({
+  block: true,
+  reason:
+    `commit.rationale: this push would publish a commit that fails the message rule (${found.unexplained}). ` +
+    "Improve the unpushed message, or record a departure with devsys_record_departure (gate commit.rationale) and push again.",
+});
 
 async function currentBranch(exec: Exec, cwd: string): Promise<string | undefined> {
   try {
@@ -147,6 +222,48 @@ async function hardStop(deps: PushGuardDeps, stop: HardStop): Promise<Verdict> {
   };
 }
 
+type PushCall = { readonly toolCallId: string; readonly input: { readonly command: string } };
+
+/** Delivery-mode and red-trunk hard stops for a push onto the trunk. */
+async function trunkVerdict(
+  deps: PushGuardDeps,
+  ctx: ExtensionContext,
+  event: PushCall,
+  config: DevsysConfig,
+  targets: readonly PushTarget[],
+): Promise<Verdict> {
+  const { mode, trunk } = config.delivery;
+  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 (extractCommits(command).length > 0) {
+    return {
+      block: true,
+      reason: `CI on ${trunk} is red and this call commits and pushes together, so the push cannot be judged as a fix for it. Commit first in one call, then push in the next.`,
+    };
+  }
+  if (await repairsRedTrunk(deps, ctx, config, status.runId)) 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",
+  });
+}
+
 /** 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) => {
@@ -157,42 +274,28 @@ export function registerPushGuard(deps: PushGuardDeps): void {
     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") {
+    if (loaded.value.delivery.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 (extractCommits(command).length > 0) {
+    if (createsUnseenCommits(event.input.command)) {
       return {
         block: true,
-        reason: `CI on ${trunk} is red and this call commits and pushes together, so the push cannot be judged as a fix for it. Commit first in one call, then push in the next.`,
+        reason:
+          "this call creates commits (cherry-pick, merge, revert, am, commit-tree or a commit with a message the guard cannot read) and pushes them together, so their messages cannot be checked first. Make the commits in one call, then push in the next.",
       };
     }
-    if (await repairsRedTrunk(deps, ctx, loaded.value, status.runId)) 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",
-    });
+    // Read-only first: an AI trailer blocks before any approval or departure is spent.
+    const found = await pushMessageFindings(deps.exec, ctx.cwd, targets, deps.excused);
+    const refused = found === undefined ? undefined : forbiddenVerdict(found);
+    if (refused !== undefined) return refused;
+    if (found !== undefined && rationaleOwed(deps, found)) return rationaleRefusal(found);
+    const stopped = await trunkVerdict(deps, ctx, event, loaded.value, targets);
+    if (stopped !== undefined) return stopped;
+    if (found?.unexplained !== undefined) departureUse(deps.state, RATIONALE).consume();
+    return undefined;
   });
 
   deps.pi.on("tool_result", (event) => {

package/src/gates/push-messages.ts

@@ -0,0 +1,94 @@
+import { resolve } from "node:path";
+import { findForbiddenTrailerKeys, findForbiddenTrailers } from "../core/commit-message.ts";
+import type { Exec } from "../core/exec.ts";
+import { messageProblem } from "../core/message-problem.ts";
+import type { PushTarget } from "../core/push-command.ts";
+import type { ExcusedMessages } from "./excused-messages.ts";
+
+type UnpushedCommit = { readonly merge: boolean; readonly message: string };
+
+/** What is wrong with the messages of the commits a push would publish. */
+export type PushMessageFindings = {
+  /** AI-attribution trailers (non-negotiable 8): never a departure. */
+  readonly forbidden: readonly string[];
+  /** Why the first non-merge commit needs a `commit.rationale` departure, if one does. */
+  readonly unexplained: string | undefined;
+};
+
+/** git prints these bytes for `%x1f` / `%x00`; the bytes themselves cannot be passed as an argument. */
+const FIELD = "\u001f";
+const RECORD = "\u0000";
+
+/** `git log <ref> --not --remotes`: what that ref has that no remote-tracking branch has (upstream commits pulled into a fork are not this push's to judge). */
+async function unpushedCommits(
+  exec: Exec,
+  cwd: string,
+  ref: string,
+): Promise<UnpushedCommit[] | undefined> {
+  const log = await exec("git", ["log", ref, "--not", "--remotes", "--format=%P%x1f%B%x00", "--"], {
+    cwd,
+    timeout: 15_000,
+  });
+  if (log.code !== 0) return undefined; // a ref git cannot resolve: the push itself will fail
+  return log.stdout
+    .split(RECORD)
+    .filter((record) => record.trim() !== "")
+    .map((record) => {
+      const [parents = "", ...message] = record.replace(/^\n/, "").split(FIELD);
+      return { merge: parents.trim().split(/\s+/).length > 1, message: message.join(FIELD) };
+    });
+}
+
+/** No remote-tracking branch at all (a first push): every commit looks unpushed, so only AI trailers are judged, never the rationale. */
+async function knowsRemotes(exec: Exec, cwd: string): Promise<boolean> {
+  const refs = await exec("git", ["for-each-ref", "--count=1", "refs/remotes"], {
+    cwd,
+    timeout: 5000,
+  });
+  return refs.code === 0 && refs.stdout.trim() !== "";
+}
+
+/** The refs a push sends: the named branches, HEAD for a bare push, every branch for `--all`. */
+const refsOf = (t: PushTarget): string[] => {
+  if (t.allBranches) return ["--branches"];
+  if (t.tagsOnly) return ["--tags"];
+  const named = t.sources.length === 0 ? ["HEAD"] : [...t.sources];
+  return t.withTags === true ? [...named, "--tags"] : named;
+};
+
+/**
+ * The messages of the commits the push would publish (what each target's refs have that its remote
+ * lacks), however each was made: `-C`, `--fixup`, `commit-tree`, `merge -m`, an alias. Read-only.
+ * Undefined when git cannot say (unknown ref). With no remote-tracking branch yet, only trailers are judged.
+ */
+export async function pushMessageFindings(
+  exec: Exec,
+  cwd: string,
+  targets: readonly PushTarget[],
+  excused: ExcusedMessages | undefined,
+): Promise<PushMessageFindings | undefined> {
+  const commits: UnpushedCommit[] = [];
+  const unjudgedForRationale = new Set<UnpushedCommit>();
+  let judged = false;
+  for (const t of targets.filter((x) => !x.deleteOnly)) {
+    const where = t.dir === undefined ? cwd : resolve(cwd, t.dir);
+    const firstPush = !(await knowsRemotes(exec, where));
+    for (const ref of refsOf(t)) {
+      const found = await unpushedCommits(exec, where, ref);
+      if (found === undefined) continue;
+      judged = true;
+      commits.push(...found);
+      if (firstPush) for (const c of found) unjudgedForRationale.add(c);
+    }
+  }
+  if (!judged) return undefined;
+  const forbidden = commits.flatMap((c) => [
+    ...findForbiddenTrailers(c.message),
+    ...findForbiddenTrailerKeys(c.message),
+  ]);
+  const unexplained = commits
+    .filter((c) => !(c.merge || unjudgedForRationale.has(c)) && excused?.has(c.message) !== true)
+    .map((c) => messageProblem(c.message))
+    .find((problem) => problem !== undefined);
+  return { forbidden: [...new Set(forbidden)], unexplained };
+}