# Plans

This directory holds per-track plan files designed for autonomous execution by
[ralphex](https://github.com/umputun/ralphex). It is the executable surface
extracted from `WORKPLAN.md`. `WORKPLAN.md` keeps the priority ladder, selected
milestone, and dependency notes; `docs/roadmap.md` keeps long-term direction;
`docs/backlog/` keeps detailed task decomposition; this directory keeps the
shape ralphex consumes.

A plan file in this directory must:

1. Start with `# Plan: <title>`.
2. Declare a `## Validation Commands` section listing the actual project
   gate commands (cargo aliases, `make` targets, host tests). ralphex runs
   them between iterations to confirm the diff is still green.
3. Use `### Task N:` (or `### Task N.M:` / `### Task Na:`) headings only for
   work items. Checkboxes (`- [ ]` / `- [x]`) appear only inside Task
   sections. They must not appear in `Overview`, `Conflict Surface`,
   `Validation Commands`, or `Success Criteria` -- ralphex would interpret
   them as extra iterations.
4. Include a `## Conflict Surface` section listing the file paths the plan
   owns and the paths it must NOT touch. ralphex itself ignores this
   section, but it lets a human (or a coordinating agent) decide which
   plans are safe to run concurrently in separate worktrees via
   `ralphex --worktree`.

Plans land here in three lifecycle states:

- Active: pulled into the current execution rotation. The track's owner sits
  in `WORKPLAN.md` if it is the selected milestone, or in the ad-hoc list if
  it is parallel work.
- Paused: kept here when prerequisites are missing. Mark explicitly in the
  plan body; ralphex will iterate over open checkboxes regardless, so a
  paused plan should leave its open boxes empty of work text or move them
  out of `### Task N:` sections.
- Completed: moved to `docs/plans/completed/` (ralphex does this
  automatically when `move_plan_on_completion` is enabled).

The mapping below records which legacy decomposition file each plan derives
from. The legacy `docs/backlog/` files remain the long-form decomposition;
plans are the action-oriented projection into ralphex format.

## Track Map

| Plan | Conflict zone | Legacy decomposition |
| --- | --- | --- |
| [Device Driver Foundation](device-driver-foundation.md) | kernel core (`kernel/src/pci.rs`, `kernel/src/device_*.rs`, `kernel/src/cap/` device authority, IOMMU sections inside `kernel/src/acpi.rs` and `kernel/src/diagnostics.rs`); plus coordinated overlap with System Configuration Slice 3 on `capos-config/` and `tools/mkmanifest/` when DDF Task 5 adds ProcessSpawner/manifest plumbing | `docs/backlog/hardware-boot-storage.md`, `docs/dma-isolation-design.md` |
| [Paperclips Showcase](paperclips-showcase.md) | `demos/paperclips/`, `demos/paperclips-content/`, `tools/paperclips-content-gen/`, `system-paperclips.cue`, `schema/paperclips-content.capnp`; Paperclips-shared types in `schema/capos.capnp` use the shared serial surface | `docs/backlog/paperclips.md` |
| [Aurelian Frontier Followups](aurelian-frontier-followups.md) | `demos/adventure-*` (incl. `demos/adventure-content/content/prototype.cue` and `demos/adventure-scenario-test/`), `system-adventure.cue`; Adventure interfaces in `schema/capos.capnp` use the shared serial surface | `docs/backlog/aurelian-frontier.md` |
| [Remote Session CapSet Client](remote-session-capset-client.md) | `tools/remote-session-client/`, `demos/remote-session-capset-gateway/`, `demos/remote-session-chat-worker/`, `demos/remote-session-adventure-worker/`, `system-remote-session-*.cue`; remote-session DTO additions in `schema/capos.capnp` use the shared serial surface | `docs/backlog/remote-session-capset-client.md`, `docs/backlog/shared-service-demos.md` |
| [System Configuration Slice 3](system-config-slice-3.md) | only the focused-proof manifests this plan migrates (`system-spawn.cue`, `system-shell.cue`, `system-terminal.cue`, `system-credential.cue`, `system-login.cue`, `system-local-users.cue`, `system-login-setup.cue`, `system-network-client.cue`, `system-revocable-read.cue`, `system-memoryobject-shared.cue`, `system-restricted-shell-launcher.cue`, `system-telnet.cue`, `system-chat.cue`); plus `cue/defaults/`, `cue.mod/`, `capos-config/`, and `tools/mkmanifest/`. Demo manifests (`system-adventure.cue`, `system-paperclips.cue`, `system-remote-session-*.cue`) and `system-measure.cue` are owned by their respective plans, not by this row. | `docs/proposals/system-configuration-proposal.md` |
| [Measure Mode Repair](measure-mode-repair.md) | `demos/thread-lifecycle/`, `kernel/src/measure.rs` (narrow fix scope), `system-measure.cue` (only if the manifest must change) | `REVIEW_FINDINGS.md`, `docs/backlog/scheduler-evolution.md` |

## Concurrency Notes

The Track Map above is the conflict-avoidance contract. The selected
milestone -- currently Device Driver Foundation -- is the kernel-core serial
track and should not be run in parallel with another plan that touches
`kernel/src/cap/` device authority objects. The other plans are sized to
operate in disjoint subdirectories and can typically run concurrently in
separate `ralphex --worktree` instances.

`schema/capos.capnp` and the checked-in generated bindings under
`tools/generated/` are a shared serial surface across the Device Driver
Foundation, Remote Session CapSet Client, Aurelian Frontier Followups,
and Paperclips Showcase plans. (Paperclips-shared types such as
`PaperclipsGame`, `PaperclipsStatusSnapshot`, and the command/project
lists already live in `schema/capos.capnp`, so any Paperclips iteration
that extends those interfaces must also queue on the serial surface.)
Only one plan at a time may add or change interfaces in
`schema/capos.capnp`; the next plan must rebase on top of the resulting
generated-code refresh. `make generated-code-check` is the gate that
catches a stale binding before downstream Cargo builds. Plans that
exclusively own a demo-specific schema file
(`schema/paperclips-content.capnp` for Paperclips content tables) remain
outside this serial constraint, but only when the iteration does not
also touch `schema/capos.capnp`.

When a new plan is added, update the Track Map and explicitly call out any
overlap with active plans. A plan must declare why it can be run alongside
the selected milestone (e.g. demo subdir only, CUE-only, host-tooling only)
or stand down until the milestone is recorded.