@bookedsolid/rea 0.27.0 → 0.28.1

package/dist/hooks/bash-scanner/walker.js

@@ -256,8 +256,204 @@ export function walkForWrites(file) {
     // emit (the path-shape decision is the scanner's, not ours — we
     // emit conservatively).
     detectCwdChangeIntoProtected(file, out);
+    // 0.28.0 round-18 P2 closure (FuncDecl-then-call). Static AST does
+    // not model invocation, so a function body's writes were emitted
+    // ONLY if the body itself contained a top-level write — but the
+    // PoC `f() { echo x > .rea/HALT; }; f` has the write in the body
+    // and the call as a separate Stmt. Pre-fix the call was an opaque
+    // CallExpr whose head matched no built-in detector, so the body
+    // writes never propagated to the outer detection set.
+    //
+    // Closure: pre-pass the AST to map every FuncDecl name → list of
+    // detected writes within its body (computed by the same walker on
+    // a synthetic file rooted at the body), then on every CallExpr
+    // whose head matches a known function name, re-emit the captured
+    // writes with `originSrc: 'funcdecl_invocation:<name>'` so the
+    // scanner refuses on the same kill-switch terms it would for a
+    // direct redirect.
+    detectFuncDeclThenCall(file, out);
     return out;
 }
+/**
+ * 0.28.0 round-18 P2 — FuncDecl-then-call closure. Two-phase:
+ *
+ *   Phase 1 (collectFuncDeclWrites): walk every FuncDecl in the file,
+ *   compute the writes its body produces (by recursively running
+ *   walkForWrites against the body), and record them keyed by the
+ *   declared function name. Functions defined inside other constructs
+ *   (e.g., a FuncDecl nested inside an IfClause body) are still
+ *   collected — `syntax.Walk` visits them.
+ *
+ *   Phase 2 (emitFuncDeclInvocationWrites): walk every CallExpr in
+ *   the file. When the CallExpr's head normalizes to a known function
+ *   name AND we have not already attributed this CallExpr's writes
+ *   (avoid double-counting when the same CallExpr was already inside
+ *   a body whose detections we collected), append the captured writes
+ *   to `out` with the call site's position.
+ *
+ * Conservative trade-offs:
+ *
+ *   - We only RE-EMIT writes; we do not re-run the walker against
+ *     a synthesized "argv-substituted" body. Bash positional
+ *     parameters (`$1`, `$@`) inside a function body that influence
+ *     write paths are ignored — too dynamic to resolve statically
+ *     and the existing dynamic-write detectors already refuse on
+ *     unresolved expansions.
+ *
+ *   - We do not chase call chains (`f() { g; }; g() { echo > .rea/HALT; }; f`).
+ *     Each declared function's body is collected independently; an
+ *     invocation matches at most ONE name. Two-hop chains require a
+ *     follow-up closure (deferred — the PoC is one-hop, which is what
+ *     the round-18 deferral cited).
+ *
+ *   - Recursive function calls would loop the body-collection phase
+ *     unless guarded. We pass a `visited` set keyed by FuncDecl
+ *     identity so a self-referential body is walked at most once.
+ */
+function detectFuncDeclThenCall(file, out) {
+    const declWrites = collectFuncDeclWrites(file);
+    if (declWrites.size === 0)
+        return;
+    emitFuncDeclInvocationWrites(file, declWrites, out);
+}
+function collectFuncDeclWrites(file) {
+    const result = new Map();
+    const visited = new Set();
+    const visitor = (node) => {
+        if (node === null || node === undefined)
+            return true;
+        const t = nodeType(node);
+        if (t !== 'FuncDecl')
+            return true;
+        if (visited.has(node))
+            return false;
+        visited.add(node);
+        const name = funcDeclName(node);
+        if (name.length === 0)
+            return true;
+        const body = node['Body'];
+        if (!body || typeof body !== 'object')
+            return true;
+        // Recursively walk the body. We synthesize a BashFile-shaped
+        // wrapper so `syntax.Walk` sees a proper top-level entry point.
+        // The wrapper carries one Stmt whose Cmd is the body — when the
+        // body is itself a Stmt (Block / Subshell), we forward it
+        // directly. mvdan-sh's body shapes vary across versions; both
+        // shapes are accepted defensively.
+        const writes = [];
+        try {
+            walkSubtreeNoFuncDecl(body, writes);
+        }
+        catch {
+            // Pathological body — fail closed at the higher tier. We do
+            // not propagate errors from this post-pass; the caller already
+            // has the primary detections.
+        }
+        if (writes.length > 0)
+            result.set(name, writes);
+        return true;
+    };
+    try {
+        syntax.Walk(file, visitor);
+    }
+    catch {
+        // Best-effort.
+    }
+    return result;
+}
+/**
+ * Walk a subtree using the same dispatch as the main `walkForWrites`
+ * loop, but WITHOUT re-entering `detectFuncDeclThenCall`. Keeps the
+ * body-collection phase bounded — a self-referential function body
+ * (`f() { f; }`) would otherwise loop the post-pass forever.
+ *
+ * Mutates `out` in place.
+ */
+function walkSubtreeNoFuncDecl(root, out) {
+    try {
+        const visit = (node) => {
+            if (node === null || node === undefined)
+                return true;
+            const t = nodeType(node);
+            switch (t) {
+                case 'Stmt':
+                    extractStmtRedirects(node, out);
+                    extractHeredocShellPayloads(node, out);
+                    break;
+                case 'CallExpr':
+                    walkCallExpr(node, out);
+                    break;
+                case 'BinaryCmd':
+                    detectPipeIntoBareShell(node, out);
+                    break;
+                case 'ParamExp':
+                    recurseParamExpSlice(node, visit);
+                    break;
+                default:
+                    break;
+            }
+            return true;
+        };
+        syntax.Walk(root, visit);
+    }
+    catch {
+        /* swallow */
+    }
+}
+function emitFuncDeclInvocationWrites(file, declWrites, out) {
+    const visitor = (node) => {
+        if (node === null || node === undefined)
+            return true;
+        const t = nodeType(node);
+        if (t !== 'CallExpr')
+            return true;
+        const args = asArray(node['Args']);
+        if (args.length === 0)
+            return true;
+        const head = args[0];
+        if (!head || typeof head !== 'object')
+            return true;
+        const headWord = wordToString(head);
+        if (headWord === null || headWord.value.length === 0)
+            return true;
+        const name = normalizeCmdHead(headWord.value);
+        const captured = declWrites.get(name);
+        if (captured === undefined || captured.length === 0)
+            return true;
+        // Re-emit each captured write with the call-site's position so
+        // the scanner's reporter shows the operator the SITE of the
+        // invocation, not the (possibly far-away) function definition.
+        const callPos = headWord.position;
+        for (const w of captured) {
+            out.push({
+                ...w,
+                position: callPos,
+                originSrc: (w.originSrc !== undefined && w.originSrc.length > 0
+                    ? `${w.originSrc} via funcdecl_invocation:${name}`
+                    : `funcdecl_invocation:${name}`),
+            });
+        }
+        return true;
+    };
+    try {
+        syntax.Walk(file, visitor);
+    }
+    catch {
+        /* swallow */
+    }
+}
+/** Extract a FuncDecl's declared name. mvdan-sh stores it on `Name.Value`. */
+function funcDeclName(funcDecl) {
+    const nameNode = funcDecl['Name'];
+    if (!nameNode || typeof nameNode !== 'object')
+        return '';
+    // mvdan-sh's Lit shape: { Value: string }. The reference probe:
+    //   syntax.Walk visits Name as a Lit; .Value is the string.
+    const v = nameNode['Value'];
+    if (typeof v !== 'string')
+        return '';
+    return v.trim();
+}
 /**
  * helix-024 F1 closure — detect `cd <DIR>` / `pushd <DIR>` (and `cd
  * $VAR` / `pushd $VAR` dynamic forms) and emit synthetic detections

package/dist/hooks/push-gate/findings.d.ts

@@ -66,3 +66,30 @@ export declare function inferVerdict(findings: Finding[]): Verdict;
  * Convenience: parse + infer in one call.
  */
 export declare function summarizeReview(reviewText: string): ReviewSummary;
