[Marius Storhaug (MariusStorhaug)]

Module authors have direct reference guidance for integration modules, data conversion, Pester test structure, framework test jobs, and guidance-script maintenance. This documentation change preserves the existing technical contracts. Module and pipeline behavior do not change, and no consumer action is required.

Changed: Module development references use direct technical prose

The references replace metaphors and vague assurances with concrete descriptions and direct instructions. They distinguish conventions from proof of enforcement. The no-mocks prohibition, Context requirements, conversion directions, test hierarchy, public names, paths, samples, and framework test IDs retain their meaning.

The conversion section has a descriptive heading and retains its previous #the-neutral-object-is-the-pivot anchor. No cross-owner link change is required. The dependency reference remains unchanged because its roles and version statement are already clear.

Technical details

Delivery and comparison. #556 owns this one focused prose delivery. The immutable comparison is 64ffb1d87f86bd5d487891fdb140b78385a00531 to 5ee3e9393c6bd47f78def6b5841cf22ecacad86f. The remote branch and PR head match the delivered SHA. The PR stays in draft; no merge, auto-merge, or Agent merge action is taken.

Three small commits deliver the change: 8d148a49fa24915dc6bbb5b5acd92bd93e27c2f9 states module-type conventions, b158a5312295ec0271c6d967aca24bd81b3d6772 states Pester test rules, and 5ee3e9393c6bd47f78def6b5841cf22ecacad86f clarifies test jobs and script maintenance. The draft was opened after the first coherent commit. Ownership checks immediately before the commits inspected 11, 14, and 16 open PRs and found no other owner of an assigned path.

Complete reviewed scope. All six assigned documents were read in full before editing and after the final edits. The five changed paths below are the complete PR diff.

Exact path	Result	Review evidence
docs\content\reference\dependencies.md	Reviewed; no change	Dependency roles, URLs, and the independent-version statement are direct. Baseline and final blob: 04e3e15b239a7e9390bed9d91e043d70ed2ce5bf.
docs\content\reference\framework-test-ids.md	Reviewed; changed	Jobs are the actors, and import validation describes the existing no-throw assertion. Source-code test rows, IDs, categories, skip examples, paths, and module-test names are unchanged.
docs\content\reference\guidance-scripts.md	Reviewed; changed	Reference scripts are distinct from module source. The complete-file import instruction names guidance/. Script names, table content, environment caution, and content preservation remain.
docs\content\reference\module-development-foundations.md	Reviewed; changed	Conventions do not become blanket enforcement claims. All five linked reference pages remain.
docs\content\reference\module-types.md	Reviewed; changed	Concrete service, settings, and conversion descriptions preserve transport choices, Context obligations, command patterns, examples, and both conversion directions.
docs\content\reference\test-specification.md	Reviewed; changed	Direct instructions preserve the hierarchy, naming examples, complete Pester sample, no-mocks prohibition, real-input recommendation, and full-coverage requirement.

Before/after acceptance evidence. The pre-edit review records the source criteria, actual baseline text, expected changes, and exclusions before editing.

Before	Delivered text or result	Acceptance basis
"feel the same to use"	"This page defines additional conventions for each module type."	A present-tense statement replaces subjective intent.
"PowerShell face"	"Integration modules provide PowerShell commands for an external service."	A concrete interface replaces a metaphor.
"common pivot"	"as the intermediate representation", followed by the two conversion steps	The object model and both directions remain explicit.
"The goal is to ensure consistency"	"This specification defines the Pester test hierarchy, input guidance, and coverage requirements for PowerShell functions."	The page states its contract instead of an aspiration.
"This ensures our tests are structured, maintainable, and adhere to best practices."	"The example groups Get-Uri tests under the Uri module and uses separate contexts for direct and pipeline input."	An observable description replaces an assurance.
"Run by the ... job"; "imports cleanly"	The named jobs run the tests; import validation says an import "does not throw an error".	Active descriptions match the existing Should -Not -Throw assertion.
"conventions that the framework supports and validates"; "framework wiring"	The pages "define repository, source, test, and release conventions"; "workflow configuration"	Guidance is distinct from implementation and enforcement evidence.
"framework learning assets"; "into this directory"	"These scripts are not Process-PSModule module source"; import into guidance/	The role and destination are explicit; the published-set condition, complete-file import, and content-preservation instructions remain.

