@bookedsolid/rea 0.13.1 → 0.13.3

package/.husky/pre-push

@@ -37,40 +37,47 @@ fi
 # splitting; `/Users/jane/My Projects/repo` produced four argv tokens
 # instead of two). The `set --` form below preserves spaces verbatim.
 #
-# The pre-push stdin carries one line per refspec; `exec` inherits stdin
-# unchanged. $@ on entry carries git's <remote-name> <remote-url>; we
-# preserve those by appending "$@" inside each `set --` arm.
+# 0.13.2 fix: the dispatch + invocation runs inside a SUBSHELL so the
+# `set --` rewrite does NOT bleed into the parent's $@. Before 0.13.2,
+# the parent's $@ ended up as the rea-CLI argv (`node /path/dist/cli/index.js
+# hook push-gate <remote-name> <remote-url>`) and the extension-fragment
+# loop below passed that mangled argv to fragments instead of git's
+# original `<remote-name> <remote-url>`. The subshell scopes the rewrite
+# so fragments see git's argv unchanged.
+#
+# The pre-push stdin carries one line per refspec; the subshell inherits
+# stdin unchanged. $@ on entry carries git's <remote-name> <remote-url>;
+# the subshell sees those as its initial $@, appends them inside each
+# `set --` arm, and the parent's $@ is preserved.
 
-if [ -x "${REA_ROOT}/node_modules/.bin/rea" ]; then
-  set -- "${REA_ROOT}/node_modules/.bin/rea" hook push-gate "$@"
-elif [ -f "${REA_ROOT}/dist/cli/index.js" ] && [ -f "${REA_ROOT}/package.json" ] && grep -q '"name": *"@bookedsolid/rea"' "${REA_ROOT}/package.json" 2>/dev/null; then
-  # rea's own repo (dogfood) — the package is not installed under
-  # node_modules here because we ARE the package. The built CLI
-  # entry point lives at dist/cli/index.js; node runs it directly.
-  # Gate this branch on `package.json` declaring `@bookedsolid/rea` so a
-  # consumer repo that happens to ship its own `dist/cli/index.js` does
-  # not get this hook executing the consumer's unrelated build.
-  set -- node "${REA_ROOT}/dist/cli/index.js" hook push-gate "$@"
-elif command -v rea >/dev/null 2>&1; then
-  set -- rea hook push-gate "$@"
-elif command -v npx >/dev/null 2>&1; then
-  # Last resort: npx will resolve the package from npm or the cache.
-  # Pass `--no-install` so a rare cache-cold machine surfaces a clear
-  # error instead of silently downloading at push time.
-  set -- npx --no-install @bookedsolid/rea hook push-gate "$@"
+if (
+  if [ -x "${REA_ROOT}/node_modules/.bin/rea" ]; then
+    set -- "${REA_ROOT}/node_modules/.bin/rea" hook push-gate "$@"
+  elif [ -f "${REA_ROOT}/dist/cli/index.js" ] && [ -f "${REA_ROOT}/package.json" ] && grep -q '"name": *"@bookedsolid/rea"' "${REA_ROOT}/package.json" 2>/dev/null; then
+    # rea's own repo (dogfood) — the package is not installed under
+    # node_modules here because we ARE the package. The built CLI
+    # entry point lives at dist/cli/index.js; node runs it directly.
+    # Gate this branch on `package.json` declaring `@bookedsolid/rea` so a
+    # consumer repo that happens to ship its own `dist/cli/index.js` does
+    # not get this hook executing the consumer's unrelated build.
+    set -- node "${REA_ROOT}/dist/cli/index.js" hook push-gate "$@"
+  elif command -v rea >/dev/null 2>&1; then
+    set -- rea hook push-gate "$@"
+  elif command -v npx >/dev/null 2>&1; then
+    # Last resort: npx will resolve the package from npm or the cache.
+    # Pass `--no-install` so a rare cache-cold machine surfaces a clear
+    # error instead of silently downloading at push time.
+    set -- npx --no-install @bookedsolid/rea hook push-gate "$@"
+  else
+    printf 'rea: cannot locate the rea CLI. Install locally (`pnpm add -D @bookedsolid/rea`) or globally (`npm i -g @bookedsolid/rea`).\n' >&2
+    exit 2
+  fi
+  exec "$@"
+); then
+  rea_status=0
 else
