safeword 0.2.4 → 0.2.6

package/.safeword/guides/user-story-guide.md

@@ -1,237 +0,0 @@
-# User Story Guide for Claude Code
-
-## How to Fill Out Feature User Stories
-
-**Template:** `@.safeword/templates/user-stories-template.md`
-
-**When user asks:** "Create user stories for issue #N" or "Create user stories for [feature]"
-
-**What you do:**
-1. Read `@.safeword/templates/user-stories-template.md`
-2. Fill in feature name, issue number, status
-3. Create numbered stories (Story 1, Story 2, etc.)
-4. Add acceptance criteria with ✅/❌ checkboxes for tracking
-5. Include test file references
-6. Add summary with completion % and phases
-7. Save to project location (e.g., `planning/user-stories/45-feature-name.md`)
-
-**DO include:**
-- Status tracking (✅/❌ per story and AC)
-- Test file references
-- Implementation status
-- Completion percentage
-- Phase tracking
-- Next steps
-
----
-
-## INVEST Validation (Do This Before Saving)
-
-After filling out story, mentally check:
-
-✅ **Independent** - Can be done without other stories?
-✅ **Negotiable** - Are details left for conversation?
-✅ **Valuable** - Does "So that" clearly state value?
-✅ **Estimable** - Can team estimate this (1-5 days)?
-✅ **Small** - Completable in one sprint?
-✅ **Testable** - Are acceptance criteria specific?
-
-**If ANY check fails → Refine or split the story**
-
----
-
-## Writing Good Acceptance Criteria
-
-**✅ GOOD - Specific, user-facing, testable:**
-- User can switch campaigns without page reload
-- Response time is under 200ms
-- Current campaign is visually highlighted
-- Error message explains what went wrong
-
-**❌ BAD - Vague, technical, or implementation:**
-- Campaign switching works ← Too vague
-- Use Zustand for state ← Implementation detail
-- Database is fast ← Not user-facing
-- Code is clean ← Not testable
-
----
-
-## Size Guidelines
-
-| Indicator | Too Big | Just Right | Too Small |
-|-----------|---------|------------|-----------|
-| Acceptance Criteria | 6+ | 1-5 | 0 |
-| Personas/Screens | 3+ | 1-2 | N/A |
-| Duration | 6+ days | 1-5 days | <1 hour |
-| **Action** | Split | ✅ Ship | Combine |
-
-**Decision rule:** When borderline (e.g., 5 AC but 2 personas), err on the side of splitting. Smaller stories are easier to estimate and complete.
-
----
-
-## Examples
-
-### ✅ GOOD Story
-
-**As a** player with multiple campaigns
-**I want** to switch between campaigns from the sidebar
-**So that** I can quickly resume different games
-
-**Acceptance Criteria:**
-- [ ] Sidebar shows all campaigns with last-played date
-- [ ] Clicking campaign loads it within 200ms
-- [ ] Current campaign is highlighted
-
-### ❌ BAD Story (Too Big)
-
-**As a** user
-**I want** a complete campaign management system
-**So that** I can organize my games
-
-**Acceptance Criteria:**
-- [ ] Create, edit, delete campaigns
-- [ ] Share campaigns with other players
-- [ ] Export/import campaign data
-- [ ] Search and filter campaigns
-- [ ] Tag campaigns by theme
-
-**Problem:** This is 5+ separate stories. Split it.
-
-### ❌ BAD Story (No Value)
-
-**As a** developer
-**I want** to refactor the GameStore
-**So that** code is cleaner
-
-**Problem:**
-- Developer is not a user
-- "Cleaner code" is not user-facing value
-- This is a technical task, not a user story
-
-### ✅ BETTER (Technical Story)
-
-**Technical Task:** Refactor GameStore to use Immer
-
-**Why:** Prevent state mutation bugs (3 bugs in last sprint)
-**Effort:** 2-3 hours
-**Test:** All existing tests pass, no new mutations
-
----
-
-## Conversation Starter, Not Contract
-
-**Remember:** User story is a placeholder for conversation.
-
-**During planning, discuss:**
-- Edge cases not in acceptance criteria
-- Technical approach (but don't document it in story)
-- Open questions or dependencies
-- How to split if too big
-
-**The story should NOT contain:**
-- Technical implementation details
-- Test strategies
-- UI mockups (link to them instead)
-- Definition of done (that's team-wide)
-
----
-
-## Technical Constraints Section
-
-**Purpose:** Capture non-functional requirements that inform test definitions. These are NOT user stories but constrain how stories are implemented.
-
-**When to use:** Fill in constraints BEFORE writing test definitions. Delete sections that don't apply—keep it lean.
-
-### Categories
-
-| Category | What It Captures | Examples |
-|----------|-----------------|----------|
-| Performance | Speed, throughput, capacity | Response time < 200ms, 1000 concurrent users |
-| Security | Auth, validation, rate limiting | Sanitized inputs, session required, 100 req/min |
-| Compatibility | Browsers, devices, accessibility | Chrome 100+, iOS 14+, WCAG 2.1 AA |
-| Data | Privacy, retention, compliance | GDPR delete in 72h, 90-day log retention |
-| Dependencies | Existing systems, restrictions | Use AuthService, no new packages |
-| Infrastructure | Resources, offline, deployment | < 512MB memory, offline-capable |
-
-### ✅ GOOD Constraints (Specific, Testable)
-
-```markdown
-### Performance
-- [ ] API response < 200ms at P95 under 100 concurrent users
-- [ ] Initial page load < 3s on simulated 3G
-
-### Security
-- [ ] All user inputs sanitized via DOMPurify
-- [ ] Rate limited: 100 requests/min per IP
-```
-
-### ❌ BAD Constraints (Vague, Untestable)
-
-```markdown
-### Performance
-- [ ] Should be fast ← How fast? Under what conditions?
-- [ ] Good performance ← Not measurable
-
-### Security
-- [ ] Secure ← What does this mean?
-- [ ] Protected from hackers ← Not specific
-```
-
-### Decision Rule
-
-**Include a constraint if:**
-- It affects how you write tests (performance tests, security tests)
-- It limits implementation choices (must use X, can't use Y)
-- Violating it would fail an audit or break SLAs
-
-**Skip if:**
-- It's a project-wide standard already in ARCHITECTURE.md
-- It's obvious (don't document "code must compile")
-
-### Tie-Breaking
-
-**If constraint fits multiple categories:** Choose the most specific one.
-
-| Constraint | Could Fit | Best Category | Why |
-|------------|-----------|---------------|-----|
-| API rate limit 100 req/min | Security, Performance | Security | Rate limiting is access control |
-| Page load < 3s on 3G | Performance, Compatibility | Performance | Speed is primary concern |
-| Must work offline | Infrastructure, Compatibility | Infrastructure | Offline is deployment concern |
-
-**Edge case:** If truly cross-cutting (e.g., "GDPR compliance" spans Data + Security), pick one and add a note: "See also: Security constraints"
-
----
-
-## LLM Optimization Tips
-
-**Core principle:** User stories are instructions that LLMs read and follow. Apply LLM instruction design best practices.
-
-**See:** `@.safeword/guides/llm-instruction-design.md` for comprehensive framework on writing LLM-consumable documentation.
-
-**When filling templates:**
-- Use specific, concrete language (not vague)
-- Avoid generic phrases ("improve UX", "make better")
-- Include numbers where relevant (200ms, 3 items, under 5 clicks)
-- Use concrete examples over abstract rules
-- Define all terms explicitly
-- Write for humans, not robots
-
-**Token efficiency:**
-- Template is 9 lines (minimal prompt caching cost)
-- No nested sections (flat structure)
-- No validation metadata in file
-
----
-
-## File Naming Convention
-
-Save stories as: `.safeword/planning/user-stories/[slug].md`
-
-**Good filenames:**
-- `campaign-switching.md`
-- `export-character-pdf.md`
-- `stress-tracking.md`
-
-**Bad filenames:**
-- `user-story-1.md` ← Not descriptive
-- `STORY_CAMPAIGN_SWITCHING_FINAL_v2.md` ← Bloated

package/.safeword/guides/zombie-process-cleanup.md

@@ -1,214 +0,0 @@
-# Zombie Process Cleanup (Multi-Project Environments)
-
-**When to use:** Working on multiple projects simultaneously, especially when they share tech stacks (Next.js, Playwright, etc.)
-
----
-
-## The Problem
-
-When running dev servers and E2E tests across multiple projects, zombie processes accumulate:
-- Dev servers holding ports
-- Playwright browser instances
-- Test runners stuck in background
-- Build processes from previous sessions
-
-**CRITICAL:** NEVER use `killall node` or `pkill -9 node` when working on multiple projects - this kills processes from ALL projects.
-
----
-
-## Port-Based Cleanup (Safest for Multi-Project)
-
-**Prerequisite:** Each project must use a different port (e.g., Project A: 3000, Project B: 3001)
-
-**Port convention:** Dev and test instances use different ports within the same project:
-- **Dev port**: Project's configured port (e.g., 3000, 5173, 8080) - manual testing
-- **Test port**: Dev port + 1000 (e.g., 4000, 6173, 9080) - Playwright managed
-
-See `testing-methodology.md` → "E2E Testing with Persistent Dev Servers" for full port isolation strategy.
-
-**Decision rule:** If unsure which cleanup method to use → port-based first (safest), then project script, then tmux.
-
-**Recommended cleanup pattern** (replace ports with your project's ports):
-
-```bash
-# Kill both dev server AND test server ports
-# Example: Next.js (3000/4000), Vite (5173/6173), or your project's ports
-lsof -ti:3000 -ti:4000 | xargs kill -9 2>/dev/null
-
-# Kill Playwright processes launched from THIS directory
-pkill -f "playwright.*$(pwd)" 2>/dev/null
-
-# Wait for cleanup
-sleep 2
-```
-
-**Why this works:**
-- ✅ Dev + test ports are unique to this project → safe to kill
-- ✅ `$(pwd)` ensures only THIS project's tests are killed
-- ✅ Other projects completely untouched
-
----
-
-## Project-Specific Cleanup Script
-
-For frequent cleanup needs, create `scripts/cleanup.sh` in each project:
-
-```bash
-#!/bin/bash
-# scripts/cleanup.sh - Kill only THIS project's processes
-
-DEV_PORT=3000                    # Dev server port (change per project)
-TEST_PORT=$((DEV_PORT + 1000))   # Test server port (Playwright managed)
-PROJECT_DIR="$(pwd)"
-
-echo "Cleaning up $PROJECT_DIR (dev: $DEV_PORT, test: $TEST_PORT)..."
-
-# Kill both dev and test servers by port
-lsof -ti:$DEV_PORT -ti:$TEST_PORT | xargs kill -9 2>/dev/null
-
-# Kill Playwright browsers for this project
-ps aux | grep -E "(playwright|chromium)" | grep "$PROJECT_DIR" | grep -v grep | awk '{print $2}' | xargs kill -9 2>/dev/null
-
-# Kill test runners
-pgrep -f "playwright test.*$(basename $PROJECT_DIR)" | xargs kill -9 2>/dev/null
-
-echo "Cleanup complete!"
-```
-
-**Make executable:** `chmod +x scripts/cleanup.sh`
-
-**Usage:** `./scripts/cleanup.sh`
-
----
-
-## Common Patterns by Tech Stack
-
-### Next.js Projects
-
-```bash
-# Kill Next.js dev server (port 3000)
-lsof -ti:3000 | xargs kill -9 2>/dev/null
-
-# Kill Next.js build processes for this project
-ps aux | grep "next dev" | grep "$(pwd)" | grep -v grep | awk '{print $2}' | xargs kill -9 2>/dev/null
-```
-
-### Playwright E2E Tests
-
-```bash
-# Kill Playwright browsers and test runners
-pkill -f "playwright.*$(pwd)" 2>/dev/null
-
-# Or more specific (by project name)
-pkill -f "playwright.*my-project-name" 2>/dev/null
-```
-
-### Vite Projects
-
-```bash
-# Kill Vite dev server (typically port 5173)
-lsof -ti:5173 | xargs kill -9 2>/dev/null
-```
-
-### React Native / Expo
-
-```bash
-# Kill Metro bundler (port 8081)
-lsof -ti:8081 | xargs kill -9 2>/dev/null
-
-# Kill Expo dev tools (port 19000-19006)
-lsof -ti:19000-19006 | xargs kill -9 2>/dev/null
-```
-
----
-
-## Alternative: tmux/Screen Sessions
-
-For complete isolation, run each project in its own terminal session:
-
-```bash
-# Start project in named session
-tmux new -s project-name
-# Run dev server here
-
-# Kill everything in this session only
-tmux kill-session -t project-name
-```
-
-**Pros:**
-- ✅ Complete isolation between projects
-- ✅ One command kills everything
-- ✅ Can detach/reattach sessions
-
-**Cons:**
-- ⚠️ Requires learning tmux
-- ⚠️ Different workflow
-
----
-
-## Best Practices
-
-1. **Assign unique ports** - Set `PORT=3000` in one project, `PORT=3001` in another
-2. **Use port-based cleanup first** - Simplest and safest
-3. **Create project cleanup scripts** - Reusable, documented
-4. **Never `killall node`** - Too broad when working on multiple projects
-5. **Clean up before starting** - Run cleanup script before `npm run dev`
-6. **Check what's running** - Use `lsof -i:PORT` to see what's using a port
-
----
-
-## Debugging Zombie Processes
-
-### Find What's Using a Port
-
-```bash
-# Check what's on port 3000
-lsof -i:3000
-
-# More details
-lsof -i:3000 -P -n
-```
-
-### Find All Node Processes
-
-```bash
-# List all node processes
-ps aux | grep -E "(node|playwright|chromium)"
-
-# More detailed (with working directory)
-lsof -p $(pgrep node) | grep cwd
-```
-
-### Find Processes by Project Directory
-
-```bash
-# Find processes running in specific directory
-ps aux | grep "/Users/alex/projects/my-project"
-```
-
----
-
-## Quick Reference
-
-| Situation | Command |
-|-----------|---------|
-| Kill dev + test servers (use your ports) | `lsof -ti:$DEV_PORT -ti:$TEST_PORT \| xargs kill -9 2>/dev/null` |
-| Kill Playwright (this project) | `pkill -f "playwright.*$(pwd)"` |
-| Kill all for this project | `./scripts/cleanup.sh` |
-| Check what's on port | `lsof -i:3000` |
-| Find zombie processes | `ps aux \| grep -E "(node\|playwright\|chromium)"` |
-| Kill by process ID | `kill -9 <PID>` |
-
----
-
-## What NOT to Do
-
-❌ **DON'T:** `killall node` (kills all projects)
-❌ **DON'T:** `pkill -9 node` (kills all projects)
-❌ **DON'T:** Kill processes without checking working directory
-❌ **DON'T:** Assume zombie browsers will clean themselves up (they won't)
-
-✅ **DO:** Use port-based cleanup
-✅ **DO:** Filter by project directory with `$(pwd)`
-✅ **DO:** Create project-specific cleanup scripts
-✅ **DO:** Clean up before AND after development sessions