[documentation-writing-alignment] Give module authors direct evergreen procedures #559

Context and request

Module authors need direct procedures that preserve the supported development, test, and review contracts. This delivery owns one prose-only draft pull request for these six files:

• docs/content/get-started/module-bootstrap.md
• docs/content/guides/module-development-orchestration.md
• docs/content/guides/skipping-framework-tests.md
• docs/content/guides/validating-before-review.md
• docs/content/guides/writing-module-tests.md
• docs/content/guides/writing-plugin-skills.md

The source snapshot is PSModule/Process-PSModule@64ffb1d87f86bd5d487891fdb140b78385a00531. All six files have a full manual read before edits and at the final head. The reader outcome is clear, evergreen en-US guidance, not a change to framework behavior.

The draft pull request is open after the first coherent commit, 5f5062cca628831bc4f3de8864c84bb2759ed6f7. Six small commits are pushed. The final head is d33a7e1773f9bde2527ae94fea7a8ed2c22a4acf. The PR remains in draft, with no merge or auto-merge.

Evidence and expected result

The writing baseline is MSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082: Natural Language, Writing Guide, Markdown, Documentation, Documentation Model, and the guide template. The Task and PR records follow the pinned Task, Issue Format, and PR Format.

The STEMG description, STEMG FAQ, and ASD-STE100 Issue 9 establish the expected wording properties. Descriptions use present tense and active voice. Procedures use short imperative instructions, with required conditions first. Each sentence gives one instruction or one fact. Technical terms, exact syntax, and normative requirements retain their meaning. The manual review uses Issue 9 rules 1.1-1.4, 3.2, 3.6, 4.1-4.3, 5.1-5.4, and 6.3, with relevant dictionary entries. Automated checks do not prove full STE conformance.

The provided local Issue 9 PDF has MD5 9c720341c350ed77943b2c73d01c716f, which matches the verified reference supplied by the coordinator. The PDF and its text extraction remain local and are not republished. No required writing source is unavailable.

The following comparisons are recorded before prose edits and verified against the final head. All six assigned guides change; no assigned guide has an unreviewed or no-change outcome.

Acceptance criteria

• All six assigned guides have concrete before/after or justified no-change evidence from a full manual read.
• Descriptions use definitive, present-tense en-US prose. Procedures use direct imperative actions and state required conditions.
• Test versions, discovery precedence, paths, framework-test IDs, bootstrap rules, command examples, warnings, and normative force remain unchanged.
• Statements about actual workflow support match repository evidence. Contradictions outside a prose fix remain explicit, with no invented enforcement claim.
• Headings, anchors, site design, navigation, and build configuration remain stable. Sentence-case heading edits retain their existing anchors.
• Small commits and an early draft PR retain review evidence and existing check results, without a new repository linter or dependency.

Technical decisions

Use the guide template's reader outcome, prerequisites, ordered actions, and verification where the existing guide provides them. Preserve the existing section structure and anchors instead of imposing a site redesign or empty template sections.

All fenced examples remain byte-for-byte unchanged. Preserve exact public inputs, defaults, paths, framework-test IDs, runtime/version constraints, discovery precedence, warnings, and MUST/SHOULD/MAY force. A manual requirement is not evidence that CI enforces it.

The following sources are inspected as read-only evidence, using the relevant sections for source and reference files: README.md, AGENTS.md, .gitignore, .github/actions/Get-PSModuleSettings/src/main.ps1, .github/actions/Test-PSModule/src/tests/SourceCode/PSModule/PSModule.Tests.ps1, .github/workflows/workflow.yml, .github/workflows/Test-ModuleLocal.yml, .github/workflows/BeforeAll-ModuleLocal.yml, .github/workflows/AfterAll-ModuleLocal.yml, .github/workflows/Docs.yml, .github/workflows/Linter.yml, .github/workflows/Release.yml, .github/linters/.markdown-lint.yml, .github/linters/.textlintrc, .github/plugin/README.md, .github/plugin/psmodule/plugin.json, .github/plugin/marketplace.json, docs/zensical.toml, docs/content/reference/versioning.md, docs/content/reference/powershell-module-standard.md, and docs/content/reference/test-specification.md. The remote action contract at PSModule/Invoke-Pester@c5494aba3c07d7bfd81bdbbc9f301e8fa4a729fb and its v5.1.1 tag are also inspected.

These supporting files have a justified no-change result: the delivery changes guide prose, not runtime behavior, implementation, native help, tests, metadata, or configuration. The plugin metadata parses without a change. The release workflow excludes this six-guide path set; this PR has no release-managed artifact record or release:* decision.

The other getting-started, workflow, authentication, structure, configuration, and release guides, reference pages, indexes, plugin skills, code/tests, and configuration are excluded. Existing owners are #524, #525, #531, #535, #537, #541, #548, and #549. #551 changes no documentation or native help. The live open-PR path check finds no overlap with the six assigned files; repeat it before each commit.

