Skip to content

Commit 2471b53

Browse files
Reserved interface descriptions state their contracts directly (#582)
Reserved action, settings, and reusable-workflow descriptions state their existing contracts directly. Native help uses direct prose and the existing source-backed types. The two consent descriptions omit only the final appeal. No caller action is required. <!-- ANNOUNCEMENT STOP --> ## Changed: Interface and consent descriptions use direct prose The five reserved actions retain every condition, effect, default, expression, permission, output, exact example, version constraint, and required artifact-name match. WhatIf descriptions use **the action only logs** so the original log-only scope stays explicit. Native help retains its tags, associations, and all 16 exact examples. The settings schema and reusable workflows change only existing description values. Each TOML edit removes only the final consent appeal; the preceding cookie/measurement statement and all consent settings remain exact. This PR does not certify that unverified statement or repair a runtime, schema, caller, output, recovery, or release contract. <details> <summary>Technical details</summary> **Current head:** `896b048fcd7624abd00dddaf6d0f55424ab399d6` on `interface-description-prose`. **Reviewed source parent:** `09d209ee07418174c6835cb64b6977c2740ad962`. **Identical full tree:** `8938314d16ecd805b595a0729b1f1c91ae77e0b2`. **Fresh main base:** `64ffb1d87f86bd5d487891fdb140b78385a00531`. Seven small prose commits and one source-identical empty trigger are pushed. The draft opened after the first coherent commit; the user later made it ready for review. The final source diff still contains 18 modified files, 176 insertions, and 151 deletions; it adds no repository file, test, enforcement tool, dependency, or audit Markdown. The November 11 preparation first verifies clean local/origin/live source, the reviewed head and full tree, and zero exact-head native check runs, suites, statuses and PR-event runs after retention expiry. Only that observed missing condition permits the one ordinary empty commit. Its immediate parent, identical tree, zero-file delta and normal remote push are verified. No reset, rebase, amendment, force push, second trigger, or source edit occurs. The accepted source audit is reused for this equal tree, not repeated or represented as a new run. [Exact trigger proof, native PR-event CI, fresh review and bounded handoff evidence](#564 (comment)) is saved on the completion Task and read back from GitHub. The complete original source audit is attached to the closing Task: - [Full candidate inventory, no-change/protected classifications, command results, and precise factual follow-ups](#564 (comment)): 38 source files, all 163 description candidates, all 22 native-help units, and all 31 existing parameter descriptions. - [Exact description/consent changed regions](#564 (comment)): complete before/after text, immutable source citations, and preserved-meaning guards. - [Exact native-help changed regions](#564 (comment)): complete before/after text, immutable source citations, and preserved-meaning guards. Together, the region tables record all **109 exact replacements**. The description inventory contains 56 revised YAML/JSON values, 102 no-change values, three protected existing-contract values, and two final-appeal-only TOML edits. | Changed surface | Standards checked | Framework/source evidence | Result | | --- | --- | --- | --- | | Five reserved action metadata files; settings schema; five reusable workflows | Pinned Natural Language, Writing Guide, YAML, GitHub Actions, Documentation; native JSON annotations | Existing action contracts, settings and workflow-input references; complete structured-node and exact raw-text comparisons | Prose aligned; every non-description node/value and exact constraint/example stays unchanged | | Five PowerShell native-help source files | Pinned PowerShell Scripts/Functions, Documentation, Natural Language; native Get-Help format | Eight PowerShell candidates inspected; 22 native-help units and 16 examples | Exact program tokens/flags, AST shape, requirements, directives, BOM, help tags/association, syntax and parameter contracts preserved; zero parse/analyzer findings | | Two existing consent descriptions | Pinned writing criteria; native TOML string format | Both complete TOML files parse; docs site builds from an exact session-local copy | Only the final appeal is removed; all 66 rendered pages retain the remaining statement and Accept/Reject labels | **Existing source validation:** one-off exact raw-text/BOM/EOL/metadata comparisons pass for all 38 candidates; all 109 expected regions are present. Existing `ConvertFrom-Yaml` parses all ten changed YAML files. Existing `Test-Json` accepts the schema and anonymous empty settings. `Invoke-ScriptAnalyzer` reports zero findings on all eight PowerShell candidates before and after. `zensical build --clean` exits 0 with `No issues found`. `git diff --check` passes and the worktree is clean. These are the retained November 4 results for the identical source tree, not repeated November 11 audit runs. Default YAML lint is not reported as clean: 152 baseline findings become 138 final findings, with no new rule/region finding. Existing formatting findings remain outside the released prose scope. No local publishing, cleanup, installation, network example, fixture, or benchmark script runs. No Markdown source or link changes; all source HTTP(S) links stay exact. The fixed writing source is MSXOrg/docs@`1b0d4893c8fefabe604d04393068a8ff6f848082`, including the Documentation Model, Natural Language, Writing Guide, Documentation, Markdown, applicable native formats, and Task/PR formats. The official STE overview/FAQ and local Issue 9 rules/dictionary are consulted. Manual material stays local. No full STE-conformance claim is made. Current main, #564's protected handback, and all first-pass path exclusions are checked before the prose commits. Every README, Markdown source, plugin, test, both functional fixture trees, first-pass #565-#570 path, and unmatched proposal-only file stays unchanged. Existing proposal contracts and branches are not amended or woken. **Retained facts:** the cookie/measurement statement remains unverified; release-note fallback wording still needs owner reconciliation with the pushed-commit-message branch; three settings descriptions remain protected; the existing all-releases and retry-count terminology and imprecise array/PSSemVer help entries remain separate contract/help questions. The full audit gives exact sources and does not select a runtime or policy fix. **Fresh native review:** one explicit request at `2026-11-11T14:57:49-14:57:51Z`, timeline event `35811024275` at `14:57:52Z`, produces [review 5860771218](#582 (review)), **APPROVED** at `15:00:10Z` on exact head `896b048fcd7624abd00dddaf6d0f55424ab399d6`. REST and GraphQL confirm its ID, timestamp, head and contributor-associated Copilot author. The old dismissed/rebound November 4 review `5769820091` is excluded. The fully paginated thread query after fresh submission has zero threads. No redundant same-head review round follows. **Native PR-event CI, bounded snapshot near `2026-11-11T15:00:40Z`:** Release, Test-Actions, Docs and Linter pass. The Default and WithManifest self-test runs remain in progress; the exact-head check list has 42 successes, four skips and six in-progress checks, with no completed failure. All six native runs associate `pull_request`, this exact head, PR582 and the recorded main base. Docs publication and index mutation are skipped on the PR event. No manual dispatch, unrelated run, fixture edit or workflow change is used. Pending jobs are not represented as passing. **Lifecycle:** the PR remains open/non-draft. Agent merge remains enabled for review, CI and conflict maintenance only, with `merge_pr=false`; GitHub `auto_merge=null`. This preparation changes none of those settings, starts no watcher or schedule, and does not merge, publish, close the Task, or make a policy decision. Root alone controls the later guarded merge/publication sequence. The two incomplete native self-test runs remain the bounded handoff blocker. The scoped convergence search covers the writing campaign and its source/contract siblings. Only the closing Task below is resolved by this delivery after eventual merge. Other campaign, caller, native-help, and output gaps remain non-closing context. </details> <details> <summary>Related references</summary> - Resolves #564 after review and merge. - References #558; its separate safe-action delivery remains unchanged. - References #574, #575, and #576; their separate contract/runtime gaps remain open. - References #578; source-bound TestData adoption work and protected guide content remain separate. </details>
1 parent 4ea45ec commit 2471b53

18 files changed

Lines changed: 176 additions & 151 deletions

File tree

‎.github/actions/Cleanup-PSModulePrereleases/action.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
name: Cleanup-PSModulePrereleases
2-
description: Cleanup prerelease GitHub releases associated with the current pull request branch.
2+
description: Delete prerelease GitHub releases associated with the current pull request branch.
33
author: PSModule
44

55
inputs:
@@ -16,11 +16,11 @@ inputs:
1616
required: false
1717
default: ''
1818
WhatIf:
19-
description: If specified, the action will only log the changes it would make.
19+
description: If specified, the action only logs the changes it would make.
2020
required: false
2121
default: 'false'
2222
WorkingDirectory:
23-
description: The working directory where the script will run from.
23+
description: Working directory for the script.
2424
required: false
2525
default: '.'
2626

‎.github/actions/Get-PSModuleSettings/action.yml‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
name: Get-PSModuleSettings
2-
description: Get settings for a PowerShell module workflow
2+
description: Get settings for a PowerShell module workflow.
33
author: PSModule
44
branding:
55
icon: settings
@@ -10,7 +10,7 @@ inputs:
1010
description: Name of the module.
1111
required: false
1212
SettingsPath:
13-
description: Path to the settings file (json, yaml/yml, or psd1)
13+
description: Path to the settings file (json, yaml/yml, or psd1).
1414
required: false
1515
Debug:
1616
description: Enable debug output.
@@ -21,29 +21,31 @@ inputs:
2121
required: false
2222
default: 'false'
2323
Version:
24-
description: Specifies the version of the GitHub module to be installed. Accepts an exact version or a NuGet version range (for example '[1.2.0, 2.0.0)').
24+
description: Version of the GitHub module to install. The action accepts an exact version or a NuGet version range (for example '[1.2.0, 2.0.0)').
2525
required: false
2626
Prerelease:
2727
description: Allow prerelease versions if available.
2828
required: false
2929
default: 'false'
3030
WorkingDirectory:
31-
description: The working directory where the script will run from.
31+
description: Working directory for the script.
3232
required: false
3333
default: ${{ github.workspace }}
3434
ImportantFilePatterns:
3535
description: |
36-
Newline-separated list of regex patterns that identify important files.
37-
Changes matching these patterns trigger build, test, and publish stages.
38-
When set, fully replaces the defaults.
36+
Newline-separated list of regular expression patterns that identify
37+
important files.
38+
Changes that match these patterns trigger build, test, and publish
39+
stages.
40+
When set, the list fully replaces the defaults.
3941
required: false
4042
default: |
4143
^src/
4244
^README\.md$
4345
4446
outputs:
4547
Settings:
46-
description: The complete settings object as JSON, including test suites
48+
description: The complete settings object as JSON, including test suites.
4749
value: ${{ fromJson(steps.Get-PSModuleSettings.outputs.result).Settings }}
4850

4951
runs:

‎.github/actions/Get-PSModuleSettings/src/Get-PSModuleSettings.Helpers.psm1‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
function Resolve-WorkflowEventRouting {
22
<#
33
.SYNOPSIS
4-
Resolves release and execution routing from normalized GitHub event state.
4+
Resolve release and execution routing from normalized GitHub event state.
55
#>
66
[CmdletBinding()]
77
[OutputType([PSCustomObject])]
@@ -82,7 +82,7 @@ function Resolve-WorkflowEventRouting {
8282
function Select-PullRequestForPush {
8383
<#
8484
.SYNOPSIS
85-
Selects the merged default-branch pull request associated with a pushed commit.
85+
Select the merged default-branch pull request associated with a pushed commit.
8686
#>
8787
[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', '',
8888
Justification = 'Parameter is used inside a Sort-Object script block.')]
@@ -112,7 +112,7 @@ function Select-PullRequestForPush {
112112
function Get-FilesFromGitTree {
113113
<#
114114
.SYNOPSIS
115-
Returns the files contained in a complete Git tree response.
115+
Return the files from a complete Git tree response.
116116
#>
117117
[CmdletBinding()]
118118
[OutputType([string])]
@@ -133,7 +133,7 @@ function Get-FilesFromGitTree {
133133
function Get-FilesFromGitHubComparison {
134134
<#
135135
.SYNOPSIS
136-
Returns files from a complete GitHub compare response.
136+
Return files from a complete GitHub compare response.
137137
#>
138138
[CmdletBinding()]
139139
[OutputType([string])]

‎.github/actions/Get-PSModuleSettings/src/Settings.schema.json‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,15 @@
1111
},
1212
"ImportantFilePatterns": {
1313
"type": "array",
14-
"description": "Regex patterns that identify important files. Changes matching these patterns trigger build, test, and publish stages. Defaults to ['^src/', '^README\\.md$'] when not configured.",
14+
"description": "Regular expression patterns that identify important files. Changes that match these patterns trigger build, test, and publish stages. When not configured, the defaults are ['^src/', '^README\\.md$'].",
1515
"items": {
1616
"type": "string",
1717
"minLength": 1
1818
}
1919
},
2020
"Test": {
2121
"type": "object",
22-
"description": "Test configuration settings",
22+
"description": "Test configuration",
2323
"properties": {
2424
"Skip": {
2525
"type": "boolean",
@@ -54,7 +54,7 @@
5454
"properties": {
5555
"Skip": {
5656
"type": "boolean",
57-
"description": "Skip test results collection"
57+
"description": "Skip collection of test results"
5858
}
5959
}
6060
},
@@ -64,7 +64,7 @@
6464
"properties": {
6565
"Skip": {
6666
"type": "boolean",
67-
"description": "Skip code coverage collection"
67+
"description": "Skip collection of code coverage"
6868
},
6969
"PercentTarget": {
7070
"type": "number",
@@ -74,15 +74,15 @@
7474
},
7575
"StepSummaryMode": {
7676
"type": "string",
77-
"description": "Mode for displaying step summary"
77+
"description": "Display mode for the step summary"
7878
}
7979
}
8080
}
8181
}
8282
},
8383
"Build": {
8484
"type": "object",
85-
"description": "Build configuration settings",
85+
"description": "Build configuration",
8686
"properties": {
8787
"Skip": {
8888
"type": "boolean",
@@ -124,7 +124,7 @@
124124
},
125125
"Publish": {
126126
"type": "object",
127-
"description": "Publish configuration settings",
127+
"description": "Publish configuration",
128128
"properties": {
129129
"Module": {
130130
"type": "object",
@@ -156,35 +156,35 @@
156156
},
157157
"MajorLabels": {
158158
"type": "string",
159-
"description": "Comma-separated labels that trigger major version bump"
159+
"description": "Comma-separated labels that trigger a major version bump"
160160
},
161161
"MinorLabels": {
162162
"type": "string",
163-
"description": "Comma-separated labels that trigger minor version bump"
163+
"description": "Comma-separated labels that trigger a minor version bump"
164164
},
165165
"PatchLabels": {
166166
"type": "string",
167-
"description": "Comma-separated labels that trigger patch version bump"
167+
"description": "Comma-separated labels that trigger a patch version bump"
168168
},
169169
"IgnoreLabels": {
170170
"type": "string",
171-
"description": "Comma-separated labels that prevent release"
171+
"description": "Comma-separated labels that prevent a release"
172172
},
173173
"PrereleaseLabels": {
174174
"type": "string",
175175
"description": "Comma-separated labels that trigger a prerelease"
176176
},
177177
"UsePRTitleAsReleaseName": {
178178
"type": "boolean",
179-
"description": "Use pull request title as the GitHub release name"
179+
"description": "Use the pull request title as the GitHub release name"
180180
},
181181
"UsePRBodyAsReleaseNotes": {
182182
"type": "boolean",
183-
"description": "Use pull request body as the release notes content"
183+
"description": "Use the pull request body as the release notes content"
184184
},
185185
"UsePRTitleAsNotesHeading": {
186186
"type": "boolean",
187-
"description": "Add pull request title as H1 heading in release notes"
187+
"description": "Add the pull request title as an H1 heading in release notes"
188188
},
189189
"ReleaseType": {
190190
"type": "string",
@@ -203,15 +203,15 @@
203203
"properties": {
204204
"Skip": {
205205
"type": "boolean",
206-
"description": "Skip publishing the generated documentation site"
206+
"description": "Skip publication of the generated documentation site"
207207
}
208208
}
209209
}
210210
}
211211
},
212212
"Linter": {
213213
"type": "object",
214-
"description": "Linter configuration settings",
214+
"description": "Linter configuration",
215215
"properties": {
216216
"Skip": {
217217
"type": "boolean",
@@ -272,7 +272,7 @@
272272
},
273273
"Run": {
274274
"type": "null",
275-
"description": "Deprecated. Runtime execution flags are now stored on each phase object."
275+
"description": "Deprecated. Runtime execution flags are stored on each phase object."
276276
}
277277
},
278278
"definitions": {

‎.github/actions/Get-PSModuleSettings/src/main.ps1‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -528,19 +528,20 @@ if ($settings.Test.Skip) {
528528
function Get-TestItemsFromFolder {
529529
<#
530530
.SYNOPSIS
531-
Retrieves test items from a specified folder.
531+
Get test items from the specified folder.
532532
533533
.DESCRIPTION
534-
This function searches for test-related files in the specified folder.
535-
It looks for configuration files (*.Configuration.ps1), container files (*.Container.ps1),
536-
and test files (*.Tests.ps1) in that order of precedence.
534+
The function searches the specified folder for test-related files.
535+
It searches for configuration files (*.Configuration.ps1), container files (*.Container.ps1),
536+
and test files (*.Tests.ps1), in that order of precedence.
537537
538538
.PARAMETER FolderPath
539-
The path to the folder to search for test items.
539+
Path to the folder to search for test items.
540540
541541
.OUTPUTS
542542
System.IO.FileInfo[]
543-
Returns an array of test-related files found in the folder.
543+
544+
An array of test-related files from the folder.
544545
#>
545546
param ([string]$FolderPath)
546547

@@ -563,18 +564,19 @@ if ($settings.Test.Skip) {
563564
function Find-TestDirectory {
564565
<#
565566
.SYNOPSIS
566-
Finds test directories recursively.
567+
Find test directories recursively.
567568
568569
.DESCRIPTION
569-
This function recursively searches for all directories starting from the specified path.
570-
It returns a flat array of all directory paths found.
570+
The function searches recursively for all directories from the specified path.
571+
It returns all directory paths in a flat array.
571572
572573
.PARAMETER Path
573-
The root path to start searching for directories.
574+
Root path for the directory search.
574575
575576
.OUTPUTS
576577
System.String[]
577-
Returns an array of directory paths.
578+
579+
An array of directory paths.
578580
#>
579581
param ([string]$Path)
580582

‎.github/actions/Publish-PSModule/action.yml‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,26 +7,26 @@ inputs:
77
description: Name of the module to publish.
88
required: false
99
ModulePath:
10-
description: Path to the folder containing the <Name>/ module subdirectory from Build-PSModule.
10+
description: Path to the folder with the <Name>/ module subdirectory from Build-PSModule.
1111
required: false
1212
default: .PSModule/module
1313
PSGALLERY_API_KEY:
14-
description: PowerShell Gallery API Key.
14+
description: PowerShell Gallery API key.
1515
required: true
1616
PullRequest:
1717
description: Normalized pull request context JSON from Get-PSModuleSettings.
1818
required: false
1919
default: ''
2020
WhatIf:
21-
description: If specified, the action will only log the changes it would make, but will not publish the module.
21+
description: If specified, the action only logs the changes it would make, but does not publish the module.
2222
required: false
2323
default: 'false'
2424
WorkingDirectory:
25-
description: The working directory where the script will run from.
25+
description: Working directory for the script.
2626
required: false
2727
default: '.'
2828
ArtifactName:
29-
description: Name of the uploaded artifact to download. Must match the name used in the upstream upload-artifact step.
29+
description: Name of the uploaded artifact to download. It must match the name used in the upstream upload-artifact step.
3030
required: false
3131
default: module
3232

‎.github/actions/Publish-PSModule/src/Publish-PSModule.Helpers.psm1‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
11
function Get-ModuleVersionString {
22
<#
33
.SYNOPSIS
4-
Builds the SemVer version string that identifies the module itself.
4+
Build the SemVer version string that identifies the module.
55
66
.DESCRIPTION
7-
Composes the module version and, when there is one, the prerelease label. This is the string the
8-
PowerShell Gallery and the module manifest understand: `Major.Minor.Patch` optionally followed by
9-
`-<prerelease>`. It never carries the repository's version prefix, because neither the manifest's
10-
`ModuleVersion` nor a Gallery package version accepts one.
7+
If a prerelease label is present, the function puts the module version and the label together.
8+
The PowerShell Gallery and the module manifest use this string: `Major.Minor.Patch` optionally followed by `-<prerelease>`.
9+
The string never includes the repository's version prefix.
10+
Neither the manifest's `ModuleVersion` nor a Gallery package version accepts a prefix.
1111
1212
.OUTPUTS
13-
String with the module version.
13+
System.String
14+
15+
The module version.
1416
1517
.EXAMPLE
1618
Get-ModuleVersionString -ModuleVersion '1.1.10'

‎.github/actions/Release-PSModule/action.yml‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,31 +7,31 @@ inputs:
77
description: Name of the module to release.
88
required: false
99
ModulePath:
10-
description: Path to the folder containing the <Name>/ module subdirectory from Build-PSModule.
10+
description: Path to the folder with the <Name>/ module subdirectory from Build-PSModule.
1111
required: false
1212
default: .PSModule/module
1313
ArtifactName:
14-
description: Name of the uploaded artifact to download. Must match the name used in the upstream upload-artifact step.
14+
description: Name of the uploaded artifact to download. It must match the name used in the upstream upload-artifact step.
1515
required: false
1616
default: module
1717
WhatIf:
18-
description: If specified, the action will only log the changes it would make, but will not actually create the release or upload artifacts.
18+
description: If specified, the action only logs the changes it would make, but does not create the release or upload artifacts.
1919
required: false
2020
default: 'false'
2121
WorkingDirectory:
22-
description: The working directory where the script will run from.
22+
description: Working directory for the script.
2323
required: false
2424
default: '.'
2525
UsePRTitleAsReleaseName:
26-
description: When enabled, uses the pull request title as the name for the GitHub release. If not set, the version string is used.
26+
description: When enabled, the action uses the pull request title as the GitHub release name. If not set, it uses the version string.
2727
required: false
2828
default: 'false'
2929
UsePRBodyAsReleaseNotes:
30-
description: When enabled, uses the pull request body as the release notes for the GitHub release. If not set, the release notes are auto-generated.
30+
description: When enabled, the action uses the pull request body as the GitHub release notes. If not set, it auto-generates the release notes.
3131
required: false
3232
default: 'true'
3333
UsePRTitleAsNotesHeading:
34-
description: When enabled along with UsePRBodyAsReleaseNotes, the release notes will begin with the pull request title as a H1 heading followed by the pull request body. The title will reference the pull request number.
34+
description: When enabled with UsePRBodyAsReleaseNotes, the release notes start with the pull request title as an H1 heading. The pull request body follows the heading. The title references the pull request number.
3535
required: false
3636
default: 'true'
3737
ReleaseTag:

0 commit comments

Comments
 (0)