Introducing Truthmark 1.4.0: Git-native truth workflows for AI coding agents

Merlin — Sat, 16 May 2026 15:23:03 +0000

AI coding agents are getting good at changing code.

That creates a new problem.

The code changes, but the repository often stops telling the truth.

The behavior moves ahead of the docs. Architecture notes become stale. Product decisions stay in chat history. Reviewers see the implementation diff, but not the context that changed around it.

Truthmark is built for that gap.

It is a Git-native, branch-scoped workflow layer for AI-assisted software development. It helps coding agents keep repository truth aligned with functional code changes, while leaving humans with ordinary Git diffs they can inspect.

The latest release, Truthmark 1.4.0, adds workflow verifier and writer agents. That makes the installed workflows more useful for larger repositories, where a single agent context can get crowded fast.

What Truthmark does

Truthmark does not try to be another AI model.

It does not host a service. It does not run a database. It does not add an MCP server. It does not ask your team to trust hidden memory.

Instead, it installs workflow infrastructure into your repository.

That infrastructure has two surfaces.

The first surface is the human-facing CLI. Maintainers use it to configure the repository, install workflow files, refresh generated surfaces, and validate the truth setup.

truthmark config
truthmark init
truthmark check

The second surface is AI-facing. Truthmark installs host-native workflow surfaces for coding agents. Depending on the host, these show up as skills, prompts, commands, managed instruction blocks, or project agents.

That distinction is important.

The CLI prepares the repository. The AI-facing surfaces are the runtime that agents use while doing the work.

The normal workflow

The default Truthmark path looks like this:

agent changes functional code
relevant tests run
Truth Sync checks mapped truth docs
truth docs update when needed
human reviews code diff + truth diff

The goal is not to create more documentation.

The goal is to make repository truth harder to skip.

When an AI agent changes behavior, Truthmark gives it a finish-time workflow guard. The agent checks the mapped truth docs before handoff. If the docs need to change, the change appears as a normal Git diff.

That makes the repository easier to review, easier to hand off, and easier to trust.

Why branch-scoped truth matters

A lot of AI tooling focuses on the next answer.

Truthmark focuses on the next handoff.

In real repositories, truth is not global in a simple way. Branches diverge. Architecture changes happen in stages. Product behavior may differ between a feature branch and main. A memory tool can help one user or one session, but it does not automatically give the reviewer a committed record of what the branch currently believes.

Truthmark keeps that context in the repository.

The route files, truth docs, generated workflow surfaces, and instruction blocks live with the branch. They can be reviewed, updated, reverted, and merged like other project files.

That is the point.

AI context becomes repository state.

What is new in 1.4.0

Truthmark 1.4.0 adds project-scoped verifier agents and a leased truth-doc-writer where supported by the host.

This gives the installed workflows a better way to handle bounded evidence work.

For example, a parent workflow can ask a verifier to inspect a specific route, a specific doc claim, or a specific truth-doc shard. The verifier stays read-only. It works inside a bounded assignment instead of wandering through the whole repository.

For document writing, the new leased writer model is intentionally strict. The parent workflow owns the lease, the write boundary, the final report, and the diff validation. The writer does not get broad permission to rewrite the repository.

That is the core idea behind this release:

delegate bounded evidence work
keep parent workflow control
validate the diff before accepting it

This matters because AI workflows often fail by becoming too broad. A task starts as “check this behavior” and turns into a vague repo-wide rewrite. Truthmark 1.4.0 pushes in the opposite direction. Smaller assignments. Clearer leases. Parent-owned acceptance.

Supported agent hosts

Truthmark currently supports generated surfaces for:

codex
opencode
claude-code
github-copilot
gemini-cli

Different hosts expose workflow surfaces differently.

Codex, Claude Code, and supported Copilot IDEs can expose /truthmark-* style workflows. OpenCode uses /skill truthmark-*. Gemini CLI uses /truthmark:*.

The exact files generated depend on your .truthmark/config.yml.

By default, Truthmark includes every supported platform. In a real project, you should remove the platforms you do not use, then rerun:

truthmark init

The workflows

Truthmark installs several AI-facing workflows.

Truth Sync is the normal finish-time workflow after functional code changes. It is code-first. The code leads, and mapped truth docs follow.

Truth Document is for implemented behavior that already exists, but is not documented well enough. It is implementation-first and doc-only. It should not change functional code.

Truth Structure repairs or splits broad routing. This is useful after initialization, because a new repository often starts with one broad route that needs to become real product, service, or domain areas.

Truth Preview is read-only. It lets an agent inspect likely routing before edits.

Truth Realize is doc-first. A truth doc leads, and the agent updates code to match it.

Truth Check is the AI-facing audit workflow. It is separate from the terminal command truthmark check, even though the names are related.

That boundary is deliberate. Humans run the CLI. Agents run the installed workflow surfaces.

Quick start

Install Truthmark in the repository you want to initialize.

cd /path/to/your-repo
npm install -g truthmark

Create the repository truth contract.

truthmark config

Review the generated config.

.truthmark/config.yml

Then install the workflow surfaces.

truthmark init

Validate the setup.

truthmark check

After that, review the generated files before committing. You will usually see route files, truth-doc scaffolding, templates, managed instruction blocks, and host-specific workflow surfaces.

On an existing repository, the first useful agent task is often a structure pass:

/truthmark-structure split the broad repository area into auth, billing, and notifications

That gives Truth Sync better destinations later.

Why I think this matters

AI-assisted development is moving from novelty to daily practice.

The hard part is no longer whether an agent can produce a change. The hard part is whether the team can still understand the repository after many agent-produced changes.

Truthmark is an attempt to make that problem concrete.

Not by adding a dashboard.

Not by adding another memory layer.

Not by asking reviewers to trust the chat transcript.

The repository should carry its own truth. Agents should read it. Agents should update it when their work changes it. Humans should review the result in Git.

That is what Truthmark is for.

Truthmark 1.4.0 takes another step in that direction by making the workflow surface more scalable. Verifier agents can inspect bounded evidence. Leased writer agents can handle bounded doc shards. Parent workflows still own the final judgment.

That balance matters.

AI agents can move fast, but the repository still has to be governable.

Try it

npm install -g truthmark
truthmark config
truthmark init
truthmark check

GitHub: https://github.com/merlinhu1/truthmark

If you try it on an existing repository, start small. Initialize the repo, review the generated config, split the default route into real ownership areas, then let Truth Sync handle the next functional code change.

DEV Community: Merlin