specweave 1.0.78 → 1.0.79

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "1.0.78",
+  "version": "1.0.79",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

package/src/templates/CLAUDE.md.template

@@ -86,75 +86,20 @@ grep -ril "keyword" .specweave/docs/internal/
 <!-- /SECTION -->
 
 <!-- SECTION:lsp -->
-## LSP-Enhanced Exploration (ACTIVE - Claude Code 2.0.74+)
+## LSP-Enhanced Exploration
 
-**LSP is POWERFUL - USE IT ACTIVELY** for semantic code understanding. 100x faster and more accurate than grep.
+**USE LSP ACTIVELY** for semantic code understanding (100x faster than grep).
 
-**WHEN to use LSP (PROACTIVE):**
+**Key operations**: `findReferences` (before refactoring) | `goToDefinition` (navigate) | `documentSymbol` (structure) | `hover` (types) | `getDiagnostics` (errors)
 
-| Scenario | LSP Operation | Why Use It |
-|----------|---------------|------------|
-| Before refactoring | `findReferences` | Know ALL usages before changing |
-| Navigate to source | `goToDefinition` | Jump directly to implementation |
-| Understand module | `documentSymbol` | See complete structure/hierarchy |
-| Check types | `hover` | Get accurate signatures, JSDoc |
-| Code quality | `getDiagnostics` | Errors, warnings before commit |
-
-**ACTIVE Usage Examples:**
-```bash
-# Before renaming a function - find ALL references
-"Use LSP findReferences to find all usages of calculateTax"
-
-# Navigate to implementation instead of grep
-"Use goToDefinition to find where PaymentService is defined"
-
-# Get accurate type signature
-"Use hover to check the type of processOrder function"
-
-# Check for errors before suggesting changes
-"Use getDiagnostics on this file to check for issues"
-
-# Understand module structure
-"Use documentSymbol to map the API surface of auth.ts"
-```
-
-**Smart Integration (ADR-0222):**
-- LSP is EXEMPT from "Code First, Tools Second" rule
-- LSP responses are small (~100-5000 bytes), no context bloat
-- Use LSP for precision, code execution for bulk processing
-
-**Install Language Servers** (required):
+**Install**:
 ```bash
-# TypeScript/JavaScript
-npm install -g typescript-language-server typescript
-
-# Python
-pip install python-lsp-server
-
-# Go
-go install golang.org/x/tools/gopls@latest
-
-# C#
-brew install omnisharp  # or: dotnet tool install -g omnisharp
+npm install -g typescript-language-server typescript  # TS/JS
+pip install python-lsp-server  # Python
+go install golang.org/x/tools/gopls@latest  # Go
 ```
 
-**Configuration** (optional, `.lsp.json` in project root):
-```json
-{
-  "vtsls": {
-    "command": "typescript-language-server",
-    "args": ["--stdio"],
-    "extensionToLanguage": { ".ts": "typescript", ".tsx": "typescriptreact", ".js": "javascript" }
-  }
-}
-```
-
-**Best Practices**:
-- **ALWAYS use findReferences** before any refactoring
-- **ALWAYS use goToDefinition** instead of grep for navigation
-- **Use documentSymbol** to understand module organization
-- **Use hover** to verify type signatures before changes
-- Combine with Explore agent for comprehensive understanding
+**Best Practices**: ALWAYS use `findReferences` before refactoring | Use `goToDefinition` instead of grep | Combine with Explore agent
 <!-- /SECTION -->
 
 <!-- SECTION:structure -->
@@ -163,54 +108,25 @@ brew install omnisharp  # or: dotnet tool install -g omnisharp
 ```
 .specweave/
 ├── increments/####-name/     # metadata.json, spec.md, tasks.md
-├── docs/internal/
-│   ├── specs/{project}/      # Living docs (check before implementing!)
-│   ├── architecture/adr/     # ADRs (check before design decisions!)
-│   └── operations/           # Runbooks
+├── docs/internal/specs/      # Living docs (check before implementing!)
+│   └── architecture/adr/     # ADRs (check before design decisions!)
 └── config.json
 ```
 
