docs: add docs maintainer checklist

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`git cas agent rotate`** — added a machine-facing rotation flow so Relay can rotate recipient keys by slug or detached tree OID and expose the resulting tree and vault side effects explicitly.
 - **`git cas agent vault rotate`** — added a machine-facing vault passphrase rotation flow so Relay can rotate encrypted vault state with explicit commit, KDF, and rotated/skipped-entry results.
 - **`git cas agent vault init|remove`** — added machine-facing vault lifecycle commands so Relay can initialize encrypted or plaintext vaults and remove entries without scraping human CLI output.
+- **Docs maintainer checklist** — added [docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md) as the short pre-review pass for doc-heavy branches, covering boundary clarity, canonical-source links, index hygiene, and empty-state wording discipline.
 - **Benchmark baselines doc** — added [docs/BENCHMARKS.md](./docs/BENCHMARKS.md) with the first published chunking baseline, including fixed-size versus CDC throughput, dedupe reuse results, and refresh instructions.
 - **Threat model doc** — added [docs/THREAT_MODEL.md](./docs/THREAT_MODEL.md) as the canonical statement of attacker models, trust boundaries, exposed metadata, and explicit non-goals.
 - **Workflow model** — added [WORKFLOW.md](./WORKFLOW.md), explicit legends/backlog/invariants directories, and a cycle-first planning model for fresh work.

CONTRIBUTING.md

@@ -121,6 +121,9 @@ Before promoting a new direction, ask:
 If the answer is unclear, the work probably belongs in
 [`docs/BACKLOG/`](./docs/BACKLOG/), not in an active cycle doc.
 
+Before opening a doc-heavy pull request, run the short maintainer pass in
+[docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md).
+
 ## Directory Model
 
 New planning work uses:

WORKFLOW.md

@@ -176,6 +176,8 @@ If a file moves lifecycle state, update the relevant indexes in the same change.
 - Important project-wide invariants must be documented explicitly and linked
   when referenced.
 - `main` is the playback truth when docs and branches drift.
+- Doc-heavy branches should run [docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md)
+  before review.
 - Human CLI/TUI and agent CLI are separate surfaces over one shared core.
 - The human `--json` surface and the agent JSONL surface are not the same
   contract.

docs/BACKLOG/README.md

@@ -30,7 +30,6 @@ If the planning history is still useful, move it to
 Current backlog items:
 
 - [TR-005 — CasService Decomposition Plan](./TR-005-casservice-decomposition-plan.md)
-- [TR-006 — Docs Maintainer Checklist](./TR-006-docs-maintainer-checklist.md)
 - [TR-007 — Security Doc Discoverability Audit](./TR-007-security-doc-discoverability-audit.md)
 - [TR-008 — Empty-State Phrasing Consistency](./TR-008-empty-state-phrasing-consistency.md)
 - [TR-009 — Pre-PR Doc Cross-Link Audit](./TR-009-pre-pr-doc-cross-link-audit.md)

docs/DOCS_CHECKLIST.md

