truthmark 1.2.0

package/README.md

@@ -0,0 +1,248 @@
+# Truthmark
+
+**Truthmark is the truth layer for AI software development.**
+
+English | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | [Русский](README.ru.md)
+
+AI coding agents are already good at writing code. They are still bad at reliably reconstructing product intent, architecture boundaries, and repository ownership from stale docs, scattered chats, and ephemeral tool memory.
+
+Truthmark fixes that by turning branch-local repository truth into a first-class runtime surface for agents. It installs a Git-native, branch-scoped truth layer directly inside the repo, gives agents explicit routing and workflow boundaries, and makes that truth move with the code that actually ships.
+
+This is not better prompt engineering. It is a more governable way to use AI in a real codebase: fewer repeated decisions, fewer stale docs, cleaner handoffs, and AI coding sessions that leave behind reviewable engineering records instead of disappearing into prompt history or opaque tool state.
+
+For teams who already know agents can generate code, and now need the repository itself to stay legible, reviewable, and governable.
+
+## Why teams try it
+
+AI coding is now easy to start and expensive to govern. Once agents can write code quickly, repository truth becomes the control surface.
+
+That failure mode shows up in predictable ways: requirements live in chat, architecture decisions get repeated, agents touch the wrong surfaces, and branches inherit context that reviewers cannot reliably inspect. The code may move fast, but the repository gets harder to trust.
+
+Truthmark changes the working model:
+
+- Branch-local truth travels with the branch instead of living in a private tool store.
+- Git makes that truth reviewable, diffable, and shareable across the team.
+- Docs follow code instead of drifting quietly into fiction.
+- Routing stays explicit in `docs/truthmark/areas.md` and delegated child route files so agents know which docs own which code.
+- Active product and architecture decisions live in the canonical docs they govern instead of in timestamped planning logs.
+- Local-first workflows avoid a daemon, database, remote service, or MCP dependency.
+- The model works across JavaScript, TypeScript, Go, Python, C#, and Java codebases.
+
+For tech leads, the value is governance without theater: tests, code review, and ownership still do the real work; Truthmark makes the agent's context durable, inspectable, and branch-scoped.
+
+## Where Truthmark fits
+
+Truthmark is not trying to replace every other AI workflow tool. It sits in a specific layer of the stack:
+
+| If you need | Best fit |
+| --- | --- |
+| Better results from a single coding session | Better prompts and tighter task framing |
+| Convenience across sessions for one agent or one operator | Memory tools |
+| Spec-first planning for new features | Spec tools such as Spec Kit |
+| Branch-scoped, reviewable repository truth that travels with the code | Truthmark |
+
+The point is not that prompts, memory, or specs are useless. The point is that none of them, by themselves, turn repository truth into a committed, inspectable asset that survives handoffs, review, and branch divergence.
+
+## Table of Contents
+
+- [What Truthmark solves](#what-truthmark-solves)
+- [Where Truthmark fits](#where-truthmark-fits)
+- [Get started](#get-started)
+- [How it runs](#how-it-runs)
+- [What it installs](#what-it-installs)
+- [Commands](#commands)
+- [Why it exists](#why-it-exists)
+- [Project status](#project-status)
+- [Documentation](#documentation)
+- [Non-goals](#non-goals)
+- [License](#license)
+
+## What Truthmark solves
+
+Truthmark turns repository truth into an explicit workflow surface for agents:
+
+- `TRUTHMARK.md` defines the branch-local workflow contract.
+- `docs/truthmark/areas.md` and delegated child route files map code areas to the docs that own them.
+- Truth Sync keeps mapped truth docs aligned with functional changes.
+- Truth Realize gives doc-first changes a bounded code-update path.
+- `truthmark check` validates the resulting truth artifacts.
+- The whole model stays local-first and Git-native.
+
+This is the core promise: agent context becomes committed repository state instead of a private session artifact.
+
+## Get started
+
+To try Truthmark from a source checkout instead of the published npm package:
+
+```bash
+cd /path/to/truthmark
+npm install
+npm run build
+
+cd /path/to/your-repo
+node /path/to/truthmark/dist/main.js config
+node /path/to/truthmark/dist/main.js init
+node /path/to/truthmark/dist/main.js check
+```
+
+Review `.truthmark/config.yml` before `init`; it is the committed hierarchy contract. After `init`, review the generated workflow surface and route files so the routed docs match the docs that actually own your code:
+
+```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
+AGENTS.md
+CLAUDE.md
+skills/truthmark-structure/SKILL.md
+skills/truthmark-sync/SKILL.md
+skills/truthmark-realize/SKILL.md
+skills/truthmark-check/SKILL.md
+```
+
+If you enable additional platforms in `.truthmark/config.yml`, Truthmark refreshes the corresponding managed surfaces on the next `init`.
+
+The default scaffold keeps feature `README.md` files as indexes and starts current behavior truth in bounded leaf docs such as `docs/features/repository/overview.md`.
+
+Truthmark does not specify which subagent should run Truth Sync. The acting agent and host environment decide whether to delegate or run the workflow inline.
+
+## How it runs
+
+### Normal code changes
+
+Most users should not need to invoke Truth Sync directly. The normal path is:
+
+```text
+agent changes functional code
+run relevant tests
+Truth Sync triggers before the agent finishes
+review the truth-doc diff if one was produced
+commit or hand off the work
+```
+
+Truth Sync is code-first: code leads, truth docs follow, and Truth Sync must not rewrite functional code. Its main job is to act as an automatic finish-time safeguard when functional code changed. Direct invocation is mainly for troubleshooting, forcing an early sync before handoff, or running the workflow intentionally.
+
+Codex users can invoke it with `/truthmark-sync` or `$truthmark-sync`. OpenCode-style hosts can invoke `/skill truthmark-sync`.
+
+### Doc-first changes
+
+Use this when a product or architecture decision starts in docs:
+
+```text
+user edits truth docs
+user explicitly invokes Truth Realize
+agent reads truth docs and relevant code
+agent updates code only
+run relevant tests
+commit or hand off the work
+```
+
+Truth Realize is manual and doc-first: truth docs lead, code follows, and the agent must not edit the truth docs it is realizing.
+
+Codex users can invoke it with `/truthmark-realize` or `$truthmark-realize`. OpenCode-style hosts can invoke `/skill truthmark-realize`.
+
+## What it installs
+
+Truthmark keeps the durable workflow surface small:
+
+- `.truthmark/config.yml` for machine-readable configuration
+- `TRUTHMARK.md` for the branch-local workflow contract
+- `docs/truthmark/areas.md` for the root route index
+- `docs/truthmark/areas/**/*.md` for delegated child route files
+- managed instruction blocks for configured platforms such as `AGENTS.md`, `CLAUDE.md`, Cursor rules, Copilot instructions, and `GEMINI.md`
+- Codex and repo-local skills for Truth Structure, Truth Sync, Truth Realize, and Truth Check
+
+The installed workflow surfaces are the runtime:
+
+- Truth Structure creates or repairs area routing and starter truth docs.
+- Truth Sync keeps mapped truth docs aligned with functional changes.
+- Truth Realize updates code to match truth docs.
+- Truth Check audits repository truth health.
+
+Feature `README.md` files are indexes. Truth Sync is expected to read and update bounded leaf docs for current behavior.
+
+Generated surfaces are managed by Truthmark, include a version marker, and may be refreshed by `truthmark init`.
+
+## Commands
+
+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.
+
+```bash
+truthmark config
+truthmark init
+truthmark check
+truthmark config --json
+truthmark check --json
+```
+
+`config` writes only `.truthmark/config.yml` unless `--stdout` is used.
+
+`init` requires `.truthmark/config.yml`, then installs or refreshes the local workflow files.
+
+`check` validates configuration, authority, routing, decision-bearing docs, frontmatter, internal links, branch scope, and coverage diagnostics.
+
+Truth Structure, Truth Sync, Truth Realize, and Truth Check are installed agent workflows, not top-level daily CLI commands.
+
+## Why it exists
+
+Most AI coding workflows optimize for the next answer. Truthmark optimizes for the next handoff.
+
+It assumes serious teams need:
+
+- branch-specific product truth
+- durable architecture and API decisions
+- explicit ownership between docs and code
+- safe write boundaries for agents
+- ordinary Git diffs that humans can review
+- readable Markdown that teammates can inspect without special tooling
+- truth that travels with the branch instead of living in hidden session state
+- workflows that still work when the package is not installed globally
+
+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.
+
+## Project status
+
+V1 currently provides:
+
+- `truthmark config`
+- `truthmark init`
+- `truthmark check`
+- managed `AGENTS.md` workflow instructions
+- generated Truth Structure, Truth Sync, Truth Realize, and Truth Check skill surfaces for configured agent hosts
+- branch-scope metadata
+- config, authority, routing, decision-structure, frontmatter, link, and polyglot coverage diagnostics
+
+## Documentation
+
+The root README is for people evaluating and trying the package. Detailed functional and business specifications live under `docs/`:
+
+- [Docs index](docs/README.md)
+- [Architecture overview](docs/architecture/overview.md)
+- [API and CLI contracts](docs/features/contracts.md)
+- [Init and scaffold behavior](docs/features/init-and-scaffold.md)
+- [Check diagnostics](docs/features/check-diagnostics.md)
+- [Installed workflows](docs/features/installed-workflows.md)
+- [Repository truth maintenance guide](docs/standards/maintaining-repository-truth.md)
+
+Current behavior belongs in the canonical docs tree above.
+
+## Non-goals
+
+Truthmark V1 is not:
+
+- a hosted service
+- an MCP server
+- a vector database
+- a documentation website generator
+- a CI or PR enforcement product
+- a replacement for tests, code review, or technical leadership
+- an autonomous code rewrite engine
+
+It is a lightweight way to make local AI coding agents respect the truth your team keeps in Git.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/README.ru.md

@@ -0,0 +1,229 @@
+# Truthmark это слой истины для разработки ПО с ИИ.
+
+[English](README.md) | [Deutsch](README.de.md) | [中文](README.zh.md) | [Español](README.es.md) | Русский
+
+ИИ-агенты для разработки уже неплохо пишут код. Но они все еще плохо восстанавливают намерения продукта, архитектурные границы и зоны ответственности в репозитории по устаревшей документации, разрозненным чатам и недолговечной памяти инструментов.
+Truthmark решает эту проблему: он превращает истину репозитория, локальную для ветки, в полноценную поверхность выполнения для агентов. Он устанавливает прямо в репозиторий Git-native слой истины с областью действия в пределах ветки, задает агентам явные границы маршрутизации и рабочих процессов и делает так, чтобы эта истина двигалась вместе с кодом, который действительно будет поставлен.
+Это не более удачная инженерия промптов. Это более управляемый способ использовать ИИ в настоящей кодовой базе: меньше повторных решений, меньше устаревшей документации, чище передача работы и сессии с ИИ, после которых остаются проверяемые инженерные записи, а не только следы в истории промптов или непрозрачном состоянии инструментов.
+Для команд, которые уже знают, что агенты умеют генерировать код, и теперь хотят, чтобы сам репозиторий оставался понятным, проверяемым и управляемым.
+
+## Что решает Truthmark
+
+Начать писать код с ИИ сейчас легко, но управлять этим дорого. Как только агенты начинают быстро писать код, истина репозитория становится поверхностью управления.
+Этот сбой проявляется предсказуемо: требования остаются в чатах, архитектурные решения принимаются заново, агенты трогают не те области, а ветки наследуют контекст, который ревьюеры не могут надежно проверить. Код может двигаться быстро, но репозиторию становится труднее доверять.
+Truthmark меняет рабочую модель:
+
+- Истина, локальная для ветки, путешествует вместе с веткой, а не живет в приватном хранилище инструмента.
+- Git делает эту истину проверяемой, сравнимой в diff и доступной всей команде.
+- Документация следует за кодом, а не тихо превращается в вымысел.
+- Маршрутизация остается явной в `docs/truthmark/areas.md` и делегированных дочерних файлах маршрутов, чтобы агенты понимали, какая документация отвечает за какой код.
+- Активные продуктовые и архитектурные решения живут в канонических документах, которыми они управляют, а не в планировочных журналах с временными метками.
+- Local-first рабочие процессы не требуют демона, базы данных, удаленного сервиса или MCP-зависимости.
+- Модель работает в кодовых базах на JavaScript, TypeScript, Go, Python, C# и Java.
+
+Для технических лидеров ценность в управлении без показухи: тесты, ревью кода и владение зонами ответственности по-прежнему делают основную работу; Truthmark делает контекст агента долговечным, проверяемым и ограниченным веткой.
+
+## Где уместен Truthmark
+
+Truthmark не пытается заменить все остальные инструменты для ИИ-процессов. Он занимает конкретный слой в стеке:
+
+| Если вам нужно                                                                                   | Лучший выбор                                   |
+| ------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
+| Лучшие результаты в одной сессии разработки                                                      | Более точные промпты и лучше очерченная задача |
+| Удобная преемственность между сессиями для одного агента или оператора                           | Инструменты памяти                             |
+| Spec-first планирование новых функций                                                            | Инструменты спецификаций, например Spec Kit    |
+| Проверяемая истина репозитория с областью действия в пределах ветки, которая идет вместе с кодом | Truthmark                                      |
+
+Смысл не в том, что промпты, память или спецификации бесполезны. Смысл в том, что ни один из этих подходов сам по себе не превращает истину репозитория в зафиксированный в Git, проверяемый актив, который переживает передачу работы, ревью и расхождение веток.
+
+## Содержание
+
+- [Что решает Truthmark](#что-решает-truthmark)
+- [Где уместен Truthmark](#где-уместен-truthmark)
+- [Рабочая поверхность](#рабочая-поверхность)
+- [Начало работы](#начало-работы)
+- [Как он работает](#как-он-работает)
+- [Что он устанавливает](#что-он-устанавливает)
+- [Команды](#команды)
+- [Зачем он существует](#зачем-он-существует)
+- [Статус проекта](#статус-проекта)
+- [Документация](#документация)
+- [Не-цели](#не-цели)
+- [Лицензия](#лицензия)
+
+## Рабочая поверхность
+
+Truthmark превращает истину репозитория в явную рабочую поверхность для агентов:
+
+- `TRUTHMARK.md` определяет контракт рабочего процесса, локальный для ветки.
+- `docs/truthmark/areas.md` и делегированные дочерние файлы маршрутов сопоставляют области кода с документами, которые за них отвечают.
+- Truth Sync поддерживает синхронизацию сопоставленных документов истины при функциональных изменениях.
+- Truth Realize дает изменениям, начинающимся с документации, ограниченный путь для обновления кода.
+- `truthmark check` валидирует получившиеся артефакты истины.
+- Вся модель остается local-first и Git-native.
+
+Главное обещание такое: контекст агента становится зафиксированным состоянием репозитория, а не приватным артефактом отдельной сессии.
+
+## Начало работы
+
+Чтобы попробовать Truthmark на другом локальном репозитории до публикации пакета где-либо еще:
+
+```bash
+cd /path/to/truthmark
+npm install
+npm run build
+cd /path/to/your-repo
+node /path/to/truthmark/dist/main.js config
+node /path/to/truthmark/dist/main.js init
+node /path/to/truthmark/dist/main.js check
+```
+
+Проверьте `.truthmark/config.yml` перед `init`; это зафиксированный в Git контракт иерархии. После `init` проверьте сгенерированную рабочую поверхность и файлы маршрутов, чтобы маршрутизированная документация действительно совпадала с документами, которые отвечают за ваш код:
+
+```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
+AGENTS.md
+CLAUDE.md
+skills/truthmark-structure/SKILL.md
+skills/truthmark-sync/SKILL.md
+skills/truthmark-realize/SKILL.md
+skills/truthmark-check/SKILL.md
+```
+
+Если вы включите дополнительные платформы в `.truthmark/config.yml`, Truthmark обновит соответствующие управляемые поверхности при следующем `init`.
+Стандартная шаблонная структура использует `README.md` функциональных разделов как индексы и начинает описывать истину текущего поведения в ограниченных листовых документах, например `docs/features/repository/overview.md`.
+
+## Как он работает
+
+Truthmark не задает, какой именно подагент должен запускать Truth Sync. Действующий агент и среда хоста сами решают, делегировать работу или выполнить процесс на месте.
+Большинству пользователей не нужно вызывать Truth Sync напрямую. Нормальный путь выглядит так:
+
+```text
+агент изменяет функциональный код
+запускаются релевантные тесты
+Truth Sync срабатывает до завершения работы агента
+если был создан diff документов истины, он проверяется
+работа коммитится или передается дальше
+```
+
+Truth Sync работает по принципу code-first: сначала идет код, затем документы истины, и Truth Sync не должен переписывать функциональный код. Его основная задача быть автоматической финальной проверкой, когда менялся функциональный код. Прямой вызов нужен в основном для отладки, ранней синхронизации перед передачей работы или намеренного запуска рабочего процесса.
+Пользователи Codex могут вызывать его через `/truthmark-sync` или `$truthmark-sync`. Хосты в стиле OpenCode могут использовать `/skill truthmark-sync`.
+Используйте этот путь, когда продуктовое или архитектурное решение начинается в документации:
+
+```text
+пользователь редактирует документы истины
+пользователь явно вызывает Truth Realize
+агент читает документы истины и связанный код
+агент обновляет только код
+запускаются релевантные тесты
+работа коммитится или передается дальше
+```
+
+Truth Realize это ручной процесс по принципу doc-first: документы истины идут первыми, код следует за ними, и агент не должен редактировать документы истины, которые он реализует.
+Пользователи Codex могут вызывать его через `/truthmark-realize` или `$truthmark-realize`. Хосты в стиле OpenCode могут использовать `/skill truthmark-realize`.
+
+## Что он устанавливает
+
+Truthmark намеренно держит постоянную рабочую поверхность маленькой:
+
+- `.truthmark/config.yml` для машиночитаемой конфигурации
+- `TRUTHMARK.md` для контракта рабочего процесса, локального для ветки
+- `docs/truthmark/areas.md` для корневого индекса маршрутов
+- `docs/truthmark/areas/**/*.md` для делегированных дочерних файлов маршрутов
+- управляемые блоки инструкций для настроенных платформ, таких как `AGENTS.md`, `CLAUDE.md`, правила Cursor, инструкции Copilot и `GEMINI.md`
+- Codex- и repo-local skills для Truth Structure, Truth Sync, Truth Realize и Truth Check
+
+Установленные рабочие поверхности и есть среда выполнения:
+
+- Truth Structure создает или исправляет маршрутизацию областей и стартовые документы истины.
+- Truth Sync поддерживает синхронизацию сопоставленных документов истины с функциональными изменениями.
+- Truth Realize обновляет код так, чтобы он соответствовал документам истины.
+- Truth Check аудитирует здоровье истины репозитория.
+
+`README.md` функциональных разделов это индексы. Ожидается, что Truth Sync будет читать и обновлять ограниченные листовые документы для текущего поведения.
+
+Сгенерированные поверхности управляются Truthmark, содержат маркер версии и могут обновляться через `truthmark init`.
+
+## Команды
+
+Truthmark V1 намеренно держит CLI небольшим. В нижестоящих репозиториях `truthmark config` создает зафиксированный контракт иерархии, `truthmark init` устанавливает и обновляет рабочие поверхности на основе этой проверенной конфигурации, а `truthmark check` валидирует артефакты истины для ручных аудитов, CI или отладки.
+
+```bash
+truthmark config
+truthmark init
+truthmark check
+truthmark config --json
+truthmark check --json
+```
+
+`config` пишет только `.truthmark/config.yml`, если не используется `--stdout`.
+`init` требует `.truthmark/config.yml`, а затем устанавливает или обновляет локальные файлы рабочих процессов.
+`check` валидирует конфигурацию, полномочия, маршрутизацию, документы с решениями, frontmatter, внутренние ссылки, область действия ветки и диагностику покрытия.
+Truth Structure, Truth Sync, Truth Realize и Truth Check это установленные агентские рабочие процессы, а не повседневные CLI-команды верхнего уровня.
+
+## Зачем он существует
+
+Большинство ИИ-процессов для разработки оптимизируют следующий ответ. Truthmark оптимизирует следующую передачу работы.
+Он исходит из того, что серьезным командам нужны:
+
+- продуктовая истина, специфичная для ветки
+- долговечные архитектурные и API-решения
+- явная ответственность между документацией и кодом
+- безопасные границы записи для агентов
+- обычные Git diff, которые могут проверить люди
+- читаемый Markdown, который команда может просматривать без специальных инструментов
+- истина, которая путешествует вместе с веткой, а не живет в скрытом состоянии сессии
+- рабочие процессы, которые продолжают работать, даже если пакет не установлен глобально
+
+## Статус проекта
+
+Truthmark не является сервером памяти и не является MCP-сервером. Это репозиторная практика, упакованная как небольшой CLI-установщик и родные для агентов рабочие поверхности.
+V1 сейчас предоставляет:
+
+- `truthmark config`
+- `truthmark init`
+- `truthmark check`
+- управляемые инструкции рабочих процессов в `AGENTS.md`
+- сгенерированные skill-поверхности Truth Structure, Truth Sync, Truth Realize и Truth Check для настроенных агентских хостов
+- метаданные области ветки
+- диагностика конфигурации, полномочий, маршрутизации, структуры решений, frontmatter, ссылок и полиглотного покрытия
+
+Не следует считать, что пакет `truthmark` без scope уже опубликован.
+
+## Документация
+
+Корневой README предназначен для людей, которые оценивают и пробуют пакет. Подробные функциональные и бизнес-спецификации находятся в `docs/`:
+
+- [Индекс документации](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)
+- [Руководство по поддержанию истины репозитория](docs/standards/maintaining-repository-truth.md)
+
+Текущее поведение должно жить в каноническом дереве документации выше.
+
+## Не-цели
+
+Truthmark V1 не является:
+
+- размещенным сервисом
+- MCP-сервером
+- векторной базой данных
+- генератором сайтов документации
+- продуктом принудительного контроля для CI или PR
+- заменой тестов, code review или технического лидерства
+- автономным движком для переписывания кода
+
+Это легкий способ заставить локальных ИИ-агентов для разработки уважать истину, которую ваша команда хранит в Git.
+
+## Лицензия
+
+MIT. См. [LICENSE](LICENSE).