Governance Model

Governance Model

The goal is not “more documentation.” The goal is a small, explicit system in which a person or AI agent can locate the current truth, expand only the relevant context, and still recover historical evidence when needed.

中文概览：每个会变化的事实只保留一个当前权威来源；入口文档负责路由，详细资料按需读取，历史和生成内容不默认灌入上下文。

One authority per changing fact

An authority is the single active place responsible for a changing fact. Other documents may link to or summarize it, but must not claim independent ownership.

Fact type	Preferred authority	Human documentation should add
HTTP endpoints and payloads	OpenAPI or equivalent contract	invariants, ownership, rationale, exceptions
Events and messages	event schema or registry	delivery semantics and operational consequences
Database structure	migrations and schema	data ownership, retention, migration rationale
Dependencies	package/workspace manifests	architectural boundaries and exceptions
Current delivery state	one compact status authority	blockers, verified evidence, next decisions
Architecture decisions	stable decision records	context, decision, tradeoffs, consequences
Product behavior	product specification or acceptance contract	user intent and deliberate constraints

If two active documents disagree, do not merge them blindly. Identify the owner, inspect machine contracts and recent evidence, choose the authority, then archive or redirect the losing copy.

Retrieval levels

The model uses access levels to control how much context is loaded.

Access level	Purpose	Read by default?
routing	Locate the authority and relevant domain	Yes, but keep it compact
on-demand	Explain current designs, decisions, plans, and runbooks	Only when the task touches them
source	Preserve imported requirements or auxiliary evidence	Only for provenance or targeted questions
historical	Preserve completed or superseded records	Only for audit or regression context
derived	Provide generated indexes and graphs	Query first; do not treat as original truth

Progressive retrieval is not a fixed token budget. Safety, contracts, migrations, privacy, and acceptance context must still be read whenever the change surface requires them.

Documentation taxonomy

The default taxonomy is deliberately role-based:

Directory	Responsibility
docs/governance/	cross-project rules, decisions, risks, and security
docs/product/	product scope and user-facing reference
docs/architecture/	cross-domain architecture and rationale
docs/domains/	one compact entry point per business capability
docs/delivery/	current status, open work, and active acceptance
docs/operations/	deploy, operate, recover, and roll back
docs/generated/	deterministic derived indexes and graphs
docs/source/	versioned source requirements
docs/reference/	auxiliary evidence and prototypes
docs/archive/	completed or superseded records

Rename categories when a repository already has strong conventions. Do not create parallel terminology merely to match this table.

Lifecycle

Use explicit lifecycle states, for example:

• draft — being developed and not yet authoritative;
• accepted — approved decision or specification;
• active — current operational or delivery authority;
• superseded — replaced by a named successor;
• archived — retained as historical evidence.

A typical active document begins with metadata:

---
status: active
owner: platform-team
last-reviewed: 2026-08-03
---

A superseded document must point to its successor:

---
status: superseded
owner: platform-team
last-reviewed: 2026-08-03
superseded-by: ADR-042
---

Rules that prevent lifecycle drift:

• archived documents cannot claim active status;
• generated documents must carry a generated-file banner and must not be hand-edited;
• current status stays compact while completed work moves to dated archives;
• links and repository instructions are updated in the same move;
• verification performed and verification still pending are recorded separately.

Stable identifiers

Stable IDs such as ADR-042, TASK-2026-08, or DOC-017 allow a query to find a decision or record even when its file moves. Prefixes are repository policy and are configured through stableIdPrefixes.

Do not assign an ID to every paragraph. Use IDs for decisions, open questions, contracts, acceptance records, and work items that must survive renames or archival.

AI change archives

Create an AI change record only for work where future recovery benefits from the evidence:

• cross-domain or contract changes;
• data, security, privacy, or infrastructure changes;
• complex defects whose diagnosis is not obvious from the final diff;
• major refactors or migrations.

Avoid per-session logs. A useful record contains scope, decisions, affected authorities, verification actually performed, unverified items, and links to durable artifacts.

Migration sequence

For an existing documentation tree:

1. Inventory files and machine contracts.
2. Classify each document by role, access level, and lifecycle.
3. Map duplicated facts to candidate authorities.
4. Resolve conflicts with owners and current evidence.
5. Move or merge content conservatively.
6. Add redirects or update every local reference in the same change.
7. Generate indexes and run governance plus link checks.
8. Commit the migration separately from unrelated product changes.

The model organizes knowledge; it does not resolve open product, compliance, provider, or release decisions on its own.