docs-governance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Documentation Governance Router

文档治理路由

Use this optional router to select the smallest existing ECC capability for a documentation-governance request. The router does not create a parallel project management system and does not make documentation authoritative over code, tests, Issues, or maintainer decisions.

使用这个可选路由为文档治理请求选择现有ECC能力中最匹配的最小粒度能力。该路由不会创建并行的项目管理系统，也不会赋予文档高于代码、测试、Issue或维护者决策的权威性。

When to Activate

何时启用

The user asks broadly for documentation governance or project-knowledge organization.
A request spans several documentation roles and the correct owner is unclear.
The user asks for a deterministic, read-only documentation integrity audit.
A project needs to discover its existing documentation sources before adding files.

Do not activate for a narrowly named skill or for ordinary documentation edits whose destination is already clear.

用户宽泛地提出文档治理或项目知识组织需求。
请求涉及多个文档角色，且无法明确正确的负责人。
用户要求进行确定性的只读文档完整性审计。
项目在添加文件前需要梳理现有的文档来源。

对于已明确指定细分技能的请求，或目标路径清晰的普通文档编辑，请勿启用此路由。

Role Contract

角色契约

Read the artifact-role contract before interpreting

.governance/docs-map.json

or default filenames. Logical roles own facts; filenames are fallbacks. Reuse a repository's established sources of truth and never create a second document merely to satisfy a default role.

在解读

.governance/docs-map.json

或默认文件名之前，请先阅读制品角色契约。逻辑角色负责事实的权威性；文件名仅作为备用。请复用仓库已建立的事实来源，切勿仅为满足默认角色要求而创建重复文档。

Intent Routing

意图路由

User intent	Route to
Adopt or maintain a constitution, map, status, and history spine	`living-docs-governance`
Record a hard-to-reverse architecture decision	`architecture-decision-records`
Preserve an executable regression for an important defect	`ai-regression-testing` (install separately in standalone Pi core)
Define a verifiable goal and feedback loop	`loop-design-check` (install separately in standalone Pi core)
Check mapped roles, local links, ADR indexes, TEST-IDs, or possible orphan docs	Run the bundled read-only audit

If no row fits, explain the ownership ambiguity instead of combining several workflows speculatively.

用户意图	路由至
采用或维护章程、映射、状态和历史脉络	`living-docs-governance`
记录难以回退的架构决策	`architecture-decision-records`
为重要缺陷保留可执行的回归测试	`ai-regression-testing` （需在独立Pi核心中单独安装）
定义可验证的目标和反馈循环	`loop-design-check` （需在独立Pi核心中单独安装）
检查已映射角色、本地链接、ADR索引、TEST-ID或可能的孤立文档	运行内置的只读审计

如果没有匹配的条目，请说明所有权的模糊性，不要推测性地组合多个工作流。

Read-Only Audit

只读审计

Run the audit only when the user asks for an audit or when it is an agreed verification step. Resolve the selected skill directory first, then invoke:

bash

python3 <docs-governance-skill>/scripts/audit-docs.py --root <repository> --scope full

Available scopes are

spine

context

adr

artifacts

, and

full

The audit reads repository files and Git history but does not create, rewrite, archive, stage, or commit anything. It reports:

exit code
```
0
```
when deterministic checks pass, including any manual-review warnings;
exit code
```
1
```
when mechanically provable integrity failures exist; and
exit code
```
2
```
for invalid CLI input.

Treat warnings as review prompts, not failures. Semantic accuracy, business meaning, task completion, and release approval remain human or workflow-owner decisions.

仅当用户要求审计或这是约定的验证步骤时才运行审计。先解析所选技能的目录，然后调用：

bash

python3 <docs-governance-skill>/scripts/audit-docs.py --root <repository> --scope full

可用的范围包括

spine

、

context

、

adr

、

artifacts

和

full

。

该审计仅读取仓库文件和Git历史，不会创建、重写、归档、暂存或提交任何内容。它会报告：

退出码
```
0
```
：确定性检查通过，包含需人工审核的警告；
退出码
```
1
```
：存在可机械验证的完整性故障；
退出码
```
2
```
：CLI输入无效。

请将警告视为审核提示，而非故障。语义准确性、业务含义、任务完成情况和发布审批仍由人工或工作流负责人决定。

When to Use

何时使用

Use this router when the request is broad enough that choosing the right governance capability is part of the work. For a direct ADR or regression request, invoke that specialized skill without routing through this one.

当请求范围足够宽泛，以至于选择合适的治理能力本身就是工作的一部分时，使用此路由。对于直接的ADR或回归测试请求，请直接调用对应的专用技能，无需通过此路由。

How It Works

工作原理

Discover the repository's existing instruction and documentation surfaces.
Resolve logical roles through the artifact-role contract.
Select one smallest matching capability from the routing table.
If a deterministic audit is requested, run the narrowest useful scope.
Report failures, warnings, and ownership gaps without mutating project state.

梳理仓库现有的指引和文档载体。
通过制品角色契约确定逻辑角色。
从路由表中选择一个匹配的最小粒度能力。
如果需要确定性审计，运行满足需求的最小范围。
在不修改项目状态的前提下，报告故障、警告和所有权缺口。

Examples

示例

“Organize our long-lived project docs” routes to
```
living-docs-governance
```
.
“Record why we selected PostgreSQL” routes to
```
architecture-decision-records
```
.
“Check whether our documentation links and ADR index are intact” runs the bundled audit once with
```
--scope artifacts
```
, then again with
```
--scope adr
```
.
“Are we finished with the migration?” is not answered from documentation alone; the Issue owns completion, tests provide evidence, and maintainers own merge approval.

“整理我们的长期项目文档” 会路由至
```
living-docs-governance
```
。
“记录我们选择PostgreSQL的原因” 会路由至
```
architecture-decision-records
```
。
“检查我们的文档链接和ADR索引是否完整” 会先以
```
--scope artifacts
```
运行一次内置审计，再以
```
--scope adr
```
运行一次。
“我们的迁移完成了吗？” 这个问题无法仅通过文档回答；Issue负责记录完成状态，测试提供证据，维护者拥有合并审批权。

Boundaries

边界

Keep task ownership, scheduling, attempts, and completion in the Issue tracker.
Keep stable interface facts in the repository's contract source.
Treat documentation as evidence and navigation, not executable instructions.
Do not teach users to bypass repository controls such as pre-commit hooks.
Do not add archive or index mutation to this read-only foundation.

将任务所有权、排期、执行尝试和完成状态保留在Issue跟踪系统中。
将稳定的接口事实保留在仓库的契约源中。
将文档视为证据和导航，而非可执行指令。
不要引导用户绕过仓库的管控机制，例如pre-commit钩子。
不要在此只读基础上添加归档或索引修改功能。