ROOT Planning and Task Delta

ROOT planning, rules, and task delta

The optional ROOT/ layer connects a request, its planning structure, canonical tasks, and observations from an IDE/harness or a cloud/bot task list. Use it when one project spans several execution surfaces or needs more planning detail than a milestone table. A small task can continue using the existing Master Plan and WORK/TASKS.json alone.

This guide describes the published 1.11.0-alpha.6 interface. Use a reviewed compatible selection; the wiki can describe features newer than your installed defaults. The versioned SX-RULES.md and SX-MILESTONE.md are the fixed portable guides for that release. See Versions and changelog for verification and publication evidence.

Each record has one responsibility

Record in the selected .SYSTEMX or .SYSTEMXP	Responsibility
ROOT/SX-RULES.md	Internal coordination rules: scope, task authority, bounded work, evidence, reconciliation, and stopping
ROOT/SX-MILESTONE.md	Shared planning vocabulary, generic tool-card contract, and worked examples
ROOT/PLAN.json	Originating/delegated request records and structural planning nodes referencing existing milestones/tasks
ROOT/MIRRORS.json	Explicit external-item bindings, timestamped observations, and reviewed tool cards
PLAN/MASTER-PLAN.md	Accepted outcomes, declared M-... milestone IDs, dependencies, and acceptance requirements
WORK/TASKS.json	The single canonical task status, owner, dependencies, evidence, and acceptance history
WORK/FOCUS.json	Current objective, existing task IDs, and optional checkpoint reference
Agent X/Y/Z records	Existing event/time records, CLI job lifecycle, and fixed-policy review evidence

SX-RULES.md describes how to use SYSTEMX. It does not override the user's instructions, a higher-priority instruction, host permissions, or a service's actual access controls. Project/company policy may be linked with its source, scope, and review date; a local document cannot grant external authority.

ROOT records start blank in the public template. No real project, founder profile, research topic, machine path, or private chat is copied into the seeds.

The directory name ROOT/ denotes this optional coordination layer. The CLI selector --root selects the outer record scope, while RTask denotes request origin. Those three uses do not grant operating-system root access.

Mesh the vocabulary without multiplying the work

Use this common order when a project needs all levels:

flowchart TD
    R["RTask: originating request"] --> S["STask: optional delegated request"]
    R --> M["Milestone: accepted outcome or checkpoint"]
    S -. "bounded scope" .-> T
    M --> W["Wave: group of related phases"]
    W --> P["Phase: coherent task list"]
    P --> G["Group: optional task collection"]
    G --> T["Task: canonical TASK ID"]
    T --> U["Subtask: optional smaller scope"]
    U --> A["Single action: next concrete step"]

Loading

The diagram describes planning meaning, rather than a mandatory execution chain. Requests provide provenance; a delegated request can cover several tasks without becoming another depth level. A milestone node references an M-... ID already declared in the selected Master Plan. Planning nodes carry references and structure, rather than a second set of task statuses.

Term	Practical meaning	Rule
Milestone	A measurable outcome or major checkpoint	Require the agreed evidence; structural progress never accepts it automatically
Wave	A group of related phases that contributes to an outcome	Size it for dependencies and review capacity; it need not run concurrently
Phase	A coherent task list, such as discovery or integration	Group work by purpose and its gate
Group	Optional collection within a phase	Omit it when it adds no useful distinction
Task	Bounded work with ownership and acceptance	Use an existing canonical TASK-... ID
Subtask	Optional finer planning detail	Give independently owned/accepted work its own canonical TASK-... ID
SingleTask / single action	One concrete step within a task	Represent it with an action node or a checklist/next action unless separate ownership or acceptance is needed
RTask	The originating request from a person or harness	Keep the accepted objective/source reference stable
STask	A child, follow-up, or delegated request linked to its parent request	State its narrower scope; it starts no separate agent and changes no task state
Event	An observed incident, crash, bug, unknown, or time observation	Record with Agent X and link relevant tasks; it is not a planning depth

Skip optional levels. For a small change, a milestone and one task may be enough. For a larger app, a milestone might have two waves, each with a few phases and only the tasks needed next. Display labels such as 01-01-01 are navigational addresses; use stable record IDs for references when the plan is rearranged.

