truthmark 1.2.2 → 1.3.0

package/README.ru.md

@@ -1,31 +1,68 @@
-# Truthmark это слой истины для разработки ПО с ИИ.
+# Truthmark
+
+**Truthmark устанавливает рабочие процессы истины репозитория для разработки ПО с ИИ.**
 
 [English](README.md) | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | Русский
 
-ИИ-агенты для разработки уже неплохо пишут код. Но они все еще плохо восстанавливают намерения продукта, архитектурные границы и зоны ответственности в репозитории по устаревшей документации, разрозненным чатам и недолговечной памяти инструментов.
-Truthmark решает эту проблему: он превращает истину репозитория, локальную для ветки, в полноценную поверхность выполнения для агентов. Он устанавливает прямо в репозиторий Git-native слой истины с областью действия в пределах ветки, задает агентам явные границы маршрутизации и рабочих процессов и делает так, чтобы эта истина двигалась вместе с кодом, который действительно будет поставлен.
-Это не более удачная инженерия промптов. Это более управляемый способ использовать ИИ в настоящей кодовой базе: меньше повторных решений, меньше устаревшей документации, чище передача работы и сессии с ИИ, после которых остаются проверяемые инженерные записи, а не только следы в истории промптов или непрозрачном состоянии инструментов.
-Для команд, которые уже знают, что агенты умеют генерировать код, и теперь хотят, чтобы сам репозиторий оставался понятным, проверяемым и управляемым.
+<img src="docs/assets/truthmark-banner.png" alt="Баннер Truthmark" width="100%" />
 
-## Что решает Truthmark
+ИИ-агенты уже быстро пишут код. Дорогая часть — удерживать истину репозитория в соответствии с тем, что реально изменилось.
+
+Truthmark добавляет в этот процесс финальную защиту на уровне рабочего процесса. Обычный путь прост:
+
+- агент меняет функциональный код
+- запускаются релевантные тесты
+- установленный рабочий процесс Truth Sync обновляет связанные документы истины до завершения работы агента
+- если был создан diff документов истины, его проверяют
+
+Большинство инструментов просит команды выработать привычку. Truthmark превращает эту привычку в инфраструктуру рабочего процесса репозитория.
+
+Truthmark превращает ИИ-процесс в инфраструктуру репозитория, а не в персональный инструмент. Он устанавливает Git-native слой истины внутри репозитория, задает агентам явную маршрутизацию и ограниченные рабочие поверхности и сохраняет эту истину проверяемой в Git вместо того, чтобы разносить ее по истории промптов, устаревшей документации или приватному состоянию инструментов.
+
+Это важно, потому что процесс живет вместе с веткой. После инициализации репозитория правила, маршрутизация и установленные рабочие поверхности путешествуют внутри репозитория, поэтому совместная работа и передача задач меньше зависят от локальной настройки одного человека.
+
+Для команд, которые уже знают, что агенты умеют генерировать код, Truthmark решает следующую проблему: как сделать так, чтобы сам репозиторий оставался понятным, проверяемым и управляемым по мере роста ИИ-ассистированной разработки.
+
+## Визуальный обзор
+
+<table>
+	<tr>
+		<td align="center" width="50%">
+			<img src="docs/assets/truthmark-features.png" alt="Возможности Truthmark" width="100%" />
+			<br><strong>Возможности</strong><br>
+			Что устанавливает Truthmark и как устроена рабочая поверхность.
+		</td>
+		<td align="center" width="50%">
+			<img src="docs/assets/truthmark-position.png" alt="Позиционирование Truthmark" width="100%" />
+			<br><strong>Позиционирование</strong><br>
+			Где Truthmark находится относительно промптов, памяти и spec-first процессов.
+		</td>
+	</tr>
+	<tr>
+		<td align="center" colspan="2">
+			<img src="docs/assets/truthmark-syncflow.png" alt="Поток sync в Truthmark" width="100%" />
+			<br><strong>Поток sync</strong><br>
+			Как Truth Sync закрывает обычные изменения кода перед передачей работы.
+		</td>
+	</tr>
+</table>
+
+## Почему команды выбирают Truthmark
 
