@codyswann/lisa 3.69.6 → 3.70.1

package/all/copy-overwrite/scripts/lisa-gates.mjs

@@ -60,7 +60,7 @@
  * @module lisa-gates
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { invokedAsScript } from "./lib/invoked-as-script.mjs";
@@ -964,8 +964,8 @@ export const SECONDARY_PROVER_JOBS = Object.freeze(["snyk"]);
 export const UNGATED_QUALITY_JOBS = Object.freeze({
   zap_baseline: Object.freeze({
     reason:
-      "`runtime-web-vulnerability` names the property, but its legal moments are deploy-only, so there is no declaration a caller can write at pull-request — where this job runs.",
-    owner: "#2832",
+      '`runtime-web-vulnerability` names the property, but its legal moments are deploy-only, so there is no declaration a caller can write at pull-request — where this job runs. #2832 built the deploy-moment runner and did NOT retire this: the gate now has an executor at the moments where it is legal, and this job still has none at the moment where it runs. Adding the row today would be worse than the gap. The job posts `🕷️ OWASP ZAP Baseline`, the gate\'s label is `🕷️ DAST Baseline`, and `contextsFor` derives `🔍 Quality Checks / <label>` — so a required declaration would derive a context nothing ever posts and hold every pull request at "Expected — Waiting for status to be reported", here and in every consumer. Closing the gap renames a live required check, which is a ruleset migration and a ruling, not an edit.',
+    owner: "#3022",
   }),
 });
 
