AI coding agents are useful because they can make changes quickly. That same strength creates a review problem.
In a typical loop, an agent edits code, runs tests, reads failures, patches the implementation, and repeats. The loop may finish with clean tests and a reasonable diff. But somewhere along the way, a small behavior can change: a timeout becomes longer, an optional field becomes required, a retry policy becomes more forgiving, or an API starts accepting a state that used to be rejected.
None of those changes has to look obviously wrong in isolation. The issue is that the project’s behavior has moved, while the review surface still looks like a normal refactor.
That is the problem Truthmark is designed to help with. It gives an AI-assisted codebase a fact layer: human-readable, Git-reviewable Markdown files that describe what the project believes to be true. Agents can still write code quickly, but before they hand work back, they have to reconcile the code changes against the repository’s maintained truth.
For loop engineering, that is the useful part. Truthmark is not just a documentation tool. It is a way to make product and engineering drift easier to observe.
The real risk in AI loops is quiet behavior change
Most AI coding workflows optimize for a loop like this:
prompt -> edit code -> run tests -> inspect failure -> patch -> repeat
That loop is effective for mechanical correctness. It catches syntax errors, broken imports, failing tests, and many obvious regressions.
It is less effective at preserving intent.
A loop engine continuously modifies and adds code. Each step can be locally reasonable. One patch extracts a helper. Another loosens validation so a fixture is easier to construct. Another changes a default because it removes a flaky branch. Another updates tests to match the new behavior.
By the end, the branch may still be green, but the product may no longer behave quite the way it did before.
Tests help, but they are not a complete product contract. They encode examples the team remembered to write. Code review helps, but large AI-generated diffs are hard to review because the reviewer has to reconstruct intent from implementation details. Chat history is also a weak source of truth because it is usually private, long, and detached from the branch.
The missing layer is durable project truth that lives with the code.
What Truthmark adds
Truthmark keeps project truth inside the repository, usually under a workspace such as:
docs/truthmark/
Those files are ordinary Markdown files. They move through Git with the branch. They can be reviewed in the same pull request as the code. They are not hidden memory, an external database, or a separate spec system that quietly falls out of date.
That gives the team a useful review pattern:
code changed -> check the routed truth docs -> update truth if behavior intentionally changed -> review code and truth together
The important word is “intentionally.”
If an agent changes code but the truth document still describes the old behavior, there may be a mismatch. If an agent updates the truth document to describe new behavior, the reviewer can ask whether that behavior change was actually requested. Either way, the change becomes easier to see.
A concrete example: session timeout drift
Imagine the repository has a Truthmark product document like this:
# Session Timeout
## Product contract
Users are signed out after 30 minutes of inactivity.
A warning is shown 2 minutes before automatic sign-out.
Extending the session requires an explicit user action.
Now an agent receives a normal maintenance task:
Refactor the session timeout logic and fix the flaky auth tests.
During the loop, the agent changes a constant:
-const SESSION_TIMEOUT_MINUTES = 30
+const SESSION_TIMEOUT_MINUTES = 60
It also removes a warning path because that path complicated the test setup:
-if (remainingMinutes <= 2) {
- showTimeoutWarning()
-}
The agent updates the tests, the suite passes, and the code looks simpler.
Without a fact layer, this can be reviewed as an implementation refactor. The behavior change is present, but it is buried in the code diff.
With Truthmark, the changed auth files can be routed to the session timeout truth document. Before handoff, the agent has to compare the code with the documented product contract. If it updates the truth document, the review now contains a plain-English behavioral diff:
# Session Timeout
## Product contract
-Users are signed out after 30 minutes of inactivity.
+Users are signed out after 60 minutes of inactivity.
-A warning is shown 2 minutes before automatic sign-out.
+No warning is shown before automatic sign-out.
Extending the session requires an explicit user action.
That diff is much easier for a product manager, tech lead, or reviewer to evaluate.
The right review question becomes:
Was the timeout change intentional?
Was removing the warning part of the request?
Should the truth document change, or should the code be corrected?
This is where Truthmark improves the loop. It turns a hidden semantic change into an explicit review decision.
Tests check execution. Truthmark checks claimed behavior.
A strong AI loop needs more than one feedback mechanism.
Tests answer questions like:
Does this example still pass?
Does this function return the expected result?
Did this integration path break?
Truthmark helps answer a different class of questions:
Does the code still match the behavior the repository claims to support?
Did this branch change a product promise?
Did the agent update engineering truth because an internal invariant changed?
That distinction matters. CI can tell you that the branch is executable. Truthmark helps make it clear whether the branch still matches the project’s documented intent.
A better loop is not simply:
Did the tests pass?
It is:
Did the tests pass, and did the branch preserve or intentionally update the relevant project truth?
Product truth and engineering truth
One useful design choice in Truthmark is the separation between product truth and engineering truth.
Product truth describes user-visible behavior: capabilities, API contracts, acceptance criteria, security boundaries, plan limits, notification rules, billing behavior, and other promises users or customers can observe.
Engineering truth describes how the system works internally: architecture, data flow, invariants, ownership, implementation constraints, and technical decisions future maintainers need to preserve.
This distinction keeps the workflow practical. Not every code change should update product truth.
If an agent rewrites a cache implementation but the external behavior is unchanged, product truth may not need to move. Engineering truth might need an update if the internal invariant changed.
If an agent changes how expired sessions behave, product truth should be checked. The user-visible contract has changed.
A simple rule works well:
If users can observe the change, check product truth.
If maintainers need to understand the change, check engineering truth.
If neither changed, report that truth was checked and left unchanged.
This gives agents a clearer finish condition. They are not only reporting that tests passed. They are reporting which behavioral surface they touched and how that surface relates to the repository’s maintained facts.
Routing reduces guesswork
Large repositories contain a lot of implicit ownership.
An experienced engineer may know that src/auth/session.ts belongs to authentication, that timeout behavior is part of the session product contract, and that the relevant tests live in the auth test suite. An agent may infer some of that from filenames, but inference is not the same as ownership.
Truthmark routes make ownership explicit. Conceptually, a route might look like this:
routes:
- area: authentication
paths:
- src/auth/**
- tests/auth/**
product_truth:
- docs/truthmark/product/session-timeout.md
engineering_truth:
- docs/truthmark/engineering/authentication.md
Now, when the agent edits auth code, it knows which truth documents are relevant. It does not have to create a new explanation in the wrong place or ignore the canonical document because it was not in context.
That improves both agent behavior and human review. The agent gets a better map of the repository. The reviewer gets a clearer relationship between code, tests, and documented intent.
A practical finish-time workflow
For loop engineering, Truthmark is most useful near handoff.
A good agent handoff should include:
1. The code diff.
2. The tests or checks that were run.
3. The Truthmark routes or documents affected by the change.
4. Any truth document updates, or a statement that behavior was checked and did not change.
A practical instruction for an AI agent can be simple:
Before handing off:
- Run the relevant tests.
- Identify Truthmark routes affected by this diff.
- Check the mapped product and engineering truth docs.
- If user-visible behavior changed, update product truth or revert the behavior.
- If an internal invariant changed, update engineering truth if needed.
- Report the code diff, test evidence, affected truth docs, and truth changes.
This does not replace code review. It makes code review more focused.
Instead of asking the reviewer to infer product behavior from a large implementation diff, the handoff gives them an explicit place to inspect behavioral changes.
How to add Truthmark to a repository
A basic setup looks like this:
npm install -g truthmark
truthmark config
truthmark init
truthmark check
Then configure the agent host you use. A minimal configuration can look like this:
version: 2
platforms:
- codex
truthmark:
workspace: docs/truthmark
generated:
portal:
enabled: false
The exact folder is less important than the review model. The truth layer should live in the repo, on the branch, and in the same review path as the code.
Where to start
Do not try to document the whole codebase at once. Start with areas where small unintended behavior changes are expensive:
- authentication
- permissions
- billing
- public API behavior
- data retention
- onboarding
- pricing or plan limits
- notification rules
- security-sensitive workflows
Pick one area. Document the current behavior. Route the relevant code to that document. Then require future agent loops to reconcile changes against it.
For example:
Document the implemented session timeout behavior across the auth middleware, session service, and auth tests. Create product truth only for user-visible behavior. Create engineering truth only for implementation constraints future agents should preserve.
That is enough to make the next refactor easier to review.
What Truthmark does not replace
Truthmark does not replace tests, static analysis, code review, product judgment, or architectural decision-making.
It adds another layer.
Prompts express intent. Tests provide executable checks. Types and linters catch mechanical errors. Code review applies human judgment. Truthmark keeps repository truth visible and reviewable while agents continue changing code.
That is the right scope. AI engineering systems work best when each layer has a clear job.
The point is controlled iteration
The goal of loop engineering is not simply to generate more code. The goal is to make repeated AI-assisted changes safe enough to use in real projects.
A controlled loop should move quickly, but it should also preserve product intent, expose behavioral changes, and make handoff easier for humans.
Truthmark helps by giving the project a place to say what is true, then asking the agent to check that truth before the work lands.
That is a practical improvement: fewer hidden behavior changes, clearer reviews, and better continuity between one AI session and the next.
SOCIAL SHARE CARD GENERATOR