A Codex Skill and zero-dependency Node.js toolkit for keeping repository documentation authoritative, searchable, and economical for humans and AI agents to read.
这是一个面向大型项目和 AI 高频迭代仓库的文档治理工具包：审计重复或冲突的知识，建立清晰的权威来源与归档边界，并用确定性索引和 CI 检查防止文档体系再次失控。
Repository documentation usually becomes difficult to trust for the same reasons:
- the same changing fact is maintained in several active documents;
- completed plans and current status are mixed together;
- API, schema, and dependency facts are copied out of machine contracts;
- AI agents must read too much context before finding the relevant source;
- generated indexes exist, but nobody checks whether they are stale.
govern-project-docs applies five practical rules:
- Give every changing fact one active authority.
- Retrieve progressively: routing first, details on demand, evidence last.
- Archive superseded evidence instead of silently deleting it.
- Keep API, event, database, and dependency truth in machine-readable contracts.
- Generate indexes deterministically and enforce freshness in CI.
- SKILL.md — the Codex workflow for auditing and reorganizing repository documentation.
- scripts/audit-docs.mjs — a read-only audit that finds documentation structure, duplication signals, missing metadata, broken local links, and stale path references.
- assets/runtime — zero-dependency CLIs for authority enforcement, document indexing, bounded search, governance checks, and Markdown link validation.
- assets/templates — adaptable governance policies, AI change records, configuration, and JSON Schema starters.
- references — focused guidance for migrations, authority design, automation, CI, hooks, and stack-specific code graphs.
Node.js 22 or newer is required. Run the CLI directly from GitHub without cloning the repository:
npx github:CH-ZHOU-0512/govern-project-docs audit --repo .
npx github:CH-ZHOU-0512/govern-project-docs init --repo . --owner engineering
npx github:CH-ZHOU-0512/govern-project-docs check --repo .audit is read-only. init first preflights every target and stops without writing when an existing file differs. Review those files or explicitly use --force; use --dry-run to preview a clean installation. A successful initialization installs the runtime, schema, and starter policies, then generates the initial document index.
Available commands:
| Command | Purpose |
|---|---|
init |
Install governance files safely and generate the initial index. |
audit |
Report documentation structure and risks without modifying files. |
check |
Run Authority Engine, index freshness, and Markdown link checks. |
index |
Generate, check, query, or watch the bounded document index. |
governance |
Run only metadata, authority, lifecycle, and archive rules. |
links |
Run only local Markdown target validation. |
Clone the repository into your Codex skills directory.
PowerShell:
git clone https://github.com/CH-ZHOU-0512/govern-project-docs.git (Join-Path $env:USERPROFILE ".codex\skills\govern-project-docs")macOS or Linux:
git clone https://github.com/CH-ZHOU-0512/govern-project-docs.git "${CODEX_HOME:-$HOME/.codex}/skills/govern-project-docs"Then ask Codex to use $govern-project-docs, for example:
使用 $govern-project-docs 审计当前仓库的文档，先只给出权威来源、重复内容和归档建议，不修改文件。
The cloned repository still supports the original direct-script workflow:
node scripts/audit-docs.mjs --repo /path/to/target-repository
node scripts/audit-docs.mjs --repo /path/to/target-repository --jsonThe audit is intentionally read-only. It reports findings without reorganizing the target repository.
Schema v2 makes “one active authority” machine-checkable. Each governed document receives a stable ID and may claim narrow authority keys:
---
doc-id: DOC-PAYMENTS-ARCHITECTURE
status: active
owner: payments-team
last-reviewed: 2026-08-03
authority-for:
- payments.architecture
- payments.retry-policy
---The governance check rejects duplicate document IDs, multiple accepted or active documents claiming the same authority key, invalid authority keys, archived authority claims, unknown supersession targets, non-reciprocal replacements, and supersession cycles. Schema v1 configurations remain supported for incremental adoption.
When replacing a document, declare both sides of the relationship:
# New authority
doc-id: DOC-PAYMENTS-V2
status: active
supersedes: [DOC-PAYMENTS-V1]
# Previous authority
doc-id: DOC-PAYMENTS-V1
status: superseded
superseded-by: DOC-PAYMENTS-V2The recommended path is the atomic init command shown above. For a manual or highly customized integration, copy the following runtime files as a unit because the three CLIs import docs-toolkit.mjs:
assets/runtime/docs-toolkit.mjs
assets/runtime/document-index.mjs
assets/runtime/check-doc-governance.mjs
assets/runtime/check-markdown-links.mjs
Copy and adapt the configuration templates only when the target repository does not already have an equivalent policy:
assets/templates/docs-governance.config.json
assets/templates/docs-governance.schema.json
Example commands after installing the files under scripts/:
node scripts/document-index.mjs generate
node scripts/document-index.mjs check
node scripts/document-index.mjs query payments
node scripts/document-index.mjs watch
node scripts/check-doc-governance.mjs
node scripts/check-markdown-links.mjswatch is local developer feedback. Deterministic generation plus CI freshness checks remain the shared correctness boundary.
.
├── SKILL.md # Codex workflow and operating rules
├── agents/openai.yaml # Skill display metadata
├── bin/ # npx command router and safe initializer
├── scripts/ # Read-only repository audit
├── assets/runtime/ # Reusable documentation CLIs
├── assets/templates/ # Policies, config, schema, record templates
├── references/ # Migration and automation guidance
└── tests/ # Cross-platform Node.js tests
Run the same local checks used by CI:
npm run validate
npm pack --dry-run --ignore-scriptsGitHub Actions validates Node.js 22 and 24 on both Ubuntu and Windows.
The project Wiki contains the longer-form guides:
- getting started and adoption paths;
- governance model, taxonomy, authority, and lifecycle;
- runtime CLI and configuration reference;
- development, validation, CI, and contribution guidance.
For a concise Chinese introduction, see the LINUX DO / V2EX launch post.
Issues and pull requests are welcome. Please keep changes deterministic, preserve cross-platform behavior, and include tests when modifying runtime tools. For a new governance rule, explain which failure mode it prevents and whether it belongs in human policy, configuration, or a machine check.
Released under the MIT License.