@bookedsolid/rea 0.10.3 → 0.12.0

package/agents/codex-adversarial.md

@@ -11,7 +11,9 @@ This is not a bolt-on. Adversarial review is a first-class, non-optional step in
 
 ## When You Are Invoked
 
-The `/codex-review` slash command calls you. The `rea-orchestrator` delegates to you after any non-trivial change. You also run automatically via the `push-review-gate` hook recipe when a recent Codex audit entry is missing on the branch being pushed.
+The `/codex-review` slash command calls you. The `rea-orchestrator` delegates to you after any non-trivial change.
+
+Note (0.11.0+): you are **not** invoked by the pre-push gate. The pre-push gate (`rea hook push-gate`) shells directly to `codex exec review --json` and parses the verdict itself — no agent wrapper, no audit-receipt consultation. When that gate blocks a push, the authoring Claude session reads the stderr banner and `.rea/last-review.json`, applies fixes, and pushes again — the auto-fix loop IS the retry mechanism. The agent wrapper (you) is kept for interactive review (`/codex-review`) where human-targeted structured output matters.
 
 ## Inputs
 
@@ -34,7 +36,7 @@ You may read additional files in the repo if needed for context, but do so read-
 5. **Parse the Codex output** — extract structured findings.
 6. **Classify findings** by category: security, correctness, edge cases, test gaps, API design, performance.
 7. **Assign verdict**: `pass` (no material findings), `concerns` (findings worth addressing but not blocking), `blocking` (findings that must be fixed before merge).
-8. **Emit audit entry** — after producing the verdict, append a structured record to `.rea/audit.jsonl` via the public `@bookedsolid/rea/audit` helper. This is what the `push-review-gate.sh` hook greps for on protected-path diffs, so the field names must match exactly:
+8. **Emit an audit entry** (optional in 0.11.0+) — the pre-push gate does not consult audit records to decide pass/fail, so you are no longer REQUIRED to emit a `codex.review` record on every interactive review. However, append one anyway via the public `@bookedsolid/rea/audit` helper when it helps forensic traceability (investigation of an intermittent verdict, review-history audit, etc.):
 
    ```ts
    import { appendAuditRecord, CODEX_REVIEW_TOOL_NAME, CODEX_REVIEW_SERVER_NAME, Tier, InvocationStatus } from '@bookedsolid/rea/audit';
@@ -54,7 +56,7 @@ You may read additional files in the repo if needed for context, but do so read-
    });
    ```
 
-   If the Codex plugin call itself flowed through rea middleware (the proxy case), the middleware also writes an envelope record — that is fine, the two are complementary: the agent-emitted record carries the semantic verdict, the middleware record carries the chain integrity proof for the underlying tool call.
+   If the Codex plugin call itself flowed through rea middleware (the proxy case), the middleware also writes an envelope record — that is fine, the two are complementary.
 
 ## Finding Shape
 

package/commands/codex-review.md

@@ -90,12 +90,10 @@ If the verdict is `blocking`, state plainly: "Do not merge until the blocking fi
 
 ## Pre-merge usage
 
-The recommended BST workflow runs `/codex-review` twice:
+This command is the **interactive** Codex adversarial review. The **pre-push** gate at `rea hook push-gate` runs Codex independently on every push — you do not need to run `/codex-review` to "prime" the push-gate. The two are complementary:
 
-1. After implementation, on the feature branch — catches issues early
-2. Immediately before merge, on the PR branch — records a fresh audit entry that the `push-review-gate` hook can check for freshness
-
-Both invocations are cheap. Run both.
+- `/codex-review` — rich, interactive review output in the chat. Use during implementation to catch issues early, at review checkpoints, or whenever you want Codex's read on a specific diff.
+- `rea hook push-gate` (wired to `.husky/pre-push`) — fresh Codex review on every push. If Codex surfaces blocking/concerns findings, the push exits 2; Claude reads `.rea/last-review.json`, fixes, and pushes again.
 
 ## Constraints
 

package/dist/audit/append.d.ts

