Summary

The current markdown link checker (scripts/linting/Markdown-Link-Check.ps1) only validates external HTTP/HTTPS URLs and does not check if relative file path links actually exist in the repository. This allows broken relative links to pass validation.

Problem

During PR review, several broken relative links were discovered:

• ../../docs/contributing/ai-assisted-engineering.md (file does not exist)
• ../../copilot/ (directory does not exist)

These links were not flagged by the link checker because it only validates external URLs by making HTTP requests.

Current Behavior

The markdown-link-check npm package:

• ✅ Validates HTTP/HTTPS URLs by making actual requests
• ❌ Does NOT validate that relative file paths exist in the repository
• ❌ Does NOT check if referenced directories contain valid content

Desired Behavior

Add validation for relative file system paths to ensure:

• Relative file links point to existing files
• Relative directory links point to existing directories
• All markdown links are fully validated before merge

Proposed Solutions

1. Add remark-validate-links: A dedicated tool for validating markdown links including file system paths

   • Pros: Purpose-built for markdown link validation
   • Cons: Additional dependency

2. Add lychee: A fast link checker that supports both URLs and file paths

   • Pros: Fast, modern, supports many link types
   • Cons: Requires Rust installation or binary download

3. Custom PowerShell validation: Extend existing script to validate relative paths

   • Pros: No new dependencies, uses existing tooling
   • Cons: More maintenance burden

Implementation Notes

This should be implemented after the repository is made public to avoid issues with private repository access during link validation.

Acceptance Criteria

• Relative file path links are validated
• Broken relative links cause build failures
• Clear error messages indicate which files contain broken links
• Documentation updated with new validation requirements

Related Files

• scripts/linting/Markdown-Link-Check.ps1
• scripts/linting/markdown-link-check.config.json
• .github/workflows/ (CI/CD workflows)