gastown/.beads/formulas/mol-sync-workspace.formula.toml

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) |
| build_command | config or default | Build command (default: `go build ./...`) |
| test_command | config or default | Test command (default: `go test ./...`) |

## 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.

**0. Prime context (critical for fresh sessions):**
```bash
gt prime   # Load gt/mol context
bd prime   # Load beads context
```
These ensure the agent has full system context, especially after session
start, compaction, or context clear.

**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:** Context primed, 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 = ["cleanup-worktrees"]
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-specific conflict resolution:**

Unlike polecats who can file a bead and delegate, the Refinery MUST resolve
conflicts inline. The Refinery processes the merge queue - if it can't resolve
a conflict, the queue backs up and polecats' completed work never lands.

**Refinery conflict protocol:**

1. **Analyze the conflict:**
   ```bash
   git status                    # See conflicted files
   git diff                      # Examine conflict markers
   ```

2. **Trivial conflicts (resolve immediately):**
   - Import ordering changes
   - Whitespace or formatting
   - Non-overlapping additions in same file
   - Version bumps or changelog entries

   Resolution:
   ```bash
   # Edit conflicted files to resolve
   git add <resolved-files>
   git rebase --continue
   ```

3. **Semantic conflicts (assess carefully):**
   - Both sides modified same function
   - Deleted code that the other side modified
   - Structural changes (renamed files, moved code)

   If you can understand both intents and merge correctly:
   ```bash
   # Carefully merge the changes, preserving both intents
   git add <resolved-files>
   git rebase --continue
   ```

4. **Complex conflicts (abort and notify polecat):**
   - Conflicting business logic changes
   - Unclear which version is correct
   - Risk of subtle bugs from incorrect merge

   ```bash
   git rebase --abort
   gt mail send {{ rig }}/polecats/<worker> -s "Rebase needed" \
     -m "Your branch conflicts with main in <files>. Please rebase and resubmit via gt done."
   # Skip this branch, continue with queue
   ```

**The Refinery judgment call:** When in doubt, abort and notify rather than
risk merging incorrectly. A resubmitted branch is better than a broken main.

**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
{{ build_command }}
# Default: go build ./...
# Configure via build_command variable for non-Go projects
```

**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
{{ test_command }}
# Default: go test ./...
# Configure via test_command variable for non-Go projects
```

**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 = ["handle-dirty-state"]
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 = ["run-tests"]
description = """
Summarize sync results for broadcast response.

**Git status check:**
```bash
# Get current branch
BRANCH=$(git rev-parse --abbrev-ref HEAD)

# Check divergence from origin/main
BEHIND=$(git rev-list HEAD..origin/main --count)
AHEAD=$(git rev-list origin/main..HEAD --count)
```

**Report format (for feature branches):**
```
SYNC COMPLETE: <agent-name>

Git:
  - Branch: <branch>
  - Commits behind main: <n>
  - Commits ahead of main: <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>)
```

**Report format (for crew on main):**

When the agent is on the main branch directly (common for crew workers),
use "Unpushed commits" instead of "Commits ahead of main":

```
SYNC COMPLETE: <agent-name>

Git:
  - Branch: main
  - Commits behind origin: <n>
  - Unpushed commits: <n>
  - Conflicts resolved: <y/n, details if yes>
...
```

This distinction is important because:
- Crew workers often work directly on main
- "Commits ahead of main" is confusing when you ARE on main
- "Unpushed commits" is clearer - it means local work not yet on origin

**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."""