@bookedsolid/rea 0.27.0 → 0.28.1

package/data/claims/helix-022.json

@@ -0,0 +1,51 @@
+{
+  "id": "helix-022",
+  "title": "Bash-tier bypass classes (F1 parent-doesn't-exist symlink walk-up; F2 interpreter writes; F3 nested-shell unwrap depth; F4 cp/mv argv walker; F5 fail-closed unresolved expansion in redirect targets)",
+  "introduced_in": "<=0.21.0",
+  "closed_in": "0.22.0",
+  "summary": "Five adjacent Bash-tier bypass classes against 0.21.0 closed by structural fixes: nearest-existing-ancestor resolution, shared interpreter-scanner.sh, fixed-point recursion (depth bound 8) for nested shells, explicit cp/mv destination walker, and __rea_unresolved_expansion__ sentinel for $-substitution / backticks in redirect targets.",
+  "pocs": [
+    {
+      "id": "F1.symlink-walkup-parent-missing",
+      "type": "scan-bash",
+      "input": "ln -s ../../etc/passwd .rea/no-such-dir/x; echo y > .rea/no-such-dir/x",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "F2.interpreter-write-node",
+      "type": "scan-bash",
+      "input": "node -e 'require(\"fs\").writeFileSync(\".rea/HALT\", \"x\")'",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "F2.interpreter-write-python",
+      "type": "scan-bash",
+      "input": "python3 -c 'open(\".rea/HALT\", \"w\").write(\"x\")'",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "F3.nested-shell-depth",
+      "type": "scan-bash",
+      "input": "bash -c 'bash -c \"bash -c \\\"echo x > .rea/HALT\\\"\"'",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "F4.cp-explicit-destination",
+      "type": "scan-bash",
+      "input": "cp /tmp/source -t .rea -- HALT",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "F5.unresolved-expansion-redirect",
+      "type": "scan-bash",
+      "input": "echo x > .rea/$(printf HALT)",
+      "mode": "protected",
+      "expected_verdict": "block"
+    }
+  ]
+}

package/data/claims/helix-023.json

@@ -0,0 +1,44 @@
+{
+  "id": "helix-023",
+  "title": "0.23.0 structural rewrite — bash hooks → Node-binary parser-backed scanner via mvdan-sh AST",
+  "introduced_in": "<=0.22.0",
+  "closed_in": "0.23.0",
+  "summary": "13 codex adversarial rounds + 12,875-fixture corpus across 23 classes A-W. Closure ladder 34 → 14 → 9 → 8 → 5 → 2 → 1 → 1 → 3 → 2 → 7 → 9 → 9 (round-13 deferred to 0.24.0 as denylist-asymptotic per codex). PoCs sample one fixture from each closure-ladder round to verify the parser-backed scanner still rejects them.",
+  "pocs": [
+    {
+      "id": "round1.alias-then-invoke",
+      "type": "scan-bash",
+      "input": "alias evil='echo x > .rea/HALT'; evil",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "round1.heredoc-into-shell",
+      "type": "scan-bash",
+      "input": "bash <<'EOF'\necho x > .rea/HALT\nEOF",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "round1.process-substitution",
+      "type": "scan-bash",
+      "input": "diff <(echo a) <(rm -rf .rea)",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "round2.tee-redirect",
+      "type": "scan-bash",
+      "input": "echo x | tee .rea/HALT",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "round3.pipe-into-bash",
+      "type": "scan-bash",
+      "input": "echo 'echo x > .rea/HALT' | bash",
+      "mode": "protected",
+      "expected_verdict": "block"
+    }
+  ]
+}

package/data/claims/helix-024.json

