# mergetrain for LLM agents

mergetrain serializes committed local branches through a SQLite queue and a
single Git worktree runner.

Rules:
- Work on a task branch/worktree.
- Commit before enqueueing.
- Do not push configured Git refs directly.
- Prefer `mergetrain doctor --json` and `mergetrain status --json`.
- Use `--auto` only after explicit unattended-deploy approval.
- Use `run-batch --validate-only` for validation and `run-batch --deploy` for deployment.
- After validation, deploy the exact `validated_trains` entry shown by status; do not assume newer queued jobs are included.

Core commands:
- `mergetrain enqueue --task TASK --branch BRANCH --capture-sha`
- `mergetrain status --json`
- `mergetrain doctor --json`
- `mergetrain inspect JOB_ID --json`
- `mergetrain events --job JOB_ID --after EVENT_ID --follow --jsonl`
- `mergetrain logs JOB_ID --tail 200`
- `mergetrain run-batch --validate-only`
- `mergetrain run-batch --deploy`
- `mergetrain daemon --once`

Vocabulary compatibility:
- `terminology.git_operation: integrate` makes human output prefer `--integrate`;
  `push` similarly prefers `--push`. Both are aliases of `--deploy`.
- Machine state stays `status=deployed` with `deploy_sha` for compatibility.
- Completion means configured Git refs were atomically pushed, not that a
  downstream provider release completed or was authorized.
