truthmark 1.2.3 → 1.4.0

package/README.zh.md

@@ -1,6 +1,6 @@
 # Truthmark
 
-**Truthmark 为 AI 软件开发自动维护仓库事实。**
+**Truthmark 为 AI 软件开发安装仓库事实工作流。**
 
 [English](README.md) | [Deutsch](README.de.md) | 中文 | [Español](README.es.md) | [Русский](README.ru.md)
 
@@ -8,14 +8,14 @@
 
 AI 编码代理已经能很快写代码了。真正昂贵的是让仓库事实和实际变更保持一致。
 
-Truthmark 在这个流程里加入了一个自动收尾保护。正常路径很简单：
+Truthmark 在这个流程里加入了一个收尾阶段的工作流保护。正常路径很简单：
 
 - 代理修改功能代码
 - 运行相关测试
-- 代理结束前，Truth Sync 更新已映射的事实文档
+- 代理结束前，已安装的 Truth Sync 工作流更新已映射的事实文档
 - 如果产生了事实文档 diff，就审查它
 
-大多数工具要求团队养成一种习惯。Truthmark 把这个习惯自动化。
+大多数工具要求团队养成一种习惯。Truthmark 把这个习惯变成仓库工作流基础设施。
 
 Truthmark 把 AI 工作流变成仓库基础设施，而不是个人工具配置。它把一个 Git 原生、按分支生效的事实层安装到仓库里，为代理提供明确的路由和有边界的工作流载体，并让这些事实继续以 Git diff 的形式可审查，而不是散落在提示历史、陈旧文档或私有工具状态里。
 
@@ -51,12 +51,12 @@ Truthmark 把 AI 工作流变成仓库基础设施，而不是个人工具配置
 
 Truthmark 不是为了让代理显得更聪明，而是为了让 AI 辅助的仓库变更更值得信任。
 
-- 代码变更后的自动 Truth Sync，把文档维护从团队习惯变成工作流保护。
+- 代码变更后的已安装 Truth Sync 工作流，把文档维护从团队习惯变成工作流保护。
 - 按分支生效的事实会跟着代码一起走，所以审查者可以在普通 Git diff 里检查当前事实。
 - 仓库原生的工作流载体让推广更轻、交接更稳，不再只依赖个人本地配置。
 - `docs/truthmark/areas.md` 和委托的子路由文件里的显式路由，为代理提供更清晰的所有权边界和更安全的写入路径。
 - 本地优先的运行方式避免了守护进程、数据库、远程服务或 MCP 依赖。
-- 这个模型适用于 JavaScript、TypeScript、Go、Python、C# 和 Java 代码库。
+- 路由模型与语言无关，并为常见的 JavaScript、TypeScript、Go、Python、C# 和 Java 代码表面提供覆盖率诊断。
 
 对技术负责人来说，它的价值是没有额外基础设施负担的治理：测试、代码审查和所有权仍然承担真正的工作；Truthmark 让代理上下文变得持久、可检查，并且限定在当前分支内。
 
@@ -96,6 +96,7 @@ Truthmark 把仓库事实变成代理可见的显式工作流载体：
 - `docs/truthmark/areas.md` 和委托的子路由文件把代码区域映射到负责它们的文档。
 - Truth Document 在无需修改代码时，为已实现行为生成或修复规范事实文档。
 - Truth Sync 在功能性变更发生时，让已映射的事实文档保持同步。
+- Truth Preview 在编辑前预览可能的工作流路由，但不授权写入。
 - Truth Realize 为文档优先的变更提供有边界的代码更新路径。
 - `truthmark check` 验证最终形成的事实产物。
 - 整个模型保持本地优先和 Git 原生。
@@ -132,17 +133,17 @@ node /path/to/truthmark/dist/main.js check
 .truthmark/config.yml
 docs/truthmark/areas.md
 docs/truthmark/areas/repository.md
-docs/templates/feature-doc.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` 之后做一次清理：当生成的 `repository` 路由过宽、所有权跨越多个产品或服务，或路由文件仍指向占位文档时，运行已安装的 Truth Structure 工作流。Truth Structure 会拆分过宽的路由，创建或修复初始的规范事实文档，并在功能代码工作开始前为 Truth Sync 提供精确目标。Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-structure` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-structure` 调用它。
 
@@ -150,51 +151,88 @@ GEMINI.md
 
 Truthmark 最强的地方是默认路径，而不是一堆手动命令。由实际执行的代理和宿主环境决定是委托执行，还是内联运行已安装的工作流。
 
-当行为已经实现但规范事实文档缺失或质量较弱时，使用 Truth Document。代理会读取实现、测试、路由和现有文档，只写事实文档和路由，不能修改功能代码。Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-document` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-document` 调用它。
+### 已实现但无文档的行为
 
-多数用户不需要直接调用 Truth Sync。关键在于，只要功能代码发生变化，Truth Sync 就会充当自动收尾保护。正常路径是：
+当实现已经存在，但规范事实文档缺失或较弱时，使用这个流程：
+
+```text
+用户识别一个已实现的行为或 API 端点
+用户显式调用 Truth Document
+代理读取实现、测试、路由和现有文档
+代理只写 truth docs 和路由
+审查 truth-doc diff
+```
+
+Truth Document 是手动、implementation-first 的流程：代码作为证据，事实文档被创建或修复，且不能修改功能代码。Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-document` 调用它；OpenCode 风格的宿主可以用 `/skill truthmark-document` 调用它。
+
+```text
+/truthmark-document 在 docs/truth/authentication 下记录已实现的会话超时行为
+```
+
+### 常规代码变更
+
+多数用户不需要直接调用 Truth Sync。关键在于，只要功能代码发生变化，已安装的代理工作流就会把 Truth Sync 当作收尾保护。正常路径是：
 
 ```text
 代理修改功能代码
 运行相关测试
-代理结束前触发 Truth Sync
-如果生成了事实文档 diff，就审查它
+已安装的 Truth Sync 工作流在代理结束前运行
+如果生成了 truth-doc diff，就审查它
 提交或交接工作
 ```
 
