truthmark 1.3.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.de.md +619 -189
  2. package/README.es.md +620 -190
  3. package/README.md +611 -188
  4. package/README.ru.md +628 -198
  5. package/README.zh.md +626 -194
  6. package/dist/main.js +2130 -178
  7. package/dist/main.js.map +1 -1
  8. package/package.json +1 -1
package/README.md CHANGED
@@ -1,301 +1,640 @@
1
1
  # Truthmark
2
2
 
3
- **Truthmark installs repository truth workflows for AI software development.**
3
+ **Your agents write code. Truthmark makes their context reviewable in Git.**
4
4
 
5
5
  English | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | [Русский](README.ru.md)
6
6
 
7
- <img src="docs/assets/truthmark-banner.png" alt="Truthmark banner" width="100%" />
7
+ ![Truthmark banner](docs/assets/truthmark-banner.png)
8
8
 
9
- AI coding agents already write code fast. The expensive part is keeping repository truth aligned with what changed.
9
+ AI coding agents can change a repository faster than humans can keep its context aligned.
10
10
 
11
- Truthmark adds a finish-time workflow guard to that workflow. The normal path is simple:
11
+ Truthmark fixes the part that usually breaks after the code is written: the repository truth.
12
12
 
13
- - agent changes functional code
14
- - run relevant tests
15
- - the installed Truth Sync workflow updates mapped truth docs before the agent finishes
16
- - review the truth-doc diff if one was produced
13
+ It installs a Git-native, branch-scoped workflow layer that helps AI coding agents update the right docs, respect ownership boundaries, and leave humans with normal diffs they can review.
17
14
 
18
- Most tools ask teams to adopt a habit. Truthmark turns the habit into repository workflow infrastructure.
15
+ No hosted service.
19
16
 
20
- Truthmark turns an AI workflow into repo infrastructure, not personal tooling. It installs a Git-native, branch-scoped truth layer inside the repository, gives agents explicit routing and bounded workflow surfaces, and keeps that truth reviewable in Git instead of scattering it across prompt history, stale docs, or private tool memory.
17
+ No database.
21
18
 
22
- That matters because the workflow lives with the branch. Once a repository is initialized, the rules, routing, and installed workflow surfaces travel in-repo, so collaboration and handoffs are less dependent on one person's machine setup.
19
+ No hidden memory layer.
23
20
 
24
- For teams who already know agents can generate code, Truthmark answers the next problem: how to keep the repository itself legible, reviewable, and governable as AI-assisted work scales.
21
+ No extra server to operate.
25
22
 
26
- ## Visual overview
23
+ Just repository truth that moves with the branch.
27
24
 
28
- <table>
29
- <tr>
30
- <td align="center" width="50%">
31
- <img src="docs/assets/truthmark-features.png" alt="Truthmark features" width="100%" />
32
- <br><strong>Features</strong><br>
33
- What Truthmark installs and how the workflow surface is split.
34
- </td>
35
- <td align="center" width="50%">
36
- <img src="docs/assets/truthmark-position.png" alt="Truthmark position" width="100%" />
37
- <br><strong>Position</strong><br>
38
- Where Truthmark fits relative to prompts, memory, and spec workflows.
39
- </td>
40
- </tr>
41
- <tr>
42
- <td align="center" colspan="2">
43
- <img src="docs/assets/truthmark-syncflow.png" alt="Truthmark sync flow" width="100%" />
44
- <br><strong>Sync flow</strong><br>
45
- How Truth Sync closes out normal code changes before handoff.
46
- </td>
47
- </tr>
48
- </table>
25
+ ## The problem
49
26
 
50
- ## Why teams adopt it
27
+ AI coding agents are good at producing code. That creates a new failure mode.
51
28
 
52
- Truthmark is not trying to make agents sound smarter. It is trying to make AI-assisted repository change easier to trust.
29
+ The implementation changes, but the repository story drifts:
53
30
 
54
- - Installed Truth Sync after code changes turns documentation maintenance into a workflow safeguard instead of a team habit.
55
- - Branch-scoped truth moves with the code, so reviewers can inspect current truth in ordinary Git diffs.
56
- - Repository-native workflow surfaces make rollout lighter and handoffs more resilient than per-user setup alone.
57
- - Explicit routing in `docs/truthmark/areas.md` and delegated child route files gives agents ownership boundaries and safer write paths.
58
- - Local-first operation avoids a daemon, database, remote service, or MCP dependency.
59
- - The routing model is language-agnostic, with coverage diagnostics for common JavaScript, TypeScript, Go, Python, C#, and Java code surfaces.
31
+ - behavior lives in chat history
32
+ - architecture docs fall behind
33
+ - product decisions disappear after handoff
34
+ - reviewers see code diffs without the related truth diffs
35
+ - branches quietly develop different versions of “what is true”
36
+ - each agent session has to rediscover context from scratch
60
37
 
61
- For tech leads, the value is governance without extra infrastructure: tests, code review, and ownership still do the real work; Truthmark makes the agent's context durable, inspectable, and branch-scoped.
38
+ Truthmark turns that fragile context into committed repository infrastructure.
62
39
 
63
- ## Where Truthmark fits
40
+ Instead of relying on every human and every agent to remember the right documentation habit, Truthmark installs the habit into the repository.
64
41
 
