Skip to content

docs(audit): the bats rule carries the trap its own advice creates - #1140

Merged
stevensacks merged 3 commits into
mainfrom
spec-064-followups-2a-3
Aug 2, 2026
Merged

docs(audit): the bats rule carries the trap its own advice creates#1140
stevensacks merged 3 commits into
mainfrom
spec-064-followups-2a-3

Conversation

@stevensacks

Copy link
Copy Markdown
Contributor

Closes two of the three follow-ups left open when the machinery-waive widening merged. The third is declined; see below.

What changed

.claude/rules/bats-assertions.md — the !-negation section prescribes writing an absence check as <positive-condition-for-the-bad-case> && return 1 and stops there. As a test's final statement that form inverts its own result: an absent needle leaves grep's non-zero status as the AND-list's status, which becomes the test's return value, so the test fails in exactly the case it exists to pass. Three lines now state the trap and the fix (an explicit trailing true), lifting phrasing already audit-proven in .gaia/tests/lib/doc-machinery-waive-prose.bats's header rather than inventing new.

Placed in the version-independent !-negation section, not the bash-3.2 one: reproduced on bash 3.2.57 and 5.3.15, both fail. cmd && return 1 is an AND-list whose status is cmd's own, and set -e is ignored for a non-final member of an AND-OR list. The section that prescribes the form is where the trap belongs.

.gaia/scripts/check-audit-base-derivation.sh — one clause on _gaia_drop_full_base_matches's awk docstring. It described FULL_BASE as the self-skip base only; the exemption also covers the default member's waive-eligibility derivation, which the assertion-1 charter comment directly above it already states. The two comments now agree. Comment only, no behavior change.

Declined, recorded so it is not re-raised

The macOS BWK awk backslash-stripping gotcha (-v-assigned regex loses \( \)) is not added to any rule. It is awk portability in a per-suite copy-pasted helper rather than assertion hygiene; it produced no false pass, because extract_section_or_fail's vacuous-match guard caught it loudly; and it is already documented at the point it bites, in the header of the suite that hit it. A rule is the wrong altitude for something that fired once.

Verification

  • bash .gaia/tests/shell-lint.sh — passes (193 scripts, 181 suites, hook-array guard clean)
  • .gaia/scripts/tests/check-audit-base-derivation.bats under the bash 5 guard — 42/42, exit 0
  • Quality Gate — skipped, confirmed against wiki/decisions/Quality Gate.md: no staged file matches the source-extension or gate-affecting-config lists, and line 46 names .claude/** and pure-markdown commits explicitly.

No mutation testing: both edits are prose and a comment with no executable behavior.

.claude/rules/bats-assertions.md prescribes writing an absence check as
`<positive-condition-for-the-bad-case> && return 1`, and stops there. As a
test's final statement that form inverts its own result: an absent needle
leaves grep's non-zero status as the AND-list's status, which becomes the
test's return value, so the test fails in exactly the case it exists to
pass. The section that prescribes the form now states the trap and the
fix, an explicit trailing `true`, lifting the phrasing already proven in
.gaia/tests/lib/doc-machinery-waive-prose.bats's header.

Reproduced on bash 3.2.57 and 5.3.15, both fail, so it sits in the
version-independent `!`-negation section rather than the bash-3.2 one.

Also adds one clause to _gaia_drop_full_base_matches's awk docstring in
.gaia/scripts/check-audit-base-derivation.sh: FULL_BASE's exemption covers
the default member's waive-eligibility derivation as well as the self-skip
base, which the assertion-1 charter comment above it already states. The
two comments now agree. Comment only, no behavior change.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KqBHpzzuqf3aLMecia7mt
@github-actions

github-actions Bot commented Aug 2, 2026

Copy link
Copy Markdown
Contributor

code-review-audit skipped: no files in the frontend auditor's scope. GAIA-Audit is already green for this commit's tree, every dispatched member has cleared. No action needed

stevensacks and others added 2 commits August 2, 2026 12:13
.claude/rules/ is shipped surface, and the CHANGELOG gate treats a changed
rule as product-surface movement. The comment-only half of this branch is
not adopter-relevant and is not mentioned.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KqBHpzzuqf3aLMecia7mt
GAIA-Audit: 1.6.1 0c18e379f597f4d3c7d457fc9835673bb9a08cc497729c6ffa04b6b14577ddbd 5ed6e41
@stevensacks

Copy link
Copy Markdown
Contributor Author

@/var/folders/pn/m58c653j1js2r48m5n358ync0000gn/T/tmp.xt2FdCSRsS

@stevensacks
stevensacks enabled auto-merge (squash) August 2, 2026 03:21
@stevensacks
stevensacks merged commit a7c0878 into main Aug 2, 2026
12 checks passed
@stevensacks
stevensacks deleted the spec-064-followups-2a-3 branch August 2, 2026 03:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant