⚙️ [Maintenance]: Cross-repository links are now verified

[Marius Storhaug (MariusStorhaug)]

Documentation that points to MSX-controlled GitHub repositories now stays trustworthy after a target changes. Each link's file and referenced heading are verified in pull requests and weekly, with results that distinguish a broken link from a target that cannot be reached.

New: Cross-repository link verification

Links to files and headings in MSX-controlled repositories are now checked before documentation is published and again each week. When a target has moved, its heading no longer exists, or readers cannot access it, the check identifies the link and the reason instead of leaving a dead reference for readers to find.

The check accepts only targets that an anonymous reader can open. No author workflow changes are needed: continue using the canonical cross-repository URLs prescribed by the Markdown standard.

---

Technical details

• Added .github/scripts/Test-CrossRepositoryLink.ps1, its 31-case Pester suite, and a separate scheduled Cross-repository links workflow.
• The check validates github.com and raw.githubusercontent.com links into MSXOrg, PSModule, and Storhaug-ting, including repository paths, named references, files, and GitHub-rendered heading slugs.
• Links into this repository resolve against the checkout, preventing a pull request that moves a file from passing against the default branch's pre-merge content.
• Repository visibility is probed before a 404 is classified; network failures, rate-limit exhaustion, inaccessible repositories, and broken links report separately. GITHUB_TOKEN provides rate-limit headroom only and does not make private targets valid public references.
• The check fails when no in-scope link is found and stops further requests after the API quota is exhausted.
• Implementation plan progress: all eight steps in Check the cross-repository links the Markdown standard tells authors to write #142 are complete. Published-site URLs remain outside this delivery and are tracked by Check the published-URL links the Markdown standard also asks authors to write #150.

Changed surface	Standards checked	Framework docs checked	Result
.github/scripts/** (PowerShell)	PowerShell/Scripts, PowerShell/Functions, Naming, Error Handling, Documentation	None (no framework-specific docs)	Aligned
tests/** (PowerShell)	Testing, PowerShell/Testing, PowerShell/Functions	None (no framework-specific docs)	Aligned
.github/workflows/**	GitHub Actions	None (no framework-specific docs)	Aligned
.github/linters/**	Markdown, Natural Language	None (no framework-specific docs)	Aligned
src/docs/**, CONTRIBUTING.md	Markdown, Documentation, Natural Language	Documentation Model	Aligned

Issue convergence sweep: scoped to open documentation-link validation work and the affected repositories. #142 is fully delivered; no other delivery issue is fully satisfied by this diff.

Relevant issues (or links)

• Resolves Check the cross-repository links the Markdown standard tells authors to write #142

Related work

• Followed by Check the published-URL links the Markdown standard also asks authors to write #150
• References 📖 [Docs]: A check that checked nothing is a failure, and the docs link check now agrees #134
• Followed by Distribute the Markdown link check instead of copying it a fourth time Custo#6
• Followed by Storhaug-ting/S62#10
• References 📖 [Docs]: Slug example now shows the anchor the function actually produces Storhaug-ting/Kilden#16

[Copilot]

Pull request overview

This PR adds CI validation for cross-repository links (into MSX-controlled GitHub orgs) so that moved files/anchors in other repositories are detected automatically, and it repairs several existing dead cross-repo links in the documentation.

Changes:

• Introduces a new PowerShell validator (Test-CrossRepositoryLink.ps1) plus an offline Pester suite with an in-process stub GitHub API.
• Adds a dedicated GitHub Actions workflow (Cross-Repository-Links.yml) to run the cross-repository link check on PRs/pushes and weekly.
• Updates documentation/standards and repairs broken links into PSModule repositories.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/Test-CrossRepositoryLink.Tests.ps1	Adds offline Pester coverage for cross-repository link parsing, resolution, anchoring, caching, and failure classification.
./.github/scripts/Test-CrossRepositoryLink.ps1	Implements the cross-repository link checker (GitHub API resolution + GitHub-style anchor validation).
.github/workflows/Cross-Repository-Links.yml	New workflow to run the cross-repo link check (PR/push + weekly schedule).
.github/workflows/Docs.yml	Clarifies that the existing Links job is intentionally network-free and that cross-repo checking lives elsewhere.
CONTRIBUTING.md	Documents running the new cross-repository link check locally before opening a PR.
src/docs/Coding-Standards/Markdown.md	Documents that links are checked and describes the new cross-repo check’s behavior/scope.
src/docs/Ways-of-Working/Git-Worktrees.md	Adds context that a referenced helper script link points to a private repository.
src/docs/Capabilities/process-psmodule/pipeline-stages.md	Repairs multiple PSModule cross-repo links to moved/renamed targets.
src/docs/Capabilities/process-psmodule/index.md	Replaces an obsolete dependency reference with links to current workflow/action structure.
.github/linters/.codespellrc	Avoids false positives from \p{...} Unicode-category escapes used in regexes.

Suppressed comments (2)

src/docs/Coding-Standards/Markdown.md:67

• Test-CrossRepositoryLink.ps1 is described here as resolving links "as published URLs", but the very next bullet scopes it to github.com and raw.githubusercontent.com. Rewording this to explicitly say “GitHub URLs” avoids confusion with published-site (Pages) URLs.

**Into another repository** — `Test-CrossRepositoryLink.ps1` resolves the links this standard asks you to write as published URLs. It runs as its own job, so a red check says the network check failed rather than the documentation being wrong, and again weekly, because a target repository moves content long after a pull request here has merged.

src/docs/Capabilities/process-psmodule/pipeline-stages.md:244

• Grammatically, “tests” is plural, so the verb should be “verify” (or rephrase to a singular subject like “test suite”).

The [PSModule - Module tests](https://github.com/PSModule/Process-PSModule/blob/main/.github/actions/Test-PSModule/src/tests/Module/PSModule/PSModule.Tests.ps1) verifies the following coding practices that the framework enforces:

[Marius Storhaug (MariusStorhaug)]

Right, and that sentence was doing exactly what this pull request exists to stop — a standard claiming a gate it does not have.

Fixed in d00db90. The bullet now says relative links, and cross-repository links on \github.com, are checked in CI, the section says the check resolves \github.com\ links rather than 'the links this standard asks you to write as published URLs', and there is a paragraph naming what is not covered: a \msxorg.github.io\ URL, which is the canonical form for a repository publishing to Pages. That gap is #150, which also records why it was not simply added here — a pull request adding a page and linking its published URL would fail until the page is published.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/docs/Capabilities/process-psmodule/pipeline-stages.md:66

• Grammar: this sentence is missing “to” (“…is used by … evaluate…”). As written it’s ungrammatical and slightly harder to read in the rendered docs.

  - [PSModule framework settings for style and standards for source code](https://github.com/PSModule/Process-PSModule/tree/main/.github/actions/Test-PSModule/src/tests/SourceCode)
- This produces a JSON-based report that is used by [Get-PesterTestResults](#get-test-results) evaluate the results of the tests.