@bookedsolid/rea 0.1.0 → 0.2.1

package/.husky/commit-msg

@@ -0,0 +1,130 @@
+#!/bin/sh
+# .husky/commit-msg — optionally BLOCKS commits that contain AI attribution
+#
+# OPT-IN: Only enforces when .rea/policy.yaml contains:
+#   block_ai_attribution: true
+#
+# When disabled (default), this hook does nothing — commits work normally.
+# When enabled, rejects (exit 1) commit messages with structural AI attribution
+# markers. This teaches agents to stop including attribution by giving clear
+# feedback on what went wrong.
+#
+# IMPORTANT: This does NOT block casual mentions of AI tools.
+# "Fix Claude API integration" or "Update OpenAI SDK" are fine.
+# What gets blocked are STRUCTURAL ATTRIBUTION MARKERS:
+#
+#   Co-Authored-By with noreply@ emails (dead giveaway)
+#   Co-Authored-By with known AI names (Claude, Copilot, GPT, Gemini, etc.)
+#   "Generated with/by [Tool]" footer lines
+#   Markdown-linked tool names: [Claude Code](...)
+#   Emoji-prefixed attribution: 🤖 Generated...
+#
+# SAFETY: set -e ensures any unexpected error BLOCKS the commit rather than
+# silently passing a message with attribution intact.
+
+set -e
+
+COMMIT_MSG_FILE="$1"
+
+# Validate input
+if [ -z "$COMMIT_MSG_FILE" ]; then
+  echo "ERROR: commit-msg hook received no file path" >&2
+  exit 1
+fi
+if [ ! -f "$COMMIT_MSG_FILE" ]; then
+  echo "ERROR: commit message file not found: $COMMIT_MSG_FILE" >&2
+  exit 1
+fi
+
+# ── Check if attribution blocking is enabled ───────────────────────────────────
+# Look for block_ai_attribution: true in .rea/policy.yaml
+# If not found or not true, exit 0 (normal commit behavior)
+
+POLICY_FILE=".rea/policy.yaml"
+if [ ! -f "$POLICY_FILE" ]; then
+  exit 0
+fi
+
+# Simple grep — no YAML parser dependency needed for a boolean flag
+if ! grep -qE '^block_ai_attribution:[[:space:]]*true' "$POLICY_FILE" 2>/dev/null; then
+  exit 0
+fi
+
+# ── Attribution blocking is enabled — check patterns ───────────────────────────
+
+BLOCKED=0
+MATCHES=""
+
+# Pattern 1: Co-Authored-By with noreply@ email
+if grep -qiE 'Co-Authored-By:.*noreply@' "$COMMIT_MSG_FILE" 2>/dev/null; then
+  BLOCKED=1
+  MATCHES="${MATCHES}$(grep -niE 'Co-Authored-By:.*noreply@' "$COMMIT_MSG_FILE" 2>/dev/null)
+"
+fi
+
+# Pattern 2: Co-Authored-By with known AI assistant names
+if grep -qiE 'Co-Authored-By:.*\b(Claude|Sonnet|Opus|Haiku|Copilot|GPT|ChatGPT|Gemini|Cursor|Codeium|Tabnine|Amazon Q|CodeWhisperer|Devin|Windsurf|Cline|Aider|Anthropic|OpenAI|GitHub Copilot)\b' "$COMMIT_MSG_FILE" 2>/dev/null; then
+  BLOCKED=1
+  MATCHES="${MATCHES}$(grep -niE 'Co-Authored-By:.*\b(Claude|Sonnet|Opus|Haiku|Copilot|GPT|ChatGPT|Gemini|Cursor|Codeium|Tabnine|CodeWhisperer|Devin|Windsurf|Cline|Aider|Anthropic|OpenAI|GitHub Copilot)\b' "$COMMIT_MSG_FILE" 2>/dev/null)
+"
+fi
+
+# Pattern 3: "Generated/Built/Powered with/by [AI Tool]" footer lines
+if grep -qiE '^\s*(Generated|Created|Built|Powered|Authored|Written|Produced)\s+(with|by)\s+(Claude|Copilot|GPT|ChatGPT|Gemini|Cursor|Codeium|Tabnine|CodeWhisperer|Devin|Windsurf|Cline|Aider|AI|an? AI)\b' "$COMMIT_MSG_FILE" 2>/dev/null; then
+  BLOCKED=1
+  MATCHES="${MATCHES}$(grep -niE '^\s*(Generated|Created|Built|Powered|Authored|Written|Produced)\s+(with|by)\s+(Claude|Copilot|GPT|ChatGPT|Gemini|Cursor|Codeium|Tabnine|CodeWhisperer|Devin|Windsurf|Cline|Aider|AI|an? AI)\b' "$COMMIT_MSG_FILE" 2>/dev/null)
+"
+fi
+
+# Pattern 4: Markdown-linked attribution
+if grep -qiE '\[Claude Code\]|\[GitHub Copilot\]|\[ChatGPT\]|\[Gemini\]|\[Cursor\]' "$COMMIT_MSG_FILE" 2>/dev/null; then
+  BLOCKED=1
+  MATCHES="${MATCHES}$(grep -niE '\[Claude Code\]|\[GitHub Copilot\]|\[ChatGPT\]|\[Gemini\]|\[Cursor\]' "$COMMIT_MSG_FILE" 2>/dev/null)
+"
+fi
+
+# Pattern 5: Emoji-prefixed "Generated" lines
+if grep -qE '🤖.*[Gg]enerated' "$COMMIT_MSG_FILE" 2>/dev/null; then
+  BLOCKED=1
+  MATCHES="${MATCHES}$(grep -nE '🤖.*[Gg]enerated' "$COMMIT_MSG_FILE" 2>/dev/null)
+"
+fi
+
+# ── Block or allow ─────────────────────────────────────────────────────────────
+
+if [ "$BLOCKED" -eq 1 ]; then
+  {
+    printf '\n'
+    printf '═══════════════════════════════════════════════════════════════════\n'
+    printf '  COMMIT BLOCKED: AI attribution detected in commit message\n'
+    printf '═══════════════════════════════════════════════════════════════════\n'
+    printf '\n'
+    printf '  Your commit message contains structural AI attribution markers\n'
+    printf '  that must be removed before committing.\n'
+    printf '\n'
+    printf '  Matched line(s):\n'
+    printf '%s' "$MATCHES" | grep -v '^$' | sed 's/^/    /'
+    printf '\n'
+    printf '  What gets BLOCKED (structural attribution):\n'
+    printf '    - Co-Authored-By with AI names or noreply@ emails\n'
+    printf '    - "Generated with/by [AI Tool]" footer lines\n'
+    printf '    - Markdown-linked tool names: [Claude Code](...)\n'
+    printf '    - Emoji attribution: 🤖 Generated...\n'
+    printf '\n'
+    printf '  What is ALLOWED (legitimate references):\n'
+    printf '    - "Fix Claude API integration"\n'
+    printf '    - "Update OpenAI SDK version"\n'
+    printf '    - "Add Copilot config"\n'
+    printf '\n'
+    printf '  Remove the attribution markers and retry your commit.\n'
+    printf '  To disable: set block_ai_attribution: false in .rea/policy.yaml\n'
+    printf '═══════════════════════════════════════════════════════════════════\n'
+    printf '\n'
+  } >&2
+  exit 1
+fi
+
+# Normalize trailing newlines (cosmetic, non-fatal)
+perl -i -0777 -pe 's/\n+$/\n/' "$COMMIT_MSG_FILE" 2>/dev/null || true
+
+exit 0