+/**
+ * 0.28.0 helix-029 — partition findings against a list of gitignore-style
+ * globs. Findings whose `file` path matches any glob land in
+ * `excluded`; everything else (including findings without a `file`
+ * field — codex prose without a path can't be path-filtered) lands in
+ * `kept`. The verdict is recomputed from `kept` only.
+ *
+ * Glob semantics (intentionally minimal — full gitignore parity is out
+ * of scope for the gate):
+ *
+ *   - `**` matches any number of path segments (including zero)
+ *   - `*` matches any chars within a single path segment
+ *   - `?` matches a single character within a segment
+ *   - leading `/` anchors the glob at the root (the default — paths are
+ *     repo-relative anyway)
+ *   - trailing `/` is treated as `/**` (directory match)
+ *
+ * Path normalization: backslashes → slashes (Windows checkout
+ * tolerance), leading `./` stripped. Globs are case-sensitive on every
+ * platform so a Windows checkout doesn't silently widen the filter.
+ */
+export interface FilterResult {
+    kept: Finding[];
+    excluded: Finding[];
+    verdict: Verdict;
+}
+export declare function filterFindingsByPath(findings: Finding[], globs: readonly string[]): FilterResult;

package/dist/hooks/push-gate/findings.js

@@ -140,3 +140,90 @@ export function summarizeReview(reviewText) {
         reviewText,
     };
 }
