suaveplan/openspec/archive/2026-05-19-add-react-auth-core/tasks.md

Tasks — add-react-auth-core (Wave 1)

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/react-auth.md
• 1.2 Read genesis openspec/AGENTS.md §§ 2a, 6a, 7, 12, 13, 14
• 1.3 Draft proposal.md with ## Source mapping table + ### Excluded from this migration
• 1.4 Draft specs/react-auth/spec.md (## ADDED Requirements) — every requirement carries **Verified by:**

2. Implementation

• 2.1 src/error-codes/error-codes.ts — defineCodes("REACT_AUTH", [...]) + 10 typed ReactAuthError subclasses
• 2.2 src/types/auth.types.ts + src/types/crud.types.ts + src/types/index.ts barrel
• 2.3 src/translations/{en-gb,cy-gb,zh-cn}.ts + src/translations/index.ts barrel
• 2.4 src/lib/better-auth-adapter.ts — 6 transforms + 2 guards over unknown payloads
• 2.5 src/client/auth-client.ts — AuthClient class + createAuthClient(config) factory, no @ts-expect-error, Zod boundary on config
• 2.6 src/context/auth-context.tsx — AuthProvider + useAuth + 11 actions
• 2.7 src/components/auth-guard/auth-guard.tsx + .types.ts + .stories.tsx
• 2.8 src/components/auth-provider/auth-provider.tsx — re-export surface for back-compat
• 2.9 src/hooks/use-auth-guard.ts + src/hooks/use-permission.ts
• 2.10 src/observability/react-auth-metrics.ts — OTel counters + histogram
• 2.11 src/index.ts — explicit named root barrel

3. Tests

• 3.1 Unit tests per feature module — every it() has { timeout: 5000 }
• 3.2 Test imports use @suaveplan/testing/runner ONLY (zero direct vitest / bun:test imports)
• 3.3 No vi.mock; better-auth client method overrides on real instances; injectable fetch via AuthClientConfig.fetch

4. Documentation

• 4.1 Sibling .md for every implementation .ts/.tsx (≥200 words, basic + advanced examples)
• 4.2 README.md linking every co-located .md under ## Modules

5. Pre-archive verification (5 gates)

• 5.1 bun run check — clean
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/react-auth — green
• 5.3 bunx turbo test:coverage --filter=@suaveplan/react-auth — 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/react-auth — 0 errors
• 5.5 bunx turbo build --filter=@suaveplan/react-auth — green
• 5.6 bun scripts/lint/check-test-runner-imports.ts — clean

6. Pre-archive 9-row checklist

• 6.1 Generics threaded; expectTypeOf assertions on every literal-type claim
• 6.2 Zod schemas wired at every declared boundary (AuthClientConfig, UseAuthGuardOptions, AuthGuardProps)
• 6.3 Every code in REACT_AUTH_CODES thrown by at least one production path
• 6.4 Strict-mode behaviors tested on and off (StrictMode double-mount cleanup)
• 6.5 OTel instruments emitted from production paths and asserted with real in-memory MeterProvider
• 6.6 No retroactive tick
• 6.7 No export * in any feature barrel
• 6.8 No // biome-ignore in src/
• 6.9 Sibling .md for every implementation .ts/.tsx

7. Archive

• 7.1 Fold specs/react-auth/spec.md → openspec/specs/react-auth/spec.md
• 7.2 Move openspec/changes/add-react-auth-core/ → openspec/archive/2026-05-19-add-react-auth-core/