git-stunts · flyingrobots · Apr 1, 2026 · Apr 1, 2026 · Apr 1, 2026 · Apr 1, 2026
diff --git 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
@@ -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, 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/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
@@ -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
@@ -30,6 +30,39 @@ 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)
+- 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.
+
+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:
@@ -65,12 +98,14 @@ 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
 
 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
@@ -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/...LOG/TR-009-pre-pr-doc-cross-link-audit.md → ...LOG/TR-009-pre-pr-doc-cross-link-audit.md b/...LOG/TR-009-pre-pr-doc-cross-link-audit.md → ...LOG/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
@@ -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
@@ -0,0 +1,147 @@
+# 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 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.
+
+### 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
@@ -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