opencode-swarm-plugin 0.21.0 → 0.22.0

package/.beads/issues.jsonl

@@ -389,7 +389,7 @@
 {"id":"opencode-swarm-plugin-637l","title":"Limit test bead 1","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:21:27.263293-08:00","updated_at":"2025-12-08T08:21:29.957087-08:00","closed_at":"2025-12-08T08:21:29.957087-08:00"}
 {"id":"opencode-swarm-plugin-64f","title":"Bead to start","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T19:39:10.34101-08:00","updated_at":"2025-12-07T19:39:12.089113-08:00","closed_at":"2025-12-07T19:39:12.089113-08:00"}
 {"id":"opencode-swarm-plugin-64sb","title":"Thread link test bead","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T07:49:11.252017-08:00","updated_at":"2025-12-08T07:49:12.801335-08:00","closed_at":"2025-12-08T07:49:12.801335-08:00"}
-{"id":"opencode-swarm-plugin-66ni8","title":"README rewrite with full repo context","description":"## Context Captured\n\n### Repo Structure (74k lines total)\n```\nsrc/\n├── index.ts              # Plugin entry, exports all tools\n├── plugin.ts             # Plugin loader (23 lines)\n├── swarm.ts              # Swarm tools aggregator (35 lines)\n│\n├── # SWARM COORDINATION (5k lines)\n├── swarm-orchestrate.ts  # 2298 lines - swarm_status, swarm_progress, swarm_complete, swarm_checkpoint, swarm_recover\n├── swarm-decompose.ts    # 912 lines - swarm_decompose, swarm_validate_decomposition\n├── swarm-prompts.ts      # 828 lines - swarm_spawn_subtask, swarm_subtask_prompt\n├── swarm-strategies.ts   # 407 lines - swarm_select_strategy (file/feature/risk/research)\n│\n├── # BEADS (git-backed issues)\n├── beads.ts              # beads_create, beads_create_epic, beads_query, beads_update, beads_close, beads_start, beads_ready, beads_sync\n│\n├── # SWARM MAIL (agent coordination)\n├── swarm-mail.ts         # 739 lines - swarmmail_init, swarmmail_send, swarmmail_inbox, swarmmail_reserve, swarmmail_release\n├── agent-mail.ts         # DEPRECATED MCP-based version\n│\n├── # SKILLS (knowledge packages)\n├── skills.ts             # 1533 lines - skills_list, skills_use, skills_read, skills_create, skills_init, skills_update, skills_delete\n│\n├── # STRUCTURED OUTPUT\n├── structured.ts         # 755 lines - structured_extract_json, structured_validate, structured_parse_*\n│\n├── # LEARNING SYSTEM\n├── learning.ts           # Confidence decay, implicit feedback scoring\n├── pattern-maturity.ts   # candidate → established → proven lifecycle\n├── anti-patterns.ts      # Auto-inversion of failing patterns\n├── eval-capture.ts       # Outcome capture for evals\n│\n├── # STORAGE \u0026 STREAMS (event sourcing)\n├── streams/\n│   ├── index.ts          # PGLite database management\n│   ├── store.ts          # Append-only event log\n│   ├── events.ts         # 15+ event types (agent_registered, message_sent, file_reserved, swarm_checkpointed, etc.)\n│   ├── projections.ts    # Materialized views (agents, messages, reservations, eval_records)\n│   ├── migrations.ts     # Schema migrations v1-v4\n│   ├── effect/           # Durable primitives (DurableCursor, DurableDeferred, DurableLock, DurableMailbox, ask pattern)\n│   └── debug.ts          # Debugging utilities\n│\n├── # OTHER\n├── storage.ts            # File-based storage utilities\n├── rate-limiter.ts       # Redis/SQLite rate limiting\n├── repo-crawl.ts         # GitHub repo analysis tools\n├── output-guardrails.ts  # MCP output validation\n├── mandates.ts           # Mandate system (deprecated?)\n└── schemas/              # Zod schemas for all data types\n\nglobal-skills/            # Bundled skills\n├── cli-builder/\n├── learning-systems/\n├── skill-creator/\n├── swarm-coordination/\n├── system-design/\n└── testing-patterns/\n\nevals/                    # Evalite integration\n├── swarm-decomposition.eval.ts\n├── lib/data-loader.ts    # PGLite eval data loader\n└── scorers/              # Outcome-based scorers\n```\n\n### Tool Groups\n- **Swarm**: 12 tools (init, select_strategy, plan_prompt, decompose, validate_decomposition, spawn_subtask, status, progress, complete, record_outcome, checkpoint, recover)\n- **Beads**: 9 tools (create, create_epic, query, update, close, start, ready, sync, link_thread)\n- **Swarm Mail**: 8 tools (init, send, inbox, read_message, reserve, release, ack, health)\n- **Skills**: 7 tools (list, use, read, create, init, update, delete)\n- **Structured**: 5 tools (extract_json, validate, parse_evaluation, parse_decomposition, parse_bead_tree)\n\n### Key Concepts to Explain\n1. **Swarm flow**: task → decomposition → beads → file reservations → parallel agents → learning\n2. **Checkpoint/recovery**: survives context compaction (NEW)\n3. **Learning loop**: outcomes → confidence decay → pattern maturity → anti-pattern inversion\n4. **Event sourcing**: append-only log → materialized views → crash recovery\n5. **Skills**: reusable knowledge packages with references\n\n### v0.21.0 Changelog\n- Swarm recovery context (swarm_checkpoint, swarm_recover, auto-checkpoint at 25/50/75%)\n- Eval data capture (DecompositionGeneratedEvent, SubtaskOutcomeEvent, eval_records table)\n- Outcome-based scorers (fileOverlap, scopeAccuracy, timeBalance, successRate, humanAcceptance)\n- PGLite data loader for Evalite\n- JSONB parsing fix in store.ts/projections.ts","status":"open","priority":1,"issue_type":"task","created_at":"2025-12-14T13:40:47.478855-08:00","updated_at":"2025-12-14T13:40:47.478855-08:00"}
+{"id":"opencode-swarm-plugin-66ni8","title":"README rewrite with full repo context","description":"## Context Captured\n\n### Repo Structure (74k lines total)\n```\nsrc/\n├── index.ts              # Plugin entry, exports all tools\n├── plugin.ts             # Plugin loader (23 lines)\n├── swarm.ts              # Swarm tools aggregator (35 lines)\n│\n├── # SWARM COORDINATION (5k lines)\n├── swarm-orchestrate.ts  # 2298 lines - swarm_status, swarm_progress, swarm_complete, swarm_checkpoint, swarm_recover\n├── swarm-decompose.ts    # 912 lines - swarm_decompose, swarm_validate_decomposition\n├── swarm-prompts.ts      # 828 lines - swarm_spawn_subtask, swarm_subtask_prompt\n├── swarm-strategies.ts   # 407 lines - swarm_select_strategy (file/feature/risk/research)\n│\n├── # BEADS (git-backed issues)\n├── beads.ts              # beads_create, beads_create_epic, beads_query, beads_update, beads_close, beads_start, beads_ready, beads_sync\n│\n├── # SWARM MAIL (agent coordination)\n├── swarm-mail.ts         # 739 lines - swarmmail_init, swarmmail_send, swarmmail_inbox, swarmmail_reserve, swarmmail_release\n├── agent-mail.ts         # DEPRECATED MCP-based version\n│\n├── # SKILLS (knowledge packages)\n├── skills.ts             # 1533 lines - skills_list, skills_use, skills_read, skills_create, skills_init, skills_update, skills_delete\n│\n├── # STRUCTURED OUTPUT\n├── structured.ts         # 755 lines - structured_extract_json, structured_validate, structured_parse_*\n│\n├── # LEARNING SYSTEM\n├── learning.ts           # Confidence decay, implicit feedback scoring\n├── pattern-maturity.ts   # candidate → established → proven lifecycle\n├── anti-patterns.ts      # Auto-inversion of failing patterns\n├── eval-capture.ts       # Outcome capture for evals\n│\n├── # STORAGE \u0026 STREAMS (event sourcing)\n├── streams/\n│   ├── index.ts          # PGLite database management\n│   ├── store.ts          # Append-only event log\n│   ├── events.ts         # 15+ event types (agent_registered, message_sent, file_reserved, swarm_checkpointed, etc.)\n│   ├── projections.ts    # Materialized views (agents, messages, reservations, eval_records)\n│   ├── migrations.ts     # Schema migrations v1-v4\n│   ├── effect/           # Durable primitives (DurableCursor, DurableDeferred, DurableLock, DurableMailbox, ask pattern)\n│   └── debug.ts          # Debugging utilities\n│\n├── # OTHER\n├── storage.ts            # File-based storage utilities\n├── rate-limiter.ts       # Redis/SQLite rate limiting\n├── repo-crawl.ts         # GitHub repo analysis tools\n├── output-guardrails.ts  # MCP output validation\n├── mandates.ts           # Mandate system (deprecated?)\n└── schemas/              # Zod schemas for all data types\n\nglobal-skills/            # Bundled skills\n├── cli-builder/\n├── learning-systems/\n├── skill-creator/\n├── swarm-coordination/\n├── system-design/\n└── testing-patterns/\n\nevals/                    # Evalite integration\n├── swarm-decomposition.eval.ts\n├── lib/data-loader.ts    # PGLite eval data loader\n└── scorers/              # Outcome-based scorers\n```\n\n### Tool Groups\n- **Swarm**: 12 tools (init, select_strategy, plan_prompt, decompose, validate_decomposition, spawn_subtask, status, progress, complete, record_outcome, checkpoint, recover)\n- **Beads**: 9 tools (create, create_epic, query, update, close, start, ready, sync, link_thread)\n- **Swarm Mail**: 8 tools (init, send, inbox, read_message, reserve, release, ack, health)\n- **Skills**: 7 tools (list, use, read, create, init, update, delete)\n- **Structured**: 5 tools (extract_json, validate, parse_evaluation, parse_decomposition, parse_bead_tree)\n\n### Key Concepts to Explain\n1. **Swarm flow**: task → decomposition → beads → file reservations → parallel agents → learning\n2. **Checkpoint/recovery**: survives context compaction (NEW)\n3. **Learning loop**: outcomes → confidence decay → pattern maturity → anti-pattern inversion\n4. **Event sourcing**: append-only log → materialized views → crash recovery\n5. **Skills**: reusable knowledge packages with references\n\n### v0.21.0 Changelog\n- Swarm recovery context (swarm_checkpoint, swarm_recover, auto-checkpoint at 25/50/75%)\n- Eval data capture (DecompositionGeneratedEvent, SubtaskOutcomeEvent, eval_records table)\n- Outcome-based scorers (fileOverlap, scopeAccuracy, timeBalance, successRate, humanAcceptance)\n- PGLite data loader for Evalite\n- JSONB parsing fix in store.ts/projections.ts","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-14T13:40:47.478855-08:00","updated_at":"2025-12-14T14:29:15.955044-08:00","closed_at":"2025-12-14T14:29:15.955044-08:00"}
 {"id":"opencode-swarm-plugin-679z","title":"Integration test epic","description":"Testing epic creation","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-08T08:11:40.133137-08:00","updated_at":"2025-12-08T08:11:42.182946-08:00","closed_at":"2025-12-08T08:11:42.182946-08:00"}
 {"id":"opencode-swarm-plugin-679z.1","title":"Subtask 1","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:11:40.165666-08:00","updated_at":"2025-12-08T08:11:42.205856-08:00","closed_at":"2025-12-08T08:11:42.205856-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-679z.1","depends_on_id":"opencode-swarm-plugin-679z","type":"parent-child","created_at":"2025-12-08T08:11:40.165959-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-679z.2","title":"Subtask 2","description":"","status":"closed","priority":3,"issue_type":"task","created_at":"2025-12-08T08:11:40.198674-08:00","updated_at":"2025-12-08T08:11:42.232434-08:00","closed_at":"2025-12-08T08:11:42.232434-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-679z.2","depends_on_id":"opencode-swarm-plugin-679z","type":"parent-child","created_at":"2025-12-08T08:11:40.198981-08:00","created_by":"daemon"}]}