-Truth Sync 是 code-first：代码在前，事实文档跟随，且 Truth Sync 不能重写功能代码。它的主要职责是在功能代码发生变化时，作为收尾阶段的自动安全检查。直接调用主要用于排查问题、交接前提前同步，或有意运行这套工作流。
+Truth Sync 是 code-first：代码在前，事实文档跟随，且 Truth Sync 不能重写功能代码。它的主要职责是在功能代码发生变化时，通过已安装的代理工作流充当收尾保护。直接调用主要用于排查问题、交接前提前同步，或有意运行这套工作流。
+
 Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-sync` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-sync` 调用它。
+
+```text
+/truthmark-sync 现在同步仓库 truth，然后再交接
+```
+
+### 文档优先变更
+
 当产品或架构决策从文档开始时，使用这个流程：
 
 ```text
-用户编辑事实文档
+用户编辑 truth docs
 用户显式调用 Truth Realize
-代理读取事实文档和相关代码
+代理读取 truth docs 和相关代码
 代理只更新代码
 运行相关测试
 提交或交接工作
 ```
 
 Truth Realize 是手动、文档优先的流程：事实文档在前，代码跟随，代理不能编辑它正在实现的事实文档。
+
 Codex、Claude Code 和支持的 Copilot IDE 可以用 `/truthmark-realize` 调用它。OpenCode 风格的宿主可以用 `/skill truthmark-realize` 调用它。
 
+```text
+/truthmark-realize 将 docs/truth/authentication/session-timeout.md 实现为代码
+```
+
 ## 它会安装什么
 
 Truthmark 把持久化的工作流载体保持得很小，而且是仓库原生的。运行 `truthmark init` 之后，仓库本身就携带路由、规则和已安装的工作流载体，因此团队不再只依赖某个人的本地配置。
 
-- `.truthmark/config.yml`，用于机器可读配置
-- `.truthmark/config.yml`，用于已提交的层级契约
+Truthmark 会安装两类不同入口：
+
+- 面向人的 CLI 命令，由人或 CI 运行，用来配置仓库、刷新已安装文件、验证 truth artifacts，并可选生成派生的审查上下文
+- 面向代理的工作流载体，由编码代理或代理宿主在实现工作流中调用；它们不是给人每天在终端里额外运行的命令
+
+- `.truthmark/config.yml`，用于机器可读的已提交层级契约
 - `docs/truthmark/areas.md`，用于根路由索引
 - `docs/truthmark/areas/**/*.md`，用于委托的子路由文件
-- `docs/templates/feature-doc.md`，用于生成工作流采用的可编辑功能文档标准
+- `docs/templates/behavior-doc.md` 以及 `docs/templates/` 下其他按类型划分的模板，用作生成工作流采用的可编辑 truth doc 标准
 - 面向已配置平台的受管说明块，例如 `AGENTS.md`、`CLAUDE.md`、Copilot 指令和 `GEMINI.md`
-- 面向 Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 的宿主原生技能、提示或命令
+- 面向 Truth Structure、Truth Document、Truth Sync、Truth Preview、Truth Realize 和 Truth Check 的宿主原生技能、提示或命令
+- `.codex/agents/`、`.claude/agents/`、`.github/agents/` 和 `.opencode/agents/` 下项目级 Codex、Claude Code、GitHub Copilot 与 OpenCode 只读验证器，以及在宿主支持代理时使用的租约式 `truth-doc-writer` 代理，用于工作流自有审计和父代理租约授权的文档分片
 
 安装后的工作流载体就是运行时：
 
 - Truth Structure 创建或修复区域路由和起始事实文档。
 - Truth Document 为已实现行为创建或修复事实文档。
 - Truth Sync 在功能性变更发生时，让已映射的事实文档保持同步。
+- Truth Preview 在编辑前预览可能的工作流路由，但不写入文件。
 - Truth Realize 更新代码，使其符合事实文档。
 - Truth Check 审计仓库事实的健康状况。
 
