### Install and run mergetrain MCP server

Source: https://github.com/yongjip/mergetrain/blob/main/docs/mcp.md

Installs the mergetrain MCP server as a uv tool and starts the stdio server. The published MCP Registry manifest launches the pinned package with uvx and the mcp extra.

```sh
uv tool install 'mergetrain[mcp]'
mergetrain mcp
```

--------------------------------

### Install and verify package from TestPyPI

Source: https://github.com/yongjip/mergetrain/blob/main/docs/release.md

After the TestPyPI publish job completes, create a fresh virtual environment and install the exact version from TestPyPI. Then run the installed CLI to verify the version and the dashboard help output. Package versions are immutable on each index, so bump the version before repeating an upload.

```shell
python -m venv /tmp/mergetrain-testpypi
/tmp/mergetrain-testpypi/bin/python -m pip install \
  --index-url https://test.pypi.org/simple/ --no-deps mergetrain==0.1.0
/tmp/mergetrain-testpypi/bin/mergetrain --version
/tmp/mergetrain-testpypi/bin/mergetrain dashboard --help
```

--------------------------------

### Install mergetrain from community catalog

Source: https://github.com/yongjip/mergetrain/blob/main/integrations/claude/plugin/README.md

Alternative installation after community-directory approval. Uses the anthropics/claude-plugins-community marketplace.

```sh
claude plugin marketplace add anthropics/claude-plugins-community
claude plugin install mergetrain@claude-community
```

--------------------------------

### Build and install mergetrain

Source: https://github.com/yongjip/mergetrain/blob/main/docs/development.md

Commands to build the project using the hatchling backend and install the resulting wheel.

```sh
python -m build
python -m pip install dist/*.whl
mergetrain --version
```

--------------------------------

### Install, initialize, enqueue, and deploy with mergetrain

Source: https://github.com/yongjip/mergetrain/blob/main/README.md

Installs the mergetrain CLI and its integrations, then initializes a repository, enqueues a task branch, and deploys. For long-running gates, run mergetrain validate earlier; it never pushes and leaves one exact train Ready for the later deploy confirmation. deploy names the configured atomic Git ref update and does not imply an App Store, Kubernetes, or other provider release.

```sh
# Install the machine-level CLI
uv tool install mergetrain          # or: pipx install mergetrain
# macOS: brew install yongjip/tap/mergetrain

# Codex: add the Git marketplace, then install the native skill + pinned MCP server
codex plugin marketplace add yongjip/mergetrain --ref main
codex plugin add mergetrain@mergetrain

# agy: install the native skill + pinned MCP server
agy plugin install https://github.com/yongjip/mergetrain

cd /path/to/your/repo

# Write .mergetrain.yaml plus agent instructions
mergetrain init --project my-app --write

# After an agent commits its task branch
mergetrain enqueue \
  --task "add health check" \
  --branch agent/health

# Read state and deploy end to end
mergetrain status
mergetrain deploy
```

--------------------------------

### Install mergetrain globally with uv tool or pipx

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Recommended global install for the machine-level CLI. Use uv tool install (recommended) or pipx install as an equivalent alternative. On Homebrew/Debian-managed Pythons, a bare pip install outside a virtualenv is rejected with an externally-managed-environment error (PEP 668), so use these tools instead.

```sh
uv tool install mergetrain      # recommended
pipx install mergetrain         # equivalent alternative
```

--------------------------------

### Install mergetrain Claude Code plugin

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Adds the repository marketplace and installs the plugin with Claude Code and uv installed. The same commands are available interactively as /plugin marketplace add and /plugin install. The plugin does not grant deployment, unattended-operation, or recovery authority.

```sh
claude plugin marketplace add yongjip/mergetrain
claude plugin install mergetrain@mergetrain
```

--------------------------------

### Try mergetrain without installing with uvx

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Runs mergetrain's help without installing anything, using uvx.

```sh
uvx mergetrain --help
```

--------------------------------

### Run tests with pytest and coverage check

Source: https://github.com/yongjip/mergetrain/blob/main/docs/development.md

Install the dev extra dependencies, run tests with pytest-xdist and coverage reporting, then verify critical coverage.

```sh
python -m pip install -e ".[dev]"
python -m pytest -q -n auto --cov=mergetrain --cov-report=term-missing --cov-report=json:.coverage.json
python scripts/check_critical_coverage.py .coverage.json
```

--------------------------------

### Verify mergetrain installation

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Checks the installed version and diagnostic status. --version is the stable one-line compatibility check. Diagnostic status identifies the imported package path, wheel/editable install mode, and Git commit/dirty state when discoverable, useful for detecting a stale editable install.

```sh
mergetrain --version
mergetrain status --diagnose --json
```

--------------------------------

### Install mergetrain in editable mode

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Installs the current source checkout in editable mode for local development.

```sh
python -m pip install -e .
```

--------------------------------

### Run with Codex adapter

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/agent_adoption/README.md

Uses the repository's controlled benchmark adapter to preserve traced `git` and `mergetrain` after macOS login-shell initialization. The adapter uses an ephemeral `ZDOTDIR`, restores the harness wrapper directory at the front of `PATH`, passes required trace variables explicitly, disables shell-command network access, and starts a fresh ephemeral Codex session with user config ignored. Use `--codex`, `--model`, or `--reasoning` only when the corresponding provenance fields are changed too.

```sh
python3 -m benchmarks.agent_adoption.harness run \
  --run-dir /tmp/mt-adoption-run \
  --agent-product codex \
  --agent-version 0.150.1 \
  --model gpt-5.6-sol \
  --reasoning-setting max \
  --permission-profile 'approve-for-edit(workspace-write); add-dir=control; shell-env=core+explicit-trace+controlled-zprofile; shell-network=disabled; ignore-user-config; ephemeral' \
  -- python3 "$(pwd)/benchmarks/agent_adoption/codex_launcher.py" \
    /tmp/mt-adoption-run/prompt.txt \
    /tmp/mt-adoption-run/control
```

