ssot

ssot — 单一事实来源与文档维护者

操作不变量

• 权威依据：为每条规则、契约或概念准确指定一个权威所有者；禁止在不同文档中重复设置或设置相互竞争的权威来源。将文件夹路径和文件元数据视为证据，而非权威性的证明。
• 只读检查规范：对于搜索、导航或仅审计请求，检查并报告权威文件、章节和发现；在这些模式下保持文档不变。
• 范围规范：仅处理获准的文档文件，并使用相对于仓库的 POSIX 链接；禁止修改代码库、使用主机绝对路径或 file:/// URI。
• 变更前关卡：以 Changeset 格式（[CREATE]、[UPDATE]、[MOVE]、[DELETE]）暂存文档变更；具体范围未获授权时，须在编辑前停止；已提供授权时则遵照执行。

领域准则

将每项计划中的文档操作归入以下 4 种原子操作之一，且只能归入其中一种：

• [CREATE]：新增规范性规格说明、ADR、架构或放置映射（docs/README.md）。
• [UPDATE]：补齐事实缺漏、使用简明术语修订现有所有者的内容，或更新前置元数据（updated: YYYY-MM-DD）。
• [MOVE]：将持久内容迁移至指定的规范性所有者；仅当本地阅读需要上游上下文时，才以直接锚点链接（[Doc § N.N](path#anchor)）替换原内容。
• [DELETE]：内容整合至规范性所有者后，清理源文档中的重复内容；或删除没有任何独立价值的过时文档。

执行协议

阶段 1：发现与权威性审计

1. 索引快速通道：检查仓库文档索引（docs/README.md 或 README.md），确认是否已有放置矩阵。参阅本地的 references/document-contract.md，了解生命周期分类法和推荐的目录模板。

2. 深度审计后备流程：如果没有索引或范围较广，则运行本地清单扫描器：

   bash scripts/discover-docs.sh <path_to_repository>
   

3. 只读退出：如果请求仅涉及搜索或审计，则使用指针引用（file:///path#L1-L20）报告权威位置，并立即结束本轮。

4. 矛盾升级关卡：如果规格说明存在冲突或规范性权威不明确：

   • 立即结束本轮。禁止继续进入阶段 2。
   • 使用指针引用（[Doc A:L12] 与 [Doc B:L40]）报告相互冲突的证据。
   • 提出解决方案，并等待人工明确指示后再暂存变更。

阶段 2：暂存与授权关卡

1. 以 Changeset 格式暂存计划中的修改：

   # Changeset: SSOT Documentation Governance (<Target Scope>) [(<optional_docs_root>/)]
   
   |-- docs/<collapsed_subsystem_dir>/
   |   |-- <document_1>.md
   |   |   `-- [<ACTION>] <Specification or canonical update>.
   |   `-- <document_2>.md
   |       `-- [<ACTION>] <Reconciliation or duplicate pruning>:
   |           * <Specific document authority or section update>.
   `-- docs/<deep/path/to/canonical_spec.md>
       `-- [<ACTION>] <Direct leaf spec without redundant folder node>.
   
   Summary: <N> files affected (<C> created, <U> updated, <M> moved, <D> deleted).
   

2. 仅提供高密度的 Changeset 摘要和技术理由。禁止在聊天中倾倒原始文档差异。

3. 暂存范围未获授权时，须在修改文档前停止。具体范围已获授权时，则继续应用变更。

阶段 3：应用与链接验证

1. 收到批准后，将变更应用到磁盘（先完成 [CREATE] 和 [MOVE]，再执行 [DELETE]）。
2. 仅在内容或生命周期发生实质性变更时，才更新 updated: YYYY-MM-DD，并遵循当前生效的文档契约。
3. 验证 Markdown 链接的解析结果和锚点的有效性。
4. 在授权范围内修正链接和锚点问题，并重新验证。如果解析需要新的权威性决定、扩大范围，或无法验证，则报告 UNRESOLVED 并提供证据，同时保留已做的编辑；不得在原范围之外重新设计。