@event4u/agent-config 14.14.0 → 14.15.0

package/src/scripts/grade_target_readiness.ts

@@ -7,7 +7,7 @@
  * written in a command's markdown cannot be asserted by anything. So the
  * detection is here and the command invokes it; the command keeps the narrative.
  *
- * THE ANTI-VANITY RULE IS STRUCTURAL, NOT A STYLE NOTE. Ten dimensions are
+ * THE ANTI-VANITY RULE IS STRUCTURAL, NOT A STYLE NOTE. Thirteen dimensions are
  * graded 0 Absent / 1 Present / 2 Enforced-in-CI / 3 Independent-and-diff-scoped,
  * and the verdict is `min` over the FOUR knockout dimensions, reported as
  * `L<n> — bound by <dimension>`. **No aggregate number is ever emitted** — no
@@ -113,6 +113,66 @@ function _ciText(root: string): string {
     return out;
 }
 
+/* -- bounded text corpus, for the Phase 4 dimensions ----------------------- */
+
+/** Directories a target scan must never descend into: cost with no signal. */
+const _SKIP_DIRS = new Set([
+    'node_modules', '.git', 'vendor', 'dist', 'build', 'out', 'coverage',
+    '.next', '.nuxt', '.venv', 'venv', '__pycache__', 'target', '.terraform',
+]);
+/** Extensions that can carry a DNS record, a policy doc or an ops runbook. */
+const _CORPUS_RE = /\.(tf|tfvars|hcl|ya?ml|json|txt|zone|dns|ini|conf|cfg|toml|md|env|example|sh)$/i;
+const _CORPUS_MAX_FILES = 2000;
+const _CORPUS_MAX_BYTES = 256 * 1024;
+
+/**
+ * Read a bounded slice of the target's text, once, for the dimensions that
+ * cannot be answered by a root-level `_exists` probe.
+ *
+ * Three dimensions need to see INSIDE files — a DMARC policy is a string in a
+ * zone file or a Terraform record, not a filename — and the existing probes are
+ * all filename-shaped. The walk is capped in three directions (skip list, file
+ * count, per-file bytes) because an unbounded read of an arbitrary target repo
+ * is a cost this grader has no way to predict.
+ *
+ * Returns the concatenated text AND the relative paths, because a dimension that
+ * says WHERE it saw something is auditable and one that only says "somewhere in
+ * the tree" is not.
+ */
+export function _textCorpus(root: string): { text: string; paths: string[] } {
+    const paths: string[] = [];
+    let text = '';
+    const walk = (dir: string, rel: string): void => {
+        if (paths.length >= _CORPUS_MAX_FILES) return;
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (paths.length >= _CORPUS_MAX_FILES) return;
+            const abs = path.join(dir, e.name);
+            const r = rel === '' ? e.name : `${rel}/${e.name}`;
+            if (e.isDirectory()) {
+                if (_SKIP_DIRS.has(e.name)) continue;
+                walk(abs, r);
+                continue;
+            }
+            if (!_CORPUS_RE.test(e.name)) continue;
+            try {
+                if (fs.statSync(abs).size > _CORPUS_MAX_BYTES) continue;
+                text += `${fs.readFileSync(abs, 'utf-8')}\n`;
+            } catch {
+                continue;
+            }
+            paths.push(r);
+        }
+    };
+    walk(root, '');
+    return { text, paths };
+}
+
 /**
  * Is this a Python-primary target?
  *
@@ -125,7 +185,7 @@ export function isPythonTarget(root: string): boolean {
     return py && !other;
 }
 
-// ── the ten dimensions ─────────────────────────────────────────────────────
+// ── the thirteen dimensions ──
 
 /**
  * Grade one dimension. `ci` decides 1 → 2: a thing that exists is `Present`; a
@@ -149,6 +209,113 @@ function _ciBlocks(ci: string, ...needles: string[]): boolean {
     return !allSoft;
 }
 
+/* -- Phase 4 dimension ladders --------------------------------------------- */
+
+interface Scored {
+    grade: Grade;
+    evidence: string;
+}
+
+/** A runbook, a restore procedure, or a rollback path — and whether CI runs it. */
+function _recovery(corpus: { text: string; paths: string[] }, ci: string): Scored {
+    const namedFile = corpus.paths.some((p) => /(^|\/)(runbook|runbooks|disaster-recovery|dr)([./-]|$)/i.test(p));
+    const procedure = /\b(restore from backup|disaster recovery|rollback plan|pg_restore|pg_dump|restic|velero|RPO|RTO)\b/i.test(corpus.text);
+    const present = namedFile || procedure;
+    const enforced = _ciBlocks(ci, 'restore', 'rollback', 'disaster-recovery', 'backup');
+    // A DRILL is what separates a documented procedure from a proven one. It is
+    // the only honest route to 3 here, because "independent" for recovery means
+    // the restore was actually exercised rather than described.
+    const drill = /\b(restore (drill|test|rehearsal)|recovery drill|game ?day)\b/i.test(corpus.text);
+    const seen: string[] = [
+        ...(namedFile ? ['a runbook or DR document'] : []),
+        ...(procedure ? ['a restore/rollback procedure in the text'] : []),
+        ...(enforced ? ['a blocking CI step naming restore/rollback/backup'] : []),
+        ...(drill ? ['a restore drill'] : []),
+    ];
+    return {
+        grade: _graded(present, enforced, drill),
+        evidence: seen.length > 0 ? seen.join('; ') : 'no runbook, restore procedure or rollback path found',
+    };
+}
+
+/**
+ * SPF, DKIM and DMARC — and the rung that must not be fudged (4.2).
+ *
+ *   0 Absent   — no SPF, DKIM or DMARC RECORD anywhere. Prose about DMARC is
+ *                not a DMARC record; the signal is the record shape.
+ *   1 Present  — SPF and/or DKIM published, OR a DMARC record with `p=none`.
+ *                `p=none` is a MONITORING policy: it requests aggregate reports
+ *                and instructs receivers to take no action on a failing message.
+ *                A domain publishing it is measuring the problem, not preventing
+ *                it, so it is capped here however much else sits alongside it.
+ *   2 Enforced — DMARC `p=quarantine` or `p=reject`, with SPF or DKIM to align
+ *                against. An enforcing policy with nothing to align is a policy
+ *                over no signal, and stays at 1.
+ *   3 Top      — `p=reject` with BOTH SPF and DKIM and an `rua=` reporting
+ *                address, so the enforcement can be observed rather than assumed.
+ */
+function _mailAuthenticity(corpus: { text: string }): Scored {
+    const t = corpus.text;
+    const spf = /v=spf1\b/i.test(t);
+    const dkim = /v=DKIM1\b/i.test(t);
+    const dmarc = /v=DMARC1\b/i.test(t);
+    const policy = /v=DMARC1[^"'\n]*?\bp\s*=\s*(none|quarantine|reject)\b/i.exec(t)?.[1]?.toLowerCase();
+    const rua = /v=DMARC1[^"'\n]*?\brua\s*=/i.test(t);
+    const aligned = spf || dkim;
+    const parts = [
+        spf ? 'SPF published' : 'no SPF record',
+        dkim ? 'DKIM published' : 'no DKIM record',
+        dmarc ? `DMARC published (p=${policy ?? 'unset'})` : 'no DMARC record',
+    ];
+    if (!spf && !dkim && !dmarc) {
+        return { grade: 0, evidence: 'no SPF, DKIM or DMARC record found in the tree' };
+    }
+    if (policy === 'none') {
+        return {
+            grade: 1,
+            evidence:
+                `${parts.join('; ')} — capped at Present: p=none is a monitoring policy and is NOT protection, ` +
+                'because receivers are told to take no action on a message that fails. A domain publishing it ' +
+                'scores below one that enforces.',
+        };
+    }
+    if (policy === 'quarantine' || policy === 'reject') {
+        if (!aligned) {
+            return {
+                grade: 1,
+                evidence: `${parts.join('; ')} — an enforcing policy with neither SPF nor DKIM to align against protects nothing yet`,
+            };
+        }
+        if (policy === 'reject' && spf && dkim && rua) {
+            return { grade: 3, evidence: `${parts.join('; ')} — enforcing, both mechanisms aligned, and reporting to an rua address` };
+        }
+        return { grade: 2, evidence: `${parts.join('; ')} — an enforcing DMARC policy with an aligned mechanism` };
+    }
+    return { grade: 1, evidence: `${parts.join('; ')} — a mail-authenticity record exists, with no enforcing DMARC policy above it` };
+}
+
+/** A privacy notice, a retention rule, a consent mechanism, a deletion path. */
+function _privacyObligations(corpus: { text: string; paths: string[] }, ci: string): Scored {
+    const notice =
+        corpus.paths.some((p) => /(privacy|datenschutz|\bdpa\b|data-processing)/i.test(p)) ||
+        /\b(privacy (policy|notice)|Datenschutzerkl)/i.test(corpus.text);
+    const retention = /\b(retention (policy|period|schedule)|data retention|storage limitation)\b/i.test(corpus.text);
+    const consent = /\b(cookie consent|consent (banner|manager|mode)|cookiebot|usercentrics|klaro|borlabs)\b/i.test(corpus.text);
+    const erasure = /\b(right to erasure|data subject request|DSAR|DSR|account deletion|delete my data)\b/i.test(corpus.text);
+    const enforced = _ciBlocks(ci, 'privacy', 'gdpr', 'retention', 'consent', 'dsar');
+    const seen: string[] = [
+        ...(notice ? ['a privacy notice or DPA'] : []),
+        ...(retention ? ['a retention rule'] : []),
+        ...(consent ? ['a consent mechanism'] : []),
+        ...(erasure ? ['an erasure / data-subject-request path'] : []),
+        ...(enforced ? ['a blocking CI step naming a privacy obligation'] : []),
+    ];
+    return {
+        grade: _graded(notice || retention || consent || erasure, enforced),
+        evidence: seen.length > 0 ? seen.join('; ') : 'no privacy notice, retention rule, consent mechanism or erasure path found',
+    };
+}
+
 export function grade(root: string): Matrix {
     const ci = _ciText(root);
     const hasCi = ci !== '';
@@ -310,6 +477,41 @@ export function grade(root: string): Matrix {
         evidence: 'out of scope by design (see the roadmap exclusion table)',
     });
 
+    // 11. operational recovery — NON-KNOCKOUT
+    //
+    // New dimensions are never knockouts. A knockout added today would re-bind
+    // every existing verdict at L0 on the day it shipped, which changes what the
+    // level MEANS while looking like a change to what it measures.
+    const corpus = _textCorpus(root);
+    const recovery = _recovery(corpus, ci);
+    dims.push({
+        id: 'operational-recovery',
+        label: 'operational recovery',
+        knockout: false,
+        grade: recovery.grade,
+        evidence: recovery.evidence,
+    });
+
+    // 12. mail authenticity — NON-KNOCKOUT, own ladder (4.2)
+    const mail = _mailAuthenticity(corpus);
+    dims.push({
+        id: 'mail-authenticity',
+        label: 'mail authenticity',
+        knockout: false,
+        grade: mail.grade,
+        evidence: mail.evidence,
+    });
+
+    // 13. privacy obligations — NON-KNOCKOUT
+    const privacy = _privacyObligations(corpus, ci);
+    dims.push({
+        id: 'privacy-obligations',
+        label: 'privacy obligations',
+        knockout: false,
+        grade: privacy.grade,
+        evidence: privacy.evidence,
+    });
+
     // ── the verdict: min over knockouts, undetectable binds at L0 ──────────
     const knockouts = dims.filter((d) => d.knockout);
     const undetectable = knockouts.find((d) => d.grade === null);
@@ -440,6 +642,23 @@ export function selfTest(): number {
                 return /%|\/100/.test(out) ? 1 : 0;
             },
         },
+        {
+            name: 'DMARC p=none scores strictly below p=quarantine — monitoring is not protection',
+            expect: 'accept',
+            run: () => {
+                const g = (zone: string): number => {
+                    const d = grade(mk({
+                        'dns/zone.txt': zone,
+                        'dns/spf.txt': '@ IN TXT "v=spf1 include:_spf.example.net -all"\n',
+                        'dns/dkim.txt': 'sel._domainkey IN TXT "v=DKIM1; k=rsa; p=MIIB"\n',
+                    }));
+                    return d.dimensions.find((x) => x.id === 'mail-authenticity')?.grade ?? -1;
+                };
+                const none = g('_dmarc IN TXT "v=DMARC1; p=none; rua=mailto:d@example.com"\n');
+                const quarantine = g('_dmarc IN TXT "v=DMARC1; p=quarantine; rua=mailto:d@example.com"\n');
+                return none === 1 && quarantine === 2 ? 0 : 1;
+            },
+        },
         {
             name: 'rejects a missing target root rather than grading an empty tree',
             expect: 'reject',

package/src/scripts/hook_effect_doctor.ts

@@ -42,8 +42,13 @@
  * measurement runs first.
  *
  * Usage:
- *   ./scripts-run src/scripts/hooks_doctor [--host <name>] [--format text|json]
- *     [--root <path>] [--limit <n>]
+ *   ./agent-config hooks:effect [--host <name>] [--format text|json]
+ *     [--root <path>] [--limit <n>] [--help]
+ *   ./scripts-run src/scripts/hook_effect_doctor  (same flags, in this checkout)
+ *
+ * `--help` prints the two verdict vocabularies FROM THE MODULE THAT DEFINES
+ * THEM. A help text that restated them by hand would be a fifth hand-typed copy
+ * of a closed set, which is the drift class this repository gates elsewhere.
  */
 import { spawnSync } from 'node:child_process';
 import * as crypto from 'node:crypto';
@@ -51,7 +56,13 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 
-import { buildHostReport, type ConcernProbe, type HostReport } from './_lib/hook_effect_probe.js';
+import {
+    HOST_VERDICTS,
+    PROBE_STATES,
+    buildHostReport,
+    type ConcernProbe,
+    type HostReport,
+} from './_lib/hook_effect_probe.js';
 
 const HERE = path.dirname(new URL(import.meta.url).pathname);
 const REPO_ROOT = path.resolve(HERE, '..', '..');
@@ -230,6 +241,34 @@ export function renderText(r: HostReport): string {
     return out.join('\n') + '\n';
 }
 
+/**
+ * The synopsis, both closed vocabularies, and the scope line.
+ *
+ * Rendered from `PROBE_STATES` and `HOST_VERDICTS` rather than restated, so the
+ * help can never describe a vocabulary the probe no longer has.
+ */
+export function renderHelp(): string {
+    return [
+        'agent-config hooks:effect — does a bound concern actually FIRE on this host?',
+        '',
+        'Usage: agent-config hooks:effect [--host <name>] [--format text|json]',
+        '                                 [--root <path>] [--limit <n>] [--help]',
+        '',
+        'Not hooks:doctor. That one reads the MANIFEST — which concerns are declared,',
+        'their posture, whether their scripts and trampolines exist. This one dispatches',
+        'each eligible concern against a scratch root and reports what was observed.',
+        '',
+        `per-concern states:  ${PROBE_STATES.join(' · ')}`,
+        `host verdicts:       ${HOST_VERDICTS.join(' · ')}`,
+        '',
+        '`unknown` is never rendered as `effective`: a concern that wrote in the sandbox,',
+        'or that could not be dispatched at all, is reported as unestablished — never as a',
+        'working configuration.',
+        '',
+        'Exits 0 on every verdict. An `inert` host is information, not a build failure.',
+    ].join('\n') + '\n';
+}
+
 export function main(argv: string[] = process.argv.slice(2)): number {
     let host = 'claude';
     let format: 'text' | 'json' = 'text';
@@ -237,6 +276,10 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     let limit = 200;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
+        if (a === '--help' || a === '-h') {
+            process.stdout.write(renderHelp());
+            return 0;
+        }
         if (a === '--host') host = argv[++i] ?? host;
         else if (a === '--format') format = (argv[++i] as 'text' | 'json') ?? format;
         else if (a === '--root') root = path.resolve(argv[++i] ?? root);
@@ -246,7 +289,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     try {
         report = buildReport(root, host, limit);
     } catch (err) {
-        process.stderr.write(`❌  hooks_doctor: ${(err as Error).message}\n`);
+        process.stderr.write(`❌  hooks:effect: ${(err as Error).message}\n`);
         return 2;
     }
     process.stdout.write(format === 'json' ? JSON.stringify(report, null, 2) + '\n' : renderText(report));

package/src/scripts/hooks/block_unauthorized_git.ts

@@ -61,12 +61,16 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { readHookStdin } from "./hook_stdin.js";
+import { analyseMergeImpact, describeImpact } from "./merge_impact.js";
 import { atomic_write_json } from "./state_io.js";
 import {
+  consumeGrantTarget,
   ledgerFileFor,
   pendingFileFor,
+  readGrants,
   STATE_FILE,
   type GitOp,
+  type MergeGrant,
 } from "../git_authorization_hook.js";
 
 const EXIT_ALLOW = 0;
@@ -95,6 +99,31 @@ export const BLOCK_OPS: ReadonlySet<GitOp> = new Set<GitOp>([
   // Enabling auto-merge commits the outcome to a condition the agent does not
   // control, so it is blocked on the same terms as the merge it schedules.
   "pr-merge-auto",
+
+  // ── Added 2026-09-03. Every one is already never-autonomous in the
+  // `non-destructive-by-default` prose; the measurement that drove it is in the
+  // `GitOp` union's own note — 17 of 25 borderline operations classified as
+  // NOTHING, including three worse than anything the guard already caught.
+  /** The undo that is more destructive than the act: lockfiles break. */
+  "unpublish",
+  /** Metadata only, and every install on earth starts warning. */
+  "deprecate",
+  /** Replaces bytes consumers already hold a checksum for. */
+  "release-asset",
+  /** Deletes the guard rather than the data — everything after is unguarded. */
+  "protection",
+  /** No data lost; the gate that protects everything downstream is off. */
+  "workflow-toggle",
+  /** Reach outside the repository, and mostly one-way. */
+  "repo-lifecycle",
+  /** No code moves, and an armed auto-merge is released. */
+  "review-approve",
+  /** Discards commits that landed after the last fetch, on a shared ref. */
+  "force-push",
+  /** Destroys uncommitted work belonging to a session this one cannot see. */
+  "worktree-remove",
+  /** `-x` is the flag that takes `.env` and local certificates. */
+  "clean-ignored",
 ]);
 
 /** Recoverable operations — warned without a this-turn authorization. */
@@ -103,6 +132,22 @@ export const WARN_OPS: ReadonlySet<GitOp> = new Set<GitOp>([
   "push",
   "pr-create",
   "branch",
+
+  // ── Added 2026-09-03, deliberately at warn rather than block.
+  //
+  // Each is destructive in some reading, and each is also routine enough that
+  // blocking it would be the friction that gets the whole guard routed around —
+  // the failure mode this estate has already recorded twice. `reset-hard` is the
+  // sharpest case and stays here for a decidable reason: the Hard Floor's
+  // qualifier is "past unpushed work", and the command text cannot say whether
+  // the work was pushed.
+  "tag-force",
+  "rebase",
+  "reset-hard",
+  "clean",
+  "stash-drop",
+  "branch-delete",
+  "close",
 ]);
 
 /**
@@ -191,6 +236,74 @@ const COMMAND_OPS: ReadonlyArray<{ op: GitOp; re: RegExp }> = [
     op: "pr-create",
     re: new RegExp(`${P}gh\\s+pr\\s+create\\b|${ghApiWrite("\\/pulls\\b").source}`, "i"),
   },
+  // ── Added 2026-09-03. Placement inside this table is as load-bearing as the
+  // patterns: the loop takes the MOST SEVERE match per segment, but within one
+  // op the first pattern wins, so anything more specific than a plain `git push`
+  // has to sit above it.
+
+  // `npm unpublish` is NOT reached by the publish pattern — `\bpublish\b` needs
+  // a word boundary that `unpublish` does not provide between `n` and `p`. That
+  // is why it classified as nothing for as long as it did.
+  { op: "unpublish", re: new RegExp(`${P}(npm|pnpm|yarn)\\s+${G}unpublish\\b`, "i") },
+  { op: "deprecate", re: new RegExp(`${P}(npm|pnpm|yarn)\\s+${G}deprecate\\b`, "i") },
+  {
+    op: "release-asset",
+    re: new RegExp(`${P}gh\\s+release\\s+(upload|edit|delete)\\b`, "i"),
+  },
+  {
+    op: "protection",
+    re: new RegExp(
+      `${P}gh\\s+api\\b(?=[^\\n]*(?:protection|rulesets?)\\b)(?=[^\\n]*(?:-X|--method)\\s+(?:DELETE|PUT|PATCH|POST)\\b)|${P}gh\\s+ruleset\\s+delete\\b`,
+      "i",
+    ),
+  },
+  {
+    op: "workflow-toggle",
+    re: new RegExp(`${P}gh\\s+workflow\\s+(disable|enable)\\b`, "i"),
+  },
+  {
+    op: "repo-lifecycle",
+    re: new RegExp(
+      `${P}gh\\s+repo\\s+(archive|delete|unarchive)\\b|${P}gh\\s+repo\\s+edit\\b(?=[^\\n]*--visibility\\b)`,
+      "i",
+    ),
+  },
+  {
+    op: "review-approve",
+    re: new RegExp(`${P}gh\\s+pr\\s+review\\b(?=[^\\n]*--approve\\b)`, "i"),
+  },
+  // Above `push`, and both spellings: `--force` and `--force-with-lease`. The
+  // "safe force" is in the same class here because what it is safe against is a
+  // stale local view, not a collaborator who pushed after your fetch.
+  {
+    op: "force-push",
+    re: new RegExp(`${P}git\\s+${G}push\\b[^\\n;|&]*(--force\\b|--force-with-lease\\b|\\s-f\\b)`, "i"),
+  },
+  {
+    op: "worktree-remove",
+    re: new RegExp(`${P}git\\s+worktree\\s+remove\\b[^\\n;|&]*(--force\\b|\\s-f\\b)`, "i"),
+  },
+  // `-x` (or `-X`) anywhere in the flag cluster is what reaches ignored files.
+  {
+    op: "clean-ignored",
+    re: new RegExp(`${P}git\\s+clean\\b[^\\n;|&]*-[A-Za-z]*x`, "i"),
+  },
+  { op: "tag-force", re: new RegExp(`${P}git\\s+tag\\b[^\\n;|&]*(-f\\b|--force\\b)`, "i") },
+  { op: "rebase", re: new RegExp(`${P}git\\s+${G}rebase\\b`, "i") },
+  { op: "reset-hard", re: new RegExp(`${P}git\\s+${G}reset\\b[^\\n;|&]*--hard\\b`, "i") },
+  { op: "clean", re: new RegExp(`${P}git\\s+clean\\b`, "i") },
+  { op: "stash-drop", re: new RegExp(`${P}git\\s+stash\\s+(drop|clear)\\b`, "i") },
+  // Remote deletion and the local `-D` are one op: both remove a ref, and the
+  // remote form additionally closes any open PR pointing at it.
+  {
+    op: "branch-delete",
+    re: new RegExp(
+      `${P}git\\s+branch\\b[^\\n;|&]*(-D\\b|--delete\\b)|${P}git\\s+${G}push\\b[^\\n;|&]*(--delete\\b|\\s:\\S)`,
+      "i",
+    ),
+  },
+  { op: "close", re: new RegExp(`${P}gh\\s+(pr|issue)\\s+close\\b`, "i") },
+
   { op: "push", re: new RegExp(`${P}git\\s+${G}push\\b`, "i") },
   { op: "commit", re: new RegExp(`${P}git\\s+${G}commit\\b`, "i") },
   { op: "branch", re: new RegExp(`${P}git\\s+${G}(checkout\\s+-b|switch\\s+-c)\\b`, "i") },
@@ -503,6 +616,55 @@ export function commandOp(command: string): GitOp | null {
   return found;
 }
 
+/**
+ * The pull request a merge command acts on, or `null` when the command does not
+ * say.
+ *
+ * `gh pr merge` with no number merges whatever the current branch's PR is — the
+ * command text identifies no object, so no grant can match it and the
+ * clock-bound path applies unchanged. That is the fail-closed direction: an
+ * unnamed target never consumes a grant minted for a named one.
+ */
+export function mergeTargetOf(command: string): number | null {
+  const gh = /\bgh\s+pr\s+merge\s+(?:-{1,2}\S+\s+)*?(\d{1,7})\b/i.exec(command);
+  if (gh) {
+    return Number.parseInt(gh[1] as string, 10);
+  }
+  // The same operation by its REST spelling. `commandOp` already classifies
+  // `gh api -X PUT repos/o/r/pulls/1499/merge` as `pr-merge`, so a reader that
+  // missed it here would silently fall back to the clock.
+  const api = /\/pulls\/(\d{1,7})\/merge\b/i.exec(command);
+  return api ? Number.parseInt(api[1] as string, 10) : null;
+}
+
+/**
+ * Does a standing grant cover this exact merge?
+ *
+ * Three conditions, all necessary: the grant is for this op, the command named
+ * a target, and that target sits in the grant's frozen set unspent.
+ *
+ * No clock is consulted here, and that is the whole of ADR-252. `authorized`
+ * answers "did the user name this operation recently"; a grant answers "did the
+ * user name this operation AND this pull request". The second question does not
+ * decay with time, because the object it names cannot drift into a different
+ * object — a force-push changes the SHA, but the grant is spent on first use, so
+ * a merge that already happened can never be replayed against a moved head.
+ */
+export function grantCovers(
+  grants: MergeGrant[],
+  op: GitOp,
+  target: number | null,
+): MergeGrant | null {
+  if (op !== "pr-merge" || target === null) {
+    return null;
+  }
+  return (
+    grants.find(
+      (g) => g.op === "pr-merge" && g.targets.includes(target) && !g.consumed.includes(target),
+    ) ?? null
+  );
+}
+
 /**
  * A ledger older than this is not "this turn" under any reading.
  *
@@ -558,7 +720,15 @@ function _loadLedger(
   consumer_root: string,
   session_id: string,
   now: number,
-): { authorized: Set<GitOp>; present: boolean } {
+): { authorized: Set<GitOp>; present: boolean; grants: MergeGrant[] } {
+  // Grants are read on their OWN path, and the separation is load-bearing.
+  // `_readLedgerFile` below discards the entire ledger once `detected_at` is
+  // older than `LEDGER_MAX_AGE_MS`, so folding grants into its return value
+  // would let the clock silently kill them too — the change would ship, look
+  // correct, and do nothing after thirty minutes, with no test going red.
+  // `readGrants` performs the session check and no age check, which is exactly
+  // the contract: object identity, not recency (ADR-252).
+  const grants = readGrants(consumer_root, session_id);
   // This session's own ledger first; the flat legacy file only as a fallback,
   // so a ledger written by an older build still counts. Reading the flat file
   // FIRST was the defect: any concurrent session in the repo overwrites it, and
@@ -570,10 +740,10 @@ function _loadLedger(
   for (const rel of candidates) {
     const found = _readLedgerFile(path.join(consumer_root, rel), session_id, now);
     if (found !== null) {
-      return found;
+      return { ...found, grants };
     }
   }
-  return { authorized: new Set<GitOp>(), present: false };
+  return { authorized: new Set<GitOp>(), present: false, grants };
 }
 
 /**
@@ -622,11 +792,21 @@ export interface Decision {
    * `git_authorization_hook.PENDING_FILE` for why that record exists at all.
    */
   blockedOp?: GitOp;
+  /**
+   * The grant target this decision spent, when a standing grant is what allowed
+   * it.
+   *
+   * `decide` stays pure; `run` turns this into the ledger write that marks the
+   * target used. Single use is the property that keeps a grant from being a
+   * standing licence: the user authorized merging PR #1499, once.
+   */
+  consumedTarget?: number;
 }
 
 export function decide(
   command: string | null,
-  ledger: { authorized: Set<GitOp>; present: boolean },
+  ledger: { authorized: Set<GitOp>; present: boolean; grants?: MergeGrant[] },
+  impact?: string,
 ): Decision {
   if (command === null) {
     return { exit: EXIT_ALLOW, stdout: "", stderr: "" };
@@ -636,13 +816,30 @@ export function decide(
     return { exit: EXIT_ALLOW, stdout: "", stderr: "" };
   }
 
+  // A standing grant is the SECOND way an operation can be authorized, and it
+  // is strictly narrower than the first rather than an escape from it. Only
+  // `pr-merge` can hold one, the command must name its pull request, and that
+  // number must sit unspent in a set the user's own sentence froze. An unnamed
+  // target matches nothing and a spent target matches nothing, so every path
+  // that is not exactly "the user named this PR and it has not been merged yet"
+  // falls through to the clock-bound decision below unchanged (ADR-252).
+  const target = mergeTargetOf(command);
+  if (grantCovers(ledger.grants ?? [], op, target) && target !== null) {
+    return { exit: EXIT_ALLOW, stdout: "", stderr: "", consumedTarget: target };
+  }
+
   const shown = command.length > 120 ? `${command.slice(0, 117)}…` : command;
 
   if (BLOCK_OPS.has(op)) {
+    // STAGE 2. The refusal stands either way — what the scan changes is whether
+    // the user has to go read the diff to answer it. `impact` is injected by
+    // `run`, never computed here, so `decide` stays pure and testable without a
+    // repository.
+    const scan = op === "pr-merge" && target !== null && impact ? ` ${impact}` : "";
     const reason =
       `Blocked: \`${op}\` with no authorization in this turn's prompt. ` +
       `This operation is irreversible and non-destructive-by-default already declares it ` +
-      `never-autonomous. Command: ${shown}. ` +
+      `never-autonomous. Command: ${shown}.${scan} ` +
       `Ask the user, in one numbered-options block, and run it only after they answer this turn.`;
     return { exit: EXIT_BLOCK, stdout: "", stderr: `${reason}\n`, blockedOp: op };
   }
@@ -675,10 +872,42 @@ export function run(stdin_text: string, options: { consumer_root: string }): num
     }
   }
   const session_id = typeof envelope["session_id"] === "string" ? envelope["session_id"] : "";
-  const decision = decide(
-    extractCommand(envelope),
-    _loadLedger(options.consumer_root, session_id, Date.now()),
-  );
+  const command = extractCommand(envelope);
+  const ledger = _loadLedger(options.consumer_root, session_id, Date.now());
+
+  // STAGE 2 runs only on the path where it can change something: a merge that is
+  // ABOUT to be refused. Not on an allowed merge (nothing to tell the user), not
+  // on an op whose target the command does not name, and never on publish or
+  // release — a scan costs a diff read, and spending one where it cannot change
+  // the outcome is latency in the user's critical path for nothing.
+  let impact: string | undefined;
+  const stage1 = command === null ? null : commandOp(command);
+  const stage2Target = command === null ? null : mergeTargetOf(command);
+  if (
+    stage1 === "pr-merge" &&
+    stage2Target !== null &&
+    !ledger.authorized.has("pr-merge") &&
+    !grantCovers(ledger.grants ?? [], "pr-merge", stage2Target)
+  ) {
+    try {
+      impact = describeImpact(
+        stage2Target,
+        analyseMergeImpact(stage2Target, { cwd: options.consumer_root }),
+      );
+    } catch {
+      // The scan is an enrichment, never a gate. A refusal without it is the
+      // pre-stage-2 message, which is still correct.
+    }
+  }
+
+  const decision = decide(command, ledger, impact);
+  if (decision.consumedTarget !== undefined) {
+    // Spend the target at the moment the merge is actually let through, never
+    // when the grant was minted. A grant the run never reached stays whole, and
+    // a pull request that merged can never be replayed — which is what makes a
+    // force-push back to an already-merged head harmless here.
+    consumeGrantTarget(options.consumer_root, session_id, decision.consumedTarget);
+  }
   if (decision.blockedOp) {
     // Record WHAT was refused, so the user's answer to the question this
     // refusal just told the agent to ask can authorize that one operation.