# Tracking System — Automation Tracking Issues

## Overview

The CleverAgents system has no shared memory between agents. All coordination happens through **Forgejo issues** with the `Automation Tracking` label. There are two distinct issue types:

| Type | Purpose | Lifecycle | Title Pattern |
|------|---------|---------|---------------|
| **Status issue** | Current agent state — what it's doing, health, progress | Replaced each cycle (old one closed) | `[{PREFIX}] Status: {Type} (Cycle N)` |
| **Announcement issue** | Persistent signals to other agents | Persists until explicitly closed | `[{PREFIX}] Announce: {Message}` |


## Status Tracking Issues

### Invariant: One at a Time Per Prefix

Each agent prefix may have **at most one open status issue** at any time. The automation-tracking-manager enforces this automatically when `CREATE_TRACKING_ISSUE` is called.

### Cycle Number

Cycle numbers are:
- **Globally unique per prefix** — never reused
- **Monotonically increasing** — computed by searching ALL issues (open AND closed)
- **Used to detect missed cycles** — a gap in cycle numbers means the agent crashed

### Rolling Average Interval

The `Estimated Cycle Interval` field is computed by automation-tracking-manager using:
```
new_interval = round(old_interval × 0.90 + actual_interval × 0.10)
```

This provides a smoothed estimate of how often the agent actually wakes up. Agents **do not** compute this themselves — they pass `sleep-interval-default` to `CREATE_TRACKING_ISSUE` and the ATM handles the calculation.

### CREATE_TRACKING_ISSUE Steps

When called, automation-tracking-manager:
1. Finds all open status issues with label `Automation Tracking` and title starting with `[{prefix}] Status:`
2. Closes every one found (posts "Superseded by next cycle" comment, then closes)
3. Searches ALL issues (including closed) to find the highest cycle number for this prefix
4. Calculates next cycle number (highest + 1)
5. Calculates estimated interval (rolling average from previous issue)
6. Creates new issue: `[{prefix}] Status: {tracking-type} (Cycle N)`
7. Applies `Automation Tracking` label via forgejo-label-manager
8. Returns the issue number and cycle number to the caller

### Mandatory Startup Recovery Protocol

**CRITICAL: READ state BEFORE creating a new one.**

```
1. READ_TRACKING_STATE    ← read the old state while it still exists
2. ANALYZE recovered state
3. CREATE_TRACKING_ISSUE  ← this closes the old issue and creates a fresh one
4. RESUME work using recovered data
```

**Why this order matters**: `CREATE_TRACKING_ISSUE` closes all existing status issues. If you call it first, then `READ_TRACKING_STATE` reads your brand-new empty issue — all previous state is lost.

### Discovery Pattern

Any agent that wants to find another agent's current status can:
1. Search for open issues with label `Automation Tracking` and title containing the prefix and "Status:"
2. The most recent open issue is the current cycle
3. Read its body and comments for detailed state


## Announcement Issues

### Purpose

Announcements are **persistent signals** to other agents. Unlike status issues (which are replaced each cycle), announcements persist until the creating agent explicitly closes them. They communicate:
- Conditions that block operation
- Problems requiring attention from other agents
- Important events (capacity degraded, human escalation, quality gates violated)

### Format

- **Title**: `[{PREFIX}] Announce: {short message}`
- **Labels**: `Automation Tracking` + one priority label
- **Body**: detailed description of the condition
- **Lifetime**: persists until `CLOSE_ANNOUNCEMENT_ISSUE` is called

### Priority Labels for Announcements

The priority label applied to an announcement determines which agents consume it (see the relevancy matrix in SKILL.md). For label definitions and the full priority hierarchy see `cleveragents-contributing` and `cleverthis-guidelines` skills.

| Label | When to Use for Autonomous System Announcements |
|-------|------------------------------------------------|
| `Priority/CI-Blocker` | CI pipeline broken; consumed by ALL agents immediately |
| `Priority/Critical` | Multiple supervisors down; system unable to make progress |
| `Priority/High` | Single supervisor repeatedly failing; degraded capacity |
| `Priority/Medium` | Informational: product completion reached, capacity changed |
| `Priority/Low` | Minor notices; no immediate action needed |

