heartbeat

WoterClip Heartbeat

Execute the WoterClip heartbeat cycle: pick up assigned GitHub issues, resolve the right persona, do the work, and report back with structured comments. All GitHub operations go through the gh CLI — no MCP server required.

Arguments:

• --dry-run — Show what would be picked up without doing work
• --persona <name> — Only pick issues matching a specific persona

Reference files (consult as needed during execution):

• ${CLAUDE_PLUGIN_ROOT}/references/comment-format.md — Comment templates and rules
• ${CLAUDE_PLUGIN_ROOT}/references/label-conventions.md — Label lifecycle and atomic label operations
• ${CLAUDE_PLUGIN_ROOT}/references/status-mapping.md — GitHub state model, sort order, inbox filtering
• ${CLAUDE_PLUGIN_ROOT}/references/sub-issues.md — Canonical create/attach/verify procedure for sub-issues
• ${CLAUDE_PLUGIN_ROOT}/references/persona-dispatch.md — Subagent dispatch, outcome contract, and fallback rules
• ${CLAUDE_PLUGIN_ROOT}/references/beat-economics.md — Clock capture, time ceiling, stop reasons, log fields

All gh issue / gh api calls below target the repo from config github.repo (pass --repo <owner/name> explicitly — never rely on the working directory's default remote).

Step 1: Load Config & Lock

1. Read .woterclip/config.yaml. If missing, stop and instruct the user to run /woterclip-init. Nothing is created yet, so this exit records nothing.
2. Check for lockfile at .woterclip/.heartbeat-lock.
   • Exists and less than stale_lock_hours old → stop: "Previous heartbeat still active. Skipping." This beat never took the lock — do not delete it and do not record a beat line.
   • Exists and older than stale_lock_hours → delete it, log: "Cleaned stale lockfile."
   • No lockfile → proceed.
3. Take the lock. This one command creates it and prints it, so the beat observes its own id and start epoch:

   printf '{"beat_id":"%s","started_at":"%s","started_epoch":%s}\n' \
     "$(date -u +%s)-$$" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$(date -u +%s)" \
     | tee .woterclip/.heartbeat-lock
   

   Carry the printed beat_id and started_epoch forward — they are the beat's identity and its clock.
4. Ownership rule, applied at every exit from here on. Re-read .woterclip/.heartbeat-lock. Delete it only if it still carries this beat's beat_id; if it is missing or carries another id, a later beat cleaned and re-took it — leave it alone. Deleting a lock this beat does not own hands two beats the same repo.
5. Every exit from here on records one beat line (step 9 format) naming that exit's stop reason, then applies the ownership rule. --dry-run and a superseded beat record none. The exit-to-reason map is in ${CLAUDE_PLUGIN_ROOT}/references/beat-economics.md. Beat elapsed is $(date -u +%s) minus started_epoch.