# Backend-Agent Status Slice Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Harden the backend HTTP foundation and add the first minimal agent-to-backend status reporting path.

**Architecture:** The backend remains a small in-memory Go service with stronger HTTP and validation tests plus a narrow `POST /api/v1/player/status` contract. The agent reuses its internal health snapshot and periodically posts it over HTTP, logging failures without stopping playback/lifecycle behavior.

**Tech Stack:** Go stdlib, existing `net/http` router, `httptest`, existing agent health model.

---

### Task 1: Backend route coverage for existing endpoints

**Files:**
- Modify: `server/backend/internal/httpapi/messagewall_test.go`
- Possibly create: `server/backend/internal/httpapi/router_test.go`

**Step 1: Write the failing tests**

Add focused tests for:
- `GET /healthz` returns `200` and `status=ok`
- `GET /api/v1` returns base info and tool list
- `GET /api/v1/meta` returns the documented tool route

**Step 2: Run test to verify it fails**

Run: `go test ./internal/httpapi -run 'TestRouter'`
Expected: FAIL because the new route tests do not exist yet or assertions fail.

**Step 3: Write minimal implementation**

Only add or adjust router/response code if the tests expose gaps. Do not refactor unrelated HTTP code.

**Step 4: Run test to verify it passes**

Run: `go test ./internal/httpapi -run 'TestRouter'`
Expected: PASS.

**Step 5: Commit**

```bash
git add server/backend/internal/httpapi/*.go
git commit -m "Ergaenze HTTP-Tests fuer Basisendpunkte"
```

### Task 2: Message-wall validation matrix

**Files:**
- Modify: `server/backend/internal/campaigns/messagewall/resolver_test.go`

**Step 1: Write the failing tests**

Add table-driven validation tests for:
- unsupported `version`
- invalid `unit`
- invalid `fit_mode`
- empty slot list
- duplicate `slot_id`
- out-of-bounds slot

**Step 2: Run test to verify it fails**

Run: `go test ./internal/campaigns/messagewall -run 'TestValidate'`
Expected: FAIL until the new cases are covered correctly.

**Step 3: Write minimal implementation**

Adjust validation only if tests reveal a real mismatch against `docs/LAYOUT-JSON.md`.

**Step 4: Run test to verify it passes**

Run: `go test ./internal/campaigns/messagewall -run 'TestValidate'`
Expected: PASS.

**Step 5: Commit**

```bash
git add server/backend/internal/campaigns/messagewall/resolver_test.go server/backend/internal/campaigns/messagewall/resolver.go
git commit -m "Pruefe Layout-Validierung systematischer"
```

### Task 3: Backend player status endpoint

**Files:**
- Modify: `server/backend/internal/httpapi/router.go`
- Create: `server/backend/internal/httpapi/playerstatus.go`
- Create: `server/backend/internal/httpapi/playerstatus_test.go`

**Step 1: Write the failing tests**

Add tests for:
- valid `POST /api/v1/player/status` returns `200` and `{"status":"accepted"}`
- invalid JSON returns the shared error envelope
- missing `screen_id` returns `400`
- malformed timestamps return `400`

**Step 2: Run test to verify it fails**

Run: `go test ./internal/httpapi -run 'TestHandlePlayerStatus'`
Expected: FAIL because handler and route do not exist yet.

**Step 3: Write minimal implementation**

Implement a small request struct, parse/validate it, and reuse the existing error/JSON helpers. Keep storage out of scope.

**Step 4: Run test to verify it passes**

Run: `go test ./internal/httpapi -run 'TestHandlePlayerStatus'`
Expected: PASS.

**Step 5: Commit**

```bash
git add server/backend/internal/httpapi/router.go server/backend/internal/httpapi/playerstatus.go server/backend/internal/httpapi/playerstatus_test.go
git commit -m "Lege ersten Player-Status-Endpunkt an"
```

### Task 4: Agent status reporter payload

**Files:**
- Create: `player/agent/internal/statusreporter/reporter.go`
- Create: `player/agent/internal/statusreporter/reporter_test.go`
- Possibly modify: `player/agent/internal/app/app.go`

**Step 1: Write the failing tests**

Add tests for converting `app.HealthSnapshot` into the HTTP payload and for a successful post to an `httptest.Server`.

**Step 2: Run test to verify it fails**

Run: `go test ./internal/statusreporter`
Expected: FAIL because package/behavior does not exist yet.

**Step 3: Write minimal implementation**

Create a small reporter with injected base URL, `http.Client`, and time source as needed. Keep the API narrow.

**Step 4: Run test to verify it passes**

Run: `go test ./internal/statusreporter`
Expected: PASS.

**Step 5: Commit**

```bash
git add player/agent/internal/statusreporter/*.go player/agent/internal/app/app.go
git commit -m "Fuehre einfachen Status-Reporter fuer den Agenten ein"
```

### Task 5: Agent periodic reporting integration

**Files:**
- Modify: `player/agent/internal/app/app.go`
- Modify: `player/agent/internal/app/app_test.go`
- Possibly modify: `player/agent/internal/config/config.go`
- Possibly modify: `player/agent/internal/config/config_test.go`

**Step 1: Write the failing tests**

Add tests that prove:
- reporting is triggered from the running app
- send failures are logged and do not stop `Run()`
- any new interval config gets sane defaults

**Step 2: Run test to verify it fails**

Run: `go test ./internal/app ./internal/config`
Expected: FAIL until integration exists.

**Step 3: Write minimal implementation**

Wire the reporter into the app loop with the smallest possible seam. Avoid broad lifecycle refactors.

**Step 4: Run test to verify it passes**

Run: `go test ./internal/app ./internal/config`
Expected: PASS.

**Step 5: Commit**

```bash
git add player/agent/internal/app/*.go player/agent/internal/config/*.go
git commit -m "Melde Agent-Status periodisch an das Backend"
```

### Task 6: Documentation update for the new status path

**Files:**
- Modify: `API-MQTT-VERTRAG.md`
- Modify: `DEVELOPMENT.md`
- Possibly modify: `README.md`
- Possibly create: `docs/PLAYER-STATUS-HTTP.md`

**Step 1: Write the failing documentation check**

Create a short checklist from the implemented contract and verify which docs are stale.

**Step 2: Run the verification**

Manual check against the implemented request/response payload and the chosen scope.
Expected: current docs are incomplete for the temporary dev-stage HTTP status path.

**Step 3: Write minimal documentation updates**

Document that the current dev slice uses a minimal HTTP status endpoint before the richer long-term API/MQTT model is fully built.

**Step 4: Run verification**

Re-read the changed docs and ensure wording matches actual code scope.

**Step 5: Commit**

```bash
git add API-MQTT-VERTRAG.md DEVELOPMENT.md README.md docs/*.md
git commit -m "Dokumentiere ersten HTTP-Statuspfad fuer den Agenten"
```

### Task 7: Final verification

**Files:**
- No planned file changes

**Step 1: Run backend tests**

Run: `go test ./...`
Workdir: `server/backend`
Expected: PASS.

**Step 2: Run agent tests**

Run: `go test ./...`
Workdir: `player/agent`
Expected: PASS.

**Step 3: Run builds**

Run:
- `go build ./...` in `server/backend`
- `go build ./...` in `player/agent`
Expected: PASS.

**Step 4: Run manual integration check**

Start backend locally, run agent locally with example config, and confirm the backend receives `POST /api/v1/player/status` successfully.

**Step 5: Commit if needed**

Only if the verification step itself required code/doc adjustments.