@bookedsolid/rea 0.8.0 → 0.9.1

package/README.md

@@ -2,14 +2,15 @@
 
 **Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review.**
 
-[![npm version](https://img.shields.io/badge/npm-pending-lightgrey)](https://www.npmjs.com/package/@bookedsolid/rea)
-[![CI](https://img.shields.io/badge/ci-pending-lightgrey)](https://github.com/bookedsolidtech/rea/actions)
-[![provenance](https://img.shields.io/badge/npm%20provenance-pending-lightgrey)](https://docs.npmjs.com/generating-provenance-statements)
+[![npm version](https://img.shields.io/npm/v/%40bookedsolid%2Frea?color=cb3837&label=npm)](https://www.npmjs.com/package/@bookedsolid/rea)
+[![CI](https://github.com/bookedsolidtech/rea/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bookedsolidtech/rea/actions/workflows/ci.yml)
+[![npm provenance](https://img.shields.io/badge/npm%20provenance-attested-blue?logo=npm)](https://docs.npmjs.com/generating-provenance-statements)
 [![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 [![DCO](https://img.shields.io/badge/DCO-required-green)](https://developercertificate.org/)
 [![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
 
-> Status: 0.0.x, pre-release. Badges are placeholders until the first publish.
+> Status: `0.9.x` — published to npm with provenance. See
+> [CHANGELOG.md](./CHANGELOG.md) for the per-release history.
 
 ---
 
@@ -31,18 +32,38 @@ Node 22+ and pnpm 9+ required.
 REA is a governance layer for Claude Code. It is a single npm package that
 ships four things:
 
-1. A **hook layer** — 11 shell scripts wired into Claude Code's `PreToolUse`
-   and `PostToolUse` events. Hooks enforce secret scanning, dangerous-command
-   interception, blocked-path protection, settings protection, attribution
-   rejection, and commit/push review gates.
+1. A **hook layer** — 14 shell scripts total. 12 are registered in the
+   shipped `.claude/settings.json` and fire on Claude Code's `PreToolUse`
+   / `PostToolUse` events (secret scanning, dangerous-command
+   interception, blocked-path protection, settings protection,
+   attribution rejection, env-file protection, disclosure-policy
+   routing, dependency audit, changeset security, architecture advisory,
+   PR-issue-link advisory, and the Claude-Code push-review adapter).
+   One more shipped hook, `commit-review-gate.sh`, is a Claude
+   `PreToolUse: Bash` hook that matches `git commit` — it is shipped
+   ready-to-wire but intentionally NOT registered in the default
+   `.claude/settings.json`, so operators who want commit-time review can
+   opt in by adding a rule. The final script,
+   `push-review-gate-git.sh`, is a thin native-git adapter that sources
+   `hooks/_lib/push-review-core.sh` (the same shared core used by the
+   Claude-Code push-review adapter), so a fix to the push-review logic
+   lands in one place. It ships for consumers who manually configure
+   a wrapper-based `.husky/pre-push` (and as scaffolding for a future
+   installer revision). The default `rea init` installer emits a
+   standalone inline `.husky/pre-push` body instead of wiring the
+   adapter — see the Hooks section for details.
 2. A **gateway layer** — an MCP server (`rea serve`) that proxies downstream
    MCP servers through a middleware chain. Every tool call — native or
    proxied — is classified, policy-checked, redacted, audited, and
-   size-capped before it executes.
-3. A **policy runtime** — `.rea/policy.yaml` with strict zod-validated
+   size-capped before it executes. The gateway also supervises downstream
+   child processes: unexpected deaths are detected eagerly, the circuit
+   breaker never reuses a zombie client, and a `SESSION_BLOCKER` audit
+   event fires when a downstream crosses the per-session failure threshold.
+3. A **policy runtime** — `.rea/policy.yaml` with a strict zod-validated
    schema. Defines autonomy level, a hard ceiling (`max_autonomy_level`),
-   blocked paths, attribution rules, context protection, and optional
-   Discord notification webhook.
+   blocked paths, attribution rules, context protection, redaction and
+   injection tuning, review/cache knobs, and an optional Discord
+   notification webhook.
 4. A **kill switch** — `.rea/HALT` is a single file. If it exists, every
    tool call is denied at the middleware and hook layers. Use
    `rea freeze --reason "..."` to create it and `rea unfreeze --reason "..."`
@@ -69,7 +90,8 @@ to build a separate package that composes with REA.
   no `rea stop`, no systemd unit. A short-lived `.rea/serve.pid`
   breadcrumb is written at startup so `rea status` can detect a live
   gateway — it is removed on graceful shutdown and never used for
-  locking or lifecycle management.
+  locking or lifecycle management. A per-session `.rea/serve.state.json`
+  snapshot accompanies it for live per-downstream introspection.
 - **Not a hosted service.** There is no REA Cloud, no SaaS tier, no
   multi-token workstreams, no workload isolation platform.
 - **Not a 70-agent roster.** 10 curated agents ship in the package. Four
@@ -130,10 +152,16 @@ its own.
 rea doctor
 ```
 
-`rea doctor` checks hook coverage, policy parse, husky commit-msg hook
-install, `.mcp.json` gateway wiring, Codex plugin availability, and the
-integrity of the audit hash chain. It returns a pass/fail summary with
-specific remediation hints.
+`rea doctor` checks `.rea/` directory presence, policy parse, registry
+parse, curated-agent presence, hook coverage, `.claude/settings.json`
+wiring, commit-msg / pre-push git hooks, Codex CLI + agent availability
+(when `codex_required: true`), and the TOFU fingerprint store. It
+returns a pass/fail summary with specific remediation hints. In non-git
+directories (knowledge repos, docs-only projects) the commit-msg and
+pre-push checks are skipped cleanly — REA governs policy and injection
+detection there, not pushes. Audit hash-chain integrity is verified by
+a separate command — `rea check` (on-disk tail) or the full replay
+verifier — not by `rea doctor`.
 
 ### 4. Watch the running gateway
 
@@ -144,10 +172,31 @@ rea status --json       # JSON — pipe to jq
 
 `rea status` is the live-process view. It reads the pidfile written by
 `rea serve`, verifies the pid is alive, and surfaces the session id,
-policy summary (profile, autonomy, HALT state), and audit stats (lines,
-last timestamp, whether the tail record's hash looks well-formed). Use
-`rea check` when you want the pure on-disk view without probing for a
-live process.
+policy summary (profile, autonomy, HALT state), audit stats (lines,
+last timestamp, whether the tail record's hash looks well-formed), and
+— as of 0.9.0 — a **per-downstream live block** sourced from
+`.rea/serve.state.json`. Each downstream entry includes:
+
+| Field                       | Type                                 | Meaning                                                         |
+| --------------------------- | ------------------------------------ | --------------------------------------------------------------- |
+| `name`                      | string                               | Registry server name                                            |
+| `connected`                 | boolean                              | MCP client currently holds an open stdio transport              |
+| `healthy`                   | boolean                              | Gateway considers the server safe to route calls to             |
+| `circuit_state`             | `closed` \| `open` \| `half-open`    | Current breaker position                                        |
+| `retry_at`                  | ISO timestamp \| `null`              | Next allowed half-open probe, when `open`                       |
+| `last_error`                | string \| `null`                     | Bounded, redacted diagnostic from the most recent failure       |
+| `tools_count`               | integer \| `null`                    | Tool count from the last successful `tools/list`                |
+| `open_transitions`          | integer                              | Cumulative circuit-open events in this session                  |
+| `session_blocker_emitted`   | boolean                              | Whether `SESSION_BLOCKER` has fired for this server yet         |
+
+`.rea/serve.state.json` is the authoritative live source — it is written
+atomically (temp+rename) on every circuit transition and supervisor
+event, debounced through a 250 ms trailing timer so a flap storm can't
+spam disk. State files written by a pre-0.9.0 gateway degrade gracefully:
+`downstreams` surfaces as `null` with a hint to upgrade.
+
+Use `rea check` when you want the pure on-disk view (policy + HALT +
+tail audit) without probing for a live process.
 
 ### 5. Optional Prometheus `/metrics` endpoint
 
@@ -172,6 +221,39 @@ Set `REA_LOG_LEVEL=debug` for verbose gateway logs; the default is
 `info`. Records are JSON lines on a non-TTY stderr and pretty-printed
 on an interactive terminal.
 
+### 6. Ask the gateway how it's doing — `__rea__health`
+
+The gateway advertises a single built-in tool, `__rea__health`, in
+every `listTools` response regardless of downstream state. Calling it
+returns a snapshot of gateway version, uptime, HALT state, policy
+summary, and per-downstream health. The handler **short-circuits the
+middleware chain** — it is callable under HALT and at any autonomy
+level — because it is the tool an operator reaches for when everything
+else is frozen. Every invocation still writes an audit record.
+
+The wire response is **sanitized by default**: `halt_reason` and
+`downstreams[].last_error` surface as `null`. Full diagnostic detail
+lives in the audit record's metadata (`halt_reason`,
+`downstream_errors[]`) — local disk, hash-chained, not
+LLM-reachable — which is the right sink for trusted-operator text.
+
+Operators who genuinely need error strings on the MCP wire can opt in:
+
+```yaml
+# .rea/policy.yaml
+gateway:
+  health:
+    expose_diagnostics: true
+```
+
+Opt-in mode still runs the full sanitizer pass: `redactSecrets` replaces
+known secret patterns with `[REDACTED:*]`, `classifyInjection` replaces
+any non-`clean` diagnostic string (verdicts `suspicious` or
+`likely_injection`) with the exported `INJECTION_REDACTED_PLACEHOLDER`
+token — the literal string `<redacted: suspected injection>` — and
+oversize values are bounded before scanning so an adversarial downstream
+can't DoS the tool with a multi-megabyte error.
+
 ## Architecture
 
 ### Middleware chain
@@ -192,12 +274,12 @@ tool call
 │ rate-limit         — token bucket per server      │
 │ circuit-breaker    — trip on downstream failure   │
 │ redact (args)      — secrets in arguments         │
-│ injection          — prompt-injection heuristics  │
 │                                                   │
 │ ==== EXECUTE ====                                 │
 │                                                   │
-│ redact (result)    — secrets in result            │
 │ result-size-cap    — bounded response             │
+│ redact (result)    — secrets in result            │
+│ injection          — prompt-injection in result   │
 │ audit.exit         — hash-chained record close    │
 └───────────────────────────────────────────────────┘
     │
@@ -209,14 +291,104 @@ result
 from policy. Policy is re-read on every invocation — any edit to
 `policy.yaml` takes effect on the next tool call.
 
-### Hook layer
+The `__rea__health` meta-tool is the one documented exception: it
+short-circuits the chain (see §6 above) and writes an audit record from
+the short-circuit handler itself.
+
+### Gateway supervisor
+
+Downstream MCP servers run as child processes over stdio. The
+`DownstreamConnection` wrapper wires the SDK `StdioClientTransport`'s
+`onclose` + `onerror` callbacks, so an unexpected child death — OS
+OOM-kill, unhandled exception in the child, stdio pipe error outside a
+caller-initiated close — is detected **eagerly**: the client and
+transport are nulled before the next `callTool` tries to use them. The
+following call forces a genuine reconnect rather than invoking through a
+stale handle.
+
+"Not connected" errors from the SDK (the in-flight fallback) are
+promoted to the same respawn path with the same eager invalidation.
+A 30-second flapping guard refuses a second reconnect that lands too
+quickly after the previous one — the child is clearly unhealthy and the
+circuit breaker is a better place to handle it.
+
+`SessionBlockerTracker` subscribes to circuit-breaker
+`onStateChange` events and counts circuit-open transitions per
+`(session_id, server_name)`. Once the threshold (default: 3) is
+crossed, exactly one `SESSION_BLOCKER` audit record is appended and a
+LOUD structured log line is emitted — subsequent opens do not re-fire
+until recovery (a transition to `closed`) re-arms the emit. A new
+session (new `rea serve` process) drops every counter and starts fresh.
+
+### Live state
+
+`.rea/serve.state.json` is the on-disk live snapshot. It is written
+once at boot and again on every circuit transition or supervisor event,
+debounced through a 250 ms trailing timer and flushed atomically via
+temp-file + rename. The snapshot carries a `session_id` (boot-time
+ownership key) and `owner_pid`; a newly-started `rea serve` whose
+predecessor crashed without cleanup can detect the abandoned file and
+take over ownership rather than stalling forever. `rea status` is a
+read-only consumer of this file.
+
+### Downstream environment safety
+
+`rea serve` does **not** forward `process.env` wholesale to downstream
+children. Each child gets:
+
+1. A fixed allowlist of neutral OS vars (`PATH`, `HOME`, `TZ`,
+   `NODE_OPTIONS`, …).
+2. Any names opted into via `registry.yaml#servers[].env_passthrough` —
+   the schema refuses secret-looking names (`*_TOKEN`, `*_KEY`,
+   `*_SECRET`, …), so secrets must be named explicitly.
+3. Values from the registry's `env:` mapping, which may contain
+   `${VAR}` placeholders resolved against the host environment
+   (0.3.0). Secret-looking values are redacted in logs by default.
+   A `${VAR}` whose host variable is unset is treated as fatal — the
+   downstream is marked unhealthy rather than handed an unresolved
+   placeholder.
 
-Hooks are shell scripts wired into `.claude/settings.json`. They run at
-Claude Code tool-invocation time, independently of the gateway. Both
-layers fail closed. Bypassing one does not disable the other.
+### Hook layer
 
-Every hook sources `hooks/_lib/halt-check.sh` and `hooks/_lib/policy-read.sh`
-at the top of the script. Every hook uses `set -euo pipefail`.
+Hooks are shell scripts. 14 ship in the package; 12 are wired into
+the default `.claude/settings.json` and run at Claude Code
+tool-invocation time, independently of the gateway. The remaining
+two (`commit-review-gate.sh` and `push-review-gate-git.sh`) ship
+ready-to-wire but are not registered by default — see "What REA is"
+above and the inventory table at the end of this section for the full
+picture. Both layers (hooks and the gateway middleware) fail closed.
+Bypassing one does not disable the other.
+
+Every hook uses `set -euo pipefail` (or `set -uo pipefail` for the
+ones that process stdin JSON) and performs a HALT check near the top.
+The review-gate hooks (`push-review-gate.sh`, `push-review-gate-git.sh`,
+`commit-review-gate.sh`) additionally anchor `REA_ROOT` to their own
+on-disk location (BUG-012 fix, 0.6.2) — for those hooks,
+`CLAUDE_PROJECT_DIR` is accepted only as an advisory signal because it
+is caller-controlled. The remaining hooks (e.g. `secret-scanner.sh`,
+`settings-protection.sh`, `blocked-paths-enforcer.sh`,
+`dangerous-bash-interceptor.sh`) still derive `REA_ROOT` from
+`${CLAUDE_PROJECT_DIR:-$(pwd)}`; extending the script-anchor idiom to
+those hooks is tracked as an open hardening item. Cross-repo
+invocations (running a review-gate hook from a consumer project that
+is not the rea install) short-circuit cleanly using
+`git --git-common-dir` comparison (0.6.1).
+
+The two push-review adapters that ship in `hooks/` share a single
+implementation core at `hooks/_lib/push-review-core.sh` (0.7.0 BUG-008
+cleanup) so a fix lands in one place: `push-review-gate.sh` consumes
+Claude-Code PreToolUse JSON and is what `rea init` copies to
+`.claude/hooks/`; `push-review-gate-git.sh` consumes git's native
+`.husky/pre-push` refspec lines and is shipped for consumers who wire
+a wrapper-based `.husky/pre-push` that execs it directly. The default
+`rea init` installer does NOT currently emit that wrapper — it writes
+a standalone inline gate body as `.husky/pre-push` (source of truth:
+`src/cli/install/pre-push.ts`). The native-git adapter and the
+inline installer currently implement the same protected-path logic
+separately; unifying the husky installer on the adapter is tracked as
+follow-up hardening. `commit-review-gate.sh` is a standalone Claude
+`PreToolUse: Bash` hook that matches `git commit`; it does not source
+the push-review core.
 
 ### Slash commands
 
@@ -228,9 +400,13 @@ during `rea init`.
 Ten curated agents ship in the package: `rea-orchestrator`, `code-reviewer`,
 `codex-adversarial`, `security-engineer`, `accessibility-engineer`,
 `typescript-specialist`, `frontend-specialist`, `backend-engineer`,
-`qa-engineer`, `technical-writer`. Four profiles
-(`client-engagement`, `bst-internal`, `lit-wc`, `open-source`) layer
-additional specialists on top.
+`qa-engineer`, `technical-writer`. Profiles
+(`client-engagement`, `bst-internal`, `bst-internal-no-codex`,
+`lit-wc`, `open-source`, `open-source-no-codex`, `minimal`) layer
+additional specialists on top. The `-no-codex` variants match their
+parents but default `review.codex_required: false` so teams without a
+Codex CLI on the bench get a first-class opt-out rather than relying on
+`REA_SKIP_CODEX_REVIEW`.
 
 The orchestrator is the single entry point for non-trivial tasks. The
 CLAUDE.md template installed by `rea init` instructs the host agent:
@@ -259,9 +435,38 @@ Three things make this work:
 2. The **`/codex-review` slash command** is one of the five shipped
    commands. It produces an audit entry including the request summary,
    response summary, and pass/fail signal.
-3. The **`push-review-gate.sh` hook** checks for a recent `/codex-review`
-   audit entry on the current branch and warns (does not block) if none
-   is present.
+3. The **`push-review-gate.sh` hook** blocks (exit 2) every protected-path
+   push that does not carry a matching `codex.review` audit entry for the
+   pushed `head_sha` with a `verdict` of `pass` or `concerns`. The only
+   other way through the protected-path branch is an active Codex-only
+   waiver (`REA_SKIP_CODEX_REVIEW=<reason>`, 0.8.0 narrowing). For
+   **non-protected-path** pushes the gate runs a separate review-cache
+   lookup — this is where the cache predicate and pushed-ref key
+   hardening live. The cache-hit predicate requires
+   `.hit == true and .result == "pass"` (0.8.0 hardening — a cached
+   `fail` verdict no longer satisfies the gate), and the cache key is
+   derived from the **pushed source ref** (from pre-push stdin) rather
+   than the checkout branch, so `git push origin hotfix:main` from a
+   `feature` checkout correctly looks up the `hotfix` cache entry.
+
+### Codex-only waiver semantics (0.8.0)
+
+Through 0.7.0, `REA_SKIP_CODEX_REVIEW=<reason>` short-circuited the
+**entire** push-review gate — operators reached for it to silence a
+transient Codex outage and accidentally bypassed HALT, the cross-repo
+guard, and the general push-review gate. 0.8.0 narrows it to what the
+name implies: the waiver satisfies **only** the protected-path Codex
+audit requirement. HALT, cross-repo guard, ref-resolution failures, and
+push-review-cache misses still block. The skip audit record is still
+named `codex.review.skipped` and still fails the `codex.review` jq
+predicate — skipping a review is not a review.
+
+For the previous whole-gate bypass, use `REA_SKIP_PUSH_REVIEW=<reason>`
+(unchanged, 0.5.0). It writes `push.review.skipped` with an
+`os_identity` sub-object (uid, whoami, hostname, pid, ppid, tty, ci)
+so auditors can distinguish a real operator from a forged git-config
+actor, and refuses on CI runners unless the policy opts in via
+`review.allow_skip_in_ci: true`.
 
 Codex responses are treated as untrusted input. They flow through the
 `redact` and `injection` middleware on return — same treatment as any
@@ -269,30 +474,32 @@ other downstream tool result. Codex never receives `.rea/policy.yaml`
 content in its prompts; Codex reviews diffs, not policy.
 
 If Codex is not installed, `rea doctor` warns with a one-line install
-hint. REA does not require Codex to function, but the default workflow
-assumes it.
+hint. REA does not require Codex to function — the `bst-internal-no-codex`
+and `open-source-no-codex` profiles disable the requirement entirely,
+and `ClaudeSelfReviewer` is the in-process fallback (tagged
+`degraded: true` in the audit record so self-review is visible and
+countable).
 
 ## Hooks
 
-Eleven hooks, down from reagent's 26. Each does one thing.
+Fourteen hooks. Each does one thing.
 
 | Hook | Event | One-line purpose |
 | --- | --- | --- |
 | `dangerous-bash-interceptor` | PreToolUse: Bash | Block categories of destructive shell commands |
 | `env-file-protection` | PreToolUse: Bash | Block reads of `.env*` files |
-| `dependency-audit-gate` | PreToolUse: Bash | Run `npm audit`; block on high/critical |
+| `dependency-audit-gate` | PreToolUse: Bash | Verify packages exist on the registry before install |
 | `commit-review-gate` | PreToolUse: Bash | Intercept `git commit`; require review on non-trivial diffs |
-| `push-review-gate` | PreToolUse: Bash | Intercept `git push`; warn if no recent `/codex-review` |
-| `attribution-advisory` | PreToolUse: Bash | Block commits containing AI attribution markers |
+| `push-review-gate` | PreToolUse: Bash | Intercept `git push` (Claude-Code-JSON adapter); protected-path + Codex audit |
+| `push-review-gate-git` | `.husky/pre-push` | Native git adapter around the same core |
+| `attribution-advisory` | PreToolUse: Bash | Block commits / PRs containing AI attribution markers |
+| `pr-issue-link-gate` | PreToolUse: Bash | Advisory warn when `gh pr create` has no linked issue |
+| `security-disclosure-gate` | PreToolUse: Bash | Route security-keyword `gh issue create` to private disclosure |
 | `secret-scanner` | PreToolUse: Write\|Edit | Scan file writes for credential patterns |
-| `settings-protection` | PreToolUse: Write\|Edit | Block agent writes to `.claude/settings.json` |
+| `settings-protection` | PreToolUse: Write\|Edit | Block agent writes to `.claude/settings.json`, hook dirs, policy |
 | `blocked-paths-enforcer` | PreToolUse: Write\|Edit | Enforce `blocked_paths` from policy |
-| `changeset-security-gate` | PreToolUse: Write\|Edit | Require changeset entry on security-relevant changes |
-| `architecture-review-gate` | PostToolUse: Write\|Edit | Flag edits crossing architectural boundaries |
-
-A twelfth hook, `security-disclosure-gate`, intercepts `gh issue create`
-commands containing security-sensitive keywords and redirects to private
-disclosure. It is installed as part of the Bash PreToolUse set.
+| `changeset-security-gate` | PreToolUse: Write\|Edit | Guard changesets against GHSA leaks and malformed frontmatter |
+| `architecture-review-gate` | PostToolUse: Write\|Edit | Flag edits crossing architectural boundaries (advisory) |
 
 ## Slash commands
 
@@ -311,7 +518,7 @@ rejected, not ignored.
 
 | Field | Type | Purpose |
 | --- | --- | --- |
-| `version` | string, `"1"` | Schema version; only `"1"` accepted in 0.1.x |
+| `version` | string, `"1"` | Schema version; only `"1"` accepted in the current major |
 | `profile` | string | Profile name from `profiles/` (e.g. `bst-internal`) |
 | `autonomy_level` | `L0`\|`L1`\|`L2`\|`L3` | Current autonomy. `L0` = read-only; `L3` = full tool access |
 | `max_autonomy_level` | `L0`\|`L1`\|`L2`\|`L3` | Hard ceiling. `autonomy_level` cannot exceed this |
@@ -321,6 +528,13 @@ rejected, not ignored.
 | `context_protection.delegate_to_subagent` | string[] | Commands that must run in a subagent context to preserve the parent's context window |
 | `context_protection.max_bash_output_lines` | number | Truncate long bash output at this line count |
 | `notification_channel` | string | Optional Discord webhook URL. Empty string = no notifications |
+| `review.codex_required` | boolean | When `false`, protected-path pushes don't require a Codex audit (first-class no-Codex mode). Default `true` |
+| `review.cache_max_age_seconds` | number | TTL for entries in `.rea/review-cache.jsonl`. Default 3600 |
+| `review.allow_skip_in_ci` | boolean | When `true`, `REA_SKIP_PUSH_REVIEW` is accepted on CI runners. Default `false` |
+| `injection.suspicious_blocks_writes` | boolean | `bst-internal` posture — `suspicious` verdict on a write/destructive tool denies instead of warning. Default `false` |
+| `redact.patterns[]` | string[] | User-supplied secret patterns; vetted via `safe-regex` at load |
+| `redact.match_timeout_ms` | number | Per-call regex budget. Default 100 |
+| `gateway.health.expose_diagnostics` | boolean | When `true`, `__rea__health` emits redacted+classified diagnostic strings on the wire. Default `false` (null) |
 
 `autonomy_level > max_autonomy_level` is rejected at parse time. Setting
 `promotion_requires_human_approval: false` requires the CLI flag
@@ -345,8 +559,11 @@ npx @bookedsolid/rea init --from-reagent
 - Leaves `.reagent/` in place; you delete it manually after verifying
   `rea doctor` passes and a dogfood run completes.
 
-Reagent will be deprecated via `npm deprecate` within seven days of
-REA 0.1.0. The deprecation notice points users here.
+See [MIGRATION-0.5.0.md](./MIGRATION-0.5.0.md) for the BUG-008 / BUG-009
+/ BUG-010 coordinated fix window. Between 0.5.0 and 0.9.0, the breaking
+semantic change worth calling out is 0.8.0's narrowing of
+`REA_SKIP_CODEX_REVIEW` to a Codex-only waiver — see the CHANGELOG
+entry for the migration steps.
 
 ## Security
 

package/SECURITY.md

@@ -2,10 +2,16 @@
 
 ## Supported Versions
 
-| Version | Supported |
-| ------- | --------- |
-| 0.1.x   | Yes       |
-| < 0.1   | No (pre-release) |
+Security fixes land on the latest minor line. Older minors receive fixes only
+when the issue is critical and a backport is tractable.
+
+| Version | Supported                                   |
+| ------- | ------------------------------------------- |
+| 0.9.x   | Yes — active line                           |
+| 0.8.x   | Critical fixes only, 30 days from 0.9.0     |
+| 0.7.x   | No — superseded; upgrade recommended        |
+| ≤ 0.6.x | No — superseded; upgrade recommended        |
+| < 0.1   | No (pre-release)                            |
 
 ## Reporting a Vulnerability
 
@@ -85,10 +91,21 @@ REA's security model is defense-in-depth across two independent layers:
 
 **Hook layer** (development-time, Claude Code hooks):
 
-- 11 Claude Code hooks enforce security at the point of tool invocation
-- `security-disclosure-gate` blocks public issue creation for security topics
+- 14 shell scripts ship in the hook layer. 12 are wired into Claude Code's
+  `PreToolUse` / `PostToolUse` events via the default `.claude/settings.json`.
+  Two are shipped but NOT registered by default: `commit-review-gate.sh`
+  is a `PreToolUse: Bash` hook that matches `git commit` for operators who
+  opt into commit-time review by adding a rule, and `push-review-gate-git.sh`
+  is a native-git adapter that sources `hooks/_lib/push-review-core.sh`
+  (the same shared core used by the Claude-Code push-review adapter),
+  shipped for consumers who wire a wrapper-based `.husky/pre-push` that
+  execs it directly. `rea init`'s default installer emits a standalone
+  inline `.husky/pre-push` body rather than a wrapper; unifying the
+  husky installer on the adapter is tracked as a follow-up
+- `security-disclosure-gate` routes public security-keyword issue creation to private disclosure
 - `settings-protection` prevents agents from modifying their own safety rails
 - `dangerous-bash-interceptor` blocks categories of destructive shell commands
+- `push-review-gate` and the shared-core adapter (`push-review-gate-git.sh` sourcing `hooks/_lib/push-review-core.sh`) anchor trust on the hook's own on-disk location via `BASH_SOURCE` rather than caller-controlled env vars; see `THREAT_MODEL.md §5.18`. The shipped inline `.husky/pre-push` body uses `git rev-parse --show-toplevel` to locate `REA_ROOT` — extending the script-anchor idiom to the inline path is tracked follow-up hardening
 
 Both layers operate independently — compromising one does not disable the other.
 
@@ -99,6 +116,6 @@ Both layers operate independently — compromising one does not disable the othe
 - Policy parsing is strict zod schema — unknown fields rejected, not ignored
 - Path traversal protection on profile loading (regex + path containment check)
 - CI publish pipeline includes gitleaks secret scanning, npm provenance attestation via OIDC, SBOM generation, and payload validation
-- All shell hooks use `set -euo pipefail` with explicit variable quoting
+- All shell hooks set fail-fast flags with explicit variable quoting (`set -euo pipefail`, or `set -uo pipefail` for hooks that consume stdin JSON where a single `jq`-path miss must not abort before the conditional branches run)
 - Commits are signed and DCO-signed-off; `main` branch protection requires passing checks and review
 - npm publish uses OIDC provenance; no long-lived NPM tokens in CI