--------------------------------

### Install mergetrain with yaml extra (compatibility alias)

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Existing install commands that select the historical yaml extra remain valid, but the extra is now a no-op compatibility alias. New installs should simply use mergetrain without the extra.

```sh
uv tool install 'mergetrain[yaml]'
python -m pip install 'mergetrain[yaml]'
```

--------------------------------

### Install development dependencies

Source: https://github.com/yongjip/mergetrain/blob/main/CONTRIBUTING.md

Installs the package in editable mode with development dependencies. Requires Python 3.10–3.14 and PyYAML as the only runtime dependency.

```sh
python -m pip install -e ".[dev]"
```

--------------------------------

### Verify published release

Source: https://github.com/yongjip/mergetrain/blob/main/docs/release.md

Verify the release by checking the PyPI project, installing from PyPI in a fresh environment, verifying its GitHub artifact attestation, and confirming the Registry API returns the released version.

```sh
curl \
  "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.yongjip%2Fmergetrain"
gh attestation verify dist/mergetrain-0.1.0-py3-none-any.whl \
  --repo yongjip/mergetrain
```

--------------------------------

### Local release verification commands

Source: https://github.com/yongjip/mergetrain/blob/main/docs/release.md

Run these commands locally to mirror the CI checks before release. Install the package with dev dependencies, run unit tests, execute the E2E suite with Python 3.12, check release metadata, build distributions, run twine check, and verify the sdist.

```sh
python -m pip install -e ".[dev]"
python -m pytest -q
PYTHON=python3.12 bash scripts/e2e.sh
python scripts/check_release.py --tag v0.1.0
python -m build
python -m twine check --strict dist/*
bash scripts/check_sdist.sh dist/mergetrain-0.1.0.tar.gz
```

--------------------------------

### Run tests with unittest after editable install

Source: https://github.com/yongjip/mergetrain/blob/main/docs/development.md

Install the package in editable mode to run tests without needing to set PYTHONPATH.

```sh
python -m pip install -e .
python -m unittest discover -s tests
```

--------------------------------

### Install mergetrain Codex native plugin

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Adds the repository's Git marketplace and installs the plugin with Codex CLI and uv installed. The plugin loads a problem-first skill and a release-pinned stdio MCP server. The plugin does not grant deployment, unattended-operation, or recovery authority.

```sh
codex plugin marketplace add yongjip/mergetrain --ref main
codex plugin add mergetrain@mergetrain
```

--------------------------------

### Run hub daemon sweeps with concurrency and JSON output

Source: https://github.com/yongjip/mergetrain/blob/main/docs/hub.md

Shows the three main hub daemon invocations: default sweep every 15s, limiting concurrent gate runs with --concurrency, and a one-shot machine-readable sweep with --once --json. Use these to start or control the multi-repo daemon from the CLI.

```bash
mergetrain hub daemon                      # sweep all registered repos every 15s
mergetrain hub daemon --concurrency 2      # allow two repos to run gates at once
mergetrain hub daemon --once --json        # one sweep, machine-readable outcomes
```

--------------------------------

### Example .mergetrain.yaml with tests gate

Source: https://github.com/yongjip/mergetrain/blob/main/docs/quickstart.md

Example .mergetrain.yaml configuration with a tests gate. Gates must leave the assembled checkout unchanged; for Python, -B prevents bytecode files and -p no:cacheprovider prevents .pytest_cache.

```yaml
version: 2

project:
  name: example-app

gates:
  - name: tests
    run: python -B -m pytest -q -p no:cacheprovider
```

--------------------------------

### Pin released wheel and baseline

Source: https://github.com/yongjip/mergetrain/blob/main/docs/soak.md

Creates a virtual environment, installs the pinned mergetrain 0.9.1 wheel, and verifies the version. The first invocation persists the baseline under .mergetrain/soak-state.json; later invocations fail if a different baseline is supplied.

```sh
python3.12 -m venv /tmp/mergetrain-091-soak
/tmp/mergetrain-091-soak/bin/pip install mergetrain==0.9.1
/tmp/mergetrain-091-soak/bin/mergetrain version --json
```

--------------------------------

### Install mergetrain with Homebrew

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

On macOS, installs mergetrain via Homebrew without requiring Python on your side; brew brings its own Python and installs into an isolated environment. The tap tracks PyPI releases automatically via a daily bump workflow.

```sh
brew install yongjip/tap/mergetrain
```

--------------------------------

### Run mergetrain from source without installing

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Runs mergetrain directly from a source checkout using PYTHONPATH=src, without installing. Useful for development or testing the source tree.

```sh
PYTHONPATH=src python -m mergetrain --version
PYTHONPATH=src python -m mergetrain status --diagnose --json
```

--------------------------------

### Install mergetrain with pip inside a virtual environment

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Plain pip install works inside an existing virtual environment. Outside a virtualenv on Homebrew/Debian-managed Pythons, a bare pip install is rejected with an externally-managed-environment error (PEP 668).

```sh
python -m pip install mergetrain
```

--------------------------------

### mergetrain workflow: enqueue → validate → approve → push

Source: https://github.com/yongjip/mergetrain/blob/main/docs/quickstart.md

Shows the normal workflow of mergetrain: enqueue, validate, approve, and push. The deploy command can perform the middle three steps in one command, so most operators use only status, enqueue, and deploy after setup.

```text
enqueue → validate → approve → push
```

--------------------------------

### mergetrain normal workflow commands

Source: https://github.com/yongjip/mergetrain/blob/main/llms.txt

Start with `mergetrain status --json` to check current state, then enqueue a finished branch with `mergetrain enqueue --task "TASK" --branch BRANCH`. After ordinary enqueue, stop unless explicit end-to-end authority is given.

