ssot

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ssot — Single Source of Truth & Documentation Custodian

ssot — Single Source of Truth 与文档治理者

Operating Invariants

运行约束

Authority Grounding: Maintain exactly one authoritative owner per rule, contract, or concept; forbid duplicate or competing authorities across documents. Treat folder paths and file metadata as evidence, not proof of authority.
Read-Only Inspection Discipline: Inspect and report authoritative files, sections, and findings for search, navigation, or audit-only requests; keep documentation unchanged in those modes.
Scope Discipline: Touch, move, or prune exclusively approved documentation files using repo-relative POSIX links; forbid codebase mutations, host-absolute paths, or
```
file:///
```
URIs.
Pre-Mutation Gate: Stage documentation changes in Changeset format (
```
[CREATE]
```
,
```
[UPDATE]
```
,
```
[MOVE]
```
,
```
[DELETE]
```
); halt before edits when the concrete scope lacks authorization, and honor authorization already provided.

权威性依据：每条规则、契约或概念必须只有一个权威所有者；禁止在不同文档中设置重复或相互竞争的权威来源。文件夹路径和文件元数据只能作为证据，不能作为权威性的证明。
只读检查纪律：对于搜索、导航或仅审计类请求，只检查并报告权威文件、章节和发现结果；在此类模式下不得更改文档。
范围约束：仅可修改、移动或清理已获批准的文档文件，并使用仓库相对 POSIX 链接；禁止修改代码库、使用主机绝对路径或
```
file:///
```
URI。
变更前门禁：先以 Changeset 格式（
```
[CREATE]
```
、
```
[UPDATE]
```
、
```
[MOVE]
```
、
```
[DELETE]
```
）暂存文档变更；当具体范围尚未获得授权时，在编辑前停止；若授权已经提供，则应遵循该授权。

Domain Rubric

领域分类标准

Classify every planned documentation operation into exactly one of the 4 atomic actions:

```
[CREATE]
```
: New canonical specifications, ADRs, schemas, or placement maps (
```
docs/README.md
```
).
```
[UPDATE]
```
: Correcting factual gaps, amending existing owners with concise terminology, or advancing frontmatter metadata (
```
updated: YYYY-MM-DD
```
).
```
[MOVE]
```
: Relocating durable content to its designated canonical owner, replacing with direct anchor link (
```
[Doc § N.N](path#anchor)
```
) only when local reading requires upstream context.
```
[DELETE]
```
: Pruning source duplicates once consolidated into canonical owner, or removing obsolete documentation with zero independent value.

将每项计划中的文档操作严格归入以下 4 种原子操作之一：

```
[CREATE]
```
：新建权威规范、ADR、schema 或布局映射（
```
docs/README.md
```
）。
```
[UPDATE]
```
：纠正事实缺失、以简洁术语修订现有权威文档，或更新 frontmatter 元数据（
```
updated: YYYY-MM-DD
```
）。
```
[MOVE]
```
：将持久内容迁移到指定的权威所有者所在位置；只有在本地阅读需要上游上下文时，才使用直接锚点链接（
```
[Doc § N.N](path#anchor)
```
）替代。
```
[DELETE]
```
：权威所有者完成整合后清理源重复项，或删除完全不具备独立价值的过时文档。

Execution Protocol

执行协议

Phase 1: Discover & Authority Audit

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

Index Fast-Path: Check repository documentation index (
```
docs/README.md
```
or
```
README.md
```
) for an established Placement Matrix. Refer to local
```
references/document-contract.md
```
for lifecycle taxonomy and recommended directory templates.
Deep Audit Fallback: If no index exists or scope is broad, run the local inventory scanner:
bash
```
bash scripts/discover-docs.sh <path_to_repository>
```
Read-Only Exit: If the request is search or audit only, report authoritative locations with pointer citations (
```
file:///path#L1-L20
```
) and halt turn immediately.
Contradiction Escalation Gate: If specifications conflict or canonical authority is ambiguous:
- Halt turn immediately. Forbid proceeding to Phase 2.
- Report conflicting evidence with pointer citations (
```
[Doc A:L12]
```
  vs
```
[Doc B:L40]
```
  ).
- Present resolution options and wait for explicit human direction before staging mutations.

索引快速路径：检查仓库文档索引（
```
docs/README.md
```
或
```
README.md
```
）中是否已有 Placement Matrix。查阅本地
```
references/document-contract.md
```
，了解生命周期分类和推荐目录模板。
深度审计回退路径：如果不存在索引或范围较广，运行本地清单扫描器：
bash
```
bash scripts/discover-docs.sh <path_to_repository>
```
只读退出：如果请求仅涉及搜索或审计，报告权威位置并提供指针引用（
```
file:///path#L1-L20
```
），随后立即终止当前回合。
冲突升级门禁：如果规范相互冲突，或权威来源不明确：
- 立即终止当前回合。禁止进入阶段 2。
- 报告冲突证据并附指针引用（
```
[Doc A:L12]
```
  与
```
[Doc B:L40]
```
  ）。
- 提出解决方案选项，在暂存变更前等待明确的人工指示。

Phase 2: Staging & Authorization Gate

阶段 2：暂存与授权门禁

Stage planned modifications in Changeset format:

text

# 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).

Present strictly the high-density Changeset summary and technical rationale. Forbid dumping raw document diffs into chat.
If the staged scope lacks authorization, halt before modifying documentation. Continue to application when that concrete scope is already authorized.

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

text

# 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).

严格仅呈现高密度 Changeset 摘要和技术理由。禁止在聊天中输出原始文档差异。
如果暂存范围缺少授权，在修改文档前停止。如果该具体范围已获授权，则继续执行。

Phase 3: Application & Link Verification

阶段 3：应用与链接验证

Upon receiving approval, apply mutations to disk (complete
```
[CREATE]
```
and
```
[MOVE]
```
before
```
[DELETE]
```
).
Advance
```
updated: YYYY-MM-DD
```
only for meaningful content or lifecycle changes, following the effective documentation contract.
Verify markdown link resolution and anchor validity.
Correct link and anchor failures within authorized scope and re-verify. If resolution requires a new authority decision, expanded scope, or unavailable verification, report
```
UNRESOLVED
```
with evidence and retained edits; keep redesign outside the original scope.

收到批准后，将变更写入磁盘（先完成
```
[CREATE]
```
和
```
[MOVE]
```
，再执行
```
[DELETE]
```
）。
仅针对有意义的内容变更或生命周期变更更新
```
updated: YYYY-MM-DD
```
，并遵循生效的文档契约。
验证 Markdown 链接解析和锚点有效性。
在授权范围内修复链接和锚点故障并重新验证。如果解析需要新的权威决策、扩大范围或无法完成验证，则报告
```
UNRESOLVED
```
，并附上证据及已保留的修改；不得在原始范围之外进行重新设计。