@tekyzinc/gsd-t 2.50.11 → 2.50.12

package/CHANGELOG.md

@@ -2,16 +2,24 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
-## [2.50.10] - 2026-03-25
+## [2.50.12] - 2026-03-25
 
 ### Added
-- **18 new stack rule files** — python, flutter, tailwind, react-native, vite, nextjs, vue, docker, postgresql (with graph-in-SQL section), github-actions, rest-api, supabase, firebase, graphql, zustand, redux, neo4j, playwright. Total: 22 stack rules (was 4).
+- **23 new stack rule files** — python, flutter, tailwind, react-native, vite, nextjs, vue, docker, postgresql (with graph-in-SQL section), github-actions, rest-api, supabase, firebase, graphql, zustand, redux, neo4j, playwright, fastapi, llm (with RAG patterns section), prisma, queues, _auth (universal). Total: 27 stack rules (was 4).
+- **`_auth.md`** (universal) — email-first registration, auth provider abstraction (Cognito/Firebase/Google), token management, password policy, session management, social auth/OAuth, email verification, MFA, authorization/RBAC, auth security, auth UI patterns.
+- **`fastapi.md`** — dependency injection, Pydantic request/response models, lifespan events, BackgroundTasks, async patterns, auto-generated OpenAPI docs.
+- **`llm.md`** — provider-agnostic LLM patterns: structured outputs, streaming, error/retry, token management, conversation state, tool/function calling, RAG patterns (chunking, embeddings, retrieval), prompt management, testing, cost/observability.
+- **`prisma.md`** — schema modeling, migrations, typed client usage, relation queries, transactions, seeding, N+1 prevention.
+- **`queues.md`** — BullMQ/Bull, SQS, RabbitMQ, Celery patterns: idempotent handlers, dead letter queues, retry/backoff, job deduplication, graceful shutdown.
 - **Playwright best practices** — coverage matrix per feature, pairwise combinatorial testing, state transition testing, multi-step workflow testing, Page Object Model, API mocking patterns. Enforces rigorous test depth across permutations.
 - **react.md expanded** — added state management decision table, form management (react-hook-form + zod), React naming conventions (3 new sections from external best practices review).
+- **Project-level stack overrides** — `.gsd-t/stacks/` directory for per-project customization of global stack rules. Local files replace global files of the same name.
 
 ### Changed
-- Stack detection in execute, quick, and debug commands updated to cover all 22 stack files with conditional detection per project dependencies.
+- Stack detection in execute, quick, and debug commands updated to cover all 27 stack files with conditional detection per project dependencies.
+- Detection refactored from one-liner to structured bash with `_sf()` (local override resolver) and `_add()` helper functions.
 - PostgreSQL graph-in-SQL patterns (adjacency lists, junction tables, recursive CTEs) added to postgresql.md based on real project analysis.
+- GSD-T-README.md stack detection table expanded to list all 27 files with their detection triggers.
 
 ## [2.46.11] - 2026-03-24
 

package/commands/gsd-t-debug.md

@@ -37,10 +37,16 @@ if [ -d "$STACKS_DIR" ]; then
     grep -q '"@reduxjs/toolkit"' package.json 2>/dev/null && _add redux.md
     grep -q '"neo4j-driver"' package.json 2>/dev/null && _add neo4j.md
     grep -qE '"(pg|prisma|drizzle-orm|knex)"' package.json 2>/dev/null && _add postgresql.md
+    grep -qE '"(prisma|@prisma/client)"' package.json 2>/dev/null && _add prisma.md
+    grep -qE '"(bullmq|bull|amqplib|@aws-sdk/client-sqs|bee-queue|agenda)"' package.json 2>/dev/null && _add queues.md
+    grep -qE '"(openai|anthropic|@anthropic-ai/sdk|langchain|llama-index|@google/generative-ai)"' package.json 2>/dev/null && _add llm.md
   fi
   ([ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -f "Pipfile" ]) && _add python.md
   ([ -f "requirements.txt" ] && grep -q "psycopg" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -q "psycopg" pyproject.toml 2>/dev/null) && _add postgresql.md
   ([ -f "requirements.txt" ] && grep -q "neo4j" requirements.txt 2>/dev/null) && _add neo4j.md
