@bookedsolid/rea 0.11.0 → 0.13.0

package/dist/cli/doctor.d.ts

@@ -46,6 +46,18 @@ export declare function checkFingerprintStore(baseDir: string): Promise<CheckRes
  * NOT a trust boundary. Do not key security decisions on the return value.
  */
 export declare function isGitRepo(baseDir: string): boolean;
+/**
+ * Hard-fail when `policy.review.codex_required: true` but the `codex`
+ * binary is not on PATH. Pre-0.12.0 this prereq surfaced only at first
+ * push, by which point the consumer had cloned, run `pnpm install`,
+ * authored a commit, and tried to push — only then to learn that they
+ * needed a separate install. Fix C of 0.12.0 surfaces it during install.
+ *
+ * Returns `pass` when codex resolves; `fail` when missing. Operators who
+ * want to disable the gate can flip `policy.review.codex_required: false`
+ * (the doctor then short-circuits past every Codex check).
+ */
+export declare function checkCodexBinaryOnPath(): CheckResult;
 /**
  * Translate a `CodexProbeState` into two doctor CheckResults: one for
  * responsiveness (pass/warn) and one informational line about the last

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))
@@ -423,6 +484,95 @@ function checkCodexCommand(baseDir) {
         detail: `missing: ${cmdPath}`,
     };
 }
+/**
+ * Resolve the absolute path of `codex` on PATH (cross-platform). Returns
+ * `null` when codex is not installed. We walk `process.env.PATH`
+ * directly rather than shelling out — earlier iterations spawned
+ * `sh -c "command -v codex"` which gave false negatives in sanitized
+ * POSIX environments where `/bin` is omitted from PATH (CI runners,
+ * hardened dev shells) but the `codex` binary lives at a project-bin
+ * path that IS on PATH. Codex [P2] 2026-04-29.
+ *
+ * On Windows we iterate `PATHEXT` (default `.COM;.EXE;.BAT;.CMD`) so
+ * `codex.cmd` (the typical npm shim) is discovered. POSIX checks the
+ * bare name and accepts any file with an execute bit set.
+ */
+function resolveCodexBinary() {
+    const isWindows = process.platform === 'win32';
+    const pathEnv = process.env.PATH ?? process.env.Path ?? '';
+    if (pathEnv.length === 0)
+        return null;
+    const sep = isWindows ? ';' : ':';
+    const entries = pathEnv.split(sep).filter((p) => p.length > 0);
+    if (isWindows) {
+        const pathExt = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';');
+        for (const dir of entries) {
+            for (const ext of pathExt) {
+                const candidate = path.join(dir, `codex${ext}`);
+                try {
+                    const st = fs.statSync(candidate);
+                    if (st.isFile())
+                        return candidate;
+                }
+                catch {
+                    // not present in this PATH entry — keep walking
+                }
+            }
+            // also check the bare name in case PATHEXT is unusual
+            const bare = path.join(dir, 'codex');
+            try {
+                const st = fs.statSync(bare);
+                if (st.isFile())
+                    return bare;
+            }
+            catch {
+                // not present — keep walking
+            }
+        }
+        return null;
+    }
+    // POSIX: check executable bit on the file mode.
+    for (const dir of entries) {
+        const candidate = path.join(dir, 'codex');
+        try {
+            const st = fs.statSync(candidate);
+            if (st.isFile() && (st.mode & 0o111) !== 0)
+                return candidate;
+        }
+        catch {
+            // not present in this PATH entry — keep walking
+        }
+    }
+    return null;
+}
+/**
+ * Hard-fail when `policy.review.codex_required: true` but the `codex`
+ * binary is not on PATH. Pre-0.12.0 this prereq surfaced only at first
+ * push, by which point the consumer had cloned, run `pnpm install`,
+ * authored a commit, and tried to push — only then to learn that they
+ * needed a separate install. Fix C of 0.12.0 surfaces it during install.
+ *
+ * Returns `pass` when codex resolves; `fail` when missing. Operators who
+ * want to disable the gate can flip `policy.review.codex_required: false`
+ * (the doctor then short-circuits past every Codex check).
+ */
+export function checkCodexBinaryOnPath() {
+    const resolved = resolveCodexBinary();
+    if (resolved !== null) {
+        return {
+            label: 'codex CLI on PATH',
+            status: 'pass',
+            detail: resolved,
+        };
+    }
+    return {
+        label: 'codex CLI on PATH',
+        status: 'fail',
+        detail: 'codex not found on PATH. policy.review.codex_required: true requires the codex binary. ' +
+            'Install: https://github.com/openai/codex (e.g. `npm i -g @openai/codex`). ' +
+            'To disable the push-gate instead, set policy.review.codex_required: false in .rea/policy.yaml.',
+    };
+}
 /**
  * Translate a `CodexProbeState` into two doctor CheckResults: one for
  * responsiveness (pass/warn) and one informational line about the last
@@ -512,6 +662,7 @@ export function collectChecks(baseDir, codexProbeState, prePushState) {
         if (prePushState !== undefined) {
             checks.push(checkPrePushHook(prePushState));
         }
+        checks.push(checkExtensionFragments(baseDir));
     }
     else {
         checks.push({
@@ -521,7 +672,7 @@ export function collectChecks(baseDir, codexProbeState, prePushState) {
         });
     }
     if (codexRequiredFromPolicy(baseDir)) {
-        checks.push(checkCodexAgent(baseDir), checkCodexCommand(baseDir));
+        checks.push(checkCodexAgent(baseDir), checkCodexCommand(baseDir), checkCodexBinaryOnPath());
         if (codexProbeState !== undefined) {
             checks.push(...checksFromProbeState(codexProbeState));
         }

package/dist/cli/hook.d.ts

@@ -31,6 +31,13 @@
 import type { Command } from 'commander';
 export interface HookPushGateOptions {
     base?: string;
+    /**
+     * Diff against `HEAD~N` instead of running the upstream ladder. Mirrors
+     * `policy.review.last_n_commits`; the CLI flag wins when both are set.
+     * `--base` always wins over both. Validated as a positive integer; the
+     * CLI rejects non-numeric input before reaching `runPushGate`.
+     */
+    lastNCommits?: number;
 }
 /**
  * Public runner, exposed so integration tests and the commander binding can

package/dist/cli/hook.js

@@ -55,6 +55,7 @@ export async function runHookPushGate(options) {
             stderr,
             refspecs,
             ...(options.base !== undefined && options.base.length > 0 ? { explicitBase: options.base } : {}),
+            ...(options.lastNCommits !== undefined ? { lastNCommits: options.lastNCommits } : {}),
         });
         process.exit(result.exitCode);
     }
@@ -121,7 +122,17 @@ export function registerHookCommand(program) {
         .argument('[gitArgs...]', 'positional args forwarded by git (remote name, URL); ignored')
         .description('Run `codex exec review` against the current diff and block on blocking findings. Exits 0/1/2: pass/HALT/blocked. No cache — every push runs Codex afresh.')
         .option('--base <ref>', 'explicit base ref to diff against (e.g. origin/main). Defaults to @{upstream} → origin/HEAD → main/master → empty-tree.')
+        .option('--last-n-commits <n>', 'narrow review to the last N commits (diff against HEAD~N). Useful for large feature branches. Loses to --base when both are set; mirrors policy.review.last_n_commits.', (raw) => {
+        const n = Number(raw);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new Error(`--last-n-commits must be a positive integer, got ${JSON.stringify(raw)}`);
+        }
+        return n;
+    })
         .action(async (_gitArgs, opts) => {
-        await runHookPushGate({ ...(opts.base !== undefined ? { base: opts.base } : {}) });
+        await runHookPushGate({
+            ...(opts.base !== undefined ? { base: opts.base } : {}),
+            ...(opts.lastNCommits !== undefined ? { lastNCommits: opts.lastNCommits } : {}),
+        });
     });
 }

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,19 +53,33 @@
  * 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 v2";
+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. */
 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.11 markers live in `LEGACY_HUSKY_GATE_MARKER_V1`.
