From 3f653a3e9dcc4db7c4b755e8832018717c62481c Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Tue, 30 Dec 2025 18:38:36 -0800 Subject: [PATCH] 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. --- .../formulas/mol-sync-workspace.formula.toml | 395 ++++++++++++++++++ 1 file changed, 395 insertions(+) create mode 100644 .beads/formulas/mol-sync-workspace.formula.toml diff --git a/.beads/formulas/mol-sync-workspace.formula.toml b/.beads/formulas/mol-sync-workspace.formula.toml new file mode 100644 index 00000000..0415d6ab --- /dev/null +++ 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: " +``` + +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 ` +- **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: " --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 + 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: " --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 +# Or force if needed: +git worktree remove --force +``` + +**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: + +Git: + - Branch: + - Commits behind main: 0 + - Commits ahead: + - Conflicts resolved: + +Beads: + - Sync status: OK + - Doctor findings: (fixed: , filed: , deferred: ) + +Build: PASS +Tests: PASS | FAIL ( failures, tracked in ) + +Worktrees cleaned: + +Ready for work: YES | NO () +``` + +**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 -s "SYNC_COMPLETE $(hostname)" -m "" +``` + +**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 "" +``` + +**Exit criteria:** Readiness signaled, molecule complete."""