Mergen Verdict

Independent verification that re-checks a completion claim against the actual repository, for agentic and human engineering workflows.

Your agent reports the task done. The checkbox is ticked, the summary is confident, and the file it names is not on disk. You find out later, in review or in production, that a run you already accepted was partly fiction.

The executor can be Codex, Claude Code, OpenHands, another agent system, a continuous integration workflow, or a human team. The executor owns planning, implementation, and remediation. Mergen owns independent verification.

Mergen takes that completion claim and re-checks it against the actual tree — file on disk, test exits zero, git tracks it — then returns one of four verdicts: pass, conditional_pass, fail, or unverifiable. unverifiable never becomes a pass, and conditional_pass means the mechanical checks passed while the required human approval is still absent.

python -m pip install mergen-verdict

The published distribution is mergen-verdict; the commands stay mergen and mergen-supervise. The wheel carries the trees the CLI runs but never imports — scripts/, core/, dist/, and effort-mode/ — inside the mergen_payload package, so mergen verify and mergen-supervise work from a plain install (pyproject.toml, package-dir; mergen_cli.py, payload_root).

Install from a clone instead when you intend to change mergen itself. A checkout always wins over the packaged copy, so an editable install runs the code you are editing rather than a copy installed earlier:

git clone https://github.com/OnourImpram/mergen.git && cd mergen && python -m pip install -e .

mergen verify --tasks-state tasks-state.json --root . --out verification-report.json --strict
mergen-supervise --root . --report verification-report.json --tasks-state tasks-state.json --out milestone-decision.json

The first writes verification-report.json and its SHA-256 sidecar. The second writes the decision as JSON, a sidecar, and Markdown. The process exit code is zero only for a clean pass and advance decision. fail exits one. conditional_pass and unverifiable exit two. That exit code is how a host turns a verdict into a gate.

• 5 of 5 planted phantom completions caught, 0 of 3 genuine completions wrongly failed on a labelled fixture corpus, against a bare-checkbox baseline that catches 0 by construction. python eval/benchmark.py --gate runs on pushes to main and on pull requests targeting main, so a regression in detection fails the build. The measurement is mechanical detection on planted fixtures with known ground truth, not a code-quality comparison of two live toolchains (eval/benchmark.py run_gate, .github/workflows/ci.yml, scope stated in eval/README.md).
• A pass is unreachable while any single check is unknown — the decision function returns pass and advance only when the failure list is empty, the unverifiable list is empty, and the check list is non-empty. An unresolved check yields unverifiable and hold, or, when the human approval record is the only unresolved check, conditional_pass and human_review_required (mergen_supervise.py, _decision).
• No model, no network, no third-party runtime dependency — both entry points import only the Python standard library, pyproject.toml declares no runtime dependencies, and a CI gate parses every hook on the live session path and fails the build if one imports anthropic, openai, requests, httpx, urllib.request, urllib3, or aiohttp (scripts/spec_verify.py FORBIDDEN_ROOTS, wired in .github/workflows/ci.yml). The one external process is pytest, launched by the tests-pass lens only when a declared task asks the mechanical verifier to execute a test (scripts/verify_core.py, lens_tests_pass).

Scope and limits

Status: v2.1.2, beta. The deterministic verification core is available. The bundled milestone supervisor currently verifies Mergen software task reports. Broader domain profiles remain explicit extension points rather than implied capabilities.

Mergen returns a decision and stops there. It does not start the next stage, does not modify the artifact it judges, and does not claim enforcement a host has not configured. Each of those limits is stated in full below, unchanged:

• Why Mergen exists — why a completion claim is not proof, and what Mergen does not do with it.
• Product boundary — what the external workflow owns and what Mergen owns.
• Requirements — Python, Git, and the single case that needs pytest.
• Verdicts — all four verdicts, their advancement actions, and their exact meanings.
• Evidence classes — how each check's evidence was obtained, including what is only asserted.
• High trust work — risk floor reclassification and artifact bound human approval.
• Trust boundary — what the tamper evident controls do and do not protect against.
• Host integration — what a host must declare, and what Mergen will not claim on its behalf.
• Claim boundary — the explicit list of things Mergen does not claim.