+ * 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 v2";
+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. */
 export declare const LEGACY_HUSKY_GATE_MARKER_V1 = "# rea:husky-pre-push-gate v1";
 /**
@@ -73,7 +87,11 @@ 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-v2";
+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. */
 export declare const LEGACY_HUSKY_GATE_BODY_MARKER_V1 = "# rea:gate-body-v1";
 /** Fallback hook body — `.git/hooks/pre-push` in vanilla-git installs. */
@@ -87,10 +105,12 @@ export declare function huskyHookContent(): string;
  */
 export declare function isReaManagedFallback(content: string): boolean;
 /**
- * True when `content` is the legacy v1 fallback (`.git/hooks/pre-push`
- * that 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.
+ * True when `content` is a legacy fallback hook authored by an earlier rea
+ * 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;
 /**
@@ -106,8 +126,10 @@ export declare function isLegacyReaManagedFallback(content: string): boolean;
  */
 export declare function isReaManagedHuskyGate(content: string): boolean;
 /**
- * True when `content` is the legacy v1 Husky gate (`.husky/pre-push` from
- * 0.10.x and earlier). Used to trigger the upgrade migration.
+ * True when `content` is a legacy Husky gate from an earlier rea release:
+ * 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,19 +65,33 @@ 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 v2';
+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. */
 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.11 markers live in `LEGACY_HUSKY_GATE_MARKER_V1`.
