# Plan — make test green on macOS: portable shell idioms (tests + prod) — r3

Date: 2026-10-06 · Branch: bugfix/macos-portability · Kind: build-plan (bugfix)
r2 after the three-lens challenge (correctness FATAL(6), robustness
CONCERNS(4), simplicity FATAL(2)); every BLOCKER/MAJOR closed by a named
change below, see § Challenge log.

## Bug
`make test` red on develop: 13 suites, ~45 FAIL lines. Suite and libs were
written and validated on Linux (GNU userland); this machine is macOS (BSD
userland, bash 5.3 from Homebrew, `timeout`/`gdate` only via
/opt/homebrew/bin, NO gnu-sed). Per-suite FAIL → cause map:

| Suite | FAIL | Cause |
|---|---|---|
| lib/gitflow-test.sh | 15 "merged into…" | early-exit consumer under pipefail (A) |
| lib/tests/run-release-candidate.sh | CHANGELOG not finalized | `sed -i` no suffix (B) |
| floor-guard, profile-census, profile-default .test.sh | 1+2+1 | `sed -i` no suffix (B) |
| effort-pins (3), source-scope (2), fast-libs H2-H4 (3) | string-compare of `wc -l` | BSD wc pads (C) |
| lib/seo-data/seo-data.test.sh | 3 perms + 1 stdlib | `stat -c` (D), `/bin/grep` (E) |
| fast-libs T7-stale | 1 | `touch -d` (F) |
| gstack-links T4 | 3 | `realpath -m` absent → guard never fires (G, prod) |
| design-tool-gate | 5 | bare `timeout` off the sanitized PATH (H, prod) |
| doctrine-citers T3 | 1 | extractor false positive + regex-interpolated resolver (I) |
| effort-routing | 2 | pins dropped from 2 gitignored SKILL.md on 2026-10-05 (J, machine state) |

Not red but same class, found by the challenge: lib/doc-shape.sh:70 (git
producer `| grep -Eq` under pipefail, fails OPEN: structural doc change
classed MINOR), update-all.sh:607 (`grep -oP`, BSD grep rc 2, `|| true`
silently empties `_plugins` → marketplace plugins never update on macOS).

