npm - @bookedsolid/rea - Versions diffs - 0.10.3 → 0.12.0 - Mend

@bookedsolid/rea 0.10.3 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (77) hide show

package/.husky/pre-push +48 -162
package/README.md +834 -552
package/agents/codex-adversarial.md +5 -3
package/commands/codex-review.md +3 -5
package/dist/audit/append.d.ts +7 -32
package/dist/audit/append.js +7 -35
package/dist/cli/audit.d.ts +0 -31
package/dist/cli/audit.js +5 -74
package/dist/cli/doctor.d.ts +12 -0
package/dist/cli/doctor.js +96 -17
package/dist/cli/hook.d.ts +55 -0
package/dist/cli/hook.js +138 -0
package/dist/cli/index.js +5 -80
package/dist/cli/init.js +1 -1
package/dist/cli/install/gitignore.d.ts +2 -2
package/dist/cli/install/gitignore.js +3 -3
package/dist/cli/install/pre-push.d.ts +158 -272
package/dist/cli/install/pre-push.js +491 -2633
package/dist/cli/install/settings-merge.d.ts +17 -0
package/dist/cli/install/settings-merge.js +48 -1
package/dist/cli/upgrade.js +131 -3
package/dist/config/tier-map.js +18 -25
package/dist/hooks/push-gate/base.d.ts +104 -0
package/dist/hooks/push-gate/base.js +198 -0
package/dist/hooks/push-gate/codex-runner.d.ts +126 -0
package/dist/hooks/push-gate/codex-runner.js +223 -0
package/dist/hooks/push-gate/findings.d.ts +68 -0
package/dist/hooks/push-gate/findings.js +142 -0
package/dist/hooks/push-gate/halt.d.ts +28 -0
package/dist/hooks/push-gate/halt.js +49 -0
package/dist/hooks/push-gate/index.d.ts +98 -0
package/dist/hooks/push-gate/index.js +416 -0
package/dist/hooks/push-gate/policy.d.ts +55 -0
package/dist/hooks/push-gate/policy.js +64 -0
package/dist/hooks/push-gate/report.d.ts +89 -0
package/dist/hooks/push-gate/report.js +140 -0
package/dist/policy/loader.d.ts +15 -10
package/dist/policy/loader.js +8 -6
package/dist/policy/types.d.ts +73 -22
package/package.json +1 -1
package/scripts/tarball-smoke.sh +7 -2
package/dist/cache/review-cache.d.ts +0 -115
package/dist/cache/review-cache.js +0 -200
package/dist/cli/cache.d.ts +0 -84
package/dist/cli/cache.js +0 -150
package/dist/hooks/review-gate/args.d.ts +0 -126
package/dist/hooks/review-gate/args.js +0 -315
package/dist/hooks/review-gate/audit.d.ts +0 -131
package/dist/hooks/review-gate/audit.js +0 -181
package/dist/hooks/review-gate/banner.d.ts +0 -97
package/dist/hooks/review-gate/banner.js +0 -172
package/dist/hooks/review-gate/base-resolve.d.ts +0 -155
package/dist/hooks/review-gate/base-resolve.js +0 -247
package/dist/hooks/review-gate/cache-key.d.ts +0 -55
package/dist/hooks/review-gate/cache-key.js +0 -41
package/dist/hooks/review-gate/cache.d.ts +0 -108
package/dist/hooks/review-gate/cache.js +0 -120
package/dist/hooks/review-gate/constants.d.ts +0 -26
package/dist/hooks/review-gate/constants.js +0 -34
package/dist/hooks/review-gate/diff.d.ts +0 -181
package/dist/hooks/review-gate/diff.js +0 -232
package/dist/hooks/review-gate/errors.d.ts +0 -72
package/dist/hooks/review-gate/errors.js +0 -100
package/dist/hooks/review-gate/hash.d.ts +0 -43
package/dist/hooks/review-gate/hash.js +0 -46
package/dist/hooks/review-gate/index.d.ts +0 -31
package/dist/hooks/review-gate/index.js +0 -35
package/dist/hooks/review-gate/metadata.d.ts +0 -98
package/dist/hooks/review-gate/metadata.js +0 -158
package/dist/hooks/review-gate/policy.d.ts +0 -55
package/dist/hooks/review-gate/policy.js +0 -71
package/dist/hooks/review-gate/protected-paths.d.ts +0 -46
package/dist/hooks/review-gate/protected-paths.js +0 -76
package/hooks/_lib/push-review-core.sh +0 -1250
package/hooks/commit-review-gate.sh +0 -330
package/hooks/push-review-gate-git.sh +0 -94
package/hooks/push-review-gate.sh +0 -92

