Configuration

Configuration

The document index and governance checker share one JSON configuration. After installing the runtime under scripts/, the default location is:

scripts/docs-governance.config.json

Use --config <path> to select another file and --repo <path> to select the repository root.

中文概览：配置决定文档根目录、生成目录、哪些目录属于当前权威、必填元数据、行数限制、路由入口和稳定 ID 前缀。

Starter configuration

{
  "$schema": "./docs-governance.schema.json",
  "schemaVersion": 1,
  "docsRoot": "docs",
  "generatedRoot": "docs/generated",
  "activeDirectories": [
    "architecture",
    "delivery",
    "domains",
    "governance",
    "operations",
    "product"
  ],
  "excludedFromMetadata": ["archive", "generated", "reference", "source"],
  "requiredMetadata": ["status", "owner", "last-reviewed"],
  "allowedStatuses": ["draft", "accepted", "active", "superseded", "archived"],
  "lineLimits": {
    "default": 500,
    "README.md": 300,
    "delivery/STATUS.md": 150
  },
  "routingPaths": ["docs/README.md", "docs/delivery/STATUS.md"],
  "routingPatterns": ["^docs/domains/(?:[^/]+/)?README\\.md$"],
  "stableIdPrefixes": ["ADR", "OQ", "CON", "AC", "TASK", "DOC"]
}

Adapt this file to the target repository; do not copy directory names or statuses that have no real owner or lifecycle.

Field reference

Field	Meaning
$schema	optional editor/schema reference
schemaVersion	configuration contract version; currently 1
docsRoot	repository-relative root containing governed Markdown
generatedRoot	repository-relative directory for derived outputs
activeDirectories	top-level directories whose Markdown must satisfy active metadata rules
excludedFromMetadata	known directories exempt from active metadata requirements
requiredMetadata	front-matter fields required in every active document
allowedStatuses	accepted values for the status field
lineLimits	active-document line limits
routingPaths	exact repository-relative paths classified as routing
routingPatterns	JavaScript regular expressions for additional routing documents
stableIdPrefixes	uppercase prefixes recognized by index and query, such as ADR

Unknown fields are rejected. Arrays must not contain duplicates, paths must stay inside the repository, regular expressions must compile, and stable-ID prefixes must match ^[A-Z][A-Z0-9]*$.

An entry cannot appear in both activeDirectories and excludedFromMetadata.

Directory policy

Every top-level directory under docsRoot must be declared either active or excluded. This catches accidental parallel taxonomies such as both docs/design/ and docs/architecture/ appearing without a governance decision.

Files directly under docsRoot are treated as active documents. A project-level docs/README.md therefore needs the configured metadata unless you deliberately change the policy or layout.

Metadata policy

Example active document:

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

# Checkout domain

last-reviewed must be a real calendar date in YYYY-MM-DD form. If status is superseded, include superseded-by even when it is not listed in requiredMetadata.

Line-limit precedence

The governance checker resolves a limit in this order:

1. exact path relative to docsRoot, for example delivery/STATUS.md;
2. filename, for example README.md;
3. lineLimits.default.

Line limits are routing and maintenance signals, not permission to remove relevant evidence. Split a large active document by responsibility or archive completed material.

Routing policy

Use routingPaths for known entry points and routingPatterns for families of entry points.

Examples:

{
  "routingPaths": ["docs/README.md", "docs/delivery/STATUS.md"],
  "routingPatterns": ["^docs/domains/(?:[^/]+/)?README\\.md$"]
}

Routing documents should be compact. Their job is to direct a reader to authority, not to duplicate every underlying fact.

Stable IDs

For a configured prefix ADR, the index recognizes IDs such as:

ADR-001
ADR-CHECKOUT-2026-08

The generated index records each occurrence and its line number. Exact stable-ID queries receive decision-oriented ranking.

Choose prefixes that have durable meaning in the target repository. Removing a prefix later can make historical records harder to query.

JSON Schema

The starter schema is available at assets/templates/docs-governance.schema.json. Keep it next to the installed configuration so editors can validate shape and provide completion. Runtime validation remains authoritative in CI even when an editor does not load the schema.