AI Tools Need Contracts, Not Prompts

The executable as the interface agents can discover, verify, and trust

An AI agent can read your README, scan your tests, inspect your source tree, and
infer a plausible architecture. Then it can still break your tool by renaming a
flag, weakening an exit condition, or "simplifying" JSON output another script
depends on.

The failure is not always that the model misunderstood the code. Often the
failure is simpler: the contract was not executable.

For AI-assisted engineering, a CLI is no longer just a human interface. It is
the narrowest place where intent, behavior, and verification can meet. It is the
surface an agent can run, observe, validate, and compose.

That is the premise behind entropyx.

entropyx is a local-first Rust CLI for codebase forensics. It scans a git
repository and emits a typed summary of temporal, structural, authorship, and
semantic signals. It can tell you which files absorb change, which ones carry
coupling stress, which public APIs drifted without tests, and which events in
the repository explain the pattern.

But the important idea is not the specific metric set. The important idea is the
shape of the interface.

The executable is the contract.

Not a prompt. Not a dashboard. Not a model-specific integration layer. The
binary exposes what it can do, what it accepts, what it emits, and how to ask
for evidence. Humans can run it. CI can run it. An AI assistant can run it. All
three see the same contract surface.

This is the design pattern: make the tool legible to agents by making the
interface more explicit, not more magical.

The Failure Mode

Many developer tools have implicit contracts.

The README says one thing. --help says another. The tests exercise internal
functions, but not the CLI behavior downstream tools depend on. The JSON output
looks stable until a field is renamed. A command returns text that is easy for a
person to read but brittle for a machine to parse. A failure exits with 0
because a human would notice the error line on stderr.

Humans compensate for this with context. They remember the old behavior. They
know which fields are load-bearing. They know that "pretty output" is not the
automation path. They know which flags are part of the public contract even if
the code does not say so.

Agents do not get that memory for free.

They can infer. They can search. They can run tests. But if the contract lives
in prose, convention, and tribal knowledge, an agent will eventually step on it.
It may even make a locally reasonable change that passes the test suite while
breaking the actual interface.

That is the operational problem AI-first tooling has to solve.

The answer is not more prompt text explaining how to behave. The answer is a
contract surface the agent can execute.

The Reframe: CLI As Protocol

The command line is often treated as a wrapper around the real product. For
AI-first tools, that is backwards.

The CLI is the protocol.

It has named commands, explicit inputs, observable outputs, exit codes, and a
natural place for versioning. It runs locally. It composes with files, pipes, CI
jobs, scripts, and terminals. It is already the interface most coding agents can
operate.

That makes it a good contract boundary.

The point is not that every product should be only a CLI. The point is that if a
tool claims to support AI-assisted engineering, it should expose a surface that
agents can discover and verify without guessing.

For entropyx, that surface is intentionally small:

entropyx describe
entropyx schema
entropyx scan /path/to/repo
entropyx explain /path/to/repo file:<blob-prefix>
entropyx calibrate --summary summary.json --labels labels.json

The core agent loop is the first four commands. calibrate is the offline
weight-fitting path: take a prior summary, join it with labeled file scores, fit
new weights, and feed those weights back into a later scan.

Five commands are enough because the commands are not just verbs. They are the
contract anatomy.

The Contract Anatomy

An AI-first executable needs more than --help.

--help is optimized for a person who already knows what kind of thing they are
running. An agent needs a machine-readable answer to a different set of
questions:

• What is this executable?
• What can it do?
• What inputs does it accept?
• What output shapes does it produce?
• What invariants does it promise?
• How expensive is this operation likely to be?
• How do I drill from a summary into evidence?

In entropyx, describe answers the first set of questions:

entropyx describe

It emits the protocol root as JSON: name, version, contract version, purpose,
capabilities, input types, output formats, cost model, and invariants.

schema answers the shape question:

entropyx schema > tq1-schema.json

It emits the JSON Schema for the tq1 summary envelope. The schema $id is tied
to the protocol contract version, so a breaking output change is not invisible.

scan answers the evidence question:

entropyx scan /path/to/repo > summary.json

It walks local git history and emits a dense repository summary.

explain answers the drill-down question:

entropyx explain /path/to/repo file:<blob-prefix>
entropyx explain /path/to/repo commit:<sha>
entropyx explain /path/to/repo range:<base>..<head>

The summary currently mints file:<blob-prefix> handles for HEAD blobs.
explain also accepts commit:<sha> and range:<base>..<head> address forms,
which lets an agent ask for commit or release-window evidence without relying on
a prior summary entry.