package/dist/hooks/push-gate/codex-runner.d.ts ADDED Viewed

@@ -0,0 +1,126 @@
+/**
+ * Codex CLI runner for the push-gate.
+ *
+ * Shells to `codex exec review --base <ref> --json --ephemeral` and consumes
+ * the JSONL event stream. Every event is parsed; the sequence of
+ * `agent_message` items becomes the review text that `findings.ts` then
+ * parses for P1/P2/P3 markers.
+ *
+ * Errors are typed so `index.ts` can distinguish:
+ *
+ *   - `CodexNotInstalledError`  → clear install-Codex prompt
+ *   - `CodexTimeoutError`       → `review.timeout_ms` exceeded; kill signal
+ *   - `CodexProtocolError`      → stdout was not JSONL or lacked agent output
+ *   - `CodexSubprocessError`    → non-zero exit with captured stderr
+ *
+ * The `GitExecutor` interface is a narrow shim around `git` invocations the
+ * gate needs (base resolution, diff-names, HEAD resolution). Extracted so
+ * `./base.ts` and `./index.ts` can be unit-tested with deterministic fakes
+ * and so the one git dependency surface is in one place.
+ */
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+export declare class CodexNotInstalledError extends Error {
+    readonly kind: "not-installed";
+    constructor();
+}
+export declare class CodexTimeoutError extends Error {
+    readonly timeoutMs: number;
+    readonly kind: "timeout";
+    constructor(timeoutMs: number);
+}
+export declare class CodexProtocolError extends Error {
+    readonly detail: string;
+    readonly sampleLine?: string | undefined;
+    readonly kind: "protocol";
+    constructor(detail: string, sampleLine?: string | undefined);
+}
+export declare class CodexSubprocessError extends Error {
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly stderrTail: string;
+    readonly kind: "subprocess";
+    constructor(exitCode: number | null, signal: NodeJS.Signals | null, stderrTail: string);
+}
+export type CodexRunError = CodexNotInstalledError | CodexTimeoutError | CodexProtocolError | CodexSubprocessError;
+export interface GitExecutor {
+    /** `git rev-parse <args>`. Returns stdout trimmed or '' on non-zero exit. */
+    tryRevParse(args: string[]): string;
+    /** `git symbolic-ref <ref>`. Returns stdout trimmed or '' on non-zero. */
+    trySymbolicRef(ref: string): string;
+    /** `git rev-parse HEAD`. Returns the 40-char SHA or '' on non-zero. */
+    headSha(): string;
+    /** `git diff --name-only <base> <head>`. Returns path list (possibly empty). */
+    diffNames(base: string, head: string): string[];
+}
+/**
+ * Real git implementation using `spawnSync`. Each call is independent (no
+ * persistent git process) — the gate runs infrequently enough that the
+ * fork overhead is inaudible.
+ */
+export declare function createRealGitExecutor(cwd: string): GitExecutor;
+export interface CodexRunOptions {
+    baseRef: string;
+    cwd: string;
+    timeoutMs: number;
+    /** Optional custom review prompt; defaults to Codex's built-in. */
+    prompt?: string;
+    /**
+     * Env passthrough. Tests inject a clean env to prevent ambient overrides.
+     * Production passes `process.env`.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Injection seam for tests. When set, replaces `spawn` entirely. Must
+     * return an object whose `stdout`/`stderr` are async iterables of Buffer
+     * chunks and whose `on('exit')` yields `(code, signal)` like a real
+     * ChildProcess. Keeping this narrow means we don't have to fake the
+     * whole ChildProcess API.
+     */
+    spawnImpl?: (command: string, args: readonly string[], options: {
+        cwd: string;
+        env: NodeJS.ProcessEnv;
+    }) => ChildProcessWithoutNullStreams;
+}
+export interface CodexRunResult {
+    /** The concatenated text of every `item.completed` agent_message item. */
+    reviewText: string;
+    /** Number of JSONL events observed — useful for debugging protocol issues. */
+    eventCount: number;
+    /** Seconds of wall time spent in the subprocess. */
+    durationSeconds: number;
+}
+/**
+ * Execute `codex exec review` and return the concatenated review text on
+ * success. Callers then pass the text to `summarizeReview()` to get a
+ * structured verdict.
+ *
+ * Every error case throws a typed `CodexRunError`. Callers are expected to
+ * catch and translate to an exit code + audit event.
+ */
+export declare function runCodexReview(options: CodexRunOptions): Promise<CodexRunResult>;
+export interface CodexJsonlParseResult {
+    reviewText: string;
+    eventCount: number;
+}
+/**
+ * Parse the JSONL event stream emitted by `codex exec review --json`. We
+ * tolerate partial lines (stream chunks may split mid-object; our caller
+ * gives us the full stdout after exit, but robustness costs nothing).
+ *
+ * The only events we care about are `item.completed` where `item.type ===
+ * "agent_message"` — those carry the review text. Everything else (turn
+ * lifecycle, command_execution telemetry, thread metadata) is counted but
+ * discarded.
+ *
+ * A JSONL line that doesn't parse as JSON is tolerated: we skip it and
+ * continue. Codex occasionally emits warnings outside the JSON envelope
+ * (e.g. macOS xcrun cache errors leak into stderr but can accidentally
+ * land on stdout in misbehaving shells); we treat these as non-fatal.
+ *
+ * We throw `CodexProtocolError` only when the ENTIRE stdout contains zero
+ * parseable events AND zero `agent_message`-carrying items. An empty diff
+ * can legitimately yield zero agent messages with events (thread.started,
+ * turn.started, turn.completed), so we allow zero findings when at least
+ * one event parsed.
+ */
+export declare function parseCodexJsonl(stdout: string): CodexJsonlParseResult;