The source review identifies these discrepancies:

• The baseline test guide names the v5.1.0 action contract. The checked-in test workflow pins v5.1.1 at c5494aba3c07d7bfd81bdbbc9f301e8fa4a729fb. That pinned interface also lacks Run.Shuffle, Run.ShuffleSeed, Run.Parallel, Run.ParallelThrottleLimit, and Debug.ShowStartMarkers. The prose uses the verified v5.1.1 label and links its exact action contract. This correction changes no workflow reference or Pester/runtime constraint.
• The baseline test guide calls the declaration a 6.1.x requirement, but the exact #Requires block has a 6.1.0 minimum and MaximumVersion = '6.*'. The prose introduces "this Pester requirement" without the misleading label. The code block and actual runtime/version constraints remain byte-for-byte unchanged. The v5.1.1 tag is independently verified to resolve to c5494aba3c07d7bfd81bdbbc9f301e8fa4a729fb.
• The shared-resource examples use $env:RUNNER_OS in one-time setup and matrix tests. Setup runs once on Linux; the examples do not provision every OS-specific name that Windows and macOS tests read. An anonymous name-only experiment reproduces the mismatch for run ID 1234: setup creates Test-Linux-1234, but Windows and macOS tests derive Test-Windows-1234 and Test-macOS-1234. The samples remain unchanged. [documentation-writing-alignment] Match shared test-resource names to the full OS matrix #571 tracks the design and example correction.
• Bootstrap says that only a change to the core's own contract is a major bump. docs/content/reference/versioning.md requires a major bump for any incompatible public-API change. The requested bootstrap-contract preservation keeps that inherited policy statement unchanged in meaning. [documentation-writing-alignment] Resolve the bootstrap major-bump policy conflict #573 owns the policy conflict; this PR does not choose a new version policy.

Implementation plan

• Read all six assigned guides and the pinned writing sources. Establish expected wording properties and record the before/after acceptance targets before edits.
• Read repository contract evidence and check live PR path ownership.
• Complete baseline checks using the existing Markdown, terminology, and site configuration.
• Revise module-bootstrap.md, preserve its branch/release contract, commit the coherent change, and immediately open a draft PR.
• Revise writing-module-tests.md and skipping-framework-tests.md without changing samples, Pester/runtime constraints, discovery, or skip contracts; commit and push.
• Revise module-development-orchestration.md and validating-before-review.md without changing ownership or validation requirements; commit and push.
• Revise writing-plugin-skills.md without changing plugin interfaces or checks; commit and push.
• Review all procedures, exact interfaces, links, unchanged passages, and normative force against the acceptance criteria.
• Run applicable existing checks. Record final scope, before/after evidence, check results, discrepancies, and blockers in this issue and the draft PR. Leave the PR in draft.

Validation evidence

The final immutable comparison is 64ffb1d87f86bd5d487891fdb140b78385a00531 to d33a7e1773f9bde2527ae94fea7a8ed2c22a4acf. The worktree is clean and the pushed branch has exactly the six assigned changed paths.

The direct textlint command is unavailable. The cache-only attempt confirms the missing packages before a session-local restore. Its Windows CLI loader does not load the configured rule. The successful kernel invocation loads the existing Markdown parser and the exact rules.terminology options from .github/linters/.textlintrc. An intentional Powershell positive control reports the required PowerShell correction. No repository dependency, linter, or configuration is added. No standalone repository link-check script exists, so the scoped link check uses the Python standard library and the actual generated HTML. These results do not prove full STE conformance.

Manual final review covers every paragraph in the six guides, including unchanged passages and all examples. It verifies the bootstrap contract, discovery precedence, exact paths, IDs, warning semantics, caller-provided TestData, runtime/version constraints, and requirement strength. No normative requirement is presented as proof of CI enforcement. No link repair requires another owner's file.

The scoped convergence sweep examines open campaign issue titles and declared paths, plus searches for bootstrap/major, version policy, and RUNNER_OS. Only #559 is fully covered by this diff. #571 and #573 remain non-closing follow-ups. Other campaign deliveries name excluded surfaces and remain open.

Hosted checks and handoff

The final-head gh pr checks 565 --repo PSModule/Process-PSModule --json name,state,link snapshot reports 22 successful checks, one skipped Publish check, and no pending or failed checks. Copilot approves d33a7e1773f9bde2527ae94fea7a8ed2c22a4acf with "No open issues" and no inline comments. This includes the final-head site Build, Lint, Lint code base, CodeQL, and Analyze (actions) results. The PR remains in draft for the requested acceptance review.

No new local failure or scope blocker remains. The two linked source discrepancies remain explicit follow-ups. Generated site output and the session-local temporary checker restore are removed after verification. The worktree is clean and local/remote commit counts are 0 0. The delivery is an inspectable committed/pushed draft, not readiness authorization, merge, or completion of the still-open issue.