@bookedsolid/rea 0.25.0 → 0.26.0

package/dist/cli/hook.js

@@ -30,6 +30,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
 import { parsePrePushStdin, runPushGate } from '../hooks/push-gate/index.js';
 import { runBlockedScan, runProtectedScan } from '../hooks/bash-scanner/index.js';
 import { loadPolicy } from '../policy/loader.js';
@@ -250,6 +251,74 @@ export async function runHookScanBash(options) {
     }
     process.exit(0);
 }
+export async function runHookPolicyGet(options) {
+    // 0.27.0+: validate the key shape so a malformed dot-path can't be
+    // exploited by a misbehaving caller. Allow only POSIX identifier
+    // segments separated by single dots; reject empty segments, slashes,
+    // shell metacharacters, etc.
+    if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(options.key)) {
+        process.stderr.write(`rea hook policy-get: invalid key ${JSON.stringify(options.key)}\n`);
+        process.exit(1);
+    }
+    const reaRoot = options.reaRoot ?? process.env['CLAUDE_PROJECT_DIR'] ?? process.cwd();
+    const policyPath = path.join(reaRoot, '.rea', 'policy.yaml');
+    const finishMissing = () => {
+        if (options.json === true)
+            process.stdout.write('null');
+        process.exit(0);
+    };
+    if (!fs.existsSync(policyPath)) {
+        finishMissing();
+    }
+    let parsed;
+    try {
+        const raw = fs.readFileSync(policyPath, 'utf8');
+        parsed = parseYaml(raw);
+    }
+    catch {
+        // Unparseable YAML — emit empty / null and exit 1 so the bash caller
+        // can distinguish "no value" from "actual parse failure" if it
+        // wants to (the local-review-gate caller swallows exit codes).
+        if (options.json === true)
+            process.stdout.write('null');
+        process.exit(1);
+    }
+    if (parsed === null || typeof parsed !== 'object') {
+        finishMissing();
+    }
+    // Walk the dotted path. Bail (empty stdout / null) at any non-object
+    // intermediate.
+    const segments = options.key.split('.');
+    let cursor = parsed;
+    for (const seg of segments) {
+        if (cursor === null || typeof cursor !== 'object' || Array.isArray(cursor)) {
+            finishMissing();
+        }
+        cursor = cursor[seg];
+        if (cursor === undefined) {
+            finishMissing();
+        }
+    }
+    if (options.json === true) {
+        // Emit JSON for scalar/object/array/null. Objects + arrays serialize
+        // recursively. Bash callers parse via jq.
+        process.stdout.write(JSON.stringify(cursor ?? null));
+        process.exit(0);
+    }
+    // Scalar mode: only print scalar leaves. Objects/arrays print empty
+    // (legacy behavior from initial F2 implementation).
+    if (cursor === null) {
+        process.exit(0);
+    }
+    if (typeof cursor === 'string') {
+        process.stdout.write(cursor);
+    }
+    else if (typeof cursor === 'number' || typeof cursor === 'boolean') {
+        process.stdout.write(String(cursor));
+    }
+    // Object/Array → no output (caller treats as unset).
+    process.exit(0);
+}
 /**
  * Attach the `rea hook` subcommand tree to a commander Program. Two
  * subcommands today: `push-gate` and `scan-bash`. New hooks should land
@@ -297,4 +366,12 @@ export function registerHookCommand(program) {
             ...(opts.lastNCommits !== undefined ? { lastNCommits: opts.lastNCommits } : {}),
         });
     });
+    hook
+        .command('policy-get')
+        .description('Read a value from `.rea/policy.yaml` via the canonical YAML parser. Used by bash-tier hooks (`hooks/_lib/policy-read.sh::policy_nested_scalar`) so inline AND block YAML forms agree at a single source of truth. Default scalar mode: prints raw value or empty. With `--json`: emits JSON (scalar or object/array; missing path → `null`). Unparseable YAML → empty / null, exit 1.')
+        .argument('<key>', 'dotted path, e.g. `review.local_review.mode`. POSIX-identifier segments only.')
+        .option('--json', 'emit JSON instead of a scalar — supports object/array leaves. Bash callers can then parse with jq.')
+        .action(async (key, opts) => {
+        await runHookPolicyGet({ key, ...(opts.json === true ? { json: true } : {}) });
+    });
 }

package/dist/cli/index.js

@@ -6,6 +6,8 @@ import { registerHookCommand } from './hook.js';
 import { runDoctor } from './doctor.js';
 import { runFreeze, runUnfreeze } from './freeze.js';
 import { runInit } from './init.js';
+import { registerPreflightCommand } from './preflight.js';
+import { registerReviewCommand } from './review.js';
 import { runServe } from './serve.js';
 import { runStatus } from './status.js';
 import { runTofuAccept, runTofuList } from './tofu.js';
@@ -106,6 +108,13 @@ async function main() {
     // Register `rea hook push-gate` — the stateless pre-push Codex gate
     // called by `.husky/pre-push` and `.git/hooks/pre-push`.
     registerHookCommand(program);
+    // 0.26.0 local-first enforcement (CTO directive 2026-05-05). Two new
+    // top-level CLIs: `rea review` writes `rea.local_review` audit entries;
+    // `rea preflight` reads them and refuses pushes/commits without a
+    // recent matching entry. The husky pre-push template + Bash-tier
+    // `local-review-gate.sh` hook both delegate to `rea preflight --strict`.
+    registerReviewCommand(program);
+    registerPreflightCommand(program);
     const tofu = program
         .command('tofu')
         .description('TOFU fingerprint operations (G7) — inspect and rebase `.rea/fingerprints.json` when a legitimate registry edit has triggered drift fail-close. Emits audit records.');

package/dist/cli/init.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import * as p from '@clack/prompts';
+import { parse as parseYaml } from 'yaml';
 import { AutonomyLevel } from '../policy/types.js';
 import { HARD_DEFAULTS, loadProfile, mergeProfiles } from '../policy/profiles.js';
 import { copyArtifacts } from './install/copy.js';
@@ -196,6 +197,29 @@ async function runWizard(options, targetDir, reagentPolicyPath, layeredBase, exi
         blockedPaths: layeredBase.blocked_paths ?? ['.env', '.env.*'],
         notificationChannel: layeredBase.notification_channel ?? '',
         codexRequired,
+        // Round-27 F6: the wizard does NOT prompt for the 0.26.0 knobs (they
+        // are advanced config — most teams accept defaults). But when the
+        // existing on-disk policy carries them, forward them verbatim so a
+        // re-run preserves operator edits exactly the same way the --yes
+        // path does.
+        ...(existingPolicy?.localReviewMode !== undefined
+            ? { localReviewMode: existingPolicy.localReviewMode }
+            : {}),
+        ...(existingPolicy?.localReviewRefuseAt !== undefined
+            ? { localReviewRefuseAt: existingPolicy.localReviewRefuseAt }
+            : {}),
+        ...(existingPolicy?.localReviewBypassEnvVar !== undefined
+            ? { localReviewBypassEnvVar: existingPolicy.localReviewBypassEnvVar }
+            : {}),
+        ...(existingPolicy?.localReviewMaxAgeSeconds !== undefined
+            ? { localReviewMaxAgeSeconds: existingPolicy.localReviewMaxAgeSeconds }
+            : {}),
+        ...(existingPolicy?.commitHygieneWarnAtCommits !== undefined
+            ? { commitHygieneWarnAtCommits: existingPolicy.commitHygieneWarnAtCommits }
+            : {}),
+        ...(existingPolicy?.commitHygieneRefuseAtCommits !== undefined
+            ? { commitHygieneRefuseAtCommits: existingPolicy.commitHygieneRefuseAtCommits }
+            : {}),
         fromReagent,
         reagentPolicyPath,
         reagentNotices: [],
@@ -259,62 +283,132 @@ async function printCodexInstallAssist() {
  * VALUES are still preserved. Operators who want full reset pass
  * `--force` to bypass the file-existence check entirely.
  */