-### ⚠️ CRITICAL: Multi-Repo Project Paths (MANDATORY)
-
-**ALL multi-project repositories MUST be created in `repositories/` folder - NEVER in project root!**
+**Increment folders - ONLY at root**: metadata.json, spec.md, plan.md, tasks.md
+**Everything else → subfolders**: reports/ (validation, QA) | logs/{YYYY-MM-DD}/ | scripts/ | docs/domain/ | backups/
 
+**Multi-repo projects**: Create in `repositories/` folder (NEVER project root!)
 ```
-❌ FORBIDDEN (pollutes root):
 my-project/
-├── frontend/        ← WRONG!
-├── backend/         ← WRONG!
-├── shared/          ← WRONG!
+├── repositories/     # All repos here: frontend/, backend/, shared/
 └── .specweave/
-
-✅ REQUIRED (clean structure):
-my-project/
-├── repositories/
-│   ├── frontend/    ← CORRECT!
-│   ├── backend/     ← CORRECT!
-│   └── shared/      ← CORRECT!
-└── .specweave/
-```
-
-**This applies to ALL cases:**
-- GitHub multi-repo → `repositories/`
-- Azure DevOps multi-repo → `repositories/`
-- Bitbucket multi-repo → `repositories/`
-- **Local git multi-repo → `repositories/`** ← Same rule!
-- Monorepo with multiple packages → `repositories/` or `packages/`
-
-**When spec.md has `projects:` array:**
-```yaml
-projects:
-  - id: my-api
-    scope: "Backend API"
 ```
-The implementation path is ALWAYS: `repositories/my-api/` (NOT `my-api/` in root!)
 
-**Multi-repo permissions**: In `.claude/settings.json`:
+**Permissions** (`.claude/settings.json`):
 ```json
-{"permissions":{"allow":["Write(//**)","Edit(//**)"],"additionalDirectories":["repositories"],"defaultMode":"bypassPermissions"}}
+{"permissions":{"allow":["Write(//**)","Edit(//**)"],"additionalDirectories":["repositories"]}}
 ```
-**Path syntax**: `//path` = absolute | `/path` = relative to settings file | `**` = recursive | `additionalDirectories` = explicit working dirs
 <!-- /SECTION -->
 
 <!-- SECTION:taskformat required -->
@@ -287,94 +203,20 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 <!-- SECTION:api -->
 ## API Development (OpenAPI-First)
 
-**For API projects only.** Skip this section if your project has no REST/GraphQL endpoints.
-
-**Use OpenAPI as the source of truth for API documentation.** Postman collections and environments are derived from OpenAPI and .env.
-
-### Configuration (`.specweave/config.json`)
+**For API projects only.** OpenAPI = source of truth → Postman derived from it.
 
