xtablo-source/.planning/phases/06-background-worker/06-VALIDATION.md

phase	slug	status	nyquist_compliant	wave_0_complete	created
6	background-worker	draft	true	true	2026-05-15

Phase 6 — Validation Strategy

Per-phase validation contract for feedback sampling during execution.

---

Test Infrastructure

Property	Value
Framework	go test
Config file	backend/go.mod
Quick run command	cd backend && go build ./cmd/worker/...
Full suite command	cd backend && go test ./... && go build ./...
Estimated runtime	~10 seconds

---

Sampling Rate

• After every task commit: Run cd backend && go build ./cmd/worker/...
• After every plan wave: Run cd backend && go test ./... && go build ./...
• Before /gsd-verify-work: Full suite must be green
• Max feedback latency: 15 seconds

---

Per-Task Verification Map

Task ID	Plan	Wave	Requirement	Threat Ref	Secure Behavior	Test Type	Automated Command	File Exists	Status
06-01-01	06-01	1	WORK-01	—	N/A	build	cd backend && grep -c "riverqueue/river" go.mod && go build ./...	✅	⬜ pending
06-01-02	06-01	1	WORK-02	—	N/A	unit	cd backend && go build ./internal/jobs/... && go test ./internal/jobs/... -v -count=1	❌ W0	⬜ pending
06-02-01	06-02	2	WORK-01, WORK-02, WORK-03	—	N/A	build	cd backend && go build ./cmd/worker/...	✅	⬜ pending
06-02-02	06-02	2	WORK-01, WORK-04	—	N/A	build	cd backend && grep -c "^worker:" justfile && grep -c "just worker" README.md	✅	⬜ pending
06-03-01	06-03	3	WORK-02, WORK-03, WORK-04	—	N/A	manual	Run just worker, observe 2+ heartbeat log lines ~60s apart, verify graceful shutdown	—	⬜ pending

Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky

---

Wave 0 Requirements

• backend/internal/jobs/heartbeat_test.go — unit tests for HeartbeatWorker (created inline in Plan 06-01 Task 2)
• backend/internal/jobs/orphan_cleanup_test.go — unit tests for OrphanCleanupWorker (created inline in Plan 06-01 Task 2)
• backend/internal/jobs/error_handler_test.go — unit tests for SlogErrorHandler (created inline in Plan 06-01 Task 2)

Wave 0 is satisfied by inline test creation in Plan 06-01 Task 2 — no separate Wave 0 stub phase required.

---

Manual-Only Verifications

Behavior	Requirement	Why Manual	Test Instructions
Heartbeat logs "worker heartbeat" every ~1 min	WORK-02	Requires running binary with real Postgres	just worker, observe logs for 2+ min, confirm ≥2 heartbeat entries ~60s apart
Orphan cleanup runs on schedule and logs results	WORK-02	Requires real DB + S3 state	Insert orphan row, start worker, wait for cleanup run, verify log output
Failed job retried with backoff visible in logs	WORK-03	Requires real river runtime	Register a job that fails, observe retry log entries with attempt/max_attempts fields
Graceful shutdown completes cleanly	WORK-01	Requires running process	Ctrl+C on running worker, verify "worker stopped" log and clean exit code

---

Validation Sign-Off

• All tasks have <automated> verify or Wave 0 dependencies
• Sampling continuity: no 3 consecutive tasks without automated verify (Wave 1: 2 auto, Wave 2: 2 auto, Wave 3: manual checkpoint)
• Wave 0 covered by inline test creation in Plan 06-01 Task 2
• No watch-mode flags
• Feedback latency < 15s
• nyquist_compliant: true set in frontmatter

Approval: pending