@@ -492,6 +492,12 @@
 {"id":"opencode-swarm-plugin-7vk.5","title":"Write swarm integration tests + update package.json","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T19:24:38.92166-08:00","updated_at":"2025-12-07T19:32:59.349281-08:00","closed_at":"2025-12-07T19:32:59.349281-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-7vk.5","depends_on_id":"opencode-swarm-plugin-7vk","type":"parent-child","created_at":"2025-12-07T19:24:38.921953-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-7w99","title":"Limit test bead 3","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:56:55.644213-08:00","updated_at":"2025-12-08T08:56:58.099234-08:00","closed_at":"2025-12-08T08:56:58.099234-08:00"}
 {"id":"opencode-swarm-plugin-7we","title":"Query test bead","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T19:36:06.436638-08:00","updated_at":"2025-12-07T19:36:08.567688-08:00","closed_at":"2025-12-07T19:36:08.567688-08:00"}
+{"id":"opencode-swarm-plugin-7x3pk","title":"Improve semantic memory usage patterns","description":"Fix test pollution, add auto-capture hooks, update agent prompts, and define clear memory triggers for proactive learning storage. FORCE agents to use semantic-memory and swarm mail at every opportunity.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-14T14:34:04.14035-08:00","updated_at":"2025-12-14T14:47:53.151758-08:00","closed_at":"2025-12-14T14:47:53.151758-08:00"}
+{"id":"opencode-swarm-plugin-7x3pk.1","title":"Add test isolation + monitoring/logging for memory operations","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-14T14:34:04.20286-08:00","updated_at":"2025-12-14T14:47:47.479252-08:00","closed_at":"2025-12-14T14:47:47.479252-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-7x3pk.1","depends_on_id":"opencode-swarm-plugin-7x3pk","type":"parent-child","created_at":"2025-12-14T14:34:04.204815-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-7x3pk.2","title":"Update all integration tests to use isolated collections","description":"✅ Completed: Updated all integration tests to use isolated collections.\n\n**Changes:**\n- learning.integration.test.ts: Added unique collection names with timestamps, added afterEach cleanup\n\n**Verified:**\n- storage.integration.test.ts: Already using isolated collections ✓\n- swarm-mail.integration.test.ts: Already using unique db paths ✓\n- All streams/* tests: Already using unique temp paths ✓\n- rate-limiter.integration.test.ts: Already using unique temp dirs ✓\n\n**Pattern documented in semantic-memory for future reference**","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-14T14:34:04.259594-08:00","updated_at":"2025-12-14T14:47:48.373226-08:00","closed_at":"2025-12-14T14:47:48.373226-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-7x3pk.2","depends_on_id":"opencode-swarm-plugin-7x3pk","type":"parent-child","created_at":"2025-12-14T14:34:04.260752-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-7x3pk.3","title":"Add automatic memory capture hook in swarm_complete","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-14T14:34:04.319433-08:00","updated_at":"2025-12-14T14:47:49.36759-08:00","closed_at":"2025-12-14T14:47:49.36759-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-7x3pk.3","depends_on_id":"opencode-swarm-plugin-7x3pk","type":"parent-child","created_at":"2025-12-14T14:34:04.320428-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-7x3pk.4","title":"Define MANDATORY memory triggers and swarm mail usage in AGENTS.md","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-14T14:34:04.379325-08:00","updated_at":"2025-12-14T14:47:50.635175-08:00","closed_at":"2025-12-14T14:47:50.635175-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-7x3pk.4","depends_on_id":"opencode-swarm-plugin-7x3pk","type":"parent-child","created_at":"2025-12-14T14:34:04.380061-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-7x3pk.5","title":"Audit and clean existing test pollution, document learnings","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-14T14:34:04.439992-08:00","updated_at":"2025-12-14T14:47:52.035028-08:00","closed_at":"2025-12-14T14:47:52.035028-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-7x3pk.5","depends_on_id":"opencode-swarm-plugin-7x3pk","type":"parent-child","created_at":"2025-12-14T14:34:04.440785-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-7ydd","title":"Thread link test bead","description":"[thread:test-thread-456]","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:22:18.267166-08:00","updated_at":"2025-12-08T08:22:19.958356-08:00","closed_at":"2025-12-08T08:22:19.958356-08:00"}
 {"id":"opencode-swarm-plugin-7yl8","title":"Query test bead","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T19:39:28.959766-08:00","updated_at":"2025-12-07T19:39:31.156979-08:00","closed_at":"2025-12-07T19:39:31.156979-08:00"}
 {"id":"opencode-swarm-plugin-7zvz","title":"Thread link test bead","description":"[thread:test-thread-123]","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:11:09.755947-08:00","updated_at":"2025-12-08T11:11:11.55818-08:00","closed_at":"2025-12-08T11:11:11.55818-08:00"}
