[documentation-writing-alignment] Clarify mission, principles, and vocabulary #263

Context and request

Readers and agents need direct, precise, en-US explanations of the MSX mission, initiatives, principles, and shared vocabulary. This delivery leaf aligns the 19 Markdown sources below with the existing writing contract. It changes guidance, not the mission, values, principles, product implementations, or enforcement.

The campaign request is to use ASD-STE100 writing practices and make resource documentation evergreen, declarative, and definitive. The review baseline is immutable commit 1b0d4893c8fefabe604d04393068a8ff6f848082. The worktree starts clean at that commit. No repository-local issue template exists in .github/ISSUE_TEMPLATE/ or .github/ISSUE_TEMPLATE.md; this body follows the canonical Issue Format and Task format.

Observable acceptance criteria

1. All 19 assigned Markdown sources have a complete review, including front matter, handwritten index prose, citations, tables, diagrams, and quotations. The delivery evidence identifies changed and unchanged paths.
2. Explanatory prose uses concrete nouns, explicit actors, active voice, short sentences, and en-US spelling. For example, Vision describes the interaction of easy, fast, and safe without the phrases paralysis or burns people out, and replaces Go see the answers with an explicit description of the linked initiatives.
3. Resource prose describes the supported target state. It does not claim that a product, control, CI enforcement, or measured result exists merely because a normative document requires it. Relative activity judgments and forecasts are replaced only by source-supported descriptions or recorded as unresolved observations.
4. The mission text, values, principle meaning, normative force, official titles, all other technical-noun definitions, attributed quotations, historical evidence, identifiers, examples, page paths, headings, and anchors remain intact. Necessary instructions remain direct. Generated INDEX:START/INDEX:END blocks remain byte-for-byte unchanged in the submitted sources.
5. The 19 concrete prose-verification examples fail before their corresponding edits and pass after editing. Structural comparison against the baseline confirms protected content. Existing Markdown, relative-link, cross-repository-link, Pester, and site checks have explicit results, including exclusions and any failures.
6. One focused draft PR implements this Task through small commits. The final evidence contains issue/PR URLs, the immutable final head SHA, source links, concrete before/after examples, the full path manifest, accepted differences, contradictions, and blockers. The PR remains draft; no merge, auto-merge, or Agent merge is enabled.

Owned paths

• src\docs\Vision\index.md

• src\docs\Initiatives\index.md

• src\docs\Initiatives\AzActions.md

• src\docs\Initiatives\PSModule.md

• src\docs\Initiatives\TFActions.md

• src\docs\Initiatives\VS-Code-Extensions.md

• src\docs\Dictionary\index.md

• src\docs\Ways-of-Working\Principles\index.md

• src\docs\Ways-of-Working\Principles\AI-First-Development.md

• src\docs\Ways-of-Working\Principles\Engineering-Practices.md

• src\docs\Ways-of-Working\Principles\Planning-and-Delivery.md

• src\docs\Ways-of-Working\Principles\Purpose-and-Direction.md

• src\docs\Ways-of-Working\Principles\References.md

• src\docs\Ways-of-Working\Principles\Software-Design.md

• src\docs\Ways-of-Working\Continuous-Practices.md

• src\docs\Ways-of-Working\DevOps-Reference.md

• src\docs\Ways-of-Working\Engineering-Taste.md

• src\docs\Ways-of-Working\Evolutionary-Development.md

• src\includes\abbreviations.md (exclusive vocabulary-source extension from the coordinator)

Actual before-text and source evidence

Technical decisions

Sourced review criteria

Derive the criteria before judging the assigned pages. The six baseline sources are Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and the applicable reference/standard artifact templates. Their contents match the clean worktree baseline.

Read the official STEMG overview and FAQ. Consult the verified local Issue 9 copy for rule details. The PDF MD5 is 9c720341c350ed77943b2c73d01c716f. The relevant rule summaries cover active voice, short clear sentences, direct procedural instructions, and one-topic descriptive paragraphs. Technical terms retain their subject-specific meaning. No reference copy or extract is republished. Word counts and automated scans do not establish full STE conformance.

