truthmark 1.6.1 → 2.1.0

package/README.zh.md

@@ -1,12 +1,12 @@
 # Truthmark
 
-**你的代理会写代码。Truthmark 让它们的上下文在 Git 中可审查。**
+**你的代理会写代码。Truthmark 维护面向人、可在 Git 中审查的文档。**
 
 [English](README.md) | [Deutsch](README.de.md) | 中文 | [Español](README.es.md) | [Русский](README.ru.md)
 
 ![Truthmark 横幅](docs/assets/truthmark-banner.png)
 
-AI 编码代理改变仓库的速度，可能比人类对齐上下文的速度更快。
+AI 编码代理改变仓库的速度，可能比人类对齐文档的速度更快。
 
 Truthmark 修复代码写完后通常会坏掉的那一部分：仓库事实。
 
@@ -26,16 +26,16 @@ Truthmark 修复代码写完后通常会坏掉的那一部分：仓库事实。
 
 AI 编码代理很擅长产出代码。这会制造一种新的失效模式。
 
-实现改变了，但仓库叙事开始漂移：
+实现改变了，但仓库说明开始漂移：
 
 - 行为存在于聊天历史里
 - 架构文档落后
 - 产品决策在交接后消失
-- 审查者看到代码 diff，却看不到相关的事实 diff
+- 审查者看到代码 diff，却看不到相关的事实文档 diff
 - 分支悄悄发展出不同版本的“什么是真的”
-- 每个代理会话都必须从头重新发现上下文
+- 每个代理会话都必须从头重新发现仓库事实
 
-Truthmark 把这种脆弱上下文变成已提交的仓库基础设施。
+Truthmark 把这种脆弱的仓库事实变成已提交的仓库基础设施。
 
 它不是依赖每个人和每个代理都记住正确的文档习惯，而是把这个习惯安装进仓库。
 
@@ -50,23 +50,23 @@ Truthmark 的正常路径是：
 运行相关测试
 Truth Sync 检查已映射的事实文档
 需要时更新事实文档
-人类审查代码 diff + 事实 diff
+人类审查代码 diff + 事实文档 diff
 提交或交接
 ```
 
 核心价值是：**AI 工作更容易被信任，因为仓库仍然清晰可读。**
 
-## 两个表面，一个事实系统
+## 两个接口，一个事实系统
 
 Truthmark 不只是一个 CLI。
 
-它有两个不同表面，这个区别很重要。
+它有两个不同接口，这个区别很重要。
 
 ### 1. 面向人的 CLI
 
 CLI 面向维护者、审查者和自动化。
 
-用它来配置仓库、安装或刷新工作流文件、验证事实产物，并生成可选的审查上下文。
+用它来配置仓库、安装或刷新工作流文件、验证事实产物，并生成可选的审查材料。
 
 ```bash
 truthmark config
@@ -78,11 +78,11 @@ CLI 会准备并验证仓库环境。
 
 它不是 AI 工作流运行时。
 
-### 2. 面向 AI 的工作流表面
+### 2. 面向 AI 的工作流接口
 
-面向 AI 的表面是给编码代理使用的。
+面向 AI 的接口是给编码代理使用的。
 
-Truthmark 会安装宿主原生的技能、提示、命令、受管说明块和受支持的子代理表面，让 AI 代理能在正常编码工具中遵循仓库专属的事实工作流。
+Truthmark 会安装宿主原生的技能、提示、命令、受管指令块和受支持的子代理接口，让 AI 代理能在正常编码工具中遵循仓库专属的事实工作流。
 
 示例：
 
@@ -101,7 +101,7 @@ Truthmark 会安装宿主原生的技能、提示、命令、受管说明块和
 
 它们是面向 AI 的工作流入口。
 
-这种拆分就是产品：
+这种拆分正是 Truthmark 的产品边界：
 
 ```text
 人类拥有仓库契约
@@ -142,7 +142,7 @@ truthmark config
 
 继续之前先审查这个文件。它定义仓库中已提交的层级契约。
 
-### 安装工作流表面
+### 安装工作流接口
 
 ```bash
 truthmark init
@@ -152,8 +152,8 @@ truthmark init
 
 - 路由文件
 - 事实文档脚手架
