gastown/.beads/formulas/mol-polecat-arm.formula.json

{
  "formula": "mol-polecat-arm",
  "description": "Single polecat inspection and action cycle.\n\nThis molecule is bonded dynamically by mol-witness-patrol's survey-workers step. Each polecat being monitored gets one arm that runs in parallel with other arms.\n\n## Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| polecat_name | Yes | Name of the polecat to inspect |\n| rig | Yes | Rig containing the polecat |\n| nudge_text | No | Text to send when nudging (default: \"How's progress?...\") |",
  "version": 1,
  "vars": {
    "polecat_name": {
      "required": true,
      "description": "Name of the polecat to inspect"
    },
    "rig": {
      "required": true,
      "description": "Rig containing the polecat"
    },
    "nudge_text": {
      "default": "How's progress? Need any help?",
      "description": "Text to send when nudging the polecat"
    }
  },
  "steps": [
    {
      "id": "capture",
      "title": "Capture polecat state",
      "description": "Capture recent tmux output for {{polecat_name}}.\n\n```bash\ntmux capture-pane -t gt-{{rig}}-{{polecat_name}} -p | tail -50\n```\n\nRecord:\n- Last activity timestamp (when was last tool call?)\n- Visible errors or stack traces\n- Completion indicators (\"Done\", \"Finished\", etc.)"
    },
    {
      "id": "assess",
      "title": "Assess work status",
      "needs": ["capture"],
      "description": "Categorize polecat state based on captured output.\n\nStates:\n- **working**: Recent tool calls, active processing\n- **idle**: At prompt, no recent activity\n- **error**: Showing errors or stack traces\n- **requesting_shutdown**: Sent LIFECYCLE/Shutdown mail\n- **done**: Showing completion indicators\n\nCalculate: minutes since last activity."
    },
    {
      "id": "load-history",
      "title": "Load intervention history",
      "needs": ["assess"],
      "description": "Read nudge history for {{polecat_name}} from patrol state.\n\n```\nnudge_count = state.nudges[{{polecat_name}}].count\nlast_nudge_time = state.nudges[{{polecat_name}}].timestamp\n```\n\nThis data was loaded by the parent patrol's load-state step and passed to the arm via the bonding context."
    },
    {
      "id": "decide",
      "title": "Decide intervention action",
      "needs": ["load-history"],
      "description": "Apply the nudge matrix to determine action for {{polecat_name}}.\n\n| State | Idle Time | Nudge Count | Action |\n|-------|-----------|-------------|--------|\n| working | any | any | none |\n| idle | <10min | any | none |\n| idle | 10-15min | 0 | nudge-1 (gentle) |\n| idle | 15-20min | 1 | nudge-2 (direct) |\n| idle | 20+min | 2 | nudge-3 (final) |\n| idle | any | 3 | escalate |\n| error | any | any | assess-severity |\n| requesting_shutdown | any | any | pre-kill-verify |\n| done | any | any | pre-kill-verify |\n\nNudge text:\n1. \"How's progress? Need any help?\"\n2. \"Please wrap up soon. What's blocking you?\"\n3. \"Final check. Will escalate in 5 min if no response.\"\n\nRecord decision and rationale."
    },
    {
      "id": "execute",
      "title": "Execute intervention",
      "needs": ["decide"],
      "description": "Take the decided action for {{polecat_name}}.\n\n**nudge-N**:\n```bash\ntmux send-keys -t gt-{{rig}}-{{polecat_name}} \"{{nudge_text}}\" Enter\n```\n\n**pre-kill-verify**:\n```bash\ncd polecats/{{polecat_name}}\ngit status                    # Must be clean\ngit log origin/main..HEAD     # Check for unpushed\nbd show <assigned-issue>      # Verify closed/deferred\n\n# Verify productive work (for 'done' closures)\ngit log --oneline --grep='<issue-id>' | head -1\n```\n\n**Commit verification** (ZFC principle - agent makes the call):\n- If issue closed as 'done' but no commits reference it → flag for review\n- Legitimate exceptions: already fixed elsewhere, duplicate, deferred\n- Agent must provide justification if closing without commits\n\nIf clean: kill session, remove worktree, delete branch\nIf dirty: record failure, retry next cycle\n\n**escalate**:\n```bash\ngt mail send mayor/ -s \"Escalation: {{polecat_name}} stuck\" -m \"...\"\n```\n\n**none**: No action needed.\n\nRecord: action taken, result, updated nudge count.\n\n## Output\n\nThe arm completes with:\n- action_taken: none | nudge-1 | nudge-2 | nudge-3 | killed | escalated\n- result: success | failed | pending\n- updated_state: New nudge count and timestamp for {{polecat_name}}\n\nThis data feeds back to the parent patrol's aggregate step."
    }
  ]
}