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

### Existing queues and explanations

- Existing mergetrain repositories keep status → enqueue → stop even for one branch. Queue counts alone do not establish health, runner ownership, or recovery needs; read `health`, `state`, and `next_action` together.
- For explanation-only requests, read the skill documentation when permitted and explain the procedure without Git or product commands. Distinguish hypothetical steps from observed state.

### Current command reference

- The v3 core commands are `init`, `status`, `enqueue`, `validate`, `deploy`, and `inspect`.
- Start with `mergetrain status --json`. Use `mergetrain status --diagnose --json` only for configuration, Git, runtime, or lock detail, and `mergetrain inspect JOB_ID --json` for job evidence. `doctor` is removed, not an alias for `status --diagnose`.
- Confirm uncertain syntax with the installed `mergetrain --version` and command-specific `--help` only when command execution is permitted. Otherwise use this reference and identify missing details; do not invent commands or copy older syntax from unversioned web results. Inspection and `next_action` do not authorize recovery or deployment.

### 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 and branch; mergetrain resolves the worktree and 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. Agents never select train IDs or supply plan hashes; structured evidence may include identifiers for inspection.
- 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 uses machine `contract_version: 5` 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, 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 multi-repository Hub does 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.
