Jobs, Tasks, and Persistent State
When a loop runs, dmx creates a persistent record of what happened. That record is what makes background execution safe and what produces the audit trail.
Jobs
A job is a unit of work corresponding to a ticket or branch. One job tracks all the loop executions for a single piece of work, from the first Spec Loop through the final Release Loop.
Each job has a unique ID derived from the ticket ID or branch name. Job state lives in .dmx/jobs/{job_id}/.
Tasks
A task is a single loop execution within a job. Every time a loop runs, whether it completes, pauses, or fails, it creates a task record.
Each task tracks:
| Field | Description |
|---|---|
job_id / task_id | Identifiers for the job and this specific execution |
loop_name | Which loop ran (e.g. spec, plan, dev) |
status | pending, running, paused, iterating, complete, failed |
skills / current_skill_index | The full ordered skill list and how far execution has progressed |
skills_completed | Which skills have finished |
skill_outputs | Output recorded from each completed skill, keyed by skill name |
validator_results | Pass/fail results reported by each validator that ran |
outcome | success, warning, or failure, once validators have run |
iteration_count | How many times the skill sequence has repeated (for repeat_until loops) |
timestamp / updated_at | When the task started and was last updated |
Task state is written to .dmx/jobs/{job_id}/{loop_name}-{task_id}.json.
The active pointer
.dmx/loop-state.json points to the currently active loop execution. When the loop advances, pauses, or completes, this file updates. It is what loop_continue reads to know where to resume.
When a loop chain finishes, the active pointer is cleared.
Inspecting loop state
Job and task state is plain JSON committed to your repo. To see the current job, its active task, which skills have run, and validator results, ask your AI assistant about the current loop state (it reads the same files), or read .dmx/loop-state.json and the relevant .dmx/jobs/{job_id}/ files directly.
Why persistent state matters
Most AI coding sessions are ephemeral. Close the window, lose the context.
dmx's persistent state changes this in two ways.
Resumability. If you close your IDE mid-loop, the state is preserved. Open it the next day, run /dmx/loop-continue, and the loop picks up exactly where it left off.
Auditability. Every loop run and validator result is recorded. If someone asks how a change was verified, the answer is in the job directory: which validators ran and what they found.
State in your repository
All dmx state lives in .dmx/, committed to your repository. This means every developer can see the current job state, reviewers can inspect what the AI produced and how validators ran, and there is no external dependency to manage.
The tradeoff is that .dmx/jobs/ grows over time. Archiving or pruning closed job directories periodically is reasonable, just as you would clean up merged branches.