Implementation and compatibility

Edit only the owned prose. Preserve headings and anchors even when their wording is not ideal. Retain the existing page structure and the distinct purposes of mission explanations, principles, vocabulary, and reference material. Use front-matter descriptions and handwritten prose as the source; do not hand-edit or commit generated index tables. No commands, diagrams, SOLID definitions, supported module settings, or examples change. The source-settled Conventional Commits synopsis and LTS abbreviation corrections below are the only additional controlled-term exceptions.

Keep direct instructions where they communicate an action. Preserve each existing MUST, SHOULD, MAY, prohibition, threshold, scope, and exception. Describe initiatives as their target-state roles rather than proof of deployed behavior. Source-supported historical models remain historical references, not invented present-day product facts.

The official GitHub Next Continuous AI page supports the definition, quotations, taxonomy, and workflow examples. The Microsoft Learn Dojo path lists six modules and eight capabilities; the Dojo introduction describes the four foundations and belt model. These sources do not prove present-day dormancy, curriculum absence, or staffing. The ISE Playbook supplies an engineering reference, not proof that it replaces Dojo. The DORA metrics history distinguishes the 2021 reliability measure from software delivery performance and documents the later five-metric model. Preserve the existing four-metric table and thresholds as historical reference data; link to the authoritative evolving model rather than redefining technical terms in this writing change.

Additional vocabulary source

The coordinator releases src\includes\abbreviations.md exclusively to this Task. The full include is reviewed. Its actual before-text is *[pwsh]: PowerShell Core (also known as PowerShell 7). The accepted replacement is *[pwsh]: PowerShell command-line interface. The key and native include syntax remain exact. Apart from the separately authorized LTS correction below, every other abbreviation line remains unchanged. The other shared include, src\includes\links.md, remains coordinator-owned and unchanged.

The official about_Pwsh short description identifies pwsh as the command-line interface. Its page metadata identifies immutable MicrosoftDocs/PowerShell-Docs source 9fc54e7fc4954f7b4af134def74ba8e8cac7e23c. This supports a version-neutral factual definition, not a change to the executable or supported runtime policy. The review count is 19 Markdown sources. The eighteenth-page baseline results above remain historical results; the additional one-line acceptance example is recorded and fails before its correction.

Reference-source verification

The reference edit retains both GitHub Next quotations verbatim, bibliographic titles/authors/years, dated method origins, the Dojo History paragraph (with only en-US spelling), the 2025 tool-name snapshot, the exact four-metric DORA table, and every listed operational threshold. The dated tool table is explicitly illustrative and does not claim present support or availability.

The baseline activity statements GitHub org quiet since late 2022 and sparse, last meaningful activity Oct 2022, the claim never published, and the comparison The de facto modern equivalent are retained here as before-text evidence with the immutable baseline source. They are not verified present-day facts. The page instead identifies the available Microsoft Learn path, linked belt descriptions, public GitHub organization, and distinct ISE Playbook purpose. This preserves historical evidence in the delivery record without converting a dated observation or unsupported absence claim into current product guidance.

The Thoughtworks Technology Radar describes a twice-yearly snapshot, which contradicts this page's before-text Quarterly opinionated assessment. The replacement states its stable purpose as an opinionated guide to the technology landscape, without adding another cadence promise. DORA's authoritative history supports the distinction between historical delivery metrics and operational reliability; no metric definition or threshold is rewritten.

Source-settled definition corrections

The coordinator confirms two factual corrections in this same Task and PR. They are settled by existing sources, not new policy choices. The other four policy/legacy-heading questions remain separate. The authored Evolutionary Development admonition retains its accepted directive force and is not restored as if it were an external quotation.

