[documentation-writing-alignment] Describe reusable action behavior in clear reference prose #557

Context and request

Reusable action users need clear descriptions of inputs, results, and failure conditions. This delivery owns the READMEs in .github/actions/Build-ZensicalSite/, Get-PesterCodeCoverage/, Get-PesterTestResults/, Inject-SiteScripts/, Install-PSModule/, Install-Zensical/, and Structure-Site/.

Evidence and expected result

The Pester-result README opens with "A GitHub Action that gathers Pester test results for the PSModule process by analyzing test artifacts from the workflow run." Its next sentence is "It validates test execution and results, providing a summary and failing if any tests are unsuccessful." The recommendation is "It is recommended to use the Process-PSModule workflow to automate the whole process of managing the PowerShell module." Results are "logged" and failures are "marking" a step failed. These exact baseline examples establish the writing gaps before the edit.

The writing baseline is MSXOrg/docs at 1b0d4893c8fefabe604d04393068a8ff6f848082. The review covers Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, and the reference and guide templates. The existing action reference layout remains in place.

The official STE description, FAQ, and Issue 9 are available. The read-only local PDF matches the publisher's MD5, 9c720341c350ed77943b2c73d01c716f. Relevant rule and dictionary details were read in the local extraction; the manual is not copied into repository or issue artifacts.

Expected wording properties, set before editing:

• Name the action, workflow, or GitHub Actions as the actor for each result.
• State supported behavior in the present tense. Remove history, promotion, and claims that do not help the reader.
• Replace action clauses such as "by analyzing", "providing", and "marking" with direct verbs. Keep exact technical nouns and identifiers.
• Give usage instructions in the imperative. Keep the workflow recommendation advisory with "For the recommended setup, use ...".
• Use short en-US sentences and sentence-style headings. Preserve heading slugs, links, input settings, output and artifact names, commands, and complete fenced examples.
• Treat source contradictions as exceptions that need separate contract work, not permission to change the interface under a writing-only task.

These properties use the pinned MSX sources and the relevant Issue 9 rule groups 1, 3, 4, 5, and 6. The review also consulted dictionary entries for collect, check, recommend, combine, generate, fail, and verify. GitHub Actions status terms, PowerShell module names, and Pester report fields keep their technical meanings. Neither a word scan nor Markdown lint proves full STE conformance.

Acceptance criteria

• Each of the seven READMEs has a full manual review and concrete changed/no-change/blocked evidence.
• Descriptive prose uses present-tense, direct en-US statements; usage instructions remain imperative.
• Input names, defaults, required flags, outputs, artifact names, command/YAML examples, version constraints, and compatibility claims remain unchanged by the writing edit. Any existing accuracy gap has explicit source evidence.
• Existing heading anchors and links remain correct. Factual contradictions that need contract changes are reported rather than silently resolved through prose.
• Only owned README prose changes. Native help, action metadata, runtime source, tests, generated output, and site configuration remain unchanged.
• Small commits, an early draft PR, and existing relevant Markdown/link checks provide review evidence. A scan is not presented as full STE verification.

Technical decisions

The repository source baseline is 64ffb1d87f86bd5d487891fdb140b78385a00531. All seven READMEs, their action.yml files, and their entry scripts were read. The coverage helper, site helper scripts, and Pester caller workflows were also read. GitHub-Script at 8083ec1f733f00357ee4d0db0c6056686e483bc0 supplies evidence for the delegated token and module bootstrap behavior.

Publish, Release, Resolve, and Cleanup action documentation belongs to existing release/recovery proposal owners. Other action READMEs, native help, action descriptions and metadata, runtime source, test files, site/plugin docs, workflows, and generated output are excluded. Open PR path ownership shows no overlap with the seven owned READMEs. Direct inspection confirms that #551 changes no README or action metadata. Ownership is checked again before each commit.

Contract exceptions

1. The installer README names Helpers and a "latest" copy in its behavior section and example. The local script installs the bundled PSModule module at 999.0.0. The behavior section and complete examples remain unchanged.
2. The coverage README requires gh run download. The local script uses Get-GitHubArtifact and Save-GitHubArtifact. The requirement and exact command remain unchanged.
3. Coverage metadata declares MissedPathReportPath through steps.Get-PesterCodeCoverage.outputs.MissedPathReportPath, but its step has no id. The pinned GitHub-Script composite exposes only result. The runtime writes the report files and the inner step output, but the outer output route is not established by this metadata. The writing edit does not repair metadata or remove the documented output.
4. Both Pester README tables say Version defaults to Latest. Their local metadata has no explicit version default. The pinned bootstrap can reuse an installed GitHub module when the input is empty, so "Latest" is not a guarantee in that environment. The table defaults remain unchanged.
5. .github/actions/Get-PesterCodeCoverage/README.md calls PSModule/Get-PesterCodeCoverage@v1. The framework caller uses ./_wf/.github/actions/Get-PesterCodeCoverage. These are different source targets; their equivalence is not established.
6. .github/actions/Get-PesterTestResults/README.md calls PSModule/Get-PesterTestResults@v1. The framework caller uses ./_wf/.github/actions/Get-PesterTestResults. These are different source targets; their equivalence is not established.
7. Both installer examples call PSModule/Install-PSModule@v1. The local composite runs its bundled entry script. The full example runs Get-Command -Module Helpers, while local source installs PSModule. The examples remain unchanged; their equivalence to the local composite is not established.