+export function filterFindingsByPath(findings, globs) {
+    if (globs.length === 0) {
+        return { kept: findings, excluded: [], verdict: inferVerdict(findings) };
+    }
+    // Compile once. Anchored at start, end, slash-tolerant.
+    const compiled = globs.map(compileGlob);
+    const kept = [];
+    const excluded = [];
+    for (const f of findings) {
+        if (f.file === undefined) {
+            kept.push(f);
+            continue;
+        }
+        const norm = normalizePath(f.file);
+        let matched = false;
+        for (const re of compiled) {
+            if (re.test(norm)) {
+                matched = true;
+                break;
+            }
+        }
+        if (matched)
+            excluded.push(f);
+        else
+            kept.push(f);
+    }
+    return { kept, excluded, verdict: inferVerdict(kept) };
+}
+function normalizePath(p) {
+    let out = p.replace(/\\/g, '/');
+    if (out.startsWith('./'))
+        out = out.slice(2);
+    if (out.startsWith('/'))
+        out = out.slice(1);
+    return out;
+}
+/**
+ * Compile a gitignore-style glob into a RegExp. Conservative — handles
+ * the four wildcard forms documented above and treats every other
+ * character as a literal. The cost of a too-narrow compiler is a
+ * miss-and-no-filter (the finding stays in `kept` and blocks the push,
+ * which is the safer failure mode). The cost of a too-wide compiler is
+ * a false suppression — strictly worse, since findings disappear
+ * silently. We err narrow.
+ */
+function compileGlob(rawGlob) {
+    let glob = rawGlob;
+    if (glob.startsWith('/'))
+        glob = glob.slice(1);
+    // Trailing `/` → `/**` (directory match).
+    if (glob.endsWith('/'))
+        glob = `${glob}**`;
+    let re = '';
+    for (let i = 0; i < glob.length; i += 1) {
+        const c = glob[i];
+        if (c === '*') {
+            // `**` matches any number of path segments (including zero); a
+            // single `*` matches any chars within a segment.
+            if (i + 1 < glob.length && glob[i + 1] === '*') {
+                // Consume the second `*`. If followed by `/`, also consume it
+                // so `a/**/b` matches both `a/b` (zero segments) and `a/x/b`.
+                i += 1;
+                if (i + 1 < glob.length && glob[i + 1] === '/') {
+                    i += 1;
+                    re += '(?:.*/)?';
+                }
+                else {
+                    re += '.*';
+                }
+            }
+            else {
+                re += '[^/]*';
+            }
+        }
+        else if (c === '?') {
+            re += '[^/]';
+        }
+        else if (c !== undefined && /[.+^$|(){}[\]\\]/.test(c)) {
+            // Escape regex meta-characters.
+            re += `\\${c}`;
+        }
+        else if (c !== undefined) {
+            re += c;
+        }
+    }
+    return new RegExp(`^${re}$`);
+}

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

@@ -22,6 +22,7 @@
  * directly — `deps.env` and `deps.baseDir` are the only ambient state.
  */
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { appendAuditRecord } from '../../audit/append.js';
 import { loadPolicyAsync } from '../../policy/loader.js';
 import { Tier, InvocationStatus } from '../../policy/types.js';