package/dist/hooks/push-gate/codex-runner.js ADDED Viewed

@@ -0,0 +1,223 @@
+/**
+ * Codex CLI runner for the push-gate.
+ *
+ * Shells to `codex exec review --base <ref> --json --ephemeral` and consumes
+ * the JSONL event stream. Every event is parsed; the sequence of
+ * `agent_message` items becomes the review text that `findings.ts` then
+ * parses for P1/P2/P3 markers.
+ *
+ * Errors are typed so `index.ts` can distinguish:
+ *
+ *   - `CodexNotInstalledError`  → clear install-Codex prompt
+ *   - `CodexTimeoutError`       → `review.timeout_ms` exceeded; kill signal
+ *   - `CodexProtocolError`      → stdout was not JSONL or lacked agent output
+ *   - `CodexSubprocessError`    → non-zero exit with captured stderr
+ *
+ * The `GitExecutor` interface is a narrow shim around `git` invocations the
+ * gate needs (base resolution, diff-names, HEAD resolution). Extracted so
+ * `./base.ts` and `./index.ts` can be unit-tested with deterministic fakes
+ * and so the one git dependency surface is in one place.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+export class CodexNotInstalledError extends Error {
+    kind = 'not-installed';
+    constructor() {
+        super('codex CLI not found on PATH. Install with `npm i -g @openai/codex`, or set `review.codex_required: false` in .rea/policy.yaml to disable the push-gate.');
+        this.name = 'CodexNotInstalledError';
+    }
+}
+export class CodexTimeoutError extends Error {
+    timeoutMs;
+    kind = 'timeout';
+    constructor(timeoutMs) {
+        super(`codex exec review exceeded policy.review.timeout_ms (${timeoutMs}ms). The subprocess was killed. Consider raising the timeout, narrowing the diff, or running /codex-review manually to debug.`);
+        this.timeoutMs = timeoutMs;
+        this.name = 'CodexTimeoutError';
+    }
+}
+export class CodexProtocolError extends Error {
+    detail;
+    sampleLine;
+    kind = 'protocol';
+    constructor(detail, sampleLine) {
+        super(`codex exec review produced unexpected output: ${detail}${sampleLine !== undefined ? ` (sample: ${sampleLine.slice(0, 120)})` : ''}`);
+        this.detail = detail;
+        this.sampleLine = sampleLine;
+        this.name = 'CodexProtocolError';
+    }
+}
+export class CodexSubprocessError extends Error {
+    exitCode;
+    signal;
+    stderrTail;
+    kind = 'subprocess';
+    constructor(exitCode, signal, stderrTail) {
+        super(`codex exec review exited ${exitCode !== null ? `with code ${exitCode}` : `via signal ${signal ?? 'unknown'}`}. stderr tail: ${stderrTail.slice(-800)}`);
+        this.exitCode = exitCode;
+        this.signal = signal;
+        this.stderrTail = stderrTail;
+        this.name = 'CodexSubprocessError';
+    }
+}
+/**
+ * Real git implementation using `spawnSync`. Each call is independent (no
+ * persistent git process) — the gate runs infrequently enough that the
+ * fork overhead is inaudible.
+ */
+export function createRealGitExecutor(cwd) {
+    const run = (args) => {
+        const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
+        return {
+            code: r.status ?? -1,
+            stdout: typeof r.stdout === 'string' ? r.stdout : '',
+            stderr: typeof r.stderr === 'string' ? r.stderr : '',
+        };
+    };
+    return {
+        tryRevParse(args) {
+            const r = run(['rev-parse', ...args]);
+            return r.code === 0 ? r.stdout.trim() : '';
+        },
+        trySymbolicRef(ref) {
+            const r = run(['symbolic-ref', ref]);
+            return r.code === 0 ? r.stdout.trim() : '';
+        },
+        headSha() {
+            const r = run(['rev-parse', 'HEAD']);
+            return r.code === 0 ? r.stdout.trim() : '';
+        },
+        diffNames(base, head) {
+            const r = run(['diff', '--name-only', base, head]);
+            if (r.code !== 0)
+                return [];
+            return r.stdout.split(/\r?\n/).filter((l) => l.length > 0);
+        },
+    };
+}
+/**
+ * Execute `codex exec review` and return the concatenated review text on
+ * success. Callers then pass the text to `summarizeReview()` to get a
+ * structured verdict.
+ *
+ * Every error case throws a typed `CodexRunError`. Callers are expected to
+ * catch and translate to an exit code + audit event.
+ */
+export async function runCodexReview(options) {
+    const spawner = options.spawnImpl ?? spawn;
+    const baseArgs = ['exec', 'review', '--base', options.baseRef, '--json', '--ephemeral'];
+    const args = options.prompt !== undefined && options.prompt.length > 0 ? [...baseArgs, options.prompt] : baseArgs;
+    let child;
+    try {
+        child = spawner('codex', args, {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+        });
+    }
+    catch (e) {
+        if (isEnoent(e))
+            throw new CodexNotInstalledError();
+        throw e;
+    }
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    const started = Date.now();
+    const exitCode = await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            // SIGTERM first; graceful shutdown. Codex cleans up its session files
+            // on SIGTERM. We don't escalate to SIGKILL here — if the subprocess
+            // hangs the event loop's own timeout handling will surface it.
+            child.kill('SIGTERM');
+            reject(new CodexTimeoutError(options.timeoutMs));
+        }, options.timeoutMs);
+        timer.unref?.();
+        child.stdout.on('data', (chunk) => stdoutChunks.push(chunk));
+        child.stderr.on('data', (chunk) => stderrChunks.push(chunk));
+        child.on('error', (e) => {
+            clearTimeout(timer);
+            if (isEnoent(e)) {
+                reject(new CodexNotInstalledError());
+                return;
+            }
+            reject(e);
+        });
+        // `close` (not `exit`) fires after BOTH stdio streams drain and the
+        // process has exited. Node can emit `exit` before the final stdout
+        // chunks are flushed on large reviews or slow pipes, causing
+        // `parseCodexJsonl()` to run against a truncated buffer and
+        // misclassify a blocking review as pass. Waiting for `close`
+        // guarantees every agent_message chunk is in `stdoutChunks`.
+        child.on('close', (code, signal) => {
+            clearTimeout(timer);
+            if (code === null && signal !== null) {
+                reject(new CodexSubprocessError(null, signal, Buffer.concat(stderrChunks).toString('utf8')));
+                return;
+            }
+            resolve(code);
+        });
+    });
+    const durationSeconds = (Date.now() - started) / 1000;
+    if (exitCode !== 0 && exitCode !== null) {
+        throw new CodexSubprocessError(exitCode, null, Buffer.concat(stderrChunks).toString('utf8'));
+    }
+    const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+    const { reviewText, eventCount } = parseCodexJsonl(stdout);
+    return { reviewText, eventCount, durationSeconds };
+}
+/**
+ * Parse the JSONL event stream emitted by `codex exec review --json`. We
+ * tolerate partial lines (stream chunks may split mid-object; our caller
+ * gives us the full stdout after exit, but robustness costs nothing).
+ *
+ * The only events we care about are `item.completed` where `item.type ===
+ * "agent_message"` — those carry the review text. Everything else (turn
+ * lifecycle, command_execution telemetry, thread metadata) is counted but
+ * discarded.
+ *
+ * A JSONL line that doesn't parse as JSON is tolerated: we skip it and
+ * continue. Codex occasionally emits warnings outside the JSON envelope
+ * (e.g. macOS xcrun cache errors leak into stderr but can accidentally
+ * land on stdout in misbehaving shells); we treat these as non-fatal.
+ *
+ * We throw `CodexProtocolError` only when the ENTIRE stdout contains zero
+ * parseable events AND zero `agent_message`-carrying items. An empty diff
+ * can legitimately yield zero agent messages with events (thread.started,
+ * turn.started, turn.completed), so we allow zero findings when at least
+ * one event parsed.
+ */
+export function parseCodexJsonl(stdout) {
+    const lines = stdout.split(/\r?\n/).filter((l) => l.length > 0);
+    let reviewText = '';
+    let eventCount = 0;
+    let parsedAny = false;
+    for (const line of lines) {
+        let evt;
+        try {
+            evt = JSON.parse(line);
+        }
+        catch {
+            // Non-JSON line. Could be a shell warning that leaked to stdout. Skip.
+            continue;
+        }
+        parsedAny = true;
+        eventCount += 1;
+        if (evt.type === 'item.completed' &&
+            evt.item !== undefined &&
+            evt.item.type === 'agent_message' &&
+            typeof evt.item.text === 'string') {
+            reviewText = reviewText.length > 0 ? `${reviewText}\n\n${evt.item.text}` : evt.item.text;
+        }
+    }
+    if (!parsedAny && lines.length > 0) {
+        throw new CodexProtocolError('no parseable JSONL events in stdout', lines[0]);
+    }
+    return { reviewText, eventCount };
+}
+function isEnoent(e) {
+    if (e === null || typeof e !== 'object')
+        return false;
+    const code = e.code;
+    return code === 'ENOENT';
+}