-- 受管说明块
-- 已配置平台的面向 AI 工作流表面
+- 受管指令块
+- 已配置平台的面向 AI 工作流接口
 
 默认事实文档模板的依据见 [Template Standards](docs/standards/template-standards.md)。该文档说明这些模板如何对齐 ISO/IEC/IEEE 42010、ISO/IEC/IEEE 29148、ISO/IEC/IEEE 12207、ISO/IEC 25010、C4、arc42、OpenAPI、SemVer、Google SRE 和 Diátaxis 等公认软件工程参考。
 
@@ -165,9 +165,7 @@ truthmark check
 
 然后在提交前审查生成的文件。
 
-具体文件取决于 `.truthmark/config.yml`，但安装形态始终相同：路由、truth scaffolding、紧凑的受管说明，以及为启用平台生成的 host-native 工作流表面。
-
-确切文件取决于 `.truthmark/config.yml`。
+具体文件取决于 `.truthmark/config.yml`，但安装形态始终相同：路由、事实文档脚手架、紧凑的受管指令，以及为启用平台生成的宿主原生工作流接口。
 
 ## 第一次真实使用
 
@@ -181,6 +179,14 @@ truthmark check
 /truthmark-structure 将宽泛的 repository 区域拆成 auth、billing 和 notifications
 ```
 
+如果项目已经有实现好的功能，但事实文档缺失或很弱，请让已安装的 Truth Document 工作流记录一个聚焦范围：
+
+```text
+/truthmark-document 记录 src/billing/retry.ts 及相关测试中已实现的 payment retry 行为
+```
+
+Truth Document 是既有项目最常用的第一个工作流。它会检查实现、测试、路由和现有文档，然后创建或修复事实文档与路由，不会修改功能代码。
+
 之后就正常使用你的 AI 编码代理。
 
 当代理修改功能代码时，Truth Sync 会作为收尾保护，在交接前检查已映射的事实文档是否需要改变。
@@ -190,21 +196,21 @@ truthmark check
 | 能力 | 作用 |
 | --- | --- |
 | Git 原生事实 | 将仓库事实保存在已提交的 Markdown 和配置中。 |
-| 按分支生效的上下文 | 事实随分支移动，而不是存在于私有会话中。 |
+| 按分支生效的文档 | 事实随分支移动，而不是存在于私有会话中。 |
 | 面向人的 CLI | 为维护者提供设置、刷新、验证和检查命令。 |
 | 面向 AI 的工作流 | 为代理提供宿主原生的同步、文档、结构、预览、实现和审计工作流。 |
 | 显式路由 | 将代码区域映射到规范事实文档。 |
 | 可审查交接 | 为代码和事实文档都产生普通 Git diff。 |
 | 本地优先运行 | 不需要托管服务、守护进程、数据库或 MCP 服务器。 |
 | 更安全的写入边界 | 区分 code-first、doc-first、read-only 和 doc-only 工作流。 |
-| 验证 | 报告路由、权限边界、frontmatter、链接、生成表面、分支范围、freshness 和覆盖率问题。 |
+| 验证 | 报告路由、权限边界、frontmatter、链接、生成接口、分支范围、freshness 和覆盖率问题。 |
 | 可选 Portal | 在明确启用并请求时，从 Markdown 事实文档生成已提交的静态 HTML 展示站点。 |
 
 ## 视觉概览
 
 ![Truthmark 功能](docs/assets/truthmark-features.png)
 
-**功能：** Truthmark 会安装什么，以及工作流表面如何拆分。
+**功能：** Truthmark 会安装什么，以及工作流接口如何拆分。
 
 ![Truthmark 定位](docs/assets/truthmark-position.png)
 
@@ -222,7 +228,7 @@ Truthmark 面向已经知道 AI 代理能生成代码的团队。
 
 不是仪式化治理。治理就是一个简单问题：
 
-> 这次 AI 辅助变更之后，仓库还在讲真话吗？
+> 这次 AI 辅助变更之后，仓库仍然准确反映事实吗？
 
 Truthmark 通过已提交文件、显式路由和可审查 diff 帮助团队回答这个问题。
 
@@ -231,10 +237,10 @@ Truthmark 通过已提交文件、显式路由和可审查 diff 帮助团队回
 - 更少的文档漂移
 - 更好的交接
 - 按分支生效的产品事实
-- 持久的架构和 API 上下文
+- 持久的架构和 API 文档
 - 文档与代码之间的明确所有权
 - 更安全的代理写入边界
-- 可审查上下文，而不是隐藏记忆
+- 可审查文档，而不是隐藏记忆层
 - 仍然能从已提交 repo 文件运行的 AI 工作流
 
 ## Truthmark 适合放在哪里
@@ -250,7 +256,7 @@ Truthmark 不替代提示词、记忆、规格、测试或代码审查。
 | plan-first 的功能工作 | 规格工作流 |
 | 随代码移动、按分支生效的事实 | Truthmark |
 | 验证行为正确性 | 测试和审查 |
-| 审查 AI 辅助的上下文变更 | Truthmark 加 Git 审查 |
+| 审查 AI 辅助的文档变更 | Truthmark 加 Git 审查 |
 
 Truthmark 的范围故意很窄：
 
@@ -267,7 +273,7 @@ Truthmark 在本地针对当前 Git worktree 运行。
 
 面向人的 CLI 读取并写入仓库文件，然后退出。
 
-面向 AI 的工作流表面是已提交文件，代理宿主之后可以加载它们。这意味着代理可以从仓库状态遵循已安装工作流，而不依赖后台 Truthmark 进程。
+面向 AI 的工作流接口是已提交文件，代理宿主之后可以加载它们。这意味着代理可以从仓库状态遵循已安装工作流，而不依赖后台 Truthmark 进程。
 
 这些层的关系如下：
 
@@ -285,9 +291,9 @@ flowchart LR
 
 Agent 不会连接 Truthmark daemon，但工作流需要验证、索引或 helper checks 时，它们可以运行已安装的 Truthmark CLI。
 
-Truthmark 拥有它生成的工作流表面，但关键契约是架构层面的：仓库内配置和路由把 agent 指向规范 truth 文档，host-native 工作流则让每个受支持的 agent 用自己的方式运行同一套 Truthmark 流程。
+Truthmark 拥有它生成的工作流接口，但关键契约是架构层面的：仓库内配置和路由把 agent 指向规范 truth 文档，host-native 工作流则让每个受支持的 agent 用自己的方式运行同一套 Truthmark 流程。
 
-生成的工作流表面包含 Truthmark 版本标记。升级 Truthmark 后，重新运行：
+生成的工作流接口包含 Truthmark 版本标记。升级 Truthmark 后，重新运行：
 
 ```bash
 truthmark init
