familysync/.planning/milestones/v1.1-phases/10-admin-role-settings/10-VALIDATION.md

phase, slug, status, nyquist_compliant, wave_0_complete, created

phase	slug	status	nyquist_compliant	wave_0_complete	created
10	admin-role-settings	draft	true	false	2026-06-13

Phase 10 — Validation Strategy

Per-phase validation contract for feedback sampling during execution.

---

Test Infrastructure

Property	Value
Framework	Vitest 4.x (apps/api unit + real-DB integration), Vitest 4.x + Playwright (apps/pwa unit + e2e)
Config file	apps/api/vitest.config.ts, apps/pwa/vitest.config.ts, apps/pwa/playwright.config.ts
Quick run command	pnpm --filter @familysync/api test
Full suite command	pnpm --filter @familysync/api test && pnpm --filter @familysync/pwa test && pnpm --filter @familysync/pwa test:e2e
Estimated runtime	~60–120 seconds (e2e dominates)

Notes:

• API real-DB integration tests need the dev MariaDB bound on 3306 + DB_HOST=127.0.0.1 + .env creds; API tests live in apps/api/tests/ (never src/) — see api-integration-test-db.
• tsc --noEmit MUST be run separately in both apps — vitest stays green on type errors (vitest-passes-tsc-fails).
• e2e relies on the dev-bypass admin user (id=1 is_admin=true) seeded by Plan 01 Task 3 in apps/pwa/e2e/global-setup.ts.

---

Sampling Rate

• After every task commit: Run pnpm --filter @familysync/api test (API tasks) or pnpm --filter @familysync/pwa exec tsc --noEmit (PWA tasks).
• After every plan wave: Run pnpm --filter @familysync/api test && pnpm --filter @familysync/api exec tsc --noEmit && pnpm --filter @familysync/pwa exec tsc --noEmit.
• Before /gsd-verify-work: Full CI fast-checks gate green (lint + typecheck + test + format:check + md:lint + PWA tests + e2e) — feedback-run-full-ci-gate-before-push.
• Max feedback latency: ~15s for the API quick run; ~120s for the full suite.

---

Per-Task Verification Map

Task ID	Plan	Wave	Requirement	Threat Ref	Secure Behavior	Test Type	Automated Command	File Exists	Status
10-01-01	01	1	ADMIN-01/02/03	T-10-01	schema additive only; no destructive DDL	typecheck	pnpm --filter @familysync/api exec tsc --noEmit	✅ existing	⬜ pending
10-01-02	01	1	ADMIN-01/02/03	T-10-01	db:generate + db:migrate actually RUN (never push); migration SQL additive-only; live DB columns verified by mysql2 query (tsc NOT proof)	integration (DB)	mysql2 SHOW COLUMNS/SHOW TABLES assert (see plan verify)	✅ existing	⬜ pending
10-01-03	01	1	ADMIN-03	T-10-03	dev-bypass admin row scoped to guarded dev/e2e DB only	source	grep -c is_admin apps/pwa/e2e/global-setup.ts	✅ existing	⬜ pending
10-02-01	02	2	ADMIN-03	T-10-04/05/06/07	requireAdmin 403s non-admin; role from DB not client flag	unit	pnpm --filter @familysync/api test -- requireAdmin	❌ W0 → apps/api/tests/lib/requireAdmin.test.ts	⬜ pending
10-02-02	02	2	ADMIN-03	T-10-04	first-login-wins is_admin; member-count-agnostic	integration (DB)	pnpm --filter @familysync/api test -- user	✅ apps/api/tests/auth/user.test.ts (extend)	⬜ pending
10-02-03	02	2	ADMIN-03	T-10-06/07	/api/me exposes isAdmin + needsProviderSetup (UX-only flag)	integration	pnpm --filter @familysync/api test -- me	✅ apps/api/tests/routes/me.test.ts (extend)	⬜ pending
10-03-01	03	3	ADMIN-01	T-10-SC	broker helpers exported; bodies unchanged	unit	pnpm --filter @familysync/api test -- outbox	✅ apps/api/tests/broker/	⬜ pending
10-03-02	03	3	ADMIN-01/02/03	T-10-08/09/10/11/13	guard-first 403; ALL credential-validation failures → one generic {error:'Invalid request'} 400 (no password echo/log); shared credentialSync helper; encrypted at rest; exclusive is_shared	integration	pnpm --filter @familysync/api test -- admin	❌ W0 → apps/api/tests/routes/admin.test.ts	⬜ pending
10-03-03	03	3	ADMIN-01	T-10-09/10/12	self-service member-scoped; no cross-member write; calls SAME shared validateEncryptAndStoreCredential helper; no echo	integration	pnpm --filter @familysync/api test -- credential	❌ W0 → in apps/api/tests/routes/admin.test.ts	⬜ pending
10-04-01	04	4	ADMIN-01/02/03	T-10-14	MeUser flags UX-only; self-service payload has no userId	typecheck	pnpm --filter @familysync/pwa exec tsc --noEmit	✅ existing	⬜ pending
10-04-02	04	4	ADMIN-01	T-10-15/16	password never pre-filled; autocomplete=new-password; SetupBanner clears ONLY on success (['me'] invalidation), no dismiss button	typecheck + source	pnpm --filter @familysync/pwa exec tsc --noEmit + grep new-password	✅ existing	⬜ pending
10-04-03	04	4	ADMIN-03	T-10-14	/admin redirect for non-admin; nav entry hidden for non-admin; e2e is the gate, playwright-cli supplementary	e2e (playwright)	pnpm --filter @familysync/pwa test:e2e -- admin	❌ W0 → apps/pwa/e2e/admin.spec.ts	⬜ pending

Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky

