specweave 1.0.78 → 1.0.80

package/CLAUDE.md

@@ -1,10 +1,10 @@
-<!-- SW:META template="claude" version="1.0.60" sections="header,start,autodetect,metarule,rules,workflow,context,lsp,structure,taskformat,secrets,syncing,mapping,testing,api,limits,troubleshooting,principles,linking,mcp,autoexecute,auto,docs" -->
+<!-- SW:META template="claude" version="1.0.79" sections="header,start,autodetect,metarule,rules,workflow,context,lsp,structure,taskformat,secrets,syncing,mapping,testing,api,limits,troubleshooting,principles,linking,mcp,autoexecute,auto,docs" -->
 
-<!-- SW:SECTION:header version="1.0.60" -->
+<!-- SW:SECTION:header version="1.0.79" -->
 **Framework**: SpecWeave | **Truth**: `spec.md` + `tasks.md`
 <!-- SW:END:header -->
 
-<!-- SW:SECTION:start version="1.0.60" -->
+<!-- SW:SECTION:start version="1.0.79" -->
 ## Getting Started
 
 **Initial increment**: `0001-project-setup` (auto-created by `specweave init`)
@@ -14,7 +14,7 @@
 2. **Customize**: Edit spec.md and use for setup tasks
 <!-- SW:END:start -->
 
-<!-- SW:SECTION:autodetect version="1.0.60" -->
+<!-- SW:SECTION:autodetect version="1.0.79" -->
 ## Auto-Detection
 
 SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
@@ -24,7 +24,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Opt-out phrases**: "Just brainstorm first" | "Don't plan yet" | "Quick discussion" | "Let's explore ideas"
 <!-- SW:END:autodetect -->
 
-<!-- SW:SECTION:metarule version="1.0.60" -->
+<!-- SW:SECTION:metarule version="1.0.79" -->
 ## Meta-Rule: Think-Before-Act
 
 **Satisfy dependencies BEFORE dependent operations.**
@@ -35,7 +35,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 ```
 <!-- SW:END:metarule -->
 
-<!-- SW:SECTION:rules version="1.0.60" -->
+<!-- SW:SECTION:rules version="1.0.79" -->
 ## Rules
 
 1. **Files** → `.specweave/increments/####-name/` (spec.md, plan.md, tasks.md at root; reports/, scripts/, logs/ subfolders)
@@ -45,7 +45,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 5. **Root clean**: NEVER create .md/reports/scripts in project root → use increment folders
 <!-- SW:END:rules -->
 
-<!-- SW:SECTION:workflow version="1.0.60" -->
+<!-- SW:SECTION:workflow version="1.0.79" -->
 ## Workflow
 
 `/sw:increment "X"` → `/sw:do` → `/sw:progress` → `/sw:done 0001`
@@ -65,7 +65,7 @@ SpecWeave auto-detects product descriptions and routes to `/sw:increment`:
 **Natural language**: "Let's build X" → `/sw:increment` | "What's status?" → `/sw:progress` | "We're done" → `/sw:done` | "Ship while sleeping" → `/sw:auto`
 <!-- SW:END:workflow -->
 
-<!-- SW:SECTION:context version="1.0.60" -->
+<!-- SW:SECTION:context version="1.0.79" -->
 ## Living Docs Context
 
 **Before implementing features**: Check existing docs for patterns and decisions.
@@ -85,176 +85,51 @@ grep -ril "keyword" .specweave/docs/internal/
 **Use `/sw:context <topic>`** to load relevant living docs into conversation.
 <!-- SW:END:context -->
 
-<!-- SW:SECTION:lsp version="1.0.61" -->
-## LSP-Enhanced Exploration (ACTIVE - Claude Code 2.0.74+)
+<!-- SW:SECTION:lsp version="1.0.79" -->
+## 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:**
+**Install**:
 ```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"
+npm install -g typescript-language-server typescript  # TS/JS
+pip install python-lsp-server  # Python
+go install golang.org/x/tools/gopls@latest  # Go
 ```
 
-**Smart Integration (ADR-0222):**
-- LSP is EXEMPT from "Code First, Tools Second" rule (ADR-0140)
-- LSP responses are small (~100-5000 bytes), no context bloat
-- Use LSP for precision, code execution for bulk processing
-
-**Install Language Servers** (required):
-```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
-```
-
-**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
 <!-- SW:END:lsp -->
 