### Announcement Lifecycle

1. **Create**: `CREATE_ANNOUNCEMENT_ISSUE` with prefix, message, priority, body
2. **Review own**: `REVIEW_OWN_ANNOUNCEMENTS` — list all your open announcements
3. **Close**: `CLOSE_ANNOUNCEMENT_ISSUE` when condition resolves
4. **Frequency**: Agents must review and close stale announcements every 3 cycles

### Announcement Consumption

Agents read others' announcements via `READ_ANNOUNCEMENTS`:
- Provide: comma-separated prefixes, minimum priority, repo info
- Returns: filtered list of open announcement issues
- Use `agent-prefix-info` to get the relevancy matrix for your prefix

**Universal baseline**: Every agent consumes **Priority/CI-Blocker** from ALL agents. This cannot be waived.

**Processing urgency**:
- Critical: process IMMEDIATELY before anything else
- High: process before starting next work cycle
- Medium/Low: opportunistically when convenient


## System-Specific Labels

Two labels have special meaning within the autonomous agent system:

### `Automation Tracking` — Universal Discovery Mechanism

This label is applied to **every** status tracking issue and every announcement issue. It is the discovery mechanism by which agents find each other's activity. Without it, no agent can locate another's tracking state.

Applied to:
- All status tracking issues (`[{PREFIX}] Status: ... (Cycle N)`)
- All announcement issues (`[{PREFIX}] Announce: ...`)

### `needs feedback` — Human Escalation Signal

This label signals that a work item cannot proceed without human intervention and that **all agents must stop dispatching workers** for the item until a human removes the label.

Applied when:
- A PR or issue has exhausted all model tier escalations (Opus × 3 same-problem failures)
- An architectural decision requires human approval before implementation
- An agent definition modification proposal is awaiting human review
- A spec change is pending human feedback

Workflow: agent applies label → posts detailed comment explaining what was tried → all supervisors skip this item in their dispatch loops → human resolves the issue and removes the label → supervisors resume normal dispatch.

### All Other Label Rules

For complete label rules — forbidden operations (`forgejo_create_label` etc.), never listing repo-level labels, why only org-level labels are used, how forgejo-label-manager works, label scope descriptions (State/, Priority/, MoSCoW/, Type/), the full priority hierarchy — see:

- **`cleveragents-contributing` skill** — enforcement rules and what each label scope means
- **`cleverthis-guidelines` skill** — company-wide label and priority hierarchy definitions
- **`forgejo-api` skill** — curl patterns for all Forgejo API operations including label endpoints (`forgejo-label-manager` loads this skill automatically)


## automation-tracking-manager Operations Summary

| Operation | Purpose |
|-----------|---------|
| `CREATE_TRACKING_ISSUE` | Creates new status issue (closes old ones first). Both creating AND updating the status issue. |
| `UPDATE_TRACKING_ISSUE` | Adds a comment to the current open status issue. |
| `READ_TRACKING_STATE` | Reads the latest status issue (open or closed) and extracts state. |
| `GET_NEXT_CYCLE_NUMBER` | Returns what the next cycle number will be (without creating the issue). |
| `CREATE_ANNOUNCEMENT_ISSUE` | Creates a persistent announcement with a priority label. |
| `CLOSE_ANNOUNCEMENT_ISSUE` | Closes a specific announcement by issue number. |
| `READ_ANNOUNCEMENTS` | Returns filtered open announcements by prefix and minimum priority. |
| `REVIEW_OWN_ANNOUNCEMENTS` | Lists all open announcements from a specific prefix. |
| `CYCLE_ANNOUNCEMENT_REVIEW` | Combined: reads others' announcements AND reviews own. |
| `CLOSE_TRACKING_ISSUE` | Closes the current status issue (without creating a new one). |