Fixed Release Management FR1 and PR Format explicitly permit the valid effective default without a per-PR bump label. FR1 also keeps invalid inputs as errors and makes the decision independent of commit-message syntax. These source contracts and all bump/default policy remain unchanged.

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

Before editing, both new definition guards fail (0/2): the no-label valid-default path is missing from the synopsis, and the LTS expansion disagrees with the canonical term. The native Conventional Commits example, all other definitions, all 63 abbreviation keys, and all other abbreviation lines are protected. The final candidate, existing checks, and current-head Copilot review will be refreshed.

Accepted differences and exclusions

• Preserve the exact mission, philosophical questions, principle headings, book/product titles, quotations, historical publication years, 2025 tool-example snapshot, and native technical vocabulary.
• Preserve all Dictionary definitions except the source-settled Conventional Commits release-decision synopsis. Its general definition and native example remain exact. The LTS abbreviation follows the existing canonical Dictionary term; no release or runtime policy changes.
• Necessary imperatives, normative target-state contracts, technical syntax, diagrams, and generated output are accepted differences from ordinary descriptive prose.
• Other pages, shared indexes, agent pointers, other includes, executable code, tests, configuration, tooling, dependencies, enforcement, and restructuring are excluded. In particular, do not edit the code or tests owned by MSXOrg/docs#240.
• The app-provided feature branch and requested session-name branch rename are accepted; no second branch or worktree is created.
• This delivery deliberately stops at a draft PR. General mark-ready and auto-merge instructions do not apply to this campaign's explicit handoff.

Substantive contradictions and evidence limits

1. AI-first context-first development says If the docs and the code disagree, the docs are wrong. Engineering practices says either can be wrong and requires diagnosis. Preserve both obligations and report the policy conflict; do not choose a new authority rule.
2. Purpose and direction maps How to Mission, while Vision presents the mission as why MSX exists. Preserve the mission and existing mapping; do not redefine either.
3. The no-downward-normative-links rule coexists with the Testing-standard ownership link. Preserve the link and flag the boundary question; no anchor repair or hierarchy change is authorized.
4. The Continuous Practices heading calls the eight items pillars, while the cited Microsoft Learn path distinguishes eight capabilities from four foundation pillars. Keep the heading/anchor and clarify the explanation. Do not invent a replacement taxonomy or rename the section.
5. DORA's linked history explicitly corrects the 2021 report's fifth-metric wording. Retain attributed historical data, clarify its scope, and do not present the four-metric reference table as the complete present-day DORA model.

Implementation plan

• Read the repository entry instructions and fixed writing sources; derive criteria; review all 18 owned pages fully, including citations and handwritten indexes.

• Record 18 exact before/expected-after prose examples before editing. Run them against the baseline: 0/18 pass, the expected red result. Establish protected-content invariants against the same immutable baseline.

• Improve Vision explanations, verify the first complete result and protected mission/anchors, commit, push, and open the focused draft PR immediately.

• Verify the initiative and Dictionary before-text against the prose examples before implementation.

• Improve initiative descriptions and the Dictionary introduction; keep every term definition and supported module contract intact; verify, commit, and push.

• Verify the Principles index, AI-first, and engineering-practices before-text before implementation.

• Improve those explanations without resolving the recorded authority conflict or changing normative force; verify, commit, and push.

• Verify the purpose, planning, software-design, and reference before-text before implementation.

• Improve those explanations; retain definitions, quantities, titles, quotations, and policy mappings; verify, commit, and push.

• Verify Engineering Taste and Evolutionary Development before-text before implementation.

• Improve engineering-judgment and evolutionary-development explanations without changing the feedback method, decision gates, or test-first obligations; verify, commit, and push.

• Verify Continuous Practices and DevOps Reference before-text and authoritative citations before implementation.

• Improve the two reference pages; preserve historical evidence, attributed quotations, technical definitions, and thresholds; distinguish source facts from unsupported status claims; verify, commit, and push.