package/dist/hooks/push-gate/findings.d.ts ADDED Viewed

@@ -0,0 +1,68 @@
+/**
+ * Finding shape and verdict inference for the stateless push-gate.
+ *
+ * `codex exec review --json` emits JSONL events over stdout. The terminal
+ * event is an `item.completed` with `item.type === "agent_message"` whose
+ * `text` body is human-prose review output using Codex's standard severity
+ * convention:
+ *
+ *   - `[P1]` — blocking. Must be addressed before merge.
+ *   - `[P2]` — concerns. Significant risk the reviewer wants fixed.
+ *   - `[P3]` — nits / low-priority suggestions.
+ *
+ * We extract one `Finding` per severity-marker bullet in the message text
+ * and infer a verdict:
+ *
+ *   - Any `P1`                  → `blocking`
+ *   - Else any `P2`             → `concerns`
+ *   - Else (P3 or nothing)      → `pass`
+ *
+ * This is a text-parse, not a schema consumer. Codex does not expose a
+ * structured review schema through the JSONL event stream today (only
+ * `--output-schema` on plain `codex exec` does that). When the plugin
+ * ecosystem catches up we can swap the parser without touching the gate.
+ */
+export type Severity = 'P1' | 'P2' | 'P3';
+export type Verdict = 'pass' | 'concerns' | 'blocking';
+export interface Finding {
+    severity: Severity;
+    title: string;
+    /** File path, when the marker line carried one. */
+    file?: string;
+    /** Starting line number, when the marker carried `<path>:<line>`. */
+    line?: number;
+    /** Full body of the finding (all lines up to the next marker or EOF). */
+    body: string;
+}
+export interface ReviewSummary {
+    verdict: Verdict;
+    findings: Finding[];
+    /** The raw `agent_message` text, concatenated from every turn. */
+    reviewText: string;
+}
+/**
+ * Parse Codex review prose into structured findings. The parser is
+ * conservative — lines that don't start with a severity marker are folded
+ * into the previous finding's body. Unknown markers (`[P4]`, `[P0]`) are
+ * ignored; we only recognize P1/P2/P3.
+ *
+ * Expected marker shapes, matched line-by-line:
+ *
+ *     - [P1] Title goes here — path/to/file.ts:42
+ *     - [P1] Title — path/to/file.ts
+ *     - [P1] Title
+ *
+ * The dash/bullet prefix is optional (Codex emits both `- [P1]` and bare
+ * `[P1]` depending on model and prompt). Whitespace around the severity
+ * marker is tolerated.
+ */
+export declare function parseFindings(reviewText: string): Finding[];
+/**
+ * Map a finding array to a single verdict. Safe-fail order: any P1 wins,
+ * then any P2, else pass.
+ */
+export declare function inferVerdict(findings: Finding[]): Verdict;
+/**
+ * Convenience: parse + infer in one call.
+ */
+export declare function summarizeReview(reviewText: string): ReviewSummary;

