@bookedsolid/rea 0.35.0 → 0.36.0

package/dist/cli/doctor.js

@@ -169,22 +169,19 @@ export const EXPECTED_HOOKS = [
     'blocked-paths-enforcer.sh',
     'changeset-security-gate.sh',
     'dangerous-bash-interceptor.sh',
-    // 0.31.0 — `delegation-advisory.sh` is INTENTIONALLY NOT in this list.
-    // It is the brand-new PostToolUse delegation-nudge hook this release
-    // ships; adding it to EXPECTED_HOOKS would make `checkHooksInstalled`
-    // hard-`fail` on every pre-0.31.0 consumer install (and on this repo's
-    // own dogfood) the instant they upgrade the rea binary but before they
-    // run `rea upgrade` to lay down the new hook file — a regression that
-    // turns a green doctor red purely from upgrade lag. This mirrors the
-    // staged rollout `delegation-capture.sh` itself used: the file-presence
-    // entry joins EXPECTED_HOOKS in the SAME future minor that promotes
-    // `checkDelegationAdvisoryHookRegistered` from `warn` to `fail`, once
-    // consumers have had upgrade-lag time. Until then, a missing
-    // `delegation-advisory.sh` surfaces only through that `warn`-tier
-    // registration check — proportionate, since the hook is advisory at
-    // runtime and never blocks a tool call. See `git blame` on the 0.29.0
-    // round-2 P2 comment on `checkDelegationHookRegistered` for the prior
-    // application of this exact discipline.
+    // 0.36.0 — `delegation-advisory.sh` PROMOTED to EXPECTED_HOOKS (charter
+    // follow-through from 0.31.0). Originally held out in 0.31.0 to give
+    // consumers an upgrade-lag window: adding a brand-new hook to
+    // EXPECTED_HOOKS would have hard-`fail`ed `checkHooksInstalled` on
+    // every pre-0.31.0 install the instant they bumped the rea binary, a
+    // regression that turns a green doctor red purely from upgrade lag.
+    // After 4 releases of propagation (0.32, 0.33, 0.34, 0.35), the lag
+    // window has closed — consumers running `rea upgrade` since 0.31.0
+    // have laid the hook down. Same ratchet `delegation-capture.sh` went
+    // through 0.29.0 → 0.30.0. Promotion happens in lockstep with
+    // `checkDelegationAdvisoryHookRegistered` flipping `warn` → `fail`
+    // (see that function for the matching commentary).
+    'delegation-advisory.sh',
     // 0.29.0 — delegation-telemetry MVP. The PreToolUse hook on
     // matcher `Agent|Skill` emits a `rea.delegation_signal` audit record
     // on every subagent / skill dispatch. Observational only — fails
@@ -1126,14 +1123,25 @@ export function checkDelegationHookRegistered(baseDir) {
  */
 export function checkDelegationAdvisoryHookRegistered(baseDir) {
     const label = 'delegation-advisory hook registered';
-    const ADVISORY = 'warn';
+    // 0.36.0 — promoted from `warn` (advisory in 0.31.0) to `fail` (hard)
+    // per the staged-rollout ratchet. After 4 releases of upgrade-lag
+    // propagation (0.32, 0.33, 0.34, 0.35), consumer installs that have
+    // run `rea upgrade` since 0.31.0 already carry the PostToolUse
+    // `Bash|Edit|Write|MultiEdit|NotebookEdit` group. Any install that
+    // still lacks it after that window is genuinely missing the nudge
+    // and `fail` is the proportionate signal. Companion change:
+    // `delegation-advisory.sh` joined `EXPECTED_HOOKS` in the same
+    // commit, so `checkHooksInstalled` also covers the file-presence +
+    // executability checks now (this function still does both directly
+    // as defense-in-depth, mirroring `checkDelegationHookRegistered`).
+    const REFUSE = 'fail';
     const MATCHER = 'Bash|Edit|Write|MultiEdit|NotebookEdit';
     const settingsPath = path.join(baseDir, '.claude', 'settings.json');
     if (!fs.existsSync(settingsPath)) {
         return {
             label,
-            status: ADVISORY,
-            detail: `missing: ${settingsPath} — run \`rea upgrade\` or \`rea init\` (advisory in 0.31.0)`,
+            status: REFUSE,
+            detail: `missing: ${settingsPath} — run \`rea upgrade\` or \`rea init\``,
         };
     }
     let parsed;
@@ -1143,7 +1151,7 @@ export function checkDelegationAdvisoryHookRegistered(baseDir) {
     catch (e) {
         return {
             label,
-            status: ADVISORY,
+            status: REFUSE,
             detail: e instanceof Error ? e.message : String(e),
         };
     }
@@ -1152,9 +1160,9 @@ export function checkDelegationAdvisoryHookRegistered(baseDir) {
     if (group === undefined) {
         return {
             label,
-            status: ADVISORY,
+            status: REFUSE,
             detail: `no PostToolUse group with matcher "${MATCHER}" found in .claude/settings.json — ` +
-                'run `rea upgrade` to install (advisory in 0.31.0; promoted to fail in a later minor). ' +
+                'run `rea upgrade` to install. ' +
                 'NOTE: the matcher INCLUDES Bash — the delegation nudge counts every write-class ' +
                 'tool call, not just file edits.',
         };
@@ -1163,16 +1171,16 @@ export function checkDelegationAdvisoryHookRegistered(baseDir) {
     if (!cmds.some((c) => c.includes('delegation-advisory.sh'))) {
         return {
             label,
-            status: ADVISORY,
+            status: REFUSE,
             detail: `${MATCHER} matcher exists but no delegation-advisory.sh command found in its hooks list`,
         };
     }
-    // Round-2/3 P2: the registration string is present — now confirm the
-    // hook file it points at actually exists AND is executable. Because
-    // `delegation-advisory.sh` is intentionally out of `EXPECTED_HOOKS`
-    // for 0.31.0, `checkHooksInstalled` does NOT cover it; this is the
-    // only signal, so it owns both the presence and the `0o111` checks
-    // that `checkHooksInstalled` does for every other shipped hook.
+    // 0.31.0 round-2/3 P2: the registration string is present — now
+    // confirm the hook file it points at actually exists AND is
+    // executable. Kept after the 0.36.0 EXPECTED_HOOKS promotion as
+    // defense-in-depth (the same `0o111` check `checkHooksInstalled`
+    // does, scoped to this hook so the failure message can name the
+    // exact remediation rather than a generic "missing X" enumeration).
     const hookFile = path.join(baseDir, '.claude', 'hooks', 'delegation-advisory.sh');
     let hookStat;
     try {
@@ -1181,19 +1189,19 @@ export function checkDelegationAdvisoryHookRegistered(baseDir) {
     catch {
         return {
             label,
-            status: ADVISORY,
+            status: REFUSE,
             detail: `${MATCHER} matcher references delegation-advisory.sh but the hook file is missing: ` +
-                `${hookFile} — run \`rea upgrade\` to lay it down (advisory in 0.31.0). ` +
+                `${hookFile} — run \`rea upgrade\` to lay it down. ` +
                 'Without the file every matching PostToolUse dispatch shells out to a nonexistent path.',
         };
     }
     if ((hookStat.mode & 0o111) === 0) {
         return {
             label,
-            status: ADVISORY,
+            status: REFUSE,
             detail: `${MATCHER} matcher references delegation-advisory.sh but the hook file is not executable ` +
                 `(mode=${(hookStat.mode & 0o777).toString(8)}): ${hookFile} — ` +
-                'run `rea upgrade` or `chmod +x` it (advisory in 0.31.0). ' +
+                'run `rea upgrade` or `chmod +x` it. ' +
                 'A non-executable hook cannot be launched by Claude Code from settings.json.',
         };
     }
@@ -1469,9 +1477,10 @@ export function collectChecks(baseDir, codexProbeState, prePushState, options =
         checkDelegationHookRegistered(baseDir),
         // 0.31.0 — delegation-telemetry completion. The PostToolUse
         // `Bash|Edit|Write|MultiEdit|NotebookEdit` matcher group drives
-        // the delegation-advisory nudge hook. Advisory (warn) for 0.31.0
-        // — same upgrade-lag ratchet checkDelegationHookRegistered went
-        // through in 0.29.0.
+        // the delegation-advisory nudge hook. 0.36.0 — promoted warn →
+        // fail (same upgrade-lag ratchet checkDelegationHookRegistered
+        // went through in 0.29.0 → 0.30.0, after 4 release cycles of
+        // propagation).
         checkDelegationAdvisoryHookRegistered(baseDir),
     ];
     // Non-git escape hatch: when `.git/` is absent, both git-hook checks are

package/dist/hooks/_lib/segments.js

@@ -467,6 +467,50 @@ function splitSegmentsRecursive(cmd, depth) {
     }
     return out;
 }
+/**
+ * Test whether a flag token is a `-c`-class introducer.
+ *
+ * Bash accepts `-c` combined with any other short single-char flags in
+ * a single short-flag bundle: `-c`, `-lc`, `-lic`, `-cli`, `-lci`,
+ * `-cil`, `-ilc`, etc. The bash cmd-segments.sh `WRAP` regex lists
+ * a non-exhaustive defensive subset (`c|lc|lic|ic|cl|cli|li|il`) but
+ * bash itself accepts ANY short-flag bundle that contains a `c`.
+ *
+ * The TS detector mirrors bash semantics: a SHORT-flag bundle
+ * (`-letters`, single leading `-`) whose letter set contains `c` is
+ * an introducer. The separated `--c` long-flag form is also
+ * recognized for parity with the bash WRAP regex's `--c` alternation.
+ *
+ * Long flags (`--rcfile`, `--noprofile`, `--login`, `--init-file`)
+ * are NOT introducers regardless of whether they contain the letter
+ * `c` — bash's long-options namespace is disjoint from the `-c`
+ * payload-execute semantics.
+ *
+ * 0.36.0 audit-trail:
+ *   - Charter item 4 / 0.34.0 codex round-7 P2 #1: pre-fix the test
+ *     was `/c/i.test(flag.replace(/^--?/, ''))` which over-matched on
+ *     every flag with a `c` in its name (`--rcfile`, `--noprofile`).
+ *   - 0.36.0 codex round-1 P1: the first fix attempt used an explicit
+ *     allowlist `Set` mirroring the bash WRAP regex's explicit
+ *     alternation, which was a NARROWING vs the pre-fix behavior —
+ *     valid combined-flag forms like `-lci`, `-cil`, `-ilc` were not
+ *     in the allowlist and stopped unwrapping, reopening a bypass
+ *     surface against env-file-protection / dependency-audit-gate /
+ *     dangerous-bash matchers. This function restores parity with
+ *     bash itself: any short-flag bundle containing `c` qualifies.
+ */
+function isCDashIntroducer(flag) {
+    // Separated long-flag form (rare but bash accepts it).
+    if (flag === '--c')
+        return true;
+    // Short-flag bundle: single leading `-`, then one-or-more letters.
+    // The bundle is a `-c` introducer iff it contains the letter `c`
+    // (any position, any other-letters mix).
+    const m = /^-([A-Za-z]+)$/.exec(flag);
+    if (m === null)
+        return false;
+    return /c/i.test(m[1] ?? '');
+}
 /**
  * Recognize a nested-shell wrapper segment and return the unquoted
  * payload string. Returns `null` when the segment is not a wrapper.
@@ -554,15 +598,29 @@ function extractNestedShellPayload(head) {
             return null;
         const flag = flagMatch[0] ?? '';
         cursor += flag.length;
-        // Recognized flag-token shapes:
-        //   `-c` `-l` `-i` `-e` `-lc` `-lic` `-ic` `-cl` `-cli` `-li` `-il`
-        //   `--c` `--noprofile` (etc.) — we don't enforce the full list,
-        //   just that it's `-<letters>` or `--<letters>`.
+        // Recognized flag-token shapes (parity with cmd-segments.sh WRAP):
+        //   - pre-flags (no `-c` yet): `-l`, `-i`, `-e`, `-li`, `-il`,
+        //     `--noprofile`, `--rcfile`, `--login` (etc.)
+        //   - `-c`-class introducer: exactly `-c`, `-lc`, `-lic`, `-cl`,
+        //     `-cli`, `-li`, `-il`, `-ic` (the bash WRAP regex's
+        //     `-(c|lc|lic|ic|cl|cli|li|il)` set), OR separated `--c`.
+        //
+        // 0.36.0 audit-trail (charter item 4 / 0.34.0 codex round-7 P2 #1):
+        // pre-fix the test `/c/i.test(flag.replace(/^--?/, ''))` treated
+        // ANY flag containing the letter `c` as a `-c` introducer. This
+        // false-positived on benign flags like `--rcfile`, `--noprofile`
+        // (with `c` in the name), causing the walker to "commit" to a -c
+        // unwrap, advance past the flag, and then either fail to find a
+        // quoted payload or unwrap something that was never a shell-payload
+        // body. Net effect: over-trigger of nested-shell unwrap, with
+        // downstream advisory matchers seeing payloads that weren't ever
+        // shell-payloads. Fix restricts the introducer set to the exact
+        // WRAP-regex shapes; any other flag shape continues the flag walk
+        // (still valid — pre-flags before `-c` are accepted) but does NOT
+        // mark `sawCFlag = true`.
         if (!/^--?[A-Za-z]+$/.test(flag))
             return null;
-        // Does this flag contain `c` (the -c introducer letter)?
-        // `--c` also counts (rare but bash accepts).
-        if (/c/i.test(flag.replace(/^--?/, ''))) {
+        if (isCDashIntroducer(flag)) {
             sawCFlag = true;
             // Continue the loop — the payload is the NEXT non-flag token.
             // (Bash's argv parser stops walking flags as soon as it sees -c,
@@ -570,6 +628,8 @@ function extractNestedShellPayload(head) {
             // safety; the bash WRAP regex similarly tolerates trailing
             // flag-like tokens before the quoted body.)
         }
+        // Else: a pre-flag (e.g. `-l`, `--rcfile`, `--noprofile`) — keep
+        // walking; if a later token IS in `CDASH_INTRODUCERS` we'll fire.
     }
     if (!sawCFlag)
         return null;

package/dist/hooks/secret-scanner/index.js

@@ -127,7 +127,22 @@ const SECRET_PATTERNS = [
     {
         severity: 'HIGH',
         label: 'Supabase service role key (JWT)',
-        regex: /SUPABASE_SERVICE_ROLE_KEY\s*=\s*["']?eyJ[A-Za-z0-9._-]{50,}/g,
+        // 0.36.0 audit-trail (charter item 5 / 0.34.0 codex round-7 P2 #2):
+        // restore byte-parity with the pre-0.34.0 bash body. The bash hook
+        // required a quote introducer (`["']`, no `?`); only quoted
+        // assignments matched HIGH. Pre-fix this TS regex made the quote
+        // OPTIONAL (`["']?`), which upgraded an unquoted `.env` line like
+        // `SUPABASE_SERVICE_ROLE_KEY=eyJ...` from MEDIUM advisory (matched
+        // by the lower-down `.env credential assignment` pattern) to HIGH
+        // blocking. That over-blocks legitimate `.env` files committed to
+        // public repos and breaks parity with consumers still on the bash
+        // body. Fix: drop the `?` so the quote is required, matching bash
+        // exactly. Unquoted assignments continue to fire MEDIUM via the
+        // `.env credential assignment` pattern below (line ~190); the only
+        // change is that they no longer ALSO fire HIGH here. The `[\"']`
+        // character class accepts both single and double quotes
+        // (mirroring the bash `["\'"'"']` literal).
+        regex: /SUPABASE_SERVICE_ROLE_KEY\s*=\s*["']eyJ[A-Za-z0-9._-]{50,}/g,
     },
     // ── MEDIUM severity (advisory) ───────────────────────────────────
     {
@@ -153,10 +168,57 @@ const SECRET_PATTERNS = [
         label: 'Hardcoded DB connection string with password',
         regex: /postgresql:\/\/[^:]+:[^@]{8,}@/g,
     },
+    {
+        severity: 'MEDIUM',
+        label: 'Supabase service role key (JWT, unquoted non-.env shape)',
+        // 0.36.0 codex round-2 P1 → round-3 P3 → round-4 P1 evolution.
+        //
+        // Background:
+        //   - Round 1: 0.34.0-introduced HIGH regex had `["']?` (quote
+        //     optional) which over-blocked unquoted .env lines vs the
+        //     pre-0.34.0 bash baseline. Charter item 5 dropped the `?`.
+        //   - Round 2 P1: dropping the `?` left a gap for unquoted forms
+        //     outside `^FOO=` shape (`export FOO=…` etc.) that ALSO
+        //     existed in the bash baseline. Added an unquoted-anywhere
+        //     MEDIUM rule to close it.
+        //   - Round 3 P3: unquoted-anywhere double-fired with the broader
+        //     `.env credential assignment` MEDIUM on plain `^FOO=` lines.
+        //     Narrowed to only fire on 5 specific shell-keyword prefixes
+        //     (`export`, `readonly`, `declare`, `local`, `typeset`).
+        //   - Round 4 P1: too narrow — left other unquoted shapes
+        //     (Dockerfile `ENV FOO=…`, k8s manifests, ad-hoc shell
+        //     `FOO=…; bar`) entirely unscanned.
+        //
+        // Round-4 resolution: fire on any unquoted assignment that is
+        // NOT at the start of a line (`^`). The `.env credential
+        // assignment` MEDIUM pattern owns `^FOO=…`; this rule owns
+        // everything else (`ENV FOO=…`, `export FOO=…`, `; FOO=…`,
+        // template-string `${FOO=…}`, etc.). Implemented via a
+        // multi-line regex with a look-behind for "anything except a
+        // line start". JS regex doesn't support a direct "not at line
+        // start" assertion, so we require at least one non-newline char
+        // before `SUPABASE_SERVICE_ROLE_KEY` on the same line.
+        //
+        // The `(?!["'])` look-ahead refuses when the value starts with
+        // a quote so the same secret isn't double-reported by the HIGH
+        // pattern above. Result: each secret produces exactly one
+        // MEDIUM finding regardless of shape, and the HIGH rule keeps
+        // exclusive ownership of quoted forms.
+        regex: /(?<=[^\n\r])\bSUPABASE_SERVICE_ROLE_KEY\s*=\s*(?!["'])eyJ[A-Za-z0-9._-]{50,}/gm,
+    },
     {
         severity: 'MEDIUM',
         label: 'Supabase anon key in non-client context',
-        regex: /SUPABASE_ANON_KEY\s*=\s*["']?eyJ[A-Za-z0-9._-]{50,}/g,
+        // 0.36.0 audit-trail (charter item 5 / 0.34.0 codex round-7 P2 #2,
+        // sibling fix): same parity restoration as the SUPABASE_SERVICE_ROLE_KEY
+        // pattern above — bash hook required a quote introducer, TS pattern
+        // had it optional via `?`. Removed for byte-parity. Unquoted .env
+        // forms continue to be advisory via the broader `.env credential
+        // assignment` MEDIUM pattern (where SUPABASE_ANON_KEY is NOT one of
+        // the named keys — anon-key prose in unquoted .env is acceptable
+        // since anon keys are public; only QUOTED-in-source matches stay
+        // an advisory MEDIUM here).
+        regex: /SUPABASE_ANON_KEY\s*=\s*["']eyJ[A-Za-z0-9._-]{50,}/g,
     },
 ];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bookedsolid/rea",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "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)",
@@ -95,8 +95,9 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "postinstall": "node scripts/postinstall.mjs",
-    "lint": "pnpm run lint:regex && eslint .",
+    "lint": "pnpm run lint:regex && pnpm run lint:awk-quotes && eslint .",
     "lint:regex": "node scripts/lint-safe-regex.mjs",
+    "lint:awk-quotes": "node scripts/lint-awk-shim-quotes.mjs",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "pnpm run build && pnpm run test:dogfood && pnpm run test:bash-syntax && node scripts/run-vitest.mjs",

package/scripts/lint-awk-shim-quotes.mjs

@@ -0,0 +1,386 @@
+#!/usr/bin/env node
+// G — Static lint for `awk '...'` blocks embedded in bash hooks.
+//
+// 0.36.0 charter item 3 / 0.34.0 round-4 + round-6 regression class.
+//
+// # The class
+//
+// Bash hooks frequently embed an awk script inside a bash-single-quoted
+// argument:
+//
+//   awk '
+//     # awk comment
+//     { print $1 }
+//   '
+//
+// Bash single-quoted strings have one rule: NO escape sequences inside.
+// The string ends at the next unescaped `'`. If any character inside the
+// awk body is a literal `'`, bash terminates the string THERE — the rest
+// of the awk body is then re-parsed as bash, almost always producing a
+// `syntax error near unexpected token` or worse, silently shelling out
+// to whatever follows.
+//
+// The 0.34.0 marathon hit this twice — once at round-4, once at round-6.
+// The round-6 instance locked the entire repo (every Bash refused at
+// hook parse time because every hook sourced `_lib/cmd-segments.sh`,
+// which crashed at parse). Repair required out-of-session `git apply`.
+//
+// # The lint
+//
+// For each `*.sh` under `hooks/` and `.claude/hooks/` (dogfood mirror),
+// find every `awk '<NL>` block opening (the awk-with-multiline-body
+// shape that the marathon class triggers in), scan inward until the
+// matching unescaped `'`, and flag any line inside that:
+//
+//   - Starts with optional whitespace then `#` (a comment line in awk),
+//   - Contains a literal `'`.
+//
+// We deliberately do NOT lint inline awk one-liners (`awk '{ print $1 }'`
+// on one line) because those have no comment lines by construction —
+// the bug class only manifests in multi-line awk bodies.
+//
+// # Wired into `pnpm lint`
+//
+// `package.json#scripts.lint` chains `lint:awk-quotes` before eslint, in
+// the same posture as `lint:regex`. A failure here means a `'` ended up
+// in an awk comment in a shipped hook body; the diff that introduced it
+// would have parse-failed the hook at runtime (the way 0.34.0 round-6
+// did). CI catches it before it ships.
+//
+// Mirrors-coverage rationale: `.claude/hooks/` is rea's own dogfood
+// mirror. `tools/check-dogfood-drift.mjs` already enforces byte-equality
+// between `hooks/*.sh` and `.claude/hooks/*.sh`, but this lint runs
+// BEFORE that gate during a typical edit cycle, and a drifted mirror
+// could still ship if the drift gate is bypassed. Lint both for
+// defense-in-depth.
+
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(here, '..');
+
+// 0.36.0 codex round-5 P2 #1: extended coverage. Originally the
+// SCAN_DIRS list only covered `hooks/` and `.claude/hooks/` — but the
+// package also ships awk-heavy shell scripts in `.husky/` (e.g.
+// `prepare-commit-msg`) and `templates/` (e.g.
+// `local-review-gate.dogfood-staged.sh`). A bare-apostrophe regression
+// in those surfaces would have shipped silently. Adding them here
+// pulls them under the same gate. Each path is checked for existence
+// in `listShellFiles` so a profile that omits the directory still
+// works.
+const SCAN_DIRS = [
+  path.join(repoRoot, 'hooks'),
+  path.join(repoRoot, 'hooks', '_lib'),
+  path.join(repoRoot, '.claude', 'hooks'),
+  path.join(repoRoot, '.claude', 'hooks', '_lib'),
+  // 0.36.0 codex round-5 P2 #1 additions.
+  path.join(repoRoot, '.husky'),
+  path.join(repoRoot, 'templates'),
+];
+
+/**
+ * List shell-script files directly under the given directory
+ * (non-recursive). A file qualifies if it ends in `.sh` OR its
+ * first line is a `#!/...sh`/`#!/...bash` shebang (for extensionless
+ * husky hooks like `.husky/pre-push`).
+ *
+ * Returns empty array if the directory doesn't exist.
+ *
+ * 0.36.0 codex round-5 P2 #1: pre-fix required `.sh` extension, which
+ * skipped every `.husky/` file (they're shipped extensionless).
+ */
+function listShellFiles(dir) {
+  if (!existsSync(dir)) return [];
+  const entries = readdirSync(dir, { withFileTypes: true });
+  const out = [];
+  for (const e of entries) {
+    if (!e.isFile()) continue;
+    const full = path.join(dir, e.name);
+    // Codex round-7 P2: `.patch` files are unified diffs (hunk-prefixed
+    // lines, comments interleaved with `+`/`-`/` `), NOT raw shell. The
+    // scanFile function only understands shell syntax, so feeding a
+    // patch through it generates false-positives on benign comment-
+    // hunks like `+# this isn't related to awk`. Skip patches; the
+    // hook body the patch SHIPS TO will be linted directly once
+    // applied, which is the more reliable signal anyway.
+    if (e.name.endsWith('.sh')) {
+      out.push(full);
+      continue;
+    }
+    // Extensionless: check shebang.
+    try {
+      const head = readFileSync(full, 'utf8').slice(0, 64);
+      if (/^#!.*\b(sh|bash|zsh|dash|ksh)\b/.test(head)) {
+        out.push(full);
+      }
+    } catch {
+      // unreadable — skip silently
+    }
+  }
+  return out;
+}
+
+/**
+ * Scan a single `.sh` file for `awk '` opening blocks (multi-line body
+ * shape: `awk '` at end of a line, OR `awk '` followed by newline). For
+ * each open block, walk lines until the closing unescaped `'` and flag
+ * any comment line containing a literal `'`.
+ *
+ * Returns an array of `{file, line, content, reason}` findings.
+ */
+function scanFile(file) {
+  const text = readFileSync(file, 'utf8');
+  const lines = text.split('\n');
+  const findings = [];
+
+  let inAwkBlock = false;
+  let awkStartLine = -1;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+
+    if (!inAwkBlock) {
+      // Detect block opening: any line containing the `awk` keyword
+      // that opens an awk-arg single-quote which DOESN'T close on
+      // the same line. Real-corpus shapes that must trigger:
+      //
+      //   awk '                                        ← bare
+      //   ... | awk '                                   ← piped
+      //   ... | awk -v key=val '                        ← -v vars
+      //   foo=$(awk -v a="$x" -v b="$y" '              ← multi-var
+      //   awk -F: '                                     ← field-sep
+      //   awk -v msg="can't" '                          ← -v with `'` in DQ-arg
+      //   awk 'BEGIN { ... }                            ← body starts on opener
+      //   ... | awk 'BEGIN { x = 1                      ← body starts on opener
+      //
+      // And must NOT trigger on:
+      //
+      //   # Example: awk '...'                          ← shell comment about awk
+      //   awk '{print $1}'                              ← one-liner (no multi-line)
+      //
+      // Algorithm:
+      //   1. Skip shell-comment lines (leading `#`).
+      //   2. Require the `awk` keyword somewhere on the line.
+      //   3. Strip benign bash quote-escape sequences.
+      //   4. Count remaining `'`. An odd count means the line opens
+      //      an awk-arg that doesn't close on this line (multi-line
+      //      body). An even count means every open is paired with a
+      //      close on this line (one-liner — no multi-line bug
+      //      class).
+      //
+      // 0.36.0 codex round-3 P2 #1: pre-fix opener was
+      // `/\bawk\b/ && /'\s*$/` which flipped on any prose line
+      // mentioning awk that happened to end in `'` (e.g. a comment
+      // like `# Example: awk '`). Shell-comment skip closes that
+      // false-positive path.
+      //
+      // 0.36.0 codex round-3 P2 #2: pre-fix opener required `'` at
+      // EOL, missing the `awk 'BEGIN { ... }` shape where the body
+      // starts on the same line as the opener. Odd-quote-count
+      // detection handles both shapes uniformly.
+      // Skip shell-comment lines — they may mention `awk` in prose
+      // (e.g. `# Example: awk '...'`) without being a real awk call.
+      const codeOnly = line.replace(/^\s+/, '');
+      if (codeOnly.startsWith('#')) continue;
+      if (!/\bawk\b/.test(line)) continue;
+      // Strip in order:
+      //   - bash double-quoted spans (`"..."`) — bash treats `'`
+      //     inside them as literal, NOT as quote terminators. Without
+      //     this strip, `awk -v msg="can't" '` would count 2 `'`s
+      //     and look balanced when it's actually 1 unclosed open.
+      //   - benign quote-escape sequences (`'\''`, `'"'"'`, `''`).
+      // Order matters: strip `"..."` first because the `'"'"'`
+      // escape contains a DQ pair that would be wrongly consumed by
+      // the DQ-strip if applied second.
+      // Codex round-7 P1 fix: the prior `"[^"]*"` strip was too naive —
+      // a valid shell line like `awk -v msg="foo \"can't\" bar" '` has
+      // backslash-escaped quotes inside the double-quoted span. `[^"]*`
+      // stops at the first `"` (which is `\"`), the next `"` opens a
+      // new span, etc. The apostrophe from `can't` is left behind and
+      // the linter false-balances the quote count. Fix: walk DQ spans
+      // with proper escape handling — treat `\\` and `\"` as escapes,
+      // ANY other char between `"`s is literal.
+      let sanitizedOpener = line
+        .replace(/'"'"'/g, '')
+        .replace(/'\\''/g, '')
+        .replace(/''/g, '');
+      // Replace each `"..."` (with backslash-escape awareness) with `""`.
+      sanitizedOpener = sanitizedOpener.replace(/"(?:[^"\\]|\\[\s\S])*"/g, '""');
+      const quoteCount = (sanitizedOpener.match(/'/g) ?? []).length;
+      // Odd → opens a multi-line body. Even (incl. 0 / 2) → no
+      // unclosed open on this line (one-liner or no quote at all).
+      if (quoteCount % 2 === 1) {
+        inAwkBlock = true;
+        awkStartLine = i + 1; // 1-indexed for human-readable errors
+        // 0.36.0 codex round-4 P2 #1: when the body starts on the
+        // SAME line as the opener (`awk 'BEGIN { print "can't"`),
+        // any apostrophe-in-word shape already on that opener line
+        // MUST be checked too. Pre-fix the opener-detect branch
+        // flipped state and immediately `continue`d, leaving the
+        // opener line's body content unscanned.
+        //
+        // Locate the OPENING `'` (the LAST `'` in the sanitized
+        // line — `awk` is typically the last token before the
+        // opening quote, so any earlier `'`s are inside upstream
+        // shell commands like `printf '%s'`). Then run the
+        // apostrophe-in-word check on the text AFTER it (the awk
+        // body content). Word-boundary detection scopes the lint
+        // to the high-confidence bug shape (same discriminator as
+        // the body-line check above).
+        const openerIdx = sanitizedOpener.lastIndexOf("'");
+        const bodyOnOpenerLine = sanitizedOpener.slice(openerIdx + 1);
+        const apostropheInWord = /\b[A-Za-z][A-Za-z]*'[A-Za-z]/g;
+        const om = bodyOnOpenerLine.match(apostropheInWord);
+        if (om !== null) {
+          const strippedOpener = line.replace(/^\s+/, '');
+          const kind = strippedOpener.startsWith('#') ? 'comment' : 'code';
+          findings.push({
+            file,
+            line: i + 1,
+            content: line,
+            reason:
+              `awk-body ${kind} content on the OPENER line ` +
+              `contains an apostrophe-in-word shape (${om[0]}). ` +
+              `Bash terminates the \`awk '...'\` single-quoted ` +
+              `argument at the embedded \`'\`, splicing the rest ` +
+              `of the body into bash context; the hook parse-fails ` +
+              `at runtime (0.34.0 round-4 + round-6 class). ` +
+              `Rewrite without the apostrophe (e.g. \`cannot\` for ` +
+              `\`can't\`) or escape as \`'\\''\`.`,
+            awkStartLine,
+          });
+          // Bail out of block-mode — the bare `'` already
+          // terminated bash quoting at runtime.
+          inAwkBlock = false;
+          awkStartLine = -1;
+        }
+      }
+      continue;
+    }
+
+    // Inside awk block. Three things can happen on this line:
+    //   1. The line contains a BARE `'` somewhere (in code OR
+    //      comment) that isn't a close → finding.
+    //   2. The line is the canonical block close → leave the block.
+    //   3. Neither — keep walking.
+    //
+    // Bare-quote definition: a `'` that isn't part of a known-safe
+    // bash escape sequence for embedding a literal apostrophe inside
+    // a single-quoted string. The three benign forms are:
+    //   - `'\''`  (close-quote, backslash-escaped quote, reopen-quote)
+    //   - `'"'"'` (close-quote, double-quoted quote, reopen-quote)
+    //   - `''`    (close + reopen, injects NO byte — used in rea
+    //              hook comments to quote literal-byte sequences like
+    //              `\\\''` without breaking bash parsing).
+    // All three are fine in awk-internal context: bash terminates the
+    // single-quoted argument, emits a literal `'` (or no byte for
+    // `''`), and resumes single-quoting.
+    //
+    // 0.36.0 codex round-2 P2 #1 fix: pre-fix the bare-quote check
+    // only ran on comment lines (`stripped.startsWith('#')`). A code
+    // line like `BEGIN { print "can't" }` or `/can't/` parse-fails
+    // the same way — bash sees the `'` in `can't` regardless of
+    // whether awk parses the surrounding chars as a comment, string,
+    // or regex. Lint now scans every line in the block.
+    //
+    // Close detection: the rea hook bodies always close an `awk '`
+    // block with a `'` followed by a redirect / pipe / end-of-line
+    // / closing paren on a line that is OTHERWISE empty of awk-body
+    // text. Concretely: leading whitespace, then `'`, then optional
+    // `|`/`>`/`)`/whitespace/EOL. We detect close BEFORE running the
+    // bare-quote check on that line so a canonical-close line
+    // (`  '`) doesn't itself trip a finding.
+    const sanitized = line
+      .replace(/'"'"'/g, '')
+      .replace(/'\\''/g, '')
+      .replace(/''/g, '');
+
+    if (!sanitized.includes("'")) {
+      // No bare `'` after stripping benign forms — no close, no bug.
+      continue;
+    }
+
+    // Detect the 0.34.0 round-4 + round-6 bug class specifically:
+    // an apostrophe-in-word shape like `can't`, `isn't`, `doesn't`
+    // — a `'` flanked by ASCII word chars on at least one side.
+    // That's the exact shape that broke the marathon (it appears
+    // naturally in English prose and slips past code review). Other
+    // possible bare-`'` shapes (e.g. `'X` at line start, where X is
+    // ASCII content) are genuinely ambiguous from the lint's POV —
+    // they may be the canonical close `'` followed by a bash
+    // continuation, the close of a bash quoted string, etc. We
+    // deliberately scope the lint to the high-confidence,
+    // demonstrated-historical-bug shape rather than risk
+    // false-positives on bash-grammar surface area we cannot parse.
+    //
+    // 0.36.0 codex round-4 P2 #2 resolution: pre-fix tried to
+    // distinguish close from bug structurally (by what preceded or
+    // followed the `'`). Both attempts produced false-positives on
+    // valid close shapes (`' "$arg"`, `END { print x }'`,
+    // `' | tr ...`). Word-boundary detection is the simplest
+    // discriminator that catches the exact bug class without
+    // tripping on legitimate bash continuation.
+    const apostropheInWord = /\b[A-Za-z][A-Za-z]*'[A-Za-z]/g;
+    const m = sanitized.match(apostropheInWord);
+    if (m !== null) {
+      const strippedLine = line.replace(/^\s+/, '');
+      const kind = strippedLine.startsWith('#') ? 'comment' : 'code';
+      findings.push({
+        file,
+        line: i + 1,
+        content: line,
+        reason:
+          `awk-body ${kind} line contains an apostrophe-in-word ` +
+          `shape (${m[0]}). Bash terminates the \`awk '...'\` ` +
+          `single-quoted argument at the embedded \`'\`, splicing ` +
+          `the rest of the body into bash context; the hook ` +
+          `parse-fails at runtime (0.34.0 round-4 + round-6 class). ` +
+          `Rewrite without the apostrophe (e.g. \`cannot\` for ` +
+          `\`can't\`) or escape as \`'\\''\`.`,
+        awkStartLine,
+      });
+      // Bail out of block-mode — the bare `'` already terminated
+      // bash quoting at runtime, so further lines are bash-parsed,
+      // not awk-parsed.
+      inAwkBlock = false;
+      awkStartLine = -1;
+      continue;
+    }
+
+    // Any other `'` shape: assume it's a legitimate close `'`
+    // followed by bash continuation. Leave the block.
+    inAwkBlock = false;
+    awkStartLine = -1;
+  }
+
+  return findings;
+}
+
+const allFindings = [];
+for (const dir of SCAN_DIRS) {
+  for (const file of listShellFiles(dir)) {
+    allFindings.push(...scanFile(file));
+  }
+}
+
+if (allFindings.length === 0) {
+  // Quiet success — matches the posture of lint:regex.
+  process.exit(0);
+}
+
+console.error(
+  '[lint:awk-quotes] FAIL — bare single-quote in awk comment line ' +
+    '(0.34.0 round-4 + round-6 regression class):\n',
+);
+for (const f of allFindings) {
+  const rel = path.relative(repoRoot, f.file);
+  console.error(`  ${rel}:${f.line}  (awk block opened at line ${f.awkStartLine})`);
+  console.error(`    ${f.content.trim()}`);
+  console.error(`    → ${f.reason}\n`);
+}
+console.error(
+  `[lint:awk-quotes] ${allFindings.length} finding(s) across ${SCAN_DIRS.length} scan path(s).`,
+);
+process.exit(1);