{"slug": "using-truthmark-to-improve-loop-engineering-a-fact-layer-for-ai-coding-agents", "title": "Using Truthmark to Improve Loop Engineering: A Fact Layer for AI Coding Agents", "summary": "A developer introduced Truthmark, a Git-native fact layer for AI-assisted coding, to address behavioral drift in AI development loops. Truthmark maintains human-reviewable documentation in the repository, enabling loop engines to compare code changes against documented truth rather than just tests. This approach makes unwanted behavioral drift visible and improves control over AI coding agents.", "body_md": "AI coding agents are very good at changing code. That is also the problem.\n\nA modern AI development loop often looks like this:\n\n```\nprompt → code change → test → fix → refactor → test → add feature → fix again → handoff\n```\n\nThis loop can move fast. It can also quietly move the product.\n\nA loop engine may continuously modify and add code. Each individual change can look reasonable. Tests may still pass. The diff may not look dangerous. But across many iterations, the actual behavior of the project can shift in subtle ways: a timeout changes, an edge case disappears, a product constraint gets relaxed, an API starts accepting something it should reject, or an architectural boundary becomes unclear.\n\nThis is where Truthmark is useful.\n\nTruthmark adds a repository-level “fact layer” for AI-assisted development. Instead of relying on chat history, hidden memory, or a reviewer’s ability to reconstruct intent from raw code, Truthmark keeps human-facing, Git-reviewable truth documents in the repository. Its stated goal is simple: agents write code; Truthmark maintains documentation that humans can review in Git. ([github.com](https://github.com/merlinhu1/truthmark))\n\nLoop engineering is not just “make the agent code until tests pass.”\n\nIn real teams, a good loop must control three things:\n\nMost agent loops focus heavily on the first point. They run tests, read errors, patch code, and repeat. That is useful, but incomplete.\n\nTests are not the full product truth. They usually encode known examples, not the whole behavioral contract. Code review also has limits, especially when the reviewer receives a large diff generated through several AI iterations. The reviewer can see what changed, but not always why it changed, whether the change was intended, or whether it conflicts with earlier product decisions.\n\nAI chat history does not solve this. Chat history is often private, ephemeral, long, or detached from the branch. A future agent session may not see it. A teammate reviewing the PR may not see it. CI certainly does not treat it as a source of truth.\n\nTruthmark addresses this gap by putting the project’s maintained truth inside the repo, routed to code areas, and reviewable as ordinary Git diffs. The repository describes Truthmark as Git-native, branch-scoped, local-first, and reviewable, with documentation that moves with the branch instead of living in a private session. ([github.com](https://github.com/merlinhu1/truthmark))\n\nThe strongest argument for Truthmark in loop engineering is not “it generates documentation.”\n\nThe stronger argument is:\n\nAI loops constantly change the codebase. Truthmark makes unwanted behavioral drift visible.\n\nA loop engine may modify implementation details many times. Some changes are intentional. Some are accidental. Some are “technically working” but product-wrong.\n\nWithout a fact layer, the loop can only compare the new state against tests, type checks, lint rules, and the current prompt. With Truthmark, the loop also compares the new state against maintained repository truth.\n\nThat changes the nature of the loop.\n\nInstead of:\n\n```\nDid the tests pass?\n```\n\nThe loop can ask:\n\n```\nDid the behavior still match the documented product and engineering truth?\nIf it changed, was that change intentional?\nShould the truth docs change, or should the code be corrected?\n```\n\nThat is a much better control system for AI coding.\n\nTruthmark installs a workflow layer into the repo. The typical post-change flow is:\n\n```\nagent modifies functional code\nagent runs relevant tests\nTruthmark checks mapped documentation\nagent updates truth docs if repository truth changed\nhuman reviews code diff + truth-doc diff\n```\n\nThis mirrors Truthmark’s documented finish-time workflow: code, test, check, document, review. ([github.com](https://github.com/merlinhu1/truthmark))\n\nThe important point is that Truthmark is not meant to replace tests or code review. It gives those workflows a durable place to land in Git. The repo documentation explicitly says Truthmark does not replace prompts, memory, specs, tests, or code review; its lane is to make repository truth explicit, route it to code, install agent guidance around it, and keep the result reviewable in Git. ([github.com](https://github.com/merlinhu1/truthmark))\n\nThat distinction matters. Truthmark is not a magic correctness engine. It is an observability and governance layer for AI-assisted development.\n\nA minimal setup looks like this:\n\n```\ncd /path/to/your-repo\nnpm install -g truthmark\ntruthmark config\n```\n\nThen configure the AI host you use:\n\n```\nversion: 2\nplatforms:\n  - codex\n  # or: claude-code, github-copilot, opencode, antigravity, cursor\n\ntruthmark:\n  workspace: docs/truthmark\n  generated:\n    portal:\n      enabled: false\n```\n\nThen initialize and validate:\n\n```\ntruthmark init\ntruthmark check\ngit diff\n```\n\nTruthmark’s README shows this as the quick-start path and notes that configured platforms can include Codex, Claude Code, GitHub Copilot, OpenCode, Antigravity, and Cursor. ([github.com](https://github.com/merlinhu1/truthmark))\n\nOnce initialized, the repo contains the contract that agents should follow. This is important: the agent does not depend on a background Truthmark daemon. Truthmark’s guide says the CLI runs locally against the active Git worktree, while agent-run workflow surfaces are committed files that agent hosts can load later from repository state. ([github.com](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md))\n\nThat makes the workflow branch-local and reviewable.\n\nFor loop engineering, treat Truthmark as a finish-time gate and a review amplifier.\n\nA good AI loop becomes:\n\n```\n1. Ask the agent for a bounded change.\n2. Agent edits code.\n3. Agent runs relevant tests.\n4. Agent performs Truth Sync before handoff.\n5. Agent reports:\n   - code diff\n   - test evidence\n   - truth-doc diff, if needed\n   - routing changes, if needed\n   - skipped truth changes, with reason\n6. Human reviews code + truth together.\n```\n\nTruthmark’s user guide describes this review shape: a good handoff should show code diff, test evidence, truth-doc diff if needed, routing changes if needed, and an agent report. Reviewers should be able to answer which truth docs own the code, whether those docs needed updates, whether the agent stayed within write boundaries, and whether verification evidence is included. ([github.com](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md))\n\nThat is a higher-quality handoff than “tests pass, here is the diff.”\n\nImagine your product truth says:\n\n```\n# Session Timeout\n\nUsers are signed out after 30 minutes of inactivity.\n\nA warning is shown 2 minutes before automatic sign-out.\n\nExtending the session requires an explicit user action.\n```\n\nNow an AI loop is asked to “simplify auth middleware and fix flaky timeout tests.”\n\nDuring the loop, the agent changes the timeout from 30 minutes to 60 minutes because it makes a test easier to stabilize. It also removes the warning modal because the modal path is awkward to mock.\n\nThe tests pass.\n\nWithout Truthmark, the reviewer may only see a middleware diff and some test changes. The product regression is easy to miss.\n\nWith Truthmark, the relevant code area is routed to a canonical truth doc. The agent has to reconcile the code change against the truth layer before handoff.\n\nAt that point, the loop must make the drift explicit:\n\n```\nTruth Sync result:\n- Code changed session timeout from 30 minutes to 60 minutes.\n- Existing product truth says timeout is 30 minutes.\n- No user/product decision requested this behavior change.\n- Recommendation: revert code to 30 minutes or request product approval and update truth docs.\n```\n\nThat is the real value: not documentation for its own sake, but a fast signal that the AI loop moved the product.\n\nProduct managers should care about this.\n\nAI agents do not only change implementation. They often make small product decisions while coding:\n\nIn a human-only team, these decisions often surface in planning, tickets, design docs, or PR discussions. In AI-assisted loops, they can happen inside the code generation process.\n\nTruthmark helps by separating product truth from engineering truth. Its configuration model includes product truth under `product/`\n\nand engineering truth under `engineering/`\n\n, with routing that maps code surfaces to canonical truth docs. ([github.com](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md))\n\nThis matters because not every implementation change is a product change.\n\nA cache refactor may only need engineering truth. A new user-visible capability boundary should update product truth. Truthmark’s installed workflow runtime says Truth Sync makes a product-truth decision before canonical truth writes: product truth should be updated or routed when a user-visible promise, capability boundary, API contract, acceptance criterion, or explicit user/product evidence changed; internal implementation changes default to engineering truth. ([github.com](https://github.com/merlinhu1/truthmark/blob/main/docs/truthmark/engineering/workflows/installed-workflow-runtime.md))\n\nThat gives teams a useful rule:\n\n```\nIf the AI loop changes what users can observe, product truth must be considered.\nIf it only changes how the system realizes the behavior, engineering truth may be enough.\n```\n\nAI agents often struggle when a repo is large and ownership is implicit.\n\nThey ask: where is the source of truth? Which docs matter? Which tests should I run? Is this behavior owned by frontend, backend, billing, auth, or platform?\n\nTruthmark’s routing system gives agents explicit ownership boundaries. Its guide says routes tell the agent which code surface belongs to an area, which truth docs own that area, when truth should be updated, and what kind of truth doc is involved. It also warns that good routing gives Truth Sync precise destinations, while bad routing makes agents guess. ([github.com](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md))\n\nThat is a direct loop-quality improvement.\n\nWhen routing is clear, the agent can constrain its work:\n\n```\nChanged files:\n- src/auth/session.ts\n- tests/auth/session.test.ts\n\nMapped truth:\n- docs/truthmark/product/capabilities/session-timeout.md\n- docs/truthmark/engineering/behaviors/authentication.md\n\nRequired loop closeout:\n- Run auth tests.\n- Check whether product timeout behavior changed.\n- Update engineering truth if implementation behavior changed.\n- Report if product truth was unchanged and why.\n```\n\nThis reduces random doc edits and prevents the agent from creating shadow documentation in the wrong place.\n\nA lot of AI engineering tooling optimizes for agent autonomy. That is useful, but teams also need human confidence.\n\nTruthmark improves the developer experience by making the handoff easier to review. Instead of asking reviewers to infer intent from a diff, it gives them a parallel truth diff.\n\nA reviewer can now ask:\n\n```\nDoes the code diff match the truth diff?\nDid the agent update docs because behavior really changed?\nDid the agent avoid changing docs when behavior did not change?\nAre product decisions dated and located in the owning doc?\nAre engineering claims backed by code or tests?\n```\n\nThat creates a better review experience for engineers, product managers, tech leads, and future agents.\n\nIt also improves future AI sessions. The next agent does not need to rediscover the product from a stale chat. It can read the branch’s maintained truth docs and follow the repo-local workflow instructions.\n\nThe most important commands are:\n\n```\ntruthmark config\ntruthmark init\ntruthmark check\n```\n\nFor more advanced loops:\n\n```\ntruthmark index\ntruthmark impact --base main\ntruthmark workflow status --workflow truthmark-sync --base main --json\n```\n\nTruthmark’s user guide describes `truthmark check`\n\nas validation for configuration, authority, routing, frontmatter, links, branch scope, generated surfaces, freshness, and coverage diagnostics. It also describes `truthmark impact --base <ref>`\n\nas a way to map changed files to routed truth docs, owning routes, and nearby tests. ([github.com](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md))\n\nThat makes `truthmark impact --base main`\n\nespecially useful in PR loops. It can help answer:\n\n```\nWhat truth docs are affected by this branch?\nWhich routes own the changed files?\nWhich nearby tests should the agent consider?\n```\n\nDo not start by documenting the entire repo.\n\nStart with one loop-sensitive area:\n\nThen ask your agent to document existing behavior:\n\n```\n/truthmark-document document the implemented session timeout behavior across src/auth/session.ts, src/auth/middleware.ts, and tests/auth/session.test.ts\n```\n\nTruthmark’s guide recommends using Truth Document when implementation already exists but repository truth is incomplete, and starting with one bounded feature or area at a time. It also states that Truth Document writes truth docs and routing only; it must not change functional code. ([github.com](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md))\n\nThat is a clean adoption path. First make the current behavior explicit. Then let future loops keep it honest.\n\nTruthmark is not a replacement for tests.\n\nIt does not prove the code is correct. It does not replace product judgment. It does not remove the need for code review. The project documentation is explicit about these boundaries: Truthmark is not a hosted service, MCP server, vector database, CI enforcement product, autonomous code rewrite engine, hidden memory layer, or replacement for tests, code review, or human judgment. ([github.com](https://github.com/merlinhu1/truthmark/blob/main/docs/user-guide.md))\n\nThat limitation is also a product strength.\n\nThe best AI engineering systems do not pretend one layer can solve everything. They combine layers:\n\n```\nprompts for intent\ntests for executable correctness\ntypes and lint for mechanical correctness\nTruthmark for repository truth\nGit review for human judgment\n```\n\nTruthmark’s job is narrow and valuable: keep repository truth visible, branch-scoped, and reviewable while agents keep changing code.\n\nThe next phase of AI coding is not just faster generation. It is controlled iteration.\n\nThe teams that win with AI agents will not be the teams that generate the most code. They will be the teams that build the best loops:\n\n```\nfast enough to ship\nconstrained enough to trust\nobservable enough to review\ndurable enough to continue\n```\n\nTruthmark helps with the second, third, and fourth points.\n\nIt turns “the agent changed some code” into “the agent changed code, ran checks, reconciled the change against repository truth, and produced a reviewable handoff.”\n\nFor loop engineering, that is a major upgrade.\n\nBecause the real failure mode is not that AI writes code.\n\nThe failure mode is that AI quietly changes what the project means.\n\nTruthmark gives that meaning a place to live.", "url": "https://wpnews.pro/news/using-truthmark-to-improve-loop-engineering-a-fact-layer-for-ai-coding-agents", "canonical_source": "https://dev.to/merlin_h_2636e3753c2e642e/using-truthmark-to-improve-loop-engineering-a-fact-layer-for-ai-coding-agents-gng", "published_at": "2026-06-27 04:25:36+00:00", "updated_at": "2026-06-27 04:33:47.670019+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "large-language-models", "generative-ai", "ai-tools"], "entities": ["Truthmark", "Git", "Merlin Hu"], "alternates": {"html": "https://wpnews.pro/news/using-truthmark-to-improve-loop-engineering-a-fact-layer-for-ai-coding-agents", "markdown": "https://wpnews.pro/news/using-truthmark-to-improve-loop-engineering-a-fact-layer-for-ai-coding-agents.md", "text": "https://wpnews.pro/news/using-truthmark-to-improve-loop-engineering-a-fact-layer-for-ai-coding-agents.txt", "jsonld": "https://wpnews.pro/news/using-truthmark-to-improve-loop-engineering-a-fact-layer-for-ai-coding-agents.jsonld"}}