@@ -700,6 +706,10 @@
 {"id":"opencode-swarm-plugin-avh","title":"Single subtask epic","description":"","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-07T19:34:53.500492-08:00","updated_at":"2025-12-07T19:34:55.104672-08:00","closed_at":"2025-12-07T19:34:55.104672-08:00"}
 {"id":"opencode-swarm-plugin-aw1tc","title":"Thread link test bead","description":"[thread:test-thread-456]","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T09:06:08.228561-08:00","updated_at":"2025-12-10T09:06:10.878323-08:00","closed_at":"2025-12-10T09:06:10.878323-08:00"}
 {"id":"opencode-swarm-plugin-ay6d","title":"Query test bead","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:14:28.622853-08:00","updated_at":"2025-12-08T08:14:31.015202-08:00","closed_at":"2025-12-08T08:14:31.015202-08:00"}
+{"id":"opencode-swarm-plugin-b0tzg","title":"Fix README + Swarm Mail docs + swarm_complete error handling","description":"1) Update README to reference Agent Mail in inspiration section but clarify our implementation is Swarm Mail with diagrams, 2) Fix swarm_complete silent failures - push errors to swarm mail for coordinator visibility, 3) Document Swarm Mail architecture based on closed PRs","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-14T14:41:44.17609-08:00","updated_at":"2025-12-14T14:47:46.049959-08:00","closed_at":"2025-12-14T14:47:46.049959-08:00"}
+{"id":"opencode-swarm-plugin-b0tzg.1","title":"Update README - Agent Mail inspiration vs Swarm Mail implementation","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-14T14:41:44.244997-08:00","updated_at":"2025-12-14T14:47:42.88356-08:00","closed_at":"2025-12-14T14:47:42.88356-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-b0tzg.1","depends_on_id":"opencode-swarm-plugin-b0tzg","type":"parent-child","created_at":"2025-12-14T14:41:44.246047-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-b0tzg.2","title":"Add error handling to swarm_complete - push failures to swarm mail","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-14T14:41:44.302057-08:00","updated_at":"2025-12-14T14:47:43.984532-08:00","closed_at":"2025-12-14T14:47:43.984532-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-b0tzg.2","depends_on_id":"opencode-swarm-plugin-b0tzg","type":"parent-child","created_at":"2025-12-14T14:41:44.304468-08:00","created_by":"daemon"}]}
+{"id":"opencode-swarm-plugin-b0tzg.3","title":"Document Swarm Mail architecture with diagrams from closed PRs","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-14T14:41:44.364356-08:00","updated_at":"2025-12-14T14:47:45.050125-08:00","closed_at":"2025-12-14T14:47:45.050125-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-b0tzg.3","depends_on_id":"opencode-swarm-plugin-b0tzg","type":"parent-child","created_at":"2025-12-14T14:41:44.365969-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-b0ydv","title":"Create TDD skill with lore from prime knowledge","description":"Created .opencode/skills/tdd/SKILL.md with RED-GREEN-REFACTOR workflow and lore from Kent Beck, Michael Feathers, Martin Fowler, and Ousterhout's counterpoint.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T09:12:37.165045-08:00","updated_at":"2025-12-13T09:12:40.904565-08:00","closed_at":"2025-12-13T09:12:40.904565-08:00"}
 {"id":"opencode-swarm-plugin-b1hf","title":"Thread link test bead","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:11:40.14326-08:00","updated_at":"2025-12-08T11:11:41.771573-08:00","closed_at":"2025-12-08T11:11:41.771573-08:00"}
 {"id":"opencode-swarm-plugin-b1wpc","title":"swarm.ts:1620-1670 - runUbsScan doesn't validate JSON structure","description":"swarm.ts:1620-1670 - runUbsScan parses JSON but doesn't validate with schema. If UBS changes output format, could return malformed data or throw cryptic errors. Suggested fix: Define Zod schema for UBS output and validate.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-12-10T09:06:33.466723-08:00","updated_at":"2025-12-10T11:56:17.052815-08:00","closed_at":"2025-12-10T11:56:17.052815-08:00"}
