@bookedsolid/rea 0.28.1 → 0.28.2

package/agents/rea-orchestrator.md

@@ -114,6 +114,24 @@ Consumer projects may extend the roster via `.rea/agents/` and profile YAMLs, bu
 4. Delegate with full context — include file paths, constraints from policy.yaml, acceptance criteria, and the commit-discipline note above
 5. Verify outputs before reporting completion — do not trust agent summaries at face value. Read the files, check git status, confirm the build.
 
+## Self-review when the orchestrator implements directly (0.29.0+)
+
+There are sessions where the orchestrator must implement work itself instead of dispatching:
+
+- Subagent dispatch is unavailable (no Task tool in the current harness, exempt-subagent scenario).
+- The task is narrowly scoped to a single small surface where the dispatch overhead exceeds the implementation cost.
+- A codex round between specialist hand-offs is being used as the de facto specialist tier (the "Option C" iteration pattern from the 0.29.0 marathon).
+
+In every such case, you MUST still apply the specialist discipline that delegation would have enforced. This is not optional — the structural risk of "one Opus turn implements five surfaces" is exactly the failure mode that principal-engineer review caught in the 0.28.0 cycle (manifest glob-injection P1 + cache-staleness P2, both pre-commit). Reach the same closure shape by:
+
+1. **Name the specialists you are channeling.** Before each surface, state which specialist's discipline applies (e.g. "shell-scripting-specialist + adversarial-test-specialist for the bash gate corpus; typescript-specialist for the CLI; platform-architect for the workflow"). State it out loud so the user can spot a mis-cast role.
+2. **Codex round between surfaces, not just at the end.** A single end-of-build codex round across 5 surfaces buries P1s in noise. One round per surface keeps the signal sharp. The 0.27.0 direct-Bash codex CLI is cheap enough at one Opus turn per round to make this routine.
+3. **Explicit threat-model framing for security-tier changes.** When patching a hook, name the bypass class, the conservative-vs-narrow reading, and the sibling shapes the class implies. Refuse to commit until the corpus enumerates every shape the class includes.
+4. **Single-commit-per-PR discipline still applies.** Squash local work before push. The pre-push gate's stateless codex review runs once against the squashed diff; granular commits multiply the review burden without surfacing new findings.
+5. **Defer ruthlessly.** Trimmed-scope greenlights from the user are a maximum, not a minimum. The marathon's 0.28.0 lesson was "principal-engineer trimmed the 11-item plate to 6 with crisp deferral reasons." Apply the same lens during direct-implementation: if surface 6 needs structural rework, defer it to the next minor with the reason in the changeset rather than ship a half-baked closure.
+
+A self-review checkpoint after each surface (read the diff back, run the targeted tests, fire codex against the working tree) IS the specialist tier when no subagent is in the path. Skip the checkpoint and the structural lesson resets.
+
 ## The Plan / Build / Review Loop (default workflow)
 
 REA's default engineering workflow is three-legged, with Review performed by a different model than Build:

package/hooks/blocked-paths-enforcer.sh

@@ -145,6 +145,45 @@ if [[ "$raw_has_traversal" -eq 1 ]] || [[ "$norm_has_traversal" -eq 1 ]]; then
   exit 2
 fi
 
