# Task Files

`docs/tasks/` is the durable file-per-task dispatch surface for capOS workflow
automation. It is introduced by
[`docs/proposals/task-state-and-agent-telemetry-proposal.md`](../proposals/task-state-and-agent-telemetry-proposal.md)
and starts as an additive source alongside `WORKPLAN.md`,
`REVIEW_FINDINGS.md`, and the executable plans under `docs/plans/`.

Task files describe the work to be done and the evidence needed to close it.
They are not authority records, lock files, agent telemetry, or a substitute
for the capOS review, branch, hazard, and merge rules.

## Directory Layout

Task files are grouped by lifecycle status:

```text
docs/tasks/
  ready/
  active/
  blocked/
  review/
  done/2026/
```

The path is a dispatch hint. The stable task identity lives in front matter, so
a task can move between status directories with `git mv` without changing its
id. Completed tasks should move under `done/YYYY/`.

## Task Schema

Each task file is Markdown with YAML-style front matter followed by
reader-facing task context. Required fields:

```yaml
id: ddf-devicemmio-write32-effect
title: "DeviceMmio.write32 bounded effect"
status: active
milestone: device-driver-foundation
priority: high
slice_class: behavior
conflict_domains:
  - resource:ddf-device-authority
  - interface:capnp-device-manager-api
write_scope:
  - kernel/src/device_manager.rs
  - kernel/src/cap/device_mmio.rs
validation:
  - make fmt-check
  - make workflow-check
  - make run-devicemmio-grant
hazards:
  - paging
  - mmio
  - docs
```

Required front matter fields:

- `id`: stable kebab-case id. Prefer `<plan-slug>-<task-slug>` and do not
  reuse ids after closeout.
- `title`: short human-readable task title.
- `status`: one of `ready`, `active`, `blocked`, `review`, or `done`.
- `milestone`: selected milestone or ad-hoc track slug that owns the task.
- `priority`: `high`, `normal`, or `low`, matching the current plan priority.
- `slice_class`: one of `behavior`, `read-side-proof`,
  `harness-hardening`, or `docs-status`.
- `conflict_domains`: semantic domains that would block parallel dispatch.
- `write_scope`: expected paths or path prefixes the task may edit.
- `validation`: commands that prove the slice.
- `hazards`: known hazard families to carry into commit trailers and review.

Useful optional fields:

- `source`: proposal, plan, backlog, or review-finding path that motivated the
  task.
- `branch`: expected task branch when active or in review.
- `depends_on`: task ids that must close first.
- `review_finding`: review-finding id or heading when the task remediates an
  unresolved finding.
- `summary_output`: generated summary target if this task refreshes a checked
  in generated view.

The Markdown body should contain acceptance criteria, design grounding,
evidence expectations, review notes, residual risks, and closeout notes. Keep
operational handoff details such as local usernames, local worktree paths,
agent session ids, and raw token accounting out of task files.

## Status Lifecycle

Task movement is explicit:

- `ready`: selectable work with enough context, write scope, conflict domains,
  and validation commands for a worker to start.
- `active`: a worker has created or adopted a branch/worktree for the task and
  is implementing or validating it.
- `blocked`: work is not selectable until the named prerequisite, design
  decision, access issue, or failing evidence gate is resolved.
- `review`: implementation is ready for independent review or review-finding
  remediation.
- `done`: the reviewed branch is merged and the relevant local and remote
  mainline publication surfaces have been synchronized.

Status changes should preserve the task id and update the front matter status
in the same commit that moves the file. A blocked task should name a concrete
unblock condition in the body.

## Conflict Domains

Conflict domains describe semantic collision risk, not merely shared status
files. Use stable strings with a type prefix:

- `resource:<slug>` for product or subsystem ownership, such as
  `resource:ddf-device-authority`, `resource:scheduler-core`, or
  `resource:posix-adapter`.
- `path:<path-or-prefix>` for write scopes that should serialize, such as
  `path:kernel/src/sched.rs` or `path:tools/generated/`.
- `interface:<slug>` for Cap'n Proto, ABI, C API, or runtime interface surfaces,
  such as `interface:schema-capos-capnp`.
- `evidence:<gate-or-log>` for validation evidence one task can invalidate,
  such as `evidence:make-run-net` or `evidence:scheduler-bench-capos-bench`.
- `docs:<slug>` for public design or status wording that must stay coherent
  across tasks.

Unknown or omitted conflict domains serialize as the reserved `unknown` domain
and should block parallel dispatch until clarified. Ordinary overlap on
planning files such as `WORKPLAN.md`, `REVIEW_FINDINGS.md`,
`docs/plans/README.md`, or generated global summaries is a merge-time
coordination cost. It should not block parallel dispatch when the underlying
code, interface, subsystem behavior, and validation evidence are disjoint.

## Generated Summaries

Task files are the editable source. Global task tables, track maps, status
summaries, and selected-work views should be generated from task metadata.

`tools/vibe-loop-capos-tasks` is the read-only task index command. Its default
and `--summary` output is a human-readable orchestration view with task counts,
the current selected milestone when it can be read from the explicit
`WORKPLAN.md` selected-milestone section, unknown conflict-domain status, and
per-task rows. `--json` preserves the stable machine-readable task list and may
include additive compatibility metadata such as status counts, the anchored
selected milestone, and whether any task serializes as `unknown`.

Early generated outputs should live under `target/` until their format is
stable. Checked-in generated summaries must declare their generator command and
use an obvious generated section marker. Humans should edit the source task
files, not generated summary rows. A workflow check may later reject hand edits
inside generated sections once the generator is proven.

## Local Telemetry Boundary

Runtime telemetry belongs under local, untracked workflow state such as
`.vibe-loop/runs/<run-id>/`. It may record branch, worktree, run status,
timestamps, heartbeat, check duration, model choice, reviewer role, and token
usage state for a particular attempt.

Do not add local run telemetry to task files. Agent identities, session ids,
local paths, and token counts are not public documentation and do not grant
repository, OS, or capability authority. Token usage must be recorded as
`exact`, `estimated`, or `unavailable`; do not invent counts when the runtime
does not expose exact usage.

## Workspace Preflight Boundary

`tools/vibe-loop-capos-tasks workspace-preflight` is a repo-local diagnostic for
checking a claimed task branch and worktree before edits or final integration.
It reports pass, warn, or block findings for the expected task, branch,
worktree, base ancestry, `main` ancestry, dirty state, unresolved paths,
duplicate git worktree registrations, and local `.vibe-loop` lock ownership
when available.

The detailed output is local run evidence. It may include local worktree paths,
lock paths, host names, process ids, and run ids from the untracked supervisor
state directory. Do not copy that raw metadata into task files or public status
docs. Durable docs should summarize only the command, result class, and
actionable boundary, such as unknown ownership blocking final integration.

## GitHub Projects Boundary

GitHub Projects, if enabled, is a mirror for human dashboards. The local task
file remains authoritative for capOS dispatch and closeout.

A future sync command may mirror task id, title, status, priority, conflict
domains, branch, issue links, and project item ids. Workers must still dispatch
from local task files plus the current review-finding and selected-milestone
rules. If GitHub is unavailable or stale, local task selection should continue
to work.