Add mol-sync-workspace formula for batch prep

Molecule for coordinated workspace sync across agents: - Git pull/rebase with conflict preservation - Beads sync and doctor check - Build/test verification - Worktree cleanup - Readiness reporting Designed for broadcast to all agents before batch assignments.
2025-12-30 18:38:36 -08:00
parent 38fe5b6a23
commit 3f653a3e9d
1 changed files with 395 additions and 0 deletions
--- a/.beads/formulas/mol-sync-workspace.formula.toml
+++ b/.beads/formulas/mol-sync-workspace.formula.toml
@@ -0,0 +1,395 @@
+description = """
+Workspace synchronization molecule for batch prep.
+
+This molecule prepares an agent's workspace for a new batch of work. It syncs git
+and beads state, cleans up cruft, verifies the baseline is healthy, and reports
+readiness. Designed to be broadcast to all agents when preparing for coordinated
+work.
+
+## When to Use
+
+- Before major batch assignments
+- After extended idle periods
+- When repo baseline has diverged significantly
+- Proactive cleanup between work sessions
+
+## Conflict Resolution Philosophy
+
+**Preserve and re-land, not discard.**
+
+When git pull/rebase hits conflicts, the agent should:
+1. Assess if the conflicting work is still valuable
+2. If valuable: re-envision against new baseline, file a bead for re-implementation
+3. If obsolete (e.g., touches deleted system): discard with a note
+4. If unclear: escalate to human/mayor
+
+Polecats can file a bead and delegate. Refinery must resolve inline.
+
+## Variables
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| role | auto-detected | Agent role (crew/polecat/refinery/witness) |
+
+## Failure Modes
+
+| Situation | Action |
+|-----------|--------|
+| Rebase conflict | Preserve work via bead, complete sync on clean state |
+| Uncommitted work | Stash or commit, then sync |
+| Untracked files | Warn, let agent decide (keep/delete/gitignore) |
+| bd doctor errors | Report findings, agent triages |
+| Test failures | File bead if not already tracked, don't block sync |
+| Build failure | Must be resolved before marking sync complete |"""
+formula = "mol-sync-workspace"
+version = 1
+
+[[steps]]
+id = "assess-state"
+title = "Assess current workspace state"
+description = """
+Capture current state before any changes.
+
+**1. Check git status:**
+```bash
+git status --porcelain
+git stash list
+git branch --show-current
+```
+
+**2. Check beads state:**
+```bash
+bd sync --status
+```
+
+**3. Document starting state:**
+- Branch name
+- Uncommitted changes (staged/unstaged)
+- Untracked files (list them)
+- Stash entries
+- Beads sync status
+
+This information guides decisions in subsequent steps.
+
+**Exit criteria:** Starting state documented."""
+
+[[steps]]
+id = "handle-dirty-state"
+title = "Handle uncommitted and untracked work"
+needs = ["assess-state"]
+description = """
+Clean up any in-flight work before syncing.
+
+**If uncommitted changes exist:**
+
+Option A - Commit if ready:
+```bash
+git add -A && git commit -m "WIP: <description>"
+```
+
+Option B - Stash if not ready:
+```bash
+git stash push -m "pre-sync stash $(date +%Y%m%d-%H%M%S)"
+```
+
+**If untracked files exist:**
+
+For each untracked file, decide:
+- **Keep**: Add to .gitignore or commit
+- **Delete**: `rm <file>`
+- **Stash**: Can't stash untracked directly; commit or delete
+
+**WARN the agent**: Report untracked files prominently. They may be:
+- WIP that should be preserved
+- Build artifacts that should be gitignored
+- Cruft that should be deleted
+
+Don't auto-delete without confirmation.
+
+**If stash entries exist:**
+
+List and assess:
+```bash
+git stash list
+git stash show -p stash@{0}  # Preview each
+```
+
+Old stashes (>1 week) are likely stale. Consider dropping.
+Recent stashes may contain valuable WIP - preserve or commit.
+
+**Exit criteria:** Working tree clean or explicitly stashed."""
+
+[[steps]]
+id = "sync-git"
+title = "Sync with git remote"
+needs = ["handle-dirty-state"]
+description = """
+Fetch and rebase onto current main.
+
+**1. Fetch latest:**
+```bash
+git fetch origin
+```
+
+**2. Check divergence:**
+```bash
+git log --oneline HEAD..origin/main | head -5   # What's new on main
+git log --oneline origin/main..HEAD | head -5   # What we have locally
+```
+
+**3. Rebase onto main:**
+```bash
+git pull --rebase origin main
+```
+
+**If rebase succeeds:** Continue to next step.
+
+**If rebase conflicts:**
+
+The Preservation Protocol:
+1. **Assess the conflicting work:**
+   - Is it still valuable against new baseline?
+   - Is the conflicting area still relevant (not deleted/refactored)?
+
+2. **If work is valuable:**
+   ```bash
+   git rebase --abort
+   # Create a bead capturing the work
+   bd create --title "Re-land: <description>" --type task --priority 2
+   # Note the changes needed in the bead description
+   # Reset to clean state
+   git reset --hard origin/main
+   ```
+
+3. **If work is obsolete:**
+   ```bash
+   git rebase --abort
+   git reset --hard origin/main
+   # Note why it was discarded
+   ```
+
+4. **If unclear:**
+   - Escalate to human/mayor
+   - Document the conflict
+   - Proceed with sync on clean baseline
+
+**Refinery exception:** Must resolve conflicts inline (can't delegate).
+
+**Exit criteria:** Local branch matches or is cleanly ahead of origin/main."""
+
+[[steps]]
+id = "sync-beads"
+title = "Sync beads state"
+needs = ["sync-git"]
+description = """
+Sync the beads database with remote.
+
+```bash
+bd sync
+```
+
+**If conflicts:**
+Beads uses JSONL append-only format, so true conflicts are rare.
+If they occur:
+```bash
+bd sync --status  # Diagnose
+```
+
+Likely causes:
+- Two agents edited same bead simultaneously
+- Corrupted beads-sync branch
+
+Resolution:
+```bash
+# Try pulling fresh
+git fetch origin beads-sync
+bd sync
+```
+
+If still failing, escalate to mayor.
+
+**Exit criteria:** Beads synced successfully."""
+
+[[steps]]
+id = "run-doctor"
+title = "Run beads health check"
+needs = ["sync-beads"]
+description = """
+Check for beads system issues.
+
+```bash
+bd doctor
+```
+
+**Triage findings:**
+
+| Finding | Action |
+|---------|--------|
+| Orphaned issues (committed but not closed) | Review and close if complete |
+| Missing dependencies | Fix with `bd dep add` |
+| Circular dependencies | Resolve or escalate |
+| Stale in_progress | Check if still active, update status |
+| Route misconfigurations | Fix routes.jsonl |
+
+**For each issue found:**
+- Quick fix (<5 min): Fix now
+- Medium fix: File a bead
+- Unclear: Note for human review
+
+**Exit criteria:** Doctor findings triaged (not necessarily all fixed)."""
+
+[[steps]]
+id = "verify-build"
+title = "Verify project builds"
+needs = ["run-doctor"]
+description = """
+Ensure the codebase compiles.
+
+```bash
+go build ./...
+# Or appropriate build command for the project
+```
+
+**If build succeeds:** Continue to next step.
+
+**If build fails:**
+
+This is a blocking issue. Options:
+
+1. **Quick fix (<15 min):** Fix it now
+   ```bash
+   # Fix the issue
+   git add <files>
+   git commit -m "fix: build failure from sync"
+   git push
+   ```
+
+2. **Non-trivial fix:** File and escalate
+   ```bash
+   bd create --title "Build broken on main" --type bug --priority 0
+   gt mail send --human -s "ALERT: Main doesn't build" -m "Details..."
+   ```
+   Cannot mark sync complete with broken build.
+
+**Exit criteria:** Project builds successfully."""
+
+[[steps]]
+id = "run-tests"
+title = "Run test suite"
+needs = ["verify-build"]
+description = """
+Verify tests pass on current baseline.
+
+```bash
+go test ./...
+```
+
+**If tests pass:** Continue to next step.
+
+**If tests fail:**
+
+Unlike build failures, test failures don't block sync completion.
+However, they must be tracked.
+
+1. **Check if already tracked:**
+   ```bash
+   bd list --type=bug --status=open | grep -i test
+   ```
+
+2. **If not tracked, file a bead:**
+   ```bash
+   bd create --title "Test failure: <test name>" --type bug --priority 1
+   ```
+
+3. **Report in summary:**
+   Note which tests are failing so batch assignment accounts for it.
+
+**Exit criteria:** Test results documented, failures tracked in beads."""
+
+[[steps]]
+id = "cleanup-worktrees"
+title = "Clean up stale worktrees"
+needs = ["run-tests"]
+description = """
+Remove orphaned worktrees from cross-rig work.
+
+**1. List worktrees:**
+```bash
+git worktree list
+```
+
+**2. Identify stale worktrees:**
+- Worktrees for branches that no longer exist on remote
+- Worktrees older than 1 week without recent commits
+- Worktrees for completed/merged work
+
+**3. Remove stale worktrees:**
+```bash
+git worktree remove <path>
+# Or force if needed:
+git worktree remove --force <path>
+```
+
+**4. Prune worktree metadata:**
+```bash
+git worktree prune
+```
+
+**CAUTION:** Don't remove worktrees for active cross-rig work.
+Check with `gt worktree list` if available.
+
+**Exit criteria:** Stale worktrees removed."""
+
+[[steps]]
+id = "generate-report"
+title = "Generate sync report"
+needs = ["cleanup-worktrees"]
+description = """
+Summarize sync results for broadcast response.
+
+**Report format:**
+```
+SYNC COMPLETE: <agent-name>
+
+Git:
+  - Branch: <branch>
+  - Commits behind main: 0
+  - Commits ahead: <n>
+  - Conflicts resolved: <y/n, details if yes>
+
+Beads:
+  - Sync status: OK
+  - Doctor findings: <count> (fixed: <n>, filed: <n>, deferred: <n>)
+
+Build: PASS
+Tests: PASS | FAIL (<count> failures, tracked in <bead-ids>)
+
+Worktrees cleaned: <count>
+
+Ready for work: YES | NO (<reason>)
+```
+
+**Exit criteria:** Report generated."""
+
+[[steps]]
+id = "signal-ready"
+title = "Signal readiness"
+needs = ["generate-report"]
+description = """
+Report sync completion to coordinator (if broadcast) or to self (if autonomous).
+
+**If responding to broadcast:**
+```bash
+gt mail send <coordinator> -s "SYNC_COMPLETE $(hostname)" -m "<report>"
+```
+
+**If autonomous sync:**
+- Log the report
+- Update any relevant agent status
+
+**If sync failed (couldn't build):**
+```bash
+gt mail send --human -s "SYNC_FAILED $(hostname)" -m "<report with failure details>"
+```
+
+**Exit criteria:** Readiness signaled, molecule complete."""