+# ── 5a-bis. Reject interior single-dot segments (0.29.0 helix-/./-class) ─────
+# Parallel to the `..` guard above. `normalize_path` does NOT collapse
+# interior `./` segments — that would corrupt `..` traversals — which leaves
+# a bypass class. A blocked entry of `.env` does not match `foo/./.env`
+# (the literal-comparison loop is byte-for-byte), so an attacker who can
+# influence the file_path string can dodge the policy entry.
+#
+# The conservative closure (per Jake 2026-05-12): treat any interior `/./`
+# segment exactly like `..`. The NORMALIZED form is the safe surface for
+# the check — `normalize_path` already stripped leading `./` segments, so
+# any `/./` that survives is interior by construction. A raw-form check
+# would false-positive on benign `./foo` paths (codex round 1 P2: a path
+# like `%2E%2Fsrc/foo.ts` decodes to `./src/foo.ts` which is the same
+# leading-`./` allowed shape the comment at the top of `normalize_path`
+# documents — guarding against it on the raw form would block legit
+# writes under `src/` and friends).
+#
+# URL-encoded companion: `.%2F` / `%2E/` / `%2E%2F` decode to `./` via
+# `normalize_path` (which knows `%2E` → `.` and `%2F` → `/`). After
+# URL-decode + leading-`./` strip, any encoded INTERIOR form hits the
+# normalized `*/./* ` check. No raw-form encoded guard is needed — the
+# normalize_path path already covers every encoded shape the helper
+# decodes, and shapes it doesn't decode wouldn't resolve to an interior
+# `./` segment on disk either.
+norm_has_dot_segment=0
+case "/$NORMALIZED/" in
+  */./*) norm_has_dot_segment=1 ;;
+esac
+if [[ "$norm_has_dot_segment" -eq 1 ]]; then
+  {
+    printf 'BLOCKED PATH: interior dot-segment rejected\n'
+    printf '\n'
+    printf '  File: %s\n' "$FILE_PATH"
+    printf "  Rule: path contains an interior '/./' segment; rewrite to a\n"
+    printf '        canonical project-relative path without dot segments.\n'
+  } >&2
+  exit 2
+fi
+
 for writable in "${AGENT_WRITABLE[@]}"; do
   if [[ "$NORMALIZED" == "$writable" ]] || [[ "$NORMALIZED" == "$writable"* && "$writable" == */ ]]; then
     exit 0

package/hooks/settings-protection.sh

@@ -128,6 +128,45 @@ if [[ "$raw_has_traversal" -eq 1 ]] || [[ "$norm_has_traversal" -eq 1 ]]; then
   exit 2
 fi
 
