@bookedsolid/rea 0.25.0 → 0.26.0

package/README.md

@@ -748,8 +748,8 @@ install so teams without a Codex bench get a first-class opt-out. Flip
 
 ## Hooks shipped
 
-Eleven hooks ship in `hooks/` and are copied into `.claude/hooks/` by
-`rea init`. All eleven are wired by default in the shipped
+Fourteen hooks ship in `hooks/` and are copied into `.claude/hooks/` by
+`rea init`. All fourteen are wired by default in the shipped
 `.claude/settings.json`.
 
 | Hook | Event | Purpose | Default |
@@ -760,11 +760,14 @@ Eleven hooks ship in `hooks/` and are copied into `.claude/hooks/` by
 | `security-disclosure-gate.sh` | `PreToolUse: Bash` | Route security-keyword `gh issue create` to private disclosure | Registered |
 | `pr-issue-link-gate.sh` | `PreToolUse: Bash` | Advisory warn when `gh pr create` has no linked issue | Registered |
 | `attribution-advisory.sh` | `PreToolUse: Bash` | Block commits/PRs containing AI attribution markers | Registered |
-| `secret-scanner.sh` | `PreToolUse: Write\|Edit` | Scan file writes for credential patterns | Registered |
-| `settings-protection.sh` | `PreToolUse: Write\|Edit` | Block agent writes to `.claude/settings.json`, hook dirs, policy | Registered |
-| `blocked-paths-enforcer.sh` | `PreToolUse: Write\|Edit` | Enforce `blocked_paths` from policy | Registered |
-| `changeset-security-gate.sh` | `PreToolUse: Write\|Edit` | Guard changesets against GHSA leaks and malformed frontmatter | Registered |
-| `architecture-review-gate.sh` | `PostToolUse: Write\|Edit` | Flag edits crossing architectural boundaries (advisory) | Registered |
+| `protected-paths-bash-gate.sh` | `PreToolUse: Bash` | Bash-tier parity with `settings-protection.sh` — refuses shell writes to `.claude/`/`.husky/`/policy paths (0.21.0+) | Registered |
+| `blocked-paths-bash-gate.sh` | `PreToolUse: Bash` | Bash-tier parity with `blocked-paths-enforcer.sh` — refuses shell writes to `blocked_paths` policy entries (0.22.0+) | Registered |
+| `local-review-gate.sh` | `PreToolUse: Bash` | Refuse `git push` (and optionally `git commit`) until a recent `rea.local_review` audit entry covers HEAD (0.26.0+) | Registered |
+| `secret-scanner.sh` | `PreToolUse: Write\|Edit\|MultiEdit\|NotebookEdit` | Scan file writes for credential patterns | Registered |
+| `settings-protection.sh` | `PreToolUse: Write\|Edit\|MultiEdit\|NotebookEdit` | Block agent writes to `.claude/settings.json`, hook dirs, policy | Registered |
+| `blocked-paths-enforcer.sh` | `PreToolUse: Write\|Edit\|MultiEdit\|NotebookEdit` | Enforce `blocked_paths` from policy | Registered |
+| `changeset-security-gate.sh` | `PreToolUse: Write\|Edit\|MultiEdit\|NotebookEdit` | Guard changesets against GHSA leaks and malformed frontmatter | Registered |
+| `architecture-review-gate.sh` | `PostToolUse: Write\|Edit\|MultiEdit\|NotebookEdit` | Flag edits crossing architectural boundaries (advisory) | Registered |
 
 The 0.10.x review-gate scripts (`push-review-gate.sh`,
 `push-review-gate-git.sh`, `commit-review-gate.sh`) and the 1,250-line

package/agents/codex-adversarial.md

@@ -5,8 +5,12 @@ description: Adversarial code review via the Codex plugin (GPT-5.4). Independent
 
 # Codex Adversarial Reviewer
 
+Run on the working tree before commit. Never let the push-gate be the first time codex sees the diff. Write the audit entry via `rea review` so the preflight gate accepts the push.
+
 You wrap the Codex plugin (`/codex:adversarial-review`) inside REA's governance envelope. Your role is to provide an **independent** adversarial perspective on code that was planned and built by another model — typically Opus. Independence is the value: the authoring model is least likely to catch the mistakes it made.
 
