[Marius Storhaug (MariusStorhaug)]

Operations and consumer-upgrade guidance uses direct en-US explanations while retaining the existing requirements, evidence boundaries, and task steps. Release guidance also distinguishes SemVer prerelease precedence from consumer opt-in and applies the existing promotion/rebuild rule consistently. No configuration, product upgrade, or other adoption action is required.

Changed: Operations and upgrade rules have direct explanations

Operators, maintainers, and integrators can read the failure-registration, release-boundary, and upgrade-evidence rules without figurative wording. Consumer Upgrades remains an imperative, six-stage procedure. Its ledger consumes release records without requiring the MSX PR-description format. This changes documentation, not monitoring, release automation, template compatibility, or CI enforcement.

Technical details

Scoped source evidence: MSXOrg/docs base 1b0d4893c8fefabe604d04393068a8ff6f848082; final candidate and remote head afe683b322ab9a19395bd98d1f89a1dda719f3fb. The entire final diff was read, including the parent-review correction. Exactly these three owned paths were read in full and changed; there are no assigned no-change paths:

• src/docs/Ways-of-Working/Observability.md
• src/docs/Ways-of-Working/Continuous-Delivery-And-Release.md
• src/docs/Ways-of-Working/Consumer-Upgrades.md

The draft opened after the first complete observability improvement, fbe708e5d0f1e078378c44ce3f4a35b07dfac4b0. Release clarification followed in aaabee346aa75bb25cde41b2cd367ab843acd6f8, upgrade clarification in 763655532cdd8f50c211340e91543822f135763b, a direct-wording correction in 51a84a4be4b865240822cb0655f65d521c337a9e, and the ledger-boundary correction in the final head. All five small logical commits were pushed.

Actual pinned-baseline wording	Verified final explanation
"A failure that is not captured did not happen"	"An unregistered failure supplies no queryable evidence for investigation or trend analysis."
"operations dashboard bolted on afterwards"	"Observability is a system property, not only a dashboard feature."
"parsing prose is guessing"	"Structured fields let an agent query failure facts directly."
"The pipeline is the same spine every time"	"The automation boundary determines how far a change proceeds without a human decision."
"A version bump alone proves none of those steps."	"A version change alone does not prove that these steps are complete."
"this ledger consumes it rather than defining another release schema"	"The ledger uses those records; it does not define another release schema." PR Format owns MSX release-record authoring, not a required ledger format.
"never copy a template wholesale"	"never copy a template in full"

Preserved meaning: every existing MUST, MUST NOT, and MAY keeps its obligation. Observability retains queryable registration for every failure/error/exception and slow response, the ten-second example, retention sufficient for trends, aggregate counts by kind and component, individual evidence, structured fields, and the free-text restriction. Release guidance retains its four practice boundaries, mainline releasability at all times, all six artifact-type choices, owned-label/default precedence, fail-closed invalid or conflicting inputs, required pre-merge decision validation, opt-in, immutable releases, and roll-forward recovery.

Consumer Upgrades retains actual immutable baseline provenance, fixed target selection, exhaustive pagination, semantic lineage order, complete (baseline, target] evidence, no-action entries, prerelease and roll-up evidence, required intermediate operations, compatible immutable template selection, local ownership, untrusted-source failure boundaries, required validation, and separate review/merge/publication/completion milestones. The floating-alias provenance block, pagination/lineage/no-upgrade blocks, action-composition steps, equivalent-external-evidence paragraph, Stage 5, quality-gate table, and outputs/evidence section remain unchanged against the pinned source.

Test-first evidence: 10 concrete prose expectations failed on the untouched baseline as expected. All 10 refined expectations pass at the final corrected head. Source comparisons preserve all front matter, 29 headings and custom anchors, every link target, inline code, fenced examples, and normative keyword order. Manual before/after review verifies the technical meaning; scans and counts alone do not prove full STE conformance or implemented enforcement.

Parent-review correction: the first ledger wording, "Use that structure for the ledger", could prescribe the PR-description format for the ledger itself. That was an introduced ambiguity, not the pinned contract. The boundary expectation failed on 51a84a4 before correction. The final head explicitly states that PR Format defines MSX release-record authoring and that the ledger uses those records. The refined expectation passes, while required fields/composition and equivalent external evidence remain unchanged. Old-head receipts are not used as proof for this corrected source.

Existing check	Final outcome
npx --no-install markdownlint-cli2 --config .github/linters/.markdown-lint.yml on the three owned pages	Pass; 0 issues; no installation
pwsh .github/scripts/Test-DocumentationLink.ps1	Pass; 130 files
pwsh .github/scripts/Test-CrossRepositoryLink.ps1	Pass on authenticated retry; 7 links across 134 files
pwsh .github/scripts/Invoke-PesterSuite.ps1	Pass; Pester 6.0.1, 66 tests, 6 suites
zensical build --clean from src	Pass locally; installed 0.0.50, not the committed 0.0.59 pin
Corrected-head Docs CI	Lint, Test, Links, and Build pass; PR publication correctly skipped
Pinned CI build	Log confirms successful installation of zensical-0.0.59 and No issues found
Corrected-head cross-repository CI	Pass
Exact scope, source identity, and whitespace checks	Pass; only three owned Markdown pages changed; remote equals candidate; worktree clean

