@bookedsolid/rea 0.30.1 → 0.32.0

package/.husky/prepare-commit-msg

@@ -36,28 +36,65 @@ set -u
 COMMIT_MSG_FILE="${1:-}"
 COMMIT_SOURCE="${2:-}"
 
+REA_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+# Forward declaration — the extension-chain runner is defined further
+# down (after $REA_ROOT is set so the dir lookup is anchored). We call
+# it from every "augmenter skipped" exit point so consumer fragments
+# under .husky/prepare-commit-msg.d/* run regardless of whether rea's
+# own augmenter ran. The function fires fragments in lex order,
+# logs-and-continues on non-zero exits, and is a no-op if the dir is
+# absent or empty.
+#
+# 0.32.0 Phase 3: the pre-0.32.0 layout exited early at every
+# precondition gate, which made the extension surface unreachable
+# when (a) attribution was disabled, (b) HALT was active, or (c)
+# REA_SKIP_ATTRIBUTION was set. The new layout runs the chain at the
+# end of every exit path EXCEPT when the message file itself is
+# missing/unparseable (no point running fragments against a path that
+# doesn't exist).
+run_extension_chain() {
+  ext_dir="${REA_ROOT}/.husky/prepare-commit-msg.d"
+  if [ -d "$ext_dir" ]; then
+    for frag in "$ext_dir"/*; do
+      [ -e "$frag" ] || continue
+      [ -f "$frag" ] || continue
+      [ -x "$frag" ] || continue
+      if ! "$frag" "$COMMIT_MSG_FILE" "$COMMIT_SOURCE"; then
+        printf 'rea: prepare-commit-msg.d fragment exited non-zero: %s (continuing)\n' \
+          "$(basename "$frag")" >&2
+      fi
+    done
+  fi
+}
+
 # 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.
+# Missing message file → nothing to augment AND nothing for fragments
+# to act on either. Exit immediately without running the chain.
 if [ -z "$COMMIT_MSG_FILE" ] || [ ! -f "$COMMIT_MSG_FILE" ]; then
   exit 0
 fi
 
-# Per-invocation override.
+# Per-invocation override — skip the augmenter, but still run consumer
+# fragments. The flag is named REA_SKIP_ATTRIBUTION, not REA_SKIP_HOOK,
+# precisely so the rest of the chain runs.
 if [ -n "${REA_SKIP_ATTRIBUTION:-}" ]; then
+  run_extension_chain
   exit 0
 fi
 
-REA_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
-
-# HALT kill switch — refuse to mutate anything while frozen.
+# HALT kill switch — refuse to mutate anything while frozen. The
+# extension chain is also skipped under HALT: a frozen system means
+# "no agent-side actions" and consumer fragments are agent-side too.
 if [ -f "${REA_ROOT}/.rea/HALT" ]; then
   exit 0
 fi
 
 POLICY_FILE="${REA_ROOT}/.rea/policy.yaml"
 if [ ! -f "$POLICY_FILE" ]; then
+  run_extension_chain
   exit 0
 fi
 
@@ -172,6 +209,7 @@ print(enabled); print(name); print(email); print(skip_merge)
 PY
 )
   if [ -z "$CO_AUTHOR_PARSE" ]; then
+    run_extension_chain
     exit 0
   fi
   ENABLED=$(printf '%s\n' "$CO_AUTHOR_PARSE" | sed -n '1p')
@@ -179,11 +217,15 @@ PY
   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.
+  # Neither rea CLI nor python3 reachable — silent no-op for the
+  # augmenter, but still run consumer fragments. The chain doesn't
+  # need policy values; it just runs `.husky/prepare-commit-msg.d/*`.
+  run_extension_chain
   exit 0
 fi
 
 if [ "$ENABLED" != "true" ]; then
+  run_extension_chain
   exit 0
 fi
 
@@ -204,11 +246,13 @@ if [ -z "$CO_NAME" ] || [ -z "$CO_EMAIL" ]; then
     "$([ -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
+  run_extension_chain
   exit 0
 fi
 
 # skip_merge: true → skip when commit source is 'merge'.
 if [ "$SKIP_MERGE" = "true" ] && [ "$COMMIT_SOURCE" = "merge" ]; then
+  run_extension_chain
   exit 0
 fi
 
@@ -226,6 +270,7 @@ LOWER_EMAIL=$(printf '%s' "$CO_EMAIL" | tr '[:upper:]' '[:lower:]')
 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
+  run_extension_chain
   exit 0
 fi
 
@@ -311,4 +356,33 @@ awk '
 } > "${COMMIT_MSG_FILE}.rea-tmp" && mv "${COMMIT_MSG_FILE}.rea-tmp" "$COMMIT_MSG_FILE"
 
 rm -f "$TMP_BODY_TRIMMED"
+
+# ── Extension-hook chaining ───────────────────────────────────────────────────
+# 0.32.0 — `.husky/prepare-commit-msg.d/*` extension surface mirrors
+# the `.husky/commit-msg.d/*` and `.husky/pre-push.d/*` patterns from
+# 0.13.0. Source every executable file under
+# `.husky/prepare-commit-msg.d/` in lexical order. Missing directory
+# is a no-op (backward compatible). Each fragment receives the same
+# `$1` (commit message file path) and `$2` (commit source) that git
+# delivered to this hook so consumers can layer on their own
+# augmenters (lint-staged --on-prepare, branch-name-injection,
+# ticket-reference-prepend, …) without losing rea coverage.
+#
+# Fragments run AFTER rea's attribution augmenter so the
+# `Co-Authored-By` trailer is already in the file before any consumer
+# fragment reads it; that lets a fragment reorder trailers, dedupe,
+# or run its own template substitution against the augmented body.
+#
+# A non-zero exit from a fragment does NOT fail the commit — this
+# hook is purely additive (its bash counterpart `commit-msg` is the
+# blocking gate). We log the failure to stderr and continue so a
+# broken consumer fragment can't take down `git commit`.
+#
+# The actual chain body lives in `run_extension_chain` (defined near
+# the top of the file). The reason for the early definition: several
+# augmenter-skip exit paths (enabled: false, missing identity, idempo-
+# tency hit, skip_merge match) need to run the chain too, so consumer
+# fragments fire regardless of whether rea's own augmenter activated.
+run_extension_chain
+
 exit 0

package/MIGRATING.md

@@ -78,13 +78,16 @@ are on the vanilla-git path — install husky first.
 The only files rea touches are explicitly enumerated above. Everything
 else is the consumer's surface.
 
-## Extension surface (added in 0.13.0)
+## Extension surface (added in 0.13.0; expanded in 0.32.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).
+`.husky/pre-push.d/*`, `.husky/commit-msg.d/*`, and (as of 0.32.0)
+`.husky/prepare-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) — EXCEPT for the `prepare-commit-msg.d/*` lane,
+which logs and continues so a broken fragment can't take down `git
+commit`.
 
 - Fragment receives positional args from git (`<remote-name> <remote-url>`
   for pre-push, `<commit-msg-file>` for commit-msg).
@@ -158,26 +161,32 @@ 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:
+Move your branch-prefix logic into a `.husky/prepare-commit-msg.d/*`
+fragment. As of **0.32.0** rea's prepare-commit-msg body sources every
+executable file in `.husky/prepare-commit-msg.d/` in lexical order
+AFTER its own attribution augmenter runs (mirrors the
+`commit-msg.d/*` and `pre-push.d/*` extension surfaces from 0.13.0).
+Each fragment receives the same `$1` (commit-message file path) and
+`$2` (commit source) git delivered to the hook:
 
 ```bash
-mkdir -p .husky/commit-msg.d
-cat > .husky/commit-msg.d/00-branch-prefix <<'EOF'
+mkdir -p .husky/prepare-commit-msg.d
+cat > .husky/prepare-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).
+# Runs AFTER rea's Co-Authored-By augmenter. $1 = commit-msg file.
 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
+chmod +x .husky/prepare-commit-msg.d/00-branch-prefix
 ```
 
+A non-zero exit from a fragment does NOT fail the commit (the augmenter
+hook is purely additive; the blocking gate is `commit-msg`). Broken
+fragments log to stderr and the hook continues.
+
 Then remove the old `.husky/prepare-commit-msg`:
 
 ```bash

package/dist/cli/audit-specialists.d.ts

@@ -1,20 +1,33 @@
 /**
- * `rea audit specialists` — 0.29.0 reader CLI for delegation-telemetry.
+ * `rea audit specialists` — reader CLI for delegation-telemetry
+ * (0.29.0; `--since` / `--session` added 0.31.0).
  *
- * Walks `.rea/audit.jsonl`, filters records by
- * `tool_name === 'rea.delegation_signal'`, groups by
- * `metadata.subagent_type`, and prints a table (default) or JSON
- * document (`--json`).
+ * Walks `.rea/audit.jsonl` (plus any rotated files when `--since` is
+ * given), filters records by `tool_name === 'rea.delegation_signal'`,
+ * groups by `metadata.subagent_type`, and prints a table (default) or
+ * JSON document (`--json`).
  *
- * # Current-session-only in v1
+ * # Session filtering
  *
- * v1 has NO `--since` flag and NO `--session=ID` flag. The principal-
- * engineer scope-cut deferred both to 0.29.1. The filter is:
+ * Three ways to scope, in precedence order:
  *
- *   - If `CLAUDE_SESSION_ID` is set, include only records whose
- *     `metadata.session_id_observed` matches.
- *   - Otherwise, include all records in the chain and print a note so
- *     the operator knows what they're seeing.
+ *   1. `--session <id>`  — explicit. Filters to records whose
+ *      `metadata.session_id_observed` matches `<id>`. The literal
+ *      `--session all` disables filtering entirely (show every
+ *      session). Wins over the env var.
+ *   2. `$CLAUDE_SESSION_ID` — when set and `--session` is omitted,
+ *      filters to the current Claude Code session.
+ *   3. neither — no filter; every record in the walked files is shown,
+ *      and a note tells the operator what they're seeing.
+ *
+ * # `--since <rotated-file>`
+ *
+ * By default the reader walks only the current `.rea/audit.jsonl`.
+ * `--since audit-YYYYMMDD-HHMMSS.jsonl` extends the walk backward: the
+ * named rotated file and every rotated file after it (timestamp-
+ * ascending) are scanned, then the current `audit.jsonl` as the tail.
+ * Mirrors `rea audit verify --since`. The filename must match the
+ * canonical rotated-audit shape or the CLI exits 1.
  *
  * # Output shape
  *
@@ -23,8 +36,8 @@
  *   code-reviewer             5      2026-05-12T21:28:00Z
  *   deep-dive                 2      2026-05-12T21:14:00Z
  *
- * JSON mode prints `{ session_filter, records, groups }` where
- * `records` is the raw filtered subset (for piping into jq) and
+ * JSON mode prints `{ session_filter, records, groups, files_scanned }`
+ * where `records` is the raw filtered subset (for piping into jq) and
  * `groups` is the per-subagent rollup.
  */
 import type { Command } from 'commander';
@@ -34,17 +47,48 @@ export interface AuditSpecialistsOptions {
     json?: boolean;
     /**
      * Override session filtering. Production callers omit (the CLI reads
-     * `CLAUDE_SESSION_ID` from the env). Tests set this so they don't
-     * mutate `process.env`.
+     * `--session` then `CLAUDE_SESSION_ID` from the env). Tests set this
+     * so they don't mutate `process.env`.
      *
      * - `string` → filter to records whose `session_id_observed` matches.
      * - `null`   → no filter (show all records).
-     * - `undefined` → derive from env.
+     * - `undefined` → derive from `--session` flag then env.
      */
     sessionFilter?: string | null;
+    /**
+     * 0.31.0 — explicit `--session <id>` flag value. Resolution rules:
+     *
+     *   - `'all'` (case-insensitive) → no filter (equivalent to
+     *     `sessionFilter: null`), `session_filter_source: 'option'`.
+     *   - any other non-empty string → filter to that session,
+     *     `session_filter_source: 'option'`.
+     *   - `undefined` → fall through to `sessionFilter`, then env.
+     *
+     * `sessionFilter` (the test seam) still wins over this when both are
+     * set — tests inject `sessionFilter` directly and don't pass
+     * `sessionOption`.
+     */
+    sessionOption?: string;
+    /**
+     * 0.31.0 — `--since <rotated-file>` flag value. When set, the named
+     * rotated audit file plus every later rotated file (timestamp-
+     * ascending) are walked before the current `.rea/audit.jsonl`.
+     * Must match `audit-YYYYMMDD-HHMMSS(-N).jsonl`. Validation failure
+     * throws `AuditSpecialistsSinceError` so the commander wrapper can
+     * exit 1 with a clear message.
+     */
+    since?: string;
     /** Override CWD. Tests set this; production uses `process.cwd()`. */
     baseDir?: string;
 }
+/**
+ * Thrown by `computeAuditSpecialists` when `--since` names something
+ * that is not a valid rotated-audit basename, or names a rotated file
+ * that does not exist. The commander wrapper catches it and exits 1.
+ */
+export declare class AuditSpecialistsSinceError extends Error {
+    constructor(message: string);
+}
 interface DelegationGroup {
     subagent_type: string;
     count: number;
@@ -53,7 +97,7 @@ interface DelegationGroup {
     /** Breakdown of which delegation_tool fired (Agent vs. Skill). */
     by_tool: Record<DelegationTool, number>;
 }
-interface DelegationRecord {
+export interface DelegationRecord {
     timestamp: string;
     session_id_observed: string;
     delegation_tool: DelegationTool;
@@ -78,11 +122,48 @@ interface AuditSpecialistsResult {
     files_scanned: string[];
 }
 /**
- * Read the audit file and return delegation records (filtered + parsed
- * into a reader-friendly shape). Malformed lines are skipped silently
- * — `rea audit verify` is the right tool for chain integrity.
+ * List rotated audit files in `.rea/`, timestamp-ascending. Filenames
+ * follow `audit-YYYYMMDD-HHMMSS(-N).jsonl`. Sorted via
+ * `rotatedAuditSortKey` — the `YYYYMMDD-HHMMSS` block lexically (it is
+ * fixed-width zero-padded, so lexical == chronological) then the `-N`
+ * intra-second suffix NUMERICALLY (a plain lexical sort of the whole
+ * basename misorders two-digit suffixes — see `rotatedAuditSortKey`).
+ * Mirrors the private helper in `audit.ts` — kept local so this reader
+ * doesn't import the verify command's internals.
+ *
+ * Exported (0.31.0 round-2 P3) so `delegation-advisory.ts` can resolve
+ * the rotated-file set without duplicating the `ROTATED_AUDIT_RE` glob:
+ * the advisory's "did this session delegate" predicate must scan rotated
+ * segments too, or a delegation recorded before an audit rotation is
+ * invisible to the nudge and the session gets a false-positive advisory.
+ */
+export declare function listRotatedAuditFiles(reaDir: string): Promise<string[]>;
+/**
+ * Resolve the ordered list of absolute audit-file paths to walk.
+ *
+ * - `since === undefined` → just the current `.rea/audit.jsonl` (when
+ *   it exists). Pre-0.31.0 behavior.
+ * - `since` set → validate it names a real rotated file, then walk
+ *   that file + every later rotated file (timestamp-ascending), with
+ *   the current `audit.jsonl` as the tail.
+ *
+ * The current `audit.jsonl` is included at the END of the walk
+ * whenever it exists — it is always the newest segment of the chain.
+ * A `--since` that names a non-rotated string, or a rotated file that
+ * isn't present on disk, throws `AuditSpecialistsSinceError`.
+ */
+export declare function resolveAuditFileWalk(baseDir: string, since: string | undefined): Promise<string[]>;
+/**
+ * Read the audit file(s) and return delegation records (filtered +
+ * parsed into a reader-friendly shape). Malformed lines are skipped
+ * silently — `rea audit verify` is the right tool for chain integrity.
+ *
+ * `since` defaults to `undefined` (current `.rea/audit.jsonl` only) so
+ * existing callers — including `computeDelegationAdvisory` in
+ * `delegation-advisory.ts` — keep their pre-0.31.0 single-file
+ * behavior without passing the argument.
  */
-export declare function loadDelegationRecords(baseDir: string, sessionFilter: string | null): Promise<{
+export declare function loadDelegationRecords(baseDir: string, sessionFilter: string | null, since?: string): Promise<{
     records: DelegationRecord[];
     filesScanned: string[];
 }>;
@@ -99,8 +180,9 @@ export declare function groupBySubagent(records: DelegationRecord[]): Delegation
  */
 export declare function computeAuditSpecialists(options?: AuditSpecialistsOptions): Promise<AuditSpecialistsResult>;
 /**
- * Commander entrypoint. Reads, renders, exits 0. The CLI is read-only
- * — no audit-chain writes, no exit-code-as-verdict semantics.
+ * Commander entrypoint. Reads, renders, exits 0 on success / 1 when
+ * `--since` is malformed or names a missing rotated file. The CLI is
+ * read-only — no audit-chain writes.
  */
 export declare function runAuditSpecialists(options: AuditSpecialistsOptions): Promise<void>;
 /**