Pinned source criteria. The writing baseline is MSXOrg/docs at 1b0d4893c8fefabe604d04393068a8ff6f848082:

• Documentation Model: present-tense resource documentation; delivery evidence belongs in the issue and PR; a contract does not prove CI enforcement.
• Natural Language and Writing Guide: en-US, concrete nouns, active verbs, precise obligations, and preserved technical meaning, identifiers, native syntax, and normative force.
• Markdown, Documentation, and reference/standard templates: retain lookup and rule purposes, native samples, and valid links without empty template sections.
• Task format and PR format: keep the executable plan in the delivery leaf and supporting evidence in this block.

The official STE description, FAQ, and Issue 9 were available. Rules 1.1-1.3, 3.2, 3.6, 5.1-5.4, 6.1-6.5, and 9.1-9.4 and relevant dictionary material informed the manual review. The supplied PDF's MD5, 9c720341c350ed77943b2c73d01c716f, matches the official Zenodo record. The reference files remain local and read-only. This review does not claim complete STE conformance or certification; lint and word counts do not establish it.

Changed surface	Standards checked	Framework docs checked	Result
framework-test-ids.md	Pinned writing criteria; active voice; exact technical names	Existing source-code and module-test definitions	Fixed in this PR.
guidance-scripts.md	Pinned writing criteria; direct instructions; explicit destinations	Existing guidance-script inventory and maintenance contract	Fixed in this PR.
module-development-foundations.md	Pinned writing criteria; guidance versus enforcement	Existing five linked reference pages	Fixed in this PR.
module-types.md	Pinned writing criteria; concrete terminology; stable anchors	Existing module-type and Context conventions; linked PowerShell module standard	Fixed in this PR.
test-specification.md	Pinned writing criteria; imperative instructions; preserved obligations	Existing Pester hierarchy and sample	Fixed in this PR. Exception - #563 remains unresolved.

Validation. These existing commands pass:

npx --no-install markdownlint-cli2 --config .github\linters\.markdown-lint.yml docs\content\reference\dependencies.md docs\content\reference\framework-test-ids.md docs\content\reference\guidance-scripts.md docs\content\reference\module-development-foundations.md docs\content\reference\module-types.md docs\content\reference\test-specification.md
git --no-pager diff 64ffb1d87f86bd5d487891fdb140b78385a00531 HEAD --check
Push-Location -LiteralPath docs
zensical build --clean
Pop-Location
gh pr checks 566 --repo PSModule/Process-PSModule

Markdownlint reports six files and zero issues before editing and at the final head (markdownlint-cli2 0.24.0, markdownlint 0.42.0). The site build reports "No issues found" before editing and after the final edit. Whitespace checks pass. Inline Python standard-library comparisons at the committed final head verify the unchanged front matter, link targets, source-code test rows, IDs, skip examples, module-test names, guidance table, REST mapping, command patterns, identifiers, Pester sample, hierarchy, and naming examples. All five original prose acceptance failures are absent.

A final generated-HTML comparison preserves all 132 baseline HTML IDs across the six pages. HTMLParser resolves all 41 rendered local article links and fragments, including both conversion anchors. The complete tracked-path comparison finds five changed paths, one reviewed/no-change path, 330 excluded paths, and zero excluded changes. The worktree is clean after removal of only task-generated site/cache outputs.

Final-head GitHub checks: 22 passed; one skipped; none pending or failing. The Docs Publish job is skipped for a PR, as the existing workflow specifies. The explicitly requested final-head review is approved at 5ee3e9393c6bd47f78def6b5841cf22ecacad86f with no inline comments.