+/**
+ * Round-30 F3 (structural): read the existing policy via the canonical
+ * YAML parser instead of regex-scraping the raw text.
+ *
+ * Pre-fix the preservation reader used independent line-anchored regexes
+ * (`^\s+mode:`, `^\s+warn_at_commits:`, etc.) that ONLY matched
+ * block-form scalars. The TS loader (and `policy_nested_scalar` in the
+ * bash hooks) accept inline mappings — `local_review: { mode: off }` —
+ * but the regex preservation slipped them through, leaving the values
+ * `undefined` after re-read. The writer then skipped emission, and the
+ * inline block vanished entirely on a `rea init` re-run. Round-trip
+ * lossy across the inline/block divergence.
+ *
+ * Structural fix: parse the YAML once, walk the resulting object tree,
+ * and read each preservation key by dotted path. Inline AND block forms
+ * agree at the parsed layer — the parser folds both into the same
+ * object shape — so this fix closes the inline/block divergence for
+ * EVERY preservation key (the round-29 cross-cutting observation), not
+ * just the 6 round-28 fields.
+ *
+ * Failure modes handled:
+ *   - Policy file missing — returns undefined (caller falls back to
+ *     profile defaults; same behavior as pre-fix).
+ *   - YAML malformed — returns undefined (same as pre-fix; the regex
+ *     reader returned undefined on any thrown read error).
+ *   - YAML parses but is null / not an object — returns an empty
+ *     ExistingPolicyValues (no fields to preserve; profile defaults
+ *     fill in).
+ *   - Individual fields wrong type — silently dropped (permissive
+ *     contract, same as the previous regex reader).
+ */
 function readExistingPolicyForPreservation(targetDir) {
     const policyPath = path.join(targetDir, REA_DIR, POLICY_FILE);
     if (!fs.existsSync(policyPath))
         return undefined;
+    let parsed;
     try {
         const raw = fs.readFileSync(policyPath, 'utf8');
-        const out = {};
-        // Profile (informational; used for stderr advisory).
-        const pm = raw.match(/^profile:\s*['"]?([a-z0-9-]+)['"]?\s*$/m);
-        if (pm)
-            out.profile = pm[1];
-        // Autonomy + ceiling (enum).
-        const am = raw.match(/^autonomy_level:\s*(L[0-3])\s*$/m);
-        const amVal = am?.[1];
-        if (amVal !== undefined && Object.values(AutonomyLevel).includes(amVal)) {
-            out.autonomyLevel = amVal;
-        }
-        const mm = raw.match(/^max_autonomy_level:\s*(L[0-3])\s*$/m);
-        const mmVal = mm?.[1];
-        if (mmVal !== undefined && Object.values(AutonomyLevel).includes(mmVal)) {
-            out.maxAutonomyLevel = mmVal;
-        }
-        // block_ai_attribution.
-        const bm = raw.match(/^block_ai_attribution:\s*(true|false)\s*$/m);
-        if (bm?.[1] !== undefined)
-            out.blockAiAttribution = bm[1] === 'true';
-        // blocked_paths block-sequence — line-by-line scan.
-        const bpStart = raw.match(/^blocked_paths:\s*$/m);
-        if (bpStart) {
-            const after = raw.slice((bpStart.index ?? 0) + bpStart[0].length + 1);
-            const lines = after.split('\n');
-            const collected = [];
-            for (const line of lines) {
-                const m2 = line.match(/^\s*-\s+(?:['"]([^'"]+)['"]|(\S.*?))\s*$/);
-                if (!m2)
-                    break;
-                const v = m2[1] ?? m2[2];
-                if (v !== undefined)
-                    collected.push(v);
-            }
-            if (collected.length > 0)
-                out.blockedPaths = collected;
-        }
-        // notification_channel.
-        const nm = raw.match(/^notification_channel:\s*['"]?([^'"\n]*)['"]?\s*$/m);
-        if (nm?.[1] !== undefined)
-            out.notificationChannel = nm[1];
-        // review.codex_required (under nested `review:` block).
-        const cm = raw.match(/^\s+codex_required:\s*(true|false)\s*$/m);
-        if (cm?.[1] !== undefined)
-            out.codexRequired = cm[1] === 'true';
-        return out;
+        parsed = parseYaml(raw);
     }
     catch {
         return undefined;
     }
+    if (parsed === null || typeof parsed !== 'object') {
+        // Empty / non-mapping document — nothing to preserve, but signal
+        // the caller that the file did exist (pre-fix returned `out` even
+        // for a fully-empty file because every regex missed without
+        // throwing). Returning `{}` matches that pre-fix shape.
+        return {};
+    }
+    const policy = parsed;
+    const out = {};
+    // Top-level scalars.
+    const profile = policy['profile'];
+    if (typeof profile === 'string' && /^[a-z0-9-]+$/.test(profile)) {
+        out.profile = profile;
+    }
+    const autonomyLevel = policy['autonomy_level'];
+    if (typeof autonomyLevel === 'string' &&
+        Object.values(AutonomyLevel).includes(autonomyLevel)) {
+        out.autonomyLevel = autonomyLevel;
+    }
+    const maxAutonomyLevel = policy['max_autonomy_level'];
+    if (typeof maxAutonomyLevel === 'string' &&
+        Object.values(AutonomyLevel).includes(maxAutonomyLevel)) {
+        out.maxAutonomyLevel = maxAutonomyLevel;
+    }
+    const blockAiAttribution = policy['block_ai_attribution'];
+    if (typeof blockAiAttribution === 'boolean')
+        out.blockAiAttribution = blockAiAttribution;
+    // blocked_paths is an array of strings. Pre-fix only preserved a
+    // non-empty list (an explicit `blocked_paths: []` fell through to
+    // profile defaults). Match that contract: skip the assignment when
+    // the parsed value is empty / wrong shape.
+    const blockedPaths = policy['blocked_paths'];
+    if (Array.isArray(blockedPaths)) {
+        const collected = blockedPaths.filter((v) => typeof v === 'string');
+        if (collected.length > 0)
+            out.blockedPaths = collected;
+    }
+    const notificationChannel = policy['notification_channel'];
+    if (typeof notificationChannel === 'string')
+        out.notificationChannel = notificationChannel;
+    // Nested review.* knobs. Inline form `review: { codex_required: true }`
+    // and block form both fold to the same object at the parser layer.
+    const review = policy['review'];
+    if (review !== null && typeof review === 'object') {
+        const r = review;
+        if (typeof r['codex_required'] === 'boolean')
+            out.codexRequired = r['codex_required'];
+        // local_review.* — round-28 F6 + round-30 F3 fields.
+        const localReview = r['local_review'];
+        if (localReview !== null && typeof localReview === 'object') {
+            const lr = localReview;
+            const mode = lr['mode'];
+            if (mode === 'enforced' || mode === 'off')
+                out.localReviewMode = mode;
+            const refuseAt = lr['refuse_at'];
+            if (refuseAt === 'push' || refuseAt === 'commit' || refuseAt === 'both') {
+                out.localReviewRefuseAt = refuseAt;
+            }
+            const bypassEnvVar = lr['bypass_env_var'];
+            if (typeof bypassEnvVar === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(bypassEnvVar)) {
+                out.localReviewBypassEnvVar = bypassEnvVar;
+            }
+            const maxAge = lr['max_age_seconds'];
+            if (typeof maxAge === 'number' && Number.isFinite(maxAge) && maxAge > 0) {
+                out.localReviewMaxAgeSeconds = maxAge;
+            }
+        }
+    }
+    // commit_hygiene.* — top-level (NOT nested under review). Inline form
+    // `commit_hygiene: { warn_at_commits: 3 }` and block form both work.
+    const commitHygiene = policy['commit_hygiene'];
+    if (commitHygiene !== null && typeof commitHygiene === 'object') {
+        const ch = commitHygiene;
+        const warnAt = ch['warn_at_commits'];
+        if (typeof warnAt === 'number' && Number.isFinite(warnAt) && warnAt >= 0) {
+            out.commitHygieneWarnAtCommits = warnAt;
+        }
+        const refuseAt = ch['refuse_at_commits'];
+        if (typeof refuseAt === 'number' && Number.isFinite(refuseAt) && refuseAt >= 0) {
+            out.commitHygieneRefuseAtCommits = refuseAt;
+        }
+    }
+    return out;
 }
 function readExistingInstalledAt(policyPath) {
     try {
@@ -413,6 +507,42 @@ function writePolicyYaml(targetDir, config, layered) {
     // single line, no need to understand the default semantics).
     lines.push(`review:`);
     lines.push(`  codex_required: ${config.codexRequired ? 'true' : 'false'}`);
+    // Round-27 F6: emit `review.local_review` and top-level
+    // `commit_hygiene` blocks ONLY when the operator (or the prior on-disk
+    // policy) set them. Pre-fix re-running `rea init` silently dropped any
+    // 0.26.0 knobs the operator had configured — `mode: off` reverted to
+    // the documented `enforced` default, etc. We deliberately do NOT emit
+    // a block when nothing was set, so consumers reading `policy.yaml` see
+    // a clean file that documents only the operator's explicit choices.
+    const hasLocalReview = config.localReviewMode !== undefined ||
+        config.localReviewRefuseAt !== undefined ||
+        config.localReviewBypassEnvVar !== undefined ||
+        config.localReviewMaxAgeSeconds !== undefined;
+    if (hasLocalReview) {
+        lines.push(`  local_review:`);
+        if (config.localReviewMode !== undefined) {
+            lines.push(`    mode: ${config.localReviewMode}`);
+        }
+        if (config.localReviewRefuseAt !== undefined) {
+            lines.push(`    refuse_at: ${config.localReviewRefuseAt}`);
+        }
+        if (config.localReviewBypassEnvVar !== undefined) {
+            lines.push(`    bypass_env_var: ${JSON.stringify(config.localReviewBypassEnvVar)}`);
+        }
+        if (config.localReviewMaxAgeSeconds !== undefined) {
+            lines.push(`    max_age_seconds: ${config.localReviewMaxAgeSeconds}`);
+        }
+    }
+    if (config.commitHygieneWarnAtCommits !== undefined ||
+        config.commitHygieneRefuseAtCommits !== undefined) {
+        lines.push(`commit_hygiene:`);
+        if (config.commitHygieneWarnAtCommits !== undefined) {
+            lines.push(`  warn_at_commits: ${config.commitHygieneWarnAtCommits}`);
+        }
+        if (config.commitHygieneRefuseAtCommits !== undefined) {
+            lines.push(`  refuse_at_commits: ${config.commitHygieneRefuseAtCommits}`);
+        }
+    }
     lines.push(``);
     fs.writeFileSync(policyPath, lines.join('\n'), 'utf8');
     return policyPath;
@@ -590,6 +720,27 @@ export async function runInit(options) {
             blockedPaths: existingPolicy?.blockedPaths ?? layeredBase.blocked_paths ?? ['.env', '.env.*'],
             notificationChannel: existingPolicy?.notificationChannel ?? layeredBase.notification_channel ?? '',
             codexRequired,
+            // Round-27 F6: forward the existing 0.26.0 knobs verbatim. Any field
+            // not set on disk stays undefined, and the writer omits it from the
+            // emitted YAML.
+            ...(existingPolicy?.localReviewMode !== undefined
+                ? { localReviewMode: existingPolicy.localReviewMode }
+                : {}),
+            ...(existingPolicy?.localReviewRefuseAt !== undefined
+                ? { localReviewRefuseAt: existingPolicy.localReviewRefuseAt }
+                : {}),
+            ...(existingPolicy?.localReviewBypassEnvVar !== undefined
+                ? { localReviewBypassEnvVar: existingPolicy.localReviewBypassEnvVar }
+                : {}),
+            ...(existingPolicy?.localReviewMaxAgeSeconds !== undefined
+                ? { localReviewMaxAgeSeconds: existingPolicy.localReviewMaxAgeSeconds }
+                : {}),
+            ...(existingPolicy?.commitHygieneWarnAtCommits !== undefined
+                ? { commitHygieneWarnAtCommits: existingPolicy.commitHygieneWarnAtCommits }
+                : {}),
+            ...(existingPolicy?.commitHygieneRefuseAtCommits !== undefined
+                ? { commitHygieneRefuseAtCommits: existingPolicy.commitHygieneRefuseAtCommits }
+                : {}),
             fromReagent,
             reagentPolicyPath,
             reagentNotices,

package/dist/cli/install/pre-push.d.ts

@@ -53,6 +53,12 @@
  * classification. Bump the version suffix whenever the body semantics
  * change so upgrades can migrate old installs cleanly.
  *
+ * v5 — 0.26.0 local-first enforcement: body runs `rea preflight --strict`
+ *      BEFORE the push-gate dispatch. `rea preflight` refuses the push
+ *      when no recent `rea.local_review` audit entry covers HEAD; the
+ *      legacy push-gate then runs as the second layer (codex on push).
+ *      Honors `policy.review.local_review.mode: off` and
+ *      `REA_SKIP_LOCAL_REVIEW=<reason>` for opt-out / per-push override.
  * v4 — 0.13.0 extension-hook chaining: rea body sources `.husky/pre-push.d/*`
  *      fragments after its own work and before the final `exec`, in lex
  *      order. Non-zero fragment exit fails the hook.
@@ -62,7 +68,9 @@
  * v2 — 0.11.0 stateless push-gate body (no bash core, no audit grep).
  * v1 — 0.10.x and prior, delegated to `.claude/hooks/push-review-gate.sh`.
  */
-export declare const FALLBACK_MARKER = "# rea:pre-push-fallback v4";
+export declare const FALLBACK_MARKER = "# rea:pre-push-fallback v5";
+/** Legacy v4 marker (0.13.x – 0.25.x bodies). Refresh-on-upgrade. */
+export declare const LEGACY_FALLBACK_MARKER_V4 = "# rea:pre-push-fallback v4";
 /** Legacy v3 marker (0.12.x bodies). Refresh-on-upgrade. */
 export declare const LEGACY_FALLBACK_MARKER_V3 = "# rea:pre-push-fallback v3";
 /** Legacy v2 marker (0.11.x bodies). Refresh-on-upgrade. */
@@ -75,7 +83,9 @@ export declare const LEGACY_FALLBACK_MARKER_V1 = "# rea:pre-push-fallback v1";
  * detects it to refresh in-place. Bump the suffix whenever the body
  * changes; pre-0.13 markers live in `LEGACY_HUSKY_GATE_MARKER_V{1,2,3}`.
  */
-export declare const HUSKY_GATE_MARKER = "# rea:husky-pre-push-gate v4";
+export declare const HUSKY_GATE_MARKER = "# rea:husky-pre-push-gate v5";
+/** Legacy v4 husky marker (0.13.x – 0.25.x bodies). Refresh-on-upgrade. */
+export declare const LEGACY_HUSKY_GATE_MARKER_V4 = "# rea:husky-pre-push-gate v4";
 /** Legacy v3 husky marker (0.12.x bodies). Refresh-on-upgrade. */
 export declare const LEGACY_HUSKY_GATE_MARKER_V3 = "# rea:husky-pre-push-gate v3";
 /** Legacy v2 husky marker (0.11.x bodies). Refresh-on-upgrade. */
@@ -87,7 +97,9 @@ export declare const LEGACY_HUSKY_GATE_MARKER_V1 = "# rea:husky-pre-push-gate v1
  * empty body (stubbed out by a consumer) is NOT classified as rea-managed.
  * A real rea hook always carries both markers.
  */
-export declare const HUSKY_GATE_BODY_MARKER = "# rea:gate-body-v4";
+export declare const HUSKY_GATE_BODY_MARKER = "# rea:gate-body-v5";
+/** Legacy v4 body marker (0.13.x – 0.25.x bodies). Refresh-on-upgrade. */
+export declare const LEGACY_HUSKY_GATE_BODY_MARKER_V4 = "# rea:gate-body-v4";
 /** Legacy v3 body marker (0.12.x bodies). Refresh-on-upgrade. */
 export declare const LEGACY_HUSKY_GATE_BODY_MARKER_V3 = "# rea:gate-body-v3";
 /** Legacy v2 body marker (0.11.x bodies). Refresh-on-upgrade. */

package/dist/cli/install/pre-push.js

@@ -65,6 +65,12 @@ const execFileAsync = promisify(execFile);
  * classification. Bump the version suffix whenever the body semantics
  * change so upgrades can migrate old installs cleanly.
  *
+ * v5 — 0.26.0 local-first enforcement: body runs `rea preflight --strict`
+ *      BEFORE the push-gate dispatch. `rea preflight` refuses the push
+ *      when no recent `rea.local_review` audit entry covers HEAD; the
+ *      legacy push-gate then runs as the second layer (codex on push).
+ *      Honors `policy.review.local_review.mode: off` and
+ *      `REA_SKIP_LOCAL_REVIEW=<reason>` for opt-out / per-push override.
  * v4 — 0.13.0 extension-hook chaining: rea body sources `.husky/pre-push.d/*`
  *      fragments after its own work and before the final `exec`, in lex
  *      order. Non-zero fragment exit fails the hook.
@@ -74,9 +80,14 @@ const execFileAsync = promisify(execFile);
  * v2 — 0.11.0 stateless push-gate body (no bash core, no audit grep).
  * v1 — 0.10.x and prior, delegated to `.claude/hooks/push-review-gate.sh`.
  */
-export const FALLBACK_MARKER = '# rea:pre-push-fallback v4';
+export const FALLBACK_MARKER = '# rea:pre-push-fallback v5';
+/** Legacy v4 marker (0.13.x – 0.25.x bodies). Refresh-on-upgrade. */
+export const LEGACY_FALLBACK_MARKER_V4 = '# rea:pre-push-fallback v4';
 /** Legacy v3 marker (0.12.x bodies). Refresh-on-upgrade. */
 export const LEGACY_FALLBACK_MARKER_V3 = '# rea:pre-push-fallback v3';
+// Legacy v4 marker is declared above next to the v5 (current) marker so
+// the canonical/current pair sits together. Keep this comment as an
+// anchor — `LEGACY_FALLBACK_MARKER_V4` is exported above.
 /** Legacy v2 marker (0.11.x bodies). Refresh-on-upgrade. */
 export const LEGACY_FALLBACK_MARKER_V2 = '# rea:pre-push-fallback v2';
 /** Legacy v1 marker — used by upgrade migration to detect old installs. */
@@ -87,7 +98,9 @@ export const LEGACY_FALLBACK_MARKER_V1 = '# rea:pre-push-fallback v1';
  * detects it to refresh in-place. Bump the suffix whenever the body
  * changes; pre-0.13 markers live in `LEGACY_HUSKY_GATE_MARKER_V{1,2,3}`.
  */
-export const HUSKY_GATE_MARKER = '# rea:husky-pre-push-gate v4';
+export const HUSKY_GATE_MARKER = '# rea:husky-pre-push-gate v5';
+/** Legacy v4 husky marker (0.13.x – 0.25.x bodies). Refresh-on-upgrade. */
+export const LEGACY_HUSKY_GATE_MARKER_V4 = '# rea:husky-pre-push-gate v4';
 /** Legacy v3 husky marker (0.12.x bodies). Refresh-on-upgrade. */
 export const LEGACY_HUSKY_GATE_MARKER_V3 = '# rea:husky-pre-push-gate v3';
 /** Legacy v2 husky marker (0.11.x bodies). Refresh-on-upgrade. */
@@ -99,7 +112,9 @@ export const LEGACY_HUSKY_GATE_MARKER_V1 = '# rea:husky-pre-push-gate v1';
  * empty body (stubbed out by a consumer) is NOT classified as rea-managed.
  * A real rea hook always carries both markers.
  */
-export const HUSKY_GATE_BODY_MARKER = '# rea:gate-body-v4';
+export const HUSKY_GATE_BODY_MARKER = '# rea:gate-body-v5';
+/** Legacy v4 body marker (0.13.x – 0.25.x bodies). Refresh-on-upgrade. */
+export const LEGACY_HUSKY_GATE_BODY_MARKER_V4 = '# rea:gate-body-v4';
 /** Legacy v3 body marker (0.12.x bodies). Refresh-on-upgrade. */
 export const LEGACY_HUSKY_GATE_BODY_MARKER_V3 = '# rea:gate-body-v3';
 /** Legacy v2 body marker (0.11.x bodies). Refresh-on-upgrade. */
@@ -161,6 +176,37 @@ fi
 # the subshell sees those as its initial \$@, appends them inside each
 # \`set --\` arm, and the parent's \$@ is preserved.
 
+# 0.26.0 local-first enforcement (CTO directive 2026-05-05). Run
+# \`rea preflight --strict\` BEFORE the push-gate dispatch. Preflight
+# refuses (exit 2) when no recent \`rea.local_review\` audit entry
+# covers HEAD, when commit-hygiene thresholds are exceeded, or when
+# the kill-switch is active. The legacy push-gate then runs as the
+# SECOND layer (codex on the diff). Honors:
+#   - policy.review.local_review.mode: off  → preflight is no-op
+#   - REA_SKIP_LOCAL_REVIEW="<reason>"      → bypass + audit
+# We resolve the rea binary the same way the dispatch below does.
+if (
+  if [ -x "\${REA_ROOT}/node_modules/.bin/rea" ]; then
+    "\${REA_ROOT}/node_modules/.bin/rea" preflight --strict
+  elif [ -f "\${REA_ROOT}/dist/cli/index.js" ] && [ -f "\${REA_ROOT}/package.json" ] && grep -q '"name": *"@bookedsolid/rea"' "\${REA_ROOT}/package.json" 2>/dev/null; then
+    node "\${REA_ROOT}/dist/cli/index.js" preflight --strict
+  elif command -v rea >/dev/null 2>&1; then
+    rea preflight --strict
+  elif command -v npx >/dev/null 2>&1; then
+    npx --no-install @bookedsolid/rea preflight --strict
+  else
+    printf 'rea: cannot locate the rea CLI for preflight. Install locally (\`pnpm add -D @bookedsolid/rea\`) or set policy.review.local_review.mode=off.\\n' >&2
+    exit 2
+  fi
+); then
+  preflight_status=0
+else
+  preflight_status=\$?
+fi
+if [ "\$preflight_status" -ne 0 ]; then
+  exit "\$preflight_status"
+fi
+
 if (
   if [ -x "\${REA_ROOT}/node_modules/.bin/rea" ]; then
     set -- "\${REA_ROOT}/node_modules/.bin/rea" hook push-gate "\$@"
@@ -290,7 +336,8 @@ export function isLegacyReaManagedFallback(content) {
     if (secondLineEnd < 0)
         return false;
     const secondLine = content.slice(10, secondLineEnd);
-    return (secondLine === LEGACY_FALLBACK_MARKER_V3 ||
+    return (secondLine === LEGACY_FALLBACK_MARKER_V4 ||
+        secondLine === LEGACY_FALLBACK_MARKER_V3 ||
         secondLine === LEGACY_FALLBACK_MARKER_V2 ||
         secondLine === LEGACY_FALLBACK_MARKER_V1);
 }
@@ -315,7 +362,8 @@ export function isReaManagedHuskyGate(content) {
  * upgrade migration.
  */
 export function isLegacyReaManagedHuskyGate(content) {
-    return (hasHeaderMarkers(content, LEGACY_HUSKY_GATE_MARKER_V3, LEGACY_HUSKY_GATE_BODY_MARKER_V3) ||
+    return (hasHeaderMarkers(content, LEGACY_HUSKY_GATE_MARKER_V4, LEGACY_HUSKY_GATE_BODY_MARKER_V4) ||
+        hasHeaderMarkers(content, LEGACY_HUSKY_GATE_MARKER_V3, LEGACY_HUSKY_GATE_BODY_MARKER_V3) ||
         hasHeaderMarkers(content, LEGACY_HUSKY_GATE_MARKER_V2, LEGACY_HUSKY_GATE_BODY_MARKER_V2) ||
         hasHeaderMarkers(content, LEGACY_HUSKY_GATE_MARKER_V1, LEGACY_HUSKY_GATE_BODY_MARKER_V1));
 }
@@ -677,6 +725,8 @@ async function cleanupStaleTempFiles(dst) {
             return;
         if (!body.includes(FALLBACK_MARKER) &&
             !body.includes(HUSKY_GATE_MARKER) &&
+            !body.includes(LEGACY_FALLBACK_MARKER_V4) &&
+            !body.includes(LEGACY_HUSKY_GATE_MARKER_V4) &&
             !body.includes(LEGACY_FALLBACK_MARKER_V3) &&
             !body.includes(LEGACY_HUSKY_GATE_MARKER_V3) &&
             !body.includes(LEGACY_FALLBACK_MARKER_V2) &&

package/dist/cli/install/settings-merge.js

@@ -303,6 +303,19 @@ export function defaultDesiredHooks() {
                     timeout: 5000,
                     statusMessage: 'Checking for AI attribution...',
                 },
+                // 0.26.0 local-first enforcement (CTO directive 2026-05-05). The
+                // Bash-tier gate refuses `git push` (and optionally `git commit`)
+                // when no recent `rea.local_review` audit entry covers HEAD. Honors
+                // `policy.review.local_review.mode: off` for teams without
+                // codex/claude installed and `REA_SKIP_LOCAL_REVIEW=<reason>` for
+                // per-invocation overrides. 60s timeout because the gate may
+                // shell out to `rea preflight` which itself loads policy.
+                {
+                    type: 'command',
+                    command: `${base}/local-review-gate.sh`,
+                    timeout: 60000,
+                    statusMessage: 'Checking local-first review status...',
+                },
             ],
         },
         {