fix(cc-254): harness assert_* no auto-pass + 3 process artifacts from PR-B.2 retro

[screenleon]

Summary

Two things in one PR, both rooted in the CC-249 PR-B.2 dispatch incident (2026-05-24):

1. Fix (CC-254) — amend PR-B.1 (feat(cc-249): PR-B.1 — add 4 unified assert_* helpers to test-harness #148): remove auto-pass from the 4 harness assert_* helpers + update self-tests + document the new contract
2. Process artifacts — capture the lesson so future spikes / additive PRs / Explore surveys don't repeat the gap

What broke (and why)

PR-B.1 helpers auto-called pass "$name" on success. PR-B.2 dispatch surfaced a hidden contract: all 13 consumer test scripts already follow assert_X "$name" ...; pass "$name" (assert is check; consumer calls pass). Pure rename would have double-counted PASS. Codex defensively shadowed the harness by re-defining 4 helpers in each of 9/13 consumer files — explicitly violating spike Q3 "no shim". Dispatch hit timeout 124 with 9 apply_patch failures in 4 complex files.

Root cause = PR-B.1 helper API, not codex's behavior or PR-B.2's brief. Spike never inspected consumer call-sites, only declarations.

Fix (CC-254)

scripts/lib/test-harness.sh:

• Strip pass "$name" from each of the 4 helpers (assert_exit, assert_file_contains, assert_file_matches, assert_string_contains)
• Add header comment documenting the new contract: success returns 0 silently; consumer is responsible for && pass "$name" if PASS accounting is desired
• Helpers still call fail on failure (unchanged)

scripts/test-test-harness.sh:

• 4 pass-path self-tests amended: explicit && pass '<name>' after each assert
• 4 fail-path self-tests unaffected
• 30/30 passes (no regression)

After this lands, PR-B.2 reverts to pure rename — each assert_contains "$n" $f "$x" → assert_file_contains "$n" $f "$x"; existing pass "$n" stays untouched. No double-count, no shim.

Process artifacts

Artifact	Where
Memory [[feedback_spike_pilot_required]]	~/.claude/projects/.../memory/ (separate repo, already committed)
Memory [[feedback_explore_call_site_context]]	same
3 new brief-authoring rules in agents/project-pm.md	this PR
Amendment section in docs/spikes/CC-249.md Open Risks	this PR

The 3 brief-authoring rules added to agents/project-pm.md:

1. Spike-pilot rule: every API-design spike MUST include ## Pilot walkthrough (1 representative consumer, verbatim before/after diff). If walkthrough can't be written cleanly → spike not yet mature.
2. Additive-PR pilot rule: every PR shipping new API MUST migrate ≥ 1 real consumer in the SAME PR.
3. Explore call-site-context rule: Explore symbol surveys must capture BOTH declarations AND call-sites with 2-line context.

Verification

• bash scripts/test-test-harness.sh — 30/30 (no regression after auto-pass removal + self-test amend)
• bash scripts/test-run-all-tests.sh — 13/13 integration
• bash pm/scripts/validate.sh BACKLOG.md — parity 30 (CC-228 baseline)
• /pr-gate express — Final: GO, critic + qa-tester both [pass], zero findings

Out of scope

• PR-B.2 re-dispatch — separate work after this merges (pure rename now possible)
• CC-244 typed spike_v1 schema adding pilot_walkthrough: field — long-term automation; ticket exists
• Tail commit flips CC-254 row pr:TBD → pr:#<this> after gh pr create

🤖 Generated with Claude Code