@bookedsolid/rea 0.10.1 → 0.10.3

package/dist/hooks/review-gate/base-resolve.js

@@ -0,0 +1,247 @@
+/**
+ * Base-ref resolution for the push-review gate.
+ *
+ * ## What "base resolution" means
+ *
+ * Given a pushed refspec (a `local_sha` + `remote_ref` pair, plus the
+ * remote name), determine:
+ *
+ *   1. the commit SHA the local changes should be diffed against
+ *      (the "merge base"), and
+ *   2. the human-facing label for the `Target:` banner line
+ *      (defect N semantic: the SEMANTIC base, not the refspec destination).
+ *
+ * The four code paths the bash core walked (push-review-core.sh §720-889):
+ *
+ *   A. Tracked-branch push (`remote_sha != ZERO`). Use
+ *      `git merge-base <remote_sha> <local_sha>`. Label = refspec target.
+ *   B. New-branch push with `branch.<source>.base` config (defect N). The
+ *      operator opted into a specific base. Prefer `refs/remotes/<remote>/
+ *      <configured>` if it exists, else fall back to `refs/heads/<configured>`
+ *      with a WARN on stderr. Label = configured base name.
+ *   C. New-branch push without config, with `refs/remotes/<remote>/HEAD`
+ *      resolvable. Use that symbolic-ref as the anchor. Label = refspec
+ *      target (preserves the cache-key contract for bare pushes).
+ *   D. Bootstrap: no config, no symbolic-ref, probe `main` then `master`.
+ *      If both fail, anchor on the empty-tree SHA so the full push content
+ *      is reviewable. Label = refspec target.
+ *
+ * ## Phase 2a scope (this file)
+ *
+ * `resolveBaseForRefspec()` composes the four paths via the `GitRunner`
+ * port from `diff.ts`. This module is pure in the same sense `diff.ts`
+ * is — every git hit goes through the injected runner, so unit tests
+ * enumerate the four paths without touching a real repo.
+ *
+ * Defect-N fail-loud (design §7) is Phase 4's final cutover and is NOT
+ * turned on here. `NoBaseResolvableError` is reserved in `errors.ts` but
+ * the empty-tree bootstrap remains the current production fallback.
+ * Phase 2b composes the final policy into `runPushReviewGate()`.
+ */
+import { EMPTY_TREE_SHA, ZERO_SHA } from './constants.js';
+import { hasCommitLocally, mergeBase, readGitConfig, refExists, resolveRemoteDefaultRef, } from './diff.js';
+/**
+ * Strip `refs/heads/` / `refs/for/` prefixes from a ref and return the
+ * trailing branch name. Used for the target-label normalization path
+ * where both ref families should collapse to a bare branch name for
+ * display. Exported for tests.
+ */
+export function stripRefsPrefix(ref) {
+    if (ref.startsWith('refs/heads/'))
+        return ref.slice('refs/heads/'.length);
+    if (ref.startsWith('refs/for/'))
+        return ref.slice('refs/for/'.length);
+    return ref;
+}
+/**
+ * Strip ONLY the `refs/heads/` prefix — leaves `refs/for/`, `refs/tags/`,
+ * and every other ref-namespace untouched. Mirrors the bash core's
+ * `${local_ref#refs/heads/}` on the source-branch lookup path (push-review-
+ * core.sh §797), so Gerrit-style pushes (`refs/for/main`) keep their
+ * namespace and do NOT accidentally match a `branch.main.base` config
+ * entry intended for a regular branch push.
+ *
+ * Codex pass-1 on Phase 2a flagged the earlier implementation that used
+ * `stripRefsPrefix` here — it would have promoted the Target: label for
+ * a Gerrit push against the reviewer's intent. Exported for tests.
+ */
+export function stripRefsHeadsOnly(ref) {
+    if (ref.startsWith('refs/heads/'))
+        return ref.slice('refs/heads/'.length);
+    return ref;
+}
+/**
+ * Resolve the base anchor for a single push refspec. See the file-top
+ * docstring for the four code paths.
+ *
+ * Deletion refspecs (local_sha === ZERO_SHA) return `{merge_base: null,
+ * status: 'ok'}` with `path: 'tracked'` — the caller is expected to have
+ * already trapped deletions via `hasDeletion()` before calling here. We
+ * don't throw in that case because the caller owns the deletion policy,
+ * not this resolver.
+ */
+export function resolveBaseForRefspec(record, deps) {
+    const { runner, cwd } = deps;
+    const targetLabel = computeInitialTargetLabel(record);
+    // Deletion — caller owns the policy.
+    if (record.is_deletion) {
+        return {
+            merge_base: null,
+            target_label: targetLabel,
+            status: 'ok',
+            path: 'tracked',
+        };
+    }
+    // Path A: tracked-branch push (remote_sha is not ZERO). Existing
+    // history is available; merge-base against the remote's tip.
+    if (record.remote_sha !== ZERO_SHA) {
+        if (!hasCommitLocally(runner, cwd, record.remote_sha)) {
+            return {
+                merge_base: null,
+                target_label: targetLabel,
+                status: 'remote_object_missing',
+                remote_sha: record.remote_sha,
+                path: 'tracked',
+            };
+        }
+        const mb = mergeBase(runner, cwd, record.remote_sha, record.local_sha);
+        if (mb === null) {
+            return {
+                merge_base: null,
+                target_label: targetLabel,
+                status: 'no_merge_base',
+                remote_sha: record.remote_sha,
+                path: 'tracked',
+            };
+        }
+        return {
+            merge_base: mb,
+            target_label: targetLabel,
+            status: 'ok',
+            path: 'tracked',
+        };
+    }
+    // Path B/C/D: new-branch push. Need a server-authoritative anchor.
+    //
+    // Bash-core parity (push-review-core.sh §797): the source-branch lookup
+    // uses `${local_ref#refs/heads/}` — strips ONLY the `refs/heads/`
+    // prefix. For a Gerrit-style `refs/for/main` push, bash leaves the ref
+    // as `refs/for/main`, the `branch.refs/for/main.base` config key never
+    // matches, and the new-branch walk proceeds to the origin/HEAD /
+    // bootstrap path. We mirror that exactly: use `stripRefsHeadsOnly`
+    // rather than the more aggressive `stripRefsPrefix` (which also strips
+    // `refs/for/`). The aggressive strip was a Phase 1 carry-over from
+    // `args.ts`'s destination-ref normalization; applied here it would
+    // cause a `refs/for/main` push to look up `branch.main.base` and
+    // potentially promote the Target: label against the reviewer's
+    // intent. Codex pass-1 on Phase 2a flagged this (P3) and we preserve
+    // byte-for-byte bash parity.
+    const sourceBranch = stripRefsHeadsOnly(record.local_ref);
+    const newBranchOutcome = resolveNewBranchBase(sourceBranch, deps);
+    if (newBranchOutcome.kind === 'config_hit') {
+        // Defect N: promote the target label to the configured base's short
+        // name. The bash core does this ONLY when the config hit fires — for
+        // all other new-branch paths the label stays as the refspec target
+        // (preserves cache-key / label continuity for pre-config consumers).
+        //
+        // `exactOptionalPropertyTypes: true` in tsconfig means we must NOT
+        // set `local_ref_fallback_warning: undefined` — we either include the
+        // key (as a string) or omit it entirely. Spread the conditional.
+        const result = {
+            merge_base: mergeBase(runner, cwd, newBranchOutcome.ref, record.local_sha) ?? EMPTY_TREE_SHA,
+            target_label: newBranchOutcome.label,
+            status: 'ok',
+            path: 'new_branch_config',
+        };
+        if (newBranchOutcome.warning !== null) {
+            result.local_ref_fallback_warning = newBranchOutcome.warning;
+        }
+        return result;
+    }
+    if (newBranchOutcome.kind === 'origin_head') {
+        return {
+            merge_base: mergeBase(runner, cwd, newBranchOutcome.ref, record.local_sha) ?? EMPTY_TREE_SHA,
+            target_label: targetLabel,
+            status: 'ok',
+            path: 'new_branch_origin_head',
+        };
+    }
+    // Bootstrap: no config, no remote HEAD — anchor on the empty-tree SHA
+    // so the full push content is reviewable. Matches bash §887.
+    return {
+        merge_base: EMPTY_TREE_SHA,
+        target_label: targetLabel,
+        status: 'ok',
+        path: 'bootstrap_empty_tree',
+    };
+}
+/**
+ * Compute the initial `Target:` label for a refspec: the short name of
+ * the remote ref, falling back to `main` when it's empty (defensive;
+ * `args.ts` should never emit an empty remote_ref for a non-deletion).
+ *
+ * Exported for unit tests. Mirrors push-review-core.sh §725-727.
+ */
+export function computeInitialTargetLabel(record) {
+    let target = stripRefsPrefix(record.remote_ref);
+    if (target.length === 0)
+        target = 'main';
+    return target;
+}
+/**
+ * Path B: consult `branch.<source>.base`. Returns `config_hit` iff a base
+ * was configured AND resolvable to a ref that exists. Falls through
+ * otherwise. Exported so tests can exercise the config-path independently.
+ */
+export function resolveNewBranchBase(sourceBranch, deps) {
+    const { runner, cwd, remote } = deps;
+    // B — branch.<source>.base config hit.
+    if (sourceBranch.length > 0 && sourceBranch !== 'HEAD') {
+        const configuredBase = readGitConfig(runner, cwd, `branch.${sourceBranch}.base`);
+        if (configuredBase.length > 0) {
+            const remoteRef = `refs/remotes/${remote}/${configuredBase}`;
+            const localRef = `refs/heads/${configuredBase}`;
+            if (refExists(runner, cwd, remoteRef)) {
+                return {
+                    kind: 'config_hit',
+                    ref: remoteRef,
+                    label: configuredBase,
+                    warning: null,
+                };
+            }
+            if (refExists(runner, cwd, localRef)) {
+                // Bash-core §819-820: local-ref fallback is less trustworthy; emit
+                // a WARN so the reviewer knows the anchor may be stale.
+                const warning = `WARN: branch.${sourceBranch}.base=${configuredBase} resolved to local ref; ` +
+                    `remote counterpart ${remote}/${configuredBase} missing — reviewer-side diff may be stale`;
+                return {
+                    kind: 'config_hit',
+                    ref: localRef,
+                    label: configuredBase,
+                    warning,
+                };
+            }
+            // Config key set but neither ref exists: fall through to origin/HEAD
+            // (bash does the same — `configured_base` stays non-empty, but
+            // `default_ref` is still empty so the OR at §844 takes over).
+        }
+    }
+    // C — refs/remotes/<remote>/HEAD.
+    const symbolic = resolveRemoteDefaultRef(runner, cwd, remote);
+    if (symbolic !== null && symbolic.length > 0) {
+        return { kind: 'origin_head', ref: symbolic };
+    }
+    // C-bis — fall-back probes: `main`, then `master`. Bash §834-843 probes
+    // both because symbolic-ref fails on shallow or mirror clones where
+    // origin/HEAD was never set.
+    const mainRef = `refs/remotes/${remote}/main`;
+    if (refExists(runner, cwd, mainRef)) {
+        return { kind: 'origin_head', ref: mainRef };
+    }
+    const masterRef = `refs/remotes/${remote}/master`;
+    if (refExists(runner, cwd, masterRef)) {
+        return { kind: 'origin_head', ref: masterRef };
+    }
+    // D — bootstrap.
+    return { kind: 'bootstrap' };
+}

