diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl index 9146194d..33f6b54f 100644 --- a/.beads/issues.jsonl +++ b/.beads/issues.jsonl @@ -1,10 +1,14 @@ +{"id":"gt-01u","title":"Design: Collapse mail into beads","description":"## Proposal\n\nReplace the separate mail system (JSONL inboxes) with beads issues using a naming convention.\n\n## Rationale\n\nIf all state should be in beads (work items, swarm state, dependencies), why have a separate system for messages? Mail is just:\n- Handoffs (agent → self)\n- Commands (Mayor → Refinery)\n- Escalations (Witness → Mayor)\n\nThese can all be beads issues with a special prefix.\n\n## Design\n\n### Convention\n- Messages use `@-` prefix: `@-witness-1734012345`\n- Assignee = recipient\n- Status: open = unread, closed = read/acknowledged\n- Priority 0 = urgent\n\n### Commands (thin wrappers)\n```bash\ngt mail send witness -s \"Subject\" -m \"Body\"\n → bd create --prefix=@ --title=\"Subject\" --assignee=witness --description=\"Body\"\n\ngt mail inbox\n → bd list --prefix=@ --assignee=$(gt whoami) --status=open\n\ngt mail read @-abc\n → bd show @-abc \u0026\u0026 bd close @-abc\n```\n\n### Notification\nDaemon watches for new `@-` issues and pokes relevant sessions.\nOr: agents poll on heartbeat (simpler).\n\n## What We Remove\n- `mail/inbox.jsonl` files\n- Mail JSONL read/write code\n- Separate delivery mechanism\n\n## What We Keep\n- `gt mail` CLI (as wrapper)\n- Handoff semantics\n- Notification (via daemon or polling)\n\n## Benefits\n- One system, one sync, one query interface\n- All communication in git history\n- Simpler architecture\n\n## Risks\n- Beads prefix filtering must be efficient\n- Namespace collision with user prefixes\n- Performance for high-frequency messages (probably fine for handoffs)\n\n## Decision Point\nDo we need first-class mail support in beads (`bd mail` commands) or is convention sufficient?","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-16T02:10:18.32879-08:00","updated_at":"2025-12-16T02:10:18.32879-08:00"} {"id":"gt-082","title":"Worker cleanup: Beads sync on shutdown","description":"Add beads sync verification to worker cleanup checklist and Witness verification.\n\n## Update to Decommission Checklist (gt-sd6)\n\nAdd to pre-done verification:\n- bd sync --status must show 'Up to date'\n- git status .beads/ must show no changes\n\n## Beads Edge Cases\n\nUncommitted beads changes:\n bd sync\n git add .beads/\n git commit -m 'beads: final sync'\n\nBeads sync conflict (rare):\n git fetch origin main\n git checkout main -- .beads/\n bd sync --force\n git add .beads/\n git commit -m 'beads: resolve sync conflict'\n\n## Update to Witness Verification (gt-f8v)\n\nWhen capturing worker state:\n town capture \u003cpolecat\u003e \"bd sync --status \u0026\u0026 git status .beads/\"\n\nCheck for:\n- bd sync --status shows 'Up to date'\n- git status .beads/ shows no changes\n\nIf beads not synced, nudge:\n WITNESS CHECK: Beads not synced. Run 'bd sync' then commit .beads/. Signal done when complete.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:47:21.757756-08:00","updated_at":"2025-12-15T20:48:37.663168-08:00","dependencies":[{"issue_id":"gt-082","depends_on_id":"gt-l3c","type":"blocks","created_at":"2025-12-15T19:47:35.977804-08:00","created_by":"daemon"}]} {"id":"gt-0pc","title":"Document Overseer role (human operator)","description":"Document the Overseer role in Gas Town architecture.\n\n## The Overseer\n\nThe **Overseer** is the human operator of Gas Town. Not an agent - a person.\n\n## Responsibilities\n\n| Area | Overseer Does | Mayor/Agents Do |\n|------|---------------|-----------------|\n| Strategy | Define project goals | Execute toward goals |\n| Priorities | Set priority order | Work in priority order |\n| Escalations | Final decision on stuck work | Escalate to Overseer |\n| Resources | Provision machines | Use allocated resources |\n| Quality | Review \u0026 approve swarm output | Produce output |\n| Operations | Run gt commands, monitor dashboards | Do the work |\n\n## Key Interactions\n\n### Overseer → Mayor\n- Start/stop Mayor sessions\n- Direct Mayor via conversation\n- Review Mayor recommendations\n- Approve cross-rig decisions\n\n### Mayor → Overseer (Escalations)\n- Stuck workers after retries\n- Resource decisions (add machines, polecats)\n- Ambiguous requirements\n- Architecture decisions\n\n## Operating Cadence\n\nTypical Overseer workflow:\n1. Morning: Check status, review overnight work\n2. During day: Monitor, respond to escalations, adjust priorities\n3. End of day: Review progress, plan next batch\n\n## Commands for Overseers\n\n```bash\ngt status # Quick health check\ngt doctor # Detailed diagnostics \ngt doctor --fix # Auto-repair issues\ngt inbox # Messages from agents\ngt stop --all # Emergency halt\n```\n\n## Documentation Updates\n\nAdd to docs/architecture.md:\n- Overseer section under Agent Roles\n- Clarify Mayor reports to Overseer\n- Add Overseer to workflow diagrams","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T23:18:03.177633-08:00","updated_at":"2025-12-15T23:22:51.477786-08:00","closed_at":"2025-12-15T23:22:51.477786-08:00","close_reason":"Overseer role documented in docs/architecture.md"} {"id":"gt-17r","title":"Doctor check: Zombie session cleanup","description":"Detect and clean up zombie tmux sessions via gt doctor.\n\n## Problem\n\nZombie sessions occur when:\n- Agent crashes without cleanup\n- gt kill fails mid-operation\n- System restart leaves orphan sessions\n- Session naming collision\n\n## Checks\n\n### ZombieSessionCheck\n- List all tmux sessions matching gt-* pattern\n- Cross-reference with known polecats\n- Flag sessions with no corresponding polecat state\n- Flag sessions for removed polecats\n- Check session age vs polecat creation time\n\n### Detection Criteria\n- Session exists but polecat directory doesn't\n- Session name doesn't match any registered polecat\n- Polecat state=idle but session running\n- Multiple sessions for same polecat\n\n## Output\n\n```\n[WARN] Zombie tmux sessions detected:\n - gt-wyvern-OldPolecat (polecat removed)\n - gt-beads-Unknown (no matching polecat)\n - gt-wyvern-Toast (duplicate session)\n\n Run 'gt doctor --fix' to clean up\n```\n\n## Auto-Fix (--fix flag)\n\n- Kill orphan tmux sessions\n- Update polecat state to match reality\n- Log all cleanup actions\n\n## Safety\n\n- Never kill sessions where polecat state=working\n- Prompt before killing if --fix used without --force\n- Create audit log of killed sessions","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T23:18:01.446702-08:00","updated_at":"2025-12-15T23:18:39.517644-08:00","dependencies":[{"issue_id":"gt-17r","depends_on_id":"gt-f9x.4","type":"blocks","created_at":"2025-12-15T23:19:05.66301-08:00","created_by":"daemon"}]} {"id":"gt-1le","title":"town handoff command (optional)","description":"CLI commands for session handoff workflow (optional convenience).\n\n## Commands\n\n### gt handoff\nGenerate handoff interactively.\n```\ngt handoff [--send]\n```\n- Collects current state (status, inbox, beads)\n- Prompts for additional notes\n- --send: Mail to self and exit\n\n### gt resume\nCheck for and display pending handoff.\n```\ngt resume\n```\n- Checks inbox for handoff message\n- Displays formatted handoff if found\n- Suggests next actions\n\n## Implementation\n\nThese are convenience wrappers. The same workflow can be done manually:\n```bash\n# Manual handoff\ntown status \u003e /tmp/handoff\ntown inbox \u003e\u003e /tmp/handoff\nbd ready \u003e\u003e /tmp/handoff\n# Edit and send\ntown mail send mayor/ -s \"Session Handoff\" -f /tmp/handoff\n```\n\n## Priority\n\nP2 - Optional. Manual workflow works fine. Nice to have for UX.\n\n## Notes\n\nPart of session cycling workflow designed in gt-u82.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-15T20:15:31.954724-08:00","updated_at":"2025-12-15T23:17:23.967562-08:00","dependencies":[{"issue_id":"gt-1le","depends_on_id":"gt-u82","type":"blocks","created_at":"2025-12-15T20:15:39.647043-08:00","created_by":"daemon"}]} +{"id":"gt-2bz","title":"Swarm learning: Refinery merge queue automation","description":"Manually merging 15 polecat branches was painful and error-prone. Refinery should automate: detect completed work, run tests, merge to main, handle conflicts. This is core Refinery value prop.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-16T01:21:51.137974-08:00","updated_at":"2025-12-16T01:51:40.603737-08:00","closed_at":"2025-12-16T01:51:40.603737-08:00","close_reason":"Addressed by gt-kmn.4 (Refinery semantic merge processing loop) and architecture.md Key Decision #12 which enables Refinery session cycling. Refinery merge queue automation is core to the swarm design."} +{"id":"gt-2c1","title":"Swarm learning: Spawn should auto-notify polecats","description":"town spawn assigns issues but doesn't notify polecats. Required separate 'town session send' to inject prompts. This should be one atomic operation - spawn assigns AND pokes the polecat to start working.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-16T01:21:47.223608-08:00","updated_at":"2025-12-16T01:27:48.746346-08:00","closed_at":"2025-12-16T01:27:48.746346-08:00","close_reason":"GGT spec already addresses this. gt-u1j.19 (spawn command) includes 'Inject initial context' as step 5, which pokes polecats to start working."} {"id":"gt-35s","title":"Architecture: beads config and direct landing docs","description":"Added to architecture.md:\n- Beads multi-agent configuration table (daemon, worktree, sync-branch)\n- ASCII directory layout for non-mermaid rendering\n- Direct landing workflow (bypass merge queue)\n- Design decisions 9 and 10 for direct landing and daemon awareness\n- CLI commands for gt land","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-16T00:29:52.395906-08:00","updated_at":"2025-12-16T00:29:59.188921-08:00","closed_at":"2025-12-16T00:29:59.188921-08:00","close_reason":"Documented in architecture.md"} {"id":"gt-35x","title":"Plugin: plan-oracle (work decomposition)","description":"Plugin that helps decompose epics/issues into sub-tasks. Analyzes scope, identifies dependencies, estimates complexity for parallelization, creates beads for sub-tasks with dependency links.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-15T22:53:05.772986-08:00","updated_at":"2025-12-15T23:17:06.423894-08:00","dependencies":[{"issue_id":"gt-35x","depends_on_id":"gt-axz","type":"blocks","created_at":"2025-12-15T22:53:17.587726-08:00","created_by":"daemon"}]} {"id":"gt-4my","title":"Doctor check: Swarm health and stuck detection","description":"Detect and report stuck swarms via gt doctor.\n\n## Checks\n\n### SwarmHealthCheck\n- List all active swarms (polecats with state=working)\n- Check last activity timestamp for each\n- Flag as potentially stuck if no progress for configurable threshold (default: 30 min)\n- Check if Witness is running for the rig\n- Verify Witness last heartbeat time\n\n### Stuck Detection Criteria\n- Polecat state=working but session not running\n- Polecat state=working but output unchanged for threshold\n- Witness not responding to health checks\n- Multiple polecats in same rig all stuck\n\n## Output\n\n```\n[WARN] Swarm in rig 'wyvern' may be stuck:\n - Toast: working for 45m, no recent output\n - Capable: working for 52m, session not found\n - Witness: last heartbeat 20m ago\n \n Suggestions:\n - gt witness status wyvern\n - gt capture wyvern/Toast 50\n - gt stop --rig wyvern (kill all)\n```\n\n## Auto-Fix\n\nCannot auto-fix stuck swarms (risk of data loss), but can:\n- Restart Witness daemon if crashed\n- Send warning mail to Mayor","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T23:17:59.265062-08:00","updated_at":"2025-12-15T23:18:18.371962-08:00","dependencies":[{"issue_id":"gt-4my","depends_on_id":"gt-f9x.4","type":"blocks","created_at":"2025-12-15T23:19:05.565606-08:00","created_by":"daemon"}]} +{"id":"gt-59p","title":"Design GGT prompt architecture","description":"Audit PGT prompts and design canonical prompt system for GGT. Create docs/prompts.md with inventory, gap analysis, and Witness prompt design.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-16T00:46:16.916031-08:00","updated_at":"2025-12-16T00:47:38.105395-08:00","closed_at":"2025-12-16T00:47:38.105395-08:00","close_reason":"Created docs/prompts.md with full PGT inventory, gap analysis, GGT architecture, and Witness prompt design"} {"id":"gt-61o","title":"Review and audit all GGT beads","description":"Thorough review of all filed beads in gastown GGT repo. Check for: consistency, completeness, correct dependencies, accurate descriptions, proper prioritization. Ensure beads are self-contained and dont rely on external docs.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T20:24:07.152386-08:00","updated_at":"2025-12-15T21:23:58.255447-08:00","closed_at":"2025-12-15T21:23:58.255447-08:00","close_reason":"Audit complete: fixed 4 stale doc refs, 1 arch inconsistency, enriched 25+ sparse descriptions"} {"id":"gt-82y","title":"Design: Swarm shutdown and worker cleanup","description":"Design for graceful swarm shutdown, worker cleanup, and session cycling.\n\n## Key Decisions\n\n1. Pre-kill verification uses model intelligence (not framework rules)\n2. Witness can request restart when context filling (mail self, exit)\n3. Mayor NOT involved in per-worker cleanup (Witness responsibility)\n4. Clear responsibility boundaries between Mayor/Witness/Polecat\n\n## Subtasks (implementation)\n\n- gt-sd6: Polecat decommission checklist prompting\n- gt-f8v: Witness pre-kill verification protocol\n- gt-eu9: Witness session cycling and handoff\n- gt-gl2: Mayor vs Witness cleanup responsibilities\n\n**Design complete.** Each subtask has full specification in its description.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-15T19:47:44.936374-08:00","updated_at":"2025-12-15T20:49:22.849598-08:00","closed_at":"2025-12-15T20:12:05.441911-08:00","close_reason":"Design complete in docs/swarm-shutdown-design.md. Subtasks remain open for implementation."} {"id":"gt-8dv","title":"CLI: plugin commands (list, status)","description":"Add gt plugins \u003crig\u003e to list plugins and gt plugin status \u003cname\u003e to check plugin state. Simple directory scan of \u003crig\u003e/plugins/.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-15T22:53:02.694926-08:00","updated_at":"2025-12-15T23:17:06.594328-08:00","dependencies":[{"issue_id":"gt-8dv","depends_on_id":"gt-axz","type":"blocks","created_at":"2025-12-15T22:53:17.413809-08:00","created_by":"daemon"}]} @@ -15,6 +19,7 @@ {"id":"gt-b1g","title":"MVP Cutover: GGT replaces PGT for swarming","description":"When this is closed, stop using town and start using gt.\n\n## Acceptance Criteria\n\n1. gt spawn assigns issue to polecat and starts session\n2. gt session manages tmux lifecycle \n3. gt send / gt inbox work for mail\n4. gt swarm create/status/list work\n5. Refinery processes merge queue with semantic merges\n6. Integration branches created and landed correctly\n7. gt stop --all halts all sessions\n8. One successful test swarm completed end-to-end\n\n## What Must Work\n\n- Spawn polecat with issue assignment\n- Session start/stop/attach\n- Mail send/inbox/read\n- Swarm create with tasks and workers\n- Refinery merge loop (semantic)\n- Integration branch → main landing\n- Witness cleanup protocol\n- Emergency stop\n\n## What Can Be Deferred\n\n- Doctor checks (use PGT)\n- TUI dashboard\n- Plugin system\n- Federation\n- Ephemeral rigs\n- Detailed swarm reports\n\n## Test Plan\n\n1. Create swarm with 2 polecats, 2 tasks\n2. Verify polecats get assigned and sessions start\n3. Simulate task completion\n4. Verify Refinery merges to integration\n5. Verify landing to main\n6. Verify cleanup\n\n## Validation\n\nRun one real swarm implementing GGT issues using GGT.","status":"open","priority":0,"issue_type":"epic","created_at":"2025-12-16T00:11:09.148751-08:00","updated_at":"2025-12-16T00:11:09.148751-08:00","dependencies":[{"issue_id":"gt-b1g","depends_on_id":"gt-u1j.19","type":"blocks","created_at":"2025-12-16T00:11:36.196292-08:00","created_by":"daemon"},{"issue_id":"gt-b1g","depends_on_id":"gt-kmn.4","type":"blocks","created_at":"2025-12-16T00:11:36.273483-08:00","created_by":"daemon"},{"issue_id":"gt-b1g","depends_on_id":"gt-kmn.6","type":"blocks","created_at":"2025-12-16T00:11:36.351097-08:00","created_by":"daemon"},{"issue_id":"gt-b1g","depends_on_id":"gt-kmn.7","type":"blocks","created_at":"2025-12-16T00:11:36.431641-08:00","created_by":"daemon"},{"issue_id":"gt-b1g","depends_on_id":"gt-u1j.22","type":"blocks","created_at":"2025-12-16T00:11:36.511124-08:00","created_by":"daemon"},{"issue_id":"gt-b1g","depends_on_id":"gt-ov2","type":"blocks","created_at":"2025-12-16T00:11:51.609649-08:00","created_by":"daemon"},{"issue_id":"gt-b1g","depends_on_id":"gt-rm3","type":"blocks","created_at":"2025-12-16T00:11:51.69062-08:00","created_by":"daemon"}]} {"id":"gt-cjb","title":"Witness updates: Remove issue filing proxy","description":"Update Witness prompting to remove issue filing proxy, since polecats now have direct beads access.\n\n## Remove from Witness Prompting\n\nThe following is NO LONGER Witness responsibility:\n- Processing polecat 'file issue' mail requests\n- Creating issues on behalf of polecats\n- Forwarding issue creation requests\n\n## Add: Legacy Request Handling\n\nIf Witness receives an old-style 'please file issue' request:\n\n1. Respond with update:\n town inject \u003cpolecat\u003e \"UPDATE: You have direct beads access now. Use bd create to file issues yourself.\"\n\n2. Do not file the issue - let the polecat learn the new workflow.\n\n## Keep in Witness Prompting\n\n- Monitoring polecat progress\n- Nudge protocol\n- Pre-kill verification\n- Session lifecycle management","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:47:19.921561-08:00","updated_at":"2025-12-15T20:48:36.020922-08:00","dependencies":[{"issue_id":"gt-cjb","depends_on_id":"gt-l3c","type":"blocks","created_at":"2025-12-15T19:47:35.896691-08:00","created_by":"daemon"}]} {"id":"gt-cr0","title":"Consolidate design docs into beads descriptions","description":"The markdown design docs (swarm-shutdown-design.md, polecat-beads-access-design.md, mayor-handoff-design.md) will decay. Extract key decisions and prompting templates into the beads descriptions themselves, then archive or remove the markdown files. Beads are the source of truth.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T20:24:05.45131-08:00","updated_at":"2025-12-15T20:51:52.083465-08:00","closed_at":"2025-12-15T20:51:52.083465-08:00","close_reason":"Consolidated: created docs/architecture.md, moved design content into bead descriptions, deleted 4 individual design docs"} +{"id":"gt-cxx","title":"Swarm learning: Witness needs automated context cycling","description":"Furiosa hit 2% context during swarm work. Witness role needs automated detection of low context and should trigger session cycling before agents get stuck. Add to Witness responsibilities in prompts.md.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-16T01:21:49.67756-08:00","updated_at":"2025-12-16T01:51:39.2553-08:00","closed_at":"2025-12-16T01:51:39.2553-08:00","close_reason":"Addressed by architecture.md Key Decision #12 (Agent Session Lifecycle). Daemon monitors agent health and restarts sessions after handoff. Witness self-cycling protocol documented in prompts.md."} {"id":"gt-d3d","title":"Design: Additional design issues (placeholder)","description":"Placeholder for additional design issues the user wants to raise and work through. Convert to specific subtasks as issues are identified.","status":"open","priority":4,"issue_type":"epic","created_at":"2025-12-15T20:24:12.601585-08:00","updated_at":"2025-12-15T23:17:32.467687-08:00"} {"id":"gt-e1y","title":"Worker prompting: Beads write access","description":"Add beads write access section to polecat AGENTS.md.template.\n\n## Beads Access Section for Prompting\n\n```markdown\n## Beads Access\n\nYou have **full beads access** - create, update, and close issues.\n\n### Quick Reference\n\n```bash\n# View work\nbd ready # Issues ready (no blockers)\nbd list # All open issues\nbd show \u003cid\u003e # Issue details\n\n# Create issues\nbd create --title=\"Fix bug\" --type=bug --priority=2\nbd create --title=\"Add feature\" --type=feature\n\n# Update issues\nbd update \u003cid\u003e --status=in_progress # Claim work\nbd close \u003cid\u003e # Mark complete\n\n# Sync (required before merge!)\nbd sync # Commit beads changes to git\n```\n\n### When to Create Issues\n\nCreate beads issues when you discover work that:\n- Is outside your current task scope\n- Would benefit from tracking\n- Should be done by someone else\n\n**Good examples**:\n```bash\nbd create --title=\"Race condition in auth\" --type=bug --priority=1\nbd create --title=\"Document API rate limits\" --type=task --priority=3\n```\n\n**Don't create for**:\n- Tiny fixes you can do in 2 minutes\n- Vague \"improvements\" with no scope\n- Work already tracked elsewhere\n\n### Beads Sync Protocol\n\n**CRITICAL**: Always sync beads before merging!\n\n```bash\nbd sync # Commits beads changes\ngit add .beads/\ngit commit -m \"beads: sync\"\n```\n\nIf you forget to sync, beads changes are lost when session ends.\n```\n\n## Implementation\n\nAdd to AGENTS.md.template polecat section.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:47:18.459363-08:00","updated_at":"2025-12-15T20:48:03.813068-08:00","dependencies":[{"issue_id":"gt-e1y","depends_on_id":"gt-l3c","type":"blocks","created_at":"2025-12-15T19:47:35.81183-08:00","created_by":"daemon"}]} {"id":"gt-eu9","title":"Witness session cycling and handoff","description":"Add session cycling and handoff protocol to Witness CLAUDE.md template.\n\n## Session Cycling Protocol\n\n```markdown\n## Session Cycling\n\nYour context will fill over long swarms. Proactively cycle when:\n- Running for many hours\n- Losing track of which workers you've checked\n- Responses getting slower\n- About to start complex operation\n\n### Handoff Protocol\n\n1. **Capture current state**:\n```bash\ntown list . # Worker states\ntown all beads # Pending verifications \ntown inbox # Unprocessed messages\n```\n\n2. **Compose handoff note**:\n```\n[HANDOFF_TYPE]: witness_cycle\n[TIMESTAMP]: \u003cnow\u003e\n[RIG]: \u003crig\u003e\n\n## Active Workers\n\u003clist workers and status\u003e\n\n## Pending Verifications\n\u003cworkers signaled done but not verified\u003e\n\n## Recent Actions\n\u003clast 3-5 actions\u003e\n\n## Warnings/Notes\n\u003canything next session should know\u003e\n\n## Next Steps\n\u003cwhat should happen next\u003e\n```\n\n3. **Send handoff**:\n```bash\ntown mail send \u003crig\u003e/witness -s \"Session Handoff\" -m \"\u003cnote\u003e\"\n```\n\n4. **Exit cleanly**: End session, daemon spawns fresh one.\n\n### On Fresh Session Start\n\n1. Check for handoff: `town inbox | grep \"Session Handoff\"`\n2. If found, read it and resume from handoff state\n3. If not found, do full status check\n```\n\n## Implementation\n\nAdd to WITNESS_CLAUDE.md template.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:48:55.484911-08:00","updated_at":"2025-12-15T20:47:30.768506-08:00","dependencies":[{"issue_id":"gt-eu9","depends_on_id":"gt-82y","type":"blocks","created_at":"2025-12-15T19:49:05.846443-08:00","created_by":"daemon"}]} @@ -34,13 +39,13 @@ {"id":"gt-gl2","title":"Clarify Mayor vs Witness cleanup responsibilities","description":"Document the cleanup authority model: Witness owns ALL per-worker cleanup, Mayor never involved.\n\n## The Rule\n\n**Witness handles ALL per-worker cleanup. Mayor is never involved.**\n\n## Why This Matters\n\n1. Separation of concerns: Mayor strategic, Witness operational\n2. Reduced coordination overhead: No back-and-forth for routine cleanup\n3. Faster shutdown: Witness kills workers immediately upon verification\n4. Cleaner escalation: Mayor only hears about problems\n\n## What Witness Handles\n\n- Verifying worker git state before kill\n- Nudging workers to fix dirty state\n- Killing worker sessions\n- Updating worker state (sleep/wake)\n- Logging verification results\n\n## What Mayor Handles\n\n- Receiving swarm complete notifications\n- Deciding whether to start new swarms\n- Handling escalations (stuck workers after 3 retries)\n- Cross-rig coordination\n\n## Escalation Path\n\nWorker stuck -\u003e Witness nudges (up to 3x) -\u003e Witness escalates to Mayor -\u003e Mayor decides: force kill, reassign, or human\n\n## Anti-Patterns\n\nDO NOT: Mayor asks Witness if worker X is clean\nDO: Witness reports swarm complete, all workers verified\n\nDO NOT: Mayor kills worker sessions directly\nDO: Mayor tells Witness to abort swarm, Witness handles cleanup\n\nDO NOT: Workers report done to Mayor\nDO: Workers report to Witness, Witness aggregates and reports up","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:48:56.678724-08:00","updated_at":"2025-12-15T20:48:12.068964-08:00","dependencies":[{"issue_id":"gt-gl2","depends_on_id":"gt-82y","type":"blocks","created_at":"2025-12-15T19:49:05.929877-08:00","created_by":"daemon"}]} {"id":"gt-iib","title":"Architecture: Decentralized rig structure with per-rig agents","description":"## Decision\n\nAdopt decentralized architecture where each rig contains all its agents (mayor/, witness/, refinery/, polecats/) rather than centralizing mayor clones at town level.\n\n## Town Level Structure\n\n```\n~/ai/ # Town root\n├── config/ # Town config (VISIBLE, not hidden)\n│ ├── town.json # {\"type\": \"town\"}\n│ ├── rigs.json # Registry of managed rigs\n│ └── federation.json # Wasteland config (future)\n│\n├── mayor/ # Mayor's HOME at town level\n│ ├── CLAUDE.md\n│ ├── mail/inbox.jsonl\n│ └── state.json\n│\n└── \u003crigs\u003e/ # Managed projects\n```\n\n## Rig Level Structure (e.g., wyvern)\n\n```\nwyvern/ # Rig = clone of project repo\n├── .git/info/exclude # Gas Town adds: polecats/ refinery/ witness/ mayor/\n├── .beads/ # Beads (if project uses it)\n├── [project files] # Clean project code on main\n│\n├── polecats/ # Worker clones\n│ └── \u003cname\u003e/ # Each is a git clone\n│\n├── refinery/\n│ ├── rig/ # Refinery's clone\n│ ├── state.json\n│ └── mail/inbox.jsonl\n│\n├── witness/ # NEW: Per-rig pit boss\n│ ├── rig/ # Witness's clone\n│ ├── state.json\n│ └── mail/inbox.jsonl\n│\n└── mayor/\n ├── rig/ # Mayor's clone for this rig\n └── state.json\n```\n\n## Key Decisions\n\n1. **Visible config dir**: `config/` not `.gastown/` (models don't find hidden dirs)\n2. **Witness per-rig**: Each rig has its own Witness (pit boss) with its own clone\n3. **Mayor decentralized**: Mayor's clones live IN each rig at `\u003crig\u003e/mayor/rig/`\n4. **Minimal invasiveness**: Only `.git/info/exclude` modified, no commits to project\n5. **Clone subdir name**: Keep `rig/` for consistency (refinery/rig/, witness/rig/, mayor/rig/)\n\n## Role Detection\n\n- Town root or mayor/ → Mayor (town level)\n- Rig root → Mayor (canonical main)\n- \u003crig\u003e/mayor/rig/ → Mayor (rig-specific)\n- \u003crig\u003e/refinery/rig/ → Refinery\n- \u003crig\u003e/witness/rig/ → Witness\n- \u003crig\u003e/polecats/\u003cname\u003e/ → Polecat\n\n## Migration from PGT\n\n- `mayor/rigs/\u003crig\u003e/` → `\u003crig\u003e/mayor/rig/`\n- `\u003crig\u003e/town/` → eliminated (rig root IS the clone)\n- Add `witness/` to each rig","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-15T19:21:19.913928-08:00","updated_at":"2025-12-15T19:21:40.461186-08:00","closed_at":"2025-12-15T19:21:40.461186-08:00","close_reason":"Design decision recorded","dependencies":[{"issue_id":"gt-iib","depends_on_id":"gt-u1j","type":"blocks","created_at":"2025-12-15T19:21:40.374551-08:00","created_by":"daemon"}]} {"id":"gt-j87","title":"Design: Swarm simulation and validation","description":"Validate GGT designs through simulation before implementation.\n\n## Validation Approaches\n\n### 1. Dry-Run Simulation (Recommended First)\nMayor walks through scenarios mentally/on paper:\n- \"If polecat Toast signals done with dirty git state, what happens?\"\n- \"If Witness context fills mid-verification, what state is lost?\"\n- \"If two polecats try to close same issue, what happens?\"\n\nCreate beads for any gaps discovered.\n\n### 2. Real Swarms in gastown-py\nUse Python Gas Town to stress-test assumptions:\n- Run actual swarms on test repos\n- Observe edge cases in practice\n- Document issues found\n\n### 3. Edge Case Analysis\nSystematic review of failure modes:\n- Agent crashes mid-operation\n- Network failures during sync\n- Concurrent access to shared state\n- Context limits hit at bad times\n\n## Key Scenarios to Validate\n\n- [ ] Witness session cycling (state preservation)\n- [ ] Polecat decommission with dirty state\n- [ ] Merge conflicts in queue\n- [ ] Beads sync conflicts between workers\n- [ ] Escalation path (stuck worker -\u003e Mayor)\n- [ ] Cross-rig communication\n- [ ] Federation mail routing (future)\n\n## Success Criteria\n\n- No data loss scenarios identified\n- Clear recovery paths for all failure modes\n- Edge cases either handled or documented as limitations\n- Design improves as model cognition improves\n\n## Output\n\nFor each scenario validated:\n1. Document in relevant bead if issue found\n2. Create new beads for missing functionality\n3. Update architecture.md if design changes","status":"open","priority":1,"issue_type":"epic","created_at":"2025-12-15T20:24:11.251841-08:00","updated_at":"2025-12-15T21:23:44.79455-08:00"} -{"id":"gt-kmn","title":"Swarm System: Atomic swarm unit with lifecycle management","description":"Implement swarm as a first-class atomic unit in GGT.\n\n## Overview\n\nA Swarm is a coordinated group of polecats working on related tasks, with:\n- Shared base commit (all workers branch from same point)\n- Integration branch (work merges here before main)\n- Lifecycle state machine (active → merging → landed)\n- Group cleanup (all workers handled together)\n\n## Key Components\n\n1. **Swarm types**: Swarm, SwarmTask, SwarmState, SwarmManifest\n2. **Swarm storage**: `\u003crig\u003e/swarms/\u003cid\u003e/` with manifest.json, state.json, events.jsonl\n3. **Integration branches**: `integration/\u003cswarm-id\u003e`\n4. **Worker branches**: `\u003cswarm-id\u003e/\u003cpolecat-name\u003e`\n5. **Beads naming convention**: swarm-started, swarm-task-merged, swarm-landed\n\n## State Machine\n\ncreated → active → merging → landed\n ↘ failed/cancelled\n\n## References\n\n- PGT: swarm/manager.py, swarm/landing.py, ephemeral.py\n- Architecture: docs/architecture.md","status":"open","priority":0,"issue_type":"epic","created_at":"2025-12-16T00:08:15.339127-08:00","updated_at":"2025-12-16T00:08:15.339127-08:00"} -{"id":"gt-kmn.1","title":"Swarm package: Swarm, SwarmTask, SwarmState types","description":"Port swarm types from PGT to Go.\n\n## Types\n\n```go\ntype Swarm struct {\n ID string // sw-1, sw-2, etc.\n RigID string // rig this swarm operates in\n BaseCommit string // SHA all workers branch from\n IntegrationBranch string // integration/\u003cswarm-id\u003e\n Title string\n Description string\n Tasks []SwarmTask\n Workers []string // polecat names\n Status SwarmStatus // active, merging, landed, failed, cancelled\n CreatedAt time.Time\n CreatedBy string\n StartedAt *time.Time\n MergeStartedAt *time.Time\n LandedAt *time.Time\n}\n\ntype SwarmTask struct {\n IssueID string // beads issue ID\n Title string\n Assignee string // polecat name\n Status TaskStatus // pending, in_progress, completed, merged, failed\n StartedAt *time.Time\n CompletedAt *time.Time\n MergedAt *time.Time\n}\n\ntype SwarmStatus string\nconst (\n SwarmActive SwarmStatus = \"active\"\n SwarmMerging SwarmStatus = \"merging\"\n SwarmLanded SwarmStatus = \"landed\"\n SwarmFailed SwarmStatus = \"failed\"\n SwarmCancelled SwarmStatus = \"cancelled\"\n)\n```\n\n## File Storage\n\n- `\u003crig\u003e/swarms/\u003cid\u003e/manifest.json` - immutable config\n- `\u003crig\u003e/swarms/\u003cid\u003e/state.json` - mutable progress\n- `\u003crig\u003e/swarms/\u003cid\u003e/events.jsonl` - audit log\n\n## Reference\n\nPGT: swarm/manager.py (SwarmManifest, SwarmState, SwarmTask)","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-16T00:08:30.364047-08:00","updated_at":"2025-12-16T00:08:30.364047-08:00","dependencies":[{"issue_id":"gt-kmn.1","depends_on_id":"gt-kmn","type":"parent-child","created_at":"2025-12-16T00:08:30.364431-08:00","created_by":"daemon"},{"issue_id":"gt-kmn.1","depends_on_id":"gt-u1j.1","type":"blocks","created_at":"2025-12-16T00:11:20.646487-08:00","created_by":"daemon"}]} +{"id":"gt-kmn","title":"Swarm System: Atomic swarm unit with lifecycle management","description":"Implement swarm as a first-class atomic unit in GGT.\n\n## Overview\n\nA Swarm is a coordinated group of polecats working on related tasks, with:\n- Shared base commit (all workers branch from same point)\n- Integration branch (work merges here before main)\n- Lifecycle state machine (active → merging → landed)\n- Group cleanup (all workers handled together)\n\n## Key Design Change: Beads as State\n\nSwarm state is encoded in beads epics/issues, NOT a separate database or manifest files:\n- Swarm = parent epic with child task issues\n- Dependencies encode ordering (multi-wave emerges automatically)\n- Status tracks progress (open → in_progress → closed)\n- `bd ready --parent \u003cepic\u003e` finds next work\n- Swarm complete when all children closed\n\nSee architecture.md Key Decision #11: Beads as Swarm State.\n\n## State Machine\n\ncreated → active → merging → landed\n ↘ failed/cancelled\n\n## References\n\n- Architecture: docs/architecture.md (sections 11, 12, 13, Multi-Wave Swarms)\n- PGT: swarm/manager.py, swarm/landing.py (for behavioral reference)","status":"open","priority":0,"issue_type":"epic","created_at":"2025-12-16T00:08:15.339127-08:00","updated_at":"2025-12-16T01:50:54.956119-08:00"} +{"id":"gt-kmn.1","title":"Swarm package: Swarm, SwarmTask, SwarmState types","description":"Define core swarm types.\n\n## Types (in `internal/swarm/`)\n\n```go\n// SwarmState represents swarm lifecycle\ntype SwarmState string\nconst (\n SwarmCreated SwarmState = \"created\"\n SwarmActive SwarmState = \"active\"\n SwarmMerging SwarmState = \"merging\"\n SwarmLanded SwarmState = \"landed\"\n SwarmFailed SwarmState = \"failed\"\n SwarmCancelled SwarmState = \"cancelled\"\n)\n\n// Swarm references a beads epic that tracks swarm work\ntype Swarm struct {\n ID string // matches beads epic ID\n RigName string\n EpicID string // beads epic tracking this swarm\n BaseCommit string // git SHA all workers branch from\n Integration string // integration branch name\n State SwarmState\n CreatedAt time.Time\n Workers []string // polecat names assigned\n}\n\n// SwarmTask represents a single task in the swarm (maps to beads issue)\ntype SwarmTask struct {\n IssueID string // beads issue ID\n Assignee string // polecat name\n Branch string // worker branch name\n State string // mirrors beads status\n}\n```\n\n## Note\n\nSwarm state is primarily stored IN beads. These types are in-memory representations for the SwarmManager to work with. No separate manifest.json files.","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-16T00:08:30.364047-08:00","updated_at":"2025-12-16T01:50:56.725325-08:00","dependencies":[{"issue_id":"gt-kmn.1","depends_on_id":"gt-kmn","type":"parent-child","created_at":"2025-12-16T00:08:30.364431-08:00","created_by":"daemon"},{"issue_id":"gt-kmn.1","depends_on_id":"gt-u1j.1","type":"blocks","created_at":"2025-12-16T00:11:20.646487-08:00","created_by":"daemon"}]} {"id":"gt-kmn.10","title":"Swarm landing report generation","description":"Generate reports on swarm completion.\n\n## Report Contents\n\n- Swarm metadata (ID, title, created by, duration)\n- Task summary (completed/failed counts)\n- Per-task details (issue, assignee, time taken)\n- Git stats (commits merged, lines changed)\n- Cleanup stats (branches deleted, clones removed)\n\n## Output Locations\n\n1. `\u003crig\u003e/swarms/\u003cid\u003e/report.md` - saved to swarm directory\n2. Mail to Mayor - summary with link to full report\n3. Bead body - included in swarm-landed bead\n\n## Format\n\nMarkdown with sections:\n- Summary\n- Tasks\n- Workers\n- Timeline\n- Cleanup\n\n## Reference\n\nPGT: swarm/report.py","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-16T00:10:23.242931-08:00","updated_at":"2025-12-16T00:10:23.242931-08:00","dependencies":[{"issue_id":"gt-kmn.10","depends_on_id":"gt-kmn","type":"parent-child","created_at":"2025-12-16T00:10:23.243287-08:00","created_by":"daemon"}]} {"id":"gt-kmn.11","title":"Daemon heartbeat swarm poking","description":"Daemon periodic checks for swarm progress.\n\n## Heartbeat Actions\n\nEvery N seconds (configurable):\n\n1. Check Witness health per rig\n - Poke if witness needs to nudge polecats\n \n2. Check Refinery queue per rig\n - Poke if pending work in queue\n \n3. Check swarm completion\n - If all tasks merged but not landed, poke Refinery\n\n## Eventually Convergent\n\nMultiple signals reinforce state:\n- Polecat signals done → Witness notices → pokes Refinery\n- Daemon heartbeat → checks queue → pokes Refinery\n- Beads status → queryable by any agent\n\nEven if one signal missed, system converges.\n\n## Interface\n\n```go\nfunc (d *Daemon) HeartbeatLoop() {\n for {\n for _, rig := range d.rigs {\n d.CheckWitness(rig)\n d.CheckRefinery(rig)\n d.CheckSwarms(rig)\n }\n time.Sleep(d.config.HeartbeatInterval)\n }\n}\n```\n\n## Notifications\n\nUse mail with low priority for heartbeat pokes.\nAgents can ignore if already processing.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-16T00:10:25.169417-08:00","updated_at":"2025-12-16T00:10:25.169417-08:00","dependencies":[{"issue_id":"gt-kmn.11","depends_on_id":"gt-kmn","type":"parent-child","created_at":"2025-12-16T00:10:25.169767-08:00","created_by":"daemon"}]} {"id":"gt-kmn.12","title":"Ephemeral rig support for ad-hoc swarms","description":"Support for temporary worker rigs without pre-existing polecats.\n\n## Use Case\n\nAd-hoc swarms where you want temporary workers:\n- gt swarm init --git-url \u003curl\u003e --workers 3\n- Creates rig-\u003cid\u003e with 3 clones\n- Workers do their thing\n- Swarm lands, clones destroyed\n\n## Interface\n\n```go\ntype EphemeralRig struct {\n ID string\n GitURL string\n BaseCommit string\n Workers []string\n IntegrationBranch string\n SwarmID string // associated swarm\n CreatedAt time.Time\n}\n\nfunc InitEphemeralRig(gitURL string, numWorkers int) (*EphemeralRig, error)\nfunc (r *EphemeralRig) AddWorker(name string) error\nfunc (r *EphemeralRig) Destroy(force bool) error\n```\n\n## Directory Structure\n\n```\n\u003crig\u003e/ephemeral/\n└── rig-a3f7/\n ├── rig.json\n ├── Alice/ # clone\n ├── Bob/ # clone\n └── Carol/ # clone\n```\n\n## Reference\n\nPGT: ephemeral.py (EphemeralRig, EphemeralRigManager)","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T00:10:44.915982-08:00","updated_at":"2025-12-16T00:10:44.915982-08:00","dependencies":[{"issue_id":"gt-kmn.12","depends_on_id":"gt-kmn","type":"parent-child","created_at":"2025-12-16T00:10:44.916346-08:00","created_by":"daemon"}]} {"id":"gt-kmn.13","title":"Plugin: swarm-oracle (pre-dispatch analysis)","description":"Plugin for pre-swarm task analysis and decomposition.\n\n## Purpose\n\nBefore dispatching a swarm, ask swarm-oracle to:\n- Validate task breakdown\n- Identify parallelization opportunities\n- Predict conflicts between tasks\n- Suggest worker count\n\n## Hook Point\n\nMayor asks swarm-oracle before gt swarm create.\n\n## Interface\n\nInput (via mail):\n- List of proposed tasks\n- Rig context (current state of codebase)\n\nOutput (via mail + bead):\n- Recommended task groupings\n- Dependency suggestions\n- Risk assessment\n- Optimal worker count\n\n## Structure\n\n```\n\u003crig\u003e/plugins/swarm-oracle/\n├── CLAUDE.md # Analysis prompts\n├── mail/inbox.jsonl\n└── state.json\n```\n\nUses existing plugin-as-agent architecture.","status":"open","priority":3,"issue_type":"task","created_at":"2025-12-16T00:10:46.139004-08:00","updated_at":"2025-12-16T00:10:46.139004-08:00","dependencies":[{"issue_id":"gt-kmn.13","depends_on_id":"gt-kmn","type":"parent-child","created_at":"2025-12-16T00:10:46.139369-08:00","created_by":"daemon"}]} -{"id":"gt-kmn.2","title":"SwarmManager: create, start, update, query operations","description":"Implement SwarmManager for swarm lifecycle operations.\n\n## Interface\n\n```go\ntype SwarmManager struct {\n rig *Rig\n}\n\nfunc NewSwarmManager(rig *Rig) *SwarmManager\n\n// Lifecycle\nfunc (m *SwarmManager) Create(spec SwarmSpec) (*Swarm, error)\nfunc (m *SwarmManager) Start(swarmID string) error\nfunc (m *SwarmManager) Cancel(swarmID string, reason string) error\n\n// Task updates\nfunc (m *SwarmManager) UpdateTaskStatus(swarmID, taskID string, status TaskStatus) error\nfunc (m *SwarmManager) AssignTask(swarmID, taskID, polecat string) error\n\n// Queries\nfunc (m *SwarmManager) Get(swarmID string) (*Swarm, error)\nfunc (m *SwarmManager) List(filter SwarmFilter) ([]*Swarm, error)\nfunc (m *SwarmManager) GetActive() ([]*Swarm, error)\n\n// State machine\nfunc (m *SwarmManager) TransitionTo(swarmID string, status SwarmStatus) error\n```\n\n## SwarmSpec\n\n```go\ntype SwarmSpec struct {\n Title string\n Description string\n Tasks []TaskSpec // issue IDs + titles\n Workers []string // polecat names (or count to auto-assign)\n CreatedBy string\n}\n```\n\n## File Locking\n\nUse flock for atomic state updates (see PGT manager.py).\n\n## Event Logging\n\nAppend to events.jsonl on every state change.","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-16T00:09:04.814385-08:00","updated_at":"2025-12-16T00:09:04.814385-08:00","dependencies":[{"issue_id":"gt-kmn.2","depends_on_id":"gt-kmn","type":"parent-child","created_at":"2025-12-16T00:09:04.814876-08:00","created_by":"daemon"},{"issue_id":"gt-kmn.2","depends_on_id":"gt-kmn.1","type":"blocks","created_at":"2025-12-16T00:11:20.744039-08:00","created_by":"daemon"}]} +{"id":"gt-kmn.2","title":"SwarmManager: create, start, update, query operations","description":"SwarmManager operations for creating and managing swarms.\n\n## Interface\n\n```go\ntype SwarmManager struct {\n rig *Rig\n beads *BeadsWrapper // shells out to bd CLI\n}\n\nfunc NewSwarmManager(rig *Rig) *SwarmManager\n\n// Lifecycle\nfunc (m *SwarmManager) Create(epicID string, workers []string) (*Swarm, error)\nfunc (m *SwarmManager) Start(swarmID string) error\nfunc (m *SwarmManager) UpdateState(swarmID string, state SwarmState) error\nfunc (m *SwarmManager) Cancel(swarmID string, reason string) error\n\n// Queries (delegate to beads)\nfunc (m *SwarmManager) GetSwarm(id string) (*Swarm, error)\nfunc (m *SwarmManager) GetReadyTasks(swarmID string) ([]SwarmTask, error)\nfunc (m *SwarmManager) GetActiveTasks(swarmID string) ([]SwarmTask, error)\nfunc (m *SwarmManager) IsComplete(swarmID string) (bool, error)\n```\n\n## Implementation Notes\n\n- `GetReadyTasks` wraps `bd ready --parent \u003cepicID\u003e`\n- `IsComplete` checks if all child issues are closed\n- State transitions update the epic's description or a tag field\n- No separate manifest files - beads IS the source of truth","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-16T00:09:04.814385-08:00","updated_at":"2025-12-16T01:50:59.051847-08:00","dependencies":[{"issue_id":"gt-kmn.2","depends_on_id":"gt-kmn","type":"parent-child","created_at":"2025-12-16T00:09:04.814876-08:00","created_by":"daemon"},{"issue_id":"gt-kmn.2","depends_on_id":"gt-kmn.1","type":"blocks","created_at":"2025-12-16T00:11:20.744039-08:00","created_by":"daemon"}]} {"id":"gt-kmn.3","title":"Integration branch management for swarms","description":"Manage integration branches for swarm merging strategy.\n\n## Branch Naming\n\n- Integration branch: `integration/\u003cswarm-id\u003e` (e.g., integration/sw-1)\n- Worker branches: `\u003cswarm-id\u003e/\u003cpolecat\u003e` (e.g., sw-1/Toast)\n\n## Operations\n\n```go\n// Create integration branch at swarm start\nfunc (m *SwarmManager) CreateIntegrationBranch(swarmID string) error\n// - Creates from BaseCommit\n// - Pushes to origin\n\n// Merge worker branch to integration\nfunc (r *Refinery) MergeToIntegration(swarmID, workerBranch string) error\n// - Fetches worker branch\n// - Merges to integration/\u003cswarm-id\u003e\n// - Handles conflicts (semantic merge)\n\n// Land integration to main\nfunc (r *Refinery) LandToMain(swarmID string) error\n// - Merges integration/\u003cswarm-id\u003e to main\n// - Pushes to origin\n// - Triggers cleanup\n\n// Cleanup branches after landing\nfunc (m *SwarmManager) CleanupBranches(swarmID string) error\n// - Deletes integration/\u003cswarm-id\u003e (local + remote)\n// - Deletes all \u003cswarm-id\u003e/\u003cpolecat\u003e branches\n```\n\n## All Workers Same Base\n\nWhen swarm starts:\n1. Record current main HEAD as BaseCommit\n2. All polecats branch from BaseCommit\n3. Integration branch also starts at BaseCommit\n\nThis ensures clean merges within the swarm.\n\n## Reference\n\nPGT: ephemeral.py (create_integration_branch, merge_integration_to_main)","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-16T00:09:06.825718-08:00","updated_at":"2025-12-16T00:09:06.825718-08:00","dependencies":[{"issue_id":"gt-kmn.3","depends_on_id":"gt-kmn","type":"parent-child","created_at":"2025-12-16T00:09:06.82608-08:00","created_by":"daemon"},{"issue_id":"gt-kmn.3","depends_on_id":"gt-kmn.1","type":"blocks","created_at":"2025-12-16T00:11:20.848983-08:00","created_by":"daemon"},{"issue_id":"gt-kmn.3","depends_on_id":"gt-u1j.3","type":"blocks","created_at":"2025-12-16T00:11:20.943465-08:00","created_by":"daemon"}]} {"id":"gt-kmn.4","title":"Refinery semantic merge processing loop","description":"Implement the Refinery semantic merge loop for processing polecat work.\n\n## Overview\n\nThe Refinery is a fully empowered Claude Code agent that:\n1. Fetches polecat branches\n2. Merges to integration branch\n3. Resolves conflicts semantically (re-implements if needed)\n4. Runs tests\n5. Escalates only when truly stuck\n\n## Processing Loop\n\n1. Check queue for completed tasks (polecat done, not yet merged)\n2. For each task:\n - Fetch polecat branch\n - Attempt merge to integration/\u003cswarm-id\u003e\n - On conflict: semantic resolution (understand intent, re-implement)\n - Run tests if configured\n - On success: mark merged, file bead, notify witness\n - On failure: notify polecat (test fail) or escalate (stuck)\n3. When all tasks merged: land integration to main\n\n## Semantic Merge\n\nWhen git merge fails, Refinery:\n1. Reads polecat changes and beads issue\n2. Understands intent\n3. Re-implements on current integration branch\n4. Only escalates if truly blocked\n\n## Daemon Poking\n\nRefinery is poked by:\n- Daemon heartbeat (periodic)\n- Witness notification (polecat done)\n- Mayor request (check queue)\n\n## Dependencies\n\nNeeds: gt-u1j.6 (mail), gt-u1j.3 (git), gt-u1j.14 (merge queue)\n\n## Reference\n\nSee PGT ephemeral.py for branch operations.","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-16T00:09:19.536429-08:00","updated_at":"2025-12-16T00:09:19.536429-08:00","dependencies":[{"issue_id":"gt-kmn.4","depends_on_id":"gt-kmn","type":"parent-child","created_at":"2025-12-16T00:09:19.536808-08:00","created_by":"daemon"},{"issue_id":"gt-kmn.4","depends_on_id":"gt-kmn.3","type":"blocks","created_at":"2025-12-16T00:11:22.86454-08:00","created_by":"daemon"},{"issue_id":"gt-kmn.4","depends_on_id":"gt-u1j.6","type":"blocks","created_at":"2025-12-16T00:11:22.952967-08:00","created_by":"daemon"},{"issue_id":"gt-kmn.4","depends_on_id":"gt-u1j.3","type":"blocks","created_at":"2025-12-16T00:11:23.046741-08:00","created_by":"daemon"}]} {"id":"gt-kmn.5","title":"Swarm beads naming convention and auto-filing","description":"Beads naming convention for swarm lifecycle events.\n\n## Bead IDs\n\n- swarm-started:\u003cswarm-id\u003e # Filed when swarm begins\n- swarm-task-merged:\u003cswarm-id\u003e:\u003ctask-id\u003e # Filed per task merge\n- swarm-landed:\u003cswarm-id\u003e # Filed when merged to main\n- swarm-failed:\u003cswarm-id\u003e # Filed on unrecoverable failure\n\n## swarm-started Bead\n\nFiled by: Mayor/Refinery at swarm creation\nContains:\n- Swarm title and description\n- List of tasks (issue IDs)\n- List of workers (polecat names)\n- Base commit SHA\n\n## swarm-task-merged Bead\n\nFiled by: Refinery after each successful merge\nContains:\n- Task issue ID and title\n- Polecat name\n- Merge commit SHA\n- Test results summary\n\n## swarm-landed Bead\n\nFiled by: Refinery after landing to main\nContains:\n- Final merge commit SHA\n- Stats: tasks completed, time taken\n- List of all merged task beads\n- Integration branch name (now deleted)\n\n## swarm-failed Bead\n\nFiled by: Refinery on unrecoverable failure\nContains:\n- Failure reason\n- Tasks merged vs not merged\n- Recovery guidance\n\n## Why Beads (not just mail)\n\n- Persistent, queryable, synced to git\n- Other agents can check status without mail\n- Creates audit trail\n- Works when agents offline","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-16T00:09:46.930708-08:00","updated_at":"2025-12-16T00:09:46.930708-08:00","dependencies":[{"issue_id":"gt-kmn.5","depends_on_id":"gt-kmn","type":"parent-child","created_at":"2025-12-16T00:09:46.931086-08:00","created_by":"daemon"},{"issue_id":"gt-kmn.5","depends_on_id":"gt-kmn.1","type":"blocks","created_at":"2025-12-16T00:11:24.746439-08:00","created_by":"daemon"},{"issue_id":"gt-kmn.5","depends_on_id":"gt-u1j.13","type":"blocks","created_at":"2025-12-16T00:11:24.81726-08:00","created_by":"daemon"}]} @@ -49,6 +54,7 @@ {"id":"gt-kmn.8","title":"Git safety audit module","description":"Port git_audit.py safety checks to Go.\n\n## Purpose\n\nBefore destroying polecat clones, verify no code is at risk.\n\n## Checks\n\n1. Uncommitted changes (staged and unstaged)\n2. Unpushed commits\n3. Git stashes\n4. Local-only branches (not tracking remote)\n\n## Beads-Only Classification\n\nSome files are safe to discard:\n- .beads/*\n- .claude/settings.json\n\nChanges only affecting these = \"beads-only\" = safe to destroy.\n\n## Interface\n\n```go\ntype GitAuditResult struct {\n Polecat string\n Path string\n UncommittedFiles []string\n UncommittedIsBeadsOnly bool\n UnpushedCommits int\n Stashes []StashInfo\n StashesAreBeadsOnly bool\n LocalBranches []string\n Error error\n}\n\nfunc (r *GitAuditResult) HasCodeAtRisk() bool\n\nfunc AuditPolecat(name string, path string) *GitAuditResult\nfunc AuditPolecats(polecats []PolecatInfo) []*GitAuditResult\n```\n\n## Reference\n\nPGT: swarm/git_audit.py","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-16T00:10:19.52029-08:00","updated_at":"2025-12-16T00:10:19.52029-08:00","dependencies":[{"issue_id":"gt-kmn.8","depends_on_id":"gt-kmn","type":"parent-child","created_at":"2025-12-16T00:10:19.520646-08:00","created_by":"daemon"},{"issue_id":"gt-kmn.8","depends_on_id":"gt-u1j.3","type":"blocks","created_at":"2025-12-16T00:11:29.174184-08:00","created_by":"daemon"}]} {"id":"gt-kmn.9","title":"Work reconciliation module","description":"Port reconcile.py work verification to Go.\n\n## Purpose\n\nVerify assigned issues are completed before landing.\n\n## Interface\n\n```go\ntype ReconcileResult struct {\n CompletedIssues []IssueInfo\n IncompleteIssues []IssueInfo\n AllComplete bool\n PolecatsChecked []string\n Errors []string\n}\n\nfunc ReconcileWork(rig string, polecats []string) *ReconcileResult\nfunc GetAssignedIssues(assignee string) []IssueInfo\nfunc UnassignIssue(issueID string, resetStatus bool) error\n```\n\n## Logic\n\n1. Get list of polecats in swarm\n2. For each polecat, query beads for assigned issues\n3. Categorize as completed (closed) or incomplete (open/in_progress)\n4. Return summary for landing decision\n\n## Handling Incomplete Work\n\nIf issues incomplete:\n- Abort landing (default)\n- Or force landing (leaves work unfinished)\n- Unassign incomplete issues for future work\n\n## Reference\n\nPGT: swarm/reconcile.py","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-16T00:10:21.351476-08:00","updated_at":"2025-12-16T00:10:21.351476-08:00","dependencies":[{"issue_id":"gt-kmn.9","depends_on_id":"gt-kmn","type":"parent-child","created_at":"2025-12-16T00:10:21.351869-08:00","created_by":"daemon"},{"issue_id":"gt-kmn.9","depends_on_id":"gt-u1j.13","type":"blocks","created_at":"2025-12-16T00:11:29.259187-08:00","created_by":"daemon"}]} {"id":"gt-l3c","title":"Design: Polecat Beads write access","description":"Design for granting polecats direct beads write access.\n\n## Background\n\nWith Beads v0.30.0 tombstone-based rearchitecture, we have solid multi-agent support. Reversing the original read-only decision.\n\n## Benefits\n\n- Simplifies architecture (no mail-based issue filing proxy)\n- Empowers polecats to file discovered work\n- Beads handles work-disavowal\n\n## Complications\n\nFor OSS projects where you cannot commit to project .beads/, need per-rig beads repo configuration.\n\n## Subtasks (implementation)\n\n- gt-zx3: Per-rig beads configuration schema\n- gt-e1y: Worker prompting updates for beads access\n- gt-cjb: Witness proxy removal\n- gt-082: Beads sync in decommission checklist\n\n**Design complete.** Each subtask has full specification in its description.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-15T19:37:42.191734-08:00","updated_at":"2025-12-15T20:49:24.598429-08:00","closed_at":"2025-12-15T20:14:04.174535-08:00","close_reason":"Design complete in docs/polecat-beads-access-design.md. Subtasks remain open for implementation."} +{"id":"gt-l9g","title":"Beads epic templates for swarm workflows","description":"Optional: Define templates for common swarm workflows.\n\n## Concept\n\nA template encodes a workflow pattern that can be instantiated as beads:\n\n```yaml\n# templates/swarm-basic.yaml\nname: basic-swarm\ndescription: Simple swarm workflow\nphases:\n - name: startup\n issues:\n - title: \"Verify workers ready\"\n - name: working\n # Actual work issues added separately\n - name: landing\n issues:\n - title: \"Merge all branches\"\n - title: \"Clean up workers\"\n - title: \"Report to Mayor\"\n```\n\n## Usage\n\n```bash\ngt swarm create --template basic-swarm --epic gt-u1j --workers Nux,Toast\n```\n\nCreates beads epic with template phases + actual work from gt-u1j children.\n\n## Decision Point\n\nTemplates are OPTIONAL. The core design (beads as state, multi-wave orchestration) works without templates. Templates are sugar for common patterns.\n\nConsider deferring to P3 or dropping entirely if beads epics with dependencies suffice.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T01:51:24.399235-08:00","updated_at":"2025-12-16T01:51:24.399235-08:00"} {"id":"gt-ov2","title":"Refinery agent: merge queue processing loop","description":"The Refinery agent processes the merge queue, merging polecat work to main.\n\n## Interface\n\n```go\ntype Refinery struct {\n rig *Rig\n queue *MergeQueue\n git *Git\n mail *Mailbox\n config RefineryConfig\n}\n\ntype RefineryConfig struct {\n AutoMerge bool // Auto-merge passing MRs\n RunTests bool // Run tests before merge\n TestCommand string // Command to run tests\n RequireReview bool // Require review before merge (future)\n}\n\nfunc NewRefinery(rig *Rig, ...) *Refinery\n\n// Lifecycle\nfunc (r *Refinery) Start() error\nfunc (r *Refinery) Stop() error\nfunc (r *Refinery) IsRunning() bool\n\n// Processing\nfunc (r *Refinery) ProcessQueue() error\nfunc (r *Refinery) ProcessMR(mr *MergeRequest) error\n```\n\n## Processing Loop\n\n1. Check queue for pending MRs\n2. For each pending MR:\n a. Fetch polecat branch\n b. Attempt merge to refinery/rig (local main)\n c. Run tests if configured\n d. If pass: push to origin, mark merged\n e. If fail: mark rejected, notify polecat\n3. Sleep, repeat\n\n## Merge Strategy\n\n- Fast-forward when possible\n- Merge commit when not\n- On conflict: reject MR, polecat must rebase\n\n## Test Integration\n\nIf tests configured:\n```bash\ncd refinery/rig\ngit merge polecat/branch\n\u003ctest_command\u003e # e.g., go test ./...\n```\nResult determines merge/reject.\n\n## Notifications\n\nOn merge success:\n- Mail to polecat: \"Your work merged\"\n- Update bead if issue tracked\n\nOn merge failure:\n- Mail to polecat: \"Merge failed: \u003creason\u003e\"\n- Include conflict details if applicable\n\n## Dependencies\n\nNeeds: Rig management, Git wrapper, Mail system, Merge queue","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-15T23:22:08.498771-08:00","updated_at":"2025-12-16T00:11:44.091792-08:00","dependencies":[{"issue_id":"gt-ov2","depends_on_id":"gt-u1j.14","type":"blocks","created_at":"2025-12-15T23:22:21.801826-08:00","created_by":"daemon"},{"issue_id":"gt-ov2","depends_on_id":"gt-u1j.6","type":"blocks","created_at":"2025-12-15T23:22:21.89716-08:00","created_by":"daemon"}]} {"id":"gt-pio","title":"Plugin: merge-oracle (merge queue analysis)","description":"Example plugin that analyzes changesets before Refinery processes them. Builds overlap graph, classifies disjointness (parallel-safe vs needs-sequencing), uses LLM for semantic complexity, identifies high-risk patterns. Based on merge-orchestration proposal. See docs/architecture.md.","status":"open","priority":3,"issue_type":"feature","created_at":"2025-12-15T22:53:04.027073-08:00","updated_at":"2025-12-15T23:17:06.507108-08:00","dependencies":[{"issue_id":"gt-pio","depends_on_id":"gt-axz","type":"blocks","created_at":"2025-12-15T22:53:17.507459-08:00","created_by":"daemon"}]} {"id":"gt-qh2","title":"Session cycling UX: smooth transitions via TUI wrapper","description":"## Problem\n\nCurrent CLI agent session cycling is painful:\n- Shell → CC starts → priming → context loads → ready → work → exit/crash → repeat\n- Each cycle is 30-60 seconds of cold boot\n- No continuity between shell and agent's inner state\n- Raw \"session not running, starting...\" loop is the baseline\n\n## GGT Advantages (already have)\n\n- Beads: Work state survives session death completely\n- Mail: Handoff notes from past-self to future-self \n- Prime commands: Structured context reload\n\n## Gap: Transition Mechanics\n\nIdeas to explore when actively using CLI:\n\n1. **In-band cycling** - `/restart` or `/cycle` command, agent handles own restart without dropping to shell\n\n2. **Hot standby** - TUI maintains pre-warmed session in background, switch to already-primed agent\n\n3. **Persistent wrapper** - Bubbletea TUI stays running across session cycles, CC sessions come/go inside it\n\n4. **Session pooling** - Keep 2-3 primed sessions ready, never wait for cold start\n\n## Deferred\n\nDeliberately P4 until we're actively using the simpler CLI and feel the pain firsthand.","status":"open","priority":4,"issue_type":"task","created_at":"2025-12-15T20:38:12.660716-08:00","updated_at":"2025-12-15T23:17:34.27061-08:00"} @@ -77,8 +83,11 @@ {"id":"gt-u1j.6","title":"Mail system: JSONL inbox, delivery, tmux injection","description":"JSONL-based mail system for agent communication.\n\n## Data Model\n\n```go\ntype Message struct {\n ID string `json:\"id\"`\n From string `json:\"from\"` // \"rig/polecat\" or \"mayor/\"\n To string `json:\"to\"`\n Subject string `json:\"subject\"`\n Body string `json:\"body\"`\n Timestamp time.Time `json:\"timestamp\"`\n Read bool `json:\"read\"`\n Priority string `json:\"priority\"` // \"normal\", \"high\"\n}\n```\n\n## Interface\n\n```go\ntype Mailbox struct {\n path string // path to inbox.jsonl\n}\n\nfunc NewMailbox(path string) *Mailbox\n\n// Reading\nfunc (m *Mailbox) List() ([]*Message, error)\nfunc (m *Mailbox) ListUnread() ([]*Message, error)\nfunc (m *Mailbox) Get(id string) (*Message, error)\nfunc (m *Mailbox) MarkRead(id string) error\n\n// Writing\nfunc (m *Mailbox) Append(msg *Message) error\nfunc (m *Mailbox) Delete(id string) error\n```\n\n## Delivery\n\n```go\ntype MailRouter struct {\n townRoot string\n}\n\nfunc (r *MailRouter) Send(msg *Message) error\nfunc (r *MailRouter) ResolveMailbox(address string) (string, error)\n```\n\nAddress resolution:\n- `mayor/` → `\u003ctown\u003e/mayor/mail/inbox.jsonl`\n- `\u003crig\u003e/refinery` → `\u003ctown\u003e/\u003crig\u003e/refinery/mail/inbox.jsonl`\n- `\u003crig\u003e/\u003cpolecat\u003e` → `\u003ctown\u003e/\u003crig\u003e/polecats/\u003cpolecat\u003e/mail/inbox.jsonl`\n\n## Tmux Notification\n\nWhen delivering to active polecat, optionally inject notification:\n```go\nfunc (r *MailRouter) NotifyPolecat(rig, polecat string, msg *Message) error\n```\nUses tmux SendKeys to inject `[MAIL] \u003csubject\u003e` into session.\n\n## File Format\n\nJSONL (one JSON object per line). Append-only for writes, rewrite for deletes.","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-15T17:12:16.226478-08:00","updated_at":"2025-12-15T21:16:41.680942-08:00","dependencies":[{"issue_id":"gt-u1j.6","depends_on_id":"gt-u1j","type":"parent-child","created_at":"2025-12-15T17:12:16.226821-08:00","created_by":"daemon"},{"issue_id":"gt-u1j.6","depends_on_id":"gt-u1j.4","type":"blocks","created_at":"2025-12-15T17:13:51.98774-08:00","created_by":"daemon"}]} {"id":"gt-u1j.7","title":"Session management: start, stop, attach, capture","description":"Polecat session lifecycle management.\n\n## Interface\n\n```go\ntype SessionManager struct {\n tmux *Tmux\n rig *Rig\n}\n\nfunc NewSessionManager(tmux *Tmux, rig *Rig) *SessionManager\n\n// Lifecycle\nfunc (sm *SessionManager) Start(polecat string, opts StartOptions) error\nfunc (sm *SessionManager) Stop(polecat string) error\nfunc (sm *SessionManager) IsRunning(polecat string) (bool, error)\nfunc (sm *SessionManager) List() ([]SessionInfo, error)\n\n// Interaction\nfunc (sm *SessionManager) Attach(polecat string) error\nfunc (sm *SessionManager) Capture(polecat string, lines int) (string, error)\nfunc (sm *SessionManager) Inject(polecat string, message string) error\n\ntype StartOptions struct {\n WorkDir string // defaults to polecat clone dir\n Issue string // optional: issue to work on\n Command string // optional: override claude command\n}\n\ntype SessionInfo struct {\n Polecat string\n SessionID string\n Running bool\n StartedAt time.Time\n}\n```\n\n## Session Naming\n\n`gt-\u003crig\u003e-\u003cpolecat\u003e` (e.g., `gt-wyvern-Toast`)\n\n## Start Flow\n\n1. Verify polecat clone exists\n2. Check no existing session\n3. Create tmux session in polecat workdir\n4. Send initial command: `claude` or custom\n5. If issue provided, inject initial prompt\n\n## Stop Flow\n\n1. Capture final output (for logging)\n2. Send exit/quit command\n3. Wait briefly for graceful shutdown\n4. Kill session if still running\n\n## Capture\n\nUses tmux capture-pane to get recent output. Returns last N lines.\n\n## Inject\n\nSends text to session via tmux send-keys. Used for:\n- Mail notifications\n- Witness nudges\n- User messages","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-15T17:12:25.473674-08:00","updated_at":"2025-12-15T21:16:59.014215-08:00","dependencies":[{"issue_id":"gt-u1j.7","depends_on_id":"gt-u1j","type":"parent-child","created_at":"2025-12-15T17:12:25.473993-08:00","created_by":"daemon"},{"issue_id":"gt-u1j.7","depends_on_id":"gt-u1j.4","type":"blocks","created_at":"2025-12-15T17:13:52.081053-08:00","created_by":"daemon"}]} {"id":"gt-u1j.8","title":"Polecat management: add, remove, list, state","description":"Polecat lifecycle: add, remove, list, state tracking.\n\n## Data Model\n\n```go\ntype Polecat struct {\n Name string `json:\"name\"`\n Rig string `json:\"rig\"`\n State PolecatState `json:\"state\"`\n ClonePath string `json:\"clone_path\"`\n Branch string `json:\"branch\"`\n Issue string `json:\"issue,omitempty\"`\n CreatedAt time.Time `json:\"created_at\"`\n UpdatedAt time.Time `json:\"updated_at\"`\n}\n\ntype PolecatState string\nconst (\n StateIdle PolecatState = \"idle\"\n StateActive PolecatState = \"active\"\n StateWorking PolecatState = \"working\"\n StateDone PolecatState = \"done\"\n StateStuck PolecatState = \"stuck\"\n)\n```\n\n## Interface\n\n```go\ntype PolecatManager struct {\n rig *Rig\n git *Git\n}\n\nfunc NewPolecatManager(rig *Rig, git *Git) *PolecatManager\n\n// Lifecycle\nfunc (pm *PolecatManager) Add(name string) (*Polecat, error)\nfunc (pm *PolecatManager) Remove(name string) error\nfunc (pm *PolecatManager) List() ([]*Polecat, error)\nfunc (pm *PolecatManager) Get(name string) (*Polecat, error)\n\n// State\nfunc (pm *PolecatManager) SetState(name string, state PolecatState) error\nfunc (pm *PolecatManager) AssignIssue(name, issue string) error\nfunc (pm *PolecatManager) ClearIssue(name string) error\n\n// Convenience\nfunc (pm *PolecatManager) Wake(name string) error // idle → active\nfunc (pm *PolecatManager) Sleep(name string) error // active → idle\n```\n\n## Add Flow\n\n1. Create directory: `\u003crig\u003e/polecats/\u003cname\u003e/`\n2. Clone rig repo into it (or copy from rig root)\n3. Create new branch: `polecat/\u003cname\u003e`\n4. Initialize polecat state file\n5. Create mail inbox\n\n## Remove Flow\n\n1. Verify session not running\n2. Check for uncommitted changes (warn/error)\n3. Remove directory\n4. Clean up state\n\n## State Persistence\n\nStore in `\u003crig\u003e/polecats/\u003cname\u003e/state.json`","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-15T17:12:27.402824-08:00","updated_at":"2025-12-15T21:17:16.725483-08:00","dependencies":[{"issue_id":"gt-u1j.8","depends_on_id":"gt-u1j","type":"parent-child","created_at":"2025-12-15T17:12:27.403171-08:00","created_by":"daemon"},{"issue_id":"gt-u1j.8","depends_on_id":"gt-u1j.5","type":"blocks","created_at":"2025-12-15T17:13:53.747126-08:00","created_by":"daemon"},{"issue_id":"gt-u1j.8","depends_on_id":"gt-u1j.3","type":"blocks","created_at":"2025-12-15T17:13:53.831197-08:00","created_by":"daemon"}]} -{"id":"gt-u1j.9","title":"Witness daemon: heartbeat loop, spawn ephemeral agent","description":"Background daemon for polecat monitoring and management.\n\n## Interface\n\n```go\ntype Witness struct {\n rig *Rig\n polecats *PolecatManager\n sessions *SessionManager\n mail *Mailbox\n config WitnessConfig\n}\n\ntype WitnessConfig struct {\n HeartbeatInterval time.Duration // default: 30s\n NudgeThreshold int // nudges before escalation\n CaptureLines int // lines to capture for status\n}\n\nfunc NewWitness(rig *Rig, ...) *Witness\n\n// Daemon lifecycle\nfunc (w *Witness) Start() error\nfunc (w *Witness) Stop() error\nfunc (w *Witness) IsRunning() bool\n\n// Core loop\nfunc (w *Witness) heartbeatLoop()\nfunc (w *Witness) checkPolecat(p *Polecat) error\nfunc (w *Witness) nudgePolecat(p *Polecat, reason string) error\nfunc (w *Witness) escalateToMayor(p *Polecat, reason string) error\n```\n\n## Heartbeat Loop\n\nEvery HeartbeatInterval:\n1. List active polecats\n2. For each polecat:\n - Check session is running\n - Capture recent output\n - Assess progress (stuck detection)\n - Nudge if needed\n - Escalate if stuck after threshold\n\n## Ephemeral Agent Spawning\n\nFor complex decisions, spawn short-lived Claude session:\n```go\nfunc (w *Witness) spawnEphemeralAgent(prompt string) (string, error)\n```\nUsed for: status assessment, nudge composition, stuck detection.\n\n## Pre-Kill Verification\n\nBefore killing a session:\n```go\nfunc (w *Witness) verifyCleanState(p *Polecat) (*VerifyResult, error)\n```\nChecks: git status, beads sync, uncommitted work.\n\n## State Persistence\n\nWitness state in `\u003crig\u003e/witness/state.json`:\n- Last heartbeat time\n- Nudge counts per polecat\n- Escalation history","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-15T17:12:29.389103-08:00","updated_at":"2025-12-15T21:17:31.648307-08:00","dependencies":[{"issue_id":"gt-u1j.9","depends_on_id":"gt-u1j","type":"parent-child","created_at":"2025-12-15T17:12:29.389428-08:00","created_by":"daemon"},{"issue_id":"gt-u1j.9","depends_on_id":"gt-u1j.7","type":"blocks","created_at":"2025-12-15T17:14:04.353775-08:00","created_by":"daemon"},{"issue_id":"gt-u1j.9","depends_on_id":"gt-u1j.8","type":"blocks","created_at":"2025-12-15T17:14:04.440363-08:00","created_by":"daemon"}]} +{"id":"gt-u1j.9","title":"Witness daemon: heartbeat loop, spawn ephemeral agent","description":"Background daemon for agent lifecycle and monitoring.\n\n## Core Responsibilities\n\n1. **Heartbeat monitoring**: Check agent health periodically\n2. **Session lifecycle**: Restart agents after handoff (Witness Protection)\n3. **Polecat monitoring**: Track worker progress, nudging\n4. **Escalation**: Report failures to Mayor\n\n## Session Lifecycle (Witness Protection)\n\nThe daemon enables autonomous long-running operation by cycling agent sessions:\n\n```go\ntype SessionLifecycle struct {\n AgentType string // \"witness\", \"refinery\"\n StatePath string // path to state.json\n}\n\nfunc (d *Daemon) monitorSessionLifecycle(agent SessionLifecycle) {\n // 1. Detect session exit\n // 2. Check state.json for requesting_cycle: true\n // 3. If cycle requested: start new session, clear flag\n // 4. If unexpected exit: escalate to Mayor\n}\n```\n\nSee architecture.md Key Decision #12: Agent Session Lifecycle.\n\n## Interface\n\n```go\ntype Daemon struct {\n rig *Rig\n polecats *PolecatManager\n sessions *SessionManager\n config DaemonConfig\n}\n\ntype DaemonConfig struct {\n HeartbeatInterval time.Duration // default: 30s\n NudgeThreshold int // nudges before escalation\n MaxWorkers int // from rig config\n}\n\nfunc NewDaemon(rig *Rig) *Daemon\nfunc (d *Daemon) Start() error\nfunc (d *Daemon) Stop() error\n\n// Lifecycle\nfunc (d *Daemon) CycleSession(agentType string) error\nfunc (d *Daemon) SpawnWorker(issueID string) error\nfunc (d *Daemon) ShutdownWorker(polecat string) error\n```\n\n## Heartbeat Loop\n\nEvery HeartbeatInterval:\n1. Check Witness session (restart if cycle requested)\n2. Check Refinery session (restart if cycle requested)\n3. For each active polecat: assess progress, nudge if stuck\n4. Query `bd ready` for new work, spawn up to max_workers","status":"open","priority":0,"issue_type":"task","created_at":"2025-12-15T17:12:29.389103-08:00","updated_at":"2025-12-16T01:51:21.638495-08:00","dependencies":[{"issue_id":"gt-u1j.9","depends_on_id":"gt-u1j","type":"parent-child","created_at":"2025-12-15T17:12:29.389428-08:00","created_by":"daemon"},{"issue_id":"gt-u1j.9","depends_on_id":"gt-u1j.7","type":"blocks","created_at":"2025-12-15T17:14:04.353775-08:00","created_by":"daemon"},{"issue_id":"gt-u1j.9","depends_on_id":"gt-u1j.8","type":"blocks","created_at":"2025-12-15T17:14:04.440363-08:00","created_by":"daemon"}]} {"id":"gt-u82","title":"Design: Mayor session cycling and handoff","description":"Design for Mayor session cycling and structured handoff.\n\n## Overview\n\nMayor coordinates across all rigs and runs for extended periods. Needs session cycling pattern with structured handoff notes.\n\n## Key Elements\n\n1. Session cycling recognition (when to cycle)\n2. Handoff note format (structured state capture)\n3. Handoff delivery (mail to self)\n4. Fresh session startup (reading and resuming)\n\n## Subtasks (implementation)\n\n- gt-g2d: Mayor session cycling prompting\n- gt-sye: Mayor startup protocol prompting\n- gt-vci: Mayor handoff mail template\n- gt-1le: town handoff command (optional, P2)\n\n**Design complete.** Each subtask has full specification in its description.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-15T20:03:16.125725-08:00","updated_at":"2025-12-15T20:49:26.203276-08:00","closed_at":"2025-12-15T20:16:10.772149-08:00","close_reason":"Design complete in docs/mayor-handoff-design.md. 4 subtasks created for implementation."} {"id":"gt-v5k","title":"Design: Failure modes and recovery","description":"Document failure modes and recovery strategies for Gas Town operations.\n\n## Critical Failure Modes\n\n### 1. Agent Crash Mid-Operation\n\n**Scenario**: Polecat crashes while committing, Witness crashes while verifying\n\n**Detection**:\n- Session suddenly gone (tmux check fails)\n- State shows 'working' but no session\n- Heartbeat stops (for Witness)\n\n**Recovery**:\n- Doctor detects via ZombieSessionCheck\n- Capture any recoverable state\n- Reset agent state to 'idle'\n- For Witness: auto-restart via supervisor or manual gt witness start\n\n### 2. Git State Corruption\n\n**Scenario**: Merge conflict, failed rebase, detached HEAD\n\n**Detection**:\n- Git commands fail\n- Dirty state that won't commit\n- Branch diverged from origin\n\n**Recovery**:\n- gt doctor reports git health issues\n- Manual intervention recommended\n- Severe cases: remove clone, re-clone\n\n### 3. Beads Sync Conflict\n\n**Scenario**: Two polecats modify same issue\n\n**Detection**:\n- bd sync fails with conflict\n- Beads tombstone mechanism handles most cases\n\n**Recovery**:\n- Beads has last-write-wins semantics\n- bd sync --force in extreme cases\n- Issues may need manual dedup\n\n### 4. Tmux Failure\n\n**Scenario**: Tmux server crashes, socket issues\n\n**Detection**:\n- All sessions inaccessible\n- \"no server running\" errors\n\n**Recovery**:\n- Kill any orphan processes\n- tmux kill-server \u0026\u0026 tmux start-server\n- All agent states reset to idle\n- Re-spawn active work\n\n### 5. Claude API Issues\n\n**Scenario**: Rate limits, outages, context limits\n\n**Detection**:\n- Sessions hang or produce errors\n- Repeated failure patterns\n\n**Recovery**:\n- Exponential backoff (handled by Claude Code)\n- For context limits: session cycling (mail-to-self)\n- For outages: wait and retry\n\n### 6. Disk Full\n\n**Scenario**: Clones, logs, or beads fill disk\n\n**Detection**:\n- Write operations fail\n- git/bd commands error\n\n**Recovery**:\n- Clean up logs: rm ~/.gastown/logs/*\n- Remove old polecat clones\n- gt doctor --fix can clean some cruft\n\n### 7. Network Failure\n\n**Scenario**: Can't reach GitHub, API servers\n\n**Detection**:\n- git fetch/push fails\n- Claude sessions hang\n\n**Recovery**:\n- Work continues locally\n- Queue pushes for later\n- Sync when connectivity restored\n\n## Recovery Principles\n\n1. **Fail safe**: Prefer stopping over corrupting\n2. **State is recoverable**: Git and beads have recovery mechanisms\n3. **Doctor heals**: gt doctor --fix handles common issues\n4. **Emergency stop**: gt stop --all as last resort\n5. **Human escalation**: Some failures need Overseer intervention\n\n## Implementation\n\n- Document each failure mode in architecture.md\n- Ensure doctor checks cover detection\n- Add recovery hints to error messages\n- Log all failures for debugging","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T23:19:07.198289-08:00","updated_at":"2025-12-15T23:19:28.171942-08:00"} {"id":"gt-vci","title":"Mayor handoff mail template","description":"Add MAYOR_HANDOFF mail template to templates.py.\n\n## Template Function\n\ndef mayor_handoff(\n active_swarms: List[SwarmStatus],\n rig_status: Dict[str, RigStatus],\n pending_escalations: List[Escalation],\n in_flight_decisions: List[Decision],\n recent_actions: List[str],\n delegated_work: List[DelegatedItem],\n user_requests: List[str],\n next_steps: List[str],\n warnings: Optional[str] = None,\n session_duration: Optional[str] = None,\n) -\u003e Message:\n metadata = {\n 'template': 'MAYOR_HANDOFF',\n 'timestamp': datetime.utcnow().isoformat(),\n 'session_duration': session_duration,\n 'active_swarm_count': len(active_swarms),\n 'pending_escalation_count': len(pending_escalations),\n }\n # ... format sections ...\n return Message.create(\n sender='mayor/',\n recipient='mayor/',\n subject='Session Handoff',\n body=body,\n priority='high',\n )\n\n## Metadata Fields\n\n- template: MAYOR_HANDOFF\n- timestamp: ISO format\n- session_duration: Human readable\n- active_swarm_count: Number of active swarms\n- pending_escalation_count: Number of escalations\n\n## Mail Priority\n\nUse priority='high' to ensure handoff is seen on startup.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T20:15:30.26323-08:00","updated_at":"2025-12-15T20:48:59.550689-08:00","dependencies":[{"issue_id":"gt-vci","depends_on_id":"gt-u82","type":"blocks","created_at":"2025-12-15T20:15:39.554108-08:00","created_by":"daemon"}]} +{"id":"gt-vjw","title":"Swarm learning: Session cleanup missing from swarm workflow","description":"## Problem\n\nAfter Enders Game swarm completed (18 issues merged), 16 polecat sessions were left running but idle. No automated cleanup occurred.\n\n## What Should Happen\n\n1. Witness detects polecat completed work (idle at prompt)\n2. Witness verifies git state is clean\n3. Witness shuts down session\n4. Witness reports completion to Mayor\n\n## GGT Components\n\n- gt-cxx: Witness context cycling (covers self-cycling)\n- gt-u1j.9: Witness daemon heartbeat loop\n- gt-kmn.6: Witness swarm landing protocol\n\n## Recommendation\n\nAdd to Witness responsibilities:\n- Monitor for 'work complete' signals (DONE keyword, idle detection)\n- Automated session shutdown after verification\n- Swarm completion reporting to Mayor\n\nSee also: architecture.md 'Worker Cleanup (Witness-Owned)' section which describes this but it wasn't implemented in PGT.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-16T01:27:52.796587-08:00","updated_at":"2025-12-16T01:51:37.409965-08:00","closed_at":"2025-12-16T01:51:37.409965-08:00","close_reason":"Addressed by gt-u1j.9 (daemon heartbeat) which now includes session lifecycle management and worker shutdown. See architecture.md Key Decision #12."} +{"id":"gt-z4g","title":"Plugin: Plan-to-Swarm converter","description":"## Purpose\n\nHelp users create swarmable beads plans from various planning inputs.\n\n## Inputs\n- Markdown task lists\n- GitHub issues\n- Linear/Jira exports\n- Free-form descriptions\n- Existing beads epics\n\n## Output\n- Beads epic with properly structured children\n- Dependencies set for wave ordering\n- Priorities assigned\n- Ready for `gt swarm create --epic \u003cid\u003e`\n\n## Implementation Options\n\n### Option A: CLI Tool\n```bash\ngt plan import --from github --repo owner/repo --label swarm-candidate\ngt plan import --from markdown tasks.md\ngt plan structure \u003cepic-id\u003e # analyze and add dependencies\n```\n\n### Option B: Plugin Agent\nA plugin at `\u003crig\u003e/plugins/plan-oracle/` that:\n- Receives planning requests via mail (or beads)\n- Analyzes scope and requirements\n- Creates structured beads epic\n- Sets dependencies based on analysis\n\n### Option C: Interactive Mode\n```bash\ngt plan create\n# Walks through questions, creates epic interactively\n```\n\n## Axiom\n\nAs stated: 'The Planning phase should end in the creation of a swarmable Beads plan.'\n\nThis plugin bridges the gap between human planning and machine-executable swarms.\n\n## Priority\n\nP2 - Nice to have for MVP. Manual epic creation works for now.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-16T02:10:20.663549-08:00","updated_at":"2025-12-16T02:10:20.663549-08:00"} +{"id":"gt-zly","title":"Swarm learning: Beads database locality gap","description":"## PGT Bug (GGT Design Already Correct)\n\nMayor created issues in `~/ai/mayor/rigs/beads/.beads/` but polecats use `~/ai/beads/.beads/`. Different databases = polecats can't see Mayor's beads.\n\n**GGT Fix**: architecture.md already specifies:\n- All agents use BEADS_DIR pointing to rig-level `.beads/`\n- Lines 116-143: Beads Configuration for Multi-Agent\n- Lines 573-586: Rig-Level Beads via BEADS_DIR\n\nThis is a PGT implementation gap, not a design issue. GGT spawn must set BEADS_DIR correctly.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-16T01:21:45.37072-08:00","updated_at":"2025-12-16T01:28:40.74469-08:00","closed_at":"2025-12-16T01:28:40.74469-08:00","close_reason":"PGT implementation gap documented. GGT design already correct - architecture.md specifies BEADS_DIR for all agents pointing to rig-level .beads/"} {"id":"gt-zx3","title":"Per-rig beads repo configuration","description":"Add per-rig beads configuration to rig config schema.\n\n## Config Schema\n\nIn each rig's config.json:\n\n```json\n{\n \"version\": 1,\n \"name\": \"wyvern\",\n \"git_url\": \"https://github.com/steveyegge/wyvern\",\n \"beads\": {\n \"repo\": \"local\", // \"local\" | \"\u003cpath\u003e\" | \"\u003cgit-url\u003e\"\n \"root\": null, // Override bd --root (optional)\n \"prefix\": \"wyv\" // Issue prefix for this rig\n }\n}\n```\n\n## Repo Options\n\n| Value | Meaning | Use Case |\n|-------|---------|----------|\n| `\"local\"` | Use project's `.beads/` | Own projects, full commit access |\n| `\"\u003cpath\u003e\"` | Use beads at path | OSS contributions |\n| `\"\u003cgit-url\u003e\"` | Clone and use repo | Team shared beads |\n\n## Environment Injection\n\nWhen spawning polecats, Gas Town sets:\n```bash\nexport BEADS_ROOT=\"\u003cresolved-path\u003e\"\n```\n\n## Resolution Logic\n\n```go\nfunc ResolveBeadsRoot(rigConfig *RigConfig, rigPath string) (string, error) {\n beads := rigConfig.Beads\n switch {\n case beads.Root != \"\":\n return beads.Root, nil\n case beads.Repo == \"local\" || beads.Repo == \"\":\n return filepath.Join(rigPath, \".beads\"), nil\n case strings.HasPrefix(beads.Repo, \"/\"):\n return beads.Repo, nil\n case strings.Contains(beads.Repo, \"://\"):\n return cloneAndResolve(beads.Repo)\n default:\n return filepath.Join(rigPath, beads.Repo), nil\n }\n}\n```\n\n## Backwards Compatibility\n\nIf `beads` section missing, assume `\"repo\": \"local\"`.","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-15T19:47:16.660049-08:00","updated_at":"2025-12-15T20:48:02.122203-08:00","dependencies":[{"issue_id":"gt-zx3","depends_on_id":"gt-l3c","type":"blocks","created_at":"2025-12-15T19:47:35.726502-08:00","created_by":"daemon"}]}