@@ -65,45 +65,20 @@ export interface AppendAuditInput {
  * Append a structured audit record to `${baseDir}/.rea/audit.jsonl` with a
  * hash chained against the tail of the existing log.
  *
- * ## emission_source (defect P)
+ * ## emission_source
  *
- * Records written through this public helper are ALWAYS stamped with
- * `emission_source: "other"`. External consumers (Helix, ad-hoc scripts,
- * plugins) have no way to self-assert `"rea-cli"` or `"codex-cli"` through
- * this entry point — the parameter is not part of the public
- * {@link AppendAuditInput} shape. Records emitted by the rea CLI itself use
- * the dedicated {@link appendCodexReviewAuditRecord} helper, which is the
- * ONLY path that stamps `"rea-cli"`.
- *
- * The push-review cache gate rejects `codex.review` records whose
- * `emission_source` is `"other"` (or missing, for legacy records), so
- * forging a `codex.review` record through this helper produces a line that
- * is on the hash chain but does NOT satisfy the gate.
+ * Records written through this public helper are stamped with
+ * `emission_source: "other"`. The field is retained for forensic analysis
+ * (who wrote this line) but no gate consults it — the 0.11.0 stateless
+ * push-gate (see `src/hooks/push-gate/`) decides on Codex's live verdict,
+ * not on a receipt in the audit log. Pre-0.11.0 `emission_source`-gated
+ * predicates have been removed.
  *
  * @param baseDir - Repo/project root (the directory that contains `.rea/`).
  * @param input   - Event data. `tool_name` and `server_name` are required.
  * @returns The full written record, including the computed `hash`.
  */
 export declare function appendAuditRecord(baseDir: string, input: AppendAuditInput): Promise<AuditRecord>;
-/**
- * Append a `tool_name: "codex.review"` audit record certifying that a Codex
- * adversarial review ran on a specific commit SHA (defect P).
- *
- * This is the ONLY write path in `@bookedsolid/rea` that produces
- * `emission_source: "rea-cli"` for `codex.review` records. Consumers MUST
- * reach this helper through the `rea audit record codex-review` CLI (which
- * is classified as a Write-tier Bash invocation by `reaCommandTier`, defect
- * E). Any other code path calling the generic {@link appendAuditRecord}
- * with `tool_name: "codex.review"` lands with `emission_source: "other"`
- * and does NOT satisfy the push-review cache gate — closing the forgery
- * surface that `.reports/hook-patches/emit-audit-*.mjs` scripts exploited
- * before this patch.
- *
- * `tool_name` and `server_name` are fixed to the canonical values
- * (`"codex.review"` / `"codex"`) and are NOT accepted as caller inputs —
- * the type excludes them so the contract is self-documenting.
- */
-export declare function appendCodexReviewAuditRecord(baseDir: string, input: Omit<AppendAuditInput, 'tool_name' | 'server_name'>): Promise<AuditRecord>;
 export type { AuditRecord, EmissionSource } from '../gateway/middleware/audit-types.js';
 export { Tier, InvocationStatus } from '../policy/types.js';
 export { CODEX_REVIEW_TOOL_NAME, CODEX_REVIEW_SERVER_NAME, type CodexVerdict, type CodexReviewMetadata, } from './codex-event.js';

package/dist/audit/append.js

@@ -37,7 +37,6 @@ import path from 'node:path';
 import { Tier, InvocationStatus } from '../policy/types.js';
 import { GENESIS_HASH, computeHash, fsyncFile, readLastRecord, withAuditLock, } from './fs.js';
 import { maybeRotate } from '../gateway/audit/rotator.js';
-import { CODEX_REVIEW_SERVER_NAME, CODEX_REVIEW_TOOL_NAME } from './codex-event.js';
 const REA_DIR = '.rea';
 const AUDIT_FILE = 'audit.jsonl';
 /** Per-file write queue to preserve linear hash-chain order within a process. */
@@ -186,20 +185,14 @@ async function enqueueAppend(baseDir, input, emissionSource) {
  * Append a structured audit record to `${baseDir}/.rea/audit.jsonl` with a
  * hash chained against the tail of the existing log.
  *
- * ## emission_source (defect P)
+ * ## emission_source
  *
- * Records written through this public helper are ALWAYS stamped with
- * `emission_source: "other"`. External consumers (Helix, ad-hoc scripts,
- * plugins) have no way to self-assert `"rea-cli"` or `"codex-cli"` through
- * this entry point — the parameter is not part of the public
- * {@link AppendAuditInput} shape. Records emitted by the rea CLI itself use
- * the dedicated {@link appendCodexReviewAuditRecord} helper, which is the
- * ONLY path that stamps `"rea-cli"`.
- *
- * The push-review cache gate rejects `codex.review` records whose
- * `emission_source` is `"other"` (or missing, for legacy records), so
- * forging a `codex.review` record through this helper produces a line that
- * is on the hash chain but does NOT satisfy the gate.
+ * Records written through this public helper are stamped with
+ * `emission_source: "other"`. The field is retained for forensic analysis
+ * (who wrote this line) but no gate consults it — the 0.11.0 stateless
+ * push-gate (see `src/hooks/push-gate/`) decides on Codex's live verdict,
+ * not on a receipt in the audit log. Pre-0.11.0 `emission_source`-gated
+ * predicates have been removed.
  *
  * @param baseDir - Repo/project root (the directory that contains `.rea/`).
  * @param input   - Event data. `tool_name` and `server_name` are required.
@@ -208,26 +201,5 @@ async function enqueueAppend(baseDir, input, emissionSource) {
 export async function appendAuditRecord(baseDir, input) {
     return enqueueAppend(baseDir, input, 'other');
 }
-/**
- * Append a `tool_name: "codex.review"` audit record certifying that a Codex
- * adversarial review ran on a specific commit SHA (defect P).
- *
- * This is the ONLY write path in `@bookedsolid/rea` that produces
- * `emission_source: "rea-cli"` for `codex.review` records. Consumers MUST
- * reach this helper through the `rea audit record codex-review` CLI (which
- * is classified as a Write-tier Bash invocation by `reaCommandTier`, defect
- * E). Any other code path calling the generic {@link appendAuditRecord}
- * with `tool_name: "codex.review"` lands with `emission_source: "other"`
- * and does NOT satisfy the push-review cache gate — closing the forgery
- * surface that `.reports/hook-patches/emit-audit-*.mjs` scripts exploited
- * before this patch.
- *
- * `tool_name` and `server_name` are fixed to the canonical values
- * (`"codex.review"` / `"codex"`) and are NOT accepted as caller inputs —
- * the type excludes them so the contract is self-documenting.
- */
-export async function appendCodexReviewAuditRecord(baseDir, input) {
-    return enqueueAppend(baseDir, { ...input, tool_name: CODEX_REVIEW_TOOL_NAME, server_name: CODEX_REVIEW_SERVER_NAME }, 'rea-cli');
-}
 export { Tier, InvocationStatus } from '../policy/types.js';
 export { CODEX_REVIEW_TOOL_NAME, CODEX_REVIEW_SERVER_NAME, } from './codex-event.js';

package/dist/cli/audit.d.ts

@@ -10,7 +10,6 @@
  * explicit by definition, and verify operates on existing files regardless
  * of policy.
  */
-import { type CodexVerdict } from '../audit/append.js';
 /**
  * Reserved for future rotate knobs (e.g. `--retain N` to prune old rotated
  * files). Empty today — kept as a typed record so the call site's option
@@ -39,33 +38,3 @@ export declare function runAuditRotate(_options: AuditRotateOptions): Promise<vo
  * exit code is the primary signal.
  */
 export declare function runAuditVerify(options: AuditVerifyOptions): Promise<void>;
-export interface AuditRecordCodexReviewOptions {
-    headSha: string;
-    branch: string;
-    target: string;
-    verdict: CodexVerdict;
-    findingCount: number;
-    summary?: string | undefined;
-    sessionId?: string | undefined;
-    alsoSetCache?: boolean | undefined;
-}
-/**
- * `rea audit record codex-review` (Defect D / rea#77). Emits the single audit
- * event the push-review cache gate looks up by `tool_name == "codex.review"` +
- * `metadata.head_sha == <sha>` + `metadata.verdict in {pass, concerns}`. Prior
- * to this command, agents had to reverse-engineer the canonical `tool_name`
- * string, the hash-chain append path, and the `CodexReviewMetadata` shape —
- * the most common failure mode was emitting `tool_name: "codex-adversarial-review"`
- * (the agent's name) instead of `codex.review` (the event type), which the
- * gate's jq predicate silently missed.
- *
- * `--also-set-cache` performs the audit record AND the review-cache write
- * in one invocation — two sequential appends in a single process, not a
- * two-phase commit. A crash between them leaves the audit entry without
- * a cache row; the cache is recomputable from audit, the audit chain is
- * the source of truth. What this DOES eliminate is the two-step race where
- * `rea cache set` is denied by permission middleware (Defect E) after the
- * audit has already been emitted, leaving the gate stuck on "audit present
- * but cache cold" with no way forward.
- */
-export declare function runAuditRecordCodexReview(options: AuditRecordCodexReviewOptions): Promise<void>;

package/dist/cli/audit.js

@@ -13,12 +13,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { forceRotate } from '../gateway/audit/rotator.js';
-import { appendCodexReviewAuditRecord, } from '../audit/append.js';
 import { computeHash, GENESIS_HASH } from '../audit/fs.js';
-import { appendEntry as appendCacheEntry } from '../cache/review-cache.js';
 import { AUDIT_FILE, REA_DIR, err, log, reaPath } from './utils.js';
-import { Tier, InvocationStatus } from '../policy/types.js';
-import { codexVerdictToCacheResult } from './cache.js';
 /**
  * `rea audit rotate`. Forces a rotation now regardless of thresholds.
  * Empty audit files are a no-op — rotating an empty chain would produce a
@@ -300,73 +296,8 @@ export async function runAuditVerify(options) {
     }
     log(`Audit chain verified: ${totalRecords} records across ${filesToVerify.length} file(s) — clean.`);
 }
-/**
- * `rea audit record codex-review` (Defect D / rea#77). Emits the single audit
- * event the push-review cache gate looks up by `tool_name == "codex.review"` +
- * `metadata.head_sha == <sha>` + `metadata.verdict in {pass, concerns}`. Prior
- * to this command, agents had to reverse-engineer the canonical `tool_name`
- * string, the hash-chain append path, and the `CodexReviewMetadata` shape —
- * the most common failure mode was emitting `tool_name: "codex-adversarial-review"`
- * (the agent's name) instead of `codex.review` (the event type), which the
- * gate's jq predicate silently missed.
- *
- * `--also-set-cache` performs the audit record AND the review-cache write
- * in one invocation — two sequential appends in a single process, not a
- * two-phase commit. A crash between them leaves the audit entry without
- * a cache row; the cache is recomputable from audit, the audit chain is
- * the source of truth. What this DOES eliminate is the two-step race where
- * `rea cache set` is denied by permission middleware (Defect E) after the
- * audit has already been emitted, leaving the gate stuck on "audit present
- * but cache cold" with no way forward.
- */
-export async function runAuditRecordCodexReview(options) {
-    if (options.headSha.length === 0) {
-        err('--head-sha must not be empty');
-        process.exit(1);
-    }
-    if (options.branch.length === 0) {
-        err('--branch must not be empty');
-        process.exit(1);
-    }
-    if (options.target.length === 0) {
-        err('--target must not be empty');
-        process.exit(1);
-    }
-    if (!Number.isFinite(options.findingCount) || options.findingCount < 0) {
-        err(`--finding-count must be a non-negative integer; got ${options.findingCount}`);
-        process.exit(1);
-    }
-    const baseDir = process.cwd();
-    const metadata = {
-        head_sha: options.headSha,
-        target: options.target,
-        finding_count: options.findingCount,
-        verdict: options.verdict,
-    };
-    if (options.summary !== undefined && options.summary.length > 0) {
-        metadata.summary = options.summary;
-    }
-    // Defect P: stamps emission_source: "rea-cli" so the record satisfies the
-    // push-review gate's new integrity predicate. Legacy records (without
-    // emission_source) and records written through the generic
-    // appendAuditRecord() helper (emission_source: "other") are rejected.
-    // tool_name/server_name are fixed inside the helper.
-    await appendCodexReviewAuditRecord(baseDir, {
-        tier: Tier.Read,
-        status: InvocationStatus.Allowed,
-        ...(options.sessionId !== undefined ? { session_id: options.sessionId } : {}),
-        metadata,
-    });
-    log(`Recorded codex.review (${options.verdict}, ${options.findingCount} finding${options.findingCount === 1 ? '' : 's'}) for ${options.headSha.slice(0, 12)}.`);
-    if (options.alsoSetCache === true) {
-        const effect = codexVerdictToCacheResult(options.verdict);
-        const cacheEntry = await appendCacheEntry(baseDir, {
-            sha: options.headSha,
-            branch: options.branch,
-            base: options.target,
-            result: effect.result,
-            ...(effect.reason !== undefined ? { reason: effect.reason } : {}),
-        });
-        log(`Cached ${cacheEntry.result} for ${cacheEntry.sha.slice(0, 12)} (${cacheEntry.branch} → ${cacheEntry.base}).`);
-    }
-}
+// `rea audit record codex-review` was removed in 0.11.0. The 0.11.0 push-gate
+// is stateless — every `git push` runs `codex exec review --json` afresh,
+// parses the verdict from the stream, and blocks or proceeds on the spot.
+// There is no audit-receipt the gate consults, so no command to emit one.
+// See `src/hooks/push-gate/index.ts` for the replacement gate.

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

@@ -147,12 +147,10 @@ const EXPECTED_HOOKS = [
     'attribution-advisory.sh',
     'blocked-paths-enforcer.sh',
     'changeset-security-gate.sh',
-    'commit-review-gate.sh',
     'dangerous-bash-interceptor.sh',
     'dependency-audit-gate.sh',
     'env-file-protection.sh',
     'pr-issue-link-gate.sh',
-    'push-review-gate.sh',
     'secret-scanner.sh',
     'security-disclosure-gate.sh',
     'settings-protection.sh',
@@ -366,7 +364,7 @@ function checkPrePushHook(state) {
         const kind = active?.reaManaged === true
             ? 'rea-managed'
             : active?.delegatesToGate === true
-                ? 'external (delegates to push-review-gate.sh)'
+                ? 'external (delegates to `rea hook push-gate`)'
                 : 'external';
         const detail = active !== undefined ? `${kind} at ${active.path}` : undefined;
         return detail !== undefined
@@ -374,23 +372,15 @@ function checkPrePushHook(state) {
             : { label: 'pre-push hook installed', status: 'pass' };
     }
     if (state.activeForeign) {
-        // Executable file exists at the active path but does not carry
-        // governance — the parser could not confirm the review gate is
-        // invoked unconditionally. Always a hard fail.
-        //
-        // R13 F3: previously, a substring match of the gate path in the hook
-        // downgraded this to WARN. That was unsafe — any comment, echo, or
-        // dead string mentioning the path would mask a silent-bypass hook.
-        // The classifier now fails closed: either the structural parser
-        // (`referencesReviewGate` in `pre-push.ts`) recognizes a real
-        // invocation, or doctor reports fail.
+        // Executable file exists at the active path but neither carries a rea
+        // marker nor invokes `rea hook push-gate` — the push-gate is silently
+        // bypassed. Always a hard fail.
         return {
             label: 'pre-push hook installed',
             status: 'fail',
             detail: `active pre-push at ${state.activePath} is present and executable but does NOT ` +
-                `reference \`.claude/hooks/push-review-gate.sh\` — the protected-path ` +
-                `Codex audit gate is silently bypassed. Either add ` +
-                '`exec .claude/hooks/push-review-gate.sh "$@"` to the existing hook, or ' +
+                'invoke `rea hook push-gate` — the 0.11.0 push-gate is silently bypassed. ' +
+                'Either add `exec rea hook push-gate "$@"` to the existing hook, or ' +
                 'remove it and re-run `rea init` to install the fallback.',
         };
     }
@@ -433,6 +423,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
@@ -531,7 +610,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

@@ -0,0 +1,55 @@
+/**
+ * `rea hook push-gate` — the CLI surface the husky `.husky/pre-push` stub
+ * calls. Stateless pre-push Codex review.
+ *
+ * Exit-code contract:
+ *
+ *   0 — push proceeds (pass verdict, empty diff, disabled by policy, or
+ *       REA_SKIP_PUSH_GATE waiver)
+ *   1 — HALT kill-switch active; block push
+ *   2 — blocked by verdict (blocking, or concerns when concerns_blocks=true
+ *       and REA_ALLOW_CONCERNS not set), or by codex error (timeout, not
+ *       installed, subprocess failure, protocol error)
+ *
+ * Invocation contract:
+ *
+ *   rea hook push-gate
+ *   rea hook push-gate --base origin/main
+ *   rea hook push-gate --base refs/remotes/upstream/main
+ *
+ * The husky stub does NOT parse the git pre-push stdin contract itself —
+ * the 0.10.x bash gate did, to diff refspec-by-refspec; the 0.11.0 gate
+ * diffs `HEAD` against the resolved base (upstream → origin/HEAD → …).
+ * That is strictly less granular than refspec parsing, but Codex reviews
+ * the whole diff anyway and pushing multiple branches simultaneously is
+ * vanishingly rare in practice.
+ *
+ * A missing `.rea/policy.yaml` is treated as "defaults apply" —
+ * `codex_required: true`, `concerns_blocks: true`. The gate still fires.
+ * This matches the protective default established in 0.10.x.
+ */
+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
+ * share the same entry. Throws via `process.exit` rather than returning a
+ * code — the commander handler is async but the convention across `src/cli/`
+ * is to exit from the leaf (see `audit.ts`, `freeze.ts`). Keeping the
+ * behavior consistent prevents commander from inferring its own default.
+ */
+export declare function runHookPushGate(options: HookPushGateOptions): Promise<void>;
+/**
+ * Attach the `rea hook` subcommand tree to a commander Program. Single
+ * subcommand today (`push-gate`); new hooks should land here rather than as
+ * top-level commands so the CLI surface stays navigable.
+ */
+export declare function registerHookCommand(program: Command): void;