@@ -29,7 +30,7 @@ import { resolvePushGatePolicy, PUSH_GATE_DEFAULT_LAST_N_COMMITS_FALLBACK, } fro
 import { readHalt } from './halt.js';
 import { resolveBaseRef } from './base.js';
 import { createRealGitExecutor, runCodexReview, CodexNotInstalledError, CodexProtocolError, CodexSubprocessError, CodexTimeoutError, IRON_GATE_DEFAULT_MODEL, IRON_GATE_DEFAULT_REASONING, } from './codex-runner.js';
-import { summarizeReview } from './findings.js';
+import { filterFindingsByPath, summarizeReview } from './findings.js';
 import { renderBanner, writeLastReview } from './report.js';
 import { isFlip, lookupVerdict, writeVerdict } from './verdict-cache.js';
 /**
@@ -359,7 +360,21 @@ export async function runPushGate(deps) {
     // reuse the cached verdict — durable PASS. Cache is bypassed when
     // policy.review.cache_ttl_ms is 0. Cache miss / expired falls
     // through to the codex call below.
-    const cacheLookup = policy.cache_ttl_ms > 0 ? lookupVerdict(deps.baseDir, headSha) : { hit: false };
+    //
+    // 0.28.0 codex round-1 P2: include a stable digest of
+    // policy.exclude_paths in the cache key so updates to the path
+    // filter immediately invalidate prior cached verdicts. Without
+    // this, enabling exclude_paths after a cached blocking verdict
+    // would keep refusing the push until TTL expires; disabling it
+    // would keep approving a previously-filtered pass. Digest is
+    // SHA-256 of a sorted JSON array — same input → same digest.
+    const excludeDigest = crypto
+        .createHash('sha256')
+        .update(JSON.stringify([...(policy.exclude_paths ?? [])].sort()))
+        .digest('hex')
+        .slice(0, 16);
+    const cacheKey = `${headSha}#${excludeDigest}`;
+    const cacheLookup = policy.cache_ttl_ms > 0 ? lookupVerdict(deps.baseDir, cacheKey) : { hit: false };
     if (cacheLookup.hit && cacheLookup.entry !== undefined) {
         const cached = cacheLookup.entry;
         const cachedBlocked = cached.verdict === 'blocking' ||
@@ -421,7 +436,38 @@ export async function runPushGate(deps) {
                 ? { reasoningEffort: policy.codex_reasoning_effort }
                 : {}),
         });
-        const summary = summarizeReview(codexResult.reviewText);
+        const rawSummary = summarizeReview(codexResult.reviewText);
+        // 0.28.0 helix-029 — apply path-scoped filter BEFORE verdict
+        // computation. When `policy.exclude_paths` is empty (the default),
+        // the filter is a no-op: kept === rawSummary.findings, excluded
+        // is empty. When set, findings whose `file` matches any glob are
+        // moved into `filtered.excluded` and the verdict recomputes from
+        // `filtered.kept` only. The audit shape stays unchanged — we add
+        // a `filtered_findings_count` counter into metadata for forensic
+        // grep but do NOT introduce a new top-level array on the audit
+        // record.
+        // Defensive `?? []` — older test fixtures and embedders that
+        // construct `ResolvedReviewPolicy` by hand may omit the field;
+        // an undefined slot would crash `filterFindingsByPath` at the
+        // `globs.length === 0` check.
+        const filtered = filterFindingsByPath(rawSummary.findings, policy.exclude_paths ?? []);
+        const summary = {
+            ...rawSummary,
+            findings: filtered.kept,
+            verdict: filtered.verdict,
+        };
+        if (filtered.excluded.length > 0) {
+            // Emit a single stderr line per excluded finding so the operator
+            // can still see them (and act — file upstream, audit, etc.) even
+            // though they no longer block the push. This is the audit-trail
+            // surface the helix bug report asked for; the `filtered_findings`
+            // array on `last-review.json` is the OPTIONAL extra layer (see
+            // below).
+            stderr(`rea: ${filtered.excluded.length} finding(s) filtered by review.exclude_paths (path-scoped):\n`);
+            for (const f of filtered.excluded) {
+                stderr(`  - [${f.severity}] ${f.title}${f.file !== undefined ? ` — ${f.file}${f.line !== undefined ? `:${String(f.line)}` : ''}` : ''}\n`);
+            }
+        }
         const blocked = summary.verdict === 'blocking' ||
             (summary.verdict === 'concerns' && policy.concerns_blocks && !isConcernsOverrideSet(env));
         const lastReviewPath = path.join(deps.baseDir, '.rea', 'last-review.json');
@@ -466,7 +512,11 @@ export async function runPushGate(deps) {
                 ttl_ms: policy.cache_ttl_ms,
             };
             try {
-                await writeVerdict(deps.baseDir, headSha, entry);
+                // 0.28.0 codex round-1 P2: write under the same compound key
+                // used for lookup so subsequent same-SHA-same-policy lookups
+                // hit cache, while same-SHA-different-policy lookups miss
+                // and produce a fresh verdict tied to the new policy state.
+                await writeVerdict(deps.baseDir, cacheKey, entry);
             }
             catch {
                 // Cache writes are best-effort. A failure here must NOT
@@ -479,6 +529,10 @@ export async function runPushGate(deps) {
         await safeAppend(appendAuditFn, deps.baseDir, EVT_REVIEWED, fullPolicy, {
             verdict: summary.verdict,
             finding_count: summary.findings.length,
+            // 0.28.0 helix-029: counter only — keeps the audit-record shape
+            // unchanged so no consumer parser breaks. Operators grep
+            // `filtered_findings_count` to see how many were suppressed.
+            filtered_findings_count: filtered.excluded.length > 0 ? filtered.excluded.length : undefined,
             base_ref: base.ref,
             base_source: base.source,
             head_sha: headSha,

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

@@ -62,6 +62,21 @@ export interface ResolvedReviewPolicy {
      * (24 hours) when policy.review.cache_ttl_ms is unset.
      */
     cache_ttl_ms: number;
