# mergetrain full LLM operating guide

mergetrain is a local Git integration 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 Git 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; inspect `push_status` and `verify_status`
  for the independent push and post-push verification outcomes.
- `canceled`: user canceled the item.

## Safe commands

```sh
mergetrain status --json
mergetrain doctor --json
mergetrain agent-contract --json
mergetrain inspect JOB_ID --json
mergetrain events --job JOB_ID --after EVENT_ID --follow --jsonl
mergetrain logs JOB_ID --tail 200
mergetrain gc --json
```

For long runs, prefer `inspect` or scoped `events --follow` over OS process
inspection. JSONL is one object per line: persisted `type=event` rows have the
resume ID, ephemeral `type=heartbeat` rows report lease progress, and the final
`type=stream_end` row reports success, failure, cancellation, lost lease, or
interruption. Reconnect after the last persisted event ID, not a heartbeat.
`logs` explicitly exposes raw local command output and may contain secrets;
structured events do not copy subprocess output.

## 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.

Repositories may configure `terminology.git_operation: integrate` or `push`.
Human output and the preferred `--integrate`/`--push` alias follow that setting,
but the JSON/SQLite contract remains `status=deployed`, `deploy_sha`, and
`deploy.*`. Completion proves the configured Git refs were atomically updated;
`deploy.verify` reports an independent post-push outcome, and a provider release
remains a separately labeled and authorized action.

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`.

Validated-gate reuse is disabled by default. Use an explicit
`deploy.reuse.enabled` policy or `run-batch --deploy --reuse-validated` only
after inspecting `--preview --json`. Reuse requires an unchanged integration
base, task heads, train membership, validation commit/tree, gate policy,
environment fingerprints, and age; otherwise it reruns all gates or fails
closed. The exact reused commit is `reused_validation_sha`. Post-push verify
hooks always run.

Run JSON distinguishes `result=warning` from full success. In particular,
`status=deployed`, `push_status=succeeded`, and `verify_status=failed` means the
remote ref changed successfully but post-push verification still needs
attention; do not report that outcome as a failed push or a full success.
