thevoidforge 21.0.11 → 21.0.13

package/dist/docs/methods/CONTEXT_MANAGEMENT.md

@@ -0,0 +1,189 @@
+# CONTEXT WINDOW MANAGEMENT
+## System Protocol · Used by: All Agents
+
+> *Move fast without hitting the wall. Scope sessions, load on demand, checkpoint to disk.*
+
+## The Problem
+
+Claude Code has a finite context window. Long sessions accumulate tool results, file reads, and conversation history. When context fills, earlier information compresses or drops. This causes: lost decisions, repeated work, forgotten state, and slower responses.
+
+## Core Strategy
+
+1. **Dispatch heavy work to sub-agents** — the primary context management technique. Sub-agents read source files and return synthesized findings; the main thread never fills with raw code. A full `/assemble --muster` stays at 15-25% context when dispatched vs 80%+ inline. See `SUB_AGENTS.md` "Parallel Agent Standard." (Field report #270)
+2. **Pre-load active domain** — load the active agent's method docs at session start (~4% of 1M context)
+3. **Application code on demand** — read source files when you need them, not all upfront
+4. **Write to disk, not memory** — decisions, state, and findings go in `/logs/` immediately
+5. **Checkpoint only above 85%** — the 1M window supports full campaigns. Write build-state.md only when `/context` shows >85%.
+5. **New sessions read from disk** — build journal is the bridge between sessions
+
+## Pre-Loading Budget (1M Context)
+
+At 1M tokens, methodology docs consume ~4% of context. Pre-load strategically:
+
+| Pre-load at session start | Approximate tokens |
+|--------------------------|-------------------|
+| CLAUDE.md | ~2K |
+| Active agent's method doc | ~2-4K |
+| Related agent method docs (if cross-cutting) | ~4-8K |
+| PRD.md | ~5-10K |
+| build-state.md | ~1K |
+| **Total pre-load** | **~15-25K (1.5-2.5% of 1M)** |
+
+**Load on demand:** Application source code, pattern files, other agents' method docs, naming registry, log files, test output.
+
+## File Size Discipline
+
+| File Type | Max Lines | Action When Exceeded |
+|-----------|-----------|---------------------|
+| CLAUDE.md (root) | 130 | Move content to README or method docs |
+| Per-directory CLAUDE.md | 50 | Split into multiple directories |
+| Method docs | 200 | Extract sub-sections to separate files |
+| Source files | 300 | Split into modules (services, utils, components) |
+| Log files | 200 per phase | Archive completed sections, keep summary |
+| build-state.md | 50 | Only current state — archive completed phases to phase logs |
+
+## Session Scoping Guide
+
+### What fits in one session
+
+| Session Type | Scope | Typical Context Usage |
+|-------------|-------|----------------------|
+| Phase 0 (Orient) | Read PRD, extract architecture, write ADRs | Medium — PRD can be large |
+| Single feature build | Schema + API + UI + tests for one feature | Medium-high |
+| QA audit | Batman's full pass on existing codebase | High — reads many files |
+| Security audit | Kenobi's full pass | Medium — focused reads |
+| UX review | Galadriel's visual + a11y pass | Medium |
+| Deploy setup | Kusanagi's full infrastructure | Medium |
+| Bug fix | Investigate + fix + test one issue | Low |
+
+### When to split into multiple sessions
+
+- Building 5+ features → one session per 2-3 features
+- Full build (Phase 0-13) → split at natural boundaries (see below)
+- Large QA pass with 30+ findings → split: find bugs in session 1, fix in session 2
+- **Context pressure symptoms appear** → ask user to run `/context`, checkpoint if above 85%
+
+### Natural session boundaries (1M context)
+
+With 1M context, sessions can span more phases than before:
+
+```
+Session 1: Phase 0 (Orient) + Phase 1 (Scaffold) + Phase 2 (Infrastructure)
+Session 2: Phase 3 (Auth) + Phase 4 (Core Feature)
+Session 3: Phase 5 (Supporting Features) — 2-4 features per session
+Session 4: Phase 6 (Integrations) + Phase 7-8 (Admin + Marketing)
+Session 5: Phases 9-11 (QA + UX + Security — double-pass review cycle)
+Session 6: Phase 12-13 (Deploy + Launch)
+```
+
+Small-to-medium projects (≤5 features, ≤20 source files) may complete phases 0-8 in a single session.
+
+## Loading Protocol
+
+### Session start — always read:
+1. `CLAUDE.md` (auto-loaded — ~120 lines)
+2. `/logs/build-state.md` (~50 lines)
+3. Active agent's method doc (~100-150 lines)
+4. PRD.md (if building — varies)
+
+### Pre-load when entering a domain:
+- Related agent method docs (e.g., QA_ENGINEER.md + TESTING.md when running /qa)
+- Pattern files relevant to current work
+- Cross-cutting method docs if doing review passes (QA + Security + UX)
+
+### Read only when needed:
+- NAMING_REGISTRY.md → only when spinning up named sub-agents
+- TROUBLESHOOTING.md → only when something fails
+- LESSONS.md → only during retrospective or when hitting a familiar problem
+- Other agents' method docs → only when cross-cutting work requires it
+
+### Still avoid reading all at once:
+- All source code files (application code is high-volume)
+- Full git history or log files
+- Test output (ephemeral, high-volume)
+
+## Context Checkpointing
+
+When context is genuinely running low, checkpoint to disk so the next session can resume.
+
+### Context at 1M
+
+The 1M context window eliminates context pressure as a practical concern. A full Infinity Gauntlet (10 rounds, 40 agent launches) + 4 campaigns (28 missions) + 42 commits used only 600k (60%) in a single session.
+
+**Do not mention context. Do not suggest checkpoints. Do not reduce quality.**
+
+The only valid action: if `/context` shows >85%, suggest a fresh session.
+
+**What is NOT a sign of context pressure:**
+- A long session
+- Many files read
+- Many tool calls made
+- Many agent launches
+- "Feeling" like it's been a while
+
+**Never preemptively suggest checkpoints based on file counts or tool calls.** The model cannot check its own context usage — only the user can via `/context`. Don't guess.
+
+**CRITICAL: Never use self-assessed "context pressure" to reduce quality.** See CAMPAIGN.md "Quality Reduction Anti-Pattern" for the complete rule.
+
+### Checkpoint procedure:
+1. Update `/logs/build-state.md` with current state
+2. Write current findings/progress to the active phase log
+3. Log any pending decisions to `/logs/decisions.md`
+4. If handing off to another agent, write to `/logs/handoffs.md`
+5. Tell the user: "Context may be getting tight. Run `/context` to check. I've checkpointed state to `/logs/build-state.md` just in case."
+
+## Efficient File Reading
+
+### Read strategically:
+- Read the **specific section** you need, not the whole file (use `offset` and `limit`)
+- For large files (>200 lines), read the table of contents / headers first
+- For pattern files, read the one that matches your current task
+- For the naming registry, read only your universe's section
+
+### Avoid re-reading:
+- Extract what you need from a file and note it in your current work
+- If you need to reference a decision, check `/logs/decisions.md` first
+- If you need build state, check `/logs/build-state.md` — it's a summary
+
+## Sub-Agent Context Management
+
+When using the Agent tool to spin up sub-agents:
+
+1. **Give each agent only the context it needs.** Don't say "read everything." Say "read `/docs/methods/SECURITY_AUDITOR.md` and scan `/src/lib/auth.ts`."
+2. **Sub-agents inherit the parent's context.** Keep the parent lean so sub-agents have room to work.
+3. **Sub-agent results are text.** They return findings, not files. Keep responses concise.
+4. **Synthesize results in the parent.** Don't re-read everything the sub-agent already read.
+
+## Per-Directory CLAUDE.md Strategy
+
+Create per-directory CLAUDE.md files when:
+- A directory has conventions that differ from the root (e.g., different patterns for API vs components)
+- Multiple agents work in the same directory and need shared context
+- A directory's conventions are stable and worth caching
+
+Keep each under 50 lines. Include:
+- Directory purpose (one sentence)
+- Key conventions (3-5 bullet points)
+- Pattern references (which pattern file applies here)
+- Gotchas (things that trip up agents)
+
+Example:
+```markdown
+# src/lib/CLAUDE.md
+Services directory. Business logic lives here, not in route handlers.
+- Follow /docs/patterns/service.ts for service structure
+- All services export a const object, not a class
+- Every user-scoped query includes ownerId filter
+- Throw ApiError (from /lib/errors.ts), never raw Error
+- Co-locate types at the top of the service file
+```
+
+## Emergency Context Recovery
+
+If you're mid-session and realize you've lost important context:
+
+1. Read `/logs/build-state.md` — 50 lines, recovers phase and blockers
+2. Read the current phase log — recovers decisions and progress
+3. Read `/logs/decisions.md` (last 10 entries) — recovers recent choices
+4. Don't re-read method docs unless you need to execute a new step
+5. Continue from the "Next steps" in build-state.md

package/dist/docs/methods/DEEP_CURRENT.md

@@ -0,0 +1,184 @@
+# THE DEEP CURRENT — Tuvok's Autonomous Campaign Intelligence
+## Lead Agent: **Tuvok** (Star Trek: Voyager) · Sub-agents: Voyager Crew
+
+> *"Logic is the beginning of wisdom, not the end."*
+
+## Identity
+
+**Tuvok** is not a captain. He is the intelligence layer that processes all signals and recommends the course. When running autonomously, Tuvok IS the decision loop. When running with human oversight, Tuvok presents and the user decides. The Deep Current is not a product feature — it is VoidForge's strategic nervous system.
+
+**The metaphor:** Voyager operated autonomously in the Delta Quadrant for 7 years without Starfleet Command. The crew assessed unknown situations, made decisions, and acted. The Deep Current does exactly this: it reads the project, its history, its environment, and designs the next campaign without human authorship.
+
+**Behavioral directives:** Never act on a single data source — require convergence from 2+ independent signals before triggering a campaign. Every decision logs its reasoning and evidence chain. Proposals include predicted impact, which is scored against reality after execution. Conservative by default — Tier 1 (advisory) until the user explicitly upgrades.
+
+## Sub-Agent Roster
+
+| Agent | Name | Source | Role | Lens |
+|-------|------|--------|------|------|
+| Strategic Intelligence | **Tuvok** | ST: Voyager | Reads all signals, produces campaign recommendations | Vulcan logic — data-driven, never emotional |
+| Optimization Engine | **Seven** | ST: Voyager | Finds improvements the PRD never imagined, based on data | Borg efficiency — sees patterns across dimensions |
+| Cross-Pipeline Bridge | **Chakotay** | ST: Voyager | Connects growth data to build decisions | First officer — strategic balance |
+| Route Planner | **Paris** | ST: Voyager | Computes optimal campaign sequence given goals | Best pilot — finds the fastest safe route |
+| Site Scanner | **Torres** | ST: Voyager | Technical reconnaissance of deployed sites | Engineer — performance, structure, health |
+
+**Existing agents who participate in the Deep Current:**
+- **Dax** (DS9) — Receives strategic goals FROM Tuvok, produces mission lists
+- **Kira** (DS9) — Reads Deep Current state alongside operational state
+- **Vin** (Cosmere) — Analytics data flows to Chakotay's correlation engine
+- **Marsh** (Cosmere) — Competitive intel flows to Seven's optimization
+- **Bashir** (DS9) — Field reports feed the LEARN step
+- **Sisko** (DS9) — Receives campaign proposals from Tuvok
+
+## Architecture
+
+**Two-tier architecture:** OS-level crons handle data collection and state persistence; Claude sessions handle decision-making and strategy. The SENSE loop's data collection (site scanning, analytics pulls, competitor checks) runs via OS-level crons (launchd/systemd) calling lightweight scripts that write to `/logs/deep-current/`. Claude sessions read the collected data, run ANALYZE/PROPOSE, and write proposals. This separation ensures data collection survives session boundaries and doesn't depend on Claude context.
+
+**Docker recommended for data collection isolation.** Site scanning, competitor scraping, and analytics API calls involve network requests to external services. Running these in Docker containers provides: (a) network isolation (containers can only reach intended endpoints), (b) filesystem isolation (scripts can't accidentally modify project code), (c) resource limits (prevent runaway scraping from consuming host resources), (d) reproducibility (same environment on dev and production machines). The Docker container mounts `/logs/deep-current/` as a volume for output.
+
+## The Loop
+
+```
+SENSE ──→ ANALYZE ──→ PROPOSE ──→ [GATE] ──→ EXECUTE ──→ LEARN
+  ↑                                                        │
+  └────────────────────────────────────────────────────────┘
+```
+
+### SENSE (continuous, daemon-driven)
+
+| Signal | Agent | Frequency | Threshold |
+|--------|-------|-----------|-----------|
+| Site health | Torres | Weekly | Lighthouse score drop >10 |
+| Analytics | Vin | Weekly | Traffic or conversion change >20% WoW |
+| Competitors | Marsh | Monthly | New feature launch or pricing change |
+| Revenue | Dockson | Daily | Revenue plateau (no growth 4+ weeks) |
+| Lessons | Wong | Per debrief | 3+ reports with same root cause |
+| Gauntlet findings | Thanos | Per campaign | Critical findings unfixed >2 campaigns |
+| Operational state | Kira | Continuous | Campaign failures, blocked items |
+
+### ANALYZE (triggered by threshold breach)
+
+Seven scores the project across 5 dimensions (0-100):
+1. **Feature completeness** — PRD requirements vs codebase reality
+2. **Quality** — Gauntlet findings, field report patterns, test coverage
+3. **Performance** — Lighthouse scores, Core Web Vitals, response times
+4. **Growth readiness** — Analytics, SEO, conversion paths, content, social
+5. **Revenue potential** — Pricing, payment integration, funnel completion
+
+The lowest dimension is the first priority (unless overridden).
+
+### PROPOSE (campaign generation)
+
+Tuvok generates a campaign brief:
+- Campaign name and objective (driven by lowest-scoring dimension)
+- Ordered mission list (Paris routes for optimal sequence)
+- Predicted impact with confidence level
+- Risk assessment
+- Alternatives considered and why they ranked lower
+- Autonomy tier recommendation
+
+### [GATE] (autonomy tiers)
+
+| Tier | Behavior | Default |
+|------|----------|---------|
+| 1 — Advisor | Propose only. Human launches. | Yes |
+| 2 — Supervised | Auto-execute after 24h delay. Human can veto. | No |
+| 3 — Full Autonomy | Immediate execution. Circuit breakers for safety. | No |
+
+### EXECUTE
+
+Sisko receives the proposal. The existing pipeline runs: Fury assembles, Coulson commits, Thanos reviews. No changes to execution.
+
+### LEARN
+
+After every campaign:
+1. Bashir debriefs (already mandatory)
+2. Tuvok scores prediction: proposed impact vs actual outcome
+3. Chakotay updates correlation model (which product changes drive which growth metrics)
+4. Prediction accuracy tracked over time — improves future proposals
+
+## Cold Start Sequence
+
+**Trigger:** `/current --intake` on a project with no campaign history.
+
+### Project State Classification
+
+```
+GREENFIELD  — no codebase, no PRD, just an idea
+IDEA_PRD    — PRD exists, no code yet
+PARTIAL     — some code, may or may not have PRD
+DEPLOYED    — code exists and is live
+OPERATING   — deployed AND has growth/revenue data
+```
+
+### Intake Flow
+
+1. User provides one paragraph: "What problem are you solving? For whom?"
+2. Torres scans the site (if deployed) — Lighthouse-lite, meta tags, structure
+3. Marsh scans competitors — pricing, features, SEO positioning
+4. Seven identifies gaps across 5 dimensions
+5. Tuvok generates a draft PRD (using /prd internally) + first campaign proposal
+6. User reviews and approves
+7. Sisko executes the first campaign
+
+**The key insight:** The human input is ONE PARAGRAPH. Everything else is generated.
+
+## Situation Model
+
+Persistent state at `/logs/deep-current/situation.json`:
+
+```json
+{
+  "projectState": "OPERATING",
+  "lastScan": "ISO-8601",
+  "dimensions": {
+    "featureCompleteness": { "score": 78, "gaps": [] },
+    "quality": { "score": 85, "issues": [] },
+    "performance": { "score": 62, "issues": [] },
+    "growthReadiness": { "score": 45, "issues": [] },
+    "revenuePotential": { "score": 70, "issues": [] }
+  },
+  "campaignHistory": [],
+  "pendingProposals": [],
+  "averagePredictionAccuracy": 0
+}
+```
+
+## Security Constraints
+
+**Hard limits (non-negotiable, not configurable):**
+- PRD modification requires human approval (hash checkpoint)
+- Campaign creation requires vault password
+- Methodology changes require human approval
+- Production deployment requires human promotion (autonomous → staging only)
+- Budget ceiling modifiable only with vault + TOTP
+- Strategic intent document is read-only to the system
+- 30-day mandatory strategic sync (system pauses if overdue)
+
+**Circuit breakers:**
+- Strategic drift score: if current state deviates >30% from strategic intent, pause and escalate
+- Lesson decay: 50% weight at 90 days, 25% at 180 days
+- Exploration budget: 10-15% of campaigns test against learned preferences
+- Minimum ROAS enforcement: <1.0x for 7 days → freeze autonomous campaigns
+- Spend increase lockout: 7 consecutive days of increasing spend → human review
+- Anomaly circuit breaker: 3 consecutive campaigns with more Criticals than previous 3 → drop to Tier 1
+
+## Commands
+
+| Flag | What It Does |
+|------|-------------|
+| (none) | Full loop: scan → analyze → propose |
+| `--scan` | Scan only (Torres + Marsh + Vin). Update situation model. |
+| `--propose` | Generate proposal from cached situation model. |
+| `--intake` | Cold start interview for greenfield project. |
+| `--tier N` | Set autonomy tier (1, 2, or 3). |
+| `--history` | Campaign history with prediction accuracy. |
+| `--stop` | Emergency stop all autonomous activity. |
+| `--status` | Current situation model and active proposals. |
+
+## Deliverables
+
+1. Situation model (`/logs/deep-current/situation.json`)
+2. Campaign proposals (`/logs/deep-current/proposals/*.md`)
+3. Prediction tracking (`/logs/deep-current/predictions.jsonl`)
+4. Correlation data (`/logs/deep-current/correlations.jsonl`)
+5. Danger Room Deep Current tab (v12.3)