+    /**
+     * 0.28.0 helix-029 — path-scoped finding filter. Gitignore-style
+     * globs (anchored to repo root). Empty when no filter is active.
+     * Includes both `policy.review.exclude_paths` AND, when
+     * `auto_exclude_managed` is on, paths from `.rea/install-manifest.json`.
+     * Resolved BEFORE the gate runs so the gate has a single list to
+     * filter against.
+     */
+    exclude_paths: string[];
+    /**
+     * 0.28.0 helix-029 — true when the resolver pulled paths from
+     * `.rea/install-manifest.json` into `exclude_paths`. Surfaced for
+     * audit shape only; the gate filter consumes `exclude_paths`.
+     */
+    auto_exclude_managed: boolean;
     /** `true` when `.rea/policy.yaml` was absent; defaults apply. */
     policyMissing: boolean;
 }

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

@@ -99,11 +99,34 @@ export async function resolvePushGatePolicy(baseDir) {
             codex_model: PUSH_GATE_DEFAULT_CODEX_MODEL,
             codex_reasoning_effort: PUSH_GATE_DEFAULT_CODEX_REASONING_EFFORT,
             cache_ttl_ms: PUSH_GATE_DEFAULT_CACHE_TTL_MS,
+            exclude_paths: [],
+            auto_exclude_managed: false,
             policyMissing: true,
         };
     }
     const policy = await loadPolicyAsync(baseDir);
     const review = policy.review ?? {};
+    // 0.28.0 helix-029 — derived default for auto_exclude_managed:
+    // - true when `exclude_paths` is set AND the operator did not
+    //   explicitly disable it
+    // - false when `exclude_paths` is unset (no filter to compose)
+    // - false when explicitly set to `false`
+    const explicitGlobs = review.exclude_paths ?? [];
+    const hasExplicitGlobs = explicitGlobs.length > 0;
+    // Principal-engineer redesign: auto_exclude_managed is meaningful
+    // only when the operator signaled intent via exclude_paths. A bare
+    // `auto_exclude_managed: true` without globs is a no-op — the
+    // operator is otherwise opting OUT of any filter. Default true when
+    // exclude_paths is set; false when unset; explicit false always wins.
+    const autoExcludeDefault = hasExplicitGlobs;
+    const autoExcludeFlag = review.auto_exclude_managed ?? autoExcludeDefault;
+    const autoExcludeActive = autoExcludeFlag && hasExplicitGlobs;
+    let mergedExcludes = [...explicitGlobs];
+    if (autoExcludeActive) {
+        mergedExcludes = mergedExcludes.concat(readManifestPaths(baseDir));
+    }
+    // De-dupe — globs and manifest entries can overlap.
+    mergedExcludes = Array.from(new Set(mergedExcludes));
     return {
         codex_required: review.codex_required ?? PUSH_GATE_DEFAULT_CODEX_REQUIRED,
         concerns_blocks: review.concerns_blocks ?? PUSH_GATE_DEFAULT_CONCERNS_BLOCKS,
@@ -113,6 +136,65 @@ export async function resolvePushGatePolicy(baseDir) {
         codex_model: review.codex_model ?? PUSH_GATE_DEFAULT_CODEX_MODEL,
         codex_reasoning_effort: review.codex_reasoning_effort ?? PUSH_GATE_DEFAULT_CODEX_REASONING_EFFORT,
         cache_ttl_ms: review.cache_ttl_ms ?? PUSH_GATE_DEFAULT_CACHE_TTL_MS,
+        exclude_paths: mergedExcludes,
+        auto_exclude_managed: autoExcludeActive,
         policyMissing: false,
     };
 }