+  ([ -f "requirements.txt" ] && grep -q "fastapi" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -q "fastapi" pyproject.toml 2>/dev/null) && _add fastapi.md
+  ([ -f "requirements.txt" ] && grep -qE "(celery|dramatiq|rq|arq)" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -qE "(celery|dramatiq|rq|arq)" pyproject.toml 2>/dev/null) && _add queues.md
+  ([ -f "requirements.txt" ] && grep -qE "(openai|anthropic|langchain|llama.index)" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -qE "(openai|anthropic|langchain|llama.index)" pyproject.toml 2>/dev/null) && _add llm.md
   [ -f "pubspec.yaml" ] && _add flutter.md
   [ -f "Dockerfile" ] && _add docker.md
   [ -d ".github/workflows" ] && _add github-actions.md

package/commands/gsd-t-execute.md

@@ -156,12 +156,18 @@ if [ -d "$STACKS_DIR" ]; then
     grep -q '"@reduxjs/toolkit"' package.json 2>/dev/null && _add redux.md
     grep -q '"neo4j-driver"' package.json 2>/dev/null && _add neo4j.md
     grep -qE '"(pg|prisma|drizzle-orm|knex)"' package.json 2>/dev/null && _add postgresql.md
+    grep -qE '"(prisma|@prisma/client)"' package.json 2>/dev/null && _add prisma.md
+    grep -qE '"(bullmq|bull|amqplib|@aws-sdk/client-sqs|bee-queue|agenda)"' package.json 2>/dev/null && _add queues.md
+    grep -qE '"(openai|anthropic|@anthropic-ai/sdk|langchain|llama-index|@google/generative-ai)"' package.json 2>/dev/null && _add llm.md
   fi
 
   # File-based detection (no package.json needed)
   ([ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -f "Pipfile" ]) && _add python.md
   ([ -f "requirements.txt" ] && grep -q "psycopg" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -q "psycopg" pyproject.toml 2>/dev/null) && _add postgresql.md
   ([ -f "requirements.txt" ] && grep -q "neo4j" requirements.txt 2>/dev/null) && _add neo4j.md
+  ([ -f "requirements.txt" ] && grep -q "fastapi" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -q "fastapi" pyproject.toml 2>/dev/null) && _add fastapi.md
+  ([ -f "requirements.txt" ] && grep -qE "(celery|dramatiq|rq|arq)" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -qE "(celery|dramatiq|rq|arq)" pyproject.toml 2>/dev/null) && _add queues.md
+  ([ -f "requirements.txt" ] && grep -qE "(openai|anthropic|langchain|llama.index)" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -qE "(openai|anthropic|langchain|llama.index)" pyproject.toml 2>/dev/null) && _add llm.md
   [ -f "pubspec.yaml" ] && _add flutter.md
   [ -f "Dockerfile" ] && _add docker.md
   [ -d ".github/workflows" ] && _add github-actions.md

package/commands/gsd-t-help.md

@@ -258,7 +258,7 @@ Use these when user asks for help on a specific command:
 - **Use when**: Ready to implement
 - **Note (M22)**: Task-level fresh dispatch (one subagent per task, ~10-20% context each). Team mode uses worktree isolation (`isolation: "worktree"`) — zero file conflicts. Adaptive replanning between domain completions.
 - **Note (M26)**: Active rule injection — evaluates declarative rules from rules.jsonl before dispatching each domain's tasks. Fires matching rules as warnings in subagent prompts.
-- **Note (M29)**: Stack Rules Engine — auto-detects project tech stack from manifest files and injects mandatory best-practice rules into each task subagent prompt. Universal rules (`_security.md`) always apply; stack-specific rules layer on top. Violations are task failures (same weight as contract violations).
+- **Note (M29)**: Stack Rules Engine — auto-detects project tech stack from manifest files and injects mandatory best-practice rules into each task subagent prompt. Universal rules (`_security.md`, `_auth.md`) always apply; stack-specific rules layer on top. Violations are task failures (same weight as contract violations).
 
 ### test-sync
 - **Summary**: Keep tests aligned with code changes

package/commands/gsd-t-quick.md

@@ -41,10 +41,16 @@ if [ -d "$STACKS_DIR" ]; then
     grep -q '"@reduxjs/toolkit"' package.json 2>/dev/null && _add redux.md
     grep -q '"neo4j-driver"' package.json 2>/dev/null && _add neo4j.md
     grep -qE '"(pg|prisma|drizzle-orm|knex)"' package.json 2>/dev/null && _add postgresql.md
