@bookedsolid/rea 0.10.3 → 0.11.0

package/dist/policy/loader.d.ts

@@ -32,16 +32,16 @@ declare const PolicySchema: z.ZodObject<{
     }>>;
     review: z.ZodOptional<z.ZodObject<{
         codex_required: z.ZodOptional<z.ZodBoolean>;
-        cache_max_age_seconds: z.ZodOptional<z.ZodNumber>;
-        allow_skip_in_ci: z.ZodOptional<z.ZodBoolean>;
+        concerns_blocks: z.ZodOptional<z.ZodBoolean>;
+        timeout_ms: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         codex_required?: boolean | undefined;
-        cache_max_age_seconds?: number | undefined;
-        allow_skip_in_ci?: boolean | undefined;
+        concerns_blocks?: boolean | undefined;
+        timeout_ms?: number | undefined;
     }, {
         codex_required?: boolean | undefined;
-        cache_max_age_seconds?: number | undefined;
-        allow_skip_in_ci?: boolean | undefined;
+        concerns_blocks?: boolean | undefined;
+        timeout_ms?: number | undefined;
     }>>;
     redact: z.ZodOptional<z.ZodObject<{
         match_timeout_ms: z.ZodOptional<z.ZodNumber>;
@@ -133,8 +133,8 @@ declare const PolicySchema: z.ZodObject<{
     } | undefined;
     review?: {
         codex_required?: boolean | undefined;
-        cache_max_age_seconds?: number | undefined;
-        allow_skip_in_ci?: boolean | undefined;
+        concerns_blocks?: boolean | undefined;
+        timeout_ms?: number | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;
@@ -176,8 +176,8 @@ declare const PolicySchema: z.ZodObject<{
     } | undefined;
     review?: {
         codex_required?: boolean | undefined;
-        cache_max_age_seconds?: number | undefined;
-        allow_skip_in_ci?: boolean | undefined;
+        concerns_blocks?: boolean | undefined;
+        timeout_ms?: number | undefined;
     } | undefined;
     redact?: {
         match_timeout_ms?: number | undefined;

package/dist/policy/loader.js

@@ -16,16 +16,17 @@ const ContextProtectionSchema = z.object({
     max_bash_output_lines: z.number().int().positive().optional(),
 });
 /**
- * G11.2: minimal review policy. Only `codex_required` is recognized today;
- * G11.4 will expand this (profile defaults, reviewer pin, token caps).
- * Kept strict so a typo (`codex_require`) fails loudly instead of silently
- * defaulting.
+ * 0.11.0 push-gate review policy. Three knobs only — the stateless gate does
+ * not have a cache and does not treat CI differently. Strict mode so typos
+ * (`codex_require`, `concerns_block`) fail loudly rather than silently
+ * defaulting. `rea upgrade` strips the removed 0.10.x fields
+ * (`cache_max_age_seconds`, `allow_skip_in_ci`) from consumer policy files.
  */
 const ReviewPolicySchema = z
     .object({
     codex_required: z.boolean().optional(),
-    cache_max_age_seconds: z.number().int().positive().optional(),
-    allow_skip_in_ci: z.boolean().optional(),
+    concerns_blocks: z.boolean().optional(),
+    timeout_ms: z.number().int().positive().optional(),
 })
     .strict();
 /**

package/dist/policy/types.d.ts

@@ -19,38 +19,47 @@ export interface ContextProtection {
     max_bash_output_lines?: number;
 }
 /**
- * Review policy knobs. G11.2 only needs `codex_required` as an optional
- * signal to the reviewer selector; G11.4 will flesh this out into a full
- * first-class no-Codex mode (profile defaults, init defaults, etc.).
+ * Review policy knobs for the 0.11.0 stateless push-gate.
+ *
+ * The gate runs `codex exec review --json` on every push and infers a verdict
+ * from the streamed findings (see `src/hooks/push-gate/findings.ts`). No
+ * cache, no audit-receipt consultation, no SHA-keyed attestation. These
+ * knobs shape only the immediate run.
+ *
+ * The 0.10.x knobs `cache_max_age_seconds` and `allow_skip_in_ci` were
+ * removed in 0.11.0. `rea upgrade` strips them from consumer policy files.
  */
 export interface ReviewPolicy {
     /**
-     * When `false`, the selector treats ClaudeSelfReviewer as the preferred
-     * reviewer (not degraded). When `true` or unset, Codex is preferred and
-     * a ClaudeSelfReviewer result is marked `degraded: true` in the audit
-     * log. Default when unset is `true` (Codex required).
+     * When `true` or unset, `git push` runs `codex exec review` before the
+     * push is allowed to proceed. When `false`, the push-gate short-circuits
+     * to `disabled` (exit 0, audit event still recorded). No middle state —
+     * either we run Codex or we don't.
+     *
+     * Profile default: `true` in `bst-internal`, `client-engagement`,
+     * `lit-wc`, `open-source`. `false` in `*-no-codex` variants.
      */
     codex_required?: boolean;
     /**
-     * Review-cache TTL used by `rea cache check` (BUG-009). Entries older
-     * than this window are treated as a miss, forcing re-review. Default
-     * when unset is 3600 seconds (1 hour) — matches the windows the
-     * push-review-gate hook already assumes. Express in seconds, positive
-     * integer.
+     * Whether a `concerns` verdict blocks the push. `true` (default) means any
+     * non-trivial Codex finding halts the push; the agent must address the
+     * concerns (or re-run with `REA_ALLOW_CONCERNS=1` for a one-push override)
+     * before retrying. `false` means only `blocking` verdicts halt — concerns
+     * are logged and written to `.rea/last-review.json` but the push proceeds.
+     *
+     * Added in 0.11.0. Default when unset is `true` — safer posture for
+     * consumers who have not thought about it.
      */
-    cache_max_age_seconds?: number;
+    concerns_blocks?: boolean;
     /**
-     * Authorization for `REA_SKIP_PUSH_REVIEW` / `REA_SKIP_CODEX_REVIEW` when
-     * the `CI` environment variable is set. The skip hatches are ambient and
-     * unauthenticated — a leaked env file or a malicious parent process can
-     * bypass the gate and record a forged actor (git config is mutable repo
-     * config). Refusing these hatches in CI contexts by default removes that
-     * bypass surface. Set `true` ONLY on build agents where the operator has
-     * an independent reason to trust the environment. Default `false`.
+     * Hard cap on the `codex exec review` subprocess in milliseconds. Exceeding
+     * this kills the subprocess and the gate returns exit 2 with a timeout
+     * error (audited). Default when unset is 600_000 (10 minutes) — matches
+     * the upper bound we observe for a 500-line diff review on a slow link.
      *
-     * Added in 0.5.0 as Codex F2 on the PR1 adversarial review.
+     * Positive integer only. The loader rejects zero/negative values.
      */
-    allow_skip_in_ci?: boolean;
+    timeout_ms?: number;
 }
 /**
  * User-supplied redaction pattern entry. Each pattern has a stable `name` used

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.10.3",
+  "version": "0.11.0",
   "description": "Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review for AI-assisted projects",
   "license": "MIT",
   "author": "Booked Solid Technology <oss@bookedsolid.tech> (https://bookedsolid.tech)",

package/dist/cache/review-cache.d.ts

@@ -1,115 +0,0 @@
-/**
- * Review cache (BUG-009). The push-review-gate hook (`hooks/push-review-gate.sh`)
- * has shipped since 0.3.x calling `rea cache check <sha>` to skip re-review on
- * a previously-approved diff, and `rea cache set <sha> pass ...` as the
- * operator's advertised way to complete the gate. Neither subcommand existed
- * in the CLI through 0.4.0. Once BUG-008's pre-push stdin adapter lands and
- * the gate actually fires, a protected-path push has no completion path
- * without this cache — hence "paired ship blocker."
- *
- * ## File layout
- *
- * `.rea/review-cache.jsonl` — one JSON object per line, terminated with `\n`.
- * Each entry:
- *
- *   {
- *     "sha": "<diff-sha256>",
- *     "branch": "<feature-branch>",
- *     "base": "<target-branch>",
- *     "result": "pass" | "fail",
- *     "recorded_at": "<ISO-8601>",
- *     "reason"?: "<free text>"   // optional, populated on fail or on skip
- *   }
- *
- * The `sha` is whatever the caller supplies — the hook happens to use a
- * SHA-256 of the full diff, but the cache does not interpret or validate the
- * value. Hash-chained is intentionally NOT required: this is a keyed cache,
- * not an append-only integrity log. The audit log at `.rea/audit.jsonl`
- * remains the integrity story.
- *
- * ## Concurrency
- *
- * Every write takes the same `proper-lockfile` lock on the `.rea/` parent
- * directory that the audit helpers use (`withAuditLock`). This means a
- * concurrent audit append and cache write serialize against each other — a
- * negligible cost given cache writes happen once per push gate completion.
- *
- * ## Idempotency
- *
- * `appendEntry` writes a new line unconditionally. `lookup` returns the most
- * recent entry matching `(sha, branch, base)`. This "last write wins" keeps
- * the write path O(1) and the read path O(n) over the file; n is bounded by
- * typical review frequency (dozens per week, not millions). If a future
- * operator needs a compact file, `rea cache clear <sha>` drops matching
- * entries and a separate `rea cache compact` (not in 0.5.0) could rewrite.
- *
- * ## TTL
- *
- * `lookup` honors `review.cache_max_age_seconds` (default 3600). Entries
- * older than the window are treated as a miss. Expired entries are not
- * garbage-collected on read — `rea cache clear` or `rea cache compact`
- * is the operator tool for shrinking.
- */
-/** Default TTL when policy does not supply one. */
-export declare const DEFAULT_CACHE_MAX_AGE_SECONDS = 3600;
-export type CacheResult = 'pass' | 'fail';
-export interface CacheEntry {
-    sha: string;
-    branch: string;
-    base: string;
-    result: CacheResult;
-    recorded_at: string;
-    reason?: string;
-}
-export interface CacheLookupInput {
-    sha: string;
-    branch: string;
-    base: string;
-    /** Epoch ms used as the "now" reference for TTL comparison. Defaults to `Date.now()`. */
-    nowMs?: number;
-    /** TTL in seconds; defaults to {@link DEFAULT_CACHE_MAX_AGE_SECONDS}. */
-    maxAgeSeconds?: number;
-}
-export interface CacheLookupResult {
-    hit: boolean;
-    entry?: CacheEntry;
-    /** Reason for a miss. One of `'no-entry' | 'expired' | 'empty-file'`. Always set when `hit === false`. */
-    missReason?: 'no-entry' | 'expired' | 'empty-file';
-}
-export interface CacheAppendInput {
-    sha: string;
-    branch: string;
-    base: string;
-    result: CacheResult;
-    reason?: string;
-    /** ISO-8601 timestamp. Defaults to `new Date().toISOString()`. */
-    timestamp?: string;
-}
-export declare function resolveCacheFile(baseDir: string): string;
-/**
- * Append an entry to the cache. Writes are serialized through the shared
- * `.rea/` directory lock so audit writes and cache writes do not interleave.
- */
-export declare function appendEntry(baseDir: string, input: CacheAppendInput): Promise<CacheEntry>;
-/**
- * Find the most-recent entry matching `(sha, branch, base)` within the TTL
- * window. Idempotent and side-effect free.
- */
-export declare function lookup(baseDir: string, input: CacheLookupInput): Promise<CacheLookupResult>;
-/**
- * Remove every entry matching `sha`. Returns the count removed. A `0` return
- * is a valid outcome (sha not present). Writes back via the same lock as
- * `appendEntry`, so concurrent sets do not lose entries.
- *
- * Writes use temp-file + `fs.rename` (atomic within a single directory on
- * POSIX) so unlocked readers (`lookup`, `list`) can never observe a torn or
- * empty intermediate state. Codex F4 on the 0.5.0 PR1 review.
- */
-export declare function clear(baseDir: string, sha: string): Promise<number>;
-/**
- * Return every entry, optionally filtered by branch. Entries are returned in
- * file order (oldest first). Callers that want "newest first" should reverse.
- */
-export declare function list(baseDir: string, options?: {
-    branch?: string;
-}): Promise<CacheEntry[]>;

package/dist/cache/review-cache.js

@@ -1,200 +0,0 @@
-/**
- * Review cache (BUG-009). The push-review-gate hook (`hooks/push-review-gate.sh`)
- * has shipped since 0.3.x calling `rea cache check <sha>` to skip re-review on
- * a previously-approved diff, and `rea cache set <sha> pass ...` as the
- * operator's advertised way to complete the gate. Neither subcommand existed
- * in the CLI through 0.4.0. Once BUG-008's pre-push stdin adapter lands and
- * the gate actually fires, a protected-path push has no completion path
- * without this cache — hence "paired ship blocker."
- *
- * ## File layout
- *
- * `.rea/review-cache.jsonl` — one JSON object per line, terminated with `\n`.
- * Each entry:
- *
- *   {
- *     "sha": "<diff-sha256>",
- *     "branch": "<feature-branch>",
- *     "base": "<target-branch>",
- *     "result": "pass" | "fail",
- *     "recorded_at": "<ISO-8601>",
- *     "reason"?: "<free text>"   // optional, populated on fail or on skip
- *   }
- *
- * The `sha` is whatever the caller supplies — the hook happens to use a
- * SHA-256 of the full diff, but the cache does not interpret or validate the
- * value. Hash-chained is intentionally NOT required: this is a keyed cache,
- * not an append-only integrity log. The audit log at `.rea/audit.jsonl`
- * remains the integrity story.
- *
- * ## Concurrency
- *
- * Every write takes the same `proper-lockfile` lock on the `.rea/` parent
- * directory that the audit helpers use (`withAuditLock`). This means a
- * concurrent audit append and cache write serialize against each other — a
- * negligible cost given cache writes happen once per push gate completion.
- *
- * ## Idempotency
- *
- * `appendEntry` writes a new line unconditionally. `lookup` returns the most
- * recent entry matching `(sha, branch, base)`. This "last write wins" keeps
- * the write path O(1) and the read path O(n) over the file; n is bounded by
- * typical review frequency (dozens per week, not millions). If a future
- * operator needs a compact file, `rea cache clear <sha>` drops matching
- * entries and a separate `rea cache compact` (not in 0.5.0) could rewrite.
- *
- * ## TTL
- *
- * `lookup` honors `review.cache_max_age_seconds` (default 3600). Entries
- * older than the window are treated as a miss. Expired entries are not
- * garbage-collected on read — `rea cache clear` or `rea cache compact`
- * is the operator tool for shrinking.
- */
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { withAuditLock } from '../audit/fs.js';
-/** Default TTL when policy does not supply one. */
-export const DEFAULT_CACHE_MAX_AGE_SECONDS = 3600;
-/**
- * Tolerated clock skew for future-dated entries. A `recorded_at` more than
- * this far in the future relative to `nowMs` is treated as tampered or
- * severely-drifted and forces a miss (re-review). 60s covers NTP jitter on
- * well-synced hosts; anything beyond that is noise we do not trust.
- */
-const FUTURE_SKEW_ALLOWANCE_MS = 60_000;
-const CACHE_FILENAME = 'review-cache.jsonl';
-const REA_DIRNAME = '.rea';
-export function resolveCacheFile(baseDir) {
-    return path.join(baseDir, REA_DIRNAME, CACHE_FILENAME);
-}
-/**
- * Load every entry from the cache file. Returns `[]` when the file does not
- * exist or is empty. Malformed lines are skipped — we never throw on a
- * corrupt line, because the cache is advisory and a bad write (e.g. a
- * half-written line from a crashed host) must not block a subsequent push.
- */
-async function loadEntries(cacheFile) {
-    let raw;
-    try {
-        raw = await fs.readFile(cacheFile, 'utf8');
-    }
-    catch (err) {
-        if (err.code === 'ENOENT')
-            return [];
-        throw err;
-    }
-    if (raw.length === 0)
-        return [];
-    const entries = [];
-    for (const line of raw.split('\n')) {
-        if (line.length === 0)
-            continue;
-        try {
-            const parsed = JSON.parse(line);
-            if (typeof parsed.sha === 'string' &&
-                typeof parsed.branch === 'string' &&
-                typeof parsed.base === 'string' &&
-                (parsed.result === 'pass' || parsed.result === 'fail') &&
-                typeof parsed.recorded_at === 'string') {
-                entries.push(parsed);
-            }
-        }
-        catch {
-            // Skip malformed line.
-        }
-    }
-    return entries;
-}
-/**
- * Append an entry to the cache. Writes are serialized through the shared
- * `.rea/` directory lock so audit writes and cache writes do not interleave.
- */
-export async function appendEntry(baseDir, input) {
-    const cacheFile = resolveCacheFile(baseDir);
-    await fs.mkdir(path.dirname(cacheFile), { recursive: true });
-    const entry = {
-        sha: input.sha,
-        branch: input.branch,
-        base: input.base,
-        result: input.result,
-        recorded_at: input.timestamp ?? new Date().toISOString(),
-        ...(input.reason !== undefined && input.reason.length > 0
-            ? { reason: input.reason }
-            : {}),
-    };
-    await withAuditLock(cacheFile, async () => {
-        const line = JSON.stringify(entry) + '\n';
-        await fs.appendFile(cacheFile, line);
-    });
-    return entry;
-}
-/**
- * Find the most-recent entry matching `(sha, branch, base)` within the TTL
- * window. Idempotent and side-effect free.
- */
-export async function lookup(baseDir, input) {
-    const cacheFile = resolveCacheFile(baseDir);
-    const entries = await loadEntries(cacheFile);
-    if (entries.length === 0)
-        return { hit: false, missReason: 'empty-file' };
-    // Walk from the tail so the first match is the newest.
-    let matched;
-    for (let i = entries.length - 1; i >= 0; i--) {
-        const e = entries[i];
-        if (e.sha === input.sha && e.branch === input.branch && e.base === input.base) {
-            matched = e;
-            break;
-        }
-    }
-    if (matched === undefined)
-        return { hit: false, missReason: 'no-entry' };
-    const nowMs = input.nowMs ?? Date.now();
-    const maxAgeSeconds = input.maxAgeSeconds ?? DEFAULT_CACHE_MAX_AGE_SECONDS;
-    const recordedMs = Date.parse(matched.recorded_at);
-    if (Number.isNaN(recordedMs)) {
-        // Corrupt timestamp — treat as an expired miss so the caller re-reviews.
-        return { hit: false, missReason: 'expired', entry: matched };
-    }
-    if (recordedMs > nowMs + FUTURE_SKEW_ALLOWANCE_MS) {
-        return { hit: false, missReason: 'expired', entry: matched };
-    }
-    if ((nowMs - recordedMs) / 1000 > maxAgeSeconds) {
-        return { hit: false, missReason: 'expired', entry: matched };
-    }
-    return { hit: true, entry: matched };
-}
-/**
- * Remove every entry matching `sha`. Returns the count removed. A `0` return
- * is a valid outcome (sha not present). Writes back via the same lock as
- * `appendEntry`, so concurrent sets do not lose entries.
- *
- * Writes use temp-file + `fs.rename` (atomic within a single directory on
- * POSIX) so unlocked readers (`lookup`, `list`) can never observe a torn or
- * empty intermediate state. Codex F4 on the 0.5.0 PR1 review.
- */
-export async function clear(baseDir, sha) {
-    const cacheFile = resolveCacheFile(baseDir);
-    return withAuditLock(cacheFile, async () => {
-        const entries = await loadEntries(cacheFile);
-        const kept = entries.filter((e) => e.sha !== sha);
-        const removed = entries.length - kept.length;
-        if (removed === 0)
-            return 0;
-        const out = kept.length === 0 ? '' : kept.map((e) => JSON.stringify(e)).join('\n') + '\n';
-        const tmpFile = `${cacheFile}.tmp.${process.pid}.${Date.now()}`;
-        await fs.writeFile(tmpFile, out);
-        await fs.rename(tmpFile, cacheFile);
-        return removed;
-    });
-}
-/**
- * Return every entry, optionally filtered by branch. Entries are returned in
- * file order (oldest first). Callers that want "newest first" should reverse.
- */
-export async function list(baseDir, options = {}) {
-    const cacheFile = resolveCacheFile(baseDir);
-    const entries = await loadEntries(cacheFile);
-    if (options.branch === undefined)
-        return entries;
-    return entries.filter((e) => e.branch === options.branch);
-}

package/dist/cli/cache.d.ts

@@ -1,84 +0,0 @@
-/**
- * `rea cache` — push-review cache operator subcommands (BUG-009).
- *
- * Four verbs:
- *   - `check <sha> --branch <b> --base <b>` — JSON to stdout ONLY; never
- *     diagnostics. `hooks/push-review-gate.sh` reads this via
- *     `printf '%s' "$CACHE_RESULT" | jq -e '.hit == true'`, so any stray
- *     text on stdout would poison the hook's JSON parse.
- *   - `set <sha> pass|fail --branch <b> --base <b> [--reason <s>]` — record
- *     a review outcome.
- *   - `clear <sha>` — drop every entry for a sha (dev convenience).
- *   - `list [--branch <b>]` — pretty-print entries.
- *
- * The TTL used by `check` reads `review.cache_max_age_seconds` from
- * `.rea/policy.yaml` when present, falling back to
- * {@link DEFAULT_CACHE_MAX_AGE_SECONDS} (1 hour) when the policy file or
- * field is absent. An unreadable/malformed policy file is NOT fatal for
- * `check` — it degrades to the default so a broken policy never deadlocks
- * the push gate; other commands that don't consume the TTL ignore the policy
- * entirely.
- */
-import { type CacheResult } from '../cache/review-cache.js';
-import type { CodexVerdict } from '../audit/codex-event.js';
-export interface CacheCheckOptions {
-    sha: string;
-    branch: string;
-    base: string;
-}
-export interface CacheSetOptions {
-    sha: string;
-    result: CacheResult;
-    branch: string;
-    base: string;
-    reason?: string;
-}
-export interface CacheClearOptions {
-    sha: string;
-}
-export interface CacheListOptions {
-    branch?: string;
-}
-/**
- * Print the cache-check JSON to stdout. Hook contract: stdout is ONLY JSON.
- * On a miss we still exit 0 with `{"hit":false}` — the hook interprets
- * non-zero as "rea broken, force re-review" via its `|| echo '{"hit":false}'`
- * fallback.
- */
-export declare function runCacheCheck(options: CacheCheckOptions): Promise<void>;
-export declare function runCacheSet(options: CacheSetOptions): Promise<void>;
-export declare function runCacheClear(options: CacheClearOptions): Promise<void>;
-export declare function runCacheList(options: CacheListOptions): Promise<void>;
-/** Parse-and-validate helper for `set` — surfaces a clean error on bad input.
- *
- * Accepts the two historical cache values (`pass`, `fail`) AND the four
- * canonical Codex verdicts (`pass`, `concerns`, `blocking`, `error`) per
- * Defect D (rea#77). Codex verdicts are mapped to cache semantics at the CLI
- * boundary: `pass|concerns` → gate-satisfying `pass`; `blocking|error` →
- * gate-failing `fail`. The cache internal vocabulary stays binary
- * (`pass`/`fail` = "gate-satisfying?") while the CLI accepts the full Codex
- * vocabulary so agents can copy the `/codex-review` verdict verbatim.
- */
-export declare function parseCacheResult(raw: string): CacheResult;
-/** Shape returned by {@link codexVerdictToCacheResult}: the binary cache result
- * plus an optional machine-readable `reason` string that records the source
- * Codex verdict. `reason` is populated for non-`pass` verdicts so downstream
- * listings expose WHY a cache fail was recorded. */
-export interface CodexVerdictCacheEffect {
-    result: CacheResult;
-    reason?: string | undefined;
-}
-/** Map a Codex verdict to the binary cache result the gate compares against.
- *
- * Mapping rationale:
- *   - `pass` → cache `pass` (clean review, gate should pass)
- *   - `concerns` → cache `pass` (non-blocking findings, gate should pass;
- *     reviewer captured concerns in the audit record `metadata.summary`)
- *   - `blocking` → cache `fail` (must address findings before merge)
- *   - `error` → cache `fail` (Codex itself errored; no clean-bill-of-health)
- *
- * Kept separate from `parseCacheResult` so callers that already have a typed
- * `CodexVerdict` (e.g. `rea audit record codex-review --also-set-cache`) don't
- * round-trip through string parsing.
- */
-export declare function codexVerdictToCacheResult(verdict: CodexVerdict): CodexVerdictCacheEffect;