truthmark 1.2.1 → 1.2.3
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.
- package/README.de.md +80 -44
- package/README.es.md +81 -45
- package/README.md +104 -43
- package/README.ru.md +80 -44
- package/README.zh.md +80 -44
- package/dist/main.js +599 -305
- package/dist/main.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,40 +1,68 @@
|
|
|
1
1
|
# Truthmark
|
|
2
2
|
|
|
3
|
-
**Truthmark
|
|
3
|
+
**Truthmark automates truth maintenance for AI software development.**
|
|
4
4
|
|
|
5
5
|
English | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | [Русский](README.ru.md)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
<img src="docs/assets/truthmark-banner.png" alt="Truthmark banner" width="100%" />
|
|
8
8
|
|
|
9
|
-
AI coding agents
|
|
9
|
+
AI coding agents already write code fast. The expensive part is keeping repository truth aligned with what changed.
|
|
10
10
|
|
|
11
|
-
Truthmark
|
|
11
|
+
Truthmark adds an automatic finish-time safeguard to that workflow. The normal path is simple:
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
- agent changes functional code
|
|
14
|
+
- run relevant tests
|
|
15
|
+
- Truth Sync updates mapped truth docs before the agent finishes
|
|
16
|
+
- review the truth-doc diff if one was produced
|
|
14
17
|
|
|
15
|
-
|
|
18
|
+
Most tools ask teams to adopt a habit. Truthmark automates the habit.
|
|
16
19
|
|
|
17
|
-
|
|
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.
|
|
18
21
|
|
|
19
|
-
|
|
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.
|
|
20
23
|
|
|
21
|
-
|
|
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.
|
|
22
25
|
|
|
23
|
-
|
|
26
|
+
## Visual overview
|
|
24
27
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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>
|
|
49
|
+
|
|
50
|
+
## Why teams adopt it
|
|
51
|
+
|
|
52
|
+
Truthmark is not trying to make agents sound smarter. It is trying to make AI-assisted repository change easier to trust.
|
|
53
|
+
|
|
54
|
+
- Automated 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.
|
|
31
59
|
- The model works across JavaScript, TypeScript, Go, Python, C#, and Java codebases.
|
|
32
60
|
|
|
33
|
-
For tech leads, the value is governance without
|
|
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.
|
|
34
62
|
|
|
35
63
|
## Where Truthmark fits
|
|
36
64
|
|
|
37
|
-
Truthmark is not
|
|
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.
|
|
38
66
|
|
|
39
67
|
| If you need | Best fit |
|
|
40
68
|
| --------------------------------------------------------------------- | --------------------------------------- |
|
|
@@ -47,6 +75,7 @@ The point is not that prompts, memory, or specs are useless. The point is that n
|
|
|
47
75
|
|
|
48
76
|
## Table of Contents
|
|
49
77
|
|
|
78
|
+
- [Why teams adopt it](#why-teams-adopt-it)
|
|
50
79
|
- [What Truthmark solves](#what-truthmark-solves)
|
|
51
80
|
- [Where Truthmark fits](#where-truthmark-fits)
|
|
52
81
|
- [Get started](#get-started)
|
|
@@ -63,8 +92,9 @@ The point is not that prompts, memory, or specs are useless. The point is that n
|
|
|
63
92
|
|
|
64
93
|
Truthmark turns repository truth into an explicit workflow surface for agents:
|
|
65
94
|
|
|
66
|
-
-
|
|
95
|
+
- `.truthmark/config.yml` defines the committed hierarchy contract.
|
|
67
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.
|
|
68
98
|
- Truth Sync keeps mapped truth docs aligned with functional changes.
|
|
69
99
|
- Truth Realize gives doc-first changes a bounded code-update path.
|
|
70
100
|
- `truthmark check` validates the resulting truth artifacts.
|
|
@@ -101,37 +131,52 @@ Review `.truthmark/config.yml` before `init`; it is the committed hierarchy cont
|
|
|
101
131
|
|
|
102
132
|
```text
|
|
103
133
|
.truthmark/config.yml
|
|
104
|
-
TRUTHMARK.md
|
|
105
134
|
docs/truthmark/areas.md
|
|
106
135
|
docs/truthmark/areas/repository.md
|
|
136
|
+
docs/templates/feature-doc.md
|
|
107
137
|
docs/features/README.md
|
|
108
138
|
docs/features/repository/README.md
|
|
109
139
|
docs/features/repository/overview.md
|
|
110
140
|
AGENTS.md
|
|
111
141
|
CLAUDE.md
|
|
112
|
-
.
|
|
113
|
-
.codex/skills/truthmark-sync/SKILL.md
|
|
114
|
-
.codex/skills/truthmark-realize/SKILL.md
|
|
115
|
-
.codex/skills/truthmark-check/SKILL.md
|
|
116
|
-
.opencode/skills/truthmark-structure/SKILL.md
|
|
117
|
-
.opencode/skills/truthmark-sync/SKILL.md
|
|
118
|
-
.opencode/skills/truthmark-realize/SKILL.md
|
|
119
|
-
.opencode/skills/truthmark-check/SKILL.md
|
|
142
|
+
GEMINI.md
|
|
120
143
|
```
|
|
121
144
|
|
|
122
|
-
|
|
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`.
|
|
123
146
|
|
|
124
147
|
The default scaffold keeps feature `README.md` files as indexes and starts current behavior truth in bounded leaf docs such as `docs/features/repository/overview.md`.
|
|
125
148
|
|
|
126
|
-
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
|
|
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`.
|
|
150
|
+
|
|
151
|
+
```text
|
|
152
|
+
/truthmark-structure split the broad repository area into auth, billing, and notifications
|
|
153
|
+
```
|
|
127
154
|
|
|
128
155
|
## How it runs
|
|
129
156
|
|
|
130
|
-
Truthmark
|
|
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.
|
|
158
|
+
|
|
159
|
+
### Existing behavior without docs
|
|
160
|
+
|
|
161
|
+
Use this when implementation already exists but the canonical truth docs are missing or weak:
|
|
162
|
+
|
|
163
|
+
```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
|
|
169
|
+
```
|
|
170
|
+
|
|
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`.
|
|
172
|
+
|
|
173
|
+
```text
|
|
174
|
+
/truthmark-document document the implemented session timeout behavior under docs/features/authentication
|
|
175
|
+
```
|
|
131
176
|
|
|
132
177
|
### Normal code changes
|
|
133
178
|
|
|
134
|
-
Most users should not need to invoke Truth Sync directly. The normal path is:
|
|
179
|
+
Most users should not need to invoke Truth Sync directly. The important behavior is that Truth Sync acts as an automatic finish-time safeguard when functional code changed. The normal path is:
|
|
135
180
|
|
|
136
181
|
```text
|
|
137
182
|
agent changes functional code
|
|
@@ -143,7 +188,11 @@ commit or hand off the work
|
|
|
143
188
|
|
|
144
189
|
Truth Sync is code-first: code leads, truth docs follow, and Truth Sync must not rewrite functional code. Its main job is to act as an automatic finish-time safeguard when functional code changed. Direct invocation is mainly for troubleshooting, forcing an early sync before handoff, or running the workflow intentionally.
|
|
145
190
|
|
|
146
|
-
Codex
|
|
191
|
+
Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-sync`. OpenCode-style hosts can invoke `/skill truthmark-sync`.
|
|
192
|
+
|
|
193
|
+
```text
|
|
194
|
+
/truthmark-sync sync the repository truth now before handoff
|
|
195
|
+
```
|
|
147
196
|
|
|
148
197
|
### Doc-first changes
|
|
149
198
|
|
|
@@ -160,33 +209,39 @@ commit or hand off the work
|
|
|
160
209
|
|
|
161
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.
|
|
162
211
|
|
|
163
|
-
Codex
|
|
212
|
+
Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-realize`. OpenCode-style hosts can invoke `/skill truthmark-realize`.
|
|
213
|
+
|
|
214
|
+
```text
|
|
215
|
+
/truthmark-realize realize docs/features/authentication/session-timeout.md into code
|
|
216
|
+
```
|
|
164
217
|
|
|
165
218
|
## What it installs
|
|
166
219
|
|
|
167
|
-
Truthmark keeps the durable workflow surface small
|
|
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.
|
|
168
221
|
|
|
169
222
|
- `.truthmark/config.yml` for machine-readable configuration
|
|
170
|
-
-
|
|
223
|
+
- `.truthmark/config.yml` for the committed hierarchy contract
|
|
171
224
|
- `docs/truthmark/areas.md` for the root route index
|
|
172
225
|
- `docs/truthmark/areas/**/*.md` for delegated child route files
|
|
173
|
-
-
|
|
174
|
-
-
|
|
226
|
+
- `docs/templates/feature-doc.md` for the editable feature-doc standard used by generated workflows
|
|
227
|
+
- managed instruction blocks for configured platforms such as `AGENTS.md`, `CLAUDE.md`, Copilot instructions, and `GEMINI.md`
|
|
228
|
+
- host-native skills, prompts, or commands for Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check
|
|
175
229
|
|
|
176
230
|
The installed workflow surfaces are the runtime:
|
|
177
231
|
|
|
178
232
|
- Truth Structure creates or repairs area routing and starter truth docs.
|
|
233
|
+
- Truth Document creates or repairs truth docs for existing implemented behavior.
|
|
179
234
|
- Truth Sync keeps mapped truth docs aligned with functional changes.
|
|
180
235
|
- Truth Realize updates code to match truth docs.
|
|
181
236
|
- Truth Check audits repository truth health.
|
|
182
237
|
|
|
183
|
-
Feature `README.md` files are indexes. Truth Sync is expected to read and update bounded leaf docs for current behavior.
|
|
238
|
+
Feature `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.
|
|
184
239
|
|
|
185
240
|
Generated surfaces are managed by Truthmark, include a version marker, and may be refreshed by `truthmark init`.
|
|
186
241
|
|
|
187
242
|
## Commands
|
|
188
243
|
|
|
189
|
-
Truthmark V1 intentionally keeps the CLI small. In downstream repositories, `truthmark config` creates the committed hierarchy contract, `truthmark init` installs and refreshes workflow surfaces from that reviewed config, and `truthmark check` validates truth artifacts for manual audits, CI, or troubleshooting.
|
|
244
|
+
Truthmark V1 intentionally keeps the CLI small 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, and `truthmark check` validates truth artifacts for manual audits, CI, or troubleshooting.
|
|
190
245
|
|
|
191
246
|
```bash
|
|
192
247
|
truthmark config
|
|
@@ -202,7 +257,13 @@ truthmark check --json
|
|
|
202
257
|
|
|
203
258
|
`check` validates configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, and coverage diagnostics.
|
|
204
259
|
|
|
205
|
-
Truth Structure, Truth Sync, Truth Realize, and Truth Check are installed agent workflows, not top-level daily CLI commands.
|
|
260
|
+
Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check are installed agent workflows, not top-level daily CLI commands.
|
|
261
|
+
|
|
262
|
+
They run through the configured agent host surfaces, for example Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*`, or Gemini `/truthmark:*`.
|
|
263
|
+
|
|
264
|
+
```text
|
|
265
|
+
/truthmark-check audit routing and truth coverage before review
|
|
266
|
+
```
|
|
206
267
|
|
|
207
268
|
## Why it exists
|
|
208
269
|
|
|
@@ -219,7 +280,7 @@ It assumes serious teams need:
|
|
|
219
280
|
- truth that travels with the branch instead of living in hidden session state
|
|
220
281
|
- workflows that still work when the package is not installed globally
|
|
221
282
|
|
|
222
|
-
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.
|
|
283
|
+
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.
|
|
223
284
|
|
|
224
285
|
## Project status
|
|
225
286
|
|
|
@@ -229,7 +290,7 @@ V1 currently provides:
|
|
|
229
290
|
- `truthmark init`
|
|
230
291
|
- `truthmark check`
|
|
231
292
|
- managed `AGENTS.md` workflow instructions
|
|
232
|
-
- generated Truth Structure, Truth Sync, Truth Realize, and Truth Check skill surfaces for configured agent hosts
|
|
293
|
+
- generated Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check skill surfaces for configured agent hosts
|
|
233
294
|
- branch-scope metadata
|
|
234
295
|
- config, authority, routing, decision-structure, frontmatter, link, and polyglot coverage diagnostics
|
|
235
296
|
|
package/README.ru.md
CHANGED
|
@@ -1,31 +1,68 @@
|
|
|
1
|
-
# Truthmark
|
|
1
|
+
# Truthmark
|
|
2
|
+
|
|
3
|
+
**Truthmark автоматизирует поддержку истины для разработки ПО с ИИ.**
|
|
2
4
|
|
|
3
5
|
[English](README.md) | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | Русский
|
|
4
6
|
|
|
5
|
-
|
|
6
|
-
Truthmark решает эту проблему: он превращает истину репозитория, локальную для ветки, в полноценную поверхность выполнения для агентов. Он устанавливает прямо в репозиторий Git-native слой истины с областью действия в пределах ветки, задает агентам явные границы маршрутизации и рабочих процессов и делает так, чтобы эта истина двигалась вместе с кодом, который действительно будет поставлен.
|
|
7
|
-
Это не более удачная инженерия промптов. Это более управляемый способ использовать ИИ в настоящей кодовой базе: меньше повторных решений, меньше устаревшей документации, чище передача работы и сессии с ИИ, после которых остаются проверяемые инженерные записи, а не только следы в истории промптов или непрозрачном состоянии инструментов.
|
|
8
|
-
Для команд, которые уже знают, что агенты умеют генерировать код, и теперь хотят, чтобы сам репозиторий оставался понятным, проверяемым и управляемым.
|
|
7
|
+
<img src="docs/assets/truthmark-banner.png" alt="Баннер Truthmark" width="100%" />
|
|
9
8
|
|
|
10
|
-
|
|
9
|
+
ИИ-агенты уже быстро пишут код. Дорогая часть — удерживать истину репозитория в соответствии с тем, что реально изменилось.
|
|
10
|
+
|
|
11
|
+
Truthmark добавляет в этот процесс автоматическую финальную защиту. Обычный путь прост:
|
|
12
|
+
|
|
13
|
+
- агент меняет функциональный код
|
|
14
|
+
- запускаются релевантные тесты
|
|
15
|
+
- Truth Sync обновляет связанные документы истины до завершения работы агента
|
|
16
|
+
- если был создан diff документов истины, его проверяют
|
|
17
|
+
|
|
18
|
+
Большинство инструментов просит команды выработать привычку. Truthmark автоматизирует эту привычку.
|
|
19
|
+
|
|
20
|
+
Truthmark превращает ИИ-процесс в инфраструктуру репозитория, а не в персональный инструмент. Он устанавливает Git-native слой истины внутри репозитория, задает агентам явную маршрутизацию и ограниченные рабочие поверхности и сохраняет эту истину проверяемой в Git вместо того, чтобы разносить ее по истории промптов, устаревшей документации или приватному состоянию инструментов.
|
|
21
|
+
|
|
22
|
+
Это важно, потому что процесс живет вместе с веткой. После инициализации репозитория правила, маршрутизация и установленные рабочие поверхности путешествуют внутри репозитория, поэтому совместная работа и передача задач меньше зависят от локальной настройки одного человека.
|
|
11
23
|
|
|
12
|
-
|
|
13
|
-
Этот сбой проявляется предсказуемо: требования остаются в чатах, архитектурные решения принимаются заново, агенты трогают не те области, а ветки наследуют контекст, который ревьюеры не могут надежно проверить. Код может двигаться быстро, но репозиторию становится труднее доверять.
|
|
14
|
-
Truthmark меняет рабочую модель:
|
|
24
|
+
Для команд, которые уже знают, что агенты умеют генерировать код, Truthmark решает следующую проблему: как сделать так, чтобы сам репозиторий оставался понятным, проверяемым и управляемым по мере роста ИИ-ассистированной разработки.
|
|
15
25
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
26
|
+
## Визуальный обзор
|
|
27
|
+
|
|
28
|
+
<table>
|
|
29
|
+
<tr>
|
|
30
|
+
<td align="center" width="50%">
|
|
31
|
+
<img src="docs/assets/truthmark-features.png" alt="Возможности Truthmark" width="100%" />
|
|
32
|
+
<br><strong>Возможности</strong><br>
|
|
33
|
+
Что устанавливает Truthmark и как устроена рабочая поверхность.
|
|
34
|
+
</td>
|
|
35
|
+
<td align="center" width="50%">
|
|
36
|
+
<img src="docs/assets/truthmark-position.png" alt="Позиционирование Truthmark" width="100%" />
|
|
37
|
+
<br><strong>Позиционирование</strong><br>
|
|
38
|
+
Где Truthmark находится относительно промптов, памяти и spec-first процессов.
|
|
39
|
+
</td>
|
|
40
|
+
</tr>
|
|
41
|
+
<tr>
|
|
42
|
+
<td align="center" colspan="2">
|
|
43
|
+
<img src="docs/assets/truthmark-syncflow.png" alt="Поток sync в Truthmark" width="100%" />
|
|
44
|
+
<br><strong>Поток sync</strong><br>
|
|
45
|
+
Как Truth Sync закрывает обычные изменения кода перед передачей работы.
|
|
46
|
+
</td>
|
|
47
|
+
</tr>
|
|
48
|
+
</table>
|
|
49
|
+
|
|
50
|
+
## Почему команды выбирают Truthmark
|
|
51
|
+
|
|
52
|
+
Truthmark не пытается сделать так, чтобы агенты звучали умнее. Он пытается сделать изменения в репозитории, выполненные с помощью ИИ, более надежными.
|
|
53
|
+
|
|
54
|
+
- Автоматический Truth Sync после изменений кода превращает поддержку документации в защиту рабочего процесса, а не в командную привычку.
|
|
55
|
+
- Истина, ограниченная веткой, движется вместе с кодом, поэтому ревьюеры могут проверять актуальную истину в обычных Git diff.
|
|
56
|
+
- Рабочие поверхности, встроенные в репозиторий, упрощают внедрение и делают передачу работы устойчивее, чем одна лишь персональная настройка.
|
|
57
|
+
- Явная маршрутизация в `docs/truthmark/areas.md` и делегированных дочерних файлах маршрутов дает агентам границы ответственности и более безопасные пути записи.
|
|
58
|
+
- Local-first работа избавляет от зависимости на демон, базу данных, удаленный сервис или MCP.
|
|
22
59
|
- Модель работает в кодовых базах на JavaScript, TypeScript, Go, Python, C# и Java.
|
|
23
60
|
|
|
24
|
-
Для технических лидеров ценность в управлении без
|
|
61
|
+
Для технических лидеров ценность в управлении без дополнительной инфраструктуры: тесты, ревью кода и владение зонами ответственности по-прежнему делают основную работу; Truthmark делает контекст агента долговечным, проверяемым и ограниченным веткой.
|
|
25
62
|
|
|
26
63
|
## Где уместен Truthmark
|
|
27
64
|
|
|
28
|
-
Truthmark не
|
|
65
|
+
Truthmark не является универсальным набором ИИ-инструментов для продуктивности. Он занимает конкретный слой в стеке: проверяемая истина репозитория, ограниченная веткой и выровненная с реализацией.
|
|
29
66
|
|
|
30
67
|
| Если вам нужно | Лучший выбор |
|
|
31
68
|
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
|
|
@@ -38,9 +75,9 @@ Truthmark не пытается заменить все остальные ин
|
|
|
38
75
|
|
|
39
76
|
## Содержание
|
|
40
77
|
|
|
78
|
+
- [Почему команды выбирают Truthmark](#почему-команды-выбирают-truthmark)
|
|
41
79
|
- [Что решает Truthmark](#что-решает-truthmark)
|
|
42
80
|
- [Где уместен Truthmark](#где-уместен-truthmark)
|
|
43
|
-
- [Рабочая поверхность](#рабочая-поверхность)
|
|
44
81
|
- [Начало работы](#начало-работы)
|
|
45
82
|
- [Как он работает](#как-он-работает)
|
|
46
83
|
- [Что он устанавливает](#что-он-устанавливает)
|
|
@@ -51,12 +88,13 @@ Truthmark не пытается заменить все остальные ин
|
|
|
51
88
|
- [Не-цели](#не-цели)
|
|
52
89
|
- [Лицензия](#лицензия)
|
|
53
90
|
|
|
54
|
-
##
|
|
91
|
+
## Что решает Truthmark
|
|
55
92
|
|
|
56
93
|
Truthmark превращает истину репозитория в явную рабочую поверхность для агентов:
|
|
57
94
|
|
|
58
|
-
-
|
|
95
|
+
- `.truthmark/config.yml` определяет зафиксированный контракт иерархии.
|
|
59
96
|
- `docs/truthmark/areas.md` и делегированные дочерние файлы маршрутов сопоставляют области кода с документами, которые за них отвечают.
|
|
97
|
+
- Truth Document создает или исправляет канонические документы истины для уже реализованного поведения, когда изменение кода не нужно.
|
|
60
98
|
- Truth Sync поддерживает синхронизацию сопоставленных документов истины при функциональных изменениях.
|
|
61
99
|
- Truth Realize дает изменениям, начинающимся с документации, ограниченный путь для обновления кода.
|
|
62
100
|
- `truthmark check` валидирует получившиеся артефакты истины.
|
|
@@ -92,33 +130,29 @@ node /path/to/truthmark/dist/main.js check
|
|
|
92
130
|
|
|
93
131
|
```text
|
|
94
132
|
.truthmark/config.yml
|
|
95
|
-
TRUTHMARK.md
|
|
96
133
|
docs/truthmark/areas.md
|
|
97
134
|
docs/truthmark/areas/repository.md
|
|
135
|
+
docs/templates/feature-doc.md
|
|
98
136
|
docs/features/README.md
|
|
99
137
|
docs/features/repository/README.md
|
|
100
138
|
docs/features/repository/overview.md
|
|
101
139
|
AGENTS.md
|
|
102
140
|
CLAUDE.md
|
|
103
|
-
.
|
|
104
|
-
.codex/skills/truthmark-sync/SKILL.md
|
|
105
|
-
.codex/skills/truthmark-realize/SKILL.md
|
|
106
|
-
.codex/skills/truthmark-check/SKILL.md
|
|
107
|
-
.opencode/skills/truthmark-structure/SKILL.md
|
|
108
|
-
.opencode/skills/truthmark-sync/SKILL.md
|
|
109
|
-
.opencode/skills/truthmark-realize/SKILL.md
|
|
110
|
-
.opencode/skills/truthmark-check/SKILL.md
|
|
141
|
+
GEMINI.md
|
|
111
142
|
```
|
|
112
143
|
|
|
113
|
-
|
|
144
|
+
Поддерживаемые платформы: `codex`, `opencode`, `claude-code`, `github-copilot` и `gemini-cli`. Конфигурация по умолчанию включает их все; удалите из `.truthmark/config.yml` платформы, которыми не пользуетесь, перед повторным запуском `truthmark init`.
|
|
114
145
|
Стандартная шаблонная структура использует `README.md` функциональных разделов как индексы и начинает описывать истину текущего поведения в ограниченных листовых документах, например `docs/features/repository/overview.md`.
|
|
115
146
|
|
|
116
|
-
Существующим репозиториям обычно нужен один этап очистки после `init`: запустите установленный рабочий процесс Truth Structure, если созданный маршрут `repository` слишком широкий, владение охватывает несколько продуктов или сервисов, либо файлы маршрутов все еще указывают на документы-заглушки. Truth Structure разделяет широкие маршруты, создает или исправляет начальные канонические документы истины и дает Truth Sync точные цели до начала работы с функциональным кодом.
|
|
147
|
+
Существующим репозиториям обычно нужен один этап очистки после `init`: запустите установленный рабочий процесс Truth Structure, если созданный маршрут `repository` слишком широкий, владение охватывает несколько продуктов или сервисов, либо файлы маршрутов все еще указывают на документы-заглушки. Truth Structure разделяет широкие маршруты, создает или исправляет начальные канонические документы истины и дает Truth Sync точные цели до начала работы с функциональным кодом. Codex, Claude Code и поддерживаемые IDE Copilot могут вызвать его через `/truthmark-structure`; хосты в стиле OpenCode могут использовать `/skill truthmark-structure`.
|
|
117
148
|
|
|
118
149
|
## Как он работает
|
|
119
150
|
|
|
120
|
-
Truthmark
|
|
121
|
-
|
|
151
|
+
Сильная сторона Truthmark — путь по умолчанию, а не набор ручных команд. Действующий агент и среда хоста сами решают, делегировать работу или выполнить установленный процесс на месте.
|
|
152
|
+
|
|
153
|
+
Используйте Truth Document, когда поведение уже реализовано, но канонические документы истины отсутствуют или слабы. Агент читает реализацию, тесты, маршруты и существующие документы, пишет только документы истины и маршруты и не должен менять функциональный код. Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-document`; хосты в стиле OpenCode могут использовать `/skill truthmark-document`.
|
|
154
|
+
|
|
155
|
+
Большинству пользователей не нужно вызывать Truth Sync напрямую. Главное, что Truth Sync работает как автоматическая финальная защита, когда менялся функциональный код. Нормальный путь выглядит так:
|
|
122
156
|
|
|
123
157
|
```text
|
|
124
158
|
агент изменяет функциональный код
|
|
@@ -129,7 +163,7 @@ Truth Sync срабатывает до завершения работы аге
|
|
|
129
163
|
```
|
|
130
164
|
|
|
131
165
|
Truth Sync работает по принципу code-first: сначала идет код, затем документы истины, и Truth Sync не должен переписывать функциональный код. Его основная задача быть автоматической финальной проверкой, когда менялся функциональный код. Прямой вызов нужен в основном для отладки, ранней синхронизации перед передачей работы или намеренного запуска рабочего процесса.
|
|
132
|
-
|
|
166
|
+
Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-sync`. Хосты в стиле OpenCode могут использовать `/skill truthmark-sync`.
|
|
133
167
|
Используйте этот путь, когда продуктовое или архитектурное решение начинается в документации:
|
|
134
168
|
|
|
135
169
|
```text
|
|
@@ -142,33 +176,35 @@ Truth Sync работает по принципу code-first: сначала и
|
|
|
142
176
|
```
|
|
143
177
|
|
|
144
178
|
Truth Realize это ручной процесс по принципу doc-first: документы истины идут первыми, код следует за ними, и агент не должен редактировать документы истины, которые он реализует.
|
|
145
|
-
|
|
179
|
+
Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-realize`. Хосты в стиле OpenCode могут использовать `/skill truthmark-realize`.
|
|
146
180
|
|
|
147
181
|
## Что он устанавливает
|
|
148
182
|
|
|
149
|
-
Truthmark
|
|
183
|
+
Truthmark держит постоянную рабочую поверхность маленькой и встроенной в репозиторий. После `truthmark init` сам репозиторий несет маршрутизацию, правила и установленные рабочие поверхности, поэтому команда не зависит только от локальной настройки одного человека.
|
|
150
184
|
|
|
151
185
|
- `.truthmark/config.yml` для машиночитаемой конфигурации
|
|
152
|
-
-
|
|
186
|
+
- `.truthmark/config.yml` для зафиксированного контракта иерархии
|
|
153
187
|
- `docs/truthmark/areas.md` для корневого индекса маршрутов
|
|
154
188
|
- `docs/truthmark/areas/**/*.md` для делегированных дочерних файлов маршрутов
|
|
155
|
-
-
|
|
156
|
-
-
|
|
189
|
+
- `docs/templates/feature-doc.md` для редактируемого стандарта feature-документов, используемого сгенерированными рабочими процессами
|
|
190
|
+
- управляемые блоки инструкций для настроенных платформ, таких как `AGENTS.md`, `CLAUDE.md`, инструкции Copilot и `GEMINI.md`
|
|
191
|
+
- нативные для хоста skills, prompts или commands для Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check
|
|
157
192
|
|
|
158
193
|
Установленные рабочие поверхности и есть среда выполнения:
|
|
159
194
|
|
|
160
195
|
- Truth Structure создает или исправляет маршрутизацию областей и стартовые документы истины.
|
|
196
|
+
- Truth Document создает или исправляет документы истины для уже реализованного поведения.
|
|
161
197
|
- Truth Sync поддерживает синхронизацию сопоставленных документов истины с функциональными изменениями.
|
|
162
198
|
- Truth Realize обновляет код так, чтобы он соответствовал документам истины.
|
|
163
199
|
- Truth Check аудитирует здоровье истины репозитория.
|
|
164
200
|
|
|
165
|
-
`README.md` функциональных разделов это индексы. Ожидается, что Truth Sync будет читать и обновлять ограниченные листовые документы для текущего поведения.
|
|
201
|
+
`README.md` функциональных разделов это индексы. Ожидается, что Truth Sync будет читать и обновлять ограниченные листовые документы для текущего поведения. Сгенерированные рабочие поверхности сохраняют приоритет правил репозитория, рассматривая код реализации и канонические документы истины как свидетельства текущего поведения.
|
|
166
202
|
|
|
167
203
|
Сгенерированные поверхности управляются Truthmark, содержат маркер версии и могут обновляться через `truthmark init`.
|
|
168
204
|
|
|
169
205
|
## Команды
|
|
170
206
|
|
|
171
|
-
Truthmark V1 намеренно держит CLI
|
|
207
|
+
Truthmark V1 намеренно держит CLI небольшим, потому что постоянный рабочий процесс должен жить в установленных агентских поверхностях, а не в длинном списке ежедневных ручных команд. В нижестоящих репозиториях `truthmark config` создает зафиксированный контракт иерархии, `truthmark init` устанавливает и обновляет рабочие поверхности на основе этой проверенной конфигурации, а `truthmark check` валидирует артефакты истины для ручных аудитов, CI или отладки.
|
|
172
208
|
|
|
173
209
|
```bash
|
|
174
210
|
truthmark config
|
|
@@ -181,7 +217,7 @@ truthmark check --json
|
|
|
181
217
|
`config` пишет только `.truthmark/config.yml`, если не используется `--stdout`.
|
|
182
218
|
`init` требует `.truthmark/config.yml`, а затем устанавливает или обновляет локальные файлы рабочих процессов.
|
|
183
219
|
`check` валидирует конфигурацию, полномочия, маршрутизацию, документы с решениями, frontmatter, внутренние ссылки, область действия ветки и диагностику покрытия.
|
|
184
|
-
Truth Structure, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.
|
|
220
|
+
Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.
|
|
185
221
|
|
|
186
222
|
## Зачем он существует
|
|
187
223
|
|
|
@@ -199,14 +235,14 @@ Truth Structure, Truth Sync, Truth Realize и Truth Check это установ
|
|
|
199
235
|
|
|
200
236
|
## Статус проекта
|
|
201
237
|
|
|
202
|
-
Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие
|
|
238
|
+
Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие поверхности, которые превращают правила ИИ-процесса в инфраструктуру репозитория.
|
|
203
239
|
V1 сейчас предоставляет:
|
|
204
240
|
|
|
205
241
|
- `truthmark config`
|
|
206
242
|
- `truthmark init`
|
|
207
243
|
- `truthmark check`
|
|
208
244
|
- управляемые инструкции рабочих процессов в `AGENTS.md`
|
|
209
|
-
- сгенерированные skill-поверхности Truth Structure, Truth Sync, Truth Realize и Truth Check для настроенных агентских хостов
|
|
245
|
+
- сгенерированные skill-поверхности Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check для настроенных агентских хостов
|
|
210
246
|
- метаданные области ветки
|
|
211
247
|
- диагностика конфигурации, полномочий, маршрутизации, структуры решений, frontmatter, ссылок и полиглотного покрытия
|
|
212
248
|
|