+ * 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 v2';
+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. */
 export const LEGACY_HUSKY_GATE_MARKER_V1 = '# rea:husky-pre-push-gate v1';
 /**
@@ -85,7 +99,11 @@ 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-v2';
+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. */
 export const LEGACY_HUSKY_GATE_BODY_MARKER_V1 = '# rea:gate-body-v1';
 // ---------------------------------------------------------------------------
@@ -107,7 +125,8 @@ const BODY_TEMPLATE = `set -eu
 # invocation, verdict inference, audit write — lives in
 # \`src/hooks/push-gate/\` and is invoked via \`rea hook push-gate\`.
 # This stub only short-circuits on the kill-switch and resolves the rea
-# binary (in priority: project node_modules/.bin/rea → PATH → npx).
+# binary (in priority: project node_modules/.bin/rea → dogfood dist →
+# PATH → npx).
 #
 # The 0.10.x hooks assumed rea was on PATH. Consumers who bootstrap via
 # \`npx @bookedsolid/rea init\` have no persistent global rea install, so
@@ -123,35 +142,83 @@ if [ -f "\${REA_ROOT}/.rea/HALT" ]; then
   exit 1
 fi
 
-# The pre-push stdin carries one line per refspec (local_ref local_sha
-# remote_ref remote_sha). Forward stdin verbatim via process substitution
-# — the \`rea hook push-gate\` CLI reads it via process.stdin to pick up
-# the actual push base. Empty stdin (direct invocation, CI, etc.) is
-# handled by the CLI falling back to upstream → origin/HEAD resolution.
+# Dispatch the rea CLI as a positional-args list rather than a string
+# (the 0.11.x \`exec \$REA_BIN ...\` pattern broke when REA_ROOT contained
+# whitespace because the unquoted \$REA_BIN expansion underwent word
+# splitting; \`/Users/jane/My Projects/repo\` produced four argv tokens
+# instead of two). The \`set --\` form below preserves spaces verbatim.
+#
+# The pre-push stdin carries one line per refspec; \`exec\` inherits stdin
+# unchanged. \$@ on entry carries git's <remote-name> <remote-url>; we
+# preserve those by appending "\$@" inside each \`set --\` arm.
 
-REA_BIN=""
 if [ -x "\${REA_ROOT}/node_modules/.bin/rea" ]; then
-  REA_BIN="\${REA_ROOT}/node_modules/.bin/rea"
-elif [ -f "\${REA_ROOT}/dist/cli/index.js" ]; then
+  set -- "\${REA_ROOT}/node_modules/.bin/rea" hook push-gate "\$@"
+elif [ -f "\${REA_ROOT}/dist/cli/index.js" ] && [ -f "\${REA_ROOT}/package.json" ] && grep -q '"name": *"@bookedsolid/rea"' "\${REA_ROOT}/package.json" 2>/dev/null; then
   # rea's own repo (dogfood) — the package is not installed under
   # node_modules here because we ARE the package. The built CLI
   # entry point lives at dist/cli/index.js; node runs it directly.
-  REA_BIN="node \${REA_ROOT}/dist/cli/index.js"
+  # Gate this branch on \`package.json\` declaring \`@bookedsolid/rea\` so a
+  # consumer repo that happens to ship its own \`dist/cli/index.js\` does
+  # not get this hook executing the consumer's unrelated build.
+  set -- node "\${REA_ROOT}/dist/cli/index.js" hook push-gate "\$@"
 elif command -v rea >/dev/null 2>&1; then
-  REA_BIN="rea"
+  set -- rea hook push-gate "\$@"
 elif command -v npx >/dev/null 2>&1; then
   # Last resort: npx will resolve the package from npm or the cache.
   # Pass \`--no-install\` so a rare cache-cold machine surfaces a clear
   # error instead of silently downloading at push time.
-  REA_BIN="npx --no-install @bookedsolid/rea"
+  set -- npx --no-install @bookedsolid/rea hook push-gate "\$@"
 else
   printf 'rea: cannot locate the rea CLI. Install locally (\`pnpm add -D @bookedsolid/rea\`) or globally (\`npm i -g @bookedsolid/rea\`).\\n' >&2
   exit 2
 fi
 
-# \$@ carries the pre-push arguments (git passes <remote-name> <remote-url>).
-# Stdin is inherited by \`exec\` → the CLI sees it unchanged.
-exec \$REA_BIN hook push-gate "\$@"
+# 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() {
@@ -202,10 +269,12 @@ export function isReaManagedFallback(content) {
     return secondLine === FALLBACK_MARKER;
 }
 /**
- * True when `content` is the legacy v1 fallback (`.git/hooks/pre-push`
- * that 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.
+ * True when `content` is a legacy fallback hook authored by an earlier rea
+ * 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'))
@@ -214,7 +283,9 @@ export function isLegacyReaManagedFallback(content) {
     if (secondLineEnd < 0)
         return false;
     const secondLine = content.slice(10, secondLineEnd);
-    return secondLine === LEGACY_FALLBACK_MARKER_V1;
+    return (secondLine === LEGACY_FALLBACK_MARKER_V3 ||
+        secondLine === LEGACY_FALLBACK_MARKER_V2 ||
+        secondLine === LEGACY_FALLBACK_MARKER_V1);
 }
 /**
  * True when `content` carries the rea Husky gate markers in the canonical
@@ -231,11 +302,15 @@ export function isReaManagedHuskyGate(content) {
     return hasHeaderMarkers(content, HUSKY_GATE_MARKER, HUSKY_GATE_BODY_MARKER);
 }
 /**
- * True when `content` is the legacy v1 Husky gate (`.husky/pre-push` from
- * 0.10.x and earlier). Used to trigger the upgrade migration.
+ * True when `content` is a legacy Husky gate from an earlier rea release:
+ * 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_V1, LEGACY_HUSKY_GATE_BODY_MARKER_V1);
+    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) {
     if (!content.startsWith('#!/bin/sh\n'))
@@ -523,6 +598,10 @@ 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) &&
             !body.includes(LEGACY_HUSKY_GATE_MARKER_V1)) {
             return;