@@ -804,7 +814,7 @@
 {"id":"opencode-swarm-plugin-coufp","title":"Query test bead","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-14T13:58:50.06641-08:00","updated_at":"2025-12-14T13:58:54.936028-08:00","closed_at":"2025-12-14T13:58:54.936028-08:00"}
 {"id":"opencode-swarm-plugin-cppl","title":"Update test bead","description":"Updated description","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T09:09:31.130656-08:00","updated_at":"2025-12-08T09:09:33.351067-08:00","closed_at":"2025-12-08T09:09:33.351067-08:00"}
 {"id":"opencode-swarm-plugin-crcm","title":"Limit test bead 0","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:23:17.504179-08:00","updated_at":"2025-12-08T08:23:19.920645-08:00","closed_at":"2025-12-08T08:23:19.920645-08:00"}
-{"id":"opencode-swarm-plugin-cs3wl","title":"Cut release v0.21.0","description":"## Changes for v0.21.0\n\n**Fixed:**\n- Migration tests updated for 4 migrations (was hardcoded to 2)\n- All 230 tests passing\n\n**Features (from bead opencode-swarm-plugin-66ni8):**\n- Swarm recovery context (swarm_checkpoint, swarm_recover, auto-checkpoint at 25/50/75%)\n- Eval data capture (DecompositionGeneratedEvent, SubtaskOutcomeEvent, eval_records table)\n- Outcome-based scorers (fileOverlap, scopeAccuracy, timeBalance, successRate, humanAcceptance)\n- PGLite data loader for Evalite\n- JSONB parsing fix in store.ts/projections.ts\n\n**Steps:**\n1. Commit test fixes\n2. Update package.json version to 0.21.0\n3. Build\n4. Git tag\n5. Push\n6. Publish to npm","status":"in_progress","priority":0,"issue_type":"task","created_at":"2025-12-14T14:21:48.794294-08:00","updated_at":"2025-12-14T14:21:53.100526-08:00"}
+{"id":"opencode-swarm-plugin-cs3wl","title":"Cut release v0.21.0","description":"## Changes for v0.21.0\n\n**Fixed:**\n- Migration tests updated for 4 migrations (was hardcoded to 2)\n- All 230 tests passing\n\n**Features (from bead opencode-swarm-plugin-66ni8):**\n- Swarm recovery context (swarm_checkpoint, swarm_recover, auto-checkpoint at 25/50/75%)\n- Eval data capture (DecompositionGeneratedEvent, SubtaskOutcomeEvent, eval_records table)\n- Outcome-based scorers (fileOverlap, scopeAccuracy, timeBalance, successRate, humanAcceptance)\n- PGLite data loader for Evalite\n- JSONB parsing fix in store.ts/projections.ts\n\n**Steps:**\n1. Commit test fixes\n2. Update package.json version to 0.21.0\n3. Build\n4. Git tag\n5. Push\n6. Publish to npm","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-14T14:21:48.794294-08:00","updated_at":"2025-12-14T14:22:50.902471-08:00","closed_at":"2025-12-14T14:22:50.902471-08:00"}
 {"id":"opencode-swarm-plugin-csdh","title":"Ordered subtasks epic","description":"","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-08T08:25:10.806508-08:00","updated_at":"2025-12-08T08:25:12.779477-08:00","closed_at":"2025-12-08T08:25:12.779477-08:00"}
 {"id":"opencode-swarm-plugin-csdh.1","title":"First","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:25:10.846377-08:00","updated_at":"2025-12-08T08:25:12.806068-08:00","closed_at":"2025-12-08T08:25:12.806068-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-csdh.1","depends_on_id":"opencode-swarm-plugin-csdh","type":"parent-child","created_at":"2025-12-08T08:25:10.846682-08:00","created_by":"daemon"}]}
 {"id":"opencode-swarm-plugin-csdh.2","title":"Second","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T08:25:10.881406-08:00","updated_at":"2025-12-08T08:25:12.834953-08:00","closed_at":"2025-12-08T08:25:12.834953-08:00","dependencies":[{"issue_id":"opencode-swarm-plugin-csdh.2","depends_on_id":"opencode-swarm-plugin-csdh","type":"parent-child","created_at":"2025-12-08T08:25:10.881733-08:00","created_by":"daemon"}]}
