# ASOP: Agent Self-Organization Protocol

> Version: 1.0 | Constitutional Layer: Above Safety Stack
> Location: `Prefrontal_Cortex/Action_Queue/task_board.json`

## Purpose

Enables multiple agents to self-organize around a shared task board.
User prompts ONCE. First agent decomposes. Others claim and execute in parallel.

## The 7 Rules

### Rule 1: Read Before Working
Before starting any work, read `task_board.json`. If tasks exist that match
your capabilities, claim one instead of starting independent work.

### Rule 2: Claim Before Touching
To claim a task:
1. Write your `agent_id` to `claimed_by`, set status to `claimed`
2. Wait 500ms, re-read the file
3. If still claimed by you -> set status to `active`, proceed
4. If claimed by another agent -> pick the next available task

### Rule 3: Declare Files You'll Touch
Before starting work on a claimed task, list all files you plan to modify
in the task's `files_touched` array. Check all other `active` tasks'
`files_touched` lists first. If overlap exists, skip the task.

### Rule 4: Report Completion
When done:
1. Set task status to `done`
2. Write outcome summary to `outcome` field
3. Update your entry in `agent_registry.json` (increment domain wins/fails)
4. Evidence flows through the existing bridge pipeline

### Rule 5: Heartbeat Every 30s
While holding an active task, update your `last_heartbeat` in
`agent_registry.json` every 30 seconds. If heartbeat goes stale (>5 min),
the dispatcher will release your claim.

### Rule 6: Yield on Lost Claims
If you re-read the board and your claim was released (stale heartbeat or
dispatcher intervention), do NOT retry the same task. Pick a different one.

### Rule 7: Never Claim Blocked Tasks
Tasks with status `blocked` have unresolved `depends_on` entries.
Only the dispatcher promotes `blocked` -> `open` when dependencies complete.

## Task Board Schema

Location: `Prefrontal_Cortex/Action_Queue/task_board.json`

```json
{
  "version": 1,
  "dispatch_id": "d_<timestamp>",
  "prompt": "user's original prompt",
  "dispatched_at": "ISO8601",
  "tasks": [
    {
      "task_id": "t_<timestamp>_001",
      "title": "short description",
      "description": "detailed instructions",
      "domain": "security|architecture|testing|features|...",
      "complexity": "low|medium|high",
      "required_capabilities": ["python", "fastapi"],
      "depends_on": [],
      "status": "open|claimed|active|done|failed|blocked",
      "claimed_by": null,
      "claimed_at": null,
      "files_touched": [],
      "outcome": null
    }
  ]
}
```

## Agent Registry Schema

Location: `state/agent_registry.json`

```json
{
  "agent_id": {
    "agent_id": "claude_daemon",
    "model": "opus",
    "status": "idle|claiming|active|offline",
    "capabilities": ["python", "security"],
    "last_heartbeat": "ISO8601",
    "current_task": null,
    "history": {
      "tasks_completed": 0,
      "domains": {}
    }
  }
}
```

## Conflict Prevention

- **Optimistic claiming** (Rule 2) prevents double-assignment without locks
- **File declaration** (Rule 3) prevents edit collisions
- **Stale recovery** (Rule 5) prevents zombie claims
- **Dependency ordering** (Rule 7) prevents semantic conflicts

## Safety Invariant

ASOP operates ABOVE the safety stack. It cannot disable:
- Titan Laws (hash-enforced, immutable)
- Harm detection (C3 compliance gate)
- PII blocking (H3 patterns)
- Constitution hash verification