package/dist/hooks/push-gate/findings.js ADDED Viewed

@@ -0,0 +1,142 @@
+/**
+ * Finding shape and verdict inference for the stateless push-gate.
+ *
+ * `codex exec review --json` emits JSONL events over stdout. The terminal
+ * event is an `item.completed` with `item.type === "agent_message"` whose
+ * `text` body is human-prose review output using Codex's standard severity
+ * convention:
+ *
+ *   - `[P1]` — blocking. Must be addressed before merge.
+ *   - `[P2]` — concerns. Significant risk the reviewer wants fixed.
+ *   - `[P3]` — nits / low-priority suggestions.
+ *
+ * We extract one `Finding` per severity-marker bullet in the message text
+ * and infer a verdict:
+ *
+ *   - Any `P1`                  → `blocking`
+ *   - Else any `P2`             → `concerns`
+ *   - Else (P3 or nothing)      → `pass`
+ *
+ * This is a text-parse, not a schema consumer. Codex does not expose a
+ * structured review schema through the JSONL event stream today (only
+ * `--output-schema` on plain `codex exec` does that). When the plugin
+ * ecosystem catches up we can swap the parser without touching the gate.
+ */
+/**
+ * Parse Codex review prose into structured findings. The parser is
+ * conservative — lines that don't start with a severity marker are folded
+ * into the previous finding's body. Unknown markers (`[P4]`, `[P0]`) are
+ * ignored; we only recognize P1/P2/P3.
+ *
+ * Expected marker shapes, matched line-by-line:
+ *
+ *     - [P1] Title goes here — path/to/file.ts:42
+ *     - [P1] Title — path/to/file.ts
+ *     - [P1] Title
+ *
+ * The dash/bullet prefix is optional (Codex emits both `- [P1]` and bare
+ * `[P1]` depending on model and prompt). Whitespace around the severity
+ * marker is tolerated.
+ */
+export function parseFindings(reviewText) {
+    const lines = reviewText.split(/\r?\n/);
+    const out = [];
+    let current = null;
+    // Anchored at the start of a trimmed line — an inline `[P1]` in the
+    // middle of a sentence is not a finding marker. The `^` excludes the
+    // all-text prefix inside the match itself; we trim before testing.
+    const MARKER_RE = /^(?:[-*]\s*)?\[(P[123])\]\s+(.+?)\s*$/;
+    for (const rawLine of lines) {
+        const trimmed = rawLine.trim();
+        const match = MARKER_RE.exec(trimmed);
+        if (match !== null) {
+            if (current !== null)
+                out.push(current);
+            const severity = match[1];
+            const titleWithLocation = match[2] ?? '';
+            const { title, file, line } = splitTitleLocation(titleWithLocation);
+            current = {
+                severity,
+                title,
+                body: rawLine,
+                ...(file !== undefined ? { file } : {}),
+                ...(line !== undefined ? { line } : {}),
+            };
+            continue;
+        }
+        if (current !== null) {
+            current.body = current.body.length > 0 ? `${current.body}\n${rawLine}` : rawLine;
+        }
+    }
+    if (current !== null)
+        out.push(current);
+    return out;
+}
+/**
+ * Split "Title — file.ts:42" or "Title - file.ts" or bare "Title" into
+ * constituent parts. Codex emits an em-dash (`—`) as the separator in the
+ * default review prompt but we also accept `--` and `-` for robustness.
+ */
+function splitTitleLocation(raw) {
+    // Try em-dash first (Codex default), then double-dash, then single-dash
+    // surrounded by whitespace. A plain `-` inside a title (e.g. "pre-push")
+    // is preserved because we require surrounding whitespace.
+    let splitIdx = raw.indexOf(' — ');
+    let sepLen = 3;
+    if (splitIdx < 0) {
+        splitIdx = raw.indexOf(' -- ');
+        sepLen = 4;
+    }
+    if (splitIdx < 0) {
+        const dashMatch = / - /.exec(raw);
+        if (dashMatch !== null) {
+            splitIdx = dashMatch.index;
+            sepLen = 3;
+        }
+    }
+    if (splitIdx < 0) {
+        return { title: raw.trim() };
+    }
+    const title = raw.slice(0, splitIdx).trim();
+    const locationRaw = raw.slice(splitIdx + sepLen).trim();
+    // `path/to/file.ts:42` or `path/to/file.ts:42-48` or bare `path/to/file.ts`.
+    const locMatch = /^([^\s:]+?)(?::(\d+)(?:-\d+)?)?$/.exec(locationRaw);
+    if (locMatch === null) {
+        // Location we can't parse — keep the whole thing as the title so we
+        // don't silently drop it.
+        return { title: raw.trim() };
+    }
+    const file = locMatch[1];
+    const lineStr = locMatch[2];
+    const result = { title };
+    if (file !== undefined && file.length > 0)
+        result.file = file;
+    if (lineStr !== undefined && lineStr.length > 0) {
+        const n = Number.parseInt(lineStr, 10);
+        if (Number.isFinite(n) && n > 0)
+            result.line = n;
+    }
+    return result;
+}
+/**
+ * Map a finding array to a single verdict. Safe-fail order: any P1 wins,
+ * then any P2, else pass.
+ */
+export function inferVerdict(findings) {
+    if (findings.some((f) => f.severity === 'P1'))
+        return 'blocking';
+    if (findings.some((f) => f.severity === 'P2'))
+        return 'concerns';
+    return 'pass';
+}
+/**
+ * Convenience: parse + infer in one call.
+ */
+export function summarizeReview(reviewText) {
+    const findings = parseFindings(reviewText);
+    return {
+        verdict: inferVerdict(findings),
+        findings,
+        reviewText,
+    };
+}