@@ -1671,6 +1681,7 @@
 {"id":"opencode-swarm-plugin-r92p","title":"Limit test bead 4","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-07T19:56:42.769539-08:00","updated_at":"2025-12-07T19:56:44.896509-08:00","closed_at":"2025-12-07T19:56:44.896509-08:00"}
 {"id":"opencode-swarm-plugin-r98c","title":"Update test bead","description":"Blocked on dependency","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-08T08:14:29.141593-08:00","updated_at":"2025-12-08T08:14:31.283727-08:00","closed_at":"2025-12-08T08:14:31.283727-08:00"}
 {"id":"opencode-swarm-plugin-ra7e8","title":"Thread link test bead","description":"Important context here\n\n[thread:test-thread-789]","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:12:42.787654-08:00","updated_at":"2025-12-08T11:12:44.360438-08:00","closed_at":"2025-12-08T11:12:44.360438-08:00"}
+{"id":"opencode-swarm-plugin-rbaud","title":"Inline Swarm Mail architecture into README","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-14T14:48:15.768044-08:00","updated_at":"2025-12-14T14:49:13.602901-08:00","closed_at":"2025-12-14T14:49:13.602901-08:00"}
 {"id":"opencode-swarm-plugin-rbi7","title":"Query test bead","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:10:52.974317-08:00","updated_at":"2025-12-08T11:10:55.610719-08:00","closed_at":"2025-12-08T11:10:55.610719-08:00"}
 {"id":"opencode-swarm-plugin-rcin","title":"High priority ready bead","description":"","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-08T07:49:10.311118-08:00","updated_at":"2025-12-08T07:49:12.327386-08:00","closed_at":"2025-12-08T07:49:12.327386-08:00"}
 {"id":"opencode-swarm-plugin-rclb","title":"Bead to close","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-08T11:11:08.938269-08:00","updated_at":"2025-12-08T11:11:08.963749-08:00","closed_at":"2025-12-08T11:11:08.963749-08:00"}

package/README.md

