A place to put the work

Task card = tracked object. Work directory = working surface. They often travel together, but they are not the same thing. A small task may only need a card. A larger effort gets a work directory alongside it to hold planning docs, doing docs, unit files, and artifacts.

Use a task when work needs to persist across turns, be tracked explicitly, or accumulate planning and artifacts over time. The key question is not importance but persistence — some work is modest but needs to survive across sessions and context resets. Quick one-off requests don't need a task. Anything the agent should remember to come back to does.

A task card is a markdown file with YAML frontmatter that declares kind: task. That declaration is the signal. Everything else in the task directory — planning docs, doing docs, unit files, artifacts — is support material that the scanner may enumerate for context but does not parse as a task card.

Cards carry status, priority, dependencies, ownership, timestamps, and pointers. They're the source of truth that the board reads from.

Tasks live in two collections, each representing a different work rhythm:

one-shots/ — bounded work with a clear finish line. Fix a bug, write a feature, review a PR. When it's done or cancelled, it archives.

ongoing/ — standing responsibilities with no single finish line. Maintenance, recurring audits, open-ended projects. These stay active and spawn one-shots as needed.

When a task needs room to think, it gets a same-stem directory next to the card. This holds planning docs, doing docs, unit files, and any outputs produced during execution. The scanner detects the directory and lists its contents, but never descends into it looking for task cards.

Not every task needs one. Small tasks may only need a card. Work directories are for tasks with enough moving parts to justify a working surface.

A common path is drafting → processing → validating → done, with paused, blocked, collaborating, or cancelled available when the work requires it. Both done and cancelled are terminal — the card and its work directory archive together.

The board is a summary, not the source of truth. Task cards are the source of truth. The board exists so the agent can quickly answer: what am I holding, what state is it in, and is the task system itself healthy?

It stays compact because prompt budget matters — the board needs to orient the agent without eating context that should go to the actual work.

Terminal tasks — done and cancelled — are hidden from active counts. They still exist in archive, but they don't clutter the view.

When issues exist, the health line splits them by urgency:

Live issues are problems affecting current operation — a task card with invalid schema, a broken dependency link. Migration issues are historical or structural cleanup discovered during import or evolution — legacy cards missing the kind field, old support docs still at the collection root.

That distinction matches real triage instead of flattening all problems into one scary number.

Both the agent and the operator can inspect and act on task-system problems. The agent can initiate checks during its own work, and the operator can request them via ouro task fix. Every issue the scanner finds has a typed code, a proposed fix, and a confidence level. Safe fixes can always be previewed before applying.

ouro task fix --safe applies all deterministic, reversible fixes. Ambiguous issues are inspected one at a time — the agent sees the problem, the options, and decides.

Not every irregularity is urgent, and not every issue should be auto-fixed. If a problem is surfaced as a fixable issue, the agent can inspect the proposed repair before applying it. The tooling supports triage, not unattended rewrites.