There is no mandatory 10-by-10 nesting. Ten phases × ten waves × ten groups × ten tasks × ten subtasks × three actions would produce 300,000 actions for one milestone. Generating that skeleton would spend context and create maintenance work before discovering whether those actions are needed. Expand the next bounded segment, retain later outcomes at a higher level, and revise the plan when new evidence changes the scope. Worker limits and the ten-task focus limit are separate execution constraints.

A ready execution batch is the non-conflicting work selected for concurrent workers. It can draw tasks from an eligible phase or wave; it does not redefine “wave,” erase dependency gates, or authorize additional processes.

Reconcile three task surfaces

1. SYSTEMX: canonical tasks, focus, plans, evidence, and acceptance.
2. IDE/harness: the app's current plan items, native subagents, tool results, and UI task state.
3. Optional cloud/bot: provider run IDs, remote task items, automation observations, or a CLI/bot's execution state.

These surfaces need traceable agreement about the same work; they do not need the same number of rows. One IDE item can map to several canonical tasks, and one task can have several provider attempts. Bind each external identity to its actual selected scope and existing TASK-... references.

flowchart LR
    C["WORK/TASKS.json\ncanonical task + acceptance"] --> D["Read-only ROOT delta"]
    H["Harness item\nidentity + observed state/revision"] --> D
    B["Cloud/bot item\nidentity + observed state/revision"] --> D
    F["Binding + task fingerprint\ntime + evidence"] --> D
    D --> Q["Explain mismatch / unknown\nchoose next reconciliation action"]
    Q --> O["Authorized owner reviews\nthen updates the correct surface"]

Loading

A saved observation records what a caller saw, at a stated time and source revision, plus its evidence references. It is a snapshot, not a live connector or proof that remote work happened. A later change to the canonical task makes an earlier observation's task fingerprint stale even if its raw label still looks compatible.

root delta reports mapping, freshness/revision, and status differences for a bounded selection. It assesses the harness layer by default. Use repeated --layer harness --layer bot to assess both; a layer you omit is explicitly not_assessed, rather than missing or implicitly synchronized. Do not invent a bot item when the project uses no bot. An observation without --expected-revision keeps the revision explicitly unverified. When supplied, the expected revision is a caller-declared comparison value; SYSTEMX does not fetch the external source to establish its truth. Treat unmapped, stale, unknown, unavailable, or unverified items as unresolved. A successful local command means that the bounded operation completed; it cannot prove an IDE plan, provider account, or cloud application remains synchronized. Read back the actual external surface using its available authorized tools, then record a fresh observation. Default freshness is change-based. A deliberate root delta --max-age-seconds N can add an age boundary for time-sensitive work; expiry is a reason to inspect the situation, not an automatic retry schedule. The default selection uses current focus when available, otherwise active tasks first, with 10 tasks returned by default. --task selects explicit existing IDs and --limit accepts 1–100. Coverage counts and truncation state describe the selected candidate set; a bounded result is not a claim about every task in the ledger. At most ten matching bindings per task/layer are returned, with truncation reported.

Correct a binding with root bind ... --supersedes BIND_ID, using a new key and retaining the original history. Supersession keeps the same layer/channel. A corrected mapping can retain the same external item and revise its task set; a replacement external attempt can change the item only while retaining the same canonical task set. Original bindings and observations remain stored, while the superseded binding leaves the current comparison. Supersession does not cancel a provider job, close a PR, or remove external resources. Verify the earlier process handle before starting conflicting replacement work. Current binding alignment does not claim that every historical attempt succeeded.

Preserve meaning when status vocabularies differ

External observation	What the owner must still establish
Pending / running	Which canonical tasks it covers and whether their recorded state agrees
Blocked	The actual blocker, scope, and next action; do not reduce it to plain pending
Completed / CLI exit 0	Execution may be ready for review; task acceptance and any live outcome remain separate
Cancelled	Retained work, cancellation reason, and owned-resource disposition
Unknown / unavailable	Access or evidence is missing; no completion inference

An external item covering several canonical tasks is compared with the aggregate state of all bound tasks, including members outside the requested delta selection. One accepted task plus one active task expects a running item; it does not create a mismatch merely because the accepted member is done. All remaining non-cancelled members done/under-review can project to completed, while canonical acceptance remains separate for each task. A change to any bound member makes the captured canonical fingerprint stale. The comparison does not hide a changed member merely because only another member was selected.