package/dist/hooks/review-gate/cache-key.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Cache-key computation. This module pins the contract between the push-
+ * review gate and the review-cache (`rea cache check` / `rea cache set`).
+ *
+ * ## The 0.10.1 revert constraint (design §8)
+ *
+ * An earlier attempt at defect N changed the cache-key input in the bash
+ * core and silently invalidated every consumer's existing cache. The
+ * failure was: the bash resolver started using the refspec target ref in
+ * the cache-key input rather than the merge-base-anchor SHA, so a
+ * legitimate cache entry from before the change produced a different key
+ * after the upgrade.
+ *
+ * The TS port makes the contract explicit:
+ *
+ *   cache_key = sha256_hex( full_git_diff_output )
+ *
+ * where `full_git_diff_output` is the UTF-8 string returned by
+ * `git diff <merge_base>..<source_sha>` with NO added framing. The key
+ * is NOT a function of ref names, branch names, or target labels — those
+ * are stored in the cache entry as context but do not participate in key
+ * derivation.
+ *
+ * ## Fixture-backed compatibility test
+ *
+ * `__fixtures__/cache-keys.json` records six scenarios captured from the
+ * 0.10.1 bash core (bare push, multi-refspec, force-push, deletion,
+ * new-branch, cross-repo). `cache-key.test.ts` asserts byte-exact
+ * `computeCacheKey(input) === expected` across all scenarios. Any phase
+ * that changes this module without updating the fixture fails the suite.
+ */
+import { type HexSha256 } from './hash.js';
+export interface CacheKeyInput {
+    /** Full `git diff <merge_base>..<source_sha>` output. */
+    diff: string;
+}
+/**
+ * Compute the cache key for a push-review entry. Stable, deterministic,
+ * pure. The key is the SHA-256 of the UTF-8 bytes of the diff string.
+ *
+ * @returns the 64-char lowercase hex digest.
+ */
+export declare function computeCacheKey(input: CacheKeyInput): HexSha256;
+/**
+ * Input shape for a cache-lookup call. The key itself is the diff digest
+ * from `computeCacheKey`; branch + base are context fields that select
+ * which entry within the key-bucket to return. The bash core and the
+ * existing `src/cache/review-cache.ts` both key lookups on
+ * `(sha, branch, base)`, and the TS port keeps that contract.
+ */
+export interface CacheLookupContext {
+    key: HexSha256;
+    branch: string;
+    base: string;
+}