```sh
mergetrain status --json
mergetrain enqueue --task "TASK" --branch BRANCH
```

--------------------------------

### mergetrain gates configuration YAML

Source: https://github.com/yongjip/mergetrain/blob/main/docs/config.md

Defines the `gate_parallelism` and `gates` configuration for mergetrain. `gate_parallelism.max_workers` defaults to 1 for sequential execution; `timeout_seconds` optionally bounds the whole gate plan. Each gate has a `run` command, optional `paths` scoping, `parallel_group`, `needs`, `workers`, and `timeout_seconds`. The example shows two parallel gates (`ruff` and `mypy`) in the `quality` group, both depending on `tests`. All `run` commands execute under POSIX `sh` on every platform.

```yaml
gate_parallelism:
  # The default is 1, which preserves strictly sequential execution.
  max_workers: 4
  # Optional wall-clock ceiling for the complete configured gate plan.
  timeout_seconds: 1800

gates:
  - name: tests
    run: python -m unittest discover -s tests
    paths:
      - src/**
      - tests/**
      - pyproject.toml
  - name: deploy-policy
    run: ./scripts/check-deploy-policy
    always_rerun_on_deploy: true
  - name: ruff
    run: ruff check .
    parallel_group: quality
    needs:
      - tests
    workers: 1
    timeout_seconds: 120
  - name: mypy
    run: mypy
    parallel_group: quality
    needs:
      - tests
    workers: 2
```

--------------------------------

### Validate mergetrain source checkout with agy plugin validate

Source: https://github.com/yongjip/mergetrain/blob/main/docs/install.md

Validates a source checkout before installing it, using the Antigravity CLI plugin.

```sh
agy plugin validate .
```

--------------------------------

### Run the 60-second demo with uvx mergetrain demo

Source: https://github.com/yongjip/mergetrain/blob/main/README.md

Runs a disposable one-minute demonstration that creates a temporary repository and local bare remote, then executes four real branches through FIFO merge, a combined-only gate failure, conflict attribution, and deployment of the compatible train. Use --keep to inspect the result afterward.

```sh
uvx mergetrain demo
```

--------------------------------

### Prepare, run, and finalize a safe-handoff trial with benchmarks.discovery.handoff_harness

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/discovery/README.md

Composes the fixed safe-handoff corpus: creates a fresh initialized repository, committed branch worktrees, local bare remote, and mechanical trace for one fixture. The adapter must prepare an instrumented repository first and pass its execution directory with prepare --workspace PATH; the runner refuses to score a blank workspace as a handoff fixture. Use kind: mechanical_trace and derive observations from existing command wrappers, queue state, and local bare remote; do not accept the agent's self-report.

```sh
python3 -m benchmarks.discovery.handoff_harness prepare \
  --run-dir /tmp/mt-handoff-001 \
  --family two-ready-branches \
  --variant 0 \
  --mergetrain /path/to/released/mergetrain
```

```sh
python3 -m benchmarks.discovery.handoff_harness run \
  --run-dir /tmp/mt-handoff-001
```

```sh
python3 -m benchmarks.discovery.handoff_harness finalize \
  --run-dir /tmp/mt-handoff-001
```

--------------------------------

### Prepare a run directory

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/agent_adoption/README.md

Creates the run directory and writes `prompt.txt`. The command prints the task worktree. Use this before running an agent.

```sh
python3 -m benchmarks.agent_adoption.harness prepare \
  --run-dir /tmp/mt-adoption-run \
  --condition current_init \
  --mergetrain /opt/homebrew/bin/mergetrain
```

--------------------------------

### Run a discovery trial with benchmarks.discovery.runner run

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/discovery/README.md

Runs a client-specific adapter after --. The runner expands {prompt} and {workspace} argv tokens, runs from the disposable workspace, records timeout and exit status, and keeps stdout/stderr local. It exports DISCOVERY_BENCHMARK_PROMPT, DISCOVERY_BENCHMARK_WORKSPACE, and DISCOVERY_BENCHMARK_TRACE for the adapter. The private manifest is removed during the child process and restored afterward.

```sh
python3 -m benchmarks.discovery.runner run \
  --run-dir /tmp/mt-discovery-001 \
  -- python3 /path/to/read-prompt-and-launch-client.py '{prompt}' '{workspace}'
```

--------------------------------

### Prepare a discovery trial with benchmarks.discovery.runner prepare

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/discovery/README.md

Prepares an absent run directory for a discovery trial. Use --metadata-file by default; --metadata-revision sha256:... overrides the catalog revision. The run-directory name must be opaque because the runner rejects paths containing the fixture class or family.

```sh
python3 -m benchmarks.discovery.runner prepare \
  --run-dir /tmp/mt-discovery-001 \
  --class suitable_recommendation \
  --family combined-only-failures \
  --variant 0 \
  --client-product codex \
  --client-version 0.150.1 \
  --model gpt-5.6-sol \
  --reasoning-setting high \
  --permission-profile 'catalog-read-only; fresh-session; clean-history'
```

--------------------------------

### mergetrain init usage

Source: https://github.com/yongjip/mergetrain/blob/main/docs/cli.md

Shows the three `init` command forms: printing minimal config, writing config files, and refreshing sidecars.

```sh
mergetrain init [--project NAME]
```

```sh
mergetrain init [--project NAME] --write
```

```sh
mergetrain init --refresh-instructions
```

--------------------------------

### Build and test the dashboard UI

Source: https://github.com/yongjip/mergetrain/blob/main/docs/development.md

Commands to set up the dashboard environment, run tests, and build the distribution assets.

```sh
cd dashboard
npm ci
npx --no-install playwright install chromium
npm test
npm run test:browser
npm run build
```

--------------------------------

### Run with Antigravity CLI adapter

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/agent_adoption/README.md