@@ -305,7 +311,7 @@ truthmark init
 truthmark init
 ```
 
-| 平台配置名 | 生成表面 | 调用形式 |
+| 平台配置名 | 生成接口 | 调用形式 |
 | --- | --- | --- |
 | `codex` | Skill packages 和 verifier agents | `/truthmark-*` 或 `$truthmark-*` |
 | `claude-code` | Project skills、verifier agents 和受管说明 | `/truthmark-*` |
@@ -335,14 +341,14 @@ truthmark init
 
 ### 重要区别
 
-不要混淆这两个表面：
+不要混淆这两个接口：
 
-| 表面 | 使用者 | 示例 | 含义 |
+| 接口 | 使用者 | 示例 | 含义 |
 | --- | --- | --- | --- |
 | 面向人的 CLI | 人类、脚本、类似 CI 的检查 | `truthmark check` | 从终端验证仓库事实产物。 |
 | 面向 AI 的工作流 | 编码代理和代理宿主 | `/truthmark-check` | 请求代理运行已安装的审计工作流。 |
 
-名称有意相关，但表面不同。
+名称有意相关，但接口不同。
 
 ## 普通 AI 辅助代码变更
 
@@ -356,7 +362,7 @@ Truth Sync 是为功能代码变更安装的收尾保护。
 已安装工作流检测到功能代码变更
 Truth Sync 检查已映射事实文档
 代理在需要时更新事实文档
-人类审查代码 diff + 事实 diff
+人类审查代码 diff + 事实文档 diff
 ```
 
 直接调用仍然适用于排查问题、强制提前同步，或让交接更明确：
@@ -367,12 +373,16 @@ Truth Sync 检查已映射事实文档
 
 ## 已有行为但没有文档
 
-当实现已经存在，但仓库事实不完整时，使用 Truth Document。
+当实现已经存在但仓库事实不完整时，使用 Truth Document。对于代码库已经存在后才接入 Truthmark 的成熟仓库，这是常规路径。
 
 ```text
-/truthmark-document 在 docs/truth/authentication 下记录已实现的会话超时行为
+/truthmark-document 记录 src/auth/session.ts、src/auth/middleware.ts 和 tests/auth/session.test.ts 中已实现的 session timeout 行为
 ```
 
