@bookedsolid/rea 0.24.0 → 0.26.0

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...',
+                },
             ],
         },
         {

package/dist/cli/preflight.d.ts

@@ -0,0 +1,120 @@
+/**
+ * `rea preflight` — local-first enforcement workhorse (0.26.0+).
+ *
+ * Called by:
+ *   - The husky pre-push template (`exec rea preflight --strict`)
+ *   - The Bash-tier `local-review-gate.sh` PreToolUse hook
+ *   - Operators directly (`rea preflight` to check status)
+ *
+ * Decision flow:
+ *
+ *   1. `policy.review.local_review.mode === 'off'` → exit 0 (no-op)
+ *   2. `<bypass_env_var>` is set (default REA_SKIP_LOCAL_REVIEW) → audit
+ *      `rea.local_review.skipped_override` with the reason; exit 0
+ *   3. `--no-review-check` flag → audit `rea.preflight.review_skipped`;
+ *      proceed to commit-count check only
+ *   4. Tail `.rea/audit.jsonl` for a `rea.local_review` (or back-compat
+ *      `codex.review`) entry with `metadata.head_sha === <git HEAD>`
+ *      AND `now - timestamp < max_age_seconds`. Found → exit 0.
+ *      Missing → exit 2 with helpful message.
+ *   5. Commit-count check (independent of step 4):
+ *        `git rev-list --count <base>..HEAD` against thresholds
+ *        from `policy.commit_hygiene`.
+ *
+ * Exit codes:
+ *
+ *   0 — clean (mode=off, recent review found, or override set)
+ *   1 — warn (commit count > warn_at_commits but ≤ refuse_at_commits)
+ *   2 — refuse (no recent review covering HEAD, OR commit count >
+ *       refuse_at_commits, OR --strict elevated a warn to refuse)
+ */
+import type { Command } from 'commander';
+import { type Policy } from '../policy/types.js';
+/** Default max age for a local-review audit entry (24h). */
+export declare const DEFAULT_MAX_AGE_SECONDS = 86400;
+/** Default bypass env-var name. */
+export declare const DEFAULT_BYPASS_ENV_VAR = "REA_SKIP_LOCAL_REVIEW";
+/** Default commit-hygiene thresholds. */
+export declare const DEFAULT_WARN_AT_COMMITS = 1;
+export declare const DEFAULT_REFUSE_AT_COMMITS = 5;
+export interface RunPreflightOptions {
+    /**
+     * Treat warn-tier commit-hygiene findings as refusals. Husky pre-push
+     * always sets this — a warn that doesn't refuse is a useless warning
+     * at the terminal layer.
+     */
+    strict?: boolean;
+    /**
+     * Skip the audit-log check. The commit-count check still runs. Used
+     * by operators who explicitly want to defer review (audit-logged so
+     * the deferral is forensically visible).
+     */
+    noReviewCheck?: boolean;
+    /** Emit a single JSON line on stdout instead of pretty output. */
+    json?: boolean;
+}
+interface PreflightOutcome {
+    status: 'clean' | 'warn' | 'refuse';
+    reason: string;
+    exitCode: 0 | 1 | 2;
+    details: Record<string, unknown>;
+}
+/**
+ * Run preflight in-process. Tests drive this directly. The CLI binding
+ * exits via `process.exit` at the end of `runPreflight()`.
+ */
+export declare function computePreflight(baseDir: string, options: RunPreflightOptions, env?: NodeJS.ProcessEnv): Promise<{
+    outcome: PreflightOutcome;
+    policy: Policy | undefined;
+}>;
+export declare function runPreflight(options: RunPreflightOptions): Promise<void>;
+/**
+ * Tail `.rea/audit.jsonl` for the most recent matching local-review
+ * entry. We accept BOTH `rea.local_review` (canonical) and
+ * `codex.review` (back-compat from pre-0.26.0 audit data) so existing
+ * users with prior reviews don't have to re-review on upgrade.
+ *
+ * Streaming approach: read the whole file (audit logs are typically
+ * < 10 MB even after months of use) and walk lines from the end. The
+ * audit log is append-only and timestamps are monotonic per writer.
+ *
+ * # Coverage matching (0.26.0 helix-026 finding-1)
+ *
+ * The first valid `metadata.content_token` on each record wins:
+ *
+ *   1. Record has `content_token` AND caller supplied `contentToken` →
+ *      exact-string match. Stable across `--amend` / fixup rebases.
+ *   2. Record has NO `content_token` (legacy `codex.review` entry, or
+ *      a future provider that can't compute one) → fall back to
+ *      exact-string `head_sha` match. Pre-0.26.0 reviews still cover.
+ *   3. Record has `content_token` but caller's `contentToken` is empty
+ *      (preflight on a non-git directory or detached state) → fall back
+ *      to `head_sha` match. The content path is the additive layer; the
+ *      head-sha layer remains as the floor.
+ *
+ * Hierarchy invariant: an entry is valid coverage when EITHER the token
+ * matches OR the head_sha matches. The two are not AND-ed — that would
+ * make legacy entries un-matchable and would break the local-first loop
+ * back to the old "commit first, then review" inversion.
+ */
+export interface LocalReviewLookupResult {
+    found: boolean;
+    /** Audit-record metadata payload, when found. */
+    metadata?: Record<string, unknown>;
+    /** ISO timestamp on the matching record. */
+    timestamp?: string;
+    /** Tool name that matched (canonical or legacy). */
+    tool_name?: string;
+    /**
+     * Which match-path validated this entry. Useful for tests and for the
+     * `--json` outcome: `'content_token'` (preferred), `'head_sha'`
+     * (back-compat / fallback).
+     */
+    match_kind?: 'content_token' | 'head_sha';
+}
+export declare function findRecentLocalReview(baseDir: string, headSha: string, maxAgeSeconds: number, now?: Date, contentToken?: string): LocalReviewLookupResult;
+/**
+ * Attach `rea preflight` to a commander Program.
+ */
+export declare function registerPreflightCommand(program: Command): void;
+export {};