Repository navigation
[documentation-writing-alignment] Reconcile reusable-action README contracts with local sources #572
Description
Context and request
Readers of the local reusable-action READMEs need examples, defaults, download prerequisites, and behavior descriptions that match the intended source contracts. The source review for #557 found accuracy gaps that its writing-only PR cannot safely resolve. This Task owns README/source-contract accuracy only. #569 preserves the existing contracts and examples.
Evidence and acceptance criteria
The evidence baseline is PSModule/Process-PSModule@64ffb1d87f86bd5d487891fdb140b78385a00531.
| Surface | Evidence | Required result |
|---|---|---|
| Installer behavior and examples | README names Helpers and a latest copy; local source, lines 8-17 installs bundled PSModule at 999.0.0. |
State the actual module and version behavior. Verify the complete example against its intended action target. |
| Coverage download prerequisite | README requires gh run download; local source, lines 34-35 delegates downloads to Get-GitHubArtifact and Save-GitHubArtifact. |
Establish the actual dependency requirement before retaining or removing the CLI claim. The local script alone does not establish a transitive CLI requirement. |
Pester Version defaults |
Both README tables state Latest; local metadata has no explicit version default. Pinned bootstrap source can reuse an installed GitHub module when no version is set. |
Explain the omitted-input behavior for both a fresh and a preloaded runner, without promising an unverified latest-version guarantee. |
| Coverage example target | .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. |
Establish the intended README target and verify its version, inputs, and outputs. No equivalence between the standalone action and the local composite is established. |
| Test-result example target | .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. |
Establish the intended README target and verify its version, inputs, and failure behavior. No equivalence between the standalone action and the local composite is established. |
| Installer example target | Both examples in .github/actions/Install-PSModule/README.md 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. |
Establish the intended README target and verify its version and module commands. Do not replace the standalone integration contract without compatibility evidence. |
Technical decisions
Keep this work separate from the writing-only delivery. Native help/action-description writing belongs to #558. Coordinate README ownership before documentation edits. Runtime source, action metadata, lifecycle settings, version policy, and Publish, Release, Resolve, and Cleanup action docs remain outside this Task.
The download prerequisite, module bootstrap defaults, and standalone examples need immutable source or execution evidence before a README accuracy decision. No equivalence between a standalone action and a local composite is assumed. No dependency or enforcement tool is prescribed.
Use the pinned MSX Task format and writing baseline. Keep runtime names, defaults, required flags, commands, and failure semantics unchanged. Correct only documentation from verified source and compatibility evidence.
References #576 for the independent MissedPathReportPath runtime/output-route repair. This is a non-closing relationship. That Bug alone owns the failing caller-boundary regression and implementation. This Task keeps the README output claim as a factual exception until the Bug supplies verification; it does not repair or absorb the runtime defect.
Implementation plan
- Verify the intended local/standalone example targets, actual artifact-download dependency, and fresh/preloaded module bootstrap behavior; record immutable source identities and compatibility evidence before README edits.
- Define repeatable README acceptance checks for examples, documented input/default/output claims, and explicit factual exceptions before changing text.
- Make only the verified README/source-contract accuracy corrections in one focused documentation PR after ownership coordination. Keep the independent runtime repair in [documentation-writing-alignment] Expose the coverage report path to composite callers #576.
- Verify complete examples against their intended source targets, preserve runtime contracts and report/artifact names, and run the relevant existing Markdown/link checks. Retain any unverified claim as an explicit exception with its owning issue.
Activity
MariusStorhaug commentedon Nov 4, 2026
The evidence now lists coverage, test-result, and installer standalone/local example targets separately. The pinned GitHub-Script output citation is corrected to lines 73-76. #569 preserves these factual exceptions at 2742b3d; its prose-preservation and writing checks do not certify the contracts. This Task remains open for the source-backed contract work, with shared-file ownership coordination before changes.
[-]Reconcile reusable-action README contracts with local sources[/-][+][documentation-writing-alignment] Reconcile reusable-action README contracts with local sources[/+]MariusStorhaug commentedon Nov 4, 2026
The campaign prefix is added to the title. The independent MissedPathReportPath runtime/output-route repair is split into native Bug #576, with immutable source evidence and its own regression-first plan. This Task now owns only README/source-contract accuracy; its runtime-fix acceptance row and plan are removed. The reference to the Bug is non-closing. No code, source, PR scope, labels, or lifecycle settings change in this tracking correction.