-<!-- SW:SECTION:structure version="1.0.61" -->
+<!-- SW:SECTION:structure version="1.0.79" -->
 ## Structure
 
 ```
 .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: Increment Folder Organization (MANDATORY)
-
-**ONLY these files allowed at increment ROOT:**
-```
-.specweave/increments/####-name/
-├── metadata.json    # Increment state
-├── spec.md          # Specification
-├── plan.md          # Implementation plan
-└── tasks.md         # Task list
-```
-
-**ALL other files MUST go in subfolders:**
-```
-.specweave/increments/####-name/
-├── reports/         # Validation reports, QA reports, completion summaries
-│   └── *.md         # PM-VALIDATION-REPORT.md, qa-post-closure.md, etc.
-├── logs/            # Debug logs, execution traces, session logs
-│   └── {YYYY-MM-DD}/ # Daily logs with assets/
-├── scripts/         # Helper scripts, automation tools
-├── docs/            # Additional documentation, domain knowledge
-│   └── domain/      # Domain models for brownfield analysis
-└── backups/         # Backup files
-```
-
-**File Routing Rules:**
-| File Type | Folder | Examples |
-|-----------|--------|----------|
-| Validation reports | `reports/` | `PM-VALIDATION-REPORT.md`, `validation-report.md` |
-| QA assessments | `reports/` | `qa-post-closure.md`, `COMPLETION-SUMMARY.md` |
-| Session logs | `logs/{date}/` | `session.md`, `assets/` |
-| Domain analysis | `docs/domain/` | `appointments/domain-model.md` |
-| Helper scripts | `scripts/` | `migrate.sh`, `validate.js` |
+**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/
 
-**FORBIDDEN - Files that pollute increment root:**
+**Multi-repo projects**: Create in `repositories/` folder (NEVER project root!)
 ```
-❌ .specweave/increments/0001/PM-VALIDATION-REPORT.md    # → reports/
-❌ .specweave/increments/0001/completion-report.md       # → reports/
-❌ .specweave/increments/0001/domain-model.md            # → docs/domain/
-❌ .specweave/increments/0001/helper.sh                  # → scripts/
-```
-
-### ⚠️ CRITICAL: Multi-Repo Project Paths (MANDATORY)
-
-**ALL multi-project repositories MUST be created in `repositories/` folder - NEVER in project root!**
-
-```
-❌ FORBIDDEN (pollutes root):
-my-project/
-├── frontend/        ← WRONG!
-├── backend/         ← WRONG!
-├── shared/          ← WRONG!
-└── .specweave/
-
-✅ REQUIRED (clean structure):
 my-project/
-├── repositories/
-│   ├── frontend/    ← CORRECT!
-│   ├── backend/     ← CORRECT!
-│   └── shared/      ← CORRECT!
+├── repositories/     # All repos here: frontend/, backend/, shared/
 └── .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
 <!-- SW:END:structure -->
 
-<!-- SW:SECTION:taskformat version="1.0.60" -->
+<!-- SW:SECTION:taskformat version="1.0.79" -->
 ## Task Format
 
 ```markdown
@@ -264,7 +139,7 @@ The implementation path is ALWAYS: `repositories/my-api/` (NOT `my-api/` in root
 ```
 <!-- SW:END:taskformat -->
 
-<!-- SW:SECTION:secrets version="1.0.60" -->
+<!-- SW:SECTION:secrets version="1.0.79" -->
 ## Secrets Check
 
 **BEFORE CLI tools**: Check existing config first!
@@ -275,7 +150,7 @@ gh auth status
 ```
 <!-- SW:END:secrets -->
 
-<!-- SW:SECTION:syncing version="1.0.60" -->
+<!-- SW:SECTION:syncing version="1.0.79" -->
 ## External Sync (GitHub/JIRA/ADO)
 
 **After increment creation**: Run `/sw-github:sync {id}` to create issues!
@@ -303,7 +178,7 @@ Living docs sync ≠ External sync. They are separate:
 **Verify tokens**: `grep GITHUB_TOKEN .env` | `gh auth status`
 <!-- SW:END:syncing -->
 
-<!-- SW:SECTION:mapping version="1.0.60" -->
+<!-- SW:SECTION:mapping version="1.0.79" -->
 ## GitHub Mapping
 
 | SpecWeave | GitHub |
@@ -313,7 +188,7 @@ Living docs sync ≠ External sync. They are separate:
 | Task T-XXX | Checkbox |
 <!-- SW:END:mapping -->
 
-<!-- SW:SECTION:testing version="1.0.60" -->
+<!-- SW:SECTION:testing version="1.0.79" -->
 ## Testing
 
 BDD in tasks.md | Unit >80% | `.test.ts` (Vitest)
@@ -325,106 +200,32 @@ vi.mock('fs', () => ({ readFile: vi.fn() }));
 ```
 <!-- SW:END:testing -->
 
