@bookedsolid/rea 0.20.0 → 0.21.1

package/dist/cli/init.js

@@ -85,7 +85,7 @@ function resolveLayered(profileName, reagentTranslated) {
     }
     return layered;
 }
-async function runWizard(options, targetDir, reagentPolicyPath, layeredBase) {
+async function runWizard(options, targetDir, reagentPolicyPath, layeredBase, existingPolicy = undefined) {
     const projectName = detectProjectName(targetDir);
     p.intro(`rea init — ${projectName}`);
     let fromReagent = options.fromReagent === true;
@@ -124,9 +124,15 @@ async function runWizard(options, targetDir, reagentPolicyPath, layeredBase) {
             cancel('Init cancelled.');
         profileName = picked;
     }
-    const autonomyDefault = layeredBase.autonomy_level ?? AutonomyLevel.L1;
+    // 0.21.1: prefer the existing on-disk value over the profile default
+    // so re-running `rea init` doesn't reset an operator's manual edit.
+    const autonomyDefault = existingPolicy?.autonomyLevel
+        ?? layeredBase.autonomy_level
+        ?? AutonomyLevel.L1;
     const autonomyPick = await p.select({
-        message: 'Starting autonomy_level',
+        message: existingPolicy?.autonomyLevel !== undefined
+            ? `Starting autonomy_level (current: ${existingPolicy.autonomyLevel})`
+            : 'Starting autonomy_level',
         initialValue: autonomyDefault,
         options: [
             { value: AutonomyLevel.L0, label: 'L0', hint: 'read-only; every write needs approval' },
@@ -139,9 +145,13 @@ async function runWizard(options, targetDir, reagentPolicyPath, layeredBase) {
         cancel('Init cancelled.');
     const autonomyLevel = autonomyPick;
     const maxCandidates = AUTONOMY_LEVELS.filter((lvl) => levelRank(lvl) >= levelRank(autonomyLevel));
-    const defaultMax = (layeredBase.max_autonomy_level !== undefined &&
-        maxCandidates.includes(layeredBase.max_autonomy_level) &&
-        layeredBase.max_autonomy_level) ||
+    // 0.21.1: prefer existing on-disk max_autonomy_level over profile default.
+    const defaultMax = (existingPolicy?.maxAutonomyLevel !== undefined &&
+        maxCandidates.includes(existingPolicy.maxAutonomyLevel) &&
+        existingPolicy.maxAutonomyLevel) ||
+        (layeredBase.max_autonomy_level !== undefined &&
+            maxCandidates.includes(layeredBase.max_autonomy_level) &&
+            layeredBase.max_autonomy_level) ||
         maxCandidates.find((l) => l === AutonomyLevel.L2) ||
         autonomyLevel;
     const maxOptions = maxCandidates.map((lvl) => {
@@ -233,6 +243,79 @@ async function printCodexInstallAssist() {
     console.log('  Install via the Claude Code Codex plugin helper: `/codex:setup`,');
     console.log('  or set `review.codex_required: false` in .rea/policy.yaml to opt out.');
 }
+/**
+ * Read user-mutable values from an existing `.rea/policy.yaml`.
+ * Returns undefined when the file doesn't exist or fails to parse.
+ *
+ * The reader is permissive — any field that fails to extract is
+ * dropped from the result; the caller falls back to the profile
+ * default for that one field. This is the idempotency contract
+ * extension introduced in 0.17.0 (`installed_at` preservation),
+ * extended in 0.21.1 to cover every field an operator might
+ * manually edit between init runs.
+ *
+ * Profile-switch is allowed but advisory: when the existing
+ * `profile:` value disagrees with the requested one, the existing
+ * VALUES are still preserved. Operators who want full reset pass
+ * `--force` to bypass the file-existence check entirely.
+ */
+function readExistingPolicyForPreservation(targetDir) {
+    const policyPath = path.join(targetDir, REA_DIR, POLICY_FILE);
+    if (!fs.existsSync(policyPath))
+        return undefined;
+    try {
+        const raw = fs.readFileSync(policyPath, 'utf8');
+        const out = {};
+        // Profile (informational; used for stderr advisory).
+        const pm = raw.match(/^profile:\s*['"]?([a-z0-9-]+)['"]?\s*$/m);
+        if (pm)
+            out.profile = pm[1];
+        // Autonomy + ceiling (enum).
+        const am = raw.match(/^autonomy_level:\s*(L[0-3])\s*$/m);
+        const amVal = am?.[1];
+        if (amVal !== undefined && Object.values(AutonomyLevel).includes(amVal)) {
+            out.autonomyLevel = amVal;
+        }
+        const mm = raw.match(/^max_autonomy_level:\s*(L[0-3])\s*$/m);
+        const mmVal = mm?.[1];
+        if (mmVal !== undefined && Object.values(AutonomyLevel).includes(mmVal)) {
+            out.maxAutonomyLevel = mmVal;
+        }
+        // block_ai_attribution.
+        const bm = raw.match(/^block_ai_attribution:\s*(true|false)\s*$/m);
+        if (bm?.[1] !== undefined)
+            out.blockAiAttribution = bm[1] === 'true';
+        // blocked_paths block-sequence — line-by-line scan.
+        const bpStart = raw.match(/^blocked_paths:\s*$/m);
+        if (bpStart) {
+            const after = raw.slice((bpStart.index ?? 0) + bpStart[0].length + 1);
+            const lines = after.split('\n');
+            const collected = [];
+            for (const line of lines) {
+                const m2 = line.match(/^\s*-\s+(?:['"]([^'"]+)['"]|(\S.*?))\s*$/);
+                if (!m2)
+                    break;
+                const v = m2[1] ?? m2[2];
+                if (v !== undefined)
+                    collected.push(v);
+            }
+            if (collected.length > 0)
+                out.blockedPaths = collected;
+        }
+        // notification_channel.
+        const nm = raw.match(/^notification_channel:\s*['"]?([^'"\n]*)['"]?\s*$/m);
+        if (nm?.[1] !== undefined)
+            out.notificationChannel = nm[1];
+        // review.codex_required (under nested `review:` block).
+        const cm = raw.match(/^\s+codex_required:\s*(true|false)\s*$/m);
+        if (cm?.[1] !== undefined)
+            out.codexRequired = cm[1] === 'true';
+        return out;
+    }
+    catch {
+        return undefined;
+    }
+}
 function readExistingInstalledAt(policyPath) {
     try {
         if (!fs.existsSync(policyPath))
@@ -297,6 +380,16 @@ function writePolicyYaml(targetDir, config, layered) {
             lines.push(`  max_bash_output_lines: ${cp.max_bash_output_lines}`);
         }
     }
+    // 0.20.1+ helix-round-N P2: emit architecture_review.patterns when
+    // the layered profile declared them. Consumers without patterns see
+    // a silent no-op from architecture-review-gate.sh.
+    if (layered.architecture_review?.patterns !== undefined) {
+        lines.push(`architecture_review:`);
+        lines.push(`  patterns:`);
+        for (const p of layered.architecture_review.patterns) {
+            lines.push(`    - ${JSON.stringify(p)}`);
+        }
+    }
     // 0.18.1+ helixir #9: emit audit.rotation when the layered profile
     // declared it. Empty `rotation: {}` opts in to documented defaults
     // (50 MiB / 30 days); explicit values override.
@@ -470,30 +563,58 @@ export async function runInit(options) {
         }
     }
     const layeredBase = resolveLayered(profileName, reagentTranslated);
+    // 0.21.1: preserve user-mutable policy values across re-init (idempotency
+    // class — same as the `installed_at` fix from 0.17.0). Pre-fix, every
+    // `rea init` re-applied profile defaults, silently resetting an
+    // operator's `autonomy_level: L2` back to the profile's L1, etc.
+    // Read the existing policy if present and merge: explicit existing
+    // value wins over profile default. Operator opts out with --force
+    // (existing flag — bypass the file-existence check entirely).
+    // Profile-switch case: when the existing profile name disagrees with
+    // the requested profile, the existing values are STILL preserved by
+    // default but a stderr advisory names what was kept; operator can
+    // pass --force to fully reset.
+    const existingPolicy = readExistingPolicyForPreservation(targetDir);
     let config;
     if (options.yes === true) {
         // G11.4 non-interactive codex resolution:
         //   1. Explicit --codex / --no-codex flag wins.
-        //   2. Otherwise derive from the profile name (`*-no-codex` → false).
+        //   2. Otherwise existing policy value wins (preserves operator edit).
+        //   3. Otherwise derive from the profile name (`*-no-codex` → false).
         const codexRequired = options.codex !== undefined
             ? options.codex
-            : profileDefaultCodexRequired(profileName);
+            : (existingPolicy?.codexRequired ?? profileDefaultCodexRequired(profileName));
         config = {
             profile: profileName,
-            autonomyLevel: layeredBase.autonomy_level ?? AutonomyLevel.L1,
-            maxAutonomyLevel: layeredBase.max_autonomy_level ?? AutonomyLevel.L2,
-            blockAiAttribution: layeredBase.block_ai_attribution ?? true,
-            blockedPaths: layeredBase.blocked_paths ?? ['.env', '.env.*'],
-            notificationChannel: layeredBase.notification_channel ?? '',
+            autonomyLevel: existingPolicy?.autonomyLevel
+                ?? layeredBase.autonomy_level
+                ?? AutonomyLevel.L1,
+            maxAutonomyLevel: existingPolicy?.maxAutonomyLevel
+                ?? layeredBase.max_autonomy_level
+                ?? AutonomyLevel.L2,
+            blockAiAttribution: existingPolicy?.blockAiAttribution
+                ?? layeredBase.block_ai_attribution
+                ?? true,
+            blockedPaths: existingPolicy?.blockedPaths
+                ?? layeredBase.blocked_paths
+                ?? ['.env', '.env.*'],
+            notificationChannel: existingPolicy?.notificationChannel
+                ?? layeredBase.notification_channel
+                ?? '',
             codexRequired,
             fromReagent,
             reagentPolicyPath,
             reagentNotices,
         };
-        log(`Non-interactive init: profile=${profileName}, autonomy=${config.autonomyLevel}, max=${config.maxAutonomyLevel}, attribution-block=${config.blockAiAttribution}, codex_required=${config.codexRequired}`);
+        if (existingPolicy !== undefined) {
+            log(`Non-interactive init (re-run): preserving existing autonomy=${config.autonomyLevel}, max=${config.maxAutonomyLevel}, attribution-block=${config.blockAiAttribution}, codex_required=${config.codexRequired}. Pass --force to reset to profile defaults.`);
+        }
+        else {
+            log(`Non-interactive init: profile=${profileName}, autonomy=${config.autonomyLevel}, max=${config.maxAutonomyLevel}, attribution-block=${config.blockAiAttribution}, codex_required=${config.codexRequired}`);
+        }
     }
     else {
-        config = await runWizard(options, targetDir, reagentPolicyPath, layeredBase);
+        config = await runWizard(options, targetDir, reagentPolicyPath, layeredBase, existingPolicy);
         config.reagentNotices = reagentNotices;
     }
     if (!fs.existsSync(reaDir))

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

@@ -363,6 +363,11 @@ export async function runPushGate(deps) {
         const cached = cacheLookup.entry;
         const cachedBlocked = cached.verdict === 'blocking'
             || (cached.verdict === 'concerns' && policy.concerns_blocks && !isConcernsOverrideSet(env));
+        // 0.19.1 P3-3 (code-reviewer): emit EVT_CACHE_HIT (forensic detail
+        // for the cache layer specifically) AND EVT_REVIEWED (the canonical
+        // verdict event with `cache_hit: true` metadata). Operators
+        // grepping `rea.push_gate.reviewed` for verdict-stability dashboards
+        // see every push, including cached ones.
         await safeAppend(appendAuditFn, deps.baseDir, EVT_CACHE_HIT, fullPolicy, {
             verdict: cached.verdict,
             finding_count: cached.finding_count,
@@ -374,16 +379,23 @@ export async function runPushGate(deps) {
             cached_reasoning_effort: cached.reasoning_effort,
             blocked: cachedBlocked,
         });
+        await safeAppend(appendAuditFn, deps.baseDir, EVT_REVIEWED, fullPolicy, {
+            verdict: cached.verdict,
+            finding_count: cached.finding_count,
+            base_ref: base.ref,
+            base_source: base.source,
+            head_sha: headSha,
+            blocked: cachedBlocked,
+            cache_hit: true,
+            cached_reviewed_at: cached.reviewed_at,
+            cached_model: cached.model,
+            cached_reasoning_effort: cached.reasoning_effort,
+        });
+        // 0.19.1 P3-1 (backend): simplified return shape. Verdict maps
+        // 1:1 to status; cachedBlocked maps 1:1 to exitCode. The prior
+        // nested ternary recomputed the same mapping in both arms.
         return {
-            status: cachedBlocked
-                ? cached.verdict === 'blocking'
-                    ? 'blocking'
-                    : 'concerns'
-                : cached.verdict === 'blocking'
-                    ? 'blocking'
-                    : cached.verdict === 'concerns'
-                        ? 'concerns'
-                        : 'pass',
+            status: cached.verdict,
             exitCode: cachedBlocked ? 2 : 0,
             summary: `${cached.verdict}: ${cached.finding_count} finding(s) (cached)`,
             verdict: cached.verdict,

package/dist/hooks/push-gate/verdict-cache.d.ts

@@ -59,6 +59,16 @@ import type { Verdict as ReviewVerdict } from './findings.js';
 export declare const VERDICT_CACHE_FILE = "last-review.cache.json";
 export declare const VERDICT_CACHE_SCHEMA_VERSION: 2;
 export declare const DEFAULT_CACHE_TTL_MS: number;
+/**
+ * Soft cap on cached entry count before `writeVerdict` opportunistically
+ * prunes expired entries (0.19.1 backend-engineer P2-3). Keeps the
+ * cache file from growing unbounded over months of pushes against many
+ * SHAs — at 500 entries × ~200 bytes/entry ≈ 100 KB, we proactively
+ * drop expired entries on the next write. The prune is best-effort:
+ * if every entry is unexpired we accept the larger file rather than
+ * dropping fresh durable verdicts.
+ */
+export declare const VERDICT_CACHE_PRUNE_THRESHOLD = 500;
 export interface VerdictCacheEntry {
     verdict: ReviewVerdict;
     finding_count: number;

package/dist/hooks/push-gate/verdict-cache.js

@@ -62,6 +62,16 @@ import { withAuditLock } from '../../audit/fs.js';
 export const VERDICT_CACHE_FILE = 'last-review.cache.json';
 export const VERDICT_CACHE_SCHEMA_VERSION = 2;
 export const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1_000; // 24h
+/**
+ * Soft cap on cached entry count before `writeVerdict` opportunistically
+ * prunes expired entries (0.19.1 backend-engineer P2-3). Keeps the
+ * cache file from growing unbounded over months of pushes against many
+ * SHAs — at 500 entries × ~200 bytes/entry ≈ 100 KB, we proactively
+ * drop expired entries on the next write. The prune is best-effort:
+ * if every entry is unexpired we accept the larger file rather than
+ * dropping fresh durable verdicts.
+ */
+export const VERDICT_CACHE_PRUNE_THRESHOLD = 500;
 /**
  * Read the cache file and look up `head_sha`. Missing file, malformed
  * JSON, missing entry, and unsupported schema_version all resolve to a
@@ -110,13 +120,40 @@ export async function writeVerdict(baseDir, headSha, entry) {
             throw new VerdictCacheForeignSchemaError(cachePath);
         }
         const existing = readCacheFile(baseDir);
+        const merged = {
+            ...(existing?.entries ?? {}),
+            [headSha]: entry,
+        };
+        // 0.19.1 P2-3 (backend-engineer): opportunistic prune.
+        // When the cache crosses the soft threshold, drop entries whose
+        // own ttl_ms has expired before writing. Cheap walk; bounded to
+        // O(n) at write time only when n > threshold. Prevents the cache
+        // file from growing unbounded over months of pushes.
+        const pruned = Object.keys(merged).length > VERDICT_CACHE_PRUNE_THRESHOLD
+            ? _pruneExpired(merged, new Date())
+            : merged;
         const next = {
             schema_version: VERDICT_CACHE_SCHEMA_VERSION,
-            entries: { ...(existing?.entries ?? {}), [headSha]: entry },
+            entries: pruned,
         };
         _atomicWriteJson(cachePath, next);
     });
 }
+function _pruneExpired(entries, now) {
+    const surviving = {};
+    const nowMs = now.getTime();
+    for (const [sha, entry] of Object.entries(entries)) {
+        const reviewedAtMs = Date.parse(entry.reviewed_at);
+        if (Number.isNaN(reviewedAtMs)) {
+            surviving[sha] = entry;
+            continue;
+        }
+        if (nowMs - reviewedAtMs < entry.ttl_ms) {
+            surviving[sha] = entry;
+        }
+    }
+    return surviving;
+}
 /**
  * Remove a single SHA from the cache. Returns true if the entry existed.
  */

package/dist/policy/loader.d.ts

@@ -178,6 +178,13 @@ declare const PolicySchema: z.ZodObject<{
             expose_diagnostics?: boolean | undefined;
         } | undefined;
     }>>;
+    architecture_review: z.ZodOptional<z.ZodObject<{
+        patterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        patterns?: string[] | undefined;
+    }, {
+        patterns?: string[] | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     version: string;
     profile: string;
@@ -228,6 +235,9 @@ declare const PolicySchema: z.ZodObject<{
             expose_diagnostics?: boolean | undefined;
         } | undefined;
     } | undefined;
+    architecture_review?: {
+        patterns?: string[] | undefined;
+    } | undefined;
 }, {
     version: string;
     profile: string;
@@ -278,6 +288,9 @@ declare const PolicySchema: z.ZodObject<{
             expose_diagnostics?: boolean | undefined;
         } | undefined;
     } | undefined;
+    architecture_review?: {
+        patterns?: string[] | undefined;
+    } | undefined;
 }>;
 /**
  * Async policy loader with TTL cache and mtime-based invalidation.

package/dist/policy/loader.js

@@ -200,6 +200,17 @@ const PolicySchema = z
     redact: RedactPolicySchema.optional(),
     audit: AuditPolicySchema.optional(),
     gateway: GatewayPolicySchema.optional(),
+    // 0.20.1 helix-round-N P2: architecture-review-gate.sh patterns
+    // are now policy-driven. Pre-fix the hook hardcoded rea-internal
+    // source-tree patterns (`src/gateway/`, `hooks/_lib/`, etc.) which
+    // produced irrelevant advisory output in consumer projects.
+    // Empty (or unset) → silent no-op. bst-internal profile pins the
+    // rea-source patterns so dogfood behaves as before.
+    architecture_review: z
+        .object({
+        patterns: z.array(z.string()).optional(),
+    })
+        .optional(),
 })
     .strict();
 const DEFAULT_CACHE_TTL_MS = 30_000;

package/dist/policy/profiles.d.ts

@@ -69,6 +69,13 @@ export declare const ProfileSchema: z.ZodObject<{
             max_age_days?: number | undefined;
         } | undefined;
     }>>;
+    architecture_review: z.ZodOptional<z.ZodObject<{
+        patterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        patterns?: string[] | undefined;
+    }, {
+        patterns?: string[] | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     autonomy_level?: AutonomyLevel | undefined;
     max_autonomy_level?: AutonomyLevel | undefined;
@@ -92,6 +99,9 @@ export declare const ProfileSchema: z.ZodObject<{
             max_age_days?: number | undefined;
         } | undefined;
     } | undefined;
+    architecture_review?: {
+        patterns?: string[] | undefined;
+    } | undefined;
 }, {
     autonomy_level?: AutonomyLevel | undefined;
     max_autonomy_level?: AutonomyLevel | undefined;
@@ -115,6 +125,9 @@ export declare const ProfileSchema: z.ZodObject<{
             max_age_days?: number | undefined;
         } | undefined;
     } | undefined;
+    architecture_review?: {
+        patterns?: string[] | undefined;
+    } | undefined;
 }>;
 export type Profile = z.infer<typeof ProfileSchema>;
 /** Hard defaults applied before any profile or wizard answer. */

package/dist/policy/profiles.js

@@ -69,6 +69,12 @@ export const ProfileSchema = z
             .optional(),
     })
         .optional(),
+    // 0.20.1+ profiles can declare architecture-sensitive paths.
+    architecture_review: z
+        .object({
+        patterns: z.array(z.string()).optional(),
+    })
+        .optional(),
 })
     .strict();
 /** Hard defaults applied before any profile or wizard answer. */

package/dist/policy/types.d.ts

@@ -289,4 +289,16 @@ export interface Policy {
     redact?: RedactPolicy;
     audit?: AuditPolicy;
     gateway?: GatewayPolicy;
+    /**
+     * Architecture-review patterns (0.20.1+). When set, the
+     * `architecture-review-gate.sh` hook fires an advisory when a
+     * Write/Edit/MultiEdit/NotebookEdit lands on a path matching one
+     * of the patterns. When unset or empty, the hook is a silent no-op
+     * — consumers without architecture-sensitive paths see zero noise.
+     * bst-internal profile pins rea's own source-tree patterns
+     * (`src/gateway/`, `hooks/_lib/`, etc.).
+     */
+    architecture_review?: {
+        patterns?: string[];
+    };
 }

package/hooks/_lib/path-normalize.sh

@@ -70,3 +70,78 @@ resolve_parent_realpath() {
   resolved=$(cd -P -- "$parent_dir" 2>/dev/null && pwd -P 2>/dev/null) || resolved=""
   printf '%s' "$resolved"
 }
+
+# 0.20.1 helix-021 fixes: shared helper for the Bash-tier symlink
+# resolution that the Write-tier `blocked-paths-enforcer.sh` has had
+# since 0.10.x. Given a project-relative LOGICAL_PATH (already
+# normalized via normalize_path) and the original raw token (whose
+# parent dir may exist on disk), return the resolved-symlink
+# project-relative form on stdout.
+#
+# Returns:
+#   - The empty string if the parent doesn't exist (caller can't
+#     resolve, falls back to LOGICAL_PATH only).
+#   - A literal `__rea_outside_root__:<resolved>` sentinel when the
+#     parent's realpath escapes REA_ROOT. Caller refuses with the
+#     same shape as the existing outside-REA_ROOT check.
+#   - The project-relative resolved form (lowercased to match
+#     case-insensitive comparisons elsewhere) when resolution
+#     succeeds.
+#
+# Reference:
+#   `blocked-paths-enforcer.sh` lines ~205-238 for the Write-tier
+#   reference implementation that this helper backports to Bash-tier.
+rea_resolved_relative_form() {
+  local raw_token="$1"
+  # Skip absolute paths whose logical form is already outside REA_ROOT
+  # — `/tmp/log`, `/var/log/x`, etc. The caller's logical-path check
+  # has already decided whether to allow or refuse based on the
+  # logical form. Re-running symlink resolution on these would
+  # produce a false "symlink resolves outside project root" refusal
+  # (because `/tmp` resolves to `/private/tmp` on macOS, which is
+  # technically outside REA_ROOT). The threat model for THIS helper
+  # is intra-project symlink walks: a path the caller thinks is
+  # under REA_ROOT but resolves elsewhere via an intermediate
+  # symlink. Pure external paths are out of scope.
+  if [[ "$raw_token" == /* ]]; then
+    # Canonicalize REA_ROOT for the comparison.
+    local rea_root_canon_for_skip
+    rea_root_canon_for_skip=$(cd -P -- "$REA_ROOT" 2>/dev/null && pwd -P 2>/dev/null) || rea_root_canon_for_skip="$REA_ROOT"
+    if [[ "$raw_token" != "$rea_root_canon_for_skip"/* && "$raw_token" != "$REA_ROOT"/* ]]; then
+      printf ''
+      return 0
+    fi
+  fi
+  local resolved_parent
+  resolved_parent=$(resolve_parent_realpath "$raw_token")
+  if [[ -z "$resolved_parent" ]]; then
+    printf ''
+    return 0
+  fi
+  # Canonicalize REA_ROOT the same way `pwd -P` canonicalized
+  # `resolved_parent`. macOS resolves `/var/folders/...` to
+  # `/private/var/folders/...` because `/var` is a symlink to
+  # `/private/var`; without this normalization the prefix-equality
+  # below produces a false outside-REA_ROOT sentinel for every path
+  # under a tmpdir that started life as `/var/...`. Memo-friendly:
+  # `cd -P` runs once per hook invocation; the cost is bounded.
+  local rea_root_canon
+  rea_root_canon=$(cd -P -- "$REA_ROOT" 2>/dev/null && pwd -P 2>/dev/null) || rea_root_canon="$REA_ROOT"
+  # Outside-REA_ROOT guard. The resolve may walk a symlink that exits
+  # the project tree entirely; emit the sentinel so the caller
+  # refuses with the same wording as the logical-path traversal
+  # check.
+  if [[ "$resolved_parent" != "$rea_root_canon" && "$resolved_parent" != "$rea_root_canon"/* ]]; then
+    printf '__rea_outside_root__:%s/%s' "$resolved_parent" "$(basename -- "$raw_token")"
+    return 0
+  fi
+  # Strip canonical REA_ROOT prefix, append basename, lowercase to
+  # match rea_path_is_protected's case-insensitive comparison.
+  local rel
+  if [[ "$resolved_parent" == "$rea_root_canon" ]]; then
+    rel="$(basename -- "$raw_token")"
+  else
+    rel="${resolved_parent#"$rea_root_canon"/}/$(basename -- "$raw_token")"
+  fi
+  printf '%s' "$rel" | tr '[:upper:]' '[:lower:]'
+}

package/hooks/_lib/protected-paths.sh

@@ -49,6 +49,11 @@ REA_PROTECTED_PATTERNS_FULL=(
   # since 0.18.1. A forged entry would skip codex on next push of that
   # SHA. Protect it like the kill-switch.
   '.rea/last-review.cache.json'
+  # 0.20.1 round-N P1: last-review.json is the operator's only forensic
+  # snapshot of the most recent codex review. A forged entry presents
+  # a fake "PASS" verdict to operators reading the file directly, and
+  # to any future tooling that consults it. Protect alongside the cache.
+  '.rea/last-review.json'
 )
 
 # Kill-switch invariants — never relaxable. Subset of FULL.
@@ -57,6 +62,7 @@ REA_KILL_SWITCH_INVARIANTS=(
   '.rea/policy.yaml'
   '.rea/HALT'
   '.rea/last-review.cache.json'
+  '.rea/last-review.json'
 )
 
 # Effective patterns after applying the relax list. Computed lazily on

package/hooks/architecture-review-gate.sh

@@ -50,15 +50,29 @@ source "$(dirname "$0")/_lib/path-normalize.sh"
 FILE_PATH=$(normalize_path "$FILE_PATH")
 
 # ── 6. Check architecture-sensitive paths ─────────────────────────────────────
-ARCH_PATTERNS=(
-  'src/types/'
-  'src/gateway/'
-  'src/config/'
-  'src/cli/commands/init/'
-  'hooks/_lib/'
-  'templates/'
-  'profiles/'
-)
+# 0.20.1 helix-round-N P2: read patterns from policy. Pre-fix the
+# rea-internal source-tree patterns (`src/gateway/`, `hooks/_lib/`,
+# `profiles/`, etc.) shipped as hardcoded defaults — irrelevant noise
+# in consumer projects whose architecture-sensitive paths are
+# different. Consumers with their own architecture surfaces declare
+# them in `.rea/policy.yaml::architecture_review.patterns`. The
+# bst-internal profile pins the rea-source patterns so the dogfood
+# install behaves the same as before; consumers without a pattern
+# set get a silent no-op.
+# shellcheck source=_lib/policy-read.sh
+source "$(dirname "$0")/_lib/policy-read.sh"
+
+ARCH_PATTERNS=()
+while IFS= read -r entry; do
+  [[ -z "$entry" ]] && continue
+  ARCH_PATTERNS+=("$entry")
+done < <(policy_list "architecture_review.patterns" 2>/dev/null || true)
+
+if [[ ${#ARCH_PATTERNS[@]} -eq 0 ]]; then
+  # Empty/unset policy → silent no-op. Consumers who haven't declared
+  # architecture-sensitive paths see zero advisory output.
+  exit 0
+fi
 
 MATCHED=""
 for pattern in "${ARCH_PATTERNS[@]}"; do

package/hooks/blocked-paths-bash-gate.sh

@@ -161,6 +161,13 @@ _refuse() {
 }
 
 # Check a single resolved-target token. Refuses on hit.
+#
+# 0.20.1 helix-021 #2: in addition to the logical post-_normalize_target
+# form, also check the symlink-resolved form. Pre-fix `ln -s . linkroot;
+# printf x > linkroot/.env` had a logical form of `linkroot/.env`
+# (no match against blocked_paths) but a resolved form of `.env`
+# (which DOES match). Refuse on either match. Write-tier
+# `blocked-paths-enforcer.sh` already has this resolution since 0.10.x.
 _check_token() {
   local token="$1" segment="$2"
   [[ -z "$token" ]] && return 0
@@ -172,9 +179,21 @@ _check_token() {
     # outside-root rejection on the protected list itself.
     return 0
   fi
+  # Symlink-resolved form via shared helper. Returns empty when the
+  # parent doesn't exist (legitimate "creating the parent" case);
+  # outside-REA_ROOT sentinel when the symlink walks out of the
+  # project (silently allow — same as the logical-path branch above).
+  local resolved_symlink
+  resolved_symlink=$(rea_resolved_relative_form "$token")
+  if [[ "$resolved_symlink" == __rea_outside_root__:* ]]; then
+    resolved_symlink=""
+  fi
   if _match_blocked "$resolved"; then
     _refuse "$MATCHED" "$resolved" "$segment"
   fi
+  if [[ -n "$resolved_symlink" ]] && _match_blocked "$resolved_symlink"; then
+    _refuse "$MATCHED" "$resolved_symlink" "$segment"
+  fi
   return 0
 }
 

package/hooks/protected-paths-bash-gate.sh

@@ -27,6 +27,8 @@ set -uo pipefail
 
 # shellcheck source=_lib/protected-paths.sh
 source "$(dirname "$0")/_lib/protected-paths.sh"
+# shellcheck source=_lib/path-normalize.sh
+source "$(dirname "$0")/_lib/path-normalize.sh"
 # shellcheck source=_lib/cmd-segments.sh
 source "$(dirname "$0")/_lib/cmd-segments.sh"
 
@@ -235,7 +237,7 @@ _check_segment() {
           # walking — there may be more positional args.
           local _t
           _t=$(_normalize_target "$target_token")
-          # 0.16.0 codex P2-3: outside-REA_ROOT sentinel handling.
+          # 0.16.0 codex P2-3: outside-REA_ROOT sentinel handling (logical).
           if [[ "$_t" == __rea_outside_root__:* ]]; then
             local resolved="${_t#__rea_outside_root__:}"
             {
@@ -244,15 +246,37 @@ _check_segment() {
             } >&2
             exit 2
           fi
-          if rea_path_is_protected "$_t"; then
+          # 0.20.1 helix-021 #1: resolve intermediate symlinks via
+          # `cd -P / pwd -P` parent-canonicalization (Write-tier parity).
+          # `ln -s ../ .husky/pre-push.d/linkdir; printf x > .husky/pre-push.d/linkdir/pre-push`
+          # had a logical form of `.husky/pre-push.d/linkdir/pre-push`
+          # that didn't match any protected pattern; the resolved form
+          # is `.husky/pre-push` which DOES match. Refuse on either.
+          local _t_resolved
+          _t_resolved=$(rea_resolved_relative_form "$target_token")
+          if [[ "$_t_resolved" == __rea_outside_root__:* ]]; then
+            local resolved="${_t_resolved#__rea_outside_root__:}"
+            {
+              printf 'PROTECTED PATH (bash): symlink resolves outside project root\n'
+              printf '  Logical: %s\n  Resolved: %s\n' "$target_token" "$resolved"
+            } >&2
+            exit 2
+          fi
+          if rea_path_is_protected "$_t" \
+             || ([[ -n "$_t_resolved" ]] && rea_path_is_protected "$_t_resolved"); then
             local matched=""
             local pattern_lc
+            local hit_form="$_t"
+            if [[ -n "$_t_resolved" ]] && rea_path_is_protected "$_t_resolved" \
+               && ! rea_path_is_protected "$_t"; then
+              hit_form="$_t_resolved"
+            fi
             for pattern in "${REA_PROTECTED_PATTERNS[@]}"; do
               pattern_lc=$(printf '%s' "$pattern" | tr '[:upper:]' '[:lower:]')
-              if [[ "$_t" == "$pattern_lc" ]]; then matched="$pattern"; break; fi
-              if [[ "$pattern_lc" == */ && "$_t" == "$pattern_lc"* ]]; then matched="$pattern"; break; fi
+              if [[ "$hit_form" == "$pattern_lc" ]]; then matched="$pattern"; break; fi
+              if [[ "$pattern_lc" == */ && "$hit_form" == "$pattern_lc"* ]]; then matched="$pattern"; break; fi
             done
-            _refuse "$matched" "$_t" "$segment"
+            _refuse "$matched" "$hit_form" "$segment"
           fi
           # Reset target_token so the post-loop check doesn't double-check.
           target_token=""
@@ -283,17 +307,38 @@ _check_segment() {
     } >&2
     exit 2
   fi
-  if rea_path_is_protected "$target"; then
+  # 0.20.1 helix-021 #1: resolve intermediate symlinks. See parallel
+  # block in the multi-target loop above for the rationale.
+  local target_resolved
+  target_resolved=$(rea_resolved_relative_form "$target_token")
+  if [[ "$target_resolved" == __rea_outside_root__:* ]]; then
+    local resolved="${target_resolved#__rea_outside_root__:}"
+    {
+      printf 'PROTECTED PATH (bash): symlink resolves outside project root\n'
+      printf '\n'
+      printf '  Logical:  %s\n' "$target_token"
+      printf '  Resolved: %s\n' "$resolved"
+      printf '  Segment:  %s\n' "$segment"
+    } >&2
+    exit 2
+  fi
+  if rea_path_is_protected "$target" \
+     || ([[ -n "$target_resolved" ]] && rea_path_is_protected "$target_resolved"); then
     # Find the matching pattern for the error message. Both `target`
     # and `pattern` lowercased to match `_normalize_target`'s case-
     # insensitive output (helix-015 P1 fix).
     local matched="" pattern_lc
+    local hit_form="$target"
+    if [[ -n "$target_resolved" ]] && rea_path_is_protected "$target_resolved" \
+       && ! rea_path_is_protected "$target"; then
+      hit_form="$target_resolved"
+    fi
     for pattern in "${REA_PROTECTED_PATTERNS[@]}"; do
       pattern_lc=$(printf '%s' "$pattern" | tr '[:upper:]' '[:lower:]')
-      if [[ "$target" == "$pattern_lc" ]]; then matched="$pattern"; break; fi
-      if [[ "$pattern_lc" == */ && "$target" == "$pattern_lc"* ]]; then matched="$pattern"; break; fi
+      if [[ "$hit_form" == "$pattern_lc" ]]; then matched="$pattern"; break; fi
+      if [[ "$pattern_lc" == */ && "$hit_form" == "$pattern_lc"* ]]; then matched="$pattern"; break; fi
     done
-    _refuse "$matched" "$target" "$segment"
+    _refuse "$matched" "$hit_form" "$segment"
   fi
   return 0
 }

package/hooks/settings-protection.sh

@@ -199,8 +199,15 @@ case "$LOWER_NORM" in
     if [ -d "$parent_dir" ]; then
       resolved_parent=$(cd -P -- "$parent_dir" 2>/dev/null && pwd -P 2>/dev/null) || resolved_parent=""
       if [ -n "$resolved_parent" ]; then
+        # 0.20.1 helix-021 #3: directory-boundary on the case glob.
+        # Pre-fix `*"/.husky/commit-msg.d"*` matched `.husky/commit-msg.d.bak/`
+        # too (substring without trailing-slash anchor). A symlink
+        # `.husky/pre-push.d/linkdir -> ../pre-push.d.bak` then resolved
+        # to `.husky/pre-push.d.bak/...` and slipped through.
+        # The trailing `/` on each pattern (and the explicit
+        # exact-match arm) requires a real directory boundary.
         case "$resolved_parent" in
-          *"/.husky/commit-msg.d"*|*"/.husky/pre-push.d"*) : ;;
+          */.husky/commit-msg.d|*/.husky/commit-msg.d/*|*/.husky/pre-push.d|*/.husky/pre-push.d/*) : ;;
           *)
             {
               printf 'SETTINGS PROTECTION: extension path resolves outside surface\n'

package/package.json

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

package/profiles/bst-internal.yaml

@@ -36,3 +36,18 @@ context_protection:
 # hash chain across the boundary.
 audit:
   rotation: {}
+# 0.20.1 helix-round-N P2: rea's own architecture-sensitive paths.
+# Hardcoded into the hook before this release; now policy-driven so
+# consumer projects don't get rea-source patterns advisory-warning on
+# their own `src/types/` directories. Empty (or unset) on other
+# profiles = silent no-op. Operators add their own
+# architecture-sensitive paths here on a per-project basis.
+architecture_review:
+  patterns:
+    - src/types/
+    - src/gateway/
+    - src/config/
+    - src/cli/commands/init/
+    - hooks/_lib/
+    - templates/
+    - profiles/