WS-FE-001-01: Canonical React + Vite app foundation

.agent-loop/initiatives/WS-FE-001-frontend-operations-console/CHUNK_MAP.md

@@ -0,0 +1,14 @@
+# Chunk Map: WS-FE-001 — Frontend Operations Console
+
+| Chunk | Title | Upstream issue | Risk | Status |
+|---|---|---|---:|---|
+| `WS-FE-001-01` | Canonical React + Vite app foundation | #50 | L2 | Implemented; internal review + human checkpoint pending |
+| `WS-FE-001-02` | Task queue + task detail/claim/submit | #51 / #52 | L2 | Planned; needs start signal |
+| `WS-FE-001-03` | Review queue + review decision + findings | #56 | L2 | Planned; blocked on review/revision backend (#34–#38) |
+| `WS-FE-001-04` | Dashboard (role-aware) | — | L1 | Planned; thin once screens exist |
+| `WS-FE-001-05` | Guide & policy activation flow | #49 | L2 | Planned; needs start signal |
+| `WS-FE-001-06` | Contribution / payment / reputation record | #53 / #55 | L1 | Planned; blocked on payment/reputation backend (#39–#40) |
+| `WS-FE-001-07` | Audit console | #51 (audit slice) | L2 | Planned; last per build order |
+
+Build order follows `docs/website_flow.md` §5. Each chunk gets its own contract in
+`chunks/` and its own explicit start signal; the loop does not auto-advance.

.agent-loop/initiatives/WS-FE-001-frontend-operations-console/INTENT.md