+As of 0.26.0 (CTO directive 2026-05-05) this review is a forceful step — the Bash-tier `local-review-gate.sh` hook + husky pre-push refuse `git push` when no recent `rea.local_review` audit entry covers HEAD. The cleanest gate-friendly invocation is `rea review`, which runs codex on the working tree and writes the canonical audit entry. The interactive `/codex-review` form is still useful for structured exploratory feedback, but it does NOT write the audit entry the gate looks for.
+
 This is not a bolt-on. Adversarial review is a first-class, non-optional step in the REA engineering process. The default workflow is Plan → Build → Review, and you are the Review leg.
 
 ## When You Are Invoked

package/agents/rea-orchestrator.md

@@ -14,6 +14,15 @@ You are the REA orchestrator. Your role is to enforce the project's governance c
 3. Verify the requested task falls within the current autonomy level
 4. If the task exceeds autonomy, escalate to the user — do not attempt workarounds
 
+## Before Dispatching Commit / Push
+
+The local-first guardrail (CTO directive 2026-05-05) is forceful as of 0.26.0. Before delegating any commit-or-push step:
+
+1. Ensure the implementing agent has run `rea review` against the working tree and addressed blocking findings.
+2. The agent's `git push` will be refused at the Bash-tier `local-review-gate.sh` hook unless a recent `rea.local_review` audit entry covers HEAD. Plan for review BEFORE commit, not after.
+3. If the consumer team has set `policy.review.local_review.mode: off`, the gate is a no-op — proceed normally. Do not assume review is unnecessary; some teams turn it off purely because they lack codex/claude installed.
+4. The push-gate is a BACKUP layer, not the primary review surface. Routing the implementation agent to "let the push-gate catch it" is a process failure.
+
 ## Autonomy Levels
 
 - **L0** — Read-only. Every write requires explicit user approval. Ask before any file change.

package/commands/codex-review.md

@@ -14,6 +14,10 @@ allowed-tools:
 
 Invokes the Codex plugin (`/codex:adversarial-review`) on the current branch's diff, captures the result, and records it to the REA audit log. Adversarial review by an independent model (GPT-5.4) is a **first-class, non-optional step** in the REA engineering process — it is the counterweight to Opus-authored code.
 
+## When to run
+
+**Default: working tree before commit.** As of 0.26.0 (CTO directive 2026-05-05) the local-first guardrail is forceful — the Bash-tier `local-review-gate.sh` + husky pre-push refuse `git push` when no recent `rea.local_review` audit entry covers HEAD. Running `/codex-review` produces structured exploratory feedback but does NOT write the audit entry the gate looks for. For the gate-friendly form, use `rea review` from a Bash invocation — it runs codex on the working tree AND writes the canonical audit entry. `/codex-review` remains the interactive surface; `rea review` is the gate-aligned automation.
+
 ## Why this exists
 
 The default workflow in REA is Plan → Build → Review, with the Review leg handed to a different model than the one that wrote the code. Codex adversarial review is free, fast, and independent — it catches the mistakes the authoring model is most likely to miss: security assumptions, correctness under edge cases, and logical gaps in tests. Treat it with the same weight as a human second set of eyes.

package/dist/audit/append.d.ts

