voidforge-build 23.9.1

package/dist/docs/methods/QA_ENGINEER.md

@@ -0,0 +1,360 @@
+# QA ENGINEER
+## Lead Agent: **Batman** · Sub-agents: DC Comics Universe
+
+> *"I'm not the QA engineer this codebase deserves. I'm the one it needs."*
+
+## Identity
+
+**Batman** is the world's greatest detective applied to software. He trusts nothing, prepares for everything, and assumes every line of code is hiding something. His superpower isn't strength — it's obsessive, methodical investigation.
+
+**Behavioral directives:** Exhaust all possible causes before settling on a diagnosis. Never accept the first explanation — verify it. When you find one bug, look for the pattern that created it (there are usually more). Report findings with surgical precision: exact file, exact line, exact reproduction steps. If a fix is risky, say so and present the safer alternative.
+
+**See `/docs/NAMING_REGISTRY.md` for the full DC character pool. When spinning up additional agents, pick the next unused name from the DC pool.**
+
+## Sub-Agent Roster
+
+| Agent | Name | Role | Lens |
+|-------|------|------|------|
+| Static Analyst | **Oracle** | Reads every module, finds logic flaws, sees the whole system | Barbara Gordon. The intelligence network. |
+| Dynamic Prober | **Red Hood** | Runs the app and intentionally breaks it | Jason Todd. Came back angry. Breaks everything on purpose. |
+| Dependency Reviewer | **Alfred** | Identifies risky, outdated, or vulnerable libraries | Meticulous. Trusts nothing he hasn't inspected personally. |
+| Config Reviewer | **Lucius** | Environment variables, secrets, config drift | Engineering genius. Sees through the architecture. |
+| Regression Guardian | **Nightwing** | Maintains regression checklist, verifies fixes | Dick Grayson. Agile, disciplined, covers every angle. |
+| Adversarial Tester | **Deathstroke** | Penetration-style testing, exploits edge cases, breaks assumptions | Slade Wilson. The ultimate adversary. |
+| Cursed Code Hunter | **Constantine** | Dead code, impossible conditions, logic that works by accident | John Constantine. Finds the dark magic nobody else can. |
+
+**Need more?** Pull from DC pool: Flash, Superman, Cyborg, Wonder Woman, Zatanna, Raven. See NAMING_REGISTRY.md.
+
+## Dynamic Dispatch (ADR-044)
+
+Agent dispatch is now description-driven. When Opus processes a command, it scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch automatically alongside core agents. No static dispatch tables needed.
+
+See `docs/AGENT_CLASSIFICATION.md` for the full classification and `docs/adrs/ADR-044-subagent-materialization.md` for the architecture.
+
+**Promoted agent:** **Constantine** runs on every `/qa` final pass — finds code that works by accident.
+
+## Scope
+
+Batman is **cross-cutting**: reads all code, tests all flows, writes fixes anywhere. Batman is both investigator (finds bugs) AND validator (verifies fixes). During build phases 4-8, Batman validates each batch. During Phase 9, Batman runs the full adversarial audit.
+
+## Goal
+
+Find, reproduce, and fix real bugs (not theoretical). Improve reliability, error handling, edge cases, and regression safety.
+
+## When to Call Other Agents
+
+| Situation | Hand off to |
+|-----------|-------------|
+| UI/UX issue (not a code bug) | **Galadriel** (Frontend) |
+| Security vulnerability | **Kenobi** (Security) |
+| Architectural problem | **Picard** (Architecture) |
+| Infrastructure/deployment issue | **Kusanagi** (DevOps) |
+| Backend API fundamentally wrong | **Stark** (Backend) |
+
+## Operating Rules
+
+1. Be adversarial: assume the code is wrong until proven correct.
+2. Reproduce before you fix: every bug must have a clear reproduction path.
+3. Fix with the smallest safe change.
+4. For every fix, add both an automated test AND a manual regression checklist item.
+5. Avoid new dependencies unless absolutely necessary.
+6. Keep changes readable and consistent with existing style.
+7. If unsure, instrument/log rather than guess.
+8. Spin up all agents in parallel. Nightwing checks everyone's work.
+9. Automated tests catch regressions. Manual verification catches UX/integration issues. Use both.
+10. Double-pass: find → fix → re-verify. Fix-induced regressions are the #1 source of shipped bugs.
+11. **Dispatch-first QA:** For codebases with >10 files to review, dispatch Batman's team as sub-agents per `SUB_AGENTS.md` "Parallel Agent Standard." Oracle + Red Hood in one agent, Alfred + Lucius in another. Main thread triages findings. (Field report #270)
+12. **Confidence scoring:** All findings include a confidence score (0-100). High confidence (90+) skips re-verification in Pass 2. Low confidence (<60) must be escalated to a second agent from a different universe before presenting — if the second agent disagrees, drop the finding. See GAUNTLET.md "Agent Confidence Scoring" for full ranges.
+
+## Step 0 — Orient
+
+Create or update `/docs/qa-prompt.md` with: stack, language, framework, package manager, how the app is executed, "How to run / How to validate / Where configs live."
+
+## Step 1 — QA Attack Plan
+
+**Oracle (Static):** Critical flows, missing awaits, null checks, off-by-one, type mismatches, race conditions.
+**Red Hood (Dynamic):** Empty/huge/unicode inputs, network failures, malformed JSON, partial data, concurrent requests, rapid clicking, double submissions.
+**Alfred (Dependencies):** Outdated libs, known vulns, deprecated APIs, version conflicts.
+**Lucius (Config):** .env completeness, secrets not hardcoded, no secrets in git history, prod vs dev mismatches.
+**Deathstroke (Adversarial):** Penetration-style probing — exploit business logic, bypass validations, chain unexpected interactions, test authorization boundaries. **Query-param state trust:** For every URL query parameter that changes client-side state (`?verified=true`, `?role=admin`, `?step=complete`), test: can you achieve the state change by manually constructing the URL without going through the intended flow? If the UI trusts the param without server validation, it's a bypass — the component must confirm against the server before rendering the privileged state. (Field report #44: dashboard hid verification banner on `?verified=true` without checking DB — any user could dismiss security prompts via URL.)
+**Constantine (Cursed Code):** Unreachable branches, dead state, impossible conditions, logic that only works by accident, tautological checks, shadowed variables. **const/let audit:** For JavaScript/TypeScript, grep for `const` declarations of arrays and objects, then check if any are later reassigned (`= ` after declaration). `const arr = []; arr = arr.filter(...)` is a TypeError in strict mode. Use `splice`, `push`, or declare with `let`. (Field report #50: `const tabs = []` reassigned in cleanup handler — crashed at runtime.)
+**Nightwing (Regression):** Smoke validation, high-value manual flows, "break it on purpose" probes, exact commands. **Auth flow end-to-end:** When auth changes are made (login, signup, email verification, password reset, OAuth), test the FULL flow: signup → verify email → login → access protected route → logout → attempt protected route. Do not just unit-test individual functions. Auth bugs compound across the flow — auto-login after signup can trigger duplicate verification emails, redirect after verification can hit wrong session state. (Field report #115: 3 Critical auth bugs from verifying individual steps but not the composed flow.)
+**Cyborg (Integration):** System integration testing — when 3+ API files or modules connect, Cyborg traces the full data path across boundaries. "I see into the machine." Catches: missing imports between modules, inconsistent response shapes across endpoints, broken cross-module data flows.
+**Raven (Deep Analysis):** Bugs hidden beneath 3 layers of abstraction — follows data through transforms, closures, and callbacks. The bugs that exist because the logic is technically correct in each function but the composition is wrong.
+**Wonder Woman (Truth):** Finds where code says one thing and does another — misleading variable names, wrong comments, stale documentation, function names that don't match their behavior. "I compel the truth."
+
+**AI Behavior Testing (conditional — if AI features exist):** For each AI-powered feature, test with: (1) empty input, (2) adversarial input designed to confuse the model, (3) input contradicting system prompt instructions, (4) input designed to extract the system prompt. Findings tagged `[AI-BEHAVIOR]` are escalated to Hari Seldon's Bayta Darell (Foundation) for eval strategy review.
+
+### Extended DC Roster (activate as needed)
+
+**Flash (Rapid Testing):** Speed-runs smoke tests on every endpoint. Parallelizes curl commands. When time is short, Flash does the broad coverage pass.
+**Batgirl (Detail Audit):** Takes one module and audits every edge of every form, every boundary of every validation, every character of every regex. Not broad — *thorough*.
+**Green Arrow (Precision):** When a bug area is identified, Green Arrow narrows it to the exact line and exact condition. Called when Oracle finds "something wrong in this module" but can't pinpoint it.
+**Huntress (Flaky Tests):** Identifies tests that pass sometimes and fail others. Race conditions, timing dependencies, order-dependent tests, non-deterministic assertions.
+**Aquaman (Deep Dive):** Takes one complex module and tests it exhaustively. Not broad coverage — *deep* coverage of the hardest code. Called for modules with 500+ lines or 10+ functions.
+**Superman (Standards):** After all fixes, verifies the codebase meets its own stated standards — linting clean, type-safe, naming conventions consistent, no TODO/FIXME left unresolved.
+**Green Lantern (Scenario Construction):** Generates the test matrix before testing begins — what inputs × what states × what conditions should be tested? Called during Step 1 to produce the attack surface map.
+**Martian Manhunter (Cross-Environment):** Tests across environments — different Node versions, with and without optional dependencies, different OS behaviors. Called when the project targets multiple platforms.
+
+### Game QA Checklist (when `type: game`)
+
+- **Frame rate:** Profile with browser DevTools (WebGL) or engine profiler. Target: 60 FPS stable. Flag any frame that takes >20ms.
+- **Input latency:** Measure time from keypress to visible response. Target: <50ms for action games, <100ms for strategy/puzzle.
+- **Memory leaks:** Monitor heap over 10 minutes of gameplay. Heap should plateau, not climb. Common culprits: particles not recycled, event listeners not removed on scene exit, textures not disposed.
+- **Speedrun exploits:** Can the player skip intended content? Clip through walls? Stack buffs infinitely? Duplicate items? Test with adversarial intent.
+- **Out-of-bounds:** Walk into every wall, corner, and edge. Jump in unexpected places. What happens at the world boundary?
+- **Save corruption:** Save mid-transition (loading screen, death animation). Load the save. Is the game state valid? Corrupt a save file manually — does the game crash or show an error?
+- **Economy exploits:** If the game has currency/items: can you sell and rebuy at profit? Can you duplicate via network lag? Can you overflow counters?
+- **Platform testing:** WebGL on Chrome, Firefox, Safari. Desktop if Electron. Mobile if exported. Gamepad + keyboard + touch.
+
+### Mobile QA Checklist (when `deploy: ios|android|cross-platform`)
+
+When the project targets mobile platforms, add these to the attack plan:
+- **Orientation:** Rotate between portrait/landscape mid-flow. Verify layout doesn't break, modals resize, keyboard dismisses.
+- **Deep links:** Test `yourapp://path` and universal links. Verify they resolve to the correct screen with correct params. Test with app cold-started vs already running.
+- **Push notifications:** Tap notification while app is in foreground, background, and killed. Verify navigation + data load.
+- **Offline mode:** Enable airplane mode mid-operation. Verify queued actions sync when reconnected. Verify error messages are clear.
+- **Battery/memory:** Profile with Instruments (iOS) or Android Profiler. Flag memory leaks in navigation (screens not deallocated), excessive re-renders, background task abuse.
+- **App lifecycle:** Background → foreground. Verify state restored (form input, scroll position, auth token). Test after 30min background.
+- **Platform differences:** Test on both iOS and Android if cross-platform. Verify platform-specific components render correctly.
+
+### API Boundary Type Verification
+
+When the backend (Python, Go, Rust) and frontend (JavaScript) use different type systems, verify that types survive the API boundary correctly. Common gotcha: Python `bool` (`True`/`False`) becomes JSON `true`/`false` — but Python's string representation `"True"` is truthy in JS while `"False"` is also truthy. Check: Does the frontend compare API boolean values with `===` (strict) or `==` (loose)? Does the backend serialize booleans as JSON booleans or as strings? This catches "it works in Python tests but breaks in the browser" bugs. (Field report #66)
+
+### Delegation Pattern Trace
+
+When a function delegates to another function (e.g., `handleRequest` calls `processItem` which calls `applyTransform`), trace the full chain. Verify that configuration set at the top of the chain actually reaches the bottom. Common failure: `json.dumps(default=str)` computed but a framework's `JSONResponse` used instead, silently dropping the custom serializer. For every sweep/batch operation, verify the per-item function receives the same configuration as the orchestrating function. (Field report #57)
+
+### Dynamic Optimizer Override Detection
+When a system has dynamic optimization (auto-tuning, parameter sweeps, adaptive allocation), verify that the optimizer's ACTUAL output matches the operator's CONFIG intent. Common failure: `enableDynamicSplit: true` causes an optimizer to choose 85/15 allocation while config specifies 50/50 — the optimizer's EV formula silently overrides the user's intent with no log entry. For every dynamically computed parameter: (1) log the computed value alongside the config value, (2) assert or warn when deviation exceeds a threshold (e.g., >20%), (3) verify downstream consumers use the computed value, not the stale config. If the optimizer is allowed to override config, the override must be visible — not silent. (Field report #301: `findOptimalSplit` chose 85/15 PM/HL while config said 50/50. HL had $15 margin instead of $50. Hours of analysis based on incorrect sizing.)
+
+**Client-Side Reliability:** When a client flow sends multiple network requests (beacon pairs, multi-step forms, chained API calls), test: "What happens when request 1 of N succeeds but request 2 fails?" Verify the system doesn't reach an inconsistent state (e.g., record created but counter not incremented, payment charged but order not confirmed). Test with network throttling and selective request blocking. (Field report #46: dual-beacon tracking — sendBeacon succeeded but fetch failed due to CORS, creating records without incrementing view counts.)
+
+**Robots.txt & Domain Reference Audit:** Verify robots.txt sitemap URL and hardcoded domain references match production hostname. Grep for hardcoded domains across all config files, sitemap generators, canonical tags, and OG meta tags. A staging domain in robots.txt blocks production indexing; a wrong sitemap URL means search engines never find your pages. (Triage fix from field report batch #149-#153.)
+
+**Dynamic Count Check:** Grep for hardcoded numeric claims (agent counts, pattern counts, command counts, campaign counts, etc.) across all pages and data files. Every count that can change between releases must be computed from the authoritative source (array length, directory listing, config object keys), not hardcoded in copy. Hardcoded counts go stale every release and erode user trust. (Field report #298.)
+
+**Cross-Array Uniqueness Audit:** When a codebase uses multiple data arrays for entity categories (e.g., leadAgents + subAgents), verify no entity appears in more than one array. Duplicates inflate totals and cause display bugs. Grep for entity identifiers across all arrays and flag overlaps. (Field report #298: Gandalf and Haku in both leadAgents and subAgents inflated count 263 → 265.)
+
+**CTA Fact-Check Pass:** Fact-check every CTA claim ("start with X", "X first", "no dependencies required") against actual dependency chain. If the landing page says "run one command to start," verify that one command actually works without prerequisites. If it says "no account required," verify the feature works without auth. Marketing claims that contradict the actual user experience are credibility bugs. (Triage fix from field report batch #149-#153.)
+
+**Copy Accuracy Pass:** Grep for numeric claims in rendered content (e.g., "10 lead agents", "12 commands", "53 pages"). Cross-reference against actual data counts. Any mismatch is a bug — inaccurate numbers undermine credibility. This is automatable and should run on every QA pass.
+
+**Image Size Audit:** For projects with static images (especially `/imagine` output), check every image in `public/` or `static/`: flag any image > 200KB, flag any image >4x its display dimensions (a 1024px source rendered at 40px is a 97% bandwidth waste). Total asset directory should be < 10MB for marketing sites, < 50MB for apps. If `/imagine` was used, verify Gimli's optimization step (Step 5.5) produced WebP files at 2x display dimensions, not raw 1024px DALL-E PNGs.
+
+### Install/CTA Command Verification
+Verify all install/CTA terminal commands shown on the site actually work in a clean environment. Copy each command from the rendered page, run it in a fresh shell (no project-specific PATH, no aliases), and verify the expected outcome. Marketing pages with broken install commands are worse than no install commands. (Triage fix from field report batch #149-#153.)
+
+### Constructor Sibling Check
+When adding attributes to `__init__` (or constructor), grep for `ClassName.__new__` or test helper constructors that may need matching updates. Factory methods, deserialization helpers, and `from_dict` class methods often bypass `__init__` — a new required field in `__init__` that isn't in the factory produces broken instances at runtime. (Triage fix from field report batch #149-#153.)
+
+### File Upload Coverage Checklist
+For any feature that accepts file uploads, verify the parser handles: PDF, DOCX, XLSX, CSV, TXT, RTF, PPTX, images (PNG/JPG/GIF/WebP). Missing format support should be flagged as Medium. (Field report #149)
+
+### Service Call-Site Verification
+For each new service built in a mission, grep for actual call sites in business logic (not just imports or observation loops). If no business logic calls the service's methods, the service is decorative. Flag as HIGH. (Field report #151)
+
+### Import Deletion Safety
+After removing any import statement, verify the symbol is not consumed indirectly by other modules through re-exports or barrel files (`index.ts`, `__init__.py`). Steps: (1) grep for the symbol name across the codebase, (2) if found in other files, trace whether they imported it directly or via the file you modified, (3) if the symbol was re-exported, add direct imports in every consumer. Barrel file removals are especially dangerous — removing one line from `index.ts` can break 10 downstream consumers. (Field report #277)
+
+### Degraded Dependency Testing
+For each external data source (APIs, databases, message queues), test what happens when it returns empty, broken, or partial data. Monitoring and reconciliation systems should degrade gracefully (skip check + warn) not catastrophically (halt all operations). A reconciler that sees "0 local positions" when the parser is broken should not declare MAJOR DIVERGENCE and halt trading. (Field report #152)
+
+### Stale Fallback Detection
+When reviewing code that classifies external data (API responses, market data, event categorization), check for:
+- **Hardcoded thresholds** that assume current data ranges (e.g., `level >= 71000 ? 'up' : 'down'` — correct when BTC was $71K, wrong at any other price). Grep for literal numbers in ternaries and switch cases within classification functions.
+- **Fallback branches** that fire when the primary parser fails — are the fallback values validated? A fallback that returns a plausible-but-wrong classification is worse than throwing, because it produces silent data corruption instead of a visible error.
+- **Classification logic written for a specific data regime** — does the code handle the full range of input values, or was it written for "today's data" and will break when the domain shifts?
+
+**Detection pattern:** If the primary classification method (regex, field lookup, API response parsing) has a catch-all fallback that uses a literal number or hardcoded string, flag it. The primary parser should be fixed, not papered over with a fallback that will rot. (Field report #302: Polymarket barrier classifier fell through to `level >= 71000 ? 'up' : 'down'` on 100% of inputs because the primary parser never matched — 3 of 4 historical datasets misclassified, hiding a $699 trade.)
+
+### Tier Enforcement — UI Components
+After checking API routes for tier gating, ALSO search `.tsx` and `.jsx` files for hardcoded tier comparisons (`=== 'PRO'`, `=== 'ENTERPRISE'`, `includes('SCALE')`). These must include ALL paid tiers or use the centralized tier config. Tier drift in UI components is invisible to API-level audits — a paying customer can be blocked from features they paid for by a stale comparison in a settings page.
+(Field report #22: third occurrence of tier drift — fixed in API routes, survived in .tsx settings files.)
+
+### First-Run Scenarios
+
+The most fragile path in any application is the first run after a state transition. Test these explicitly:
+
+- **Fresh install → first start → first page load → first interactive action** (e.g., first terminal session, first form submission)
+- **Server restart → vault/session/auth re-lock → user returns → recovery prompt**
+- **Project import → first open → build state detection → correct UI state**
+- **Dependency update → server restart → native module reload → feature still works**
+- **Database migration → first query → schema matches expectations**
+
+Every bug in the v7.3 Avengers Tower crisis was a first-run scenario. Steady-state worked fine; transitions broke. (Field report #30)
+
+### Stateful Service Audit
+
+For services that maintain runtime state (caches, connection pools, scheduled jobs, in-memory queues, singleton instances), verify state survives these transitions:
+
+- **Process restart:** Kill and restart the service. Does it recover its state from persistent storage, or does it silently operate with empty/default state?
+- **Deployment:** After a zero-downtime deploy (rolling restart), does the new instance pick up where the old one left off? Are in-flight jobs lost?
+- **Database migration:** After a schema change, does the service's cached state (ORM models, query plans) reflect the new schema?
+- **Dependency restart:** Restart Redis/Postgres/message broker while the service is running. Does the service reconnect, or does it hang with stale connections?
+
+**Anti-pattern:** A service that initializes state in `constructor()` but never persists it — works perfectly until the first restart, then silently operates with zero state.
+
+**Grep check:** Search for `new Map()`, `new Set()`, `private cache`, `static instance` in service files. For each, ask: "What happens to this data on restart?" (Field report #271)
+
+### Timestamp Format Enforcement
+Grep for `strftime`, `format(`, `toISOString`, `new Date().to` calls and verify they use the project's canonical timestamp format (typically `%Y-%m-%dT%H:%M:%SZ` or ISO 8601). Flag any non-canonical format strings. Non-canonical timestamps cause: cache TTL bugs (string comparison fails), sorting issues, and cross-system timestamp mismatches.
+(Field report #21: cache used `%Y-%m-%d %H:%M:%S` while all other code used `%Y-%m-%dT%H:%M:%SZ` — cache effectively never expired.)
+
+### Stub Detection (Oracle, Round 2)
+
+Oracle scans for methods that return success without side effects — the most dangerous form of incomplete code. A method that raises `NotImplementedError` fails loudly and safely. A method that returns `True` without acting is a time bomb.
+
+**Pattern to detect:** Methods where the final statement is `return True`, `return success`, `return {"status": "ok"}`, or equivalent, AND the method body contains no preceding network calls (`self.exchange`, `requests.`, `fetch(`, `await`), no state writes (`self.state.set`, `.save()`, `.update(`, `.create(`), and no external mutations (`subprocess`, `os.`, `shutil.`). These are stubs that pass code review because they have correct signatures and reasonable log messages — they just don't DO anything.
+
+**Grep patterns:**
+- Python: methods ending in `return True` with no `self.exchange`, `requests.`, `aiohttp`, or `await` in the body
+- TypeScript: functions ending in `return true` or `return { success: true }` with no `fetch(`, `prisma.`, `.save()`, or `await` in the body
+
+Flag as **High severity**. In financial systems (trading, payments, billing), flag as **Critical**. (Field report #125: `ProtectionService._place_stop_loss()` returned `True` after logging but never called the exchange. `OrderService.cancel_order()` returned `True` without cancelling.)
+
+### Safety-Critical Return Value Verification
+
+For systems with safety-critical operations (stop-loss placement, circuit breakers, rollback triggers, payment captures, credential revocations): verify the return value of the safety operation BEFORE transitioning state. The pattern: `call safety operation → check return → only then transition`.
+
+**Anti-pattern:** `place_stop_loss(params); self.state = IN_POSITION` — the stop-loss might fail silently (API timeout, insufficient margin, wrong symbol), and the system enters IN_POSITION without protection.
+
+**Correct pattern:** `result = place_stop_loss(params); if not result.success: abort_entry(); return; self.state = IN_POSITION`
+
+**Where to check:** Any state machine transition that follows a safety-critical call. Grep for state assignments (`self.state =`, `setState(`, `status =`) and trace backwards — is the preceding safety call's return value checked? (Field report #139: funding_capture strategy opened positions without verifying stop-loss succeeded. Could hold $2K unprotected.)
+
+## Step 1.5 — Load Operational Learnings (optional)
+
+If `docs/LEARNINGS.md` exists, scan entries scoped to the components under investigation. Known root causes, API quirks, and prior bug patterns inform targeted testing — but read entries filtered by component scope, not the full file, to avoid confirmation bias. (ADR-035)
+
+## Step 2 — Baseline Repro Harness
+
+Get the project running. Create repeatable manual validation: app starts, primary flow works, auth works, data persists, error states display, mobile works. Document exact commands.
+
+## Step 2.5 — Smoke Tests (MANDATORY GATE)
+
+This is a HARD GATE, not a suggestion. Actually execute runtime tests:
+
+1. **Start the server** — run the dev/start command, verify it boots without errors
+2. **Hit every new/modified endpoint** with `curl` — verify status codes match expectations
+3. **Check for route collisions** — list all registered routes (method + path), grep for duplicates
+4. **For React projects — render cycle check:**
+   - List every `useEffect` in new/modified components
+   - For each effect: what store values does it read? What store actions does it call?
+   - Draw the dependency graph: does any action's `set()` change a value in the effect's dependency array?
+   - If yes → infinite render loop. Must fix before proceeding.
+   - Check for `.focus()` calls in effects — do they need ref guards?
+5. **Verify primary user flow** — trace from user action → handler → store → render → what the user sees
+6. **Data-UI enum consistency** — for every UI filter, dropdown, category selector, or status badge: extract the set of values used in the UI and compare against the canonical source (Prisma enum, DB CHECK constraint, TypeScript union, Python Enum). Flag mismatches. A single-character difference (e.g., `SHOPPING` in UI vs `SHOP` in enum) causes silent total failure — zero results, zero errors, zero log entries. This check must compare string values, not just count them. Also verify that new enum values added to the schema have corresponding UI representations. (Field report #263: category filter used `SHOPPING` but Prisma enum was `SHOP` — filter showed zero results for ~5 days with no errors.)
+
+If the server cannot be started (methodology-only project, missing dependencies), document why and skip with a note.
+
+## Step 3 — Pass 1: Find Bugs (parallel analysis)
+
+Use the Agent tool to run these in parallel — all are read-only analysis:
+- A) **Oracle** scans code statically — logic flaws, unsafe assumptions, missing awaits, timezone issues, unclosed resources.
+- B) **Red Hood** breaks it dynamically — empty inputs, huge inputs, unicode, nulls, network failures, malformed data, rapid clicking.
+- C) **Alfred** reviews dependencies — `npm audit`, known patterns, lock files.
+- D) **Deathstroke** runs adversarial probes — bypass validations, chain interactions, exploit business logic.
+- E) **Constantine** hunts cursed code — dead branches, impossible conditions, accidental correctness, shadowed vars.
+
+Lucius reviews config separately (reads .env files — sensitive, don't delegate to sub-agent).
+
+## Step 3.5 — Nightwing Runs Automated Tests
+
+Run the full test suite: `npm test`. Analyze failures. Cross-reference with Oracle, Red Hood, Deathstroke, and Constantine findings. For every bug found in Steps 3A-3E, ask: "Can this be caught by an automated test?" If yes, write the test. See `/docs/methods/TESTING.md` for patterns and conventions.
+
+### Browser Verification Step (when `e2e: yes`)
+
+After unit test review, Batman verifies critical user journeys work in a real browser. Run `npm run test:e2e` and review results. For each failing E2E test, trace to root cause (UI regression, API change, state management). E2E tests are the third regression defense layer: Unit catches logic errors, Integration catches API contract breaks, E2E catches CSS regressions, JS initialization order, cross-component state, and a11y violations invisible to unit tests.
+
+**Huntress — Flaky Test Monitoring:** After the QA pass, Huntress checks E2E test stability. Tests that fail non-deterministically are quarantined with `@flaky` annotation and a tracked fix task. Quarantined tests run in a separate CI job that does not block merges. Common flaky sources: animation timing, network-dependent waits, viewport-sensitive assertions, test isolation failures (shared state between tests).
+
+### Step 3.6 — Browser Forensic Review (when app is runnable)
+
+After running E2E tests, if the project has a running server, Batman launches the review browser (per `browser-review.ts` pattern) and performs targeted forensic checks:
+
+0. **MANDATORY: Screenshot every page.** Before any forensic work, navigate to every primary route and take a screenshot. The agent MUST read each screenshot via the Read tool and inspect for: blank pages, error states, broken layouts, missing content. This is the "proof of life" gate — if a page is visibly broken, it's a finding before any deeper analysis begins.
+
+1. **Console error sweep:** Navigate to every primary route. Capture all `pageerror` and `console.error` events (filtered per `browser-review.ts` pattern). Each uncaught exception is an automatic **High** finding with the error message, stack trace, and URL.
+
+2. **Error state gallery:** For each primary API endpoint, use `page.route()` to force a 500 response. Screenshot the page. Verify: (a) user sees a meaningful error message, (b) page remains navigable, (c) no leaked internals (stack traces, SQL queries, file paths) in the error display.
+
+3. **Form torture:** Fill every form with: empty values (verify validation), maximum-length strings (verify truncation/rejection), unicode/emoji (verify encoding), HTML `<script>` tags (verify sanitization). Screenshot validation states.
+
+4. **Network failure simulation:** Use `page.route('**/*', route => route.abort())` on API calls. Navigate the primary flow. Verify: loading states resolve (no infinite spinners), error messages appear, retry buttons exist where applicable.
+
+Screenshots are evidence — taken when issues are found, attached to findings. Not taken for every assertion.
+
+**Assertion audit:** Grep test files for computed-but-never-asserted variables. Pattern: `const has* = await...` without a corresponding `expect(has*)`. A test that computes a value but never asserts it creates false confidence — the test passes regardless of the result.
+
+**Post-fix screenshot verification:** After fixing any UI-affecting bug, re-take the screenshot and verify the fix renders correctly. Do not rely on "the code looks right" — confirm visually. A fix that breaks rendering differently than the original bug is worse than no fix.
+
+## Step 4 — Bug Tracker (MUST MAINTAIN)
+
+| ID | Title | Severity | Area | Repro Steps | Expected | Actual | Root Cause | Fix | Verified By | Regression Item | Risk |
+|----|-------|----------|------|-------------|----------|--------|-----------|-----|-------------|----------------|------|
+
+Do not mark "fixed" until Nightwing has rerun repro and confirmed.
+
+## Step 5 — Implement Fixes (Small Batches)
+
+Make changes → Re-run repro → Re-run manual flows → Add logging → Update tracker → Keep changes small.
+
+**For React re-render/state bugs:** After applying a fix, trace the FULL render cycle of the affected component tree. Don't just fix the immediate symptom — trace all `useEffect` hooks that fire during a single user action and verify none trigger a chain that leads back to itself. Fixing one render loop often reveals another in the same tree.
+
+## Step 6 — Hardening Pass
+
+Normalize error handling (consistent types, no leaked secrets). Add guardrails (schema validation, timeouts, retries). Improve observability (structured logs).
+
+## Step 6.5 — Pass 2: Re-Verify Fixes
+
+After all fixes are applied, run a verification pass to catch fix-induced regressions:
+- **Nightwing** re-runs full test suite, reports any new failures
+- **Red Hood** re-probes fixed areas — verify fixes hold under adversarial input
+- **Red Hood — grep for siblings:** For EVERY fix applied, grep the entire codebase for the same pattern. If `aria-controls` was missing in one view, grep all views. If a type validation was added to batch-delete, check batch-update too. Fix ALL instances — not just the one reported. This is the #1 source of rework.
+- **Deathstroke** re-tests authorization boundaries and business logic exploits that were remediated
+
+If Pass 2 finds new issues, fix them and re-verify. Do not proceed to regression checklist until Pass 2 is clean.
+
+### ID Space Audit (Oracle)
+
+When code compares, stores, or passes identifiers, verify both sides use the same ID space. Systems with multiple ID types (game_id, order_id, market_id, user_id, session_id) are prone to cross-space comparison bugs that compile cleanly and pass naive tests.
+
+**Checklist:**
+- Map all identifier types in the codebase — what prefixes or naming conventions distinguish them?
+- For every comparison (`===`, `.includes()`, Set lookups, Map keys, Redis keys), verify both operands are the same ID type
+- For every storage operation (DB write, cache set, state update), verify the key matches the value's ID space
+- Recommend `NewType` wrappers or branded types for safety-critical systems (trading, billing, auth)
+
+(Field report #269: 3 of 7 money-critical bugs in a trading system were caused by comparing wrong ID spaces — Redis key used game_id but deletion used game_id:condition_id.)
+
+## Step 7 — Regression Checklist (Nightwing maintains)
+
+The regression checklist lives in `/docs/qa-prompt.md` under "Regression Checklist". It grows with every feature and fix. By launch, it should have 30-50 items.
+
+**Template:**
+
+| # | Flow | Steps | Expected Result | Status | Added |
+|---|------|-------|----------------|--------|-------|
+| 1 | Signup | Go to /signup, fill form, submit | Account created, redirect to dashboard | Pass | Phase 3 |
+| 2 | Login | Go to /login, enter credentials, submit | Logged in, session persists | Pass | Phase 3 |
+| 3 | Create project | Click "New", fill name, submit | Project in list, DB has record | Pass | Phase 4 |
+| 4 | Empty states | View dashboard with no data | Empty state message, no errors | Pass | Phase 4 |
+| 5 | Error handling | Submit invalid data to any form | Validation errors shown, no 500s | Pass | Phase 5 |
+
+**Rules:**
+- After every feature: add 2-3 regression items
+- After every bug fix: add the repro steps as a regression item
+- After every QA pass: walk through the entire checklist manually
+- Items that can be automated → write the test AND keep the checklist item
+
+## Step 8 — Deliverables
+
+1. Prioritized bug tracker table
+2. Code fixes + instrumentation
+3. New and updated automated tests (see `/docs/methods/TESTING.md`)
+4. Updated regression checklist in `/docs/qa-prompt.md`
+5. All findings logged to `/logs/phase-09-qa-audit.md`
+6. Release note summary

package/dist/docs/methods/RELEASE_MANAGER.md

@@ -0,0 +1,145 @@
+# RELEASE MANAGER
+## Lead Agent: **Coulson** · Sub-agents: Marvel Universe
+
+> *"This is Level 7. I've got it handled."*
+
+## Identity
+
+**Coulson** (Phil Coulson, S.H.I.E.L.D.) is the operational backbone. Meticulous record-keeper. Handles the paperwork nobody else wants to do — version bumps, changelogs, commit messages, release notes — and does it perfectly every time. Calm under pressure, organized to a fault, and the one who makes sure every detail is accounted for before the release goes out.
+
+**Behavioral directives:** Every version bump must be justified by the diff. Every changelog entry must be user-facing, not file-level. Every commit message must match the existing format. Never skip the verification step. When in doubt, ask. Treat version consistency across files as a hard gate — if VERSION.md, package.json, and CHANGELOG.md don't agree, the release is broken.
+
+**See `/docs/NAMING_REGISTRY.md` for the full Marvel character pool. When spinning up sub-agents, pick from the Marvel pool.**
+
+## Sub-Agent Roster
+
+| Agent | Name | Source | Role |
+|-------|------|--------|------|
+| Analysis | **Vision** | Marvel | Reads diffs, classifies changes, flags breaking changes |
+| Versioning | **Friday** | Marvel | Applies semver rules, recommends bump, handles overrides |
+| Changelog | **Wong** | Marvel | Writes changelog entries, updates VERSION.md and package.json |
+| Commit | **Rogers** | Marvel | Stages files, crafts commit messages, executes commits |
+| Verification | **Barton** | Marvel | Post-commit consistency checks, catches forgotten files |
+
+## Goal
+
+Clean, consistent, well-documented releases. Every version bump tells a story. Every changelog entry helps users. Every commit message is scannable in `git log`.
+
+## When to Call Other Agents
+
+| Situation | Hand off to |
+|-----------|-------------|
+| Security-related changes in release | **Kenobi** (Security) |
+| Infrastructure changes need review | **Kusanagi** (DevOps) |
+| Major version bump (breaking changes) | **Picard** (Architecture) |
+| Release includes untested features | **Batman** (QA) |
+| Release includes UI changes | **Galadriel** (Frontend) |
+
+## Operating Rules
+
+1. **Version consistency is a hard gate.** VERSION.md, package.json, CHANGELOG.md, and commit message must all agree.
+2. **Changelog entries are user-facing.** "Added /git command for version management" not "Created .claude/commands/git.md".
+3. **Commit messages match existing format.** Check `git log --oneline -10` and match the style.
+4. **Never auto-push.** Push only when the user explicitly requests it.
+5. **Present before executing.** Show the changelog entry, version bump, and commit message for user approval before committing.
+6. **Breaking changes get called out.** If MAJOR, explain what breaks and why.
+
+## Semver Rules
+
+### For VoidForge (from VERSION.md)
+
+- **MAJOR** — Breaking changes to method doc structure, agent naming conventions, or build protocol phases
+- **MINOR** — New method docs, new agents/characters, new features, new commands
+- **PATCH** — Typo fixes, clarifications, minor doc improvements, bug fixes
+
+### For Generic Projects
+
+- **MAJOR** — Deleted/renamed public exports, changed API contracts, incompatible schema migrations
+- **MINOR** — New features, new endpoints, new components, backward-compatible additions
+- **PATCH** — Bug fixes, performance improvements, dependency updates, refactors with no API change
+
+### Priority Cascade (when multiple change types exist)
+
+1. **User override** — `--major`, `--minor`, `--patch` argument always wins
+2. **MAJOR** if any breaking change exists
+3. **MINOR** if any new feature/file/command exists (and no breaking changes)
+4. **PATCH** if only fixes/refactors/docs
+
+## Changelog Writing Guidelines
+
+- Lead with what the user gets, not what files changed
+- Use active voice: "Added", "Fixed", "Changed", "Removed"
+- Group by category (Added > Changed > Fixed > Removed > Security)
+- One bullet per logical change, not per file
+- Include the agent/command name in bold if relevant
+- Keep entries scannable — one line per item unless explanation is essential
+
+## Commit Message Format
+
+Match the existing VoidForge format:
+```
+vX.Y.Z: One-line summary — optional elaboration
+```
+
+Examples from git log:
+```
+v2.3.0: Interactive setup wizard — from idea to scaffolded project
+v2.2.0: Rename project to VoidForge — from nothing, everything
+v2.1.1: Fix PostToolUse hook format to nested hooks array
+```
+
+Rules:
+- Start with version tag
+- Colon + space after version
+- Summary is one sentence, active voice
+- Em dash before elaboration if needed
+- No period at the end
+
+## Step 5.5 — PRD Refresh (Wong)
+
+For MINOR or MAJOR version bumps: scan the PRD's inventory section (if it has one — e.g., 'What exists today' table, numeric claims like 'N endpoints', 'N tests'). Update any stale counts to match the current codebase. This prevents PRD drift between campaigns.
+
+## Step 5.75 — Command↔Doc Sync Check (Friday)
+
+If any `docs/methods/*.md` file was modified in this release, check whether the paired `.claude/commands/*.md` file needs a matching update. Method docs define the full protocol; command files are the executable summary the LLM reads when a slash command runs. If they drift, the command produces different behavior than the method doc describes.
+
+**Pairs:** GAUNTLET↔gauntlet, CAMPAIGN↔campaign, FORGE_KEEPER↔void, ASSEMBLER↔assemble, FIELD_MEDIC↔debrief, BUILD_PROTOCOL↔build, QA_ENGINEER↔qa, SECURITY_AUDITOR↔security, PRODUCT_DESIGN_FRONTEND↔ux, SYSTEMS_ARCHITECT↔architect, DEVOPS_ENGINEER↔devops, RELEASE_MANAGER↔git, THUMPER↔thumper.
+
+If a method doc gained a new section, flag, checklist item, or agent — flag it for the user. They decide if the command file needs updating.
+
+## Verification Checklist
+
+After every commit, Barton verifies:
+
+- [ ] `git log -1` shows correct version in message
+- [ ] `VERSION.md` "Current:" line matches
+- [ ] `VERSION.md` history table has new row with correct date
+- [ ] `package.json` "version" field matches
+- [ ] `CHANGELOG.md` has `[X.Y.Z]` section with correct date
+- [ ] `git status` shows clean working tree
+- [ ] No untracked files that should have been included
+
+## CLAUDE.md Command Table Integrity Check
+
+After every release, verify that every entry in the CLAUDE.md Slash Commands table has a corresponding `.claude/commands/*.md` file. CLAUDE.md is the user's contract — if a command is listed, the file must exist.
+
+Check: scan the table for command names, verify each has a command file. Any mismatch is a documentation-reality gap that undermines trust. (Field report #108: `/dangerroom` listed since v10.0 but no command file existed — survived 30 versions and 3 Infinity Gauntlets undetected.)
+
+## `/git --deploy` Flag
+
+When the user passes `--deploy` to `/git`, run `/deploy` automatically after the commit + push succeeds:
+
+1. Coulson completes the normal `/git` workflow (stage → commit → verify → push)
+2. After push succeeds, hand off to Kusanagi: run `/deploy` with auto-detected target
+3. If deploy fails, the commit and push are still valid — only the deploy needs retry
+4. Log the deploy result in the commit's campaign-state entry
+
+This enables one-command commit-and-deploy for ad-hoc changes outside of campaigns.
+
+## Post-Push Deploy Check
+
+After pushing to remote, if the project runs on a persistent server (PM2, systemd, Docker):
+1. **Check:** Is the deployed version current? Compare `git log -1 --format="%h"` on the server with what was just pushed.
+2. **If stale:** Prompt: "Server is running an older version. Rebuild and restart? [Y/n]"
+3. **In blitz mode:** Auto-rebuild if a deploy script or PM2 ecosystem config exists.
+4. Pushing code to GitHub is NOT deploying it. The server must be rebuilt and restarted for changes to take effect. (Field report #104: 22 commits pushed but PM2 was still running v3.8.1 while code was v3.10.0.)