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

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

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