@bookedsolid/rea 0.25.0 → 0.26.0

package/dist/cli/review.js

@@ -0,0 +1,325 @@
+/**
+ * `rea review` — local-first codex review CLI (0.26.0+).
+ *
+ * Runs `codex exec review` against the working tree (or a specified
+ * base ref), parses the verdict, and writes a `rea.local_review`
+ * audit entry that `rea preflight` consults.
+ *
+ * Exit codes:
+ *
+ *   0 — pass (or skipped because `mode: off` + codex unavailable)
+ *   1 — concerns (configurable via --strict-fail-on)
+ *   2 — blocking, codex error, or codex unavailable in `mode: enforced`
+ *
+ * Behavior matrix:
+ *
+ *   policy.local_review.mode  codex available?  result
+ *   ------------------------  ---------------   ----------------------
+ *   enforced or unset (def.)  yes               run review, audit
+ *   enforced or unset (def.)  no                exit 2 with helpful msg
+ *   off                       yes               run review, audit
+ *   off                       no                exit 0, audit skipped
+ *
+ * The `provider` field on the audit record is `'codex'` today. Future
+ * providers (Claude-subagent, Pi, Gemma) write the SAME `rea.local_review`
+ * shape with their own `provider:` value — `rea preflight` accepts any.
+ *
+ * The CLI is a thin wrapper around `runCodexReview` from
+ * `src/hooks/push-gate/codex-runner.ts`. We do NOT re-implement codex
+ * spawning. The push-gate's iron-gate defaults (gpt-5.4 + high reasoning)
+ * apply identically here so a local review carries the same weight as
+ * the push-gate's review.
+ */
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { appendAuditRecord } from '../audit/append.js';
+import { LOCAL_REVIEW_TOOL_NAME, LOCAL_REVIEW_SKIPPED_UNAVAILABLE_TOOL_NAME, LOCAL_REVIEW_SERVER_NAME, } from '../audit/local-review-event.js';
+import { Tier, InvocationStatus } from '../policy/types.js';
+import { loadPolicyAsync } from '../policy/loader.js';
+import { CodexNotInstalledError, CodexProtocolError, CodexSubprocessError, CodexTimeoutError, IRON_GATE_DEFAULT_MODEL, IRON_GATE_DEFAULT_REASONING, createRealGitExecutor, runCodexReview, } from '../hooks/push-gate/codex-runner.js';
+import { resolvePushGatePolicy } from '../hooks/push-gate/policy.js';
+import { resolveBaseRef } from '../hooks/push-gate/base.js';
+import { summarizeReview } from '../hooks/push-gate/findings.js';
+import { computeTreeToken, EMPTY_TREE_SHA } from '../audit/content-token.js';
+import { err, log } from './utils.js';
+const PROVIDER_CODEX = 'codex';
+/**
+ * Probe `codex --version` synchronously. Same shape as the push-gate's
+ * pre-flight probe — ENOENT/EACCES means "not installed".
+ */
+function probeCodexAvailable(cwd) {
+    const probe = spawnSync('codex', ['--version'], {
+        cwd,
+        timeout: 2000,
+        encoding: 'utf8',
+    });
+    if (probe.error !== undefined) {
+        return { available: false };
+    }
+    if (probe.status !== 0) {
+        return { available: false };
+    }
+    const version = (probe.stdout ?? '').toString().trim();
+    return version.length > 0 ? { available: true, version } : { available: true };
+}
+/**
+ * Resolve the effective `local_review.mode`. A missing policy is treated
+ * as `enforced` — the protective default. A missing `local_review` block
+ * also enforces. Only an explicit `mode: off` opts out.
+ */
+async function resolveLocalReviewMode(baseDir) {
+    let policy;
+    try {
+        policy = await loadPolicyAsync(baseDir);
+    }
+    catch {
+        // Missing/invalid policy — protective default.
+        return { mode: 'enforced', policy: undefined };
+    }
+    const mode = policy.review?.local_review?.mode ?? 'enforced';
+    return { mode, policy };
+}
+/**
+ * Public runner — exposed so tests can drive the function in-process and
+ * the commander binding can stay thin. Throws via `process.exit` (CLI
+ * convention across `src/cli/`).
+ */
+export async function runReview(options) {
+    const baseDir = process.cwd();
+    const strictFailOn = options.strictFailOn ?? 'blocking';
+    const { mode, policy } = await resolveLocalReviewMode(baseDir);
+    // Probe codex before any heavy lifting so we can branch on availability.
+    const probe = probeCodexAvailable(baseDir);
+    // Codex unavailable — branch on policy mode.
+    if (!probe.available) {
+        if (mode === 'off') {
+            // Off mode: skip silently and audit so the absence is forensically
+            // visible. Exit 0 — the team has explicitly opted out.
+            const skipped = {
+                reason: 'codex-not-installed',
+                provider: PROVIDER_CODEX,
+            };
+            // Best-effort HEAD probe for the audit record.
+            try {
+                const git = createRealGitExecutor(baseDir);
+                const head = git.headSha();
+                if (head.length > 0)
+                    skipped.head_sha = head;
+            }
+            catch {
+                /* no head — leave undefined */
+            }
+            await safeAudit(baseDir, LOCAL_REVIEW_SKIPPED_UNAVAILABLE_TOOL_NAME, InvocationStatus.Allowed, skipped, policy);
+            if (options.json === true) {
+                process.stdout.write(JSON.stringify({ status: 'skipped', reason: 'codex-not-installed' }) + '\n');
+            }
+            else {
+                log('codex not found on PATH — review skipped (policy.review.local_review.mode: off).');
+            }
+            process.exit(0);
+        }
+        // Enforced mode: hard-refuse with a helpful message.
+        err('codex CLI not found on PATH.');
+        console.error('');
+        console.error('  Install:  npm i -g @openai/codex');
+        console.error('  Or set:   policy.review.local_review.mode: off');
+        console.error('            (in .rea/policy.yaml — disables local-review enforcement');
+        console.error('             for teams without codex/claude installed)');
+        console.error('');
+        process.exit(2);
+    }
+    // Codex available — run the review.
+    let outcome;
+    try {
+        outcome = await executeCodexReview(baseDir, options);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        err(`codex review failed: ${msg}`);
+        // Audit the error so operators can correlate failures.
+        await safeAudit(baseDir, LOCAL_REVIEW_TOOL_NAME, InvocationStatus.Error, {
+            provider: PROVIDER_CODEX,
+            error: msg,
+            kind: classifyCodexError(e),
+        }, policy);
+        process.exit(2);
+    }
+    // Write the canonical audit record. THIS is the entry `rea preflight`
+    // looks for. Use server_name='rea' (the pre-existing convention) and
+    // tool_name='rea.local_review'.
+    //
+    // 0.26.0 helix-026 finding-1: `content_token` is the field preflight
+    // matches coverage on. `head_sha` is recorded for forensics. The token
+    // stays optional so legacy `codex.review` entries and future providers
+    // that can't compute a tree fingerprint still flow through preflight's
+    // back-compat head-sha fallback.
+    const metadata = {
+        head_sha: outcome.headSha,
+        base_ref: outcome.baseRef,
+        verdict: outcome.verdict,
+        finding_count: outcome.findingCount,
+        provider: PROVIDER_CODEX,
+        model: outcome.model,
+        reasoning_effort: outcome.reasoningEffort,
+        duration_seconds: outcome.durationSeconds,
+    };
+    if (outcome.contentToken.length > 0)
+        metadata.content_token = outcome.contentToken;
+    if (probe.version !== undefined)
+        metadata.provider_version = probe.version;
+    await safeAudit(baseDir, LOCAL_REVIEW_TOOL_NAME, outcome.verdict === 'blocking' ? InvocationStatus.Denied : InvocationStatus.Allowed, metadata, policy);
+    // Decide exit code based on strictFailOn.
+    let exitCode;
+    if (outcome.verdict === 'blocking') {
+        exitCode = 2;
+    }
+    else if (outcome.verdict === 'concerns') {
+        exitCode = strictFailOn === 'concerns' ? 1 : 0;
+    }
+    else {
+        exitCode = 0;
+    }
+    if (options.json === true) {
+        process.stdout.write(JSON.stringify({
+            status: outcome.verdict,
+            finding_count: outcome.findingCount,
+            head_sha: outcome.headSha,
+            base_ref: outcome.baseRef,
+            provider: PROVIDER_CODEX,
+            model: outcome.model,
+            reasoning_effort: outcome.reasoningEffort,
+            duration_seconds: outcome.durationSeconds,
+            exit_code: exitCode,
+        }) + '\n');
+    }
+    else {
+        log(`local review: ${outcome.verdict} (${outcome.findingCount} finding(s)) — head=${outcome.headSha.slice(0, 12)} base=${outcome.baseRef}`);
+        log(`audit entry written: tool_name=${LOCAL_REVIEW_TOOL_NAME}`);
+    }
+    process.exit(exitCode);
+}
+/**
+ * Execute the codex review subprocess and translate the output to a
+ * verdict. Reuses the push-gate's resolved policy so `codex_model` /
+ * `codex_reasoning_effort` / `timeout_ms` flow through identically.
+ */
+async function executeCodexReview(baseDir, options) {
+    const resolved = await resolvePushGatePolicy(baseDir);
+    const git = createRealGitExecutor(baseDir);
+    const explicit = options.base !== undefined && options.base.length > 0 ? options.base : undefined;
+    const base = explicit !== undefined
+        ? resolveBaseRef(git, { explicit })
+        : resolveBaseRef(git);
+    // 0.26.0 round-25 P2-B fix: do NOT throw on empty HEAD. An unborn-HEAD
+    // repo (`git init` + immediately `rea review`, before any commit) is a
+    // legitimate scaffolding state — `create-helix-app` and similar tools
+    // bootstrap consumer repos this way. Pre-fix, `runReview()` threw
+    // "could not resolve HEAD sha — is this a valid git repo?" which under
+    // `refuse_at: commit/both` caused a deadlock: the commit-tier hook
+    // refused commits until rea review wrote an audit entry, but rea
+    // review refused without HEAD.
+    //
+    // Resolution: when HEAD is unborn, use git's well-known empty-tree
+    // SHA as the synthetic head_sha for the audit record. `computeTreeToken`
+    // already returns empty cleanly in this state; the working-tree tokens
+    // takes over via `git stash create` once the tree is dirty (round-25
+    // P1-A path), or remains empty for a truly empty repo. Preflight's
+    // content-token match (round-25 P1-A) handles either case.
+    //
+    // Round-27 F2 fix: EMPTY_TREE_SHA promoted to a shared constant in
+    // `src/audit/content-token.ts` so `rea preflight` (reader) uses the
+    // SAME value when its `git rev-parse HEAD` probe fails. Without that
+    // symmetry the reader returned `''` and short-circuited the lookup,
+    // deadlocking the documented `git init → rea review → git commit`
+    // bootstrap flow under `refuse_at: both`.
+    const resolvedHeadSha = git.headSha();
+    const headSha = resolvedHeadSha.length > 0 ? resolvedHeadSha : EMPTY_TREE_SHA;
+    // 0.26.0 helix-026 finding-1: capture working-tree token as the content
+    // token for preflight coverage matching. Computed BEFORE codex runs so
+    // we never race a concurrent commit (the token reflects the state codex
+    // is about to review). An empty token is allowed — preflight falls back
+    // to head_sha matching when the field is absent.
+    const contentToken = computeTreeToken(baseDir);
+    const codexResult = await runCodexReview({
+        baseRef: base.ref,
+        cwd: baseDir,
+        timeoutMs: resolved.timeout_ms,
+        env: process.env,
+        ...(resolved.codex_model !== undefined ? { model: resolved.codex_model } : {}),
+        ...(resolved.codex_reasoning_effort !== undefined
+            ? { reasoningEffort: resolved.codex_reasoning_effort }
+            : {}),
+    });
+    const summary = summarizeReview(codexResult.reviewText);
+    return {
+        verdict: summary.verdict,
+        findingCount: summary.findings.length,
+        baseRef: base.ref,
+        headSha,
+        contentToken,
+        durationSeconds: codexResult.durationSeconds,
+        model: resolved.codex_model ?? IRON_GATE_DEFAULT_MODEL,
+        reasoningEffort: resolved.codex_reasoning_effort ?? IRON_GATE_DEFAULT_REASONING,
+    };
+}
+function classifyCodexError(e) {
+    if (e instanceof CodexNotInstalledError)
+        return 'not-installed';
+    if (e instanceof CodexTimeoutError)
+        return 'timeout';
+    if (e instanceof CodexProtocolError)
+        return 'protocol';
+    if (e instanceof CodexSubprocessError)
+        return 'subprocess';
+    return 'unknown';
+}
+/**
+ * Best-effort audit append — never throws. An audit failure must not
+ * change the CLI exit code.
+ */
+async function safeAudit(baseDir, toolName, status, metadata, policy) {
+    try {
+        const cleanMeta = {};
+        for (const [k, v] of Object.entries(metadata)) {
+            if (v !== undefined)
+                cleanMeta[k] = v;
+        }
+        await appendAuditRecord(baseDir, {
+            tool_name: toolName,
+            server_name: LOCAL_REVIEW_SERVER_NAME,
+            tier: Tier.Read,
+            status,
+            ...(Object.keys(cleanMeta).length > 0 ? { metadata: cleanMeta } : {}),
+            ...(policy !== undefined ? { policy } : {}),
+        });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`rea: audit append failed (${toolName}): ${msg}\n`);
+    }
+}
+/**
+ * Attach `rea review` to a commander Program.
+ */
+export function registerReviewCommand(program) {
+    program
+        .command('review')
+        .description('Run a local codex adversarial review of the working tree, write a `rea.local_review` audit entry, and exit 0 (pass), 1 (concerns), or 2 (blocking). The push-gate is the BACKUP layer — this is the primary review surface.')
+        .option('--base <ref>', 'explicit base ref to diff against (default: @{upstream} → origin/HEAD → main/master)')
+        .option('--strict-fail-on <level>', 'verdict floor that triggers non-zero exit: `concerns` or `blocking` (default `blocking`)', (raw) => {
+        if (raw !== 'concerns' && raw !== 'blocking') {
+            throw new Error(`--strict-fail-on must be "concerns" or "blocking", got ${JSON.stringify(raw)}`);
+        }
+        return raw;
+    })
+        .option('--json', 'emit a single-line JSON result instead of human-readable output')
+        .action(async (opts) => {
+        await runReview({
+            ...(opts.base !== undefined ? { base: opts.base } : {}),
+            ...(opts.strictFailOn !== undefined ? { strictFailOn: opts.strictFailOn } : {}),
+            ...(opts.json === true ? { json: true } : {}),
+        });
+    });
+}
+// Path constant for tests — not consumed elsewhere.
+export const REA_AUDIT_RELATIVE = path.join('.rea', 'audit.jsonl');