package/.husky/pre-push

@@ -0,0 +1,128 @@
+#!/bin/sh
+# .husky/pre-push — rea governance gate for terminal-initiated pushes.
+#
+# Mirrors the logic of `.claude/hooks/push-review-gate.sh` but consumes the
+# git pre-push stdin contract directly (one line per refspec:
+#   <local_ref> <local_sha> <remote_ref> <remote_sha>).
+#
+# Minimum viable check — NOT a full replacement for the Claude Code gate:
+#   1. If `.rea/HALT` exists, block.
+#   2. If the push touches a protected path AND policy.review.codex_required
+#      is not explicitly false, require a `codex.review` audit entry for the
+#      HEAD SHA (or REA_SKIP_CODEX_REVIEW env var for a one-off bypass).
+#
+# Escape hatch: REA_SKIP_CODEX_REVIEW=<reason> bypasses the protected-path
+# check. The skip record is appended by `push-review-gate.sh` in the Claude
+# Code path; for terminal pushes, export the variable AND append a skip
+# record manually if you want it in the audit trail.
+#
+# Subshell-safety note: earlier versions piped `echo "$INPUT" | while read`,
+# which ran the loop in a subshell — `exit 1` inside the loop aborted the
+# subshell only, and the script then ran `exit 0` and allowed the push. We
+# now feed the loop with a here-doc so it runs in the main shell, and we
+# track `block_push` in the enclosing scope. Final `exit 1` is reached only
+# if no refspec is blocked; a single blocking refspec propagates correctly.
+
+set -eu
+
+REA_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+if [ -f "${REA_ROOT}/.rea/HALT" ]; then
+  # POSIX `head` does not specify `-c`; use awk for the first line. HALT is
+  # a short reason string, so the first line is enough for display.
+  reason=$(awk 'NR==1 { print; exit }' "${REA_ROOT}/.rea/HALT" 2>/dev/null || printf 'unknown')
+  [ -z "${reason:-}" ] && reason='unknown'
+  printf 'REA HALT: %s\nAll push operations suspended. Run: rea unfreeze\n' "$reason" >&2
+  exit 1
+fi
+
+# Read refspec lines from stdin. Each line: <local_ref> <local_sha> <remote_ref> <remote_sha>
+INPUT=$(cat)
+[ -z "$INPUT" ] && exit 0
+
+# Anchor every alternative so a legitimate file like `docs/hooks-guide.md` or
+# `src/thirdparty/src/policy/loader.c` is not mistaken for a protected path.
+# `^\.claude/hooks/` is included so someone editing the consumer install
+# (which ships alongside rea itself) cannot sneak past the gate.
+PROTECTED_RE='^src/gateway/middleware/|^hooks/|^\.claude/hooks/|^src/policy/|^\.github/workflows/'
+AUDIT_LOG="${REA_ROOT}/.rea/audit.jsonl"
+
+# G11.4 — honor review.codex_required. When explicitly false, skip the
+# protected-path Codex audit requirement entirely (first-class no-Codex
+# mode). Mirrors the logic in `.claude/hooks/push-review-gate.sh`.
+#
+# Fail-closed: if the helper is missing or errors, treat as true. A missing
+# helper means rea is unbuilt — the operator can run `pnpm build` or set
+# REA_SKIP_CODEX_REVIEW for a one-off bypass.
+CODEX_REQUIRED=true
+READ_FIELD_JS="${REA_ROOT}/dist/scripts/read-policy-field.js"
+if [ -f "$READ_FIELD_JS" ]; then
+  field_value=$(REA_ROOT="$REA_ROOT" node "$READ_FIELD_JS" review.codex_required 2>/dev/null || printf '')
+  if [ "$field_value" = "false" ]; then
+    CODEX_REQUIRED=false
+  fi
+fi
+
+block_push=0
+
+# Here-doc feeds the loop without creating a subshell, so `block_push=1`
+# assignments below persist in the enclosing scope and the final `exit`
+# reflects them. A pipeline would run the loop in a subshell and `exit 1`
+# inside it would only abort that subshell — NOT the push — which was a
+# real governance defect in the pre-review version of this file.
+while IFS=' ' read -r local_ref local_sha remote_ref remote_sha; do
+  [ -z "${local_sha:-}" ] && continue
+  # Branch deletion: local_sha is 40 zeros. Skip protected-path check.
+  case "$local_sha" in
+    0000000000000000000000000000000000000000) continue ;;
+  esac
+
+  # Determine merge base. If remote is new (remote_sha is zeros), diff against
+  # the default branch; else against remote_sha.
+  if [ "$remote_sha" = "0000000000000000000000000000000000000000" ]; then
+    default_branch=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')
+    [ -z "${default_branch:-}" ] && default_branch="main"
+    base=$(git merge-base "$default_branch" "$local_sha" 2>/dev/null || printf '')
+  else
+    base=$(git merge-base "$remote_sha" "$local_sha" 2>/dev/null || printf '')
+  fi
+  [ -z "${base:-}" ] && continue
+
+  # Check if the diff touches protected paths.
+  if git diff --name-only "$base" "$local_sha" 2>/dev/null | grep -qE "$PROTECTED_RE"; then
+    if [ "$CODEX_REQUIRED" = "false" ]; then
+      # Policy opts out of the Codex gate. The downstream `.claude/hooks/`
+      # path already records telemetry; terminal pushes skip silently.
+      continue
+    fi
+    if [ -n "${REA_SKIP_CODEX_REVIEW:-}" ]; then
+      printf 'rea: REA_SKIP_CODEX_REVIEW set (%s) — skipping Codex review requirement for %s\n' \
+        "$REA_SKIP_CODEX_REVIEW" "$local_sha" >&2
+      continue
+    fi
+    if [ ! -f "$AUDIT_LOG" ]; then
+      printf 'PUSH BLOCKED: protected paths changed but no audit log found at %s\n' "$AUDIT_LOG" >&2
+      printf '  Run /codex-review on HEAD %s before pushing.\n' "$local_sha" >&2
+      block_push=1
+      continue
+    fi
+    # Require both (a) a `codex.review` tool_name and (b) the exact head_sha
+    # on the same JSONL line. The `codex.review` pattern ends with a closing
+    # quote, so `codex.review.skipped` never satisfies the gate.
+    if ! grep -E '"tool_name":"codex\.review"' "$AUDIT_LOG" 2>/dev/null | \
+         grep -qF "\"head_sha\":\"$local_sha\""; then
+      printf 'PUSH BLOCKED: protected paths changed — /codex-review required for HEAD %s\n' "$local_sha" >&2
+      printf '  Run /codex-review, or set REA_SKIP_CODEX_REVIEW=<reason> to bypass.\n' >&2
+      block_push=1
+      continue
+    fi
+  fi
+done <<HOOK_INPUT_EOF
+$INPUT
+HOOK_INPUT_EOF
+
+if [ "$block_push" -ne 0 ]; then
+  exit 1
+fi
+
+exit 0