@@ -0,0 +1,72 @@
+{
+  "id": "helix-024",
+  "title": "Round-24 kill-switch bypass classes (cd-cwd, double-eval, ln-symlink) — 9 PoCs",
+  "introduced_in": "0.23.0",
+  "closed_in": "0.23.1",
+  "summary": "Three P1 bypass classes against 0.23.0 closed via cd-target tracking + bash-eval payload re-parse + ln-symlink target sandbox. 5 codex local pre-push rounds caught every refinement-introduced over-block. PR #131 landed green-first-try.",
+  "pocs": [
+    {
+      "id": "F1.1.cd-and-write-literal",
+      "type": "scan-bash",
+      "input": "cd .rea && echo x > HALT",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "F1.2.cd-with-quoted-target",
+      "type": "scan-bash",
+      "input": "cd '.rea' && echo x > HALT",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "F1.3.cd-then-write-via-redirect",
+      "type": "scan-bash",
+      "input": "cd .husky; echo x > pre-push",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "F1.4.pushd-then-write",
+      "type": "scan-bash",
+      "input": "pushd .rea && cat /tmp/payload > HALT",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "F1.5.cd-with-binary-and-write",
+      "type": "scan-bash",
+      "input": "cd .claude && echo x > settings.json",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "F2.1.double-eval-string",
+      "type": "scan-bash",
+      "input": "eval 'echo x > .rea/HALT'",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "F2.2.eval-bash-c-string",
+      "type": "scan-bash",
+      "input": "eval \"bash -c 'echo x > .rea/HALT'\"",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "F3.1.ln-symlink-into-protected",
+      "type": "scan-bash",
+      "input": "ln -s /tmp/x .rea/HALT",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "F3.2.ln-symlink-into-husky",
+      "type": "scan-bash",
+      "input": "ln -sf /tmp/payload .husky/pre-push",
+      "mode": "protected",
+      "expected_verdict": "block"
+    }
+  ]
+}

package/data/claims/helix-028.json

@@ -0,0 +1,23 @@
+{
+  "id": "helix-028",
+  "title": "0.23.0 cmd-segments multiline awk + ANSI-C bypass classes",
+  "introduced_in": "0.23.0",
+  "closed_in": "0.26.1",
+  "summary": "Multiline awk inside command-substitutions and ANSI-C $'...' string literals were silently dropped from segment scanning. Two P1 bypass classes closed in 0.26.1: awk multiline body now flagged when destination is protected; ANSI-C strings normalize to their decoded form before scanning.",
+  "pocs": [
+    {
+      "id": "multiline-awk-redirect",
+      "type": "scan-bash",
+      "input": "awk 'BEGIN { print \"x\" > \".rea/HALT\" }'",
+      "mode": "protected",
+      "expected_verdict": "block"
+    },
+    {
+      "id": "ansi-c-string-redirect",
+      "type": "scan-bash",
+      "input": "echo $'\\x78' > .rea/HALT",
+      "mode": "protected",
+      "expected_verdict": "block"
+    }
+  ]
+}

package/data/claims/helix-031.json

@@ -0,0 +1,27 @@
+{
+  "id": "helix-031",
+  "title": "shellcheck SC1078 false positive on cmd-segments.sh closed by removing legacy bash module (0.27.0)",
+  "introduced_in": "0.26.1",
+  "closed_in": "0.27.0",
+  "summary": "0.26.1 added an ANSI-C handling path inside hooks/_lib/cmd-segments.sh that confused shellcheck SC1078 (mismatched single-quote in unclosed-string). 0.27.0 removed the legacy bash cmd-segments path entirely (the parser-backed Node scanner has owned the segmentation work since 0.23.0). This claim verifies that shellcheck runs clean on every shipped hook.",
+  "pocs": [
+    {
+      "id": "SC1078-clean-protected-paths-bash-gate",
+      "type": "shellcheck",
+      "target": "hooks/protected-paths-bash-gate.sh",
+      "expected_verdict": "clean"
+    },
+    {
+      "id": "SC1078-clean-blocked-paths-bash-gate",
+      "type": "shellcheck",
+      "target": "hooks/blocked-paths-bash-gate.sh",
+      "expected_verdict": "clean"
+    },
+    {
+      "id": "SC1078-clean-local-review-gate",
+      "type": "shellcheck",
+      "target": "hooks/local-review-gate.sh",
+      "expected_verdict": "clean"
+    }
+  ]
+}