+**Config** (`.specweave/config.json`):
 ```json
-{
-  "apiDocs": {
-    "enabled": true,
-    "openApiPath": "openapi.yaml",
-    "generatePostman": true,
-    "postmanPath": "postman-collection.json",
-    "postmanEnvPath": "postman-environment.json",
-    "generateOn": "on-increment-done",
-    "baseUrl": "http://localhost:3000"
-  }
-}
-```
-
-### Generated Artifacts
-
-| File | Purpose | Source |
-|------|---------|--------|
-| `openapi.yaml` | API specification (source of truth) | Framework decorators/annotations |
-| `postman-collection.json` | API requests for testing | Derived from OpenAPI |
-| `postman-environment.json` | Variables (baseUrl, tokens, etc.) | Derived from .env |
-
-### OpenAPI Generation by Framework
-
-| Framework | Auto-Generation | Setup |
-|-----------|-----------------|-------|
-| **NestJS** | `@nestjs/swagger` | Decorators auto-generate OpenAPI |
-| **FastAPI** | Built-in | Auto-generates at `/openapi.json` |
-| **Express** | `swagger-jsdoc` | JSDoc comments → OpenAPI |
-| **Spring Boot** | `springdoc-openapi` | Annotations auto-generate |
-| **Go/Gin** | `swag` | Comments → OpenAPI |
-
-### Workflow
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ Code (decorators/annotations)                                │
-│         ↓ (auto-generated or manual)                         │
-│ openapi.yaml (SOURCE OF TRUTH - version controlled)         │
-│         ↓ (derived on /sw:done or /sw:api-docs)             │
-│ ├── postman-collection.json (requests with {{baseUrl}})     │
-│ └── postman-environment.json (variables from .env)          │
-└─────────────────────────────────────────────────────────────┘
+{"apiDocs":{"enabled":true,"openApiPath":"openapi.yaml","generatePostman":true,"generateOn":"on-increment-done"}}
 ```
 
-### Commands
+**Frameworks**: NestJS (`@nestjs/swagger`) | FastAPI (built-in) | Express (`swagger-jsdoc`) | Spring Boot (`springdoc-openapi`)
 
-```bash
-# Generate all API docs (OpenAPI + Postman collection + environment)
-/sw:api-docs --all
-
-# Generate only OpenAPI
-/sw:api-docs --openapi
-
-# Generate only Postman collection from existing OpenAPI
-/sw:api-docs --postman
-
-# Generate only environment file from .env
-/sw:api-docs --env
-
-# Validate existing OpenAPI spec
-/sw:api-docs --validate
-
-# Generate on increment close (automatic if enabled)
-/sw:done 0001  # → triggers API doc generation
-```
-
-### Postman Import
-
-After generation:
-1. Postman → Import → `postman-collection.json`
-2. Postman → Environments → Import → `postman-environment.json`
-3. Fill in secret values (marked as secret type, values empty)
-4. Select environment from dropdown
+**Commands**: `/sw:api-docs --all` (OpenAPI + Postman) | `--openapi` | `--postman` | `--env` | `--validate`
 
-### When Docs Update
+**Flow**: Code decorators → `openapi.yaml` → `/sw:done` or `/sw:api-docs` → Postman collection + env
 
-| `generateOn` Setting | When API Docs Regenerate |
-|---------------------|--------------------------|
-| `on-increment-done` | When closing increment (recommended) |
-| `on-api-change` | When API files change (hook-based) |
-| `manual` | Only via `/sw:api-docs` command |
+**Import**: Postman → Import collection + env → Fill secrets → Select env
 <!-- /SECTION -->
 
 <!-- SECTION:limits -->
@@ -421,495 +263,114 @@ Task format: `**AC**: AC-US1-01, AC-US1-02` (CRITICAL for linking)
 <!-- /SECTION -->
 
 <!-- SECTION:mcp -->
-## External Service Connection (MCP + Smart Fallbacks)
+## External Service Connection
 
-**Core principle: Never fight connection issues. Use the path of least resistance.**
-
-### Connection Priority (ALWAYS follow this order)
-
-```
-MCP Server → REST API → SDK/Client → CLI → Direct Connection
-     ↑                                              ↓
-   BEST                                          WORST
-```
-
-### Service Connection Matrix
-
-| Service | BEST Method | Fallback | AVOID |
-|---------|-------------|----------|-------|
-| **Supabase** | MCP Server | REST API / JS Client | Direct `psql` (IPv6 issues) |
-| **Cloudflare** | `wrangler` + OAuth | REST API | Manual curl |
-| **PostgreSQL** | MCP / Pooler (6543) | `psql` with pooler | Direct port 5432 |
-| **MongoDB** | Atlas Data API | MCP / Driver | Direct connection |
-| **Redis** | Upstash REST | MCP | `redis-cli` (TCP issues) |
-| **AWS** | CLI with SSO | SDK | Hardcoded keys |
-| **Vercel** | CLI with OAuth | REST API | Manual deploys |
-
-### Quick Setup Commands
+**Priority**: MCP Server → REST API → CLI → Direct Connection
 
+**Setup**:
 ```bash
-# MCP Servers (one-time, restart Claude Code after)
+# MCP (restart Claude Code after)
 npx @anthropic-ai/claude-code-mcp add supabase
