Unit Executor

Unit Executor

The leading principle is atomicity: one invocation owns one Unit Attempt and

either commits one accepted Completion or records one diagnosable block. It

never starts a second Unit.

Inputs

• UNITS.csv and the selected Unit row.
• Files declared by that row's inputs field.
• DECISIONS.md when the Unit is checkpoint-gated.

Outputs

• Files declared by the Unit's outputs field.
• Updated UNITS.csv, Run Evidence, and optional STATUS.md projection.
• output/QUALITY_GATE.md when strict quality checks block Completion.

Steps

1. Reconcile and select one Unit

Inspect the Workspace through the Pipeline adapter. Select the requested Unit,

or the first TODO Unit whose dependencies are DONE. Stop when a HUMAN

checkpoint, unresolved Decision, open Attempt, or integrity failure prevents

selection.

Completion criterion: exactly one eligible Unit is selected, or one blocking

condition is recorded with a concrete next action.

2. Open the Attempt

Start semantic work through the adapter, never by editing a status cell:

uv run python scripts/pipeline.py mark \
  --workspace workspaces/<name> \
  --unit-id <U###> \
  --status DOING \
  --note "starting semantic execution"

Completion criterion: the Unit is DOING and one matching open Attempt owns

the execution.

3. Execute the declared Skill

Read the selected Unit's Skill and only the context pointers required by this

branch. Produce the declared outputs without changing unrelated Workspace

artifacts.

Completion criterion: every required output exists or the failure is specific

enough to commit as BLOCKED.

4. Verify and commit Completion

Evaluate the Unit acceptance rule and strict quality contract when requested.

Commit through the adapter:

uv run python scripts/pipeline.py mark \
  --workspace workspaces/<name> \
  --unit-id <U###> \
  --status DONE \
  --note "acceptance checked"

Use BLOCKED with a concrete reason when acceptance fails. Do not directly

edit UNITS.csv; the adapter aligns Attempt, Artifact, Manifest, Decision, and

status projections.

Completion criterion: Completion is DONE with acceptance and provenance

evidence, or BLOCKED with a diagnosable Failure.

5. Stop after one Unit

Refresh the Workspace projection and report the completed or blocked Unit. Do

not claim end-to-end completion and do not start the next eligible Unit.

Completion criterion: exactly one Unit changed execution state during this

invocation and the next operator can resume from Workspace files.

Context Pointers

• The selected row in UNITS.csv owns dependencies, inputs, outputs,

acceptance, checkpoint, and Skill identity.

• The selected Skill owns semantic behavior.
• The locked Pipeline owns cross-Unit gates and target Artifacts.
• Use research-pipeline-runner for automatic continuation across Units.

Script

Quick Start

uv run python .codex/skills/unit-executor/scripts/run.py \
  --workspace workspaces/<name>

All Options

• --workspace <path>: existing Workspace.
• --unit-id <U###>: execute a specific eligible Unit.
• --inputs, --outputs, --checkpoint: Pipeline-runner compatibility

arguments.

• --strict: block scaffold-like outputs and write the quality-gate report.

Examples

Run exactly one strict Unit:

uv run python .codex/skills/unit-executor/scripts/run.py \
  --workspace workspaces/<name> \
  --strict

Equivalent adapter command:

uv run python scripts/pipeline.py run-one \
  --workspace workspaces/<name> \
  --strict

The helper returns 0 for DONE or IDLE, and 2 for BLOCKED or ERROR.

Troubleshooting

• When no Unit is runnable, inspect dependencies, checkpoint approvals, and

open Attempts before changing status.

• When a DONE Unit has missing outputs, reopen it through the adapter with an

explanatory note; never repair the CSV projection alone.