AI coding agents are becoming better at changing software.

That is no longer the hardest problem.

The harder problem is keeping the repository understandable after those changes land.

Code changes quickly. Documentation often does not. Product intent lives in chat history. Architecture notes fall behind. Reviewers can inspect the implementation diff, but they often cannot see whether the product promise, engineering contract, and repository workflow are still aligned.

Truthmark is built for that gap.

It is a Git-native workflow layer for AI-assisted software development. It installs repository-local truth workflows so AI agents can keep canonical truth docs aligned with functional code changes, while humans still review normal Git diffs.

Truthmark 2.2.0 takes a significant step forward: it separates product truth from engineering truth.

That may sound like a documentation detail.

It is not.

It is a workflow boundary for AI coding agents.

Why truth needs lanes

Most documentation systems treat “docs” as one surface.

That works until AI agents start using those docs as operational context.

A product promise and an implementation detail are not the same kind of truth.

A product doc should say what must be true, why it matters, who benefits, what boundary is being protected, and what success means.

An engineering doc should say how the repository currently realizes that promise: the behavior, contract, architecture, workflow, operations, tests, and source-backed implementation facts.

When those two kinds of truth collapse into one file, the result is usually weak in both directions.

Product truth becomes a summary of implementation mechanics.

Engineering truth becomes a detailed version of product rationale.

Neither is ideal for humans. Neither is ideal for agents.

Truthmark 2.2.0 introduces explicit product and engineering lanes so agents can reason about these surfaces separately.

The core rule is simple:

Product truth says what must be true and why.
Engineering truth says how the repository currently realizes it.

What is new in Truthmark 2.2.0

Truthmark 2.2.0 adds lane-separated truth surfaces under the Truthmark workspace.

By default, product truth lives under:

docs/truthmark/product

Engineering truth lives under:

docs/truthmark/engineering

Product truth currently uses product capability docs. These docs capture capability promises, users and value, capability scope, current product behavior, acceptance criteria, product decisions, engineering realization links, non-goals, and source references.

Engineering truth uses more specific engineering kinds:

engineering-behavior
engineering-contract
engineering-architecture
engineering-workflow
engineering-operations
engineering-test-behavior

This gives agents a stronger map of what they are editing.

A functional code change usually updates engineering truth first.

A product-lane change should only happen when the implemented behavior, product promise, capability boundary, or explicit product evidence supports it.

Both-lane work is possible, but it must write separate product and engineering docs and link them.

That is the important part.

The goal is not just to split folders.

The goal is to prevent agents from creating mixed documents that blur intent, implementation, and operational evidence.

Cross-lane traceability

Truthmark 2.2.0 adds explicit relationship metadata between product and engineering truth.

Product docs can declare which engineering docs realize them.

Engineering docs can declare which product docs they realize.

Conceptually:

# product truth
realized_by:
  - docs/truthmark/engineering/workflows/installed-workflow-runtime.md

# engineering truth
realizes:
  - docs/truthmark/product/capabilities/agent-native-workflow-injection.md

This creates a practical traceability layer.

A reviewer can start from a product promise and inspect the current engineering realization.

An agent can start from an implementation change and find the product capability it may affect.

The connection is committed to the repository. It is not hidden in model memory. It is not stored in a dashboard. It is not dependent on a live service.

It is just Git.

Why this matters for AI coding agents

AI agents need context, but context is not enough.

They also need boundaries.

Without boundaries, an agent asked to “update the docs” can easily do the wrong thing:

rewrite product intent as implementation detail
mix architecture with user-facing promises
append behavior to README indexes
create catch-all docs that nobody owns
update stale docs without checking code

Truthmark 2.2.0 pushes against that failure mode.

Before writing canonical truth docs, the workflow asks the agent to classify the work:

product-lane
engineering-lane
both-lane
ambiguous

If the lane is ambiguous, the agent should block or route the task through Truth Structure rather than creating a mixed document.

That is a deliberately conservative design.

Truthmark does not try to decide whether a product decision is commercially correct, valuable, prioritized, or desirable.

That judgment belongs to humans.

Truthmark focuses on a narrower workflow question:

Is the repository truth organized, routed, and evidence-backed enough for agents and reviewers to trust the next handoff?

Product truth is not a feature brochure

A product lane can be misunderstood.

Truthmark product truth is not marketing copy. It is not roadmap speculation. It is not a place for aspirational feature promises.

A product truth doc describes current product capability boundaries that are supported by repository evidence, explicit product instruction, or implemented behavior.

For example, a product capability doc can state:

Truthmark gives supported AI hosts explicit, committed workflow surfaces for Structure, Document, Sync, Preview, Realize, Check, and Portal.

That is product truth because it describes the user-visible capability.

The engineering lane then explains how the repository realizes it through generated skills, prompts, commands, managed instruction blocks, helper manifests, and host-specific workflow files.

The two lanes are related, but neither should be a copy of the other.

Engineering truth is not lower-status truth

The engineering lane is not just “implementation notes.”

It is the source-backed current realization of the product and system behavior.

Engineering truth owns things like:

