@bookedsolid/rea 0.11.0 → 0.12.0

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

@@ -124,38 +124,102 @@ export async function runPushGate(deps) {
             summary: 'review.codex_required is false — push-gate skipped',
         };
     }
-    // 3. REA_SKIP_PUSH_GATE — value-carrying waiver. HALT-wins ordering means
-    //    this is checked AFTER halt (step 1) and AFTER codex_required=false
+    // 3. Value-carrying skip waivers. HALT-wins ordering means these are
+    //    checked AFTER halt (step 1) and AFTER codex_required=false
     //    short-circuit (step 2). Both of those should hold anyway; this is
-    //    for the case where codex is required but the operator wants to
+    //    for the case where codex IS required but the operator wants to
     //    skip for a narrow, documented reason.
-    const skipReason = (env.REA_SKIP_PUSH_GATE ?? '').trim();
-    if (skipReason.length > 0) {
-        stderr(`rea: REA_SKIP_PUSH_GATE=${skipReason} — push-gate skipped (audited).\n`);
+    //
+    //    Two equivalent env vars are honored — gate behavior is identical;
+    //    only the audit metadata's `skip_var` differs so operators can grep
+    //    their audit log to see which variant agents used:
+    //
+    //      - REA_SKIP_PUSH_GATE     — the original 0.11.0 var
+    //      - REA_SKIP_CODEX_REVIEW  — added in 0.12.0 to match the variant
+    //                                 documented elsewhere in the codebase
+    //                                 (gateway/reviewers, codex-probe). Prior
+    //                                 to 0.12.0 this string only worked at
+    //                                 the gateway tier; agents who set it on
+    //                                 a `git push` got no skip and codex still
+    //                                 ran. The mismatch surfaced during the
+    //                                 helixir migration session 2026-04-26.
+    //
+    //    Precedence on simultaneous set: REA_SKIP_PUSH_GATE wins (it was the
+    //    canonical name) and REA_SKIP_CODEX_REVIEW is logged but not used.
+    //    Either var alone with non-empty reason short-circuits.
+    const skipPush = (env.REA_SKIP_PUSH_GATE ?? '').trim();
+    const skipCodex = (env.REA_SKIP_CODEX_REVIEW ?? '').trim();
+    if (skipPush.length > 0 || skipCodex.length > 0) {
+        const skipVar = skipPush.length > 0 ? 'REA_SKIP_PUSH_GATE' : 'REA_SKIP_CODEX_REVIEW';
+        const skipReason = skipVar === 'REA_SKIP_PUSH_GATE' ? skipPush : skipCodex;
+        stderr(`rea: ${skipVar}=${skipReason} — push-gate skipped (audited).\n`);
         await safeAppend(appendAuditFn, deps.baseDir, EVT_SKIPPED, {
             reason: skipReason,
+            skip_var: skipVar,
         });
         return {
             status: 'skipped',
             exitCode: 0,
-            summary: `REA_SKIP_PUSH_GATE waiver: ${skipReason}`,
+            summary: `${skipVar} waiver: ${skipReason}`,
         };
     }
     // 4. Resolve (base_ref, head_sha) for the actual review.
     //
-    //    When pre-push stdin yielded at least one refspec (`git push` path),
-    //    diff against the first NON-DELETION refspec's (remote_sha..local_sha).
-    //    This matches what git itself is about to push — critical when the
-    //    operator uses `git push origin HEAD:release/1.0` and the branch's
-    //    tracking ref is a different branch entirely (the 0.10.x gate
-    //    silently reviewed against the wrong base in that case).
+    //    Precedence (highest first):
+    //      a) `--base <ref>` CLI flag (deps.explicitBase) — explicit ref the
+    //         operator named; we trust it.
+    //      b) `--last-n-commits N` CLI flag (deps.lastNCommits) — diff
+    //         against HEAD~N. Wins over the policy key.
+    //      c) `policy.review.last_n_commits` — same effect as (b), but
+    //         configured in `.rea/policy.yaml`. Persistent narrow-window.
+    //      d) Active refspec from pre-push stdin — what git is about to
+    //         push. Critical for `git push origin HEAD:release/1.0`.
+    //      e) Upstream → origin/HEAD → main/master ladder.
     //
-    //    When stdin was empty (manual invocation, test), fall back to the
-    //    upstream → origin/HEAD → main/master ladder.
+    //    When (a) collides with (b) or (c), (a) wins and we warn — explicit
+    //    ref beats relative count.
+    const policyLastN = policy.last_n_commits;
+    const explicitBaseSet = deps.explicitBase !== undefined && deps.explicitBase.length > 0;
+    const lastNFromFlag = deps.lastNCommits;
+    const effectiveLastN = lastNFromFlag !== undefined ? lastNFromFlag : policyLastN;
+    if (explicitBaseSet && effectiveLastN !== undefined) {
+        const source = lastNFromFlag !== undefined ? '--last-n-commits' : 'policy.review.last_n_commits';
+        stderr(`rea: --base ${deps.explicitBase} overrides ${source}=${effectiveLastN}; using explicit ref.\n`);
+    }
     const activeRefspec = (deps.refspecs ?? []).find((r) => r.localSha !== NULL_SHA && r.localSha.length > 0);
     let base;
     let headSha;
-    if (activeRefspec !== undefined && (deps.explicitBase === undefined || deps.explicitBase.length === 0)) {
+    if (explicitBaseSet) {
+        // (a) explicit base wins absolutely.
+        base = resolveBaseRef(git, { explicit: deps.explicitBase });
+        headSha = activeRefspec !== undefined ? activeRefspec.localSha : git.headSha();
+    }
+    else if (effectiveLastN !== undefined && effectiveLastN > 0) {
+        // (b) / (c) last-n-commits. Resolves to a SHA via `git rev-parse
+        // <headRef>~N`. Compute headSha FIRST so the resolver walks back N
+        // commits from the pushed ref rather than the local HEAD — critical
+        // for `git push origin some-other-branch` where the active refspec's
+        // localSha is a different branch entirely from the checkout's HEAD.
+        headSha = activeRefspec !== undefined ? activeRefspec.localSha : git.headSha();
+        base = resolveBaseRef(git, {
+            lastNCommits: effectiveLastN,
+            headRef: headSha,
+        });
+        if (base.lastNCommitsRequested !== undefined &&
+            base.lastNCommits !== undefined &&
+            base.lastNCommits < base.lastNCommitsRequested) {
+            // Clamp warning: the resolver couldn't go back N commits, so it
+            // clamped to the entire branch history (diff vs empty-tree, K+1
+            // commits reviewed) — `base.lastNCommits` carries the actual K+1.
+            // This warning fires both when source is 'last-n-commits' (clamped
+            // mid-branch, root commit included via empty-tree) and when source
+            // is 'empty-tree' (single-commit branch). The user-facing message
+            // is identical: we wanted N, got K, here's what we reviewed.
+            stderr(`rea: ${headSha.slice(0, 12)}~${base.lastNCommitsRequested} not reachable; reviewing all ${base.lastNCommits} commits on this branch instead.\n`);
+        }
+    }
+    else if (activeRefspec !== undefined) {
+        // (d) refspec-aware base — use what git is about to push.
         headSha = activeRefspec.localSha;
         if (activeRefspec.remoteSha === NULL_SHA || activeRefspec.remoteSha.length === 0) {
             // New remote ref — no existing commits to diff against. Fall back to
@@ -168,11 +232,8 @@ export async function runPushGate(deps) {
         }
     }
     else {
-        base = resolveBaseRef(git, {
-            ...(deps.explicitBase !== undefined && deps.explicitBase.length > 0
-                ? { explicit: deps.explicitBase }
-                : {}),
-        });
+        // (e) upstream ladder.
+        base = resolveBaseRef(git);
         headSha = git.headSha();
     }
     if (headSha.length === 0) {
@@ -190,6 +251,8 @@ export async function runPushGate(deps) {
             base_ref: base.ref,
             base_source: base.source,
             head_sha: headSha,
+            last_n_commits: base.lastNCommits,
+            last_n_commits_requested: base.lastNCommitsRequested,
         });
         return {
             status: 'empty-diff',
@@ -238,6 +301,8 @@ export async function runPushGate(deps) {
             duration_seconds: codexResult.durationSeconds,
             event_count: codexResult.eventCount,
             concerns_override: summary.verdict === 'concerns' && isConcernsOverrideSet(env) ? true : undefined,
+            last_n_commits: base.lastNCommits,
+            last_n_commits_requested: base.lastNCommitsRequested,
         });
         if (blocked) {
             return {

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

@@ -9,9 +9,16 @@
  * skip". This module is pure policy.
  *
  * Defaults (when a field is absent or `review:` is missing entirely):
- *   - `codex_required`   → `true`  (safe-by-default: run Codex)
- *   - `concerns_blocks`  → `true`  (safe-by-default: concerns halt the push)
- *   - `timeout_ms`       → 600_000 (10 minutes)
+ *   - `codex_required`   → `true`    (safe-by-default: run Codex)
+ *   - `concerns_blocks`  → `true`    (safe-by-default: concerns halt the push)
+ *   - `timeout_ms`       → 1_800_000 (30 minutes — raised in 0.12.0 from the
+ *                                     previous 10-minute default after the
+ *                                     helixir migration session 2026-04-26
+ *                                     showed realistic feature-branch
+ *                                     reviews routinely exceeded 10 minutes
+ *                                     on large diffs. Operators who pin
+ *                                     `timeout_ms:` in policy.yaml are
+ *                                     unaffected by this change.)
  *
  * A missing `.rea/policy.yaml` is treated as "defaults apply" — the
  * operator may not have run `rea init` yet, and the gate's behavior
@@ -22,10 +29,17 @@ export interface ResolvedReviewPolicy {
     codex_required: boolean;
     concerns_blocks: boolean;
     timeout_ms: number;
+    /**
+     * When set, the gate resolves the diff base to `HEAD~N` (see Fix D in
+     * 0.12.0). The CLI flag `--last-n-commits N` overrides this; the
+     * policy key surfaces here as a runtime knob with the same effect.
+     * `undefined` when unset (default-untouched behavior).
+     */
+    last_n_commits: number | undefined;
     /** `true` when `.rea/policy.yaml` was absent; defaults apply. */
     policyMissing: boolean;
 }
-export declare const PUSH_GATE_DEFAULT_TIMEOUT_MS = 600000;
+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;
 /**

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

@@ -9,9 +9,16 @@
  * skip". This module is pure policy.
  *
  * Defaults (when a field is absent or `review:` is missing entirely):
- *   - `codex_required`   → `true`  (safe-by-default: run Codex)
- *   - `concerns_blocks`  → `true`  (safe-by-default: concerns halt the push)
- *   - `timeout_ms`       → 600_000 (10 minutes)
+ *   - `codex_required`   → `true`    (safe-by-default: run Codex)
+ *   - `concerns_blocks`  → `true`    (safe-by-default: concerns halt the push)
+ *   - `timeout_ms`       → 1_800_000 (30 minutes — raised in 0.12.0 from the
+ *                                     previous 10-minute default after the
+ *                                     helixir migration session 2026-04-26
+ *                                     showed realistic feature-branch
+ *                                     reviews routinely exceeded 10 minutes
+ *                                     on large diffs. Operators who pin
+ *                                     `timeout_ms:` in policy.yaml are
+ *                                     unaffected by this change.)
  *
  * A missing `.rea/policy.yaml` is treated as "defaults apply" — the
  * operator may not have run `rea init` yet, and the gate's behavior
@@ -21,7 +28,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadPolicyAsync } from '../../policy/loader.js';
-export const PUSH_GATE_DEFAULT_TIMEOUT_MS = 600_000;
+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;
 /**
@@ -41,6 +48,7 @@ export async function resolvePushGatePolicy(baseDir) {
             codex_required: PUSH_GATE_DEFAULT_CODEX_REQUIRED,
             concerns_blocks: PUSH_GATE_DEFAULT_CONCERNS_BLOCKS,
             timeout_ms: PUSH_GATE_DEFAULT_TIMEOUT_MS,
+            last_n_commits: undefined,
             policyMissing: true,
         };
     }
@@ -50,6 +58,7 @@ export async function resolvePushGatePolicy(baseDir) {
         codex_required: review.codex_required ?? PUSH_GATE_DEFAULT_CODEX_REQUIRED,
         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,
         policyMissing: false,
     };
 }

package/dist/policy/loader.d.ts

@@ -34,14 +34,17 @@ declare const PolicySchema: z.ZodObject<{
         codex_required: z.ZodOptional<z.ZodBoolean>;
         concerns_blocks: z.ZodOptional<z.ZodBoolean>;
         timeout_ms: z.ZodOptional<z.ZodNumber>;
+        last_n_commits: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         codex_required?: boolean | undefined;
         concerns_blocks?: boolean | undefined;
         timeout_ms?: number | undefined;
+        last_n_commits?: number | undefined;
     }, {
         codex_required?: boolean | undefined;
         concerns_blocks?: boolean | undefined;
         timeout_ms?: number | undefined;
+        last_n_commits?: number | undefined;
     }>>;
     redact: z.ZodOptional<z.ZodObject<{
         match_timeout_ms: z.ZodOptional<z.ZodNumber>;
@@ -135,6 +138,7 @@ declare const PolicySchema: z.ZodObject<{
         codex_required?: boolean | undefined;
         concerns_blocks?: boolean | undefined;
         timeout_ms?: number | undefined;
+        last_n_commits?: number | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;
@@ -178,6 +182,7 @@ declare const PolicySchema: z.ZodObject<{
         codex_required?: boolean | undefined;
         concerns_blocks?: boolean | undefined;
         timeout_ms?: number | undefined;
+        last_n_commits?: number | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;

package/dist/policy/loader.js

@@ -27,6 +27,7 @@ const ReviewPolicySchema = z
     codex_required: z.boolean().optional(),
     concerns_blocks: z.boolean().optional(),
     timeout_ms: z.number().int().positive().optional(),
+    last_n_commits: z.number().int().positive().optional(),
 })
     .strict();
 /**

package/dist/policy/types.d.ts

@@ -54,12 +54,54 @@ export interface ReviewPolicy {
     /**
      * Hard cap on the `codex exec review` subprocess in milliseconds. Exceeding
      * this kills the subprocess and the gate returns exit 2 with a timeout
-     * error (audited). Default when unset is 600_000 (10 minutes) — matches
-     * the upper bound we observe for a 500-line diff review on a slow link.
+     * error (audited). Default when unset is 1_800_000 (30 minutes) as of
+     * 0.12.0 — raised from 10 minutes after the helixir migration session
+     * 2026-04-26 showed realistic feature-branch diffs routinely exceeded
+     * the previous default. Operators with explicit `timeout_ms:` in
+     * `.rea/policy.yaml` are unaffected.
      *
      * Positive integer only. The loader rejects zero/negative values.
      */
     timeout_ms?: number;
+    /**
+     * When set, `rea hook push-gate` resolves the diff base to `HEAD~N`
+     * instead of the upstream → origin/HEAD ladder. Useful when a feature
+     * branch accumulates many commits and the full origin/main diff
+     * overwhelms the reviewer (the helixir 2026-04-26 case: 50+ commits
+     * relative to origin/main produced non-deterministic Codex verdicts and
+     * 10-minute timeouts).
+     *
+     * Precedence: explicit `--base <ref>` flag wins; then `--last-n-commits N`
+     * flag; then this policy key; then refspec-aware base resolution; then
+     * the upstream-ladder fallback. When `--base` AND
+     * `--last-n-commits`/`policy.last_n_commits` are both set, `--base`
+     * wins and a stderr warning is emitted.
+     *
+     * Resolution: `git rev-parse HEAD~N`. When `HEAD~N` is unreachable
+     * the resolver consults `git rev-parse --is-shallow-repository` to
+     * pick the right clamp:
+     *
+     *   - FULL clone, branch shorter than N: clamps to the empty-tree
+     *     sentinel so the root commit's changes are included
+     *     (`git diff base..HEAD` excludes `base`, so diffing against
+     *     `HEAD~K` would silently drop the root commit). Reports
+     *     `last_n_commits: K+1` — every commit on the branch reviewed.
+     *
+     *   - SHALLOW clone: clamps to `HEAD~K` (the deepest LOCALLY
+     *     resolvable ancestor) since older history exists on the remote
+     *     but isn't fetched. Using empty-tree here would balloon the
+     *     review to every tracked file in the checkout. Reports
+     *     `last_n_commits: K`. The K-th commit's content is excluded —
+     *     accepted as the cost of the shallow clone.
+     *
+     * 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).
+     *
+     * Positive integer. The loader rejects zero/negative values.
+     */
+    last_n_commits?: 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.11.0",
+  "version": "0.12.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)",

package/scripts/tarball-smoke.sh

@@ -74,8 +74,13 @@ echo "[smoke]   → $VERSION_OUT"
 echo "[smoke] rea --help"
 ./node_modules/.bin/rea --help >/dev/null
 
-echo "[smoke] rea init --yes --profile open-source"
-./node_modules/.bin/rea init --yes --profile open-source
+echo "[smoke] rea init --yes --profile open-source-no-codex"
+# 0.12.0+: doctor hard-fails when policy.review.codex_required: true and codex
+# is not on PATH (fix C of the helixir migration unblocker — see PR #85). CI
+# does not provision the codex CLI, so the smoke uses the -no-codex profile
+# variant which defaults codex_required: false. The new doctor probe is
+# covered by unit tests in src/cli/doctor.test.ts.
+./node_modules/.bin/rea init --yes --profile open-source-no-codex
 
 # Verify the installed layout matches what init claims it wrote.
 for expected in .rea/policy.yaml .rea/registry.yaml .claude/settings.json CLAUDE.md .rea/install-manifest.json; do