ssot(Single Source of Truth & Documentation Custodian)是 venhdev/zenforge 项目下的文档治理技能,用于在仓库文档中维护唯一权威来源、协调冲突规范并审计文档权威性。
用途:
- 审计文档权威归属,确保每个规则、契约或概念只有一个权威所有者,禁止跨文档出现重复或竞争的权威。
- 协调相互冲突的规范,在权威不明时停止并请求人工方向。
- 维护规范的单一事实来源记录,对文档进行创建、更新、移动和删除等治理操作。
主要能力:
- 权威审计:检查文档索引(如 docs/README.md 或 README.md)中的放置矩阵,或使用本地扫描脚本 scripts/discover-docs.sh 进行深度清点。
- 只读检查:对搜索、导航或审计类请求,仅报告权威文件与章节位置并提供指针引用,不修改文档。
- 变更暂存:将计划中的文档变更整理为 Changeset 格式,明确每个文件的操作类型([CREATE]、[UPDATE]、[MOVE]、[DELETE])及摘要。
- 授权门控:在具体范围未获授权时停止修改,已获授权则继续执行。
- 链接验证:应用变更后验证 Markdown 链接解析与锚点有效性,并在授权范围内修正链接问题。
使用方式:
- 先检查仓库文档索引是否存在放置矩阵;无索引或范围较宽时,运行 bash scripts/discover-docs.sh <path_to_repository> 进行文档清点。
- 若仅为搜索或审计,报告权威位置与指针引用后立即停止。
- 遇到规范冲突或权威模糊时,立即停止并报告冲突证据(如 [Doc A:L12] vs [Doc B:L40]),提供解决选项并等待人工指示。
- 将拟定变更以 Changeset 格式呈现,包含受影响文件数及创建、更新、移动、删除数量,等待授权。
- 获得批准后执行磁盘变更(先完成 [CREATE] 和 [MOVE],再执行 [DELETE]),并验证链接与锚点。
适用场景:
- 仓库文档体系需要建立或维护唯一权威来源时。
- 多个规范文档出现冲突或重复权威,需要审计与协调时。
- 需要对文档进行结构化的创建、更新、移动或删除治理时。
限制:
- 仅操作已批准的文档文件,禁止修改代码库。
- 只使用仓库相对 POSIX 链接,禁止使用主机绝对路径或 file:/// URI。
- 需要明确授权后才能执行文档变更;未授权时停止。
- 链接或锚点验证失败若涉及新权威决策或范围扩展,会报告 UNRESOLVED 并保留已有编辑,不进行范围外的重新设计。