Plans
This directory holds per-track plan files designed for autonomous execution by
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:
- Start with
# Plan: <title>. - Declare a
## Validation Commandssection listing the actual project gate commands (cargo aliases,maketargets, host tests). ralphex runs them between iterations to confirm the diff is still green. - 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 inOverview,Conflict Surface,Validation Commands, orSuccess Criteria– ralphex would interpret them as extra iterations. - Include a
## Conflict Surfacesection 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 viaralphex --worktree.
Plans land here in three lifecycle states:
- Active: pulled into the current execution rotation. The track’s owner sits
in
WORKPLAN.mdif 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 whenmove_plan_on_completionis 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 | 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 | 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 | 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 | 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 | 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 | 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.