[documentation-writing-alignment] State framework contracts without vague or unverified claims #562

Context and request

Framework maintainers need precise specification and reference prose. This delivery owns released grammar, en-US spelling and shorter descriptive prose, not whole files or proposal contracts.

Exact source and region handback

The verified main source is 64ffb1d87f86bd5d487891fdb140b78385a00531. The integration coordinator releases linguistic edits in the four docs/content/specification/*.md pages and these references: powershell-module-standard.md, repository-standard.md, scenario-matrix.md, settings.md, versioning.md, and workflow-inputs.md. Descriptions may become shorter and more direct; behaviour becomes behavior outside literal tokens/quotations.

The actual #541 coordinating parent separately releases existing prose in docs/content/reference/pipeline-stages.md, including artifact-root explanations only where present in the selected main source. Preserve its headings/anchors, exact stage names, <WorkingDirectory>/.PSModule/ and every listed artifact path, code/examples, inputs/defaults, roles, publication/recovery guarantees, dependency order, runner-only exceptions, artifact behavior and all proposal decisions. Do not import a proposal-only section or change #541 or its owner branch.

In reference/versioning.md, the rhetorical no risk promise may express intended compatibility rather than an absolute guarantee, without changing SemVer policy. Requirements retain their modality, IDs/anchors, supported roles, examples, compatibility classifications, inputs/defaults and publication/recovery guarantees. A requirement is not evidence that CI enforces it.

Protected and split scope

The API-fingerprint automation section in reference/versioning.md, blob ee2eafdd83405ab42da7a25aa5f6e9ff367e6d5e, lines 127-155, and related unsupported automation claims are protected. Their factual conformance to the real settings/label resolver versus an approved implemented fingerprint mechanism belongs to #577, with #359 / #524 as the owning producer context. Neither shorter wording nor future-to-present substitution supplies that proof.

The mocked-environment requirements and the core-only-major policy passages remain unchanged. #563 and #573 retain those separate decisions. Preserve exact external quotations, legal text, identifiers, examples, links, requirement force and compatibility policy. No runtime, framework, site-design, release-decision, merge or lifecycle change is authorized. Do not wake/amend held proposal branches or import unmatched/new proposal-only files.

Evidence and acceptance criteria

The design uses behaviour and sensible defaults; principles use long first-person explanations; versioning promises patch updates with no risk. The earlier review read all eleven pages and recorded those phrases. Use the fixed Documentation Model, Natural Language, Writing Guide and applicable spec/design/reference/standard templates.

• Every page has a full changed/no-change/protected review with concrete before/after evidence.
• Released prose is concise, direct en-US and present-tense; necessary procedures stay imperative.
• Modality, requirement IDs, headings/anchors, code/examples, interface values, source links, quotations and all protected passage text remain exact or unchanged in meaning as explicitly allowed.
• No descriptive change invents shipping, automation, enforcement, compatibility or publication behavior.
• One fresh-main focused draft PR records small commits and existing Markdown/link/site checks. No new enforcement tool, dependency or repository prose/implementation snapshot test is added.

Implementation plan

• Verify the integration handback and independent pipeline-page handback; split fingerprint conformance into [documentation-writing-alignment] Reconcile API-fingerprint versioning claims with the resolver #577.
• Read all eleven pages and source rules; mark protected text and establish before/after expectations before editing.
• Establish existing checks and one-off protected passage/token/example/anchor baselines.
• Make only released linguistic corrections in small commits and open the focused draft PR early.
• Recheck source and ownership before each commit; incidental line movement is not a meaning conflict.
• Verify all requirements, contracts, protected text, examples, anchors and existing checks; record acceptance evidence and keep the PR draft.

Delivery evidence

Draft PSModule/Process-PSModule#580 is pushed at b8a2e4ff2056409f89289a3209f5b08c3ad42031 on framework-contract-prose, with base main at 64ffb1d87f86bd5d487891fdb140b78385a00531. It opened after the first real slice, 9ba4a606ca4a6aa2e460b8e994c9fdc9eff82631, followed by three small commits. All eleven pages are reviewed: nine changed and two whole-page no-change reviews. The PR contains the complete source-cited before/after table, exact scope, protected-region results, commands, and residual decisions. The coordinating parent accepted the exact current head after independent content review. All applicable hosted checks pass, and Copilot approved that head without inline comments. These results do not authorize a draft, lifecycle, or merge-state change.

Before repository edits, all eleven released pages and the fixed MSX writing sources were read in full. The official STE overview and FAQ were read; Issue 9 rules 3.2, 3.6, 4.1-4.2, and 6.1-6.6 were consulted through the locally retained official PDF/text. Its MD5 is 9c720341c350ed77943b2c73d01c716f, matching the official record. These checks do not certify full ASD-STE100 conformance.

Concrete original/expected wording is recorded before edits in session evidence. Nine page-level wording cases fail on the original source; the specification and scenario matrix are intentional no-change reviews. Examples include behaviour to behavior, first-person linear-versioning prose to a latest-only declarative statement with the same 2.1.3/1.x example, the missing verb connection in report descriptions, and the explicitly released no risk promise to intended compatibility.

The one-off session baseline covers 120 headings, 11 explicit anchors, 11 requirement IDs, 144 requirement-modal tokens, 652 inline-code spans, 22 fenced examples, 134 link targets, 269 numeric literals, 233 table rows, 148 bold labels, seven quotation spans, rendered anchor/link sets, and 13 protected policy/automation/contract passages. The main pipeline page has no Consumer artifact root section or <WorkingDirectory>/.PSModule/ token; neither is imported.

Existing checks pass before edits: explicit eleven-file markdownlint-cli2 with .github/linters/.markdown-lint.yml reports 11 files and 0 issues; zensical build --clean from docs reports no issues. No standalone documentation-link checker is present in this main tree; the MSX repository's named link scripts are not installed here. No dependency was installed. No repository test, enforcement tool, inventory, or audit document is added.

Completed current-head evidence

The complete base-to-head diff is nine Markdown files, 47 insertions and 51 deletions. The changed pages are specification index.md, design.md, and principles-and-practices.md; reference pipeline-stages.md, powershell-module-standard.md, repository-standard.md, settings.md, versioning.md, and workflow-inputs.md. specification/spec.md and reference/scenario-matrix.md are unchanged in full. Their base/head Git blobs are respectively 5755abf2797a699e0ef0846ac2521cb1fb90b2bb and d9c5490f5379fe94adf94df6ac349dfc0b82b8d1.

At exact pushed head b8a2e4ff2056409f89289a3209f5b08c3ad42031, all eleven wording cases pass and the one-off preservation comparison reports zero failures. All source counts above are preserved exactly. Another 43 example-bearing paragraphs remain exact; the three narrative examples in principles use shorter prose with the same scenarios and literal tokens. All 317 rendered anchor IDs and 1,055 rendered link targets across the eleven built pages match the pre-edit site baseline. This proves preservation, not external-link reachability or full STE conformance.

All 13 protected policy/automation/contract passages remain text-exact after line-ending normalization. They cover public-API major policy, latest-only maintenance/support, fingerprint implementation and related claims, mocked-environment and boundary-mock requirements, version resolution/publication, the pipeline runtime contract, root-only test phases/discovery, generated-code coverage, and stable publication/cleanup. The fingerprint section's SHA-256 remains fb098e0eea00a129b7f87f13806acc104de6ad47439769355d2d2c8fcf824e23. A hunk-by-hunk review preserves roles, compatibility classifications, inputs/defaults, publication/recovery guarantees, dependency order, runner-only exceptions, procedures, quotations, attribution, and every literal example. No requirement becomes a claim of implemented enforcement.

The existing explicit eleven-file npx --no-install markdownlint-cli2 --config .github/linters/.markdown-lint.yml ... command reports 11 files and 0 issues. The existing zensical build --clean command from docs reports no issues. git diff --check 64ffb1d87f86bd5d487891fdb140b78385a00531 HEAD passes. The full copyable commands and output limits are in the PR evidence. The worktree is clean and local/remote head identities match. No dependency, new repository checker/test, audit document, runtime change, or site redesign is introduced.

Main and live handbacks were rechecked before all four commits. #541 remains at 2001551566898e59efc764e68450c2238667d607; no proposal or first-pass PR is amended. A scoped open-issue convergence search finds no additional issue fully satisfied by this linguistic delivery. Only this leaf is linked to close after eventual merge. #577, #563, and #573 remain non-closing, with #359/#524 as fingerprint producer context.

The draft is not marked ready, merged, or placed under auto-merge/Agent merge. All six applicable hosted checks succeed at the exact candidate: Docs Build and Lint, repository Lint code base, CodeQL, Actions analysis, and Copilot review. Publication is skipped as expected. The explicitly requested Copilot review is APPROVED at b8a2e4ff2056409f89289a3209f5b08c3ad42031, with no inline comments or active issues. Docs, repository lint, and hosted review retain those results. The coordinating parent accepted content at b8a2e4ff2056409f89289a3209f5b08c3ad42031 after reading all nine changed-page diffs and independently comparing all eleven pages. Its comparison preserves headings, inline literals, destinations, fences, table rows, modality sequences, fingerprint/related automation text, and mocked-environment requirements. This issue remains open until the draft is eventually approved for merge and merged.