Design Decisions

A summary of key architectural decisions. Full details in spec/design-decisions.md.

Completion Semantics

• Psychonauts are multiturn by default — they loop until done
• Burst completion is deterministic (Burst.Manager monitors pids, not LLM judgment)
• Wave stops when br ready returns empty

Tool Contract

• Parameter schemas use a JSON Schema subset
• Validation is lenient (ignore unknown fields)
• Tool args JSON is buffered until end (not incrementally parsed)
• All errors become tool results (validation-as-feedback)

Persistence

• One JSONL file per burst (session_id == burst_id)
• Thinking deltas are stored (not transient)
• Session search via SQLite FTS5 index

Security

• Trust model: local machine, single user
• Shell commands classified as safe/caution/danger
• Generated code goes through staging → grounding
• Harmful feedback weighted 4x in memory system

Beads Integration

• Shell out to br CLI (don’t parse SQLite directly)
• Only Burst.Manager modifies bead status
• Test/security psychonauts can make direct code fixes

Open Items

• Grounding for tool calls above risk threshold
• Inline TUI editor vs $EDITOR for grounding edits
• Version history / rollback for generated modules
• Name collision prevention for generated psychonauts
• Conversation branching UX