# mergetrain full LLM operating guide

For local, worktree-first repositories: queue committed branches from parallel
coding agents, test the combined tree in order, keep integration pushes under
one human-gated owner, and recover interrupted pushes. Not for single-agent
work or PR-first repositories already using GitHub Merge Queue or GitLab Merge
Trains.

## Shared operating protocol

<!-- BEGIN GENERATED: mergetrain-agent-protocol -->
Purpose: Serialize committed local task branches through one merge/test/push/verify runner.

### Rules

1. Work on a task-specific branch and worktree.
2. Commit a clean HEAD before handing work off.
3. Read mergetrain status --json and follow its next action before changing queue state.
4. Enqueue every named finished branch in the requested order using only its task, branch, and optional worktree; mergetrain captures the exact commits. Stop after the last successful enqueue unless the user explicitly authorized validation or the complete validation-and-deployment workflow.
5. Never push configured integration refs directly. One authorized runner owns validation and deployment; recovery and destructive actions require their stated approval.

### Safety boundary

- A task agent enqueues every named finished branch, then stops. "Queue for validation" authorizes enqueue only; only an explicit request to run validation or the complete end-to-end workflow authorizes `validate`.
- Only a separately authorized runner uses `deploy` or a daemon.
- Deployment requires either confirmation of the human-readable exact plan or prior bounded unattended approval. Train IDs and hashes stay internal.
- Unattended approval is bound to the exact destination and execution policy. Any change blocks before push.
- Recovery and destructive cleanup require their stated approval. Follow `status.next_action`; never rewrite permanent deploy audit refs.

### Stable machine contract

- Every JSON payload carries `contract_version`; ignore unknown keys and fail closed on unknown safety actions.
- `deploy` means the atomic Git ref update plus configured verification. A downstream provider release is separate.
<!-- END GENERATED: mergetrain-agent-protocol -->

## Product grammar

The six commands shown by default help are permanent:

```text
init  status  enqueue  validate  deploy  inspect
```

- `init` prints or safely writes the minimal config and generated instructions.
- `status` is the one state read and supplies the next safe action.
- `enqueue` verifies the matching clean worktree and captures both exact SHAs.
- `validate` assembles FIFO work and runs combined gates without pushing. It
  pauses while one exact train is already Ready.
- `deploy` validates if needed, displays the sole exact Ready plan, confirms,
  rechecks identity, applies the configured gate-reuse policy, atomically
  pushes, and verifies.
- `inspect` returns the detailed evidence for one job.

Routine task agents use `status --json`, `enqueue`, then stop. Operators with
bounded deployment authority use `status` and `deploy`; they do not select
trains or copy hashes. `deploy --json` may validate but never pushes. The MCP
adapter owns the supported non-interactive confirmation flow.

## State interpretation

`status --json` exposes five grouped job states:

- `waiting`: queued for validation;
- `running`: owned by the lease-fenced runner;
- `ready`: one exact validated train awaiting approval;
- `attention`: blocked, failed, unresolved remote truth, or unknown verify
  outcome;
- `done`: deployed or canceled, with the exact terminal value in `outcome`.

Use the human `summary` and structured `next_action`. Inspect a job only when
evidence is needed. Internal queue, push, verify, conflict, and recovery fields
remain available through inspect and diagnostics but must not be reinterpreted
as a competing state machine.

## Authority boundaries

An ordinary edit, fix, merge, integrate, or handoff request does not authorize
a push. A bounded request to QA, deploy, verify, and finish the named task to
the named destination permits unattended enqueue with the hidden `--auto`
option. That approval is bound to the exact destination and execution policy;
any change blocks before claim or push.

Interactive CLI and MCP deployment show a human-readable plan. The plan hash
and train identity are private bindings. A model cannot supply confirmation,
and an MCP client without form elicitation receives the ordinary terminal
command instead of a weaker path.

Recovery and destructive actions require their stated authority. When status
reports stranded or ambiguous push evidence, follow its exact command—normally
`mergetrain reconcile --apply`. Reconciliation asks the pinned remote endpoint
what landed and never blindly repeats a push. Never delete or rewrite
`refs/mergetrain/deploys/*`.

## Machine contract

mergetrain 3 uses machine `contract_version: 3` and config schema `version: 2`.
They are independent. Every one-shot JSON payload carries the contract version;
`ok` says the command produced a normal response, while run outcome lives in
`result`, repository condition in `health` and `state`, and failures in
`error.code`. Ignore unknown object keys. Unknown safety or next-action values
must stop mutation and be shown to the operator.

JSONL event streams put `contract_version` on `stream_start`. Dispatch frames
by `type` and resume only after a persisted event ID, never a heartbeat. Raw
logs may contain sensitive command output; prefer structured inspect evidence.

## Optional operations and integrations

Daemons, dashboard, Hub, evidence commands, repair, cleanup, and performance
settings are advanced surfaces. They remain hidden from default help. Do not
memorize them in routine agent behavior; `status.next_action.command` names an
exceptional command when one is needed.

The stdio MCP server exposes exactly:

```text
mergetrain_status
mergetrain_inspect
mergetrain_enqueue
mergetrain_validate
mergetrain_deploy
```

MCP does not expose unattended deployment, cancellation, recovery, forced
unlock, or destructive cleanup. The read-only dashboard and multi-repository
Hub do not own queue state.

See `docs/agent-contract.md`, `docs/contract.md`, `docs/cli.md`,
`docs/failure-modes.md`, and `docs/security.md` for authoritative details.
