# ACE Tasks Control Plane

This directory contains shared execution artifacts consumed by ACE prompts, tools, and resources.

## Files

- `todo.md`: active execution board and verification checklist.
- `lessons.md`: durable guardrails captured after failures/corrections.
- `role_tasks.md`: bounded task packs for each ACE role.
- `cli_work_split.md`: Codex CLI vs Gemini CLI routing contract.
- `SWARM_HANDOFF.template.json`: canonical inter-agent handoff schema.
- `SWARM_HANDOFF.example*.json`: concrete routing examples.
- `agent-state/job-queue.json`: scheduler job queue for deferred/gated dispatch.
- `agent-state/job-locks.json`: collision-free scheduler locks.
- `agent-state/scheduler-lease.json`: active scheduler lease ownership.

## When To Read This Directory

- Before starting non-trivial work that needs explicit task, role, or handoff structure.
- Before issuing or consuming a `SWARM_HANDOFF`.
- When recovering blocked or deferred work through the scheduler and TODO surfaces.
- When a repeated failure should become a durable lesson or guardrail.

## Common Workflows

1. Start work: check `todo.md`, then use `role_tasks.md` to confirm the bounded contract for the active role.
2. Route work: begin from `SWARM_HANDOFF.template.json`, then compare with the example payloads before publishing.
3. Recover work: inspect `agent-state/job-queue.json`, `agent-state/job-locks.json`, and `agent-state/scheduler-lease.json` together instead of in isolation.
4. Harden work: write repeatable failures to `lessons.md` so the same mistake does not re-enter the loop.

## Operating Rules

1. Update `todo.md` before non-trivial work and after verification.
2. Log every repeatable correction pattern in `lessons.md`.
3. Use `SWARM_HANDOFF.template.json` as the base for all routing payloads.
4. Keep acceptance criteria measurable and tied to file-based evidence.

## Validation Rules

- Handoffs must reference real artifacts, owners, and acceptance criteria.
- Scheduler state is advisory unless it matches current task and status artifacts.
- Lessons should capture a failure pattern, a guardrail, and a verification check, not just an anecdote.

## Common Failure Modes

- `todo.md` is stale while work has already moved; refresh it before trusting downstream routing.
- A handoff exists without evidence or acceptance criteria; treat it as incomplete, not merely “draft.”
- Scheduler files disagree with task or status truth; route the contradiction through ops instead of guessing which surface won.