gastown/.beads/formulas/mol-dep-propagate.formula.toml

description = """
Propagate cross-rig dependency resolution.

Dogs execute this formula when dependencies resolve across rig boundaries.
When an issue in one rig closes, dependent issues in other rigs may unblock.
This formula handles:
- Finding cross-rig dependents
- Notifying affected rigs
- Updating blocked status
- Triggering work dispatch if appropriate

## Dog Contract

This is infrastructure work. You:
1. Receive closed issue ID via hook_bead
2. Find all cross-rig dependents (issues in other rigs blocked by this)
3. Notify affected Witnesses
4. Optionally trigger dispatch if issues are now ready
5. Return to kennel

## Variables

| Variable | Source | Description |
|----------|--------|-------------|
| resolved_issue | hook_bead | The issue that just closed |

## Why Dogs?

Cross-rig work requires multi-rig worktrees. Dogs have these, polecats don't.
The Deacon detects the closure, but the propagation needs rig access."""
formula = "mol-dep-propagate"
version = 1

[squash]
trigger = "on_complete"
template_type = "work"
include_metrics = true

[[steps]]
id = "load-resolved-issue"
title = "Load resolved issue and find dependents"
description = """
Load the closed issue and identify cross-rig dependents.

**1. Check your assignment:**
```bash
gt mol status               # Shows hook_bead = resolved issue ID
bd show {{resolved_issue}}  # Full issue details
```

**2. Verify issue is closed:**
```bash
bd show {{resolved_issue}}
# Status should be 'closed' or similar terminal state
```

**3. Find dependents (issues blocked by this one):**
```bash
bd show {{resolved_issue}}
# Look at 'blocks' field - these are issues waiting on this one
```

**4. Identify cross-rig dependents:**
- Same-rig dependents: Already handled by local beads (automatic unblock)
- Cross-rig dependents: Different prefix (e.g., gt- vs bd-) need propagation

```bash
# Example: resolved_issue is bd-xxx, blocks gt-yyy
# gt-yyy is cross-rig and needs notification
```

**Exit criteria:** Resolved issue loaded, cross-rig dependents identified."""

[[steps]]
id = "update-blocked-status"
title = "Update blocked status in affected rigs"
needs = ["load-resolved-issue"]
description = """
Update the blocked status for cross-rig dependents.

**1. For each cross-rig dependent:**
```bash
# Navigate to the rig containing the dependent issue
# Dogs have multi-rig worktrees for this

bd show <dependent-id>
# Check if this was the only blocker
```

**2. Check if now unblocked:**
```bash
bd blocked <dependent-id>
# If empty or only shows other blockers, issue is now unblocked
```

**3. Verify automatic unblock worked:**
Beads should auto-update blocked status when dependencies close.
This step verifies and fixes if needed:
```bash
# If still showing as blocked by resolved issue (shouldn't happen):
bd dep remove <dependent-id> {{resolved_issue}}
```

**Exit criteria:** All cross-rig dependents have updated blocked status."""

[[steps]]
id = "notify-witnesses"
title = "Notify affected rig Witnesses"
needs = ["update-blocked-status"]
description = """
Send notifications to Witnesses of affected rigs.

**1. Group dependents by rig:**
- gastown/witness: for gt-* issues
- beads/witness: for bd-* issues
- etc.

**2. For each affected rig, send notification:**
```bash
gt mail send <rig>/witness -s "Dependency resolved: {{resolved_issue}}" -m "$(cat <<EOF
External dependency has closed, unblocking work in your rig.

## Resolved Issue
- ID: {{resolved_issue}}
- Title: {{resolved_issue.title}}
- Rig: {{resolved_issue.prefix}}

## Unblocked in Your Rig
{{range dependent}}
- {{dependent.id}}: {{dependent.title}} ({{dependent.status}})
{{end}}

These issues may now proceed. Check bd ready for available work.
EOF
)"
```

**3. Log notification:**
Note which Witnesses were notified for audit trail.

**Exit criteria:** All affected Witnesses notified."""

[[steps]]
id = "trigger-dispatch"
title = "Optionally trigger work dispatch"
needs = ["notify-witnesses"]
description = """
Trigger work dispatch for newly-unblocked issues if appropriate.

**1. For each unblocked issue, check if ready for work:**
```bash
bd show <issue-id>
# Check:
# - Status: should be 'open' (not already in_progress)
# - Priority: high priority may warrant immediate dispatch
# - No other blockers: bd blocked should be empty
```

**2. Decision: trigger dispatch?**

| Condition | Action |
|-----------|--------|
| High priority (P0-P1) + open + unblocked | Recommend immediate dispatch |
| Medium priority (P2) + open + unblocked | Note in Witness notification |
| Low priority (P3-P4) | Let Witness handle in next patrol |

**3. If triggering dispatch:**
```bash
# For high priority, suggest to Mayor:
gt mail send mayor/ -s "High-priority work unblocked: <issue>" -m "..."
```

Usually, the Witness notification (previous step) is sufficient - Witnesses
handle their own dispatch decisions.

**Exit criteria:** Dispatch recommendations sent where appropriate."""

[[steps]]
id = "return-to-kennel"
title = "Signal completion and return to kennel"
needs = ["trigger-dispatch"]
description = """
Signal work complete and return to available pool.

**1. Signal completion to Deacon:**
```bash
gt mail send deacon/ -s "DOG_DONE $(hostname)" -m "Task: dep-propagate
Resolved: {{resolved_issue}}
Cross-rig dependents: {{dependent_count}}
Witnesses notified: {{witness_list}}
Status: COMPLETE

Ready for next assignment."
```

**2. Update activity feed:**
The propagation creates implicit feed entries (dependency updates).
No explicit entry needed.

**3. Return to kennel:**
Dog returns to available state in the pool.

**Exit criteria:** Deacon notified, dog ready for next work or retirement."""

[vars]
[vars.resolved_issue]
description = "The issue ID that just closed and needs propagation"
required = true