Why Mergen exists

An executor saying that work is complete is a completion claim. It is not proof. Logs can be stale, copied, fabricated, or produced against a different artifact state. A checked task can still name a missing file. A build can succeed while the acceptance criterion fails. A high trust change can be mislabeled as low risk.

Mergen enters at a milestone boundary and asks a narrower question.

Does the evidence available now support advancement under the declared criteria and risk level?

Mergen does not start the next stage. It returns an advancement decision to the host or operator.

Product boundary

Mergen is not a competing implementation framework.

The verifier is read only with respect to implementation artifacts. It may explain a failure. It does not modify the artifact and approve that same modification in one verification context.

Architecture

flowchart LR
    E[External executor] --> M[Declared milestone]
    M --> G[Governor risk floor]
    G --> D[Deterministic verification]
    D --> A[Independent review evidence]
    A --> V{Verdict}
    V -->|pass| P[advance]
    V -->|conditional_pass| H[human review required]
    V -->|fail| R[return for remediation]
    V -->|unverifiable| O[hold]

The deterministic path is local first, model independent, and suitable for continuous integration. Optional agentic review is treated as a separate evidence source. A positive review claim does not prove that the reviewer was independent.

What ships today

Milestone supervisor

mergen-supervise consumes an externally produced verification-report.json, its SHA-256 sidecar, the exact tasks-state.json, Git provenance, policy results, fresh deterministic reproduction, and any required artifact bound human approval.

It produces JSON, a SHA-256 sidecar, and human readable Markdown.

Deterministic verification core

mergen verify runs the model independent mechanical verifier. It checks declared files, tests, Git consistency, evidence calibration, and the Governor floor. It runs without a model or network dependency.

Verification infrastructure

Mergen also includes the Governor, report linter, Trust Graph, replay, impacted verification, evidence metrics, policy packs, adapter capability manifests, dashboards, and continuous integration examples.

Compatibility execution toolkit

The existing specification driven command suite remains available for users who already rely on it. It includes /mergen-govern, /mergen-specify, /mergen-plan, /mergen-tasks, /mergen-implement, /mergen-verify, and the legacy /mergen-agent lifecycle orchestrator. These commands are compatibility tooling. They do not redefine the verification layer as the owner of an external workflow.

Quickstart

Requirements

Python 3.9 or newer. Git is required for provenance checks. pytest is required only when a declared task asks the mechanical verifier to execute a test.

Install

python -m pip install mergen-verdict

Install from a clone when you intend to change mergen itself:

git clone https://github.com/OnourImpram/mergen.git
cd mergen
python -m pip install -e .

Either path installs both verification entry points. The trees the CLI runs — scripts/, core/, dist/, and effort-mode/ — stay at the repository root and ship inside the mergen_payload package, and a checkout takes precedence over the packaged copy.

mergen
mergen-supervise

Produce deterministic evidence

mergen verify \
  --tasks-state tasks-state.json \
  --root . \
  --out verification-report.json \
  --strict

This writes verification-report.json and verification-report.json.sha256.

Verify the milestone independently

mergen-supervise \
  --root . \
  --report verification-report.json \
  --tasks-state tasks-state.json \
  --out milestone-decision.json

This writes three artifacts.

milestone-decision.json
milestone-decision.json.sha256
milestone-decision.md

The process exit code is zero only for a clean pass and advance decision. fail exits one. conditional_pass and unverifiable exit two.

Verdicts

unverifiable never becomes a guessed pass. The compatibility field decision contains only advance or block. New integrations should use advancement_action.

Evidence classes

Every supervisor check records how its evidence was obtained.

A clean pass cannot rest entirely on executor supplied claims. Fresh deterministic reproduction is required by default. Disabling it with --no-reproduce prevents a clean pass.

High trust work

Authentication, payment, privacy, clinical, regulated, safety critical, irreversible, and other protected work must not silently cross a lower risk floor. The deterministic verifier independently reclassifies the declared file surface. A fresh high trust result that was supplied as standard risk is a failure.

