Proposal: Task State and Agent Telemetry

capOS planning currently overloads a few shared files: WORKPLAN.md, docs/roadmap.md, docs/plans/README.md, and per-track plans act as priority queue, status log, dependency graph, dispatch surface, and evidence index at the same time. That structure is readable for a single worker, but it creates avoidable merge conflicts when several independent agents run in parallel.

The repository should move toward file-per-task state with generated global views. Task files become the durable source of truth for dispatch and closeout. Large overview files become either generated summaries or short entry points that humans do not edit for every slice.

Goals

• Make independent work slices edit independent task files instead of the same global status paragraphs.
• Preserve the selected-milestone rule and review-finding priority without requiring every worker to patch WORKPLAN.md.
• Record conflict domains, write scope, validation gates, and hazard families in structured metadata that supervisors can consume.
• Treat shared planning-file edits as normal integration work, not a dispatch blocker for otherwise independent slices.
• Track active agent/session ownership, wall time, check duration, and model selection in local runtime telemetry without publishing local operational residue in reader-facing docs.
• Allow GitHub Projects integration as a mirror or dashboard, not as the first source of truth for capOS task execution.

Non-Goals

• Do not move capability, security, review, or merge authority into an external project tracker.
• Do not require GitHub Projects for local development, offline work, or reproducible task selection.
• Do not publish raw local paths, agent session IDs, or token accounting in public documentation.
• Do not treat task metadata as a security authority or permission grant. It is workflow telemetry and validation input; capOS capability authority remains in the OS design and implementation.
• Do not replace detailed design proposals, backlog files, or review findings; task files reference them and carry execution state.

Task File Layout

Use one file per task, grouped by status:

docs/tasks/
  README.md
  ready/
  active/
  blocked/
  review/
  done/2026/

The file path is a dispatch hint; the stable task id lives in front matter so links survive git mv between status directories. A task moves from ready/ to active/, then to review/ or blocked/, and finally to done/YYYY/ when the reviewed branch is merged and synchronized.

Representative front matter:

id: ddf-devicemmio-write32-effect
title: "DeviceMmio.write32 bounded effect"
status: active
milestone: device-driver-foundation
priority: high
slice_class: behavior
conflict_domains:
  - ddf-devicemmio-cap
  - 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

The body contains acceptance criteria, design grounding, review notes, evidence, residual risks, and closeout. Backlog and proposal documents remain the detailed context; the task file records what a worker must do now.

Conflict domains should describe real semantic collision risk: edits to the same code files or functions, changes to the same kernel subsystem behavior, changes to the same Cap’n Proto interfaces or generated bindings, or validation evidence that another task can invalidate. Shared planning files such as WORKPLAN.md, roadmap entries, status notes, and generated summaries should be tracked as integration surfaces, but they should not by themselves block parallel dispatch when the underlying implementation work is independent.

Generated Views

WORKPLAN.md should shrink to the selected milestone and pointers, then eventually stop being a hand-edited dispatch surface. Track maps, active-work tables, and status summaries should be generated from task metadata.

Initial generated outputs can live under target/ until the format stabilizes. After the generator proves useful, checked-in summaries may be refreshed by an explicit command and guarded by workflow checks that reject hand edits inside generated sections.

Runtime Telemetry

Runtime telemetry is local operational state for a workflow attempt, not task metadata and not public documentation. A supervisor may keep it under a run-centric directory:

.vibe-loop/runs/<run-id>/
  state.json
  events.jsonl

state.json records the task id, branch, worktree, run status, start time, last heartbeat, and known blockers for that attempt. Agent participation is recorded in this run record, not in the task schema: a task describes the work, while a specific workflow run records which implementation, pre-review, and final-review agents were used for that attempt. These run records are telemetry only; they do not grant repository, OS, or capability authority. events.jsonl records append-only events such as agent spawn, check start, check pass/fail, review finding, commit, merge, push, and cleanup.

Wall time can be recorded exactly from timestamps. Token accounting should use three explicit states:

• exact, when the agent runtime exposes per-agent usage;
• estimated, when only prompt size, file bytes read, tool count, model, effort, and elapsed time are available;
• unavailable, when no credible usage source exists.

The ledger must not invent token numbers. It should store null plus a usage source label when exact data is unavailable.

GitHub Projects

GitHub Projects is useful for human-facing dashboards, cross-repository visibility, and broader milestone coordination. It should not become the only source of task truth for capOS automation.

Preferred integration:

• task files remain the authoritative local execution record;
• a sync command mirrors task id, title, status, priority, conflict domains, branch, and linked issue/project item metadata to GitHub Projects;
• GitHub Projects may hold triage and assignment views, but local workers dispatch from task files plus review findings;
• if GitHub is unavailable or stale, local task selection still works.

This keeps capOS reproducible and branch-local while still allowing project management views for humans.

Migration Plan

1. Add docs/tasks/README.md with the task-file schema, status lifecycle, conflict-domain vocabulary, generated-view rules, and telemetry boundary.
2. Add a read-only task index command that emits JSON from docs/tasks/, selected milestone metadata, and REVIEW_FINDINGS.md.
3. Pilot one workflow track, preferably the existing Vibe-Loop Supervisor Pilot, using task files while leaving current WORKPLAN.md rules in force.
4. Add workflow checks that validate task metadata and reject hand edits in generated sections.
5. Move selected-milestone dispatch from narrative paragraphs into task files.
6. Add optional GitHub Projects synchronization after the local format is stable.
7. Shrink WORKPLAN.md to selected-milestone pointers and eventually retire it as an execution queue.

Success Criteria

• Independent branches can update task state without touching the same global planning files.
• Supervisors can list ready, active, blocked, review, and done work with stable ids, conflict domains, validation gates, and write scopes.
• Parallel dispatch is based on semantic conflict domains, while ordinary planning-summary conflicts remain merge-time integration work.
• Runtime run state records which agents worked on a task attempt and how long they were active, without adding agent identity fields to the task schema.
• Exact token usage is recorded only when available; otherwise the telemetry states that usage is estimated or unavailable.
• GitHub Projects, if enabled, mirrors task state without becoming a required runtime dependency.