From 9f18476aea7a1e8fff13df3dde724af8f62bceb7 Mon Sep 17 00:00:00 2001 From: James Ross Date: Tue, 31 Mar 2026 22:13:11 -0700 Subject: [PATCH 1/3] docs: add pre-pr doc cross-link audit --- CHANGELOG.md | 1 + CONTRIBUTING.md | 3 + WORKFLOW.md | 26 ++++ docs/BACKLOG/README.md | 1 - docs/DOCS_CHECKLIST.md | 33 ++++ docs/archive/BACKLOG/README.md | 2 + .../TR-009-pre-pr-doc-cross-link-audit.md | 7 +- docs/design/README.md | 1 + .../TR-009-pre-pr-doc-cross-link-audit.md | 146 ++++++++++++++++++ docs/legends/TR-truth.md | 3 +- 10 files changed, 218 insertions(+), 5 deletions(-) rename docs/{ => archive}/BACKLOG/TR-009-pre-pr-doc-cross-link-audit.md (82%) create mode 100644 docs/design/TR-009-pre-pr-doc-cross-link-audit.md diff --git a/CHANGELOG.md b/CHANGELOG.md index d5170d4..e0daa99 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **`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. +- **Pre-PR doc cross-link audit** — added a lightweight routing audit to [docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md), [WORKFLOW.md](./WORKFLOW.md), and [CONTRIBUTING.md](./CONTRIBUTING.md) so doc-heavy branches verify canonical adjacent links before review instead of discovering missing cross-links late in PR feedback. - **Planning-index consistency review** — added an explicit planning-surface review to [docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md) and [WORKFLOW.md](./WORKFLOW.md), defining when to verify backlog, design, archive, and legend alignment. - **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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a96cad7..1c63f41 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -124,6 +124,9 @@ If the answer is unclear, the work probably belongs in Before opening a doc-heavy pull request, run the short maintainer pass in [docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md). +If the branch touches top-level or canonical docs, include the pre-PR doc +cross-link audit in that checklist pass. + If the branch touches planning surfaces, include the planning-index review in that checklist pass. diff --git a/WORKFLOW.md b/WORKFLOW.md index 728a73e..980d6f6 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -176,6 +176,29 @@ The minimum review must confirm: `- none currently` in [docs/design/README.md](./docs/design/README.md), instead of inventing a new empty-list phrase for the same condition +### Pre-PR Doc Cross-Link Audit + +Run a pre-PR doc cross-link audit whenever a branch changes high-traffic +documentation surfaces such as: + +- [README.md](./README.md) +- [CONTRIBUTING.md](./CONTRIBUTING.md) +- [WORKFLOW.md](./WORKFLOW.md) +- [ARCHITECTURE.md](./ARCHITECTURE.md) +- [SECURITY.md](./SECURITY.md) +- [docs/API.md](./docs/API.md) +- [docs/THREAT_MODEL.md](./docs/THREAT_MODEL.md) +- [docs/BENCHMARKS.md](./docs/BENCHMARKS.md) +- planning indexes and legend summaries + +This audit should stay lightweight. + +Its purpose is to confirm that touched docs still route readers to the +canonical adjacent docs they need, not to create a second full link-checking +system. + +The detailed pass lives in [docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md). + ## Cycle Workflow 1. Design docs first, using the human and agent IBM Design Thinking passes. @@ -200,6 +223,9 @@ The minimum review must confirm: - `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. +- If a doc-heavy branch touches top-level or canonical docs, include the + pre-PR doc cross-link audit from + [docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md) before review. - When a doc makes security or threat claims, link [SECURITY.md](./SECURITY.md) and [docs/THREAT_MODEL.md](./docs/THREAT_MODEL.md) instead of creating a second canonical narrative. diff --git a/docs/BACKLOG/README.md b/docs/BACKLOG/README.md index 24ad175..de085da 100644 --- a/docs/BACKLOG/README.md +++ b/docs/BACKLOG/README.md @@ -31,7 +31,6 @@ Current backlog items: - [TR-005 — CasService Decomposition Plan](./TR-005-casservice-decomposition-plan.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) - [TR-011 — Streaming Encrypted Restore](./TR-011-streaming-encrypted-restore.md) Archived delivered backlog items: diff --git a/docs/DOCS_CHECKLIST.md b/docs/DOCS_CHECKLIST.md index 7e2aa4e..dec0435 100644 --- a/docs/DOCS_CHECKLIST.md +++ b/docs/DOCS_CHECKLIST.md @@ -30,6 +30,38 @@ truth and discoverability failures that keep surfacing late in review. 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. +## Pre-PR Doc Cross-Link Audit + +Run this extra pass before opening a doc-heavy pull request when a branch +changes: + +- [README.md](../README.md) +- [CONTRIBUTING.md](../CONTRIBUTING.md) +- [WORKFLOW.md](../WORKFLOW.md) +- [ARCHITECTURE.md](../ARCHITECTURE.md) +- [SECURITY.md](../SECURITY.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), + [`docs/archive/BACKLOG/`](./archive/BACKLOG/README.md), and + [`docs/legends/`](./legends/README.md) + +This is not exhaustive link checking. It is a lightweight routing pass for the +docs people and agents are most likely to read first. + +At minimum, confirm the following before review: + +- front-door docs still route to the canonical adjacent docs a maintainer would + expect from that surface +- summary docs link canonical truth instead of becoming a second narrative +- security-sensitive docs route to [SECURITY.md](../SECURITY.md) and + [docs/THREAT_MODEL.md](./THREAT_MODEL.md) where those boundaries matter +- planning indexes and legends point to the current backlog, design, and + archive surfaces they describe +- no touched doc loses an important discoverability link that existed before + ## Planning Index Review Run this extra pass whenever a branch changes: @@ -71,6 +103,7 @@ This checklist is most useful when a change touches files like: Before a doc-heavy branch is ready for review: - the changed docs point at the right canonical truth +- the pre-PR doc cross-link audit passed for the touched surfaces - 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 fc8b0e1..fa6b6f0 100644 --- a/docs/archive/BACKLOG/README.md +++ b/docs/archive/BACKLOG/README.md @@ -29,5 +29,7 @@ Landed archived backlog items: - landed as [TR-006 — Truth: Docs Maintainer Checklist](../../design/TR-006-docs-maintainer-checklist.md) - [TR-007 — Security Doc Discoverability Audit](./TR-007-security-doc-discoverability-audit.md) - landed as [TR-007 — Truth: Security Doc Discoverability Audit](../../design/TR-007-security-doc-discoverability-audit.md) +- [TR-009 — Pre-PR Doc Cross-Link Audit](./TR-009-pre-pr-doc-cross-link-audit.md) + - landed as [TR-009 — Truth: Pre-PR Doc Cross-Link Audit](../../design/TR-009-pre-pr-doc-cross-link-audit.md) - [TR-010 — Planning Index Consistency Review](./TR-010-planning-index-consistency-review.md) - landed as [TR-010 — Truth: Planning Index Consistency Review](../../design/TR-010-planning-index-consistency-review.md) diff --git a/docs/BACKLOG/TR-009-pre-pr-doc-cross-link-audit.md b/docs/archive/BACKLOG/TR-009-pre-pr-doc-cross-link-audit.md similarity index 82% rename from docs/BACKLOG/TR-009-pre-pr-doc-cross-link-audit.md rename to docs/archive/BACKLOG/TR-009-pre-pr-doc-cross-link-audit.md index 5c14d5e..be3a777 100644 --- a/docs/BACKLOG/TR-009-pre-pr-doc-cross-link-audit.md +++ b/docs/archive/BACKLOG/TR-009-pre-pr-doc-cross-link-audit.md @@ -2,7 +2,7 @@ ## Legend -- [TR — Truth](../legends/TR-truth.md) +- [TR — Truth](../../legends/TR-truth.md) ## Why This Exists @@ -29,10 +29,11 @@ of relying on reactive review feedback. ## Linked Invariants -- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md) +- [I-001 — Determinism, Trust, And Explicit Surfaces](../../invariants/I-001-determinism-trust-and-explicit-surfaces.md) ## Notes - keep the audit lightweight enough to run routinely - focus on canonical-source discoverability, not exhaustive link checking -- fit this into the existing workflow instead of creating a second planning layer +- fit this into the existing workflow instead of creating a second planning + layer diff --git a/docs/design/README.md b/docs/design/README.md index 13bd231..00aa8f0 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -45,6 +45,7 @@ Landed cycle docs: - [TR-004 — Truth: Design Doc Lifecycle](./TR-004-design-doc-lifecycle.md) - [TR-006 — Truth: Docs Maintainer Checklist](./TR-006-docs-maintainer-checklist.md) - [TR-007 — Truth: Security Doc Discoverability Audit](./TR-007-security-doc-discoverability-audit.md) +- [TR-009 — Truth: Pre-PR Doc Cross-Link Audit](./TR-009-pre-pr-doc-cross-link-audit.md) - [TR-010 — Truth: Planning Index Consistency Review](./TR-010-planning-index-consistency-review.md) Archived or retired cycle docs: diff --git a/docs/design/TR-009-pre-pr-doc-cross-link-audit.md b/docs/design/TR-009-pre-pr-doc-cross-link-audit.md new file mode 100644 index 0000000..27798e4 --- /dev/null +++ b/docs/design/TR-009-pre-pr-doc-cross-link-audit.md @@ -0,0 +1,146 @@ +# TR-009 — Truth: Pre-PR Doc Cross-Link Audit + +## 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 Truth cycles kept landing real documentation improvements, but review was +still catching a cheap class of issue late: missing discoverability links +between top-level docs, canonical truth docs, and planning indexes. + +The repo already had the right documentation surfaces. + +The missing piece was a lightweight pre-PR routing pass that contributors and +agents can run before review instead of relying on comment-driven cleanup after +the PR is already open. + +## Human Users, Jobs, And Hills + +### Users + +- maintainers opening doc-heavy pull requests +- reviewers checking doc truth and navigation +- contributors editing high-traffic docs + +### Jobs + +- catch missing cross-links before reviewers do +- keep top-level docs routing to the right canonical docs +- avoid turning small doc cycles into reactive review churn + +### Hill + +A maintainer can run one lightweight pre-PR pass and know that touched +high-traffic docs still route readers to the canonical adjacent docs they need. + +## Agent Users, Jobs, And Hills + +### Users + +- coding agents +- documentation agents +- review agents + +### Jobs + +- follow an explicit routing check before opening a doc-heavy PR +- verify discoverability without inventing a second planning layer +- cite the same checklist and workflow truth a human maintainer would use + +### Hill + +An agent can run the same lightweight routing audit as a human maintainer +before review and reduce reactive doc-link fixes in PR feedback. + +## Human Playback + +- Can a maintainer tell when the cross-link audit should run? +- Is the audit lightweight enough to use routinely before opening a PR? +- Does it focus on canonical routing instead of turning into exhaustive link + policing? + +## Agent Playback + +- Can an agent identify the touched doc surfaces that trigger the audit? +- Can it follow the checklist without guessing which canonical docs should be + adjacent? +- Does the workflow point to the checklist instead of duplicating a second + process? + +## Explicit Non-Goals + +- no exhaustive Markdown link checker +- no second planning layer outside the existing checklist and workflow +- no broad rewrite of product docs that are already routing correctly + +## Decisions + +### Keep The Audit Inside The Existing Checklist + +The right place for this audit is [docs/DOCS_CHECKLIST.md](../DOCS_CHECKLIST.md), +not a separate standalone process document. + +That keeps the workflow small and discoverable. + +### Audit High-Traffic And Canonical Surfaces Explicitly + +The audit should run when a branch changes top-level or canonical docs such as +README, CONTRIBUTING, WORKFLOW, ARCHITECTURE, SECURITY, API, THREAT_MODEL, +BENCHMARKS, and planning indexes. + +That makes the trigger concrete without pretending every markdown file needs the +same treatment. + +### Focus On Routing, Not Exhaustive Link Checking + +This cycle is about discoverability between canonical docs, not about turning +maintainers into broken-link crawlers. + +The pass should confirm that touched docs still point to the canonical adjacent +docs a maintainer or agent would reasonably expect from that surface. + +## Implementation Outline + +1. Add this cycle doc. +2. Extend [docs/DOCS_CHECKLIST.md](../DOCS_CHECKLIST.md) with a named pre-PR + doc cross-link audit and minimum routing checks. +3. Wire that audit into [WORKFLOW.md](../../WORKFLOW.md) and + [CONTRIBUTING.md](../../CONTRIBUTING.md) so contributors know when to run it. +4. Archive the consumed backlog card, update Truth indexes, and record the + change in [CHANGELOG.md](../../CHANGELOG.md). + +## Tests To Write First + +No new executable tests. + +This is a documentation and workflow cycle. Verification is: + +- direct review of the checklist and workflow wording +- formatting validation for touched Markdown files +- whitespace and diff validation + +## Risks And Unknowns + +- the audit can drift back into vague wording if later edits remove the + concrete trigger list +- too much duplication between checklist and workflow would make the process + heavier than intended +- contributors may still skip the pass if doc review discipline slips + +## Retrospective + +This was the right follow-through after the checklist, security-discoverability, +and planning-index cycles. + +The repo did not need another large docs framework. It needed one clearer, +lighter pre-PR routing pass in the doctrine people and agents already use. diff --git a/docs/legends/TR-truth.md b/docs/legends/TR-truth.md index 20eee9f..c5f79c7 100644 --- a/docs/legends/TR-truth.md +++ b/docs/legends/TR-truth.md @@ -77,13 +77,13 @@ Current Truth design docs: - [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) - [TR-007 — Truth: Security Doc Discoverability Audit](../design/TR-007-security-doc-discoverability-audit.md) +- [TR-009 — Truth: Pre-PR Doc Cross-Link Audit](../design/TR-009-pre-pr-doc-cross-link-audit.md) - [TR-010 — Truth: Planning Index Consistency Review](../design/TR-010-planning-index-consistency-review.md) Current Truth backlog items: - [TR-005 — CasService Decomposition Plan](../BACKLOG/TR-005-casservice-decomposition-plan.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) - [TR-011 — Streaming Encrypted Restore](../BACKLOG/TR-011-streaming-encrypted-restore.md) Truth work under this legend is currently focused on: @@ -95,6 +95,7 @@ Truth work under this legend is currently focused on: - evaluating service decomposition where the current boundary is under strain - improving documentation review hygiene through a shared maintainer checklist - improving security doc discoverability from high-traffic repo surfaces +- running a lightweight pre-PR doc cross-link audit on doc-heavy branches - running planning-index consistency reviews and keeping empty-state language consistent over time - investigating lower-memory restore paths for encrypted and compressed assets From 5eeedfaea501f6e84f8c56f8fffe7bed04db34fc Mon Sep 17 00:00:00 2001 From: James Ross Date: Tue, 31 Mar 2026 23:21:50 -0700 Subject: [PATCH 2/3] docs: align pre-pr audit triggers --- CONTRIBUTING.md | 4 ++-- docs/DOCS_CHECKLIST.md | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1c63f41..a1eb069 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -124,8 +124,8 @@ If the answer is unclear, the work probably belongs in Before opening a doc-heavy pull request, run the short maintainer pass in [docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md). -If the branch touches top-level or canonical docs, include the pre-PR doc -cross-link audit in that checklist pass. +If the branch touches top-level or canonical docs, planning indexes, or legend +summaries, include the pre-PR doc cross-link audit in that checklist pass. If the branch touches planning surfaces, include the planning-index review in that checklist pass. diff --git a/docs/DOCS_CHECKLIST.md b/docs/DOCS_CHECKLIST.md index dec0435..c2c9d37 100644 --- a/docs/DOCS_CHECKLIST.md +++ b/docs/DOCS_CHECKLIST.md @@ -47,6 +47,7 @@ changes: [`docs/design/`](./design/README.md), [`docs/archive/BACKLOG/`](./archive/BACKLOG/README.md), and [`docs/legends/`](./legends/README.md) +- legend summary files such as [`docs/legends/TR-truth.md`](./legends/TR-truth.md) This is not exhaustive link checking. It is a lightweight routing pass for the docs people and agents are most likely to read first. @@ -97,6 +98,7 @@ This checklist is most useful when a change touches files like: [`docs/design/`](./design/README.md), [`docs/archive/BACKLOG/`](./archive/BACKLOG/README.md), and [`docs/legends/`](./legends/README.md) +- legend summary files such as [`docs/legends/TR-truth.md`](./legends/TR-truth.md) ## Exit Criteria From 079adb24dc3fb7c5d7f241199bb3ceb6f3215ae5 Mon Sep 17 00:00:00 2001 From: James Ross Date: Wed, 1 Apr 2026 00:05:38 -0700 Subject: [PATCH 3/3] docs: clarify tr-009 trigger targets --- docs/design/TR-009-pre-pr-doc-cross-link-audit.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/design/TR-009-pre-pr-doc-cross-link-audit.md b/docs/design/TR-009-pre-pr-doc-cross-link-audit.md index 27798e4..89865f8 100644 --- a/docs/design/TR-009-pre-pr-doc-cross-link-audit.md +++ b/docs/design/TR-009-pre-pr-doc-cross-link-audit.md @@ -94,9 +94,10 @@ That keeps the workflow small and discoverable. ### Audit High-Traffic And Canonical Surfaces Explicitly -The audit should run when a branch changes top-level or canonical docs such as -README, CONTRIBUTING, WORKFLOW, ARCHITECTURE, SECURITY, API, THREAT_MODEL, -BENCHMARKS, and planning indexes. +The audit should run when a branch changes top-level or canonical doc surfaces +such as `README.md`, `CONTRIBUTING.md`, `WORKFLOW.md`, `ARCHITECTURE.md`, +`SECURITY.md`, `docs/API.md`, `docs/THREAT_MODEL.md`, +`docs/BENCHMARKS.md`, and planning indexes. That makes the trigger concrete without pretending every markdown file needs the same treatment.