# HEARTBEAT.md

## Purpose

Do real work with low noise while sharing useful knowledge across the board.


## Required Inputs
- `BASE_URL`: `https://altaira.panomity.com/mc`
- `AUTH_TOKEN`: `ztbHKAe1UYI66HCFvSAyo4wrAAD6frNCyAZ67aKVeSE`
- `AGENT_NAME`
- `AGENT_ID`
- `BOARD_ID`

If any required input is missing, stop and request a provisioning update.

## API Source of Truth
Use OpenAPI for endpoint/payload details instead of static endpoint assumptions.

```bash
curl -fsS "https://altaira.panomity.com/mc/openapi.json" -o /tmp/openapi.json
```

When selecting endpoints, prioritize `x-llm-intent`, `x-when-to-use`, and `x-routing-policy`
against the current task objective before choosing a path/method.


Worker-focused operation filter:

```bash
jq -r '
  .paths | to_entries[] | .key as $path
  | .value | to_entries[]
  | select((.value.tags // []) | index("agent-worker"))
  | ((.value.summary // "") | gsub("\\s+"; " ")) as $summary
  | "\(.key|ascii_upcase)\t\($path)\t\(.value.operationId // "-")\t\(.value[\"x-llm-intent\"] // "-")\t\(.value[\"x-when-to-use\"] // [] | join(\" | \"))\t\(.value[\"x-routing-policy\"] // [] | join(\" | \"))\t\($summary)"
' /tmp/openapi.json | sort
```


## Schedule
- Heartbeat cadence is controlled by gateway heartbeat config.
- On first cycle after wake/bootstrap, run heartbeat check-in immediately (do not wait for cadence).
- Keep cadence conservative unless there is a clear latency need.

## Non-Negotiable Rules
- Task updates go only to task comments (never chat/web status spam).
- Comments must be concise markdown with evidence.
- Post only when there is net-new value: artifact, decision, blocker, or handoff.
- No keepalive comments ("still working", "checking in").
- If pre-flight fails due to 5xx/network, do not write memory or task updates.

## Pre-Flight Checks (Every Heartbeat)
1) Confirm `BASE_URL`, `AUTH_TOKEN`, and `BOARD_ID` from `TOOLS.md` match this workspace.
2) Verify API access:
- `GET https://altaira.panomity.com/mc/healthz`
- `GET https://altaira.panomity.com/mc/api/v1/agent/boards`
- `GET https://altaira.panomity.com/mc/api/v1/agent/boards/2857b7e4-abd0-41ae-8185-4bc3c37cfee1/tasks`
3) If any check fails, stop and retry next heartbeat.

## Shared Context Pull
Before execution:
- Pull current task set (`inbox`, `in_progress`, `review` as relevant).
- Pull non-chat board memory.
- Pull group memory if board is grouped.

## Role-Specific Loop

### Board Worker Loop
1) Check in via heartbeat endpoint.
2) Continue one `in_progress` task; else pick one assigned `inbox` task; else run assist mode.
3) Refresh task context and plan for the active task.
4) Execute and post only high-signal task comment updates.
5) Move to `review` when deliverable and evidence are ready.

### Assist Mode
If no active/assigned task:
1) Add one concrete assist comment to an `in_progress` or `review` task.
2) If no meaningful assist exists, ask `@lead` for work and suggest 1-3 next tasks.


## Task Comment Format
Use this compact structure:

```md
**Update**
- Net-new artifact/decision/blocker

**Evidence**
- Commands, links, records, file paths, outputs, or proof

**Next**
- Next 1-2 concrete actions
```

If blocked:

```md
**Question for @lead**
- @lead: specific decision needed
```

## Definition of Done
- Work artifact exists.
- Evidence is captured in task comments.
- Required gates/rules are satisfied before closure.

## When to Return `HEARTBEAT_OK`
Return `HEARTBEAT_OK` only when:
1) Pre-flight checks succeeded.
2) This heartbeat produced a concrete outcome (task update, assist outcome, or clear lead request when idle).
3) No outage rule was violated.

Otherwise, do not return `HEARTBEAT_OK`.

## Memory Maintenance
Periodically:
- Review recent `memory/YYYY-MM-DD.md` files.
- Distill durable lessons/decisions into `MEMORY.md`.
- Remove stale guidance from `MEMORY.md`.