package/dist/hooks/review-gate/cache-key.js

@@ -0,0 +1,41 @@
+/**
+ * Cache-key computation. This module pins the contract between the push-
+ * review gate and the review-cache (`rea cache check` / `rea cache set`).
+ *
+ * ## The 0.10.1 revert constraint (design §8)
+ *
+ * An earlier attempt at defect N changed the cache-key input in the bash
+ * core and silently invalidated every consumer's existing cache. The
+ * failure was: the bash resolver started using the refspec target ref in
+ * the cache-key input rather than the merge-base-anchor SHA, so a
+ * legitimate cache entry from before the change produced a different key
+ * after the upgrade.
+ *
+ * The TS port makes the contract explicit:
+ *
+ *   cache_key = sha256_hex( full_git_diff_output )
+ *
+ * where `full_git_diff_output` is the UTF-8 string returned by
+ * `git diff <merge_base>..<source_sha>` with NO added framing. The key
+ * is NOT a function of ref names, branch names, or target labels — those
+ * are stored in the cache entry as context but do not participate in key
+ * derivation.
+ *
+ * ## Fixture-backed compatibility test
+ *
+ * `__fixtures__/cache-keys.json` records six scenarios captured from the
+ * 0.10.1 bash core (bare push, multi-refspec, force-push, deletion,
+ * new-branch, cross-repo). `cache-key.test.ts` asserts byte-exact
+ * `computeCacheKey(input) === expected` across all scenarios. Any phase
+ * that changes this module without updating the fixture fails the suite.
+ */
+import { sha256Hex } from './hash.js';
+/**
+ * Compute the cache key for a push-review entry. Stable, deterministic,
+ * pure. The key is the SHA-256 of the UTF-8 bytes of the diff string.
+ *
+ * @returns the 64-char lowercase hex digest.
+ */
+export function computeCacheKey(input) {
+    return sha256Hex(input.diff);
+}