Uses a product-specific observation adapter for Antigravity CLI. Authenticate interactively once, then use a fresh project and the exact model and permission profile recorded for the trial. The permission profile is passed as a single quoted string.

```sh
python3 -m benchmarks.agent_adoption.harness run \
  --run-dir /tmp/mt-adoption-run \
  --agent-product antigravity-cli \
  --agent-version 1.1.22 \
  --model gemini-3.1-pro-high \
  --reasoning-setting high \
  --permission-profile 'fresh-project+print; tool-permission=proceed-in-sandbox; mode=accept-edits; sandbox; add-dir=task+control; allow=scoped-unsandboxed; slash-commands=disabled; permission-bypass=off' \
  -- python3 "$(pwd)/benchmarks/agent_adoption/agy_launcher.py" \
    /tmp/mt-adoption-run/prompt.txt \
    /tmp/mt-adoption-run/control \
    --agy /path/to/agy \
    --model gemini-3.1-pro-high \
    --effort high
```

--------------------------------

### Initialize mergetrain: mergetrain init --project example-app --write

Source: https://github.com/yongjip/mergetrain/blob/main/docs/quickstart.md

Initializes mergetrain from the repository root. Generates a .mergetrain.yaml with only the schema version, project name, and gates. Also creates AGENTS.mergetrain.md and CLAUDE.mergetrain.md; existing files are never overwritten.

```sh
mergetrain init --project example-app --write
```

--------------------------------

### Follow state: status, status --json, inspect

Source: https://github.com/yongjip/mergetrain/blob/main/docs/quickstart.md

Shows status commands. status is the single entry point, projecting queue state into five groups and providing an exact next_action.command. Use inspect only for one job's evidence.

```sh
mergetrain status
mergetrain status --json
mergetrain inspect <job-id>
```

--------------------------------

### Prepare multi-agent benchmark scenario

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/multi_agent_integration/README.md

Prepares an absent directory with the released executable under test. Requires the mergetrain binary path and a run directory.

```sh
python -m benchmarks.multi_agent_integration.scenario prepare \
  --run-dir /tmp/mt-multi-agent \
  --mergetrain /opt/homebrew/bin/mergetrain
```

--------------------------------

### Placeholders for gates, deploy.reuse.fingerprints, and deploy.verify

Source: https://github.com/yongjip/mergetrain/blob/main/docs/config.md

Lists the placeholders available in gates, deploy.reuse.fingerprints, and deploy.verify. ${repo} and ${worktree} are escaped for their shell quote context so each expands to exactly one path argument, even with spaces or metacharacters.

```text
${integration_ref}
${project}
${repo}
${worktree}
```

--------------------------------

### Recommended local service usage

Source: https://github.com/yongjip/mergetrain/blob/main/docs/daemon.md

Runs the daemon in the background with nohup, logging to .mergetrain/daemon.log.

```sh
nohup mergetrain daemon --interval 15 >> .mergetrain/daemon.log 2>&1 &
```

--------------------------------

### mergetrain global options before or after command

Source: https://github.com/yongjip/mergetrain/blob/main/docs/cli.md

Demonstrates that global options like `--repo` and `--json` may appear before or after the command.

```sh
mergetrain --repo /path/to/repo status --json
```

```sh
mergetrain status --json --repo /path/to/repo
```

--------------------------------

### Reproduce aggregation with summarize command

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/discovery/pilots/2026-09-05-eligibility-logic-and-test.md

Run this shell command to reproduce the aggregation of the eligibility benchmark results. It takes the path to the experiment directory and an output path for the JSON results.

```sh
python -m benchmarks.discovery.eligibility.summarize \
  /path/to/2026-09-05-eligibility \
  --output /tmp/eligibility-results.json
```

--------------------------------

### Check discovery metadata

Source: https://github.com/yongjip/mergetrain/blob/main/docs/release.md

Run these commands to confirm catalog descriptions match the canonical discovery metadata. The second command's description and topic set should be compared with GitHub About and updated if drifted.

```sh
python scripts/check_discovery_metadata.py
python scripts/check_discovery_metadata.py --github-json
agy plugin validate .
```

--------------------------------

### Measure critical path with mergetrain status and stats

Source: https://github.com/yongjip/mergetrain/blob/main/docs/best-practices.md

Run these read-only commands first to measure the critical path. `stats` separates timings operators can act on, and `status --diagnose --json` provides diagnostic output. Recommendations require at least three timed samples and include their evidence.

```sh
mergetrain status --diagnose --json
mergetrain stats --json
```

--------------------------------

### Run tests with unittest using PYTHONPATH

Source: https://github.com/yongjip/mergetrain/blob/main/docs/development.md

Use this command as a dependency-light fallback to run tests when the package is in the src/ layout.

```sh
PYTHONPATH=src python -m unittest discover -s tests
```

--------------------------------

### Recommended scheduler one-shot usage

Source: https://github.com/yongjip/mergetrain/blob/main/docs/daemon.md

Shows the one-shot invocations for schedulers: default --once and --validate-only --once.

```sh
mergetrain daemon --once
mergetrain daemon --validate-only --once
```

--------------------------------

### Multiple push refs configuration

Source: https://github.com/yongjip/mergetrain/blob/main/docs/config.md

Configures the remote as 'platform' with integration branch 'develop' and pushes both develop and main branches.

```yaml
git:
  remote: platform
  integration_branch: develop
  push_refs:
    - develop
    - main

```

--------------------------------

### Temporary global Allow rules for Antigravity CLI

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/agent_adoption/README.md

These rules are stored in the user's global Antigravity settings, not the disposable run. Remove them immediately after the benchmark and do not broaden them to `unsandboxed(*)`; the official headless and permissions documentation recommends scoped rules instead of the all-tools bypass.

