docs: add project state audit and execution plan

docs/PROJECT_STATE_AUDIT.md

@@ -0,0 +1,57 @@
+# Project State Audit - Fiddy
+
+Snapshot date: 2026-02-16
+
+## 1) Confirmed stack and structure
+- Backend: Express API in `backend/` with `routes/`, `controllers/`, `models/`, `middleware/`, `utils/`.
+- Frontend: React + Vite in `frontend/` with API wrappers in `frontend/src/api`, auth/state in `frontend/src/context`, pages in `frontend/src/pages`.
+- DB migrations: canonical folder is `packages/db/migrations`.
+
+## 2) Governance and agentic setup status
+- Present and aligned:
+  - `PROJECT_INSTRUCTIONS.md`
+  - `AGENTS.md`
+  - `DEBUGGING_INSTRUCTIONS.md`
+  - `docs/DB_MIGRATION_WORKFLOW.md`
+  - `docs/AGENTIC_CONTRACT_MAP.md`
+- Commit discipline added in `PROJECT_INSTRUCTIONS.md` section 12 and being followed with small conventional commits.
+
+## 3) Current implementation status vs vertical-slice goals
+1. DB migrate command + schema:
+   - Implemented: root scripts `db:migrate`, `db:migrate:status`, `db:migrate:verify`.
+   - Implemented: migration tracking + runbook.
+2. Register/Login/Logout (custom sessions):
+   - Implemented: DB sessions table migration (`create_sessions_table.sql`).
+   - Implemented: session model, HttpOnly cookie set/clear, `/auth/logout`, auth middleware fallback to DB session cookie.
+   - Implemented: frontend credentialed API (`withCredentials`), logout route call.
+3. Protected dashboard page:
+   - Partially implemented via existing `PrivateRoute` token gate.
+4. Group create/join + switcher:
+   - Existing household create/join/switch flow exists but does not yet match all group-policy requirements.
+5. Entries CRUD:
+   - Existing list CRUD exists in legacy and multi-household paths.
+6. Receipt upload/download endpoints:
+   - Not implemented as dedicated receipt domain/endpoints.
+7. Settings + Reports:
+   - Settings page exists; reporting is not fully formalized.
+
+## 4) Contract gaps and risks
+- `DATABASE_URL` is now supported in runtime pool config, but local operator environment still needs this variable configured.
+- No automated test suite currently exercises the new auth/session behavior; API behavior is mostly validated by static/lint checks.
+- Group policy requirements (owner role, join policy states, invite lifecycle constraints, revive semantics) are not fully implemented.
+- No explicit audit log persistence layer verified for invite events/request IDs.
+- Encoding cleanliness needs ongoing watch; historical mojibake appears in some UI text/log strings.
+
+## 5) Recommended next implementation order
+1. Finalize auth session contract:
+   - Add authenticated session introspection endpoint (`/users/me` already exists) to support cookie-only bootstrapping if token absent.
+   - Update frontend auth bootstrap so protected routes work with DB session cookie as canonical auth.
+2. Add explicit API tests (auth + households/list negative cases):
+   - unauthorized
+   - not-a-member
+   - invalid input
+3. Implement group-policy requirements incrementally:
+   - owner role migration + policy enums
+   - invite policy and immutable settings
+   - approval-required flow + revive/single-use semantics
+4. Add dedicated receipt domain endpoints (metadata list vs byte retrieval split) if the product scope requires the receipt contract verbatim.