@@ -82,3 +82,4 @@ export declare function appendAuditRecord(baseDir: string, input: AppendAuditInp
 export type { AuditRecord, EmissionSource } from '../gateway/middleware/audit-types.js';
 export { Tier, InvocationStatus } from '../policy/types.js';
 export { CODEX_REVIEW_TOOL_NAME, CODEX_REVIEW_SERVER_NAME, type CodexVerdict, type CodexReviewMetadata, } from './codex-event.js';
+export { LOCAL_REVIEW_TOOL_NAME, LOCAL_REVIEW_SKIPPED_OVERRIDE_TOOL_NAME, LOCAL_REVIEW_SKIPPED_UNAVAILABLE_TOOL_NAME, LOCAL_REVIEW_PREFLIGHT_SKIPPED_TOOL_NAME, LOCAL_REVIEW_SERVER_NAME, type LocalReviewVerdict, type LocalReviewMetadata, type LocalReviewSkippedOverrideMetadata, type LocalReviewSkippedUnavailableMetadata, } from './local-review-event.js';

package/dist/audit/append.js

@@ -203,3 +203,4 @@ export async function appendAuditRecord(baseDir, input) {
 }
 export { Tier, InvocationStatus } from '../policy/types.js';
 export { CODEX_REVIEW_TOOL_NAME, CODEX_REVIEW_SERVER_NAME, } from './codex-event.js';
+export { LOCAL_REVIEW_TOOL_NAME, LOCAL_REVIEW_SKIPPED_OVERRIDE_TOOL_NAME, LOCAL_REVIEW_SKIPPED_UNAVAILABLE_TOOL_NAME, LOCAL_REVIEW_PREFLIGHT_SKIPPED_TOOL_NAME, LOCAL_REVIEW_SERVER_NAME, } from './local-review-event.js';

package/dist/audit/content-token.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Content-token computation for the local-first review audit trail.
+ *
+ * 0.26.0 P1 fix (helix-026, codex finding 1): `rea preflight` originally
+ * keyed reviews to `git rev-parse HEAD`. The local-first flow is
+ * "working tree → review → fix → commit → push" — by design the COMMIT
+ * happens AFTER the review, so HEAD changes between them. Matching by
+ * `head_sha` guaranteed a stale lookup and broke the advertised loop.
+ *
+ * The fix is to record a token tied to the CONTENT codex actually
+ * reviewed instead of the commit it sat on top of.
+ *
+ * 0.26.0 round-25 P1-A fix: codex `exec review` diffs the WORKING TREE
+ * against base — meaning the token must reflect the working tree (with
+ * any uncommitted edits), NOT `HEAD^{tree}`. Pre-fix the token was
+ * computed via `git rev-parse HEAD^{tree}` — the LAST COMMIT's tree,
+ * not the working-tree state codex actually reviewed. The documented
+ * happy path is `edit → review → fix → commit → push`; after commit
+ * HEAD changes, preflight's token doesn't match the audit entry's
+ * token, and the gate REFUSES the very flow it documents.
+ *
+ * Fix: compute the WORKING-TREE token via `git stash create`. That
+ * command returns the SHA of a commit object whose tree is the
+ * working-tree + index merged. `git rev-parse <stash-sha>^{tree}` then
+ * gives a deterministic fingerprint of what codex actually reviewed:
+ *
+ *   - At review time: working tree dirty → token = Tw (working-tree tree).
+ *   - Operator commits: HEAD becomes B with tree Tb. Tb == Tw because
+ *     `git commit` just persists the index, not new content.
+ *   - Push time: working tree CLEAN, `git stash create` returns empty,
+ *     fall back to `HEAD^{tree}` = Tb == Tw. Match. Allow.
+ *
+ * Stable behaviors preserved from the 0.26.0 finding-1 fix:
+ *   - Stable across `git commit --amend` with no content change
+ *   - Stable across rebases that don't touch content (fixup, reword)
+ *   - Differs immediately on any real content edit
+ *
+ * NOTE: untracked AND `.gitignore`'d content is by design NOT part of
+ * the token, because:
+ *   - `git stash create` does not include untracked files (without `-u`,
+ *     and even `-u` excludes ignored files).
+ *   - `git push` cannot transmit them either.
+ * So the token reflects what would actually be pushed. Codex review
+ * follows the same `git diff` semantics.
+ *
+ * The audit record continues to record `head_sha` for forensics —
+ * `content_token` is what `rea preflight` matches on. Legacy
+ * `codex.review` audit entries (pre-0.26.0) only have `head_sha`;
+ * preflight falls back to head-sha matching for those.
+ */
+/**
+ * Git's well-known "empty tree" object SHA — the SHA-1 of an empty tree
+ * object, identical across every git repository on Earth.
+ *
+ * Round-27 F2 fix: this constant exists so the unborn-HEAD bootstrap path
+ * is symmetric between writer (`rea review` audit-record `head_sha`) and
+ * reader (`rea preflight` HEAD probe). Pre-fix:
+ *
+ *   - `rea review` (writer) used `EMPTY_TREE_SHA` as the synthetic head
+ *     when HEAD couldn't be resolved (round-25 P2-B).
+ *   - `rea preflight` (reader) returned `''` for headSha AND empty
+ *     contentToken on unborn HEAD, then refused with a both-empty guard.
+ *
+ * The asymmetry deadlocked the bootstrap flow `git init` →
+ * `rea review` → `rea preflight` under `refuse_at: both`. Both sides
+ * now reference THIS constant when HEAD cannot be resolved, so the
+ * head_sha-fallback path in `findRecentLocalReview` matches uniformly.
+ */
+export declare const EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+/**
+ * Compute a deterministic content token for the working tree.
+ *
+ * Returns `''` (empty string) when the tree token cannot be resolved
+ * (no git repo, no HEAD, etc.). Callers MUST treat empty token as
+ * "no token" — the audit record's `content_token` field should be
+ * omitted in that case so `rea preflight` does not match a missing
+ * token against a missing token (which would be a trivial bypass).
+ *
+ * The token is the SHA of the working-tree tree object (or HEAD's
+ * tree object if the working tree is clean). Format: 40-char lowercase
+ * hex (or 64-char if the repo uses SHA-256). The function does not
+ * normalize or truncate — `rea preflight` does an exact-string match.
+ *
+ * Resolution order (round-25 P1-A):
+ *   1. `git stash create` — non-empty stdout means there are tracked
+ *      changes. The stash SHA is a commit object; its tree is the
+ *      working-tree + index merged. Use `<sha>^{tree}` as treeSource.
+ *      `git stash create` does NOT modify the stash list, working tree,
+ *      or index — it only synthesizes a commit object pointing at the
+ *      current state.
+ *   2. Empty stdout from `git stash create` (or non-zero exit) → tree
+ *      is clean OR repo is empty. Fall back to `HEAD^{tree}`. A clean
+ *      working tree's tree object is identical to HEAD's tree by
+ *      definition.
+ *   3. Both fail → return empty string. `head_sha` fallback in
+ *      preflight takes over.
+ */
+export declare function computeTreeToken(cwd: string): string;

package/dist/audit/content-token.js

@@ -0,0 +1,136 @@
+/**
+ * Content-token computation for the local-first review audit trail.
+ *
+ * 0.26.0 P1 fix (helix-026, codex finding 1): `rea preflight` originally
+ * keyed reviews to `git rev-parse HEAD`. The local-first flow is
+ * "working tree → review → fix → commit → push" — by design the COMMIT
+ * happens AFTER the review, so HEAD changes between them. Matching by
+ * `head_sha` guaranteed a stale lookup and broke the advertised loop.
+ *
+ * The fix is to record a token tied to the CONTENT codex actually
+ * reviewed instead of the commit it sat on top of.
+ *
+ * 0.26.0 round-25 P1-A fix: codex `exec review` diffs the WORKING TREE
+ * against base — meaning the token must reflect the working tree (with
+ * any uncommitted edits), NOT `HEAD^{tree}`. Pre-fix the token was
+ * computed via `git rev-parse HEAD^{tree}` — the LAST COMMIT's tree,
+ * not the working-tree state codex actually reviewed. The documented
+ * happy path is `edit → review → fix → commit → push`; after commit
+ * HEAD changes, preflight's token doesn't match the audit entry's
+ * token, and the gate REFUSES the very flow it documents.
+ *
+ * Fix: compute the WORKING-TREE token via `git stash create`. That
+ * command returns the SHA of a commit object whose tree is the
+ * working-tree + index merged. `git rev-parse <stash-sha>^{tree}` then
+ * gives a deterministic fingerprint of what codex actually reviewed:
+ *
+ *   - At review time: working tree dirty → token = Tw (working-tree tree).
+ *   - Operator commits: HEAD becomes B with tree Tb. Tb == Tw because
+ *     `git commit` just persists the index, not new content.
+ *   - Push time: working tree CLEAN, `git stash create` returns empty,
+ *     fall back to `HEAD^{tree}` = Tb == Tw. Match. Allow.
+ *
+ * Stable behaviors preserved from the 0.26.0 finding-1 fix:
+ *   - Stable across `git commit --amend` with no content change
+ *   - Stable across rebases that don't touch content (fixup, reword)
+ *   - Differs immediately on any real content edit
+ *
+ * NOTE: untracked AND `.gitignore`'d content is by design NOT part of
+ * the token, because:
+ *   - `git stash create` does not include untracked files (without `-u`,
+ *     and even `-u` excludes ignored files).
+ *   - `git push` cannot transmit them either.
+ * So the token reflects what would actually be pushed. Codex review
+ * follows the same `git diff` semantics.
+ *
+ * The audit record continues to record `head_sha` for forensics —
+ * `content_token` is what `rea preflight` matches on. Legacy
+ * `codex.review` audit entries (pre-0.26.0) only have `head_sha`;
+ * preflight falls back to head-sha matching for those.
+ */
+import { spawnSync } from 'node:child_process';
+/**
+ * Git's well-known "empty tree" object SHA — the SHA-1 of an empty tree
+ * object, identical across every git repository on Earth.
+ *
+ * Round-27 F2 fix: this constant exists so the unborn-HEAD bootstrap path
+ * is symmetric between writer (`rea review` audit-record `head_sha`) and
+ * reader (`rea preflight` HEAD probe). Pre-fix:
+ *
+ *   - `rea review` (writer) used `EMPTY_TREE_SHA` as the synthetic head
+ *     when HEAD couldn't be resolved (round-25 P2-B).
+ *   - `rea preflight` (reader) returned `''` for headSha AND empty
+ *     contentToken on unborn HEAD, then refused with a both-empty guard.
+ *
+ * The asymmetry deadlocked the bootstrap flow `git init` →
+ * `rea review` → `rea preflight` under `refuse_at: both`. Both sides
+ * now reference THIS constant when HEAD cannot be resolved, so the
+ * head_sha-fallback path in `findRecentLocalReview` matches uniformly.
+ */
+export const EMPTY_TREE_SHA = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+/**
+ * Compute a deterministic content token for the working tree.
+ *
+ * Returns `''` (empty string) when the tree token cannot be resolved
+ * (no git repo, no HEAD, etc.). Callers MUST treat empty token as
+ * "no token" — the audit record's `content_token` field should be
+ * omitted in that case so `rea preflight` does not match a missing
+ * token against a missing token (which would be a trivial bypass).
+ *
+ * The token is the SHA of the working-tree tree object (or HEAD's
+ * tree object if the working tree is clean). Format: 40-char lowercase
+ * hex (or 64-char if the repo uses SHA-256). The function does not
+ * normalize or truncate — `rea preflight` does an exact-string match.
+ *
+ * Resolution order (round-25 P1-A):
+ *   1. `git stash create` — non-empty stdout means there are tracked
+ *      changes. The stash SHA is a commit object; its tree is the
+ *      working-tree + index merged. Use `<sha>^{tree}` as treeSource.
+ *      `git stash create` does NOT modify the stash list, working tree,
+ *      or index — it only synthesizes a commit object pointing at the
+ *      current state.
+ *   2. Empty stdout from `git stash create` (or non-zero exit) → tree
+ *      is clean OR repo is empty. Fall back to `HEAD^{tree}`. A clean
+ *      working tree's tree object is identical to HEAD's tree by
+ *      definition.
+ *   3. Both fail → return empty string. `head_sha` fallback in
+ *      preflight takes over.
+ */
+export function computeTreeToken(cwd) {
+    // Step 1: try `git stash create`. Width-preserved by design — never
+    // touches the stash list, working tree, or index.
+    const stashResult = spawnSync('git', ['stash', 'create'], {
+        cwd,
+        encoding: 'utf8',
+    });
+    let treeSource;
+    if (stashResult.status === 0 && (stashResult.stdout ?? '').toString().trim().length > 0) {
+        const stashSha = (stashResult.stdout ?? '').toString().trim();
+        // Defensive: only accept hex SHA shapes — otherwise treat as
+        // unresolvable and fall through to HEAD^{tree}.
+        if (!/^[0-9a-f]{40,64}$/.test(stashSha)) {
+            treeSource = 'HEAD^{tree}';
+        }
+        else {
+            treeSource = `${stashSha}^{tree}`;
+        }
+    }
+    else {
+        // Step 2: clean working tree OR empty repo — clean tree's content
+        // is identical to HEAD^{tree} by definition; resolve that. Empty
+        // repo will fail in step 3 below and return empty string.
+        treeSource = 'HEAD^{tree}';
+    }
+    const treeResult = spawnSync('git', ['rev-parse', treeSource], {
+        cwd,
+        encoding: 'utf8',
+    });
+    if (treeResult.status !== 0)
+        return '';
+    const out = (treeResult.stdout ?? '').toString().trim();
+    // Defensive: only accept hex strings — git's tree SHA is always hex.
+    // This rejects unexpected output (error messages, ANSI noise, etc.).
+    if (!/^[0-9a-f]{40,64}$/.test(out))
+        return '';
+    return out;
+}

package/dist/audit/local-review-event.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Single source of truth for the `rea.local_review` audit event shape
+ * (0.26.0+).
+ *
+ * The local-first delegation enforcement (CTO directive 2026-05-05)
+ * replaces the soft "memory rule + orchestrator routing convention"
+ * with three forceful enforcement layers:
+ *
+ *   1. Bash-tier PreToolUse hook (hooks/local-review-gate.sh) — refuses
+ *      `git push`/`git commit` from the agent's Bash tool.
+ *   2. Husky pre-push (`exec rea preflight --strict`) — refuses git push
+ *      at the terminal layer.
+ *   3. `rea preflight` CLI — the workhorse all enforcement layers call.
+ *
+ * `rea review` writes a `rea.local_review` audit entry. `rea preflight`
+ * reads the audit log, finds the most recent matching entry for HEAD,
+ * and exits 0/1/2 accordingly.
+ *
+ * # Provider seam
+ *
+ * The `provider` field is the LIGHT seam for future review providers
+ * (Claude-subagent, Pi, Gemma). Today the only writer is `rea review`
+ * with `provider: 'codex'`. Tomorrow a different provider writes the
+ * SAME shape with its own `provider:` value, and `rea preflight` reads
+ * any of them — no registry, no factory, no swap mechanism.
+ *
+ * # Skipped variants
+ *
+ * - `rea.local_review.skipped_override`: env-var bypass; reason logged
+ * - `rea.local_review.skipped_unavailable`: codex missing + `mode: off`;
+ *   no review run, gate is a no-op
+ * - `rea.preflight.review_skipped`: `--no-review-check` CLI escape hatch
+ *
+ * Both `rea preflight` and any future audit-log reader treat these
+ * sibling tool names as INFORMATIONAL — they do NOT cover HEAD. Only
+ * the canonical `rea.local_review` entry (or the back-compat
+ * `codex.review` entry from pre-0.26.0 audit data) covers HEAD.
+ */
+export declare const LOCAL_REVIEW_TOOL_NAME: "rea.local_review";
+export declare const LOCAL_REVIEW_SKIPPED_OVERRIDE_TOOL_NAME: "rea.local_review.skipped_override";
+export declare const LOCAL_REVIEW_SKIPPED_UNAVAILABLE_TOOL_NAME: "rea.local_review.skipped_unavailable";
+export declare const LOCAL_REVIEW_PREFLIGHT_SKIPPED_TOOL_NAME: "rea.preflight.review_skipped";
+export declare const LOCAL_REVIEW_SERVER_NAME: "rea";
+/**
+ * The verdict shape — same alphabet as the push-gate's CodexVerdict.
+ * `error` is reserved for future providers that surface a non-execution
+ * outcome (timeout, transport failure, etc.) so `rea preflight` can
+ * decide whether to honor a stale error-marker.
+ */
+export type LocalReviewVerdict = 'pass' | 'concerns' | 'blocking' | 'error';
+/**
+ * Canonical metadata payload written under `metadata` on a
+ * `rea.local_review` audit record. `rea preflight` reads `head_sha`
+ * (must match `git rev-parse HEAD`) and `verdict` (must not be `error`
+ * for the entry to count as covering HEAD).
+ *
+ * `provider`, `provider_version`, `model`, `reasoning_effort` are
+ * non-semantic identification — the gate doesn't read them, but
+ * they're invaluable for forensic analysis ("which review producer
+ * did this concerns verdict come from?").
+ */
+export interface LocalReviewMetadata {
+    /**
+     * git rev-parse HEAD at review time. Recorded for forensics.
+     *
+     * 0.26.0 helix-026 finding-1: prior to this release `rea preflight`
+     * matched coverage by exact `head_sha`. That keyed coverage to a
+     * commit that didn't exist yet at review time (the local-first flow
+     * is "review → fix → commit → push" — HEAD changes between review
+     * and preflight). Coverage is now matched by `content_token` instead;
+     * `head_sha` remains in the payload purely for audit forensics.
+     */
+    head_sha: string;
+    /**
+     * Tree SHA of HEAD at review time — the deterministic content
+     * fingerprint codex reviewed. `rea preflight` matches coverage on
+     * this field. Stable across content-equivalent commits (`--amend` with
+     * no edits, fixup rebases). Differs on any real content change.
+     *
+     * Optional for back-compat: legacy `codex.review` entries (pre-0.26.0)
+     * and any future provider that can't compute a tree fingerprint should
+     * omit this. `rea preflight` falls back to `head_sha` exact match when
+     * `content_token` is absent.
+     */
+    content_token?: string;
+    /** Base ref (or SHA) the review diffed against. */
+    base_ref: string;
+    /** Verdict alphabet shared with the push-gate. */
+    verdict: LocalReviewVerdict;
+    /** Total findings extracted from the review prose. */
+    finding_count: number;
+    /**
+     * Logical name of the review provider. Today: `'codex'`. Future:
+     * `'claude-subagent'`, `'gemini'`, `'pi'`. Free-form lowercase
+     * identifier; the gate doesn't consume it.
+     */
+    provider: string;
+    /** Version string of the provider binary, when available. */
+    provider_version?: string;
+    /** Model name passed to the provider, when applicable. */
+    model?: string;
+    /** Reasoning effort, when applicable to the model. */
+    reasoning_effort?: string;
+    /** Wall-time of the review subprocess in seconds. */
+    duration_seconds: number;
+    /**
+     * Identifier the reviewer attached to this run. Today this is the
+     * codex session id; future providers use whatever identifies a
+     * single review invocation.
+     */
+    reviewer_session_id?: string;
+}
+/**
+ * Metadata for the `rea.local_review.skipped_override` event. Carries
+ * the reason string from the bypass env-var so audit-log readers can
+ * see WHY the gate was bypassed.
+ */
+export interface LocalReviewSkippedOverrideMetadata {
+    head_sha: string;
+    /** Verbatim env-var value (the operator's reason). */
+    reason: string;
+    /** Which env-var was set (configurable via policy). */
+    bypass_env_var: string;
+}
+/**
+ * Metadata for the `rea.local_review.skipped_unavailable` event. This
+ * fires when codex is absent AND `policy.review.local_review.mode === 'off'`
+ * — `rea review` exits 0 silently with this entry recording the no-op.
+ */
+export interface LocalReviewSkippedUnavailableMetadata {
+    head_sha?: string;
+    /** Why the run was skipped: `'codex-not-installed'`, etc. */
+    reason: string;
+    /** Provider that was probed, e.g. `'codex'`. */
+    provider: string;
+}

package/dist/audit/local-review-event.js

@@ -0,0 +1,43 @@
+/**
+ * Single source of truth for the `rea.local_review` audit event shape
+ * (0.26.0+).
+ *
+ * The local-first delegation enforcement (CTO directive 2026-05-05)
+ * replaces the soft "memory rule + orchestrator routing convention"
+ * with three forceful enforcement layers:
+ *
+ *   1. Bash-tier PreToolUse hook (hooks/local-review-gate.sh) — refuses
+ *      `git push`/`git commit` from the agent's Bash tool.
+ *   2. Husky pre-push (`exec rea preflight --strict`) — refuses git push
+ *      at the terminal layer.
+ *   3. `rea preflight` CLI — the workhorse all enforcement layers call.
+ *
+ * `rea review` writes a `rea.local_review` audit entry. `rea preflight`
+ * reads the audit log, finds the most recent matching entry for HEAD,
+ * and exits 0/1/2 accordingly.
+ *
+ * # Provider seam
+ *
+ * The `provider` field is the LIGHT seam for future review providers
+ * (Claude-subagent, Pi, Gemma). Today the only writer is `rea review`
+ * with `provider: 'codex'`. Tomorrow a different provider writes the
+ * SAME shape with its own `provider:` value, and `rea preflight` reads
+ * any of them — no registry, no factory, no swap mechanism.
+ *
+ * # Skipped variants
+ *
+ * - `rea.local_review.skipped_override`: env-var bypass; reason logged
+ * - `rea.local_review.skipped_unavailable`: codex missing + `mode: off`;
+ *   no review run, gate is a no-op
+ * - `rea.preflight.review_skipped`: `--no-review-check` CLI escape hatch
+ *
+ * Both `rea preflight` and any future audit-log reader treat these
+ * sibling tool names as INFORMATIONAL — they do NOT cover HEAD. Only
+ * the canonical `rea.local_review` entry (or the back-compat
+ * `codex.review` entry from pre-0.26.0 audit data) covers HEAD.
+ */
+export const LOCAL_REVIEW_TOOL_NAME = 'rea.local_review';
+export const LOCAL_REVIEW_SKIPPED_OVERRIDE_TOOL_NAME = 'rea.local_review.skipped_override';
+export const LOCAL_REVIEW_SKIPPED_UNAVAILABLE_TOOL_NAME = 'rea.local_review.skipped_unavailable';
+export const LOCAL_REVIEW_PREFLIGHT_SKIPPED_TOOL_NAME = 'rea.preflight.review_skipped';
+export const LOCAL_REVIEW_SERVER_NAME = 'rea';

package/dist/cli/doctor.js

@@ -145,12 +145,29 @@ const EXPECTED_AGENTS = [
 const EXPECTED_HOOKS = [
     'architecture-review-gate.sh',
     'attribution-advisory.sh',
+    // 0.22.0 — Bash-tier parity with `blocked-paths-enforcer.sh`.
+    // Round-27 F8 fix: was silently missing from EXPECTED_HOOKS, so
+    // doctor returned pass on consumer installs that lacked this
+    // security-load-bearing hook (any consumer who upgraded from
+    // 0.21.x → 0.22.x without `rea upgrade` was undetected).
+    'blocked-paths-bash-gate.sh',
     'blocked-paths-enforcer.sh',
     'changeset-security-gate.sh',
     'dangerous-bash-interceptor.sh',
     'dependency-audit-gate.sh',
     'env-file-protection.sh',
+    // 0.26.0 local-first enforcement (CTO directive 2026-05-05).
+    // Round-25 P3 fix: doctor's EXPECTED_HOOKS list missed this entry.
+    // Without it, `rea doctor` returned pass on consumer installs that
+    // didn't actually have the new gate present after upgrade — silently
+    // disabling the local-first guardrail.
+    'local-review-gate.sh',
     'pr-issue-link-gate.sh',
+    // 0.21.0 — Bash-tier parity with `settings-protection.sh`.
+    // Round-27 F8 fix: same class as blocked-paths-bash-gate.sh — silently
+    // missing since 0.21.0, doctor would pass even when the hook was
+    // absent from a consumer install.
+    'protected-paths-bash-gate.sh',
     'secret-scanner.sh',
     'security-disclosure-gate.sh',
     'settings-protection.sh',

package/dist/cli/hook.d.ts

@@ -80,6 +80,50 @@ export interface HookScanBashOptions {
  * writes the verdict JSON, exits with the appropriate code.
  */
 export declare function runHookScanBash(options: HookScanBashOptions): Promise<void>;
+/**
+ * `rea hook policy-get <dot.path>` — single source of truth for
+ * policy-value reads from the bash-tier hooks. Round-30 F2 structural
+ * fix.
+ *
+ * Pre-fix: `hooks/_lib/policy-read.sh::policy_nested_scalar` used a
+ * regex/awk parser that ONLY handled block-form mappings. The TS loader
+ * (`src/policy/loader.ts`) accepted inline-form mappings — `local_review:
+ * { mode: off }` — but the bash reader missed them. Silent split-brain:
+ * TS preflight saw `mode=off` (no-op), bash gate saw the field as unset
+ * and fell through to the enforced default → refused the push.
+ *
+ * Fix: have the bash gate shell out HERE for nested reads. The TS
+ * `yaml.parse()` call accepts both forms identically — single source of
+ * truth, drift impossible by construction.
+ *
+ * Contract:
+ *   - `key` is dot-separated: `review.local_review.mode`. Only
+ *     scalar leaves are supported (objects/arrays print empty).
+ *   - Output is the raw scalar VALUE on stdout (no trailing newline,
+ *     no quoting). Booleans render as `true`/`false`. Numbers render
+ *     as their JS string form.
+ *   - Unknown / missing path → empty stdout, exit 0. The bash caller
+ *     treats empty as "default applies".
+ *   - Unparseable YAML → empty stdout, exit 1. Bash callers swallow
+ *     the exit and treat as default (matches pre-fix posture: any read
+ *     error returns empty rather than refusing the gate).
+ */
+export interface HookPolicyGetOptions {
+    /** Dotted path; e.g. `review.local_review.mode`. */
+    key: string;
+    /**
+     * When true, emit the resolved subtree as JSON instead of a scalar.
+     * Object/array leaves print as their JSON form; scalars print as
+     * JSON-encoded scalars (`"off"`, `42`, `true`, `null`). Missing
+     * paths print `null`. Used by the bash hooks to read an entire
+     * sub-object in one node-spawn (e.g. all `review.local_review.*`
+     * fields at once) and parse client-side via jq.
+     */
+    json?: boolean;
+    /** Override REA_ROOT. Production callers omit. */
+    reaRoot?: string;
+}
+export declare function runHookPolicyGet(options: HookPolicyGetOptions): Promise<void>;
 /**
  * Attach the `rea hook` subcommand tree to a commander Program. Two
  * subcommands today: `push-gate` and `scan-bash`. New hooks should land