# Scheduler Flow (Single Source of Truth)

Use this document for **all scheduler runs**. Task locking uses the **TORCH** protocol (see `docs/agents/TORCH.md`).

## Scheduler Override (Top-Line Rule)

During scheduler execution, the scheduler-specific instructions in this document and the cadence prompt (`daily-scheduler.md` or `weekly-scheduler.md`) **supersede generic AGENTS workflow details** when they conflict.

### Global rules that still apply

- Follow core safety and policy constraints (no harmful behavior, no secret exfiltration, no policy violations).
- Do not perform destructive or irreversible actions unless explicitly required by the scheduler task definition.
- Keep repository integrity checks (e.g., required lint/test commands in the scheduler flow) and leave an auditable log trail.
- Respect non-interactive execution constraints and do not pause for manual approvals.

### Generic AGENTS workflow details intentionally ignored for scheduler runs

- The normal "one subsystem per PR" restriction, because scheduler operations are orchestration/meta-work that may touch scheduler logs, prompts, and coordination docs together.
- The standard task-claim sequence described for general agents when it conflicts with the stricter, numbered MUST sequence below.
- Generic start-of-task bookkeeping patterns not referenced by scheduler prompts (for example, creating extra context/todo artifacts) when they would add noise to automated scheduler runs.

## Numbered MUST Procedure

1. **MUST** set cadence variables before any command:
   - `cadence` = `daily` or `weekly`
   - `log_dir` = `docs/agents/task-logs/<cadence>/`
   - `branch_prefix` = `agents/<cadence>/`
   - `prompt_dir` = `docs/agents/prompts/<cadence>/`

2. **MUST** run the preflight check to build the exclusion set:

   ```bash
   node scripts/agent/nostr-lock.mjs check --cadence <cadence>
   ```

   This queries Nostr relays for active lock events and returns JSON with `locked` and `available` agent lists. Use the `locked` array as the exclusion set.

3. **MUST** read both policy files before selecting an agent:

   ```bash
   cat AGENTS.md CLAUDE.md
   ```

4. **MUST** run this command to identify the latest cadence log file, then choose the next roster agent not in the exclusion set:

   ```bash
   ls -1 <log_dir> | sort | tail -n 1
   ```

5. **MUST** stop and write a `_failed.md` log with `All roster tasks currently claimed by other agents` when every roster agent is excluded.

6. **MUST** claim the selected agent:

   ```bash
   AGENT_PLATFORM=<jules|claude-code|codex> \
   node scripts/agent/nostr-lock.mjs lock \
     --agent <agent-name> \
     --cadence <cadence>
   ```

   The script generates an ephemeral keypair, publishes a NIP-78 lock event to Nostr relays with NIP-40 auto-expiration (2 hours), and performs a built-in race check. No tokens or secrets needed.

   - **Exit code 0** = lock acquired, proceed to Step 7.
   - **Exit code 3** = race lost (another agent claimed first). Return to Step 2.
   - **Exit code 2** = relay error. Write a `_failed.md` log with reason `Nostr relay error` and stop.

7. **MUST** execute `<prompt_dir>/<prompt-file>` end-to-end.

8. **MUST** create exactly one final status file (`_completed.md` or `_failed.md`), run `npm run lint`, then commit and push.

## Canonical Example Run

```text
# Step 1: Set cadence
cadence=daily

# Step 2: Preflight — check Nostr locks
$ node scripts/agent/nostr-lock.mjs check --cadence daily
{
  "cadence": "daily",
  "date": "2026-02-14",
  "locked": ["audit-agent"],
  "available": ["ci-health-agent", "const-refactor-agent", ...],
  "lockCount": 1,
  "locks": [...]
}

# Step 3: Read policies
$ cat AGENTS.md CLAUDE.md
...

# Step 4: Check logs, select next agent
$ ls -1 docs/agents/task-logs/daily/ | sort | tail -n 1
2026-02-13_18-40-00_load-test-agent_completed.md

Selected agent: nip-research-agent

# Step 6: Claim via Nostr lock
$ AGENT_PLATFORM=jules node scripts/agent/nostr-lock.mjs lock --agent nip-research-agent --cadence daily
Locking: agent=nip-research-agent, cadence=daily, date=2026-02-14
Step 1: Checking for existing locks...
Step 2: Generating ephemeral keypair...
Step 3: Building lock event...
Step 4: Publishing to relays...
  Published to 3/3 relays
Step 5: Race check...
RACE CHECK: won
LOCK_STATUS=ok
LOCK_EVENT_ID=ea2724c76d2bd707...
LOCK_AGENT=nip-research-agent
LOCK_CADENCE=daily
LOCK_EXPIRES_ISO=2026-02-14T02:00:00.000Z

# Step 7: Execute agent prompt
(agent runs nip-research-agent prompt...)

# Step 8: Finalize
$ npm run lint
> lint passed

Wrote: docs/agents/task-logs/daily/2026-02-14_00-12-00_nip-research-agent_completed.md
```