For an external item, cancelled members are omitted when other members remain; their canonical cancellation/history stay intact. Projection rules apply in this order:

Covered canonical tasks	Compatible external state
All cancelled	cancelled
Remaining members all done or needs-review	completed
Blocked plus in-progress	blocked or running
Blocked without in-progress	blocked
In-progress, or done/review mixed with pending work	running
Remaining members all todo	pending

An IDE may expose only pending, in-progress, and completed. That lossy projection must preserve SYSTEMX blocked, needs_review, and cancelled distinctions in annotations/evidence. Never mark a canonical task done merely to match a provider's completed label. Agent 0 or the user accepts a task through the existing reviewed transition after its criteria are met.

A useful reconciliation pass reads the canonical task and exact external item, compares revisions and evidence, classifies the difference, updates only the correct surface under existing authority, and records the readback. Stop when the evidence has not changed or access is unavailable. Do not repeat the same check indefinitely or create a new worker just because a delta exists.

Initialize and use the selected scope

ROOT is optional in adopted projects. Initialization previews missing files; --apply adds the reviewed seeds while preserving existing project files. Enable it separately in each scope where it is useful. Run relative launcher commands from the outer workspace directory containing the intended .SYSTEMX:

cd "/path/to/workspace"
# Outer records: preview, then apply the reviewed addition.
bash .SYSTEMX/SYSTEMX.sh root init
bash .SYSTEMX/SYSTEMX.sh root init --apply
bash .SYSTEMX/SYSTEMX.sh root status

# A registered child has independent ROOT records.
bash .SYSTEMX/SYSTEMX.sh projects root init --project Project-A
bash .SYSTEMX/SYSTEMX.sh projects root init --project Project-A --apply
bash .SYSTEMX/SYSTEMX.sh projects root status --project Project-A

# Installed manager: target is the directory containing outer .SYSTEMX.
systemx run --target /path/to/workspace --offline -- root status
systemx projects --target /path/to/workspace -- root delta --project Project-A

The child does not receive another CLI/default cache or nested .SYSTEMX. .SYSTEMX/ROOT means the outer record layer; a child's equivalent is .SYSTEMX/Projects/Project-A/.SYSTEMXP/ROOT. Root and child IDs are local to their scope. Include that scope in every handoff.

root packet --task TASK_ID returns selected canonical work and bounded related request/node/card references. Repeat --task to select several tasks; --limit accepts 1–10 and the complete packet must fit 64 KiB. The command reports selection truncation and refuses an oversized packet, rather than silently removing task acceptance criteria. Select fewer tasks and leave large evidence behind references when needed. It makes no remote observation or tool call.

The packet cap measures the actual final CLI output in UTF-8 bytes, including indented JSON, scope/limit metadata, and its trailing newline. Other ROOT command replies are bounded to 128 KiB. An output-cap refusal happens before a request/node/binding/observation/card replaces its ledger; initialization also checks its final response before writing scaffolds or an operation log. This specific rejection leaves records unchanged. Other filesystem failures retain the normal atomic-write and operation-receipt behavior.

root status derives milestone task counts from unique canonical task IDs, including descendant references and canonical milestone assignments. Counts show recorded task progress, while milestoneAcceptanceEstablished remains false: accepting the milestone's outcome still requires the agreed review. An empty set is not an accepted milestone.

Capture request origin and planning references

Run this example only in an adopted project. Replace example references and use the IDs actually returned by each command:

bash .SYSTEMX/SYSTEMX.sh root request \
  --key initial-brief --kind rtask --title 'Build the accepted application' \
  --source-ref 'approved-brief.md' --apply

An STask uses --kind stask --parent RETURNED_REQUEST_ID with its own title, source reference, and stable key. Declare M-001 in the selected PLAN/MASTER-PLAN.md table before creating its canonical task. For example:

| ID | Outcome | Acceptance evidence required | Dependencies | Task IDs |
| --- | --- | --- | --- | --- |
| M-001 | Reviewed project baseline | Reproducible setup and retained relevant checks | None | Fill with the returned task ID |

Then create the task with that same canonical milestone assignment:

