gastown/.beads/formulas/mol-convoy-cleanup.formula.toml

description = """
Archive completed convoys and notify overseer.

Dogs execute this formula when convoys complete. The Deacon detects completed
convoys (all tracked issues closed) and slings this work to a dog for:
- Generating convoy summary
- Archiving convoy state
- Notifying the overseer (Mayor)
- Updating activity feed

## Dog Contract

This is infrastructure work. You:
1. Receive convoy ID via hook_bead
2. Generate summary of completed work
3. Archive to appropriate location
4. Notify stakeholders
5. Return to kennel

## Variables

| Variable | Source | Description |
|----------|--------|-------------|
| convoy | hook_bead | The convoy ID to archive |

## Failure Modes

| Situation | Action |
|-----------|--------|
| Convoy not found | Exit with error, notify Deacon |
| Archive location full | Create space, retry, or escalate |
| Mail send fails | Retry once, then proceed anyway |"""
formula = "mol-convoy-cleanup"
version = 1

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

[[steps]]
id = "load-convoy"
title = "Load convoy and verify completion"
description = """
Load the convoy bead and verify it's ready for archival.

**1. Check your assignment:**
```bash
gt hook               # Shows hook_bead = convoy ID
bd show {{convoy}}          # Full convoy details
```

**2. Verify convoy is complete:**
- Status should be 'closed' or all tracked issues closed
- If convoy is still open, exit - Deacon dispatched too early

```bash
bd show {{convoy}}
# Check 'tracks' or 'dependencies' field
# All tracked issues should be closed
```

**3. Gather convoy metadata:**
- Start date (created_at)
- End date (last closure timestamp)
- Total issues tracked
- Contributing polecats

**Exit criteria:** Convoy loaded, verified complete, metadata gathered."""

[[steps]]
id = "generate-summary"
title = "Generate convoy summary"
needs = ["load-convoy"]
description = """
Create a summary of the convoy's completed work.

**1. Collect tracked issue details:**
```bash
# For each tracked issue
bd show <tracked-id>
# Extract: title, type, assignee, duration
```

**2. Calculate statistics:**
- Total duration (convoy start to finish)
- Issues by type (task, bug, feature)
- Contributors (unique assignees)
- Commits generated (if tracked)

**3. Create summary text:**
```markdown
## Convoy Summary: {{convoy.title}}

**Duration**: X days/hours
**Issues completed**: N

### Work Breakdown
- Tasks: N
- Bugs: N
- Features: N

### Contributors
- polecat-1: N issues
- polecat-2: N issues

### Key Outcomes
- <notable achievement 1>
- <notable achievement 2>
```

**Exit criteria:** Summary text generated and ready for notification."""

[[steps]]
id = "archive-convoy"
title = "Archive convoy to cold storage"
needs = ["generate-summary"]
description = """
Move convoy from active to archived state.

**1. Update convoy status:**
```bash
bd update {{convoy}} --status=archived
# Or close if not already closed
bd close {{convoy}} --reason="Convoy complete, archived"
```

**2. Generate archive record:**
The convoy bead with all metadata is the archive record. Beads retention
handles moving it to `.beads/archive/` after the retention period.

**3. Verify archive:**
```bash
bd show {{convoy}}
# Status should reflect archived state
```

**4. Sync to persist:**
```bash
bd sync
```

**Exit criteria:** Convoy archived, changes synced."""

[[steps]]
id = "notify-overseer"
title = "Send completion notification to overseer"
needs = ["archive-convoy"]
description = """
Notify the Mayor (overseer) of convoy completion.

**1. Send completion mail:**
```bash
gt mail send mayor/ -s "Convoy complete: {{convoy.title}}" -m "$(cat <<EOF
Convoy {{convoy}} has completed and been archived.

## Summary
{{generated_summary}}

## Metrics
- Duration: {{duration}}
- Issues: {{issue_count}}
- Contributors: {{contributor_list}}

This convoy has been archived. View details: bd show {{convoy}}
EOF
)"
```

**2. Post to activity feed:**
The convoy closure already creates a feed entry. Verify:
```bash
gt feed --since 5m
# Should show convoy completion
```

**Exit criteria:** Overseer notified via mail, activity feed updated."""

[[steps]]
id = "return-to-kennel"
title = "Signal completion and return to kennel"
needs = ["notify-overseer"]
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: convoy-cleanup
Convoy: {{convoy}}
Status: COMPLETE
Duration: {{work_duration}}

Ready for next assignment."
```

**2. Clean workspace:**
- No convoy-specific state to clean
- Workspace should already be clean

**3. Return to kennel:**
Dog returns to available state in the pool. Deacon will assign next work
or retire the dog if pool is oversized.

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

[vars]
[vars.convoy]
description = "The convoy ID to archive"
required = true