nextjs-hackathon-stack 0.1.35 → 0.1.37

package/dist/index.js

@@ -72,6 +72,25 @@ function getTemplateDir() {
 function processTemplate(content, vars) {
   return content.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? `{{${key}}}`);
 }
+function createClaudeDir(targetDir) {
+  const cursorDir = join(targetDir, ".cursor");
+  const claudeDir = join(targetDir, ".claude");
+  if (!existsSync(cursorDir)) return;
+  const mirrorDirs = ["agents", "rules", "skills"];
+  for (const dir of mirrorDirs) {
+    const srcDir = join(cursorDir, dir);
+    if (!existsSync(srcDir)) continue;
+    const destDir = join(claudeDir, dir);
+    mkdirSync(destDir, { recursive: true });
+    for (const entry of readdirSync(srcDir)) {
+      const relTarget = `../../.cursor/${dir}/${entry}`;
+      const destPath = join(destDir, entry);
+      if (!existsSync(destPath)) {
+        symlinkSync(relTarget, destPath);
+      }
+    }
+  }
+}
 function copyDir(src, dest, vars, skip = /* @__PURE__ */ new Set(), templateRoot = src) {
   mkdirSync(dest, { recursive: true });
   for (const entry of readdirSync(src)) {
@@ -133,21 +152,18 @@ export default async function HomePage() {
   );
 }
 `;
-var EMPTY_APP_SCHEMA = `import { pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
-import { createInsertSchema, createSelectSchema } from "drizzle-zod";
+var EMPTY_APP_BARREL = `export * from "./profiles.schema";
+`;
+var EMPTY_APP_DB_INDEX = `import { drizzle } from "drizzle-orm/postgres-js";
+import postgres from "postgres";
 
-export const profiles = pgTable("profiles", {
-  id: uuid("id").primaryKey(),
-  email: text("email").notNull().unique(),
-  createdAt: timestamp("created_at").notNull().defaultNow(),
-  updatedAt: timestamp("updated_at").notNull().defaultNow(),
-});
+import * as profiles from "./profiles.schema";
+
+const schema = { ...profiles };
 
-export const insertProfileSchema = createInsertSchema(profiles);
-export const selectProfileSchema = createSelectSchema(profiles);
+const client = postgres(process.env.DATABASE_URL ?? "");
 
-export type InsertProfile = typeof profiles.$inferInsert;
-export type SelectProfile = typeof profiles.$inferSelect;
+export const db = drizzle(client, { schema });
 `;
 var EMPTY_APP_PAGE_TEST = `import { describe, it, expect, vi, beforeEach } from "vitest";
 
@@ -196,7 +212,8 @@ describe("HomePage (protected)", () => {
 function buildSkipSet() {
   return /* @__PURE__ */ new Set([
     "src/features/todos",
-    "src/e2e/todos.spec.ts"
+    "src/e2e/todos.spec.ts",
+    "src/shared/db/todos.schema.ts"
   ]);
 }
 async function scaffold(projectName, skipInstall, skipMcp = false, template = "example") {
@@ -211,11 +228,13 @@ async function scaffold(projectName, skipInstall, skipMcp = false, template = "e
   const spinner2 = p3.spinner();
   spinner2.start("Copying template files");
   copyDir(templateDir, targetDir, vars, skip, templateDir);
+  createClaudeDir(targetDir);
   if (template === "empty") {
     const pageDir = join(targetDir, "src/app/(protected)");
     mkdirSync(pageDir, { recursive: true });
     writeFileSync(join(pageDir, "page.tsx"), EMPTY_APP_PAGE);
-    writeFileSync(join(targetDir, "src/shared/db/schema.ts"), EMPTY_APP_SCHEMA);
+    writeFileSync(join(targetDir, "src/shared/db/schema.ts"), EMPTY_APP_BARREL);
+    writeFileSync(join(targetDir, "src/shared/db/index.ts"), EMPTY_APP_DB_INDEX);
     const testDir = join(targetDir, "src/app/__tests__");
     mkdirSync(testDir, { recursive: true });
     writeFileSync(join(testDir, "protected-page.test.tsx"), EMPTY_APP_PAGE_TEST);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextjs-hackathon-stack",
-  "version": "0.1.35",
+  "version": "0.1.37",
   "description": "Scaffold a full-stack Next.js hackathon starter",
   "type": "module",
   "bin": {

package/template/.cursor/agents/backend.md

@@ -1,15 +1,18 @@
 ---
 name: backend
-description: Backend specialist for Node.js, Next.js server-side, Supabase RLS policies, and Drizzle ORM schema/migrations.
+description: Backend specialist for Node.js, Next.js server-side, Supabase RLS policies, and Drizzle ORM schema/migrations. Triggers: database changes, Server Actions, API routes, auth flows, schema definitions, RLS policies, migrations.
 model: inherit
 readonly: false
 ---
 
 # Backend Agent
 
-## First Step
+## First Step — Load Context via MCP Memory
 
-Read `.cursor/memory/architecture-snapshot.md` to understand the existing schema, features, and proven Server Action patterns before writing new code. Use the canonical pattern references to copy the correct structure.
+1. Read `package.json` to get the project name (`<project-name>`)
+2. Call `search_memory` with `tags: ["project:<project-name>", "domain:database"]` — existing tables and their columns
+3. Call `search_memory` with `tags: ["project:<project-name>", "domain:patterns"]` and `query: "server action"` — canonical Server Action pattern to copy
+4. **Fallback**: if the memory service is unavailable or returns no results, read `.cursor/memory/architecture-snapshot.md` directly
 
 ## Responsibilities
 - Build Next.js Server Actions, API routes, and middleware

package/template/.cursor/agents/business-intelligence.md

@@ -1,15 +1,17 @@
 ---
 name: business-intelligence
-description: Requirements analyst. Use when defining features, writing user stories, validating acceptance criteria, or creating requirements documentation.
+description: Requirements analyst (readonly). Discovers requirements through questions before defining anything. Triggers: new feature definition, writing requirements, user stories, acceptance criteria, requirements documentation, feature scope clarification.
 model: inherit
 readonly: true
 ---
 
 # Business Intelligence Agent
 
-## First Step
+## First Step — Load Context via MCP Memory
 
-Read `.cursor/memory/architecture-snapshot.md` to understand existing features before asking discovery questions. Use it to identify relationships with existing data and patterns.
+1. Read `package.json` to get the project name (`<project-name>`)
+2. Call `search_memory` with `tags: ["project:<project-name>", "domain:features"]` — existing features and their descriptions, to identify relationships with new requirements
+3. **Fallback**: if the memory service is unavailable or returns no results, read `.cursor/memory/architecture-snapshot.md` directly
 
 ## Responsibilities
 - Discover requirements through user questions before defining anything

package/template/.cursor/agents/code-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: code-reviewer
-description: Code review specialist. Use when reviewing branch changes, PRs, or MRs. Supports GitHub (gh) and GitLab (glab).
+description: Code review specialist (readonly, fast model). Reviews branch diffs and PRs against the project quality checklist. Supports GitHub (gh) and GitLab (glab). Triggers: review my branch, review PR, code review, check my changes.
 model: fast
 readonly: true
 ---
@@ -34,8 +34,8 @@ glab --version 2>/dev/null && echo "GitLab"
 
 ### Testing
 - [ ] Tests written BEFORE implementation (TDD)
-- [ ] 100% coverage on new/changed files
-- [ ] 100% BRANCH coverage (every if/else/ternary/catch)
+- [ ] ≥95% statement/function/line coverage on new/changed files
+- [ ] ≥90% branch coverage (every if/else/ternary/catch)
 - [ ] Behavior tested, not implementation
 - [ ] AAA pattern with labeled comments on every test
 - [ ] Tests NOT weakened (no removed assertions, no loosened matchers, no .skip)

package/template/.cursor/agents/frontend.md

@@ -1,15 +1,18 @@
 ---
 name: frontend
-description: UI specialist. Use when building components, pages, layouts, or any styling with Tailwind CSS v4 and shadcn/ui.
+description: UI specialist for React components, pages, layouts, Tailwind CSS v4, shadcn/ui, and accessibility. Triggers: building UI, styling, component creation, page layouts, client-side interactions, form UI, empty states, loading states.
 model: inherit
 readonly: false
 ---
 
 # Frontend Agent
 
-## First Step
+## First Step — Load Context via MCP Memory
 
-Read `.cursor/memory/architecture-snapshot.md` to see which shadcn/ui components are already installed before running `shadcn add`. Use the canonical component test reference to follow the established testing pattern.
+1. Read `package.json` to get the project name (`<project-name>`)
+2. Call `search_memory` with `tags: ["project:<project-name>", "domain:ui", "category:components"]` — installed shadcn/ui components (check before running `shadcn add`)
+3. Call `search_memory` with `tags: ["project:<project-name>", "domain:patterns"]` and `query: "component test"` — canonical component test reference to follow
+4. **Fallback**: if the memory service is unavailable or returns no results, read `.cursor/memory/architecture-snapshot.md` directly
 
 ## Responsibilities
 - Build accessible React components with shadcn/ui and Tailwind v4

package/template/.cursor/agents/security-researcher.md

@@ -1,6 +1,6 @@
 ---
 name: security-researcher
-description: Security auditor. Use when implementing auth, handling sensitive data, reviewing API routes, or auditing the codebase for vulnerabilities.
+description: Security auditor (readonly). Checks OWASP vulnerabilities, RLS gaps, exposed secrets, and missing auth checks. Triggers: security audit, check vulnerabilities, review auth, audit dependencies, check for secrets, RLS review.
 model: inherit
 readonly: true
 ---

package/template/.cursor/agents/technical-lead.md

@@ -1,6 +1,6 @@
 ---
 name: technical-lead
-description: Orchestrator and architecture owner. Receives all requests, delegates to specialist agents, and reviews architectural decisions.
+description: Orchestrator and architecture owner. Default entry point for all requests — breaks down tasks, delegates to specialists, and validates architecture. Triggers: new feature planning, architecture questions, task breakdown, multi-agent coordination, refactor planning.
 model: inherit
 # Note: `model: inherit` means this agent uses whatever model the user selected.
 # For security-critical reviews, consider switching to a more capable model explicitly.
@@ -9,9 +9,13 @@ readonly: false
 
 # Technical Lead Agent
 
-## First Step
+## First Step — Load Context via MCP Memory
 
-Read `.cursor/memory/architecture-snapshot.md` to understand the current project state before planning. Use it to identify which patterns to reuse and what already exists.
+1. Read `package.json` to get the project name (`<project-name>`)
+2. Call `search_memory` with `tags: ["project:<project-name>", "domain:features"]` — existing features and their paths
+3. Call `search_memory` with `tags: ["project:<project-name>", "domain:patterns"]` — canonical patterns to reuse
+4. Call `search_memory` with `tags: ["project:<project-name>", "domain:database"]` — current DB schema
+5. **Fallback**: if the memory service is unavailable or returns no results, read `.cursor/memory/architecture-snapshot.md` directly
 
 ## Responsibilities
 - Act as the default entry point for all requests
@@ -47,7 +51,7 @@ Delegate to the appropriate specialist based on domain:
 ## Workflow Sequences
 
 ### New feature
-@business-intelligence (functional issue) → @technical-lead (task breakdown + test plan) → @test-qa (RED) → **@backend + @frontend in parallel** (GREEN) → **@code-reviewer + @security-researcher in parallel**
+`/discover-feature` (Conversation 1) → `/build-feature` (Conversation 2, fresh) — planning, TDD, review, and memory sync are all automated inside `/build-feature`
 
 ### Bug fix
 @test-qa (reproduce with failing test) → @backend/@frontend (fix) → @code-reviewer

package/template/.cursor/agents/test-qa.md

@@ -1,15 +1,19 @@
 ---
 name: test-qa
-description: Testing specialist. Use proactively when code changes to write tests and ensure 100% coverage. Always write tests BEFORE implementation.
+description: Testing specialist. Use when writing tests, enforcing TDD workflow, fixing coverage gaps, or debugging test failures. Always write tests BEFORE implementation. Triggers: writing tests, TDD workflow, coverage gaps, test failures, mock setup.
 model: inherit
 readonly: false
 ---
 
 # Test & QA Agent
 
-## First Step
+## First Step — Load Context via MCP Memory
 
-Read `.cursor/memory/architecture-snapshot.md` to find the canonical test references. Import `makeChain` and `makeSupabaseMock` from `@/shared/test-utils/supabase-mock` — never recreate the mock chain from scratch.
+1. Read `package.json` to get the project name (`<project-name>`)
+2. Call `search_memory` with `tags: ["project:<project-name>", "domain:patterns"]` and `query: "test mock supabase"` — canonical test references and mock setup (`makeChain`, `makeSupabaseMock`)
+3. **Fallback**: if the memory service is unavailable or returns no results, read `.cursor/memory/architecture-snapshot.md` directly
+
+Import `makeChain` and `makeSupabaseMock` from `@/shared/test-utils/supabase-mock` — never recreate the mock chain from scratch.
 
 ## TDD Workflow
 
@@ -26,7 +30,7 @@ Each phase requires pasting the actual terminal output before proceeding:
 |------|---------|-----------------|
 | After RED | `pnpm test:unit` | All new tests **FAIL** (red) |
 | After GREEN | `pnpm test:unit` | All tests **PASS** (green) |
-| After VERIFY | `pnpm test:coverage` | 100% across all metrics |
+| After VERIFY | `pnpm test:coverage` | ≥95% statements/functions/lines, ≥90% branches |
 
 **Never say "tests pass" or "tests fail" without showing the actual output.**
 **Do NOT write any implementation code until the RED gate output confirms failures.**
@@ -37,16 +41,18 @@ Each phase requires pasting the actual terminal output before proceeding:
 
 ## Coverage Requirement
 ```
-branches: 100%
-functions: 100%
-lines: 100%
-statements: 100%
+branches: 90%
+functions: 95%
+lines: 95%
+statements: 95%
 ```
 
+Use `/* v8 ignore next */` for genuinely unreachable defensive branches only.
+
 After every change:
 1. Run `pnpm test:coverage`
-2. If below 100%, add missing tests
-3. Never mark work complete without full coverage
+2. If below thresholds, add missing tests
+3. Never mark work complete without meeting thresholds
 
 ## Supabase Mock Pattern
 
@@ -73,7 +79,7 @@ When the Technical Lead provides a test plan, follow it:
 - Flag missing edge cases to the TL **before** adding unplanned tests — do not expand scope unilaterally
 - If the plan is ambiguous or incomplete, ask for clarification rather than guessing
 
-For the full Server Action test template, see `create-feature` skill references.
+For the full Server Action test template, see `build-feature` skill references (`references/server-action-test-template.md`).
 
 ## Guardrails
 - Never write implementation without a failing test first

package/template/.cursor/memory/architecture-snapshot.md

@@ -47,4 +47,81 @@ Read these files to understand the project's proven patterns before writing new
 - Toast feedback required for every mutation (success + error) via `sonner`
 - RLS must be enabled on every table before a feature is considered complete
 - UI text: Spanish | Code-level text: English (test descriptions, variable names)
-- 100% test coverage — no exceptions
+- Coverage threshold: 95% statements/functions/lines, 90% branches — use `/* v8 ignore next */` for genuinely unreachable defensive branches
+
+## Shared Utilities
+
+Reuse these before writing new helpers:
+
+| Utility | Location | Purpose |
+|---------|----------|---------|
+| `formFieldText(formData, key)` | `src/shared/lib/form-utils.ts` | Safe `FormData` text extraction — avoids `no-base-to-string` lint error |
+| `firstZodIssueMessage(error)` | `src/shared/lib/zod-utils.ts` | Extract first Zod validation error message |
+| `readUploadFileBuffer(file)` | `src/shared/lib/upload-utils.ts` | Read a `File`/`Blob` upload to `ArrayBuffer` safely |
+
+## Strict Rules Reference
+
+Read this before writing any code. These are the rules that most often cause post-hoc fix cycles.
+
+### TypeScript Compiler (`tsconfig.json`)
+
+`"strict": true` plus additional flags:
+
+| Flag | What it enforces | How to comply |
+|------|-----------------|---------------|
+| `noUncheckedIndexedAccess` | `arr[i]` / `obj[key]` return `T \| undefined` | Guard: `const val = arr[0]; if (val) { ... }` |
+| `exactOptionalPropertyTypes` | Cannot assign `undefined` to optional props | Omit the key entirely; never write `{ prop: undefined }` |
+| `noImplicitOverride` | Subclass overrides need `override` keyword | `override render() {}` |
+| `noFallthroughCasesInSwitch` | Every `case` needs `break`/`return`/`throw` | Add `break` to every case |
+| `noImplicitReturns` | Every code path must return | Add explicit `return` in all branches |
+| `noUnusedLocals` / `noUnusedParameters` | No unused vars/params | Prefix unused params with `_` |
+| `useUnknownInCatchVariables` | `catch (e)` → `e` is `unknown` | Narrow: `if (e instanceof Error)` before `.message` |
+
+### ESLint — Rules That Most Often Trip AI Agents
+
+Preset: `tseslint.configs.strictTypeChecked` + `stylisticTypeChecked`. Runs with `--max-warnings 0` (warnings = errors).
+
+**Unsafe-any family (all "error"):**
+- `no-unsafe-assignment`, `no-unsafe-member-access`, `no-unsafe-call`, `no-unsafe-return`, `no-unsafe-argument`
+- Never let `any` flow through. Cast `JSON.parse()` results. Type all mock returns explicitly.
+
+**Promise handling:**
+- `no-floating-promises`: Every Promise must be `await`ed, returned, or `void`-prefixed
+- `no-misused-promises`: Async functions in React event handlers need a `void` wrapper: `onClick={() => void handleSubmit()}`
+- `require-await`: `async` functions must contain `await`; remove `async` if not needed
+- `return-await`: Must use `return await` inside `try/catch`
+
+**Type safety:**
+- `no-explicit-any`: Use `unknown` and narrow; never use `any`
+- `no-non-null-assertion`: Cannot use `!` postfix; narrow with conditionals
+- `no-base-to-string`: Objects without `toString()` cannot appear in template literals or string concatenation — use `formFieldText()` for `FormData` values
+- `restrict-template-expressions`: Template literals only accept `string | number | boolean`
+- `no-unnecessary-condition`: Don't check conditions that are always truthy/falsy per types
+- `unbound-method`: Don't detach methods from objects; bind or use arrow functions
+- `only-throw-error`: Only throw `Error` instances, never strings or plain objects
+- `use-unknown-in-catch-callback-variable`: `.catch(err => ...)` — `err` must be `unknown`
+
+**Imports & style:**
+- `consistent-type-imports`: Use `import type { X }` for type-only imports
+- `import-x/order`: Imports grouped (builtin → external → internal → parent → sibling → index), alphabetized, blank lines between groups
+- `no-inferrable-types`: Don't annotate types TS can infer (`const count: number = 0` → `const count = 0`)
+- `prefer-optional-chain`: Use `?.` instead of `&&` chains
+- `prefer-nullish-coalescing`: Use `??` instead of `||` for nullable defaults
+- `consistent-type-definitions`: Prefer `interface` over `type` for object shapes
+- `array-type`: Use `T[]` not `Array<T>`
+
+**React-specific:**
+- `react-hooks/rules-of-hooks`: Hooks only at top level of components/custom hooks
+- `react-hooks/exhaustive-deps`: All reactive values must be in hook dependency arrays
+
+**Console:**
+- `no-console`: warn — but `--max-warnings 0` makes it an error. Only allowed in `**/error.tsx`.
+
+**Test files (`.test.ts`, `.test.tsx`):**
+- `vitest/expect-expect`: Every test must have an assertion
+- `vitest/no-identical-title`: Test titles must be unique
+- `vitest/no-conditional-expect`: No `expect()` inside conditionals
+
+### File-specific exceptions
+- `**/error.tsx`: `no-console` disabled (Next.js error boundaries)
+- `src/shared/lib/supabase/server.ts`, `middleware.ts`: `no-deprecated` disabled (Supabase SSR)

package/template/.cursor/rules/architecture.mdc

@@ -45,3 +45,4 @@ If two features share logic, move it to `shared/`.
 - Return typed result objects, use `redirect()` for navigation
 - Actions that mutate data must return `ActionResult` from `@/shared/lib/action-result` — never return `void`
 - The calling component is responsible for showing `toast.success()` / `toast.error()` based on the result
+- NEVER import or call client-only APIs inside server actions (`toast` from sonner, React hooks, `window`, `document`). Server actions run on the server where these APIs do not exist and will throw at runtime.

package/template/.cursor/rules/coding-standards.mdc

@@ -41,7 +41,7 @@ Follow the RED → GREEN → REFACTOR cycle. See `testing.mdc` for the full rule
 - Always handle Promise rejections
 
 ## Types
-- Prefer `type` over `interface` for data shapes
+- Prefer `interface` for object shapes (enforced by ESLint `consistent-type-definitions`). Use `type` for unions, intersections, and utility types.
 - Use `satisfies` for type-checked literals
 - Use `as const` for immutable literals
 - **Never use `as` type assertions for data from external sources** (DB, API, user input). Use Zod `.parse()` or `.safeParse()` to validate and type runtime data. `as const` is acceptable for literals.
@@ -76,7 +76,7 @@ it("retorna error si el candidato no existe", async () => { ... });
 ## Coverage Exclusions (configure upfront, not reactively)
 
 Before writing tests, add exclusions to `vitest.config.ts` for:
-- Drizzle schema definition files (`src/shared/db/schema.ts`)
+- Drizzle schema definition files (`src/shared/db/*.schema.ts`)
 - Pure type files (files with only `type`/`interface` exports, no runtime logic)
 - Third-party UI wrapper components that rely on portals or browser APIs not supported in jsdom (e.g., `sonner.tsx`, toast providers)
 
@@ -86,7 +86,7 @@ Configure these exclusions **before writing tests** to avoid reactive coverage f
 // vitest.config.ts
 coverage: {
   exclude: [
-    "src/shared/db/schema.ts",
+    "src/shared/db/*.schema.ts",
     "src/shared/components/ui/sonner.tsx",
     // add other portal/type-only files here
   ],
@@ -96,6 +96,6 @@ coverage: {
 ## Pre-commit Quality Gates
 Every commit must pass two sequential gates:
 1. **lint-staged** — runs `eslint --max-warnings 0` on staged `.ts/.tsx` files. Any lint warning or error blocks the commit immediately (before the slower test suite runs).
-2. **Full test suite** — runs `vitest run --coverage` with 100% branch/function/line/statement coverage required.
+2. **Full test suite** — runs `vitest run --coverage` with 95% statement/function/line and 90% branch coverage required.
 
 Code that fails either gate cannot be committed.

package/template/.cursor/rules/forms.mdc

@@ -64,6 +64,8 @@ Share the Zod schema between client and server from a single source (e.g., `lib/
 
 ## Toast Feedback
 
+> **⚠️ Toast calls belong in client components ONLY.** Never import `sonner` or call `toast()` inside a `"use server"` file. The server action returns `ActionResult`; the component reads the result and shows the toast.
+
 Every action that affects the database MUST show a toast to the user. No mutation should complete silently.
 
 - Use `toast.success(message)` for successful operations

package/template/.cursor/rules/general.mdc

@@ -1,7 +1,6 @@
 ---
-description: Stack overview and project conventions. Applies to all source files.
-alwaysApply: false
-globs: ["src/**"]
+description: Stack overview and project conventions. Always loaded — defines the technology stack, project structure, and naming conventions for this project.
+alwaysApply: true
 ---
 
 # Stack Overview

package/template/.cursor/rules/supabase.mdc

@@ -61,7 +61,7 @@ Files in `src/shared/db/migrations/` are **auto-generated** by Drizzle CLI — n
 | `pnpm db:migrate` | Apply pending migrations to the database |
 | `pnpm db:push` | Push schema directly to DB (dev only, no migration file) |
 
-Workflow: edit `src/shared/db/schema.ts` → `pnpm db:generate` → review SQL → `pnpm db:migrate`
+Workflow: edit `src/shared/db/<table>.schema.ts` → `pnpm db:generate` → review SQL → `pnpm db:migrate`
 
 ## Environment Variables
 - `NEXT_PUBLIC_SUPABASE_URL` + `NEXT_PUBLIC_SUPABASE_ANON_KEY` — client-safe, used in browser + server

package/template/.cursor/rules/testing.mdc

@@ -8,7 +8,7 @@ globs: ["**/*.test.*", "**/e2e/**"]
 ## Iron Rules (Non-Negotiable)
 1. **NEVER modify a test to make it pass** — always fix the implementation code. Tests define the contract. If a test fails, the code is wrong, not the test.
 2. **Tests are immutable during GREEN phase** — only modify tests in RED phase (writing new ones) or REFACTOR phase (improving structure, never weakening assertions)
-3. **100% branch coverage** — every `if`, `else`, `switch`, `??`, `?.`, ternary, and `catch` must be exercised
+3. **Coverage thresholds** — 95% statements/functions/lines, 90% branches. Use `/* v8 ignore next */` only for genuinely unreachable defensive branches
 4. **Every edge case gets a test** — null/undefined, empty string, empty array, boundary values, error responses, timeout, concurrent calls
 5. **AAA is mandatory** — every test uses Arrange-Act-Assert with labeled comments
 
@@ -124,10 +124,12 @@ jsdom does not implement all browser APIs. Hitting these in tests causes failure
 // vitest.config.ts
 coverage: {
   thresholds: {
-    branches: 100,
-    functions: 100,
-    lines: 100,
-    statements: 100,
+    branches: 90,
+    functions: 95,
+    lines: 95,
+    statements: 95,
   },
 }
 ```
+
+Use `/* v8 ignore next */` for genuinely unreachable defensive branches (e.g., exhaustive `switch` default arms, type narrowing guards that cannot be hit at runtime).