hive.colony-progress-tracker

Operational Protocol: Colony Progress Tracker

Applies when your spawn message has db_path: and colony_id: fields. The DB is your durable working memory — tells you what's done, what to skip, which SOP gates you owe.

Access via terminal_exec running sqlite3 "<db_path>" "...". Tables: tasks (queue), steps (per-task decomposition), sop_checklist (hard gates).

Claim: assigned task (check this FIRST)

If your spawn message includes a task_id: field, the queen pre-assigned a specific row to you. Claim that row by id — do not use the generic next-pending pattern below:

sqlite3 "<db_path>" <<'SQL'
UPDATE tasks SET status='claimed', worker_id='<worker-id>',
  claim_token=lower(hex(randomblob(8))),
  claimed_at=datetime('now'), updated_at=datetime('now')
WHERE id='<task_id>' AND status='pending'
RETURNING id, goal, payload;
SQL

Empty output → another worker raced you or the row is already done. Stop and report. Non-empty → that row is yours, proceed to "Load the plan".

Claim: next pending (fallback when no task_id is assigned)

If your spawn message did NOT include task_id: — you are a generic fan-out worker racing on a shared queue. Use the generic next-pending claim:

sqlite3 "<db_path>" <<'SQL'
UPDATE tasks SET status='claimed', worker_id='<worker-id>',
  claim_token=lower(hex(randomblob(8))),
  claimed_at=datetime('now'), updated_at=datetime('now')
WHERE id=(SELECT id FROM tasks WHERE status='pending'
  ORDER BY priority DESC, seq, created_at LIMIT 1)
RETURNING id, goal, payload;
SQL

Empty output → queue drained, exit. Otherwise the returned id is yours. Never SELECT-then-UPDATE — races.

Load the plan

sqlite3 "<db_path>" "SELECT seq, id, title, status FROM steps WHERE task_id='<task-id>' ORDER BY seq;"
sqlite3 "<db_path>" "SELECT key, description, required, done_at FROM sop_checklist WHERE task_id='<task-id>';"

Skip any step where status='done'. That's the point — don't redo completed work.