Docs Stale Reference Guardrails

Docs Stale-Reference Guardrails

Use when a repo has migrated away from old workflow paths (for example scripts/work-queue/*, scripts/agents/*, specs/wrk/*, .Codex/work-queue/*) and you need to stop live docs from reintroducing those paths.

When to use

• Historical session logs show repeated reads of deleted paths
• You have already cleaned some docs and want regression protection
• A few legacy/reference docs still need to mention deleted paths intentionally
• You want to shrink the exception surface over time

Core pattern

Build 3 layers:

1. Strict banned-reference scan for current high-value docs
2. Allowlist-confinement scan for legacy/reference docs only
3. Explicit allowlist-lock test so exceptions cannot quietly grow

Implementation steps

1. Start with a strict curated set

Create a pytest that scans only the cleanest, highest-value live docs first. Good initial candidates:

• AGENTS.md
• AGENTS.md
• README.md
• docs/README.md
• docs/plans/README.md
• workflow templates under .planning/templates/
• recently cleaned live docs under docs/

Do NOT start by scanning generated reports, archives, or known legacy reference docs.

2. Centralize stale-path patterns in a helper

Create a shared test helper, e.g.:

• tests/helpers/stale_reference_docs.py

Export:

• CORE_BANNED_STALE_REFERENCE_PATTERNS
• scan_stale_reference_hits(relative_path, patterns=...)

Core banned families to encode:

• scripts/work-queue/new-spec.sh
• scripts/work-queue/parse-session-logs.sh
• scripts/agents/
• specs/wrk/WRK-(\d+|NNN)/plan.md
• deleted work-queue gate scripts, expressed as current guardrail regex families rather than live execution guidance
• deleted lifecycle helpers:
  • close-item.sh
  • whats-next.sh
  • archive-item.sh
  • claim-item.sh
• .Codex/work-queue/
• deleted work-queue skill paths

Keep test-specific extra patterns local to the test that needs them.

3. Add a strict banned-reference test

Create or maintain a test like:

• tests/docs/test_banned_stale_references.py

Pattern:

• curated STRICT_FILES = [...]
• loop through each file
• assert scan_stale_reference_hits(relative_path) returns no violations

Use this for live/current docs only.

4. Add an allowlist-confinement test

Create or maintain a test like:

• tests/docs/test_legacy_reference_allowlist.py

Pattern:

• broader SCAN_FILES = [...] covering live docs and explicit legacy/reference docs
• tiny ALLOWED_LEGACY_REFERENCE_FILES = {...}
• assert stale references appear only in those allowlisted files

This catches stale-path spread while still allowing redirect/reference docs to mention old paths intentionally.

5. Lock the allowlist

Add a separate explicit test:

• assert ALLOWED_LEGACY_REFERENCE_FILES == {...expected files...}

This is important. Behavioral tests alone do not prevent quiet allowlist growth.

6. Expand strict coverage gradually

Workflow:

1. Find next best live docs with the broader scan
2. Clean those docs with minimal wording changes
3. Move them from allowlist/broader scan into strict scan
4. Re-run tests

Good cleanup strategy:

• replace explicit deleted-path mentions with generic wording where possible
• keep the redirect/reference meaning intact
• reserve explicit deleted-path strings only for true legacy mapping docs

Practical wording pattern for cleanup

Instead of:

• "the old scripts/agents/* wrappers are deleted legacy paths"

Prefer:

• "older wrapper-based entrypoints are deleted legacy paths"

Instead of:

• "Do not invoke scripts/work-queue/close-item.sh"

Prefer:

• "Do not invoke any legacy local closure helper"

This preserves guidance while satisfying strict stale-path bans.

Recommended exception docs

In a migrated workflow repo, the allowlist should usually be tiny. Example steady state:

• docs/ops/legacy-Codex-reference-map.md
• docs/modules/ai/AGENT_EQUIVALENCE_ARCHITECTURE.md

If more files are allowlisted, treat that as debt to reduce.

Verification

Run targeted tests repeatedly while expanding coverage:

• uv run pytest tests/docs/test_banned_stale_references.py tests/docs/test_legacy_reference_allowlist.py -q

If there is related audit/export logic, include those tests too.

Pitfalls

• Do not scan generated reports or archives in the strict test
• Do not rely only on an allowlist behavior test; lock the allowlist explicitly
• Do not duplicate regex lists across tests; centralize them in a helper
• Do not leave live docs in the allowlist just because cleanup is inconvenient; clean and move them into strict coverage when possible

Outcome to aim for

• Most current docs under strict no-stale-reference enforcement
• Only 1–2 intentional legacy/reference docs allowlisted
• Shared helper owns the core stale-path policy
• Allowlist changes require an explicit reviewed test update