From 2ff800d7a77f292a9a2934f488888810902682d8 Mon Sep 17 00:00:00 2001
From: Steve Yegge <stevey@sourcegraph.com>
Date: Sun, 2 Nov 2025 13:11:57 -0800
Subject: [PATCH] bd-627d: Design agent-supervised migration safety framework

- Architecture: Beads provides observability, agents supervise
- No AI API calls from beads (proper inversion of control)
- Phase 1: Migration invariants (required_config, foreign_keys, issue_count)
- Phase 2: Inspection tools (--dry-run, --schema)
- Phase 3-4: MCP tools for agent workflows

Would have caught GH #201 (missing issue_prefix after migration)
---
 NEXT_SESSION_PROMPT.md | 87 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 NEXT_SESSION_PROMPT.md

diff --git a/NEXT_SESSION_PROMPT.md b/NEXT_SESSION_PROMPT.md
new file mode 100644
index 00000000..c5760aa0
--- /dev/null
+++ b/NEXT_SESSION_PROMPT.md
@@ -0,0 +1,87 @@
+# Next Session: Agent-Supervised Migration Safety
+
+## Context
+We identified that database migrations can lose user data through edge cases (e.g., GH #201 where `bd migrate` failed to set `issue_prefix`, breaking commands). Since beads is designed for AI agents, we should leverage **agent supervision** to make migrations safer.
+
+## Key Architectural Decision
+**Beads provides observability primitives; agents supervise using their own reasoning.**
+
+Beads does NOT:
+- ❌ Make AI API calls
+- ❌ Invoke external models
+- ❌ Call agents
+
+Beads DOES:
+- ✅ Provide deterministic invariant checks
+- ✅ Expose migration state via `--dry-run --json`
+- ✅ Roll back on validation failures
+- ✅ Give agents structured data to analyze
+
+## The Work (bd-627d)
+
+### Phase 1: Migration Invariants (Start here!)
+Create `internal/storage/sqlite/migration_invariants.go` with:
+
+```go
+type MigrationInvariant struct {
+    Name        string
+    Description string
+    Check       func(*sql.DB, *Snapshot) error
+}
+
+type Snapshot struct {
+    IssueCount      int
+    ConfigKeys      []string
+    DependencyCount int
+    LabelCount      int
+}
+```
+
+Implement these invariants:
+1. **required_config_present** - Would have caught GH #201!
+2. **foreign_keys_valid** - Detect orphaned dependencies
+3. **issue_count_stable** - Catch unexpected data loss
+
+### Phase 2: Inspection Tools
+Add CLI commands for agents to inspect migrations:
+
+1. `bd migrate --dry-run --json` - Shows what will change
+2. `bd info --schema --json` - Current schema + detected prefix
+3. Update `RunMigrations()` to check invariants and rollback on failure
+
+### Phase 3 & 4: MCP Tools + Agent Workflows
+Add MCP tools so agents can:
+- Inspect migration plans before running
+- Detect missing config (like `issue_prefix`)
+- Auto-fix issues before migration
+- Validate post-migration state
+
+## Starting Prompt for Next Session
+
+```
+Let's implement Phase 1 of bd-627d (agent-supervised migration safety).
+
+We need to create migration invariants that check for common data loss scenarios:
+1. Missing required config keys (would have caught GH #201)
+2. Foreign key integrity (no orphaned dependencies)
+3. Issue count stability (detect unexpected deletions)
+
+Start by creating internal/storage/sqlite/migration_invariants.go with the Snapshot type and invariant infrastructure. Then integrate it into RunMigrations() in migrations.go.
+
+The goal: migrations should automatically roll back if invariants fail, preventing data loss.
+```
+
+## Related Issues
+- bd-627d: Main epic for agent-supervised migrations
+- GH #201: Real-world example of migration data loss (missing issue_prefix)
+- bd-d355a07d: False positive data loss warnings
+- bd-b245: Migration registry (just completed - makes migrations introspectable!)
+
+## Success Criteria
+After Phase 1, migrations should:
+- ✅ Check invariants before committing
+- ✅ Roll back on any invariant failure
+- ✅ Provide clear error messages
+- ✅ Have unit tests for each invariant
+
+This prevents silent data loss like GH #201 where users discovered breakage only after migration completed.