# State Center Web State Machine Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build the browser-based Web state machine for `state_center`: job list, timeline, task list, and task/node actions.

**Architecture:** Keep the existing FastAPI backend as the source of truth for workflow state. Add small, focused backend endpoints for timeline, jobs, tasks, and dev ingestion, then build a React/Vite frontend that only renders backend-computed state and posts actions back. Do not move business rules into the frontend.

**Tech Stack:** Python 3.13, FastAPI, Pydantic, pymysql, pytest, Node.js, Vite, React, TypeScript, plain CSS.

---

### Task 1: Add backend task/timeline data contracts

**Files:**
- Modify: `state_center/sql/schema.sql`
- Modify: `state_center/app/main.py`
- Create: `state_center/tests/test_web_state_machine.py`

- [ ] **Step 1: Write the failing test**

Add tests for:
- `GET /api/jobs/{job_id}/timeline` returns all 13 nodes with backend-computed statuses.
- `POST /api/tasks/{task_id}/submit` stores `submitted_result_json` and returns the stored result on duplicate `submitToken`.
- `POST /api/jobs/{job_id}/items` rejects unsafe replace-after-match behavior.

- [ ] **Step 2: Run test to verify it fails**

Run: `python -m pytest state_center/tests/test_web_state_machine.py -v`
Expected: fail because endpoints/fields do not exist yet.

- [ ] **Step 3: Write minimal implementation**

Add the schema column for stored task results, then implement the backend helpers and endpoints in `main.py`.

- [ ] **Step 4: Run test to verify it passes**

Run: `python -m pytest state_center/tests/test_web_state_machine.py -v`
Expected: pass.

- [ ] **Step 5: Commit**

```bash
git add state_center/sql/schema.sql state_center/app/main.py state_center/tests/test_web_state_machine.py
git commit -m "feat: add web state machine backend contracts"
```

### Task 2: Add browser-ready frontend app

**Files:**
- Create: `state_center_web/package.json`
- Create: `state_center_web/vite.config.ts`
- Create: `state_center_web/index.html`
- Create: `state_center_web/src/main.tsx`
- Create: `state_center_web/src/App.tsx`
- Create: `state_center_web/src/api/client.ts`
- Create: `state_center_web/src/components/JobList.tsx`
- Create: `state_center_web/src/components/JobTimeline.tsx`
- Create: `state_center_web/src/components/TaskList.tsx`
- Create: `state_center_web/src/styles.css`

- [ ] **Step 1: Write the failing test**

Add a lightweight frontend build check and a small unit test for timeline status mapping.

- [ ] **Step 2: Run test to verify it fails**

Run: `npm test`
Expected: fail because the app does not exist yet.

- [ ] **Step 3: Write minimal implementation**

Create the Vite app, route-less operational UI, and fetch-based API client.

- [ ] **Step 4: Run test to verify it passes**

Run: `npm test`
Expected: pass.

- [ ] **Step 5: Commit**

```bash
git add state_center_web
git commit -m "feat: add web state machine frontend"
```

### Task 3: Wire local dev workflow

**Files:**
- Create: `state_center_web/README.md`
- Modify: `state_center/README.md`

- [ ] **Step 1: Write the failing test**

Not required; this task is documentation and run instructions only.

- [ ] **Step 2: Write minimal implementation**

Document the start commands for the FastAPI backend and Vite frontend on Windows/macOS.

- [ ] **Step 3: Verify manually**

Start backend and frontend locally, open the browser app, and confirm the timeline and task list render.

- [ ] **Step 4: Commit**

```bash
git add state_center/README.md state_center_web/README.md
git commit -m "docs: add web state machine runbook"
```