The anonymous cross-repository rerun exhausted GitHub's shared API quota. Repeating the existing checker with existing GitHub authentication passed all seven links. This was an environmental request limit, not a broken link; no credential was written to a file or added to the repository. The successful pinned CI build resolves the local Zensical version limitation without installing dependencies. Generated local site output was removed after inspection. Reference copies and extracted standard text remain local.

Source and path coverage: repository entry points and the fixed Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, and applicable guide/standard/playbook templates were read without changes. The Task records immutable source links, official STEMG overview/FAQ, and consulted local Issue 9 rules and dictionary. Shared indexes, capability pages, PR-format guidance, other process pages, scripts, tests, workflows, configuration, and requirements remain unchanged. No code or test changes overlap #240. Excluded paths are not claimed as writing-audited.

Changed surface	Standards checked	Framework docs checked	Result
Observability.md	Fixed writing sources; standard template; official STEMG explanations and selected local Issue 9 rules	None (no framework-specific docs)	Fixed in this PR
Continuous-Delivery-And-Release.md	Fixed writing sources; standard template; exact identifiers/examples and normative requirements	None (no framework-specific docs)	Fixed in this PR
Consumer-Upgrades.md	Fixed writing sources; guide/playbook templates; all six stage/failure gates; record-versus-format boundary	None (no framework-specific docs)	Fixed in this PR

Task and convergence: source review, before-text verification, all three prose improvements, the parent-review correction, preservation checks, repeated local validation, complete-diff review, standards alignment, and durable evidence are complete. A narrow open-issue title search for Observability, Consumer Upgrades, and Continuous Delivery found no additional matching issue. This PR closes only its scoped Task.

Accepted differences: imperative work steps, exact syntax and identifiers, technical nouns, normative target-state contracts, version-order language, reference titles, external quotations, and existing headings/anchors retain their purpose. This is a scoped STE-informed prose review, not full-conformance certification. No target-state rule is presented as proof of implemented enforcement.

The Docs publication route does not invoke Release Management; no release-decision block, publication-baseline claim, or release:* label applies. The requested app-managed branch name and continued draft state take precedence over the generic handoff procedure. The PR remains draft. Auto-merge and Agent merge are disabled. No unresolved scope blocker or cross-owned repair remains.

Fixed: Prerelease comparisons and stable publication follow the existing contracts

The release explanation compares a prerelease with the stable version that has the same major, minor, and patch numbers. Consumer opt-in remains separate from version precedence. Stable publication follows D1's existing artifact-type decision instead of implying that every prerelease artifact can be promoted unchanged. These are documentation corrections; no release implementation or consumer reference changes.

Technical details

Actual pinned-baseline wording	Verified final explanation
"A promoted artifact behaves like continuous delivery"	"Promotion preserves the artifact that reviewers verified." Rebuild guarantees depend on reproducibility, not on whether deployment is automatic.
"sorts below every stable version"	"has lower precedence than the stable version with the same major, minor, and patch numbers"
"it is the same content with the prerelease suffix removed"	"D1 determines whether the pipeline promotes the artifact or rebuilds it with the stable version."

SemVer sections 9 and 11 establish the associated-version boundary. A native PowerShell SemanticVersion comparison independently confirms 1.2.0 < 1.3.0-add-widgets.1 < 1.3.0. This disproves the baseline every-stable-version explanation. D1 already requires rebuilding version-embedded artifacts; the D3 wording now agrees with that rule. Promotion/rebuild guarantees no longer imply a deployment-automation choice. The three existing version examples remain exact.

Changed surface	Standards checked	Framework docs checked	Result
Release explanations in D1 and D3	Fixed writing sources; SemVer 9/11; existing D1 artifact table and D3 authorization/opt-in requirements	None (no framework-specific docs)	Fixed in this PR

The corrected-head automated review completed with no new inline comments or changes requested. Its source is exactly afe683b322ab9a19395bd98d1f89a1dda719f3fb. No unresolved substantive contradiction remains in the changed explanations.

Related references

• Resolves [documentation-writing-alignment] Clarify operations and consumer upgrade guidance #255

[Copilot]

🟢 Approval recommended

No active review issues are recorded for this documentation-only clarification of the observability guidance.

No open issues 🎉

What changed in this PR

This documentation-only change makes the observability guidance more direct while preserving requirements for queryable failure records, retention, and structured data. It does not change monitoring behavior or enforcement.

Changes:

• Replaces figurative explanations with direct language about failure discovery and investigation.
• Clarifies slow-response registration, trend retention, and aggregate evidence.
• Explains how structured fields support queries without parsing free text.

File	Description
src/​docs/​Ways-of-Working/​Observability.md	Simplifies observability guidance while retaining existing failure-record requirements.

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues are reported for these documentation-only clarifications to the Ways of Working guidance.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues were identified in the documentation-only updates to operational, release, and consumer-upgrade guidance.

No open issues 🎉

_{Review effort: Balanced}