thevoidforge 21.0.10 → 21.0.12

package/dist/docs/methods/TESTING.md

@@ -0,0 +1,359 @@
+# TESTING PROTOCOL
+## Lead Agent: **Batman** · Sub-agent: **Nightwing** (Regression Guardian)
+
+> *"The test suite is your silent guardian."*
+
+## Purpose
+
+Automated tests catch regressions that manual checklists miss. Manual verification catches UX and integration issues that automated tests miss. Use both. Neither replaces the other.
+
+## Testing Pyramid
+
+```
+         /  E2E  \          ← Few: critical user journeys only
+        / Integration \      ← Some: API routes, service interactions
+       /    Unit Tests   \   ← Many: business logic, utils, transforms
+```
+
+## Framework-to-Test-Runner Mapping
+
+| Framework | Unit Tests | Integration Tests | E2E | Assertion |
+|-----------|-----------|------------------|-----|-----------|
+| Next.js / Node | vitest or jest | vitest + supertest | Playwright | expect (vitest/jest) |
+| Express | vitest or jest | vitest + supertest | Playwright | expect (vitest/jest) |
+| Django | pytest | pytest + Django test client | Playwright | assert (pytest) |
+| Rails | RSpec or Minitest | RSpec + request specs | Playwright | expect (RSpec) |
+| Go | testing (stdlib) | testing + httptest | Playwright | testify |
+| Spring Boot | JUnit 5 | JUnit 5 + MockMvc | Playwright | AssertJ |
+
+Adapt the patterns below to your stack's test runner. The principles (test behavior not implementation, deterministic, co-located) are universal.
+
+## When to Write Which
+
+| Code Type | Test Type | Tool | Coverage Target |
+|-----------|-----------|------|----------------|
+| Pure functions, utils, transforms | Unit | vitest / jest | High — these are cheap to test |
+| Service layer (business logic) | Unit | vitest / jest | High — core value lives here |
+| API routes | Integration | vitest / supertest | All routes — validate input/output contracts |
+| Database queries | Integration | vitest + test DB | Complex queries, edge cases |
+| Auth flows | Integration | vitest / supertest | All auth paths including failures |
+| Full user journeys | E2E / Manual | Playwright or manual | Top 3-5 critical paths only |
+| UI components | Manual | Browser | Visual, interaction, responsive, a11y |
+| Edge cases, broken states | Manual | Browser | Red Hood's domain — break it on purpose |
+
+## Unit Test Rules
+
+1. Test behavior, not implementation. Assert outcomes, not internals.
+2. One assertion concept per test. Name describes what's being verified.
+3. No mocking unless the dependency is external (API, DB, filesystem).
+4. Use factories for test data, not raw objects scattered across files.
+5. Tests must be deterministic — no time-dependent, order-dependent, or network-dependent tests.
+
+### Pattern
+
+```typescript
+// services/__tests__/billing.test.ts
+import { describe, it, expect } from 'vitest'
+import { calculateProration } from '../billing'
+
+describe('calculateProration', () => {
+  it('returns zero when upgrade happens on billing date', () => {
+    const result = calculateProration({
+      currentPlan: 'basic',
+      newPlan: 'pro',
+      billingDate: new Date('2026-03-01'),
+      upgradeDate: new Date('2026-03-01'),
+    })
+    expect(result.amount).toBe(0)
+  })
+
+  it('prorates proportionally for mid-cycle upgrade', () => {
+    const result = calculateProration({
+      currentPlan: 'basic',
+      newPlan: 'pro',
+      billingDate: new Date('2026-03-01'),
+      upgradeDate: new Date('2026-03-15'),
+    })
+    expect(result.amount).toBeGreaterThan(0)
+    expect(result.daysRemaining).toBe(16)
+  })
+})
+```
+
+## Integration Test Rules
+
+1. Use a real test database (SQLite in-memory or Docker Postgres).
+2. Reset state between tests (transactions or truncation).
+3. Test the full request/response cycle for API routes.
+4. Validate response shape, status codes, and error formats.
+5. Test auth: authenticated, unauthenticated, wrong role, wrong owner.
+6. **Validation constraint smoke test:** For each model with validation constraints (Pydantic `Field`, Zod schema, Joi, class-validator decorators), write at least one test that sends invalid input and verifies rejection. Frameworks may silently ignore constraints on incompatible types (e.g., Pydantic v2 ignores `max_length` on dict). The test catches this. (Field report #99: `max_length=50` on a dict field was silently ignored — no size validation occurred.)
+7. **Route integration test mandate:** For each API route, at least one test must exercise the full HTTP → handler → service → response path. Unit tests on service functions are not sufficient — they miss middleware, auth guards, request parsing, and response formatting. A route with no integration test is an untested route. (Field report #119: zero integration tests across 278 unit tests — route-level regressions were invisible.)
+
+### Pattern
+
+```typescript
+// api/__tests__/projects.test.ts
+import { describe, it, expect, beforeEach } from 'vitest'
+import { createTestApp, createTestUser } from '../test-utils'
+
+describe('POST /api/projects', () => {
+  let app: TestApp
+  let user: TestUser
+
+  beforeEach(async () => {
+    app = await createTestApp()
+    user = await createTestUser(app)
+  })
+
+  it('creates project for authenticated user', async () => {
+    const res = await app.post('/api/projects')
+      .auth(user.token)
+      .send({ name: 'Test Project' })
+
+    expect(res.status).toBe(201)
+    expect(res.body.project.name).toBe('Test Project')
+    expect(res.body.project.ownerId).toBe(user.id)
+  })
+
+  it('rejects unauthenticated request', async () => {
+    const res = await app.post('/api/projects')
+      .send({ name: 'Test Project' })
+
+    expect(res.status).toBe(401)
+  })
+
+  it('validates input', async () => {
+    const res = await app.post('/api/projects')
+      .auth(user.token)
+      .send({ name: '' })
+
+    expect(res.status).toBe(400)
+    expect(res.body.error.code).toBe('VALIDATION_ERROR')
+  })
+})
+```
+
+## E2E Testing
+
+E2E tests sit at the top of the testing pyramid. They're slow, expensive, and brittle compared to unit tests — but they catch integration failures that nothing else can. A unit test verifies that `calculateTotal()` returns the right number; an E2E test verifies that the user can actually complete a purchase.
+
+### Where E2E Fits
+
+```
+         /  E2E  \          ← 10-15 tests. Critical user journeys ONLY.
+        / Integration \      ← API routes, service interactions, auth flows
+       /    Unit Tests   \   ← Business logic, utils, transforms, edge cases
+```
+
+**Write E2E when:**
+- Testing critical user journeys (signup, purchase, core workflow)
+- Verifying a11y across real page compositions (axe-core in browser)
+- Testing cross-component flows where integration tests can't reach (navigation, redirects, auth state persistence)
+- Validating real browser behavior (CSP headers, cookie handling, responsive layout)
+
+**Write unit/integration instead when:**
+- Testing business logic, calculations, or data transforms
+- Testing API input validation and error handling
+- Testing edge cases and boundary conditions
+- Testing isolated component behavior
+
+### Performance Budget
+
+| Metric | Limit | Action if Exceeded |
+|--------|-------|--------------------|
+| Total CI time | 2 minutes | Shard tests across workers |
+| Test count | 50 | Shard or prune — you're testing too many paths |
+| Single test duration | 30 seconds | Split into smaller focused tests |
+| Retry rate | < 5% per week | Fix or quarantine flaky tests |
+
+Sharding in CI (when you hit 50+ tests):
+```yaml
+# GitHub Actions example
+strategy:
+  matrix:
+    shard: [1/3, 2/3, 3/3]
+steps:
+  - run: npx playwright test --shard=${{ matrix.shard }}
+```
+
+### Flaky Test Protocol
+
+Flaky tests erode trust in the test suite. Huntress (stability monitor) tracks flake rates.
+
+1. **Detection:** Test fails intermittently — passes on retry but fails on fresh runs
+2. **Annotation:** After 3 flakes in a week, add `@flaky` tag with a tracking issue
+3. **Quarantine:** Flaky tests run in a separate CI job (`grep: /@flaky/`) with 3 retries
+4. **Investigation:** Root-cause the flakiness — usually timing, external state, or test ordering
+5. **Resolution:** Fix within 2 weeks or rewrite. If unfixable, demote to manual verification
+6. **Return:** Remove `@flaky` tag — test returns to the stable suite
+
+```typescript
+// Annotating a flaky test
+test('payment webhook processes correctly', {
+  tag: ['@flaky'],
+  annotation: { type: 'flaky', description: 'Webhook timing race — tracking in #234' },
+}, async ({ page }) => {
+  // test body
+});
+```
+
+**Rules:**
+- NEVER use `@flaky` to suppress real bugs
+- NEVER use `page.waitForTimeout()` — it's the #1 cause of flakiness
+- NEVER use `waitForLoadState('networkidle')` — it's non-deterministic
+- ALWAYS use explicit waits: `await expect(locator).toBeVisible()`
+
+### Framework-to-Test-Runner Mapping (E2E Column)
+
+| Framework | Unit | Integration | E2E Runner | E2E Start Command |
+|-----------|------|-------------|------------|-------------------|
+| Next.js / Node | vitest or jest | vitest + supertest | Playwright | `next dev -p 3199` |
+| Express | vitest or jest | vitest + supertest | Playwright | `PORT=3199 npx tsx src/server.ts` |
+| Django | pytest | pytest + Django client | Playwright | `python manage.py runserver 3199` |
+| Rails | RSpec / Minitest | RSpec + request specs | Playwright | `RAILS_ENV=test bin/rails server -p 3199` |
+| Go | testing (stdlib) | testing + httptest | Playwright | `PORT=3199 go run ./cmd/server` |
+| Spring Boot | JUnit 5 | JUnit 5 + MockMvc | Playwright | `./gradlew bootRun --args='--server.port=3199'` |
+
+### PRD Frontmatter
+
+Add `e2e: yes | no` to PRD frontmatter. Defaults:
+- `yes` — full-stack, static-site (has pages to test)
+- `no` — api-only, prototype (no browser UI, or too early)
+
+The Build Protocol reads this flag to decide whether Phase 10 (E2E tests) runs.
+
+### E2E Test File Conventions
+
+```
+e2e/
+  fixtures.ts             ← axe-core fixture, auth helper, network mocks
+  auth.setup.ts           ← Login via API, save session state
+  smoke.test.ts           ← Page loads, no crashes, a11y clean
+  auth.test.ts            ← Login/logout/session persistence
+  [feature].test.ts       ← One file per critical journey
+  page-objects/
+    login.page.ts         ← Page Object Model classes
+    dashboard.page.ts
+  .auth/
+    session.json          ← Saved auth state (gitignored)
+```
+
+### Reference Pattern
+
+See `/docs/patterns/e2e-test.ts` for the complete reference implementation:
+- Page Object Model example
+- axe-core a11y fixture
+- Auth helper (login via API, reuse session)
+- Network mock (intercept external API calls)
+- WebSocket mock
+- CWV measurement helper
+- Flaky test annotation pattern
+- Framework-specific Playwright config
+
+## Testing Anti-Patterns
+
+**No hardcoded dates:** Never use hardcoded dates in tests. Use relative datetime (e.g., `new Date(Date.now() - 86400000)` for 'yesterday'). A test with `expect(date).toBe('2026-03-15')` becomes a time bomb that fails when the date passes.
+
+**Mock signature verification:** When mocking external dependencies, verify the mocked methods exist on the real class. A mock that defines `sendMessage()` when the real SDK uses `send_message()` creates false confidence — tests pass but the integration fails. Pattern: `expect(Object.keys(mock)).toEqual(expect.arrayContaining(Object.keys(realInstance)))`.
+
+**No source-code string assertions:** Never assert on status code strings or error class names found in source code (`'403' in source`, `'HTTPException' in source`). These break on any refactor that changes error handling mechanics (e.g., `HTTPException(403)` → `Errors.forbidden()`). Test the actual HTTP response status and body instead. (Field report #227)
+
+**Error format migration checklist:** Before committing any change to error response shape (e.g., `{"detail": ...}` → `{"error": {"code", "message"}}`), grep test files for the old shape. Tests asserting `response["detail"]` will silently pass if the test never reaches the assertion (wrong status code) or will fail confusingly. Fix all test assertions to match the new shape in the same commit. (Field report #227)
+
+**Standalone test app handler registration (FastAPI/Express):** When tests create their own application instance (`FastAPI()`, `express()`) for isolated testing, register all custom error handlers from the main app (`app.add_exception_handler(ApiError, api_error_handler)` or equivalent). Without this, custom error classes propagate as unhandled exceptions instead of structured JSON — tests pass for the wrong reason. (Field report #227)
+
+**Version-agnostic assertions:** When asserting on prefixed or versioned values (encryption prefixes, API version headers, token formats), use the stable prefix, not the exact version. `startswith("enc:")` survives key rotation; `startswith("enc::")` breaks when the format becomes `enc:v1::`. Assert on the behavior ("value is encrypted") not the version ("value uses encryption v1"). (Field report #227)
+
+## What NOT to Test Automatically
+
+- Visual appearance (manual — Arwen's domain)
+- "Does this feel right?" UX flows (manual — Elrond's domain)
+- Performance under real conditions (manual — Fury/Gimli's domain)
+- Third-party service behavior (mock it, don't call it)
+- Implementation details that could change without affecting behavior
+
+## Test File Conventions
+
+```
+src/
+  services/
+    billing.ts
+    __tests__/
+      billing.test.ts         ← Unit tests co-located
+  api/
+    projects/
+      route.ts
+    __tests__/
+      projects.test.ts        ← Integration tests co-located
+  test-utils/
+    index.ts                  ← Shared factories, helpers, test app setup
+```
+
+## Running Tests
+
+```bash
+# All tests
+npm test
+
+# Unit tests only
+npm run test:unit
+
+# Integration tests only
+npm run test:integration
+
+# Watch mode during development
+npm run test:watch
+
+# Coverage report
+npm run test:coverage
+```
+
+## Regression Strategy
+
+Automated tests are the **first line** of regression defense. The manual regression checklist in `/docs/qa-prompt.md` is the **second line** — it catches integration and UX regressions that tests can't.
+
+When Nightwing adds a regression checklist item, also ask: "Can this be an automated test?" If yes, write the test AND add the checklist item. The test runs on every change; the checklist runs on QA passes.
+
+## Relationship to QA_ENGINEER.md
+
+Batman's QA protocol now includes automated testing as Step 3.5 (between "Find Bugs" and "Bug Tracker"). The sequence:
+
+1. Oracle scans statically
+2. Red Hood breaks dynamically
+3. Alfred reviews dependencies
+4. Lucius reviews config
+5. **Nightwing runs the test suite and reports failures**
+6. All findings go into the bug tracker
+7. Fixes include new tests to prevent regression
+
+### Test Schema vs. Production Schema
+Verify test fixtures (conftest, factories, seed files) create ALL tables from the migration runner. Compare table lists between the test DB setup and the production schema — any table present in migrations but missing from test fixtures is a gap that causes silent test failures. This is especially critical when using a hardcoded migration list instead of the actual migration runner.
+(Field report #21: conftest missed tables from later migrations — ALTER TABLE on non-existent table was silently caught.)
+
+### Database Fixtures — Use the Production Schema
+
+Always use the test framework's shared database fixture (e.g., conftest `db` fixture) for store and service tests. It applies the full production schema + all migrations.
+
+Do NOT create custom DDL in test files — it drifts from the real schema (missing NOT NULL constraints, columns added by later migrations, different defaults). If you need tables the shared fixture doesn't have, add them AFTER the fixture yields — don't replace it.
+
+Custom DDL causes test DB schema mismatches that require 2-3 fix-and-retry cycles per occurrence. (Field report #31)
+
+## Setup Checklist
+
+When setting up testing for a new project:
+
+- [ ] Install test runner (`npm i -D vitest` or `jest`)
+- [ ] Add test scripts to `package.json`
+- [ ] Create `test-utils/` with app setup and factories
+- [ ] Configure test database (if applicable)
+- [ ] Write first test for the most critical service function
+- [ ] Write first integration test for the most important API route
+- [ ] Verify `npm test` passes in CI-equivalent conditions
+- [ ] **E2E (if PRD `e2e: yes`):** Install Playwright (`npm i -D @playwright/test @axe-core/playwright`)
+- [ ] **E2E:** Install browser (`npx playwright install chromium`)
+- [ ] **E2E:** Create `playwright.config.ts` with framework-appropriate `webServer.command`
+- [ ] **E2E:** Create `e2e/fixtures.ts` with axe-core fixture and auth helper
+- [ ] **E2E:** Write first smoke test — page loads, no a11y violations
+- [ ] **E2E:** Add `e2e/.auth/`, `test-results/`, `playwright-report/` to `.gitignore`
+- [ ] **E2E:** Verify `npx playwright test` passes in CI-equivalent conditions (< 2 min)

package/dist/docs/methods/THUMPER.md

@@ -0,0 +1,175 @@
+# THE THUMPER — Chani's Worm Rider
+## Lead Agent: **Chani** (Chani Kynes) · Sub-agents: Dune Universe
+
+> *"Tell me of your homeworld, Usul."*
+
+## What Is This
+
+Send prompts to Claude Code from Telegram and get responses back. Plant a thumper, ride the sandworm, command from anywhere.
+
+## Identity
+
+**Chani** is a Worm Rider. She doesn't write code — she ensures The Voice reaches its destination across any environment. Her domain is cross-environment session bridging: connecting your Telegram to a live Claude Code session.
+
+**Behavioral directives:** Every channel must pass the Gom Jabbar. Default to the most reliable worm path. Never store credentials outside the sietch vault. When a signal fails, notify the sender — silence is betrayal in the desert.
+
+**See `/docs/NAMING_REGISTRY.md` for the full Dune character pool.**
+
+## Sub-Agent Roster
+
+| Agent | Name | Role | Lens |
+|-------|------|------|------|
+| Channel Security | **Stilgar** | Naib — protects the tribe's secrets | No outsider enters the sietch. |
+| Protocol Parsing | **Thufir** | Mentat — message processing | A million computations per second. |
+| Relay Operations | **Idaho** | Swordmaster — the eternal connection | Dies a thousand times, always returns. |
+| Authentication | **Mohiam** | Reverend Mother — the Gom Jabbar | "Put your hand in the box." |
+
+## Goal
+
+Authenticated, bidirectional Telegram bridge to Claude Code. One command to start, passphrase-gated, works across macOS local, macOS+tmux, headless Linux SSH, and Linux+tmux.
+
+## When to Call Other Agents
+
+| Situation | Hand off to |
+|-----------|-------------|
+| Security review of credential handling | **Kenobi** (Security) |
+| Infrastructure for daemon supervision | **Kusanagi** (DevOps) |
+| Architecture of transport layer | **Picard** (Architecture) |
+| Bug in injection mechanics | **Batman** (QA) |
+
+## Operating Rules
+
+1. Every session must pass the Gom Jabbar — no exceptions.
+2. Credentials live in `sietch.env` (chmod 600, umask 077). Never committed.
+3. The Gom Jabbar hash is session-scoped — destroyed on `/thumper off`.
+4. Passphrase messages are deleted from Telegram. If deletion fails, the session is invalidated.
+5. After 60 minutes idle, re-authentication is required.
+6. 3 failed auth attempts trigger a 5-minute lockout.
+7. Messages during auth challenge are discarded, not queued.
+8. The water rings hook always exits 0 — never blocks Claude Code.
+9. Log operations, not message content.
+10. Control characters (0x00-0x1F, 0x7F) are stripped before injection. Newlines collapsed to spaces.
+11. The thumper must never run as root.
+
+## Worm Paths (Transport Vectors)
+
+| Worm Path | Environment | Mechanism | Platform |
+|-----------|-------------|-----------|----------|
+| **TMUX_SENDKEYS** | Any with tmux | `tmux send-keys -l -t [session]` | Cross-platform |
+| **PTY_INJECT** | Headless Linux SSH | Write to `/proc/[pid]/fd/0` | Linux only |
+| **OSASCRIPT** | macOS Terminal.app / iTerm2 | File-based AppleScript injection | macOS only |
+
+**Detection priority:** TMUX (most reliable) > Headless SSH > macOS local > Linux PTY > manual override. OSASCRIPT is only auto-selected for Terminal.app and iTerm2 — VS Code, Warp, Alacritty, and Kitty users get explicit guidance to use tmux. Windows Git Bash/MSYS2 gets a "use WSL" message.
+
+## The Gom Jabbar Protocol
+
+**How it works:**
+1. On `/thumper on`, the relay sends a challenge to Telegram: "Choose your word of passage."
+2. You type a passphrase (any word or phrase) in the Telegram chat.
+3. The passphrase is hashed with PBKDF2 (100k iterations via python3, HMAC-SHA256 fallback) and stored in `.gom-jabbar`.
+4. The passphrase message is deleted from Telegram via the `deleteMessage` API (3 retries).
+5. If deletion fails, the session is invalidated and you must choose a new passphrase.
+6. Messages flow normally while authenticated.
+7. After 60 minutes idle: "The sands have shifted. Speak your word of passage."
+8. 3 wrong attempts: locked for 5 minutes.
+
+**Security properties:**
+- PBKDF2 with 100k iterations prevents brute force
+- Message deletion removes passphrase from chat history
+- Session-scoped hash — destroyed on `/thumper off`
+- No message queuing during auth — prevents unauthenticated payload laundering
+- Empty hash bypass prevention — refuses auth when hashing tools are unavailable
+
+## Setup Flow
+
+`/thumper setup` walks through everything interactively:
+1. **Bot creation:** Guides you through BotFather or accepts an existing token. Auto-detects your chat ID.
+2. **Environment scan:** Auto-detects your terminal and selects the best worm path.
+3. **Config write:** Creates `.voidforge/thumper/sietch.env` (chmod 600, umask 077).
+4. **Activate:** Offers to start the channel immediately.
+
+No manual config editing required — `scan.sh` handles everything.
+
+**Non-interactive mode:** Claude Code's Bash tool doesn't support interactive stdin (`read -r -p`). For setup from within Claude Code, use: `bash scripts/thumper/scan.sh --token YOUR_BOT_TOKEN --chat-id YOUR_CHAT_ID`. This skips all prompts and writes the sietch vault directly. (Field report #35)
+
+## Usage
+
+```
+/thumper setup    — First-time scan or re-configure
+/thumper on       — Start sandworm daemon + Gom Jabbar challenge
+/thumper off      — Stop daemon, destroy auth state
+/thumper status   — Channel state, worm path, auth state, log size
+```
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `thumper.sh` | Router — dispatches on/off/setup/status |
+| `scan.sh` | Setup wizard — bot creation, env detection, config write |
+| `relay.sh` | Sandworm daemon — polls Telegram, injects into Claude Code |
+| `gom-jabbar.sh` | Auth protocol — sourced by relay.sh, not standalone |
+| `water-rings.sh` | Stop hook — sends task completion notification to Telegram |
+
+## Water Rings (Stop Hook)
+
+`water-rings.sh` is a Claude Code Stop hook registered in `.claude/settings.json`. It fires every time Claude Code finishes responding.
+
+1. Checks if config exists and channel is active — exits silently if not.
+2. Reads session JSON from stdin, extracts last assistant message.
+3. Truncates to 3600 chars, sends to Telegram in a background process.
+4. Always exits 0 — never blocks Claude Code.
+
+The shutdown logic (killing daemon, removing channel flag, destroying auth) lives in `thumper.sh cmd_off`, not in the stop hook.
+
+## Security Considerations
+
+### Mitigations (implemented)
+
+- Gom Jabbar with PBKDF2 hashing and message deletion
+- Root guard (`id -u` check, unspoofable on macOS bash 3.2)
+- Control character sanitization (Ctrl+C, ESC, ANSI injection prevented)
+- Message length cap (8192 chars)
+- Config injection prevention (`printf '%q'`, umask 077)
+- AppleScript injection prevention (file-based, user text never in source)
+- Atomic state files (write-to-tmp-then-rename)
+- Empty hash bypass prevention
+
+### Known risks (inherent)
+
+- **Prompt injection:** Telegram messages are Claude Code prompts. Mitigated by settings.json deny list + Gom Jabbar.
+- **Data exfiltration via water rings:** Up to 3600 chars of output sent to Telegram.
+- **Bot token in process listing:** Telegram API constraint. Low risk on single-user machines.
+- **CHAT_ID is not a secret:** Bot token is the primary credential.
+- **PTY race condition:** Mitigated by control character sanitization.
+
+## Troubleshooting
+
+**Problem: "The sands have shifted" keeps appearing**
+Your 60-minute idle timeout expired. Re-enter your passphrase. To change the timeout, edit `GOM_JABBAR_IDLE_TIMEOUT` in `gom-jabbar.sh`.
+
+**Problem: "Could not erase your word from the sands"**
+Telegram failed to delete the passphrase. Session invalidated for safety. Manually delete the message from chat. Run `/thumper off` then `/thumper on`.
+
+**Problem: Sandworm starts but messages don't inject**
+Check `/thumper status` for worm path and auth state. For PTY_INJECT: is Claude running? For TMUX: does session name match? For OSASCRIPT: is Terminal/iTerm2 focused with Accessibility permissions?
+
+**Problem: Bot doesn't respond at all**
+Check worm log: `tail -f .voidforge/thumper/worm.log`. Verify token: `curl https://api.telegram.org/bot[TOKEN]/getMe`.
+
+**Problem: Locked out (3 failed attempts)**
+Wait 5 minutes. If you forgot your passphrase: `/thumper off` then `/thumper on` to choose a new one.
+
+## Deliverables
+
+1. `scripts/thumper/` — thumper.sh, scan.sh, relay.sh, gom-jabbar.sh, water-rings.sh
+2. `.claude/commands/thumper.md` — Slash command
+3. `.claude/settings.json` — Stop hook registration
+4. This document
+
+## Handoffs
+
+- Security review → **Kenobi**, log to `/logs/handoffs.md`
+- Infrastructure → **Kusanagi**, log to `/logs/handoffs.md`
+- Architecture → **Picard**, log to `/logs/handoffs.md`
+- Testing → **Batman**, log to `/logs/handoffs.md`

package/dist/docs/methods/TIME_VAULT.md

@@ -0,0 +1,120 @@
+# TIME VAULT — Seldon's Session Intelligence Preservation
+## Lead Agent: **Hari Seldon** (Foundation) · Sub-agent: **Gaal Dornick** (Foundation)
+
+> *"The future is already written. I merely ensure the right people can read it."*
+
+## Identity
+
+**Hari Seldon** invented psychohistory — the science of predicting the behavior of large populations. In VoidForge, his Time Vault distills the expensive analysis from one session into a portable briefing that lets the next session skip the re-derivation. Seldon compresses, Jake Sisko writes, Gaal Dornick gathers the raw materials.
+
+## Goal
+
+Preserve expensive analysis across session boundaries. A new session with a vault briefing should reach productive work in under 60 seconds. Without one, recovering context costs 5-15 minutes of re-reading and re-tracing.
+
+## Operating Rules
+
+### 1. Include What's Expensive to Re-Derive
+
+These items require synthesis, tracing, or multi-file analysis to produce. They cannot be recovered by reading a single file:
+
+- **Decisions and rationale** — "We chose X over Y because Z" requires the full context that led to the decision
+- **Failed approaches** — Knowing what didn't work (and why) prevents repeated dead ends
+- **Cross-module relationships** — Which files connect to which, non-obvious wiring, integration points
+- **Agent findings** — Consolidated results from review passes (not the full tables — the actionable summary)
+- **Execution plan** — Ordered next steps with dependencies, derived from current state analysis
+- **Test state** — What passes, what fails, what's missing, what was skipped
+
+### 2. Exclude What's Cheap to Re-Read
+
+These items are stored in well-known locations and can be loaded on demand:
+
+- Full file contents (git)
+- PRD text (`/docs/PRD.md`)
+- Method doc contents (`/docs/methods/`)
+- Pattern references (`/docs/patterns/`)
+- Agent naming registry (`/docs/NAMING_REGISTRY.md`)
+- Build journal entries (`/logs/` — read directly when needed)
+
+### 3. Psychohistorical Compression
+
+Seldon doesn't transcribe — he compresses. A 3-hour session that produced 47 findings across 6 agents becomes:
+
+> "Security pass found 3 Critical (all fixed): CSRF on /api/settings, missing rate limit on /auth/login, leaked stack trace in error handler. UX pass found 12 issues (10 fixed, 2 deferred): focus management in modal, contrast on muted text. QA found the modal fix broke keyboard nav — re-fixed in Pass 2. Next: deploy checklist, then Phase 13 launch verification."
+
+Not 47 rows. The signal, compressed.
+
+### 4. Per-Task File Lists
+
+For each unit of work completed in the session, list the files created or modified. This lets the next session quickly scope what changed without running `git log --stat` across dozens of commits:
+
+```
+### Auth middleware refactor
+- src/middleware/auth.ts (modified — added rate limiting)
+- src/middleware/rate-limit.ts (created)
+- tests/middleware/auth.test.ts (modified — 4 new tests)
+```
+
+### 5. Vault File Format
+
+Files live at `/logs/vault-YYYY-MM-DD.md` with YAML frontmatter:
+
+```yaml
+---
+sealed: 2026-03-26T14:30:00Z
+project: my-app
+branch: main
+commit: abc1234
+session_focus: Security pass + UX fixes for Phase 10-11
+---
+```
+
+The frontmatter enables programmatic reading by other commands (`/campaign`, `/current`, `/thumper`).
+
+### 6. Pickup Prompt
+
+Every vault produces a pickup prompt — a copyable block that the next session pastes to recover context immediately:
+
+```
+Read /logs/vault-2026-03-26.md for session context.
+Then read /logs/build-state.md and /logs/campaign-state.md for operational state.
+Resume from: Phase 12 deploy checklist — all review passes complete.
+```
+
+The pickup prompt is the vault's delivery mechanism. It's printed to console, not buried in a file.
+
+## Integration Points
+
+| Command | How It Uses the Vault |
+|---------|----------------------|
+| `/campaign` | Reads most recent vault at Step 0 (state recovery). Seals a vault at campaign pause/end. |
+| `/debrief` | Vault provides session context for Bashir's post-mortem analysis. |
+| `/thumper` | `--for trigger` format enables automated session pickup via Telegram bridge. |
+| `/current` | Deep Current reads vault history to track session-over-session progress. |
+| Session start | User pastes pickup prompt. Agent reads vault. Context recovered. |
+
+## When to Seal a Vault
+
+- **End of session** — Always. Even short sessions produce decisions worth preserving.
+- **Before context checkpoint** — If approaching 70%+ context usage, seal first.
+- **Campaign pause** — When `/campaign` pauses between missions across sessions.
+- **Before destructive operations** — Before `git reset`, branch switches, or major refactors.
+
+### 7. Operational Learnings Sync
+
+At session end, before sealing the vault, check for approved operational learnings from this session:
+
+1. If `/debrief` ran and produced approved learnings → they're already in `docs/LEARNINGS.md`
+2. If no debrief ran but the session discovered operational facts (API quirks, decision rationale, root causes that took multiple attempts) → Seldon flags candidates using the same criteria as FIELD_MEDIC.md Step 2.5
+3. Present candidates to user for approval. Append approved entries to `docs/LEARNINGS.md`
+4. Include in the vault's "Open Items" section: *"[N] operational learnings added to LEARNINGS.md this session"*
+
+This ensures learnings are captured even in sessions that don't run a formal debrief. The vault is the last checkpoint — if a learning was discovered but not captured by debrief, the vault catches it.
+
+**Do NOT duplicate LEARNINGS.md content in the vault narrative.** The vault references the file; the file holds the structured entries. The vault says "3 learnings captured" — it doesn't repeat them. See ADR-035 for the full design rationale.
+
+## Anti-Patterns
+
+- **Vault as transcript** — Don't dump the session log. Compress to signal.
+- **Vault as documentation** — Don't write docs in the vault. Write docs in `/docs/`, reference them from the vault.
+- **Vault without pickup prompt** — A vault file nobody reads is wasted. The pickup prompt is mandatory.
+- **Stale vaults** — Vaults older than 7 days are historical, not operational. The next session should read the most recent vault, not the oldest.