package/dist/hooks/push-gate/halt.d.ts ADDED Viewed

@@ -0,0 +1,28 @@
+/**
+ * HALT kill-switch reader for the push-gate.
+ *
+ * The push-gate is a pure composition (see `./index.ts`). `readHalt()` is the
+ * only side-effectful probe that must run before policy is even consulted —
+ * HALT overrides every other signal, including `review.codex_required: false`.
+ *
+ * `.rea/HALT` is a short plain-text file. Content is not structured — the
+ * first non-empty line is the "reason" we surface to the operator. Absence
+ * of the file means "not halted"; presence means "block every gated
+ * operation until `rea unfreeze`".
+ */
+export interface HaltState {
+    halted: boolean;
+    /** Present only when `halted === true`. Trimmed first line. */
+    reason?: string;
+}
+/**
+ * Read `.rea/HALT` from `baseDir`. Never throws — filesystem errors collapse
+ * to `{ halted: false }` so a corrupted read does not silently block the
+ * operator. The fail-closed posture lives in the caller (`runPushGate`) when
+ * the gate is asked to assess HALT and cannot.
+ *
+ * We explicitly do NOT reuse `src/cli/freeze.ts`'s reader — that one prompts
+ * via clack for unfreeze confirmation. The hook path must stay dependency-
+ * free and deterministic.
+ */
+export declare function readHalt(baseDir: string): HaltState;

