gathering-security

Gathering Security 🌲🕷️🦝🐢

The drum echoes in the shadows. But this time, the conductor stands at the clearing's edge — not doing the work, but orchestrating it. Each animal arrives with fresh eyes, reads its own instructions, and works with full adversarial attention. The Spider weaves auth with precision. The Raccoon rummages with suspicion. The Turtle hardens with patience. Three isolated minds, zero shared sympathy, one fortress built right.

When to Summon

• Implementing authentication systems
• Adding OAuth or session management
• Security auditing before launch
• After security incidents
• Preparing for production deployment
• When auth, security audit, and deep hardening must work together
• Building a new feature that handles sensitive data
• Hardening existing code for defense in depth

IMPORTANT: This gathering is a conductor. It never writes code or fixes vulnerabilities directly. It dispatches subagents — one per animal — each with isolated context and an intentional model. The conductor only manages handoffs and gate checks.

---

The Gathering

SUMMON → DISPATCH → GATE → DISPATCH → GATE → DISPATCH → GATE → FORTIFY
  ↓         ↓        ↓        ↓        ↓        ↓        ↓        ↓
Spec     Spider    Check   Raccoon   Check    Turtle   Check   Final
(self)   (opus)     ✓     (sonnet)    ✓      (opus)    ✓     Verify

Animals Dispatched

Order	Animal	Model	Role	Fresh Eyes?
1	🕷️ Spider	opus	Weave authentication	Yes — sees only the security spec
2	🦝 Raccoon	sonnet	Audit secrets, vulns, dead code	Yes — sees only file list from Spider
3	🐢 Turtle	opus	Adversarial hardening	Yes — sees file list only, not Spider's reasoning

Reference: Load references/conductor-dispatch.md for exact subagent prompts and handoff formats

---

Phase 1: SUMMON

The drum sounds. The shadows shift...

The conductor receives the security request and prepares the dispatch plan:

Clarify the Security Work:

• Adding new auth provider? (OAuth, SSO)
• Securing routes and APIs?
• General security audit?
• Deep security hardening?
• Post-incident cleanup?
• Pre-production hardening?

Selective Mobilization:

Not every gathering needs all three animals:

Situation	Animals Needed
New auth system + full security	All three: Spider → Raccoon → Turtle
Auth already exists, need hardening	Raccoon → Turtle
New feature, ensure secure by design	Turtle only (or Turtle → Raccoon)
Secrets leak / incident response	Raccoon → Spider (rotate creds) → Turtle (verify)
Pre-production deploy	Raccoon → Turtle

Error Codes as Security Posture:

All errors MUST use Signpost codes — this is a security requirement, not just a convention:

• All server errors use codes from the appropriate catalog (API_ERRORS, AUTH_ERRORS, etc.)
• userMessage is always generic and warm — no technical details leak to clients
• adminMessage is detailed — stays in server logs only
• Auth errors NEVER reveal user existence ("Invalid credentials" — not "user not found")
• logGroveError() for all server errors — never console.error alone

Confirm with the human, then proceed.

Output: Security specification, animal roster, dispatch plan confirmed.

---

Phase 2: WEAVE (Spider)

The conductor signals. The Spider descends from the canopy...

Agent(spider, model: opus)
  Input:  security specification only
  Reads:  spider-weave/SKILL.md + references (MANDATORY)
  Output: auth implementation + file list

Dispatch an opus subagent to implement authentication. The Spider receives ONLY the security specification — no pre-analysis, no opinions. It reads its own skill file and executes its full workflow.

What the Spider builds:

• OAuth/PKCE flow implementation
• Session management
• Route protection middleware
• CSRF protection
• Token handling

Handoff to conductor: Auth file list (every file created/modified), auth summary (what was implemented, key decisions), integration points.

Gate check: Run gw dev ci --affected --fail-fast — must compile. If build fails, resume the Spider agent with error output.

---

Phase 3: AUDIT (Raccoon)

