Task Board + Ledger Architecture
> Deterministic multi-agent task system with evidence-gated completion, terminal state locks, and append-only audit ledger.
Full Public Reader
Task Board + Ledger Architecture
> Deterministic multi-agent task system with evidence-gated completion, terminal state locks, and append-only audit ledger.
---
Hard Rules (enforced in database)
1. Every task has a UUID (`mac_tasks.id`)
2. Every task lives in Supabase `mac_tasks` table
3. DONE requires real proof — output (>50 chars), commit hash, or verified URL
4. Placeholder URLs are rejected (localhost, [ip], example.com)
5. Parent tasks cannot close while children are still open
6. Once a task is DONE, it stays DONE — no status regression
7. Every state transition is logged to append-only `task_events` ledger
---
Execution Path
intake → classify → store → claim → execute → complete (with evidence)┌─────────────┐ ┌──────────────┐ ┌───────────┐
│ Discord │────▶│ Classifier │────▶│ Supabase │
│ SMS │ │ (model + │ │ mac_tasks │
│ Telegram │ │ type + │ │ INSERT │
│ Nexus UI │ │ platform) │ │ pending │
└─────────────┘ └──────────────┘ └─────┬─────┘
│
┌──────────────────────┘
▼
┌──────────────┐ ┌──────────────┐
│ Agent Pool │────▶│ Execution │
│ (poll+claim) │ │ Claude/ │
│ status: │ │ Gemini/ │
│ running │ │ Codex │
└──────────────┘ └──────┬───────┘
│
┌─────────────────────┘
▼
┌───────────────────────┐
│ complete_task_with_ │
│ evidence() RPC │
│ │
│ ┌─ Evidence Gate ───┐ │
│ │ output > 50 chars │ │
│ │ commit hash │ │
│ │ verified URL │ │
│ └──────────────────┘ │
│ ┌─ Dependency Gate ┐ │
│ │ all children │ │
│ │ complete/failed │ │
│ └──────────────────┘ │
│ ┌─ Terminal Lock ──┐ │
│ │ not already done │ │
│ └──────────────────┘ │
└───────────┬───────────┘
Pass ✓ │ Block ✗
┌───────────┴───────────┐
▼ ▼
┌────────────┐ ┌────────────┐
│ COMPLETE │ │ BLOCKED │
│ terminal │ │ logged to │
│ locked │ │ task_events│
└────────────┘ └────────────┘---
Enforcement Path
status change → terminal lock → evidence gate → dependency gate → audit log┌──────────┐ status ┌──────────────────┐
│ Agent │──────────▶│ BEFORE trigger │
│ UPDATE │ │ enforce_terminal │
└──────────┘ │ _state() │
└────────┬─────────┘
Pass │ Block (revert NEW.status)
▼
┌──────────────────┐
│ AFTER trigger │
│ log_task_event() │
└────────┬─────────┘
▼
┌──────────────────┐
│ task_events │
│ (append-only) │
│ INSERT only │
└──────────────────┘---
State Tables
mac_tasks (materialized state)
| Column | Type | Purpose |
|---|---|---|
| `id` | uuid | Primary key |
| `task_content` | text | The task prompt |
| `project_path` | text | Target project directory |
| `source` | text | Origin: discord, sms, telegram, api |
| `status` | text | pending → running → complete/failed |
| `claimed_by` | text | Device that claimed (mac1, mac4, cloud-vm) |
| `parent_task_id` | uuid | FK to parent (for subtasks) |
| `team_id` | uuid | Team grouping ID |
| `team_role` | text | team_lead, worker, aggregator |
| `model_preference` | text | Requested model |
| `model_used` | text | Actual model that responded |
| `output` | text | Task result |
| `commit_hash` | text | Git evidence |
| `evidence_url` | text | URL evidence |
| `evidence_type` | text | output, commit, url, or multiple |
| `exit_code` | int | Process exit code |
| `attempt_count` | int | Current attempt number |
| `max_attempts` | int | Max retries before terminal fail |
| `error_log` | text | Append-only failure log |
| `timeout_at` | timestamptz | Auto-reclaim deadline |
| `relay_from` | text | Previous device (on handoff) |
| `relay_to` | text | Target device (on handoff) |
| `relay_reason` | text | timeout, manual, capability |
| `admissibility_token` | text | HMAC policy compliance proof |
| `discord_thread_id` | text | Linked Discord thread |
| `result_delivered` | bool | Prevents duplicate delivery |
| Timestamps | timestamptz | created_at, started_at, completed_at |
task_events (append-only audit ledger)
| Column | Type | Purpose |
|---|---|---|
| `id` | uuid | Event ID |
| `task_id` | uuid | FK to mac_tasks |
| `event_type` | text | created, claimed, completed, failed, reclaimed, evidence_blocked, terminal_blocked, dependency_blocked |
| `from_status` | text | Previous status |
| `to_status` | text | New status |
| `agent_id` | text | Who triggered the transition |
| `evidence` | jsonb | Evidence payload (has_output, has_commit, has_url) |
| `metadata` | jsonb | Context (relay info, block reasons, etc.) |
| `created_at` | timestamptz | When the event occurred |
RLS: SELECT + INSERT only. No UPDATE. No DELETE. Ledger is immutable.
---
Status Transitions
┌──────────┐
│ pending │
└────┬─────┘
│ claim
┌────▼─────┐
┌────── │ running │ ──────┐
│ └────┬─────┘ │
│ timeout │ complete │ fail
│ (reclaim) │ (evidence) │
│ │ │
┌─────▼────┐ ┌────▼─────┐ ┌────▼─────┐
│ pending │ │ complete │ │ failed │
│ (retry) │ │ TERMINAL │ │ │
└──────────┘ └──────────┘ └──────────┘Terminal states: `complete` (always), `failed` (when attempt_count >= max_attempts)
---
Triggers
| Trigger | Timing | Function | Purpose |
|---|---|---|---|
| `trg_enforce_terminal_state` | BEFORE UPDATE | `enforce_terminal_state()` | Blocks status regression on complete/exhausted-failed tasks |
| `trg_log_task_event` | AFTER INSERT/UPDATE | `log_task_event()` | Records every transition to task_events ledger |
---
RPC Functions
`complete_task_with_evidence(task_id, output, commit_hash, evidence_url, agent_id)`
Gated completion with 4 checks:
1. Terminal lock: Already complete? Reject.
2. Evidence gate: At least one of output (>50 chars), commit hash (>=7 chars), or valid URL.
3. URL validation: Reject localhost, [ip], example.com, /smoke/, /remediate/.
4. Dependency gate: If parent task, all children must be complete or failed.
Returns `{success: true, task_id, evidence_type, evidence_count}` or `{success: false, error: "reason"}`.
`reclaim_timeout_tasks(caller_device)`
Auto-reclaims stalled tasks where `timeout_at < NOW()`. Resets to pending, increments attempt_count, logs relay chain.
---
Config Reference
| Variable | Source | Default |
|---|---|---|
| `SUPABASE_URL` | env | — |
| `SUPABASE_ANON_KEY` | env | — |
| `SUPABASE_SERVICE_KEY` | env | — |
| Task table | Supabase | `mac_tasks` |
| Event table | Supabase | `task_events` |
| Thread table | Supabase | `discord_threads` |
| Device table | Supabase | `mesh_devices` |
---
Smoke Test Results (2026-03-01)
| Test | Input | Expected | Actual | Status |
|---|---|---|---|---|
| A | Complete with no evidence | evidence_blocked | evidence_blocked | PASS |
| B | Complete with valid output (>50 chars) | success, type=output | success, type=output | PASS |
| C | Regress complete → running | terminal_blocked, status stays complete | terminal_blocked, status=complete | PASS |
| D | Parent complete with open child | dependency_blocked (1 open) | dependency_blocked (1 open) | PASS |
| E | Parent complete after all children done | success, type=multiple | success, type=multiple (3 evidence) | PASS |
| F | Complete with localhost URL | evidence_blocked (placeholder) | evidence_blocked (placeholder) | PASS |
| G | Audit trail check | All transitions logged | 11 events, all correct | PASS |
Promotion Decision
Promote into a technical note or architecture paper with implementation anchors.
Source Anchor
Comp-Core/docs/TASK-ARCHITECTURE.md
Detected Structure
Method · Evaluation · Architecture