• Read the abbreviation include fully and verify the official current description and immutable source; establish the failing one-line acceptance example before editing.

• Correct only the pwsh expansion, verify all other abbreviation lines and native syntax are unchanged, commit, and push.

• Re-run the 19 acceptance examples and structural invariants, existing Markdown/link/Pester/site checks, scoped issue-convergence search, and the standards alignment pass. Publish the final path/evidence report in the issue and draft PR; report immutable identities and remaining gaps to the coordinator.

• Verify fixed FR1/PR Format, canonical Dictionary LTS, tracked runtime contexts, and official terminology; establish 0/2 failing definition guards before edits.

• Correct only the Conventional Commits release synopsis and LTS expansion; preserve all other controlled text and syntax; verify, commit, and push.

• Refresh exact-head protection checks, Markdown/links/site checks, CI, and clean review; update Task/PR evidence and report the new head to the coordinator.

Validation notes

Delivery identity

The delivery record is MSXOrg/docs#263, native type Task. The focused draft is MSXOrg/docs#273.

The immutable review baseline is 1b0d4893c8fefabe604d04393068a8ff6f848082. The candidate is 7f19e88045ee50d2e26a39387f44602961deaf90. The scoped comparison contains exactly 19 Markdown sources, 273 insertions, and 259 deletions. Eleven small commits are pushed. The worktree is clean.

The draft opened after the first complete, verified Vision improvement at 0a545c1cd379d68d0b1285f615895909da482a52. The remaining improvements finish in the same Task and PR. The PR remains draft, auto_merge is null, and no mark-ready, merge, or Agent merge action is performed. The GitHub Task stays open for the later review and merge lifecycle.

Complete owned read/change manifest and acceptance examples

All 18 assigned pages and the exclusively transferred abbreviation include have a complete read. This includes front matter, handwritten index prose, citations, bibliography, tables, diagrams, and quotations where present. Every source below changes. There is no unchanged assigned source.

The first 18 acceptance examples fail against the immutable baseline before editing. The additional abbreviation example fails before its one-line correction. All 19 pass against the committed candidate. The table gives the actual before-text and required after-text used in those repeatable comparisons.

The prose examples above display rendered words; the comparisons retain the source's link and emphasis syntax. Additional Vision evidence replaces Safe without fast is paralysis. with Safety without timely delivery prevents progress. and Fast without easy burns people out. with Speed without ease increases workload. The mission statement and decision questions remain exact.

Source-settled factual corrections

The coordinator confirms the following two facts from existing canonical sources. They are corrected in this same Task and PR, not deferred as new policy choices. Both added guards fail before editing (0/2) and pass after editing (2/2).

Fixed Release Management FR1 and PR Format explicitly permit a valid effective default without a per-PR bump label. The Dictionary links to the owning release rule. No bump/default value, precedence, failure boundary, or commit-message policy changes.

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

Protected content and no-change evidence

The committed comparison confirms that both owned generated INDEX blocks are byte-identical to the baseline. All titles, headings, anchors, fenced diagrams, inline identifiers, and uppercase normative terms retain their source identity and order.

Exact protected sections include all other Dictionary term definitions, the SOLID definitions, the integration/sensoring definitions, the four signal definitions, the planning matrix, PSModule audience/settings/canonical-boundary content, attributed quotations, bibliography titles/authors/years, dated tool names, the four-metric DORA table, and the listed operational thresholds. The general Conventional Commits definition and native feat(api): add pagination example remain exact; only its release-decision synopsis changes. The Dojo History narrative retains its dates and names; only catalysed becomes catalyzed.

The authorized definition corrections are the pwsh expansion, the source-settled Conventional Commits release-decision synopsis, and the source-settled LTS expansion. All 63 abbreviation keys, native include syntax, and every other abbreviation line remain exact. The existing native Markdown renderer verifies the original pwsh correction:

