@bookedsolid/rea 0.12.0 → 0.13.0

package/.husky/commit-msg

@@ -1,4 +1,5 @@
 #!/bin/sh
+# rea:commit-msg v1
 # .husky/commit-msg — optionally BLOCKS commits that contain AI attribution
 #
 # OPT-IN: Only enforces when .rea/policy.yaml contains:
@@ -40,13 +41,34 @@ fi
 # Look for block_ai_attribution: true in .rea/policy.yaml
 # If not found or not true, exit 0 (normal commit behavior)
 
+# Helper: chain extension fragments under .husky/commit-msg.d/ in lex
+# order. Defined once and called from every exit path so consumers get
+# consistent behavior regardless of whether attribution blocking ran.
+chain_commit_msg_fragments() {
+  REA_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+  ext_dir="${REA_ROOT}/.husky/commit-msg.d"
+  if [ -d "$ext_dir" ]; then
+    for frag in "$ext_dir"/*; do
+      [ -e "$frag" ] || continue
+      [ -f "$frag" ] || continue
+      [ -x "$frag" ] || continue
+      "$frag" "$COMMIT_MSG_FILE"
+    done
+  fi
+}
+
 POLICY_FILE=".rea/policy.yaml"
 if [ ! -f "$POLICY_FILE" ]; then
+  chain_commit_msg_fragments
   exit 0
 fi
 
 # Simple grep — no YAML parser dependency needed for a boolean flag
 if ! grep -qE '^block_ai_attribution:[[:space:]]*true' "$POLICY_FILE" 2>/dev/null; then
+  # Attribution blocking is disabled — still chain extension fragments
+  # (consumers may want commitlint/conventional-commits checks regardless
+  # of rea's attribution stance).
+  chain_commit_msg_fragments
   exit 0
 fi
 
@@ -127,4 +149,14 @@ fi
 # Normalize trailing newlines (cosmetic, non-fatal)
 perl -i -0777 -pe 's/\n+$/\n/' "$COMMIT_MSG_FILE" 2>/dev/null || true
 
+# ── Extension-hook chaining ────────────────────────────────────────────────────
+# Source every executable file under `.husky/commit-msg.d/` in lexical order.
+# Missing directory = no-op (backward compatible). Each fragment receives the
+# commit-msg file path as $1. Non-zero exit fails the commit (set -e above).
+#
+# Fragments run AFTER rea's attribution check so HALT/governance enforcement
+# happens first; consumers can layer on commitlint, conventional-commits
+# linters, or branch-policy checks without losing rea coverage.
+chain_commit_msg_fragments
+
 exit 0

package/.husky/pre-push

@@ -1,6 +1,6 @@
 #!/bin/sh
-# rea:husky-pre-push-gate v3
-# rea:gate-body-v3
+# rea:husky-pre-push-gate v4
+# rea:gate-body-v4
 #
 # Husky pre-push hook installed by `rea init` / `rea upgrade`. Do NOT
 # edit by hand — the file is refreshed on every rea upgrade.
@@ -63,4 +63,48 @@ else
   exit 2
 fi
 
-exec "$@"
+# Run the rea push-gate FIRST. We capture its exit and explicitly propagate
+# instead of `exec`-ing — extension fragments must only run after rea's own
+# governance work succeeds. The fragments are user code; surfacing them
+# AFTER rea's body (HALT check, Codex review, audit write) preserves the
+# governance contract while letting consumers chain their own checks (e.g.
+# commitlint, branch-policy linters) without losing rea coverage.
+"$@"
+rea_status=$?
+if [ "$rea_status" -ne 0 ]; then
+  exit "$rea_status"
+fi
+
+# Extension-hook chaining: source every executable file under
+# `.husky/pre-push.d/` in lexical order. Missing directory = no-op
+# (backward compatible). Each fragment receives the original positional
+# args from git's `<remote-name> <remote-url>` invocation. Non-zero exit
+# from any fragment fails the push; this matches husky's normal hook
+# chaining semantics.
+#
+# The git pre-push contract delivers refspecs on stdin. Once rea's body has
+# consumed it (`exec rea hook push-gate "$@"` reads stdin during `runPushGate`),
+# subsequent fragments cannot replay it — that's by design: agents that need
+# refspec data should run before rea, not after. Fragments that need ambient
+# repo state can call `git rev-parse` themselves.
+ext_dir="${REA_ROOT}/.husky/pre-push.d"
+if [ -d "$ext_dir" ]; then
+  # Collect fragments deterministically. POSIX sort orders the same way on
+  # macOS (BSD sort) and Linux (GNU sort) for ASCII filenames; consumers who
+  # name their fragments `10-foo` / `20-bar` get predictable ordering.
+  for frag in "$ext_dir"/*; do
+    # Glob expands to itself when no matches — guard with -e.
+    [ -e "$frag" ] || continue
+    # Skip non-files (directories, sockets) and non-executables. The
+    # executable bit is the consumer's opt-in: dropping a non-executable
+    # README into the dir does not become a hook.
+    [ -f "$frag" ] || continue
+    [ -x "$frag" ] || continue
+    # Each fragment runs in its own subprocess with the original git args.
+    # Failures propagate via `set -eu` above (loop body inherits, so any
+    # non-zero exit blocks the push immediately).
+    "$frag" "$@"
+  done
+fi
+
+exit 0

package/README.md

@@ -348,6 +348,8 @@ review:
                               #   600000 in 0.12.0 — see CHANGELOG)
   last_n_commits: 10          # OPTIONAL — narrow review to the last N commits
                               #   (diff vs HEAD~N). Defaults unset.
+  auto_narrow_threshold: 30   # OPTIONAL — auto-narrow when commit count
+                              #   behind base > N (0 disables, default 30)
 ```
 
 | Key | Type | Default | Purpose |
@@ -356,6 +358,84 @@ review:
 | `review.concerns_blocks` | boolean | `true` | When `true`, `[P2]` verdicts return exit 2. Flip to `false` for a looser posture where only `[P1]` halts the push. |
 | `review.timeout_ms` | number | `1800000` | Hard cap on the `codex exec review` subprocess in milliseconds. Exceeding it kills the subprocess and returns exit 2 with a `timeout` kind. Positive integer; zero/negative is rejected at load. **Raised from 600000 (10 min) to 1800000 (30 min) in 0.12.0** after operator data showed realistic feature-branch reviews routinely exceeded 10 minutes; pin `timeout_ms: 600000` explicitly to retain the old default. |
 | `review.last_n_commits` | number | unset | When set, the gate diffs against `HEAD~N` instead of running the upstream → origin/HEAD → main/master ladder. Useful when a feature branch has accumulated many commits and the full base diff overwhelms the reviewer. Positive integer. CLI `--last-n-commits N` overrides this; `--base <ref>` overrides both. When `HEAD~N` is unreachable the resolver clamps based on whether the repo is a shallow clone: **(full clone, branch shorter than N)** clamps to the empty-tree sentinel so the root commit's changes are included (reviewing all `K+1` commits on the branch); **(shallow clone)** clamps to `HEAD~K` SHA — the deepest locally resolvable ancestor — so the review does not balloon to every tracked file (older history exists on the remote but isn't fetched). A stderr warning surfaces the requested-vs-clamped numbers in both cases. Audit metadata records `base_source: 'last-n-commits'`, `last_n_commits: <count actually reviewed>`, and `last_n_commits_requested: N` (only present when clamped). |
+| `review.auto_narrow_threshold` | number | `30` | Added in **0.13.0**. When the resolved diff base is more than N commits behind HEAD AND the base was resolved from the active refspec's `remoteSha` (i.e. previously-pushed remote tip of this branch — commits already Codex-reviewed) AND no explicit narrowing was set, the gate auto-scopes to the last 10 commits and emits a stderr warning. Set to `0` to disable. **Suppressed** when any of `--base`, `--last-n-commits`, `policy.review.last_n_commits`, OR the base was resolved via the upstream / origin-head / origin-main ladder (initial push, no upstream, fallback to trunk). Auto-narrow never fires on initial pushes — earlier commits on the branch may not have been reviewed yet, and skipping past them would silently bypass the gate's coverage contract. Audit metadata records `auto_narrowed: true` and `original_commit_count: N` so operators can grep for narrowed reviews. Background: large feature branches (50+ commits relative to a previously-pushed tip) routinely produced non-deterministic Codex verdicts and 30-minute timeouts; J makes the protective default automatic without compromising first-push coverage. |
+
+### Auto-narrow on large divergence (0.13.0)
+
+When pushing a long-running branch that has already been pushed before (so
+the remote tip is the previously-reviewed Codex baseline), follow-up
+pushes that pile up many commits since the last push can timeout the
+reviewer or produce inconsistent verdicts. **Auto-narrow** detects this
+case and scopes the review down to recent commits automatically:
+
+```
+$ git push origin feature/big-thing
+rea: auto-narrow — 80 commits behind <previous-remote-tip-sha> (threshold 30);
+  reviewing the last 10 commits instead.
+  Override: pass `--last-n-commits N` or `--base <ref>`, set
+  `review.last_n_commits` in .rea/policy.yaml, or disable with
+  `review.auto_narrow_threshold: 0`.
+```
+
+The probe runs `git rev-list --count base..HEAD` after base resolution.
+**Auto-narrow only fires when the base was resolved from the active
+refspec's `remoteSha`** — i.e. the previously-pushed tip of this branch,
+where the older commits have already been Codex-reviewed in a prior push.
+Initial pushes (where the resolver falls back to `origin/main` or the
+upstream ladder) are NEVER auto-narrowed: skipping past those earlier
+commits would silently bypass the advertised pre-push review for any
+hook/policy/security change made early in the branch.
+
+When eligible and the count exceeds `review.auto_narrow_threshold`
+(default 30) and no narrowing override is in effect, the gate re-resolves
+to `HEAD~10` and proceeds with the smaller diff. Every reviewed event
+includes `auto_narrowed: true` + `original_commit_count: <N>` in audit
+metadata.
+
+To opt out for one push: pass `--last-n-commits N` or `--base <ref>`. To
+opt out persistently: set `review.last_n_commits` (any value), or set
+`review.auto_narrow_threshold: 0`.
+
+### Extension-hook chaining (0.13.0)
+
+Drop executable scripts into `.husky/commit-msg.d/` or `.husky/pre-push.d/`
+and rea will run them after its own governance work, in lexical order, with
+the same positional args. Useful for layering commitlint, conventional-
+commits linters, branch-policy checks, or any other per-commit / per-push
+work without losing rea coverage.
+
+```bash
+mkdir -p .husky/pre-push.d
+cat > .husky/pre-push.d/10-commitlint <<'EOF'
+#!/bin/sh
+# Verify every new commit on the pushed range has a conventional message.
+exec npx --no-install commitlint --from "origin/main" --to "HEAD"
+EOF
+chmod +x .husky/pre-push.d/10-commitlint
+```
+
+Rules:
+
+- **Sourced AFTER rea's body** — HALT, attribution blocking, and Codex
+  review run first; fragments only fire when rea succeeds. A non-zero exit
+  from rea short-circuits before any fragment runs.
+- **Lexical order** — `10-foo` runs before `20-bar` runs before `90-baz`.
+  The standard convention is to prefix with a two-digit ordering number.
+- **Executable bit gates** — only files with `chmod +x` are run. A README
+  or `.disabled` file in the directory is silently skipped.
+- **Non-zero exit fails the hook** — the next fragment does not run, the
+  push / commit is blocked. This matches husky's normal hook chaining
+  semantics.
+- **Missing directory is a no-op** — backward compatible with consumers
+  who never opt into fragments.
+- **Fragments cannot replay pre-push stdin** — git delivers refspec data
+  on stdin which rea consumes during its own review. Fragments that need
+  refspec data should run before rea (use a custom hook in
+  `core.hooksPath` instead). Fragments that need ambient repo state can
+  call `git rev-parse` themselves.
+
+`rea doctor` lists every fragment it sees and warns when a non-executable
+file is sitting in either directory (silently skipped at hook-fire time).
 
 ### Codex CLI dependency
 
@@ -595,6 +675,8 @@ review:
   concerns_blocks: true
   timeout_ms: 1800000
   # last_n_commits: 10            # optional — narrow review to HEAD~N
+  # auto_narrow_threshold: 30     # optional — auto-narrow when commits
+                                   # behind base > N (0 disables, default 30)
 redact:
   match_timeout_ms: 100
   patterns:

package/dist/cli/doctor.js

@@ -403,6 +403,67 @@ function checkPrePushHook(state) {
             'Run `rea init` to install the fallback.',
     };
 }
+/**
+ * Detect and list extension-hook fragments under `.husky/commit-msg.d/` and
+ * `.husky/pre-push.d/`. Informational only — fragments are an opt-in feature
+ * (added in 0.13.0); their presence is something operators should know about
+ * but never a hard fail. Non-executable files in the directories are
+ * surfaced as a warning since they are silently skipped at hook-fire time
+ * (executable bit is the consumer's opt-in).
+ */
+function checkExtensionFragments(baseDir) {
+    const dirs = [
+        { name: 'commit-msg.d', path: path.join(baseDir, '.husky', 'commit-msg.d') },
+        { name: 'pre-push.d', path: path.join(baseDir, '.husky', 'pre-push.d') },
+    ];
+    const found = [];
+    const inert = [];
+    for (const d of dirs) {
+        if (!fs.existsSync(d.path))
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(d.path, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (!e.isFile())
+                continue;
+            const abs = path.join(d.path, e.name);
+            try {
+                const st = fs.statSync(abs);
+                if ((st.mode & 0o111) !== 0) {
+                    found.push(`${d.name}/${e.name}`);
+                }
+                else {
+                    inert.push(`${d.name}/${e.name}`);
+                }
+            }
+            catch {
+                // unreadable — skip, will be surfaced at hook-fire time
+            }
+        }
+    }
+    if (found.length === 0 && inert.length === 0) {
+        return {
+            label: 'extension hook fragments',
+            status: 'info',
+            detail: 'none — drop executables into .husky/{commit-msg,pre-push}.d/ to chain custom checks',
+        };
+    }
+    if (inert.length > 0) {
+        const detail = `executable: ${found.length === 0 ? 'none' : found.join(', ')}; ` +
+            `non-executable (silently skipped): ${inert.join(', ')} — chmod +x to enable`;
+        return { label: 'extension hook fragments', status: 'warn', detail };
+    }
+    return {
+        label: 'extension hook fragments',
+        status: 'info',
+        detail: `${found.length} executable fragment(s): ${found.join(', ')}`,
+    };
+}
 function checkCodexAgent(baseDir) {
     const agentPath = path.join(baseDir, '.claude', 'agents', 'codex-adversarial.md');
     if (fs.existsSync(agentPath))
@@ -601,6 +662,7 @@ export function collectChecks(baseDir, codexProbeState, prePushState) {
         if (prePushState !== undefined) {
             checks.push(checkPrePushHook(prePushState));
         }
+        checks.push(checkExtensionFragments(baseDir));
     }
     else {
         checks.push({

package/dist/cli/install/commit-msg.d.ts

@@ -17,6 +17,40 @@
  * `.rea/policy.yaml`, so it is safe to install unconditionally — see the
  * header of `.husky/commit-msg` for the opt-in check.
  */
+/**
+ * Marker baked into every rea-installed commit-msg hook. Anchored on line 2
+ * of the file (immediately after the shebang) for classification. Bump the
+ * version suffix whenever the body semantics change so upgrades can migrate
+ * old installs cleanly.
+ *
+ * v1 — 0.13.0: first version of the commit-msg marker. Pre-0.13 installs
+ *      shipped the same file content but without a marker line — those
+ *      classify as `unmarked` and are upgraded in place.
+ */
+export declare const COMMIT_MSG_MARKER = "# rea:commit-msg v1";
+/**
+ * Classify an existing `commit-msg` file. The classifier is permissive on
+ * upgrades (treat `unmarked` as legacy rea body) and conservative on
+ * foreign hooks (do not stomp).
+ */
+export type CommitMsgClassification = {
+    kind: 'absent';
+} | {
+    kind: 'rea-managed';
+    version: string;
+} | {
+    kind: 'unmarked';
+} | {
+    kind: 'foreign';
+    reason: string;
+};
+/**
+ * Inspect `hookPath` and decide whether it is rea-authored, a pre-marker
+ * legacy rea body, or a foreign user hook. The pre-0.13 commit-msg shipped
+ * with no marker line; we detect that shape via the literal "block_ai_attribution"
+ * grep — every rea body has consulted that policy field since 0.1.0.
+ */
+export declare function classifyCommitMsgHook(hookPath: string): Promise<CommitMsgClassification>;
 export interface CommitMsgInstallResult {
     gitHook?: string;
     huskyHook?: string;

package/dist/cli/install/commit-msg.js

@@ -24,6 +24,66 @@ import path from 'node:path';
 import { promisify } from 'node:util';
 import { PKG_ROOT, warn } from '../utils.js';
 const execFileAsync = promisify(execFile);
+/**
+ * Marker baked into every rea-installed commit-msg hook. Anchored on line 2
+ * of the file (immediately after the shebang) for classification. Bump the
+ * version suffix whenever the body semantics change so upgrades can migrate
+ * old installs cleanly.
+ *
+ * v1 — 0.13.0: first version of the commit-msg marker. Pre-0.13 installs
+ *      shipped the same file content but without a marker line — those
+ *      classify as `unmarked` and are upgraded in place.
+ */
+export const COMMIT_MSG_MARKER = '# rea:commit-msg v1';
+/**
+ * Inspect `hookPath` and decide whether it is rea-authored, a pre-marker
+ * legacy rea body, or a foreign user hook. The pre-0.13 commit-msg shipped
+ * with no marker line; we detect that shape via the literal "block_ai_attribution"
+ * grep — every rea body has consulted that policy field since 0.1.0.
+ */
+export async function classifyCommitMsgHook(hookPath) {
+    let stat;
+    try {
+        stat = await fsPromises.lstat(hookPath);
+    }
+    catch {
+        return { kind: 'absent' };
+    }
+    if (stat.isDirectory())
+        return { kind: 'foreign', reason: 'is-directory' };
+    if (stat.isSymbolicLink())
+        return { kind: 'foreign', reason: 'is-symlink' };
+    if (!stat.isFile())
+        return { kind: 'foreign', reason: 'not-regular-file' };
+    let content;
+    try {
+        content = await fsPromises.readFile(hookPath, 'utf8');
+    }
+    catch (e) {
+        return {
+            kind: 'foreign',
+            reason: `read-error: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+    // Anchor the marker on the second line — substring match would be tricked
+    // by a foreign hook that mentions the marker in a comment.
+    if (content.startsWith('#!/bin/sh\n')) {
+        const secondLineEnd = content.indexOf('\n', 10);
+        if (secondLineEnd > 0) {
+            const secondLine = content.slice(10, secondLineEnd);
+            if (secondLine === COMMIT_MSG_MARKER) {
+                return { kind: 'rea-managed', version: 'v1' };
+            }
+        }
+    }
+    // Pre-0.13 rea body had no marker but always contained the attribution
+    // grep. Treat that shape as upgradeable rather than foreign.
+    if (content.includes('block_ai_attribution') &&
+        content.includes('AI attribution detected')) {
+        return { kind: 'unmarked' };
+    }
+    return { kind: 'foreign', reason: 'no-marker' };
+}
 /**
  * Read `core.hooksPath` via `git config --get`. This is the only correct way
  * to consult git config: regex-matching `.git/config` (finding #9) is

package/dist/cli/install/pre-push.d.ts

@@ -53,13 +53,18 @@
  * classification. Bump the version suffix whenever the body semantics
  * change so upgrades can migrate old installs cleanly.
  *
+ * v4 — 0.13.0 extension-hook chaining: rea body sources `.husky/pre-push.d/*`
+ *      fragments after its own work and before the final `exec`, in lex
+ *      order. Non-zero fragment exit fails the hook.
  * v3 — 0.12.0 BODY_TEMPLATE rewrite: positional-args dispatch via `case`
  *      arms with `set --`, removing the `exec $REA_BIN` word-splitting bug
  *      that broke pushes from repo paths containing spaces.
  * v2 — 0.11.0 stateless push-gate body (no bash core, no audit grep).
  * v1 — 0.10.x and prior, delegated to `.claude/hooks/push-review-gate.sh`.
  */
-export declare const FALLBACK_MARKER = "# rea:pre-push-fallback v3";
+export declare const FALLBACK_MARKER = "# rea:pre-push-fallback v4";
+/** Legacy v3 marker (0.12.x bodies). Refresh-on-upgrade. */
+export declare const LEGACY_FALLBACK_MARKER_V3 = "# rea:pre-push-fallback v3";
 /** Legacy v2 marker (0.11.x bodies). Refresh-on-upgrade. */
 export declare const LEGACY_FALLBACK_MARKER_V2 = "# rea:pre-push-fallback v2";
 /** Legacy v1 marker — used by upgrade migration to detect old installs. */
@@ -68,9 +73,11 @@ export declare const LEGACY_FALLBACK_MARKER_V1 = "# rea:pre-push-fallback v1";
  * Marker present in the shipped `.husky/pre-push` governance gate. The
  * second line of the shipped husky hook is this marker — rea upgrade
  * detects it to refresh in-place. Bump the suffix whenever the body
- * changes; pre-0.12 markers live in `LEGACY_HUSKY_GATE_MARKER_V{1,2}`.
+ * changes; pre-0.13 markers live in `LEGACY_HUSKY_GATE_MARKER_V{1,2,3}`.
  */
-export declare const HUSKY_GATE_MARKER = "# rea:husky-pre-push-gate v3";
+export declare const HUSKY_GATE_MARKER = "# rea:husky-pre-push-gate v4";
+/** Legacy v3 husky marker (0.12.x bodies). Refresh-on-upgrade. */
+export declare const LEGACY_HUSKY_GATE_MARKER_V3 = "# rea:husky-pre-push-gate v3";
 /** Legacy v2 husky marker (0.11.x bodies). Refresh-on-upgrade. */
 export declare const LEGACY_HUSKY_GATE_MARKER_V2 = "# rea:husky-pre-push-gate v2";
 /** Legacy v1 husky marker for migration. */
@@ -80,7 +87,9 @@ export declare const LEGACY_HUSKY_GATE_MARKER_V1 = "# rea:husky-pre-push-gate v1
  * empty body (stubbed out by a consumer) is NOT classified as rea-managed.
  * A real rea hook always carries both markers.
  */
-export declare const HUSKY_GATE_BODY_MARKER = "# rea:gate-body-v3";
+export declare const HUSKY_GATE_BODY_MARKER = "# rea:gate-body-v4";
+/** Legacy v3 body marker (0.12.x bodies). Refresh-on-upgrade. */
+export declare const LEGACY_HUSKY_GATE_BODY_MARKER_V3 = "# rea:gate-body-v3";
 /** Legacy v2 body marker (0.11.x bodies). Refresh-on-upgrade. */
 export declare const LEGACY_HUSKY_GATE_BODY_MARKER_V2 = "# rea:gate-body-v2";
 /** Legacy body marker — used by upgrade migration detection. */
@@ -97,10 +106,11 @@ export declare function huskyHookContent(): string;
 export declare function isReaManagedFallback(content: string): boolean;
 /**
  * True when `content` is a legacy fallback hook authored by an earlier rea
- * release: v2 (0.11.x — broken `exec $REA_BIN` body) or v1 (0.10.x —
- * delegated to `.claude/hooks/push-review-gate.sh`). Used by `rea upgrade`
- * to migrate — we overwrite these unconditionally because we control the
- * entire body shape.
+ * release: v3 (0.12.x — pre-extension body), v2 (0.11.x — broken
+ * `exec $REA_BIN` body), or v1 (0.10.x — delegated to
+ * `.claude/hooks/push-review-gate.sh`). Used by `rea upgrade` to migrate
+ * — we overwrite these unconditionally because we control the entire
+ * body shape.
  */
 export declare function isLegacyReaManagedFallback(content: string): boolean;
 /**
@@ -117,8 +127,9 @@ export declare function isLegacyReaManagedFallback(content: string): boolean;
 export declare function isReaManagedHuskyGate(content: string): boolean;
 /**
  * True when `content` is a legacy Husky gate from an earlier rea release:
- * v2 (0.11.x — broken `exec $REA_BIN` body) or v1 (0.10.x — bash core
- * delegating). Used to trigger the upgrade migration.
+ * v3 (0.12.x — pre-extension body), v2 (0.11.x — broken `exec $REA_BIN`
+ * body), or v1 (0.10.x — bash core delegating). Used to trigger the
+ * upgrade migration.
  */
 export declare function isLegacyReaManagedHuskyGate(content: string): boolean;
 /**

package/dist/cli/install/pre-push.js

@@ -65,13 +65,18 @@ const execFileAsync = promisify(execFile);
  * classification. Bump the version suffix whenever the body semantics
  * change so upgrades can migrate old installs cleanly.
  *
+ * v4 — 0.13.0 extension-hook chaining: rea body sources `.husky/pre-push.d/*`
+ *      fragments after its own work and before the final `exec`, in lex
+ *      order. Non-zero fragment exit fails the hook.
  * v3 — 0.12.0 BODY_TEMPLATE rewrite: positional-args dispatch via `case`
  *      arms with `set --`, removing the `exec $REA_BIN` word-splitting bug
  *      that broke pushes from repo paths containing spaces.
  * v2 — 0.11.0 stateless push-gate body (no bash core, no audit grep).
  * v1 — 0.10.x and prior, delegated to `.claude/hooks/push-review-gate.sh`.
  */
-export const FALLBACK_MARKER = '# rea:pre-push-fallback v3';
+export const FALLBACK_MARKER = '# rea:pre-push-fallback v4';
+/** Legacy v3 marker (0.12.x bodies). Refresh-on-upgrade. */
+export const LEGACY_FALLBACK_MARKER_V3 = '# rea:pre-push-fallback v3';
 /** Legacy v2 marker (0.11.x bodies). Refresh-on-upgrade. */
 export const LEGACY_FALLBACK_MARKER_V2 = '# rea:pre-push-fallback v2';
 /** Legacy v1 marker — used by upgrade migration to detect old installs. */
@@ -80,9 +85,11 @@ export const LEGACY_FALLBACK_MARKER_V1 = '# rea:pre-push-fallback v1';
  * Marker present in the shipped `.husky/pre-push` governance gate. The
  * second line of the shipped husky hook is this marker — rea upgrade
  * detects it to refresh in-place. Bump the suffix whenever the body
- * changes; pre-0.12 markers live in `LEGACY_HUSKY_GATE_MARKER_V{1,2}`.
+ * changes; pre-0.13 markers live in `LEGACY_HUSKY_GATE_MARKER_V{1,2,3}`.
  */
-export const HUSKY_GATE_MARKER = '# rea:husky-pre-push-gate v3';
+export const HUSKY_GATE_MARKER = '# rea:husky-pre-push-gate v4';
+/** Legacy v3 husky marker (0.12.x bodies). Refresh-on-upgrade. */
+export const LEGACY_HUSKY_GATE_MARKER_V3 = '# rea:husky-pre-push-gate v3';
 /** Legacy v2 husky marker (0.11.x bodies). Refresh-on-upgrade. */
 export const LEGACY_HUSKY_GATE_MARKER_V2 = '# rea:husky-pre-push-gate v2';
 /** Legacy v1 husky marker for migration. */
@@ -92,7 +99,9 @@ export const LEGACY_HUSKY_GATE_MARKER_V1 = '# rea:husky-pre-push-gate v1';
  * empty body (stubbed out by a consumer) is NOT classified as rea-managed.
  * A real rea hook always carries both markers.
  */
-export const HUSKY_GATE_BODY_MARKER = '# rea:gate-body-v3';
+export const HUSKY_GATE_BODY_MARKER = '# rea:gate-body-v4';
+/** Legacy v3 body marker (0.12.x bodies). Refresh-on-upgrade. */
+export const LEGACY_HUSKY_GATE_BODY_MARKER_V3 = '# rea:gate-body-v3';
 /** Legacy v2 body marker (0.11.x bodies). Refresh-on-upgrade. */
 export const LEGACY_HUSKY_GATE_BODY_MARKER_V2 = '# rea:gate-body-v2';
 /** Legacy body marker — used by upgrade migration detection. */
@@ -165,7 +174,51 @@ else
   exit 2
 fi
 
-exec "\$@"
+# Run the rea push-gate FIRST. We capture its exit and explicitly propagate
+# instead of \`exec\`-ing — extension fragments must only run after rea's own
+# governance work succeeds. The fragments are user code; surfacing them
+# AFTER rea's body (HALT check, Codex review, audit write) preserves the
+# governance contract while letting consumers chain their own checks (e.g.
+# commitlint, branch-policy linters) without losing rea coverage.
+"\$@"
+rea_status=\$?
+if [ "\$rea_status" -ne 0 ]; then
+  exit "\$rea_status"
+fi
+
+# Extension-hook chaining: source every executable file under
+# \`.husky/pre-push.d/\` in lexical order. Missing directory = no-op
+# (backward compatible). Each fragment receives the original positional
+# args from git's \`<remote-name> <remote-url>\` invocation. Non-zero exit
+# from any fragment fails the push; this matches husky's normal hook
+# chaining semantics.
+#
+# The git pre-push contract delivers refspecs on stdin. Once rea's body has
+# consumed it (\`exec rea hook push-gate "\$@"\` reads stdin during \`runPushGate\`),
+# subsequent fragments cannot replay it — that's by design: agents that need
+# refspec data should run before rea, not after. Fragments that need ambient
+# repo state can call \`git rev-parse\` themselves.
+ext_dir="\${REA_ROOT}/.husky/pre-push.d"
+if [ -d "\$ext_dir" ]; then
+  # Collect fragments deterministically. POSIX sort orders the same way on
+  # macOS (BSD sort) and Linux (GNU sort) for ASCII filenames; consumers who
+  # name their fragments \`10-foo\` / \`20-bar\` get predictable ordering.
+  for frag in "\$ext_dir"/*; do
+    # Glob expands to itself when no matches — guard with -e.
+    [ -e "\$frag" ] || continue
+    # Skip non-files (directories, sockets) and non-executables. The
+    # executable bit is the consumer's opt-in: dropping a non-executable
+    # README into the dir does not become a hook.
+    [ -f "\$frag" ] || continue
+    [ -x "\$frag" ] || continue
+    # Each fragment runs in its own subprocess with the original git args.
+    # Failures propagate via \`set -eu\` above (loop body inherits, so any
+    # non-zero exit blocks the push immediately).
+    "\$frag" "\$@"
+  done
+fi
+
+exit 0
 `;
 /** Fallback hook body — `.git/hooks/pre-push` in vanilla-git installs. */
 export function fallbackHookContent() {
@@ -217,10 +270,11 @@ export function isReaManagedFallback(content) {
 }
 /**
  * True when `content` is a legacy fallback hook authored by an earlier rea
- * release: v2 (0.11.x — broken `exec $REA_BIN` body) or v1 (0.10.x —
- * delegated to `.claude/hooks/push-review-gate.sh`). Used by `rea upgrade`
- * to migrate — we overwrite these unconditionally because we control the
- * entire body shape.
+ * release: v3 (0.12.x — pre-extension body), v2 (0.11.x — broken
+ * `exec $REA_BIN` body), or v1 (0.10.x — delegated to
+ * `.claude/hooks/push-review-gate.sh`). Used by `rea upgrade` to migrate
+ * — we overwrite these unconditionally because we control the entire
+ * body shape.
  */
 export function isLegacyReaManagedFallback(content) {
     if (!content.startsWith('#!/bin/sh\n'))
@@ -229,7 +283,8 @@ export function isLegacyReaManagedFallback(content) {
     if (secondLineEnd < 0)
         return false;
     const secondLine = content.slice(10, secondLineEnd);
-    return (secondLine === LEGACY_FALLBACK_MARKER_V2 ||
+    return (secondLine === LEGACY_FALLBACK_MARKER_V3 ||
+        secondLine === LEGACY_FALLBACK_MARKER_V2 ||
         secondLine === LEGACY_FALLBACK_MARKER_V1);
 }
 /**
@@ -248,11 +303,13 @@ export function isReaManagedHuskyGate(content) {
 }
 /**
  * True when `content` is a legacy Husky gate from an earlier rea release:
- * v2 (0.11.x — broken `exec $REA_BIN` body) or v1 (0.10.x — bash core
- * delegating). Used to trigger the upgrade migration.
+ * v3 (0.12.x — pre-extension body), v2 (0.11.x — broken `exec $REA_BIN`
+ * body), or v1 (0.10.x — bash core delegating). Used to trigger the
+ * upgrade migration.
  */
 export function isLegacyReaManagedHuskyGate(content) {
-    return (hasHeaderMarkers(content, LEGACY_HUSKY_GATE_MARKER_V2, LEGACY_HUSKY_GATE_BODY_MARKER_V2) ||
+    return (hasHeaderMarkers(content, LEGACY_HUSKY_GATE_MARKER_V3, LEGACY_HUSKY_GATE_BODY_MARKER_V3) ||
+        hasHeaderMarkers(content, LEGACY_HUSKY_GATE_MARKER_V2, LEGACY_HUSKY_GATE_BODY_MARKER_V2) ||
         hasHeaderMarkers(content, LEGACY_HUSKY_GATE_MARKER_V1, LEGACY_HUSKY_GATE_BODY_MARKER_V1));
 }
 function hasHeaderMarkers(content, header, body) {
@@ -541,6 +598,8 @@ async function cleanupStaleTempFiles(dst) {
             return;
         if (!body.includes(FALLBACK_MARKER) &&
             !body.includes(HUSKY_GATE_MARKER) &&
+            !body.includes(LEGACY_FALLBACK_MARKER_V3) &&
+            !body.includes(LEGACY_HUSKY_GATE_MARKER_V3) &&
             !body.includes(LEGACY_FALLBACK_MARKER_V2) &&
             !body.includes(LEGACY_HUSKY_GATE_MARKER_V2) &&
             !body.includes(LEGACY_FALLBACK_MARKER_V1) &&

package/dist/hooks/push-gate/codex-runner.d.ts

@@ -51,6 +51,14 @@ export interface GitExecutor {
     headSha(): string;
     /** `git diff --name-only <base> <head>`. Returns path list (possibly empty). */
     diffNames(base: string, head: string): string[];
+    /**
+     * `git rev-list --count <base>..<head>`. Returns the integer commit count
+     * or `null` when the range cannot be resolved (unreachable base, shallow
+     * clone, etc.) — null lets the caller treat divergence-counting as
+     * best-effort without breaking the gate. Used by the auto-narrow probe
+     * (J / 0.13.0).
+     */
+    revListCount(base: string, head: string): number | null;
 }
 /**
  * Real git implementation using `spawnSync`. Each call is independent (no

package/dist/hooks/push-gate/codex-runner.js

@@ -95,6 +95,19 @@ export function createRealGitExecutor(cwd) {
                 return [];
             return r.stdout.split(/\r?\n/).filter((l) => l.length > 0);
         },
+        revListCount(base, head) {
+            // `git rev-list --count base..head` — number of commits reachable
+            // from head but not base. Returns null on any failure so the caller
+            // can treat divergence-counting as best-effort (auto-narrow probe).
+            const r = run(['rev-list', '--count', `${base}..${head}`]);
+            if (r.code !== 0)
+                return null;
+            const trimmed = r.stdout.trim();
+            if (trimmed.length === 0)
+                return null;
+            const n = Number(trimmed);
+            return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
+        },
     };
 }
 /**

package/dist/hooks/push-gate/index.js

@@ -24,7 +24,7 @@
 import path from 'node:path';
 import { appendAuditRecord } from '../../audit/append.js';
 import { Tier, InvocationStatus } from '../../policy/types.js';
-import { resolvePushGatePolicy, } from './policy.js';
+import { resolvePushGatePolicy, PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK, } from './policy.js';
 import { readHalt } from './halt.js';
 import { resolveBaseRef } from './base.js';
 import { createRealGitExecutor, runCodexReview, CodexNotInstalledError, CodexProtocolError, CodexSubprocessError, CodexTimeoutError, } from './codex-runner.js';
@@ -189,6 +189,13 @@ export async function runPushGate(deps) {
     const activeRefspec = (deps.refspecs ?? []).find((r) => r.localSha !== NULL_SHA && r.localSha.length > 0);
     let base;
     let headSha;
+    // Tracks whether the base was resolved from the active refspec's
+    // remoteSha — i.e. "the tip of this branch as the remote currently sees
+    // it". Only that case represents commits Codex has already reviewed in
+    // a prior push; auto-narrow is only safe there (J / 0.13.0). Initial
+    // pushes against `origin/main`-shaped bases must NOT auto-narrow,
+    // because earlier commits on the branch may never have been reviewed.
+    let baseFromPushedRemoteTip = false;
     if (explicitBaseSet) {
         // (a) explicit base wins absolutely.
         base = resolveBaseRef(git, { explicit: deps.explicitBase });
@@ -229,6 +236,9 @@ export async function runPushGate(deps) {
         }
         else {
             base = { ref: activeRefspec.remoteSha, source: 'explicit' };
+            // ONLY this path produces a base that represents the previously-
+            // reviewed remote tip of THIS branch. Auto-narrow is safe here.
+            baseFromPushedRemoteTip = true;
         }
     }
     else {
@@ -241,6 +251,67 @@ export async function runPushGate(deps) {
         await safeAppend(appendAuditFn, deps.baseDir, EVT_ERROR, { kind: 'head-sha-missing' });
         return { status: 'error', exitCode: 2, summary: 'head-sha-missing' };
     }
+    // 4b. Auto-narrow probe (J / 0.13.0). When the resolved base is far
+    //     behind HEAD AND the operator has not already pinned an explicit
+    //     window, scope the review down to the recent commits and warn.
+    //
+    //     CRITICAL safety rule: auto-narrow ONLY fires when the base was
+    //     resolved from the active refspec's remoteSha — i.e. "the tip of
+    //     this branch as the remote currently sees it". Only that case
+    //     represents commits Codex already reviewed in a prior push, so
+    //     skipping older commits on the branch is safe.
+    //
+    //     For initial pushes (or any base resolved via the upstream /
+    //     origin-head / origin-main ladder), the diff target is a trunk-
+    //     like ref where commits earlier in the branch may never have been
+    //     reviewed. Auto-narrowing past them would silently bypass the
+    //     advertised pre-push review for a hook/policy/security change
+    //     made early in the branch (codex-review 0.13.0 [P1]).
+    //
+    //     Suppression rules (any one prevents auto-narrow from firing):
+    //
+    //       - `--base` flag set (operator picked an explicit ref)
+    //       - `--last-n-commits` flag set (operator picked an explicit
+    //         window)
+    //       - `policy.review.last_n_commits` set (persistent narrow window)
+    //       - `policy.review.auto_narrow_threshold: 0` (disabled)
+    //       - resolver already produced a `last-n-commits` source (we got
+    //         here via the policyLastN branch above)
+    //       - resolver fell back to `empty-tree` (single-commit branch /
+    //         orphan; no usable upstream — narrowing would be silly)
+    //       - base was NOT derived from the active refspec's remoteSha
+    //         (initial push, no upstream, fallback to origin/main, etc.)
+    //
+    //     The probe uses `git rev-list --count base..HEAD` rather than
+    //     `diffNames().length` — line-counting commits is far cheaper than
+    //     listing every changed path on a 50+ commit branch. A null result
+    //     (range unresolvable) suppresses auto-narrow entirely; we'd
+    //     rather err on the side of reviewing more than tripping a
+    //     half-baked auto-narrow on a degenerate ref.
+    let autoNarrowed = false;
+    let originalCommitCount = null;
+    const autoNarrowEligible = !explicitBaseSet &&
+        lastNFromFlag === undefined &&
+        policyLastN === undefined &&
+        policy.auto_narrow_threshold > 0 &&
+        base.source !== 'last-n-commits' &&
+        base.source !== 'empty-tree' &&
+        baseFromPushedRemoteTip;
+    if (autoNarrowEligible) {
+        originalCommitCount = git.revListCount(base.ref, headSha);
+        if (originalCommitCount !== null &&
+            originalCommitCount > policy.auto_narrow_threshold) {
+            const fallbackWindow = PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK;
+            const narrowed = resolveBaseRef(git, {
+                lastNCommits: fallbackWindow,
+                headRef: headSha,
+            });
+            stderr(`rea: auto-narrow — ${originalCommitCount} commits behind ${base.ref} (threshold ${policy.auto_narrow_threshold}); reviewing the last ${fallbackWindow} commits instead.\n` +
+                `  Override: pass \`--last-n-commits N\` or \`--base <ref>\`, set \`review.last_n_commits\` in .rea/policy.yaml, or disable with \`review.auto_narrow_threshold: 0\`.\n`);
+            base = narrowed;
+            autoNarrowed = true;
+        }
+    }
     // 5. Empty-diff short-circuit. An initial push against the empty-tree
     //    sentinel ALWAYS has a non-empty diff (HEAD vs empty tree); this
     //    short-circuit only fires when the feature branch really is a
@@ -253,6 +324,8 @@ export async function runPushGate(deps) {
             head_sha: headSha,
             last_n_commits: base.lastNCommits,
             last_n_commits_requested: base.lastNCommitsRequested,
+            auto_narrowed: autoNarrowed ? true : undefined,
+            original_commit_count: originalCommitCount !== null ? originalCommitCount : undefined,
         });
         return {
             status: 'empty-diff',
@@ -303,6 +376,8 @@ export async function runPushGate(deps) {
             concerns_override: summary.verdict === 'concerns' && isConcernsOverrideSet(env) ? true : undefined,
             last_n_commits: base.lastNCommits,
             last_n_commits_requested: base.lastNCommitsRequested,
+            auto_narrowed: autoNarrowed ? true : undefined,
+            original_commit_count: originalCommitCount !== null ? originalCommitCount : undefined,
         });
         if (blocked) {
             return {

package/dist/hooks/push-gate/policy.d.ts

@@ -36,12 +36,33 @@ export interface ResolvedReviewPolicy {
      * `undefined` when unset (default-untouched behavior).
      */
     last_n_commits: number | undefined;
+    /**
+     * Auto-narrow threshold (J / 0.13.0). When the resolved diff base is more
+     * than N commits behind HEAD AND no explicit narrowing was pinned, the
+     * gate scopes to `PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK` (10) and
+     * emits a stderr warning. Defaults to 30 when unset; 0 disables.
+     */
+    auto_narrow_threshold: number;
     /** `true` when `.rea/policy.yaml` was absent; defaults apply. */
     policyMissing: boolean;
 }
 export declare const PUSH_GATE_DEFAULT_TIMEOUT_MS = 1800000;
 export declare const PUSH_GATE_DEFAULT_CODEX_REQUIRED = true;
 export declare const PUSH_GATE_DEFAULT_CONCERNS_BLOCKS = true;
+/**
+ * Default auto-narrow threshold (J / 0.13.0). When the divergence between
+ * the resolved base and HEAD exceeds this count and the operator has not
+ * pinned an explicit window, the gate auto-narrows to
+ * `PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK` commits.
+ */
+export declare const PUSH_GATE_DEFAULT_AUTO_NARROW_THRESHOLD = 30;
+/**
+ * Window the gate auto-narrows to when the threshold trips and the operator
+ * has not pinned `policy.review.last_n_commits`. Conservative — small
+ * enough that Codex review stays fast, large enough to capture meaningful
+ * recent work.
+ */
+export declare const PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK = 10;
 /**
  * Resolve the push-gate policy for `baseDir`. Never throws — a malformed
  * policy file surfaces as a typed error via the underlying zod validator,

package/dist/hooks/push-gate/policy.js

@@ -31,6 +31,20 @@ import { loadPolicyAsync } from '../../policy/loader.js';
 export const PUSH_GATE_DEFAULT_TIMEOUT_MS = 1_800_000;
 export const PUSH_GATE_DEFAULT_CODEX_REQUIRED = true;
 export const PUSH_GATE_DEFAULT_CONCERNS_BLOCKS = true;
+/**
+ * Default auto-narrow threshold (J / 0.13.0). When the divergence between
+ * the resolved base and HEAD exceeds this count and the operator has not
+ * pinned an explicit window, the gate auto-narrows to
+ * `PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK` commits.
+ */
+export const PUSH_GATE_DEFAULT_AUTO_NARROW_THRESHOLD = 30;
+/**
+ * Window the gate auto-narrows to when the threshold trips and the operator
+ * has not pinned `policy.review.last_n_commits`. Conservative — small
+ * enough that Codex review stays fast, large enough to capture meaningful
+ * recent work.
+ */
+export const PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK = 10;
 /**
  * Resolve the push-gate policy for `baseDir`. Never throws — a malformed
  * policy file surfaces as a typed error via the underlying zod validator,
@@ -49,6 +63,7 @@ export async function resolvePushGatePolicy(baseDir) {
             concerns_blocks: PUSH_GATE_DEFAULT_CONCERNS_BLOCKS,
             timeout_ms: PUSH_GATE_DEFAULT_TIMEOUT_MS,
             last_n_commits: undefined,
+            auto_narrow_threshold: PUSH_GATE_DEFAULT_AUTO_NARROW_THRESHOLD,
             policyMissing: true,
         };
     }
@@ -59,6 +74,7 @@ export async function resolvePushGatePolicy(baseDir) {
         concerns_blocks: review.concerns_blocks ?? PUSH_GATE_DEFAULT_CONCERNS_BLOCKS,
         timeout_ms: review.timeout_ms ?? PUSH_GATE_DEFAULT_TIMEOUT_MS,
         last_n_commits: review.last_n_commits,
+        auto_narrow_threshold: review.auto_narrow_threshold ?? PUSH_GATE_DEFAULT_AUTO_NARROW_THRESHOLD,
         policyMissing: false,
     };
 }

package/dist/policy/loader.d.ts

@@ -35,16 +35,28 @@ declare const PolicySchema: z.ZodObject<{
         concerns_blocks: z.ZodOptional<z.ZodBoolean>;
         timeout_ms: z.ZodOptional<z.ZodNumber>;
         last_n_commits: z.ZodOptional<z.ZodNumber>;
+        /**
+         * Auto-narrow threshold (J / 0.13.0). When the resolved diff base is more
+         * than N commits away from HEAD, the gate auto-scopes to
+         * `last_n_commits` (or the 0.13 fallback default of 10) and emits a
+         * stderr warning. Default 30 when unset; explicit 0 disables auto-narrow
+         * entirely. Suppressed when the operator pinned `--last-n-commits`,
+         * `--base`, or `policy.review.last_n_commits` (those are explicit
+         * intent and auto-narrow stays out of the way).
+         */
+        auto_narrow_threshold: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         codex_required?: boolean | undefined;
         concerns_blocks?: boolean | undefined;
         timeout_ms?: number | undefined;
         last_n_commits?: number | undefined;
+        auto_narrow_threshold?: number | undefined;
     }, {
         codex_required?: boolean | undefined;
         concerns_blocks?: boolean | undefined;
         timeout_ms?: number | undefined;
         last_n_commits?: number | undefined;
+        auto_narrow_threshold?: number | undefined;
     }>>;
     redact: z.ZodOptional<z.ZodObject<{
         match_timeout_ms: z.ZodOptional<z.ZodNumber>;
@@ -139,6 +151,7 @@ declare const PolicySchema: z.ZodObject<{
         concerns_blocks?: boolean | undefined;
         timeout_ms?: number | undefined;
         last_n_commits?: number | undefined;
+        auto_narrow_threshold?: number | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;
@@ -183,6 +196,7 @@ declare const PolicySchema: z.ZodObject<{
         concerns_blocks?: boolean | undefined;
         timeout_ms?: number | undefined;
         last_n_commits?: number | undefined;
+        auto_narrow_threshold?: number | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;

package/dist/policy/loader.js

@@ -28,6 +28,16 @@ const ReviewPolicySchema = z
     concerns_blocks: z.boolean().optional(),
     timeout_ms: z.number().int().positive().optional(),
     last_n_commits: z.number().int().positive().optional(),
+    /**
+     * Auto-narrow threshold (J / 0.13.0). When the resolved diff base is more
+     * than N commits away from HEAD, the gate auto-scopes to
+     * `last_n_commits` (or the 0.13 fallback default of 10) and emits a
+     * stderr warning. Default 30 when unset; explicit 0 disables auto-narrow
+     * entirely. Suppressed when the operator pinned `--last-n-commits`,
+     * `--base`, or `policy.review.last_n_commits` (those are explicit
+     * intent and auto-narrow stays out of the way).
+     */
+    auto_narrow_threshold: z.number().int().nonnegative().optional(),
 })
     .strict();
 /**

package/dist/policy/types.d.ts

@@ -102,6 +102,34 @@ export interface ReviewPolicy {
      * Positive integer. The loader rejects zero/negative values.
      */
     last_n_commits?: number;
+    /**
+     * Auto-narrow threshold (J / 0.13.0). When the resolved diff base is more
+     * than N commits behind HEAD, the gate automatically scopes the review to
+     * the last 10 commits (or `last_n_commits` if pinned) and emits a stderr
+     * warning explaining the auto-narrow + how to override.
+     *
+     * Default `30` when unset. Explicit `0` disables auto-narrow entirely.
+     *
+     * Auto-narrow is SUPPRESSED when the operator already expressed explicit
+     * intent — any of these prevents auto-narrow from firing:
+     *
+     *   - `--last-n-commits N` flag (the operator picked an exact window)
+     *   - `--base <ref>` flag (the operator picked an exact base)
+     *   - `policy.review.last_n_commits` (persistent narrow-window config)
+     *
+     * Audit metadata records `auto_narrowed: true|false` and
+     * `original_commit_count: N` on every reviewed event so operators can
+     * grep their audit log for narrowed reviews.
+     *
+     * Background: large feature branches (50+ commits relative to origin/main)
+     * routinely produced non-deterministic Codex verdicts, 10-minute timeouts,
+     * and the "thrashing" reported in helixir migration 2026-04-26. The 0.12.0
+     * `last_n_commits` knob fixed it for operators who knew to set it; J makes
+     * the protective default automatic.
+     *
+     * Non-negative integer. The loader rejects negative values.
+     */
+    auto_narrow_threshold?: number;
 }
 /**
  * User-supplied redaction pattern entry. Each pattern has a stable `name` used

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review for AI-assisted projects",
   "license": "MIT",
   "author": "Booked Solid Technology <oss@bookedsolid.tech> (https://bookedsolid.tech)",