Skip to content

Commit 09107c4

Browse files
Framework contracts use direct en-US prose (#580)
Framework maintainers get shorter, direct en-US specification and reference prose. The existing requirements, workflow interfaces, examples, release policy, and publication guarantees stay unchanged. Module authors do not need to change code, settings, or caller workflows. <!-- ANNOUNCEMENT STOP --> ## Changed: Framework guidance states existing contracts directly The design uses `behavior` and removes the subjective phrase `sensible defaults`. The principles describe linear version history and colocation without first-person narration. Reference descriptions use clear subjects and present tense. The patch-version description states intended compatibility instead of the absolute `no risk` promise, under the explicit handback in #562. This is a wording change, not a SemVer policy change or evidence of new runtime enforcement. Procedures stay imperative. All eleven assigned pages were read in full before editing. Nine pages change; the normative specification and scenario matrix are intentional no-change reviews. No proposal-only artifact-root section is imported. The protected fingerprint mechanism and its related automation claims remain unchanged for #577. The mock-policy and major-policy decisions remain separate. <details> <summary>Technical details</summary> ### Source and delivery identities - Fresh-main PR base: `PSModule/Process-PSModule@64ffb1d`. - Pushed candidate: `PSModule/Process-PSModule@b8a2e4f`, branch `framework-contract-prose`, base branch `main`. - [Complete scoped comparison](64ffb1d...b8a2e4f): nine Markdown files, 47 insertions and 51 deletions. No other repository path changes. - The draft opened after the first real slice, `9ba4a606ca4a6aa2e460b8e994c9fdc9eff82631`. Small follow-ups are `769fad09b875efec70c2fc6199f9a9c53297990f`, `30d6bc69fcf8ff9c0673e8c055a3b35927f69276`, and `b8a2e4ff2056409f89289a3209f5b08c3ad42031`. No old proposal or first-pass PR is amended. - Current source and issue-body ownership were rechecked before each commit. Main remained at the released source. The separate #541 head remains `2001551566898e59efc764e68450c2238667d607` on `complete-artifact-path-isolation`; its proposal and owner branch are untouched. The recorded issue handback is the authority for existing pipeline prose, not permission to import that proposal's additions. ### Writing sources The fixed baseline is `MSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs`: [Documentation Model](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Documentation-Model.md), [Natural Language](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md), [Writing Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md), [Markdown](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Markdown.md), [Documentation](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Documentation.md), and the applicable specification/design/reference/standard [templates](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md). Their artifact distinctions remain intact; no template scaffolding is added. The [official STE overview](https://www.asd-ste100.org/about_STE.html), [FAQ](https://www.asd-ste100.org/STE_faq.html), and relevant [Issue 9](https://doi.org/10.5281/zenodo.23666006) rules were read. Issue 9 rules 3.2, 3.6, 4.1-4.2, and 6.1-6.6 informed tense, active voice, short complete sentences, and descriptive paragraphs. The locally retained official PDF MD5 is `9c720341c350ed77943b2c73d01c716f`, matching the official record. No manual content is republished. The bounded review and scans do not certify full ASD-STE100 conformance. ### Complete reviewed scope and before/after evidence All paths below are under `docs/content/`. The before text comes from the immutable PR base above; the after text is in the pushed candidate. Natural Language supplies en-US and direct language, the Documentation Model preserves normative contracts without implying implementation, and STE guidance supplies short complete sentences and active descriptive language. | Page | Review | Concrete before to after | Preserved distinction | | --- | --- | --- | --- | | `specification/index.md` | Changed | `aimed at people maintaining Process-PSModule itself` to `for maintainers of Process-PSModule` | Maintainer/module-author roles, `normally`, and both reader links remain. | | `specification/spec.md` | No change, whole page exact | FR1 still says `The pipeline MUST compile the PowerShell module source code into a module artifact` | Every requirement, modality, FR/NFR ID, scenario, and publication/quality guarantee stays exact. A requirement is not CI evidence. | | `specification/design.md` | Changed | `behaviour` to `behavior`; `everything else uses sensible defaults` to `Other settings use defaults` | Same reusable entry point, caller/settings contract, phase roles, runtime enrichment, release decisions, and alternatives. | | `specification/principles-and-practices.md` | Changed | `we only maintain a single linear ancestry of versions` to `maintains one linear version history` | Latest-only maintenance; the `2.1.3` security fix does not go to 1.x. Dependency declarations and parameter descriptions retain their colocation examples and exact code tokens. | | `reference/pipeline-stages.md` | Changed | `report that is used by ... evaluate the results` to `report that ... uses to evaluate the test results` | Same report consumer, stage names/order, coverage, root-only phases, runtime paths, publication/cleanup guarantees, and artifact behavior. | | `reference/powershell-module-standard.md` | Changed | `resource or behaviour groups` to `resource or behavior groups`; `knobs` to `inputs` | Layout rules, normative force, test IDs, discovery precedence, examples, mock requirements, version resolution, and publication sequence remain. | | `reference/repository-standard.md` | Changed | `operates at the same altitude as` to `complements`; `then points` to `then point` | Unchanged MSX rules still apply. Module and non-module scope, both baseline expectations, required files, ownership, examples, and attribution requirements remain. | | `reference/scenario-matrix.md` | No change, whole page exact | The scenario table, conditional cells, and all four footnotes stay exact | Important-change gates, SHA matching, manual Patch releases, cleanup-only closed PRs, and stable cleanup retries remain. | | `reference/settings.md` | Changed | `By default, it will look for` to `The default path is` | Same JSON/YAML/PSD1 formats, `.github/PSModule.yml` default, authorable/runtime boundary, and complete settings/default tables and example. | | `reference/versioning.md` | Changed with protected regions | `with no risk of breaking functionality` to `intended to preserve compatibility` | Same major/minor/patch/no-bump classifications, optional/required parameter distinctions, examples, quoted sources, latest-only policy, and protected automation text. | | `reference/workflow-inputs.md` | Changed | `For how to wire it up` to `For caller configuration` | Exact inputs/defaults, four declared secrets, required flags, GitHub-token/App permission distinction, and permission example remain. | The two no-change Git blob identities are exact on base and head: `specification/spec.md` is `5755abf2797a699e0ef0846ac2521cb1fb90b2bb`; `reference/scenario-matrix.md` is `d9c5490f5379fe94adf94df6ac349dfc0b82b8d1`. ### Preservation results Pre-edit session evidence records concrete original text, its expected wording property, and source-backed acceptance before repository edits. Nine intended wording cases fail on the original source; all eleven page-level cases pass on the pushed candidate, including the two no-change cases. The session-only comparison reports zero preservation failures. | Checked surface | Result | | --- | --- | | Source structure | All 120 headings, 11 explicit anchors, eight front-matter titles, and 11 requirement IDs preserved exactly and in order. | | Normative/interface tokens | All 144 requirement-modal tokens, 652 inline-code spans, 269 numeric literals, 233 table rows, and 148 bold labels preserved exactly and in order. | | Code and examples | All 22 fenced examples and every inline code example preserved exactly. Another 43 example-bearing paragraphs remain text-exact. The three narrative examples in principles use shorter prose with the same scenarios and exact literals. No example is removed. | | Source links and quotations | All 134 source link targets and seven quoted spans preserved exactly. No external quotation, legal text, or actual attribution is rewritten. | | Rendered site | All 317 rendered anchor IDs and 1,055 rendered link targets across the eleven built pages match the pre-edit site baseline. This is preservation evidence, not an external-reachability audit. | | Protected passages | All 13 selected policy/automation/contract passages remain text-exact after line-ending normalization. | | Supported behavior | Hunk review preserves supported roles, compatibility classifications, inputs/defaults, publication/recovery guarantees, dependency order, runner-only exceptions, and literal identifiers. No wording claims new shipping or CI enforcement. | The protected passages include the public-API major policy, latest-version support policy, API-fingerprint section, both related automation-claim paragraphs, mocked-environment requirement, module-owned boundary-mock rule, linear maintenance policy, version resolution/publication sequence, pipeline runtime contract, root-only phase/discovery rules, framework-generated coverage guarantee, and stable publication/cleanup section. The fingerprint source is blob `ee2eafdd83405ab42da7a25aa5f6e9ff367e6d5e`, base lines 127-155; its section SHA-256 remains `fb098e0eea00a129b7f87f13806acc104de6ad47439769355d2d2c8fcf824e23`. The selected main pipeline page contains neither a Consumer artifact root section nor a `<WorkingDirectory>/.PSModule/` token. Both remain absent. Existing paths are unchanged; no unmatched proposal content or runner-only exception is added, removed, or reinterpreted. ### Existing checks and accepted review The existing repository Markdown configuration passes on all eleven explicit paths, before edits and on the completed source: ```powershell npx --no-install markdownlint-cli2 --config .github\linters\.markdown-lint.yml docs\content\specification\index.md docs\content\specification\spec.md docs\content\specification\design.md docs\content\specification\principles-and-practices.md docs\content\reference\pipeline-stages.md docs\content\reference\powershell-module-standard.md docs\content\reference\repository-standard.md docs\content\reference\scenario-matrix.md docs\content\reference\settings.md docs\content\reference\versioning.md docs\content\reference\workflow-inputs.md ``` Result: 11 files, 0 issues. An initial Windows wildcard invocation selected only seven files; it was corrected to the explicit eleven-file command above, not treated as full-scope evidence. The existing site command, `zensical build --clean` from `docs`, passes before and after the changes with `No issues found`. `git diff --check` passes for the complete base-to-head change. The session-only preservation/wording command also passes at exact pushed head `b8a2e4ff2056409f89289a3209f5b08c3ad42031`. No standalone documentation-link checker is present in this main tree. The link-check scripts named in the MSX Markdown standard belong to the MSX docs repository, not this repository. No dependency was installed; no enforcement tool, prose/inventory/implementation-shape snapshot test, or repository audit document is added. All six applicable hosted checks succeed at the exact candidate: Docs Build and Lint, repository Lint code base, CodeQL, Actions analysis, and Copilot review. Publication is skipped as expected on the draft. Copilot review was explicitly requested with the CLI-supported `@copilot` value. Its [completed review](#580 (review)) is `APPROVED` at `b8a2e4ff2056409f89289a3209f5b08c3ad42031`, with no inline comments or active issues. [Docs run](https://github.com/PSModule/Process-PSModule/actions/runs/41842157105), [repository lint run](https://github.com/PSModule/Process-PSModule/actions/runs/41842157084), and [hosted review run](https://github.com/PSModule/Process-PSModule/actions/runs/41842463614) retain the results. The coordinating parent also accepted the content at this exact head after independently reading all nine changed-page diffs and comparing all eleven pages. Its comparison preserves headings, inline literals, destinations, fences, table rows, modality sequences, the fingerprint section and related automation text, and mocked-environment requirements. This records content acceptance only; the PR remains draft and no readiness or merge action is authorized. ### Alignment and residual decisions | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Specification index, design, and principles | Fixed MSX writing/Markdown and specification/design templates; STE clarity principles | Entire released spec/design/principles set | Aligned within released linguistic scope; normative spec unchanged. | | Pipeline, settings, and workflow-input references | Fixed MSX writing/Markdown and reference template | Existing stage/runtime/caller contracts and scenario matrix | Aligned; all contract tables/examples and protected guarantees unchanged. | | Module and repository standards | Fixed MSX writing/Markdown and standard template | Layout, repository roles, test, version, and publishing guidance | Aligned; mock-policy conflict remains #563. | | Versioning reference | Fixed MSX writing/Markdown and reference/standard templates | SemVer classifications and released no-risk wording exception | Aligned within handback; fingerprint truth and core/major-policy conflicts remain #577 and #573. | The delivery issue's pre-edit read, expectations, baseline, small-commit wording, ownership-recheck, and local current-head validation steps are complete. The scoped convergence sweep covered open `documentation-writing-alignment` issues, the protected follow-ups, the eleven owned paths, and the disjoint first-pass PR paths. No additional issue is closed by this bounded prose change. Residual decisions are precise: #577 reconciles the unsupported fingerprint mechanism and related claims with the real resolver after #359/#524 producer decisions; #563 decides mock policy by test category; #573 decides bootstrap-core versus complete-public-API major policy. No runtime, framework upgrade, site redesign, release-label, readiness, merge, or automation change is made. This PR stays draft. </details> <details> <summary>Related references</summary> - Resolves #562. - References #577, with #359 and #524 as producer context. - References #563 and #573 for the separate policy decisions. - References #541 for the separate pipeline-prose handback; its proposal and branch stay unchanged. </details>
1 parent bc376d0 commit 09107c4

9 files changed

Lines changed: 47 additions & 51 deletions

File tree

‎docs/content/reference/pipeline-stages.md‎

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,19 +5,16 @@ description: The job-by-job breakdown of the Process-PSModule workflow, from Pla
55

66
# Pipeline stages
77

8-
The Process-PSModule workflow composes its work from a set of reusable jobs. Each
9-
one is described below, in the order it runs, with a link to the workflow that
10-
implements it.
8+
The Process-PSModule workflow uses reusable jobs. The sections below describe the jobs in the order they run and link to their workflows.
119

12-
For which of these jobs run in a given trigger scenario, see the [scenario matrix](scenario-matrix.md).
10+
The [scenario matrix](scenario-matrix.md) defines which jobs run for each trigger scenario.
1311

1412
## Plan
1513

1614
[workflow](https://github.com/PSModule/Process-PSModule/blob/main/.github/workflows/Plan.yml)
1715

18-
The Plan job is the single decision point of the workflow. It reads the settings file (`.github/PSModule.yml`),
19-
collects event context from GitHub, and decides what should happen in the rest of the process. Using that
20-
situational awareness, it calculates the next module version.
16+
The Plan job is the workflow's single decision point. It reads the settings file (`.github/PSModule.yml`),
17+
collects GitHub event context, and decides what should happen in the rest of the process. It uses this context to calculate the next module version.
2118

2219
The user-facing settings file stays in `.github/PSModule.yml`. The workflow enriches that input into an internal runtime
2320
`Settings` object passed between jobs. In this runtime contract, execution decisions are phase-owned (`*.Enabled`), test
@@ -65,7 +62,7 @@ suite matrices are computed under each owning test phase, and resolved version m
6562

6663
- Tests the source code in parallel (matrix) using:
6764
- [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)
68-
- This produces a JSON-based report that is used by [Get-PesterTestResults](#get-test-results) evaluate the results of the tests.
65+
- Produces a JSON-based report that [Get-PesterTestResults](#get-test-results) uses to evaluate the test results.
6966

7067
For the coding practices this step enforces, see [framework test IDs](framework-test-ids.md#source-code-tests).
7168

@@ -75,7 +72,7 @@ For the coding practices this step enforces, see [framework test IDs](framework-
7572

7673
- Lints the source code in parallel (matrix) using:
7774
- [PSScriptAnalyzer rules](https://github.com/PSModule/Invoke-ScriptAnalyzer)
78-
- This produces a JSON-based report that is used by [Get-PesterTestResults](#get-test-results) evaluate the results of the linter.
75+
- Produces a JSON-based report that [Get-PesterTestResults](#get-test-results) uses to evaluate the linter results.
7976

8077
## Framework test
8178

@@ -84,7 +81,7 @@ For the coding practices this step enforces, see [framework test IDs](framework-
8481
- Tests and lints the module in parallel (matrix) using:
8582
- [PSModule framework settings for style and standards for modules](https://github.com/PSModule/Process-PSModule/tree/main/.github/actions/Test-PSModule/src/tests/Module)
8683
- [PSScriptAnalyzer rules](https://github.com/PSModule/Invoke-ScriptAnalyzer)
87-
- This produces a JSON-based report that is used by [Get-PesterTestResults](#get-test-results) evaluate the results of the tests.
84+
- Produces a JSON-based report that [Get-PesterTestResults](#get-test-results) uses to evaluate the test results.
8885
- **Code coverage for framework-generated code**: This step collects code coverage for framework-generated
8986
boilerplate. During the [build step](#build-module), [Build-PSModule](https://github.com/PSModule/Build-PSModule)
9087
injects boilerplate code into the compiled `.psm1` file — including type accelerator registration for public classes
@@ -106,7 +103,7 @@ For the checks this step enforces on the built module, see [framework test IDs](
106103
- `tests/BeforeAll.ps1`: Runs once before all module-local test matrix jobs to set up the test environment.
107104
- `tests/AfterAll.ps1`: Runs once after all module-local test matrix jobs complete to clean up the test environment.
108105
- The workflow checks only those exact repository-root paths; phase detection is non-recursive.
109-
- This produces a JSON-based report that is used by [Get-PesterTestResults](#get-test-results) to evaluate the results of the tests.
106+
- Produces a JSON-based report that [Get-PesterTestResults](#get-test-results) uses to evaluate the test results.
110107

111108
How to write these tests, including the Pester version requirement and shared-infrastructure patterns, is covered in
112109
[Writing module tests](../guides/writing-module-tests.md).
@@ -116,7 +113,7 @@ How to write these tests, including the Pester version requirement and shared-in
116113
[workflow](https://github.com/PSModule/Process-PSModule/blob/main/.github/workflows/Get-TestResults.yml)
117114

118115
- Gathers the test results from the previous steps and creates a summary of the results.
119-
- If any tests have failed, the workflow will fail here.
116+
- If any tests fail, the workflow fails here.
120117

121118
## Get code coverage
122119

@@ -126,7 +123,7 @@ How to write these tests, including the Pester version requirement and shared-in
126123
- Aggregates coverage from the [Framework test](#framework-test) step (framework-generated boilerplate) and the
127124
[Test module](#test-module) step (module author code). A command executed in either step counts as covered, so
128125
framework-generated lines do not count against the module author's coverage target.
129-
- If the code coverage is below the target, the workflow will fail here.
126+
- If the code coverage is below the target, the workflow fails here.
130127

131128
## Publish module
132129

‎docs/content/reference/powershell-module-standard.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ The framework treats `src/` as the source for the compiled module. Place code in
4444
Layout rules:
4545

4646
- **One declaration per file.** Filename matches the declared symbol exactly, including casing.
47-
- **Group by domain.** Use resource or behaviour groups — not verb folders, not endpoint paths.
47+
- **Group by domain.** Use resource or behavior groups — not verb folders, not endpoint paths.
4848
- **Mirror public and private domains.** Public command under `src/functions/public/Projects/` has related private helpers under `src/functions/private/Projects/`.
4949
- **No nested functions.** Do not define helper functions inside other functions. Extract helper logic to a separate function file and decide whether it belongs in `src/functions/private/<Group>/` (internal-only) or `src/functions/public/<Group>/` (part of the module API).
5050
- **Declare dependencies where they are used.** Use `#Requires -Modules <Name>` at the top of each function file that needs an external module. Do not add `RequiredModules` to `src/manifest.psd1` — the build collects all `#Requires` declarations automatically and writes them into the compiled manifest. Entries in `src/manifest.psd1` are silently ignored for this purpose.
@@ -65,7 +65,7 @@ Layout rules:
6565

6666
## SOLID applied
6767

68-
- **Single Responsibility.** One file, one function. One function, one user-visible behaviour. If the synopsis needs "and", split it.
68+
- **Single Responsibility.** One file, one function. One function, one user-visible behavior. If the synopsis needs "and", split it.
6969
- **Open/Closed.** Extend via parameter sets, private helpers, or new files — not boolean switches that fork large blocks.
7070
- **Liskov.** A derived class must work wherever the base is expected.
7171
- **Interface Segregation.** Narrow, intent-named parameter sets.
@@ -79,9 +79,9 @@ Every parameter that has a natural default should declare one. The most common u
7979

8080
- Prefer `= 'main'` over making `-Branch` mandatory in commands that act on branches.
8181
- Prefer sensible page sizes, counts, or ranges over requiring callers to specify them.
82-
- Prefer `= $false` for switches rather than leaving the behaviour implicit.
82+
- Prefer `= $false` for switches rather than leaving the behavior implicit.
8383

84-
This is a usability expression of the **Open/Closed** principle: the common path is open by default; callers that need different behaviour extend it by supplying alternatives — they are never forced to know the default just to get started.
84+
Parameter defaults apply the **Open/Closed** principle. The common path is open by default. Callers that need different behavior extend it with alternative inputs. They are never forced to know the default to get started.
8585

8686
### Object-first parameters
8787

@@ -91,7 +91,7 @@ Parameters represent attributes of a real-world entity. Design them to reflect t
9191
- **Group flat parameters by their conceptual object.** When a typed object is not available, prefix each parameter with the name of the entity it belongs to: `$ServerHost`, `$ServerPort`, `$ServerTls` rather than `$Host`, `$Port`, `$Tls`. The prefix makes the grouping explicit, prevents collisions with unrelated parameters, and avoids shadowing PowerShell built-in variables (`$Host`).
9292
- **Offer both modes when callers need both.** A parameter set that accepts an object and a parallel parameter set that accepts its individual attributes are equally valid; use both when that genuinely serves users.
9393

94-
This mirrors **Interface Segregation**: each parameter set represents one coherent input contract — not a flat list of loosely related knobs — so callers only touch what they need.
94+
This applies **Interface Segregation**: each parameter set represents one coherent input contract, not a flat list of loosely related inputs. Callers supply only the inputs they need.
9595

9696
> Note: the rule "avoid repeating the noun" (e.g. `-ID` not `-ProjectID` in `Get-ContosoProject`) applies to a command's *own* noun. The object-prefix convention above applies when a single command spans *multiple* conceptual objects (`$ServerHost` vs `$ClientID`) — the prefix is the object name, not the command noun, so there is no conflict.
9797

‎docs/content/reference/repository-standard.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# Repository Standard
22

3-
This is the PSModule organization's Repository Standard. It applies to the PSModule organization and is the standard for PowerShell module repositories. It describes what a newly created or maintained module repository should look like before module-specific code, tests, documentation, and managed repository files are considered.
3+
This standard defines repository requirements for PowerShell modules in the PSModule organization. It describes how a newly created or maintained module repository should look. It defines the baseline before module-specific code, tests, documentation, and managed repository files are considered.
44

5-
This standard operates at the same altitude as the [MSX Enterprise Repository Standard](https://msx.no/docs/Ways-of-Working/Repository-Standard/): MSX sets the enterprise-wide default, and this standard adds to and adjusts that default for PowerShell module repositories. Rules this standard does not change are inherited from the MSX default; where this standard adds or overrides a rule, it governs PowerShell module repositories.
5+
This standard complements the [MSX Enterprise Repository Standard](https://msx.no/docs/Ways-of-Working/Repository-Standard/). MSX defines the enterprise-wide default. This standard adds requirements and overrides for PowerShell module repositories. Unchanged MSX rules still apply. Additions and overrides on this page govern PowerShell module repositories.
66

7-
The implementation standard still lives in [PowerShell module standard](powershell-module-standard.md). Type-specific conventions for integration (API) and data modules live in [Module types](module-types.md). This page covers the repository standard for module repositories: files, metadata, README shape, release integration, placeholder handling, shared community files, and managed-file distribution.
7+
The implementation standard is in [PowerShell module standard](powershell-module-standard.md). Type-specific conventions for integration (API) and data modules are in [Module types](module-types.md). This page covers the repository standard for module repositories: files, metadata, README shape, release integration, placeholder handling, shared community files, and managed-file distribution.
88

99
## Scope
1010

@@ -17,7 +17,9 @@ It does not apply directly to:
1717
- Template repositories other than `Template-PSModule`.
1818
- Test, archive, service, or infrastructure repositories that are not published as module artifacts.
1919

20-
Two baseline expectations still apply to every PSModule repository, including the types listed above. Each repository stands on its own: it carries its own governance and community files instead of relying on the organization `.github` fallback, and each repository ships the [agent onboarding files](#agent-onboarding-files) so an agent can work in it without prior context. What differs by type is the concrete file set and layout: the required files, README shape, and framework wiring on the rest of this page are the module standard, and non-module repositories keep only the equivalent baseline appropriate to their own type. This documentation project, maintained in `PSModule/Process-PSModule`, follows those two baseline expectations itself.
20+
Two baseline expectations apply to every PSModule repository, including the types above. Each repository carries its own governance and community files instead of relying on the organization `.github` fallback. Each repository also ships the [agent onboarding files](#agent-onboarding-files) so an agent can work without prior context.
21+
22+
The required file set, README shape, and framework wiring on this page apply to module repositories. Non-module repositories keep the equivalent baseline for their type. This documentation project, maintained in `PSModule/Process-PSModule`, also follows the two baseline expectations.
2123

2224
Each initiative should keep its own repository standards in its central documentation repository. For the PSModule organization, this repository is the source of truth.
2325

@@ -306,7 +308,7 @@ Keep, trim, or relocate content — do not delete it:
306308
- **Trim:** exhaustive command inventories, parameter tables, and repetitive examples that differ only by a parameter. These come from comment-based help — point to `Get-Help` and the documentation site instead of restating them.
307309
- **Keep content in a published home — never drop it:** long-form guides and unique conceptual content (authentication and setup walkthroughs, deep operational detail, end-to-end scenarios) belong in a surface that is actually published: a command group's overview page under `src/functions/public/<Group>/<Group>.md`, comment-based help, or published documentation in `docs/` or `examples/`. When no published home exists, keep the full content in the README to ensure it reaches users. A longer landing page is acceptable and expected for feature-rich modules; do not shorten by deleting.
308310

309-
Retain upstream attribution and licensing context. Credit, acknowledgements, donation notes, and third-party license notices for wrapped or bundled work must stay in the README or appear in a clearly linked location. The rule below about community and policy sections does not apply to attribution the project is expected to carry.
311+
Retain upstream attribution and licensing context. Credit, acknowledgments, donation notes, and third-party license notices for wrapped or bundled work must stay in the README or appear in a clearly linked location. The rule below about community and policy sections does not apply to attribution the project is expected to carry.
310312

311313
README pages should not duplicate generated command documentation. Do not add full command inventories, parameter tables, or long reference sections when those details are already produced from comment-based help.
312314

@@ -357,7 +359,7 @@ For an implemented module, also confirm the README keeps a capabilities or usage
357359

358360
## Documentation ownership
359361

360-
Command details belong in comment-based help and generated documentation. The README can showcase capability, then points to those sources for reference detail.
362+
Command details belong in comment-based help and generated documentation. The README can showcase capability, then point to those sources for reference detail.
361363

362364
Use these defaults:
363365

‎docs/content/reference/settings.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@ description: The Process-PSModule settings file — every available setting in .
55

66
# Settings
77

8-
The workflow is configured using a settings file in the module repository.
9-
The file can be a `JSON`, `YAML`, or `PSD1` file. By default, it will look for `.github/PSModule.yml`.
8+
The workflow uses a settings file in the module repository.
9+
The file can use `JSON`, `YAML`, or `PSD1`. The default path is `.github/PSModule.yml`.
1010

1111
The settings listed on this page are the user-facing configuration contract in `.github/PSModule.yml`. During the
1212
Plan phase, Process-PSModule enriches this input into an internal runtime `Settings` object that downstream workflows

0 commit comments

Comments
 (0)