package/dist/cli/index.js

@@ -12,6 +12,7 @@ import { runServe } from './serve.js';
 import { runStatus } from './status.js';
 import { runTofuAccept, runTofuList } from './tofu.js';
 import { runUpgrade } from './upgrade.js';
+import { registerVerifyClaimCommand } from './verify-claim.js';
 import { err, getPkgVersion } from './utils.js';
 async function main() {
     const program = new Command();
@@ -115,6 +116,11 @@ async function main() {
     // `local-review-gate.sh` hook both delegate to `rea preflight --strict`.
     registerReviewCommand(program);
     registerPreflightCommand(program);
+    // 0.28.0 — `rea verify-claim <claim-id>` replays recorded
+    // security-claim PoC batteries against the CLI under test. The
+    // centerpiece of 0.28.0 (4th structural pivot — claims as
+    // machine-verifiable artifacts).
+    registerVerifyClaimCommand(program);
     const tofu = program
         .command('tofu')
         .description('TOFU fingerprint operations (G7) — inspect and rebase `.rea/fingerprints.json` when a legitimate registry edit has triggered drift fail-close. Emits audit records.');

package/dist/cli/preflight.d.ts

@@ -111,6 +111,18 @@ export interface LocalReviewLookupResult {
      * (back-compat / fallback).
      */
     match_kind?: 'content_token' | 'head_sha';
+    /**
+     * 0.28.0 round-29 P3 — set when the most recent path-matching audit
+     * entry for this HEAD had verdict `blocking` (or `error`) and was
+     * therefore skipped as "not coverage". Surfacing this lets the
+     * preflight caller render a clearer message than "no recent local-
+     * review audit entry covers HEAD" — the operator hasn't forgotten
+     * to review, they've already done one and it told them to fix
+     * findings.
+     */
+    last_blocking_verdict?: 'blocking' | 'error';
+    /** ISO timestamp of the last blocking entry, when present. */
+    last_blocking_timestamp?: string;
 }
 export declare function findRecentLocalReview(baseDir: string, headSha: string, maxAgeSeconds: number, now?: Date, contentToken?: string): LocalReviewLookupResult;
 /**

package/dist/cli/preflight.js

@@ -124,10 +124,20 @@ export async function computePreflight(baseDir, options, env = process.env) {
     if (!reviewCheckSkipped) {
         const lookup = findRecentLocalReview(baseDir, headSha, maxAgeSeconds, new Date(), contentToken);
         if (!lookup.found) {
+            // 0.28.0 round-29 P3: when the most recent path-matching audit
+            // entry was blocking/error, the operator HAS reviewed — they
+            // just need to address the findings. The original message ("no
+            // recent local-review audit entry covers HEAD") makes them
+            // think they forgot to review. Distinguish the two cases.
+            const reason = lookup.last_blocking_verdict === 'blocking'
+                ? 'your last local review was blocking — address findings or override'
+                : lookup.last_blocking_verdict === 'error'
+                    ? 'your last local review errored — re-run `rea review` and address findings'
+                    : 'no recent local-review audit entry covers HEAD';
             return {
                 outcome: {
                     status: 'refuse',
-                    reason: 'no recent local-review audit entry covers HEAD',
+                    reason,
                     exitCode: 2,
                     details: {
                         head_sha: headSha,
@@ -135,6 +145,12 @@ export async function computePreflight(baseDir, options, env = process.env) {
                         max_age_seconds: maxAgeSeconds,
                         bypass_env_var: bypassEnvVar,
                         policy_off_switch: 'policy.review.local_review.mode: off',
+                        ...(lookup.last_blocking_verdict !== undefined
+                            ? {
+                                last_blocking_verdict: lookup.last_blocking_verdict,
+                                last_blocking_timestamp: lookup.last_blocking_timestamp,
+                            }
+                            : {}),
                     },
                 },
                 policy,
@@ -292,6 +308,21 @@ function resolveCommitCountBase(baseDir) {
         if (resolveRef(baseDir, ref).length > 0)
             return ref;
     }
+    // 0.28.0 round-29 P3: develop-branch repos sometimes omit
+    // `origin/HEAD` entirely (the symbolic ref is unset until a fresh
+    // `git remote set-head origin -a`), and `origin/main` /
+    // `origin/master` may not exist when the trunk is `origin/develop`.
+    // Pre-fix the resolver silently fell through to `null`, disabling
+    // the auto-narrow check without telling the operator. Emit a single
+    // advisory line on stderr so the failure mode is visible — but do
+    // not fail; this path is best-effort and a missing trunk is a
+    // recoverable misconfiguration.
+    if (resolveRef(baseDir, 'origin/develop').length > 0) {
+        process.stderr.write(`rea: preflight commit-count base falling through to origin/develop ` +
+            `(origin/HEAD/main/master not resolvable). ` +
+            `Consider: \`git remote set-head origin -a\` to seed origin/HEAD.\n`);
+        return 'origin/develop';
+    }
     // `@{upstream}` LAST. We additionally probe what it resolves to —
     // if it's a remote feature-branch ref under `refs/remotes/origin/`
     // (not a primary trunk ref we already tried), the candidate is
@@ -365,6 +396,13 @@ export function findRecentLocalReview(baseDir, headSha, maxAgeSeconds, now = new
     }
     const lines = raw.split(/\r?\n/);
     const cutoffMs = now.getTime() - maxAgeSeconds * 1000;
+    // 0.28.0 round-29 P3: track the most recent blocking/error entry that
+    // path-matched HEAD even though it didn't qualify as coverage. The
+    // not-found return path consumes this so the operator-facing message
+    // distinguishes "you haven't reviewed" from "your review found
+    // problems".
+    let lastBlockingVerdict;
+    let lastBlockingTimestamp;
     // Walk in reverse — most recent first.
     for (let i = lines.length - 1; i >= 0; i--) {
         const line = lines[i];
@@ -421,8 +459,19 @@ export function findRecentLocalReview(baseDir, headSha, maxAgeSeconds, now = new
         if (matchKind === null)
             continue;
         const verdict = typeof metadata.verdict === 'string' ? metadata.verdict : '';
-        if (verdict === 'error' || verdict === 'blocking')
+        if (verdict === 'error' || verdict === 'blocking') {
+            // 0.28.0 round-29 P3 — capture the FIRST (i.e., most-recent in
+            // reverse walk) blocking/error entry that path-matched HEAD so
+            // the not-found path can render a better message. Don't
+            // overwrite a later catch — we want the most-recent one.
+            if (lastBlockingVerdict === undefined) {
+                lastBlockingVerdict = verdict;
+                const ts = typeof record.timestamp === 'string' ? record.timestamp : '';
+                if (ts.length > 0)
+                    lastBlockingTimestamp = ts;
+            }
             continue;
+        }
         const timestamp = typeof record.timestamp === 'string' ? record.timestamp : '';
         if (timestamp.length > 0) {
             const ts = Date.parse(timestamp);
@@ -430,7 +479,13 @@ export function findRecentLocalReview(baseDir, headSha, maxAgeSeconds, now = new
                 // Older than max_age_seconds — keep walking; a more recent valid
                 // record may exist further back? No: we walk newest-to-oldest so
                 // anything older from here on is also stale. Stop early.
-                return { found: false };
+                return {
+                    found: false,
+                    ...(lastBlockingVerdict !== undefined ? { last_blocking_verdict: lastBlockingVerdict } : {}),
+                    ...(lastBlockingTimestamp !== undefined
+                        ? { last_blocking_timestamp: lastBlockingTimestamp }
+                        : {}),
+                };
             }
         }
         return {
@@ -441,7 +496,13 @@ export function findRecentLocalReview(baseDir, headSha, maxAgeSeconds, now = new
             match_kind: matchKind,
         };
     }
-    return { found: false };
+    return {
+        found: false,
+        ...(lastBlockingVerdict !== undefined ? { last_blocking_verdict: lastBlockingVerdict } : {}),
+        ...(lastBlockingTimestamp !== undefined
+            ? { last_blocking_timestamp: lastBlockingTimestamp }
+            : {}),
+    };
 }
 async function safeAudit(baseDir, toolName, status, metadata, policy) {
     try {

package/dist/cli/review.d.ts

@@ -31,6 +31,8 @@
  * the push-gate's review.
  */
 import type { Command } from 'commander';
+import { type LocalReviewVerdict } from '../audit/local-review-event.js';
+import { type Finding } from '../hooks/push-gate/findings.js';
 export interface RunReviewOptions {
     /** Optional explicit base ref. Defaults to upstream-ladder resolution. */
     base?: string;
@@ -42,13 +44,65 @@ export interface RunReviewOptions {
     strictFailOn?: 'concerns' | 'blocking';
     /** Emit a single JSON line on stdout instead of pretty output. */
     json?: boolean;
+    /**
+     * 0.28.1 defect-V: when true, after the human-readable summary line
+     * (or alongside the JSON payload), emit the finding bodies grouped by
+     * severity. Default off — preserves backward-compatible single-line
+     * stdout for existing CI consumers.
+     */
+    withFindings?: boolean;
+}
+/**
+ * Exported so tests can construct fake outcomes for the seam in
+ * `runReview`. Production callers don't reference this directly.
+ */
+export interface ReviewOutcome {
+    verdict: LocalReviewVerdict;
+    findingCount: number;
+    baseRef: string;
+    headSha: string;
+    /**
+     * 0.26.0 helix-026 finding-1: tree SHA of HEAD at review time. The
+     * deterministic content fingerprint `rea preflight` matches coverage
+     * on. Empty string when not resolvable (no HEAD, no git repo) — the
+     * audit writer omits `content_token` from metadata in that case.
+     */
+    contentToken: string;
+    durationSeconds: number;
+    model: string;
+    reasoningEffort: string;
+    /**
+     * 0.28.1 defect-V: structured findings produced by the review. Pre-fix
+     * the CLI threw these away after counting; agents could not remediate
+     * blocking verdicts because the bodies were unreadable through any
+     * documented surface.
+     */
+    findings: Finding[];
+    /**
+     * 0.28.1 defect-V: full agent-prose review text. Persisted to
+     * `.rea/last-review.json` (post-redaction) so consumers have a
+     * machine-readable transcript for parser-miss debugging.
+     */
+    reviewText: string;
+    /** Count of raw JSONL events from codex — recorded in last-review.json. */
+    eventCount: number;
+}
+/**
+ * 0.28.1 defect-V — narrow test seam. Production callers never set this;
+ * tests inject a fake to drive `runReview` deterministically without
+ * spawning codex. The seam matches `executeCodexReview`'s signature so
+ * the production path and the test path go through the same downstream
+ * wiring (audit append, last-review.json, exit code, output).
+ */
+export interface RunReviewDeps {
+    executeCodexReview?: (baseDir: string, options: RunReviewOptions) => Promise<ReviewOutcome>;
 }
 /**
  * Public runner — exposed so tests can drive the function in-process and
  * the commander binding can stay thin. Throws via `process.exit` (CLI
  * convention across `src/cli/`).
  */
-export declare function runReview(options: RunReviewOptions): Promise<void>;
+export declare function runReview(options: RunReviewOptions, deps?: RunReviewDeps): Promise<void>;
 /**
  * Attach `rea review` to a commander Program.
  */