-npx @anthropic-ai/claude-code-mcp add postgres
-
-# CLI Auth (persistent OAuth sessions)
-wrangler login        # Cloudflare
-vercel login          # Vercel
-aws configure sso     # AWS
-supabase login        # Supabase CLI
-
-# Verify auth status
-wrangler whoami && vercel whoami && aws sts get-caller-identity
-```
-
-### Supabase (Most Common Issues)
-
-```bash
-# ❌ DON'T: Direct psql or supabase db push (IPv6 fails)
-supabase db push  # Often fails with connection errors
-
-# ✅ DO: Use REST API or MCP
-# REST API works everywhere - no network issues
-curl "${SUPABASE_URL}/rest/v1/table" \
-  -H "apikey: ${SUPABASE_ANON_KEY}"
 
-# For migrations: Use Supabase Dashboard SQL Editor
-# OR use connection pooler (port 6543, NOT 5432)
-DATABASE_URL="postgresql://postgres.[ref]:[pass]@aws-0-region.pooler.supabase.com:6543/postgres"
-```
-
-### Cloudflare Workers
-
-```bash
-# One-time login (saves OAuth session)
-wrangler login
-
-# All operations then work:
-wrangler deploy                          # Deploy worker
-echo "value" | wrangler secret put KEY   # Set secret
-wrangler kv:key put --binding=KV k v     # KV operations
-wrangler d1 execute DB --command "SQL"   # D1 database
+# CLI Auth
+wrangler login && vercel login && supabase login
 ```
 
-### Auto-Detection (Run Before External Ops)
+**Supabase**: Use REST API or pooler (port 6543), AVOID direct `psql`
+**Cloudflare**: `wrangler login` once, then `wrangler deploy/secret put/kv:key put`
 
+**Check credentials before ops**:
 ```bash
-# Check configured services
-grep -E "SUPABASE_|DATABASE_URL|MONGODB|UPSTASH|CF_API" .env 2>/dev/null
+grep -E "SUPABASE_|DATABASE_URL|CF_API" .env 2>/dev/null
 wrangler whoami 2>/dev/null
-aws sts get-caller-identity 2>/dev/null
 ```
-
-**Full reference**: See `/sw:service-connect` skill for complete patterns.
 <!-- /SECTION -->
 
 <!-- SECTION:autoexecute -->
-## Auto-Execute Rule (CRITICAL)
-
-**NEVER output "Manual Step Required" or "Next Steps" when credentials are available.**
-
-### The Golden Rule
-
-```
-❌ FORBIDDEN: "Manual Step Required: Open Supabase SQL Editor..."
-❌ FORBIDDEN: "Next Steps: 1. Run wrangler deploy..."
-❌ FORBIDDEN: "Execute this SQL in your database console..."
+## Auto-Execute Rule
 
