# mergetrain full LLM operating guide

mergetrain is a local deploy train for coding-agent worktrees. It is not a
background job queue, cloud CI provider, deploy provider wrapper, or PR-first
merge queue.

## Contract

Agents should:
1. Work in task-specific branches and worktrees.
2. Commit a clean result before enqueueing.
3. Run `mergetrain doctor --json` before deciding the next queue action.
4. Enqueue with `mergetrain enqueue --task TASK --branch BRANCH --capture-sha`.
5. Never push configured deploy refs directly.
6. Leave merge/test/push/verify to one runner or daemon.
7. Use `--auto` only after explicit unattended-deploy approval.

## Status interpretation

- `queued`: waiting for a runner.
- `in_progress`: claimed by a single-job runner.
- `blocked`: merge conflict or user action needed.
- `failed`: gate or command failure.
- `validated`: validation succeeded without push; the exact train remains deployable after approval.
- `deployed`: deploy push succeeded; note may include post-push verify warning.
- `canceled`: user canceled the item.

## Safe commands

```sh
mergetrain status --json
mergetrain doctor --json
mergetrain agent-contract --json
mergetrain gc --json
```

## Consent-sensitive commands

```sh
mergetrain run-batch --deploy
mergetrain enqueue --auto ...
mergetrain gc --apply
mergetrain gc --apply --delete-branches
```

Do not infer consent from context. Require explicit user/operator approval for
unattended deploy and deploy execution.

After `run-batch --validate-only`, read `status --json.validated_trains` to
identify the approved `train_id`, member branches, and recorded HEADs. A later
`run-batch --deploy` rebuilds that train on the current integration ref and
reruns gates. If several validated trains are pending, pass `--train-id`.
Validated-but-not-deployed branches are never branch-deletion candidates for
`gc --delete-branches`.
