[Marius Storhaug (MariusStorhaug)]

Language-specific coding standards use direct en-US technical prose and state the existing controls without idioms. PowerShell guidance also distinguishes diagnostic policy from runtime behavior and declared GUID identity from content integrity. Runtime behavior, pinning policy, compatibility requirements, and technical examples do not change. No adoption action is required.

Changed: Language-specific standards state controls directly

PowerShell, Terraform, TypeScript, and YAML guidance uses concrete descriptions, shorter sentences, and present-tense statements. Direct instructions remain imperative. The same version bounds, optional identity checks, native help, parameter and output contracts, VS Code compatibility floor, and YAML obligations remain in force.

The PowerShell factual corrections are bounded by official sources and reproducible probes. Cmdlets and advanced functions support the Debug common parameter. Write-Error is non-terminating by default, with termination controlled by effective error-action settings. Important information summaries still should be visible without Verbose, but the default information preference suppresses display unless the caller selects a visibility setting. A module GUID checks declared identity metadata, not immutable contents or publisher authenticity.

Technical details

Immutable coverage: MSXOrg/docs 1b0d4893c8fefabe604d04393068a8ff6f848082 to cd29fcb9d2fe3247aca71ae4f137279c0e8ed1cd. Five small logical commits are pushed. This draft opened after the first complete improvement, abfd5a48850124a565f71930ad6db3892af924ba, before the rest of the assigned part was implemented. The diff changes only the 10 declared Markdown paths below: 174 insertions and 164 deletions. The worktree is clean.

Full-read dispositions: every assigned page was read in full, including examples, native help, and handwritten PowerShell index content. Paths below are relative to src/docs/Coding-Standards/.

Fully read path	Disposition	Concrete acceptance evidence
PowerShell/Classes.md	Changed	reach for becomes use; behaviour becomes behavior. Class selection, member order, and the complete class example remain unchanged.
PowerShell/Functions.md	Changed	for free, honour, and breadcrumbs become direct feature, error-action, and diagnostic descriptions. Native help, parameter sets, output contracts, and SHOULD force remain intact. WhatIf retains the existing state-change condition.
PowerShell/index.md	Changed, handwritten prose only	gluing tools together, string surgery, and quietly winning become tool integration, custom string manipulation, and an accidental write that fails. The generated INDEX block is unchanged.
PowerShell/Messaging.md	Changed	plumbing becomes implementation details. The false Debug/termination/automatic-visibility statements are corrected without changing the diagnostic-channel policy.
PowerShell/Requires-Modules.md	Changed	flow in, would break you, and false green become accepted releases, an incompatible next major, and a false-success result. GUID is explicitly declared metadata, not a content hash or proof of publisher authenticity.
PowerShell/Scripts.md	Changed	flow in, would break you, freeze out patches, and reach for it become available patches, an incompatible-major bound, excluded later patches, and a separate declared-identity control.
PowerShell/Testing.md	No change	The complete page matches the baseline. Its Simple/Standard/Advanced documentation profiles, discovery precedence, filenames, sibling suppression, and root-only phases already use direct evergreen guidance.
PowerShell/Version-Constraints.md	Changed	Range semantics and the PSResourceGet/.NET bare-version distinction are stated directly. GUID identity is separate from contents/authenticity. All range tables and examples retain their exact values.
Terraform.md	Changed	labelled becomes labeled; dependency-graph rationale identifies redundant depends_on entries directly. Version, state, naming, and module controls are unchanged.
TypeScript.md	Changed	quietly drops users, escape hatch, and when a needed API lands become explicit compatibility-floor and type-exception guidance. Exact dependency pins, the engine caret exception, paired single-commit updates, and the package-error example are unchanged.
YAML.md	Changed	next year becomes existing content and later additions. All three MUST obligations, the pre-commit filename exception, and native suppression example remain unchanged.

Test-first evidence and preservation: ten page-level prose cases failed before editing and pass after it. The three Messaging factual cases and three GUID qualification cases also have recorded before/after evidence. Read-only comparisons preserve all 22 fenced blocks, every original inline identifier in order, every numeric/version literal, every heading/anchor, all generated source INDEX content, navigation keys, and uppercase normative keywords. Manual review preserves the conditional controls and requirement force; the function-help description retains SHOULD rather than becoming mandatory.

The only added code spans are $InformationPreference, SilentlyContinue, -InformationAction Continue, -ErrorAction Stop, $ErrorActionPreference = 'Stop', and -TargetObject. These explain existing runtime conditions. No original inline identifier or executable example is removed or changed. The GUID qualification adds no identifier, version, or pinning-policy change.

Source and factual evidence: the fixed-baseline Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and Standard template supplied the writing criteria. The official STEMG overview/FAQ and relevant Issue 9 rules and dictionary were consulted. The PDF/extract remain local; the PDF MD5 is 9c720341c350ed77943b2c73d01c716f. Automated scans and counts do not establish full STE conformance.

Exact PowerShell 7.6.9 probe commands/results verify Debug metadata/output, continued execution for ErrorAction Continue, catchable termination for both Stop controls, hidden information by default, and displayed information with InformationAction Continue. Companion probes verify structured TargetObject context and conditional WhatIf availability. Immutable MicrosoftDocs/PowerShell-Docs sources are 5f46b78db1f0b6593e1854c5fefdea75abd13e52 for common parameters and 3bcc275f46fd8537780ee1549c0862bb0266e06c for Write-Error and Write-Information.

The GUID definition uses MicrosoftDocs/PowerShell-Docs 364305cae1cd43135147df815661f0a1dddd9967, reference/7.6/Microsoft.PowerShell.Core/About/about_Module_Manifests.md#guid. Two local manifests with equal declared GUID/version and different anonymous descriptions have different SHA-256 values; both pass Test-ModuleManifest. This verifies the metadata/content distinction, not package signing or gallery trust. The Task retains the source, exact declared values, hashes, and bounded interpretation.

