docs: fix 23 broken documentation links across codebase

vishnu2kmohan · claude · vishnu2kmohan · commit 9b428c68c17a · 2025-11-25T18:20:36.000-05:00
- Add .claude/templates/ to link checker exclusions (placeholder links) - Fix runbook deployment paths (kubernetes/base → base) - Fix ADR format references (add adr- prefix to filenames) - Fix TESTING.md path references (now at docs-internal/testing/) - Fix SECRETS.md path (now at .github/SECRETS.md) - Fix ADR-0056 references (renumbered to ADR-0060) - Fix docs-internal relative path issues (../adr → ../../adr) Reduces broken links from 88 to 65 (26% reduction). All high-priority links (GitHub, ADR, active docs) now valid. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -295,7 +295,7 @@ pre-commit run --all-files --hook-stage push  # Phase 4
 
 #### Documentation
 
-- Full guide: [TESTING.md](TESTING.md#git-hooks-and-validation)
+- Full guide: [TESTING.md](docs-internal/testing/TESTING.md#git-hooks-and-validation)
 - Categorization: `docs-internal/HOOK_CATEGORIZATION.md`
 - Migration guide: `docs-internal/PRE_COMMIT_PRE_PUSH_REORGANIZATION.md`
 
diff --git a/README.md b/README.md
@@ -40,7 +40,7 @@ Pick the quickstart that matches your needs:
 
 This project uses **19 GitHub Actions workflows** with Google Cloud Platform (GCP) Workload Identity Federation for secure deployments.
 
-**Quick setup**: [SECRETS.md](SECRETS.md) | **Full CI/CD status**: [docs/ci-cd/badges.mdx](docs/ci-cd/badges.mdx) | **Workflow details**: [.github/archive/audits-2025-11/WORKFLOW_AUDIT_REMAINING.md](.github/archive/audits-2025-11/WORKFLOW_AUDIT_REMAINING.md)
+**Quick setup**: [SECRETS.md](.github/SECRETS.md) | **Full CI/CD status**: [docs/ci-cd/badges.mdx](docs/ci-cd/badges.mdx) | **Workflow details**: [.github/archive/audits-2025-11/WORKFLOW_AUDIT_REMAINING.md](.github/archive/audits-2025-11/WORKFLOW_AUDIT_REMAINING.md)
 
 ---
 
@@ -277,7 +277,7 @@ print(f'Databases: {list(result.databases.keys())}')
 "
 ```
 
-**See**: [ADR-0056: Database Architecture](adr/adr-0056-database-architecture-and-naming-convention.md) | [Migration Script](migrations/000_init_databases.sh) | [Database Validation Module](src/mcp_server_langgraph/health/database_checks.py)
+**See**: [ADR-0060: Database Architecture](adr/adr-0060-database-architecture-and-naming-convention.md) | [Migration Script](migrations/000_init_databases.sh) | [Database Validation Module](src/mcp_server_langgraph/health/database_checks.py)
 
 ## Quick Start
 
@@ -329,7 +329,7 @@ curl http://localhost:8000/health    # Test
 - **Pre-commit** (< 30s): Fast validation on changed files - commit frequently!
 - **Pre-push** (8-12 min): Comprehensive validation matching CI - prevents surprises!
 
-**See**: [Complete Installation Guide](docs/getting-started/installation.mdx) | [Day-1 Developer Guide](docs/getting-started/day-1-developer.mdx) | [Git Hooks Guide](TESTING.md#git-hooks-and-validation)
+**See**: [Complete Installation Guide](docs/getting-started/installation.mdx) | [Day-1 Developer Guide](docs/getting-started/day-1-developer.mdx) | [Git Hooks Guide](docs-internal/testing/TESTING.md#git-hooks-and-validation)
 
 ### 👤 Creating Test Users
 
diff --git a/deployments/QUICKSTART.md b/deployments/QUICKSTART.md
@@ -47,7 +47,7 @@ print(f'Databases: {list(result.databases.keys())}')
 "
 ```
 
-**See**: [ADR-0056: Database Architecture](../adr/adr-0056-database-architecture-and-naming-convention.md) for complete architecture documentation.
+**See**: [ADR-0060: Database Architecture](../adr/adr-0060-database-architecture-and-naming-convention.md) for complete architecture documentation.
 
 ## Quick Start Options
 
diff --git a/docs-internal/DOCS_VALIDATION_SIMPLIFICATION.md b/docs-internal/DOCS_VALIDATION_SIMPLIFICATION.md
@@ -506,7 +506,7 @@ git push
 ### Documentation
 - [Archive README](../scripts/validators/archive/README.md) - Deprecated validators
 - [CLAUDE.md](../CLAUDE.md) - Updated developer workflow
-- [TESTING.md](../TESTING.md) - Updated testing and validation approach
+- [TESTING.md](testing/TESTING.md) - Updated testing and validation approach
 - [Makefile](../Makefile) - Updated documentation targets
 
 ### Code
diff --git a/docs-internal/DUPLICATE_VALIDATOR_ANALYSIS_2025-11-16.md b/docs-internal/DUPLICATE_VALIDATOR_ANALYSIS_2025-11-16.md
@@ -566,5 +566,5 @@ def test_pytest_addopts_flags_have_required_plugins():
 
 - [Codex Findings Remediation Report](./CODEX_FINDINGS_REMEDIATION_REPORT_2025-11-16.md)
 - [Script Inventory](../scripts/SCRIPT_INVENTORY.md)
-- [Testing Strategy](../TESTING.md)
+- [Testing Strategy](testing/TESTING.md)
 - [Validation Strategy](../docs/development/VALIDATION_STRATEGY.md)
diff --git a/docs-internal/PYTESTMARK_GUIDELINES.md b/docs-internal/PYTESTMARK_GUIDELINES.md
@@ -426,4 +426,4 @@ def test_with_freezegun():
 
 ---
 
-**Questions or issues?** See [TESTING.md](TESTING.md) or open a GitHub issue.
+**Questions or issues?** See [TESTING.md](testing/TESTING.md) or open a GitHub issue.
diff --git a/docs-internal/SESSION_2_COMPLETION_SUMMARY.md b/docs-internal/SESSION_2_COMPLETION_SUMMARY.md
@@ -262,7 +262,7 @@ python scripts/audit_resource_ratios.py: All ratios ≤ 4.0 ✅
 - [SESSION_2_INDEX.md](./SESSION_2_INDEX.md) - Navigation and context
 
 ### Related ADRs
-- [ADR-0054: Pod Failure Prevention Framework](./adr/adr-0054-pod-failure-prevention-framework.md)
+- [ADR-0054: Pod Failure Prevention Framework](../adr/adr-0054-pod-failure-prevention-framework.md)
 
 ### External References
 - [GKE Autopilot Resource Limits](https://cloud.google.com/kubernetes-engine/docs/concepts/autopilot-resource-requests)
diff --git a/docs-internal/VALIDATOR_CONSOLIDATION_PLAN_2025-11-17.md b/docs-internal/VALIDATOR_CONSOLIDATION_PLAN_2025-11-17.md
@@ -467,7 +467,7 @@ Following the pattern successfully applied to pytest config and ADR synchronizat
 
 - [Duplicate Validator Analysis](./DUPLICATE_VALIDATOR_ANALYSIS_2025-11-16.md)
 - [Codex Findings Remediation Report](./CODEX_FINDINGS_REMEDIATION_REPORT_2025-11-16.md)
-- [Testing Strategy](../TESTING.md)
+- [Testing Strategy](testing/TESTING.md)
 - [Validation Strategy](../docs/development/VALIDATION_STRATEGY.md)
 
 ---
diff --git a/docs-internal/architecture/agentic-loop-guide.md b/docs-internal/architecture/agentic-loop-guide.md
@@ -389,7 +389,7 @@ print(f"Refinement attempts: {state['refinement_attempts']}")
 
 ## References
 
-- **ADR**: [ADR-0024: Agentic Loop Implementation](../adr/0024-agentic-loop-implementation.md)
+- **ADR**: [ADR-0024: Agentic Loop Implementation](../../adr/adr-0024-agentic-loop-implementation.md)
 - **Implementation Summary**: [IMPLEMENTATION_SUMMARY.md](../archive/IMPLEMENTATION_SUMMARY.md)
 - **Anthropic Guides**:
   - [Building Agents with the Claude Agent SDK](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)
@@ -717,7 +717,7 @@ COMPACTION_THRESHOLD=8000
 
 For questions or issues with the agentic loop implementation:
 
-1. Check the [ADR-0024](../adr/0024-agentic-loop-implementation.md) for design rationale
+1. Check the [ADR-0024](../../adr/adr-0024-agentic-loop-implementation.md) for design rationale
 2. Review [IMPLEMENTATION_SUMMARY.md](../archive/IMPLEMENTATION_SUMMARY.md) for technical details
 3. Run tests: `./scripts/test_agentic_loop.sh`
 4. Check logs for compaction/verification events
diff --git a/docs-internal/documentation-versioning.md b/docs-internal/documentation-versioning.md
@@ -450,7 +450,7 @@ Example:
 For questions about documentation versioning:
 1. Review this guide
 2. Check recent documentation commits
-3. Review [ADR-0018: Semantic Versioning Strategy](../adr/0018-semantic-versioning-strategy.md)
+3. Review [ADR-0018: Semantic Versioning Strategy](../adr/adr-0018-semantic-versioning-strategy.md)
 4. Open a discussion on GitHub
 
 ---
diff --git a/docs-internal/migrations/MIGRATION.md b/docs-internal/migrations/MIGRATION.md
@@ -467,7 +467,7 @@ After rollback:
 
 - **Issues**: https://github.com/your-org/mcp-server-langgraph/issues
 - **Documentation**: [BREAKING_CHANGES.md](./BREAKING_CHANGES.md)
-- **ADR**: [adr/0026-lazy-observability-initialization.md](./adr/0026-lazy-observability-initialization.md)
+- **ADR**: [ADR-0026: Lazy Observability Initialization](../adr/adr-0026-lazy-observability-initialization.md)
 
 ---
 
diff --git a/docs-internal/operations/storage-backend-requirements.md b/docs-internal/operations/storage-backend-requirements.md
@@ -624,7 +624,7 @@ async def test_end_to_end_retention():
 
 - [TODO Catalog](TODO_CATALOG.md) - Original TODO analysis
 - [Technical Debt Sprint Progress](TECHNICAL_DEBT_SPRINT_PROGRESS.md)
-- [ADR-0012: Compliance Framework](../adr/0012-compliance-framework-integration.md)
+- [ADR-0012: Compliance Framework](../adr/adr-0012-compliance-framework-integration.md)
 - [Retention Policy Spec](../docs/compliance/retention-policy.md)
 
 ---
diff --git a/docs-internal/sprints/todo-catalog.md b/docs-internal/sprints/todo-catalog.md
@@ -358,7 +358,7 @@ results = tavily.search(query, max_results=5)
 - [Technical Debt Sprint Plan](../TECHNICAL_DEBT_SPRINT.md)
 - [Monitoring Architecture](../docs/architecture/monitoring.md)
 - [Compliance Framework](../docs/compliance/README.md)
-- [ADR-0012: Compliance Framework Integration](../adr/0012-compliance-framework-integration.md)
+- [ADR-0012: Compliance Framework Integration](../adr/adr-0012-compliance-framework-integration.md)
 
 ---
 
diff --git a/docs-internal/testing/TESTING.md b/docs-internal/testing/TESTING.md
@@ -501,8 +501,8 @@ pytest --cov-report=term-missing               # Terminal with missing lines
 - [pytest Documentation](https://docs.pytest.org/)
 - [Hypothesis Documentation](https://hypothesis.readthedocs.io/)
 - [Coverage.py Documentation](https://coverage.readthedocs.io/)
-- [Project README](README.md)
-- [Contributing Guide](.github/CONTRIBUTING.md)
+- [Project README](../../README.md)
+- [Contributing Guide](../../.github/CONTRIBUTING.md)
 
 ---
 
diff --git a/examples/README.md b/examples/README.md
@@ -383,9 +383,9 @@ python -c "from mcp_server_langgraph.core.dynamic_context_loader import DynamicC
 ### Documentation
 
 - [Anthropic Best Practices Assessment](../reports/ANTHROPIC_BEST_PRACTICES_ASSESSMENT_20251017.md) - Full assessment report
-- [ADR-0023: Tool Design Best Practices](../adr/0023-anthropic-tool-design-best-practices.md)
-- [ADR-0024: Agentic Loop Implementation](../adr/0024-agentic-loop-implementation.md)
-- [ADR-0025: Advanced Enhancements](../adr/0025-anthropic-best-practices-enhancements.md)
+- [ADR-0023: Tool Design Best Practices](../adr/adr-0023-anthropic-tool-design-best-practices.md)
+- [ADR-0024: Agentic Loop Implementation](../adr/adr-0024-agentic-loop-implementation.md)
+- [ADR-0025: Advanced Enhancements](../adr/adr-0025-anthropic-best-practices-enhancements.md)
 - [Agentic Loop Guide](../docs-internal/AGENTIC_LOOP_GUIDE.md) - Technical deep-dive
 
 ### Anthropic Articles
diff --git a/runbooks/keycloak-down.md b/runbooks/keycloak-down.md
@@ -218,5 +218,5 @@ If issue persists after 30 minutes:
 ## References
 
 - [Keycloak Documentation](https://www.keycloak.org/documentation)
-- [Deployment Configuration](../deployments/kubernetes/base/keycloak-deployment.yaml)
+- [Deployment Configuration](../deployments/base/keycloak-deployment.yaml)
 - [Integration Guide](../integrations/keycloak.md)
diff --git a/runbooks/keycloak-slow.md b/runbooks/keycloak-slow.md
@@ -265,5 +265,5 @@ If latency remains above 2s after 1 hour:
 ## References
 
 - [Keycloak Performance Tuning](https://www.keycloak.org/high-availability/concepts-memory-and-cpu-sizing)
-- [Deployment Configuration](../deployments/kubernetes/base/keycloak-deployment.yaml)
+- [Deployment Configuration](../deployments/base/keycloak-deployment.yaml)
 - [Integration Guide](../integrations/keycloak.md)
diff --git a/runbooks/redis-down.md b/runbooks/redis-down.md
@@ -313,6 +313,6 @@ If issue persists after 30 minutes:
 ## References
 
 - [Redis Documentation](https://redis.io/documentation)
-- [Deployment Configuration](../deployments/kubernetes/base/redis-session-deployment.yaml)
+- [Deployment Configuration](../deployments/base/redis-session-deployment.yaml)
 - [Session Management Code](../src/mcp_server_langgraph/auth/session.py)
 - [Redis High Availability](https://redis.io/topics/sentinel)
diff --git a/runbooks/redis-memory.md b/runbooks/redis-memory.md
@@ -302,5 +302,5 @@ Set up Prometheus alerts at multiple thresholds:
 
 - [Redis Memory Optimization](https://redis.io/topics/memory-optimization)
 - [Redis Eviction Policies](https://redis.io/docs/manual/eviction/)
-- [Deployment Configuration](../deployments/kubernetes/base/redis-session-deployment.yaml)
+- [Deployment Configuration](../deployments/base/redis-session-deployment.yaml)
 - [Session Management Code](../src/mcp_server_langgraph/auth/session.py)
diff --git a/runbooks/redis-pool.md b/runbooks/redis-pool.md
@@ -368,4 +368,4 @@ If issue persists after tuning:
 - [Redis Connection Pooling](https://redis.io/docs/manual/clients/)
 - [redis-py Documentation](https://redis-py.readthedocs.io/en/stable/connections.html)
 - [Session Store Implementation](../src/mcp_server_langgraph/auth/session.py)
-- [Deployment Configuration](../deployments/kubernetes/base/deployment.yaml)
+- [Deployment Configuration](../deployments/base/deployment.yaml)
diff --git a/runbooks/session-errors.md b/runbooks/session-errors.md
@@ -368,4 +368,4 @@ If errors persist after 30 minutes:
 - [Session Management Implementation](../src/mcp_server_langgraph/auth/session.py)
 - [Redis Documentation](https://redis.io/documentation)
 - [Error Handling Best Practices](https://docs.python.org/3/tutorial/errors.html)
-- [Deployment Configuration](../deployments/kubernetes/base/deployment.yaml)
+- [Deployment Configuration](../deployments/base/deployment.yaml)
diff --git a/scripts/ci/check-links.py b/scripts/ci/check-links.py
@@ -113,7 +113,8 @@ def main():
 
     # Always exclude infrastructure directories (venv, node_modules, etc.)
     # These are not user-maintained docs and should never be checked
-    infrastructure_excludes = [".venv/", "venv/", "node_modules/", "__pycache__/", ".git/"]
+    # Also exclude template files which contain intentional placeholder links
+    infrastructure_excludes = [".venv/", "venv/", "node_modules/", "__pycache__/", ".git/", ".claude/templates/"]
     all_excludes = list(set(args.exclude + infrastructure_excludes))
 
     print("🔍 Checking for broken internal links...")

Original file line number	Diff line number	Diff line change
`@@ -47,7 +47,7 @@ print(f'Databases: {list(result.databases.keys())}')`
`47`	`47`	`"`
`48`	`48`	```
`49`	`49`
`50`		`-See: [ADR-0056: Database Architecture](../adr/adr-0056-database-architecture-and-naming-convention.md) for complete architecture documentation.`
	`50`	`+See: [ADR-0060: Database Architecture](../adr/adr-0060-database-architecture-and-naming-convention.md) for complete architecture documentation.`
`51`	`51`
`52`	`52`	`## Quick Start Options`
`53`	`53`
Original file line number	Diff line number	Diff line change
`@@ -426,4 +426,4 @@ def test_with_freezegun():`
`426`	`426`
`427`	`427`	`---`
`428`	`428`
`429`		`-Questions or issues? See [TESTING.md](TESTING.md) or open a GitHub issue.`
	`429`	`+Questions or issues? See [TESTING.md](testing/TESTING.md) or open a GitHub issue.`