+# ── 5a-bis. Reject interior single-dot segments (0.29.0 helix-/./-class) ─────
+# Companion to the `..` guard above. The `normalize_path` helper deliberately
+# does NOT collapse interior `./` segments because doing so would corrupt
+# `..` traversals — but that leaves a parallel bypass class. A path like
+# `.husky/./pre-push` resolves on disk to `.husky/pre-push`, yet the literal/
+# prefix matchers in §6 compare against the un-collapsed `.husky/./pre-push`
+# string and miss the match.
+#
+# Conservative reading (per Jake 2026-05-12): treat any interior `./`
+# segment exactly like a `..` segment — refuse outright, force the caller
+# to send a canonical path. The corpus design pairs shell-scripting-specialist
+# with adversarial-test-specialist; the canonical attack shapes are:
+#
+#   .husky/./pre-push                  — single segment
+#   .husky/././pre-push                — repeated segments
+#   .husky/.//pre-push                 — `./` immediately followed by another `/`
+#   .claude/hooks/./_lib/halt-check.sh — inside a protected directory
+#   %2E%2F                             — percent-encoded `./`, caught after URL-decode
+#   .\.\pre-push                       — backslash variant, normalize_path → `./`
+#
+# Only the NORMALIZED form is checked (not the raw form) because raw `./foo`
+# at start-of-string is a legitimate relative path; `normalize_path` already
+# strips leading `./` segments, so anything that survives into the normalized
+# form's `/./` shape is INTERIOR by construction.
+norm_has_dot_segment=0
+case "/$NORMALIZED/" in
+  */./*) norm_has_dot_segment=1 ;;
+esac
+if [[ "$norm_has_dot_segment" -eq 1 ]]; then
+  {
+    printf 'SETTINGS PROTECTION: interior dot-segment rejected\n'
+    printf '\n'
+    printf '  File: %s\n' "$SAFE_FILE_PATH"
+    printf "  Rule: path contains an interior '/./' segment; rewrite to a\n"
+    printf '        canonical project-relative path without dot segments.\n'
+  } >&2
+  exit 2
+fi
+
 # Compute lower-cased path early so the §5b allow-list (and §6/§6b matchers
 # below) all reference a single normalized variable.
 LOWER_NORM=$(printf '%s' "$NORMALIZED" | tr '[:upper:]' '[:lower:]')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.28.1",
+  "version": "0.28.2",
   "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/scripts/dist-regression-gate.sh

@@ -167,8 +167,52 @@ trap 'rm -rf -- "$WORK"' EXIT HUP INT TERM
 # a new tarball was published. The release.yml rebuild+verify step
 # remains the catching net at publish time, so skipping here does not
 # re-open the BUG-013 attack surface for the merge-to-main path.
-if ! ( cd "$WORK" && npm pack "${PKG_NAME}@${PREV_VERSION}" --silent >/dev/null 2>&1 ); then
-  log "skip — npm pack ${PKG_NAME}@${PREV_VERSION} failed (network issue or registry outage)"
+#
+# 0.29.0: bounded retry loop for npm CDN propagation lag. The memory
+# entries for 0.9.0, 0.12.0, 0.13.0, 0.28.0, and 0.28.1 all note
+# "release verify flaked on npm CDN lag" — `npm view` returns the
+# version metadata but `npm pack` against the same version times out
+# or 404s because the tarball blob has not propagated to all CDN edges
+# yet. The CI-side workflow already has a 12×10s retry (release.yml
+# phase 2); this script runs locally / in PR CI where the failure
+# window is shorter but still occurs.
+#
+# Shape: initial attempt + three retries with sleeps 2s / 8s / 30s.
+# Total worst-case wait = 2 + 8 + 30 = 40s, all on the failure path.
+# That covers the empirically observed CDN propagation window (cf.
+# release.yml phase 2 retry loops) while bounding the local-/ PR-side
+# blocking time to under a minute on a genuine outage.
+NPM_PACK_OK=0
+NPM_PACK_DELAYS=(2 8 30)
+NPM_PACK_ATTEMPTS=$((${#NPM_PACK_DELAYS[@]} + 1))
+# Codex round 1 P2-2: use bash arithmetic for-loop instead of `$(seq 1 N)`.
+# `seq` is not in the preflight tool list (line 104: npm jq git shasum tar)
+# and `set -e` at the top of the script would exit 127 inside the loop body
+# on minimal images that lack it (Alpine, some BusyBox shells). Bash's
+# arithmetic for-loop is a builtin and works on every supported version.
+for ((attempt = 1; attempt <= NPM_PACK_ATTEMPTS; attempt++)); do
+  if ( cd "$WORK" && npm pack "${PKG_NAME}@${PREV_VERSION}" --silent >/dev/null 2>&1 ); then
+    if [ "$attempt" -gt 1 ]; then
+      log "npm pack succeeded after ${attempt} attempt(s) (CDN propagation lag)"
+    fi
+    NPM_PACK_OK=1
+    break
+  fi
+  # Clean up any partial artifact npm pack may have left in $WORK
+  # before retrying so the next attempt has a clean slate.
+  find "$WORK" -maxdepth 1 -type f -name '*.tgz' -delete 2>/dev/null || true
+  if [ "$attempt" -lt "$NPM_PACK_ATTEMPTS" ]; then
+    # Bash array is 0-indexed; $attempt is 1-indexed; index into
+    # NPM_PACK_DELAYS at $attempt-1 to read the delay AFTER this
+    # failed attempt (before the next try).
+    idx=$((attempt - 1))
+    delay="${NPM_PACK_DELAYS[$idx]}"
+    log "npm pack attempt ${attempt}/${NPM_PACK_ATTEMPTS} failed; sleeping ${delay}s for CDN propagation"
+    sleep "$delay"
+  fi
+done
+if [ "$NPM_PACK_OK" -ne 1 ]; then
+  log "skip — npm pack ${PKG_NAME}@${PREV_VERSION} failed after ${NPM_PACK_ATTEMPTS} attempts (network issue, registry outage, or persistent CDN lag)"
   exit 0
 fi