ci: no gate covers shell portability — a GNU-only \b nearly shipped a fail-open security predicate

[kyle-sexton]

What is missing

No CI gate checks shell scripts for GNU-only constructs. This is a missing capability, not a defect in an existing gate.

To be explicit about what already exists and why neither covers this:

• portability-lint / ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source) #531 matches skill-coupling tokens (stack, forge, branch, tracker defaults) from scripts/skill-portability-tokens.txt against changed skill files. That is its job and it does it. It is not a shell-portability gate and was never meant to be.
• ci: no Windows runner anywhere — green checks carry no signal for platform-sensitive shell changes #1414 ("no Windows runner anywhere") is adjacent but different. A Windows runner would not catch this class either: Git Bash on Windows ships GNU grep, so a GNU-only construct passes there exactly as it passes on ubuntu-24.04. The exposure is BSD userland — macOS system grep/sed — which no runner in this repo covers.

The concrete near-miss that motivated this

While hardening plugins/markdown-format/hooks/markdown-format.sh on #1097, a predicate deciding whether a markdownlint config's module specifiers can be pinned to an approval was written with \b word boundaries:

grep -Eq '\brequire\b' "$file"

\b is a GNU extension. POSIX leaves \<ordinary char> undefined, and BSD grep may read \b as a literal b — turning \brequire\b into brequireb, which matches nothing. The predicate would then have returned "nothing unpinnable found" for every input.

That is a fail-open in a security predicate, on macOS, that no test on a GNU runner could ever catch. markdown-format.sh's own header explicitly commits to macOS system bash, so the platform is in declared scope.

The fix, now on main, is POSIX-portable and is the reference implementation for what a gate should accept:

• word starts/ends spelled as bracket expressions — (^|[^A-Za-z0-9_$])require($|[^A-Za-z0-9_$]) — instead of \b
• the residue test uses grep -q rather than grep -o, so no boundary character is consumed (which is what made a count-based approach undercount a nested require(require("x")))

Suggested shape

A changed-file-scoped lane over **/*.sh flagging GNU-only constructs. Non-exhaustive starter set, all of which differ or are undefined under BSD userland:

• ERE/BRE: \b, \<, \>, \s, \S, \w, \W, \+, \? in grep/sed patterns
• grep -P (PCRE — absent in BSD grep and in some GNU builds)
• sed -i without a backup suffix (BSD requires an argument)
• sed \|, \+, \? and GNU-only addresses
• readlink -f, date -d, stat -c, mktemp -p, head -c on some builds, sort -V
• echo -e

Two design notes from the near-miss:

1. The token list belongs outside the script, the way ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source) #531's does, so a re-catch is a one-line data change rather than a gate edit.
2. Direction matters. Flagging a GNU-ism that is actually safe costs a reviewer one line of justification; missing one in a security predicate costs a silent fail-open. The gate should over-flag and allow an inline opt-out with a stated reason, not under-flag.

An alternative or complement worth weighing: run the existing shell test suites once under a BSD-userland container so the behavioral difference surfaces as a test failure rather than a lint finding. That catches constructs no token list anticipated, at the cost of a slower lane.

Provenance

Found on #1097 by adversarially re-probing a predicate I had just written, not by any reviewer. It is the kind of defect that produces no symptom until it is exploited on the one platform CI does not cover.

[kyle-sexton]

This was generated by AI during triage.

Triage

Verification: CONFIRMED as a missing capability, not a currently-shipped defect.

The specific near-miss (a grep -Eq '\brequire\b' GNU-only \b word boundary in
plugins/markdown-format/hooks/markdown-format.sh) is already fixed on main — I grepped the
current file for \b-style boundary patterns and found none; the live predicate uses the
bracket-expression form the issue describes as the reference implementation
((^|[^A-Za-z0-9_$])(require($|[^A-Za-z0-9_$])|import[[:space:]]*\(), confirmed at
unpinnable_js_specifier()). So there is no live fail-open defect today.

The gap claim itself also checks out: .github/workflows/ci.yml runs shellcheck (twice) and a
portability-lint job, but I confirmed portability-lint (scripts/check-skill-portability.sh)
matches only the skill-coupling token list in scripts/skill-portability-tokens.txt against changed
skill files — it has no GNU-vs-BSD regex-construct vocabulary, and ShellCheck's own scope is shell
syntax/style, not portability of patterns handed to grep/sed as string arguments. Neither tool
would have caught the original \b construct. No other gate in the workflow targets shell
portability. Confirmed: this is a real, currently-missing CI capability.

Classification

• Type: Task
• Priority: medium — preventive/hygiene; the concrete instance that motivated this is already
  fixed, so there is no live exposure, but the failure mode (a fail-open security predicate on an
  uncovered platform) is high-severity when it recurs and no gate exists to catch a repeat.
• Work class: work-class: scoped — a new changed-file-scoped lint lane over **/*.sh, following
  the existing portability-lint job's external-token-list pattern.