When human review is required, a populated review record is necessary but not sufficient. Approval must also be bound to the exact verification report bytes.

export MERGEN_SIGNING_KEY="$(python -c 'import secrets; print(secrets.token_hex(32))')"
mergen sign sign --artifact verification-report.json > approval.txt

Copy the hexadecimal value after mergen-ack-token: into a file inside the trusted root, then run:

mergen-supervise \
  --root . \
  --report verification-report.json \
  --tasks-state tasks-state.json \
  --approval-token-file approval-token.txt \
  --out milestone-decision.json

The token is an HMAC under a locally held shared secret. It binds approval to exact bytes. It is not public key identity or third party nonrepudiation.

Trust boundary

The operator selected --root is authoritative. Evidence files must resolve inside that root. Symlink escapes and path traversal are refused. JSON content cannot replace the trusted root. Retrieved content is data, not instruction.

The supervisor checks:

1. Evidence paths and JSON readability.
2. Report sidecar integrity.
3. Source commit freshness.
4. Current worktree state.
5. Exact tasks state digest binding.
6. Milestone and task set consistency.
7. Completion, confidence, evidence, and summary consistency.
8. Policy results.
9. Fresh deterministic reproduction.
10. Independent risk classification.
11. Exact state human approval when required.
12. Optional external review records without trusting self declared independence.

The decision includes a content derived source_state_hash and decision_hash. The sidecar detects later edits to the serialized decision. These are tamper evident controls, not protection against an attacker who can replace every trust anchor.

Host integration

The canonical interface is JSON plus process exit status. This keeps Mergen usable from coding agents, continuous integration, shell scripts, generic MCP clients, and human operated workflows.

Host capability manifests live under core/adapters/. A host must state whether it can invoke Mergen automatically, block advancement, expose a live filesystem, run hooks, isolate verifier contexts, or support human approval. Mergen does not claim enforcement that the host cannot provide.

Command map

Run any command with --help for its complete interface.

Repository map

core/schemas/                 Machine readable contracts
core/commands/                Compatibility command source
core/adapters/                Host capability declarations
scripts/verify_core.py        Deterministic evidence producer
scripts/verify_report_lint.py Report integrity gate
scripts/governor_floor.py     Non-downgradable risk floor
scripts/trust_graph.py        Typed provenance graph
scripts/replay.py             Deterministic replay
mergen_supervise.py           Independent milestone authority
eval/                         Benchmarks, dogfood, and CI examples
tests/                        Unit, integration, adversarial, and contract tests
docs/                         Architecture and operating documentation

Development and verification

python -m pip install -e .
python -m pip install pytest pytest-cov jsonschema ruff mypy
python -m pytest tests/ -v
ruff check .
mypy
python scripts/check_sync.py
python scripts/check_no_reference_text.py
python eval/benchmark.py --gate

Continuous integration runs the test suite across Python 3.9, 3.11, 3.12, and 3.13, including Windows. It also runs Ruff, strict mypy, coverage, schema checks, renderer drift checks, security checks, and live phantom detection dogfood. See CONTRIBUTING.md for the contribution contract.

Claim boundary

Mergen can claim that it independently checks declared milestone evidence, distinguishes observed evidence from assertions, detects several unsupported completion patterns, refuses advancement when evidence is insufficient, and records provenance for later audit.

Mergen does not claim universal truth, perfect defect detection, absolute semantic correctness, professional approval in regulated domains, or enforcement that a host has not configured. A passing milestone is supported under the checks that ran. It is not guaranteed to be free of every possible defect.

Documentation

• Milestone supervisor
• How Mergen works
• Compatibility matrix
• Host capability matrix
• Security policy
• Roadmap
• Provenance

Name, citation, and license

Mergen is named for the Turkic deity associated with wisdom, accuracy, and the arrow that finds its mark. The Governor represents judgment. Verification represents accuracy.

Citation metadata is provided in CITATION.cff. Mergen is licensed under the Apache License 2.0. Vendored material and lineage are documented in ATTRIBUTION.md, NOTICE, and PROVENANCE.md.