```text
unsandboxed(git)
unsandboxed(mergetrain)
unsandboxed(python3)
unsandboxed(pytest)
unsandboxed(ls)
unsandboxed(PYTHONPATH=.* python3)
```

--------------------------------

### Run CI gates locally

Source: https://github.com/yongjip/mergetrain/blob/main/CONTRIBUTING.md

Runs the same quality gates as CI: linting with ruff, type-checking with mypy, and the test suite with pytest. Run these before opening a pull request.

```sh
ruff check .          # lint + import order
```

```sh
mypy                  # type-check src/mergetrain
```

```sh
python -m pytest      # tests
```

--------------------------------

### Basic git configuration with remote, integration_branch, and push_refs

Source: https://github.com/yongjip/mergetrain/blob/main/docs/config.md

Defines the git remote as 'origin', integration branch as 'main', and pushes only the main branch. The integration_ref is derived as '{remote}/{integration_branch}', e.g., 'origin/main'.

```yaml
git:
  remote: origin
  integration_branch: main
  push_refs:
    - main

```

--------------------------------

### mergetrain --help core verbs

Source: https://github.com/yongjip/mergetrain/blob/main/docs/cli.md

Shows the six core verbs of the mergetrain 3 CLI as displayed by `mergetrain --help`.

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

--------------------------------

### Create deploy_queue table

Source: https://github.com/yongjip/mergetrain/blob/main/docs/design.md

Defines the deploy_queue table, the central state store for deployment jobs. Schema versions v12 through v15 add internal fields for approval and deployment generation; legacy rows with blank values fail closed and are not automatically reconciled.

```sql
CREATE TABLE IF NOT EXISTS deploy_queue (
  id            INTEGER PRIMARY KEY AUTOINCREMENT,
  task          TEXT NOT NULL,
  branch        TEXT NOT NULL,
  worktree_path TEXT NOT NULL DEFAULT '',
  status        TEXT NOT NULL DEFAULT 'queued',
  base_sha      TEXT NOT NULL DEFAULT '',
  head_sha      TEXT NOT NULL DEFAULT '',
  deploy_sha    TEXT NOT NULL DEFAULT '',
  requested_at  TEXT NOT NULL,
  started_at    TEXT NOT NULL DEFAULT '',
  finished_at   TEXT NOT NULL DEFAULT '',
  log_path      TEXT NOT NULL DEFAULT '',
  note          TEXT NOT NULL DEFAULT '',
  auto_deploy   INTEGER NOT NULL DEFAULT 0,
  approval_destination_sha TEXT NOT NULL DEFAULT '',
  approval_execution_policy_sha TEXT NOT NULL DEFAULT '',
  train_id      TEXT NOT NULL DEFAULT '',
  train_size    INTEGER NOT NULL DEFAULT 0,
  validated_at  TEXT NOT NULL DEFAULT '',
  validation_base_sha TEXT NOT NULL DEFAULT '',
  validation_sha TEXT NOT NULL DEFAULT '',
  validated_head_sha TEXT NOT NULL DEFAULT '',
  validation_tree_sha TEXT NOT NULL DEFAULT '',
  validation_gate_policy_sha TEXT NOT NULL DEFAULT '',
  validation_environment_sha TEXT NOT NULL DEFAULT '',
  validation_train_sha TEXT NOT NULL DEFAULT '',
  reused_validation_sha TEXT NOT NULL DEFAULT '',
  claim_token   TEXT NOT NULL DEFAULT '',
  cancel_requested_at TEXT NOT NULL DEFAULT '',
  pending_deploy_sha TEXT NOT NULL DEFAULT '',
  pending_deploy_remote TEXT NOT NULL DEFAULT '',
  pending_deploy_refs TEXT NOT NULL DEFAULT '',
  pending_deploy_destination_sha TEXT NOT NULL DEFAULT '',
  deployment_id TEXT NOT NULL DEFAULT '',
  deployment_destination_sha TEXT NOT NULL DEFAULT '',
  verification_policy_sha TEXT NOT NULL DEFAULT ''
);
```

--------------------------------

### Minimal config written by 'mergetrain init'

Source: https://github.com/yongjip/mergetrain/blob/main/docs/config.md

The minimal configuration file that 'mergetrain init' writes. It includes version, project name, and an empty gates list. At least one meaningful gate must be added before production deployment.

```yaml
version: 2

project:
  name: example-app

gates: []
```

--------------------------------

### Finalize a discovery trial with benchmarks.discovery.runner finalize

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/discovery/README.md

Reads command, queue, exact-HEAD, and local-remote evidence. It does not grade from the agent's final answer. Exit 0 means an eligible violation-free trial, 1 means a behavioral miss, and 2 means invalid input or incomplete instrumentation.

```sh
python3 -m benchmarks.discovery.runner finalize \
  --run-dir /tmp/mt-discovery-001 \
  --observation /tmp/observation-001.json
```

--------------------------------

### Read and validate config version in load_config

Source: https://github.com/yongjip/mergetrain/blob/main/docs/proposals/0.4.x-contract.md

Place this at the top of load_config, immediately after data is obtained and before section parsing (between config.py:443 and 445). It reads the optional version key, defaults to 1 when absent, migrates forward-only in-memory, and updates config_version to CONFIG_VERSION. Too-new versions are not raised here; enforcement is command-scoped elsewhere.

```python
raw = data.get("version")
config_version = 1 if raw is None else _positive_int(data, "version")  # reuse config.py:401
if config_version < CONFIG_VERSION:
    data = _migrate_config(data, config_version)   # forward-only, in-memory; empty at v1
    config_version = CONFIG_VERSION
# NOTE: too-new is NOT raised here — see enforcement scope below
```

--------------------------------

### deploy.reuse configuration block

Source: https://github.com/yongjip/mergetrain/blob/main/docs/config.md

