[Marius Storhaug (MariusStorhaug)]

Documentation command help uses direct en-US statements for supported results and controls. It distinguishes log/status strings, individual anchor strings, and structured results. The index command's synopsis, description, and Check help are visible through Get-Help.

Changed output entries use the native format owner's full .NET type name, a blank line, and a description paragraph. Callers need no action. Executable statements, emitted values/shapes, parameters/defaults, existing examples, and exit behavior remain unchanged.

Fixed: Native command help describes supported results

The help replaces figurative wording with observable conditions: missing test files and zero tests cause failure; valid Markdown pages without links differ from missing Markdown files; planned pin updates differ from written updates. Review help states its selected start times, SkipRequest/WhatIf window, result properties, and exit codes. Cross-repository help explains owner/host scope, GitHub anchor rules, the three outcomes, retry/cache behavior, and anonymous-reader access.

Output help describes existing emitted items, not internal List/HashSet containers or structured domain data that the commands do not return. Two commands gain missing native .OUTPUTS sections. A single required blank separator also fixes the index help's attachment defect. These corrections affect documentation and help visibility, not runtime behavior or caller contracts.

Technical details

Final source and alignment

The immutable PR base and writing-review baseline are MSXOrg/docs 1b0d4893c8fefabe604d04393068a8ff6f848082. The delivered head is 1ba4dc5174399f859e4a0afee516bd007f13fe37. Eight small commits are pushed; the draft opens after the first complete index-help improvement.

Changed surface	Standards checked	Framework docs checked	Result
.github/scripts/Invoke-PesterSuite.ps1: native help/parameters and log-output description	Fixed Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, PowerShell Scripts/Functions, native help, relevant Issue 9 guidance	None (no framework-specific docs)	Fixed in this PR
.github/scripts/Test-DocumentationLink.ps1: help/parameters, missing output section, emitted-anchor types	Same fixed sources; link/footnote/anchor contracts and actual output probes	None (no framework-specific docs)	Fixed in this PR
.github/scripts/Update-DocumentationIndex.ps1: help/parameter, one separator, missing output section	Same fixed sources; native help placement, nav-array behavior, status/silence probes	None (no framework-specific docs)	Fixed in this PR
.github/scripts/Update-GitHubActionPin.ps1: help/parameter and structured-output description	Same fixed sources; stable-release, authentication, ShouldProcess, actual structured result, and native output format	None (no framework-specific docs)	Fixed in this PR
.github/scripts/Wait-CopilotReview.ps1: help/parameters and structured-output description	Same fixed sources; timing, result properties/exits, and native output format	Fixed Contribution Workflow	Fixed in this PR
.github/scripts/Test-CrossRepositoryLink.ps1: released native help and parameter prose	Same fixed sources; scope, slug, checkout, retry/cache, actual output, and historical provenance	Matching replacement blocks in #240 at reviewed ee3c17855cb282cdf236fc764df3f45502f4c057	Released prose fixed here; two version-specific blocks covered by the existing matching effort, not baseline-aligned

No executable code, declaration/directive, actual output value/shape, exit, existing example/command, test, configuration, or Markdown page changes. No dependency, new tooling, repository audit/planning file, additional PR, or #240 lifecycle change is introduced.

Final format-only receipt

Commit 1ba4dc5174399f859e4a0afee516bd007f13fe37 changes only six output entries already modified by this campaign. Get-HeadingSlug, Get-CachedSlug, Get-MarkdownAnchor, and the cross-repository Write-WorkflowAnnotation use System.String. The previously edited action-pin and review-controller root entries use System.Management.Automation.PSCustomObject. Each full type is alone on its first line, followed by a blank line and its description paragraph. The four other changed root string entries already have that format. Earlier [string] directions identify the semantic type, not a prescribed help-field spelling.

Before-format cases pass 0/6; after-format cases pass 6/6. All ten changed/added output entries pass the fixed native format owner's rule and render the full name through Get-Help -Full. Exact masked-file comparison permits only those six output-field text spans and proves every other byte unchanged, including unrelated legacy entries and both code-PR-covered blocks. Executable token text, AST parent topology, original examples, and every help keyword remain identical to the already-verified 3d7a740e8a04d2b95cc8edec1b102b55c6388d89 implementation head. Existing analyzer settings report zero diagnostics in the four corrected files. No whole-help audit or section restructure is added.

Retained before/after and contract evidence

“Glue across the ecosystem is PowerShell” becomes the actual quoted-path/nav-array operation. “Drives one round” becomes the exact review-cycle/timestamp contract. “Green and worthless” becomes explicit no-file/zero-test failure conditions. Released honours, recognised, and Memoise wording becomes direct en-US explanations. Eight factual output corrections describe existing emitted items; the final format pass does not change those meanings.

Source-loaded and existing-fixture probes establish the actual contracts before the help corrections: annotation helper emits zero items outside Actions and one System.String inside; its caller emits two or three log/annotation strings with exit 1 for the no-link input; the pinned Pester empty-directory run emits five log strings with exit 1; valid-link validation emits one status string with exit 0; stale index check/update/current check emit three/two/zero items with exits 1/0/0. Heading/cache helpers emit four individual strings for the existing README, and the anchor helper emits two strings for anonymous two-heading input. No output is changed to fit the help. Named anonymous fixtures are removed, and no dependency is installed.

The fixed-baseline proof remains applicable: 8,591 original non-comment tokens plus the sole required index NewLine, all 7,284 AST nodes and parent relationships, 29 exact examples, six exact URL-shape rows, all 110 original help keywords plus only two authorized missing .OUTPUTS additions (112 total), unchanged protected bytes/non-owned comments/BOMs, six-path scope, and clean pushed source. No executable token is excluded or changed. The final formatting delta adds no keyword, layout outside an output entry, or code difference.

