ci: check-shell-portability.sh --all reports 68 pre-existing untriaged findings on main

[kyle-sexton]

This was generated by AI during work-loop execution.

Context

While working #1527 (migrating mktemp -p test-scaffolding call sites to a portable form and
activating that class in scripts/shell-portability-tokens.txt), the issue's own acceptance
criteria required scripts/check-shell-portability.sh --all to exit 0 against the full repo.

Running --all against origin/main before #1527's changes (verified in a separate, throwaway
detached worktree at origin/main HEAD, unrelated to #1527's branch) already exits 1 with 68
pre-existing PORTABILITY: findings — none of them mktemp. Running the identical scan on #1527's
branch produces the byte-for-byte identical finding set (diff of the sorted PORTABILITY: lines
is empty), proving the mktemp -p migration and its newly-active token contribute zero net findings
either way. These 68 are pre-existing corpus debt, orthogonal to #1527's scope.

Breakdown (68 findings, by token)

Token	Count
\<	18
\>	17
\w	8
\S	7
\s	7
\b	7
sed -i (unsuffixed)	2
\W	2

All are the regex-escape family (\b \< \> \s \S \w \W — ACTIVE since #1491/#1511, deliberately
bare/over-flag by design per shell-portability-tokens.txt's own header) plus two sed -i
unsuffixed sites in plugins/context-guard/scripts/context-zone.test.sh and
plugins/markdown-format/hooks/markdown-format.test.sh. Every hit is either a portable-but-flagged
non-regex use (printf/glob bracket expressions, PowerShell backslash paths in test fixtures, sed
scripts operating on the gate's own literal test data) or a genuinely GNU-only construct that has
simply never been triaged since #1491 shipped — CI only runs this gate in diff-mode on pull requests
(scripts/check-shell-portability.sh is diff-gated per #1491's PR description), so --all against
the full historical corpus has never actually been exercised end-to-end and reported clean.

Proposed work

For each of the 68 sites: either add a per-site portability-ok: <reason> annotation (the documented
escape for a reviewed false positive) or fix the two genuine sed -i non-portable sites to a
BSD-safe attached-suffix form. Re-run scripts/check-shell-portability.sh --all and confirm exit 0
once triaged.

References

• ci: migrate mktemp -p test-scaffolding call sites to a portable form #1527 — the item that surfaced this gap while satisfying its own mktemp -p scope; did not expand
  to cover it (orthogonal, ~68-site triage effort, not a mechanical one-line fix).
• ci: no gate covers shell portability — a GNU-only \b nearly shipped a fail-open security predicate #1491, feat(ci): add shell-portability-lint gate for GNU-only constructs #1511 — the gate and its ACTIVE regex-escape-family token, deliberately bare/over-flag by
  design.
• ci: harden shell-portability-lint detection precision (sed -i spellings, portability-scope precision, awk operand edge case) #1513, ci: shell-portability-lint detection precision, round 2 (escape-class scoping, line continuations, realpath control-flow guard, sed -i scope, sort long forms) #1517 — prior detection-precision hardening rounds on the SCANNER logic; neither covers this
  residual un-triaged CORPUS state.

[kyle-sexton]

This was generated by AI during triage.

Verification

Re-ran bash scripts/check-shell-portability.sh --all against current main (HEAD d5513ca1):
exactly 68 PORTABILITY: findings, confirming the issue's count exactly. Spot-checked the
breakdown against the issue's table:

• The two claimed sed -i (unsuffixed) sites are exact: plugins/context-guard/scripts/context-zone.test.sh
  and plugins/markdown-format/hooks/markdown-format.test.sh are the only two hits for that token.
• The regex-escape family (\b \< \> \s \S \w \W) accounts for the large majority of hits, and a
  large share of those are the same hook-utils.sh:1114 line duplicated once per plugin (each
  plugin vendors its own copy of hook-utils.sh), which matches the issue's framing that this is
  mostly the deliberately-bare/over-flagging escape-class token hitting legitimate non-regex uses
  (character-class literals, PowerShell backslash paths in test fixtures), not 68 independent bugs.

Claim verified: the count and breakdown are accurate.

Triage decision: work-class / scoping (human judgment call)

This is not a bounded fix. It is a mixed bag of ~66 likely false-positive sites needing case-by-case
portability-ok: <reason> review (is this really a non-portable regex construct or a flagged
non-regex string?) plus 2 genuine sed -i portability bugs — and the right way to slice that review
work (one item, category-batched items, or a tracked backlog list) is itself a judgment call with
real tradeoffs (parallelizability vs. review overhead vs. tracking granularity). That's a scoping
decision, not something to default silently.

Routing this human-gated rather than decision-defaulting a slicing strategy — deciding how to
break this down is open design space, not a single reversible fork.

Agent Brief (for the human-gated decision)

Type: Task
Summary: check-shell-portability.sh --all has never been run to green against the full
historical corpus (CI only ever ran it in diff-mode); running it now surfaces 68 pre-existing
findings that need triage and a decision on how to structure that triage as workable, reviewable
units of work.

Current behavior: The gate is diff-gated in CI, so historical corpus debt was never surfaced.
--all now reports 68 findings against main, none blocking any current PR.

Desired behavior: A maintainer decides the slicing strategy (single cleanup item vs. batched
items by token/category vs. a tracked backlog list), and the resulting item(s) get worked until
check-shell-portability.sh --all exits 0 against main.

Key interfaces:

• scripts/check-shell-portability.sh — the --all corpus-wide scan mode
• portability-ok: <reason> — the documented per-site escape/annotation mechanism for reviewed
  false positives
• scripts/shell-portability-tokens.txt — the active token list (regex-escape family is
  deliberately bare/over-flagging by design)

Acceptance criteria:

• A maintainer picks a slicing strategy for the 68 findings
• Follow-up item(s) are filed/updated per that decision
• scripts/check-shell-portability.sh --all exits 0 against main once the resulting work lands

Out of scope:

• Changing the token list's detection precision (that's ci: harden shell-portability-lint detection precision (sed -i spellings, portability-scope precision, awk operand edge case) #1513/ci: shell-portability-lint detection precision, round 2 (escape-class scoping, line continuations, realpath control-flow guard, sed -i scope, sort long forms) #1517/fix(ci): shell-portability-lint's sort -V token misses operator-terminated forms #1537, separate scanner-logic
  work)
• Re-litigating whether the regex-escape family should be bare/over-flagging (that's an intentional
  design choice per shell-portability-tokens.txt's own header)

[kyle-sexton]

Frontier disposition (drain session)

Ruling: Close as completed.

Inventory captured — 68 pre-existing shell-portability findings on main are known untriaged debt, not an open discovery task.

Re-open trigger: When the portability lint lane (#531) staffs systematic triage of the inventory.