@bookedsolid/rea 0.10.1 → 0.10.3

package/dist/hooks/review-gate/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Public entry point for the review-gate TypeScript port (G).
+ *
+ * ## Scope after Phase 2a (0.10.3)
+ *
+ * - Phase 1 primitives (args, banner, cache-key, constants, errors,
+ *   hash, metadata, policy, protected-paths) — pure, dependency-free.
+ * - Phase 2a supporting modules (base-resolve, diff, audit, cache) —
+ *   wrap git subprocesses, wrap audit append/scan, wrap the review-
+ *   cache lookup. No top-level gate yet; composition lands in Phase 2b.
+ *
+ * The bash core in `hooks/_lib/push-review-core.sh` continues to run in
+ * production until phase 4. These exports are library-level primitives
+ * that tests and Phase 2b compose; no behavioral surface is registered
+ * for external callers here.
+ *
+ * See `docs/design/push-review-ts-port.md` for the full plan.
+ */
+export * from './args.js';
+export * from './banner.js';
+export * from './cache-key.js';
+export * from './constants.js';
+export * from './errors.js';
+export * from './hash.js';
+export * from './metadata.js';
+export * from './policy.js';
+export * from './protected-paths.js';
+export { currentBranch, diffNameStatus, fullDiff, gitCommonDir, hasCommitLocally, mergeBase, readGitActor, readGitConfig, refExists, resolveHead, resolveRefToSha, resolveRemoteDefaultRef, resolveUpstream, revListCount, spawnGit, type DiffResult, type GitRunResult, type GitRunner, type NameStatusResult, } from './diff.js';
+export { computeInitialTargetLabel, resolveBaseForRefspec, resolveNewBranchBase, stripRefsHeadsOnly, type ResolveBaseDeps, type ResolvedBase, } from './base-resolve.js';
+export { CODEX_REVIEW_SKIPPED_TOOL, ESCAPE_HATCH_SERVER, PUSH_REVIEW_CACHE_ERROR_TOOL, PUSH_REVIEW_CACHE_HIT_TOOL, PUSH_REVIEW_SERVER, PUSH_REVIEW_SKIPPED_TOOL, emitCodexReviewSkipped, emitPushReviewSkipped, hasValidCodexReview, isQualifyingCodexReview, type SkipCodexReviewAuditInput, type SkipPushReviewAuditInput, } from './audit.js';
+export { checkReviewCache, type CacheOutcome, type CheckReviewCacheInput, } from './cache.js';

package/dist/hooks/review-gate/index.js

@@ -0,0 +1,35 @@
+/**
+ * Public entry point for the review-gate TypeScript port (G).
+ *
+ * ## Scope after Phase 2a (0.10.3)
+ *
+ * - Phase 1 primitives (args, banner, cache-key, constants, errors,
+ *   hash, metadata, policy, protected-paths) — pure, dependency-free.
+ * - Phase 2a supporting modules (base-resolve, diff, audit, cache) —
+ *   wrap git subprocesses, wrap audit append/scan, wrap the review-
+ *   cache lookup. No top-level gate yet; composition lands in Phase 2b.
+ *
+ * The bash core in `hooks/_lib/push-review-core.sh` continues to run in
+ * production until phase 4. These exports are library-level primitives
+ * that tests and Phase 2b compose; no behavioral surface is registered
+ * for external callers here.
+ *
+ * See `docs/design/push-review-ts-port.md` for the full plan.
+ */
+// Phase 1 primitives
+export * from './args.js';
+export * from './banner.js';
+export * from './cache-key.js';
+export * from './constants.js';
+export * from './errors.js';
+export * from './hash.js';
+export * from './metadata.js';
+export * from './policy.js';
+export * from './protected-paths.js';
+// Phase 2a supporting modules — re-export explicit names to avoid
+// double-exporting `computeCacheKey` (which lives in both cache-key.ts
+// and cache.ts; cache.ts's is a strict re-export of Phase 1's).
+export { currentBranch, diffNameStatus, fullDiff, gitCommonDir, hasCommitLocally, mergeBase, readGitActor, readGitConfig, refExists, resolveHead, resolveRefToSha, resolveRemoteDefaultRef, resolveUpstream, revListCount, spawnGit, } from './diff.js';
+export { computeInitialTargetLabel, resolveBaseForRefspec, resolveNewBranchBase, stripRefsHeadsOnly, } from './base-resolve.js';
+export { CODEX_REVIEW_SKIPPED_TOOL, ESCAPE_HATCH_SERVER, PUSH_REVIEW_CACHE_ERROR_TOOL, PUSH_REVIEW_CACHE_HIT_TOOL, PUSH_REVIEW_SERVER, PUSH_REVIEW_SKIPPED_TOOL, emitCodexReviewSkipped, emitPushReviewSkipped, hasValidCodexReview, isQualifyingCodexReview, } from './audit.js';
+export { checkReviewCache, } from './cache.js';