An initial --site-dir build attempt failed because the installed Zensical CLI does not support that option. The unmodified repository build command passed. No tool or dependency was installed or added. The repository has no Test-DocumentationLink.ps1 or Test-CrossRepositoryLink.ps1; external URL availability is not asserted. Runtime Pester tests were not run because no executable source or sample changed.

Exclusions. Every tracked path outside the six-row reviewed scope is excluded. The complete excluded reference list is pipeline-stages.md, powershell-module-standard.md, repository-standard.md, scenario-matrix.md, settings.md, versioning.md, and workflow-inputs.md, all under docs\content\reference\. All four specification pages remain excluded: docs\content\specification\design.md, index.md, principles-and-practices.md, and spec.md. All guides, getting-started pages, indexes, glossary/module pages, skills, source code, native help, tests, functional test-fixture Markdown, configuration, site design, README files, and guidance-script source remain unchanged. #551 is outside this delivery.

Unresolved policy exception. The baseline test specification says "No Mocks: We do not use mocks in tests." The reserved powershell-module-standard.md#tests says "Unit tests mock boundaries owned by the module, not third-party APIs or SDKs directly." The delivered instruction is "No Mocks: Do not use mocks in tests." It preserves the prohibition without choosing a policy or claiming enforcement. #563 owns the unresolved contradiction and is not closed by this PR. There is no blocker to this prose-only draft.

Plan and issue convergence. Source review, pre-edit evidence, baseline checks, three prose slices, invariant review, final checks, and durable evidence complete the delivery leaf's plan. The scoped search covered the documentation-writing leaves and open issues whose bodies name module-types or test-specification. #479 requires module audits, #483 requires a resilience contract, #338 requires DSC support, and #471 requires dependency-versioning guidance. This diff does not deliver those outcomes. No additional issue fully converges. Only #556 is a closing reference.

The documentation-only paths do not invoke .github/workflows/Release.yml; no release labels or release-decision block apply.

Related references

• Resolves [documentation-writing-alignment] State module reference rules with precise technical prose #556
• References [documentation-writing-alignment] Resolve conflicting mock requirements in module test guidance #563

[github-actions]

Super-linter summary

Language	Validation result
CHECKOV	Pass ✅
CSS	Pass ✅
CSS_PRETTIER	Pass ✅
GITHUB_ACTIONS	Pass ✅
GITHUB_ACTIONS_ZIZMOR	Pass ✅
GITLEAKS	Pass ✅
GIT_MERGE_CONFLICT_MARKERS	Pass ✅
HTML	Pass ✅
JAVASCRIPT_ES	Pass ✅
JAVASCRIPT_PRETTIER	Pass ✅
MARKDOWN	Pass ✅
NATURAL_LANGUAGE	Pass ✅
POWERSHELL	Pass ✅
PRE_COMMIT	Pass ✅
SPELL_CODESPELL	Pass ✅
TRIVY	Pass ✅
YAML	Pass ✅

All files and directories linted successfully

For more information, see the GitHub Actions workflow run

Powered by Super-linter

[Copilot]

🟢 Approval recommended

No active review issues were identified in this documentation-only clarification of module-development conventions.

No open issues 🎉

What changed in this PR

This documentation-only PR clarifies module-development conventions in the Process-PSModule reference without changing module or pipeline behavior.

Changes:

• Replaces metaphors with direct descriptions of integration modules, transport choices, and Context settings.
• Clarifies conversions through the PowerShell object model while retaining both conversion directions.
• Preserves the previous conversion-section anchor alongside the renamed heading.

File	Description
docs/​content/​reference/​module-types.md	Clarifies integration and data module guidance while preserving technical requirements and anchor compatibility.

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues are reported for these documentation-only clarifications.

No open issues 🎉

_{Review effort: Balanced}