-✅ REQUIRED: Execute commands directly using available credentials
-```
-
-### Decision Tree
-
-```
-Credentials in .env? ──YES──→ EXECUTE IMMEDIATELY
-         │
-         NO
-         │
-         ▼
-ASK for credentials (don't show manual steps!)
-         │
-         ▼
-Save to .env → EXECUTE IMMEDIATELY → Continue
-```
+**NEVER** output "Manual Step Required" when credentials exist. **EXECUTE DIRECTLY.**
 
-### Credential Lookup (MANDATORY before any external operation)
+**Flow**: Check `.env` → If exists, EXECUTE | If missing, ASK for credentials → Save → EXECUTE
 
+**Check before ops**:
 ```bash
-# 1. Check .env
 grep -E "(SUPABASE_|DATABASE_URL|CF_API_|GITHUB_TOKEN)" .env 2>/dev/null
-
-# 2. Check CLI auth
-supabase status 2>/dev/null     # Supabase
-wrangler whoami 2>/dev/null     # Cloudflare
-gh auth status 2>/dev/null      # GitHub
-aws sts get-caller-identity 2>/dev/null  # AWS
-
-# 3. Use MCP server if available
-# MCP servers provide direct API access
-```
-
-### Auto-Execute Examples
-
-```bash
-# Supabase SQL execution
-if [ -n "$DATABASE_URL" ]; then
-  psql "$DATABASE_URL" -f schema.sql  # ✅ Execute directly
-fi
-
-# Wrangler secrets
-if wrangler whoami 2>/dev/null; then
-  echo "$SECRET" | wrangler secret put MY_SECRET  # ✅ Execute directly
-  wrangler deploy  # ✅ Deploy directly
-fi
-```
-
-### If Credentials Missing → ASK, Don't Show Manual Steps
-
-```markdown
-🔐 **Credential Required**
-
-I need your DATABASE_URL to execute the migration.
-
-**Paste your connection string:**
-[I will save to .env and execute automatically]
+wrangler whoami 2>/dev/null && gh auth status 2>/dev/null
 ```
 <!-- /SECTION -->
 
 <!-- SECTION:auto -->
 ## Auto Mode (Autonomous Execution)
 
-**Auto mode enables continuous autonomous execution** until all tasks are complete.
-
-### 🚨 CRITICAL: Zero Manual Steps in Auto Mode
-
-**Auto mode MUST be fully autonomous. NEVER ask user to:**
-- Open a web dashboard (Supabase, AWS Console, etc.)
-- Copy/paste SQL into an editor
-- Run commands manually
-- Click buttons in UIs
-
-**If you need external access:**
-1. Check for credentials in `.env`
-2. Use CLI tools (`supabase`, `wrangler`, `gh`, `aws`)
-3. Use MCP servers for direct API access
-4. If credentials missing → ASK for them, save to `.env`, then EXECUTE
-
-### 🧪 Test Execution Loop (MANDATORY)
-
-**After EVERY implementation task, run tests in a self-healing loop:**
-
-```bash
-# 1. Run unit/integration tests
-npm test  # or: npx vitest run
-
-# 2. If UI exists, run E2E tests
-npx playwright test
-
-# 3. If tests fail → FIX → RE-RUN (max 3 attempts)
-```
-
-**Test Loop Pattern (Ralph Loop):**
-```
-┌─────────────────────────────────────────────────────────────┐
-│ IMPLEMENT → TEST → FAIL? → FIX → TEST → PASS → NEXT TASK   │
-│                     ↑________________↓                       │
-│                    (max 3 iterations)                        │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**E2E Test Execution (when UI exists):**
-```bash
-# Install Playwright browsers if needed
-npx playwright install --with-deps chromium
-
-# Run E2E tests with proper reporting
-npx playwright test --reporter=list
-
-# On failure, capture screenshot/trace
-npx playwright test --trace on
-```
-
-**Focus on MVP Critical Paths:**
-1. **Authentication flows** (login, logout, register)
-2. **Core business transactions** (create, update, delete)
-3. **Payment/checkout flows** (if applicable)
-4. **Data integrity scenarios**
-
-### ⚠️ Pragmatic Completion (NOT 100% Blindly!)
-
-**Don't blindly follow 100% completion rules!** Reality:
-- Specs have bugs, ambiguities, conflicts
-- Requirements change mid-implementation
-- Some planned tasks become irrelevant
-- Edge cases may not be worth the effort
-
-**Smart Completion Criteria:**
-```
-┌─────────────────────────────────────────────────────────────┐
-│ MUST COMPLETE (block release):                               │
-│ • MVP critical paths (auth, core CRUD, payments)            │
-│ • Security-sensitive flows                                   │
-│ • Data integrity operations                                  │
-│ • User-facing error handling                                 │
-├─────────────────────────────────────────────────────────────┤
-│ SHOULD COMPLETE (aim for, but pragmatic):                    │
-│ • Edge case handling                                         │
-│ • Performance optimizations                                  │
-│ • Nice-to-have features                                      │
-├─────────────────────────────────────────────────────────────┤
-│ CAN SKIP/DEFER (if blocking progress):                       │
-│ • Conflicting requirements (flag and ask user)              │
-│ • Over-engineered edge cases                                 │
-│ • Tasks made obsolete by other changes                       │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**When to STOP and ask user:**
-- Spec conflicts with another spec
-- Task seems unnecessary given implementation
-- Edge case would require major refactoring
-- Requirement is ambiguous
-
-### 🧑‍🤝‍🧑 Smart Test User Strategy
-
-**Create test users strategically, not blindly:**
-
-```typescript
-// Good: Create users with specific roles/states
-const testUsers = {
-  admin: { email: 'admin@test.com', role: 'admin' },
-  regularUser: { email: 'user@test.com', role: 'user' },
-  premiumUser: { email: 'premium@test.com', plan: 'premium' },
-  blockedUser: { email: 'blocked@test.com', status: 'blocked' },
-};
-
-// When to create multiple test users:
-// ✅ Testing role-based access control
-// ✅ Testing subscription tiers
-// ✅ Testing user states (active, blocked, pending)
-// ✅ Testing multi-user interactions (sharing, permissions)
-
-// When ONE test user is enough:
-// ✅ Basic CRUD operations
-// ✅ Form validation
-// ✅ UI component tests
-// ✅ API endpoint tests (mocked auth)
-```
-
-**E2E Test User Setup:**
-```typescript
-// playwright/fixtures/users.ts
-export const testUsers = {
-  // Seeded in database before tests
-  admin: { id: 'test-admin-001', email: 'admin@test.local' },
-  user: { id: 'test-user-001', email: 'user@test.local' },
-};
-
-// Use fixtures, don't create users per test!
-test.use({ storageState: 'playwright/.auth/user.json' });
-```
-
-### 🔐 E2E Authentication (CRITICAL - Avoid Flaky Tests!)
-
-**Auth is the #1 cause of flaky E2E tests. Be ULTRASMART:**
-
-| Strategy | Speed | Reliability | Use When |
-|----------|-------|-------------|----------|
-| **storageState** | ⚡⚡⚡ | ⭐⭐⭐ | Default - login ONCE, reuse |
-| **API auth** | ⚡⚡ | ⭐⭐⭐ | When UI is unstable |
-| **UI login per test** | ⚡ | ⭐ | Only testing login flow |
-
-**Playwright Auth Setup (MANDATORY):**
-
-```typescript
-// playwright/auth.setup.ts - Global setup
-import { test as setup } from '@playwright/test';
-
-setup('authenticate', async ({ page }) => {
-  await page.goto('/login');
-  await page.fill('[name="email"]', 'test@example.com');
-  await page.fill('[name="password"]', 'testpass123');
-  await page.click('button[type="submit"]');
-  await page.waitForURL('/dashboard');
-  await page.context().storageState({ path: 'playwright/.auth/user.json' });
-});
-```
-
-```typescript
-// playwright.config.ts - Reuse auth state
-projects: [
-  { name: 'setup', testMatch: /.*\.setup\.ts/ },
-  {
-    name: 'chromium',
-    use: { storageState: 'playwright/.auth/user.json' },
-    dependencies: ['setup'],
-  },
-]
-```
+**Continuous execution until all tasks complete.**
 
-**Common Auth Fixes:**
+### Zero Manual Steps
 
-| Problem | Solution |
-|---------|----------|
-| Session expires | Increase TTL for test env |
-| Rate limited | Use API auth, seed users |
-| Captcha blocks | Disable in test env |
-| OAuth fails | Mock provider |
+**NEVER ask user to**: Open dashboards | Copy/paste | Run commands manually
 
-**Auto Mode E2E Checklist:**
-```
-✅ Test users seeded with known passwords
-✅ Auth state files generated
-✅ Tests DON'T login (except login flow tests)
-✅ Captcha/2FA disabled in test env
-```
+**Instead**: Check `.env` → Use CLI (`wrangler`, `gh`, `aws`) → Use MCP → If missing, ASK → Save → EXECUTE
 
-### 🔄 Continuous Refactoring (Part of Auto Loop)
+### Test Loop (MANDATORY)
 
-**As tests grow, REFACTOR proactively:**
+**After EVERY task**: `npm test` → If E2E exists: `npx playwright test` → Fail? FIX → Rerun (max 3x) → Pass → Next
 
-```
-After every 3-5 tasks:
-1. Review test organization → Extract shared fixtures
-2. Review code duplication → Extract utilities
-3. Review file sizes → Split if >300 lines
-4. Review imports → Consolidate, remove unused
-```
+**Pattern**: IMPLEMENT → TEST → FAIL? → FIX → TEST → PASS → NEXT
 
-**Refactoring Triggers:**
-- Test file > 200 lines → Split by feature
-- Duplicate test setup → Extract to fixtures
-- Same assertion pattern 3+ times → Create helper
-- Source file > 300 lines → Extract module
+**MVP paths**: Auth (login/logout) | Core CRUD | Payments | Data integrity
 
-### 📊 Test Status Reporting (MANDATORY in Auto Mode)
+### Pragmatic Completion
 
-**After EVERY task, report test status to user:**
-
-```markdown
-## 🧪 Test Status Report
+**Don't blindly follow 100%!** Specs have bugs, requirements change, some tasks become irrelevant.
 
-| Type | Status | Pass/Total | Coverage |
-|------|--------|------------|----------|
-| Unit | ✅ | 42/42 | 87% |
-| Integration | ✅ | 12/12 | - |
-| E2E | ⚠️ | 8/10 | - |
+**MUST**: MVP paths | Security flows | Data integrity | User-facing errors
+**SHOULD**: Edge cases | Performance | Nice-to-haves
+**CAN SKIP**: Conflicts (ask user) | Over-engineered cases | Obsolete tasks
 
-**Failing tests:**
-- `auth.spec.ts:45` - Login redirect not working
-- `checkout.spec.ts:112` - Payment timeout
+**STOP & ASK** if: Spec conflicts | Task seems unnecessary | Requirement ambiguous
 
-**Next:** Fixing E2E failures before continuing...
-```
+### Test User Strategy
 
-### 🏠 Local-First Development
+**Multiple users**: RBAC | Subscription tiers | User states | Multi-user interactions
+**One user**: CRUD | Form validation | Component tests | Mocked auth
 
-**If no deployment instructions provided, BUILD AND TEST LOCALLY FIRST:**
+**E2E**: Seed DB with known users → Use fixtures → `storageState` (auth once, reuse)
 
-```
-1. Implement feature locally
-2. Run ALL tests (unit, integration, E2E)
-3. Verify everything works
-4. THEN ask user about deployment preferences
-```
+### E2E Authentication
 
-**Don't assume deployment target!** Ask user:
-```markdown
-🚀 **Deployment Options**
+**Auth = #1 flaky test cause.** Use `storageState` (login ONCE, reuse) | API auth (UI unstable) | UI login (only for login tests)
 
-Your scraper is ready and all tests pass locally.
+**Setup**: Global auth.setup.ts → Save to `playwright/.auth/user.json` → Reuse in config
 
-**Where would you like to deploy?**
-- Vercel Cron (serverless, free tier available)
-- Railway (always-on, $5/mo)
-- GitHub Actions (CI-based, free)
-- Local cron (self-hosted)
-- Other?
-```
+**Fixes**: Session expires? Increase TTL | Rate limited? API auth | Captcha? Disable in test env
 
-### 🔧 Infrastructure Decision-Making
+**Checklist**: Seed users | Gen auth state | Tests DON'T login | Disable captcha/2FA
 
-**For scrapers, cron jobs, background tasks - ULTRATHINK on best approach:**
+### Refactoring & Reporting
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│ INFRASTRUCTURE DECISION TREE                                 │
-├─────────────────────────────────────────────────────────────┤
-│ Scraper/Cron Job:                                           │
-│ ├─ Frequency < 1/hour → Vercel Cron, GitHub Actions         │
-│ ├─ Frequency ≥ 1/hour → Railway, Render, dedicated server   │
-│ ├─ Heavy compute → Dedicated VM, Docker container           │
-│ └─ Real-time → Always-on server, WebSocket                  │
-│                                                              │
-│ Data Storage:                                                │
-│ ├─ Simple KV → Upstash Redis, Vercel KV                     │
-│ ├─ Relational → Supabase, PlanetScale, Neon                 │
-│ ├─ Document → MongoDB Atlas, Supabase                       │
-│ └─ Time-series → TimescaleDB, InfluxDB                      │
-│                                                              │
-│ File Storage:                                                │
-│ ├─ Static assets → Cloudflare R2, S3                        │
-│ └─ Large files → S3, GCS, Backblaze B2                      │
-└─────────────────────────────────────────────────────────────┘
-```
+**Every 3-5 tasks**: Extract fixtures | Remove duplication | Split if >300 lines | Clean imports
 
-**When implementing scrapers/cron jobs:**
-1. **Ultrathink** on best hosting options given requirements
-2. **Research** rate limits, costs, reliability
-3. **Propose** 2-3 options with trade-offs
-4. **Build locally first** with tests
-5. **Deploy** only after user confirms target
+**Triggers**: Test >200 lines? Split | Duplicate setup? Extract | Same assertion 3x? Helper
 
-### For Claude Code Users
+**Report after EVERY task**: Pass/Total | Coverage | Failing tests | Next steps
 
-Auto mode uses Claude Code's Stop Hook to create a feedback loop:
-- `/sw:do` continues until all tasks complete
-- `/sw:auto-status` shows session progress
-- `/sw:cancel-auto` stops autonomous execution
+### Local-First & Infrastructure
 
-Session state stored in `.specweave/state/auto-session.json`.
+**No deploy instructions?** Build locally → Test all → Verify → ASK user about deploy target
 
-### For Non-Claude AI Systems
+**Infra Decision Tree**:
+- **Cron**: <1/hr → Vercel/GitHub Actions | ≥1/hr → Railway/Render
+- **Storage**: KV → Upstash/Vercel KV | SQL → Supabase/Neon | Docs → MongoDB | Files → R2/S3
 
-If using SpecWeave with other AI systems (GPT, Gemini, etc.), implement this loop pattern:
+**Process**: Ultrathink options → Research costs → Propose 2-3 → Build local → User confirms → Deploy
 
-```bash
-# Bash loop for autonomous execution
-while true; do
-    # Check if all tasks complete
-    TOTAL=$(grep -c "^### T-" .specweave/increments/*/tasks.md 2>/dev/null || echo "0")
-    DONE=$(grep -c '\[x\].*completed' .specweave/increments/*/tasks.md 2>/dev/null || echo "0")
-
-    if [ "$TOTAL" -gt 0 ] && [ "$DONE" -ge "$TOTAL" ]; then
-        echo "All tasks complete!"
-        break
-    fi
-
-    # Feed prompt to your AI
-    cat PROMPT.md | your-ai-cli
-
-    # Safety: max iterations
-    ITER=$((ITER + 1))
-    if [ "$ITER" -ge 100 ]; then
-        echo "Max iterations reached"
-        break
-    fi
-done
-```
+### Implementation
 
-**Key Concepts**:
-- **Completion Detection**: Check tasks.md for `[x] completed` status
-- **Completion Tag**: Output `<auto-complete>DONE</auto-complete>` when finished
-- **Max Iterations**: Always set a limit (default: 100)
-- **Human Gates**: Pause for sensitive ops (deploy, publish, force-push)
+**Claude Code**: `/sw:do` (continues till done) | `/sw:auto-status` (progress) | `/sw:cancel-auto` (stop)
 
-**Human-Gated Operations** (require manual approval):
-- `npm publish`, `git push --force`, `rm -rf /`
-- Any `production` deployment
-- API key or credential changes
-- Database migrations (`drop`, `delete from`, `migrate`)
+**Other AI**: Loop check tasks.md `[x]` status → Max 100 iter → Human gates for: publish, force-push, prod deploy, migrations
 
-**Circuit Breaker Pattern**: If external API (GitHub, JIRA) fails 3+ times, queue operations and continue.
+**Circuit Breaker**: External API fails 3x? Queue & continue
 <!-- /SECTION -->
 
 <!-- SECTION:docs -->