docpact

docpact is a standalone Rust CLI for deterministic, diff-driven documentation governance.

It helps teams and agents answer three practical questions:

before coding: what documents should I read first?
after coding: what documentation should this change have reviewed or updated?
ongoing: which governed documents have gone stale?

docpact stays deterministic. It does not replace governance decisions with AI inference, and it does not hide state in background services or opaque caches.

License: MIT

Why docpact

AI coding tools make code changes cheaper. They also make documentation drift cheaper.

In agentic coding workflows, that usually breaks down in three places:

before coding: an agent does not know which documents it should read first, so it either loads too much, relies on coarse pointers, or skips discovery entirely
after coding: an agent does not know which documents should have been reviewed or updated as a consequence of the change
ongoing: an agent treats documentation as authoritative input, but has no built-in signal for whether that documentation has silently gone stale

docpact closes that loop:

route helps decide what to read before coding
lint enforces which governed docs should have been reviewed or updated after coding
freshness detects governed docs that may no longer be trustworthy
render exposes short, read-only summaries over catalog, ownership, navigation, and workspace context

Public design principles:

docs/design-principles.md

Install

Install from crates.io:

cargo install docpact

Run from source:

cargo run -- <command>

Install from a local checkout:

cargo install --path .

Quick Start

Start from one of the bundled config examples:
Copy the right shape into the target repository as .docpact/config.yaml.
Validate the config.
Run lint against an explicit diff source.

Example:

docpact validate-config --root /path/to/repo
docpact validate-config --root /path/to/repo --strict
docpact lint --root /path/to/repo --files src/api/client.ts,README.md --format text

lint always needs one explicit diff source. Use one of:

--files <csv>
--staged
--worktree
--merge-base <ref>
--base <sha> --head <sha>

Core Commands

Validate configuration

docpact validate-config --root /path/to/repo
docpact validate-config --root /path/to/repo --strict

Check a concrete change

docpact lint --root /path/to/repo --files src/api/client.ts,README.md --format json --output .docpact/runs/latest.json

Drill into one finding

docpact diagnostics show --report .docpact/runs/latest.json --id d001 --format json

Record completed review evidence

docpact review mark --root /path/to/repo --path docs/api.md

or, when coming from one explicit lint finding:

docpact review mark --root /path/to/repo --report .docpact/runs/latest.json --id d001

Audit governance coverage

docpact coverage --root /path/to/repo --format json

Audit document freshness

docpact freshness --root /path/to/repo --format json

Route reading before coding

docpact route --root /path/to/repo --paths src/payments/** --format json
docpact route --root /path/to/repo --module src/payments --format text
docpact route --root /path/to/repo --intent payments --format json

Render derived summaries

docpact render --root /path/to/repo --view catalog-summary --format json
docpact render --root /path/to/repo --view navigation-summary --paths src/payments/** --format text

Adoption Controls

docpact supports explicit adoption controls for repositories that cannot enforce all existing debt immediately.

Create and apply a baseline:

docpact baseline create --report .docpact/runs/latest.json --output .docpact/baseline.json
docpact lint --root /path/to/repo --files src/api/client.ts,README.md --baseline .docpact/baseline.json

Add a waiver for one explicit finding:

docpact waiver add \
  --report .docpact/runs/latest.json \
  --id d001 \
  --reason "temporary exception during migration" \
  --owner "team-docs" \
  --expires-at 2026-05-31 \
  --output .docpact/waivers.yaml

Then apply it during lint:

docpact lint --root /path/to/repo --files src/api/client.ts,README.md --waivers .docpact/waivers.yaml

Use waivers sparingly. They are temporary, explicit exceptions, not a default suppression path.

GitHub Actions

This repository ships a thin official GitHub Action wrapper in action.yml.

Typical usage:

- uses: <org>/docpact@v1
  with:
    version: 0.1.2
    args: >
      lint
      --root .
      --base ${{ github.event.pull_request.base.sha }}
      --head ${{ github.sha }}
      --mode enforce

Reference workflows:

Repository CI workflows:

test.yml: minimal PR and default-branch test CI
release.yml: tag-driven crates.io publish and GitHub Release

Skills

This repository also ships official workflow skills under skills/:

skills/README.md
skills/docpact/SKILL.md: direct workflow entrypoint
skills/docpact-governance/SKILL.md: governance-maintainer entrypoint

Current Capabilities

Current docpact capabilities include:

repo and workspace config loading
explicit workspace profile inheritance and child overrides
deterministic trigger-to-required-doc matching
metadata checks on governed Markdown and YAML docs
diff coverage and repository coverage audit
repository freshness audit
deterministic routing with paths, module scope, and controlled intents
read-only derived render views for catalog, ownership, navigation, and workspace summaries
report-backed diagnostics drill-down
explicit review-evidence recording
baseline and waiver lifecycle
list-rules and doctor inspection commands
text, JSON, and SARIF reporting
official GitHub Action wrapper
official skills for direct workflow and governance maintenance

Still deferred:

symbol-level drift checks
executable documentation hooks
AI-assisted semantic review
documentation generation from code

docpact 0.1.2