Flow Mesh — Sync Grid
Definitive matrix of what syncs where. Every cell verified against source code + live tests. Principle: Any field change on ANY surface → propagates to ALL other surfaces. Most recent action is the anchor. Last updated: 2026-02-20 10:25 PST
2026-10-01 authority correction. The Mesh DB row previously read "Source of truth", which contradicted TWO-WAY-TASKS.md ("Beads is the local truth") and the master gap plan. Corrected below. No sync behavior changed — this was a wording defect that misstated where authority lives. Authority boundary is now stated once, canonically, in ../AGENTS.md#authority-boundary-read-this-first. The per-cell verification claim still covers the 2026-02-20 matrix below it, not this correction.
Domains
| Mesh DB |
Integration state + materialized projection — NOT task truth |
SQLite (work_items = projection view, event_ledger = durable history, work_item_links = cross-surface identity map) |
| Asana |
Project tracker; owner of owner/team engineering history |
REST API v1.0 (PAT auth) |
| Discord |
Chat/collaboration; delivery is a projection, the message is not state |
REST API v10 (Bot token) |
| Beads |
Local git-based tracking; the local task truth |
bd CLI (.beads/ repos) |
| CLI |
Human/agent interface |
mesh task create/update/close/delete |
Field Sync Matrix
Every field that changes anywhere is pushed everywhere else.
| Title |
✅ snapshot diff |
✅ name |
✅ message + thread rename |
✅ --title |
--title |
| Description |
✅ snapshot diff |
✅ notes |
✅ message |
✅ --append-notes |
--note |
| Status |
✅ completed flag |
✅ completed |
✅ message + ✅ thread prefix |
✅ --status |
--status |
| Assignee |
✅ GID + Name |
✅ assignee (GID) |
✅ message |
✅ --assignee |
--assignee |
| Due Date |
✅ due_on |
✅ due_on (set/clear) |
✅ message |
✅ --due |
--due |
| Priority |
— (custom field) |
— |
✅ message |
✅ -p |
--priority |
| Comments |
✅ stories poll |
✅ create story |
✅ send message |
✅ bd comments add |
via events |
CRUD Operations Grid
Create Task
| Asana |
✅ Auto |
— |
✅ Thread (rich) |
✅ bd create |
| Discord |
✗ |
✗ |
— |
✗ |
| Beads |
✅ pollBeadsCRUD |
✅ Projector |
✅ Projector |
— |
| CLI / UI |
✅ Direct |
✅ Task (all fields) |
✅ Thread (all fields) |
✅ bd create |
- Asana → Mesh: Poller detects new tasks, creates
work_items with ALL fields (title, description, status, assignee, due_date)
- Asana → Discord: Forum thread with rich initial message (description, status, priority, assignee, due date)
- Asana → Beads:
bd create with title, priority, assignee, due date
- Beads → Mesh:
pollBeadsCRUD runs bd list --json, snapshot-diffs to detect new beads → creates work_items + events
- Beads → Asana + Discord: Projector picks up beads-originated events and syncs to Asana + Discord
- CLI → All:
mesh task create writes DB, projector creates Asana task + Discord thread + bead — all with full field payloads
- Discord cannot create tasks inbound (Discord threads are chat, not structured tasks)
Update Task (any field)
| Asana |
✅ All fields |
— |
✅ Message + rename |
✅ bd update |
| Discord |
✗ |
✗ |
— |
✗ |
| Beads |
✅ pollBeadsCRUD |
✅ Projector |
✅ Projector |
— |
| CLI / UI |
✅ All fields |
✅ PUT (all fields) |
✅ Message + rename |
✅ bd update |
- Asana → Mesh: Snapshot comparison detects ALL changes: title, description, status (re-open), assignee, due_date
- Asana → Discord: Human-readable message with labeled fields ("Title → X", "Due Date → Y") + thread rename on title change
- Asana → Beads:
bd update with --title, --append-notes, --status, --assignee, --due, -p
- Beads → Mesh:
pollBeadsCRUD snapshot-diffs title, status, priority changes → update events
- Beads → Asana + Discord: Projector picks up beads update events and syncs
- CLI → Asana: PUT /tasks/{gid} with: name, notes, completed, assignee (GID, set/clear), due_on (set/clear)
- CLI → Discord: Labeled field messages + thread rename
- CLI → Beads: All bd update flags
Complete / Uncomplete Task
| Asana (complete) |
✅ status=done |
— |
✅ "✅ Completed" + thread prefix |
✅ bd close |
| Asana (uncomplete) |
✅ status=in_progress |
— |
✅ "Status → in_progress" |
✅ bd update --status |
| Discord |
✗ |
✗ |
— |
✗ |
| Beads |
✅ pollBeadsCRUD |
✅ Projector |
✅ Projector |
— |
| CLI / UI |
✅ status=done |
✅ completed:true |
✅ "✅ Completed" + thread prefix |
✅ bd close |
- Complete: Asana
completed:true → status=done in DB → projector sends to Discord (✅ prefix on thread name) + Beads (bd close)
- Uncomplete: Asana
completed:false → status=in_progress → projector sends update to Discord + Beads
- Beads → Mesh:
pollBeadsCRUD detects status→"closed" → EventComplete
- CLI:
mesh task close sets status=done, projector cascades to all three
Delete Task
| Asana |
✅ Event logged |
— |
✅ "🗑️ Deleted" + archive |
✅ bd delete |
| Discord |
✗ |
✗ |
— |
✗ |
| Beads |
✅ pollBeadsCRUD |
✅ Projector |
✅ Projector |
— |
| CLI |
✅ Soft delete |
✅ DELETE /tasks |
✅ Archive thread |
✅ bd delete |
- Asana → Mesh: Poller detects task missing from project (set difference) → delete event
- Asana → Discord: Projector sends delete message + archives thread
- Asana → Beads: Projector runs
bd delete <id> --force
- Beads → Mesh:
pollBeadsCRUD detects bead missing from bd list → EventDelete
- CLI:
mesh task delete --force soft-deletes work_item, projector cascades to all three
| Asana |
✅ Event |
— |
✅ Mirror |
✅ bd comments add |
| Discord |
✅ Event |
✅ Story |
— |
✅ bd comments add |
| Beads |
✅ Event |
✅ Story |
✅ Message |
— |
| CLI / UI |
✅ Event |
✅ Story |
✅ Message |
✅ bd comments add |
- Asana → Discord + Beads: Poller reads stories, projector sends to thread + beads
- Discord → Asana + Beads: Poller reads messages (human only, skips bots), projector creates story + beads comment
- Beads → Asana + Discord: Poller reads .beads/events/, projector sends to both
- Loop prevention: "Mirrored by Mesh" footer in all outbound, filtered on inbound
What Does NOT Sync (Honest Gaps)
| Discord → Mesh (CRUD) |
Discord threads are chat, not structured tasks |
Use CLI or Asana for task CRUD |
| Asana custom fields |
Not in standard Task struct; priority is a custom field in Asana |
Set priority via CLI (--priority P1) — syncs to Discord + Beads |
| Webhook/realtime (Asana/Beads) |
Asana + Beads inbound is polling (5-15s). Discord intelligence uses Gateway WebSocket. |
Per-mesh interval tuning available |
| Discord thread → Asana rename |
No structured inbound from Discord |
Rename in Asana or CLI, it flows to Discord |
| Asana sections → status |
Sections exist but not mapped to mesh status |
Status tracked via completed flag; use CLI for richer statuses |
Loop Prevention
Asana story → [contains "Mirrored by Mesh"?] → SKIP
→ INGEST → Projector → Discord + Beads
↓
Discord message → [author.bot == true?] → SKIP
→ [contains "Mirrored by Mesh"?] → SKIP
→ INGEST → Projector → Asana + Beads
Beads event → [contains "Mirrored by Mesh"?] → SKIP
→ INGEST → Projector → Asana + Discord
Projector ALWAYS skips the SOURCE system (won't echo Asana event back to Asana)
Data Flow Diagram
┌─────────────────────────────────────────┐
│ MESH ENGINE │
│ │
┌────────┐ │ ┌──────────┐ ┌───────────┐ │ ┌─────────┐
│ ASANA │◄─15s─┤ │ Asana │ │ Event │ ├─────►│ ASANA │
│ (read) │ │ │ Poller │───►│ Ledger │───► │ │ (write) │
└────────┘ │ └──────────┘ │ │ Proj- │ └─────────┘
│ │ (SQLite) │ ector │
┌────────┐ │ ┌──────────┐ │ │ │ ┌─────────┐
│DISCORD │◄─15s─┤ │ Discord │───►│ │───► ├─────►│DISCORD │
│ (read) │ │ │ Poller │ │ │ │ │ (write) │
└────────┘ │ └──────────┘ │ │ │ └─────────┘
│ │ │ │
┌────────┐ │ ┌──────────┐ │ │ │ ┌─────────┐
│ BEADS │◄──5s─┤ │ Beads │───►│ │───► ├─────►│ BEADS │
│ (.beads│ │ │ Watcher │ └───────────┘ │ │(bd CLI) │
│ /evts) │ │ └──────────┘ ▲ │ └─────────┘
└────────┘ │ │ │
│ ┌────┴────┐ │
│ │ CLI / │ │
│ │ Web UI │ │
│ └─────────┘ │
└─────────────────────────────────────────┘
Polling Intervals
| Beads watcher |
5s |
— (filesystem) |
0 |
| Asana task poller |
15s |
poll_interval_seconds |
1 GetTasks + N GetStories |
| Discord msg poller |
15s |
poll_interval_seconds |
1 GetMessages per thread |
| Projector |
1s |
sync_interval_seconds |
0 (DB only) |
Set per-mesh overrides in Mesh Detail → Poll / Sync Intervals. 0 = use global default. Any positive value overrides.
Live Test Evidence
| Asana → Discord + Beads (create) |
2026-02-19 23:15 PST |
✅ New task auto-created thread + bead |
| Asana → Discord (rename) |
2026-02-20 01:10 PST |
✅ "📝 Updated • Title → Build admin dashboard" |
| Asana → Discord (complete) |
2026-02-20 01:12 PST |
✅ "✅ Completed" message |
| Asana → Discord (uncomplete) |
2026-02-20 10:20 PST |
✅ "Status → in_progress" message |
| Asana → Discord (delete) |
2026-02-20 01:15 PST |
✅ "🗑️ Deleted" + thread archived |
| Asana → Discord (assignee) |
2026-02-20 01:16 PST |
✅ "assignee → Verious" |
| Asana → Discord + Beads (description) |
2026-02-20 10:23 PST |
✅ Both updated |
| Asana → Discord (due date) |
2026-02-20 10:23 PST |
✅ "Due Date → 2026-03-15" |
| Asana → Discord (comment) |
2026-02-20 09:37 PST |
✅ Mirror with footer |
| Asana → Beads (comment) |
2026-02-20 10:11 PST |
✅ bd comments add with mirror footer |
| CLI → Asana + Discord (create) |
2026-02-19 21:30 PST |
✅ 3 tasks synced |
| CLI → Asana (status) |
2026-02-19 22:45 PST |
✅ completed:true |
| CLI → Discord (comment) |
2026-02-19 22:50 PST |
✅ Message in thread |
| Discord → Asana (comment) |
2026-02-20 09:40 PST |
✅ Story created (human messages only) |
| Beads → Asana + Discord (comment) |
2026-02-20 09:42 PST |
✅ Both received |
Generated from the Flow Mesh repository by scripts/build-docs-site.sh.
If a page is wrong here, the file it was rendered from is wrong.