@bookedsolid/rea 0.29.0 → 0.30.1

package/.husky/prepare-commit-msg

@@ -0,0 +1,314 @@
+#!/bin/sh
+# rea:prepare-commit-msg v1
+# rea:augment-body-v1
+#
+# Husky prepare-commit-msg hook installed by `rea init` / `rea upgrade`.
+# Do NOT edit by hand — the file is refreshed on every rea upgrade.
+#
+# Governance contract: when policy.attribution.co_author.enabled is
+# `true`, append a `Co-Authored-By: <name> <email>` trailer to the
+# commit message file. Idempotent on email match (case-insensitive,
+# line-anchored). Skips merge commits when policy.attribution.co_author
+# .skip_merge is true.
+#
+# Triggers under all five commit sources git delivers:
+#   - $2 unset / empty   (`git commit` with no body provided)
+#   - $2 = 'message'     (`git commit -m "..."`)
+#   - $2 = 'template'    (commit.template configured)
+#   - $2 = 'merge'       (merge commit; honored by skip_merge: true)
+#   - $2 = 'squash'      (squash merge / rebase)
+#   - $2 = 'commit'      (`git commit --amend`)
+#
+# Skip conditions:
+#   - REA_SKIP_ATTRIBUTION=1 in env (per-invocation override)
+#   - .rea/HALT present (kill switch active)
+#   - $1 (message file path) missing or not a file
+#   - policy.attribution.co_author.enabled !== true
+#
+# Coexistence: this hook does NOT block on anything. The companion
+# `commit-msg` hook (which runs AFTER prepare-commit-msg in git's
+# lifecycle) still enforces `block_ai_attribution`. A human trailer
+# `Co-Authored-By: Real Name <real@email.tld>` is NOT AI attribution
+# (no AI noreply domain, no AI name keyword) and is not blocked.
+
+set -u
+
+COMMIT_MSG_FILE="${1:-}"
+COMMIT_SOURCE="${2:-}"
+
+# Skip conditions: any missing precondition exits 0 silently. The hook
+# is purely additive; refusing here would break commits with no upside.
+
+# Missing message file → nothing to augment.
+if [ -z "$COMMIT_MSG_FILE" ] || [ ! -f "$COMMIT_MSG_FILE" ]; then
+  exit 0
+fi
+
+# Per-invocation override.
+if [ -n "${REA_SKIP_ATTRIBUTION:-}" ]; then
+  exit 0
+fi
+
+REA_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+# HALT kill switch — refuse to mutate anything while frozen.
+if [ -f "${REA_ROOT}/.rea/HALT" ]; then
+  exit 0
+fi
+
+POLICY_FILE="${REA_ROOT}/.rea/policy.yaml"
+if [ ! -f "$POLICY_FILE" ]; then
+  exit 0
+fi
+
+# Delegate policy reads to the canonical rea CLI when available so we
+# get the zod-validated document regardless of whether the operator
+# wrote block-form (`attribution:\n  co_author:\n    enabled: true`)
+# or inline-form (`attribution: { co_author: { enabled: true } }`)
+# YAML. Codex round 1 P2: the prior Python inline parser only handled
+# block form. When the CLI is unreachable (fresh consumer install
+# pre-`pnpm i`, foreign dev environment, …) we fall back to the
+# embedded Python state machine — it correctly handles block-form
+# YAML, which is what `rea init` writes.
+#
+# Locator priority mirrors `.husky/pre-push`: project node_modules →
+# dogfood dist → PATH.
+rea_invoke() {
+  if [ -x "${REA_ROOT}/node_modules/.bin/rea" ]; then
+    "${REA_ROOT}/node_modules/.bin/rea" "$@"
+  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
+    node "${REA_ROOT}/dist/cli/index.js" "$@"
+  elif command -v rea >/dev/null 2>&1; then
+    rea "$@"
+  else
+    return 127
+  fi
+}
+
+ENABLED=$(rea_invoke hook policy-get attribution.co_author.enabled 2>/dev/null)
+REA_RC=$?
+
+# REA_RC interpretation:
+#   0          — rea CLI ran and returned a value (or empty for an
+#                unset key). Use the CLI reads.
+#   non-zero   — rea CLI unreachable (127 sentinel), too old to know
+#                `hook policy-get`, OR the policy YAML is unparseable.
+#                In every one of those cases the policy file ITSELF
+#                may still be valid block-form YAML, so fall back to
+#                the embedded python3 parser. The realistic invalid-
+#                config case — `enabled: true` with an empty name or
+#                email — is caught downstream by the `[ -z "$CO_NAME" ]`
+#                defense-in-depth guard, which exits 0 without
+#                augmenting regardless of which reader produced the
+#                values. (An earlier 0.30.1 revision fail-closed on
+#                non-127 exit codes; codex round 1 showed that
+#                regressed the supported stale-CLI / pre-`pnpm i` flow,
+#                because an old `rea` exits non-zero exactly like an
+#                unparseable policy — the two are indistinguishable by
+#                exit code.)
+if [ "$REA_RC" = "0" ]; then
+  CO_NAME=$(rea_invoke hook policy-get attribution.co_author.name 2>/dev/null || printf '')
+  CO_EMAIL=$(rea_invoke hook policy-get attribution.co_author.email 2>/dev/null || printf '')
+  SKIP_MERGE=$(rea_invoke hook policy-get attribution.co_author.skip_merge 2>/dev/null || printf 'false')
+elif command -v python3 >/dev/null 2>&1; then
+  # rea CLI unreachable / stale / policy unparseable — fall back to the
+  # Python block-form parser.
+  CO_AUTHOR_PARSE=$(python3 - "$POLICY_FILE" <<'PY' 2>/dev/null
+import re
+import sys
+
+path = sys.argv[1]
+try:
+    with open(path, 'r', encoding='utf-8') as fh:
+        lines = fh.readlines()
+except OSError:
+    print('false'); print(''); print(''); print('false'); sys.exit(0)
+
+in_attr = False
+in_co = False
+enabled = 'false'
+name = ''
+email = ''
+skip_merge = 'false'
+
+def strip_value(raw):
+    raw = raw.rstrip('\n').rstrip()
+    if len(raw) >= 2 and raw[0] == raw[-1] and raw[0] in ("'", '"'):
+        return raw[1:-1]
+    if '#' in raw:
+        raw = raw.split('#', 1)[0].rstrip()
+    return raw
+
+for line in lines:
+    stripped_line = line.rstrip('\n')
+    if re.match(r'^\s*#', stripped_line):
+        continue
+    if re.match(r'^attribution:\s*(#.*)?$', stripped_line):
+        in_attr = True; in_co = False; continue
+    if in_attr and re.match(r'^\S', stripped_line):
+        in_attr = False; in_co = False
+    if in_attr and re.match(r'^\s+co_author:\s*(#.*)?$', stripped_line):
+        in_co = True; continue
+    if in_co:
+        m = re.match(r'^(\s*)\S', stripped_line)
+        if m and len(m.group(1)) <= 2:
+            in_co = False; continue
+        if re.search(r'enabled:\s*true(\s|$)', stripped_line):
+            enabled = 'true'
+        elif re.search(r'enabled:\s*false(\s|$)', stripped_line):
+            enabled = 'false'
+        if re.search(r'skip_merge:\s*true(\s|$)', stripped_line):
+            skip_merge = 'true'
+        elif re.search(r'skip_merge:\s*false(\s|$)', stripped_line):
+            skip_merge = 'false'
+        m = re.search(r'name:\s*(.*)$', stripped_line)
+        if m:
+            name = strip_value(m.group(1))
+        m = re.search(r'email:\s*(.*)$', stripped_line)
+        if m:
+            email = strip_value(m.group(1))
+
+print(enabled); print(name); print(email); print(skip_merge)
+PY
+)
+  if [ -z "$CO_AUTHOR_PARSE" ]; then
+    exit 0
+  fi
+  ENABLED=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '1p')
+  CO_NAME=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '2p')
+  CO_EMAIL=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '3p')
+  SKIP_MERGE=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '4p')
+else
+  # Neither rea CLI nor python3 reachable — silent no-op.
+  exit 0
+fi
+
+if [ "$ENABLED" != "true" ]; then
+  exit 0
+fi
+
+# Defense-in-depth: if we got here with enabled=true but no identity,
+# the policy loader's cross-field refinement was bypassed (or someone
+# edited the YAML around the load path). Bail without augmenting and
+# emit a stderr advisory so the operator sees the misconfig at commit
+# time. We deliberately do NOT exit non-zero — refusing the commit
+# would be more disruptive than the silent no-op (the loader + doctor
+# already surface the misconfig at policy load and at `rea doctor`).
+#
+# When `rea audit record <topic>` lands in a future release this
+# branch should emit a `rea.attribution_augmented_invalid_config`
+# record instead of stderr. Tracked as a 0.31.0+ item.
+if [ -z "$CO_NAME" ] || [ -z "$CO_EMAIL" ]; then
+  printf 'rea: attribution.co_author.enabled=true but %s%s%s is empty — augmenter no-op.\n' \
+    "$([ -z "$CO_NAME" ] && printf name)" \
+    "$([ -z "$CO_NAME" ] && [ -z "$CO_EMAIL" ] && printf '+')" \
+    "$([ -z "$CO_EMAIL" ] && printf email)" >&2
+  printf 'rea: edit .rea/policy.yaml — set name + email, OR set enabled: false.\n' >&2
+  exit 0
+fi
+
+# skip_merge: true → skip when commit source is 'merge'.
+if [ "$SKIP_MERGE" = "true" ] && [ "$COMMIT_SOURCE" = "merge" ]; then
+  exit 0
+fi
+
+# Idempotency: scan the current message file for a Co-Authored-By line
+# that names the same email (case-insensitive). Line-anchored — body
+# prose mentioning the email in passing does NOT count.
+LOWER_EMAIL=$(printf '%s' "$CO_EMAIL" | tr '[:upper:]' '[:lower:]')
+# grep -E with case-insensitive flag; portable across BSD + GNU grep.
+# The pattern: ^co-authored-by: <anything> <EMAIL>[ws]*$
+# Email is regex-escaped via the conservative approach: assume the
+# email passed policy validation (only safe chars per loader regex
+# /^[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+$/), so the only metachars present
+# are `.` and possibly `+` / `-`. We escape `.` and rely on the
+# permissive char set.
+ESCAPED_EMAIL=$(printf '%s' "$LOWER_EMAIL" | sed 's/[.[\*^$(){}+?|]/\\&/g')
+if grep -iE "^co-authored-by:[[:space:]]*[^<]*<${ESCAPED_EMAIL}>[[:space:]]*$" \
+  "$COMMIT_MSG_FILE" >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Build the trailer line. Idempotency above already lower-cased the
+# email for comparison; we ship the trailer with the policy-supplied
+# casing so the user's preferred display name + email render verbatim.
+TRAILER="Co-Authored-By: ${CO_NAME} <${CO_EMAIL}>"
+
+# Find the insert point: at the bottom of the message, after stripping
+# trailing blank/comment lines (git's scissors line `# -- >8 --` and
+# everything below is appended verbatim to preserve git's own view).
+TMP_BODY=$(mktemp "${TMPDIR:-/tmp}/rea-pcm.XXXXXX") || exit 0
+TMP_TAIL=$(mktemp "${TMPDIR:-/tmp}/rea-pcm.XXXXXX") || { rm -f "$TMP_BODY"; exit 0; }
+trap 'rm -f "$TMP_BODY" "$TMP_TAIL"' EXIT INT TERM
+
+# Split the file: body (above the scissors marker) vs. tail (scissors
+# and everything below). Codex round 2 P1: previously used python3
+# unconditionally — on environments where rea CLI is reachable but
+# python3 is missing, the split silently failed and the user's commit
+# body got dropped. awk is universally available on POSIX systems and
+# does the same work.
+SCISSORS='# ------------------------ >8 ------------------------'
+awk -v scissors="$SCISSORS" -v body_dst="$TMP_BODY" -v tail_dst="$TMP_TAIL" '
+  BEGIN { found = 0 }
+  {
+    if (!found && $0 == scissors) found = 1
+    if (found) print > tail_dst
+    else        print > body_dst
+  }
+' "$COMMIT_MSG_FILE"
+
+# Determine whether the body's last non-blank/non-comment line is a
+# real git trailer (`Key: value` where Key matches `[A-Za-z][-A-Za-z0-9]*`)
+# AND part of a multi-line trailer block (not the subject of a single-line
+# conventional commit). Codex round 3 P1: the round-2 fix correctly
+# rejected commit-prose `: ` patterns but still matched the conventional
+# commit subject form `feat: add x` because that line is ALSO
+# `[A-Za-z][-A-Za-z0-9]*: <value>`. The right distinguisher: a real
+# trailer block has at least one preceding non-blank body line; a bare
+# `feat: x` commit is just a subject and always needs a separator.
+LAST_BODY_LINE=$(awk '
+  /^[[:space:]]*#/ { next }
+  /^[[:space:]]*$/ { next }
+  { lastline = $0 }
+  END { if (lastline != "") print lastline }
+' "$TMP_BODY")
+BODY_LINE_COUNT=$(awk '
+  /^[[:space:]]*#/ { next }
+  /^[[:space:]]*$/ { next }
+  { count++ }
+  END { print count + 0 }
+' "$TMP_BODY")
+
+SEPARATOR_NEEDED=1
+if [ -z "$LAST_BODY_LINE" ]; then
+  SEPARATOR_NEEDED=0
+elif [ "$BODY_LINE_COUNT" -gt 1 ] && printf '%s' "$LAST_BODY_LINE" | grep -qE '^[A-Za-z][-A-Za-z0-9]*: '; then
+  SEPARATOR_NEEDED=0
+fi
+
+# Trim trailing blank lines from the body so the trailer lands cleanly
+# (without leaving a triple-newline before it).
+TMP_BODY_TRIMMED=$(mktemp "${TMPDIR:-/tmp}/rea-pcm.XXXXXX") || exit 0
+awk '
+  { lines[NR] = $0; total = NR }
+  END {
+    end = total
+    while (end > 0 && lines[end] ~ /^[[:space:]]*$/) { end-- }
+    for (i = 1; i <= end; i++) print lines[i]
+  }
+' "$TMP_BODY" > "$TMP_BODY_TRIMMED"
+
+# Compose the new file: trimmed body + (optional blank) + trailer + tail.
+{
+  cat "$TMP_BODY_TRIMMED"
+  if [ "$SEPARATOR_NEEDED" -eq 1 ]; then
+    printf '\n'
+  fi
+  printf '%s\n' "$TRAILER"
+  if [ -s "$TMP_TAIL" ]; then
+    cat "$TMP_TAIL"
+  fi
+} > "${COMMIT_MSG_FILE}.rea-tmp" && mv "${COMMIT_MSG_FILE}.rea-tmp" "$COMMIT_MSG_FILE"
+
+rm -f "$TMP_BODY_TRIMMED"
+exit 0

package/MIGRATING.md

@@ -59,6 +59,10 @@ are on the vanilla-git path — install husky first.
 - `.husky/pre-push` — package-managed; **do not edit**. Refreshed on every
   `rea upgrade`.
 - `.husky/commit-msg` — package-managed; **do not edit**. Same.
+- `.husky/prepare-commit-msg` — package-managed (added in 0.30.0).
+  Drives the optional `attribution.co_author` augmenter; **do not edit**.
+  No-op when `policy.attribution.co_author.enabled !== true`, so it is
+  safe to ship under every profile (default disabled).
 - `.git/hooks/pre-push` (fallback when `core.hooksPath` is unset).
 - `.claude/hooks/*.sh` — protection + audit + advisory hooks.
 - `.claude/agents/*.md`, `.claude/commands/*.md`.
@@ -125,6 +129,77 @@ 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: existing prepare-commit-msg (rea 0.30.0+)
+
+You probably have a hook that templates the message, adds a Jira
+ticket prefix, or inserts a branch name:
+
+```sh
+#!/bin/sh
+# .husky/prepare-commit-msg — user-authored
+COMMIT_MSG_FILE=$1
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+echo "[$BRANCH] $(cat "$COMMIT_MSG_FILE")" > "$COMMIT_MSG_FILE"
+```
+
+**rea 0.30.0+ refuses to overwrite a foreign `.husky/prepare-commit-msg`.**
+On `rea init` you'll see a `[fail]` from `rea doctor`:
+
+```
+[fail] prepare-commit-msg hook (attribution augmenter)
+       (attribution.co_author.enabled: true but the prepare-commit-msg
+        hook is foreign (no rea marker) — remove the existing hook
+        and re-run `rea init`, or set enabled: false.)
+```
+
+### Migration
+
+Two paths, depending on whether you intend to use the rea augmenter.
+
+**Path A — you want the augmenter (Co-Authored-By trailer)**
+
+Move your branch-prefix logic into rea's chained body. As of 0.30.0
+rea's prepare-commit-msg body does NOT support `.husky/prepare-commit-msg.d/*`
+fragments yet (it's on the 0.31.0 roadmap). For now, port the logic
+into a wrapper invoked by `commit-msg.d` instead:
+
+```bash
+mkdir -p .husky/commit-msg.d
+cat > .husky/commit-msg.d/00-branch-prefix <<'EOF'
+#!/bin/sh
+# Branch-prefix logic moved from prepare-commit-msg to commit-msg.d
+# (runs AFTER rea's augmenter, before the commit is finalized).
+BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo unknown)
+case $(head -1 "$1") in
+  "[$BRANCH]"*) ;;  # already prefixed
+  *) printf '[%s] %s' "$BRANCH" "$(cat "$1")" > "$1" ;;
+esac
+EOF
+chmod +x .husky/commit-msg.d/00-branch-prefix
+```
+
+Then remove the old `.husky/prepare-commit-msg`:
+
+```bash
+rm .husky/prepare-commit-msg .git/hooks/prepare-commit-msg
+```
+
+Re-run `rea init`. rea's prepare-commit-msg now installs cleanly.
+
+**Path B — you do NOT want the augmenter**
+
+Leave your existing hook in place. Set the augmenter off explicitly:
+
+```yaml
+# .rea/policy.yaml
+attribution:
+  co_author:
+    enabled: false
+```
+
+`rea doctor` reports `[warn]` (not fail) for the foreign hook —
+your commits keep going through your existing logic.
+
 ## Conflict pattern: lint-staged on pre-push
 
 You probably have:

package/dist/cli/doctor.d.ts

@@ -19,6 +19,44 @@ export interface CheckResult {
  * Exported so tests can drive this without spinning up the full `runDoctor`.
  */
 export declare function checkFingerprintStore(baseDir: string): Promise<CheckResult>;
+/**
+ * 0.30.0 (Class M settings.json schema) — `EXPECTED_HOOKS` is exported
+ * so the schema validator at `src/config/settings-schema.ts` can
+ * cross-check rea-shipped hook filenames against entries it sees in
+ * a consumer's `.claude/settings.json`. The validator's `--strict`
+ * mode FAILS when a known rea-managed hook is missing from the
+ * consumer's registration; default mode logs a warn.
+ */
+export declare const EXPECTED_AGENTS: string[];
+export declare const EXPECTED_HOOKS: string[];
+/**
+ * 0.30.0 Class M — validate `.claude/settings.json` against the zod
+ * schema in `src/config/settings-schema.ts`.
+ *
+ * Status posture:
+ *
+ *   - `strict: false` (default `rea doctor`) — emit a warn when:
+ *       - zod parse fails (unknown top-level key, missing matcher,
+ *         malformed hook entry, etc.),
+ *       - any `command` contains a `..` traversal after stripping
+ *         `$CLAUDE_PROJECT_DIR`,
+ *       - any rea-shipped hook from `EXPECTED_HOOKS` is missing from
+ *         the consumer's registrations.
+ *     The harness keeps working — the schema only refuses to call
+ *     malformed hook entries; we surface the issue without breaking
+ *     the install.
+ *
+ *   - `strict: true` (`rea doctor --strict`) — fail (hard) on the
+ *     same conditions. Used by CI gates that want a hard floor on
+ *     consumer settings.
+ *
+ * Returns `pass` when everything cleared. Returns one `CheckResult`
+ * per concern; called once and emits one result. Combined with the
+ * existing `checkSettingsJson` (which checks for the historical Bash
+ * + Write|Edit|MultiEdit|NotebookEdit matchers), gives consumers a
+ * complete picture.
+ */
+export declare function checkSettingsSchema(baseDir: string, strict: boolean): CheckResult;
 /**
  * Detect whether `baseDir` is a git repository. Returns true for the three
  * shapes git itself accepts:
@@ -46,6 +84,7 @@ export declare function checkFingerprintStore(baseDir: string): Promise<CheckRes
  * NOT a trust boundary. Do not key security decisions on the return value.
  */
 export declare function isGitRepo(baseDir: string): boolean;
+export declare function checkPrepareCommitMsgHook(baseDir: string): CheckResult;
 /**
  * Hard-fail when `policy.review.codex_required: true` but the `codex`
  * binary is not on PATH. Pre-0.12.0 this prereq surfaced only at first
@@ -137,7 +176,9 @@ export declare function checkDelegationRoundTrip(baseDir: string): Promise<Check
  *
  * `activeForeign` always yields `fail` — a foreign hook bypassing the gate is a hard governance gap.
  */
-export declare function collectChecks(baseDir: string, codexProbeState?: CodexProbeState, prePushState?: PrePushDoctorState): CheckResult[];
+export declare function collectChecks(baseDir: string, codexProbeState?: CodexProbeState, prePushState?: PrePushDoctorState, options?: {
+    strict?: boolean;
+}): CheckResult[];
 export interface RunDoctorOptions {
     /** When true, print a 7-day telemetry summary after the checks (G11.5). */
     metrics?: boolean;
@@ -156,6 +197,13 @@ export interface RunDoctorOptions {
      * audit log with probe records.
      */
     smoke?: boolean;
+    /**
+     * 0.30.0 — when true, every advisory check (settings.json schema
+     * cross-check, prepare-commit-msg foreign-hook warn, etc.) is
+     * promoted to hard fail. Used by CI gates that want a strict floor
+     * on consumer installs. Default `false`.
+     */
+    strict?: boolean;
 }
 export interface DriftRow {
     path: string;