-Начать писать код с ИИ сейчас легко, но управлять этим дорого. Как только агенты начинают быстро писать код, истина репозитория становится поверхностью управления.
-Этот сбой проявляется предсказуемо: требования остаются в чатах, архитектурные решения принимаются заново, агенты трогают не те области, а ветки наследуют контекст, который ревьюеры не могут надежно проверить. Код может двигаться быстро, но репозиторию становится труднее доверять.
-Truthmark меняет рабочую модель:
+Truthmark не пытается сделать так, чтобы агенты звучали умнее. Он пытается сделать изменения в репозитории, выполненные с помощью ИИ, более надежными.
 
-- Истина, локальная для ветки, путешествует вместе с веткой, а не живет в приватном хранилище инструмента.
-- Git делает эту истину проверяемой, сравнимой в diff и доступной всей команде.
-- Документация следует за кодом, а не тихо превращается в вымысел.
-- Маршрутизация остается явной в `docs/truthmark/areas.md` и делегированных дочерних файлах маршрутов, чтобы агенты понимали, какая документация отвечает за какой код.
-- Активные продуктовые и архитектурные решения живут в канонических документах, которыми они управляют, а не в планировочных журналах с временными метками.
-- Local-first рабочие процессы не требуют демона, базы данных, удаленного сервиса или MCP-зависимости.
-- Модель работает в кодовых базах на JavaScript, TypeScript, Go, Python, C# и Java.
+- Установленный Truth Sync после изменений кода превращает поддержку документации в защиту рабочего процесса, а не в командную привычку.
+- Истина, ограниченная веткой, движется вместе с кодом, поэтому ревьюеры могут проверять актуальную истину в обычных Git diff.
+- Рабочие поверхности, встроенные в репозиторий, упрощают внедрение и делают передачу работы устойчивее, чем одна лишь персональная настройка.
+- Явная маршрутизация в `docs/truthmark/areas.md` и делегированных дочерних файлах маршрутов дает агентам границы ответственности и более безопасные пути записи.
+- Local-first работа избавляет от зависимости на демон, базу данных, удаленный сервис или MCP.
+- Модель маршрутизации не зависит от языка и дает диагностику покрытия для распространенных поверхностей кода JavaScript, TypeScript, Go, Python, C# и Java.
 
-Для технических лидеров ценность в управлении без показухи: тесты, ревью кода и владение зонами ответственности по-прежнему делают основную работу; Truthmark делает контекст агента долговечным, проверяемым и ограниченным веткой.
+Для технических лидеров ценность в управлении без дополнительной инфраструктуры: тесты, ревью кода и владение зонами ответственности по-прежнему делают основную работу; Truthmark делает контекст агента долговечным, проверяемым и ограниченным веткой.
 
 ## Где уместен Truthmark
 
-Truthmark не пытается заменить все остальные инструменты для ИИ-процессов. Он занимает конкретный слой в стеке:
+Truthmark не является универсальным набором ИИ-инструментов для продуктивности. Он занимает конкретный слой в стеке: проверяемая истина репозитория, ограниченная веткой и выровненная с реализацией.
 
 | Если вам нужно                                                                                   | Лучший выбор                                   |
 | ------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
@@ -38,9 +75,9 @@ Truthmark не пытается заменить все остальные ин
 
 ## Содержание
 
