truthmark 1.2.2 → 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 +75 -31
- package/README.es.md +76 -32
- package/README.md +97 -30
- package/README.ru.md +75 -31
- package/README.zh.md +75 -31
- package/dist/main.js +360 -102
- 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,14 +131,15 @@ 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
|
|
142
|
+
GEMINI.md
|
|
112
143
|
```
|
|
113
144
|
|
|
114
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`.
|
|
@@ -117,13 +148,35 @@ The default scaffold keeps feature `README.md` files as indexes and starts curre
|
|
|
117
148
|
|
|
118
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`.
|
|
119
150
|
|
|
151
|
+
```text
|
|
152
|
+
/truthmark-structure split the broad repository area into auth, billing, and notifications
|
|
153
|
+
```
|
|
154
|
+
|
|
120
155
|
## How it runs
|
|
121
156
|
|
|
122
|
-
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
|
+
```
|
|
123
176
|
|
|
124
177
|
### Normal code changes
|
|
125
178
|
|
|
126
|
-
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:
|
|
127
180
|
|
|
128
181
|
```text
|
|
129
182
|
agent changes functional code
|
|
@@ -137,6 +190,10 @@ Truth Sync is code-first: code leads, truth docs follow, and Truth Sync must not
|
|
|
137
190
|
|
|
138
191
|
Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-sync`. OpenCode-style hosts can invoke `/skill truthmark-sync`.
|
|
139
192
|
|
|
193
|
+
```text
|
|
194
|
+
/truthmark-sync sync the repository truth now before handoff
|
|
195
|
+
```
|
|
196
|
+
|
|
140
197
|
### Doc-first changes
|
|
141
198
|
|
|
142
199
|
Use this when a product or architecture decision starts in docs:
|
|
@@ -154,31 +211,37 @@ Truth Realize is manual and doc-first: truth docs lead, code follows, and the ag
|
|
|
154
211
|
|
|
155
212
|
Codex, Claude Code, and supported Copilot IDEs can invoke it with `/truthmark-realize`. OpenCode-style hosts can invoke `/skill truthmark-realize`.
|
|
156
213
|
|
|
214
|
+
```text
|
|
215
|
+
/truthmark-realize realize docs/features/authentication/session-timeout.md into code
|
|
216
|
+
```
|
|
217
|
+
|
|
157
218
|
## What it installs
|
|
158
219
|
|
|
159
|
-
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.
|
|
160
221
|
|
|
161
222
|
- `.truthmark/config.yml` for machine-readable configuration
|
|
162
|
-
-
|
|
223
|
+
- `.truthmark/config.yml` for the committed hierarchy contract
|
|
163
224
|
- `docs/truthmark/areas.md` for the root route index
|
|
164
225
|
- `docs/truthmark/areas/**/*.md` for delegated child route files
|
|
226
|
+
- `docs/templates/feature-doc.md` for the editable feature-doc standard used by generated workflows
|
|
165
227
|
- managed instruction blocks for configured platforms such as `AGENTS.md`, `CLAUDE.md`, Copilot instructions, and `GEMINI.md`
|
|
166
|
-
- host-native skills, prompts, or commands for Truth Structure, Truth Sync, Truth Realize, and Truth Check
|
|
228
|
+
- host-native skills, prompts, or commands for Truth Structure, Truth Document, Truth Sync, Truth Realize, and Truth Check
|
|
167
229
|
|
|
168
230
|
The installed workflow surfaces are the runtime:
|
|
169
231
|
|
|
170
232
|
- Truth Structure creates or repairs area routing and starter truth docs.
|
|
233
|
+
- Truth Document creates or repairs truth docs for existing implemented behavior.
|
|
171
234
|
- Truth Sync keeps mapped truth docs aligned with functional changes.
|
|
172
235
|
- Truth Realize updates code to match truth docs.
|
|
173
236
|
- Truth Check audits repository truth health.
|
|
174
237
|
|
|
175
|
-
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.
|
|
176
239
|
|
|
177
240
|
Generated surfaces are managed by Truthmark, include a version marker, and may be refreshed by `truthmark init`.
|
|
178
241
|
|
|
179
242
|
## Commands
|
|
180
243
|
|
|
181
|
-
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.
|
|
182
245
|
|
|
183
246
|
```bash
|
|
184
247
|
truthmark config
|
|
@@ -194,10 +257,14 @@ truthmark check --json
|
|
|
194
257
|
|
|
195
258
|
`check` validates configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, and coverage diagnostics.
|
|
196
259
|
|
|
197
|
-
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.
|
|
198
261
|
|
|
199
262
|
They run through the configured agent host surfaces, for example Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*`, or Gemini `/truthmark:*`.
|
|
200
263
|
|
|
264
|
+
```text
|
|
265
|
+
/truthmark-check audit routing and truth coverage before review
|
|
266
|
+
```
|
|
267
|
+
|
|
201
268
|
## Why it exists
|
|
202
269
|
|
|
203
270
|
Most AI coding workflows optimize for the next answer. Truthmark optimizes for the next handoff.
|
|
@@ -213,7 +280,7 @@ It assumes serious teams need:
|
|
|
213
280
|
- truth that travels with the branch instead of living in hidden session state
|
|
214
281
|
- workflows that still work when the package is not installed globally
|
|
215
282
|
|
|
216
|
-
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.
|
|
217
284
|
|
|
218
285
|
## Project status
|
|
219
286
|
|
|
@@ -223,7 +290,7 @@ V1 currently provides:
|
|
|
223
290
|
- `truthmark init`
|
|
224
291
|
- `truthmark check`
|
|
225
292
|
- managed `AGENTS.md` workflow instructions
|
|
226
|
-
- 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
|
|
227
294
|
- branch-scope metadata
|
|
228
295
|
- config, authority, routing, decision-structure, frontmatter, link, and polyglot coverage diagnostics
|
|
229
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,14 +130,15 @@ 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
|
|
141
|
+
GEMINI.md
|
|
103
142
|
```
|
|
104
143
|
|
|
105
144
|
Поддерживаемые платформы: `codex`, `opencode`, `claude-code`, `github-copilot` и `gemini-cli`. Конфигурация по умолчанию включает их все; удалите из `.truthmark/config.yml` платформы, которыми не пользуетесь, перед повторным запуском `truthmark init`.
|
|
@@ -109,8 +148,11 @@ CLAUDE.md
|
|
|
109
148
|
|
|
110
149
|
## Как он работает
|
|
111
150
|
|
|
112
|
-
Truthmark
|
|
113
|
-
|
|
151
|
+
Сильная сторона Truthmark — путь по умолчанию, а не набор ручных команд. Действующий агент и среда хоста сами решают, делегировать работу или выполнить установленный процесс на месте.
|
|
152
|
+
|
|
153
|
+
Используйте Truth Document, когда поведение уже реализовано, но канонические документы истины отсутствуют или слабы. Агент читает реализацию, тесты, маршруты и существующие документы, пишет только документы истины и маршруты и не должен менять функциональный код. Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-document`; хосты в стиле OpenCode могут использовать `/skill truthmark-document`.
|
|
154
|
+
|
|
155
|
+
Большинству пользователей не нужно вызывать Truth Sync напрямую. Главное, что Truth Sync работает как автоматическая финальная защита, когда менялся функциональный код. Нормальный путь выглядит так:
|
|
114
156
|
|
|
115
157
|
```text
|
|
116
158
|
агент изменяет функциональный код
|
|
@@ -138,29 +180,31 @@ Codex, Claude Code и поддерживаемые IDE Copilot могут выз
|
|
|
138
180
|
|
|
139
181
|
## Что он устанавливает
|
|
140
182
|
|
|
141
|
-
Truthmark
|
|
183
|
+
Truthmark держит постоянную рабочую поверхность маленькой и встроенной в репозиторий. После `truthmark init` сам репозиторий несет маршрутизацию, правила и установленные рабочие поверхности, поэтому команда не зависит только от локальной настройки одного человека.
|
|
142
184
|
|
|
143
185
|
- `.truthmark/config.yml` для машиночитаемой конфигурации
|
|
144
|
-
-
|
|
186
|
+
- `.truthmark/config.yml` для зафиксированного контракта иерархии
|
|
145
187
|
- `docs/truthmark/areas.md` для корневого индекса маршрутов
|
|
146
188
|
- `docs/truthmark/areas/**/*.md` для делегированных дочерних файлов маршрутов
|
|
189
|
+
- `docs/templates/feature-doc.md` для редактируемого стандарта feature-документов, используемого сгенерированными рабочими процессами
|
|
147
190
|
- управляемые блоки инструкций для настроенных платформ, таких как `AGENTS.md`, `CLAUDE.md`, инструкции Copilot и `GEMINI.md`
|
|
148
|
-
- нативные для хоста skills, prompts или commands для Truth Structure, Truth Sync, Truth Realize и Truth Check
|
|
191
|
+
- нативные для хоста skills, prompts или commands для Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check
|
|
149
192
|
|
|
150
193
|
Установленные рабочие поверхности и есть среда выполнения:
|
|
151
194
|
|
|
152
195
|
- Truth Structure создает или исправляет маршрутизацию областей и стартовые документы истины.
|
|
196
|
+
- Truth Document создает или исправляет документы истины для уже реализованного поведения.
|
|
153
197
|
- Truth Sync поддерживает синхронизацию сопоставленных документов истины с функциональными изменениями.
|
|
154
198
|
- Truth Realize обновляет код так, чтобы он соответствовал документам истины.
|
|
155
199
|
- Truth Check аудитирует здоровье истины репозитория.
|
|
156
200
|
|
|
157
|
-
`README.md` функциональных разделов это индексы. Ожидается, что Truth Sync будет читать и обновлять ограниченные листовые документы для текущего поведения.
|
|
201
|
+
`README.md` функциональных разделов это индексы. Ожидается, что Truth Sync будет читать и обновлять ограниченные листовые документы для текущего поведения. Сгенерированные рабочие поверхности сохраняют приоритет правил репозитория, рассматривая код реализации и канонические документы истины как свидетельства текущего поведения.
|
|
158
202
|
|
|
159
203
|
Сгенерированные поверхности управляются Truthmark, содержат маркер версии и могут обновляться через `truthmark init`.
|
|
160
204
|
|
|
161
205
|
## Команды
|
|
162
206
|
|
|
163
|
-
Truthmark V1 намеренно держит CLI
|
|
207
|
+
Truthmark V1 намеренно держит CLI небольшим, потому что постоянный рабочий процесс должен жить в установленных агентских поверхностях, а не в длинном списке ежедневных ручных команд. В нижестоящих репозиториях `truthmark config` создает зафиксированный контракт иерархии, `truthmark init` устанавливает и обновляет рабочие поверхности на основе этой проверенной конфигурации, а `truthmark check` валидирует артефакты истины для ручных аудитов, CI или отладки.
|
|
164
208
|
|
|
165
209
|
```bash
|
|
166
210
|
truthmark config
|
|
@@ -173,7 +217,7 @@ truthmark check --json
|
|
|
173
217
|
`config` пишет только `.truthmark/config.yml`, если не используется `--stdout`.
|
|
174
218
|
`init` требует `.truthmark/config.yml`, а затем устанавливает или обновляет локальные файлы рабочих процессов.
|
|
175
219
|
`check` валидирует конфигурацию, полномочия, маршрутизацию, документы с решениями, frontmatter, внутренние ссылки, область действия ветки и диагностику покрытия.
|
|
176
|
-
Truth Structure, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.
|
|
220
|
+
Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.
|
|
177
221
|
|
|
178
222
|
## Зачем он существует
|
|
179
223
|
|
|
@@ -191,14 +235,14 @@ Truth Structure, Truth Sync, Truth Realize и Truth Check это установ
|
|
|
191
235
|
|
|
192
236
|
## Статус проекта
|
|
193
237
|
|
|
194
|
-
Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие
|
|
238
|
+
Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие поверхности, которые превращают правила ИИ-процесса в инфраструктуру репозитория.
|
|
195
239
|
V1 сейчас предоставляет:
|
|
196
240
|
|
|
197
241
|
- `truthmark config`
|
|
198
242
|
- `truthmark init`
|
|
199
243
|
- `truthmark check`
|
|
200
244
|
- управляемые инструкции рабочих процессов в `AGENTS.md`
|
|
201
|
-
- сгенерированные skill-поверхности Truth Structure, Truth Sync, Truth Realize и Truth Check для настроенных агентских хостов
|
|
245
|
+
- сгенерированные skill-поверхности Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check для настроенных агентских хостов
|
|
202
246
|
- метаданные области ветки
|
|
203
247
|
- диагностика конфигурации, полномочий, маршрутизации, структуры решений, frontmatter, ссылок и полиглотного покрытия
|
|
204
248
|
|