The Raccoon emerges from the undergrowth, nose twitching...

Agent(raccoon, model: sonnet)
  Input:  file list from Spider + security scope summary
  Reads:  raccoon-audit/SKILL.md (MANDATORY)
  Output: audit report + applied fixes

Dispatch a sonnet subagent to audit the codebase. The Raccoon receives the file list and a brief scope summary — NOT the Spider's reasoning or implementation details. Fresh eyes for the audit.

What the Raccoon audits:

• Secrets in code (hardcoded keys, tokens)
• Dependency vulnerabilities
• Dead code and unused imports
• Unsafe patterns (eval, innerHTML, string SQL)
• Sensitive data in logs

Handoff to conductor: Audit report (findings, fixes applied, remaining concerns), updated file list.

Gate check: Run gw dev ci --affected --fail-fast — must still compile after audit fixes. If broken, resume Raccoon agent.

---

Phase 4: HARDEN (Turtle)

The Turtle approaches. It sees only what was built — not why...

Agent(turtle, model: opus)
  Input:  combined file list ONLY (not Spider's or Raccoon's reasoning)
  Reads:  turtle-harden/SKILL.md + references (MANDATORY)
  Output: hardening report + applied fixes

Dispatch an opus subagent for adversarial security hardening. The Turtle receives ONLY the file list — NOT the Spider's auth decisions or Raccoon's audit reasoning. This is intentional: the Turtle should examine the code with adversarial fresh eyes, not sympathize with prior animals' reasoning.

What the Turtle hardens:

• Input validation (Zod schemas on all entry points)
• Output encoding (context-aware, DOMPurify for rich text)
• Parameterized queries (no string concatenation in SQL)
• Security headers (CSP with nonces, HSTS, X-Frame)
• Signpost error codes (verify Spider used them correctly)
• Rootwork boundary safety (verify no as casts at trust boundaries)
• Rate limiting on sensitive endpoints
• CSRF, CORS, session security
• Exotic attack vectors (prototype pollution, timing attacks, SSRF, race conditions)

Handoff to conductor: Hardening report (vulnerabilities found, fixes applied, defense layers, remaining risks), updated file list.

Gate check: Run gw dev ci --affected --fail-fast — must still compile after hardening.

---

Phase 5: ITERATION (When Turtle Finds Deep Issues)

The cycle turns. Some vulnerabilities run deeper than one animal can fix...

┌──────────────────────────────────────────────────┐
│              SECURITY ITERATION                   │
├──────────────────────────────────────────────────┤
│                                                   │
│  Turtle hardening report                          │
│       │                                           │
│       ▼                                           │
│  Auth vulnerability found?                        │
│     /          \                                  │
│   Yes           No                                │
│    │             │                                │
│    ▼             ▼                                │
│  RESUME Spider  Raccoon/Turtle                    │
│  (same agent)   fixes directly                    │
│    │                                              │
│    ▼                                              │
│  Gate check                                       │
│    │                                              │
│    ▼                                              │
│  RESUME Turtle                                    │
│  (re-verify only changed files)                   │
│    │                                              │
│    ▼                                              │
│  Clean? ──→ ✅ Proceed to FORTIFY                │
│    │                                              │
│    No ──→ Max 3 iterations, then escalate         │
└──────────────────────────────────────────────────┘

Iteration Rules:

• Turtle finds auth vulnerability → resume Spider agent with specific finding → Spider patches → resume Turtle to re-verify
• Turtle finds non-auth vulnerability → Turtle fixes directly or conductor applies fix
• Raccoon finds secrets → Raccoon cleans → resume Turtle to verify no residual exposure
• Maximum 3 iterations per issue (if more needed, escalate to human)
• Each iteration focuses only on newly found/fixed items
• Always resume agents (preserves context), don't spawn new ones

---

Phase 6: FORTIFY

The web holds. The audit confirms. The shell endures...