@@ -204,20 +242,33 @@ Truthmark 把持久化的工作流载体保持得很小，而且是仓库原生
 
 ## 命令
 
-Truthmark V1 有意保持 CLI 很小，因为持续运行的工作流应该活在已安装的代理载体里，而不是一长串日常手动命令里。在下游仓库中，`truthmark config` 创建已提交的层级契约，`truthmark init` 根据这份已审查的配置安装和刷新工作流载体，`truthmark check` 则为人工审计、CI 或问题排查验证事实产物。
+Truthmark V1 会保持终端 CLI 聚焦。大多数人类用户只需要设置、刷新和验证：
 
-```bash
-truthmark config
-truthmark init
-truthmark check
-truthmark config --json
-truthmark check --json
-```
+| 面向人的 CLI | 用途 |
+| ------------ | ---- |
+| `truthmark config` | 创建 `.truthmark/config.yml`；除非使用 `--stdout`，否则只写入这个文件。 |
+| `truthmark init` | 根据已审查配置安装或刷新本地工作流文件。 |
+| `truthmark check` | 验证配置、权限边界、路由、承载决策的文档、frontmatter、内部链接、分支范围和覆盖率诊断。 |
+
+其余 CLI 命令是可选的仓库情报辅助工具。它们为当前 checkout 生成派生审查上下文；它们不是事实来源：
 
-`config` 只写入 `.truthmark/config.yml`，除非使用 `--stdout`。
-`init` 需要 `.truthmark/config.yml`，然后安装或刷新本地工作流文件。
-`check` 验证配置、权限边界、路由、承载决策的文档、frontmatter、内部链接、分支范围和覆盖率诊断。
-Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 是已安装的代理工作流，不是日常使用的顶层 CLI 命令。
+| 可选 CLI | 用途 |
+| -------- | ---- |
+| `truthmark index` | 为当前 checkout 构建 RepoIndex 和 RouteMap JSON。 |
+| `truthmark impact --base <ref>` | 把变更文件映射到已路由的 truth docs、所属路由、附近测试和 public symbols。 |
+| `truthmark context --workflow <workflow> [--base <ref>]` | 为 Truth Sync、Truth Document 或 Truth Realize 生成受限的 ContextPack。`--format markdown` 会把它渲染成可读文本。 |
+
+上面所有 CLI 命令在需要结构化输出用于自动化时都支持 `--json`。
+
+Truth Structure、Truth Document、Truth Sync、Truth Preview、Truth Realize 和 Truth Check 是已安装的代理工作流，不是日常使用的顶层 CLI 命令。
+
+它们通过已配置的代理宿主表面运行，例如 Codex/Claude/Copilot 的 `/truthmark-*`、OpenCode 的 `/skill truthmark-*`，或者 Gemini 的 `/truthmark:*`。
+
+这些调用看起来像命令，是因为代理宿主会通过 slash commands 暴露技能。应把它们当作给代理的指令，而不是人类需要在终端中运行的 Truthmark CLI 命令。
+
+```text
+/truthmark-check 在 review 前审计路由和 truth 覆盖
+```
 
 ## 它为什么存在
 
@@ -236,15 +287,20 @@ Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check
 ## 项目状态
 
 Truthmark 不是记忆服务器，也不是 MCP 服务器。它是一套仓库实践，被打包成一个小型 CLI 安装器和代理原生的工作流载体，用来把 AI 工作流规则变成仓库基础设施。
+
 V1 目前提供：
 
 - `truthmark config`
 - `truthmark init`
 - `truthmark check`
+- `truthmark index`
+- `truthmark impact`
+- `truthmark context`
 - 受管的 `AGENTS.md` 工作流说明
-- 为已配置代理宿主生成的 Truth Structure、Truth Document、Truth Sync、Truth Realize 和 Truth Check 技能载体
+- 为已配置代理宿主生成的 Truth Structure、Truth Document、Truth Sync、Truth Preview、Truth Realize 和 Truth Check 技能载体
 - 分支范围元数据
 - 配置、权限边界、路由、决策结构、frontmatter、链接和多语言覆盖率诊断
+- RepoIndex、RouteMap、ImpactSet 和 ContextPack 派生产物，可在 CLI 可用时加快本地检查
 
 ## 文档
 
@@ -252,10 +308,10 @@ V1 目前提供：
 
 - [文档索引](docs/README.md)
 - [架构概览](docs/architecture/overview.md)
-- [API 和 CLI 契约](docs/features/contracts.md)
-- [Init 和脚手架行为](docs/features/init-and-scaffold.md)
-- [Check 诊断](docs/features/check-diagnostics.md)
-- [已安装工作流](docs/features/installed-workflows.md)
+- [API 和 CLI 契约](docs/truth/contracts.md)
+- [Init 和脚手架行为](docs/truth/init-and-scaffold.md)
+- [Check 诊断](docs/truth/check-diagnostics.md)
+- [已安装工作流](docs/truth/workflows/overview.md)
 - [仓库事实维护指南](docs/standards/maintaining-repository-truth.md)
 
 当前行为应放在上面的规范文档树中。