---
name: unit-executor
description: |
  Execute exactly one runnable unit from `UNITS.csv` (first TODO whose dependencies are DONE), then update unit status and artifacts.
  **Trigger**: unit executor, run one unit, next unit, step-by-step pipeline, 逐条执行, UNITS.csv.
  **Use when**: 需要严格“一次只做一个 unit”（可审计、可中断），并遵守 checkpoints/HUMAN 阻塞逻辑。
  **Skip if**: 要端到端自动跑（用 `research-pipeline-runner`）或 workspace 不存在。
  **Network**: none.
  **Guardrail**: 只执行一个 unit；满足验收且输出存在才可标 `DONE`；遇到 HUMAN checkpoint 必须停下。
---

# Skill: unit-executor

## Goal

- Execute **one** unit end-to-end and leave the workspace in a consistent state.

## Inputs

- `UNITS.csv`
- Unit inputs listed in the row (files)

## Outputs

- Unit outputs listed in the row (files)
- Updated `UNITS.csv` status (`TODO → DOING → DONE/BLOCKED`)
- Optional: `STATUS.md` updated

## Procedure (MUST FOLLOW)

1. Load `UNITS.csv` and find the first unit with:
   - `status=TODO`
   - all `depends_on` units are `DONE`
2. Set its status to `DOING` and persist `UNITS.csv`.
3. Run the referenced skill (by following that skill’s `SKILL.md`).
4. Check the unit’s `acceptance` against produced artifacts.
5. If acceptance passes, set status to `DONE`; otherwise set to `BLOCKED` with a short note in `STATUS.md`.
6. Stop after one unit (do not start the next unit automatically).

## Acceptance criteria (MUST CHECK)

- [ ] Exactly one unit changes from `TODO` to `DONE/BLOCKED` (via `DOING`).
- [ ] Output files exist (or acceptance explicitly allows otherwise).

## Side effects

- Allowed: edit workspace artifacts (`UNITS.csv`, `STATUS.md`, unit outputs).
- Not allowed: modify `.codex/skills/` content.

## Script

### Quick Start

- `python .codex/skills/unit-executor/scripts/run.py --help`
- `python .codex/skills/unit-executor/scripts/run.py --workspace <workspace_dir>`

### All Options

- `--strict`: enable quality gate (blocks on scaffolds; writes `output/QUALITY_GATE.md`)

### Examples

- Run exactly one unit (strict):
  - `python .codex/skills/unit-executor/scripts/run.py --workspace <ws> --strict`
- Equivalent repo wrapper:
  - `python scripts/pipeline.py run-one --workspace <ws> --strict`

### Notes

- Returns 0 on `DONE/IDLE`, 2 on `BLOCKED/ERROR` (useful for automation).

## Troubleshooting

### Issue: no runnable unit is found

**Fix**:
- Check `UNITS.csv` for unmet dependencies, missing outputs, or `owner=HUMAN` units waiting on approvals in `DECISIONS.md`.

### Issue: a unit is marked `DONE` but outputs are missing

**Fix**:
- Fix the status to `TODO`/`BLOCKED` and re-run; only mark `DONE` when acceptance criteria and outputs are satisfied.