---
title: Documentation audit v1
description: Configurable deterministic checks for documentation quality and agreement with repository structure.
---

# Documentation audit v1

Run the repository audit after discovery and reconciliation:

```bash
ak-docs audit documentation --json
ak-docs audit documentation --text
```

The JSON report is versioned and content-hashed. It includes criterion-level evidence, metrics, blocking findings, generated-document freshness boundaries, and limitations.

## Configuration

Configure the optional `audit.documentation` block in `doc-bridge.config.json`:

```json
{
  "audit": {
    "documentation": {
      "criticalPaths": ["src/cli/**", "src/mcp/**"],
      "generatedPaths": ["docs/generated/**"],
      "minWords": 20,
      "requiredSections": ["Usage", "Examples"],
      "requireExamples": true,
      "exactDuplicates": true,
      "defaultTier": "tier-2",
      "tierRules": [
        { "pattern": "docs/agent-corpus/**", "tier": "tier-0", "critical": true },
        { "pattern": "docs/adr/**", "tier": "tier-1" }
      ],
      "requiredCriticalMetadata": ["owner", "lifecycle", "sourceOfTruth", "validationPath"]
    }
  }
}
```

- `criticalPaths` makes high-confidence contradictions and missing structure documentation blocking.
- `generatedPaths` excludes generated documents from manual quality checks and reports freshness as `not-analyzed`; configure the generator's real check separately.
- `requiredSections`, `minWords`, and `requireExamples` are opt-in to avoid false positives for indexes and short reference files.
- `exactDuplicates` detects identical normalized bodies. It does not claim that similar prose is redundant.
- `defaultTier` and ordered `tierRules` classify every included document as `tier-0`, `tier-1`, or `tier-2`. A document may override the configured tier with `tier` frontmatter; `critical: true` frontmatter or a rule marks it critical.
- Critical documents are checked for `owner`, `lifecycle`, `sourceOfTruth`, and `validationPath` metadata. `requiredCriticalMetadata` can reduce this list for a declared project profile.

The audit reuses the canonical discovery snapshot and reconciliation report. A finding is not proof that prose is wrong unless its evidence and confidence say so. `not-analyzed` is intentional and includes semantic contradiction, unnecessary content, and agent-review boundaries. A document title is satisfied by a Markdown level-one heading, a `title` frontmatter field, or a visible HTML `<h1>` used by README-style documents.

## Independent quality dimensions

Each document receives an assessment instead of one opaque quality score. The machine-readable report exposes `documentAssessments` and independent status counts for:

- correctness: deterministic reconciliation can expose evidence, but semantic correctness remains `not-analyzed` until code, configuration, tests, and applicable runtime behavior are reviewed;
- completeness: structural signals such as title and configured required sections are reported as `partial`, never as semantic completeness;
- clarity: title and basic structure are measurable, while human readability remains `not-analyzed`;
- agent efficiency: title and example presence are signals only; retrieval usefulness and task success require the controlled study;
- maintainability: owner, lifecycle, source-of-truth, and validation-path metadata are directly measurable.

Example presence and example correctness are separate. The audit reports `example.present`; `example.validation` remains `not-analyzed` unless a real validation flow supplies evidence. Similar prose, unnecessary content, and document/document semantic contradictions are intentionally deferred to the Registry-agent and human-adjudication path.

## Hash algorithm migration

The report inherits its snapshot's declared hash algorithm. `sha256-semantic-v1` excludes
revision kind/value, generated timestamps and reuse-run coverage while preserving evidence,
configuration, analyzer versions and meaningful coverage/limitations. Legacy `sha256-normalized-v1`
verification is unchanged. Unknown algorithms require a compatible doc-bridge version and explicit
regeneration. See [incremental scan v1](../spec/incremental-scan-v1.md). Semantic equality does not
rebind an approval to another revision; proposal and study seals retain their original projections.

## Caller service profile

The caller-selected [service profile v1](service-profile-v1.md) restricts this
surface before repository configuration is interpreted. Repository config admits
only the enumerated leaves; ignored options retain path-only diagnostics and
`not-analyzed` coverage. Agent execution, repository module imports, federation,
watch and legacy writes are denied. Service library calls use injected storage;
service CLI writes require `--artifact-root`. MCP mutating/agent operations and
filesystem fallbacks are refused. Ordinary local calls remain unchanged.

## Findings and negotiated handoff caveats

Region fixes and settled human decisions follow [region remediation v1](../spec/region-remediation-v1.md),
[FindingV1](../schemas/finding-v1.md), [RemediationV1](../schemas/remediation-v1.md) and
[DecisionV1](../schemas/decision-v1.md). CLI and MCP use region remediation contracts;
region creation/review is a deterministic library API. Enrichment retains settled Decision records
through cache replay, without converting remediation rejection into finding rejection.

`AgentHandoffV1` readers accept optional bounded `caveats` with `pendingFindings`,
`analyzed` repository/revision identities and `coverage` limitations. New writers emit
it only with explicit `includeCaveats: true` and caller-supplied validated caveats; unknown
capability defaults to the legacy field set. Default index and MCP writers never embed
caveats. New strict readers accept legacy payloads; old strict readers receive legacy
output. The public reader preserves negotiated caveats. Limitations cannot establish
semantic validation or invent an answer.