@@ -2828,14 +2828,162 @@ export const EXECUTOR_VERDICTS = Object.freeze([
  */
 const BLOCKING_VERDICTS = Object.freeze([ORPHANED, VACUOUS_PROVER]);
 
-/** Moment families whose executor is the generic hook runner. */
-const HOOK_RUNNER_MOMENTS = Object.freeze([
-  SESSION_START,
-  PRE_TOOL,
-  POST_TOOL,
-  COMMIT,
-  PUSH,
-]);
+/** Where a repository declares which moments it runs gates at. */
+export const MOMENT_EXECUTOR_DIR = ".github/workflows";
+
+/**
+ * A moment handed to a gate runner, in either spelling a workflow uses.
+ *
+ * `moment: <value>` is how a caller parameterises a reusable workflow, and
+ * `--moment=<value>` is how a shell step invokes `lisa-run-gates.mjs` directly.
+ * Both are the same statement — "this workflow executes gates at this moment" —
+ * and a scan that read only one of them would report a repository as having no
+ * runner while looking straight at one.
+ *
+ * `[ \t]*` rather than `\s*` around the colon, deliberately. A workflow that
+ * DEFINES a `moment:` input writes the key with its value on following lines,
+ * and `\s*` would step over the newline and capture `description` as the
+ * moment. The definition of an input is not the use of one.
+ *
+ * The backtick is excluded from the unquoted form for the same class of reason,
+ * and it was measured rather than anticipated: the header of Lisa's own
+ * `gates.yml` documents the defect it fixes by quoting
+ * ``list --moment=pre-deploy:production``, and the first version of this scan
+ * read that PROSE as a runner and reported the moment executed. A workflow
+ * describing a command is not a workflow running one.
+ */
+const MOMENT_ARGUMENT =
+  /(?:\bmoment[ \t]*:[ \t]*|--moment=)(?:'([^'\n]+)'|"([^"\n]+)"|([^\s'"#`]+))/g;
+
+/** A line that is entirely a comment — YAML's and the shell's are both `#`. */
+const COMMENT_LINE = /^\s*#/;
+
+/** The answer when nothing has been measured: no moment is executed. */
+const NOTHING_EXECUTED = Object.freeze({
+  moments: Object.freeze([]),
+  families: Object.freeze([]),
+});
+
+/**
+ * Which moments THIS repository actually runs gates at, read off its workflows.
+ *
+ * The registry's `no-runner-for-moment` verdict used to be an ASSERTION: every
+ * declaration in a deploy or continuous family got told "nothing runs gates
+ * here at all yet", because at the time nothing did. That sentence is a fact
+ * about the repository, not about the gate, and hardcoding it has two failure
+ * modes that arrive together. It keeps saying "nothing runs this" after a runner
+ * ships — a control lying in the reassuring direction. And it keeps EXCUSING a
+ * declaration that resolves to no prover, calling it inert-but-fine, at exactly
+ * the moment the runner would have executed it and reported UNPROVABLE.
+ *
+ * So it is measured instead. A repository executes a moment when one of its
+ * workflows names that moment to a gate runner.
+ *
+ * ## Family, when the environment is computed
+ *
+ * A deploy caller writes `moment: pre-deploy:${{ ... }}` — the family is
+ * literal and the environment is a run-time expression. Requiring an exact
+ * match would report "no runner" for every real deploy façade there is, so a
+ * computed environment registers the FAMILY, and any moment in it counts as
+ * executed. A value with no readable family (`moment: ${{ inputs.moment }}`,
+ * which is how a reusable workflow forwards its own input) contributes nothing:
+ * it is plumbing between two workflows, and the caller at the other end is the
+ * one that made a statement about a moment.
+ *
+ * ## An unreadable directory answers "nothing", and that is the honest answer
+ *
+ * A repository with no `.github/workflows` runs no workflows, so no workflow of
+ * its executes any moment. That is not a guess made under uncertainty; it is
+ * the measurement.
+ * @param {object} [options] Inputs.
+ * @param {string} [options.cwd] Repository root.
+ * @param {string} [options.dir] Directory holding the workflows.
+ * @returns {{moments: string[], families: string[]}} Exact moments executed, and families executed at a computed environment.
+ */
+export function momentsExecutedBy({
+  cwd = process.cwd(),
+  dir = MOMENT_EXECUTOR_DIR,
+} = {}) {
+  const moments = new Set();
+  const families = new Set();
+  const root = join(cwd, dir);
+  let entries;
+  try {
+    entries = readdirSync(root);
+  } catch {
+    return NOTHING_EXECUTED;
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith(".yml") && !entry.endsWith(".yaml")) continue;
+    let text;
+    try {
+      text = readFileSync(join(root, entry), "utf8");
+    } catch {
+      continue;
+    }
+    for (const value of momentArguments(text)) {
+      recordExecutedMoment(value, moments, families);
+    }
+  }
+  return {
+    moments: [...moments].sort(),
+    families: [...families].sort(),
+  };
+}
+
+/**
+ * Every moment argument one workflow file names.
+ * @param {string} text The workflow source.
+ * @returns {string[]} The raw values, unvalidated.
+ */
+function momentArguments(text) {
+  const found = [];
+  // Line by line, so a whole-line comment can be dropped before it is read.
+  // Both languages in a workflow file — YAML and the shell inside `run:` —
+  // comment with `#`, so one rule covers both, and a header documenting the
+  // very command this scan looks for stops counting as an invocation of it.
+  for (const line of text.split("\n")) {
+    if (COMMENT_LINE.test(line)) continue;
+    for (const match of line.matchAll(MOMENT_ARGUMENT)) {
+      const value = match[1] ?? match[2] ?? match[3];
+      if (value) found.push(value.trim());
+    }
+  }
+  return found;
+}
+
+/**
+ * Record one workflow's moment argument against the exact/family sets.
+ * @param {string} value The raw value read from the workflow.
+ * @param {Set<string>} moments Exact moments, mutated in place.
+ * @param {Set<string>} families Families executed at a computed environment.
+ */
+function recordExecutedMoment(value, moments, families) {
+  if (MOMENTS.includes(value)) {
+    moments.add(value);
+    return;
+  }
+  const separator = value.indexOf(":");
+  if (separator === -1) return;
+  const family = value.slice(0, separator);
+  const environment = value.slice(separator + 1);
+  if (!MOMENT_FAMILIES.includes(family) || environment === "") return;
+  // `${{ ... }}` and `$VAR` both mean "decided at run time". The family is
+  // still a statement, and it is the only one available.
+  if (environment.includes("$")) families.add(family);
+  else moments.add(`${family}:${environment}`);
+}
+
+/**
+ * Whether the measured inventory covers one declared moment.
+ * @param {{moments?: string[], families?: string[]}} executed The inventory.
+ * @param {string} moment The declared moment.
+ * @returns {boolean} Whether something in the repository runs gates there.
+ */
+function executesMoment(executed, moment) {
+  const { moments = [], families = [] } = executed ?? {};
+  return moments.includes(moment) || families.includes(momentFamily(moment));
+}
 
 /**
  * Gates whose only prover reports findings and cannot fail.
@@ -2893,15 +3041,44 @@ function declaredLevel(entry) {
 }
 
 /**
- * The task one gate resolves to, honouring a `run:` override.
- * @param {string} gate Gate id.
- * @param {object} block The gate's own block from the config.
- * @returns {string|undefined} The task name.
+ * The task one declaration resolves to, by the SAME order `resolveMoment` uses.
+ *
+ * It has to be the same order or the classifier judges a command the runner
+ * would never issue. The five sources, narrowest first: the moment entry's own
+ * `run:`, the gate block's `run:`, the `shippedAs` alias when the registry
+ * default is absent and the alias is present, the moment family's `taskAt`
+ * default, and finally the plain registry `task`.
+ *
+ * The alias matters most here and is the easiest to omit. `security:dast` is the
+ * registry name for a dynamic scan and NO stack ships a script under it; two
+ * stacks ship `security:zap`, and the runner substitutes it. A classifier that
+ * looked only at `task` would call every real DAST declaration an orphan and
+ * refuse a configuration that works.
+ * @param {object} options Inputs.
+ * @param {string} options.gate Gate id.
+ * @param {object} options.block The gate's own block from the config.
+ * @param {string} options.moment The declared moment.
+ * @param {Record<string, string>} options.scripts The project's package scripts.
+ * @returns {string|null|undefined} The task the runner would run.
  */