PSModule/Process-PSModule#572 is the open owning-repository Task for all seven contract exceptions. Each standalone/local example mismatch has a separate evidence row there. These are factual exceptions, not acceptance passes for source accuracy. The writing PR does not repair runtime behavior, action metadata, version policy, or integration targets.

Verification before edits

The five targeted Pester-result wording checks fail on the baseline, as expected: by analyzing; providing a summary and failing; It is recommended; Detailed results are logged; and marking the workflow step.

The existing Markdown configuration passes on all seven baseline files:

$readmes = @(
    '.github\actions\Build-ZensicalSite\README.md',
    '.github\actions\Get-PesterCodeCoverage\README.md',
    '.github\actions\Get-PesterTestResults\README.md',
    '.github\actions\Inject-SiteScripts\README.md',
    '.github\actions\Install-PSModule\README.md',
    '.github\actions\Install-Zensical\README.md',
    '.github\actions\Structure-Site\README.md'
)
npx --no-install markdownlint-cli2 --config .github\linters\.markdown-lint.yml @readmes

Result: markdownlint-cli2 v0.24.0, markdownlint v0.42.0, seven files, zero issues, exit 0. No dependency installation was needed. The repository has no dedicated documentation link checker. Markdownlint checks same-file fragments. The only six prose links use two unchanged public targets, https://github.com/PSModule and https://github.com/PSModule/Process-PSModule; both resolve through GitHub's API. Final checks compare all fenced blocks, heading slugs, URLs, input/default cells, and inline identifiers with the source baseline.

Implementation plan

• Read all seven READMEs and applicable writing sources; record expected changes and before/after interface preservation checks.
• Read corresponding action metadata/source and identify relevant existing checks.
• Revise Pester-result prose, verify its contracts, commit, push, and open the focused draft PR.
• Revise coverage prose in a small commit; recheck open PR ownership and preserve contract exceptions.
• Revise neutral installer prose in a small commit; recheck open PR ownership and preserve contract exceptions.
• Verify all documented interfaces, examples, anchors, and links against the source baseline and record manual source-review results.
• Run the applicable existing checks and record acceptance evidence and unresolved contradictions in the issue and draft PR; keep the PR in draft.

The early draft is PSModule/Process-PSModule#569. Its first pushed commit is 11e54fa38bb4a2aae57140ed6c55efecfa4f8726. All five baseline wording checks now pass. The first-commit comparison passes for all seven READMEs: fenced examples, headings apart from case, link URLs, inline identifiers, and input name/required/default cells remain unchanged. The Pester-result README passes the existing Markdown rules with zero issues. Open PR ownership still has no overlap with the seven assigned README paths.

The coverage prose is pushed in cb48ff8308ddb46d98eb3527f0e4dbc4289b705c. The final comparison verifies its four complete fenced examples, including the list-indented summary-selection example, plus headings apart from case, URLs, inline identifiers, and input name/required/default cells. All match the baseline. Its Markdown check reports zero issues. Ownership was rechecked before the commit, with only this draft touching the assigned README paths.

Before the installer edit, four expected baseline checks fail: introductory sentence fragment, the unsupported "critical component" claim, the impersonal recommendation, and the contraction "Here's". The edit changes only neutral prose. The three Helpers behavior bullets and both fenced examples remain unchanged because they have a source-contract conflict.

Acceptance evidence

The pushed draft head is 2742b3da509fbdd67caf5c5c5d2c19a8959dd899. GitHub and git ls-remote --heads origin action-readme-alignment report that same head. The PR base is 64ffb1d87f86bd5d487891fdb140b78385a00531. The worktree is clean. The PR remains open and draft; auto-merge is unset.

Exact before/after evidence

The source citations above support the contract exceptions. The changed test-result behavior also matches artifact collection, result/failure evaluation, and summary/exit handling. Coverage target selection matches lines 123-131, and failure below target matches lines 389-397.

Final checks

A native Copilot review was explicitly requested. Review 5768356776 is APPROVED at the final head, with no inline comments. Its clean wording review does not convert the retained source-contract exceptions into accuracy passes. At final inspection, all reported GitHub checks are complete with SUCCESS or SKIPPED; none reports failure. This includes the repository linter and both default/manifest workflow test runs.

The scoped issue-convergence search covers open issues with README/action terms, the seven action names, and the documentation-writing-alignment family. It also checks #442 and #360. Only #557 is satisfied by this writing diff. #572 remains open for contract repair; sibling and broader issues are not closed.

All required sources are available. No cross-owner heading or link repair is needed. There is no blocked prose edit. The remaining factual exceptions are not repaired or counted as accuracy passes. No runtime, action/lifecycle metadata, workflow configuration, or release label changes form part of this delivery.