current implementation behavior
API and CLI contracts
generated host surfaces
workflow execution models
architecture boundaries
operations
tests and invariants

For AI agents, that distinction is important.

When an agent changes functional code, the engineering truth is usually where the immediate sync happens.

When the change also affects a product promise or capability boundary, product truth can be updated too, but that update needs explicit support.

This keeps product docs from becoming automatic summaries of every implementation change.

It also keeps engineering docs from becoming product rationale documents.

The workflow model remains Git-native

Truthmark is still not a hosted service.

It does not add a database.

It does not require hidden memory.

It does not ask a reviewer to trust a chat transcript.

Truthmark installs workflow infrastructure into the repository.

That infrastructure includes:

route files
product truth docs
engineering truth docs
templates
managed instruction blocks
host-native skills
host-native prompts and commands
project agents
optional helper metadata

The CLI prepares and validates the repository.

The installed workflow surfaces are what agents use during work.

This distinction matters.

The terminal command truthmark check can validate repository truth health. But the AI-facing Truth Check workflow is an installed workflow surface that an agent can follow directly by reading the checkout.

Truthmark 2.2.0 continues to favor direct checkout inspection.

If the CLI is unavailable, an agent should still be able to inspect committed config, route files, truth docs, source files, templates, and tests directly.

Token-conscious workflow surfaces

Truthmark 2.2.0 also improves generated prompt and command surfaces for supported AI hosts.

The product direction here is straightforward: agents should not preload everything.

A workflow entrypoint should be small. Detailed procedure files should be loaded only when the workflow actually needs them.

That is why generated prompt and command surfaces now act as lightweight adapters.

They point to the canonical installed skill and support files instead of duplicating the full workflow body everywhere.

For example, a host command can say:

Use this prompt as a light-weight adapter for Truthmark Sync.

To run the full workflow, use the installed skill surface.

For the canonical workflow procedure, report template, and workflow-specific support files, read:
- SKILL.md
- support/procedure.md
- support/report-template.md

This reduces prompt bloat while preserving a complete workflow contract in the repository.

It is a practical tradeoff for real agent environments, where unnecessary tokens can crowd out the actual task context.

Supported agent hosts

Truthmark continues to generate host-native surfaces for multiple AI coding environments:

codex
opencode
claude-code
github-copilot
gemini-cli

Different hosts expose workflows differently.

Some use skills. Some use prompts. Some use commands. Some support project agents or subagents.

Truthmark does not force one runtime shape on every host. It generates the surface that fits the host while keeping the workflow contract consistent.

That is important because AI development teams are not standardizing on a single coding agent interface yet.

Truthmark treats the repository as the stable integration point.

The installed workflows

Truthmark includes several AI-facing workflows.

Truth Sync is the finish-time workflow after functional code changes. Code leads; truth docs follow.

Truth Document is for documenting existing implemented behavior. It is implementation-first and doc-only.

Truth Structure repairs routing and truth ownership. It is used when docs are broad, stale, catch-all, mixed-owner, or unrouteable.

Truth Preview is read-only. It helps an agent preview likely workflow routing, target docs, expected writes, or blocking ambiguity before edits.

Truth Realize is doc-first. Truth docs lead, and the agent updates code to match bounded current truth claims.

Truth Check audits repository truth health, routing, ownership, canonical docs, and evidence hygiene.

Truthmark Portal is a manual presentation workflow for generating a committed static HTML view of the truth docs when enabled.

These workflows are intentionally separate.

That separation is part of the product.

A sync workflow should not silently become a structure repair.

A preview workflow should not authorize writes.

A realize workflow should not rewrite truth docs while implementing them.

A check workflow should not replace normal tests or code review.

Each workflow has a boundary.

Quick start

Install Truthmark:

npm install -g truthmark

Create the repository config:

truthmark config

Install or refresh the workflow surfaces:

truthmark init

Validate the setup:

truthmark check

Then review the generated files before committing.

For an existing repository, the first useful workflow is often a structure pass:

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

That gives later Truth Sync runs better destinations.

Why Truthmark is different

Many AI tools focus on producing the next answer.

Truthmark focuses on the next handoff.

That is a different product lane.

The question is not only:

Can the agent change the code?

The question is:

Can the repository still explain itself after the agent changes the code?

Truthmark makes that question concrete.

It gives agents committed workflow surfaces.

It gives reviewers normal Git diffs.

It keeps product truth and engineering truth separate.

It makes traceability explicit.

It treats repository state, not hidden memory, as the durable context.

That is the lane Truthmark is building in: Git-native truth infrastructure for AI coding agents.

Closing

AI-assisted development is moving from isolated prompts to ongoing repository work.

That shift changes what teams need.

They do not only need faster code generation.

They need governed handoffs.

They need evidence-backed repository context.

They need agent workflows that can scale without turning into broad rewrites.

Truthmark 2.2.0 is a step in that direction.

Product truth says what must be true and why.

Engineering truth says how the repository currently realizes it.

Agents use both.

Humans review the diff.

The repository carries its own truth.

Try it

npm install -g truthmark
truthmark config
truthmark init
truthmark check

GitHub:

https://github.com/merlinhu1/truthmark