[Marius Storhaug (MariusStorhaug)]

Mission, initiative, principle, and vocabulary guidance uses direct, en-US explanations. Historical research and attributed quotations remain distinct from supported target-state contracts.

The Conventional Commits synopsis describes the existing explicit-label-or-effective-default release decision, independently of commit messages. LTS expands to the canonical Long-Term Support, and pwsh has a version-neutral definition. No release policy, runtime policy, commands, configuration, or integrations change.

Changed: Mission and principle guidance uses direct explanations

The edited explanations in the 18 assigned pages and exclusively transferred abbreviation include state the existing intent without promotional comparisons or unclear metaphors. The mission, principle meaning, technical contracts, attributed quotations, historical models, titles, headings, and anchors remain intact. Necessary instructions remain direct.

The reference pages identify their sources rather than claiming delivery or enforcement. The 2025 tool examples remain a dated snapshot, not support guarantees. The four-metric DORA table and thresholds remain exact historical data. Source-supported Dojo curriculum descriptions replace unsupported activity and absence judgments.

Before	After
Safe without fast is paralysis.	Safety without timely delivery prevents progress.
Fast without easy burns people out.	Speed without ease increases workload.
Go see the answers	The Initiatives describe how products apply these principles.
Work like a zipper	Each structural step makes the next change easier.
sets it on hyper-speed	A direct explanation of small experiments and frequent feedback.
Don't build for tomorrow's requirements	Do not implement a requirement before the current deliverable needs it (YAGNI).
This ecosystem derives the bump from a pull-request label instead	A reviewed PR's explicit bump label overrides a valid effective DefaultBump; without that label, the valid default supplies the bump. Commit messages do not select it.
*[LTS]: Long-Term Servicing	*[LTS]: Long-Term Support
*[pwsh]: PowerShell Core (also known as PowerShell 7)	*[pwsh]: PowerShell command-line interface

Technical details

Immutable delivery evidence

• Native Task: MSXOrg/docs#263, with canonical context, acceptance criteria, technical decisions, test-first plan, source links, and audit comments.
• Fixed baseline: 1b0d4893c8fefabe604d04393068a8ff6f848082.
• Final head: 7f19e88045ee50d2e26a39387f44602961deaf90.
• Scoped comparison: exactly 19 Markdown sources, 273 insertions, 259 deletions, eleven small pushed commits. Local and remote heads match; worktree clean. This is PR evidence, not a release-publication range.
• The draft opened immediately after the first complete, verified Vision improvement at 0a545c1cd379d68d0b1285f615895909da482a52. All remaining changes finish in this same Task and PR.

Complete owned read/change manifest

All 19 sources are fully read, including front matter, handwritten indexes, citations, bibliography, tables, diagrams, and quotations where present. Every assigned source changes; there is no unchanged assigned source. The Task also contains the complete read-only supporting-path manifest and per-source before/after examples.

Read and changed path	Delivered scope
src\docs\Vision\index.md	Mission explanations and initiative navigation; exact mission and decision questions retained.
src\docs\Initiatives\index.md	Roles, inheritance, and target-state/evidence distinction; generated block retained.
src\docs\Initiatives\AzActions.md	Direct Azure initiative description.
src\docs\Initiatives\PSModule.md	Framework introduction; audience, settings, and canonical boundary unchanged.
src\docs\Initiatives\TFActions.md	Direct Terraform description and unchanged approval requirement.
src\docs\Initiatives\VS-Code-Extensions.md	Direct editor-tool explanation.
src\docs\Dictionary\index.md	Introduction and source-settled Conventional Commits release synopsis; all other definitions and native examples exact.
src\docs\Ways-of-Working\Principles\index.md	Principle explanations; normative obligations and generated block retained.
src\docs\Ways-of-Working\Principles\AI-First-Development.md	Agent participation, deterministic-tool priority, shared context, and review explanations.
src\docs\Ways-of-Working\Principles\Engineering-Practices.md	Shared records, target-state documentation, diagnosis, local validation, and fleet rationale.
src\docs\Ways-of-Working\Principles\Planning-and-Delivery.md	Small increments and feedback; present-need constraint, matrix, and quantities retained.
src\docs\Ways-of-Working\Principles\Purpose-and-Direction.md	Product and least-privilege explanations; mission mapping and cross-platform MUSTs retained.
src\docs\Ways-of-Working\Principles\References.md	Source introduction and Lean synopsis; titles/authors/citations retained.
src\docs\Ways-of-Working\Principles\Software-Design.md	API, default, security, and structural-preparation explanations; SOLID definitions and thresholds retained.
src\docs\Ways-of-Working\Continuous-Practices.md	Source-bound taxonomy, examples, historical snapshot, and reference descriptions.
src\docs\Ways-of-Working\DevOps-Reference.md	Stable explanations and historical DORA scope; bibliography and operational thresholds retained.
src\docs\Ways-of-Working\Engineering-Taste.md	Judgment, trade-off, and current-deliverable guidance.
src\docs\Ways-of-Working\Evolutionary-Development.md	Experiment/feedback method; diagrams, signal definitions, test-first sequence, and decision gates retained.
src\includes\abbreviations.md	Only pwsh and LTS expansions differ from baseline; all 63 keys, native syntax, and other lines retained.