+    grep -qE '"(prisma|@prisma/client)"' package.json 2>/dev/null && _add prisma.md
+    grep -qE '"(bullmq|bull|amqplib|@aws-sdk/client-sqs|bee-queue|agenda)"' package.json 2>/dev/null && _add queues.md
+    grep -qE '"(openai|anthropic|@anthropic-ai/sdk|langchain|llama-index|@google/generative-ai)"' package.json 2>/dev/null && _add llm.md
   fi
   ([ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -f "Pipfile" ]) && _add python.md
   ([ -f "requirements.txt" ] && grep -q "psycopg" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -q "psycopg" pyproject.toml 2>/dev/null) && _add postgresql.md
   ([ -f "requirements.txt" ] && grep -q "neo4j" requirements.txt 2>/dev/null) && _add neo4j.md
+  ([ -f "requirements.txt" ] && grep -q "fastapi" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -q "fastapi" pyproject.toml 2>/dev/null) && _add fastapi.md
+  ([ -f "requirements.txt" ] && grep -qE "(celery|dramatiq|rq|arq)" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -qE "(celery|dramatiq|rq|arq)" pyproject.toml 2>/dev/null) && _add queues.md
+  ([ -f "requirements.txt" ] && grep -qE "(openai|anthropic|langchain|llama.index)" requirements.txt 2>/dev/null || [ -f "pyproject.toml" ] && grep -qE "(openai|anthropic|langchain|llama.index)" pyproject.toml 2>/dev/null) && _add llm.md
   [ -f "pubspec.yaml" ] && _add flutter.md
   [ -f "Dockerfile" ] && _add docker.md
   [ -d ".github/workflows" ] && _add github-actions.md

package/docs/GSD-T-README.md

@@ -231,20 +231,42 @@ GSD-T auto-detects your project's tech stack and injects mandatory best-practice
 ### How It Works
 
 1. At subagent spawn time, GSD-T reads project manifest files to detect the active stack(s).
-2. Universal rules (`templates/stacks/_security.md`) are **always** injected.
+2. Universal rules (`templates/stacks/_security.md`, `_auth.md`) are **always** injected.
 3. Stack-specific rules are injected when the corresponding stack is detected.
-4. Rules are appended to the subagent prompt as a `## Stack Rules (MANDATORY)` section.
+4. Project-level overrides in `.gsd-t/stacks/` replace global files of the same name.
+5. Rules are appended to the subagent prompt as a `## Stack Rules (MANDATORY)` section.
 
-### Stack Detection
+### Stack Detection (27 files)
 
-| Project File | Detected Stack |
+| Project File | Detected Stack(s) |
 |---|---|
-| `package.json` with `"react"` | React |
-| `package.json` with `"typescript"` or `tsconfig.json` | TypeScript |
-| `package.json` with `"express"`, `"fastify"`, `"hono"`, or `"koa"` | Node API |
-| `requirements.txt` or `pyproject.toml` | Python |
-| `go.mod` | Go |
-| `Cargo.toml` | Rust |
+| *(always)* | `_security.md`, `_auth.md` |
+| `package.json` with `"react"` | `react.md` |
+| `package.json` with `"react-native"` | `react-native.md` |
+| `package.json` with `"next"` | `nextjs.md` |
+| `package.json` with `"vue"` | `vue.md` |
+| `package.json` with `"typescript"` or `tsconfig.json` | `typescript.md` |
+| `package.json` with `"tailwindcss"` | `tailwind.md` |
+| `package.json` with `"express"`, `"fastify"`, `"hono"`, or `"koa"` | `node-api.md`, `rest-api.md` |
+| `package.json` with `"vite"` | `vite.md` |
+| `package.json` with `"@supabase/supabase-js"` | `supabase.md` |
+| `package.json` with `"firebase"` | `firebase.md` |
+| `package.json` with `"graphql"` or `"@apollo/server"` | `graphql.md` |
+| `package.json` with `"zustand"` | `zustand.md` |
+| `package.json` with `"@reduxjs/toolkit"` | `redux.md` |
+| `package.json` with `"prisma"` or `"@prisma/client"` | `prisma.md` |
+| `package.json` with `"pg"`, `"knex"`, or `"drizzle-orm"` | `postgresql.md` |
+| `package.json` with `"neo4j-driver"` | `neo4j.md` |
+| `package.json` with `"bullmq"`, `"bull"`, `"amqplib"`, or `"@aws-sdk/client-sqs"` | `queues.md` |
+| `package.json` with `"openai"`, `"anthropic"`, `"langchain"` | `llm.md` |
+| `Dockerfile` or `compose.yaml` | `docker.md` |
+| `.github/workflows/*.yml` | `github-actions.md` |
+| `playwright.config.*` | `playwright.md` |
+| `requirements.txt` or `pyproject.toml` | `python.md` |
+| `requirements.txt` with `fastapi` | `fastapi.md` |
+| `requirements.txt` with `celery`, `dramatiq`, `rq`, or `arq` | `queues.md` |
+| `requirements.txt` with `openai`, `anthropic`, `langchain` | `llm.md` |
+| `pubspec.yaml` | `flutter.md` |
 
 ### Commands That Inject Stack Rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.50.11",