package/dist/hooks/review-gate/cache.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Review-cache adapter for the push-review gate.
+ *
+ * ## What this module owns
+ *
+ * 1. Compute the cache key from a diff. **Re-exports** `computeCacheKey`
+ *    from the Phase-1 `cache-key.ts` module — this is the same function,
+ *    not a reimplementation. The fixture suite (`cache.test.ts`) locks
+ *    that invariant via a byte-exact re-run against
+ *    `__fixtures__/cache-keys.json`. If the two modules ever diverge,
+ *    the 0.10.x → 0.11.0 cache contract is broken and every consumer's
+ *    on-disk cache becomes unreachable. See design §8.
+ *
+ * 2. Wrap `src/cache/review-cache.ts` so callers get a single entry
+ *    point — `checkReviewCache({ diff, branch, base })` — that hides
+ *    the TTL semantics, the `(sha, branch, base)` key tuple, and the
+ *    cache-lookup result shape.
+ *
+ * 3. Translate the cache lookup into the same three-way outcome the
+ *    bash core's §1203 `jq -e '.hit == true and .result == "pass"'`
+ *    check emitted:
+ *
+ *      - `hit_pass`    — cache hit AND result === 'pass'. Gate passes.
+ *      - `hit_fail`    — cache hit AND result === 'fail'. Cached
+ *                        negative verdict; gate blocks. (Bash §1197-1202
+ *                        rejects this; we preserve.)
+ *      - `miss`        — no hit / expired / empty file. Gate falls
+ *                        through to the review-required banner.
+ *      - `query_error` — cache lookup threw. Bash §1180-1196 treated
+ *                        this as a `{"hit":false,"reason":"query_error"}`
+ *                        cached result; we carry the error body so the
+ *                        caller can emit the CACHE CHECK FAILED banner
+ *                        with the SANITIZED stderr (defect C0/C1 strip).
+ *
+ * ## Phase 2a scope
+ *
+ * This file exports pure functions over the already-TS
+ * `review-cache.ts`. No subprocess `spawn`, no CLI fork. The bash
+ * core's `rea cache check` subprocess hop is obviated entirely —
+ * once Phase 3 swaps the shim we no longer fork/exec node for the
+ * cache lookup at all.
+ *
+ * ## Phase 2b composition
+ *
+ * `runPushReviewGate` in `index.ts` calls `computeCacheKeyFromDiff` +
+ * `checkReviewCache` sequentially; the latter returns a discriminated
+ * outcome the gate branches on. No new behavior lands here — that's
+ * the `codex-gate.ts` / composition step.
+ */
+import type { HexSha256 } from './hash.js';
+/**
+ * Compute the cache key for a diff. This is a thin re-export of Phase 1's
+ * `computeCacheKey` — exposed on this module so callers can use a single
+ * import when they need both the key AND the lookup.
+ *
+ * The function is UNCHANGED from Phase 1. The fixture suite in
+ * `cache.test.ts` proves byte-exact parity against
+ * `__fixtures__/cache-keys.json` for all six scenarios.
+ */
+export declare function computeCacheKey(diff: string): HexSha256;
+/**
+ * Discriminated outcome of a cache lookup. Matches the three-way state
+ * the bash core's §1203 predicate surfaces, plus a `query_error` kind
+ * for the §1180-1196 case.
+ */
+export type CacheOutcome = {
+    kind: 'hit_pass';
+    key: HexSha256;
+    recorded_at: string;
+} | {
+    kind: 'hit_fail';
+    key: HexSha256;
+    recorded_at: string;
+    reason?: string;
+} | {
+    kind: 'miss';
+    key: HexSha256;
+    reason: 'no-entry' | 'expired' | 'empty-file';
+} | {
+    kind: 'query_error';
+    key: HexSha256;
+    error: string;
+};
+/**
+ * Input for `checkReviewCache`. `diff` is the full `git diff` body; the
+ * cache key is derived from it via `computeCacheKey`. `branch` + `base`
+ * select which entry in the key-bucket is returned (most-recent match).
+ */
+export interface CheckReviewCacheInput {
+    baseDir: string;
+    diff: string;
+    branch: string;
+    base: string;
+    /** Optional override for `Date.now()`-driven TTL expiration — test hook only. */
+    nowMs?: number;
+    /** Optional override for the TTL (seconds). Defaults to cache-module default. */
+    maxAgeSeconds?: number;
+}
+/**
+ * Perform a cache lookup and translate into the discriminated outcome.
+ *
+ * Does NOT throw on a lookup failure — every known error path routes
+ * through the `query_error` variant so the caller's single `switch`
+ * handles all four outcomes. This mirrors the bash core's
+ * `CACHE_STDOUT || CACHE_EXIT != 0 → {"hit":false,...}` collapse at
+ * §1180-1196.
+ */
+export declare function checkReviewCache(input: CheckReviewCacheInput): Promise<CacheOutcome>;