Final validation at cd29fcb9d2fe3247aca71ae4f137279c0e8ed1cd:

Existing check or evidence	Result
markdownlint-cli2 0.24.0 / markdownlint 0.42.0, shared repository config	11 assigned files, 0 issues.
Test-DocumentationLink.ps1	All links resolve across 130 documentation files.
Test-CrossRepositoryLink.ps1, scoped to the assigned pages	1 qualifying same-repository GitHub target resolves across 11 files. No claim that this local scope checks all external URLs.
Existing index generator and Zensical 0.0.59	CI-equivalent regeneration in a temporary copy, then zensical build --clean --strict: no issues. A second copied-index Check passes. Only the expected Coding Standards and PowerShell index copies regenerate; source tables remain untouched.
Rendered-output acceptance	All 11 pages exist. Changed controls, runtime conditions, GUID limits, and regenerated class description occur in rendered main content.
Preservation, scope, and whitespace	All invariants pass; only the 10 owned Markdown files differ; git diff --check passes; clean worktree.
GitHub CI for the exact final head	Lint, Test, Links, Build, and Cross-repository links succeed. Publish is skipped as expected for a PR.
Explicit automated review	Review 5768663442 approves the exact final head with 0 inline comments. Wait-CopilotReview reports a clean round. The earlier review of 6c4102d is not used as final-head evidence.

The declared Zensical 0.0.59 was restored in isolated session storage only after the installed 0.0.50 failed the version preflight. Repository requirements and the global installation are unchanged. No tool or dependency is added to the repository.

Standards and framework alignment:

Changed surface	Standards checked	Framework or domain docs checked	Result
Seven changed PowerShell/ pages	Fixed-baseline Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, Standard template; original language contracts	Official PowerShell common parameters, Write-Error, Write-Information, and module-manifest GUID references for bounded factual repairs	Fixed in this PR; existing declaration-scope interpretation is recorded below.
Terraform.md	Same writing sources and original Terraform contract	None (no framework-specific docs)	Fixed in this PR.
TypeScript.md	Same writing sources and original TypeScript/VS Code compatibility contract	None (no framework-specific docs)	Fixed in this PR.
YAML.md	Same writing sources and original YAML/linter contract	None (no framework-specific docs)	Fixed in this PR.

Accepted differences and exclusions: exact technical terms, commands, native help, code examples, imperative instructions, normative target contracts, and generated descriptions retain their purpose. Observed Pester exit-code evidence retains its tested versions and unknown cause. A normative requirement is not proof of implementation or enforcement. The shared standards, GitHub Actions page, top-level index, all code/configuration/tests, and #240 remain untouched. No heading, page path, requirement, or enforcement mechanism is added. No repository audit/planning file is created. No cross-owned anchor repair is needed; CI derives dependent index descriptions.

Unresolved interpretation: Scripts places module dependencies in #Requires, while Module Requirements excludes verdict-reporting entry scripts. Both existing contracts remain unchanged. The policy scope needs a separate clarification; this PR does not infer a new loading policy. There is no delivery blocker for the requested prose/factual slice.

Issue convergence: the scoped open-issue search used PowerShell, Terraform, TypeScript, YAML, and language in titles. #55 requires new display UX policy, and #136 requires updater implementation; neither is delivered by this diff. No additional issue converges. Only the native Task below is closed on a later merge.

This PR remains DRAFT and open. It is not marked ready or merged. No auto-merge or Agent merge action is taken; GitHub auto_merge is null.

Related references

• Resolves [documentation-writing-alignment] Clarify language-specific coding standards #245
• References Keep documentation tooling tests focused on supported behavior #240 for the excluded active tooling work

[Copilot]

🟢 Approved

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

No open issues 🎉

What changed in this PR

This documentation-only PR advances #245 by making language-specific coding standards clearer and more direct. It preserves technical examples and coding controls while correcting PowerShell diagnostic-runtime descriptions.

Changes:

• Replaces figurative wording with direct en-US prose across PowerShell, Terraform, TypeScript, and YAML guidance.
• Clarifies module version constraints, script structure, function contracts, and class selection.
• Corrects PowerShell Debug availability, error termination, and information-stream visibility guidance without changing runtime behavior.

File	Description
src/​docs/​Coding-Standards/​YAML.md	Clarifies linting, suppression scope, and workflow checks.
src/​docs/​Coding-Standards/​TypeScript.md	Clarifies typing rules and VS Code compatibility constraints.
src/​docs/​Coding-Standards/​Terraform.md	Simplifies infrastructure, state, dependency, and tooling guidance.
src/​docs/​Coding-Standards/​PowerShell/​Version-Constraints.md	Clarifies version-range semantics and separate identity controls.
src/​docs/​Coding-Standards/​PowerShell/​Scripts.md	States script structure and dependency controls directly.
src/​docs/​Coding-Standards/​PowerShell/​Requires-Modules.md	Clarifies module constraints and documented exit-code observations.
src/​docs/​Coding-Standards/​PowerShell/​Messaging.md	Clarifies channel policy and corrects runtime descriptions.
src/​docs/​Coding-Standards/​PowerShell/​index.md	Simplifies shared conventions while preserving generated navigation.
src/​docs/​Coding-Standards/​PowerShell/​Functions.md	Clarifies parameters, pipelines, state changes, and native help.
src/​docs/​Coding-Standards/​PowerShell/​Classes.md	States class-selection and organization guidance directly.

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues were identified for this documentation-only clarification of coding standards.

No open issues 🎉

_{Review effort: Balanced}