That distinction matters. A contract should say exactly which identifiers it
emits and which identifiers it accepts.

What The Contract Looks Like

The most important output path is not prose. It is tq1, a typed JSON envelope.

A simplified summary looks like this:

{
  "schema": {"name": "tq1", "version": "0.1.0"},
  "dict": {
    "files": ["src/lib.rs"],
    "authors": ["[e-mail]"],
    "metrics": [
      "change_density",
      "author_entropy",
      "temporal_volatility",
      "coupling_stress",
      "blame_youth",
      "semantic_drift",
      "test_cooevolution",
      "composite"
    ]
  },
  "files": [
    {
      "file": 0,
      "values": [0.4, 0.2, 0.1, 0.7, 0.3, 0.6, 0.5, 0.43],
      "lineage_confidence": 1.0,
      "signal_class": "api_drift"
    }
  ],
  "events": [],
  "handles": {
    "file:abc123def456": {
      "kind": "file",
      "file": 0,
      "blob_prefix": "abc123def456"
    }
  },
  "enrichments": {"pull_requests": {}}
}

This is not pretty terminal output that an agent has to reverse-engineer. It is
the protocol.

The dictionary pins the string tables. The metric column order is explicit. The
file rows are dense. Events are typed. Handles are keyed by their canonical
string form. Optional enrichments live in a sidecar.

That design gives an agent a stable path:

1. Read the schema and contract version.
2. Decode the dictionaries.
3. Rank or filter file rows.
4. Inspect typed events.
5. Ask explain for evidence by address.

The final answer can be prose. The instrument should emit structure.

Entropyx As The Case Study

entropyx measures seven axes for each file:

• D_n: change density
• H_a: author dispersion
• V_t: temporal volatility
• C_s: coupling stress
• B_y: blame youth
• S_n: semantic drift
• T_c: test co-evolution

The composite score is useful, but it is not the contract by itself. Every score
decomposes into the axes that produced it.

That is the difference between a measurement and an opinion. If a file scores
high because coupling stress is high, the assistant should say that. If the
score is driven by semantic drift without test co-evolution, that is a different
claim. If author dispersion is rising on a hot file, that is an ownership
problem, not a generic risk label.

The rule-based signal taxonomy is also part of the protocol:

• incident_aftershock
• coupled_amplifier
• refactor_convergence
• api_drift
• ownership_fragmentation
• frozen_neglect

And the event stream has five variants:

• rename
• hotspot
• incident_aftershock
• ownership_split
• api_drift

These are not generated explanations. They are typed outputs. An assistant can
use them, cite them, filter them, and ask for the evidence behind them.

That is the central division of labor:

• The executable measures.
• The protocol preserves structure.
• The assistant chooses what to inspect.
• The assistant explains the evidence to the user.

Determinism Is Agent UX

Determinism is not just a testing preference. It is user experience for agents.

If the same command on the same repository produces different results, the
assistant has to reason about the measurement system instead of the codebase.
Did the repository change? Did the tool change? Did a clock, random seed,
network call, parallel reduction, or model update move the result?

entropyx keeps the core scan deterministic for the same repo state, entropyx
version, flags, and local inputs.

That means:

• no wall-clock reads in the core measurement layer
• deterministic floating-point reductions
• stable interning across serialization round trips
• local git history as the source of truth
• no ML scoring in the deterministic physics layer
• versioned protocol contracts

Optional GitHub enrichment is deliberately separate. It can attach pull request
metadata to event commit SHAs, but that remote sidecar is not the foundation of
the local measurement.

This separation is important. A deterministic core can be cached, diffed,
tested, signed, and reproduced. Remote enrichment can add context without
turning the core finding into a network-dependent claim.

For a human, this makes the output auditable. For an agent, it makes the output
safe to build on.

Evidence Before Interpretation

An AI assistant is good at interpretation. That does not mean the tool should
ask the assistant to invent the evidence.

entropyx starts with the repository. Commits, diffs, authorship, renames, blame
snapshots, public API deltas, test co-change, and co-change graphs become the
measurement layer. The assistant does not need to infer the whole history from
raw git log output before it can answer a question.

The result is a smaller and more reliable loop.

Instead of:

1. Read the README.
2. Guess which git commands to run.
3. Inspect a pile of diffs.
4. Infer which files matter.
5. Hope the answer is grounded.

The assistant can:

1. Run entropyx describe.
2. Run entropyx scan.
3. Inspect the typed summary.
4. Ask entropyx explain for the few addresses that matter.
5. Write an answer tied to concrete evidence.

This is not about replacing engineering judgment. It is about giving judgment a
better input.