• Routing: autonomous-eligible (agent-ready), decision-defaulted.
  Decision defaulted: implement the token-list-based lint lane (mirroring #531's
  portability-lint shape: token list lives in an external data file, gate over changed **/*.sh
  files, over-flag with an inline opt-out) rather than the BSD-userland-container test-run
  alternative — veto before merge if you'd rather run the shell suites under a BSD container
  instead (or in addition). The token-list approach is cheaper, matches an established precedent in
  this repo, and the issue's own "Two design notes" section (token list outside the script; over-flag
  rather than under-flag) already specify its shape completely — the only open question is the
  starter token list's exact membership, which is a reversible, low-stakes choice the implementer can
  make from the issue's own "non-exhaustive starter set." The container-based alternative remains a
  valid complement a maintainer can request afterward; it is not blocked by this default.

Agent Brief

Type: Task
Summary: Add a CI gate that flags GNU-only shell constructs in changed **/*.sh files, so a
BSD-userland-incompatible construct (macOS system grep/sed) is caught before merge instead of
failing silently on the one platform no CI runner here covers.

Current behavior: No gate in this repository's CI checks shell scripts for GNU-only regex/flag
constructs. shellcheck and portability-lint (skill-coupling tokens) both run today but neither
covers this class, and no runner in the workflow uses BSD userland (a Windows runner's Git Bash still
ships GNU grep/sed, so it would not help either).

Desired behavior: A changed-file-scoped CI lane over **/*.sh that flags GNU-only constructs
(word-boundary regex escapes, grep -P, sed -i without a backup-suffix argument, GNU-only sed
addresses, readlink -f, date -d, stat -c, mktemp -p, sort -V, echo -e, and similar), with
an external token/pattern list (not hardcoded in the gate script) and an inline opt-out mechanism for
a reviewed false positive. Direction over-flags rather than under-flags: a justified false positive
costs a reviewer one line; a missed true positive can ship a silent fail-open security predicate.

Key interfaces: a new gate script (data-driven from an external pattern/token list file, same
shape as scripts/skill-portability-tokens.txt for portability-lint), wired as a new CI job scoped
to changed .sh files.

Acceptance criteria:

• A CI job flags at least the starter construct set (GNU-only regex escapes in grep/sed
  patterns, grep -P, unsuffixed sed -i, GNU-only date/stat/readlink/mktemp/sort
  flag forms, echo -e) in changed shell files.
• The flagged-construct list lives in an external file, not inline in the gate script.
• A reviewed false positive can be silenced with an inline, stated-reason opt-out.
• The gate does not flag the already-fixed reference implementation in
  plugins/markdown-format/hooks/markdown-format.sh's unpinnable_js_specifier() (a known-good
  construct to self-test against).

Out of scope: running the existing shell test suites under an actual BSD-userland container (a
valid complementary approach the issue names as "worth weighing," left for a separate decision);
rewriting any currently-shipped shell script.

[kyle-sexton]