package/dist/hooks/review-gate/metadata.d.ts

@@ -0,0 +1,98 @@
+/**
+ * OS / agent / repo identity collection for audit records.
+ *
+ * Closes defect M (0.9.4): the bash core's `jq --arg os_pid "$PID"` wrote
+ * the pid as a JSON string; the audit consumer expected an integer, and the
+ * schema had to tolerate both. The TS port emits pid/ppid as numbers from
+ * day one (the JS runtime's `process.pid` is already a `number`), removing
+ * the whole class of jq `--arg` vs `--argjson` confusion.
+ *
+ * ## Why capture this at all
+ *
+ * A skip-audit record (`REA_SKIP_PUSH_REVIEW` / `REA_SKIP_CODEX_REVIEW`) is
+ * the one place the gate is voluntarily weakened. The actor field (from
+ * `git config user.email`) is mutable — a process with write access to
+ * `.git/config` can stamp any email it likes. Supplementing that with
+ * non-forgeable host-level identity (uid, hostname, pid, ppid, tty, CI
+ * flag) gives a forensic investigator something to cross-reference when
+ * a skip record turns out to have been unauthorized.
+ *
+ * ## Determinism + testability
+ *
+ * Every collector is a plain function over `process` / `os` / `node:child_process`
+ * so tests can stub the collector's inputs cleanly. The public API takes no
+ * arguments (production use) and the helpers are exported for tests.
+ */
+export interface OsIdentity {
+    /** POSIX uid as a string (empty when not available — Windows). */
+    uid: string;
+    /** `whoami` output — username or empty string. */
+    whoami: string;
+    /** `hostname` output. */
+    hostname: string;
+    /** This process's pid — number, not string (defect M). */
+    pid: number;
+    /** Parent process's pid — number, not string (defect M). */
+    ppid: number;
+    /** `ps -o command= -p $PPID` output, capped at 512 bytes. */
+    ppid_cmd: string;
+    /** `tty` output or `"not-a-tty"`. */
+    tty: string;
+    /** `CI` env var value or empty string. */
+    ci: string;
+}
+/**
+ * Collect current-process OS identity. Every individual collector degrades
+ * to an empty-string fallback on any exception — matching the bash core's
+ * `id -u || echo ""`, `whoami || echo ""`, `hostname || echo ""` pattern
+ * (push-review-core.sh §420-422, 426). Codex pass-1 on phase 1 flagged
+ * the earlier implementation that called `userInfo()` and `hostname()`
+ * outside any try/catch and could therefore throw on hosts with broken
+ * NSS/passwd lookups, which would silently block the skip-audit path.
+ */
+export declare function collectOsIdentity(): OsIdentity;
+/**
+ * Read POSIX uid + whoami. Each field is collected INDEPENDENTLY so a
+ * partial-lookup-failure (e.g. LDAP/NSS returns the uid but no passwd
+ * entry) still yields one field rather than dropping both. Bash-core
+ * parity (push-review-core.sh §420-421): `id -u` and `whoami` are two
+ * separate invocations, each with its own `|| echo ""` fallback.
+ *
+ * Codex pass-2 on phase 1 flagged the prior single-`userInfo()` version:
+ * a broken NSS lookup zeroed out both fields at once, weakening forensic
+ * metadata on shared hosts. We now prefer the POSIX primitives
+ * (`os.userInfo()` internally reads the passwd entry) but isolate the
+ * failures so uid and whoami cannot both disappear together when only
+ * one of them is actually unavailable.
+ */
+export declare function readUidAndWhoami(): {
+    uid: string;
+    whoami: string;
+};
+/**
+ * Read `hostname` via `os.hostname`. Returns an empty string on any error.
+ * Exported for unit tests.
+ */
+export declare function readHostname(): string;
+/**
+ * Read `ps -o command= -p <ppid>` safely. Returns the (truncated) command
+ * or an empty string on any failure.
+ *
+ * Security: args are passed as an array, never interpolated into a shell
+ * string. `ps` is the only executable spawned.
+ */
+export declare function readPpidCommand(ppid: number): string;
+/**
+ * Return the actual controlling tty path (e.g. `/dev/ttys001`) when one
+ * exists, or the literal string `not-a-tty` otherwise. Bash-core parity
+ * (push-review-core.sh §426): `tty 2>/dev/null || echo "not-a-tty"`.
+ *
+ * Codex pass-1 on phase 1 flagged the earlier `/dev/tty` literal as a
+ * parity regression — the audit consumer expects the real device path so
+ * forensic tooling can distinguish tty1 from tty2 on the same host.
+ *
+ * Implementation: we shell out to `tty(1)` exactly as bash does. On
+ * systems without `tty` (distroless, minimal Alpine without coreutils-
+ * full) we degrade to `not-a-tty`.
+ */
+export declare function readTty(): string;