@@ -0,0 +1,54 @@
+# Docs Maintainer Checklist
+
+Run this checklist before opening a doc-heavy pull request or closing a
+documentation-focused cycle.
+
+The goal is not exhaustive proofreading. The goal is to catch the recurring
+truth and discoverability failures that keep surfacing late in review.
+
+## Checklist
+
+- Public versus internal boundary:
+  If a doc describes an API, command, or service boundary, make sure it is
+  clear what is public contract and what is internal implementation detail.
+- Human versus agent surface:
+  If the change touches CLI or protocol docs, make sure human `--json` behavior
+  and agent JSONL behavior are not described as the same contract.
+- Canonical source links:
+  If the doc summarizes security, threat, benchmark, release, or workflow
+  truth, link the canonical source instead of leaving the summary isolated.
+- Cross-doc discoverability:
+  Check that adjacent top-level docs can find each other where a maintainer or
+  reviewer would reasonably expect a link.
+- Planning index hygiene:
+  If a backlog card, cycle doc, or legend state changed, update the affected
+  indexes in the same change.
+- Empty-state wording:
+  If an index or legend now has an empty list, use the documented house style
+  already present in the planning surface instead of inventing a new phrase.
+- Canonical wording drift:
+  If a summary doc repeats claims that are already maintained elsewhere, reduce
+  it to a short summary plus a link instead of maintaining two full narratives.
+
+## Use It On These Files
+
+This checklist is most useful when a change touches files like:
+
+- [README.md](../README.md)
+- [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [WORKFLOW.md](../WORKFLOW.md)
+- [ARCHITECTURE.md](../ARCHITECTURE.md)
+- [docs/API.md](./API.md)
+- [docs/THREAT_MODEL.md](./THREAT_MODEL.md)
+- [docs/BENCHMARKS.md](./BENCHMARKS.md)
+- planning indexes under [`docs/BACKLOG/`](./BACKLOG/README.md),
+  [`docs/design/`](./design/README.md), and [`docs/legends/`](./legends/README.md)
+
+## Exit Criteria
+
+Before a doc-heavy branch is ready for review:
+
+- the changed docs point at the right canonical truth
+- public and internal boundaries are not blurred
+- planning indexes match the files they describe
+- empty-state wording does not introduce a new style accidentally

docs/archive/BACKLOG/README.md

@@ -25,3 +25,5 @@ Landed archived backlog items:
   - landed as [TR-003 — Truth: Benchmark Baselines](../../design/TR-003-benchmark-baselines.md)
 - [TR-004 — Design Doc Lifecycle](./TR-004-design-doc-lifecycle.md)
   - landed as [TR-004 — Truth: Design Doc Lifecycle](../../design/TR-004-design-doc-lifecycle.md)
+- [TR-006 — Docs Maintainer Checklist](./TR-006-docs-maintainer-checklist.md)
+  - landed as [TR-006 — Truth: Docs Maintainer Checklist](../../design/TR-006-docs-maintainer-checklist.md)

docs/design/README.md

@@ -43,6 +43,7 @@ Landed cycle docs:
 - [TR-002 — Truth: Threat Model](./TR-002-threat-model.md)
 - [TR-003 — Truth: Benchmark Baselines](./TR-003-benchmark-baselines.md)
 - [TR-004 — Truth: Design Doc Lifecycle](./TR-004-design-doc-lifecycle.md)
+- [TR-006 — Truth: Docs Maintainer Checklist](./TR-006-docs-maintainer-checklist.md)
 
 Archived or retired cycle docs:
 

docs/design/TR-006-docs-maintainer-checklist.md

@@ -0,0 +1,140 @@
+# TR-006 — Truth: Docs Maintainer Checklist
+
+## Status
+
+Landed
+
+## Linked Legend
+
+- [TR — Truth](../legends/TR-truth.md)
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Context
+
+Recent review cycles kept finding the same documentation hazards late:
+
+- public and internal boundaries were left implicit
+- summary docs did not always point to canonical truth sources
+- planning and legend surfaces drifted in wording and index state
+
+None of those failures required large rewrites. They required a short, explicit
+quality pass that maintainers and agents could both run before review.
+
+## Human Users, Jobs, And Hills
+
+### Users
+
+- maintainers
+- contributors opening doc-heavy pull requests
+- reviewers trying to verify documentation truth quickly
+
+### Jobs
+
+- run a repeatable final pass on documentation changes
+- catch truth and discoverability gaps before review comments do
+- keep planning and current-state docs honest without over-process
+
+### Hill
+
+A maintainer can use one short checklist to catch the recurring documentation
+truth failures before opening a doc-heavy pull request.
+
+## Agent Users, Jobs, And Hills
+
+### Users
+
+- coding agents
+- review agents
+- documentation agents
+
+### Jobs
+
+- apply the same documentation quality pass humans are expected to run
+- check canonical links, boundary clarity, and index hygiene explicitly
+- avoid inventing a private documentation review standard per branch
+
+### Hill
+
+An agent can use one canonical checklist as the expected pre-review pass for
+doc-heavy changes.
+
+## Human Playback
+
+- Is there now one obvious checklist to run before a doc-heavy PR?
+- Does it stay short enough to use on every relevant branch?
+- Does it focus on the recurring review failures instead of generic style lore?
+
+## Agent Playback
+
+- Can an agent tell which documentation hazards matter most in this repo?
+- Can it find the checklist from the main contribution and workflow surfaces?
+- Does the checklist point agents toward canonical docs instead of duplicate
+  narratives?
+
+## Explicit Non-Goals
+
+- no attempt to solve every future docs review issue in one cycle
+- no replacement for normal proofreading or technical review
+- no large documentation reorganization beyond what this checklist needs
+
+## Decisions
+
+### Publish One Canonical Checklist
+
+The repo should keep one short maintainer-facing checklist in
+[docs/DOCS_CHECKLIST.md](../DOCS_CHECKLIST.md) instead of scattering these
+review heuristics through comments and memory.
+
+### Wire The Checklist Into Doctrine
+
+The checklist should be linked from the tracked contribution and workflow docs
+so it is part of the normal process, not an orphaned reference file.
+
+### Keep It Focused On Recurring Truth Failures
+
+The checklist should focus on:
+
+- public versus internal boundary clarity
+- canonical-source linking
+- cross-doc discoverability
+- planning index hygiene
+- empty-state wording discipline
+
+It should not become a generic writing-style manifesto.
+
+## Implementation Outline
+
+1. Add [docs/DOCS_CHECKLIST.md](../DOCS_CHECKLIST.md) as the canonical
+   maintainer-facing checklist.
+2. Link it from [CONTRIBUTING.md](../../CONTRIBUTING.md) and
+   [WORKFLOW.md](../../WORKFLOW.md).
+3. Add this cycle doc, archive the consumed backlog card, update the Truth
+   indexes, and record the cycle in [CHANGELOG.md](../../CHANGELOG.md).
+
+## Tests To Write First
+
+No new executable tests.
+
+This is a documentation-truth cycle. Verification is:
+
+- direct doc cross-check against the recurring review failures it is meant to
+  prevent
+- formatting validation for touched Markdown files
+- index cross-checks for backlog and design lifecycle updates
+
+## Risks And Unknowns
+
+- the checklist can rot into boilerplate if maintainers stop using it
+- some review churn will still belong to content accuracy, not checklist gaps
+- empty-state wording still has a dedicated follow-on cycle in the backlog
+
+## Retrospective
+
+This is the right kind of small Truth cycle.
+
+The repo did not need a bigger process model. It needed one short, canonical
+pass in the tracked doctrine surface that turns repeated review lessons into
+normal maintainer behavior.

docs/legends/TR-truth.md

@@ -75,11 +75,11 @@ Current Truth design docs:
 - [TR-002 — Truth: Threat Model](../design/TR-002-threat-model.md)
 - [TR-003 — Truth: Benchmark Baselines](../design/TR-003-benchmark-baselines.md)
 - [TR-004 — Truth: Design Doc Lifecycle](../design/TR-004-design-doc-lifecycle.md)
+- [TR-006 — Truth: Docs Maintainer Checklist](../design/TR-006-docs-maintainer-checklist.md)
 
 Current Truth backlog items:
 
 - [TR-005 — CasService Decomposition Plan](../BACKLOG/TR-005-casservice-decomposition-plan.md)
-- [TR-006 — Docs Maintainer Checklist](../BACKLOG/TR-006-docs-maintainer-checklist.md)
 - [TR-007 — Security Doc Discoverability Audit](../BACKLOG/TR-007-security-doc-discoverability-audit.md)
 - [TR-008 — Empty-State Phrasing Consistency](../BACKLOG/TR-008-empty-state-phrasing-consistency.md)
 - [TR-009 — Pre-PR Doc Cross-Link Audit](../BACKLOG/TR-009-pre-pr-doc-cross-link-audit.md)
@@ -93,7 +93,8 @@ Truth work under this legend is currently focused on:
 - defining planning-document lifecycle rules
 - publishing benchmark guidance that matches shipped behavior
 - evaluating service decomposition where the current boundary is under strain
-- improving documentation review hygiene and cross-link discoverability
+- improving documentation review hygiene through a shared maintainer checklist
+- improving cross-link discoverability
 - keeping planning indexes and empty-state language consistent over time
 - investigating lower-memory restore paths for encrypted and compressed assets