package/README.md

@@ -206,15 +206,15 @@ REA ships it out of the box.
 | Phase | Primary model | Codex role | Governance |
 | --- | --- | --- | --- |
 | Plan | Claude Opus | — | Full middleware chain |
-| Pre-implementation review | — | `/codex review` — review the PLAN before code | Audited |
+| Pre-implementation review | — | `/codex:review` — review the PLAN before code | Audited |
 | Build | Claude Opus | — | Full middleware chain |
-| Adversarial review | — | `/codex adversarial-review` on the diff (independent perspective) | Audited, redacted, kill-switched |
-| Pre-merge gate | — | `/codex adversarial-review` re-run; recorded in audit.jsonl | Required status check (recommended) |
+| Adversarial review | — | `/codex:adversarial-review` on the diff (independent perspective) | Audited, redacted, kill-switched |
+| Pre-merge gate | — | `/codex:adversarial-review` re-run; recorded in audit.jsonl | Required status check (recommended) |
 
 Three things make this work:
 
 1. The **`codex-adversarial` agent** in the curated roster wraps
-   `/codex adversarial-review`. The orchestrator delegates to it after
+   `/codex:adversarial-review`. The orchestrator delegates to it after
    any non-trivial change.
 2. The **`/codex-review` slash command** is one of the five shipped
    commands. It produces an audit entry including the request summary,