<!-- Before -->
<p><abbr title="PowerShell Core (also known as PowerShell 7)">pwsh</abbr></p>
<!-- After -->
<p><abbr title="PowerShell command-line interface">pwsh</abbr></p>

The refreshed renderer probe uses the anonymous LTS pwsh sample and emits the following exact output. The pwsh result is unchanged by the LTS correction.

<p><abbr title="Long-Term Support">LTS</abbr> <abbr title="PowerShell command-line interface">pwsh</abbr></p>

The Evolutionary Development standing-directive admonition is editable guidance, not an attributed quotation. Its native [!IMPORTANT] marker and immediate-update obligation are checked separately. Direct instructions, decision gates, experiment quantities, test-first sequence, domain-signal condition, and clarification-marker condition retain their force.

All other tracked repository paths are unchanged. Shared indexes are not edited. Index regeneration changes only a temporary export during validation; CI derives the published rows from owning front matter. No heading or anchor repair is needed.

Validation results

The final anonymous cross-repository attempt exhausts the shared 60-request quota and reports five unresolved targets, not broken links. The documented authenticated-headroom rerun resolves all seven links. The owned-only invocation finds no eligible cross-repository links and correctly exits 1; an empty check is not counted as a pass.

The cached local textlint does not execute this repository's rules and is not counted as a pass. The successful CI NATURAL_LANGUAGE result supplies the terminology evidence. CI earlier identifies an unquoted colon and two terminology defects introduced by this PR. Each is reproduced or tied to an exact CI message and corrected in a small pushed commit. No rule, workflow, code, test, or configuration workaround is added.

The first Copilot review identifies a semantic regression in the intermediate YAGNI sentence: Do not build for requirements that are not established confuses confirmation with present need. An established requirement in Later can still be unnecessary for the current deliverable. The prose verification is strengthened with that boundary case before the correction. The corrected sentence restores the original present-need constraint without changing the principle: Do not implement a requirement before the current deliverable needs it (YAGNI). A scoped search finds the same substitution in Engineering Taste. Its guard also fails before correction, and its sentence becomes Build only what the current deliverable needs. Both present-need guards pass after the propagated fix.

An advisory changed-sentence screen identifies only the retained historical Dojo sentence for contextual review. That screen, technical-term word counts, and other automated checks do not establish full STE conformance.

Standards and source alignment

The six required fixed-baseline writing sources are read before judging the owned pages: Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and applicable reference/standard templates. Their contents match the clean starting worktree.

The official STEMG overview, FAQ, and relevant local Issue 9 rule details support the writing review. The verified PDF MD5 is 9c720341c350ed77943b2c73d01c716f. The reference copy and extract remain local and are not republished. This delivery applies STE-informed writing practices and does not claim full STE conformance.

The official about_Pwsh description and immutable MicrosoftDocs source 9fc54e7fc4954f7b4af134def74ba8e8cac7e23c support the pwsh correction. Canonical Dictionary terminology and official Node.js documentation settle the LTS expansion; fixed FR1 and PR Format settle the Conventional Commits synopsis, as recorded above.

Source verification for changed reference claims uses GitHub Next Continuous AI, the Microsoft Learn Dojo path, Dojo introduction, public Dojo organization, ISE Playbook, DORA guide, DORA metrics history, and Thoughtworks Radar. Retained bibliography and historical notes are not presented as a complete new historical verification.

Read-only supporting paths

The following supporting paths are read in full or at the relevant source sections, procedure/help sections, or tracked usage lines. They remain unchanged. The full-read requirement applies to every owned source in the manifest above.

