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.
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.
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.
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.
Routes make ownership explicit
Files, areas, and truth docs are connected by committed routing metadata instead of implicit tribal knowledge.
Product truth and mechanics do not collapse together
User-facing promises can link to implementation reality without becoming the same document.
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.
Agent guidance follows the repo
Generated skills, prompts, commands, and instruction blocks are committed where the agent can read them.
Overgrown docs trigger structure work
When a file starts mixing owners, Truth Structure is the product answer, not a larger paragraph.
Repository files outrank session memory
Current truth lives where maintainers can diff, revert, blame, and review it.
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?
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.
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.
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.
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.
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 $ truthmark init $ truthmark check # After setup, agent guidance and truth routes live in the checkout.