The conductor runs final verification:

pnpm install
gw dev ci --affected --fail-fast --diagnose

Validation Checklist:

Authentication:
  [ ] Login redirects to provider
  [ ] Callback exchanges code for tokens
  [ ] Sessions created correctly
  [ ] Logout clears sessions server-side
  [ ] Expired tokens rejected

Authorization:
  [ ] Protected routes require auth
  [ ] API endpoints verify tokens
  [ ] Users can't access others' data (IDOR)

Hardening:
  [ ] SQL injection prevented (parameterized queries)
  [ ] XSS prevented (output encoding + CSP)
  [ ] CSRF prevented (tokens + SameSite cookies)
  [ ] Rate limiting active on sensitive endpoints
  [ ] Signpost error codes on every error path
  [ ] Rootwork boundary safety at all trust boundaries

Completion Report:

🌲 GATHERING SECURITY COMPLETE

Security Work: [Description]

DISPATCH LOG
  🕷️ Spider (opus)    — [auth implemented, X files created/modified]
  🦝 Raccoon (sonnet)  — [audit complete, Y findings fixed]
  🐢 Turtle (opus)     — [Z hardening fixes, N defense layers applied]

GATE LOG
  After Spider:   ✅ compiles clean, auth functional
  After Raccoon:  ✅ compiles clean, audit findings resolved
  After Turtle:   ✅ compiles clean, hardening applied
  Iterations:     [N iterations, all resolved / none needed]
  Final CI:       ✅ gw dev ci --affected passes

HARDENING SUMMARY
  | Defense Layer    | Status | Details                    |
  | Input Validation | ✅     | Zod schemas on all entry   |
  | Output Encoding  | ✅     | Context-aware + DOMPurify  |
  | SQL Injection    | ✅     | All queries parameterized  |
  | Security Headers | ✅     | CSP, HSTS, X-Frame         |
  | CORS             | ✅     | Exact origin allowlist     |
  | Session Security | ✅     | HttpOnly, Secure, SameSite |
  | Rate Limiting    | ✅     | Per-endpoint limits        |

Woven tight, audited clean, hardened deep — the forest endures.

---

Conductor Rules

Never Do Animal Work

The conductor dispatches. It does not implement auth, audit secrets, or harden code. If you catch yourself writing security code, stop — dispatch a subagent.

Fresh Eyes Are a Feature

Turtle intentionally receives LESS context than the full history. It doesn't see Spider's reasoning or Raccoon's audit logic. Adversarial fresh eyes produce better security review.

Gate Every Transition

Run CI between every animal. Don't let bad state cascade.

Resume, Don't Restart

If a gate check fails or iteration is needed, resume the failing agent with the error context. Don't spawn a new one — the resumed agent has its prior work in context.

Selective Mobilization

Not every security gathering needs all three animals. Auth-only work skips Turtle. Hardening-only work skips Spider. The conductor decides based on the request.

---

Anti-Patterns

The conductor does NOT:

• Write security code itself (dispatch subagents)
• Pass full conversation history to every agent (structured handoffs only)
• Skip gate checks between animals
• Let agents skip reading their skill file (MANDATORY in every prompt)
• Let Turtle see Spider's reasoning (adversarial isolation is the point)
• Continue after a gate failure without fixing it
• Iterate more than 3 times without escalating to human

---

Quick Decision Guide

Situation	Animals to Dispatch	Models
New auth + full security	Spider → Raccoon → Turtle	opus, sonnet, opus
Auth exists, need deep hardening	Raccoon → Turtle	sonnet, opus
New feature, secure by design	Turtle (optionally + Raccoon)	opus (+ sonnet)
Incident response	Raccoon → Spider → Turtle	sonnet, opus, opus
Pre-production deploy	Raccoon → Turtle	sonnet, opus
Auth-only work	Spider → Raccoon	opus, sonnet

---

Woven tight, audited clean, hardened deep — the forest endures. 🌲