• AGENTS.md
• README.md
• .github\CONTRIBUTING.md
• src\docs\index.md
• src\docs\Ways-of-Working\index.md
• src\docs\Ways-of-Working\Documentation-Model.md
• src\docs\Coding-Standards\Natural-Language.md
• src\docs\Coding-Standards\Writing-Guide.md
• src\docs\Coding-Standards\Markdown.md
• src\docs\Coding-Standards\Documentation.md
• src\docs\Coding-Standards\PowerShell\index.md
• src\docs\Coding-Standards\TypeScript.md
• src\docs\Capabilities\release-management\spec.md
• src\docs\Ways-of-Working\Spec-Driven-Development-Templates.md
• src\docs\Ways-of-Working\Workflow.md
• src\docs\Ways-of-Working\Issues\index.md
• src\docs\Ways-of-Working\Issues\Process\Format.md
• src\docs\Ways-of-Working\Issues\Process\Planning.md
• src\docs\Ways-of-Working\Issues\Types\Task.md
• src\docs\Ways-of-Working\Workflow-Stages\Define.md
• src\docs\Ways-of-Working\Workflow-Stages\Implement.md
• src\docs\Ways-of-Working\Contribution-Workflow.md
• src\docs\Ways-of-Working\Commit-Conventions.md
• src\docs\Ways-of-Working\PR-Format.md
• src\docs\Ways-of-Working\Definition-of-Ready-and-Done.md
• src\docs\Ways-of-Working\Branching-and-Merging.md
• src\docs\Ways-of-Working\Review-Etiquette.md
• .github\workflows\Docs.yml
• .github\workflows\Cross-Repository-Links.yml
• .github\linters\.markdown-lint.yml
• .github\linters\.textlintrc
• requirements.txt
• src\zensical.toml
• .github\scripts\Test-DocumentationLink.ps1
• .github\scripts\Test-CrossRepositoryLink.ps1
• .github\scripts\Invoke-PesterSuite.ps1
• .github\scripts\Update-DocumentationIndex.ps1
• .github\scripts\Wait-CopilotReview.ps1

The referenced parent-directory ..\AGENTS.md does not exist in this worktree layout. The repository's actual AGENTS.md is read and its required README, contribution-guide, and documentation-root order is followed. No pointer file is changed.

Accepted differences, contradictions, and exclusions

Necessary imperatives, normative target-state contracts, technical syntax, official titles, quotations, historical dates and models, and generated output retain their purpose. A normative contract is not evidence that a product or enforcement exists. No current status or implementation claim is inferred from a specification.

The following questions remain explicit rather than becoming new policy:

1. AI-first context-first development says If the docs and the code disagree, the docs are wrong. Engineering practices requires diagnosis because either documented intent or implementation can be wrong. The existing authority conflict remains.
2. Purpose and direction maps How to Mission, while Vision presents the mission as why MSX exists. The mission and existing mapping remain unchanged.
3. The no-downward-normative-links rule coexists with the engineering-practices Testing-standard ownership link. The existing link is retained.
4. The retained eight-pillars heading differs from Microsoft's eight-capability/four-foundation terminology. The explanation is source-supported; the heading and anchor remain stable.

DORA's source resolves the factual fifth-metric framing without rewriting the historical table. The Radar's twice-yearly source contradicts the former quarterly claim; the replacement states its stable purpose rather than introducing another cadence promise.

The old GitHub org quiet since late 2022, sparse, last meaningful activity Oct 2022, never published, and The de facto modern equivalent claims are preserved as before-text evidence in this Task and immutable baseline, not asserted as present-day facts. The page retains the intentional Dojo History narrative and dated tool snapshot.

Other owners' pages, shared indexes, agent pointers, src\includes\links.md, executable code, tests, configuration, dependencies, enforcement, and restructuring are excluded. MSXOrg/docs#240 code and tests are untouched. No new repository audit, planning, or tooling file is added.

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.

The two factual definitions are corrected from settled sources, not deferred as policy choices. Writing, source/check verification, and the fresh exact-head Copilot round are complete. No blocker remains for the assigned draft deliverable. The other four policy/legacy-heading questions stay separate. The PR remains draft by explicit campaign instruction. No full STE conformance or implemented-product/enforcement claim is made.