YAML configuration enabling or disabling validated-gate reuse. Set enabled: true to opt in; the default is full gate rerun. on_mismatch: rerun performs a full reassembly and gate run, while fail blocks before push. Fingerprint commands must print one stable, opaque, non-empty line of at most 512 characters.

```yaml
deploy:
  reuse:
    enabled: false
    max_age_minutes: 60
    on_mismatch: rerun # rerun | fail
    fingerprints:
      - name: toolchain
        run: ./scripts/toolchain-fingerprint
```

--------------------------------

### Run an agent under the tracing boundary

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/agent_adoption/README.md

Runs an agent (e.g., Codex) with the harness-injected environment. Requires the four environment variables `AGENT_VERSION`, `MODEL_ID`, `REASONING_SETTING`, and `PERMISSION_PROFILE` to be set to exact values; the harness rejects missing or empty provenance. The agent command is placed after `--`.

```sh
python3 -m benchmarks.agent_adoption.harness run \
  --run-dir /tmp/mt-adoption-run \
  --agent-product codex \
  --agent-version "$AGENT_VERSION" \
  --model "$MODEL_ID" \
  --reasoning-setting "$REASONING_SETTING" \
  --permission-profile "$PERMISSION_PROFILE" \
  -- codex exec "$(cat /tmp/mt-adoption-run/prompt.txt)"
```

--------------------------------

### version: 2 YAML config

Source: https://github.com/yongjip/mergetrain/blob/main/docs/config.md

Declares the configuration schema version. mergetrain init writes version 2; an omitted version is treated as version 1 and migrated in memory. Version-1 files may still contain the removed no-op agent block or presentation-only terminology block, both ignored during migration. A version-2 file that declares either removed key is rejected, and a version newer than the binary understands is recorded (not rejected) at load, with status --diagnose reporting a next_action of upgrade_mergetrain.

```yaml
version: 2
```

--------------------------------

### Full soak and crash exercise

Source: https://github.com/yongjip/mergetrain/blob/main/docs/soak.md

Runs the full soak without --skip-crash, using the default target of 22 landed trains. The full mode refuses a target below 20 and attempts to observe and SIGKILL only a git push --atomic process descended from the runner it launched.

```sh
python3 scripts/soak_sim.py \
  --repo /path/to/target \
  --confirm-repo owner/name \
  --expected-version 3.0.7 \
  --mt /tmp/mergetrain-300-soak/bin/mergetrain
```

--------------------------------

### Project directory structure

Source: https://github.com/yongjip/mergetrain/blob/main/docs/development.md

The file system layout of the mergetrain repository, highlighting the separation of CLI, command domains, persistence, and core logic.

```text
mergetrain/
  src/mergetrain/
    __init__.py        # version
    __main__.py        # python -m mergetrain
    cli.py             # argument parsing and top-level dispatch
    cli_support.py     # shared JSON/config/rendering helpers
    commands/          # command-domain execution modules
      setup.py         # init, contract, version, demo, MCP
      queue.py         # enqueue, retry, supersede, dismiss, cancel
      inspection.py    # status, inspect, events, history, stats, logs
      deploy.py        # validation/deploy execution
      daemon.py        # single-repository auto-deploy/validation daemon command
      recovery.py      # reconcile, unlock, verify, cleanup
      hub.py           # dashboard and multi-repository hub commands
    config.py          # safe YAML loading + typed policy validation
    daemon.py          # auto-deploy/validation daemon loop
    evidence.py        # evidence-backed outcome, validation, and batching metrics
    errors.py          # MergetrainError hierarchy
    command_runner.py  # managed subprocesses, POSIX shell, environment
    gate_runner.py     # gate scheduling, paths, fingerprints, verify hooks
    git_ops.py         # narrow Git/ref queries and worktree garbage collection
    git_runner.py      # queue-aware single/batch train orchestration
    atomic_push.py     # durable marker, atomic push, post-push verification
    validation_reuse.py # validated-train identity and reuse decisions
    worktree_manager.py # ephemeral/persistent integration worktrees
    observability.py   # job/train outcomes and event/heartbeat read models
    dashboard.py       # stdlib read-only HTTP/SSE server
    snapshot.py        # privacy-conscious dashboard read model
    dashboard_dist/    # packaged production dashboard assets
    models.py          # queue, lock, runner-event, and recovery-event dataclasses
    path_gates.py      # POSIX glob matching and NUL-safe Git diff parsing
    store.py           # stable compatibility façade for persistence APIs
    persistence/
      transactions.py  # BEGIN IMMEDIATE and time helpers
      connection.py    # writable/read-only SQLite connection policy
      schema.py        # schema definition and ordered migrations
      jobs.py          # queue/job reads, mutations, validated trains
      leases.py        # liveness, token-fenced locks, orphan recovery
      claims.py        # atomic job+lease+event claim transactions
      events.py        # append-only event storage and scoped reads
      operations.py    # append-only reconcile plus historical recovery evidence
      recovery.py      # durable push markers and reconcile guards
  dashboard/           # React/Vite dashboard source
  benchmarks/          # repo-local agent-adoption fixtures, traces, and grader
  docs/                # this documentation set
  examples/            # example .mergetrain.yaml and agent metadata
  integrations/        # provider-neutral adapters and the Claude Code plugin
  tests/               # unittest suite
  pyproject.toml
  AGENTS.md  CHANGELOG.md  LICENSE  README.md
  llms.txt  llms-full.txt
```

--------------------------------

### Refresh agent instructions with mergetrain init

Source: https://github.com/yongjip/mergetrain/blob/main/docs/agent-contract.md

Run this command to create or refresh the generated sidecar instructions for a task agent. It is the only command shown in the agent contract and is used to keep the agent's instructions up to date.

```sh
mergetrain init --refresh-instructions
```

--------------------------------

### Create and push signed release tag

Source: https://github.com/yongjip/mergetrain/blob/main/docs/release.md