@@ -260,7 +260,7 @@ disclosure. It is installed as part of the Bash PreToolUse set.
 | --- | --- |
 | `/rea` | Session status — autonomy level, HALT state, last audit entries, next action |
 | `/review` | Invoke the `code-reviewer` agent on current changes |
-| `/codex-review` | Invoke the `codex-adversarial` agent → `/codex adversarial-review` |
+| `/codex-review` | Invoke the `codex-adversarial` agent → `/codex:adversarial-review` |
 | `/freeze` | Prompt for a reason and write `.rea/HALT` |
 | `/halt-check` | Verify every middleware and hook respects HALT |
 

package/agents/codex-adversarial.md

@@ -5,7 +5,7 @@ description: Adversarial code review via the Codex plugin (GPT-5.4). Independent
 
 # Codex Adversarial Reviewer
 
-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.
+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.
 
 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.
 
@@ -30,16 +30,31 @@ You may read additional files in the repo if needed for context, but do so read-
 1. **Check HALT and policy** — read `.rea/policy.yaml`, check `.rea/HALT`. If frozen, stop immediately.
 2. **Validate Codex availability** — if `/codex` is not installed, report and stop. Do not silently fall back to another reviewer.
 3. **Prepare the Codex invocation** — construct the adversarial-review prompt with the diff, commit log, and any relevant context files.