+  "version": "2.50.12",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 51 slash commands with headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/stacks/_auth.md

@@ -0,0 +1,324 @@
+# Authentication Standards (Universal — All Projects)
+
+These rules are MANDATORY. Violations fail the task. No exceptions.
+
+---
+
+## 1. Registration — Email-First, Password-Later
+
+```
+MANDATORY:
+  ├── Signup collects email + app-specific fields only — NO password at registration
+  ├── After signup, send a "set your password" email (same flow as forgot password)
+  ├── The set-password link is a one-time, time-limited token (15-60 minutes)
+  ├── User clicks link → lands on set-password page → sets their password → logged in
+  ├── This eliminates: temporary passwords, forced password changes, password-in-transit risks
+  └── If the link expires, user can request a new one (same as forgot password)
+```
+
+**Why one flow**: "Set password" and "Forgot password" are the same operation — generate a token, email a link, user sets a password. Building them as one flow halves the auth code and guarantees consistent behavior.
+
+**GOOD**
+```
+1. User submits: { email, name, [app-specific fields] }
+2. Server creates account (no password set, status: pending_verification)
+3. Server sends email: "Welcome! Set your password: [link with token]"
+4. User clicks link → set-password page
+5. User sets password → account activated → logged in
+6. If link expires → user clicks "Resend" → same flow
+```
+
+---
+
+## 2. Provider Abstraction
+
+```
+MANDATORY:
+  ├── Wrap the auth provider behind an AuthService interface
+  ├── Application code NEVER calls Cognito/Firebase/Google/Supabase Auth directly
+  ├── AuthService exposes: signup, login, logout, resetPassword, refreshToken, getCurrentUser
+  ├── Switching providers = rewrite AuthService implementation, not the entire app
+  └── Auth provider config (pool IDs, client IDs, URLs) lives in env vars — not in code
+```
+
+**GOOD**
+```typescript
+// auth/AuthService.ts — interface
+interface AuthService {
+  signup(email: string, metadata?: Record<string, string>): Promise<{ userId: string }>;
+  login(email: string, password: string): Promise<AuthTokens>;
+  logout(): Promise<void>;
+  sendPasswordResetEmail(email: string): Promise<void>;
+  setPassword(token: string, newPassword: string): Promise<void>;
+  refreshToken(refreshToken: string): Promise<AuthTokens>;
+  getCurrentUser(): Promise<User | null>;
+}
+
+// auth/providers/CognitoAuthService.ts — implementation
+// auth/providers/FirebaseAuthService.ts — implementation
+// auth/providers/SupabaseAuthService.ts — implementation
+```
+
+**BAD** — calling provider directly in components:
+```typescript
+import { signInWithEmailAndPassword } from 'firebase/auth';
+// Scattered across 15 components, impossible to switch providers
+```
+
+---
+
+## 3. Token Management
+
+```
+MANDATORY:
+  ├── Access tokens: short-lived (15-60 minutes)
+  ├── Refresh tokens: longer-lived (7-30 days), used to get new access tokens
+  ├── Web: store tokens in httpOnly, secure, sameSite cookies — NEVER localStorage
+  ├── Mobile (React Native/Flutter): use platform secure storage (Keychain/Keystore)
+  ├── Auto-refresh: intercept 401 responses, refresh token, retry the request
+  ├── NEVER store tokens in JavaScript-accessible storage (localStorage, sessionStorage)
+  └── NEVER send tokens in URL query parameters
+```
+
+**GOOD** — auto-refresh interceptor:
+```typescript
+api.interceptors.response.use(
+  (response) => response,
+  async (error) => {
+    if (error.response?.status === 401 && !error.config._retry) {
+      error.config._retry = true;
+      const newTokens = await authService.refreshToken(getRefreshToken());
+      setTokens(newTokens);
+      error.config.headers.Authorization = `Bearer ${newTokens.accessToken}`;
+      return api(error.config);
+    }
+    return Promise.reject(error);
+  }
+);
+```
+
+---
+
+## 4. Password Policy
+
+```
+MANDATORY:
+  ├── Minimum 8 characters — no maximum (allow up to 128)
+  ├── Require mix of: uppercase, lowercase, number, special character
+  ├── Check against common password list (top 10,000) — reject "Password123!"
+  ├── Show password strength indicator in real-time as user types
+  ├── Allow paste into password fields — NEVER disable paste
+  ├── NEVER store plaintext passwords — hashing is server-side only (bcrypt/argon2)
+  ├── NEVER transmit password requirements to the client beyond the UI hints
+  └── Rate-limit login attempts: lock after 5 failed attempts for 15 minutes
+```
+
+---
+
+## 5. Session Management
+
+```
+MANDATORY:
+  ├── Logout clears ALL state: tokens, cached user data, in-memory state
+  ├── Logout invalidates the refresh token server-side (not just client delete)
+  ├── Session timeout: auto-logout after inactivity period (configurable per app)
+  ├── Multi-tab sync (web): logout in one tab logs out all tabs
+  ├── Token expiry: show "session expired" message, redirect to login
+  ├── NEVER keep stale auth state — if token refresh fails, force logout
+  └── On app startup: validate the stored token before showing authenticated UI
+```
+
+**GOOD** — multi-tab logout sync:
+```typescript
+// Listen for storage events (fires when another tab changes storage)
+window.addEventListener('storage', (event) => {
+  if (event.key === 'logout-event') {
+    authService.clearLocalState();
+    window.location.href = '/login';
+  }
+});
+
+// On logout, broadcast to other tabs
+function logout() {
+  localStorage.setItem('logout-event', Date.now().toString());
+  localStorage.removeItem('logout-event');
+  authService.logout();
+}
+```
+
+---
+
+## 6. Social Auth / OAuth
+
+```
+WHEN SUPPORTING SOCIAL LOGIN:
+  ├── Use OAuth 2.0 / OpenID Connect — NEVER custom social auth flows
+  ├── Handle "email already exists" — offer to link accounts, don't create duplicates
+  ├── Store the provider + provider user ID alongside the local account
+  ├── Social login creates a local account on first use (same as email signup, but pre-verified)
+  ├── Allow users to set a password later (to enable email+password login alongside social)
+  ├── NEVER trust the email from the OAuth provider without verifying it's the same user
+  └── Implement PKCE for public clients (SPAs, mobile apps)
+```
+
+**Account linking flow:**
+```
+1. User clicks "Sign in with Google" → OAuth flow → returns email: jane@example.com
+2. Server checks: does jane@example.com already have an account?
+   YES → Link Google provider to existing account → login
+   NO  → Create new account with Google as primary provider → login
+3. User can later set a password to also use email+password login
+```
+
+---
+
+## 7. Email Verification
+
+```
+MANDATORY:
+  ├── Email must be verified before account is fully activated
+  ├── Verification link = one-time token, expires in 24 hours
+  ├── Unverified accounts: allow login but restrict access (show "verify your email" banner)
+  ├── Resend verification: rate-limit to 3 per hour
+  ├── After email change: re-verify the new email before switching
+  └── NEVER expose whether an email is registered (prevents enumeration)
+```
+
+**Anti-enumeration pattern:**
+```
+// BAD — reveals whether email exists
+"No account found for jane@example.com"
+
+// GOOD — same message regardless
+"If an account exists for this email, you'll receive a password reset link"
+```
+
+---
+
+## 8. Multi-Factor Authentication (MFA)
+
+```
+WHEN MFA IS REQUIRED:
+  ├── Support TOTP (authenticator app) as primary — SMS as fallback only
+  ├── Provide recovery codes (8-10 one-time codes) during MFA setup
+  ├── Store recovery codes hashed — display only once during setup
+  ├── MFA enrollment: optional by default, mandatory for admin/elevated roles
+  ├── Remember device: offer "trust this device for 30 days" option
+  └── NEVER use email as a second factor — it's the same channel as password reset
+```
+
+---
+
+## 9. Authorization Patterns
+
+```
+MANDATORY:
+  ├── Role-based access control (RBAC): define roles with explicit permissions
+  ├── Check permissions server-side on EVERY request — client checks are UI hints only
+  ├── Define roles as enums: ADMIN, MEMBER, VIEWER — not strings
+  ├── Permission check: can(user, action, resource) — not role string comparison
+  ├── UI: hide or disable actions the user can't perform — don't show then reject
+  ├── API: return 403 Forbidden for unauthorized actions — not 404
+  └── NEVER derive permissions from user properties — use explicit role → permission mapping
+```
+
+**GOOD**
+```typescript
+// Define permissions explicitly
+const ROLE_PERMISSIONS: Record<UserRole, Permission[]> = {
+  [UserRole.ADMIN]: ['users:read', 'users:write', 'users:delete', 'settings:write'],
+  [UserRole.MEMBER]: ['users:read', 'users:write'],
+  [UserRole.VIEWER]: ['users:read'],
+};
+
+function can(user: User, permission: Permission): boolean {
+  return ROLE_PERMISSIONS[user.role]?.includes(permission) ?? false;
+}
+
+// In API handler
+if (!can(currentUser, 'users:delete')) {
+  throw new ForbiddenError('Insufficient permissions');
+}
+```
+
+---
+
+## 10. Auth-Related Security
+
+```
+MANDATORY:
+  ├── All auth endpoints over HTTPS — no exceptions
+  ├── CSRF protection on auth forms (use framework's built-in CSRF tokens)
+  ├── Brute force protection: rate-limit login, lock after N failures
+  ├── Password reset tokens: single-use, time-limited, cryptographically random
+  ├── Log all auth events: login, logout, failed attempts, password changes, MFA events
+  ├── NEVER log passwords, tokens, or session IDs — even in error logs
+  ├── NEVER include auth tokens in URLs — use headers or cookies
+  └── Rotate signing keys periodically (JWT secret, cookie signing key)
+```
+
+---
+
+## 11. Auth UI Patterns
+
+```
+MANDATORY:
+  ├── Login form: email + password + "Forgot password?" link + social login buttons
+  ├── Signup form: email + app-specific fields + "Already have an account?" link
+  ├── Forgot password: email input → "Check your email" (same message regardless of email existence)
+  ├── Set password: new password + confirm password + strength indicator
+  ├── Loading state on all auth buttons — disable during submission
+  ├── Show/hide password toggle on password fields
+  ├── Preserve form data on validation errors — don't clear the form
+  └── Redirect to intended destination after login (not always to homepage)
+```
+
+**Redirect after login:**
+```typescript
+// Before redirecting to login, store the intended URL
+const returnUrl = window.location.pathname;
+router.push(`/login?returnUrl=${encodeURIComponent(returnUrl)}`);
+
+// After successful login
+const returnUrl = searchParams.get('returnUrl') || '/dashboard';
+router.push(returnUrl);
+```
+
+---
+
+## 12. Anti-Patterns
+
+```
+NEVER:
+  ├── Password at registration — use email-first, set-password-later flow
+  ├── Tokens in localStorage — use httpOnly cookies (web) or secure storage (mobile)
+  ├── Tokens in URL query parameters
+  ├── Calling auth provider directly from components — use AuthService abstraction
+  ├── Revealing whether an email is registered ("no account found for...")
+  ├── Client-side-only permission checks — always enforce server-side
+  ├── Same message for login failure types ("wrong password" vs "account locked")
+  ├── Disabling paste on password fields
+  ├── Email as a second factor for MFA
+  ├── Storing plaintext passwords or unhashed recovery codes
+  └── Silent token expiry — always inform the user and redirect to login
+```
+
+---
+
+## Auth Verification Checklist
+
+- [ ] Signup is email-first — no password at registration
+- [ ] Set-password and forgot-password share the same token-based flow
+- [ ] Auth provider wrapped in AuthService interface — no direct provider calls
+- [ ] Tokens stored in httpOnly cookies (web) or secure storage (mobile)
+- [ ] Access tokens short-lived with auto-refresh on 401
+- [ ] Logout clears all state and invalidates refresh token server-side
+- [ ] Multi-tab logout sync (web)
+- [ ] Password policy enforced with strength indicator
+- [ ] Login rate-limited — lock after 5 failed attempts
+- [ ] Email enumeration prevented (same response for existing/non-existing emails)
+- [ ] Social auth handles account linking for existing emails
+- [ ] Permissions checked server-side on every request
+- [ ] Roles defined as enums with explicit permission mapping
+- [ ] All auth events logged (no tokens/passwords in logs)
+- [ ] Redirect to intended destination after login