+- [Почему команды выбирают Truthmark](#почему-команды-выбирают-truthmark)
 - [Что решает Truthmark](#что-решает-truthmark)
 - [Где уместен Truthmark](#где-уместен-truthmark)
-- [Рабочая поверхность](#рабочая-поверхность)
 - [Начало работы](#начало-работы)
 - [Как он работает](#как-он-работает)
 - [Что он устанавливает](#что-он-устанавливает)
@@ -51,12 +88,13 @@ Truthmark не пытается заменить все остальные ин
 - [Не-цели](#не-цели)
 - [Лицензия](#лицензия)
 
-## Рабочая поверхность
+## Что решает Truthmark
 
 Truthmark превращает истину репозитория в явную рабочую поверхность для агентов:
 
-- `TRUTHMARK.md` определяет контракт рабочего процесса, локальный для ветки.
+- `.truthmark/config.yml` определяет зафиксированный контракт иерархии.
 - `docs/truthmark/areas.md` и делегированные дочерние файлы маршрутов сопоставляют области кода с документами, которые за них отвечают.
+- Truth Document создает или исправляет канонические документы истины для уже реализованного поведения, когда изменение кода не нужно.
 - Truth Sync поддерживает синхронизацию сопоставленных документов истины при функциональных изменениях.
 - Truth Realize дает изменениям, начинающимся с документации, ограниченный путь для обновления кода.
 - `truthmark check` валидирует получившиеся артефакты истины.
@@ -92,88 +130,145 @@ node /path/to/truthmark/dist/main.js check
 
 ```text
 .truthmark/config.yml
-TRUTHMARK.md
 docs/truthmark/areas.md
 docs/truthmark/areas/repository.md
-docs/features/README.md
-docs/features/repository/README.md
-docs/features/repository/overview.md
+docs/templates/behavior-doc.md
+docs/truth/README.md
+docs/truth/repository/README.md
+docs/truth/repository/overview.md
 AGENTS.md
 CLAUDE.md
+GEMINI.md
 ```
 
 Поддерживаемые платформы: `codex`, `opencode`, `claude-code`, `github-copilot` и `gemini-cli`. Конфигурация по умолчанию включает их все; удалите из `.truthmark/config.yml` платформы, которыми не пользуетесь, перед повторным запуском `truthmark init`.
-Стандартная шаблонная структура использует `README.md` функциональных разделов как индексы и начинает описывать истину текущего поведения в ограниченных листовых документах, например `docs/features/repository/overview.md`.
+Стандартная шаблонная структура использует truth-`README.md` как индексы и начинает описывать истину текущего поведения в ограниченных листовых документах, например `docs/truth/repository/overview.md`.
 
 Существующим репозиториям обычно нужен один этап очистки после `init`: запустите установленный рабочий процесс Truth Structure, если созданный маршрут `repository` слишком широкий, владение охватывает несколько продуктов или сервисов, либо файлы маршрутов все еще указывают на документы-заглушки. Truth Structure разделяет широкие маршруты, создает или исправляет начальные канонические документы истины и дает Truth Sync точные цели до начала работы с функциональным кодом. Codex, Claude Code и поддерживаемые IDE Copilot могут вызвать его через `/truthmark-structure`; хосты в стиле OpenCode могут использовать `/skill truthmark-structure`.
 
 ## Как он работает
 
-Truthmark не задает, какой именно подагент должен запускать Truth Sync. Действующий агент и среда хоста сами решают, делегировать работу или выполнить процесс на месте.
-Большинству пользователей не нужно вызывать Truth Sync напрямую. Нормальный путь выглядит так:
+Сильная сторона Truthmark — путь по умолчанию, а не набор ручных команд. Действующий агент и среда хоста сами решают, делегировать работу или выполнить установленный процесс на месте.
+
+### Существующее поведение без документации
+
+Используйте это, когда реализация уже есть, но канонические документы истины отсутствуют или слабы:
+
+```text
+пользователь определяет реализованное поведение или api-эндпоинт
+пользователь явно вызывает truth document
+агент читает реализацию, тесты, маршрутизацию и существующие docs
+агент пишет только truth docs и маршрутизацию
+проверить diff truth docs
+```
+
+Truth Document — это ручной процесс с приоритетом реализации: код служит доказательством, документы истины создаются или исправляются, и функциональный код менять нельзя. Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-document`; хосты в стиле OpenCode могут использовать `/skill truthmark-document`.
+
+```text
+/truthmark-document документирует реализованное поведение session timeout в docs/truth/authentication
+```
+
+### Обычные изменения кода
+
+Большинству пользователей не нужно напрямую вызывать Truth Sync. Главное, что установленный агентский процесс рассматривает Truth Sync как финальную защиту, когда менялся функциональный код. Нормальный путь выглядит так:
 
 ```text
 агент изменяет функциональный код
 запускаются релевантные тесты
-Truth Sync срабатывает до завершения работы агента
-если был создан diff документов истины, он проверяется
+установленный truth sync workflow запускается до завершения агента
+если был создан diff truth docs, он проверяется
 работа коммитится или передается дальше
 ```
 
-Truth Sync работает по принципу code-first: сначала идет код, затем документы истины, и Truth Sync не должен переписывать функциональный код. Его основная задача быть автоматической финальной проверкой, когда менялся функциональный код. Прямой вызов нужен в основном для отладки, ранней синхронизации перед передачей работы или намеренного запуска рабочего процесса.
+Truth Sync работает по принципу code-first: сначала идет код, затем документы истины, и Truth Sync не должен переписывать функциональный код. Его основная задача - выполняться через установленный агентский процесс как финальная защита, когда менялся функциональный код. Прямой вызов нужен в основном для отладки, ранней синхронизации перед передачей работы или намеренного запуска рабочего процесса.
+
 Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-sync`. Хосты в стиле OpenCode могут использовать `/skill truthmark-sync`.
+
+```text
+/truthmark-sync синхронизируй истину репозитория прямо сейчас перед передачей
+```
+
+### Doc-first изменения
+
 Используйте этот путь, когда продуктовое или архитектурное решение начинается в документации:
 
 ```text
-пользователь редактирует документы истины
-пользователь явно вызывает Truth Realize
-агент читает документы истины и связанный код
+пользователь редактирует truth docs
+пользователь явно вызывает truth realize
+агент читает truth docs и связанный код
 агент обновляет только код
 запускаются релевантные тесты
 работа коммитится или передается дальше
 ```
 
-Truth Realize это ручной процесс по принципу doc-first: документы истины идут первыми, код следует за ними, и агент не должен редактировать документы истины, которые он реализует.
+Truth Realize — это ручной doc-first процесс: документы истины идут первыми, код следует за ними, и агент не должен редактировать документы истины, которые он реализует.
+
 Codex, Claude Code и поддерживаемые IDE Copilot могут вызывать его через `/truthmark-realize`. Хосты в стиле OpenCode могут использовать `/skill truthmark-realize`.
 
+```text
+/truthmark-realize реализуй docs/truth/authentication/session-timeout.md в код
+```
+
 ## Что он устанавливает
 
-Truthmark намеренно держит постоянную рабочую поверхность маленькой:
+Truthmark держит постоянную рабочую поверхность маленькой и встроенной в репозиторий. После `truthmark init` сам репозиторий несет маршрутизацию, правила и установленные рабочие поверхности, поэтому команда не зависит только от локальной настройки одного человека.
 
-- `.truthmark/config.yml` для машиночитаемой конфигурации
-- `TRUTHMARK.md` для контракта рабочего процесса, локального для ветки
+- `.truthmark/config.yml` для машиночитаемого зафиксированного контракта иерархии
 - `docs/truthmark/areas.md` для корневого индекса маршрутов
 - `docs/truthmark/areas/**/*.md` для делегированных дочерних файлов маршрутов
+- `docs/templates/behavior-doc.md` и другие шаблоны по видам под `docs/templates/` для редактируемых стандартов truth docs, используемых сгенерированными рабочими процессами
 - управляемые блоки инструкций для настроенных платформ, таких как `AGENTS.md`, `CLAUDE.md`, инструкции Copilot и `GEMINI.md`
-- нативные для хоста skills, prompts или commands для Truth Structure, Truth Sync, Truth Realize и Truth Check
+- нативные для хоста skills, prompts или commands для Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check
 
 Установленные рабочие поверхности и есть среда выполнения:
 
 - Truth Structure создает или исправляет маршрутизацию областей и стартовые документы истины.
+- Truth Document создает или исправляет документы истины для уже реализованного поведения.
 - Truth Sync поддерживает синхронизацию сопоставленных документов истины с функциональными изменениями.
 - Truth Realize обновляет код так, чтобы он соответствовал документам истины.
 - Truth Check аудитирует здоровье истины репозитория.
 
-`README.md` функциональных разделов это индексы. Ожидается, что Truth Sync будет читать и обновлять ограниченные листовые документы для текущего поведения.
+`README.md` функциональных разделов это индексы. Ожидается, что Truth Sync будет читать и обновлять ограниченные листовые документы для текущего поведения. Сгенерированные рабочие поверхности сохраняют приоритет правил репозитория, рассматривая код реализации и канонические документы истины как свидетельства текущего поведения.
 
 Сгенерированные поверхности управляются Truthmark, содержат маркер версии и могут обновляться через `truthmark init`.
 
 ## Команды
 
-Truthmark V1 намеренно держит CLI небольшим. В нижестоящих репозиториях `truthmark config` создает зафиксированный контракт иерархии, `truthmark init` устанавливает и обновляет рабочие поверхности на основе этой проверенной конфигурации, а `truthmark check` валидирует артефакты истины для ручных аудитов, CI или отладки.
+Truthmark V1 намеренно держит CLI небольшим, потому что постоянный рабочий процесс должен жить в установленных агентских поверхностях, а не в длинном списке ежедневных ручных команд. В нижестоящих репозиториях `truthmark config` создает зафиксированный контракт иерархии, `truthmark init` устанавливает и обновляет рабочие поверхности на основе этой проверенной конфигурации, `truthmark check` валидирует артефакты истины для ручных аудитов, CI или отладки, а команды репозиторной аналитики создают производные артефакты для проверки, когда доступны локальные инструменты.
 
 ```bash
 truthmark config
 truthmark init
 truthmark check
+truthmark index
+truthmark impact --base main
+truthmark context --workflow truth-sync --base main
 truthmark config --json
 truthmark check --json
+truthmark index --json
+truthmark impact --base main --json
+truthmark context --workflow truth-sync --base main --json
 ```
 
 `config` пишет только `.truthmark/config.yml`, если не используется `--stdout`.
+
 `init` требует `.truthmark/config.yml`, а затем устанавливает или обновляет локальные файлы рабочих процессов.
+
 `check` валидирует конфигурацию, полномочия, маршрутизацию, документы с решениями, frontmatter, внутренние ссылки, область действия ветки и диагностику покрытия.
-Truth Structure, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.
+
+`index` строит JSON RepoIndex и RouteMap для активного checkout.
+
+`impact --base <ref>` сопоставляет измененные файлы с routed truth docs, owning routes, nearby tests и public symbols.
+
+`context --workflow <workflow> [--base <ref>]` генерирует ограниченный ContextPack для Truth Sync, Truth Document или Truth Realize. `--format markdown` рендерит его в читаемый человеком вид.
+
+Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.
+
+Они запускаются через настроенные поверхности хоста агента, например Codex/Claude/Copilot `/truthmark-*`, OpenCode `/skill truthmark-*` или Gemini `/truthmark:*`.
+
+```text
+/truthmark-check проверь маршрутизацию и покрытие truth перед review
+```
 
 ## Зачем он существует
 
@@ -191,16 +286,21 @@ Truth Structure, Truth Sync, Truth Realize и Truth Check это установ
 
 ## Статус проекта
 
-Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие поверхности.
+Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие поверхности, которые превращают правила ИИ-процесса в инфраструктуру репозитория.
+
 V1 сейчас предоставляет:
 
 - `truthmark config`
 - `truthmark init`
 - `truthmark check`
+- `truthmark index`
+- `truthmark impact`
+- `truthmark context`
 - управляемые инструкции рабочих процессов в `AGENTS.md`
-- сгенерированные skill-поверхности Truth Structure, Truth Sync, Truth Realize и Truth Check для настроенных агентских хостов
+- сгенерированные skill-поверхности Truth Structure, Truth Document, Truth Sync, Truth Realize и Truth Check для настроенных агентских хостов
 - метаданные области ветки
 - диагностика конфигурации, полномочий, маршрутизации, структуры решений, frontmatter, ссылок и полиглотного покрытия
+- производные артефакты RepoIndex, RouteMap, ImpactSet и ContextPack для более быстрой локальной проверки, когда CLI доступен
 
 ## Документация
 
@@ -208,10 +308,10 @@ V1 сейчас предоставляет:
 
 - [Индекс документации](docs/README.md)
 - [Обзор архитектуры](docs/architecture/overview.md)
-- [Контракты API и CLI](docs/features/contracts.md)
-- [Поведение init и scaffold](docs/features/init-and-scaffold.md)
-- [Диагностика check](docs/features/check-diagnostics.md)
-- [Установленные workflow](docs/features/installed-workflows.md)
+- [Контракты API и CLI](docs/truth/contracts.md)
+- [Поведение init и scaffold](docs/truth/init-and-scaffold.md)
+- [Диагностика check](docs/truth/check-diagnostics.md)
+- [Установленные workflow](docs/truth/workflows/overview.md)
 - [Руководство по поддержанию истины репозитория](docs/standards/maintaining-repository-truth.md)
 
 Текущее поведение должно жить в каноническом дереве документации выше.