+提供功能名、代码路径、测试路径或目标事实文档区域。在 OpenCode 风格的宿主中，同一个工作流用 `/skill truthmark-document ...` 调用；在 Gemini CLI 中，使用 `/truthmark:doc ...`。
+
+如果大型仓库仍然只有一个宽泛的占位路由，请先运行 Truth Structure，然后每次针对一个有边界的功能或区域调用 Truth Document。
+
 Truth Document 会把实现、测试、路由文件和现有文档作为证据来检查。
 
 它只写事实文档和路由。
@@ -384,7 +394,7 @@ Truth Document 会把实现、测试、路由文件和现有文档作为证据
 当产品或架构决策从文档开始，并且代码应更新以匹配时，使用 Truth Realize。
 
 ```text
-/truthmark-realize 将 docs/truth/authentication/session-timeout.md 实现到代码中
+/truthmark-realize 将 docs/truthmark/truth/authentication/session-timeout.md 实现到代码中
 ```
 
 Truth Realize 是 doc-first。
@@ -428,10 +438,10 @@ truthmark check
 | 命令 | 用途 |
 | --- | --- |
 | `truthmark config` | 创建 `.truthmark/config.yml`。除非使用 `--stdout`，否则只写这个文件。 |
-| `truthmark init` | 从已审查配置安装或刷新已配置的工作流表面。 |
-| `truthmark check` | 验证配置、权限边界、路由、承载决策的文档、frontmatter、内部链接、分支范围、生成表面、freshness 和覆盖率诊断。 |
+| `truthmark init` | 从已审查配置安装或刷新已配置的工作流接口。 |
+| `truthmark check` | 验证配置、权限边界、路由、承载决策的文档、frontmatter、内部链接、分支范围、生成接口、freshness 和覆盖率诊断。 |
 
-可选的仓库情报辅助工具会为当前 checkout 生成派生审查上下文。生成的工作流 skill packages 也可以暴露 helper manifests 和 helper policies，用来调用已安装的 `truthmark validate ... --json` CLI validators；这些 helpers 是加速器，不是打包进仓库的本地脚本，也不是事实来源。独立的 Copilot prompts 和 Gemini commands 在已安装 runner 可用时使用同一 CLI validator contract；不可用时应报告可见的 skipped helper status，并进行 manual validation。
+可选的仓库情报辅助工具会为当前 checkout 生成派生审查材料，例如 RepoIndex、RouteMap、ImpactSet 和有边界的 ContextPack 产物。生成的工作流 skill packages 也可以暴露 helper manifests 和 helper policies，用来调用已安装的 `truthmark validate ... --json` CLI validators；这些 helpers 是加速器，不是打包进仓库的本地脚本，也不是事实来源。独立的 Copilot prompts 和 Gemini commands 在已安装 runner 可用时使用同一 CLI validator contract；不可用时应报告可见的 skipped helper status，并进行 manual validation。
 
 它们不是事实来源。
 
@@ -439,7 +449,7 @@ truthmark check
 | --- | --- |
 | `truthmark index` | 为当前 checkout 构建 RepoIndex 和 RouteMap JSON。 |
 | `truthmark impact --base <ref>` | 将变更文件映射到已路由事实文档、所属路由、附近测试和公开符号。 |
-| `truthmark context --workflow <workflow> [--base <ref>]` | 为 Truth Sync、Truth Document 或 Truth Realize 生成有边界的 ContextPack。使用 `--format markdown` 生成可读版本。 |
+| `truthmark ctx --workflow <workflow> [--base <ref>]` | 为 Truth Sync、Truth Document 或 Truth Realize 生成有边界的 ContextPack。使用 `--format markdown` 生成可读版本。 |
 
 受支持位置可使用 `--json` 获取结构化输出。
 
@@ -458,10 +468,10 @@ Truthmark Portal 是一个可选的展示工作流，适合想要基于已提交
 用这个命名空间配置块启用它：
 
 ```yaml
-truthmark-portal:
-  enabled: true
-  output: docs/truthmark-portal
-  template: default
+truthmark:
+  generated:
+    portal:
+      enabled: true
 ```
 
 然后重新运行：