-4. **Invoke `/codex adversarial-review`** — this call flows through the REA middleware chain (audit → kill-switch → tier → policy → redact → injection → execute → result-size-cap).
+4. **Invoke `/codex:adversarial-review`** — this call flows through the REA middleware chain (audit → kill-switch → tier → policy → redact → injection → execute → result-size-cap).
 5. **Parse the Codex output** — extract structured findings.
 6. **Classify findings** by category: security, correctness, edge cases, test gaps, API design, performance.
 7. **Assign verdict**: `pass` (no material findings), `concerns` (findings worth addressing but not blocking), `blocking` (findings that must be fixed before merge).
-8. **Emit audit entry** — the middleware records the invocation automatically, but include a structured summary in your return so `.rea/audit.jsonl` gets:
-   - `tool: "codex-adversarial-review"`
-   - `head_sha`, `target`
-   - `finding_count`
-   - `verdict`
-   - `summary` (one sentence)
+8. **Emit audit entry** — after producing the verdict, append a structured record to `.rea/audit.jsonl` via the public `@bookedsolid/rea/audit` helper. This is what the `push-review-gate.sh` hook greps for on protected-path diffs, so the field names must match exactly:
+
+   ```ts
+   import { appendAuditRecord, CODEX_REVIEW_TOOL_NAME, CODEX_REVIEW_SERVER_NAME, Tier, InvocationStatus } from '@bookedsolid/rea/audit';
+
+   await appendAuditRecord(process.cwd(), {
+     tool_name: CODEX_REVIEW_TOOL_NAME,   // "codex.review"
+     server_name: CODEX_REVIEW_SERVER_NAME, // "codex"
+     status: InvocationStatus.Allowed,
+     tier: Tier.Read,
+     metadata: {
+       head_sha: '<git rev-parse HEAD>',
+       target:   '<base ref or SHA diffed against>',
+       finding_count: <total>,
+       verdict:  'pass' | 'concerns' | 'blocking' | 'error',
+       summary:  '<one sentence>',
+     },
+   });
+   ```
+
+   If the Codex plugin call itself flowed through rea middleware (the proxy case), the middleware also writes an envelope record — that is fine, the two are complementary: the agent-emitted record carries the semantic verdict, the middleware record carries the chain integrity proof for the underlying tool call.
 
 ## Finding Shape
 

package/commands/codex-review.md

@@ -11,7 +11,7 @@ allowed-tools:
 
 # /codex-review — Adversarial Review via Codex
 
-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.
+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.
 
 ## Why this exists
 
@@ -52,7 +52,7 @@ Invoke the `codex-adversarial` agent with:
 - The commit log summary
 - The full diff text
 
-The agent wraps `/codex adversarial-review` and returns structured findings.
+The agent wraps `/codex:adversarial-review` and returns structured findings.
 
 ## Step 3 — Record to audit log
 

