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

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

Dogs work through molecules (poured from 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 hook               # 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