bash-format: docs/tests polish — out-of-project scope docs, opt-in/shfmt test coverage, setup Gotchas (F1, F2-local, F6)

[kyle-sexton]

Source

Handoff-inbox audit item 20260723-095036-bash-format-audit-docs-tests-polish (producer: SW2030).
Full consumer-side audit of bash-format@0.6.1; no behavioral defects found — this is docs/tests
polish only. Findings re-verified against current source in this repo before filing (see notes).

What to build

Four small, independent docs/tests improvements, all inside plugins/bash-format/, mergeable as one PR:

• F1 (docs). The shared hook::read_file_path membership guard silently skips shell files written
  outside CLAUDE_PROJECT_DIR (verified: lib/hook-utils.sh returns 1 for out-of-project paths,
  symlink-resolved). For an advisory linter this out-of-project no-op is undocumented. Add a scope
  caveat to README.md ("scope: files inside the current project only") and a scope note to the setup
  skill's check output so it doesn't report "fully operational" without the caveat.
  Note: the membership guard itself is already thoroughly tested centrally in
  lib/hook-utils.test.sh (Test 12: in-project accept, prefix-sibling reject, escaping-symlink reject,
  symlinked-root cases) — so F1's original "add a membership-guard test" sub-item is already
  satisfied; this slice is docs only.

• F2 (bash-format-local tests). Add bash-format.test.sh cases for the bash-format-specific paths
  that are currently unexercised:

  • shfmt < 3.8 --apply-ignore fallback branch (shfmt --apply-ignore -w … || shfmt -w …).
  • .editorconfig opt-in forms [*.{sh,bash}] (brace list) and [**/*.sh] (path-prefixed) — both
    implemented in section_applies_to_shell but only [*.sh], [*], [*.md] are tested today.
    (The shared-lib F2 gaps — buffer_stdin timeout and EPOCHREALTIME-absent degradation — are
    out of scope here; they are shared-lib behavior and are tracked in the sibling lib/fleet issue.)

• F3 — MOVED to hook-observability + hook-utils: refresh statusMessage adoption doc (30/31) + shared-lib tests for buffer_stdin timeout & EPOCHREALTIME degradation (F2-shared, F4) #1169 (not in scope here). Grounding during implementation refuted F3's
  "bash-format-local" premise: (dim-9 doctrine) is fleet vocabulary cited in 9 hook scripts with no
  shared glossary. Stripping it from bash-format alone would fragment the convention, so the fix is a
  shared-doc definition — implemented in hook-observability + hook-utils: refresh statusMessage adoption doc (30/31) + shared-lib tests for buffer_stdin timeout & EPOCHREALTIME degradation (F2-shared, F4) #1169, not here. Left in this list only as a pointer.

• F6 (skill hygiene, advisory). skills/setup/SKILL.md has no ## Gotchas section
  (skill-quality:check WARN). Add one capturing any real failure history (e.g. the ENAMETOOLONG
  spawn quirk when grepping the long plugin-cache path).

Acceptance criteria

• README.md documents the in-project-only scope of the hook.
• Setup skill check output surfaces the scope caveat (no unqualified "fully operational").
• bash-format.test.sh covers the shfmt<3.8 fallback and the [*.{sh,bash}] + [**/*.sh] opt-in forms; suite passes.
• skills/setup/SKILL.md has a ## Gotchas section.
• (F3 moved to hook-observability + hook-utils: refresh statusMessage adoption doc (30/31) + shared-lib tests for buffer_stdin timeout & EPOCHREALTIME degradation (F2-shared, F4) #1169 — no criterion here.)
• plugins/bash-format/.claude-plugin/plugin.json version bumped per repo convention; CHANGELOG updated.

Blocked by

None — can start immediately.

[kyle-sexton]

Scope correction (F3 moved to #1169). Grounding against source refuted F3's premise that dim-9 doctrine is bash-format-local: the label is a fleet-wide convention cited in 9 hook scripts (actionlint, bash-format, biome-format, desktop-notification, eol-normalizer, go-format, powershell-format, ruff-format, typos-format), part of a broader undefined dim-N dimension-numbering vocabulary (dim-8 conformance wave, dim-6/7 in babysit, etc.). Stripping the label from bash-format alone would fragment the convention (reuse-or-replace). The correct fix — define the numbering in shared vocabulary — belongs with the hook-observability owner doc, so F3 moves to #1169. This issue (#1168) now covers F1 docs, F2-local tests, F6 only.