bash .SYSTEMX/SYSTEMX.sh task-add \
  --title 'Establish the project baseline' --milestone M-001 \
  --acceptance 'Setup is reproducible and relevant verification evidence is retained' \
  --next 'Inspect the actual project setup and required checks'

The following commands assume the returned ID is TASK-001 in a fresh ledger. Use the actual returned ID throughout if it differs. Add that ID to the Master Plan row. An existing unassigned task cannot be placed under an M-001 planning node; its canonical milestone must already match. The standard task-set command does not reassign milestones. Omit milestone ancestry for unassigned work, or review a deliberate canonical-record migration while preserving its history. Declaring a milestone is not accepting its outcome.

bash .SYSTEMX/SYSTEMX.sh root node \
  --key baseline-outcome --kind milestone --title 'Reviewed project baseline' \
  --request RETURNED_REQUEST_ID --milestone M-001 --apply
bash .SYSTEMX/SYSTEMX.sh root node \
  --key baseline-task --kind task --title 'Establish the project baseline' \
  --request RETURNED_REQUEST_ID --parent RETURNED_MILESTONE_NODE_ID \
  --task TASK-001 --apply

root node supports milestone, wave, phase, group, task, subtask, and action kinds. Referencing tasks does not create, reassign, or complete them. Keys make a repeated intended operation identifiable; inspect an existing result rather than creating duplicate records with a different key.

Bind an external item and record a readback

bash .SYSTEMX/SYSTEMX.sh root bind \
  --key app-plan-baseline --layer harness --channel 'current-ide-session' \
  --item 'actual-plan-item-id' --task TASK-001 --apply
bash .SYSTEMX/SYSTEMX.sh root observe \
  --key baseline-readback-1 --binding RETURNED_BINDING_ID \
  --raw-state 'in progress' --state running \
  --revision OBSERVED_SOURCE_REVISION \
  --expected-revision EXPECTED_SOURCE_REVISION \
  --evidence 'retained-tool-result-or-record-reference' --apply
# Assess the actual layers used by this project.
bash .SYSTEMX/SYSTEMX.sh root delta --task TASK-001
bash .SYSTEMX/SYSTEMX.sh root delta --task TASK-001 --layer harness --layer bot

Use --layer bot for an actual cloud/bot/provider identity. Repeat --task on a binding for several existing tasks and --evidence on an observation for multiple references. The fresh task in the example is still canonical todo; a real external running observation therefore exposes state_difference. That is a successful report of disagreement, not a command failure. Record the actual external state and follow the normal task workflow; do not rewrite a canonical state simply to make the delta look aligned. Assessing bot without a real bot binding likewise reports unmapped work.

The normalized observation states are pending, running, blocked, completed, cancelled, unknown, and unavailable; preserve the original label in --raw-state. An optional --at supplies an actually observed time. Evidence references and revision strings remain caller claims until independently checked. Keep credentials and raw private transcripts out of public records.

When the harness has no plan revision ID

Some harness plan tools expose an item list without a native revision. Capture the actual observed plan snapshot and use a reproducible digest of that snapshot when a revision identity is needed. Label it plan-snapshot digest (for example observed-snapshot:sha256:ACTUAL_DIGEST), retain the capture time, scope/tool readback evidence, and document the normalization used to make the digest reproducible. A Git commit ID describes source code; it cannot silently stand in for the harness plan's version.

If no trustworthy source revision or snapshot is available, retain revision_unverified by omitting --expected-revision and recording the limitation honestly. Equality between caller-supplied source and expected revision strings remains an attested comparison. ROOT does not fetch the plan or authenticate either value.

Use a tool card without inventing a universal tool API

A tool card is a bounded, inspectable handoff describing the selected task, request/scope, advertised capability, reviewed inputs, expected effect, permissions, source revision, required evidence, and stopping condition. It helps a model choose the next real tool call. It does not install a provider, create a tool, bypass consent, or execute a shell/MCP call by existing on disk. For example, after identifying an existing task and the real enabled tool:

bash .SYSTEMX/SYSTEMX.sh root card \
  --key inspect-baseline --task TASK-001 \
  --provider ACTUAL_HARNESS_OR_PROVIDER --tool ACTUAL_ADVERTISED_TOOL_NAME \
  --purpose 'Inspect the agreed baseline evidence' \
  --input-revision REVIEWED_INPUT_REVISION \
  --expected-evidence 'Retained result with task and source revision' \
  --permission-boundary 'Read only within the accepted project scope' \
  --stop-condition 'Return the result or the first unresolved access blocker'