Source-settled factual definitions

These two corrections are settled by existing sources, not new policy choices. Both added guards fail before editing (0/2) and pass afterward (2/2). The correction commit changes only the authorized release synopsis and LTS line relative to the prior verified writing head d272d8d0a36e7dad1c3c9632c43c372324c60134.

Fixed Release Management FR1 and PR Format explicitly permit a valid effective default without a per-PR bump label. The Dictionary now states the explicit-label override, no-label valid-default path, and commit-message independence, and links to the owning rule. No bump/default value, precedence, failure boundary, or policy changes. The general Conventional Commits definition and feat(api): add pagination example remain exact.

The unchanged fixed Dictionary LTS entry supplies the canonical shared term. A tracked-tree search finds only Node Active LTS, PowerShell 7 LTS, general supported runtimes, the Dictionary entry, and the inconsistent expansion. The official Node.js release page explicitly uses long-term support. The official PowerShell lifecycle page uses product-specific Long Term Servicing wording; that publisher wording is not misrepresented as a universal expansion. The shared include follows MSX's existing canonical Dictionary and changes no supported-runtime policy.

The official about_Pwsh and immutable MicrosoftDocs source 9fc54e7fc4954f7b4af134def74ba8e8cac7e23c support the retained version-neutral pwsh definition.

Writing criteria and reference sources

Criteria were derived before judging the owned pages from fixed-baseline Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and applicable reference/standard templates. The Task links each immutable source. The official STEMG overview, FAQ, and relevant local Issue 9 rule details support the review. The verified PDF MD5 is 9c720341c350ed77943b2c73d01c716f. No copy or extract is republished. Automated scans and word counts do not establish full STE conformance.

Reference checks use GitHub Next Continuous AI, the Microsoft Learn Dojo path, Dojo introduction, ISE Playbook, DORA guide, DORA history, and Thoughtworks Radar. Retained bibliography and historical notes are not presented as a complete new historical verification.

Validation and review

Check	Result at the final head
Prose and factual guards	19/19 per-source examples, both present-need guards, and 2/2 settled-definition guards pass. Guards fail before their corresponding corrections.
Scope and protected content	Exactly 19 assigned sources change. Both submitted generated INDEX blocks are byte-identical to baseline. Titles, headings, anchors, diagrams, other controlled definitions, native examples, module contracts, source quotations, matrix, bibliography, dated tool names, and operational thresholds remain intact. The accepted authored admonition is unchanged from the prior verified head; no blanket quotation assertion restores it.
Metadata	All 18 page title/description mappings parse as strings.
Markdown lint	Existing configuration and explicit 19-source manifest: 0 issues.
Relative links/anchors	Existing checker passes for 130 documentation files, including the added canonical release-rule link.
Cross-repository links	Existing checker passes for seven links in 134 Markdown files using documented API rate-limit headroom. The owned-only empty-check guard remains an expected exit 1, not a pass.
Pester	Final-head CI passes 66 tests in six suites using the existing Pester 6.0.1 runner. No code or test changes.
Native abbreviation rendering	An anonymous LTS pwsh sample renders Long-Term Support and PowerShell command-line interface with both keys unchanged.
Generated site	Exact-head temporary export passes generation and -Check; existing local Zensical 0.0.50 builds exactly 130 pages with no issues. The pinned Zensical 0.0.59 CI build passes. No local dependency install; named build artifacts are removed.
Final-head CI	Docs: Lint, Build, Links, and Test succeed; Publish is skipped. Cross-repository links succeeds. All reported lint statuses, including NATURAL_LANGUAGE, succeed.
Issue convergence	The scoped campaign/principles/vocabulary/pwsh searches identify no additional fully convergent issue; no other campaign Task is closed.
Automated review	The fresh factual-correction review approves exact head 7f19e88045ee50d2e26a39387f44602961deaf90 at 2026-11-04T13:53:13Z, with zero new inline comments. The complete thread query confirms zero unresolved threads.

The first writing review finds a valid YAGNI regression: an established Later requirement is not necessarily needed by the current deliverable. The stronger guards fail before correction; the fix is propagated to Planning and Delivery and Engineering Taste. Its discussion is explained and resolved. CI also identifies an unquoted colon and two terminology defects introduced during editing; each is fixed in a small commit. The cached local textlint does not execute this repository's rules and is not counted as a pass; successful CI NATURAL_LANGUAGE supplies that evidence. No configuration or tooling workaround is added.

Standards and framework alignment

Changed surface	Standards checked	Framework or domain evidence	Result
Vision and initiatives	Fixed writing sources, Documentation Model, Markdown, Natural Language	PSModule audience/settings/boundary verified unchanged	Fixed in this PR
Principles, Engineering Taste, Evolutionary Development	Fixed writing sources, standard template, existing contracts	None (no framework-specific docs)	Fixed in this PR
Dictionary and abbreviation include	Fixed writing sources, reference template, native syntax	Fixed FR1/PR Format, canonical LTS, official runtime sources	Fixed in this PR
Continuous Practices and DevOps Reference	Fixed writing sources, reference template	Relevant cited source descriptions	Fixed in this PR