@@ -18,9 +18,24 @@
       bzzzz...
 ```
 
-## What is this?
+## The Problem
 
-You give it a task. It breaks it into pieces. It spawns agents to work on each piece simultaneously. They coordinate so they don't step on each other. When they're done, you have working code.
+You're working with an AI coding agent. You ask it to "add OAuth authentication." It starts writing code. Five minutes later, you realize it's going down the wrong path. Or it's touching files it shouldn't. Or it's making changes that conflict with what you just did in another session.
+
+**The fundamental issue:** AI agents are single-threaded, context-limited, and have no memory of what worked before.
+
+## The Solution
+
+What if the agent could:
+
+- **Break the task into pieces** that can be worked on simultaneously
+- **Spawn parallel workers** that don't step on each other
+- **Remember what worked** and avoid patterns that failed
+- **Survive context compaction** without losing progress
+
+That's what Swarm does.
+
+## How It Works
 
 ```
                             "Add OAuth"
@@ -28,62 +43,85 @@ You give it a task. It breaks it into pieces. It spawns agents to work on each p
                                  ▼
                     ┌────────────────────────┐
                     │      COORDINATOR       │
-                    │  picks strategy, splits│
+                    │                        │
+                    │  1. Query CASS:        │
+                    │     "How did we solve  │
+                    │      this before?"     │
+                    │                        │
+                    │  2. Pick strategy:     │
+                    │     file-based?        │
+                    │     feature-based?     │
+                    │     risk-based?        │
+                    │                        │
+                    │  3. Break into pieces  │
                     └────────────────────────┘
                                  │
            ┌─────────────────────┼─────────────────────┐
            ▼                     ▼                     ▼
     ┌─────────────┐       ┌─────────────┐       ┌─────────────┐
     │  Worker A   │       │  Worker B   │       │  Worker C   │
+    │             │       │             │       │             │
     │ auth/oauth  │       │ auth/session│       │ auth/tests  │
     │   🔒 files  │       │   🔒 files  │       │   🔒 files  │
+    │             │       │             │       │             │
+    │ "I need     │──────►│ "Got it,    │       │ "Running    │
+    │  session    │       │  here's the │       │  tests..."  │
+    │  types"     │       │  interface" │       │             │
     └─────────────┘       └─────────────┘       └─────────────┘
+           │                     │                     │
            │                     │                     │
            └─────────────────────┼─────────────────────┘
+                                 │
                                  ▼
-                         working code
+                    ┌────────────────────────┐
+                    │    LEARNING SYSTEM     │
+                    │                        │
+                    │  "File-based split     │
+                    │   worked well for      │
+                    │   auth - 3 workers,    │
+                    │   15 min, 0 conflicts" │
+                    │                        │
+                    │  Next time: use this   │
+                    │  pattern again         │
+                    └────────────────────────┘
 ```
 
-The plugin learns from outcomes - what decomposition strategies work, which patterns fail, how long things take. Over time, it gets better at breaking down tasks.
+### The Flow
 
-## Install
+1. **You give it a task**: `/swarm "Add OAuth authentication"`
 
-```bash
-npm install -g opencode-swarm-plugin@latest
-swarm setup
-```
+2. **It queries history**: "Have we done something like this before?" (via CASS - cross-agent session search)
 
-## Usage
+3. **It picks a strategy**:
+   - **File-based**: "Split by directory structure" (good for refactoring)
+   - **Feature-based**: "Split by vertical slices" (good for new features)
+   - **Risk-based**: "Tests first, then implementation" (good for bug fixes)
+   - **Research-based**: "Explore before committing" (good for unknowns)
 
-```
-/swarm "Add user authentication with OAuth"
-```
+4. **It breaks the work into beads** (git-backed issues):
 
-## How it decides to split work
+   ```
+   Epic: Add OAuth
+   ├─ Bead 1: OAuth provider integration (src/auth/oauth.ts)
+   ├─ Bead 2: Session management (src/auth/session.ts)
+   └─ Bead 3: Integration tests (tests/auth/)
+   ```
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     STRATEGY SELECTION                          │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  "refactor auth"  ──────►  FILE-BASED                          │
-│  "migrate to v2"           Group by directory structure         │
-│  "rename all X"            Minimize cross-directory deps        │
-│                                                                 │
-│  "add feature"    ──────►  FEATURE-BASED                       │
-│  "implement X"             Vertical slices (data→logic→UI)      │
-│  "build new"               Keep related components together     │
-│                                                                 │
-│  "fix bug"        ──────►  RISK-BASED                          │
-│  "security issue"          Tests FIRST                          │
-│  "critical"                Isolate risky changes                │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
+5. **It spawns parallel workers**:
+   - Each worker reserves its files (no conflicts)
+   - Workers coordinate via Swarm Mail (actor-model messaging)
+   - Progress is checkpointed at 25%, 50%, 75%
+
+6. **It learns from the outcome**:
+   - Fast + success = good signal
+   - Slow + errors = bad signal
+   - Patterns that fail >60% of the time get auto-inverted
 
-## What survives when context dies
+## What Makes It Different
 
-Swarms used to die when OpenCode compacted context. Not anymore.
+### It Survives Context Death
+
+OpenCode compacts context when it gets too long. Swarms used to die when this happened. Not anymore.
 
 ```
      Session 1                    Context                   Session 2