package/dist/audit/append.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Public audit-append helper — exported from `@bookedsolid/rea/audit`.
+ *
+ * This is the single hash-chain entry point for external consumers (the
+ * `codex-adversarial` agent, Helix's `helix.plan` / `helix.apply` events, and
+ * any future plugin that needs to emit structured events through rea's audit
+ * trail). Consumers own their event semantics; rea owns the contract.
+ *
+ * ## Guarantees
+ *
+ * - Reads the last JSONL line of `.rea/audit.jsonl` to seed `prev_hash`.
+ * - Computes a SHA-256 hash over the serialized record minus `hash`.
+ * - Appends a single `\n`-terminated JSON line, then fsyncs the file.
+ * - Creates `.rea/` and `audit.jsonl` on first use.
+ * - Never throws on stat/missing-file conditions; only throws on write failure
+ *   (the caller decides how to react).
+ *
+ * ## Concurrency
+ *
+ * The helper serializes writes per-process via a module-scoped queue keyed by
+ * the resolved audit-file path. Cross-process concurrency on the same file is
+ * NOT handled here — writers in separate processes can interleave and break
+ * the chain. The current deployment targets (rea's own governance hooks, the
+ * Codex agent, Helix) all funnel through a single process at a time. If that
+ * changes, add an exclusive-lock file (`audit.jsonl.lock`) before lifting this
+ * restriction. Documented risk; do not silently expand the guarantee.
+ *
+ * @see {@link file://./codex-event.ts} for the canonical `codex.review` shape.
+ */
+import { Tier, InvocationStatus } from '../policy/types.js';
+import type { AuditRecord } from '../gateway/middleware/audit-types.js';
+/**
+ * Input shape for {@link appendAuditRecord}. All fields except `tool_name`
+ * and `server_name` are optional; sensible defaults are applied to keep the
+ * hash chain uniform across event types.
+ */
+export interface AppendAuditInput {
+    tool_name: string;
+    server_name: string;
+    status?: InvocationStatus;
+    tier?: Tier;
+    autonomy_level?: string;
+    session_id?: string;
+    duration_ms?: number;
+    error?: string;
+    redacted_fields?: string[];
+    metadata?: Record<string, unknown>;
+    /** ISO-8601 timestamp; defaults to `new Date().toISOString()` */
+    timestamp?: string;
+}
+/**
+ * Append a structured audit record to `${baseDir}/.rea/audit.jsonl` with a
+ * hash chained against the tail of the existing log.
+ *
+ * @param baseDir - Repo/project root (the directory that contains `.rea/`).
+ * @param input   - Event data. `tool_name` and `server_name` are required.
+ * @returns The full written record, including the computed `hash`.
+ */
+export declare function appendAuditRecord(baseDir: string, input: AppendAuditInput): Promise<AuditRecord>;
+export type { AuditRecord } 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';

package/dist/audit/append.js

@@ -0,0 +1,189 @@
+/**
+ * Public audit-append helper — exported from `@bookedsolid/rea/audit`.
+ *
+ * This is the single hash-chain entry point for external consumers (the
+ * `codex-adversarial` agent, Helix's `helix.plan` / `helix.apply` events, and
+ * any future plugin that needs to emit structured events through rea's audit
+ * trail). Consumers own their event semantics; rea owns the contract.
+ *
+ * ## Guarantees
+ *
+ * - Reads the last JSONL line of `.rea/audit.jsonl` to seed `prev_hash`.
+ * - Computes a SHA-256 hash over the serialized record minus `hash`.
+ * - Appends a single `\n`-terminated JSON line, then fsyncs the file.
+ * - Creates `.rea/` and `audit.jsonl` on first use.
+ * - Never throws on stat/missing-file conditions; only throws on write failure
+ *   (the caller decides how to react).
+ *
+ * ## Concurrency
+ *
+ * The helper serializes writes per-process via a module-scoped queue keyed by
+ * the resolved audit-file path. Cross-process concurrency on the same file is
+ * NOT handled here — writers in separate processes can interleave and break
+ * the chain. The current deployment targets (rea's own governance hooks, the
+ * Codex agent, Helix) all funnel through a single process at a time. If that
+ * changes, add an exclusive-lock file (`audit.jsonl.lock`) before lifting this
+ * restriction. Documented risk; do not silently expand the guarantee.
+ *
+ * @see {@link file://./codex-event.ts} for the canonical `codex.review` shape.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { Tier, InvocationStatus } from '../policy/types.js';
+const GENESIS_HASH = '0'.repeat(64);
+const REA_DIR = '.rea';
+const AUDIT_FILE = 'audit.jsonl';
+/** Per-file write queue to preserve linear hash-chain order within a process. */
+const writeQueues = new Map();
+/**
+ * Resolve a baseDir to a stable, process-wide canonical form. Two callers that
+ * pass `'.'` and `process.cwd()` for the same project must land on the same
+ * queue key — otherwise the per-process serialization promise in this module's
+ * header is broken and concurrent appends can interleave, corrupting the hash
+ * chain.
+ *
+ * Strategy:
+ *   1. `path.resolve(baseDir)` — makes relative paths absolute against the
+ *      CURRENT `process.cwd()`. This must run every call; caching by the raw
+ *      input key would return a stale absolute path after a `process.chdir()`,
+ *      which is how rea's audit helper gets used across repos in long-lived
+ *      processes. (See finding R2-3.)
+ *   2. Best-effort `fs.realpath(resolvedBase)` — unwraps symlinks (e.g. macOS
+ *      `/tmp` → `/private/tmp`). If it throws (directory doesn't exist yet on
+ *      first write, permission error, etc.), fall back to the `path.resolve`
+ *      result. The directory will be created in `doAppend` via `mkdir`.
+ *
+ * NOTE: no caching here. `path.resolve` is microseconds and `fs.realpath` is a
+ * single `lstat` syscall; audit append is not a hot path. A previous revision
+ * keyed a cache by the raw `baseDir` string, which returned stale absolute
+ * paths across `chdir` — a brand-new regression worse than the cost it saved.
+ * If a future profiler demands caching, key it by `path.resolve(baseDir)` and
+ * only cache already-absolute inputs.
+ */
+async function resolveBaseDir(baseDir) {
+    const absolute = path.resolve(baseDir);
+    try {
+        return await fs.realpath(absolute);
+    }
+    catch {
+        // Directory doesn't exist yet, or realpath isn't permitted here. Fall back
+        // to the path.resolve'd absolute form — still stable per input, still
+        // collapses `'.' === cwd` via the absolute path.
+        return absolute;
+    }
+}
+function computeHash(record) {
+    return crypto.createHash('sha256').update(JSON.stringify(record)).digest('hex');
+}
+async function readLastHash(auditFile) {
+    let data;
+    try {
+        data = await fs.readFile(auditFile, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return GENESIS_HASH;
+        throw err;
+    }
+    // Walk the file backwards by newline — the last non-empty line is the tail.
+    const trimmed = data.replace(/\n+$/, '');
+    if (trimmed.length === 0)
+        return GENESIS_HASH;
+    const lastNewline = trimmed.lastIndexOf('\n');
+    const lastLine = lastNewline === -1 ? trimmed : trimmed.slice(lastNewline + 1);
+    try {
+        const parsed = JSON.parse(lastLine);
+        if (typeof parsed.hash === 'string' && parsed.hash.length === 64) {
+            return parsed.hash;
+        }
+    }
+    catch {
+        // Corrupt tail line — fall through to genesis. The operator will see this
+        // because the chain verify tool (future) will flag the break point. We do
+        // not throw: refusing to append would mask every subsequent event.
+    }
+    return GENESIS_HASH;
+}
+async function fsyncFile(filePath) {
+    let fh;
+    try {
+        fh = await fs.open(filePath, 'r');
+        await fh.sync();
+    }
+    catch {
+        // fsync failure is not fatal — durability is best-effort here; the write
+        // itself already succeeded.
+    }
+    finally {
+        if (fh)
+            await fh.close();
+    }
+}
+async function doAppend(resolvedBase, input) {
+    const reaDir = path.join(resolvedBase, REA_DIR);
+    const auditFile = path.join(reaDir, AUDIT_FILE);
+    await fs.mkdir(reaDir, { recursive: true });
+    const prevHash = await readLastHash(auditFile);
+    const now = input.timestamp ?? new Date().toISOString();
+    const recordBase = {
+        timestamp: now,
+        session_id: input.session_id ?? 'external',
+        tool_name: input.tool_name,
+        server_name: input.server_name,
+        tier: input.tier ?? Tier.Read,
+        status: input.status ?? InvocationStatus.Allowed,
+        autonomy_level: input.autonomy_level ?? 'unknown',
+        duration_ms: input.duration_ms ?? 0,
+        prev_hash: prevHash,
+    };
+    if (input.error)
+        recordBase.error = input.error;
+    if (input.redacted_fields?.length)
+        recordBase.redacted_fields = input.redacted_fields;
+    if (input.metadata && Object.keys(input.metadata).length > 0) {
+        recordBase.metadata = input.metadata;
+    }
+    const hash = computeHash(recordBase);
+    const record = { ...recordBase, hash };
+    const line = JSON.stringify(record) + '\n';
+    await fs.appendFile(auditFile, line);
+    await fsyncFile(auditFile);
+    return record;
+}
+/**
+ * Append a structured audit record to `${baseDir}/.rea/audit.jsonl` with a
+ * hash chained against the tail of the existing log.
+ *
+ * @param baseDir - Repo/project root (the directory that contains `.rea/`).
+ * @param input   - Event data. `tool_name` and `server_name` are required.
+ * @returns The full written record, including the computed `hash`.
+ */
+export async function appendAuditRecord(baseDir, input) {
+    // Canonicalize the baseDir so every caller targeting the same on-disk
+    // directory lands on the same queue key, regardless of whether they passed
+    // `'.'`, `process.cwd()`, or a symlinked path. Without this, two callers in
+    // the same process can bypass the serialization promise and interleave
+    // appends — corrupting the hash chain (finding #6).
+    const resolvedBase = await resolveBaseDir(baseDir);
+    const key = path.join(resolvedBase, REA_DIR, AUDIT_FILE);
+    const prev = writeQueues.get(key) ?? Promise.resolve();
+    let record;
+    const next = prev
+        .catch(() => {
+        /* previous write's error is owned by that caller */
+    })
+        .then(async () => {
+        record = await doAppend(resolvedBase, input);
+    });
+    writeQueues.set(key, next.finally(() => {
+        // Keep the queue lean — once this write resolves, drop the reference
+        // if nothing newer is chained behind it.
+        if (writeQueues.get(key) === next)
+            writeQueues.delete(key);
+    }));
+    await next;
+    return record;
+}
+export { Tier, InvocationStatus } from '../policy/types.js';
+export { CODEX_REVIEW_TOOL_NAME, CODEX_REVIEW_SERVER_NAME, } from './codex-event.js';

package/dist/audit/codex-event.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Single source of truth for the `codex.review` audit event shape.
+ *
+ * Both the `codex-adversarial` agent (via `@bookedsolid/rea/audit`) and the
+ * `push-review-gate.sh` shell hook depend on these constants. If either drifts,
+ * the push gate will silently stop detecting Codex reviews. Keep them in lockstep.
+ *
+ * The shell gate parses audit lines with `jq` and matches on the top-level
+ * `tool_name` plus `metadata.{head_sha, verdict}` — substring greps against the
+ * raw JSON were retired because they were forgeable via arbitrary `metadata`
+ * payloads. If you rename any of those fields, update both this file and the
+ * `jq -e` predicate in `hooks/push-review-gate.sh`.
+ */
+export declare const CODEX_REVIEW_TOOL_NAME = "codex.review";
+export declare const CODEX_REVIEW_SERVER_NAME = "codex";
+export type CodexVerdict = 'pass' | 'concerns' | 'blocking' | 'error';
+export interface CodexReviewMetadata {
+    /** git rev-parse HEAD at the time of the review */
+    head_sha: string;
+    /** base ref or SHA the review diffed against (typically `main` or a merge-base) */
+    target: string;
+    /** total count of findings surfaced by Codex */
+    finding_count: number;
+    /** verdict classification — see {@link CodexVerdict} */
+    verdict: CodexVerdict;
+    /** optional one-sentence summary from the reviewer */
+    summary?: string;
+}

package/dist/audit/codex-event.js

@@ -0,0 +1,15 @@
+/**
+ * Single source of truth for the `codex.review` audit event shape.
+ *
+ * Both the `codex-adversarial` agent (via `@bookedsolid/rea/audit`) and the
+ * `push-review-gate.sh` shell hook depend on these constants. If either drifts,
+ * the push gate will silently stop detecting Codex reviews. Keep them in lockstep.
+ *
+ * The shell gate parses audit lines with `jq` and matches on the top-level
+ * `tool_name` plus `metadata.{head_sha, verdict}` — substring greps against the
+ * raw JSON were retired because they were forgeable via arbitrary `metadata`
+ * payloads. If you rename any of those fields, update both this file and the
+ * `jq -e` predicate in `hooks/push-review-gate.sh`.
+ */
+export const CODEX_REVIEW_TOOL_NAME = 'codex.review';
+export const CODEX_REVIEW_SERVER_NAME = 'codex';