truthmark 1.4.0 → 1.6.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.
- package/README.de.md +672 -194
- package/README.es.md +673 -195
- package/README.md +663 -192
- package/README.ru.md +680 -202
- package/README.zh.md +679 -199
- package/dist/main.js +1307 -145
- package/dist/main.js.map +1 -1
- package/package.json +1 -2
package/README.ru.md
CHANGED
|
@@ -1,294 +1,687 @@
|
|
|
1
1
|
# Truthmark
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Ваши агенты пишут код. Truthmark делает их контекст проверяемым в Git.**
|
|
4
4
|
|
|
5
5
|
[English](README.md) | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | Русский
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
|
|
8
8
|
|
|
9
|
-
ИИ-агенты
|
|
9
|
+
ИИ-агенты для разработки могут менять репозиторий быстрее, чем люди успевают выравнивать его контекст.
|
|
10
10
|
|
|
11
|
-
Truthmark
|
|
11
|
+
Truthmark чинит ту часть, которая обычно ломается после написания кода: истину репозитория.
|
|
12
12
|
|
|
13
|
-
-
|
|
14
|
-
- запускаются релевантные тесты
|
|
15
|
-
- установленный рабочий процесс Truth Sync обновляет связанные документы истины до завершения работы агента
|
|
16
|
-
- если был создан diff документов истины, его проверяют
|
|
13
|
+
Он устанавливает Git-native, ограниченный веткой слой рабочего процесса, который помогает ИИ-агентам обновлять правильные документы, соблюдать границы владения и оставлять людям обычные diff для ревью.
|
|
17
14
|
|
|
18
|
-
|
|
15
|
+
Без размещенного сервиса.
|
|
19
16
|
|
|
20
|
-
|
|
17
|
+
Без базы данных.
|
|
21
18
|
|
|
22
|
-
|
|
19
|
+
Без скрытого слоя памяти.
|
|
23
20
|
|
|
24
|
-
|
|
21
|
+
Без дополнительного сервера в эксплуатации.
|
|
25
22
|
|
|
26
|
-
|
|
23
|
+
Только истина репозитория, которая движется вместе с веткой.
|
|
27
24
|
|
|
28
|
-
|
|
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.
|
|
59
|
-
- Модель маршрутизации не зависит от языка и дает диагностику покрытия для распространенных поверхностей кода JavaScript, TypeScript, Go, Python, C# и Java.
|
|
60
|
-
|
|
61
|
-
Для технических лидеров ценность в управлении без дополнительной инфраструктуры: тесты, ревью кода и владение зонами ответственности по-прежнему делают основную работу; Truthmark делает контекст агента долговечным, проверяемым и ограниченным веткой.
|
|
25
|
+
## Проблема
|
|
62
26
|
|
|
63
|
-
|
|
27
|
+
ИИ-агенты для разработки хорошо создают код. Это порождает новый режим отказа.
|
|
28
|
+
|
|
29
|
+
Реализация меняется, но история репозитория начинает расходиться:
|
|
30
|
+
|
|
31
|
+
- поведение живет в истории чата
|
|
32
|
+
- архитектурные документы отстают
|
|
33
|
+
- продуктовые решения исчезают после передачи работы
|
|
34
|
+
- ревьюеры видят diff кода без связанных diff истины
|
|
35
|
+
- ветки незаметно развивают разные версии того, «что является правдой»
|
|
36
|
+
- каждой сессии агента приходится заново открывать контекст
|
|
37
|
+
|
|
38
|
+
Truthmark превращает этот хрупкий контекст в зафиксированную инфраструктуру репозитория.
|
|
64
39
|
|
|
65
|
-
|
|
40
|
+
Вместо надежды на то, что каждый человек и каждый агент вспомнят правильную привычку документирования, Truthmark устанавливает эту привычку в репозиторий.
|
|
66
41
|
|
|
67
|
-
|
|
68
|
-
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
|
|
69
|
-
| Лучшие результаты в одной сессии разработки | Более точные промпты и лучше очерченная задача |
|
|
70
|
-
| Удобная преемственность между сессиями для одного агента или оператора | Инструменты памяти |
|
|
71
|
-
| Spec-first планирование новых функций | Инструменты спецификаций, например Spec Kit |
|
|
72
|
-
| Проверяемая истина репозитория с областью действия в пределах ветки, которая идет вместе с кодом | Truthmark |
|
|
42
|
+
## Обещание
|
|
73
43
|
|
|
74
|
-
|
|
44
|
+
Когда агент меняет функциональный код, работа не должна заканчиваться только diff кода.
|
|
75
45
|
|
|
76
|
-
|
|
46
|
+
Обычный путь Truthmark:
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
агент меняет функциональный код
|
|
50
|
+
запускаются релевантные тесты
|
|
51
|
+
Truth Sync проверяет сопоставленные документы истины
|
|
52
|
+
документы истины обновляются при необходимости
|
|
53
|
+
человек проверяет diff кода + diff истины
|
|
54
|
+
коммит или передача работы
|
|
55
|
+
```
|
|
77
56
|
|
|
78
|
-
|
|
79
|
-
- [Что решает Truthmark](#что-решает-truthmark)
|
|
80
|
-
- [Где уместен Truthmark](#где-уместен-truthmark)
|
|
81
|
-
- [Начало работы](#начало-работы)
|
|
82
|
-
- [Как он работает](#как-он-работает)
|
|
83
|
-
- [Что он устанавливает](#что-он-устанавливает)
|
|
84
|
-
- [Команды](#команды)
|
|
85
|
-
- [Зачем он существует](#зачем-он-существует)
|
|
86
|
-
- [Статус проекта](#статус-проекта)
|
|
87
|
-
- [Документация](#документация)
|
|
88
|
-
- [Не-цели](#не-цели)
|
|
89
|
-
- [Лицензия](#лицензия)
|
|
57
|
+
Главная ценность такова: **ИИ-работе легче доверять, потому что репозиторий остается понятным.**
|
|
90
58
|
|
|
91
|
-
##
|
|
59
|
+
## Две поверхности, одна система истины
|
|
92
60
|
|
|
93
|
-
Truthmark
|
|
61
|
+
Truthmark — это не только CLI.
|
|
94
62
|
|
|
95
|
-
|
|
96
|
-
- `docs/truthmark/areas.md` и делегированные дочерние файлы маршрутов сопоставляют области кода с документами, которые за них отвечают.
|
|
97
|
-
- Truth Document создает или исправляет канонические документы истины для уже реализованного поведения, когда изменение кода не нужно.
|
|
98
|
-
- Truth Sync поддерживает синхронизацию сопоставленных документов истины при функциональных изменениях.
|
|
99
|
-
- Truth Preview предварительно показывает вероятную маршрутизацию рабочего процесса до правок, не авторизуя записи.
|
|
100
|
-
- Truth Realize дает изменениям, начинающимся с документации, ограниченный путь для обновления кода.
|
|
101
|
-
- `truthmark check` валидирует получившиеся артефакты истины.
|
|
102
|
-
- Вся модель остается local-first и Git-native.
|
|
63
|
+
У него две разные поверхности, и это различие важно.
|
|
103
64
|
|
|
104
|
-
|
|
65
|
+
### 1. CLI для людей
|
|
105
66
|
|
|
106
|
-
|
|
67
|
+
CLI предназначен для мейнтейнеров, ревьюеров и автоматизации.
|
|
107
68
|
|
|
108
|
-
|
|
69
|
+
Используйте его, чтобы настроить репозиторий, установить или обновить файлы рабочих процессов, проверить артефакты истины и создать дополнительный контекст для ревью.
|
|
109
70
|
|
|
110
71
|
```bash
|
|
111
|
-
cd /path/to/your-repo
|
|
112
|
-
npm install -g truthmark
|
|
113
72
|
truthmark config
|
|
114
73
|
truthmark init
|
|
115
74
|
truthmark check
|
|
116
75
|
```
|
|
117
76
|
|
|
118
|
-
|
|
77
|
+
CLI подготавливает и валидирует среду репозитория.
|
|
78
|
+
|
|
79
|
+
Он не является runtime для ИИ-рабочего процесса.
|
|
80
|
+
|
|
81
|
+
### 2. Поверхности рабочих процессов для ИИ
|
|
82
|
+
|
|
83
|
+
Поверхности для ИИ предназначены для coding agents.
|
|
84
|
+
|
|
85
|
+
Truthmark устанавливает host-native skills, prompts, commands, управляемые блоки инструкций и поддерживаемые поверхности subagents, чтобы ИИ-агенты могли следовать специфичным для репозитория truth-workflows внутри своих обычных инструментов разработки.
|
|
86
|
+
|
|
87
|
+
Примеры:
|
|
88
|
+
|
|
89
|
+
```text
|
|
90
|
+
/truthmark-sync
|
|
91
|
+
/truthmark-document
|
|
92
|
+
/truthmark-structure
|
|
93
|
+
/truthmark-realize
|
|
94
|
+
/truthmark-preview
|
|
95
|
+
/truthmark-check
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Они выглядят как команды, потому что agent hosts раскрывают workflows через slash commands, prompts, skills или project commands.
|
|
99
|
+
|
|
100
|
+
Это не shell-команды.
|
|
101
|
+
|
|
102
|
+
Это точки входа workflow для ИИ.
|
|
103
|
+
|
|
104
|
+
Разделение и есть продукт:
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
люди владеют контрактом репозитория
|
|
108
|
+
Truthmark устанавливает контракт в repo
|
|
109
|
+
агенты работают внутри этого контракта
|
|
110
|
+
обновления истины появляются как Git diff
|
|
111
|
+
люди проверяют результат
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Быстрый старт
|
|
115
|
+
|
|
116
|
+
### Требования
|
|
117
|
+
|
|
118
|
+
- Node.js `>=20`
|
|
119
|
+
- npm
|
|
120
|
+
- Git-репозиторий
|
|
121
|
+
|
|
122
|
+
### Установить Truthmark
|
|
123
|
+
|
|
124
|
+
Выполните это внутри репозитория, который хотите инициализировать:
|
|
119
125
|
|
|
120
126
|
```bash
|
|
121
|
-
cd /path/to/truthmark
|
|
122
|
-
npm install
|
|
123
|
-
npm run build
|
|
124
127
|
cd /path/to/your-repo
|
|
125
|
-
|
|
126
|
-
node /path/to/truthmark/dist/main.js init
|
|
127
|
-
node /path/to/truthmark/dist/main.js check
|
|
128
|
+
npm install -g truthmark
|
|
128
129
|
```
|
|
129
130
|
|
|
130
|
-
|
|
131
|
+
### Создать контракт истины репозитория
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
truthmark config
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Это создает:
|
|
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
|
-
|
|
146
|
-
Стандартная шаблонная структура использует truth-`README.md` как индексы и начинает описывать истину текущего поведения в ограниченных листовых документах, например `docs/truth/repository/overview.md`.
|
|
143
|
+
Проверьте этот файл перед продолжением. Он определяет зафиксированный контракт иерархии для репозитория.
|
|
147
144
|
|
|
148
|
-
|
|
145
|
+
### Установить поверхности рабочих процессов
|
|
149
146
|
|
|
150
|
-
|
|
147
|
+
```bash
|
|
148
|
+
truthmark init
|
|
149
|
+
```
|
|
151
150
|
|
|
152
|
-
|
|
151
|
+
Это устанавливает или обновляет:
|
|
153
152
|
|
|
154
|
-
|
|
153
|
+
- файлы маршрутов
|
|
154
|
+
- scaffolding документов истины
|
|
155
|
+
- управляемые блоки инструкций
|
|
156
|
+
- поверхности рабочих процессов для ИИ для настроенных платформ
|
|
155
157
|
|
|
156
|
-
|
|
158
|
+
### Проверить настройку
|
|
157
159
|
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
пользователь явно вызывает truth document
|
|
161
|
-
агент читает реализацию, тесты, маршрутизацию и существующие docs
|
|
162
|
-
агент пишет только truth docs и маршрутизацию
|
|
163
|
-
проверить diff truth docs
|
|
160
|
+
```bash
|
|
161
|
+
truthmark check
|
|
164
162
|
```
|
|
165
163
|
|
|
166
|
-
|
|
164
|
+
Затем проверьте сгенерированные файлы перед коммитом.
|
|
165
|
+
|
|
166
|
+
Точный набор файлов зависит от `.truthmark/config.yml`, но форма установки всегда одна: routing, truth scaffolding, компактные managed instructions и host-native workflow surfaces для включённых платформ.
|
|
167
|
+
|
|
168
|
+
## Первое реальное использование
|
|
169
|
+
|
|
170
|
+
Большинству репозиториев после инициализации нужен один этап очистки.
|
|
171
|
+
|
|
172
|
+
Стандартный scaffold начинается с широкого area `repository`. Реальным репозиториям обычно нужна более точная маршрутизация.
|
|
173
|
+
|
|
174
|
+
Попросите агента разделить широкий маршрут на реальные области продукта, сервиса, домена или владения:
|
|
167
175
|
|
|
168
176
|
```text
|
|
169
|
-
/truthmark-
|
|
177
|
+
/truthmark-structure раздели широкий repository area на auth, billing и notifications
|
|
170
178
|
```
|
|
171
179
|
|
|
172
|
-
|
|
180
|
+
После этого используйте своего ИИ-агента для разработки как обычно.
|
|
181
|
+
|
|
182
|
+
Когда агент меняет функциональный код, Truth Sync действует как финальная защита, которая перед передачей работы проверяет, должны ли измениться сопоставленные документы истины.
|
|
183
|
+
|
|
184
|
+
## Что вы получаете
|
|
185
|
+
|
|
186
|
+
| Возможность | Что она делает |
|
|
187
|
+
| --- | --- |
|
|
188
|
+
| Git-native истина | Хранит истину репозитория в зафиксированных Markdown и config. |
|
|
189
|
+
| Контекст в пределах ветки | Истина движется с веткой вместо жизни в приватной сессии. |
|
|
190
|
+
| CLI для людей | Дает мейнтейнерам команды настройки, обновления, валидации и инспекции. |
|
|
191
|
+
| Workflows для ИИ | Дает агентам host-native workflows для sync, documentation, structure, preview, realization и audit. |
|
|
192
|
+
| Явная маршрутизация | Сопоставляет области кода с каноническими документами истины. |
|
|
193
|
+
| Проверяемые передачи работы | Создает обычные Git diff для кода и документов истины. |
|
|
194
|
+
| Local-first работа | Не требует размещенного сервиса, daemon, базы данных или MCP-сервера. |
|
|
195
|
+
| Более безопасные границы записи | Разделяет code-first, doc-first, read-only и doc-only workflows. |
|
|
196
|
+
| Валидация | Сообщает о проблемах маршрутизации, authority, frontmatter, ссылок, generated surfaces, branch scope, freshness и coverage. |
|
|
197
|
+
| Опциональный Portal | Генерирует зафиксированный статический HTML-сайт презентации из Markdown-документов истины, когда он явно включен и запрошен. |
|
|
198
|
+
|
|
199
|
+
## Визуальный обзор
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
**Возможности:** что устанавливает Truthmark и как разделена поверхность workflow.
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
**Позиция:** где Truthmark находится относительно prompts, memory и spec workflows.
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
**Поток sync:** как Truth Sync закрывает обычные изменения кода перед передачей.
|
|
212
|
+
|
|
213
|
+
## Почему команды выбирают его
|
|
214
|
+
|
|
215
|
+
Truthmark предназначен для команд, которые уже знают, что ИИ-агенты могут генерировать код.
|
|
216
|
+
|
|
217
|
+
Следующая проблема — governance.
|
|
218
|
+
|
|
219
|
+
Не governance как церемония. Governance как простой вопрос:
|
|
220
|
+
|
|
221
|
+
> После этого ИИ-ассистированного изменения репозиторий все еще говорит правду?
|
|
222
|
+
|
|
223
|
+
Truthmark помогает командам отвечать на это с помощью зафиксированных файлов, явной маршрутизации и проверяемых diff.
|
|
224
|
+
|
|
225
|
+
Он полезен, когда нужны:
|
|
226
|
+
|
|
227
|
+
- меньший дрейф документации
|
|
228
|
+
- лучшие передачи работы
|
|
229
|
+
- продуктовая истина, специфичная для ветки
|
|
230
|
+
- долговечный архитектурный и API-контекст
|
|
231
|
+
- явное владение между документацией и кодом
|
|
232
|
+
- более безопасные границы записи для агентов
|
|
233
|
+
- проверяемый контекст вместо скрытой памяти
|
|
234
|
+
- ИИ-workflows, которые продолжают работать из зафиксированных файлов repo
|
|
235
|
+
|
|
236
|
+
## Где уместен Truthmark
|
|
237
|
+
|
|
238
|
+
Truthmark не заменяет prompts, memory, specs, tests или code review.
|
|
239
|
+
|
|
240
|
+
Он дает этим workflows долговечное место в Git.
|
|
173
241
|
|
|
174
|
-
|
|
242
|
+
| Потребность | Лучше подходит |
|
|
243
|
+
| --- | --- |
|
|
244
|
+
| Лучший результат из одной сессии агента | Лучший prompt |
|
|
245
|
+
| Персональная или сессионная преемственность | Memory tool |
|
|
246
|
+
| Работа над функцией plan-first | Spec workflow |
|
|
247
|
+
| Истина в пределах ветки, которая путешествует с кодом | Truthmark |
|
|
248
|
+
| Проверка корректности поведения | Tests and review |
|
|
249
|
+
| Ревью контекстных изменений, выполненных с ИИ | Truthmark plus Git review |
|
|
250
|
+
|
|
251
|
+
Область Truthmark намеренно узкая:
|
|
175
252
|
|
|
176
253
|
```text
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
254
|
+
сделать истину репозитория явной
|
|
255
|
+
связать ее с кодом
|
|
256
|
+
установить вокруг нее workflows агентов
|
|
257
|
+
сохранить результат проверяемым в Git
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
## Как работает Truthmark
|
|
261
|
+
|
|
262
|
+
Truthmark работает локально с активным Git worktree.
|
|
263
|
+
|
|
264
|
+
CLI для людей читает и записывает файлы репозитория, а затем завершается.
|
|
265
|
+
|
|
266
|
+
Поверхности рабочих процессов для ИИ — это зафиксированные файлы, которые agent hosts могут загрузить позже. Поэтому агенты могут следовать установленному workflow из состояния репозитория, не завися от фонового процесса Truthmark.
|
|
267
|
+
|
|
268
|
+
Эти слои связаны так:
|
|
269
|
+
|
|
270
|
+
```mermaid
|
|
271
|
+
flowchart LR
|
|
272
|
+
Human["Human / CI"] --> CLI["Truthmark CLI"]
|
|
273
|
+
CLI --> Config["Config и routing"]
|
|
274
|
+
CLI --> Truth["Канонические truth docs"]
|
|
275
|
+
CLI --> Surfaces["Сгенерированные host-native workflows"]
|
|
276
|
+
Surfaces --> Hosts["Codex / Claude Code / Copilot / OpenCode / Gemini"]
|
|
277
|
+
Hosts --> Worktree["Активный Git worktree"]
|
|
278
|
+
Hosts -->|"helper checks / validate / index"| CLI
|
|
279
|
+
Worktree --> Truth
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
Agents не подключаются к daemon Truthmark, но могут запускать установленный Truthmark CLI, когда workflow требует validation, indexing или helper checks.
|
|
283
|
+
|
|
284
|
+
Truthmark владеет сгенерированными workflow surfaces, но главный контракт архитектурный: repo-local config и routing направляют agents к каноническим truth docs, а host-native workflows дают каждому поддерживаемому agent способ выполнять одни и те же процедуры Truthmark.
|
|
285
|
+
|
|
286
|
+
Сгенерированные поверхности workflow включают маркеры версии Truthmark. После обновления Truthmark снова выполните:
|
|
287
|
+
|
|
288
|
+
```bash
|
|
289
|
+
truthmark init
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
Затем проверьте сгенерированные diff.
|
|
293
|
+
|
|
294
|
+
## Поддерживаемые платформы агентов
|
|
295
|
+
|
|
296
|
+
Конфигурация по умолчанию включает все поддерживаемые платформы.
|
|
297
|
+
|
|
298
|
+
Удалите платформы, которыми не пользуетесь, из `.truthmark/config.yml`, затем снова выполните:
|
|
299
|
+
|
|
300
|
+
```bash
|
|
301
|
+
truthmark init
|
|
182
302
|
```
|
|
183
303
|
|
|
184
|
-
|
|
304
|
+
| Имя платформы в config | Сгенерированная поверхность | Форма вызова |
|
|
305
|
+
| --- | --- | --- |
|
|
306
|
+
| `codex` | `.codex/skills/truthmark-*/`, `.codex/agents/` | `/truthmark-*` или `$truthmark-*` |
|
|
307
|
+
| `claude-code` | `.claude/skills/truthmark-*/`, `.claude/agents/`, `CLAUDE.md` | `/truthmark-*` |
|
|
308
|
+
| `github-copilot` | `.github/skills/truthmark-*/`, `.github/prompts/`, `.github/agents/`, `.github/copilot-instructions.md` | `/truthmark-*` в поддерживаемых Copilot IDE; custom agents `@truth-*` в Copilot CLI |
|
|
309
|
+
| `opencode` | `.opencode/skills/truthmark-*/`, `.opencode/agents/` | `/skill truthmark-*` |
|
|
310
|
+
| `gemini-cli` | `.gemini/skills/truthmark-*/`, `.gemini/commands/truthmark/`, `.gemini/agents/`, `GEMINI.md` | `/truthmark:*` |
|
|
311
|
+
|
|
312
|
+
Неизвестные имена платформ являются ошибками config.
|
|
313
|
+
|
|
314
|
+
Удаление платформы останавливает будущие обновления для нее. Оно не удаляет ранее сгенерированные файлы.
|
|
315
|
+
|
|
316
|
+
## Workflows для ИИ
|
|
317
|
+
|
|
318
|
+
Эти workflows устанавливаются в поддерживаемые ИИ coding hosts.
|
|
319
|
+
|
|
320
|
+
Они используются агентами или agent hosts во время работы с репозиторием. Это не shell-команды верхнего уровня.
|
|
321
|
+
|
|
322
|
+
| Workflow | Направление | Когда использовать | Граница записи |
|
|
323
|
+
| --- | --- | --- | --- |
|
|
324
|
+
| Truth Structure | topology-first | Стандартный маршрут слишком широкий, владение охватывает несколько областей или файлы маршрутов все еще указывают на placeholders. | Создает или чинит routing и стартовые документы истины. |
|
|
325
|
+
| Truth Document | implementation-first | Поведение уже есть в коде, но канонические документы истины отсутствуют или слабы. | Пишет только документы истины и routing. Функциональный код менять нельзя. |
|
|
326
|
+
| Truth Sync | code-first | Функциональный код изменился, и сопоставленные документы истины могут потребовать обновления перед передачей. | Обновляет документы истины. Truth Sync не должен переписывать функциональный код. |
|
|
327
|
+
| Truth Preview | read-only | Агенту нужно предварительно понять вероятный routing перед правками. | Только чтение. Не авторизует записи. |
|
|
328
|
+
| Truth Realize | doc-first | Продуктовые или архитектурные документы истины ведут, и код нужно обновить под них. | Обновляет только код. Агент не должен редактировать документы истины, которые реализует. |
|
|
329
|
+
| Truth Check | audit-first | Ревьюеру или агенту нужно проверить здоровье истины репозитория. | Аудитирует и сообщает. |
|
|
330
|
+
| Truthmark Portal | presentation-only | Человек явно просит доступный для просмотра статический HTML Portal по документам истины репозитория. | Пишет только сгенерированные неканонические статические файлы в настроенную директорию вывода Portal. |
|
|
331
|
+
|
|
332
|
+
### Важное различие
|
|
333
|
+
|
|
334
|
+
Не путайте эти две поверхности:
|
|
335
|
+
|
|
336
|
+
| Поверхность | Используется | Пример | Значение |
|
|
337
|
+
| --- | --- | --- | --- |
|
|
338
|
+
| CLI для людей | людьми, скриптами, CI-подобными проверками | `truthmark check` | Проверить артефакты истины репозитория из терминала. |
|
|
339
|
+
| Workflow для ИИ | coding agents и agent hosts | `/truthmark-check` | Попросить агента выполнить установленный audit workflow. |
|
|
185
340
|
|
|
186
|
-
|
|
341
|
+
Имена намеренно похожи, но поверхности разные.
|
|
342
|
+
|
|
343
|
+
## Обычное изменение кода с помощью ИИ
|
|
344
|
+
|
|
345
|
+
Большинству пользователей не нужно вручную вызывать Truth Sync каждый раз.
|
|
346
|
+
|
|
347
|
+
Truth Sync — установленная финальная защита для изменений функционального кода.
|
|
348
|
+
|
|
349
|
+
```text
|
|
350
|
+
агент меняет функциональный код
|
|
351
|
+
агент запускает или запрашивает релевантные тесты
|
|
352
|
+
установленный workflow обнаруживает, что функциональный код изменился
|
|
353
|
+
Truth Sync проверяет сопоставленные документы истины
|
|
354
|
+
агент обновляет документы истины при необходимости
|
|
355
|
+
человек проверяет diff кода + diff истины
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
Прямой вызов все равно полезен для отладки, принудительной ранней синхронизации или явной передачи работы:
|
|
187
359
|
|
|
188
360
|
```text
|
|
189
361
|
/truthmark-sync синхронизируй истину репозитория прямо сейчас перед передачей
|
|
190
362
|
```
|
|
191
363
|
|
|
192
|
-
|
|
364
|
+
## Существующее поведение без docs
|
|
193
365
|
|
|
194
|
-
Используйте
|
|
366
|
+
Используйте Truth Document, когда реализация уже существует, но истина репозитория неполна.
|
|
195
367
|
|
|
196
368
|
```text
|
|
197
|
-
|
|
198
|
-
пользователь явно вызывает truth realize
|
|
199
|
-
агент читает truth docs и связанный код
|
|
200
|
-
агент обновляет только код
|
|
201
|
-
запускаются релевантные тесты
|
|
202
|
-
работа коммитится или передается дальше
|
|
369
|
+
/truthmark-document задокументируй реализованное поведение session timeout в docs/truth/authentication
|
|
203
370
|
```
|
|
204
371
|
|
|
205
|
-
Truth
|
|
372
|
+
Truth Document проверяет реализацию, тесты, файлы маршрутов и существующие docs как evidence.
|
|
373
|
+
|
|
374
|
+
Он пишет только документы истины и routing.
|
|
206
375
|
|
|
207
|
-
|
|
376
|
+
Он не должен менять функциональный код.
|
|
377
|
+
|
|
378
|
+
## Doc-first изменения
|
|
379
|
+
|
|
380
|
+
Используйте Truth Realize, когда продуктовое или архитектурное решение начинается в docs и код нужно обновить под него.
|
|
208
381
|
|
|
209
382
|
```text
|
|
210
|
-
/truthmark-realize реализуй docs/truth/authentication/session-timeout.md в
|
|
383
|
+
/truthmark-realize реализуй docs/truth/authentication/session-timeout.md в коде
|
|
211
384
|
```
|
|
212
385
|
|
|
213
|
-
|
|
386
|
+
Truth Realize работает doc-first.
|
|
214
387
|
|
|
215
|
-
|
|
388
|
+
Документы истины ведут. Код следует.
|
|
216
389
|
|
|
217
|
-
|
|
390
|
+
Агент не должен редактировать документы истины, которые реализует.
|
|
218
391
|
|
|
219
|
-
-
|
|
220
|
-
- агентские рабочие поверхности, которые вызывают coding agents или агентские хосты во время реализации; это не дополнительные ежедневные терминальные команды для людей
|
|
392
|
+
## Read-only preview маршрутизации
|
|
221
393
|
|
|
222
|
-
|
|
223
|
-
- `docs/truthmark/areas.md` для корневого индекса маршрутов
|
|
224
|
-
- `docs/truthmark/areas/**/*.md` для делегированных дочерних файлов маршрутов
|
|
225
|
-
- `docs/templates/behavior-doc.md` и другие шаблоны по видам под `docs/templates/` для редактируемых стандартов truth docs, используемых сгенерированными рабочими процессами
|
|
226
|
-
- управляемые блоки инструкций для настроенных платформ, таких как `AGENTS.md`, `CLAUDE.md`, инструкции Copilot и `GEMINI.md`
|
|
227
|
-
- нативные для хоста skills, prompts или commands для Truth Structure, Truth Document, Truth Sync, Truth Preview, Truth Realize и Truth Check
|
|
228
|
-
- проектные проверяющие агенты Codex, Claude Code, GitHub Copilot и OpenCode в режиме только чтения, а также leased-агенты `truth-doc-writer` там, где хост поддерживает агентов, под `.codex/agents/`, `.claude/agents/`, `.github/agents/` и `.opencode/agents/` для аудитов, которыми владеет рабочий процесс, и для документных шардов, выданных родительским агентом
|
|
394
|
+
Используйте Truth Preview перед изменением, когда агенту нужно понять вероятную маршрутизацию.
|
|
229
395
|
|
|
230
|
-
|
|
396
|
+
```text
|
|
397
|
+
/truthmark-preview покажи вероятный truth routing для изменений billing API
|
|
398
|
+
```
|
|
231
399
|
|
|
232
|
-
|
|
233
|
-
- Truth Document создает или исправляет документы истины для уже реализованного поведения.
|
|
234
|
-
- Truth Sync поддерживает синхронизацию сопоставленных документов истины с функциональными изменениями.
|
|
235
|
-
- Truth Preview предварительно показывает вероятную маршрутизацию рабочего процесса до правок без записи файлов.
|
|
236
|
-
- Truth Realize обновляет код так, чтобы он соответствовал документам истины.
|
|
237
|
-
- Truth Check аудитирует здоровье истины репозитория.
|
|
400
|
+
Truth Preview работает read-only.
|
|
238
401
|
|
|
239
|
-
|
|
402
|
+
Это средство выбора и планирования, а не авторизация записи и не замена Truth Check.
|
|
240
403
|
|
|
241
|
-
|
|
404
|
+
## Аудит истины репозитория
|
|
242
405
|
|
|
243
|
-
|
|
406
|
+
Используйте Truth Check, когда нужен audit workflow для агента.
|
|
244
407
|
|
|
245
|
-
|
|
408
|
+
```text
|
|
409
|
+
/truthmark-check проверь routing и truth coverage перед review
|
|
410
|
+
```
|
|
246
411
|
|
|
247
|
-
|
|
248
|
-
| --------------------- | ---------- |
|
|
249
|
-
| `truthmark config` | Создает `.truthmark/config.yml`; пишет только этот файл, если не используется `--stdout`. |
|
|
250
|
-
| `truthmark init` | Устанавливает или обновляет локальные файлы рабочих процессов из проверенной конфигурации. |
|
|
251
|
-
| `truthmark check` | Валидирует конфигурацию, полномочия, маршрутизацию, документы с решениями, frontmatter, внутренние ссылки, область действия ветки и диагностику покрытия. |
|
|
412
|
+
Используйте CLI для людей, когда нужна terminal validation:
|
|
252
413
|
|
|
253
|
-
|
|
414
|
+
```bash
|
|
415
|
+
truthmark check
|
|
416
|
+
```
|
|
254
417
|
|
|
255
|
-
|
|
256
|
-
|
|
418
|
+
Оба варианта полезны. Это не одна и та же поверхность.
|
|
419
|
+
|
|
420
|
+
## CLI-команды для людей
|
|
421
|
+
|
|
422
|
+
Большинство мейнтейнеров начинают с трех команд.
|
|
423
|
+
|
|
424
|
+
| Команда | Назначение |
|
|
425
|
+
| --- | --- |
|
|
426
|
+
| `truthmark config` | Создает `.truthmark/config.yml`. Пишет только этот файл, если не используется `--stdout`. |
|
|
427
|
+
| `truthmark init` | Устанавливает или обновляет настроенные поверхности workflow из проверенной config. |
|
|
428
|
+
| `truthmark check` | Валидирует config, authority, routing, документы с decisions, frontmatter, внутренние ссылки, branch scope, generated surfaces, freshness и coverage diagnostics. |
|
|
429
|
+
|
|
430
|
+
Необязательные helpers repository-intelligence создают производный review context для активного checkout. Сгенерированные workflow skill packages также могут предоставлять helper manifests и helper policies, которые вызывают установленные CLI validators `truthmark validate ... --json`; эти helpers являются ускорителями, а не локальными скриптами, упакованными в репозиторий, и не источниками истины. Отдельные Copilot prompts и Gemini commands используют тот же CLI validator contract, когда установленный runner доступен; иначе они должны сообщать видимый skipped helper status и выполнять manual validation.
|
|
431
|
+
|
|
432
|
+
Они не являются источниками истины.
|
|
433
|
+
|
|
434
|
+
| Команда | Назначение |
|
|
435
|
+
| --- | --- |
|
|
257
436
|
| `truthmark index` | Строит JSON RepoIndex и RouteMap для активного checkout. |
|
|
258
437
|
| `truthmark impact --base <ref>` | Сопоставляет измененные файлы с routed truth docs, owning routes, nearby tests и public symbols. |
|
|
259
|
-
| `truthmark context --workflow <workflow> [--base <ref>]` | Генерирует ограниченный ContextPack для Truth Sync, Truth Document или Truth Realize. `--format markdown`
|
|
438
|
+
| `truthmark context --workflow <workflow> [--base <ref>]` | Генерирует ограниченный ContextPack для Truth Sync, Truth Document или Truth Realize. Используйте `--format markdown` для человекочитаемой версии. |
|
|
439
|
+
|
|
440
|
+
Структурированный вывод доступен с `--json` там, где поддерживается.
|
|
441
|
+
|
|
442
|
+
## Truthmark Portal
|
|
443
|
+
|
|
444
|
+
Truthmark Portal — опциональный презентационный workflow для команд, которым нужен человекочитаемый сайт поверх зафиксированных документов истины.
|
|
445
|
+
|
|
446
|
+
Он намеренно отделен от основного workflow истины:
|
|
447
|
+
|
|
448
|
+
- Markdown-документы истины остаются каноническими.
|
|
449
|
+
- Сгенерированный HTML Portal предназначен только для презентации.
|
|
450
|
+
- Portal запускается только вручную; он не выполняется как completion gate, шаг Truth Sync, шаг `truthmark check` или автоматический post-change hook.
|
|
451
|
+
- Записи Portal остаются внутри настроенной директории вывода, если пользователь явно не меняет scope.
|
|
452
|
+
- Сгенерированные страницы должны использовать локальные assets, provenance источников и видимое уведомление, что Markdown является каноническим источником.
|
|
453
|
+
|
|
454
|
+
Включите его namespaced config-блоком:
|
|
455
|
+
|
|
456
|
+
```yaml
|
|
457
|
+
truthmark-portal:
|
|
458
|
+
enabled: true
|
|
459
|
+
output: docs/truthmark-portal
|
|
460
|
+
template: default
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
Затем запустите снова:
|
|
464
|
+
|
|
465
|
+
```bash
|
|
466
|
+
truthmark init
|
|
467
|
+
```
|
|
260
468
|
|
|
261
|
-
|
|
469
|
+
Когда Portal включен, Truthmark устанавливает host-native Portal workflow surfaces для настроенных платформ, например `/truthmark-portal` или `/truthmark:portal` в зависимости от agent host.
|
|
262
470
|
|
|
263
|
-
|
|
471
|
+
## Конфигурация
|
|
264
472
|
|
|
265
|
-
|
|
473
|
+
Truthmark работает config-first.
|
|
266
474
|
|
|
267
|
-
|
|
475
|
+
Главный config-файл:
|
|
268
476
|
|
|
269
477
|
```text
|
|
270
|
-
/
|
|
478
|
+
.truthmark/config.yml
|
|
271
479
|
```
|
|
272
480
|
|
|
273
|
-
|
|
481
|
+
Новые репозитории должны выполнить:
|
|
274
482
|
|
|
275
|
-
|
|
276
|
-
|
|
483
|
+
```bash
|
|
484
|
+
truthmark config
|
|
485
|
+
```
|
|
277
486
|
|
|
278
|
-
|
|
279
|
-
- долговечные архитектурные и API-решения
|
|
280
|
-
- явная ответственность между документацией и кодом
|
|
281
|
-
- безопасные границы записи для агентов
|
|
282
|
-
- обычные Git diff, которые могут проверить люди
|
|
283
|
-
- читаемый Markdown, который команда может просматривать без специальных инструментов
|
|
284
|
-
- истина, которая путешествует вместе с веткой, а не живет в скрытом состоянии сессии
|
|
285
|
-
- рабочие процессы, которые продолжают работать, даже если пакет не установлен глобально
|
|
487
|
+
Затем проверить сгенерированную config перед запуском:
|
|
286
488
|
|
|
287
|
-
|
|
489
|
+
```bash
|
|
490
|
+
truthmark init
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
Важные области config:
|
|
494
|
+
|
|
495
|
+
| Область config | Назначение |
|
|
496
|
+
| --- | --- |
|
|
497
|
+
| `version` | Версия контракта config. |
|
|
498
|
+
| `platforms` | Agent hosts, которые должны получить сгенерированные поверхности для платформы. |
|
|
499
|
+
| `docs.layout` | Текущий режим layout документации. |
|
|
500
|
+
| `docs.roots` | Именованные корни канонической документации. |
|
|
501
|
+
| `docs.routing.root_index` | Путь к корневому индексу маршрутов. |
|
|
502
|
+
| `docs.routing.area_files_root` | Директория для делегированных дочерних файлов маршрутов. |
|
|
503
|
+
| `docs.routing.default_area` | Базовое имя начального scaffolded дочернего маршрута. |
|
|
504
|
+
| `docs.routing.max_delegation_depth` | Текущая максимальная глубина делегирования routing. |
|
|
505
|
+
| `truthmark-portal` | Опциональные настройки ручного презентационного workflow: `enabled`, `output` и `template`. |
|
|
506
|
+
| `authority` | Упорядоченные канонические docs и globs, используемые как authority истины репозитория. |
|
|
507
|
+
| `instruction_targets` | Файлы, которые получают общие управляемые блоки инструкций, например `AGENTS.md`. |
|
|
508
|
+
| `frontmatter.required` | Поля metadata, которые создают error diagnostics при отсутствии. |
|
|
509
|
+
| `frontmatter.recommended` | Поля metadata, которые создают review diagnostics при отсутствии. |
|
|
510
|
+
| `ignore` | Glob-паттерны, исключенные из релевантных checks и routing logic. |
|
|
511
|
+
|
|
512
|
+
## Маршрутизация истины репозитория
|
|
513
|
+
|
|
514
|
+
Truthmark сопоставляет code surfaces с документами истины.
|
|
515
|
+
|
|
516
|
+
Основные файлы маршрутизации:
|
|
517
|
+
|
|
518
|
+
```text
|
|
519
|
+
docs/truthmark/areas.md
|
|
520
|
+
docs/truthmark/areas/**/*.md
|
|
521
|
+
```
|
|
522
|
+
|
|
523
|
+
Маршрут сообщает агенту:
|
|
524
|
+
|
|
525
|
+
- какая code surface принадлежит области
|
|
526
|
+
- какие документы истины владеют этой областью
|
|
527
|
+
- когда истину нужно обновлять
|
|
528
|
+
- какой тип документа истины участвует
|
|
529
|
+
|
|
530
|
+
Стандартный scaffold начинается широко. Существующие репозитории обычно должны разделить стандартный маршрут на реальные области владения.
|
|
531
|
+
|
|
532
|
+
Пример:
|
|
533
|
+
|
|
534
|
+
```text
|
|
535
|
+
/truthmark-structure раздели широкий repository area на frontend, backend, billing и deployment
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
Хороший routing дает Truth Sync точные цели.
|
|
539
|
+
|
|
540
|
+
Плохой routing заставляет агентов гадать.
|
|
541
|
+
|
|
542
|
+
## Что устанавливает Truthmark
|
|
543
|
+
|
|
544
|
+
Truthmark устанавливает компактный, встроенный в репозиторий слой истины.
|
|
545
|
+
|
|
546
|
+
Он устанавливает четыре слоя:
|
|
547
|
+
|
|
548
|
+
- config и routing для границ владения
|
|
549
|
+
- канонические truth docs и стартовые шаблоны
|
|
550
|
+
- компактные управляемые instruction blocks для repo-wide agent context
|
|
551
|
+
- host-native workflow packages, commands, prompts и verifier agents для платформ, включённых в config
|
|
552
|
+
|
|
553
|
+
Truthmark сохраняет ручной контент вне управляемых блоков инструкций.
|
|
554
|
+
|
|
555
|
+
Сгенерированные поверхности workflow управляются Truthmark и могут обновляться повторным запуском:
|
|
556
|
+
|
|
557
|
+
```bash
|
|
558
|
+
truthmark init
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
## Subagents и ограниченные проверки evidence
|
|
562
|
+
|
|
563
|
+
Там, где host поддерживает это, Truthmark может устанавливать project-scoped verifier agents и leased `truth-doc-writer`.
|
|
564
|
+
|
|
565
|
+
Они помогают держать большие truth-задачи ограниченными:
|
|
566
|
+
|
|
567
|
+
- route auditors проверяют владение маршрутами
|
|
568
|
+
- claim verifiers проверяют, поддержаны ли claims документов evidence
|
|
569
|
+
- doc reviewers проверяют качество truth docs
|
|
570
|
+
- leased doc writers обрабатывают ограниченные shards записи truth docs
|
|
571
|
+
|
|
572
|
+
Родительский workflow все еще владеет финальной интерпретацией, границами записи, проверкой diff и приемкой.
|
|
573
|
+
|
|
574
|
+
Это важно: subagents помогают с ограниченной evidence work. Они не заменяют основной контракт workflow.
|
|
575
|
+
|
|
576
|
+
## Цикл ревью
|
|
577
|
+
|
|
578
|
+
Truthmark спроектирован для обычного Git review.
|
|
579
|
+
|
|
580
|
+
Хорошая ИИ-ассистированная передача работы должна показывать:
|
|
581
|
+
|
|
582
|
+
```text
|
|
583
|
+
diff кода
|
|
584
|
+
test evidence
|
|
585
|
+
diff truth docs, если нужен
|
|
586
|
+
изменения routing, если нужны
|
|
587
|
+
отчет агента
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
Ревьюер должен уметь ответить:
|
|
591
|
+
|
|
592
|
+
- Какой код изменился?
|
|
593
|
+
- Какие документы истины владеют этим кодом?
|
|
594
|
+
- Нужно ли было обновлять эти документы?
|
|
595
|
+
- Если нет, почему?
|
|
596
|
+
- Остался ли агент внутри границы записи workflow?
|
|
597
|
+
- Приложена ли evidence тестов или проверки?
|
|
598
|
+
|
|
599
|
+
## Примеры
|
|
600
|
+
|
|
601
|
+
### Инициализировать репозиторий
|
|
602
|
+
|
|
603
|
+
```bash
|
|
604
|
+
npm install -g truthmark
|
|
605
|
+
truthmark config
|
|
606
|
+
truthmark init
|
|
607
|
+
truthmark check
|
|
608
|
+
```
|
|
609
|
+
|
|
610
|
+
### Удалить неиспользуемые платформы агентов
|
|
611
|
+
|
|
612
|
+
Отредактируйте:
|
|
613
|
+
|
|
614
|
+
```text
|
|
615
|
+
.truthmark/config.yml
|
|
616
|
+
```
|
|
617
|
+
|
|
618
|
+
Затем снова выполните:
|
|
619
|
+
|
|
620
|
+
```bash
|
|
621
|
+
truthmark init
|
|
622
|
+
truthmark check
|
|
623
|
+
```
|
|
624
|
+
|
|
625
|
+
### Разделить широкий routing
|
|
626
|
+
|
|
627
|
+
```text
|
|
628
|
+
/truthmark-structure раздели широкий repository area на auth, billing, notifications и deployment
|
|
629
|
+
```
|
|
630
|
+
|
|
631
|
+
### Документировать реализованное поведение
|
|
632
|
+
|
|
633
|
+
```text
|
|
634
|
+
/truthmark-document задокументируй реализованный password reset flow в docs/truth/authentication
|
|
635
|
+
```
|
|
636
|
+
|
|
637
|
+
### Синхронизировать после изменений кода
|
|
638
|
+
|
|
639
|
+
```text
|
|
640
|
+
/truthmark-sync синхронизируй истину репозитория прямо сейчас перед передачей
|
|
641
|
+
```
|
|
642
|
+
|
|
643
|
+
### Реализовать doc-first решение
|
|
644
|
+
|
|
645
|
+
```text
|
|
646
|
+
/truthmark-realize реализуй docs/truth/billing/invoice-retry-policy.md в коде
|
|
647
|
+
```
|
|
648
|
+
|
|
649
|
+
### Проверить здоровье истины из терминала
|
|
650
|
+
|
|
651
|
+
```bash
|
|
652
|
+
truthmark check
|
|
653
|
+
```
|
|
654
|
+
|
|
655
|
+
### Создать branch-impact context
|
|
656
|
+
|
|
657
|
+
```bash
|
|
658
|
+
truthmark impact --base main
|
|
659
|
+
```
|
|
660
|
+
|
|
661
|
+
### Создать workflow context
|
|
288
662
|
|
|
289
|
-
|
|
663
|
+
```bash
|
|
664
|
+
truthmark context --workflow truth-sync --base main --format markdown
|
|
665
|
+
```
|
|
290
666
|
|
|
291
|
-
|
|
667
|
+
### Включить опциональный Portal workflow
|
|
668
|
+
|
|
669
|
+
```yaml
|
|
670
|
+
truthmark-portal:
|
|
671
|
+
enabled: true
|
|
672
|
+
output: docs/truthmark-portal
|
|
673
|
+
template: default
|
|
674
|
+
```
|
|
675
|
+
|
|
676
|
+
```bash
|
|
677
|
+
truthmark init
|
|
678
|
+
```
|
|
679
|
+
|
|
680
|
+
Затем явно попросите agent host выполнить установленный Portal workflow, когда нужно сгенерировать или обновить статический презентационный сайт.
|
|
681
|
+
|
|
682
|
+
## Статус проекта
|
|
683
|
+
|
|
684
|
+
Truthmark V1 сейчас предоставляет:
|
|
292
685
|
|
|
293
686
|
- `truthmark config`
|
|
294
687
|
- `truthmark init`
|
|
@@ -296,39 +689,124 @@ V1 сейчас предоставляет:
|
|
|
296
689
|
- `truthmark index`
|
|
297
690
|
- `truthmark impact`
|
|
298
691
|
- `truthmark context`
|
|
299
|
-
-
|
|
300
|
-
-
|
|
301
|
-
-
|
|
302
|
-
-
|
|
303
|
-
-
|
|
692
|
+
- branch-scope metadata
|
|
693
|
+
- управляемые блоки инструкций
|
|
694
|
+
- сгенерированные поверхности workflow Truth Structure
|
|
695
|
+
- сгенерированные поверхности workflow Truth Document
|
|
696
|
+
- сгенерированные поверхности workflow Truth Sync
|
|
697
|
+
- сгенерированные поверхности workflow Truth Preview
|
|
698
|
+
- сгенерированные поверхности workflow Truth Realize
|
|
699
|
+
- сгенерированные поверхности workflow Truth Check
|
|
700
|
+
- опциональные сгенерированные поверхности workflow Truthmark Portal
|
|
701
|
+
- diagnostics для route, authority, decision-structure, frontmatter, links, freshness, generated-surface и coverage
|
|
702
|
+
- производные артефакты RepoIndex, RouteMap, ImpactSet и ContextPack
|
|
703
|
+
- host-specific поверхности для Codex, Claude Code, GitHub Copilot, OpenCode и Gemini CLI
|
|
704
|
+
|
|
705
|
+
## Разработка
|
|
706
|
+
|
|
707
|
+
Установить зависимости:
|
|
708
|
+
|
|
709
|
+
```bash
|
|
710
|
+
npm install
|
|
711
|
+
```
|
|
712
|
+
|
|
713
|
+
Запустить локальную development CLI:
|
|
714
|
+
|
|
715
|
+
```bash
|
|
716
|
+
npm run dev -- init
|
|
717
|
+
npm run dev -- check
|
|
718
|
+
```
|
|
719
|
+
|
|
720
|
+
Запустить полный project check:
|
|
721
|
+
|
|
722
|
+
```bash
|
|
723
|
+
npm run check
|
|
724
|
+
```
|
|
725
|
+
|
|
726
|
+
Полезные scripts:
|
|
727
|
+
|
|
728
|
+
| Script | Назначение |
|
|
729
|
+
| --- | --- |
|
|
730
|
+
| `npm run dev` | Запускает TypeScript CLI entry point через `tsx`. |
|
|
731
|
+
| `npm run build` | Собирает package. |
|
|
732
|
+
| `npm run lint` | Запускает ESLint. |
|
|
733
|
+
| `npm run typecheck` | Запускает TypeScript checks. |
|
|
734
|
+
| `npm run test` | Запускает tests. |
|
|
735
|
+
| `npm run check` | Запускает lint, typecheck, tests и build. |
|
|
736
|
+
| `npm run release:check` | Запускает release-oriented validation. |
|
|
737
|
+
|
|
738
|
+
Когда меняете сам Truthmark, смотрите [CONTRIBUTORS.md](CONTRIBUTORS.md).
|
|
304
739
|
|
|
305
740
|
## Документация
|
|
306
741
|
|
|
307
|
-
|
|
742
|
+
README — быстрый путь для оценки и настройки.
|
|
743
|
+
|
|
744
|
+
Подробное текущее поведение живет в `docs/`:
|
|
308
745
|
|
|
309
746
|
- [Индекс документации](docs/README.md)
|
|
310
747
|
- [Обзор архитектуры](docs/architecture/overview.md)
|
|
311
748
|
- [Контракты API и CLI](docs/truth/contracts.md)
|
|
312
749
|
- [Поведение init и scaffold](docs/truth/init-and-scaffold.md)
|
|
313
750
|
- [Диагностика check](docs/truth/check-diagnostics.md)
|
|
314
|
-
- [Установленные
|
|
751
|
+
- [Установленные workflows](docs/truth/workflows/overview.md)
|
|
315
752
|
- [Руководство по поддержанию истины репозитория](docs/standards/maintaining-repository-truth.md)
|
|
316
753
|
|
|
317
|
-
|
|
754
|
+
## Границы дизайна
|
|
318
755
|
|
|
319
|
-
|
|
756
|
+
Truthmark намеренно небольшой.
|
|
320
757
|
|
|
321
|
-
|
|
758
|
+
Он не является:
|
|
322
759
|
|
|
323
760
|
- размещенным сервисом
|
|
324
761
|
- MCP-сервером
|
|
325
762
|
- векторной базой данных
|
|
326
|
-
- генератором сайтов документации
|
|
327
|
-
-
|
|
328
|
-
- заменой
|
|
329
|
-
- автономным движком
|
|
763
|
+
- каноническим генератором сайтов документации или hosted docs platform
|
|
764
|
+
- CI- или PR-enforcement продуктом
|
|
765
|
+
- заменой tests, code review или technical leadership
|
|
766
|
+
- автономным движком переписывания кода
|
|
767
|
+
- framework для model training или fine-tuning
|
|
768
|
+
- скрытым слоем памяти
|
|
769
|
+
|
|
770
|
+
Эти границы — часть продукта.
|
|
771
|
+
|
|
772
|
+
Truthmark держит workflow локальным, зафиксированным, ограниченным веткой и проверяемым.
|
|
773
|
+
|
|
774
|
+
## Безопасность и дисциплина ревью
|
|
775
|
+
|
|
776
|
+
Truthmark помогает репозиторию оставаться честным. Он не доказывает, что код корректен.
|
|
777
|
+
|
|
778
|
+
Команды все равно должны:
|
|
330
779
|
|
|
331
|
-
|
|
780
|
+
- запускать релевантные тесты
|
|
781
|
+
- проверять изменения функционального кода
|
|
782
|
+
- проверять изменения документов истины
|
|
783
|
+
- держать secrets вне документации
|
|
784
|
+
- держать специфичные для репозитория инструкции вне managed blocks
|
|
785
|
+
- проверять diff сгенерированных workflow surfaces после upgrades
|
|
786
|
+
- сохранять человеческое владение продуктовыми и архитектурными решениями
|
|
787
|
+
|
|
788
|
+
Truthmark делает контекст агента видимым. Он не заменяет человеческое суждение.
|
|
789
|
+
|
|
790
|
+
## Направление roadmap
|
|
791
|
+
|
|
792
|
+
Текущее будущее направление делает акцент на:
|
|
793
|
+
|
|
794
|
+
- более сильной evidence reporting в `truthmark check`
|
|
795
|
+
- более ясных примерах adoption
|
|
796
|
+
- примерных репозиториях, показывающих реальные циклы Truth Sync
|
|
797
|
+
- migration guides для команд, уже использующих agent instruction files
|
|
798
|
+
- conformance tests для generated host surfaces
|
|
799
|
+
- route-aware подсказках о stale truth
|
|
800
|
+
- ограниченных implementation checklists для doc-first work
|
|
801
|
+
|
|
802
|
+
Центр тяжести остается прежним:
|
|
803
|
+
|
|
804
|
+
```text
|
|
805
|
+
истина репозитория
|
|
806
|
+
agent-native workflows
|
|
807
|
+
Git review
|
|
808
|
+
контекст в пределах ветки
|
|
809
|
+
```
|
|
332
810
|
|
|
333
811
|
## Лицензия
|
|
334
812
|
|