@bookedsolid/rea 0.24.0 → 0.26.0

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

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.');