Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Task Files

docs/tasks/ is the durable file-per-task dispatch surface for capOS workflow automation. It is introduced by Task State and Agent Telemetry 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:

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:

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.

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.