At baseline, index GetHelpContent() is null and native Get-Help shows syntax only. Native help exposes synopsis, description, and Check after the one required separator. This is an intentional documentation-format correction, not a retained gap.

Two-source coverage and deferred implementation metadata

The baseline Get-RenderedHeadingText help and top-level .NOTES remain byte-exact here: 655 and 337 UTF-8/CRLF bytes, with fingerprints retained in #256. Their matching replacement blocks and renderer implementation are reviewed at #240 source ee3c17855cb282cdf236fc764df3f45502f4c057. Both the coordinator and this session read that persistent source. The helper uses bundled Markdig with GitHub inline autolinks/strikethrough, keeps generic attributes literal, and separates GitHub slug generation; NOTES distinguishes original slug provenance from the renderer. No additional prose correction is identified in those reviewed blocks.

Those blocks are covered by the existing matching effort at that exact SHA, NOT baseline-aligned or permanent exceptions. This branch retains the old helper, so new-renderer claims/code are not copied here; edits to those version-specific blocks would wait until the code PR merges. No merge or extra future writing edit is needed to review the already-persistent matching source. #240 lifecycle remains untouched. Historical character-class facts retain their recorded comparison, named Unicode groups, 52 arrow/symbol differences, and 3 CJK differences.

Get-MarkdownAnchor retains the exact executable attribute [OutputType([System.Collections.Generic.HashSet[string]])] despite emitting two System.String items in the anonymous probe. Help describes emitted items accurately; the pre-existing implementation-metadata mismatch is explicitly deferred to the #240 functional owner. It is not metadata conformance or verified no-change. No source warning/history paragraph or unauthorized runtime/declaration change is added.

Validation and completed delivery

The retained implementation verification passes 49/49 affected Pester 6.0.1 tests with expected GUID, zero analyzer diagnostics across six scripts, zero syntax errors, relative links across 130 Markdown files, index -Check exit 0 without writes, whitespace checks, and exact invariants. Its runtime/output probes and six-script executable/AST proof remain applicable because this follow-up changes comment format only. The narrow follow-up adds native-format assertions, native-help display checks, exact output-span-only comparison, and zero analyzer diagnostics in the four corrected scripts.

All five new-head repository checks pass: Build, Lint, Links, Test, and Cross-repository links. Publish is skipped for this PR, as configured.

The one requested source-bound review approves exact head 1ba4dc5174399f859e4a0afee516bd007f13fe37. Its full summary reports no active review issues and no open issues. All review threads are resolved, with hasNextPage=false. The review arrives after the helper's three-minute wait; the result is verified directly through GitHub REST, without requesting a second review. That service timing is not a repository error or remaining blocker.

#256 retains the complete read/changed/no-change inventory, source expectations, before/after/probe evidence, commit identities, two-source coverage, and deferred metadata finding. No full inventory repeat or whole-help audit is needed for this format-only delta. Counts and scans do not certify full STE conformance. The focused convergence sweep identifies no additional fully satisfied issue; #239 and #245 remain non-closing context.

The missing parent ../AGENTS.md source-path limitation is recorded; the existing root route is followed. The inspected workflows publish Pages and do not invoke Release Management for this route, so no release metadata is added. No in-scope blocker remains. This PR remains DRAFT with auto-merge unset; app Agent merge is disabled with merge_pr=false. No readiness or merge action is performed. The Task stays open for later review and merge.

Related references

• Resolves [documentation-writing-alignment] Clarify documentation command help #256
• References Keep documentation tooling tests focused on supported behavior #240
• References [functional-test-alignment] Test supported documentation tooling behavior #239
• References [documentation-writing-alignment] Clarify language-specific coding standards #245
• Matching reviewed heading-fix source
• Fixed native output format owner
• Fixed Documentation Model
• Fixed Natural Language
• Fixed Technical Writing Guide
• Native PowerShell help conventions
• Official STEMG overview
• Official STEMG FAQ
• ASD-STE100 Issue 9

[Copilot]

🟡 Changes recommended

The PR description and preservation evidence still claim the native-help separator is absent, contradicting the intentional native-help visibility change in this diff.

1 open issue

• Update PR description for native-help visibility change · New

What changed in this PR

This PR clarifies help for six repository automation scripts so contributors can understand their supported behavior. It also adds the separator needed to expose the index script’s native help, without changing executable logic.

Changes:

• Clarifies parameters, validation scope, outputs, and exit conditions.
• Replaces idiomatic explanations with direct descriptions of existing behavior.
• Restores native-help attachment for the documentation index command.

File	Description
.github/​scripts/​Wait-CopilotReview.ps1	Clarifies request timing, polling, reviewer identities, and results.
.github/​scripts/​Update-GitHubActionPin.ps1	Clarifies token selection and output when writes are not approved.
.github/​scripts/​Update-DocumentationIndex.ps1	Explains navigation ordering and read-only checks; restores help attachment.
.github/​scripts/​Test-DocumentationLink.ps1	Clarifies supported links, footnotes, anchors, and empty-run behavior.
.github/​scripts/​Test-CrossRepositoryLink.ps1	Simplifies the description of validation scope and resolution outcomes.
.github/​scripts/​Invoke-PesterSuite.ps1	Clarifies test outcomes, module identity checks, and reporting.

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues remain for the PowerShell help clarifications and index-command help visibility update.

No open issues 🎉

1 resolved since last review

• Update PR description for native-help visibility change

_{Review effort: Balanced}

[Copilot]

🟢 Approved

There are no active review issues for the PowerShell help documentation updates.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues are identified for the PowerShell help documentation changes.

No open issues 🎉

_{Review effort: Balanced}