The same pattern applies beyond codebase forensics. Test selection, dependency
analysis, migration planning, security review, release risk, documentation
drift, and compliance evidence all benefit from the same contract shape:
summarize the domain, expose typed findings, and let the agent fetch proof.

Handles Make The Protocol Navigable

Handle-addressable evidence is the most important part of the pattern.

A summary should be compact enough to read as a map. It should not dump the
entire warehouse into the agent's context. But a summary without drill-down is
just another report.

Handles bridge that gap.

A handle is a stable, user-facing pointer from a finding to evidence that can be
retrieved on demand. In entropyx, file handles are content-addressed by blob
prefix. Commit and range address forms let explain resolve git objects and
release windows directly.

That gives the assistant a clean workflow:

• read the map
• choose the region
• fetch the evidence
• cite the address
• repeat only where needed

This matters because context is expensive, even when the context window is
large. A tool that emits everything at once forces the assistant to pay for
everything before it knows what matters. A handle-driven protocol lets the
assistant spend attention where the evidence points.

It also helps humans. A reviewer can take the same handle, run the same command,
and inspect the same evidence. The handle becomes a shared reference, not an
opaque explanation generated in a chat transcript.

Honest Absence

AI systems are vulnerable to confident falsehoods. Tools should not make that
worse.

entropyx is designed to return explicit absence when it cannot measure
something. If a language backend is unknown, semantic drift contributes zero for
that file. That zero means "unmeasured by this axis," not "stable." If optional
GitHub enrichment is missing, the pull request sidecar is empty. If a handle
cannot be resolved, the command fails cleanly.

This is less flashy than a tool that always has an answer. It is more useful.

An AI-first instrument should not try to sound intelligent. It should be precise
about what it knows, where the measurement came from, and where the evidence
stops.

The assistant can then say, "the scan did not measure semantic drift for this
file type," rather than treating silence as safety.

The Tradeoff

Executable contracts are less flexible than informal interfaces.

That is a feature.

If a JSON field is part of the protocol, changing it should feel like changing
an API. If an exit code communicates failure, weakening it should break a test.
If a schema version is pinned to a contract version, a breaking change should be
visible to consumers. If a command emits handles, the accepted handle forms
should be documented and tested.

This creates friction. It should.

AI agents need stable edges. CI needs stable edges. Human operators need stable
edges during incidents. A tool that changes shape casually forces every consumer
to rediscover the boundary.

The lesson is not that a CLI can never evolve. It is that the evolution should
be explicit. Version the contract. Preserve compatibility where possible. Break
it deliberately when necessary.

The Blueprint

The entropyx pattern generalizes to other AI-first developer tools.

Start with a small executable surface:

tool describe
tool schema
tool scan <target>
tool explain <target> <address>

Add domain-specific commands only when they have a clear role, as calibrate
does for entropyx.

Then make the contract explicit:

• describe exposes capabilities, inputs, outputs, costs, and invariants.
• schema exposes machine-readable output shapes.
• scan produces a dense typed map of the target domain.
• explain resolves stable addresses into evidence.
• exit codes are commitments, not decoration.
• structured output is the automation path.
• prose is for humans and final answers.
• optional network enrichment is sidecar data, not the measurement core.
• absence is explicit.
• breaking changes bump the contract.

This is the difference between a prompt-shaped tool and a contract-shaped tool.

A prompt-shaped tool relies on instructions around the tool. A contract-shaped
tool exposes behavior the agent can run and verify.

What Changes Next

The next generation of developer tools will not be judged only by how well
humans can read their documentation. They will also be judged by how reliably
agents can discover, run, validate, and compose their behavior.

That changes what a CLI is.

It is not the wrapper around the product.

It is the contract boundary.

If the contract lives only in prose, an agent can misunderstand it. If it lives
only in internal tests, the agent may never see it. If it lives in the
executable surface, the agent can run it.

That is the standard AI-first developer tools should meet: not documented
intent, but executable commitment.

entropyx is one concrete implementation of that idea. It measures codebase
history, emits a typed protocol, preserves deterministic local evidence, and
lets an assistant drill from summary to proof.

The broader pattern is the part worth carrying forward.

Build tools the agent can call. Make them describe themselves. Give them
schemas. Give them stable addresses. Make the core deterministic. Keep evidence
local when you can. Tell the truth when you cannot measure something.

The code already knows more than the incident room usually remembers.

The tool's job is to read it back in a form both humans and agents can trust.

Attribution and Disclosure

Written by Don / copyleftdev from the entropyx project.

This article was drafted and edited with AI assistance, then reviewed against
the entropyx source and DEV's current publishing guidance before submission.