-<!-- SW:SECTION:api version="1.0.60" -->
+<!-- SW:SECTION:api version="1.0.79" -->
 ## 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
+**Commands**: `/sw:api-docs --all` (OpenAPI + Postman) | `--openapi` | `--postman` | `--env` | `--validate`
 
-# 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
-```
+**Flow**: Code decorators → `openapi.yaml` → `/sw:done` or `/sw:api-docs` → Postman collection + env
 
-### 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
-
-### When Docs Update
-
-| `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
 <!-- SW:END:api -->
 
-<!-- SW:SECTION:limits version="1.0.60" -->
+<!-- SW:SECTION:limits version="1.0.79" -->
 ## Limits
 
 **Max 1500 lines/file** — extract before adding
 <!-- SW:END:limits -->
 
-<!-- SW:SECTION:troubleshooting version="1.0.60" -->
+<!-- SW:SECTION:troubleshooting version="1.0.79" -->
 ## Troubleshooting
 
 | Issue | Fix |
@@ -441,10 +242,9 @@ After generation:
 | No GITHUB_TOKEN | Check `.env` file or run `gh auth login` |
 | Edits blocked in repositories/ | Add `"additionalDirectories":["repositories"]` + `Write(//**)`, `Edit(//**)` to `.claude/settings.json` |
 | Path patterns not working | `//path` = absolute, `/path` = relative to settings file, `additionalDirectories` for explicit working dirs |
-| **specweave/claude not found after Node upgrade** | **nvm users**: Global packages are lost when switching Node versions! Fix: `nvm reinstall-packages <old-version>` OR `npm install -g specweave @anthropic-ai/claude-code`. See [Node Version Management](/.specweave/docs/internal/operations/runbook-node-version-management.md) |
 <!-- SW:END:troubleshooting -->
 
-<!-- SW:SECTION:principles version="1.0.60" -->
+<!-- SW:SECTION:principles version="1.0.79" -->
 ## Principles
 
 1. **Spec-first**: `/sw:increment` before coding
@@ -454,7 +254,7 @@ After generation:
 5. **Clean**: All files in increment folders
 <!-- SW:END:principles -->
 
-<!-- SW:SECTION:linking version="1.0.60" -->
+<!-- SW:SECTION:linking version="1.0.79" -->
 ## Bidirectional Linking
 
 Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
@@ -462,534 +262,118 @@ Tasks ↔ User Stories auto-linked via AC-IDs: `AC-US1-01` → `US-001`
 Task format: `**AC**: AC-US1-01, AC-US1-02` (CRITICAL for linking)
 <!-- SW:END:linking -->
 
-<!-- SW:SECTION:mcp version="1.0.60" -->
-## External Service Connection (MCP + Smart Fallbacks)
-
-**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 |
+<!-- SW:SECTION:mcp version="1.0.79" -->
+## External Service Connection
 
-### 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.
 <!-- SW:END:mcp -->
 
