Reconcile the Repository Defaults required-files tables with what Template-PSModule ships

[MariusStorhaug]

Repository defaults is normative: it states which files a module repository must carry. PSModule/Template-PSModule is the implementation: it is what a new repository actually starts from. Nothing checks that the two agree, so a maintainer following the page produces a repository that differs from every other repository in the organization, and finds out only when review or CI pushes back.

Request

What is confusing or missing

A maintainer bootstrapping a module reads the required-files table, adds what it lists, and reasonably assumes the result matches the template. Four separate places where that assumption failed were found on this one page in a single day:

• RepoType: Module as the repository custom property. The organization has no RepoType property; the correct one is Type.
• .github/workflows/workflow.yml as the layout entry. Every module repository names it Process-PSModule.yml; workflow.yml is only the file name inside the uses: reference to the reusable workflow.
• package-ecosystem: "powershell" in the Dependabot example. Dependabot has no PowerShell ecosystem, so following the example makes .github/dependabot.yml invalid.
• .github/copilot-instructions.md in the required-files tables, while the same page's own "Agent onboarding files" prose names only AGENTS.md and CLAUDE.md, and the template deliberately removed it in Template-PSModule#33.

All four are corrected in PSModule/docs#101, which is green and awaiting review. This issue is deliberately not about those four; it is about the fact that four unrelated drifts accumulated undetected on a page whose entire purpose is to be authoritative, and that nothing would stop a fifth.

The motivating case is PSModule/Lovdata#3, where a new module repository was bootstrapped by following the tables literally. .github/copilot-instructions.md was created because the table required it, then removed in a later commit once the drift surfaced. The page was the only source consulted, and it was wrong.

What should be true instead

The required-files table and the template hold the same set of files, and a reader can rely on that without cross-checking a real repository first.

Acceptance criteria

• Every row in the required-files table and the default layout table is reconciled against what Template-PSModule ships, in both directions: nothing required but missing from the template, nothing shipped by the template but absent from the tables
• Each difference found is resolved as either a documentation fix or a template fix, and which one is recorded
• The page states which of the two is authoritative when they disagree, so the next reader knows where to look
• A decision is recorded on whether the agreement should be verified automatically rather than by inspection

References

• PSModule/docs#101 — corrects the four known drifts on this page
• PSModule/docs#100 and PSModule/docs#102 — the individual drift reports
• Template-PSModule#37 — the template side of the community and governance files
• Template-PSModule#33 — removed .github/copilot-instructions.md from the template
• PSModule/docs#63 — distributing the mandatory repository files, which shares the same file set but solves distribution rather than verification
• MSXOrg/Custo — the managed-file distribution runtime the page points at

---

Technical decisions

Scope: Reconciliation and a decision about enforcement. Not a rewrite of the page, and not a re-litigation of the four drifts already fixed in #101.

Why not fold this into #101: That pull request is green and awaiting review. Widening its scope restarts the review it has already earned, and the reconciliation is a different kind of work: #101 fixes known-wrong statements, this establishes that the statements stay right.

Authority direction: State it explicitly on the page rather than leaving it implicit. The template is the implementation and is executable, so it is the more reliable of the two — but the page is what a human reads first. Whichever is chosen, the page should say so, because "which one is wrong" was the first question in every one of the four cases.

Enforcement, open question: Four drifts on one page suggests inspection is not enough. Options, in increasing cost:

• Nothing beyond this reconciliation, and accept that the page drifts again.
• A test in PSModule/docs that parses the required-files table out of the Markdown and asserts each path exists in Template-PSModule. Cheap, catches the "documented but not shipped" direction, which is the direction that cost time here. It requires the table to keep a parseable shape.
• The same check in both directions, which additionally catches files the template ships that the page never mentions — the .github/release.yml and .github/linters/ case 📖 [Docs]: Module repository defaults match how PSModule repositories actually work #101 also had to fix.
• Generate the table from the template rather than maintaining it by hand, which removes the failure mode entirely but changes how the page is authored.

Open: which of these to adopt. Resolve before the implementation plan is filled in.

Related but out of scope: PSModule/docs#95 renames this page. Whatever is decided here should survive that rename, so any check should key off the table rather than the file name.

---

Implementation plan

Reconciliation

• List the files Template-PSModule ships, at repository root and under .github/
• Compare against the required common files table and the default layout table, in both directions
• Record each difference with a decision: fix the page, or fix the template
• Apply the documentation fixes in PSModule/docs
• File or apply the template fixes in PSModule/Template-PSModule

Page changes

• State which of the page and the template is authoritative when they disagree

Enforcement

• Resolve the open question above and record the choice on this issue
• Implement the chosen check, or record why none is warranted