+/**
+ * 0.28.0 helix-029 — read repo-relative paths from
+ * `.rea/install-manifest.json` for the auto-exclude path. The manifest
+ * shape is `{ files: { "<rel-path>": { sha256: ..., source: ... } } }`
+ * (or similar). We pull only the keys (relative paths) and degrade to
+ * an empty array on parse / shape errors — auto-exclude is best-effort,
+ * never the gate's failure mode.
+ */
+function readManifestPaths(baseDir) {
+    const manifestPath = path.join(baseDir, '.rea', 'install-manifest.json');
+    if (!fs.existsSync(manifestPath))
+        return [];
+    try {
+        const raw = fs.readFileSync(manifestPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object')
+            return [];
+        const obj = parsed;
+        const candidates = [];
+        // Common shapes: `{ files: {...} }` (object keyed by path), or
+        // `{ files: [...] }` (array of strings or `{path: ...}`). Be
+        // tolerant — the manifest format has shifted across rea minors.
+        if (obj.files !== undefined) {
+            if (Array.isArray(obj.files))
+                candidates.push(...obj.files);
+            else if (typeof obj.files === 'object' && obj.files !== null) {
+                candidates.push(...Object.keys(obj.files));
+            }
+        }
+        else if (Array.isArray(obj)) {
+            candidates.push(...obj);
+        }
+        const out = [];
+        for (const c of candidates) {
+            const candidate = typeof c === 'string'
+                ? c
+                : typeof c === 'object' && c !== null && typeof c.path === 'string'
+                    ? c.path
+                    : '';
+            if (candidate.length === 0)
+                continue;
+            // 0.28.0 codex round-1 P1: manifest entries are LITERAL paths to
+            // managed files written by `rea init`. They are NEVER glob
+            // patterns. Reject any entry containing glob metachars to prevent
+            // a manifest like `{"files":["**"]}` from suppressing every
+            // finding via the auto_exclude_managed code path. Fail closed —
+            // a tampered manifest entry is dropped, never trusted as a glob.
+            if (/[*?\[\]!]/.test(candidate))
+                continue;
+            out.push(candidate);
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/policy/loader.d.ts

@@ -90,6 +90,18 @@ declare const PolicySchema: z.ZodObject<{
          * verdict. Set to 0 to disable caching (every push re-invokes codex).
          */
         cache_ttl_ms: z.ZodOptional<z.ZodNumber>;
+        /**
+         * 0.28.0 helix-029 — path-scoped finding filter. Gitignore-style
+         * globs; findings whose `file` matches any are filtered out before
+         * verdict computation. Enables `auto_exclude_managed: true` by
+         * default; pass `auto_exclude_managed: false` explicitly to opt out.
+         */
+        exclude_paths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /**
+         * 0.28.0 helix-029 — derived default. Defaults to true when
+         * `exclude_paths` is set, false when `exclude_paths` is unset.
+         */
+        auto_exclude_managed: z.ZodOptional<z.ZodBoolean>;
         /**
          * 0.26.0 local-first enforcement. Strict so a typo in the off-switch
          * surface (`mode: of`, `refuse_at: pushh`) fails policy load instead
@@ -122,6 +134,8 @@ declare const PolicySchema: z.ZodObject<{
         codex_model?: string | undefined;
         codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
         cache_ttl_ms?: number | undefined;
+        exclude_paths?: string[] | undefined;
+        auto_exclude_managed?: boolean | undefined;
         local_review?: {
             mode?: "enforced" | "off" | undefined;
             max_age_seconds?: number | undefined;
@@ -137,6 +151,8 @@ declare const PolicySchema: z.ZodObject<{
         codex_model?: string | undefined;
         codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
         cache_ttl_ms?: number | undefined;
+        exclude_paths?: string[] | undefined;
+        auto_exclude_managed?: boolean | undefined;
         local_review?: {
             mode?: "enforced" | "off" | undefined;
             max_age_seconds?: number | undefined;
@@ -260,6 +276,8 @@ declare const PolicySchema: z.ZodObject<{
         codex_model?: string | undefined;
         codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
         cache_ttl_ms?: number | undefined;
+        exclude_paths?: string[] | undefined;
+        auto_exclude_managed?: boolean | undefined;
         local_review?: {
             mode?: "enforced" | "off" | undefined;
             max_age_seconds?: number | undefined;
@@ -323,6 +341,8 @@ declare const PolicySchema: z.ZodObject<{
         codex_model?: string | undefined;
         codex_reasoning_effort?: "low" | "medium" | "high" | undefined;
         cache_ttl_ms?: number | undefined;
+        exclude_paths?: string[] | undefined;
+        auto_exclude_managed?: boolean | undefined;
         local_review?: {
             mode?: "enforced" | "off" | undefined;
             max_age_seconds?: number | undefined;

package/dist/policy/loader.js

@@ -89,6 +89,18 @@ const ReviewPolicySchema = z
      * verdict. Set to 0 to disable caching (every push re-invokes codex).
      */
     cache_ttl_ms: z.number().int().nonnegative().optional(),
+    /**
+     * 0.28.0 helix-029 — path-scoped finding filter. Gitignore-style
+     * globs; findings whose `file` matches any are filtered out before
+     * verdict computation. Enables `auto_exclude_managed: true` by
+     * default; pass `auto_exclude_managed: false` explicitly to opt out.
+     */
+    exclude_paths: z.array(z.string().min(1)).optional(),
+    /**
+     * 0.28.0 helix-029 — derived default. Defaults to true when
+     * `exclude_paths` is set, false when `exclude_paths` is unset.
+     */
+    auto_exclude_managed: z.boolean().optional(),
     /**
      * 0.26.0 local-first enforcement. Strict so a typo in the off-switch
      * surface (`mode: of`, `refuse_at: pushh`) fails policy load instead

package/dist/policy/types.d.ts

@@ -169,6 +169,37 @@ export interface ReviewPolicy {
      * a `rea.push_gate.verdict_flip` audit event and overwrite the cache.
      */
     cache_ttl_ms?: number;
+    /**
+     * 0.28.0 helix-029 — path-scoped finding filter. Gitignore-style
+     * globs against repo-relative paths. Findings whose `file` matches
+     * any glob in this list are filtered OUT before the verdict is
+     * computed, but are still emitted on stderr (so the operator can
+     * file them upstream). Useful for downstream consumers of rea who
+     * cannot patch rea-managed paths but should not be blocked from
+     * pushing while waiting on an upstream fix.
+     *
+     * Setting this list also enables `auto_exclude_managed` by default —
+     * paths from `.rea/install-manifest.json` are excluded in addition
+     * to whatever globs are listed here. Pass `auto_exclude_managed:
+     * false` to opt out and rely on `exclude_paths` alone.
+     *
+     * Empty (or unset) → no filtering, pre-0.28.0 behavior.
+     *
+     * The audit shape is unchanged; the gate emits a
+     * `filtered_findings_count` counter into the audit metadata so
+     * operators can grep `rea.push_gate.reviewed` to see how many
+     * findings were suppressed without re-parsing prose.
+     */
+    exclude_paths?: string[];
+    /**
+     * 0.28.0 helix-029 — derived default. When `exclude_paths` is set,
+     * defaults to `true` — paths from `.rea/install-manifest.json` are
+     * excluded in addition to the explicit globs. Set explicitly to
+     * `false` to rely only on `exclude_paths`. When `exclude_paths` is
+     * unset, this field is a no-op (no filter is active in the first
+     * place).
+     */
+    auto_exclude_managed?: boolean;
     /**
      * Local-first review enforcement (0.26.0+ — CTO directive 2026-05-05).
      *