package/dist/hooks/review-gate/metadata.js

@@ -0,0 +1,158 @@
+/**
+ * OS / agent / repo identity collection for audit records.
+ *
+ * Closes defect M (0.9.4): the bash core's `jq --arg os_pid "$PID"` wrote
+ * the pid as a JSON string; the audit consumer expected an integer, and the
+ * schema had to tolerate both. The TS port emits pid/ppid as numbers from
+ * day one (the JS runtime's `process.pid` is already a `number`), removing
+ * the whole class of jq `--arg` vs `--argjson` confusion.
+ *
+ * ## Why capture this at all
+ *
+ * A skip-audit record (`REA_SKIP_PUSH_REVIEW` / `REA_SKIP_CODEX_REVIEW`) is
+ * the one place the gate is voluntarily weakened. The actor field (from
+ * `git config user.email`) is mutable — a process with write access to
+ * `.git/config` can stamp any email it likes. Supplementing that with
+ * non-forgeable host-level identity (uid, hostname, pid, ppid, tty, CI
+ * flag) gives a forensic investigator something to cross-reference when
+ * a skip record turns out to have been unauthorized.
+ *
+ * ## Determinism + testability
+ *
+ * Every collector is a plain function over `process` / `os` / `node:child_process`
+ * so tests can stub the collector's inputs cleanly. The public API takes no
+ * arguments (production use) and the helpers are exported for tests.
+ */
+import { hostname, userInfo } from 'node:os';
+import { spawnSync } from 'node:child_process';
+/**
+ * Collect current-process OS identity. Every individual collector degrades
+ * to an empty-string fallback on any exception — matching the bash core's
+ * `id -u || echo ""`, `whoami || echo ""`, `hostname || echo ""` pattern
+ * (push-review-core.sh §420-422, 426). Codex pass-1 on phase 1 flagged
+ * the earlier implementation that called `userInfo()` and `hostname()`
+ * outside any try/catch and could therefore throw on hosts with broken
+ * NSS/passwd lookups, which would silently block the skip-audit path.
+ */
+export function collectOsIdentity() {
+    const { uid, whoami } = readUidAndWhoami();
+    const host = readHostname();
+    const pid = process.pid;
+    const ppid = process.ppid;
+    const ppid_cmd = readPpidCommand(ppid);
+    const tty = readTty();
+    const ci = process.env['CI'] ?? '';
+    return { uid, whoami, hostname: host, pid, ppid, ppid_cmd, tty, ci };
+}
+/**
+ * Read POSIX uid + whoami. Each field is collected INDEPENDENTLY so a
+ * partial-lookup-failure (e.g. LDAP/NSS returns the uid but no passwd
+ * entry) still yields one field rather than dropping both. Bash-core
+ * parity (push-review-core.sh §420-421): `id -u` and `whoami` are two
+ * separate invocations, each with its own `|| echo ""` fallback.
+ *
+ * Codex pass-2 on phase 1 flagged the prior single-`userInfo()` version:
+ * a broken NSS lookup zeroed out both fields at once, weakening forensic
+ * metadata on shared hosts. We now prefer the POSIX primitives
+ * (`os.userInfo()` internally reads the passwd entry) but isolate the
+ * failures so uid and whoami cannot both disappear together when only
+ * one of them is actually unavailable.
+ */
+export function readUidAndWhoami() {
+    let uid = '';
+    let whoami = '';
+    try {
+        // Node exposes the raw numeric uid via process.getuid() on POSIX —
+        // this goes through the kernel, not through passwd. If it throws
+        // (Windows), the fallback is '' and we still try whoami below.
+        const getuid = process.getuid;
+        if (typeof getuid === 'function') {
+            const raw = getuid.call(process);
+            if (typeof raw === 'number' && raw >= 0)
+                uid = String(raw);
+        }
+    }
+    catch {
+        // swallow — uid stays ''
+    }
+    try {
+        const info = userInfo({ encoding: 'utf8' });
+        whoami = info.username ?? '';
+        // If the kernel-uid probe above failed but userInfo() succeeded, use
+        // its uid as a secondary source.
+        if (uid.length === 0 && typeof info.uid === 'number' && info.uid >= 0) {
+            uid = String(info.uid);
+        }
+    }
+    catch {
+        // swallow — whoami stays ''
+    }
+    return { uid, whoami };
+}
+/**
+ * Read `hostname` via `os.hostname`. Returns an empty string on any error.
+ * Exported for unit tests.
+ */
+export function readHostname() {
+    try {
+        return hostname();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Read `ps -o command= -p <ppid>` safely. Returns the (truncated) command
+ * or an empty string on any failure.
+ *
+ * Security: args are passed as an array, never interpolated into a shell
+ * string. `ps` is the only executable spawned.
+ */
+export function readPpidCommand(ppid) {
+    if (!Number.isFinite(ppid) || ppid <= 0)
+        return '';
+    try {
+        const result = spawnSync('ps', ['-o', 'command=', '-p', String(ppid)], {
+            encoding: 'utf8',
+            timeout: 2_000,
+        });
+        if (result.status !== 0)
+            return '';
+        const out = (result.stdout ?? '').replace(/\n+$/, '');
+        return out.slice(0, 512);
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Return the actual controlling tty path (e.g. `/dev/ttys001`) when one
+ * exists, or the literal string `not-a-tty` otherwise. Bash-core parity
+ * (push-review-core.sh §426): `tty 2>/dev/null || echo "not-a-tty"`.
+ *
+ * Codex pass-1 on phase 1 flagged the earlier `/dev/tty` literal as a
+ * parity regression — the audit consumer expects the real device path so
+ * forensic tooling can distinguish tty1 from tty2 on the same host.
+ *
+ * Implementation: we shell out to `tty(1)` exactly as bash does. On
+ * systems without `tty` (distroless, minimal Alpine without coreutils-
+ * full) we degrade to `not-a-tty`.
+ */
+export function readTty() {
+    try {
+        const result = spawnSync('tty', [], {
+            encoding: 'utf8',
+            timeout: 2_000,
+            stdio: ['inherit', 'pipe', 'pipe'],
+        });
+        if (result.status === 0) {
+            const out = (result.stdout ?? '').replace(/\n+$/, '');
+            if (out.length > 0)
+                return out;
+        }
+    }
+    catch {
+        // fall through to the not-a-tty fallback
+    }
+    return 'not-a-tty';
+}

package/dist/hooks/review-gate/policy.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Policy accessors for the review-gate modules.
+ *
+ * The bash core resolves `review.codex_required` via `node dist/scripts/read-
+ * policy-field.js` and evaluates `REA_SKIP_PUSH_REVIEW` / `REA_SKIP_CODEX_REVIEW`
+ * directly from env vars. The TS port composes the same behavior over the
+ * already-TS `loadPolicy` helper, removing the fork/exec hop and the
+ * exit-code-parsing that came with it.
+ *
+ * Fail-closed: when the policy file is malformed or unreadable, the
+ * returned `codex_required` is `true`. This matches the bash core's
+ * "treating as true" path (design §2, security carry-forward).
+ */
+import type { Policy } from '../../policy/types.js';
+export interface ResolvedPolicy {
+    /** Resolved `review.codex_required`; true when malformed/absent. */
+    codex_required: boolean;
+    /** Resolved `review.allow_skip_in_ci`; false when absent. */
+    allow_skip_in_ci: boolean;
+    /** Full policy (undefined when load failed — caller emits a WARN). */
+    policy: Policy | null;
+    /** Warning text from the loader, if any — surfaced to stderr by the caller. */
+    warning: string | null;
+}
+/**
+ * Resolve review-related policy fields. Never throws — any error path
+ * returns `codex_required: true` with a `warning` populated so the caller
+ * can decide whether to echo it.
+ */
+export declare function resolveReviewPolicy(baseDir: string): ResolvedPolicy;
+/**
+ * Skip-env evaluation. The bash core reads `REA_SKIP_PUSH_REVIEW` +
+ * `REA_SKIP_CODEX_REVIEW` with simple non-empty semantics. We preserve
+ * that exactly: any non-empty value triggers the skip path, and the
+ * VALUE is used as the skip reason. Empty or unset = no skip.
+ */
+export interface SkipEnv {
+    /** `REA_SKIP_PUSH_REVIEW` value or null. */
+    push_review_reason: string | null;
+    /** `REA_SKIP_CODEX_REVIEW` value or null. */
+    codex_review_reason: string | null;
+}
+export declare function readSkipEnv(env?: NodeJS.ProcessEnv): SkipEnv;
+/**
+ * True iff `CI` env is set to a non-empty value. The bash core checks
+ * `[[ -n "${CI:-}" ]]` — we match that.
+ */
+export declare function isCiContext(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Legacy-bash kill switch (design §11.2). When `REA_LEGACY_PUSH_REVIEW=1`,
+ * the CLI entry point delegates to the preserved bash core for one
+ * release window. Advertised in `rea doctor`; sunset after 90 days of
+ * clean 0.11.x running on canaries.
+ */
+export declare function isLegacyBashKillSwitchOn(env?: NodeJS.ProcessEnv): boolean;

package/dist/hooks/review-gate/policy.js

@@ -0,0 +1,71 @@
+/**
+ * Policy accessors for the review-gate modules.
+ *
+ * The bash core resolves `review.codex_required` via `node dist/scripts/read-
+ * policy-field.js` and evaluates `REA_SKIP_PUSH_REVIEW` / `REA_SKIP_CODEX_REVIEW`
+ * directly from env vars. The TS port composes the same behavior over the
+ * already-TS `loadPolicy` helper, removing the fork/exec hop and the
+ * exit-code-parsing that came with it.
+ *
+ * Fail-closed: when the policy file is malformed or unreadable, the
+ * returned `codex_required` is `true`. This matches the bash core's
+ * "treating as true" path (design §2, security carry-forward).
+ */
+import { loadPolicy } from '../../policy/loader.js';
+/**
+ * Resolve review-related policy fields. Never throws — any error path
+ * returns `codex_required: true` with a `warning` populated so the caller
+ * can decide whether to echo it.
+ */
+export function resolveReviewPolicy(baseDir) {
+    try {
+        const policy = loadPolicy(baseDir);
+        const review = policy.review;
+        const codex_required = review?.codex_required === false ? false : true;
+        const allow_skip_in_ci = review?.allow_skip_in_ci === true;
+        return {
+            codex_required,
+            allow_skip_in_ci,
+            policy,
+            warning: null,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Policy-file-not-found is a first-run condition for consumers running
+        // the gate before `rea init`; treat codex_required as true and surface
+        // the warning so the operator knows what state the gate is in.
+        return {
+            codex_required: true,
+            allow_skip_in_ci: false,
+            policy: null,
+            warning: `review-gate: could not load .rea/policy.yaml — ${msg}. Treating codex_required=true (fail-closed).`,
+        };
+    }
+}
+export function readSkipEnv(env = process.env) {
+    const pr = env['REA_SKIP_PUSH_REVIEW'];
+    const cr = env['REA_SKIP_CODEX_REVIEW'];
+    return {
+        push_review_reason: typeof pr === 'string' && pr.length > 0 ? pr : null,
+        codex_review_reason: typeof cr === 'string' && cr.length > 0 ? cr : null,
+    };
+}
+/**
+ * True iff `CI` env is set to a non-empty value. The bash core checks
+ * `[[ -n "${CI:-}" ]]` — we match that.
+ */
+export function isCiContext(env = process.env) {
+    const v = env['CI'];
+    return typeof v === 'string' && v.length > 0;
+}
+/**
+ * Legacy-bash kill switch (design §11.2). When `REA_LEGACY_PUSH_REVIEW=1`,
+ * the CLI entry point delegates to the preserved bash core for one
+ * release window. Advertised in `rea doctor`; sunset after 90 days of
+ * clean 0.11.x running on canaries.
+ */
+export function isLegacyBashKillSwitchOn(env = process.env) {
+    const v = env['REA_LEGACY_PUSH_REVIEW'];
+    return typeof v === 'string' && v.length > 0 && v !== '0';
+}

package/dist/hooks/review-gate/protected-paths.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Protected-path detection. Given a `git diff --name-status` output blob,
+ * return true iff any change touches one of the prefixes in
+ * `PROTECTED_PATH_PREFIXES`.
+ *
+ * ## Why this is a dedicated module
+ *
+ * The bash core uses `awk -v re='^(src/gateway/...)' '{...}'` inline in
+ * the main gate loop (push-review-core.sh:904-923). That regex is
+ * duplicated in `.husky/pre-push` (the native-git shim) and in at least
+ * two places in THREAT_MODEL.md. A single TS helper with a grep-able
+ * constant in `constants.ts` removes the drift risk.
+ *
+ * ## Input shape
+ *
+ * `git diff --name-status <merge_base>..<local_sha>` output. Each line is:
+ *   <STATUS>\t<path1>[\t<path2>]
+ * STATUS is one letter, possibly followed by a similarity score for
+ * rename/copy (`R100`, `C95`). STATUS letters we care about: A, C, D, M,
+ * R, T, U — the bash core's `status !~ /^[ACDMRTU]/` filter. We match
+ * that exactly.
+ */
+/**
+ * Parse a single `git diff --name-status` line and extract the paths that
+ * matter for protected-path detection. Rename (`R`) and copy (`C`) lines
+ * carry two paths separated by tabs; both are checked against the
+ * protected-path set.
+ *
+ * Returns an empty array for irrelevant status letters or malformed lines.
+ */
+export declare function extractPathsFromStatusLine(line: string): string[];
+/**
+ * True iff `path` starts with one of the protected-path prefixes. Exported
+ * for unit tests; callers should usually use `diffTouchesProtectedPaths`.
+ */
+export declare function isProtectedPath(filePath: string): boolean;
+/**
+ * True iff the given `git diff --name-status` output contains at least
+ * one protected-path hit. Returns the set of hit paths (deduped) for
+ * audit-record metadata.
+ */
+export interface ProtectedPathScanResult {
+    hit: boolean;
+    paths: string[];
+}
+export declare function scanNameStatusForProtectedPaths(nameStatusOutput: string): ProtectedPathScanResult;

package/dist/hooks/review-gate/protected-paths.js

@@ -0,0 +1,76 @@
+/**
+ * Protected-path detection. Given a `git diff --name-status` output blob,
+ * return true iff any change touches one of the prefixes in
+ * `PROTECTED_PATH_PREFIXES`.
+ *
+ * ## Why this is a dedicated module
+ *
+ * The bash core uses `awk -v re='^(src/gateway/...)' '{...}'` inline in
+ * the main gate loop (push-review-core.sh:904-923). That regex is
+ * duplicated in `.husky/pre-push` (the native-git shim) and in at least
+ * two places in THREAT_MODEL.md. A single TS helper with a grep-able
+ * constant in `constants.ts` removes the drift risk.
+ *
+ * ## Input shape
+ *
+ * `git diff --name-status <merge_base>..<local_sha>` output. Each line is:
+ *   <STATUS>\t<path1>[\t<path2>]
+ * STATUS is one letter, possibly followed by a similarity score for
+ * rename/copy (`R100`, `C95`). STATUS letters we care about: A, C, D, M,
+ * R, T, U — the bash core's `status !~ /^[ACDMRTU]/` filter. We match
+ * that exactly.
+ */
+import { PROTECTED_PATH_PREFIXES } from './constants.js';
+/** Set of single-letter status codes the gate cares about. */
+const RELEVANT_STATUS = new Set(['A', 'C', 'D', 'M', 'R', 'T', 'U']);
+/**
+ * Parse a single `git diff --name-status` line and extract the paths that
+ * matter for protected-path detection. Rename (`R`) and copy (`C`) lines
+ * carry two paths separated by tabs; both are checked against the
+ * protected-path set.
+ *
+ * Returns an empty array for irrelevant status letters or malformed lines.
+ */
+export function extractPathsFromStatusLine(line) {
+    if (line.length === 0)
+        return [];
+    const parts = line.split('\t');
+    if (parts.length < 2)
+        return [];
+    const status = parts[0] ?? '';
+    if (status.length === 0)
+        return [];
+    const statusLetter = status[0];
+    if (statusLetter === undefined || !RELEVANT_STATUS.has(statusLetter)) {
+        return [];
+    }
+    return parts.slice(1).filter((p) => p.length > 0);
+}
+/**
+ * True iff `path` starts with one of the protected-path prefixes. Exported
+ * for unit tests; callers should usually use `diffTouchesProtectedPaths`.
+ */
+export function isProtectedPath(filePath) {
+    for (const prefix of PROTECTED_PATH_PREFIXES) {
+        if (filePath.startsWith(prefix))
+            return true;
+        // A bare `.rea` or `hooks` path (no trailing slash) is a directory
+        // boundary match — `.rea/audit.jsonl` passes, `my-rea.config` does
+        // not. startsWith on the prefix-with-slash enforces that naturally.
+    }
+    return false;
+}
+export function scanNameStatusForProtectedPaths(nameStatusOutput) {
+    if (nameStatusOutput.length === 0) {
+        return { hit: false, paths: [] };
+    }
+    const hits = new Set();
+    for (const line of nameStatusOutput.split('\n')) {
+        const paths = extractPathsFromStatusLine(line);
+        for (const p of paths) {
+            if (isProtectedPath(p))
+                hits.add(p);
+        }
+    }
+    return { hit: hits.size > 0, paths: Array.from(hits).sort() };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.10.1",
+  "version": "0.10.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)",