Repository navigation
Keep links to the renamed Repository Standard page resolving #487
Description
Activity
Referrer sweep executed. The decision recorded above — fix the referrers rather than add a redirect — is implemented across all three repositories:
Repository Pull request Files Template-PSModulePSModule/Template-PSModule#42 README.md,AGENTS.md,CONTRIBUTING.mdPSSemVerPSModule/PSSemVer#53 AGENTS.md,CONTRIBUTING.mdLovdataPSModule/Lovdata#22 README.md,AGENTS.md,CONTRIBUTING.mdAll eight files are covered, so
gh search code "Repository-Defaults" --owner PSModuleshould return no hits once the three merge. All three are drafts and depend on PSModule/docs#107: the URL they introduce returns 404 until publishing is restored.Two things changed relative to the plan above.
A second broken link was found in the same files.
https://msxorg.github.io/docs/Ways-of-Working/Issue-Format/returns 404; the page moved toWays-of-Working/Issues/Process/Format/. It is present in all three repositories and is corrected in the same pull requests, since it is the same class of defect in the same files and separating it would mean three more pull requests touching the same lines.The MSX links were left on
msxorg.github.io. The plan called for canonical hosts. That is unambiguous for PSModule —PSModule/docsdeclaressite_url = "https://psmodule.io/docs/"— so those links now usepsmodule.io. It is not settled for MSX:msxorg.github.ioredirects tomsx.no, butMSXOrg/docsstill declaressite_url = "https://msxorg.github.io/...", so its own configuration and its deployment disagree about which host is canonical. Rewriting the MSX links either way would be guessing. Only the broken MSX path was corrected. Open, and now the only thing keeping this issue from closing cleanly with its pull requests: whetherMSXOrg/docsshould declaremsx.noassite_url, which belongs in that repository rather than here.The last open item from the plan — recording on #478 whether distribution is now needed — remains, and this sweep is evidence for it: one rename produced eight broken links across four repositories, and only found them because an unrelated deployment bug was being investigated.
Body updated:
CasingStyleadded to the referrer table, the blast-radius open question resolved, and the plan items closed. What changed and why.A fourth referrer appeared while this issue was being worked, which settles the open question. PSModule/CasingStyle#22 adds
AGENTS.mdandCONTRIBUTING.mdfrom the baseline set. It was opened after the scan above, from a branch created before the correction existed, so it would have shipped two more dead links. The referrer set is not a list to be drained — it grows with every adoption. With 58 repositories carryingType: Moduleand #478 wanting these files distributed to all of them, a one-time sweep is a floor, not a fix.Template-PSModuleis the blocking referrer; every other copy is downstream of it.No action is needed on CasingStyle. Its branch already carries the corrected wording, and it is not an approximation — the copies were compared against
Template-PSModule's corrected branch directly:File Result CONTRIBUTING.mdbyte-identical, SHA-256 7970576693C631D7…on bothAGENTS.mdevery shared line identical; differs only by the repo-specific README.mddescription and the template-onlyTemplate quickstartbullet, both expectedAll four corrected links match exactly, including the
Issues/Process/Format/path and thepsmodule.iohost. Zero drift.On not patching managed files locally. The instinct is right and matches the Repository Standard: a local edit to a centrally managed file is drift, and guessing at wording that is still under review is how a fifth inconsistency gets created — the exact failure #484 exists to stop. The distinction worth recording is that adopting the managed source's settled pending wording verbatim is not a local change; it is a fast-forward, and it is verifiable by comparison rather than by judgment, as above. That is why byte-comparison was used instead of review. If PSModule/Template-PSModule#42's wording changes under review, the difference is the template's to propagate, and this issue will catch it.
Second broken link, already covered.
msxorg.github.io/docs/Ways-of-Working/Issue-Format/returns 404 today, independent of PSModule/docs#107 — the page moved toWays-of-Working/Issues/Process/Format/. It was found during the sweep and corrected in all three pull requests, and CasingStyle's copy already has the corrected path.Only one plan item remains, and it is gated on PSModule/docs#107 merging: confirm the search returns no hits and that the Repository Standard URL returns 200.
The MSX host question is now owned upstream: MSXOrg/docs#152.
Stating the ordering explicitly, because it is the part that is easy to get backwards:
MSXOrg/docsdeclares its real canonical host first, and only then are referrers rewritten. Rewriting referrers first would bake in a guess, and a guess in 58 repositories' worth of managed files is expensive to unwind.The evidence that settles which host is real:
`console
$ gh api repos/MSXOrg/docs/pages --jq '"(.html_url) cert=(.https_certificate.domains)"'
https://msx.no/docs/ cert=["msx.no"]$ curl -s https://msx.no/docs/Coding-Standards/GitHub-Actions/ | grep canonical
$ curl -s https://msx.no/docs/sitemap.xml | grep -m1 loc
https://msxorg.github.io/docs/Vision/
`msx.nois what GitHub Pages serves and what the certificate covers, butsrc/zensical.tomldeclaressite_url = "https://msxorg.github.io/docs/", so every canonical link and every sitemap entry names a host that 301s straight back. The site is telling search engines its canonical form is a redirect.This is the same failure shape as #486 — configuration and reality disagree, no check fails, and the only way to see it is to inspect the artifact rather than the green check mark. Worth noting that
PSModule/docsis the consistent counter-example:site_url = "https://psmodule.io/docs/"and its sitemap emitspsmodule.ioto match, which is why the PSModule half of this issue could be corrected with confidence while the MSX half could not.No change here. The decision recorded in this issue's body — MSX links stay on
msxorg.github.io, only the broken path corrected — stands and is still the right call: it matches whatMSXOrg/docscurrently declares, so it is consistent with the upstream source rather than ahead of it. When MSXOrg/docs#152 lands, the MSX host rewrite becomes a follow-up sweep with a settled answer behind it.Incidental confirmation of #486 found while checking this:
https://psmodule.io/docs/sitemap.xmlstill listsModules/Repository-Defaults/and has noRepository-Standardentry. The published sitemap is itself an artifact of the frozen build, independent of the run logs and the deployment timestamps.
PSModule/docs#96 renamed
Modules/Repository-DefaultstoModules/Repository-Standard. Restoring publishing (#106) makes that rename go live, and at that moment every existing link to the old path starts returning 404. Eight files across four repositories point at the old path today, and three of them are files thatTemplate-PSModulecopies into every new module repository, so the count grows with each repository created.Observed behavior
The old path is still the only one that resolves, because the site has not been republished since 2026-07-18:
Once #486 merges and the site rebuilds, these invert: the new path resolves and the old one 404s. Referrers, found with
gh search code "Repository-Defaults" --owner PSModule:Template-PSModuleREADME.md,AGENTS.md,CONTRIBUTING.mdPSSemVerAGENTS.md,CONTRIBUTING.mdLovdataREADME.md,AGENTS.md,CONTRIBUTING.mdCasingStyleAGENTS.md,CONTRIBUTING.md— added by PSModule/CasingStyle#22, after the scan aboveAll eight use
https://psmodule.github.io/docs/Modules/Repository-Defaults/, which is a second, independent drift:psmodule.github.ioonly 301s to the canonicalpsmodule.iodeclared assite_urlinsrc/zensical.toml.Expected behavior
A reader or agent following a repository-defaults link from any PSModule repository reaches the Repository Standard page. New repositories created from the template carry a link that resolves on the canonical domain.
Reproduction
AGENTS.mdin any repository in the table and follow the repository-defaults link.Environment
PSModule/docsbuilt with Zensical and served from GitHub Pages athttps://psmodule.io/docs/;psmodule.github.ioredirects there with a 301.Regression
Introduced by PSModule/docs#96, which renamed the page without updating referrers outside this repository. Not yet observable, because #486 keeps the rename from reaching the live site.
Workaround
None. The old path stops resolving the moment publishing is restored.
Acceptance criteria
Template-PSModule,PSSemVer, andLovdatareaches a page that resolves.Template-PSModulecarries a link that resolves.psmodule.iohost rather than relying on thepsmodule.github.ioredirect.References
Technical decisions
Redirect versus fixing referrers: fix the referrers. Zensical has no redirect support —
zensical/backlog#23, "Supportmkdocs-redirectsplugin functionality", is open, and this site'szensical.tomlloads only themetaandsearchplugins. A redirect would therefore have to be a hand-written stub page underModules/Repository-Defaults.mddoing a client-sidemeta refreshor script hop. That stub is a real page: it is built, indexed by search, and has to be excluded from navigation and kept correct forever, and it teaches future readers that renames are free. Against that, the referrers are enumerable, in-organization, and editable, and the link text already reads "repository defaults" rather than a URL. Fixing them is the smaller and more honest correction.Host. Update to
https://psmodule.io/docs/Modules/Repository-Standard/. Keepingpsmodule.github.ioworks only through a 301 and hides which host is canonical.Blast radius: resolved, and worse than a fixed set.
AGENTS.md,CONTRIBUTING.md, andREADME.mdare copied into module repositories, so the referrer set is not a list to be drained — it grows every time a repository adopts the baseline files. PSModule/CasingStyle#22 demonstrated this within hours: it was opened after the scan above and would have shipped two more dead links, from a branch created before the correction existed. The organization has 58 repositories withType: Module, and #478 wants these files distributed to all of them, so a one-time sweep is a floor, not a fix.Template-PSModuleis therefore the blocking referrer — every other copy is downstream of it — and the sweep is only durable once distribution carries the correction forward. Recorded on #478.External links. Links from outside the organization cannot be fixed and will 404. Accepted, given that Zensical cannot express a redirect today. Revisit if
zensical/backlog#23ships.Verification. No automated test exists for cross-repository link health. The equivalent repeatable verification is a search for the old path returning no hits, plus a request for the new path returning 200.
Implementation plan
gh search code "Repository-Defaults" --owner PSModuleand record the current referrer set.Template-PSModuleto the canonicalpsmodule.ioRepository Standard URL, so new repositories start correct. — 📖 [Docs]: Documentation links in the template resolve again Template-PSModule#42PSSemVerandLovdata, and any further repositories the re-run finds. — 📖 [Docs]: Documentation links in the community files resolve again PSSemVer#53, 📖 [Docs]: Documentation links in the community files resolve again Lovdata#22; ⚙️ [Maintenance]: CasingStyle meets the current repository standard and runs on Process-PSModule v6 CasingStyle#22 carries the corrected wording on its own branch, verified byte-identical to the templatehttps://psmodule.io/docs/Modules/Repository-Standard/returns 200 after Publish the documentation site on push and schedule again #486 merges.