MTM Contract
A framework for Machine to Machine communication to prevent hallucination and architectural drift in agentic AI coding.
Two failure modes current tooling does not address.
Hallucination
Agentic AI coding agents confidently invoke APIs, entities, and endpoints that do not exist. They do not know they do not know. Token prediction lands in a plausible neighborhood, and the agent takes that as licence to commit.
Architectural Drift
Multi-step tasks accumulate decisions. By step 15, the agent has forgotten step 3, and the new code silently contradicts the earlier decision. Long context windows dilute earlier commitments
rather than preserving them.
Function-calling schemas and type checkers do not catch either failure mode. Both occur in the gap between intent and code generation.
MTM Contract in one page.
An MTM Contract is a markdown file with eleven required sections, written before implementation begins, and amended with an audit section after implementation ships.
The contract externalizes intent, preconditions, schema assumptions, cross-module obligations, and escalation triggers into a markdown artifact that survives the agent's context window - binding the agent's future decisions to its declared scope, and giving uncertainty a legal place to live.
After the change ships, every clause is marked PASS, FAIL, or MUTATED with a reason. The audit closes the loop between declared intent and observable outcome.
See the full template → Link: https://github.com/jewanchen/mtm-contract/blob/main/TEMPLATE.md
Nine mechanisms of value observed across nine production scenarios.
01 — Hallucination prevention
Forced grounding citations catch DTO drift and missing APIreferences before any code is written.
02 — Cross-module discovery
The contract phase surfaces existing helpers and shared infrastructure that an unstructured prompt would have re-implemented.
03 — Architectural decision inheritance
Prior architectural decisions carry forward into new tasks through explicit cross-module-contract citations.
04 — Design-time architectural reasoning
N+1 query patterns, paywall strategies, and concurrency models are reasoned about in the contract phase, not as refactoring follow-ups.
05 — Direction correction
The agent's v1 design was rejected at the contract's escalation step. Five minutes of conversation produced a v2 design. Without the contract, a production rollback and migration would have been required to discover the same issue.
06 — Methodology overrides stale planning
A planning document specified a feature as "paid-only." The contract surfaced a question the plan had not asked. The answer reversed the plan.
07 — User intent disambiguation
"Bulk send invitations" could mean any of four candidate populations. The contract enumerated them and surfaced the choice as an escalation, instead of letting the agent guess.
08 — Knowledge-graph reuse
A previously-logged decision became a one-line reference in a later contract, eliminating re-derivation of the same paywall posture.
09 — Emergent meta-pattern crystallization
After three audits each made an ad-hoc paywall choice, the implicit pattern crystallized into a reusable three-strategy framework. The methodology improves with use.
Read each mechanism with full original contract + audit text →
Link: https://github.com/jewanchen/mtm-contract/tree/main/examples
Try it in 10 minutes.
Step 1 COPY
Copy the template into your project.
mkdir -p contracts
curl the template URL into contracts/<date>_<task>.md
Step 2 FILL
Fill in intent, affected_layers, expected_outcome — before you ask an AI agent to do the work. (About 5 minutes.)
Step 3 HAND
Hand the filled contract to your AI agent as the work specification.
Step 4 AUDIT
After the change ships, return to the file and write the audit section (PASS / FAIL / MUTATED per clause).
Get the template →
Link: https://github.com/jewanchen/mtm-contract/blob/main/TEMPLATE.md
Where this goes next.
Phase 1 — Markdown convention
AVAILABLE NOW. Zero dependencies. Adopt by agreeing to fill in the template before AI-delegated work.
Phase 2 — CLI toolchain
PLANNED. mtm new, validate, audit, metrics, list, search.
Consumes the markdown; enforces and indexes the discipline.
Phase 3 — Editor and orchestrator integrations
PLANNED. MCP server for Anthropic-compatible clients; Claude Code skill; Cursor extension; Aider annotation; OpenAI function-calling schema. Thin wrappers over the CLI.
Pull requests welcome under Apache 2.0.
License
Apache License, Version 2.0. Attribution to Vast Intelligence Limited required in derivative works (forks, tools implementing the MTM Contract specification, adapted documentation, academic
citations).
Citation
Vast Intelligence Limited. (2026).
MTM Contract: A Framework for Preventing Hallucination and Architectural Drift in Agentic AI Coding.
https://github.com/jewanchen/mtm-contract
LICENSE and NOTICE →
Contact Us
Get in touch so we can start working together.