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

Domain Role Interface
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.

Field Asana → Mesh Mesh → Asana Discord (display) Beads (bd) CLI flags
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

From ↓ · To → Mesh DB Asana Discord Beads
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)

From ↓ · To → Mesh DB Asana Discord Beads
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

From ↓ · To → Mesh DB Asana Discord Beads
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

From ↓ · To → Mesh DB Asana Discord Beads
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

Comment / Message

From ↓ · To → Mesh DB Asana Discord Beads
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)

Gap Why Workaround
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

Poller Default Per-Mesh Override API Calls/Cycle
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

Test Timestamp Result
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.