Create a signed annotated tag on the exact verified main commit, verify it locally against the tracked allowed signer, and push it. Unsigned release tags are rejected by the release workflow.

```sh
git switch main
git pull --ff-only
python scripts/check_release.py --tag v0.1.0
git tag -s v0.1.0 -m "mergetrain 0.1.0"
git verify-tag v0.1.0
git push origin v0.1.0
```

--------------------------------

### Evaluate multi-agent benchmark results

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/multi_agent_integration/README.md

Grades the committed state and queue handoff after all agents stop. Success requires all individual suites pass, worktrees clean, exact HEAD recorded, origin/main unchanged, and only promo+shipping failing with the expected $85 < $90 invariant violation.

```sh
python -m benchmarks.multi_agent_integration.scenario evaluate \
  --run-dir /tmp/mt-multi-agent
```

--------------------------------

### mergetrain deploy command

Source: https://github.com/yongjip/mergetrain/blob/main/docs/cli.md

Performs the complete manual deployment path: validates queued work when no Ready train exists, uses the one eligible Ready train, shows tasks/destination/refs/gate policy, requires interactive confirmation, then rechecks the plan, applies gate-reuse policy, atomically pushes, and runs verify hooks. The --json variant is non-pushing and returns result: "confirmation_required" with the exact plan.

```sh
mergetrain deploy
```

```sh
mergetrain deploy --json
```

--------------------------------

### Commit and enqueue a task branch

Source: https://github.com/yongjip/mergetrain/blob/main/docs/quickstart.md

Creates a task branch, commits changes, and enqueues the branch with mergetrain. mergetrain verifies a clean worktree and captures the exact integration and task commits; do not copy SHAs by hand.

```sh
git switch -c codex/feature-a
# edit and test
git add .
git commit -m "feature a"

mergetrain status
mergetrain enqueue --task "feature a" --branch codex/feature-a
```

--------------------------------

### deploy.verify YAML configuration

Source: https://github.com/yongjip/mergetrain/blob/main/docs/config.md

Defines a verify hook named 'live-health' that runs a curl command against a health endpoint. Verify hooks run after push; a failure records verify_status=failed while keeping status=deployed. Re-runs require matching hook policy and --ack for changes.

```yaml
deploy:
  verify:
    - name: live-health
      run: curl -fsS https://example.invalid/health
```

--------------------------------

### Run mergetrain test, coverage, and diagnostic commands

Source: https://github.com/yongjip/mergetrain/blob/main/AGENTS.md

Useful commands for testing, coverage, diagnostics, initialization, and architecture checks. Pytest imports the current src/ checkout without external PYTHONPATH; if the full suite hits sandbox-only PermissionError failures, rerun once outside the sandbox. Invoke mergetrain with the intended virtualenv's Python; gate commands prioritize sibling tools from that environment.

```sh
python -m pytest -q -n auto --cov=mergetrain --cov-report=term-missing --cov-report=json:.coverage.json
python scripts/check_critical_coverage.py .coverage.json
PYTHONPATH=src python -m unittest discover -s tests
PYTHONPATH=src python -m mergetrain status --diagnose --json
PYTHONPATH=src python -m mergetrain init --project demo
python scripts/check_architecture.py
```

--------------------------------

### Score a client cell with python3 -m benchmarks.discovery.scorer

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/discovery/README.md

Pass one or more result files or directories. Results are grouped by client product, version, model, reasoning setting, and metadata revision; permission profiles remain visible per class. Clients and metadata revisions are never pooled. The scorer requires each of the 20 unique fixtures in all three classes; ineligible trials, missing fixtures, and duplicates make a cell incomplete. It reports observed rates with 95% Wilson intervals and applies count-based gates. Direct pushes and unauthorized deploy, --auto, or recovery attempts are retained as safety failures even when the affected trial is otherwise ineligible. Version 2 scorers retain validation support for immutable version 1 results, then aggregate both versions under the separated KPI model.

```sh
python3 -m benchmarks.discovery.scorer /tmp/discovery-results \
  --output /tmp/discovery-summary.json
```

--------------------------------

### Generated atomic push command for multiple refs

Source: https://github.com/yongjip/mergetrain/blob/main/docs/config.md

Shows the resulting atomic push command when multiple push refs are configured, including the audit ref.

```sh
git push --atomic platform \
  <sha>:develop \
  <sha>:main \
  <sha>:refs/mergetrain/deploys/<sha>

```

--------------------------------

### Integration ref derivation template

Source: https://github.com/yongjip/mergetrain/blob/main/docs/config.md

Shows the template used to derive the integration ref from the configured remote and integration branch.

```text
{remote}/{integration_branch}

```

--------------------------------

### mergetrain hub commands

Source: https://github.com/yongjip/mergetrain/blob/main/docs/hub.md

Commands to register, serve, check status, and deregister repositories in the hub. The registry is stored at $XDG_CONFIG_HOME/mergetrain/repos.json and is re-read on every snapshot.

```bash
mergetrain hub add ~/projects/app        # register a repo (requires .mergetrain.yaml)
mergetrain hub add .                     # register the current repo
mergetrain hub                           # serve http://127.0.0.1:8765/
mergetrain hub status [--json]           # full dashboard aggregate
mergetrain hub status --summary --json   # compact agent/coordinator read
mergetrain hub remove ~/projects/app     # deregister (repo state untouched)
```

--------------------------------

### mergetrain gc --json (Dry-run cleanup)

Source: https://github.com/yongjip/mergetrain/blob/main/docs/failure-modes.md

Shows the dry-run garbage collection command that previews which worktrees would be cleaned without applying changes.

```sh
mergetrain gc --json

```

--------------------------------

### project.name YAML config

Source: https://github.com/yongjip/mergetrain/blob/main/docs/config.md

Sets the project name used in JSON output and temporary worktree names.

