Truthmark - an agent-native truth governance workflow for large project collaboration

[weak raft]

I’ve been building a small open-source tool called Truthmark, and I’d like feedback from people who actually use AI agents / vibe coding in real projects.

The problem I’m trying to solve:

When I use AI coding tools, the code can move fast, but the “why” behind changes gets messy. Requirements live in chat. Architecture decisions get repeated. Docs drift. The agent remembers something in one session, then forgets it later. Reviewers can see the code diff, but not always the context that led to it.

Truthmark is my attempt to make that context live inside the repo instead of disappearing into prompt history.

The basic idea:

create a branch-scoped truth layer in Git
map parts of the codebase to the docs that own them
give AI agents explicit routing/workflow boundaries
keep truth docs updated when code changes
make the agent’s context reviewable as normal repo files

So instead of:

“Claude/Codex made some changes and the context is buried in chat”

it becomes:

“Here is the code diff, and here is the committed repo truth that changed with it.”

It’s not an MCP server, not a memory database, and not a hosted product. It’s more like a lightweight repo practice packaged as a small CLI + agent workflow files.

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

[dense flower]

This hits a real pain point. I've run into the exact same issue building multi-agent systems with LangGraph — the agent does the right thing but the reasoning behind a decision is buried in chat history or lost between sessions.
The architecture diagram looks solid. Does Truthmark persist the "why" as structured metadata alongside the code, or is it more like a linked doc layer? Curious how you handle conflicts when the agent's decision contradicts earlier requirements.

[weak raft]

Currently I try to enforce business level decisions ("what the user has decided it should do") at document layer only. I do have plan to make technical decisions ("why it is implemented this way") stored in the code in the form of comments. However this will modify code files and is slightly crossing the boundary I defined for the "Sync" flow. And some people may not like this behavior too. I'm thinking if I can make it optional in config

[dense flower]

That makes sense — keeping business decisions at doc layer and technical decisions as code comments is a clean separation.
Making it optional in config sounds like the right call. Some teams are strict about clean commit history and wouldn't want auto-generated comments touching their code. A toggle would cover both workflows.
Are you planning to expose this via a config file or more like a per-project setting?

[weak raft]

One nice thing about this project is that config file is per-project. What will happen is when config and init is called, the workflow will be inject to the repository itself based on the config (not to a user/developer's local profile). So let's say if we configure a repo to auto-generate technical decisions as code comments, the workflow in this repo will always behave this way, and other projects won't be affected

And because it is agent-native, collaborators do not have to install the truthmark at all (though recommended for optional CLI tools). The assumption is everyone in the team writes code with AI

[weak raft]

Also to say, I will be very cautious with this feature because truthmark also has the potential to run by agent instead of human, so allowing truthmark agent to change code comment can interfer with other ongoing coding agent. I currently restricts doc-write agent to not touch code, and technical decisions live as markdown as default behavior. The toggle config that enables comment sytle documention will be an opt-in feature

[dense flower]

That makes a lot of sense — keeping the toggle as opt-in is the right call, especially if truthmark agents could eventually run autonomously.

The interference concern you raised is something I've run into building multi-agent systems with LangGraph. The pattern I rely on is scoping each agent's write domain at the graph level — so even when agents share state or context, their output targets are structurally isolated. It makes coexistence much safer without needing runtime locks or coordination overhead.

Would be curious to see how truthmark handles agent boundaries internally. Is the project open source?

[weak raft]

Yes the source is in the post body
https://github.com/merlinhu1/truthmark

[dense flower]

This is a really clean approach — branch-scoped truth is
exactly the kind of auditability layer that's missing in
most agent systems.

It connects directly to something I've been working on:
in my LangGraph orchestrator, the critic loop generates
decision logs at each evaluation, but they're buried in
the checkpoint state. Truthmark's approach of surfacing
those decisions alongside the code in PR reviews would
make the whole system much more reviewable.

Have you thought about integrating with LangGraph's
checkpoint store? The state diffs at each node boundary
could map naturally to your branch-scoped truth model.

[weak raft]

Yes the LangGraph can really provide better quality evidence than my native workflow and script. I can imagine a flow like

LangGraph runtime
  ↓
exports structured decision/evidence artifact
  ↓
Truthmark validates/imports artifact
  ↓
Truthmark uses it as routing/context evidence
  ↓
agent updates truth docs or produces PR-review report

But this will place some burden to the LangGraph user to make LangGraph to export evidence to a certain agreed folder.

However evidence freshness check can be a passive pain. If people touch the repo without LangGraph runtime we gonna have problem..

Or maybe using Langgraph as additional supportive evidence layer, this could work better