Epic: stop shipping spec-compliance theater — the user-facing state/copy layer is implemented in name only

[bepcyc]

What this is

A tester run (sandbox, end-to-end, real LLM coach) surfaced a cluster of defects — #115, #116, #117, #118, #119, #120. The core engine is solid: ingestion, analytics (TSS/PMC), and grounded coaching all compute correctly and honestly — the tester found zero numeric/correctness bugs there. The rot is concentrated in ONE layer: the last mile to the user — state reporting, the async/sync contract, user-facing copy, and onboarding.

Why this is an epic, not six tickets

Several of these are direct spec/ violations (API-R46, QUAL-R13), and that is the tell: the spec was treated as a SHAPE to satisfy, not a BEHAVIOR to deliver. Concretely:

• ImportJob.status: "queued|processing|done|failed" exists as a type, but done/failed are unreachable in the code (Import job status is stuck at "queued" forever — done/failed never reached #115) — the status machine was never wired, even though API-R46 depends on done → recent_ready → complete. The type "implements the spec"; the behavior does not.
• The import is synchronous but wrapped in an async 202 queued job contract — the contract lies about the shape of the work (root of Import job status is stuck at "queued" forever — done/failed never reached #115).
• QUAL-R13 explicitly bans blame/misleading copy, yet /v1/sync/run says "we're pulling in your training" with zero connections (POST /v1/sync/run returns a falsely-reassuring 202 when there are no connections; no way to see it did nothing #118) and the intervals 422 blames a valid key (intervals.icu connect 422 message blames the user's key instead of saying the connector is inert in OSS #119).
• Undocumented dependencies and missing onboarding guidance (New self-hoster sees an all-zero fitness chart: FTP prerequisite is never surfaced #116 FTP, Setting the FTP/fitness signature reads as a silent no-op (PUT 200 returns null; depends on current_sport) #117 current_sport).

The uncomfortable part: all of this passed review and a green test suite. So the review nodded "looks ok" without checking the actual spec'd behavior, and/or the tests asserted something OTHER than the contract — the same vacuous-test disease #93 already had to clean up in another layer. We can NOT keep pretending a surface is spec-compliant because the types match, the PR was approved, and tests are green, when the behavior the spec and the user rely on simply is not there. Так не пойдёт.

Members

spec/ violations:

• Import job status is stuck at "queued" forever — done/failed never reached #115 — import status never reaches done/failed (API-R46 / API-R33)
• POST /v1/sync/run returns a falsely-reassuring 202 when there are no connections; no way to see it did nothing #118 — sync/run misleading status copy with no connections (QUAL-R13)
• intervals.icu connect 422 message blames the user's key instead of saying the connector is inert in OSS #119 — intervals 422 blames the user's valid key (QUAL-R13 d/e)

Same-layer roughness:

• New self-hoster sees an all-zero fitness chart: FTP prerequisite is never surfaced #116 — FTP prerequisite never surfaced → all-zero chart (onboarding/docs)
• Setting the FTP/fitness signature reads as a silent no-op (PUT 200 returns null; depends on current_sport) #117 — signature write reads as a no-op (undocumented current_sport dependency)
• Minor: activity flag/data inconsistencies + coach formats negative form as "--4.8" #120 — flag/data inconsistencies + coach --4.8 formatting

Definition of done (the bar this epic sets — for each member AND as policy for this layer)

1. The fix delivers the spec'd BEHAVIOR end-to-end, not just the type / happy path. (e.g. upload → ImportJob.status actually reaches done → GET /v1/onboarding/status actually reaches complete.)
2. A test that asserts the real spec contract, not a vacuous proxy — the assertion MUST be coupled to the behavior the spec/user depends on (cf. the impossible-fixture-state / Test-suite audit: useless / false-confidence tests (4 HIGH incl GDPR-erasure tests that never call production erase_athlete) #93 audit lesson: a fake that returns an unreachable state, or a test that never exercises done/the honest copy, is NOT coverage).
3. Independent review confirms spec ⇄ code correspondence BOTH ways — the reviewer verifies the actual behavior against the requirement IDs, not "вроде ок".
4. spec/ extended/clarified in the SAME PR wherever the contract was ambiguous enough to let shape-without-behavior through.

This is the same root cause the project already paid for once (#93). Let us not re-pay it by shipping shape without behavior.