feat(cc-249): PR-B.1 — add 4 unified assert_* helpers to test-harness

[screenleon]

Summary

PR-B.1 of the CC-249 sequence — pure additive harness changes per spike (docs/spikes/CC-249.md from PR #146). Adds 4 unified assert_* helpers + shared fail-message formatter to scripts/lib/test-harness.sh. Zero consumer changes; PR-B.2 (14-file consumer migration) follows separately.

Helpers added (per spike Q1/Q2)

Helper	Signature	Behavior
assert_exit	<name> <actual> <expected>	Exit-code equality (majority arg order; value-under-test first)
assert_file_contains	<name> <file> <literal_substring>	grep -Fq for literal string in file
assert_file_matches	<name> <file> <regex>	grep -qE for regex pattern in file
assert_string_contains	<name> <haystack_string> <needle>	bash [[ haystack != *needle* ]] containment

Plus _th_assert_fail_msg — shared fail-path formatter each helper calls; message contains helper-name + relevant args + failed condition (debuggable from output alone, no need to re-read helper source).

All 4 helpers call existing harness pass / fail fns on success/failure → FORMAT-aware output preserved + counter increments go through the standard path. No direct printf bypass.

What's NOT in this PR (deferred to PR-B.2)

• Consumer migrations (14 scripts/test-*.sh files keep their local assert_* definitions for now)
• assert_output_contains deletion (lives in 2 consumers; deleted in PR-B.2)

Test coverage

8 new self-test cases in scripts/test-test-harness.sh (1 pass-path + 1 fail-path per helper):

• assert-exit-{pass,fail}
• assert-file-contains-{pass,fail}
• assert-file-matches-{pass,fail}
• assert-string-contains-{pass,fail}

Each case invokes the new helper in a probe subshell (per file's existing run_harness_probe pattern — outer test uses local pass_case/fail_case, not the harness's own pass/fail, to avoid polluting the harness's counters during a self-test).

Fail-path cases assert: (a) helper's fail was called in the probe (FAIL line + counter increment); (b) the captured probe stderr/stdout contains the helper name AND the failing args (debuggability check).

Test plan

• bash scripts/test-test-harness.sh — 30/30 (was 22; +8 new)
• bash scripts/test-run-all-tests.sh — 13/13 integration
• bash pm/scripts/validate.sh BACKLOG.md — parity 30 (CC-228 baseline)
• git diff scripts/lib/test-harness.sh — only additions after th_summary close; no deletions; existing th_init/pass/fail/should_run/th_summary byte-identical
• /pr-gate standard — Final: GO, critic + qa-tester + architecture-reviewer all approve, zero findings
• shellcheck --severity=style on test-harness.sh + test-test-harness.sh — not installed locally; CI will run

Brief discipline applied (per [[feedback_codex_brief_discipline]] CC-251)

• expected_head_sha: 03555fe verified by codex before first edit ✓
• apply_patch retry-cap constraint included (no debug-loop hang) ✓
• verbatim-as-attached-file N/A (< 50 lines literal embedded)

PR-B.2 brief will trigger ALL 3 patterns (14 files > 4-files trigger; per-file migration matrix > 50 lines → attached as /tmp/cc-249-migration/<file>.md).

Next (PR-B.2, after this merges)

Consumer migration in lockstep — replace each consumer's local assert_* defs with calls to the now-installed harness helpers, delete the local defs, validate stdout byte-identity per consumer. Estimated 14 files × 5–15 LoC delta each, net –50 to –150 LoC.

🤖 Generated with Claude Code