Accepted differences and exclusions

Necessary imperatives, normative contracts, technical syntax, official titles, quotations, historical years, and generated output retain their purpose. The authored Evolutionary Development self-directed-update admonition is not an external quotation; its directive force is preserved and the accepted wording is not restored to the old long prose.

Only four policy/legacy-heading questions remain separate: AI-first's the docs are wrong mismatch rule versus diagnosis of either intent or implementation; How-to-Mission mapping versus Vision's mission-as-why; no-downward-normative-links versus the Testing-standard ownership link; and the protected eight-pillars heading versus Microsoft's eight-capability/four-foundation terminology. LTS and the Conventional Commits release synopsis are source-settled factual corrections completed here, not deferred policy choices.

Former Dojo activity/absence and replacement claims are preserved as before-text evidence in the Task and immutable baseline, not asserted as present-day facts. The intentional historical narrative and dated tool snapshot remain in the page.

All other tracked paths remain unchanged. Other owners' pages, shared indexes, agent pointers, src\includes\links.md, executable code, tests, configuration, dependencies, enforcement, and restructuring are excluded. #240 code and tests are untouched. No heading or anchor repair is needed. The missing parent-directory AGENTS.md link is not repaired; the actual repository AGENTS.md and required read order are followed.

The route builds Zensical and deploys GitHub Pages; it does not invoke Release Management. No release metadata or release:* label applies. No versioned producer/template interface changes. No blocker remains for the assigned draft deliverable. This PR remains draft, with auto_merge: null; mark-ready, merge, auto-merge, and Agent merge are excluded.

Related references

• Resolves [documentation-writing-alignment] Clarify mission, principles, and vocabulary #263
• References Keep documentation tooling tests focused on supported behavior #240 (excluded code/test ownership)

[Copilot]

🟡 Changes recommended

The revised YAGNI wording drops the present-need constraint, allowing established future requirements to justify premature implementation and changing the principle rather than merely clarifying it.

1 open issue

• Preserve the present-need constraint in YAGNI wording · New

What changed in this PR

This documentation-only PR clarifies the MSX mission, initiatives, principles, and shared vocabulary with direct, en-US language. It updates guidance without changing executable code, configuration, or enforcement.

Changes:

• Replaces promotional language and metaphors with concrete explanations.
• Distinguishes target-state contracts from implementation evidence and historical reference material.
• Defines pwsh as the PowerShell command-line interface without tying it to a version.

File	Description
src/​includes/​abbreviations.md	Makes the pwsh definition version-neutral.
src/​docs/​Ways-of-Working/​Principles/​Software-Design.md	Clarifies API, default, security, and design guidance.
src/​docs/​Ways-of-Working/​Principles/​References.md	Simplifies the source introduction and Lean synopsis.
src/​docs/​Ways-of-Working/​Principles/​Purpose-and-Direction.md	Clarifies product purpose, audience, and least privilege.
src/​docs/​Ways-of-Working/​Principles/​Planning-and-Delivery.md	Revises small-deliverable and feedback guidance.
src/​docs/​Ways-of-Working/​Principles/​index.md	Explains principle ownership and reference direction.
src/​docs/​Ways-of-Working/​Principles/​Engineering-Practices.md	Clarifies shared records, target-state contracts, and validation.
src/​docs/​Ways-of-Working/​Principles/​AI-First-Development.md	Clarifies agent participation, deterministic tools, and review responsibilities.
src/​docs/​Ways-of-Working/​Evolutionary-Development.md	Explains experimentation, feedback cycles, and decision gates directly.
src/​docs/​Ways-of-Working/​Engineering-Taste.md	Makes judgment and trade-off guidance more concrete.
src/​docs/​Ways-of-Working/​DevOps-Reference.md	Clarifies reference descriptions and historical DORA scope.
src/​docs/​Ways-of-Working/​Continuous-Practices.md	Adds source context and qualifies historical tool examples.
src/​docs/​Vision/​index.md	Clarifies mission explanations and initiative navigation.
src/​docs/​Initiatives/​VS-Code-Extensions.md	Describes the editor tools directly.
src/​docs/​Initiatives/​TFActions.md	Clarifies Terraform automation and approval guidance.
src/​docs/​Initiatives/​PSModule.md	Describes the framework and canonical documentation boundary.
src/​docs/​Initiatives/​index.md	Clarifies initiative roles, inheritance, and target-state scope.
src/​docs/​Initiatives/​AzActions.md	Describes Azure automation and shared standards directly.
src/​docs/​Dictionary/​index.md	Simplifies the introduction without changing definitions.

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues block the documentation-only clarifications.

No open issues 🎉

1 resolved since last review

• Preserve the present-need constraint in YAGNI wording

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues block these documentation clarifications.

No open issues 🎉

_{Review effort: Balanced}