-<!-- SW:SECTION:autoexecute version="1.0.60" -->
-## 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..."
-
-✅ REQUIRED: Execute commands directly using available credentials
-```
-
-### Decision Tree
+<!-- SW:SECTION:autoexecute version="1.0.79" -->
+## Auto-Execute Rule
 
-```
-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
 ```
 <!-- SW:END:autoexecute -->
 
-<!-- SW:SECTION:auto version="1.0.60" -->
+<!-- SW:SECTION:auto version="1.0.79" -->
 ## Auto Mode (Autonomous Execution)
 
-**Auto mode enables continuous autonomous execution** until all tasks are complete.
-
-### 🆕 Intelligent Increment Creation (NEW!)
-
-**Auto mode now auto-creates increments when none exist!**
-
-**Default behavior**: `/sw:auto` with no arguments will:
-1. Check for active/in-progress increments → use if found
-2. If none found → **intelligently create increments** based on user context
-3. Match existing planned/backlog increments OR create new ones
-4. Ask user if ambiguous
-
-**Strict mode**: Use `--no-increment` or `--no-inc` flag to require existing increments (no auto-creation)
-
-**Examples:**
-```bash
-# User says: "Let's build the dashboard feature"
-/sw:auto
-# → Finds 0004-dashboard in backlog OR creates it
-
-# User says: "Work on auth and notifications"
-/sw:auto
-# → Creates queue: [0001-auth, 0002-notifications]
-
-# Strict mode (no auto-creation) - both forms work
-/sw:auto --no-increment
-/sw:auto --no-inc
-# → ERROR if no active increment
-```
-
-**Intelligence patterns:**
-- **Match**: "continue auth" → finds `0002-authentication`
-- **Extend**: "add password reset" → adds tasks to active auth increment
-- **Create**: "build payment system" → creates `0003-payment-integration`
-- **Queue**: "finish all pending" → processes all backlog items
-- **Ask**: If ambiguous → present options to user
-
-### 🚨 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:**
+**Don't blindly follow 100%!** Specs have bugs, requirements change, some tasks become irrelevant.
 
-```markdown
-## 🧪 Test Status Report
+**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
 
-| Type | Status | Pass/Total | Coverage |
-|------|--------|------------|----------|
-| Unit | ✅ | 42/42 | 87% |
-| Integration | ✅ | 12/12 | - |
-| E2E | ⚠️ | 8/10 | - |
+**STOP & ASK** if: Spec conflicts | Task seems unnecessary | Requirement ambiguous
 
-**Failing tests:**
-- `auth.spec.ts:45` - Login redirect not working
-- `checkout.spec.ts:112` - Payment timeout
+### Test User Strategy
 
-**Next:** Fixing E2E failures before continuing...
-```
+**Multiple users**: RBAC | Subscription tiers | User states | Multi-user interactions
+**One user**: CRUD | Form validation | Component tests | Mocked auth
 
-### 🏠 Local-First Development
+**E2E**: Seed DB with known users → Use fixtures → `storageState` (auth once, reuse)
 
-**If no deployment instructions provided, BUILD AND TEST LOCALLY FIRST:**
+### E2E Authentication
 
-```
-1. Implement feature locally
-2. Run ALL tests (unit, integration, E2E)
-3. Verify everything works
-4. THEN ask user about deployment preferences
-```
+**Auth = #1 flaky test cause.** Use `storageState` (login ONCE, reuse) | API auth (UI unstable) | UI login (only for login tests)
 
-**Don't assume deployment target!** Ask user:
-```markdown
-🚀 **Deployment Options**
+**Setup**: Global auth.setup.ts → Save to `playwright/.auth/user.json` → Reuse in config
 
-Your scraper is ready and all tests pass locally.
+**Fixes**: Session expires? Increase TTL | Rate limited? API auth | Captcha? Disable in test env
 
-**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?
-```
+**Checklist**: Seed users | Gen auth state | Tests DON'T login | Disable captcha/2FA
 
-### 🔧 Infrastructure Decision-Making
+### Refactoring & Reporting
 
-**For scrapers, cron jobs, background tasks - ULTRATHINK on best approach:**
+**Every 3-5 tasks**: Extract fixtures | Remove duplication | Split if >300 lines | Clean imports
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│ 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                      │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**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
 <!-- SW:END:auto -->
 
-<!-- SW:SECTION:docs version="1.0.60" -->
+<!-- SW:SECTION:docs version="1.0.79" -->
 ## Docs
 
 [spec-weave.com](https://spec-weave.com) | `.specweave/docs/internal/`
@@ -1017,6 +401,16 @@ For **contributors to SpecWeave itself** (not users).
 
 ## Marketplace Installation (CRITICAL)
 
+**⚠️ CRITICAL: NEVER suggest `bash scripts/refresh-marketplace.sh` to end users!**
+
+End users **don't have the `scripts/` folder** - they installed SpecWeave via npm globally.
+
+**Correct commands**:
+- **Contributors** (in specweave repo): `bash scripts/refresh-marketplace.sh`
+- **End Users** (user projects): `specweave refresh-marketplace`
+
+---
+
 ### For SpecWeave Contributors (Development)
 
 **ALWAYS use GitHub marketplace mode. NEVER use local symlinks or directory mode.**