Repository navigation
Commit a40a9eb
authored
Native help and action descriptions state framework behavior directly (#570)
Native help and action descriptions state framework operations directly
in en-US. Contributors and callers can read helper operations and action
inputs without future-tense boilerplate. Runtime behavior and caller
configuration remain unchanged; callers need no adoption changes.
<!-- ANNOUNCEMENT STOP -->
## Changed: Native help and action descriptions state supported
operations
Native help uses imperative synopses and present-tense descriptions.
Action descriptions identify build, documentation, installation,
test-reporting, site, test, and index operations directly. The changes
preserve command names, parameter names, help tags, exact examples,
paths, output and error strings, YAML keys and defaults, expressions,
option values, and version constraints.
This is a prose-only delivery. It does not repair runtime behavior,
complete every helper's help contract, or certify full STE conformance.
Protected examples and unresolved contract discrepancies remain explicit
follow-up work.
<details>
<summary>Technical details</summary>
### Delivery and immutable comparison
- Delivery leaf: #558.
- Base and review snapshot: `64ffb1d87f86bd5d487891fdb140b78385a00531`.
- Pushed candidate: `aa992660e3eefe8d9a3881d95fe32bab491d9f52`.
- Scope comparison: `git diff 64ffb1d
aa99266`.
- The first coherent commit, `29d8cca`, was pushed before this draft
opened at `2026-11-04T12:28:44Z`. Five later small commits remain
pushed: `c4319be`, `f8a4e0a`, `d25f9eb`, `a2bde66`, and `aa99266`.
- The final local, origin branch, and PR head identities match. The PR
is open and draft, has no labels, and has no auto-merge request. No
merge or Agent merge action is requested.
The manual review covers all 64 candidates: 52 PowerShell files and 12
action metadata files with 110 existing description fields. Each
candidate and its surrounding implementation was read. The committed
diff changes 34 paths: 22 PowerShell files and all 12 action metadata
files. It revises 73 description values. No repository file is added or
deleted.
### Exact acceptance evidence
The four original expected-text checks failed before editing. Three
additional parent-review checks failed at
`a2bde6694cf238a77e21b3441066a61813a10567` before the bounded
corrections below. All seven checks pass at the pushed candidate. The
original text in this first table is from the immutable base above.
| Location | Original text | Candidate text |
| --- | --- | --- |
| `Build-PSModule\src\helpers\Build\Add-ContentFromItem.ps1`,
`.DESCRIPTION` | `This function will add the content of a folder or file
to the root module file.` | `Add-ContentFromItem adds the content of a
folder or file to the root module file.` |
| `Build-PSModule\src\helpers\Build-PSModule.ps1`, `.SYNOPSIS` and
`.DESCRIPTION` | Both sections say `Builds a module.` | `Build a
PowerShell module from source files.` / `Build-PSModule copies the
source files, creates the manifest, and combines the scripts into the
root module.` |
| `Get-PesterCodeCoverage\action.yml`, root `description` | `A GitHub
Action that is used to gather Code Coverage for the PSModule process.` |
`Collect code coverage results for the PSModule process.` |
| `Get-PesterCodeCoverage\action.yml`,
`inputs.WorkingDirectory.description` | `The working directory where the
script will run from.` | `Working directory for the script.` |
| `Build-PSModule\action.yml`, `inputs.OutputFolder.description` | `Path
to the folder where the built module is outputted.` | `Path to the
folder for the built module.` |
| `Document-PSModule\src\helpers\Build-PSModuleDocumentation.ps1`,
`.SYNOPSIS` and `.DESCRIPTION` | Both sections say `Builds a module.` |
`Build documentation for a PowerShell module.` /
`Build-PSModuleDocumentation creates Markdown help for exported commands
and arranges the pages to match the public source folders.` |
| `Test-PSModule\action.yml`,
`inputs.CodeCoverage_RecursePaths.description` | `Will recurse through
directories in the Path option.` | `Search subdirectories of the
directories in the Path option.` |
| `Test-PSModule\action.yml`, `inputs.Debug_ShowFullErrors.description`
| `Show full errors including Pester internal stack. This property is
deprecated, and if set to true it will override
Output.StackTraceVerbosity to 'Full'.` | `Show full errors with the
internal Pester stack. When true, this deprecated property overrides
Output.StackTraceVerbosity with 'Full'.` |
Implementation review also removes incorrect prose claims without
changing behavior: base-module help describes the empty root module that
the code creates; function and variable export helpers describe
source-file inspection instead of manifest reads; documentation help
describes Markdown generation; index API help no longer claims that its
wrapper establishes an App context. The exact examples and disputed
cmdlet-source claim remain protected, as recorded below.
### Bounded parent-review corrections
The parent review independently confirms code tokens/flags, AST
structure, BOM state, and zero parse errors in all 22 changed PowerShell
files at `a2bde6694cf238a77e21b3441066a61813a10567`, plus the
73-description YAML boundary. Commit `aa99266` then changes only these
two prose files:
| Location | Previous draft text | Final text |
| --- | --- | --- |
| `Test-PSModule\action.yml`, `Run_Exit` | `If Throw is also enabled,
prefer an exception.` | `Run_Throw takes precedence over Run_Exit when
both are enabled.` |
| `Test-PSModule\action.yml`, `Run_Throw` | `If Exit is also enabled,
prefer an exception.` | `Run_Throw takes precedence over Run_Exit when
both are enabled.` |
| `Get-PesterCodeCoverage\src\Get-PesterCodeCoverage.Helpers.psm1`,
`.OUTPUTS` | Description on the first line | `System.String` on the
first line, a blank line, then the existing description |
The [pinned Invoke-Pester
action](https://github.com/PSModule/Invoke-Pester/blob/c5494aba3c07d7bfd81bdbbc9f301e8fa4a729fb/action.yml)
forwards both flags. Its [initialization
script](https://github.com/PSModule/Invoke-Pester/blob/c5494aba3c07d7bfd81bdbbc9f301e8fa4a729fb/src/init.ps1)
maps them to `Run.Exit` and `Run.Throw`, and its [execution
script](https://github.com/PSModule/Invoke-Pester/blob/c5494aba3c07d7bfd81bdbbc9f301e8fa4a729fb/src/exec.ps1)
passes the configuration to Pester without changing that precedence.
An anonymous isolated Pester 6.1.0 probe confirms the behavior with one
intentional failing assertion. With both flags enabled, the child
catches the expected `Pester run failed` exception and returns code 0.
With only Exit enabled, the child terminates with code 1 and no
fallthrough or caught exception. No repository test or fixture runs in
this probe.
The helper's unchanged `[OutputType([string])]` supports the output
heading. Native `Get-Help` renders the exact block `System.String`, a
blank line, and `The multiline string with adjusted indentation.` No
help tag, association, example, or executable token changes.
### Behavior-preservation proof
The baseline was captured before the first prose edit. The comparison
covers all 52 candidate PowerShell files, including unchanged guidance
and read-only action test files. At the candidate, all 23,371
non-comment tokens retain their kind, flags, and exact text. All 25,196
AST nodes retain their type and parent shape. Parse errors remain zero.
`#Requires`, structural/test directives, help association, ordered help
tags, parameter-help keys, all 36 complete examples, all three native
`.LINK` entries, and forwarding/external-help metadata match the
baseline.
The comparison keeps here-string and string tokens intact. Generated
Markdown/HTML, output text, error messages, suppression attribute
strings, and embedded generated-code comments are therefore unchanged.
All 34 changed files retain their original BOM state in raw-byte
comparisons against the Git blobs. No generic help sections are added,
and no existing help tag moves to another command.
The YAML proof parses each of the 12 action files. It ignores only
existing scalar values at root `description`,
`inputs.<name>.description`, and `outputs.<name>.description`. All other
node tags, mapping keys and order, sequence entries, scalar values, and
exact text outside those description scalar spans match the base. This
includes every default, required flag, action reference, environment
mapping, shell command, expression, output mapping, and
compatibility/version value.
`git diff --name-only` also matches the 34 manually classified revised
paths exactly. Every other repository path, including tests and fixture
inputs, is unchanged. The verification scripts, baseline JSON,
inventories, and console output are session artifacts, not repository
changes.
### Validation commands and results
Environment: PowerShell `7.6.9`, Pester `6.1.0`, PSScriptAnalyzer
`1.25.0`, PyYAML `6.0.3`, and yamllint `1.38.0`. No package or module
was installed or restored.
In the commands below, `$audit` is the directory containing the retained
session verification artifacts; `$PWD.Path` is this worktree.
```powershell
& (Join-Path $audit 'Test-ProseBoundary.ps1') -Mode Compare -RepositoryPath $PWD.Path
& (Join-Path $audit 'Test-ProseBoundary.ps1') -Mode Acceptance -RepositoryPath $PWD.Path
& (Join-Path $audit 'Test-NativeHelp.ps1') -RepositoryPath $PWD.Path
& (Join-Path $audit 'Test-AnalyzerBaseline.ps1') -RepositoryPath $PWD.Path
python (Join-Path $audit 'test_action_descriptions.py') $PWD.Path
python (Join-Path $audit 'test_action_yaml_lint.py') $PWD.Path (Join-Path $audit 'workflow-yaml-lint.yml')
python (Join-Path $audit 'test_bom_preservation.py') $PWD.Path
pwsh -NoLogo -NoProfile -File (Join-Path $audit 'Confirm-ThrowExitPrecedence.ps1') -ThrowOnFailure
pwsh -NoLogo -NoProfile -File (Join-Path $audit 'Confirm-ThrowExitPrecedence.ps1')
Import-Module Pester -RequiredVersion 6.1.0
$configuration = New-PesterConfiguration
$configuration.Run.Path = '.github\actions\update-index\tests'
$configuration.Run.Throw = $true
$configuration.Run.PassThru = $true
$configuration.Output.Verbosity = 'Normal'
Invoke-Pester -Configuration $configuration
git --no-pager diff --check 64ffb1d HEAD
```
| Check | Result |
| --- | --- |
| Parser, non-comment tokens, AST shape, directives, help association,
tags, examples, and links | Pass for all 52 PowerShell files; zero parse
errors |
| Seven expected prose results | Four original failures before editing
and three parent-review failures before correction; all seven pass at
the candidate |
| Rendered native help | `Get-Help -Full` resolves all 71 existing
topics: 52 action topics and 19 guidance topics; the helper output block
has the exact type/blank-line/description order |
| Help inspection safety | Function definitions are isolated for
inspection; no function body, benchmark, network example, or fixture
script runs |
| Throw/Exit precedence | Anonymous child-process probe passes:
Throw+Exit catches the expected exception and returns 0; Exit-only
terminates with expected code 1 |
| BOM preservation | Raw-byte checks pass for all 34 changed files |
| Repository PSScriptAnalyzer profile | Exactly the same two existing
informational `PSAvoidUsingPositionalParameters` findings for `Heading`
calls in `Get-PesterCodeCoverage\src\main.ps1`; no new finding |
| YAML structure and non-description text | Pass for all 12 action files
and 110 description fields; 73 revised descriptions |
| Existing workflow YAML lint profile | Zero errors before and after;
warnings decrease from 73 to 43; no new finding by file/rule/description
field |
| Existing update-index Pester suite | Baseline and final runs pass: one
test passed, zero failed |
| Whole committed diff whitespace | Pass |
| Manual inventory against committed paths | Pass: all 64 candidates
classified; exactly the 34 planned revised paths change |
| Local/origin/PR identity and draft-only state | Pass at the candidate
SHA above |
The YAML profile is the exact [super-linter
template](https://github.com/super-linter/super-linter/blob/4ce20838b8ab83717e78138c5b3a1407148e0918/TEMPLATES/.yaml-lint.yml)
selected by this repository's pinned workflow. Lint input uses
Git-normalized LF text, as the Linux workflow does. The 43 retained
warnings are not presented as a clean lint result. The analyzer findings
are compared by path, rule, severity, message, and source extent, not by
shifted line numbers.
These are local evidence and narrow regression results, not a claim that
every CI job, platform, external link, help example, or STE dictionary
entry is verified. CI and the requested review are separate from the
prose-only proof.
### Current-head review and hosted checks
The parent acceptance review accepts
`aa992660e3eefe8d9a3881d95fe32bab491d9f52` after reading the final diff
and independently checking the bounded corrections. The hosted review is
also `APPROVED` on this exact head: review `5768802328`, submitted at
`2026-11-04T13:04:57Z`, with zero inline comments. The earlier approval
at `a2bde66` is dismissed after the head change and is not the final
approval evidence.
At the retained `2026-11-04T13:05:28Z` CI snapshot, 25 reported checks
pass, three are skipped, and three remain in progress. No failing check
is reported in that snapshot. These pending jobs are not presented as
passes:
| Pending check | State | Evidence |
| --- | --- | --- |
| WorkflowTestWithManifest / Lint-Repository / Lint code base | In
progress |
[Job](https://github.com/PSModule/Process-PSModule/actions/runs/41834197504/job/126590878494)
|
| WorkflowTestWithManifest / Build-Module / Build-Module | In progress |
[Job](https://github.com/PSModule/Process-PSModule/actions/runs/41834197504/job/126590878718)
|
| WorkflowTestDefault / Plan / Plan | In progress |
[Job](https://github.com/PSModule/Process-PSModule/actions/runs/41834197280/job/126588793486)
|
The requested handoff is a verified, pushed draft. The PR remains draft
while the remaining hosted checks run; no merge or release readiness is
asserted.
### Complete manual candidate inventory
`Revised` means reviewed in full and changed only on an owned prose
surface. `No prose` means no editable explanatory comment/help text is
present. `No change` means reviewed prose is preserved under the
guidance snapshot contract. `Excluded` means reviewed but read-only
test/configuration implementation. There is no wholly blocked candidate
file; blocked portions and decisions are listed after the inventory.
| Exact path | Classification | Review result |
| --- | --- | --- |
| `.github\actions\Build-PSModule\action.yml` | Revised | Direct build,
output-folder, prerelease, and working-directory descriptions |
| `.github\actions\Build-PSModule\src\main.ps1` | No prose | Only code
and suppression attribute strings |
| `.github\actions\Build-PSModule\src\helpers\Build-PSModule.ps1` |
Revised | Distinct synopsis/description and direct folder comments |
|
`.github\actions\Build-PSModule\src\helpers\Build\Add-ContentFromItem.ps1`
| Revised | Present-tense description; exact example preserved |
|
`.github\actions\Build-PSModule\src\helpers\Build\Build-PSModuleBase.ps1`
| Revised | Direct copy/root-module description; protected example gap |
|
`.github\actions\Build-PSModule\src\helpers\Build\Build-PSModuleManifest.ps1`
| Revised | Direct manifest description; protected example gap |
|
`.github\actions\Build-PSModule\src\helpers\Build\Build-PSModuleRootModule.ps1`
| Revised | Direct build-order prose; protected example and
cmdlet-source claim |
|
`.github\actions\Build-PSModule\src\helpers\Build\Get-PSModuleAliasesToExport.ps1`
| Revised | Direct manifest-read help |
|
`.github\actions\Build-PSModule\src\helpers\Build\Get-PSModuleClassesToExport.ps1`
| Revised | Direct class/enum discovery help; exact example preserved |
|
`.github\actions\Build-PSModule\src\helpers\Build\Get-PSModuleCmdletsToExport.ps1`
| Revised | Direct manifest-read help |
|
`.github\actions\Build-PSModule\src\helpers\Build\Get-PSModuleFunctionsToExport.ps1`
| Revised | Source-file and filter discovery, not manifest reads |
|
`.github\actions\Build-PSModule\src\helpers\Build\Get-PSModuleVariablesToExport.ps1`
| Revised | Public variable source inspection, not manifest reads |
|
`.github\actions\Build-PSModule\src\helpers\Build\Get-RootLevelVariables.ps1`
| Revised | Correct AST article and concise assignment comment |
|
`.github\actions\Build-PSModule\src\helpers\Build\Update-PSModuleManifestAliasesToExport.ps1`
| Revised | Imperative synopsis and direct folder/file comments |
| `.github\actions\Build-ZensicalSite\action.yml` | Revised | Build
location, not a stale output-normalization claim |
| `.github\actions\Build-ZensicalSite\src\main.ps1` | Revised |
Imperative synopsis and direct build description |
| `.github\actions\Build-ZensicalSite\src\build-zensical-site.ps1` | No
prose | No comments or help |
| `.github\actions\Document-PSModule\action.yml` | Revised | Direct
summary and working-directory descriptions |
| `.github\actions\Document-PSModule\src\main.ps1` | No prose | Only
code and suppression attribute strings |
|
`.github\actions\Document-PSModule\src\helpers\Build-PSModuleDocumentation.ps1`
| Revised | Documentation operation, output folders, and section-index
rationale |
| `.github\actions\Expose-TestData\action.yml` | Revised | Active
validation and environment export description |
| `.github\actions\Get-PesterCodeCoverage\action.yml` | Revised | Direct
collection and inputs; exact NuGet range example retained |
|
`.github\actions\Get-PesterCodeCoverage\src\Get-PesterCodeCoverage.Helpers.psm1`
| Revised | Direct indentation help, typed output block, and removal of
a stray comment character |
| `.github\actions\Get-PesterCodeCoverage\src\main.ps1` | Revised |
Combined-report comments and accurate action-failure wording |
| `.github\actions\Get-PesterTestResults\action.yml` | Revised | Direct
collection/expected-suite descriptions; exact-version constraint
retained |
| `.github\actions\Get-PesterTestResults\src\main.ps1` | Revised |
Accurate report-name comments and direct failure wording |
| `.github\actions\Inject-SiteScripts\action.yml` | Revised | Clear
checked-out repository modifier |
| `.github\actions\Inject-SiteScripts\src\main.ps1` | Revised |
Imperative synopsis and direct injection description |
| `.github\actions\Inject-SiteScripts\src\inject-site-scripts.ps1` | No
prose | No comments or help |
| `.github\actions\Install-PSModule\action.yml` | Revised | Identifies
the bundled helper module |
| `.github\actions\Install-PSModule\src\main.ps1` | No prose | Only code
and suppression attribute strings |
| `.github\actions\Install-PSModule\src\PSModule\PSModule.psm1` |
Revised | Native helper help and explanatory comments; all examples and
links preserved |
| `.github\actions\Install-Zensical\action.yml` | Revised | Direct CLI
purpose |
| `.github\actions\Install-Zensical\src\main.ps1` | Revised | Imperative
synopsis and direct package-install description |
| `.github\actions\Install-Zensical\src\install-zensical.ps1` | No prose
| No comments or help |
| `.github\actions\Structure-Site\action.yml` | Revised | Direct
documentation/configuration purpose |
| `.github\actions\Structure-Site\src\main.ps1` | Revised | Imperative
synopsis and direct copy/configuration description |
| `.github\actions\Structure-Site\src\structure-site.ps1` | No prose |
No comments or help |
| `.github\actions\Test-PSModule\action.yml` | Revised | Direct option
descriptions; exact option values, examples, deprecation, and
compatibility constraints retained |
| `.github\actions\Test-PSModule\src\main.ps1` | No prose | No comments
or help |
|
`.github\actions\Test-PSModule\src\tests\Module\Module.Configuration.ps1`
| Excluded | Read-only test configuration |
|
`.github\actions\Test-PSModule\src\tests\Module\PSModule\PSModule.Container.ps1`
| Excluded | Read-only container data |
|
`.github\actions\Test-PSModule\src\tests\Module\PSModule\PSModule.Tests.ps1`
| Excluded | Read-only assertions and discovery implementation |
|
`.github\actions\Test-PSModule\src\tests\SourceCode\SourceCode.Configuration.ps1`
| Excluded | Read-only test configuration |
|
`.github\actions\Test-PSModule\src\tests\SourceCode\PSModule\PSModule.Container.ps1`
| Excluded | Read-only container data |
|
`.github\actions\Test-PSModule\src\tests\SourceCode\PSModule\PSModule.Tests.ps1`
| Excluded | Read-only assertions and discovery implementation |
| `.github\actions\update-index\action.yml` | Revised | Direct index
update description |
| `.github\actions\update-index\src\main.ps1` | No prose | No comments
or help |
| `.github\actions\update-index\src\Helper.psm1` | Revised | Direct
native help; generated output and exact examples preserved |
| `.github\actions\update-index\tests\Update-Index.Helpers.Tests.ps1` |
Excluded | Existing narrow regression test; no assertion change |
| `guidance\Add-Array.ps1` | No change | Complete guidance snapshot
preserved |
| `guidance\Add-HashTable.ps1` | No change | Complete guidance snapshot
preserved |
| `guidance\Add-String.ps1` | No prose | No comments or help; snapshot
preserved |
| `guidance\Caller.ps1` | No change | Synopsis changes require a
source/provenance decision |
| `guidance\ClassExtension.ps1` | No change | Complete guidance snapshot
preserved |
| `guidance\Loops.ps1` | No change | Synopsis changes require a
source/provenance decision |
| `guidance\Out-Null.ps1` | No prose | No comments or help; snapshot
preserved |
| `guidance\PipelineExecution.ps1` | No change | Synopsis changes
require a source/provenance decision |
| `guidance\PSCallStack.ps1` | No change | Synopsis changes require a
source/provenance decision |
| `guidance\PSCmdlet.ps1` | No change | Synopsis changes require a
source/provenance decision |
| `guidance\PSModuleTest.psm1` | No change | Snapshot preserved;
dot-source comment differs from Import-Module |
| `guidance\Read-File.ps1` | No change | Snapshot preserved;
greater-than token is redirection, not a Boolean comparison |
| `guidance\root.ps1` | No change | PSScriptAnalyzer loader snapshot
preserved |
| `guidance\WebCalls.ps1` | No change | Complete guidance snapshot
preserved |
Totals: 34 revised, 11 no-prose, 12 reviewed/no-change, and seven
excluded candidates. The reviewed CSV classifications match the
committed path set.
### Additional exclusions and blocked portions
| Surface | Disposition and evidence |
| --- | --- |
| `Build-PSModule\src\helpers\Build\PSScriptAnalyzer.Tests.psd1`;
`Install-PSModule\src\PSModule\PSModule.psd1`;
`Install-PSModule\src\PSModule\PSScriptAnalyzer.Tests.psd1` | Three
additional data/configuration files were read and left unchanged; no
configuration redesign or string edits |
| `.github\actions\Cleanup-PSModulePrereleases\**` | Entire reserved
source/metadata area excluded; existing release/recovery ownership
retained |
| `.github\actions\Get-PSModuleSettings\**`, including
`Settings.schema.json` | Entire reserved source/metadata/schema area
excluded |
| `.github\actions\Publish-PSModule\**` | Entire reserved
source/metadata/test area excluded |
| `.github\actions\Release-PSModule\**` | Entire reserved
source/metadata/test area excluded |
| `.github\actions\Resolve-PSModuleVersion\**` | Entire reserved
source/metadata/test area excluded |
| `tests\srcTestRepo\**`; `tests\srcWithManifestTestRepo\**` |
Functional fixture inputs excluded entirely from local reading, parsing,
execution, and edits |
| All README/Markdown, plugin, TOML, JSON, HTML, and workflow files |
Read-only sibling surfaces; the full diff proves that none changes |
| Exact examples and export descriptions | #574
records invalid example parameters, the mismatched Get-PSModuleManifest
example name, class output shape, the disputed `cmdlets/public` claim,
and missing substantive helper help. The protected text is not claimed
to be corrected here |
| `Test-PSModule` `Run_Path` input | #575
records the public input versus fixed `steps.paths.outputs.CodePath`
forwarding. Its caller contract needs a separate decision and behavior
checks |
| Guidance writing and behavior | The [complete-blob preservation
contract](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/reference/guidance-scripts.md#maintenance)
and the existing policy question in #481
require a source decision. The [audit
comment](#481 (comment))
records the `Read-File.ps1` FileRedirectionAst at line 15 and the
PSModuleTest import/comment discrepancy |
| Dependency resolver roadmap notes | Native help states the existing
manifest-based interface rather than future plans.
Prerequisite/parameter-set work remains separate;
#476 is relevant context |
| Release route | `.github\workflows\Release.yml` pins
`Release-GHRepository` at `750abed0ecab02394554b610dc3aa191e75e3248`.
Its interface uses legacy label defaults, not a verified canonical
`release:*` mapping. No release label or release-readiness claim is
added, and no release route changes |
Missing help sections and preserved output declarations are not evidence
of complete native-help contract coverage. This delivery does not add
copied/generated help or blanket section scaffolding. Existing native
`.LINK` values are preserved; preservation is not a claim that every
external target resolves.
### Ownership, plan progress, and convergence
Every commit follows a fresh live open-PR path check. Each check reads
all paginated file lists and compares exact paths, rather than assuming
directory ownership from a title. The checks cover 15 open PRs before
the first commit and 16 before later commits, excluding this PR itself.
The last pre-commit check is `2026-11-04T13:59:19+01:00`: all 34
proposed paths have no conflict. Reserved release/recovery areas and the
#551 test work remain untouched.
The delivery issue's inventory, baseline, early-draft, prose-edit, and
local-verification steps are complete. The issue retains the plan and
links this audit. The requested handoff is a pushed draft, not a
ready/merged PR.
The scoped convergence sweep searches open issues for native help,
`Run_Path`, `Read-File`, and help examples. It includes the
documentation-writing siblings and the existing guidance/dependency
issues. Only #558 converges with this prose
diff. #574, #575,
#481, and #476 remain
non-closing references. No additional issue is closed by this PR.
### Writing and framework sources
The writing criteria use
`MSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082`, not an unpinned
recollection:
| Source | Applied criterion |
| --- | --- |
| [Documentation
Model](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Documentation-Model.md)
| Evergreen resource prose; per-change evidence stays in the delivery
issue and PR |
| [Natural
Language](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md)
| en-US, direct and specific statements, present tense, exact technical
meaning |
| [Writing
Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md)
| Consult official STE rules/dictionary; preserve native formats and
contracts |
|
[Markdown](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Markdown.md)
| GFM for this audit; no repository Markdown edits |
|
[Documentation](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Documentation.md)
| Native help near code; concise explanatory comments, not copied
scaffolding |
| [PowerShell
Functions](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/PowerShell/Functions.md)
and
[Scripts](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/PowerShell/Scripts.md)
| Imperative synopses and native comment-based help; preserve tags and
association |
|
[YAML](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/YAML.md)
and [GitHub
Actions](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/GitHub-Actions.md)
| Preserve metadata syntax and execution/security configuration; use the
existing lint profile |
| [Microsoft native-help
syntax](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-7.5)
| Help keyword and script/function association checks |
| [STEMG overview](https://www.asd-ste100.org/about_STE.html),
[FAQ](https://www.asd-ste100.org/STE_faq.html), and [Issue
9](https://doi.org/10.5281/zenodo.23666006) | Active voice, short
sentences, imperative instructions, consistent technical terms, and
American spelling |
| [Pinned Task
format](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Issues/Types/Task.md)
and [PR
format](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/PR-Format.md)
| One delivery leaf, early draft, audience-facing result, section-scoped
evidence |
The official Issue 9 PDF is available locally and matches the published
MD5 `9c720341c350ed77943b2c73d01c716f`. The review consults rules 1.14,
3.2, 3.4, 3.6, 4.1, 5.3, and 6.3; technical-term categories in rules 1.5
and 1.12; and relevant dictionary entries, including the `gather` to
`collect` choice. No required writing source is unavailable. The PDF and
its extracted text remain local and are not republished. Manual review
and scans support these changes; they do not prove full STE conformance.
| Changed surface | Standards checked | Framework documentation checked
| Result |
| --- | --- | --- | --- |
| Build and documentation native help/comments | Pinned Documentation,
Natural Language, Writing Guide, PowerShell Functions | [Module layout
guidance](https://psmodule.io/Process-PSModule/guides/structuring-your-module/)
and complete local build/documentation implementation | Fixed in this
PR; protected contract gaps recorded in #574 |
| Installation and index helper native help | Same pinned
PowerShell/native-writing sources | Local manifest, installation,
TestData, and index implementations; [framework
overview](https://psmodule.io/Process-PSModule/) | Fixed in this PR; no
runtime or generated-output change |
| Site and test-report native help/comments | Pinned PowerShell Scripts
and writing sources | Local action entry points and [pipeline
reference](https://psmodule.io/Process-PSModule/reference/pipeline-stages/)
| Fixed in this PR |
| Action metadata description values | Pinned YAML, GitHub Actions, and
writing sources | All owned `action.yml` files and their complete
implementations | Fixed in this PR; Run_Path contract remains
#575 |
| Reviewed guidance snapshots | Pinned documentation/native-writing
sources | [Guidance
scripts](https://psmodule.io/Process-PSModule/reference/guidance-scripts/)
and immutable maintenance contract | Exception -
#481; all contents preserved |
</details>
<details>
<summary>Related references</summary>
- Resolves #558
- References #574
- References #575
- References #481
- References #476
</details>1 parent 96a4f16 commit a40a9eb
34 files changed
Lines changed: 317 additions & 313 deletions
File tree
- .github/actions
- Build-PSModule
- src/helpers
- Build
- Build-ZensicalSite
- src
- Document-PSModule
- src/helpers
- Expose-TestData
- Get-PesterCodeCoverage
- src
- Get-PesterTestResults
- src
- Inject-SiteScripts
- src
- Install-PSModule
- src/PSModule
- Install-Zensical
- src
- Structure-Site
- src
- Test-PSModule
- update-index
- src
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | | - | |
| 2 | + | |
3 | 3 | | |
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
8 | 8 | | |
9 | 9 | | |
10 | | - | |
| 10 | + | |
11 | 11 | | |
12 | 12 | | |
13 | 13 | | |
14 | 14 | | |
15 | 15 | | |
16 | 16 | | |
17 | | - | |
| 17 | + | |
18 | 18 | | |
19 | 19 | | |
20 | 20 | | |
21 | 21 | | |
22 | 22 | | |
23 | 23 | | |
24 | | - | |
| 24 | + | |
25 | 25 | | |
26 | 26 | | |
27 | 27 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
5 | 5 | | |
6 | 6 | | |
7 | | - | |
| 7 | + | |
8 | 8 | | |
9 | 9 | | |
10 | 10 | | |
| |||
21 | 21 | | |
22 | 22 | | |
23 | 23 | | |
24 | | - | |
| 24 | + | |
25 | 25 | | |
26 | 26 | | |
27 | 27 | | |
28 | | - | |
| 28 | + | |
29 | 29 | | |
30 | 30 | | |
31 | 31 | | |
32 | 32 | | |
33 | 33 | | |
34 | 34 | | |
35 | 35 | | |
36 | | - | |
| 36 | + | |
37 | 37 | | |
38 | 38 | | |
39 | 39 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
7 | | - | |
| 7 | + | |
8 | 8 | | |
9 | 9 | | |
10 | 10 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
5 | 5 | | |
6 | 6 | | |
7 | | - | |
8 | | - | |
| 7 | + | |
| 8 | + | |
9 | 9 | | |
10 | 10 | | |
11 | 11 | | |
| |||
24 | 24 | | |
25 | 25 | | |
26 | 26 | | |
27 | | - | |
| 27 | + | |
28 | 28 | | |
29 | 29 | | |
30 | 30 | | |
31 | | - | |
| 31 | + | |
32 | 32 | | |
33 | 33 | | |
34 | 34 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
5 | 5 | | |
6 | 6 | | |
7 | | - | |
8 | | - | |
| 7 | + | |
9 | 8 | | |
10 | 9 | | |
11 | 10 | | |
| |||
28 | 27 | | |
29 | 28 | | |
30 | 29 | | |
31 | | - | |
| 30 | + | |
32 | 31 | | |
33 | 32 | | |
34 | 33 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
5 | 5 | | |
6 | 6 | | |
7 | | - | |
8 | | - | |
9 | | - | |
| 7 | + | |
| 8 | + | |
10 | 9 | | |
11 | | - | |
12 | | - | |
13 | | - | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
14 | 13 | | |
15 | 14 | | |
16 | 15 | | |
17 | 16 | | |
18 | 17 | | |
19 | 18 | | |
20 | 19 | | |
21 | | - | |
22 | | - | |
23 | | - | |
24 | | - | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
25 | 24 | | |
26 | | - | |
27 | | - | |
| 25 | + | |
| 26 | + | |
28 | 27 | | |
29 | 28 | | |
30 | 29 | | |
| |||
43 | 42 | | |
44 | 43 | | |
45 | 44 | | |
46 | | - | |
| 45 | + | |
47 | 46 | | |
48 | 47 | | |
49 | 48 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
5 | 5 | | |
6 | 6 | | |
7 | | - | |
| 7 | + | |
8 | 8 | | |
9 | 9 | | |
10 | 10 | | |
| |||
13 | 13 | | |
14 | 14 | | |
15 | 15 | | |
16 | | - | |
| 16 | + | |
17 | 17 | | |
18 | 18 | | |
19 | 19 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
5 | 5 | | |
6 | 6 | | |
7 | | - | |
| 7 | + | |
8 | 8 | | |
9 | 9 | | |
10 | 10 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
5 | 5 | | |
6 | 6 | | |
7 | | - | |
| 7 | + | |
8 | 8 | | |
9 | 9 | | |
10 | 10 | | |
| |||
13 | 13 | | |
14 | 14 | | |
15 | 15 | | |
16 | | - | |
| 16 | + | |
17 | 17 | | |
18 | 18 | | |
19 | 19 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
5 | 5 | | |
6 | 6 | | |
7 | | - | |
| 7 | + | |
8 | 8 | | |
9 | 9 | | |
10 | 10 | | |
| |||
14 | 14 | | |
15 | 15 | | |
16 | 16 | | |
17 | | - | |
| 17 | + | |
18 | 18 | | |
19 | 19 | | |
20 | 20 | | |
| |||
0 commit comments