package/dist/policy/loader.d.ts

@@ -90,6 +90,29 @@ declare const PolicySchema: z.ZodObject<{
          * verdict. Set to 0 to disable caching (every push re-invokes codex).
          */
         cache_ttl_ms: z.ZodOptional<z.ZodNumber>;
+        /**
+         * 0.26.0 local-first enforcement. Strict so a typo in the off-switch
+         * surface (`mode: of`, `refuse_at: pushh`) fails policy load instead
+         * of silently disabling. `bypass_env_var` is constrained to the
+         * shell-safe identifier alphabet so a nonsense value can't smuggle
+         * shell metacharacters through the Bash-tier gate that reads it.
+         */
+        local_review: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodOptional<z.ZodEnum<["enforced", "off"]>>;
+            max_age_seconds: z.ZodOptional<z.ZodNumber>;
+            refuse_at: z.ZodOptional<z.ZodEnum<["push", "commit", "both"]>>;
+            bypass_env_var: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            mode?: "enforced" | "off" | undefined;
+            max_age_seconds?: number | undefined;
+            refuse_at?: "push" | "commit" | "both" | undefined;
+            bypass_env_var?: string | undefined;
+        }, {
+            mode?: "enforced" | "off" | undefined;
+            max_age_seconds?: number | undefined;
+            refuse_at?: "push" | "commit" | "both" | undefined;
+            bypass_env_var?: string | undefined;
+        }>>;
     }, "strict", z.ZodTypeAny, {
         codex_required?: boolean | undefined;
         concerns_blocks?: boolean | undefined;
@@ -99,6 +122,12 @@ declare const PolicySchema: z.ZodObject<{
         codex_model?: string | undefined;
         codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
         cache_ttl_ms?: number | undefined;
+        local_review?: {
+            mode?: "enforced" | "off" | undefined;
+            max_age_seconds?: number | undefined;
+            refuse_at?: "push" | "commit" | "both" | undefined;
+            bypass_env_var?: string | undefined;
+        } | undefined;
     }, {
         codex_required?: boolean | undefined;
         concerns_blocks?: boolean | undefined;
@@ -108,6 +137,12 @@ declare const PolicySchema: z.ZodObject<{
         codex_model?: string | undefined;
         codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
         cache_ttl_ms?: number | undefined;
+        local_review?: {
+            mode?: "enforced" | "off" | undefined;
+            max_age_seconds?: number | undefined;
+            refuse_at?: "push" | "commit" | "both" | undefined;
+            bypass_env_var?: string | undefined;
+        } | undefined;
     }>>;
     redact: z.ZodOptional<z.ZodObject<{
         match_timeout_ms: z.ZodOptional<z.ZodNumber>;
@@ -185,6 +220,16 @@ declare const PolicySchema: z.ZodObject<{
     }, {
         patterns?: string[] | undefined;
     }>>;
+    commit_hygiene: z.ZodOptional<z.ZodObject<{
+        warn_at_commits: z.ZodOptional<z.ZodNumber>;
+        refuse_at_commits: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        warn_at_commits?: number | undefined;
+        refuse_at_commits?: number | undefined;
+    }, {
+        warn_at_commits?: number | undefined;
+        refuse_at_commits?: number | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     version: string;
     profile: string;
@@ -215,6 +260,12 @@ declare const PolicySchema: z.ZodObject<{
         codex_model?: string | undefined;
         codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
         cache_ttl_ms?: number | undefined;
+        local_review?: {
+            mode?: "enforced" | "off" | undefined;
+            max_age_seconds?: number | undefined;
+            refuse_at?: "push" | "commit" | "both" | undefined;
+            bypass_env_var?: string | undefined;
+        } | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;
@@ -238,6 +289,10 @@ declare const PolicySchema: z.ZodObject<{
     architecture_review?: {
         patterns?: string[] | undefined;
     } | undefined;
+    commit_hygiene?: {
+        warn_at_commits?: number | undefined;
+        refuse_at_commits?: number | undefined;
+    } | undefined;
 }, {
     version: string;
     profile: string;
@@ -268,6 +323,12 @@ declare const PolicySchema: z.ZodObject<{
         codex_model?: string | undefined;
         codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
         cache_ttl_ms?: number | undefined;
+        local_review?: {
+            mode?: "enforced" | "off" | undefined;
+            max_age_seconds?: number | undefined;
+            refuse_at?: "push" | "commit" | "both" | undefined;
+            bypass_env_var?: string | undefined;
+        } | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;
@@ -291,6 +352,10 @@ declare const PolicySchema: z.ZodObject<{
     architecture_review?: {
         patterns?: string[] | undefined;
     } | undefined;
+    commit_hygiene?: {
+        warn_at_commits?: number | undefined;
+        refuse_at_commits?: number | undefined;
+    } | undefined;
 }>;
 /**
  * Async policy loader with TTL cache and mtime-based invalidation.

package/dist/policy/loader.js

@@ -89,6 +89,36 @@ const ReviewPolicySchema = z
      * verdict. Set to 0 to disable caching (every push re-invokes codex).
      */
     cache_ttl_ms: z.number().int().nonnegative().optional(),
+    /**
+     * 0.26.0 local-first enforcement. Strict so a typo in the off-switch
+     * surface (`mode: of`, `refuse_at: pushh`) fails policy load instead
+     * of silently disabling. `bypass_env_var` is constrained to the
+     * shell-safe identifier alphabet so a nonsense value can't smuggle
+     * shell metacharacters through the Bash-tier gate that reads it.
+     */
+    local_review: z
+        .object({
+        mode: z.enum(['enforced', 'off']).optional(),
+        max_age_seconds: z.number().int().positive().optional(),
+        refuse_at: z.enum(['push', 'commit', 'both']).optional(),
+        bypass_env_var: z
+            .string()
+            .regex(/^[A-Z][A-Z0-9_]{0,63}$/)
+            .optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+/**
+ * 0.26.0 commit hygiene refusal thresholds. Top-level policy block (NOT
+ * under `review`) — it's a process-discipline knob, not a review knob.
+ * `rea preflight` reads it; the push-gate ignores it.
+ */
+const CommitHygienePolicySchema = z
+    .object({
+    warn_at_commits: z.number().int().nonnegative().optional(),
+    refuse_at_commits: z.number().int().nonnegative().optional(),
 })
     .strict();
 /**
@@ -214,6 +244,9 @@ const PolicySchema = z
         patterns: z.array(z.string()).optional(),
     })
         .optional(),
+    // 0.26.0 commit-hygiene thresholds — top-level so it's discoverable
+    // separately from `review.local_review`. `rea preflight` consumes it.
+    commit_hygiene: CommitHygienePolicySchema.optional(),
 })
     .strict();
 const DEFAULT_CACHE_TTL_MS = 30_000;

package/dist/policy/types.d.ts

@@ -169,6 +169,84 @@ export interface ReviewPolicy {
      * a `rea.push_gate.verdict_flip` audit event and overwrite the cache.
      */
     cache_ttl_ms?: number;
+    /**
+     * Local-first review enforcement (0.26.0+ — CTO directive 2026-05-05).
+     *
+     * The push-gate is the BACKUP layer. The primary review surface is the
+     * working tree BEFORE commit, run via `rea review`, recorded as a
+     * `rea.local_review` audit entry. The Bash-tier `local-review-gate.sh`
+     * hook + husky `rea preflight --strict` refuse `git push` (and optionally
+     * `git commit`) when no recent matching audit entry exists for HEAD.
+     *
+     * The off-switch is the FIRST-class concern. Teams without codex/claude
+     * installed set `mode: off` to disable the new enforcement layers
+     * cleanly — no env-var hacks, no policy strip, no special init flag.
+     *
+     * The provider seam is the audit-record `provider` field, NOT this
+     * policy block. Future providers (Claude-subagent, Pi, Gemma) write
+     * `rea.local_review` records with their own `provider:` value; this
+     * block governs WHETHER the gate fires, not WHO runs the review.
+     */
+    local_review?: LocalReviewPolicy;
+}
+/**
+ * Local-first review enforcement (0.26.0+).
+ *
+ * `mode: 'enforced'` — the new Bash-tier gate, husky preflight, and
+ * `rea review` requirement all fire. Pushes are refused unless a
+ * recent matching `rea.local_review` audit entry exists OR
+ * `bypass_env_var` is set with a non-empty reason.
+ *
+ * `mode: 'off'` — every new enforcement layer becomes a silent no-op.
+ * Teams without codex/claude opt out cleanly. The push-gate (which is
+ * a separate layer governed by `codex_required`) is unaffected by this
+ * setting.
+ *
+ * Default when unset: `enforced`. The CTO directive 2026-05-05 applies
+ * to ALL rea work, OSS + enterprise — the off-switch is opt-out, never
+ * opt-in.
+ */
+export interface LocalReviewPolicy {
+    mode?: 'enforced' | 'off';
+    /**
+     * Maximum age (seconds) of a `rea.local_review` audit entry that
+     * `rea preflight` will accept as covering the current HEAD. A review
+     * older than this is treated as missing and the gate refuses.
+     * Default 86400 (24 hours).
+     */
+    max_age_seconds?: number;
+    /**
+     * Which git operations the Bash-tier gate refuses when no recent
+     * review covers HEAD.
+     *   - `'push'`   — refuse `git push` only (default)
+     *   - `'commit'` — refuse `git commit` only
+     *   - `'both'`   — refuse both
+     *
+     * The husky pre-push hook honors `'push' | 'both'`. The Bash-tier
+     * hook honors all three.
+     */
+    refuse_at?: 'push' | 'commit' | 'both';
+    /**
+     * Env-var name that, when set with a non-empty value, causes
+     * `rea preflight` to short-circuit (exit 0) AFTER writing a
+     * `rea.local_review.skipped_override` audit entry that records
+     * the reason. Default `REA_SKIP_LOCAL_REVIEW`.
+     *
+     * The override is per-invocation, audited every time, and a
+     * release valve — not a sustained way to disable enforcement.
+     * Teams that need to DISABLE enforcement set `mode: off`.
+     */
+    bypass_env_var?: string;
+}
+/**
+ * Commit-hygiene refusal thresholds (0.26.0+). `rea preflight` runs
+ * `git rev-list --count <base>..HEAD` and compares against these
+ * thresholds. Set to a sentinel value (e.g. very large integer) to
+ * effectively disable.
+ */
+export interface CommitHygienePolicy {
+    warn_at_commits?: number;
+    refuse_at_commits?: number;
 }
 /**
  * User-supplied redaction pattern entry. Each pattern has a stable `name` used
@@ -301,4 +379,15 @@ export interface Policy {
     architecture_review?: {
         patterns?: string[];
     };
+    /**
+     * Commit-hygiene refusal thresholds (0.26.0+). `rea preflight` checks
+     * `git rev-list --count <base>..HEAD`; `> warn_at_commits` warns
+     * (exit 1), `> refuse_at_commits` refuses (exit 2). The CTO directive
+     * 2026-05-05 sets the new BST default at warn_at=1 / refuse_at=5 to
+     * push every change toward squash-on-commit hygiene.
+     *
+     * Top-level (not under `review`) because it's a process-discipline
+     * knob, not a review knob. The push-gate doesn't consume it.
+     */
+    commit_hygiene?: CommitHygienePolicy;
 }