## Root cause classes and their portable form
- (A) **Early-exit consumer under `set -o pipefail`**: `grep -q`, `head -1`,
  awk `{print; exit}` exit before the producer finished → producer gets
  SIGPIPE → rc 141 → pipeline false. Reproduced 5/5 on `git log | grep -q`.
  NOT fixed by `grep PAT >/dev/null` (GNU grep treats stdout=/dev/null like
  `-q`, challenger-verified in grep's main()). Portable form: take the
  producer OUT of the pipeline — tests: `grep -q PAT < <(cmd)`; prod:
  `out="$(cmd)"` then grep/awk/head the variable (here-string). Only sites
  whose producer is an external command under pipefail. `printf '%s' "$v" |
  grep -q` is safe (builtin writes once; 50/50 probe) and is left alone.
- (B) `sed -i 'x' f` → tests (temp dirs): `sed -i.bak 'x' f && rm -f f.bak`.
  Prod on a user dotfile: unique sibling `t=$(mktemp "$f.XXXXXX")`, `sed 'x'
  "$f" >"$t" && cat "$t" >"$f"`, `rm -f "$t"`, explicit failure branch (never
  `-i.bak`: it would overwrite and then delete a hand-made ~/.zshrc.bak, and a
  failing sed in a non-final `&&` escapes errexit).
- (C) `$(… | wc -l)` → append `| tr -d ' '` (idiom of hooks/unpushed-guard.sh:41).
- (D) `stat -c '%a'` → `python3 -I -c 'import os,stat,sys; print(oct(stat.S_IMODE(os.stat(sys.argv[1]).st_mode))[2:])' F`.
- (E) `/bin/grep` → `/usr/bin/grep` (LRN-074 pin, 6 files already).
- (F) `touch -d '10 days ago' F` → `touch -t 200001010000 F` (POSIX; cache_status only tests `-mtime -N`).
- (G) `realpath -m` → emulate: walk up to the nearest EXISTING ancestor, `cd` + `pwd -P`, append the unresolved remainder.
- (H) bare `timeout 15` → `perl -e 'alarm shift; exec @ARGV' 15 …` (perl ships in /usr/bin on both OS; keeps the 15 s bound everywhere, comment stays true).
- (I) citation name must start with a non-blank; resolver matches FIXED strings (awk `index()` on heading / bold lines), never interpolates the name into `-E`.

## Decided (user, 2026-10-06)
- Scope: tests AND prod sites. Doctrine: POSIX/BSD-portable scripts on the
  native userland of both OS. Rejected: Homebrew GNU tools on PATH.

## Fix plan (exact sites)
1. lib/gitflow-test.sh — the 26 assertions whose producer is an external
   command (git, bash …) `cmd | grep -q[xF|i] PAT` → `grep -q[xF|i] PAT <
   <(cmd)` (A); the 11 `printf '%s' "$v" | grep -q` sites stay. Same form at
   lib/tests/gstack-playwright.test.sh:126-127 (negative destructive-command
   guard, fails OPEN on SIGPIPE), lib/tests/run-doc-commit.sh:104 (git
   status), lib/tests/run-release-candidate.sh:55 (git show).
2. lib/profile.sh:269-274 and lib/design-tool-gate.sh:163-165 — capture
   `claude plugin list` into a variable, then awk+grep on it (kills both the
   awk `exit` and the grep -q race). lib/profile.sh:285,374,444,
   lib/design-tool-gate.sh:170, lib/toggle-external.sh:142,
   install-plugins.sh:474 — the call STAYS inside the condition:
   `if grep -q[iE] PAT <<<"$(cmd 2>&1)"; then` (A). Never a bare
   `out="$(cmd)"`: profile.sh:374/444 (enable_skill/disable_skill),
   install-plugins.sh:474 (install_plugin) and toggle-external.sh:142
   (pack_hints) run bare under `set -euo pipefail`, a bare capture of a
   failing CLI would abort `profile.sh set` / `make plugin` (confirmation
   pass, bash 5.3 probe). lib/tests/profile-set-managed.test.sh — add a
   fake-claude case returning rc≠0 on `plugin enable` so the regression is
   caught.
3. lib/design-tool-gate.sh:125 — `line="$(perl -e 'alarm shift; exec @ARGV' 15 21st whoami 2>/dev/null </dev/null)"`, first line via `${line%%$'\n'*}` (H + A). install-plugins.sh:1143 `TFD_WHO=$(21st whoami … | head -1)` — same capture-then-first-line (A, errexit-safe).
4. lib/design-tool-gate.sh `ensure_21st_on_path` / `ensure_claude_on_path` — add `/opt/homebrew/bin/<bin>` to the candidate list (Apple-Silicon npm global prefix, `npm prefix -g` = /opt/homebrew here). SAME change: lib/tests/design-tool-gate.test.sh:20-21 hermeticity precondition gains `|| [ -e /opt/homebrew/bin/21st ]` so CLI_ABSENT_10 skips loudly instead of reaching a real CLI.
5. lib/doc-shape.sh:70 — `grep -Eq … < <(git diff HEAD -- "$p")` (A).
6. update-all.sh:607 — `grep -oP '(?<=❯ )\S+'` → `sed -n 's/.*❯ \([^[:space:]][^[:space:]]*\).*/\1/p'` (non-empty token, so a line ending in "❯ " never yields `claude plugin update ""`; one token per line, as `claude plugin list` prints one plugin per line).
7. install-plugins.sh:1201,1204 — sibling-temp form (B). Delete :1207-1208
   (`{ N; /^\n$/d; }`): dead on GNU (pattern space never `^\n$`), and BSD `N`
   at EOF would DROP the marker comment; deletion = GNU behaviour preserved.
8. lib/tests/run-release-candidate.sh:43, floor-guard.test.sh, profile-census.test.sh, profile-default.test.sh — `-i.bak` + rm (B); BSD sed expands `\n` in the replacement, no rewrite.
9. lib/tests/effort-pins.test.sh:41,99,109; source-scope.test.sh:48,49,66; fast-libs.test.sh:46,47,50 — `| tr -d ' '` (C).
10. lib/seo-data/seo-data.test.sh:26,28,480 (D); :139 (E).
11. lib/tests/fast-libs.test.sh:39 (F).
12. lib/gstack-links.sh:64 — `_gstack_links_realpath_m <path>` helper (G):
    refuse (rc 1, warn) any path holding a `..` component; walk up with
    `[ -d ]` to the nearest existing directory; `CDPATH= cd -P -- "$dir" &&
    pwd -P`; append the unresolved remainder. Line 63 unchanged (plain
    `realpath` is native on both). lib/tests/gstack-links.test.sh — add T4b:
    dst=`$SRC/missing/x` (parent absent) must be refused, nothing created.
13. lib/tests/doctrine-citers.test.sh:19 extractor `["“][^"”[:space:]][^"”]{1,59}["”]`; :27-28 resolver → awk, fixed strings (I): a heading line resolves when the text right after `#+ ` STARTS with the name and the next char is one of ` ` `:` `(` `—` or end of line; a `**name` substring anywhere on a line still resolves (bullet labels like `- **Secrets**`). Flip fixture gains a case: doctrine heading "Alphabet", citation "Alpha" → must stay DANGLING.
14. Machine state (no commit): `bash lib/effort-pins.sh` re-pins the two skills (J).
15. Regression guard `lib/tests/portability-census.test.sh` — DETERMINISTIC
    idioms only, over a file list given as args (default: tracked `*.sh` +
    `hooks/*`), comment lines skipped, exit 2 on hit:
    `sed -i ['"]` (no suffix) · `stat -c` · `realpath -m` · `touch -d` ·
    `grep -[A-Za-z]*P` · `(^|[^a-z])/bin/grep`.
    Allowlist with reasons, file:line: lib/tests/guard-bash.test.sh:221,225
    (deny fixtures must keep the GNU spelling an agent types), and the census
    file itself. Flip test: plant `sed -i 's/a/b/' x` in a mktemp dir and pass
    that file as the arg → must red. NO `| grep -q` rule (not deterministic
    by text; the real fix is structural). Makefile untouched (glob already
    picks `lib/tests/*.test.sh`).
16. TODO.md: known re-red trigger — update-all.sh applies pins only at :572
    after every vendoring step; an abort upstream drops them again. Follow-up:
    pin right after each vendoring step or flag in doctor.

Untouched on purpose: hooks/rtk-rewrite.sh:115 (not under pipefail,
sha256-pinned hook); doctor.sh:405,564 (printf/one-line producers, cannot
SIGPIPE; doctor not in the suite); other `printf | grep -q` sites.

## Acceptance
- `make test` exits 0 on this macOS machine; no SKIP added, no suite removed.
- New: gstack-links T4b green; portability census green on the tree and red
  on the planted fixture.
- Linux: NOT verifiable from this machine. Every replacement is chosen to be
  semantically identical under GNU tools (producer capture, `-i.bak`, tr,
  python3, perl alarm, sed -n). `[deferred 2026-10-06]` a Linux `make test`
  run before the next release is the human's call.

## Out of scope
- Why the 2026-10-05 fetch dropped the two pins (not reproduced; TODO entry).
- lib/tests/effort-routing.test.sh reading live gitignored files (it is the drift detector).
- doctor.sh `readlink -f` (separate pass).

## Challenge log (r1 → r2)
- BLOCKER (correctness 1, simplicity 1, robustness 4): census red by
  construction → §15 narrowed to deterministic idioms, file-list arg,
  allowlist, self-exclusion, no `grep -q` rule.
- MAJOR (correctness 2): `>/dev/null` is not a fix under GNU grep → class (A)
  form = producer out of the pipeline.
- MAJOR (correctness 3, robustness 3): upstream awk `exit` / `head -1` → §2, §3 capture first.
- MAJOR (correctness 4, robustness 3): missed same-class prod sites → §5 doc-shape, §6 update-all.
- MAJOR (correctness 5, robustness 1): `-i.bak` on dotfiles → sibling temp, explicit failure.
- MAJOR (correctness 6, robustness 2): gstack-links fallback false → §12 ancestor walk + T4b.
- MINOR accepted: `/usr/bin/grep` (LRN-074), `touch -t`, dead :1208 deleted,
  Makefile untouched, perl alarm bound, /opt/homebrew/bin candidates,
  fixed-string resolver, TODO re-red trigger.
- MINOR declined: none.
- Confirmation pass (correctness CONCERNS(2), r3): MAJOR errexit on bare
  capture → §2 keeps the call inside the condition + rc≠0 fake-claude case;
  MAJOR hermeticity → §4 precondition; MINOR 4 unlisted class-(A) test sites
  → §1; resolver semantics + Alphabet/Alpha flip → §13; `..`/CDPATH/-P →
  §12; non-empty token → §6.