# 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.
- After a crash, resolve `needs_reconcile` jobs with `reconcile`/`recover` against the remote; deploy is refused while any job needs reconciling.
- Across several repos, read the whole machine with `mergetrain hub status --json`; the hub is read-only and owns no queue state.
- A job `blocked` with a non-empty `conflict_with` is a semantic conflict: it passes gates alone but fails combined with the listed job IDs. Rebase onto the integration branch with the partner's change merged, fix the joint breakage, and enqueue a fresh job.
- Every `--json` payload and the `stream_start` JSONL frame carry `contract_version` (currently 1; separate from the product version). `ok` means only "the command ran without an error envelope" — branch outcomes on `result`, repo health on `health`, failures on `error.code`. Ignore unknown keys; dispatch JSONL on `type`. See `docs/contract.md`.

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`
- `mergetrain reconcile` (dry-run) / `mergetrain recover` (apply, after a crash)
- `mergetrain hub add REPO` / `mergetrain hub status --json` / `mergetrain hub` (dashboard)
- `mergetrain hub daemon --once` (auto-only, across registered repos)

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.
