# Development Plan
## SOP Governance Tool — Stage 1

Assumption: solo beginner + Claude Code, 10–15 focused hrs/week ⇒ ~15–17 weeks. Each milestone ends with a **demo you can show on your own phone/laptop** and a short acceptance checklist. Do not start a milestone until the previous checklist passes.

Golden rules:
1. **One milestone at a time.** Resist building ahead.
2. **Never paste code you can't explain.** Ask Claude Code to explain until you can.
3. **Commit after every working step** with a plain-English message.
4. **Deploy to Vercel from Week 1** — always have a live URL.

---

### M0 · Setup (Week 1)
Scaffold Next.js + TypeScript + Tailwind + shadcn/ui; create Supabase project (Singapore); run `db/schema.sql`; connect; deploy "hello world" to Vercel; put this `/docs` pack + `CLAUDE.md` in the repo.
✅ Live URL loads · schema visible in Supabase table editor · repo pushed.

### M1 · Auth & Users (Weeks 2–3) — FR-1.x
Login/logout; profiles; role-based redirect; Users & Departments admin pages; JWT claims hook; role guard middleware.
✅ Staff login lands on /my-sops and CANNOT open /users (test it) · admin can invite a user and change a role · deactivated user blocked.

### M2 · SOP Repository & Editor (Weeks 4–6) — FR-2.x
SOP list with filters/search; create SOP; structured editor with steps + photo upload; autosave.
✅ Create WH-PICK-001, add 5 steps with 2 photos, refresh mid-edit and lose ≤10s · duplicate code rejected politely.

### M3 · Governance (Weeks 7–8) — FR-3.x
`lib/workflow.ts` state machine; submit / decide / publish routes; version snapshotting; approvals queue; version history tab; audit log writes + audit page.
✅ Full loop: draft → submit → approve → publish v1.0 → edit → publish v1.1 → open v1.0 frozen content · reject requires a comment · every action appears in audit log · illegal transitions blocked at API (curl test).

### M4 · Distribution & Acknowledgement (Weeks 9–10) — FR-4.x
Assign departments; staff My SOPs + mobile viewer; acknowledge flow with typed-name signature; share link; re-ack on new version.
✅ On YOUR OWN PHONE: staff account sees assigned SOP in BM… acknowledges… it moves to "Acknowledged" · same user cannot ack twice · publishing v1.2 moves it back to "Needs acknowledgement".

### M5 · Dashboard & Reports (Week 11) — FR-5.x
Stat cards; per-SOP % table; department table; overdue-review flag; CSV export.
✅ Numbers match a hand-count of seeded data · CSV opens in Excel with outstanding names listed.

### M6 · AI (Weeks 12–13) — FR-6.x
`/api/ai/draft` + editor modal; `/api/ai/translate` + translations tab + reviewed flag; ai_log; rate limit.
✅ Describe a process in 3 sentences → usable structured draft in the editor · translate v1.x to BM + ZH, mark BM reviewed, staff viewer shows BM (safety in English until reviewed) · 21st call today politely refused · Anthropic key absent from client bundle.

### M6.5 · Incident Log (Week 14) — FR-7.x
Incidents table + RLS; staff report flow (viewer link + My SOPs button, photo, severity); admin incident list + review/close with resolution note; SOP detail Incidents tab; dashboard open-incidents card.
✅ Staff reports a problem with photo from the viewer in <60s · approver closes it with a note and jumps to the SOP editor · closed incident is read-only · all transitions in audit log.

### M7 · Hardening & Go-Live (Weeks 15–16)
Security checklist from 03-architecture §6 (all boxes); Supabase backups on + one restore test; seed real company data; onboard real staff via WhatsApp-shared link; fix top frictions for one week.
✅ 20+ real SOPs published · ≥80% acknowledgement · founder does ZERO manual screenshot/Sheet work for a full week.

### Scope-cut order (if behind schedule)
Cut from the end of the week's scope, never extend weeks: 1) ZH translation (keep BM) · 2) CSV exports (screen only) · 3) incident photo + per-SOP tab (keep report + list) · 4) audit log UI (data still recorded) · 5) photo upload in steps (text only). NEVER cut: RLS, the state machine, acknowledgement immutability, the basic incident report+list.

### Weekly rhythm (fits around warehouse + trading)
- 2 × 2-hr build sessions with Claude Code (follow CLAUDE.md session plan)
- 1 × 1-hr review: read the week's code, run the checklist, commit, deploy
- 10 min: write next session's goal at the top of CLAUDE.md scratch section