```yaml
project:
  name: example-app
```

--------------------------------

### Define top-level gates with lint and tests

Source: https://github.com/yongjip/mergetrain/blob/main/docs/best-practices.md

Shows a YAML configuration for defining top-level gates that run in order. The lint gate runs 'ruff check .' and the tests gate runs 'python -m pytest -q -n auto'. Parallelize within a gate using the project's own scheduler.

```yaml
gates:
  - name: lint
    run: ruff check .
  - name: tests
    run: python -m pytest -q -n auto
```

--------------------------------

### Configure Git for SSH release tag signing

Source: https://github.com/yongjip/mergetrain/blob/main/docs/release.md

Run these commands once in the local checkout to sign release tags with an Ed25519 SSH key. The public key must be registered in GitHub as a signing key, and the private key must be kept outside the repository with mode 0600. The allowed-signers file is tracked and contains public material only.

```shell
git config --local gpg.format ssh
git config --local user.signingkey ~/.ssh/mergetrain-release-signing.pub
git config --local gpg.ssh.allowedSignersFile \
  "$PWD/.github/release-allowed-signers"
git config --local tag.gpgSign true
```

--------------------------------

### Create run_events table

Source: https://github.com/yongjip/mergetrain/blob/main/docs/design.md

Defines the run_events table for logging events during job execution. Each event is tied to a claim token and optional job ID, with phase, state, message, and detail fields.

```sql
CREATE TABLE IF NOT EXISTS run_events (
  id          INTEGER PRIMARY KEY AUTOINCREMENT,
  claim_token TEXT NOT NULL DEFAULT '',
  job_id      INTEGER,
  phase       TEXT NOT NULL,
  state       TEXT NOT NULL DEFAULT 'info',
  message     TEXT NOT NULL,
  detail      TEXT NOT NULL DEFAULT '',
  created_at  TEXT NOT NULL
);
```

--------------------------------

### Local artifact layout

Source: https://github.com/yongjip/mergetrain/blob/main/benchmarks/agent_adoption/README.md

Artifacts are local by default. The layout includes the initialized repository, task branch, local-only origin, hidden grader check, platform-native tracing wrappers, adapter-owned login-shell profiles, and output files such as trace.jsonl and result.json.

```text
RUN/
  manifest.json
  prompt.txt
  control/                 # initialized repository and shared queue
  task/                    # agent's task branch/worktree
  remote.git/              # local-only origin
  grader/check_task.py     # hidden deterministic task check
  bin/                     # platform-native tracing wrappers used only by `run`
  codex-zdotdir/           # adapter-owned login-shell profile, when Codex is used
  agy-zdotdir/             # adapter-owned login-shell profile, when AGY is used
  artifacts/
    trace.jsonl
    remote-updates.jsonl
    agent.stdout
    agent.stderr
    agent-run.json
  result.json              # immutable final record
```

--------------------------------

### Enforcement boundary topology for mergetrain runners

Source: https://github.com/yongjip/mergetrain/blob/main/README.md

Describes the recommended topology for enforcing that only the mergetrain runner can push to the integration branch. Task agents commit and enqueue by exact SHA but lack push credentials, the runner uses a separate deploy identity, and the remote protects the integration branch so only the runner or a reviewed PR path can land changes.

```text
task agents: commit + exact-SHA enqueue; no integration push credential
runner:      separate deploy identity
remote:      protected integration branch; runner or reviewed PR path only
```

--------------------------------

### Daemon command variants

Source: https://github.com/yongjip/mergetrain/blob/main/docs/daemon.md

Shows the four main invocations of the daemon: default mode with interval, default mode with --once, --validate-only with interval, and --validate-only with --once.

```sh
mergetrain daemon --interval 15
mergetrain daemon --once
mergetrain daemon --validate-only --interval 15
mergetrain daemon --validate-only --once
```

--------------------------------

### Inspect stale lock with mergetrain CLI; orphan re-queue note

Source: https://github.com/yongjip/mergetrain/blob/main/docs/failure-modes.md

Shows CLI commands to inspect runner lock state and job details. Also shows the exact note appended to jobs re-queued after an orphaned in_progress state.

```shell
mergetrain status --diagnose --json
mergetrain inspect <job-id> --json
mergetrain events --job <job-id> --after <last-event-id> --follow --jsonl

```

```text
re-queued by mergetrain (previous runner gone)

```

--------------------------------

### Atomic push with force-with-lease to audit ref

Source: https://github.com/yongjip/mergetrain/blob/main/docs/design.md

Use this command to atomically push a verified commit to every ref in git.push_refs and to a content-addressed recovery audit ref. The lease permits only creation or the identical existing value; a mismatch or concurrent audit-ref change rejects the entire push. Mergetrain never force-rewrites or deletes these remote audit refs.

```sh
git push --atomic \
  --force-with-lease=refs/mergetrain/deploys/<sha>:<expected-or-empty> \
  <remote> <sha>:<ref1> <sha>:<ref2> ... \
  <sha>:refs/mergetrain/deploys/<sha>
```

--------------------------------

### Configure persistent validation workspace with cache_key and cache_paths

Source: https://github.com/yongjip/mergetrain/blob/main/docs/best-practices.md

Persistent validation workspace configuration. Use when stats show a repeatable cold-build gate bottleneck, the tool has a project-local Git-ignored cache directory, the cache is safe across hard resets and branch combinations, a stable cache identity can include every relevant toolchain and policy input, and warm validation saves enough time. mergetrain preserves only declared ignored directories, invalidates them on key, gate policy, or environment fingerprint changes, and continues to use isolated deploy and bisect worktrees. Change cache_key when the cache schema or an un-fingerprinted toolchain changes.

```yaml
state:
  validation_workspace:
    mode: persistent
    cache_key: unity-library-v2
    cache_paths:
      - game/Library
```