Repository truth carried by the branch

The branch should explain itself.

Truthmark gives AI-assisted work a reviewable truth layer: current claims, ownership routes, product promises, and implementation facts travel with the same Git branch as the code.

View on GitHub Explore the workflows

Checkout-nativeAfter setup, normal agent work can proceed from committed repository files.
Claim-level reviewDocs change as small, source-backed claims instead of anonymous summaries.
Topology awareWhen truth gets too broad, ownership gets repaired rather than hidden.
Host-shapedInstructions meet agents in their existing coding environments.

More than a docs generator.

Truthmark is best understood as a repository-truth workflow surface. The value is not one feature; it is how several constraints reinforce each other.

Operation

No resident service in the critical path

Helpers can validate and refresh, but the daily closeout path is designed to remain readable from the checkout.

Continuity

Truth is maintained after the first draft

Code changes keep revisiting the mapped docs, so documentation becomes a living review artifact rather than a launch-week export.

Architecture

Routes make ownership explicit

Files, areas, and truth docs are connected by committed routing metadata instead of implicit tribal knowledge.

Governance

Product truth and mechanics do not collapse together

User-facing promises can link to implementation reality without becoming the same document.

Review

Claims are small enough for Git

The desired unit is a durable claim per line or bullet, making truth updates easy to inspect in pull requests.

Portability

Agent guidance follows the repo

Generated skills, prompts, commands, and instruction blocks are committed where the agent can read them.

Repair

Overgrown docs trigger structure work

When a file starts mixing owners, Truth Structure is the product answer, not a larger paragraph.

Boundary

Repository files outrank session memory

Current truth lives where maintainers can diff, revert, blame, and review it.

Workflow field guide

Five workflows. One reviewable loop.

Truthmark does not turn every activity into a command. Three workflows are clear user entry points; Sync closes functional code changes; Structure appears only when ownership needs repair.

You start · truth writes/truthmark-document

Document what already exists

Read implementation and tests, then create or update bounded truth docs without changing functional code.

You start · code writes/truthmark-realize

Turn accepted truth into code

Use product truth as requirements and engineering truth as implementation context. The source docs remain unchanged.

You start · read only/truthmark-check

Audit before review

Inspect routing, evidence, lane shape, and truth health without authorizing writes.

Agent finish-time · truth writesTruth Sync

Close the branch honestly

After functional code changes, review mapped truth, capture supported decisions, and update or explicitly leave claims unchanged with evidence.

Only when needed · topologyTruth Structure

Repair ownership before adding prose

Split broad routes and overgrown docs when the repository can no longer identify a bounded owner.

A truth document over time.

This demo is fictional, but the workflow is concrete: create the right doc, update it when behavior changes, and split it when ownership gets crowded.

Truth Document creates a narrow engineering owner.created

Evidence read

src/webhooks/retry-policy.ts

tests/webhooks/retry-policy.test.ts

config/webhook-delivery.yml

Created doc

Webhook delivery behavior

Current behavior

Failed deliveries are retried three times.
Backoff starts at 30 seconds and doubles per attempt.
Manual replay remains available after automatic retries stop.

Non-goals

The service does not claim exactly-once delivery.

Truth Sync separates a user promise from runtime mechanics.curated

Branch changes

README.md adds operator reliability copy

src/webhooks/replay-audit.ts

tests/webhooks/replay-audit.test.ts

Two updated surfaces

Product promise vs implementation fact

Product truth

Operators can inspect failed delivery history before replay.
The product presents replay as an operator recovery tool, not an automatic guarantee.

Engineering truth

Replay writes an audit row with actor, delivery id, and timestamp.
The retry limit remains unchanged.

Truth Structure changes the shape before prose gets heavier.split

Topology pressure

delivery retries + manual replay + alert thresholds + export audit

one doc now has four owners

future edits would be ambiguous

New ownership map

Owned docs after split

engineering/webhook-delivery.md owns retry and delivery lifecycle.
engineering/webhook-replay.md owns operator replay behavior.
engineering/webhook-audit.md owns audit rows and export format.
product/webhook-reliability.md owns customer-facing recovery promises.

The reviewer sees a small packet, not a mystery transcript.review

Pull request surface

code diff: retry + replay behavior

test diff: replay audit coverage

truth diff: product + engineering docs

route diff: ownership split

Reviewer questions

What the PR now answers

Which user promise changed?
Which implementation behavior supports it?
Which files own future updates?
Which claims should be rejected if the code changes again?

Repository truth model

Keep the promise and the mechanism in different rooms.

Truthmark links what users can rely on to how the repository currently realizes it. The relationship is explicit, but neither document inherits authority from the other.

Two lanes, linked on purpose.

Truthmark can let product and engineering documents reference each other without forcing them into the same voice or authority level.

Promise lane

What the project says users can rely on

This lane is for product capabilities, boundaries, acceptance criteria, and non-goals.

Operators can inspect replay history.
The workflow is repository-native by default.
Generated presentation pages are not canonical truth.

Mechanics lane

What the current implementation actually does

This lane is for runtime behavior, contracts, operations, architecture, and failure modes.

Backoff doubles after each failed delivery attempt.
GitHub Pages deploys the committed static site under site/**.
Generated surfaces refresh when rendered content changes.

Three committed layers make the handoff legible.

The route map decides ownership, truth docs preserve current claims, and host-native guidance tells the coding agent when each surface may change.

Route

Find the bounded owner

Changed paths map to an area and its canonical product or engineering truth docs.

Truth

Preserve the claim

Human-facing Markdown records current behavior, rationale, boundaries, and evidence in the right lane.

Guidance

Meet the agent in its host

Committed skills, prompts, commands, and instruction blocks carry write boundaries into normal coding work.

The workflow is deliberately boring at runtime.

Truthmark's ambition is in the repository model, not in requiring every contributor to adopt a new always-on system.

1. SetupConfigure routes and install agent-facing surfaces.

→

2. WorkAgent changes code in its normal host.

→

3. CloseoutMapped truth docs are checked, edited, split, or left unchanged with evidence.

Adoption path

Install the contract, then get out of the way.

Choose the agent host your team already uses. Truthmark commits its guidance, routes, and truth docs to the repository, so the next branch can continue without a background service.

Start with the repo, not a server.

Install once, commit the workflow surface, and let future branches carry their truth updates through normal review.

$ cd /path/to/your-repo
$ npm install -g truthmark
$ truthmark config
# Add the host you use to .truthmark/config.yml, for example: platforms: [codex]
$ truthmark init
$ truthmark check

# After setup, agent guidance and truth routes live in the checkout.

What lands in the repo

A small contract with visible parts

Every durable surface can be reviewed, blamed, reverted, and carried by the branch.

1

Config and routesChoose platforms and map code areas to bounded truth owners.

2

Human-facing truthKeep product capabilities and engineering reality separate but linked.

3

Host-native guidanceInstall the workflow shape where your coding agent already looks.

Choose your first move

Begin with one bounded area

Document one implemented behavior with code and test evidence. Then keep coding normally and let finish-time Sync review future changes.

Codex
Claude Code
GitHub Copilot
OpenCode
Antigravity
Cursor

Read the quick start Open the user guide

Presentation is not authority.

This website explains the product. Canonical behavior remains in the repository's README, routed truth docs, source, tests, and configuration. Truthmark adds no required daemon, database, hosted service, or hidden memory layer.