@@ -470,7 +480,7 @@ truthmark-portal:
 truthmark init
 ```
 
-启用后，Truthmark 会为已配置平台安装宿主原生 Portal 工作流表面，例如 `/truthmark-portal` 或 `/truthmark:portal`，具体取决于代理宿主。
+启用后，Truthmark 会为已配置平台安装宿主原生 Portal 工作流接口，例如 `/truthmark-portal` 或 `/truthmark:portal`，具体取决于代理宿主。
 
 ## 配置
 
@@ -499,34 +509,34 @@ truthmark init
 | 配置区域 | 用途 |
 | --- | --- |
 | `version` | 配置契约版本。 |
-| `platforms` | 应接收平台专属生成表面的代理宿主。 |
-| `docs.layout` | 当前文档布局模式。 |
-| `docs.roots` | 命名的规范文档根。 |
-| `docs.routing.root_index` | 根路由索引路径。 |
-| `docs.routing.area_files_root` | 委托子路由文件目录。 |
-| `docs.routing.default_area` | 初始脚手架子路由 basename。 |
-| `docs.routing.max_delegation_depth` | 当前最大路由委托深度。 |
-| `truthmark-portal` | 可选手动展示工作流设置：`enabled`、`output` 和 `template`。 |
-| `authority` | 用作仓库事实权威的有序规范文档和 glob。 |
-| `instruction_targets` | 接收共享受管说明块的文件，例如 `AGENTS.md`。 |
+| `platforms` | 应接收平台专属生成接口的代理宿主。 |
+| `truthmark.workspace` | Truthmark 拥有的工作区，用于路由、事实文档、模板和生成的展示输出。 |
+| `truthmark.routes.index` | 相对于 `truthmark.workspace` 的根路由索引路径。 |
+| `truthmark.routes.areas` | 相对于 `truthmark.workspace` 的委托子路由目录。 |
+| `truthmark.routes.default_area` | 初始脚手架子路由 basename。 |
+| `truthmark.routes.max_delegation_depth` | 当前最大路由委托深度。 |
+| `truthmark.truth.root` | 相对于 `truthmark.workspace` 的事实文档根。 |
+| `truthmark.templates.root` | 相对于 `truthmark.workspace` 的事实文档模板根。 |
+| `truthmark.generated.portal` | 可选手动展示工作流启用设置：`enabled`。 |
+| `instruction_targets` | 接收共享受管指令块的文件，例如 `AGENTS.md`。 |
 | `frontmatter.required` | 缺失时产生错误诊断的元数据字段。 |
 | `frontmatter.recommended` | 缺失时产生审查诊断的元数据字段。 |
 | `ignore` | 从相关检查和路由逻辑中排除的 glob 模式。 |
 
 ## 仓库事实路由
 
-Truthmark 将代码表面映射到事实文档。
+Truthmark 将代码区域映射到事实文档。
 
 主要路由文件是：
 
 ```text
-docs/truthmark/areas.md
-docs/truthmark/areas/**/*.md
+docs/truthmark/routes/areas.md
+docs/truthmark/routes/areas/**/*.md
 ```
 
 路由告诉代理：
 
-- 哪个代码表面属于某个区域
+- 哪个代码区域属于某个区域
 - 哪些事实文档拥有该区域
 - 何时应该更新事实
 - 涉及哪类事实文档
@@ -550,13 +560,13 @@ Truthmark 安装一个紧凑、仓库原生的事实层。
 它分为四层安装：
 
 - 用于所有权边界的配置和路由
-- 规范 truth 文档和起始模板
-- 用于仓库级 agent 上下文的紧凑受管说明块
-- 为配置中启用的平台生成 host-native 工作流包、命令、prompts 和 verifier agents
+- 规范事实文档和起始模板
+- 用于仓库级代理指令的紧凑受管指令块
+- 为配置中启用的平台生成宿主原生的工作流包、命令、prompts 和 verifier agents
 
-Truthmark 会保留受管说明块之外的手写内容。
+Truthmark 会保留受管指令块之外的手写内容。
 
-生成的工作流表面由 Truthmark 管理，可以通过重新运行来刷新：
+生成的工作流接口由 Truthmark 管理，可以通过重新运行来刷新：
 
 ```bash
 truthmark init
@@ -635,7 +645,7 @@ truthmark check
 ### 记录已实现行为
 
 ```text
-/truthmark-document 在 docs/truth/authentication 下记录已实现的密码重置流程
+/truthmark-document 在 docs/truthmark/truth/authentication 下记录已实现的密码重置流程
 ```
 
 ### 代码变更后同步
@@ -647,7 +657,7 @@ truthmark check
 ### 实现 doc-first 决策
 
 ```text
-/truthmark-realize 将 docs/truth/billing/invoice-retry-policy.md 实现到代码中
+/truthmark-realize 将 docs/truthmark/truth/billing/invoice-retry-policy.md 实现到代码中
 ```
 
 ### 从终端审计事实健康