-  printf 'rea: cannot locate the rea CLI. Install locally (`pnpm add -D @bookedsolid/rea`) or globally (`npm i -g @bookedsolid/rea`).\n' >&2
-  exit 2
+  rea_status=$?
 fi
-
-# Run the rea push-gate FIRST. We capture its exit and explicitly propagate
-# instead of `exec`-ing — extension fragments must only run after rea's own
-# governance work succeeds. The fragments are user code; surfacing them
-# AFTER rea's body (HALT check, Codex review, audit write) preserves the
-# governance contract while letting consumers chain their own checks (e.g.
-# commitlint, branch-policy linters) without losing rea coverage.
-"$@"
-rea_status=$?
 if [ "$rea_status" -ne 0 ]; then
   exit "$rea_status"
 fi

package/MIGRATING.md

@@ -0,0 +1,306 @@
+# Migrating to `@bookedsolid/rea` from a project with prior tooling
+
+`rea` was originally written for greenfield projects. Real consumers
+arrive with prior infrastructure already in place — commitlint,
+lint-staged, gitleaks, act-CI, branch-policy linters, project-specific
+gates wired into `.husky/`. This guide names the conflict patterns by
+name and shows the supported migration path for each.
+
+If you hit something this doc doesn't cover, file an issue at
+https://github.com/bookedsolidtech/rea/issues with the offending hook
+body and the prior tool name.
+
+## Prerequisite — husky must be installed and `core.hooksPath` configured
+
+The `.husky/{commit-msg,pre-push}.d/` extension surface is sourced from
+the rea-managed bodies under `.husky/<hookname>`. Those bodies only fire
+when git is configured to use husky. Confirm one of the following:
+
+- Husky 9 (recommended): `pnpm dlx husky init` (or `npx husky init`)
+  during onboarding. Husky 9 sets `core.hooksPath=.husky/_` automatically;
+  rea's bodies live at `.husky/<hookname>` and husky's auto-generated
+  stubs at `.husky/_/<hookname>` source them at hook-fire time. `rea
+  doctor` (0.13.1+) follows the husky 9 stub indirection correctly.
+- Husky 4-8 (legacy): `core.hooksPath=.husky` set, husky's
+  `_/husky.sh` runner installed. Functional but unsupported by husky
+  upstream — migrate to husky 9.
+- Vanilla git (no husky): rea installs the fallback at
+  `.git/hooks/pre-push`. **The fragment recipes below DO NOT run** in
+  this configuration — `.git/hooks/pre-push` is not the same body as
+  `.husky/pre-push`. Either install husky (recommended) or chain your
+  per-tool commands directly into the fallback (you'll lose the
+  upgrade-safe property — `rea upgrade` will refresh the fallback and
+  drop your chain).
+
+`pnpm rea doctor` reports the active hook path. If it shows
+`.git/hooks/pre-push` (rea-managed at .../.git/hooks/pre-push), you
+are on the vanilla-git path — install husky first.
+
+## TL;DR
+
+1. Confirm husky is installed (see prereq above).
+2. Run `rea init` (fresh install) or `rea upgrade` (existing).
+3. **Do not lose your existing chain.** rea now refuses to silently
+   overwrite an executable `.husky/pre-push` or `.husky/commit-msg`
+   that is not rea-managed; you'll see a `[fail]` from `rea doctor`
+   pointing here.
+4. Move each chained command from your existing hook body to a
+   per-tool fragment under `.husky/pre-push.d/<NN>-<name>` or
+   `.husky/commit-msg.d/<NN>-<name>` (executable, lex-ordered).
+5. Re-run `rea init`. The fresh hook body delegates to
+   `rea hook push-gate` and then runs your fragments AFTER the
+   governance gate.
+6. `rea doctor` should now report all checks green.
+
+## What rea ships and what it doesn't
+
+`rea init` / `rea upgrade` install:
+
+- `.husky/pre-push` — package-managed; **do not edit**. Refreshed on every
+  `rea upgrade`.
+- `.husky/commit-msg` — package-managed; **do not edit**. Same.
+- `.git/hooks/pre-push` (fallback when `core.hooksPath` is unset).
+- `.claude/hooks/*.sh` — protection + audit + advisory hooks.
+- `.claude/agents/*.md`, `.claude/commands/*.md`.
+- `.rea/policy.yaml`, `.rea/registry.yaml`.
+
+`rea` does **not** install:
+
+- `.husky/pre-commit` — completely yours. Out of scope for the rea
+  push-gate. If you have one, keep it.
+- `.husky/post-commit`, `post-merge`, `post-checkout`, etc. — yours.
+- Any tool's binary (`commitlint`, `gitleaks`, `husky`, etc.) — yours.
+
+The only files rea touches are explicitly enumerated above. Everything
+else is the consumer's surface.
+
+## Extension surface (added in 0.13.0)
+
+`.husky/pre-push.d/*` and `.husky/commit-msg.d/*` are the
+**upgrade-safe** place to layer your own gates. Files in those
+directories must be executable; rea sources them in lex order AFTER
+its own governance work succeeds. A non-zero exit from any fragment
+fails the hook (matches husky's normal chaining).
+
+- Fragment receives positional args from git (`<remote-name> <remote-url>`
+  for pre-push, `<commit-msg-file>` for commit-msg).
+- Missing directory is a no-op (no fragments = no chained checks).
+- Non-executable files are silently skipped (drop a `README` if you
+  want context next to the fragments — it won't run).
+- Fragments run with the current shell's `set -eu`; an unset variable
+  or a non-zero exit anywhere in the fragment short-circuits.
+
+`rea doctor` reports detected fragments at `[info]` level so you can
+confirm the chain.
+
+## Conflict pattern: commitlint
+
+You probably have something like this in `.husky/commit-msg`:
+
+```sh
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"   # husky 4-8
+npx --no-install commitlint --edit "$1"
+```
+
+Or, with husky 9, your own command interleaved with `husky 9`'s body.
+
+**rea 0.11.0+ overwrites `.husky/commit-msg` on `rea upgrade --force`.**
+Your commitlint invocation will be lost.
+
+### Migration
+
+Move commitlint to a fragment:
+
+```bash
+mkdir -p .husky/commit-msg.d
+cat > .husky/commit-msg.d/01-commitlint <<'EOF'
+#!/bin/sh
+exec npx --no-install commitlint --edit "$1"
+EOF
+chmod +x .husky/commit-msg.d/01-commitlint
+```
+
+Re-run `rea upgrade`. The package-managed `.husky/commit-msg` body now
+runs first (HALT check, AI-attribution block when policy enables it),
+then runs your fragment.
+
+## Conflict pattern: lint-staged on pre-push
+
+You probably have:
+
+```sh
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+npx --no-install lint-staged
+```
+
+### Migration
+
+```bash
+mkdir -p .husky/pre-push.d
+cat > .husky/pre-push.d/02-lint-staged <<'EOF'
+#!/bin/sh
+exec npx --no-install lint-staged
+EOF
+chmod +x .husky/pre-push.d/02-lint-staged
+```
+
+## Conflict pattern: gitleaks (pre-commit)
+
+`rea` does NOT install a pre-commit hook. Your existing
+`.husky/pre-commit` keeps working unchanged. Just confirm:
+
+- Shebang is `#!/usr/bin/env bash` (not `#!/bin/sh`) if the body uses
+  `set -o pipefail`. On Linux where `/bin/sh = dash`, `pipefail`
+  aborts immediately.
+- gitleaks invocation includes `--redact` so detected secrets don't
+  hit terminal scrollback.
+- gitleaks binary is vendored or installed via postinstall (e.g.
+  `gitleaks-secret-scanner` npm wrapper) so fresh clones work without
+  manual install.
+
+If you want gitleaks to run on push instead of commit, add a fragment:
+
+```bash
+cat > .husky/pre-push.d/03-gitleaks <<'EOF'
+#!/bin/sh
+exec gitleaks detect --redact --no-banner
+EOF
+chmod +x .husky/pre-push.d/03-gitleaks
+```
+
+## Conflict pattern: act-CI matrix
+
+If you have a project-specific CI gate like `./scripts/act-ci.sh`
+chained into `.husky/pre-push` (e.g. BST), it gets clobbered by
+`rea upgrade --force`.
+
+### Migration
+
+```bash
+cat > .husky/pre-push.d/00-act-ci <<'EOF'
+#!/bin/sh
+exec ./scripts/act-ci.sh
+EOF
+chmod +x .husky/pre-push.d/00-act-ci
+```
+
+The `00-` prefix puts act-CI first in lex order so it runs before any
+later fragments. Adjust ordering as needed.
+
+## Conflict pattern: branch-policy linter
+
+A common pattern that reads `$1` (remote name) and `$2` (remote URL)
+to allow/deny pushes to specific remotes:
+
+```sh
+#!/bin/sh
+remote="$1"
+url="$2"
+if [ "$remote" = "origin" ] && echo "$url" | grep -q "production"; then
+  echo "Direct push to production blocked. PR via main." >&2
+  exit 1
+fi
+```
+
+This requires the standard pre-push argv. **rea 0.13.2+ preserves
+git's argv unchanged** for fragments — earlier versions (0.13.0 /
+0.13.1) had a known bug where `set --` mutation in the rea dispatch
+clobbered `$@`. Upgrade to `^0.13.2` if branch-policy linters are part
+of your chain.
+
+### Migration
+
+Drop the body into a fragment as-is:
+
+```bash
+cat > .husky/pre-push.d/05-branch-policy <<'EOF'
+#!/bin/sh
+remote="$1"
+url="$2"
+if [ "$remote" = "origin" ] && echo "$url" | grep -q "production"; then
+  echo "Direct push to production blocked. PR via main." >&2
+  exit 1
+fi
+EOF
+chmod +x .husky/pre-push.d/05-branch-policy
+```
+
+## Conflict pattern: pre-existing rea-CLI invocation
+
+Some consumers had `exec rea hook push-gate "$@"` chained inline in a
+foreign hook body. `rea doctor` recognizes this pattern and reports
+the hook as `external (delegates to rea hook push-gate)` — `pass`,
+not `fail`. No migration required, but you cannot benefit from the
+extension-fragment chain unless you let rea own the hook body.
+
+If you want both — rea ownership AND your other commands — migrate the
+other commands to fragments.
+
+## Conflict pattern: husky 9 layout (`core.hooksPath=.husky/_`)
+
+This is the default husky 9 install. rea 0.13.1+ supports it
+correctly: doctor follows the husky 9 stub indirection from
+`.husky/_/<hookname>` through `.husky/_/h` to the canonical
+`.husky/<hookname>`. No migration required.
+
+If you're on rea 0.13.0 and seeing `[fail] pre-push hook` despite a
+correctly-installed `.husky/pre-push`, upgrade to `^0.13.1`.
+
+## What `rea doctor` will tell you
+
+After migration, run `pnpm rea doctor`. The relevant lines:
+
+- `[ok] pre-push hook installed` — rea-managed body active, fragments
+  (if any) detected
+- `[fail] pre-push hook installed` with **"Detected prior tooling: X,
+  Y, Z"** — your existing hook still chains tooling that should be in
+  fragments. Move each named tool to a `.d/` fragment, then re-run
+  `rea init`.
+- `[info] extension-hook fragments detected: N pre-push.d, M
+  commit-msg.d` — your fragment chain is active
+
+## Policy knobs worth setting
+
+For consumers with a long-running migration branch (>30 commits since
+last push), the push-gate auto-narrows the codex review window unless
+you opt out. Pin explicit values to avoid surprises:
+
+```yaml
+# .rea/policy.yaml
+review:
+  codex_required: true
+  timeout_ms: 1800000              # 30 min — explicit pin
+  auto_narrow_threshold: 30        # 0 to disable auto-narrow
+  last_n_commits: 10               # explicit scope window
+```
+
+## Bypass when you genuinely need to
+
+```bash
+# Audited skip: codex flips on a known-ambivalent file
+REA_SKIP_CODEX_REVIEW="cemPath-ambivalence" git push
+
+# Whole-gate skip: codex CLI itself is broken
+REA_SKIP_PUSH_GATE="codex-cli-crash-pinging-team" git push
+
+# Concerns-only override (P2 findings) without skipping the gate
+REA_ALLOW_CONCERNS=1 git push
+```
+
+Every bypass is audit-logged with the reason in `.rea/audit.jsonl`.
+Reasons should be specific — "skip" is not a reason; the file or
+verdict that triggered it is.
+
+## When to file an issue vs handle in-tree
+
+- **rea hook ate my chain on `rea upgrade`** → file an issue, that's
+  rea's fault. Workaround: migrate to `.d/` fragments.
+- **rea doctor false-positives on my legitimate setup** → file an
+  issue.
+- **codex flips verdicts on the same code** → upstream of rea (codex
+  CLI itself). Use `REA_SKIP_CODEX_REVIEW` with a specific reason and
+  document the ambivalence.
+- **My pre-commit hook breaks on push** → not rea (rea ships no
+  pre-commit). Fix in your repo.

package/dist/cli/doctor.js

@@ -374,14 +374,30 @@ function checkPrePushHook(state) {
     if (state.activeForeign) {
         // Executable file exists at the active path but neither carries a rea
         // marker nor invokes `rea hook push-gate` — the push-gate is silently
-        // bypassed. Always a hard fail.
+        // bypassed. Always a hard fail. When the foreign hook references a
+        // recognizable prior tool (commitlint, lint-staged, gitleaks, act-CI,
+        // …), surface the .d/ migration path explicitly so consumers know
+        // exactly how to keep their existing chain without losing rea coverage
+        // or having `rea upgrade` clobber them again.
+        const hints = state.activePath !== null
+            ? detectPriorToolHints(state.activePath)
+            : [];
+        let detail = `active pre-push at ${state.activePath} is present and executable but does NOT ` +
+            'invoke `rea hook push-gate` — the 0.11.0 push-gate is silently bypassed. ' +
+            'Either add `exec rea hook push-gate "$@"` to the existing hook, or ' +
+            'remove it and re-run `rea init` to install the fallback.';
+        if (hints.length > 0) {
+            detail +=
+                `\n      Detected prior tooling in the foreign hook: ${hints.join(', ')}. ` +
+                    'Recommended migration (rea 0.13.0+): move each chained command to ' +
+                    '`.husky/pre-push.d/<NN>-<name>` as a separate executable file; rea then ' +
+                    'runs them in lex order AFTER the push-gate, surviving `rea upgrade` ' +
+                    'unchanged. See `MIGRATING.md` for a worked example.';
+        }
         return {
             label: 'pre-push hook installed',
             status: 'fail',
-            detail: `active pre-push at ${state.activePath} is present and executable but does NOT ` +
-                'invoke `rea hook push-gate` — the 0.11.0 push-gate is silently bypassed. ' +
-                'Either add `exec rea hook push-gate "$@"` to the existing hook, or ' +
-                'remove it and re-run `rea init` to install the fallback.',
+            detail,
         };
     }
     const present = state.candidates
@@ -403,6 +419,47 @@ function checkPrePushHook(state) {
             'Run `rea init` to install the fallback.',
     };
 }
+/**
+ * Best-effort scan of a foreign hook body for references to recognizable
+ * consumer tooling. Each match returns a short label so doctor can render
+ * a precise migration recommendation without dumping the raw hook body.
+ *
+ * Patterns are intentionally narrow: a substring match in a non-comment line
+ * referencing a tool's CLI binary or a well-known wrapper. False positives
+ * here are cosmetic (extra hint) — the hard-fail decision still drives the
+ * doctor verdict.
+ *
+ * Read errors are swallowed (return []). Doctor's foreign-hook message is
+ * still useful without hints.
+ */
+function detectPriorToolHints(hookPath) {
+    let body;
+    try {
+        body = fs.readFileSync(hookPath, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const lines = body.split(/\r?\n/);
+    const found = new Set();
+    for (const raw of lines) {
+        if (/^\s*#/.test(raw))
+            continue; // skip comments
+        if (/\bcommitlint\b/.test(raw))
+            found.add('commitlint');
+        if (/\blint-staged\b/.test(raw))
+            found.add('lint-staged');
+        if (/\bgitleaks\b/.test(raw))
+            found.add('gitleaks');
+        if (/\bact[-_]ci\b/i.test(raw) || /\bact-CI\b/.test(raw))
+            found.add('act-CI');
+        if (/\bhusky\.sh\b/.test(raw))
+            found.add('legacy husky 4-8 wrapper');
+        if (/\bnpx\s+--no-install\s+commitlint/.test(raw))
+            found.add('commitlint');
+    }
+    return Array.from(found).sort();
+}
 /**
  * Detect and list extension-hook fragments under `.husky/commit-msg.d/` and
  * `.husky/pre-push.d/`. Informational only — fragments are an opt-in feature

package/dist/cli/install/pre-push.js

@@ -148,40 +148,47 @@ fi
 # splitting; \`/Users/jane/My Projects/repo\` produced four argv tokens
 # instead of two). The \`set --\` form below preserves spaces verbatim.
 #
-# The pre-push stdin carries one line per refspec; \`exec\` inherits stdin
-# unchanged. \$@ on entry carries git's <remote-name> <remote-url>; we
-# preserve those by appending "\$@" inside each \`set --\` arm.
+# 0.13.2 fix: the dispatch + invocation runs inside a SUBSHELL so the
+# \`set --\` rewrite does NOT bleed into the parent's \$@. Before 0.13.2,
+# the parent's \$@ ended up as the rea-CLI argv (\`node /path/dist/cli/index.js
+# hook push-gate <remote-name> <remote-url>\`) and the extension-fragment
+# loop below passed that mangled argv to fragments instead of git's
+# original \`<remote-name> <remote-url>\`. The subshell scopes the rewrite
+# so fragments see git's argv unchanged.
+#
+# The pre-push stdin carries one line per refspec; the subshell inherits
+# stdin unchanged. \$@ on entry carries git's <remote-name> <remote-url>;
+# the subshell sees those as its initial \$@, appends them inside each
+# \`set --\` arm, and the parent's \$@ is preserved.
 
-if [ -x "\${REA_ROOT}/node_modules/.bin/rea" ]; then
-  set -- "\${REA_ROOT}/node_modules/.bin/rea" hook push-gate "\$@"
-elif [ -f "\${REA_ROOT}/dist/cli/index.js" ] && [ -f "\${REA_ROOT}/package.json" ] && grep -q '"name": *"@bookedsolid/rea"' "\${REA_ROOT}/package.json" 2>/dev/null; then
-  # rea's own repo (dogfood) — the package is not installed under
-  # node_modules here because we ARE the package. The built CLI
-  # entry point lives at dist/cli/index.js; node runs it directly.
-  # Gate this branch on \`package.json\` declaring \`@bookedsolid/rea\` so a
-  # consumer repo that happens to ship its own \`dist/cli/index.js\` does
-  # not get this hook executing the consumer's unrelated build.
-  set -- node "\${REA_ROOT}/dist/cli/index.js" hook push-gate "\$@"
-elif command -v rea >/dev/null 2>&1; then
-  set -- rea hook push-gate "\$@"
-elif command -v npx >/dev/null 2>&1; then
-  # Last resort: npx will resolve the package from npm or the cache.
-  # Pass \`--no-install\` so a rare cache-cold machine surfaces a clear
-  # error instead of silently downloading at push time.
-  set -- npx --no-install @bookedsolid/rea hook push-gate "\$@"
+if (
+  if [ -x "\${REA_ROOT}/node_modules/.bin/rea" ]; then
+    set -- "\${REA_ROOT}/node_modules/.bin/rea" hook push-gate "\$@"
+  elif [ -f "\${REA_ROOT}/dist/cli/index.js" ] && [ -f "\${REA_ROOT}/package.json" ] && grep -q '"name": *"@bookedsolid/rea"' "\${REA_ROOT}/package.json" 2>/dev/null; then
+    # rea's own repo (dogfood) — the package is not installed under
+    # node_modules here because we ARE the package. The built CLI
+    # entry point lives at dist/cli/index.js; node runs it directly.
+    # Gate this branch on \`package.json\` declaring \`@bookedsolid/rea\` so a
+    # consumer repo that happens to ship its own \`dist/cli/index.js\` does
+    # not get this hook executing the consumer's unrelated build.
+    set -- node "\${REA_ROOT}/dist/cli/index.js" hook push-gate "\$@"
+  elif command -v rea >/dev/null 2>&1; then
+    set -- rea hook push-gate "\$@"
+  elif command -v npx >/dev/null 2>&1; then
+    # Last resort: npx will resolve the package from npm or the cache.
+    # Pass \`--no-install\` so a rare cache-cold machine surfaces a clear
+    # error instead of silently downloading at push time.
+    set -- npx --no-install @bookedsolid/rea hook push-gate "\$@"
+  else
+    printf 'rea: cannot locate the rea CLI. Install locally (\`pnpm add -D @bookedsolid/rea\`) or globally (\`npm i -g @bookedsolid/rea\`).\\n' >&2
+    exit 2
+  fi
+  exec "\$@"
+); then
+  rea_status=0
 else
-  printf 'rea: cannot locate the rea CLI. Install locally (\`pnpm add -D @bookedsolid/rea\`) or globally (\`npm i -g @bookedsolid/rea\`).\\n' >&2
-  exit 2
+  rea_status=\$?
 fi
-
-# Run the rea push-gate FIRST. We capture its exit and explicitly propagate
-# instead of \`exec\`-ing — extension fragments must only run after rea's own
-# governance work succeeds. The fragments are user code; surfacing them
-# AFTER rea's body (HALT check, Codex review, audit write) preserves the
-# governance contract while letting consumers chain their own checks (e.g.
-# commitlint, branch-policy linters) without losing rea coverage.
-"\$@"
-rea_status=\$?
 if [ "\$rea_status" -ne 0 ]; then
   exit "\$rea_status"
 fi

package/hooks/settings-protection.sh

@@ -130,6 +130,59 @@ if [[ "$raw_has_traversal" -eq 1 ]] || [[ "$norm_has_traversal" -eq 1 ]]; then
   exit 2
 fi
 
+# Compute lower-cased path early so the §5b allow-list (and §6/§6b matchers
+# below) all reference a single normalized variable.
+LOWER_NORM=$(printf '%s' "$NORMALIZED" | tr '[:upper:]' '[:lower:]')
+
+# ── 5b. Extension-surface allow-list ──────────────────────────────────────────
+# `.husky/commit-msg.d/*` and `.husky/pre-push.d/*` are the documented
+# consumer extension surface (Fix H / 0.13.0). Consumers — and the agents
+# that govern those consumers — are expected to write here freely so they
+# can layer commitlint, lint-staged, branch-policy, act-CI, etc. without
+# losing rea coverage on `rea upgrade`.
+#
+# The §6 PROTECTED_PATTERNS list below has `.husky/` as a prefix block,
+# which (correctly) keeps `.husky/pre-push`, `.husky/commit-msg`, and
+# the `.husky/_/*` runtime stubs out of agent reach. But the same prefix
+# also caught `.husky/pre-push.d/00-act-ci` and `.husky/commit-msg.d/*`
+# until 0.13.2 — the very directories advertised as the extension
+# surface. This early allow-list closes that contract gap.
+#
+# Anchored on the literal `.d/` segment (not `.d`) so `.husky/pre-push.d.bak/`
+# or `.husky/pre-push.dump` still hit the prefix block. Nested fragments
+# (e.g. `pre-push.d/sub/file`) are allowed so the surface composes naturally.
+#
+# SECURITY: runs AFTER §5a (path-traversal reject), so a clever
+# `.husky/pre-push.d/../pre-push` cannot bypass §6's protection of the
+# package-managed body — §5a kills it before this matcher runs.
+#
+# SECURITY (defense-in-depth): symlinks INSIDE the .d/ surface are
+# refused. A fragment is a short shell script authored in place;
+# consumers do not need symlinks here. Without this check, a sequence
+# like `ln -s ../pre-push .husky/pre-push.d/00-evil; write 00-evil`
+# would be allowed by §5b's path-string match and the downstream
+# Write/Edit tool would follow the symlink, overwriting the
+# package-managed `.husky/pre-push` body that §6 is meant to protect.
+# Costs near-zero (no legitimate use case for symlinked fragments);
+# closes the path-string→symlink bypass completely.
+case "$LOWER_NORM" in
+  .husky/commit-msg.d/*|.husky/pre-push.d/*)
+    if [ -L "$FILE_PATH" ]; then
+      {
+        printf 'SETTINGS PROTECTION: symlink in extension surface refused\n'
+        printf '\n'
+        printf '  File: %s\n' "$SAFE_FILE_PATH"
+        printf '  Rule: .husky/commit-msg.d/* and .husky/pre-push.d/* must be\n'
+        printf '        regular files (a symlink could resolve to a protected\n'
+        printf '        package-managed body and bypass §6 protection).\n'
+      } >&2
+      exit 2
+    fi
+    # Documented extension surface — agents can write here freely.
+    exit 0
+    ;;
+esac
+
 # ── 6. Protected path patterns ────────────────────────────────────────────────
 # §6 runs BEFORE the patch-session allowlist so hook-patch sessions cannot
 # reach .rea/policy.yaml, .rea/HALT, or .claude/settings.json via any glob
@@ -149,7 +202,7 @@ PATCH_SESSION_PATTERNS=(
   '.claude/hooks/'
 )
 
-LOWER_NORM=$(printf '%s' "$NORMALIZED" | tr '[:upper:]' '[:lower:]')
+# LOWER_NORM was computed in §5b above and is reused here.
 
 # Match $NORMALIZED against PROTECTED_PATTERNS (exact or prefix for patterns
 # ending in '/'). Sets $PROTECTED_MATCH to the matched pattern; exit 0 on hit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "Agentic governance layer for Claude Code — policy enforcement, hook-based safety gates, audit logging, and Codex-integrated adversarial review for AI-assisted projects",
   "license": "MIT",
   "author": "Booked Solid Technology <oss@bookedsolid.tech> (https://bookedsolid.tech)",
@@ -49,6 +49,7 @@
     ".husky/",
     "LICENSE",
     "README.md",
+    "MIGRATING.md",
     "SECURITY.md",
     "THREAT_MODEL.md"
   ],