65
- Truthmark is not a general AI productivity suite. It occupies a specific layer of the stack: branch-scoped, reviewable repository truth that stays aligned with implementation.
42
+ ## The promise
66
43
 
67
- | If you need | Best fit |
68
- | --------------------------------------------------------------------- | --------------------------------------- |
69
- | Better results from a single coding session | Better prompts and tighter task framing |
70
- | Convenience across sessions for one agent or one operator | Memory tools |
71
- | Spec-first planning for new features | Spec tools such as Spec Kit |
72
- | Branch-scoped, reviewable repository truth that travels with the code | Truthmark |
44
+ When an agent changes functional code, the work should not end with only a code diff.
73
45
 
74
- The point is not that prompts, memory, or specs are useless. The point is that none of them, by themselves, turn repository truth into a committed, inspectable asset that survives handoffs, review, and branch divergence.
46
+ The normal Truthmark path is:
75
47
 
76
- ## Table of Contents
48
+ ```text
49
+ agent changes functional code
50
+ relevant tests run
51
+ Truth Sync checks mapped truth docs
52
+ truth docs update when needed
53
+ human reviews code diff + truth diff
54
+ commit or hand off
55
+ ```
77
56
 
78
- - [Why teams adopt it](#why-teams-adopt-it)
79
- - [What Truthmark solves](#what-truthmark-solves)
80
- - [Where Truthmark fits](#where-truthmark-fits)
81
- - [Get started](#get-started)
82
- - [How it runs](#how-it-runs)
83
- - [What it installs](#what-it-installs)
84
- - [Commands](#commands)
85
- - [Why it exists](#why-it-exists)
86
- - [Project status](#project-status)
87
- - [Documentation](#documentation)
88
- - [Non-goals](#non-goals)
89
- - [License](#license)
57
+ That is the core value: **AI work becomes easier to trust because the repository stays legible.**
90
58
 
91
- ## What Truthmark solves
59
+ ## Two surfaces, one truth system
92
60
 
93
- Truthmark turns repository truth into an explicit workflow surface for agents:
61
+ Truthmark is not just a CLI.
94
62
 
95
- - `.truthmark/config.yml` defines the committed hierarchy contract.
96
- - `docs/truthmark/areas.md` and delegated child route files map code areas to the docs that own them.
97
- - Truth Document generates or repairs canonical truth docs for existing implemented behavior when no code change is needed.
98
- - Truth Sync keeps mapped truth docs aligned with functional changes.
99
- - Truth Realize gives doc-first changes a bounded code-update path.
100
- - `truthmark check` validates the resulting truth artifacts.
101
- - The whole model stays local-first and Git-native.
63
+ It has two distinct surfaces, and the distinction matters.
102
64
 
103
- This is the core promise: agent context becomes committed repository state instead of a private session artifact.
65
+ ### 1. Human-facing CLI
104
66
 
105
- ## Get started
67
+ The CLI is for maintainers, reviewers, and automation.
106
68
 
107
- Install Truthmark in the repository you want to initialize:
69
+ Use it to configure a repository, install or refresh workflow files, validate truth artifacts, and generate optional review context.
108
70
 
109
71
  ```bash
110
- cd /path/to/your-repo
111
- npm install -g truthmark
112
72
  truthmark config
113
73
  truthmark init
114
74
  truthmark check
115
75
  ```
116
76
 
117
- If you want to try unreleased changes from a source checkout instead:
77
+ The CLI prepares and validates the repository environment.
118
78
 
119
- ```bash
120
- cd /path/to/truthmark
121
- npm install
122
- npm run build
79
+ It is not the AI workflow runtime.
80
+
81
+ ### 2. AI-facing workflow surfaces
82
+
83
+ The AI-facing surfaces are for coding agents.
123
84
 
85
+ Truthmark installs host-native skills, prompts, commands, managed instruction blocks, and supported subagent surfaces so AI agents can follow repository-specific truth workflows inside their normal coding tools.
86
+
87
+ Examples:
88
+
89
+ ```text
90
+ /truthmark-sync
91
+ /truthmark-document
92
+ /truthmark-structure
93
+ /truthmark-realize
94
+ /truthmark-preview
95
+ /truthmark-check
96
+ ```
97
+
98
+ These look like commands because agent hosts expose workflows through slash commands, prompts, skills, or project commands.
99
+
100
+ They are not shell commands.
101
+
102
+ They are AI-facing workflow entrypoints.
103
+
104
+ The split is the product:
105
+
106
+ ```text
107
+ humans own the repository contract
108
+ Truthmark installs the contract into the repo
109
+ agents operate inside that contract
110
+ truth updates appear as Git diffs
111
+ humans review the result
112
+ ```
113
+
114
+ ## Quick start
115
+
116
+ ### Requirements
117
+
118
+ - Node.js `>=20`
119
+ - npm
120
+ - a Git repository
121
+
122
+ ### Install Truthmark
123
+
124
+ Run this inside the repository you want to initialize:
125
+
126
+ ```bash
124
127
  cd /path/to/your-repo
125
- node /path/to/truthmark/dist/main.js config
126
- node /path/to/truthmark/dist/main.js init
127
- node /path/to/truthmark/dist/main.js check
128
+ npm install -g truthmark
129
+ ```
130
+
131
+ ### Create the repository truth contract
132
+
133
+ ```bash
134
+ truthmark config
128
135
  ```
129
136
 
130
- Review `.truthmark/config.yml` before `init`; it is the committed hierarchy contract. After `init`, review the generated workflow surface and route files so the routed docs match the docs that actually own your code:
137
+ This creates:
131
138
 
132
139
  ```text
133
140
  .truthmark/config.yml
134
- docs/truthmark/areas.md
135
- docs/truthmark/areas/repository.md
136
- docs/templates/behavior-doc.md
137
- docs/truth/README.md
138
- docs/truth/repository/README.md
139
- docs/truth/repository/overview.md
140
- AGENTS.md
141
- CLAUDE.md
142
- GEMINI.md
143
141
  ```
144
142
 
145
- Supported platforms are `codex`, `opencode`, `claude-code`, `github-copilot`, and `gemini-cli`. The default config includes all of them; remove platforms you do not use from `.truthmark/config.yml` before rerunning `truthmark init`.
143
+ Review this file before continuing. It defines the committed hierarchy contract for the repository.
144
+
145
+ ### Install the workflow surfaces
146
+
147
+ ```bash
148
+ truthmark init
149
+ ```
150
+
151
+ This installs or refreshes:
152
+
153
+ - route files
154
+ - truth-doc scaffolding
155
+ - managed instruction blocks
156
+ - AI-facing workflow surfaces for configured platforms
157
+
158
+ ### Validate the setup
159
+
160
+ ```bash
161
+ truthmark check
162
+ ```
146
163
 
147
- The default scaffold keeps truth `README.md` files as indexes and starts current behavior truth in bounded leaf docs such as `docs/truth/repository/overview.md`.
164
+ Then review the generated files before committing.
148
165
 
149
- Existing repositories usually need one cleanup pass after `init`: run the installed Truth Structure workflow when the generated `repository` route is too broad, ownership spans multiple products or services, or route files still point at placeholder docs. Truth Structure splits broad routing, creates or repairs starter canonical truth docs, and gives Truth Sync precise destinations before functional-code work begins. Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-structure`; OpenCode-style hosts can invoke `/skill truthmark-structure`.
166
+ The exact files depend on `.truthmark/config.yml`, but the install always has the same shape: routing, truth scaffolding, compact managed instructions, and host-native workflow surfaces for the enabled platforms.
167
+
168
+ ## First real use
169
+
170
+ Most repositories need one cleanup pass after initialization.
171
+
172
+ The default scaffold starts with a broad `repository` area. Real repositories usually need more precise routing.
173
+
174
+ Ask your agent to split the broad route into actual product, service, domain, or ownership areas:
150
175
 
151
176
  ```text
152
177
  /truthmark-structure split the broad repository area into auth, billing, and notifications
153
178
  ```
154
179
 
155
- ## How it runs
180
+ After that, use your AI coding agent normally.
181
+
182
+ When the agent changes functional code, Truth Sync acts as the finish-time guard that checks whether mapped truth docs need to change before handoff.
183
+
184
+ ## What you get
185
+
186
+ | Capability | What it does |
187
+ | --- | --- |
188
+ | Git-native truth | Keeps repository truth in committed Markdown and config. |
189
+ | Branch-scoped context | Truth moves with the branch instead of living in a private session. |
190
+ | Human CLI | Gives maintainers setup, refresh, validation, and inspection commands. |
191
+ | AI-facing workflows | Gives agents host-native workflows for sync, documentation, structure, preview, realization, and audit. |
192
+ | Explicit routing | Maps code areas to canonical truth docs. |
193
+ | Reviewable handoffs | Produces ordinary Git diffs for both code and truth docs. |
194
+ | Local-first operation | Requires no hosted service, daemon, database, or MCP server. |
195
+ | Safer write boundaries | Separates code-first, doc-first, read-only, and doc-only workflows. |
196
+ | Validation | Reports routing, authority, frontmatter, link, generated-surface, branch-scope, freshness, and coverage issues. |
197
+
198
+ ## Visual overview
199
+
200
+ ![Truthmark features](docs/assets/truthmark-features.png)
201
+
202
+ **Features:** what Truthmark installs and how the workflow surface is split.
203
+
204
+ ![Truthmark position](docs/assets/truthmark-position.png)
156
205
 
157
- Truthmark is strongest on the default path, not as a pile of manual commands. The acting agent and host environment decide whether to delegate or run the installed workflow inline.
206
+ **Position:** where Truthmark fits relative to prompts, memory, and spec workflows.
207
+
208
+ ![Truthmark sync flow](docs/assets/truthmark-syncflow.png)
209
+
210
+ **Sync flow:** how Truth Sync closes out normal code changes before handoff.
211
+
212
+ ## Why teams adopt it
158
213
 
159
- ### Existing behavior without docs
214
+ Truthmark is for teams that already know AI agents can generate code.
160
215
 
161
- Use this when implementation already exists but the canonical truth docs are missing or weak:
216
+ The next problem is governance.
217
+
218
+ Not governance as ceremony. Governance as a simple question:
219
+
220
+ > After this AI-assisted change, does the repository still tell the truth?
221
+
222
+ Truthmark helps teams answer that with committed files, explicit routing, and reviewable diffs.
223
+
224
+ It is useful when you need:
225
+
226
+ - less documentation drift
227
+ - better handoffs
228
+ - branch-specific product truth
229
+ - durable architecture and API context
230
+ - explicit ownership between docs and code
231
+ - safer agent write boundaries
232
+ - reviewable context instead of hidden memory
233
+ - AI workflows that still work from committed repo files
234
+
235
+ ## Where Truthmark fits
236
+
237
+ Truthmark does not replace prompts, memory, specs, tests, or code review.
238
+
239
+ It gives those workflows a durable place to land in Git.
240
+
241
+ | Need | Better fit |
242
+ | --- | --- |
243
+ | Better output from one agent session | Better prompt |
244
+ | Personal or session-level continuity | Memory tool |
245
+ | Plan-first feature work | Spec workflow |
246
+ | Branch-scoped truth that travels with code | Truthmark |
247
+ | Validating behavior correctness | Tests and review |
248
+ | Reviewing AI-assisted context changes | Truthmark plus Git review |
249
+
250
+ Truthmark’s lane is narrow by design:
162
251
 
163
252
  ```text
164
- user identifies an implemented behavior or API endpoint
165
- user explicitly invokes Truth Document
166
- agent reads implementation, tests, routing, and existing docs
167
- agent writes truth docs and routing only
168
- review the truth-doc diff
253
+ make repository truth explicit
254
+ route it to code
255
+ install agent workflows around it
256
+ keep the result reviewable in Git
169
257
  ```
170
258
 
171
- Truth Document is manual and implementation-first: code is inspected as evidence, truth docs are created or repaired, and functional code must not be changed. Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-document`. OpenCode-style hosts can invoke `/skill truthmark-document`.
259
+ ## How Truthmark runs
172
260
 
173
- ```text
174
- /truthmark-document document the implemented session timeout behavior under docs/truth/authentication
261
+ Truthmark runs locally against the active Git worktree.
262
+
263
+ The human-facing CLI reads and writes repository files, then exits.
264
+
265
+ The AI-facing workflow surfaces are committed files that agent hosts can load later. That means agents can follow the installed workflow from repository state instead of depending on a background Truthmark process.
266
+
267
+ The layers fit together like this:
268
+
269
+ ```mermaid
270
+ flowchart LR
271
+ Human["Human / CI"] --> CLI["Truthmark CLI"]
272
+ CLI --> Config["Config and route map"]
273
+ CLI --> Truth["Canonical truth docs"]
274
+ CLI --> Surfaces["Generated host-native workflows"]
275
+ Surfaces --> Hosts["Codex / Claude Code / Copilot / OpenCode / Gemini"]
276
+ Hosts --> Worktree["Active Git worktree"]
277
+ Hosts -->|"helper checks / validate / index"| CLI
278
+ Worktree --> Truth
279
+ ```
280
+
281
+ Agents do not talk to a Truthmark daemon, but they can run the installed Truthmark CLI when a workflow asks for validation, indexing, or helper checks.
282
+
283
+ Truthmark owns the generated workflow surfaces it creates, but the important contract is architectural: repo-local config and routing point agents at canonical truth docs, while host-native workflows give each supported agent a way to run the same Truthmark procedures.
284
+
285
+ Generated workflow surfaces include Truthmark version markers. After upgrading Truthmark, rerun:
286
+
287
+ ```bash
288
+ truthmark init
175
289
  ```
176
290
 
177
- ### Normal code changes
291
+ Then review the generated diffs.
292
+
293
+ ## Supported agent platforms
294
+
295
+ The default config includes every supported platform.
296
+
297
+ Remove platforms you do not use from `.truthmark/config.yml`, then rerun:
298
+
299
+ ```bash
300
+ truthmark init
301
+ ```
178
302
 
179
- Most users should not need to invoke Truth Sync directly. The important behavior is that the installed agent workflow treats Truth Sync as a finish-time guard when functional code changed. The normal path is:
303
+ | Platform config name | Generated surface | Invocation shape |
304
+ | --- | --- | --- |
305
+ | `codex` | Skill packages and verifier agents | `/truthmark-*` or `$truthmark-*` |
306
+ | `claude-code` | Project skills, verifier agents, and managed instructions | `/truthmark-*` |
307
+ | `github-copilot` | Agent skills, prompt commands, custom agents, and managed instructions | `/truthmark-*` in supported Copilot IDEs; `@truth-*` custom agents in Copilot CLI |
308
+ | `opencode` | Skill packages and verifier agents | `/skill truthmark-*` |
309
+ | `gemini-cli` | Agent skills, slash commands, subagents, and managed instructions | `/truthmark:*` |
310
+
311
+ Unknown platform names are config errors.
312
+
313
+ Removing a platform stops future refreshes for that platform. It does not delete previously generated files.
314
+
315
+ ## AI-facing workflows
316
+
317
+ These workflows are installed into supported AI coding hosts.
318
+
319
+ They are used by agents or agent hosts during repository work. They are not top-level shell commands.
320
+
321
+ | Workflow | Direction | Use it when | Write boundary |
322
+ | --- | --- | --- | --- |
323
+ | Truth Structure | topology-first | The default route is too broad, ownership spans multiple areas, or route files still point at placeholders. | Creates or repairs routing and starter truth docs. |
324
+ | Truth Document | implementation-first | Behavior already exists in code, but canonical truth docs are missing or weak. | Writes truth docs and routing only. Functional code must not change. |
325
+ | Truth Sync | code-first | Functional code changed and mapped truth docs may need to be updated before handoff. | Updates truth docs. Functional code must not be rewritten by Truth Sync. |
326
+ | Truth Preview | read-only | The agent needs to preview likely routing before edits. | Reads only. Does not authorize writes. |
327
+ | Truth Realize | doc-first | Product or architecture truth docs lead and code should be updated to match. | Updates code only. The agent must not edit the truth docs it is realizing. |
328
+ | Truth Check | audit-first | A reviewer or agent needs to audit repository truth health. | Audits and reports. |
329
+
330
+ ### Important distinction
331
+
332
+ Do not confuse these two surfaces:
333
+
334
+ | Surface | Used by | Example | Meaning |
335
+ | --- | --- | --- | --- |
336
+ | Human CLI | humans, scripts, CI-like checks | `truthmark check` | Validate repository truth artifacts from the terminal. |
337
+ | AI-facing workflow | coding agents and agent hosts | `/truthmark-check` | Ask an agent to run the installed audit workflow. |
338
+
339
+ The names are intentionally related, but the surfaces are different.
340
+
341
+ ## Normal AI-assisted code change
342
+
343
+ Most users should not need to invoke Truth Sync manually every time.
344
+
345
+ Truth Sync is the installed finish-time guard for functional code changes.
180
346
 
181
347
  ```text
182
348
  agent changes functional code
183
- run relevant tests
184
- the installed Truth Sync workflow runs before the agent finishes
185
- review the truth-doc diff if one was produced
186
- commit or hand off the work
349
+ agent runs or asks for relevant tests
350
+ installed workflow detects that functional code changed
351
+ Truth Sync checks mapped truth docs
352
+ agent updates truth docs if needed
353
+ human reviews code diff + truth diff
187
354
  ```
188
355
 
189
- Truth Sync is code-first: code leads, truth docs follow, and Truth Sync must not rewrite functional code. Its main job is to run through the installed agent workflow as a finish-time guard when functional code changed. Direct invocation is mainly for troubleshooting, forcing an early sync before handoff, or running the workflow intentionally.
190
-
191
- Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-sync`. OpenCode-style hosts can invoke `/skill truthmark-sync`.
356
+ Direct invocation is still useful for troubleshooting, forcing an early sync, or making the handoff explicit:
192
357
 
193
358
  ```text
194
359
  /truthmark-sync sync the repository truth now before handoff
195
360
  ```
196
361
 
197
- ### Doc-first changes
362
+ ## Existing behavior without docs
198
363
 
199
- Use this when a product or architecture decision starts in docs:
364
+ Use Truth Document when the implementation already exists but the repository truth is incomplete.
200
365
 
201
366
  ```text
202
- user edits truth docs
203
- user explicitly invokes Truth Realize
204
- agent reads truth docs and relevant code
205
- agent updates code only
206
- run relevant tests
207
- commit or hand off the work
367
+ /truthmark-document document the implemented session timeout behavior under docs/truth/authentication
208
368
  ```
209
369
 
210
- Truth Realize is manual and doc-first: truth docs lead, code follows, and the agent must not edit the truth docs it is realizing.
370
+ Truth Document inspects implementation, tests, route files, and existing docs as evidence.
371
+
372
+ It writes truth docs and routing only.
211
373
 
212
- Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-realize`. OpenCode-style hosts can invoke `/skill truthmark-realize`.
374
+ It must not change functional code.
375
+
376
+ ## Doc-first changes
377
+
378
+ Use Truth Realize when a product or architecture decision starts in docs and code should be updated to match.
213
379
 
214
380
  ```text
215
381
  /truthmark-realize realize docs/truth/authentication/session-timeout.md into code
216
382
  ```
217
383
 
218
- ## What it installs
384
+ Truth Realize is doc-first.
385
+
386
+ The truth docs lead. The code follows.
387
+
388
+ The agent must not edit the truth docs it is realizing.
389
+
390
+ ## Read-only routing preview
391
+
392
+ Use Truth Preview before a change when the agent needs to understand likely routing.
393
+
394
+ ```text
395
+ /truthmark-preview preview the likely truth routing for changes to the billing API
396
+ ```
397
+
398
+ Truth Preview is read-only.
399
+
400
+ It is a selector and planning aid, not write authorization and not a replacement for Truth Check.
401
+
402
+ ## Repository truth audit
403
+
404
+ Use Truth Check when you want an agent-facing audit workflow.
405
+
406
+ ```text
407
+ /truthmark-check audit routing and truth coverage before review
408
+ ```
409
+
410
+ Use the human-facing CLI when you want terminal validation:
411
+
412
+ ```bash
413
+ truthmark check
414
+ ```
415
+
416
+ Both are useful. They are not the same surface.
417
+
418
+ ## Human-facing CLI commands
419
+
420
+ Most maintainers start with three commands.
219
421
 
220
- Truthmark keeps the durable workflow surface small and repository-native. After `truthmark init`, the repo itself carries the routing, rules, and installed workflow surfaces, so teams are not relying only on one operator's local setup.
422
+ | Command | Purpose |
423
+ | --- | --- |
424
+ | `truthmark config` | Create `.truthmark/config.yml`. Writes only that file unless `--stdout` is used. |
425
+ | `truthmark init` | Install or refresh configured workflow surfaces from the reviewed config. |
426
+ | `truthmark check` | Validate configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, generated surfaces, freshness, and coverage diagnostics. |
221
427
 
222
- - `.truthmark/config.yml` for the machine-readable committed hierarchy contract
223
- - `docs/truthmark/areas.md` for the root route index
224
- - `docs/truthmark/areas/**/*.md` for delegated child route files
225
- - `docs/templates/behavior-doc.md` plus the other kind-specific templates under `docs/templates/` for the editable truth-doc standards used by generated workflows
226
- - managed instruction blocks for configured platforms such as `AGENTS.md`, `CLAUDE.md`, Copilot instructions, and `GEMINI.md`
227
- - host-native skills, prompts, or commands for Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check
428
+ Optional repository-intelligence helpers generate derived review context for the active checkout. Generated workflow skill packages may also expose helper manifests and helper policies that call installed `truthmark validate ... --json` CLI validators; those helpers are accelerators, not bundled repo-local scripts or sources of truth. Standalone Copilot prompts and Gemini commands use the same CLI validator contract when the installed runner is available, and otherwise report a visible skipped helper status with manual validation.
228
429
 
229
- The installed workflow surfaces are the runtime:
430
+ They are not sources of truth.
230
431
 
231
- - Truth Structure creates or repairs area routing and starter truth docs.
232
- - Truth Document creates or repairs truth docs for existing implemented behavior.
233
- - Truth Sync keeps mapped truth docs aligned with functional changes.
234
- - Truth Realize updates code to match truth docs.
235
- - Truth Check audits repository truth health.
432
+ | Command | Purpose |
433
+ | --- | --- |
434
+ | `truthmark index` | Build RepoIndex and RouteMap JSON for the active checkout. |
435
+ | `truthmark impact --base <ref>` | Map changed files to routed truth docs, owning routes, nearby tests, and public symbols. |
436
+ | `truthmark context --workflow <workflow> [--base <ref>]` | Generate a bounded ContextPack for Truth Sync, Truth Document, or Truth Realize. Use `--format markdown` for a human-readable pack. |
236
437
 
237
- Truth `README.md` files are indexes. Truth Sync is expected to read and update bounded leaf docs for current behavior. Generated workflow surfaces preserve repository-rule authority while treating implementation code and canonical truth docs as evidence for current behavior.
438
+ Structured output is available with `--json` where supported.
238
439
 
239
- Generated surfaces are managed by Truthmark, include a version marker, and may be refreshed by `truthmark init`.
440
+ ## Configuration
240
441
 
241
- ## Commands
442
+ Truthmark is config-first.
242
443
 
243
- Truthmark V1 keeps the CLI focused because the ongoing workflow is meant to live in the installed agent surfaces, not in a long list of daily manual commands. In downstream repositories, `truthmark config` creates the committed hierarchy contract, `truthmark init` installs and refreshes workflow surfaces from that reviewed config, `truthmark check` validates truth artifacts for manual audits, CI, or troubleshooting, and the repository-intelligence commands generate derived review artifacts when local tooling is available.
444
+ The main config file is:
445
+
446
+ ```text
447
+ .truthmark/config.yml
448
+ ```
449
+
450
+ New repositories should run:
244
451
 
245
452
  ```bash
246
453
  truthmark config
454
+ ```
455
+
456
+ Then review the generated config before running:
457
+
458
+ ```bash
459
+ truthmark init
460
+ ```
461
+
462
+ Important config areas include:
463
+
464
+ | Config area | Purpose |
465
+ | --- | --- |
466
+ | `version` | Config contract version. |
467
+ | `platforms` | Agent hosts that should receive platform-specific generated surfaces. |
468
+ | `docs.layout` | Current docs layout mode. |
469
+ | `docs.roots` | Named canonical documentation roots. |
470
+ | `docs.routing.root_index` | Root route index path. |
471
+ | `docs.routing.area_files_root` | Directory for delegated child route files. |
472
+ | `docs.routing.default_area` | Initial scaffolded child route basename. |
473
+ | `docs.routing.max_delegation_depth` | Current maximum route delegation depth. |
474
+ | `authority` | Ordered canonical docs and globs used as repository truth authority. |
475
+ | `instruction_targets` | Files that receive shared managed instruction blocks, such as `AGENTS.md`. |
476
+ | `frontmatter.required` | Metadata fields that produce error diagnostics when missing. |
477
+ | `frontmatter.recommended` | Metadata fields that produce review diagnostics when missing. |
478
+ | `ignore` | Glob patterns excluded from relevant checks and routing logic. |
479
+
480
+ ## Repository truth routing
481
+
482
+ Truthmark maps code surfaces to truth docs.
483
+
484
+ The main routing files are:
485
+
486
+ ```text
487
+ docs/truthmark/areas.md
488
+ docs/truthmark/areas/**/*.md
489
+ ```
490
+
491
+ A route tells the agent:
492
+
493
+ - which code surface belongs to an area
494
+ - which truth docs own that area
495
+ - when truth should be updated
496
+ - what kind of truth doc is involved
497
+
498
+ The default scaffold starts broad. Existing repositories should usually split the default route into real ownership areas.
499
+
500
+ Example:
501
+
502
+ ```text
503
+ /truthmark-structure split the broad repository area into frontend, backend, billing, and deployment
504
+ ```
505
+
506
+ Good routing gives Truth Sync precise destinations.
507
+
508
+ Bad routing makes agents guess.
509
+
510
+ ## What Truthmark installs
511
+
512
+ Truthmark installs a compact repository-native truth layer.
513
+
514
+ It does this in four layers:
515
+
516
+ - configuration and routing for ownership boundaries
517
+ - canonical truth docs and starter templates
518
+ - compact managed instruction blocks for repository-wide agent context
519
+ - host-native workflow packages, commands, prompts, and verifier agents for the platforms enabled in config
520
+
521
+ Truthmark preserves manual content outside managed instruction blocks.
522
+
523
+ Generated workflow surfaces are managed by Truthmark and may be refreshed by rerunning:
524
+
525
+ ```bash
526
+ truthmark init
527
+ ```
528
+
529
+ ## Subagents and bounded evidence checks
530
+
531
+ Where supported by the host, Truthmark can install project-scoped verifier agents and a leased `truth-doc-writer`.
532
+
533
+ These help keep large truth tasks bounded:
534
+
535
+ - route auditors inspect route ownership
536
+ - claim verifiers check whether doc claims are supported by evidence
537
+ - doc reviewers inspect truth-doc quality
538
+ - leased doc writers handle bounded truth-doc writing shards
539
+
540
+ The parent workflow still owns final interpretation, write boundaries, diff validation, and acceptance.
541
+
542
+ This is important: subagents help with bounded evidence work. They do not replace the main workflow contract.
543
+
544
+ ## Review loop
545
+
546
+ Truthmark is designed for ordinary Git review.
547
+
548
+ A good AI-assisted handoff should show:
549
+
550
+ ```text
551
+ code diff
552
+ test evidence
553
+ truth-doc diff, if needed
554
+ routing changes, if needed
555
+ agent report
556
+ ```
557
+
558
+ The reviewer should be able to answer:
559
+
560
+ - What code changed?
561
+ - Which truth docs own that code?
562
+ - Did those docs need updates?
563
+ - If not, why not?
564
+ - Did the agent stay inside the workflow write boundary?
565
+ - Are tests or verification evidence included?
566
+
567
+ ## Examples
568
+
569
+ ### Initialize a repository
570
+
571
+ ```bash
572
+ npm install -g truthmark
573
+ truthmark config
247
574
  truthmark init
248
575
  truthmark check
249
- truthmark index
250
- truthmark impact --base main
251
- truthmark context --workflow truth-sync --base main
252
- truthmark config --json
253
- truthmark check --json
254
- truthmark index --json
255
- truthmark impact --base main --json
256
- truthmark context --workflow truth-sync --base main --json
257
576
  ```
258
577
 
259
- `config` writes only `.truthmark/config.yml` unless `--stdout` is used.
578
+ ### Remove unused agent platforms
260
579
 
261
- `init` requires `.truthmark/config.yml`, then installs or refreshes the local workflow files.
580
+ Edit:
262
581
 
263
- `check` validates configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, and coverage diagnostics.
582
+ ```text
583
+ .truthmark/config.yml
584
+ ```
264
585
 
265
- `index` builds RepoIndex and RouteMap JSON for the active checkout.
586
+ Then rerun:
266
587
 
267
- `impact --base <ref>` maps changed files to routed truth docs, owning routes, nearby tests, and public symbols.
588
+ ```bash
589
+ truthmark init
590
+ truthmark check
591
+ ```
268
592
 
269
- `context --workflow <workflow> [--base <ref>]` generates a bounded ContextPack for Truth Sync, Truth Document, or Truth Realize. `--format markdown` renders a human-readable pack.
593
+ ### Split broad routing
270
594
 
271
- Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check are installed agent workflows, not top-level daily CLI commands.
595
+ ```text
596
+ /truthmark-structure split the broad repository area into auth, billing, notifications, and deployment
597
+ ```
272
598
 
273
- They run through the configured agent host surfaces, for example Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*`, or Gemini `/truthmark:*`.
599
+ ### Document implemented behavior
274
600
 
275
601
  ```text
276
- /truthmark-check audit routing and truth coverage before review
602
+ /truthmark-document document the implemented password reset flow under docs/truth/authentication
277
603
  ```
278
604
 
279
- ## Why it exists
605
+ ### Sync after code changes
280
606
 
281
- Most AI coding workflows optimize for the next answer. Truthmark optimizes for the next handoff.
607
+ ```text
608
+ /truthmark-sync sync the repository truth now before handoff
609
+ ```
282
610
 
283
- It assumes serious teams need:
611
+ ### Realize a doc-first decision
284
612
 
285
- - branch-specific product truth
286
- - durable architecture and API decisions
287
- - explicit ownership between docs and code
288
- - safe write boundaries for agents
289
- - ordinary Git diffs that humans can review
290
- - readable Markdown that teammates can inspect without special tooling
291
- - truth that travels with the branch instead of living in hidden session state
292
- - workflows that still work when the package is not installed globally
613
+ ```text
614
+ /truthmark-realize realize docs/truth/billing/invoice-retry-policy.md into code
615
+ ```
616
+
617
+ ### Audit truth health from the terminal
618
+
619
+ ```bash
620
+ truthmark check
621
+ ```
293
622
 
294
- Truthmark is not a memory server and it is not an MCP server. It is a repository practice packaged as a small CLI installer plus agent-native workflow surfaces that turn AI workflow rules into repo infrastructure.
623
+ ### Generate branch-impact context
624
+
625
+ ```bash
626
+ truthmark impact --base main
627
+ ```
628
+
629
+ ### Generate workflow context
630
+
631
+ ```bash
632
+ truthmark context --workflow truth-sync --base main --format markdown
633
+ ```
295
634
 
296
635
  ## Project status
297
636
 
298
- V1 currently provides:
637
+ Truthmark V1 currently provides:
299
638
 
300
639
  - `truthmark config`
301
640
  - `truthmark init`
@@ -303,15 +642,58 @@ V1 currently provides:
303
642
  - `truthmark index`
304
643
  - `truthmark impact`
305
644
  - `truthmark context`
306
- - managed `AGENTS.md` workflow instructions
307
- - generated Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check skill surfaces for configured agent hosts
308
645
  - branch-scope metadata
309
- - config, authority, routing, decision-structure, frontmatter, link, freshness, and polyglot coverage diagnostics
310
- - derived RepoIndex, RouteMap, ImpactSet, and ContextPack artifacts for faster local review when the CLI is available
646
+ - managed instruction blocks
647
+ - generated Truth Structure workflow surfaces
648
+ - generated Truth Document workflow surfaces
649
+ - generated Truth Sync workflow surfaces
650
+ - generated Truth Preview workflow surfaces
651
+ - generated Truth Realize workflow surfaces
652
+ - generated Truth Check workflow surfaces
653
+ - route, authority, decision-structure, frontmatter, link, freshness, generated-surface, and coverage diagnostics
654
+ - derived RepoIndex, RouteMap, ImpactSet, and ContextPack artifacts
655
+ - host-specific surfaces for Codex, Claude Code, GitHub Copilot, OpenCode, and Gemini CLI
656
+
657
+ ## Development
658
+
659
+ Install dependencies:
660
+
661
+ ```bash
662
+ npm install
663
+ ```
664
+
665
+ Run the local development CLI:
666
+
667
+ ```bash
668
+ npm run dev -- init
669
+ npm run dev -- check
670
+ ```
671
+
672
+ Run the full project check:
673
+
674
+ ```bash
675
+ npm run check
676
+ ```
677
+
678
+ Useful scripts:
679
+
680
+ | Script | Purpose |
681
+ | --- | --- |
682
+ | `npm run dev` | Run the TypeScript CLI entry point with `tsx`. |
683
+ | `npm run build` | Build the package. |
684
+ | `npm run lint` | Run ESLint. |
685
+ | `npm run typecheck` | Run TypeScript checks. |
686
+ | `npm run test` | Run tests. |
687
+ | `npm run check` | Run lint, typecheck, tests, and build. |
688
+ | `npm run release:check` | Run release-oriented validation. |
689
+
690
+ When changing Truthmark itself, see [CONTRIBUTORS.md](CONTRIBUTORS.md).
311
691
 
312
692
  ## Documentation
313
693
 
314
- The root README is for people evaluating and trying the package. Detailed functional and business specifications live under `docs/`:
694
+ The README is the fast path for evaluation and setup.
695
+
696
+ Detailed current behavior lives under `docs/`:
315
697
 
316
698
  - [Docs index](docs/README.md)
317
699
  - [Architecture overview](docs/architecture/overview.md)
@@ -321,11 +703,11 @@ The root README is for people evaluating and trying the package. Detailed functi
321
703
  - [Installed workflows](docs/truth/workflows/overview.md)
322
704
  - [Repository truth maintenance guide](docs/standards/maintaining-repository-truth.md)
323
705
 
324
- Current behavior belongs in the canonical docs tree above.
706
+ ## Design boundaries
325
707
 
326
- ## Non-goals
708
+ Truthmark is intentionally small.
327
709
 
328
- Truthmark V1 is not:
710
+ It is not:
329
711
 
330
712
  - a hosted service
331
713
  - an MCP server
@@ -334,8 +716,49 @@ Truthmark V1 is not:
334
716
  - a CI or PR enforcement product
335
717
  - a replacement for tests, code review, or technical leadership
336
718
  - an autonomous code rewrite engine
719
+ - a model-training or fine-tuning framework
720
+ - a hidden memory layer
721
+
722
+ Those boundaries are part of the product.
723
+
724
+ Truthmark keeps the workflow local, committed, branch-scoped, and reviewable.
725
+
726
+ ## Safety and review discipline
727
+
728
+ Truthmark helps the repository stay honest. It does not prove the code is correct.
729
+
730
+ Teams should still:
731
+
732
+ - run relevant tests
733
+ - review functional code changes
734
+ - review truth-doc changes
735
+ - keep secrets out of docs
736
+ - keep repository-specific instructions outside managed blocks
737
+ - review generated workflow-surface diffs after upgrades
738
+ - keep human ownership over product and architecture decisions
739
+
740
+ Truthmark makes agent context visible. It does not replace human judgment.
741
+
742
+ ## Roadmap direction
743
+
744
+ The current future direction emphasizes:
337
745
 
338
- It is a lightweight way to make local AI coding agents respect the truth your team keeps in Git.
746
+ - stronger `truthmark check` evidence reporting
747
+ - clearer adoption examples
748
+ - example repositories showing real Truth Sync cycles
749
+ - migration guides for teams already using agent instruction files
750
+ - conformance tests for generated host surfaces
751
+ - route-aware stale-truth hints
752
+ - bounded implementation checklists for doc-first work
753
+
754
+ The center of gravity stays the same:
755
+
756
+ ```text
757
+ repository truth
758
+ agent-native workflows
759
+ Git review
760
+ branch-scoped context
761
+ ```
339
762
 
340
763
  ## License
341
764