diff --git a/CHANGELOG.md b/CHANGELOG.md index 0eaa8a9..1c5a243 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cbafa78..8867ecf 100644 --- a/CONTRIBUTING.md +++ b/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: diff --git a/WORKFLOW.md b/WORKFLOW.md index 1b499ac..340d5fd 100644 --- a/WORKFLOW.md +++ b/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. diff --git a/docs/BACKLOG/README.md b/docs/BACKLOG/README.md index fa3ca41..c8070a3 100644 --- a/docs/BACKLOG/README.md +++ b/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) diff --git a/docs/DOCS_CHECKLIST.md b/docs/DOCS_CHECKLIST.md new file mode 100644 index 0000000..b37407f --- /dev/null +++ b/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 diff --git a/docs/archive/BACKLOG/README.md b/docs/archive/BACKLOG/README.md index 5de9b4b..e02cf8e 100644 --- a/docs/archive/BACKLOG/README.md +++ b/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) diff --git a/docs/BACKLOG/TR-006-docs-maintainer-checklist.md b/docs/archive/BACKLOG/TR-006-docs-maintainer-checklist.md similarity index 100% rename from docs/BACKLOG/TR-006-docs-maintainer-checklist.md rename to docs/archive/BACKLOG/TR-006-docs-maintainer-checklist.md diff --git a/docs/design/README.md b/docs/design/README.md index 7dbfea1..9c60ed1 100644 --- a/docs/design/README.md +++ b/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: diff --git a/docs/design/TR-006-docs-maintainer-checklist.md b/docs/design/TR-006-docs-maintainer-checklist.md new file mode 100644 index 0000000..13197f8 --- /dev/null +++ b/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. diff --git a/docs/legends/TR-truth.md b/docs/legends/TR-truth.md index fcbd5e7..c19934d 100644 --- a/docs/legends/TR-truth.md +++ b/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