ci: bulletproof test gates + binding test-quality contract for the port

[LukasParke]

Why

This repo is a living port — every sync is a machine-generated diff to load-bearing concurrent code (tool loop, streaming fan-out, approval/HITL ordering, hooks). The only thing between a subtly-wrong port and main is what CI and the two gates actually check. They weren't checking enough.

I probed the tree rather than reading it. The first probe found a real bug:

Probe	Before
go test ./...	passes, 65.9% coverage
go test -race ./...	FAILED — data race in TestHooksManagerAsyncDrain
Deterministic tests driving a successful stream	zero (1 streaming fake, error-only; 26 non-streaming)
retryCurrentRequest — runs on the last turn of every tool conversation	0%; StrictFinalResponse had zero test references
FinishReasonIs — contract-Required API	0% — exported, so the presence check passed
stream_guards.go, tool_event_broadcaster.go, +2	zero callers anywhere

The race is the headline. It's in test code, but that's luck, not process: CI had never run -race on a package whose headline feature is concurrent stream fan-out and whose hooks manager is documented as concurrency-safe. Upstream ships a dedicated turn-end-race-condition.test.ts; this port had no counterpart and no gate.

FinishReasonIs is the second: listed in the contract's parity floor, exported, and never called by any test. A presence check structurally cannot see that. It's the exact failure mode PORTING.md says the gates exist to prevent — "a port which compiles cleanly while sitting a version behind on real behavior."

What changed

Gates — -race (blocking), -shuffle, -count=1 (the cache was reporting (cached)), pinned staticcheck, a dependency-free goroutine-leak TestMain, and two coverage gates shared between CI and the port verifier:

• Ratchet — coverage can't fall below .upstreamer/coverage-floor.txt; a real gain must be locked in by raising it. Measured deterministic across three runs, so it won't flake. Floor at 72.0 vs 72.2 actual, leaving headroom.
• Per-symbol — every contract-Required symbol must be exercised, not just exported. This is the hole that hid FinishReasonIs.

Tests — 65.9% → 72.2%. consumeCreateResponse 42% → 88%, ReasoningStream 0% → 100%. All Required-API symbols now covered. The unlock was a fake EventStream that emits real SSE frames decoded by the SDK's own decoder; three SDK details each produce a fake that looks fine and silently carries no events, which is why TestSanityFakeStreamDecodesThroughSDK guards the fake itself.

Contract — a binding Test Quality section in upstreamer.md, upstream-test-parity criteria in eval.md (an untested changed behavior is now a FAIL), and a new porting-tests skill. Per PORTING.md's own rule, fixing the contract rather than only the code is what stops this re-rotting next sync.

Judgment calls worth reviewing

• Every gate was proven to fail. Reverting the mutex reproduces the race; disabling the FinishReasonIs tests makes Gate B name that exact symbol; a 40-goroutine probe trips the leak check; floors of 99 and 50 both fail Gate A. Mutating Drain and the retry branch makes those tests fail. A gate I hadn't watched fail would be decoration.
• I reverted one of my own changes. I had wrapped the completed-event check in IsResponseCompletedEvent(data) && …. That narrows behavior rather than deduplicating — any event with the pointer set but Type unset would turn a working run into "stream ended without response.completed". Not worth the risk.
• I did not wire in ExecuteToolLoop. It looks like the tool loop but passes a zero TurnContext and nil emitter, silently dropping hooks, approval gating, and generator streaming. Wiring it in would be a regression; testing it would legitimize a footgun.
• verify-port stays advisory. Its required-API check fails by design until the port catches up to upstream. Making that red on every PR teaches people to ignore CI.

User-visible change

The wrapped Stop-hook error is now stop hook: … (was Stop hook: …, flagged ST1005). Noted in the changelog — code matching on that text rather than errors.Is/errors.As needs updating. Also fixed a real nil-deref in an existing test that staticcheck caught.

Follow-ups (deliberately not here)

• tool_orchestrator.go and next_turn_params.go are still uncalled. Deleting them touches the port's API surface, so it needs a contract amendment rather than being smuggled into a CI PR.
• stream_transformers.go's three Extract*Deltas remain unused; I didn't manufacture call sites for them.
• Upstream has whole test files with no Go counterpart — the six *-adversarial suites, schema-sanitization, shared-context, tool-context, turn-end-race-condition. They map onto this repo's lowest-coverage files, so they're the best guide for what to cover next.

Verification

gofmt -l .                                  # clean
go test -race -shuffle=on -count=1 ./...    # ok
staticcheck ./...                           # clean
.upstreamer/scripts/verify.sh               # PASS: 0 failures
env -u OPENROUTER_API_KEY go test -run TestE2E -v .   # 5 SKIP, not fail

All six commits build and pass independently (git bisect-safe): the race fix lands before the gate that would catch it, and the streaming tests land before the loop refactor they protect.

🤖 Generated with Claude Code