package/dist/hooks/review-gate/cache.js

@@ -0,0 +1,120 @@
+/**
+ * Review-cache adapter for the push-review gate.
+ *
+ * ## What this module owns
+ *
+ * 1. Compute the cache key from a diff. **Re-exports** `computeCacheKey`
+ *    from the Phase-1 `cache-key.ts` module — this is the same function,
+ *    not a reimplementation. The fixture suite (`cache.test.ts`) locks
+ *    that invariant via a byte-exact re-run against
+ *    `__fixtures__/cache-keys.json`. If the two modules ever diverge,
+ *    the 0.10.x → 0.11.0 cache contract is broken and every consumer's
+ *    on-disk cache becomes unreachable. See design §8.
+ *
+ * 2. Wrap `src/cache/review-cache.ts` so callers get a single entry
+ *    point — `checkReviewCache({ diff, branch, base })` — that hides
+ *    the TTL semantics, the `(sha, branch, base)` key tuple, and the
+ *    cache-lookup result shape.
+ *
+ * 3. Translate the cache lookup into the same three-way outcome the
+ *    bash core's §1203 `jq -e '.hit == true and .result == "pass"'`
+ *    check emitted:
+ *
+ *      - `hit_pass`    — cache hit AND result === 'pass'. Gate passes.
+ *      - `hit_fail`    — cache hit AND result === 'fail'. Cached
+ *                        negative verdict; gate blocks. (Bash §1197-1202
+ *                        rejects this; we preserve.)
+ *      - `miss`        — no hit / expired / empty file. Gate falls
+ *                        through to the review-required banner.
+ *      - `query_error` — cache lookup threw. Bash §1180-1196 treated
+ *                        this as a `{"hit":false,"reason":"query_error"}`
+ *                        cached result; we carry the error body so the
+ *                        caller can emit the CACHE CHECK FAILED banner
+ *                        with the SANITIZED stderr (defect C0/C1 strip).
+ *
+ * ## Phase 2a scope
+ *
+ * This file exports pure functions over the already-TS
+ * `review-cache.ts`. No subprocess `spawn`, no CLI fork. The bash
+ * core's `rea cache check` subprocess hop is obviated entirely —
+ * once Phase 3 swaps the shim we no longer fork/exec node for the
+ * cache lookup at all.
+ *
+ * ## Phase 2b composition
+ *
+ * `runPushReviewGate` in `index.ts` calls `computeCacheKeyFromDiff` +
+ * `checkReviewCache` sequentially; the latter returns a discriminated
+ * outcome the gate branches on. No new behavior lands here — that's
+ * the `codex-gate.ts` / composition step.
+ */
+import { lookup } from '../../cache/review-cache.js';
+import { computeCacheKey as computePhase1CacheKey } from './cache-key.js';
+/**
+ * Compute the cache key for a diff. This is a thin re-export of Phase 1's
+ * `computeCacheKey` — exposed on this module so callers can use a single
+ * import when they need both the key AND the lookup.
+ *
+ * The function is UNCHANGED from Phase 1. The fixture suite in
+ * `cache.test.ts` proves byte-exact parity against
+ * `__fixtures__/cache-keys.json` for all six scenarios.
+ */
+export function computeCacheKey(diff) {
+    return computePhase1CacheKey({ diff });
+}
+/**
+ * Perform a cache lookup and translate into the discriminated outcome.
+ *
+ * Does NOT throw on a lookup failure — every known error path routes
+ * through the `query_error` variant so the caller's single `switch`
+ * handles all four outcomes. This mirrors the bash core's
+ * `CACHE_STDOUT || CACHE_EXIT != 0 → {"hit":false,...}` collapse at
+ * §1180-1196.
+ */
+export async function checkReviewCache(input) {
+    const key = computeCacheKey(input.diff);
+    let result;
+    try {
+        result = await lookup(input.baseDir, {
+            sha: key,
+            branch: input.branch,
+            base: input.base,
+            ...(input.nowMs !== undefined ? { nowMs: input.nowMs } : {}),
+            ...(input.maxAgeSeconds !== undefined ? { maxAgeSeconds: input.maxAgeSeconds } : {}),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { kind: 'query_error', key, error: msg };
+    }
+    if (!result.hit) {
+        // `result.missReason` is always set when `hit` is false (see
+        // review-cache.ts's CacheLookupResult contract). The fallback to
+        // 'no-entry' is defensive for an ill-formed result we shouldn't see.
+        return {
+            kind: 'miss',
+            key,
+            reason: result.missReason ?? 'no-entry',
+        };
+    }
+    // Hit. Branch on verdict — the bash core requires BOTH hit==true AND
+    // result==pass. A hit with result==fail is a cached negative verdict
+    // and must NOT unblock the push.
+    const entry = result.entry;
+    if (entry === undefined) {
+        // Defensive: `hit: true` without an entry is an ill-formed result.
+        return { kind: 'miss', key, reason: 'no-entry' };
+    }
+    if (entry.result === 'pass') {
+        return { kind: 'hit_pass', key, recorded_at: entry.recorded_at };
+    }
+    // result === 'fail'
+    const hitFail = {
+        kind: 'hit_fail',
+        key,
+        recorded_at: entry.recorded_at,
+    };
+    if (entry.reason !== undefined && entry.reason.length > 0) {
+        hitFail.reason = entry.reason;
+    }
+    return hitFail;
+}

package/dist/hooks/review-gate/constants.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Constants shared across the review-gate modules. Kept in one file so the
+ * values that a reader cares about (the all-zeros SHA, the empty-tree SHA,
+ * the protected-path set) are trivially grep-able.
+ */
+/** The git-native "null" SHA — a deletion on the pre-push contract. */
+export declare const ZERO_SHA = "0000000000000000000000000000000000000000";
+/**
+ * The canonical empty-tree SHA-1. Used as the merge-base baseline when a
+ * new-branch push has no remote-tracking ref to anchor on — `git diff
+ * <empty-tree>..<local_sha>` gives the full push content, and the gate
+ * treats it as a diff against nothing (which is what it is, operationally).
+ */
+export declare const EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+/**
+ * The protected-path set. A push that touches any file under one of these
+ * prefixes requires a matching `codex.review` audit record with verdict in
+ * {pass, concerns} AND emission_source in {rea-cli, codex-cli}. See the
+ * THREAT_MODEL for the full threat statement, and the design doc §9 for
+ * the carry-forward from the bash core.
+ *
+ * Pattern format: leading/trailing slashes stripped; matched as directory
+ * prefixes by `protected-paths.ts`. Order is not significant (a hit on any
+ * entry is sufficient), but we keep the list sorted for grep-ability.
+ */
+export declare const PROTECTED_PATH_PREFIXES: readonly string[];

package/dist/hooks/review-gate/constants.js

@@ -0,0 +1,34 @@
+/**
+ * Constants shared across the review-gate modules. Kept in one file so the
+ * values that a reader cares about (the all-zeros SHA, the empty-tree SHA,
+ * the protected-path set) are trivially grep-able.
+ */
+/** The git-native "null" SHA — a deletion on the pre-push contract. */
+export const ZERO_SHA = '0000000000000000000000000000000000000000';
+/**
+ * The canonical empty-tree SHA-1. Used as the merge-base baseline when a
+ * new-branch push has no remote-tracking ref to anchor on — `git diff
+ * <empty-tree>..<local_sha>` gives the full push content, and the gate
+ * treats it as a diff against nothing (which is what it is, operationally).
+ */
+export const EMPTY_TREE_SHA = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+/**
+ * The protected-path set. A push that touches any file under one of these
+ * prefixes requires a matching `codex.review` audit record with verdict in
+ * {pass, concerns} AND emission_source in {rea-cli, codex-cli}. See the
+ * THREAT_MODEL for the full threat statement, and the design doc §9 for
+ * the carry-forward from the bash core.
+ *
+ * Pattern format: leading/trailing slashes stripped; matched as directory
+ * prefixes by `protected-paths.ts`. Order is not significant (a hit on any
+ * entry is sufficient), but we keep the list sorted for grep-ability.
+ */
+export const PROTECTED_PATH_PREFIXES = [
+    '.claude/hooks/',
+    '.github/workflows/',
+    '.husky/',
+    '.rea/',
+    'hooks/',
+    'src/gateway/middleware/',
+    'src/policy/',
+];