-function declaredTask(gate, block) {
-  const override =
-    block !== null && typeof block === "object" ? block.run : undefined;
-  return typeof override === "string" ? override : REGISTRY[gate]?.task;
+function resolvedTaskFor({ gate, block, moment, scripts }) {
+  const definition = REGISTRY[gate];
+  const entry = block?.[moment];
+  const entryRun =
+    entry !== null && typeof entry === "object" && typeof entry.run === "string"
+      ? entry.run
+      : null;
+  const blockRun = typeof block?.run === "string" ? block.run : null;
+  const declared = entryRun ?? blockRun;
+  const registryTask =
+    definition?.taskAt?.[momentFamily(moment)] ?? definition?.task ?? null;
+  const alias = aliasFor({
+    declared,
+    registryTask,
+    shippedAs: definition?.shippedAs ?? null,
+    scripts,
+  });
+  return declared ?? alias?.to ?? registryTask;
 }
 
 /**
@@ -2938,6 +3115,7 @@ export function classifyDeclaredExecutors({
   gates,
   scripts,
   outsideFacade = PROVED_OUTSIDE_FACADE,
+  executedMoments = NOTHING_EXECUTED,
 }) {
   const findings = [];
   for (const [gate, block] of Object.entries(gates ?? {})) {
@@ -2961,6 +3139,7 @@ export function classifyDeclaredExecutors({
         level,
         scripts,
         outsideFacade,
+        executedMoments,
       });
       if (finding !== null) findings.push(finding);
     }
@@ -2977,9 +3156,18 @@ export function classifyDeclaredExecutors({
  * @param {string} options.level Declared level.
  * @param {Record<string, string>|null|undefined} options.scripts Project scripts.
  * @param {Record<string, string>} options.outsideFacade Gates proved outside the façade.
+ * @param {{moments?: string[], families?: string[]}} options.executedMoments Moments this repository actually runs gates at.
  * @returns {{gate: string, moment: string, level: string, verdict: string, detail: string}|null} The finding.
  */
-function verdictFor({ gate, block, moment, level, scripts, outsideFacade }) {
+function verdictFor({
+  gate,
+  block,
+  moment,
+  level,
+  scripts,
+  outsideFacade,
+  executedMoments,
+}) {
   const make = (verdict, detail) => ({ gate, moment, level, verdict, detail });
   if (level === "required" && Object.hasOwn(ADVISORY_PROVERS, gate)) {
     return make(VACUOUS_PROVER, ADVISORY_PROVERS[gate]);
@@ -2993,17 +3181,6 @@ function verdictFor({ gate, block, moment, level, scripts, outsideFacade }) {
     );
   }
   const family = momentFamily(moment);
-  if (HOOK_RUNNER_MOMENTS.includes(family)) {
-    if (scripts === null || scripts === undefined) return null;
-    const task = declaredTask(gate, block);
-    if (task !== undefined && Object.hasOwn(scripts, task)) return null;
-    return make(
-      ORPHANED,
-      `gates."${gate}"."${moment}" resolves to the task "${task}", and this ` +
-        `project has no such script. The hook runner would find nothing to ` +
-        `run, so the level in front of it describes nothing.`
-    );
-  }
   if (family === PULL_REQUEST) {
     if (Object.values(QUALITY_JOB_GATES).includes(gate)) return null;
     return make(
@@ -3015,10 +3192,44 @@ function verdictFor({ gate, block, moment, level, scripts, outsideFacade }) {
         `reported" indefinitely.`
     );
   }
+  // The deploy and continuous families have a generic runner the same way the
+  // hooks do — `lisa-run-gates.mjs --moment=<moment>` — but unlike a hook,
+  // which every repository installs, the CALLER is a workflow this repository
+  // either has or does not. So the question is asked of the repository rather
+  // than answered from a table: is there a workflow that hands this moment to
+  // the runner?
+  if (
+    MOMENT_FAMILIES.includes(family) &&
+    !executesMoment(executedMoments, moment)
+  ) {
+    return make(
+      NO_RUNNER_FOR_MOMENT,
+      `nothing in this repository runs gates at "${moment}": no workflow ` +
+        `under ${MOMENT_EXECUTOR_DIR} hands that moment to Lisa's gate ` +
+        `runner. The declaration is read, validated and listed, and then ` +
+        `never executed — inert rather than wrong. Add a caller for Lisa's ` +
+        `gates.yml at this moment (the shipped deploy.yml and ` +
+        `continuous-gates.yml templates do exactly that), or declare it ` +
+        `"off" to put on record that you meant it not to run.`
+    );
+  }
+  // Everything remaining is executed by the generic runner: a hook at its
+  // moment, or a workflow at a deploy or scheduled one. Both resolve a task and
+  // run it, so both need a task that exists.
+  if (scripts === null || scripts === undefined) return null;
+  const task = resolvedTaskFor({ gate, block, moment, scripts });
+  if (
+    task !== undefined &&
+    task !== null &&
+    Object.hasOwn(scripts ?? {}, task)
+  ) {
+    return null;
+  }
   return make(
-    NO_RUNNER_FOR_MOMENT,
-    `nothing runs gates at "${moment}" at all yet, so this declaration is ` +
-      `inert rather than wrong. A different defect, tracked separately.`
+    ORPHANED,
+    `gates."${gate}"."${moment}" resolves to the task "${task}", and this ` +
+      `project has no such script. The gate runner would find nothing to ` +
+      `run, so the level in front of it describes nothing.`
   );
 }
 
@@ -3877,7 +4088,15 @@ function main() {
     // suppress "configuration is valid" for every project that ever runs this,
     // which turns the verdict into noise and trains an operator to ignore both.
     reportUngoverned(gates);
-    const executors = classifyDeclaredExecutors({ gates, scripts });
+    // MEASURED, not assumed. Whether a deploy or continuous declaration has
+    // anything able to run it is a fact about THIS repository's workflows, and
+    // the answer changed the day a deploy façade shipped. Reading it here means
+    // the report cannot go stale in the reassuring direction.
+    const executors = classifyDeclaredExecutors({
+      gates,
+      scripts,
+      executedMoments: momentsExecutedBy(),
+    });
     // BLOCKING, and this is the change #2843 called "the substantive work".
     // The classifier existed as a vitest suite reading THIS repository's own
     // config — so the check existed for Lisa and did not exist for anyone Lisa

package/all/copy-overwrite/scripts/lisa-hooks/block-no-verify.sh

@@ -12,7 +12,9 @@
 #   2. HUSKY=0 / HUSKY_SKIP_HOOKS=... — disables husky-managed git hooks;
 #   3. core.hooksPath pointed anywhere but an allowlisted in-repo hooks dir;
 #   4. --config-env=core.hooksPath=VAR, in both the one- and two-token spellings;
-#   5. GIT_CONFIG_KEY_<n>=core.hooksPath env-var-style command-scope config.
+#   5. GIT_CONFIG_KEY_<n>=core.hooksPath env-var-style command-scope config;
+#   6. the short `-n`, as a real argv token of a `git commit` — bare, or bundled
+#      into a short-option cluster such as `-nm "msg"`.
 #
 # The line below is what lets `lisa apply` tell a downstream copy of this guard
 # that is BEHIND from one that is AHEAD. Byte comparison cannot: both look like
@@ -23,15 +25,31 @@
 # Add a name here in the same commit that closes a vector. A hardening that
 # forgets to is invisible to refresh, and shows up as an unexplained diff at
 # review time instead of a named capability.
-# lisa-guard-capabilities: no-verify-abbrev, husky-env, hookspath-allowlist, config-env, git-config-key
+# lisa-guard-capabilities: no-verify-abbrev, husky-env, hookspath-allowlist, config-env, git-config-key, no-verify-short
 #
 # Shell-token matching avoids false positives from issue bodies, heredocs, and
 # commit-message prose while still catching quoted real argv values such as
 # `git -c "core.hooksPath=/dev/null"`.
 #
-# The short `-n` form is intentionally NOT matched (see block-no-verify.agy.sh):
-# grep cannot distinguish a real -n option from -n in commit-message prose or an
-# unrelated piped command, and -n is far more common than --no-verify.
+# The short `-n` form used to be excluded here, and the stated reason was that
+# "grep cannot distinguish a real -n option from -n in commit-message prose or
+# an unrelated piped command". That was true of the matcher it was written for.
+# It is not true of this one: the command is TOKENIZED, not grepped, so `-m "fix
+# the -n flag"` is one token holding the message and `grep -n` is a separate
+# command — the two cases the comment called inseparable are separated by the
+# same machinery `--config-env` and `GIT_CONFIG_KEY_<n>` already depend on.
+#
+# A rationale that outlives the implementation it describes is worse than none:
+# it reads as a considered decision and stops the next reader from re-examining
+# it. Measured against real git, `git commit -n`, `-nm msg`, and `-anm msg` all
+# skip pre-commit exactly as completely as `--no-verify`, and `-nm` is the more
+# likely spelling in practice because it reads as an ordinary message flag.
+#
+# What the old comment got right is the part about `-n` being common, and that
+# concern is answered by SCOPE rather than by giving up: `-n` is `--dry-run` for
+# `push`, `--no-stat` for `merge`, and a line count for head/tail/sort/grep, so
+# the match is confined to the argv of a `git commit` invocation and nothing
+# else. See `git_commit_skips_verification` below.
 set -euo pipefail
 
 input="$(cat)"
@@ -168,6 +186,203 @@ def disables_verification(token):
         and NO_VERIFY.startswith(token)
     )
 
+
+# `git commit -n` is the short spelling of --no-verify and skips pre-commit and
+# commit-msg identically. Matching it needs one thing the `--no-verify` scan
+# above does not: SCOPE. `-n` means --dry-run to `git push`, --no-stat to `git
+# merge`, and a line count to head/tail/sort/grep, so a token-anywhere match
+# would refuse ordinary commands all day. Only `git commit` reads it as a hook
+# bypass, so only that invocation's argv is scanned.
+#
+# The tokenizer below is a SECOND pass, deliberately not shared with the one the
+# checks above use. `shlex.split` leaves `|` and `;` glued to their neighbours,
+# which those checks paper over by stripping the punctuation off each token —
+# fine when the question is "does this token look like a bypass anywhere in the
+# line", fatal when the question is "where does this command end", because
+# `git commit -m x && grep -n foo` would then read as one long git invocation
+# and refuse the grep. `punctuation_chars=True` emits the operators as their own
+# tokens, so the invocation's boundary is a token the scan can stop at.
+COMMAND_SEPARATORS = {
+    ";", "|", "||", "&", "&&", "(", ")", "<", ">", ">>", "<<", "&|",
+}
+
+# git's own options that take a SEPARATE value token, which therefore must be
+# skipped when looking for the subcommand: `git -c core.hooksPath=x commit` and
+# `git -C /repo commit` both reach `commit`.
+GIT_GLOBAL_SEPARATE_VALUE = {
+    "-c", "-C", "--config-env", "--git-dir", "--work-tree",
+    "--namespace", "--exec-path", "--super-prefix",
+}
+
+# `git commit` long options whose value can be a separate token. Listed so the
+# VALUE is never mistaken for a flag — `git commit --author "A -n B" -m x`
+# must stay allowed. Only genuinely value-taking options belong here: adding a
+# boolean one by mistake would swallow the token after it, and `git commit
+# --amend -n` would go unnoticed.
+COMMIT_LONG_SEPARATE_VALUE = {
+    "--message", "--file", "--author", "--date", "--template", "--cleanup",
+    "--reuse-message", "--reedit-message", "--fixup", "--squash",
+    "--pathspec-from-file", "--trailer",
+}
+
+# Short `git commit` options that REQUIRE a value: `-m`/`-F`/`-c`/`-C`/`-t`.
+# In a cluster the value is whatever follows them in the same token, or the next
+# token when nothing does — which is why `-mn` is the message "n" and not a
+# bypass, and `-nm msg` IS one.
+COMMIT_SHORT_REQUIRED_VALUE = set("mFcCt")
+
+# Short options taking an OPTIONAL value, which git only ever reads attached:
+# `-uno` is --untracked-files=no, `-Skeyid` is --gpg-sign=keyid. The cluster
+# ends at them either way, so `-un` is untracked-files "n" rather than a bypass.
+COMMIT_SHORT_OPTIONAL_VALUE = set("uS")
+
+
+def line_boundaries_as_separators(text):
+    """Turn newlines into command separators, keeping continuations intact.
+
+    A newline ends a command exactly as `;` does, but shlex treats it as plain
+    whitespace — so `git commit -m x` on one line and `grep -n foo` on the next
+    read as ONE invocation and the grep gets refused. That is the same
+    false-positive class the short-form match exists to avoid, arriving through
+    the boundary rather than through the token.
+
+    Backslash-newline is joined first, because there the newline is NOT a
+    boundary: `git commit \\` + newline + `-nm x` is one command, and turning
+    that newline into a separator would hide a real bypass.
+
+    Args:
+        text: The command line, heredoc payloads already stripped.
+
+    Returns:
+        The same command with line breaks spelled as separators.
+    """
+    joined = text.replace("\r\n", "\n").replace("\\\n", " ")
+    return joined.replace("\n", " ; ")
+
+
+def shell_tokens(text):
+    """Tokenize a command with shell operators kept as their own tokens.
+
+    Args:
+        text: The command line, heredoc payloads already stripped.
+
+    Returns:
+        The token list, with `;`, `|`, `&&`, `(` and friends standing alone.
+    """
+    lexer = shlex.shlex(
+        line_boundaries_as_separators(text), posix=True, punctuation_chars=True
+    )
+    lexer.whitespace_split = True
+    # shlex treats `#` as a comment introducer by default and would silently
+    # truncate the rest of the line; `shlex.split` disables it, and so must this.
+    lexer.commenters = ""
+    return list(lexer)
+
+
+def cluster_skips_verification(cluster):
+    """Read a short-option cluster the way git's own parser reads it.
+
+    Args:
+        cluster: A single token beginning with one `-`, e.g. `-nm` or `-mn`.
+
+    Returns:
+        A pair (bypasses, consumes_next_token). `bypasses` is True when a real
+        `-n` option is present; `consumes_next_token` is True when the cluster
+        ends in a value-taking option whose value is the following token.
+    """
+    body = cluster[1:]
+    for offset, letter in enumerate(body):
+        if letter == "n":
+            return (True, False)
+        if letter in COMMIT_SHORT_REQUIRED_VALUE:
+            # Everything after this letter is the value. It is a separate token
+            # only when nothing is attached.
+            return (False, offset == len(body) - 1)
+        if letter in COMMIT_SHORT_OPTIONAL_VALUE:
+            return (False, False)
+    return (False, False)
+
+
+def commit_bypasses_verification(argv):
+    """Whether a `git commit` invocation's argv carries a real short `-n`.
+
+    Args:
+        argv: Tokens following the `commit` subcommand, to the end of the line.
+
+    Returns:
+        True if git would read one of them as --no-verify.
+    """
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        index += 1
+        # `--` ends the options; everything after it is a pathspec, and a file
+        # legitimately named `-n` is not a bypass.
+        if token in COMMAND_SEPARATORS or token == "--":
+            return False
+        if token.startswith("--"):
+            if token in COMMIT_LONG_SEPARATE_VALUE:
+                index += 1
+            continue
+        # A bare `-` is git's stdin placeholder, not an option cluster.
+        if not token.startswith("-") or token == "-":
+            continue
+        bypasses, consumes_next = cluster_skips_verification(token)
+        if bypasses:
+            return True
+        if consumes_next:
+            index += 1
+    return False
+
+
+def subcommand_after_git(tokens, start):
+    """Find the subcommand a `git` token introduces, and its argv.
+
+    Args:
+        tokens: The full operator-aware token list.
+        start: Index just past the `git` token.
+
+    Returns:
+        A pair (subcommand, argv), or None when the invocation names none.
+    """
+    index = start
+    while index < len(tokens):
+        token = tokens[index]
+        if token in COMMAND_SEPARATORS:
+            return None
+        if not token.startswith("-"):
+            return (token, tokens[index + 1:])
+        index += 2 if token in GIT_GLOBAL_SEPARATE_VALUE else 1
+    return None
+
+
+def git_commit_skips_verification(text):
+    """Whether the command runs `git commit` with the short `-n` bypass.
+
+    Args:
+        text: The command line, heredoc payloads already stripped.
+
+    Returns:
+        True if any `git commit` invocation on the line skips verification.
+    """
+    try:
+        scoped_tokens = shell_tokens(text)
+    except ValueError:
+        return False
+    for index, token in enumerate(scoped_tokens):
+        # `/usr/bin/git` and a bare `git` are the same program; an env prefix
+        # (`HUSKY=1 git commit -n`) simply sits in an earlier token.
+        if token != "git" and not token.endswith("/git"):
+            continue
+        found = subcommand_after_git(scoped_tokens, index + 1)
+        if found and found[0] == "commit" and commit_bypasses_verification(found[1]):
+            return True
+    return False
+
+
+if git_commit_skips_verification(strip_heredocs(command)):
+    sys.exit(1)
+
 for i, token in enumerate(normalized_tokens):
     if disables_verification(token):
         sys.exit(1)
@@ -238,8 +453,10 @@ sys.exit(0)
 PY
 then
   cat >&2 <<'EOF'
-Blocked: this command bypasses pre-commit/pre-push hooks (--no-verify, HUSKY=0,
-or core.hooksPath disabling). Fix the underlying issue (security audit, lint,
+Blocked: this command bypasses pre-commit/pre-push hooks (--no-verify or its
+short form -n, HUSKY=0, or core.hooksPath disabling). `git commit -n` and a
+cluster such as `-nm "msg"` skip pre-commit exactly as completely as the long
+flag. Fix the underlying issue (security audit, lint,
 typecheck, tests, formatting) instead. If a fix is genuinely impossible, ask the
 user to make the risk-acceptance decision and add a specific documented ignore;
 never bypass the hook.