package/dist/hooks/push-gate/halt.js ADDED Viewed

@@ -0,0 +1,49 @@
+/**
+ * HALT kill-switch reader for the push-gate.
+ *
+ * The push-gate is a pure composition (see `./index.ts`). `readHalt()` is the
+ * only side-effectful probe that must run before policy is even consulted —
+ * HALT overrides every other signal, including `review.codex_required: false`.
+ *
+ * `.rea/HALT` is a short plain-text file. Content is not structured — the
+ * first non-empty line is the "reason" we surface to the operator. Absence
+ * of the file means "not halted"; presence means "block every gated
+ * operation until `rea unfreeze`".
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Read `.rea/HALT` from `baseDir`. Never throws — filesystem errors collapse
+ * to `{ halted: false }` so a corrupted read does not silently block the
+ * operator. The fail-closed posture lives in the caller (`runPushGate`) when
+ * the gate is asked to assess HALT and cannot.
+ *
+ * We explicitly do NOT reuse `src/cli/freeze.ts`'s reader — that one prompts
+ * via clack for unfreeze confirmation. The hook path must stay dependency-
+ * free and deterministic.
+ */
+export function readHalt(baseDir) {
+    const p = path.join(baseDir, '.rea', 'HALT');
+    if (!fs.existsSync(p)) {
+        return { halted: false };
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(p, 'utf8');
+    }
+    catch {
+        // Unreadable HALT file is treated as "halted with unknown reason" — the
+        // file exists, so the operator intended to halt; we just can't read the
+        // message. Surfacing a generic reason preserves the kill-switch
+        // semantics without silently passing.
+        return { halted: true, reason: 'unknown (HALT file unreadable)' };
+    }
+    const firstLine = raw
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    return {
+        halted: true,
+        reason: firstLine !== undefined && firstLine.length > 0 ? firstLine : 'unknown',
+    };
+}