@@ -97,11 +135,31 @@ Swarms used to die when OpenCode compacted context. Not anymore.
 └─────────────────┘                                   └─────────────────┘
 ```
 
-The plugin checkpoints at 25%, 50%, and 75% progress. Files reserved, progress tracked, context preserved.
+**Checkpoints capture:**
+
+- Which subtasks are done/in-progress/pending
+- File reservations (who owns what)
+- Shared context for workers
+- Progress percentage
+
+**Recovery restores:**
+
+- Swarm state from last checkpoint
+- File locks (prevents conflicts)
+- Worker context (what they were doing)
+
+All stored in PGLite (embedded Postgres) - no external servers, survives across sessions.
+
+### It Learns From Outcomes
 
-## Learning
+Every swarm completion records:
 
-The plugin tracks outcomes and adjusts over time:
+- Duration (how long did it take?)
+- Errors (how many retries?)
+- Files touched (did scope match prediction?)
+- Success (did tests pass? were changes accepted?)
+
+This feeds back into the decomposition strategy:
 
 ```
                     ┌─────────────────────────────────┐
@@ -126,18 +184,188 @@ The plugin tracks outcomes and adjusts over time:
                     unless patterns are revalidated
 ```
 
-## Skills
+**Pattern maturity lifecycle:**
+
+- `candidate` → new pattern, low confidence
+- `established` → validated 3+ times
+- `proven` → 10+ successes (gets 1.5x weight in future decompositions)
+- `deprecated` → >60% failure rate (auto-inverted to anti-pattern)
+
+**Confidence decay:** Patterns fade over 90 days unless revalidated. Prevents stale knowledge from dominating.
+
+### Swarm Mail: Actor-Model Coordination
+
+Workers don't just run in parallel - they coordinate via **Swarm Mail**, an event-sourced actor model built on local-first primitives.
+
+**What makes Swarm Mail different from traditional agent messaging:**
+
+- **Actor model over durable streams** - DurableMailbox, DurableLock, DurableDeferred (inspired by Electric SQL patterns)
+- **Local-first with PGlite** - embedded Postgres, no external servers, survives across sessions
+- **Event-sourced coordination** - append-only log, materialized views, full audit trail
+- **Context-safe by design** - hard caps on inbox (max 5 messages), thread summarization, body-on-demand
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                      SWARM MAIL                              │
+│                                                              │
+│  Worker A: "I need the SessionUser type"                    │
+│            ↓                                                 │
+│  Worker B: "Here's the interface:"                          │
+│            interface SessionUser {                           │
+│              id: string                                      │
+│              email: string                                   │
+│              roles: string[]                                 │
+│            }                                                 │
+│            ↓                                                 │
+│  Worker A: "Got it, implementing OAuth flow now"            │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**File reservations** prevent conflicts:
+
+- Worker A reserves `src/auth/oauth.ts` (exclusive via DurableLock)
+- Worker B tries to reserve it → blocked
+- Worker B waits or works on something else
+
+**Inbox limits** prevent context bloat:
+
+- Max 5 messages per fetch (headers only)
+- Read individual message bodies on demand
+- Thread summarization for long conversations
+
+All coordination state survives context compaction and session restarts.
+
+#### Architecture: 3-Tier Stack
+
+Swarm Mail is built on **Durable Streams primitives** (inspired by Kyle Matthews' [Electric SQL patterns](https://x.com/kylemathews/status/1999896667030700098)):
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     SWARM MAIL STACK                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  TIER 3: COORDINATION                                       │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │  ask<Req, Res>() - Request/Response (RPC-style)       │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                          │                                  │
+│  TIER 2: PATTERNS        ▼                                  │
+│  ┌─────────────────┐  ┌─────────────────┐                  │
+│  │ DurableMailbox  │  │  DurableLock    │                  │
+│  │ Actor Inbox     │  │  File Mutex     │                  │
+│  └─────────────────┘  └─────────────────┘                  │
+│          │                    │                             │
+│  TIER 1: PRIMITIVES           ▼                             │
+│  ┌─────────────────┐  ┌─────────────────┐                  │
+│  │ DurableCursor   │  │ DurableDeferred │                  │
+│  │ Checkpointed    │  │ Distributed     │                  │
+│  │ Reader          │  │ Promise         │                  │
+│  └─────────────────┘  └─────────────────┘                  │
+│                          │                                  │
+│  STORAGE                 ▼                                  │
+│  ┌───────────────────────────────────────────────────────┐  │
+│  │      PGLite (Embedded Postgres) + Migrations          │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Tier 1 - Primitives:**
+
+- **DurableCursor** - Positioned event stream consumption with checkpointing (exactly-once)
+- **DurableDeferred** - URL-addressable distributed promises for async coordination
+- **DurableLock** - CAS-based mutual exclusion for file reservations (TTL + retry/backoff)
+
+**Tier 2 - Patterns:**
+
+- **DurableMailbox** - Actor inbox with typed envelopes (sender, replyTo, payload)
+- File reservation protocol built on DurableLock
+
+**Tier 3 - Coordination:**
+
+- **ask()** pattern - Synchronous-style RPC over async streams (creates DurableDeferred, appends to mailbox, returns promise)
+
+#### Message Flow Example
+
+```
+Agent A                    Event Stream                Agent B
+   │                            │                         │
+   │  ask("get SessionUser")    │                         │
+   ├───────────────────────────>│                         │
+   │  (creates deferred)        │                         │
+   │                            │   consume event         │
+   │                            ├────────────────────────>│
+   │                            │                         │
+   │                            │   reply to deferred     │
+   │                            │<────────────────────────┤
+   │  await deferred.value      │                         │
+   │<───────────────────────────┤                         │
+   │                            │                         │
+   │  SessionUser interface     │                         │
+   │                            │                         │
+```
+
+**Why this matters:**
+
+- No external servers (Redis, Kafka, NATS) - just PGlite
+- Full audit trail - every message is an event
+- Resumable - cursors checkpoint position, survive crashes
+- Type-safe - Effect-TS with full inference
+
+> **Architecture deep-dive:** See [Swarm Mail Architecture](docs/swarm-mail-architecture.md) for complete implementation details, database schemas, and Effect-TS patterns.
+
+### It Has Skills
 
 Skills are knowledge packages agents can load. Teach once, use everywhere.
 
+```typescript
+skills_use((name = "testing-patterns")); // Load Feathers seams + Beck's 4 rules
+skills_use((name = "swarm-coordination")); // Load swarm workflow patterns
 ```
-skills_use(name="testing-patterns")    # Load testing knowledge
-skills_use(name="swarm-coordination")  # Load swarm workflow
+
+**Bundled skills:**
+
+- `testing-patterns` - 25 dependency-breaking techniques, characterization tests
+- `swarm-coordination` - Multi-agent decomposition, file reservations
+- `cli-builder` - Argument parsing, help text, subcommands
+- `system-design` - Architecture decisions, module boundaries
+- `learning-systems` - Confidence decay, pattern maturity
+
+**Create your own:**
+
+```bash
+swarm init  # Creates .opencode/skills/ in project
 ```
 
-Bundled: `cli-builder`, `learning-systems`, `swarm-coordination`, `system-design`, `testing-patterns`, `skill-creator`
+Skills can include:
+
+- Step-by-step workflows
+- Code examples
+- Reference documentation
+- Executable scripts
 
-Create your own in `.opencode/skills/` or `~/.config/opencode/skills/`.
+## Install
+
+```bash
+npm install -g opencode-swarm-plugin@latest
+swarm setup
+```
+
+## Usage
+
+```bash
+/swarm "Add user authentication with OAuth"
+```
+
+The coordinator will:
+
+1. Query CASS for similar past tasks
+2. Select decomposition strategy
+3. Break into subtasks (beads)
+4. Spawn parallel workers
+5. Track progress with checkpoints
+6. Record outcome for learning
 
 ## Architecture
 
@@ -151,29 +379,64 @@ Everything runs in-process. No external servers.
                                 ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │  DECOMPOSITION         strategy selection, subtask creation     │
+│                        (queries CASS, semantic memory)          │
 └─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │  BEADS                 git-backed issues for each subtask       │
+│                        (atomic epic + subtasks creation)        │
 └─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
 ┌─────────────────────────────────────────────────────────────────┐
-│  SWARM MAIL            agent coordination, file reservations    │
+│  SWARM MAIL            actor-model coordination (local-first)   │
+│                        (DurableMailbox, DurableLock, PGlite)    │
 └─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │  PGLITE                embedded postgres, event-sourced state   │
+│                        (append-only log, materialized views)    │
 └─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │  LEARNING              outcomes feed back into decomposition    │
+│                        (confidence decay, pattern maturity)     │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
+### Event Sourcing
+
+All state is stored as an append-only event log:
+
+```
+Event Log (PGLite)
+├─ agent_registered      → Agent joins swarm
+├─ message_sent          → Agent-to-agent communication
+├─ file_reserved         → Exclusive file lock acquired
+├─ file_released         → Lock released
+├─ swarm_checkpointed    → Progress snapshot saved
+├─ decomposition_generated → Task broken into subtasks
+└─ subtask_outcome       → Worker completion result
+
+Materialized Views (derived from events)
+├─ agents                → Active agents per project
+├─ messages              → Agent inbox/outbox
+├─ file_reservations     → Current file locks
+└─ eval_records          → Outcome data for learning
+```
+
+**Why event sourcing?**
+
+- **Audit trail** - full history of what happened
+- **Replay** - reconstruct state from events
+- **Debugging** - see exactly what went wrong
+- **Learning** - analyze outcomes over time
+
+See the [Swarm Mail Architecture](docs/swarm-mail-architecture.md) section above for details on the durable primitives (DurableCursor, DurableDeferred, DurableLock, DurableMailbox) and how they enable exactly-once processing, request/response patterns, and actor coordination.
+
 ## Dependencies
 
 | Required                                     | Optional                                                                                      |
@@ -186,7 +449,7 @@ Run `swarm doctor` to check status.
 
 ## CLI
 
-```
+```bash
 swarm setup     # Install and configure
 swarm doctor    # Check dependencies
 swarm init      # Initialize beads in project
@@ -197,17 +460,19 @@ swarm config    # Show config file paths
 
 ```bash
 bun install
-bun test
+bun test                # Unit tests (230 tests)
+bun run test:integration # Integration tests
 bun run build
 ```
 
 ## Credits
 
-Built on ideas from:
+**Inspiration & Core Ideas:**
 
-- [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) - multi-agent coordination patterns
-- [Superpowers](https://github.com/obra/superpowers) - verification patterns and skill architecture
-- [Electric SQL](https://electric-sql.com) - durable streams and event sourcing
+- [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) - **THE INSPIRATION** for multi-agent coordination. Swarm Mail is our implementation built on actor-model primitives (DurableMailbox, DurableLock) with local-first PGlite and event sourcing.
+- [Superpowers](https://github.com/obra/superpowers) - verification patterns, Socratic planning, skill architecture
+- [Electric SQL](https://electric-sql.com) - durable streams and event sourcing patterns that power Swarm Mail
+- [Evalite](https://evalite.dev) - outcome-based evaluation framework for learning systems
 
 ## License