Inspect the preview, then repeat with --apply to save the card. Repeat --task or --expected-evidence where appropriate; optional --request links the originating/delegated request. Saving a card does not invoke its named tool.

The host supplies available tool names, input schemas, confirmations, and results. Inspect those capabilities in the current session and use the actual advertised interface. VS Code tools can be built in, extension-provided, or MCP-provided; their availability depends on the session's enabled tools. VS Code tools documentation, extension tool contract. MCP exposes a discovery/call protocol and input schemas; SYSTEMX's card does not implement that protocol or turn a hint into an authorization boundary. MCP tool specification.

Keep argument descriptions minimal and reviewed. Use existing Agent Y jobs for provider execution, Agent X events for observed timing/incidents, and canonical task evidence for acceptance. A card links those records rather than duplicating full job histories, prompt transcripts, or output streams.

How the roles work together

Role	ROOT coordination responsibility
Agent 0	Resolve the originating objective and scope, select bounded ready work, reconcile delta, review evidence, and own task acceptance
Agent X	Record actual events/time and link task/revision/evidence; preserve failed attempts without automatically retrying
Agent Y	Carry a separately authorized CLI task and optional draft-PR handoff under its existing lifecycle gates
Agent Z	Apply its fixed review to the named subject/policy/evidence revision; changed inputs may justify another review
AGENTA / Agent Alpha	Retrieve selected specialist detail and reuse unchanged results with their original evidence time
Native subagent / external bot	Execute the bounded assignment its actual harness authorized, then return an evidence-backed result

A request, event, card, or mismatch does not automatically trigger every role. Call only the role needed next. Agent Z's score cannot accept a task, Agent Y's exit code cannot certify delivery, and AGENTA's detail result cannot change the canonical backlog. Agent 0, Agent X, Agent Y, Agent Z, Agent Alpha.

Worked project pattern

For a new web app, accept one researched brief as an RTask. Declare milestone M-001 for a verified foundation, organize a small discovery/foundation wave, and give each phase only the tasks that can currently be scoped. Map the IDE's “Foundation” item to those tasks; bind a provider attempt separately if Agent Y or an authorized cloud bot is used.

When a provider reports completed, record that observation and retain its actual revision/output. Review the diff/checks against the original task criteria; use needs_review while acceptance is pending. An incident becomes an Agent X event and, if actionable, a separately scoped follow-up task. After acceptance, refresh the harness/cloud projection and save the readback. Later delivery and live verification remain explicit tasks with their own required evidence.

For two research topics, use registered child scopes Project-A and Project-B when sources, access, or acceptance differ. Each child's Global context, Master Plan, tasks, ROOT records, and memory remain independent. Keep only deliberately shared constraints and portfolio outcomes in the outer records. A source URL provides a location; actual read/write access and transport remain external.

Checkpoint and stop

On interruption, preserve the accepted objective, scope, request/node/task IDs, source and evidence revisions, actual last observations, failed attempts, remaining delta, blocker, and one concrete next action. Save a session checkpoint and select it in focus when appropriate. An explicit stop/pause instruction ends new execution; checkpointing must not silently restart workers or loops.

A later session checks the saved revisions and changed inputs, then resumes the next authorized step. Reuse still-valid evidence and report its original time. Read only the relevant ROOT segment and selected role/reference detail; the entire planning tree is not required context for every turn.

Planning and memory · Task workflow · One-shot project guide · Shared workspaces, clouds, and bots · CLI and Tools

ROOT in the four-part 4K field guide

The refreshed four-part infographic shows this layer together with Agent 0/X/Y/Z, AGENTA, all ten AUTOBOTS, DATA, and named .SYSTEMXP scopes. The overview identifies internal rules/planning and the three task surfaces; the detailed pages trace selected evidence and context routing. Read the accompanying text for exact file paths and limits. The pictures show a coordination workflow: local observations → read-only delta → Agent 0's authorized tool action → external readback. They do not install an IDE/cloud connector, synchronize TODOs in the background, or accept a task because an external item reports completed.