refactor: slim template scaffolding to minimum baseline - #33
Merged
Marius Storhaug (MariusStorhaug) merged 9 commits intoJul 23, 2026
Merged
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ze module test function
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
July 23, 2026 21:27
This was referenced Aug 2, 2026
📖 [Docs]: Module repository defaults match how PSModule repositories actually work
PSModule/docs#101
Merged
Marius Storhaug (MariusStorhaug)
added a commit
to PSModule/docs
that referenced
this pull request
Aug 2, 2026
…actually work (#101) Following this page literally used to produce a repository that could not exist: a custom property the organization does not have, a CI workflow file no repository uses, an agent file the template deliberately removed, and a Dependabot entry that makes `dependabot.yml` invalid. Every statement below has been checked against the live organization and the repositories the page describes. ## Fixed: The documented repository custom property now exists The page asked for `RepoType: Module`. The PSModule organization has no `RepoType` property, so that step could not be completed. The required property is `Type`, a single select whose value for a module repository is `Module`. A new repository inherits `Other` until it is set explicitly. The page now also documents the rest of the organization property schema, so setting up a repository no longer requires reading the schema out of the API first: `Type`, `SubscribeTo`, `Description`, `Archive`, and `Upstream`, with their value types and what a module repository is expected to put in each. `SubscribeTo` is the opt-in that decides which managed files the distribution runtime owns in a repository, and it is now described next to the managed file distribution section it drives. ## Fixed: The CI workflow file is named the way real repositories name it The default repository layout listed `.github/workflows/workflow.yml`. Every module repository actually names its workflow `.github/workflows/Process-PSModule.yml`. `workflow.yml` is the file name of the shared workflow inside `PSModule/Process-PSModule`, which the module repository's workflow calls. The two roles were conflated in a single table row, so a reader creating a repository from the template would create a file that does not match the template or any existing module. The layout table now names the caller workflow correctly, and a short section spells out the two roles with the `uses:` reference that connects them. The Process-PSModule repository structure contract, which described the same file only as "workflow entrypoint", now names it too. ## Fixed: The Dependabot example no longer breaks Dependabot The supply-chain section told every module repository to configure `package-ecosystem: "powershell"`. Dependabot has no PowerShell ecosystem. Adding that entry does not produce PowerShell updates — it makes `.github/dependabot.yml` invalid, which puts the repository's whole Dependabot configuration at risk, including the `github-actions` entry that does work. For a page whose own text calls Dependabot "part of the repository supply-chain control, not an optional convenience", that is the worst possible failure mode. The example is now the configuration `Template-PSModule` actually ships: `github-actions`, daily, with a seven-day cooldown. `nuget` is documented as the addition for modules with .NET dependencies, the way `Sodium` uses it. A "PowerShell dependencies" subsection states the rule — configure only values Dependabot lists — links the two authoritative sources, and points at the upstream proposal to adopt when it ships. Because PowerShell dependencies are declared with `#Requires -Modules` and collected by the build, keeping them current is named as a review responsibility rather than something Dependabot will do. No repository had adopted the broken entry, so nothing was silently failing in production — this was documentation drift, and it is now closed before the next generated repository picks it up. The section also links the upstream work that would make a PowerShell ecosystem real, so the guidance reads as "not yet" rather than "never" and there is a specific thing to watch. ## Changed: `AGENTS.md` and `CLAUDE.md` are the required agent entry points The page required `.github/copilot-instructions.md` in two tables while its own "Agent onboarding files" section described only `AGENTS.md` and `CLAUDE.md`. The two tables now match the prose. `AGENTS.md` is the entry point that AGENTS.md-aware runtimes read directly, so a per-runtime copy of the same pointer is duplication that drifts. Runtime adapter files are described as optional rather than banned, because that is what the MSX guidance actually says, and the page now states which guidance says what so the next reader does not have to reconstruct it. ## Changed: The layout table agrees with the required files list The default layout table omitted `.github/release.yml` and the `.github/linters/` configuration that the required common files list on the same page demands, so the two tables disagreed with each other and with real repositories. The layout table now includes them. --- <details> <summary>Technical details</summary> - Changed files: `src/docs/Modules/Repository-Defaults.md` and `src/docs/Modules/Process-PSModule/repository-structure.md`. - **Custom properties.** Read from `gh api /orgs/PSModule/properties/schema`, cross-checked against `/repos/PSModule/<repo>/properties/values` for `Template-PSModule`, `Domeneshop`, `Base64`, `Jwt`, `Toml`, `Sodium`, and `Context`. All module repositories carry `Type=Module`; `Template-PSModule` carries `Type=Template`. `SubscribeTo` is currently unset on all of them. The `props.Type:Module` qualifier was verified with `gh search repos --owner PSModule 'props.Type:Module'`. - **Workflow file name.** Listing `.github/workflows` in the same repositories returns exactly `Process-PSModule.yml` in every one. `Template-PSModule`'s copy calls `uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@<sha>`, which is where the `workflow.yml` name legitimately appears. - **Dependabot ecosystem.** `PACKAGE_MANAGER_LOOKUP` in `common/lib/dependabot/config/file.rb` on `dependabot-core@main` enumerates the valid values; `powershell` is not among them, and GitHub's own options reference contains no occurrence of the string. `.github/dependabot.yml` was read from `Template-PSModule`, `Domeneshop`, `Base64`, `Jwt`, `Toml`, `Sodium`, `Context`, `GitHub`, and `Lovdata`: all use `github-actions` only, except `Sodium`, which adds `nuget`. `gh search code --owner PSModule 'package-ecosystem powershell'` returns nothing, so no repository adopted it. The template's `daily` interval and `cooldown.default-days: 7` were copied from the file it ships, and `cooldown` was confirmed as a supported option in the Dependabot options reference. - One claim was deliberately softened: the exact blast radius of an invalid ecosystem value is not stated in public GitHub documentation that I could find, so the page says an invalid file "puts the repository's whole Dependabot configuration at risk" rather than asserting that all updates stop. - Upstream support is proposed but not shipped: dependabot/dependabot-core#15501 requests the ecosystem and dependabot/dependabot-core#15666 implements it for native `#Requires -Modules` and `RequiredModules` declarations against the PowerShell Gallery. That pull request is open with review required, so it does not change what is valid today; the page links it so the section is revisited when it lands rather than staying pessimistic forever. Notably its scope matches how PSModule modules already declare dependencies. - The same invalid entry still exists in the managed source at `PSModule/Distributor` → `Repos/Module/dependabot.yml/.github/dependabot.yml`, which is where the page's snippet came from. Filed separately so it is not carried into `MSXOrg/Custo`. - **Agent files.** `.github/copilot-instructions.md` is present in 2 of 96 organization repositories (`PSModule/GitHub` and `PSModule/docs`); `Template-PSModule` removed it in PSModule/Template-PSModule#33. MSX guidance was read first-hand and is not uniform: [Ways of Working → Agentic Development](https://msxorg.github.io/docs/Ways-of-Working/Agentic-Development/) lists the per-repository pointer files as `AGENTS.md`, the `CLAUDE.md` that imports it, and path-scoped adapters, while the [agentic development capability spec](https://msxorg.github.io/docs/Capabilities/agentic-development/spec/) and its design page name `.github/copilot-instructions.md` explicitly as a client adapter that **MAY** add runtime-specific loading rules. Neither makes it mandatory, so the page treats it as optional rather than forbidden, and says so. - **Layout additions** were cross-checked against the repository trees of `Template-PSModule`, `Domeneshop`, `Base64`, and `Jwt`, which all carry `.github/release.yml` and a `.github/linters/` directory. - **Checked and left unchanged:** `main` as the default branch (correct in all sampled repositories) and the branch-protection claim (correct — `/repos/PSModule/Base64/rules/branches/main` reports pull-request, code-owner-review, linear-history, and squash-only rules sourced from an organization ruleset). - `markdownlint-cli2` was run against both changed files with `.github/linters/.markdown-lint.yml`; no issues. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `src/docs/Modules/Repository-Defaults.md` | MSX documentation conventions, PSModule doc link patterns | PSModule organization property schema, `Template-PSModule`, `Process-PSModule` caller contract, MSX Agentic Development and its capability spec, Dependabot options reference | Fixed in this PR | | `src/docs/Modules/Process-PSModule/repository-structure.md` | MSX documentation conventions | `Process-PSModule` caller contract | Fixed in this PR | **Issue convergence sweep.** This pull request opened against #100 (custom property and workflow filename). #102 was filed independently and lists three items: the workflow filename, `.github/copilot-instructions.md`, and the Dependabot ecosystem. Its workflow-filename item was already satisfied by the first commits here, so the remaining two were added rather than opened as a second pull request against the same file. The finished diff satisfies every acceptance criterion in #102 except the one that is out of scope for this repository — the `PSModule/Distributor` managed file — which is filed as its own issue and linked below. Both issues therefore close with this pull request. **Why one pull request instead of a stack.** A stacked layer was considered, since this pull request was already open on the same file. Both changes are corrections to one page with no independent landing requirement; the only reason to stack was textual conflict, and this pull request had received no review. Stacking would have added bottom-up merge and retarget overhead while #96 is separately renaming this page, increasing conflict exposure for no review benefit. Splitting is still cheap if a reviewer prefers it. </details> <details> <summary>Relevant issues (or links)</summary> - Fixes #100 - Fixes #102 - Related, tracked separately: PSModule/Distributor#16 </details> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Why
This is PR 2 in the stacked simplification. The template should start lean and practical, not present optional feature catalog examples.
Validation