@@ -0,0 +1,33 @@
+# Intent: WS-FE-001 — Frontend Operations Console
+
+## Problem
+
+`AGENTS.md` and `docs/architecture_system_architecture.md` lock the frontend as a
+React + Vite + TypeScript internal operations UI, but no canonical frontend
+exists. Backend contracts for auth, tasks, projects, checkers, and actors are now
+stable, and the upstream frontend epic (`Flow-Research/workstream#29`) with its
+starter issue (#50) is ready to start.
+
+## Goal
+
+Build the canonical Workstream operations console incrementally, one screen family
+at a time, against the paper-and-ink design system, so operators (project manager,
+worker, reviewer, admin/finance) can run the internal loop through a UI.
+
+## Non-goals (v0.1)
+
+- No Workstream-owned auth: Flow token handoff only (ADR 0006).
+- No marketing site; operations/workflow surfaces only.
+- No dark theme, no heavy component library.
+- No screens whose backend contracts are not yet stable (e.g. payment/reputation
+  screens wait on their backends).
+
+## Design source of truth
+
+`docs/design_system.md` and `docs/website_flow.md`.
+
+## Sequencing
+
+Foundation first (`WS-FE-001-01`, upstream #50), then screen chunks following the
+`docs/website_flow.md` build order: task queue, review, dashboard, guides,
+contribution record, audit.

.agent-loop/initiatives/WS-FE-001-frontend-operations-console/PLAN.md

@@ -0,0 +1,31 @@
+# Plan: WS-FE-001 — Frontend Operations Console
+
+## Approach
+
+Deliver the console as a sequence of bounded chunks, each mapped to an upstream
+issue under epic #29, each following the repository loop (contract → implement →
+evidence → internal review → PR → human checkpoint). The foundation chunk fixes
+the conventions every later chunk inherits; screen chunks then wire one surface at
+a time to its stable backend contract.
+
+## Locked conventions (set by WS-FE-001-01, see ADR 0012)
+
+- Stack: React + Vite + TypeScript, strict.
+- Routing: React Router. API client: one native `fetch` wrapper at
+  `src/api/client.ts` targeting `/api/v1`, bearer-token attach, typed `ApiError`.
+- Auth: token-carry only (env/local storage); no login/session ownership.
+- Tests: Vitest + React Testing Library. Lint: ESLint. Typecheck: `tsc --noEmit`.
+- CI: a `frontend` workflow runs lint, typecheck, test, build.
+- Design: paper-and-ink system, no component kit, no sans-serif, no dark theme.
+
+## Chunk sequence
+
+See `CHUNK_MAP.md`. Foundation is active; screen chunks are planned and each needs
+its own start signal.
+
+## Risks
+
+- Backend contract gaps for a given screen → a chunk stops and escalates rather
+  than inventing endpoints (stop condition in each chunk contract).
+- Design drift → `docs/design_system.md` is the single arbiter; deviations require
+  an ADR update, not ad-hoc styling.

.agent-loop/initiatives/WS-FE-001-frontend-operations-console/STATUS.md

@@ -0,0 +1,19 @@
+# Status: WS-FE-001 — Frontend Operations Console
+
+## Current
+
+- Active chunk: `WS-FE-001-01` (upstream #50).
+- Branch: `codex/ws-fe-001-01-frontend-foundation` off `upstream/main`.
+- Implementation complete; automated gates green (lint, typecheck, Vitest 13/13,
+  build). Live `/api/v1/health` + `/api/v1/auth/me` confirmed against a local
+  backend. Internal reviewer tracks (senior-eng/architecture, security/auth,
+  QA/test, product/ops) passed; findings applied.
+- Submitted for maintainer review as Flow-Research/workstream #50 (PR #83).
+
+## Evidence
+
+- `reviews/WS-FE-001-01-internal-review-evidence.md`.
+
+## History
+
+- 2026-07-08: initiative opened; foundation contract written and implemented.

.agent-loop/initiatives/WS-FE-001-frontend-operations-console/chunks/WS-FE-001-01-canonical-react-vite-foundation.md

@@ -0,0 +1,227 @@
+# Chunk Contract: WS-FE-001-01 — Canonical React + Vite App Foundation
+
+## Parent initiative
+
+WS-FE-001 — Frontend Operations Console
+
+> **Prerequisite note.** WS-FE-001 is a new, large initiative and per `AGENTS.md`
+> ("an initiative plan for large work") it needs `INTENT.md`, `PLAN.md`, and
+> `CHUNK_MAP.md`. This foundation chunk is bounded and was contracted first; the
+> initiative plan (`INTENT.md`, `PLAN.md`, `CHUNK_MAP.md`) was authored alongside
+> it and ships in this PR.
+
+## Upstream issue
+
+Flow-Research/workstream#50 — "Frontend: Canonical React + Vite app foundation"
+(parent epic #29; area/frontend, priority/P0, focus/v0.1). This contract maps
+directly to that issue's five acceptance criteria. Contribution path: sync then
+branch off `upstream/main`, push to `origin` (fork `jorshimayor/workstream`), PR
+into `Flow-Research/workstream`.
+
+> **Two ground-truth notes recorded during discovery:**
+> 1. The fork `main` is 10 commits behind `upstream/main` (missing WS-POL-001-14).
+>    Sync before branching.
+> 2. Issue #50's "Why" states the repo "currently has only `demos/week1_api_demo_ui`".
+>    That directory exists on **neither the fork nor `upstream/main`**, and no
+>    README "demo UI" note exists either. There is no demo UI to retire; the
+>    "demo UI separated or retired" criterion is met by documenting this, not by
+>    removing a nonexistent artifact. Flag the stale premise to the maintainer.
+
+## Goal
+
+Establish the single canonical React + Vite + TypeScript operations app under
+`frontend/` that proves a live connection to the backend and gives every later
+frontend chunk a shell to build into.
+
+Scope is deliberately modest and matches issue #50 exactly: the app builds, it
+calls `/api/v1/health` and `/api/v1/auth/me` against the backend with Flow-style
+bearer-token handling, its shell carries navigation placeholders for the five
+operations surfaces, and the docs explain how to run it. It applies the
+`design.md` visual language to the shell so the look is correct from the start,
+but it does **not** build the full primitive library, keyboard model, or any real
+screen — those are later chunks.
+
+## Why this chunk exists
+
+`AGENTS.md` locks the frontend as React + Vite + TypeScript and
+`docs/architecture_system_architecture.md` gives that stack the internal
+operations UI, but no canonical app exists yet. `docs/roadmap_30_day_master_plan.md`
+sequences dashboards and review UI after backend contracts stabilize — which they
+now have for task/project/checker/actor and for auth (`/api/v1/auth/me` and
+`/api/v1/health` are live). This chunk creates that canonical foundation and
+proves backend connectivity, unblocking the per-surface screen chunks
+(#49/#51/#52/#56).
+
+## Approved plan reference
+
+- Authoritative scope: Flow-Research/workstream#50 (parent #29)
+- INTENT: `.agent-loop/initiatives/WS-FE-001-frontend-operations-console/INTENT.md`
+- PLAN: `.agent-loop/initiatives/WS-FE-001-frontend-operations-console/PLAN.md`
+- CHUNK_MAP: `.agent-loop/initiatives/WS-FE-001-frontend-operations-console/CHUNK_MAP.md`
+- Design reference (committed in-repo by this chunk): `docs/design_system.md`,
+  `docs/website_flow.md` — the visual language for the shell and all later chunks.
+
+## Risk class
+
+L2 — additive and frontend-only (no backend, data, migration, or auth-boundary
+change), but architecturally load-bearing: it fixes the canonical app location,
+routing, API-client, and token-handling conventions every later frontend chunk
+inherits. Requires the architecture reviewer.
+
+## SLA
+
+P0
+
+## Allowed files
+
+```text
+frontend/**
+docs/design_system.md
+docs/website_flow.md
+docs/decision_0012_frontend_stack_and_design_system.md
+docs/architecture_system_architecture.md
+README.md
+.gitignore
+.github/workflows/**
+.agent-loop/LOOP_STATE.md
+.agent-loop/WORK_QUEUE.md
+.agent-loop/initiatives/WS-FE-001-frontend-operations-console/**
+```
+
+## Not allowed
+
+```text
+backend/**
+any change to the /api/v1 request/response contract
+real screen content or business logic for guides, task queue, worker tasks,
+review, dashboards, contributions, or audit (navigation placeholders only)
+the full reusable primitive library and global keyboard model (deferred to a
+follow-up chunk and the per-screen chunks #49/#51/#52/#56)
+payment, reputation, or finance UI logic
+a dark theme or theme-switching system (paper-first only, design.md)
+any sans-serif typeface (design.md)
+any opinionated UI component kit: Material/MUI, Bootstrap, Chakra, Ant Design,
+Tailwind UI kits, or similar (design.md, flow handoff notes)
+Workstream-owned login, signup, password, or session storage (Flow token
+handoff only — ADR 0006, AGENTS.md)
+```
+
+## Implementation boundaries
+
+- Stack is locked: React + Vite + TypeScript. Routing via React Router; a single
+  native `fetch` wrapper for the API client; unit tests via Vitest + React
+  Testing Library. No visual component library, no server-state cache library in
+  this chunk (kept minimal; add later if a screen chunk needs it).
+- Auth: the client attaches a Flow-style bearer token to backend calls and reads
+  it from a single configurable source (env/local input for dev). It stores no
+  credentials and owns no session primitives; the unauthenticated `/auth/me`
+  response is handled as a first-class state, not an error crash.
+- Visual language comes only from `design.md`: warm paper background, editorial
+  serif for content, uppercase letter-spaced IBM Plex Mono for metadata/status,
+  hairline dividers, no cards/shadows, one accent plus the state colors used as
+  small text only. Fonts: IBM Plex Mono for mono; editorial serif via a licensed
+  face if available, else the approved Google Fonts stand-in (Source Serif 4 /
+  Newsreader / Lora) per `website_flow.md`, self-hosted or pinned.
+- Navigation placeholders name the five operations surfaces from issue #50 —
+  project setup, task queue, worker tasks, review queue, dashboards — mapped to
+  the project-manager / worker / reviewer / admin-finance roles. Full nav-label
+  and role-visibility reconciliation with `website_flow.md` happens in the screen
+  chunks.
+- The canonical UI lives at `frontend/`. Because no demo UI exists in the tree,
+  the docs must state that `frontend/` is the one canonical UI and note the stale
+  issue reference; nothing is "retired".
+
+## Acceptance criteria
+
+Mapped to issue #50 (first five are the issue's own criteria):
+
+- [ ] Canonical `frontend/` React + Vite + TypeScript app builds with TypeScript
+      (`npm run build` and `tsc --noEmit` both clean).
+- [ ] The app calls `GET /api/v1/health` against the backend and renders the
+      connectivity result.
+- [ ] The app calls `GET /api/v1/auth/me` with a Flow-style bearer token and
+      renders the current actor (name/role), handling the unauthenticated case
+      gracefully.
+- [ ] The app shell includes navigation placeholders for: project setup, task
+      queue, worker tasks, review queue, dashboards.
+- [ ] Docs state that `frontend/` is the canonical UI and record that the
+      `demos/week1_api_demo_ui` named in issue #50 is not present on
+      `upstream/main` (nothing to retire) — the "demo UI separated or retired"
+      criterion, satisfied by documentation.
+- [ ] README/docs are updated with how to run the canonical frontend against the
+      backend (install, dev server, backend base URL, dev token).
+
+Supporting quality gates:
+
+- [ ] The API client is a single typed `fetch` wrapper targeting `/api/v1` with
+      bearer-token handling and a typed error shape.
+- [ ] The shell applies the `design.md` visual language (paper background,
+      serif content, uppercase mono metadata, hairline dividers, no cards/shadows);
+      no sans-serif face, no dark theme, and no UI component kit is present in
+      `package.json`.
+- [ ] Lint, typecheck, unit tests, and build all pass in a new `frontend` CI job.
+- [ ] Screenshot evidence of the shell (nav placeholders + health/actor status)
+      matches `design.md`.
+
+## Verification commands
+
+```bash
+git fetch upstream
+cd frontend && npm ci
+cd frontend && npm run lint
+cd frontend && npm run typecheck          # tsc --noEmit
+cd frontend && npm run test -- --run      # vitest
+cd frontend && npm run build
+# manual backend-connectivity proof (dev): with backend running, load the app and
+# confirm /api/v1/health and /api/v1/auth/me render; capture as evidence.
+# repo loop + docs gates for the contract and design docs
+python3 scripts/check_markdown_links.py
+python3 scripts/check_stale_workstream_wording.py
+python3 scripts/check_loop_memory_state.py
+python3 scripts/workstream_agent_gate.py --base upstream/main --head HEAD --format json
+```
+
+## Required reviewers
+
+Every listed reviewer must end with one exact result value:
+
+- `PASS`
+- `PASS AFTER FIXES`
+- `PASS WITH LOW RISKS`
+- `N/A - with approved reason`
+
+Required:
+
+- senior engineering
+- QA/test
+- security/auth — bearer-token handling only; assert no credential/session storage
+- product/ops
+- architecture — establishes canonical app location, routing, API-client, tokens
+- docs — README run instructions, in-repo design/flow docs, new ADR, arch doc note
+- CI integrity — new `frontend` workflow, `package.json`, build/test config
+- reuse/dedup — API client and shell are single-source, not duplicated
+- test delta — new Vitest suites for the client wrapper and shell
+
+## Human review focus
+
+- The three backend-connectivity criteria genuinely work: `/api/v1/health` and
+  `/api/v1/auth/me` are called against a running backend with a real bearer token,
+  and the unauthenticated path is handled, not crashed.
+- Scope stayed at foundation: navigation is placeholders only; no screen content,
+  primitive library, or keyboard model leaked in.
+- Strictly additive and frontend-only — no `backend/**` or `/api/v1` contract drift.
+- No Workstream-owned auth: token handling only, no credential/session storage (ADR 0006).
+- No heavy UI component kit and no sans-serif face entered the dep tree.
+- Docs correctly record the stale demo-UI premise instead of inventing a retirement.
+
+## Stop conditions
+
+Stop and escalate if:
+
+- scope must expand beyond the allowed files (e.g. a placeholder needs a new backend endpoint)
+- the design direction in `design.md` must change to proceed
+- an auth/session/data boundary change becomes necessary to call `/auth/me`
+- CI/test must be weakened to pass
+- the same blocker remains after 2 repair attempts
+- secrets or production data are needed
+```