Sampling continuity: every task has an <automated> verify; no 3 consecutive tasks lack automated coverage.

---

Wave 0 Requirements

• apps/api/tests/lib/requireAdmin.test.ts — NEW unit tests for the guard (403 non-admin / next() admin / no-user / DB-not-client-flag). Created in Plan 02 Task 1 (RED first).
• apps/api/tests/routes/admin.test.ts — NEW integration tests covering ADMIN-01 (credential validate/encrypt/no-echo, all failure modes → one generic 400), ADMIN-02 (exclusive is_shared), ADMIN-03 (403 for non-admin on every admin route — import app, never adminRouter directly), and the member self-service credential cases (shared-helper reuse). Created in Plan 03 Tasks 2 & 3 (RED first).
• apps/pwa/e2e/admin.spec.ts — NEW e2e: admin sees nav entry + reaches /admin; non-admin (route-mocked isAdmin:false) sees no entry and is redirected. Created in Plan 04 Task 3 (RED first; this spec is the binding gate, playwright-cli is supplementary).
• Extend apps/api/tests/auth/user.test.ts — first-login-wins cases (Plan 02 Task 2).
• Extend apps/api/tests/routes/me.test.ts — isAdmin + needsProviderSetup cases (Plan 02 Task 3).

Existing infrastructure (Vitest + Playwright + real-DB harness + global-setup seed) covers all framework needs — no framework install required.

---

Manual-Only Verifications

Behavior	Requirement	Why Manual	Test Instructions
Live CalDAV PROPFIND against the real Fastmail account on a real credential save	ADMIN-01	CI/e2e mock CalDAV (dev-bypass user 1 has no Fastmail credential — dev-data-user1-no-calendars); a true end-to-end save against Fastmail needs a real app password	At go-live, an admin enters a real Fastmail app password in the credential sheet; confirm 200 + the member's calendar appears after the initial sync. Optional operator spot-check, not a phase gate.

All other phase behaviors (route guard, no-echo, encryption-at-rest, exclusive is_shared, nav gating, /admin redirect) have automated coverage (Vitest + Playwright/playwright-cli — the route guard and nav gating are desktop-Chromium-drivable per CLAUDE.md, so no human checkpoint; playwright-cli is a supplementary confirmation while the e2e spec is the binding gate).

---

Validation Sign-Off

• All tasks have <automated> verify or Wave 0 dependencies
• Sampling continuity: no 3 consecutive tasks without automated verify
• Wave 0 covers all MISSING references (requireAdmin.test.ts, admin.test.ts, admin.spec.ts + the two extends)
• No watch-mode flags
• Feedback latency < 120s (full) / < 15s (quick)
• nyquist_compliant: true set in frontmatter

Approval: approved 2026-06-13