@@ -656,25 +666,25 @@ truthmark check
 truthmark check
 ```
 
-### 生成分支影响上下文
+### 生成分支影响摘要
 
 ```bash
 truthmark impact --base main
 ```
 
-### 生成工作流上下文
+### 生成工作流 ContextPack
 
 ```bash
-truthmark context --workflow truth-sync --base main --format markdown
+truthmark ctx --workflow truth-sync --base main --format markdown
 ```
 
 ### 启用可选 Portal 工作流
 
 ```yaml
-truthmark-portal:
-  enabled: true
-  output: docs/truthmark-portal
-  template: default
+truthmark:
+  generated:
+    portal:
+      enabled: true
 ```
 
 ```bash
@@ -692,19 +702,19 @@ Truthmark V1 目前提供：
 - `truthmark check`
 - `truthmark index`
 - `truthmark impact`
-- `truthmark context`
+- `truthmark ctx`
 - 分支范围元数据
-- 受管说明块
-- 生成的 Truth Structure 工作流表面
-- 生成的 Truth Document 工作流表面
-- 生成的 Truth Sync 工作流表面
-- 生成的 Truth Preview 工作流表面
-- 生成的 Truth Realize 工作流表面
-- 生成的 Truth Check 工作流表面
-- 可选生成的 Truthmark Portal 工作流表面
-- 路由、权限边界、决策结构、frontmatter、链接、freshness、生成表面和覆盖率诊断
+- 受管指令块
+- 生成的 Truth Structure 工作流接口
+- 生成的 Truth Document 工作流接口
+- 生成的 Truth Sync 工作流接口
+- 生成的 Truth Preview 工作流接口
+- 生成的 Truth Realize 工作流接口
+- 生成的 Truth Check 工作流接口
+- 可选生成的 Truthmark Portal 工作流接口
+- 路由、权限边界、决策结构、frontmatter、链接、freshness、生成接口和覆盖率诊断
 - 派生的 RepoIndex、RouteMap、ImpactSet 和 ContextPack 产物
-- 面向 Codex、Claude Code、GitHub Copilot、OpenCode 和 Gemini CLI 的宿主专属表面
+- 面向 Codex、Claude Code、GitHub Copilot、OpenCode 和 Gemini CLI 的宿主专属接口
 
 ## 开发
 
@@ -748,11 +758,11 @@ README 是评估和设置的快速路径。
 详细的当前行为位于 `docs/` 下：
 
 - [文档索引](docs/README.md)
-- [架构概览](docs/architecture/overview.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/truthmark/truth/architecture/overview.md)
+- [API 和 CLI 契约](docs/truthmark/truth/contracts.md)
+- [Init 和脚手架行为](docs/truthmark/truth/init-and-scaffold.md)
+- [Check 诊断](docs/truthmark/truth/check-diagnostics.md)
+- [已安装工作流](docs/truthmark/truth/workflows/overview.md)
 - [仓库事实维护指南](docs/standards/maintaining-repository-truth.md)
 
 ## 设计边界
@@ -786,10 +796,10 @@ Truthmark 帮助仓库保持诚实。它不能证明代码正确。
 - 审查事实文档变更
 - 不把 secrets 放进文档
 - 把仓库专属说明保留在受管块之外
-- 升级后审查生成工作流表面的 diff
+- 升级后审查生成工作流接口的 diff
 - 保留人类对产品和架构决策的所有权
 
-Truthmark 让代理上下文可见。它不替代人类判断。
+Truthmark 让面向代理的仓库事实可见。它不替代人类判断。
 
 ## 路线图方向
 
@@ -799,8 +809,8 @@ Truthmark 让代理上下文可见。它不替代人类判断。
 - 更清晰的采用示例
 - 展示真实 Truth Sync 循环的示例仓库
 - 面向已经使用代理说明文件团队的迁移指南
-- 生成宿主表面的符合性测试
-- 感知路由的 stale truth 提示
+- 生成宿主接口的符合性测试
+- 基于路由的 stale truth 提示
 - 面向 doc-first 工作的有边界实现清单
 
 重心保持不变：
@@ -809,7 +819,7 @@ Truthmark 让代理上下文可见。它不替代人类判断。
 仓库事实
 代理原生工作流
 Git 审查
-按分支生效的上下文
+按分支生效的文档
 ```
 
 ## 许可证