[documentation-writing-alignment] State native help and action descriptions directly #558

Context and request

Contributors and action callers need precise native help and interface descriptions. This delivery reviews comment-based help and documentation comments in the safe build, documentation, installation, test-reporting, site, test-framework, and index actions under .github/actions/, plus explanatory prose in guidance/. It also owns natural-language description values in those safe actions' action.yml files. It does not own any README, site Markdown, plugin skill, or workflow file.

Evidence and expected result

Build-PSModule/src/helpers/Build/Add-ContentFromItem.ps1 says "This function will add the content...". Build-PSModule/src/helpers/Build-PSModule.ps1 repeats "Builds a module" and calls the output location where modules are "outputted". Get-PesterCodeCoverage/action.yml says "A GitHub Action that is used to gather Code Coverage" and "where the script will run from". Use direct present-tense descriptions that retain the actual behavior and native help syntax.

Apply MSX Documentation, Natural Language, and Writing Guide. Use the language's native documentation format and the official STE rules, with the STEMG FAQ.

Acceptance criteria

• Every candidate native-help/interface-prose file has a recorded reviewed, no-prose, excluded, or blocked result.
• Native help and descriptions use direct en-US statements; executable instructions keep imperative verbs.
• Runtime tokens, function/parameter names, help tags, exact examples, paths, YAML keys/defaults/expressions, output text, and interface constraints remain unchanged.
• No code, tests, workflow behavior, generated copy, legal/external text, or dependency changes occur. A token/AST or equivalent comparison confirms the prose-only boundary.
• Existing parser/help/metadata checks and relevant narrow tests provide evidence; a prose scan is not presented as full STE verification.
• A focused early draft PR contains small commits and before/after evidence.

Technical decisions

Allowed action directories are Build-PSModule, Build-ZensicalSite, Document-PSModule, Expose-TestData, Get-PesterCodeCoverage, Get-PesterTestResults, Inject-SiteScripts, Install-PSModule, Install-Zensical, Structure-Site, Test-PSModule, and update-index. Only their help/comments and natural-language action descriptions are editable. Treat action test implementation as read-only. Exclude all Cleanup-PSModulePrereleases, Get-PSModuleSettings, Publish-PSModule, Release-PSModule, and Resolve-PSModuleVersion source/metadata/schema files because existing proposals own them. Exclude tests/srcTestRepo and tests/srcWithManifestTestRepo: their prose is functional fixture input. Recheck open PR file ownership before each commit. Report conflicts instead of editing another owner's paths.

The review baseline is 64ffb1d87f86bd5d487891fdb140b78385a00531. The manual inventory covers 64 candidates: 52 PowerShell files and 12 action metadata files with 110 description fields. Every file and its implementation has been read. Seven action test/configuration files remain read-only. Three additional .psd1 data/configuration files are excluded from prose edits. All 14 guidance files remain unchanged under the complete-blob preservation contract. Their prose findings remain review evidence, not permission to change copied snapshots.

The first build-help commit is pushed as 29d8cca. PSModule/Process-PSModule#570 opened as a draft immediately after that commit and remains draft. Six small commits are pushed through aa992660e3eefe8d9a3881d95fe32bab491d9f52. Local, origin branch, and PR head identities match. The full committed diff changes 34 paths: 22 PowerShell files and 12 action metadata files. The live ownership check reads every file page for all open PRs before each commit; no owned-path conflict is present.

Before prose edits, four exact expected-text checks fail as intended. The preservation baseline records 52 parsed PowerShell files, 71 native help topics, and zero parse errors. It retains non-comment token text/flags, AST shape, #Requires and structural directives, native-help association/tags, complete examples, and links. YAML comparison allows only existing root/input/output description values and also compares all text outside those scalar spans. The existing update-index Pester 6.1.0 test passes (1 passed, 0 failed). The repository analyzer profile reports two existing PSAvoidUsingPositionalParameters findings; final comparison must introduce no new finding.

Final proof retains all 23,371 non-comment PowerShell tokens, all 25,196 AST node/parent shapes, zero parse errors, native help association/tags, all 36 complete examples, and all three native .LINK entries. Get-Help -Full resolves all 71 existing topics without executing function bodies, benchmarks, network examples, or fixtures. YAML proof covers all 12 action files and 110 description fields; 73 descriptions change and all other nodes/text remain unchanged. The analyzer comparison retains only the two existing informational findings. The workflow's pinned YAML lint profile reports zero errors and reduces warnings from 73 to 43 with no new finding. The final existing update-index Pester suite passes (1 passed, 0 failed), and the full committed diff passes git diff --check.

The final commit includes both parent-review corrections: declarative Run_Throw precedence over Run_Exit in both descriptions, and System.String followed by a blank line and the indentation helper's output description. Seven expected-text/shape checks pass. An isolated anonymous Pester 6.1.0 probe confirms the actual precedence; the pinned runner forwards both flags unchanged. Raw-byte comparisons preserve BOM state in all 34 changed files. The parent acceptance review accepts the final head. Hosted review 5768802328 approves the same head with zero inline comments. At 2026-11-04T13:05:28Z, CI reports 25 passed, three skipped, and three in progress, with no reported failure. Pending checks are recorded, not claimed as passed; the PR stays draft.

The complete 64-file manual inventory and exact changed-path list are in the draft PR's Technical details: 34 revised, 11 no-prose, 12 reviewed/no-change, and seven excluded candidates. That block also records before/after acceptance text, source citations, exact validation commands/results, additional exclusions, scope proof, and the scoped issue-convergence result. All required writing sources are available. Scans and manual review support these changes; they do not prove full STE conformance.

Known gaps remain separate and open: PSModule/Process-PSModule#574 records example/help/export contracts; PSModule/Process-PSModule#575 records the unused Test-PSModule Run_Path input; PSModule/Process-PSModule#481 records guidance policy and the redirection/import discrepancies. Exact examples, disputed contract text, and runtime code remain unchanged. The release route uses the pinned legacy Release-GHRepository producer rather than a verified canonical release:* mapping. No release label or release-readiness claim is added. Only this delivery leaf converges with the prose diff. The requested result remains a draft with no merge, auto-merge, Agent merge, or further session.

Implementation plan

• Inventory and read candidate native help and action descriptions; record actual text evidence and review classifications before editing.
• Establish parser, non-comment-token, metadata-value, and applicable existing test baselines that can prove behavior is unchanged.
• Make the first coherent build-help commit and open a draft PR.
• Complete the remaining prose-only edits in small pushed commits, including the bounded parent-review corrections for Throw/Exit precedence and the System.String output heading.
• Compare code tokens and exact non-description YAML values, then review help rendering, examples, links, and technical meaning.
• Run applicable existing checks and record acceptance evidence, exclusions, and blockers in the issue and draft PR; leave the PR in draft.