[Marius Storhaug (MariusStorhaug)]

Shared coding standards use direct en-US guidance and present-tense contracts. Explanations replace idioms and distinguish what each check verifies. Module GUID guidance distinguishes declared metadata from content identity. Commands, examples, anchors, and technical requirements remain unchanged. No consumer action is required.

Changed: Shared standards explain rules directly

Twelve shared standards explain their existing rules with concrete terms and shorter sentences. The guidance covers function reuse, code layout, naming, errors, dependency updates, performance, pre-commit checks, security, documentation, natural language, Markdown, and testing. The Technical Writing Guide is unchanged because it already gives direct source-reading, artifact-format, preservation, and verification instructions.

The changes improve guidance, not the software or enforcement it describes. A local check result is not proof of every standard or every CI result. Native help requirements, exact commands and examples, settings filenames, pinning and security controls, compatibility boundaries, and normative force remain intact. No migration or configuration action is required.

Technical details

Source identities and delivery. The scoped base is 1b0d4893c8fefabe604d04393068a8ff6f848082; the final candidate is 74bc8b9e634538cd7fb19ad0bcea694692f3ab67. The comparison changes only 12 eligible Markdown pages, with 163 insertions and 163 deletions. The remote branch and PR report that same head, and the worktree is clean. This is scoped implementation evidence, not an invented publication baseline.

The five pushed commits are 2a47f05d5ac4ad49e9ccf54c08b12ef0071a6dbd, 4d144df3ed360596e7c9c69662e515aab16c8cc3, 2337c5456d51e9212664ae46fae0cd624bfc60f0, 62b521bc1fca219fbc1324f86f526d113e478c18, and 74bc8b9e634538cd7fb19ad0bcea694692f3ab67. The draft opened immediately after the first complete, one-page Markdown improvement. The remaining pages and the source-backed GUID factual correction were completed in the same PR.

Fixed review criteria. The authoritative review sources are pinned to the base commit: Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and the applicable standard template. Editing a source-owning page does not weaken the criteria.

The official STEMG overview and FAQ were read. The local Issue 9 PDF matched MD5 9c720341c350ed77943b2c73d01c716f. Selected rule summaries and explanations were consulted in its local extract, including terminology, en-US, full word forms, clear sentences, direct instructions, and descriptive structure. The PDF was not exhaustively reviewed or republished. No scan, count, automated approval, or overview is treated as full STE conformance.

Owned read and acceptance evidence. Every eligible page was read in full at the fixed baseline. Changed passages and their surrounding rules were reviewed again after editing. The following excerpts are prose acceptance evidence, not required-string tests.

Path	Read/change result	Before and after	Preserved contract
src\docs\Coding-Standards\Code-Layout.md	Full; changed	hold in your head becomes Keep functions small; formatter acceptance becomes verification of configured rules only	Standard-first derivation, screen-fit guidance, and file-layout rules
src\docs\Coding-Standards\Dependencies.md	Full; changed	maximizes control but rots becomes excluded fixes and delayed adoption; where you sit becomes source, compatibility risk, and consumer role	Identity/version axes, pin forms, owned-major limits, human review, library/application roles
src\docs\Coding-Standards\Documentation.md	Full; changed	This is a floor, not a ceiling becomes a direct native-format requirement for internal and private units	Public minimum content, internal help, comment examples, and the decision-rationale table
src\docs\Coding-Standards\Error-Handling.md	Full; changed	fulfil becomes fulfill; pushes the bug downstream becomes failures found by later callers	Immediate errors, typed catches, propagation, separate channels, secret exclusion, cleanup
src\docs\Coding-Standards\Functions.md	Full; changed	hand-rolled version becomes custom implementation; the weak link guidance explicitly improves the shared function for all callers	Reuse order, validation, pure core logic, preview-or-confirm behavior
src\docs\Coding-Standards\Markdown.md	Full; changed	labelled becomes labeled; behaviour becomes behavior; the honour sentence becomes direct rule statements; Every code fence has a language tag. identifies the correct element	Lint settings, commands, anchor examples, links, configuration precedence
src\docs\Coding-Standards\Naming.md	Full; changed	turns it into a riddle becomes the direct explanation that notReady = false means ready	All identifiers, including daysUntilExpiry, settings filenames, overrides, and exceptions
src\docs\Coding-Standards\Natural-Language.md	Full; changed	source code for humans and agents becomes instructions and information; evergreen prose states the supported contract	Issue 9 MUST, en-US, audience-language policy, quotations, negative tables, fenced examples
src\docs\Coding-Standards\Performance.md	Full; changed	catastrophic for ten thousand becomes Code acceptable for ten items can be too slow for ten thousand.; a second measurement replaces a hunch	Quadratic-growth example, data structures, filtering, streaming, safe caching, clarity first
src\docs\Coding-Standards\Pre-Commit.md	Full; changed	a commit that passes locally passes the gate becomes A local pass covers only the checks and inputs that local run examined.	Configured-hook MUST, prohibition on new rules, immutable revisions, CI gate, commands, exceptions
src\docs\Coding-Standards\Security.md	Full; changed	don't hope becomes Revoke and rotate it.; the image-secret prohibition is direct	Least privilege, external pins, owned-major limits, PR-author identity, event names, trusted follow-up data
src\docs\Coding-Standards\Testing.md	Full; changed	the suite stays green forever becomes the same wrong anchor in two implementations; the check is decoration becomes a controlled broken case that must fail	Observable behavior, independent results, no source-freezing tests, zero-count exceptions, protected live APIs, unexecuted coverage
src\docs\Coding-Standards\Writing-Guide.md	Full; no change	Existing direct instructions already cover sources, formats, preservation, and verification limits	Bytes identical to the fixed baseline

The test-first Task existed before repository edits. Its before-text observations established the prose gaps before implementation. Baseline Markdown, links, Pester, and site checks passed. The final one-off preservation comparison examines all 13 pages and retains 104 heading lines, all 77 original link targets in order, 194 inline code spans, 13 fenced blocks, and 14 normative token occurrences. One official module-manifest reference is added, for 78 extracted link targets. Front matter, Natural Language's tables and blockquoted examples, and all generated index blocks are unchanged. These comparisons establish preservation of the extracted surfaces, not full correctness or STE conformance. Manual reading supplies the meaning comparison. No source-freezing policy test was added.

Final validation at 74bc8b9e634538cd7fb19ad0bcea694692f3ab67.

Existing check	Result
Markdown CLI with the repository configuration	Pass: markdownlint-cli2 0.24.0, all 13 eligible files, 0 issues
Relative-link and anchor validator	Pass: 130 files scanned
Cross-repository-link validator	Pass: 7 links checked in 134 files
Pester 6.0.1 through the existing runner	Pass: 66 passed, 0 failed, 0 skipped, 6 suites
Local Zensical build	Pass: no issues; installed version 0.0.50, not the pinned-version oracle
Docs CI run 41833563676	Pass: Build, Links, Lint, Test; Publish skipped for the PR
CI Build job	Pass using the unchanged pinned zensical==0.0.59 requirement
Cross-repository-link CI run 41833563852	Pass; immutable head matches this candidate
Final automated review	Approved on this candidate; 0 new inline comments
Scoped git diff --check and worktree check	Pass; clean worktree and pushed head

The local/CI Zensical versions are reported separately; CI supplies the pinned-version result. No local package was installed, and no dependency was added or changed. The baseline has no tracked .pre-commit-config.yaml, so no configured local hook run is claimed. A normative requirement for hooks is not evidence that they exist here.

Standards and framework alignment. Fixed criteria below means the immutable writing, Markdown, Documentation, and standard-template sources linked above. Fixed model means the immutable Documentation Model. The standard artifact purpose is preserved: rules carry their reasoning, and author actions remain direct imperatives. No framework implementation, schema, supported command, or consumer configuration changes, so no producer/template migration applies.

Changed surface	Standards checked	Framework docs checked	Result
src\docs\Coding-Standards\Code-Layout.md	Fixed criteria	Fixed model	Fixed in this PR
src\docs\Coding-Standards\Dependencies.md	Fixed criteria	Fixed model	Fixed in this PR
src\docs\Coding-Standards\Documentation.md	Fixed criteria	Fixed model	Fixed in this PR
src\docs\Coding-Standards\Error-Handling.md	Fixed criteria	Fixed model	Fixed in this PR
src\docs\Coding-Standards\Functions.md	Fixed criteria	Fixed model	Fixed in this PR
src\docs\Coding-Standards\Markdown.md	Fixed criteria	Fixed model	Fixed in this PR
src\docs\Coding-Standards\Naming.md	Fixed criteria	Fixed model	Fixed in this PR
src\docs\Coding-Standards\Natural-Language.md	Fixed criteria	Fixed model	Fixed in this PR
src\docs\Coding-Standards\Performance.md	Fixed criteria	Fixed model	Fixed in this PR
src\docs\Coding-Standards\Pre-Commit.md	Fixed criteria	Fixed model	Fixed in this PR
src\docs\Coding-Standards\Security.md	Fixed criteria	Fixed model	Fixed in this PR
src\docs\Coding-Standards\Testing.md	Fixed criteria	Fixed model	Fixed in this PR

Other read-only paths. The following repository paths were read for context, fixed criteria, process, or existing validation. All remain unchanged. Reads are complete except the two explicitly marked ranges.

AGENTS.md
README.md
.github\CONTRIBUTING.md
src\docs\index.md
src\docs\Coding-Standards\index.md
src\docs\Ways-of-Working\Documentation-Model.md
src\docs\Ways-of-Working\Spec-Driven-Development-Templates.md
src\docs\Ways-of-Working\Issues\index.md
src\docs\Ways-of-Working\Issues\Types\Task.md
src\docs\Ways-of-Working\Issues\Process\Format.md
src\docs\Ways-of-Working\PR-Format.md
src\docs\Ways-of-Working\Commit-Conventions.md
src\docs\Ways-of-Working\Contribution-Workflow.md
src\docs\Ways-of-Working\Comparative-Review-Orchestration.md
src\docs\Ways-of-Working\Workflow.md
src\docs\Ways-of-Working\Workflow-Stages\Implement.md
src\docs\Ways-of-Working\Workflow-Stages\Maintain-Guidance.md
src\docs\Ways-of-Working\Definition-of-Ready-and-Done.md
src\docs\Ways-of-Working\Branching-and-Merging.md
.github\workflows\Docs.yml
.github\workflows\Cross-Repository-Links.yml
.github\linters\.markdown-lint.yml
requirements.txt
.github\scripts\Invoke-PesterSuite.ps1
.github\scripts\Wait-CopilotReview.ps1 (lines 1-160)
src\zensical.toml (lines 1-100)

The local coordination frame was read in full. The PDF was hash-verified; selected extract rules were read at lines 1700-1795, 2540-2570, 3220-3325, 3675-3707, and 3990-4035, with targeted rule-location searches. The official overview and FAQ were read in full, as were the published Documentation Model and Ways of Working index reached through the installed skill routes. Their published aliases redirected to msx.no; the immutable Git sources remain the criteria. No local issue-template directory or legacy issue-template file exists. The configured parent-relative AGENTS.md is absent in this worktree layout; the repository's own AGENTS.md is present and was followed.

Task progress and issue convergence. All implementation-plan items in #242 are complete for this draft delivery. The Task remains open for its normal merge closure. The convergence search used open MSXOrg/docs issues with "shared coding" in:title,body, "ASD-STE100" in:title,body, and "Markdown.md" in:title,body. These returned this Task, the 15 separately owned campaign Tasks, and #150 and #186. Both existing non-campaign issues were read in full and are not satisfied by this prose-only diff. No additional issue receives a closing keyword.

Accepted differences and open questions. Technical nouns, native syntax, exact examples, normative contracts, direct instructions, intentional negative examples, and generated indexes retain their purpose. Existing heading idioms and contractions remain unchanged to preserve anchors. No new enforcement, functional changes, broad restructure, repository audit files, or edits to the scripts/tests reserved by #240 are included.

The source-precedence question remains unresolved. The coding-standards index says configuration derives from standards. Markdown makes its configuration authoritative if they differ. Implement says repo-local linter configuration wins. This PR preserves these contracts and selects no new precedence rule. The decision-rationale table's relationship to durable decision records remains a scope question. The GUID equivalence is a factual error corrected below, not a new supply-chain policy.

Published-URL checking remains #150, and the redirecting alias/canonical-domain decision remains #186. The absent local pre-commit configuration is not treated as an implemented enforcement gate. One remote push rejection was resolved by a normal retry, without force-pushing. No implementation blocker remains. Full STE conformance is not claimed.

The two checked-in workflows run lint, links, tests, and a Zensical Pages build/deploy without a versioned Release Management route. No release decision block or release:* label applies. This PR remains draft and assigned to its author, with no auto-merge request. No readiness, merge, auto-merge, or Agent merge action is taken.

Related references

• Resolves [documentation-writing-alignment] Clarify shared coding and writing standards #242
• References Check the published-URL links the Markdown standard also asks authors to write #150
• References The docs site is cited by its redirecting alias rather than its canonical domain #186
• References Keep documentation tooling tests focused on supported behavior #240; its scripts and tests are outside this PR

Fixed: Declared module identity is distinct from content integrity

A PowerShell module GUID is declared identity metadata, not a content hash. A matching module name, GUID, and version does not prove that the module bytes are unchanged. The dependency table and related explanations distinguish fixed version selection from fixed content.

The existing optional GUID check, version and pinning policy, all #Requires examples, SHA/digest controls, and normative force remain unchanged. No new enforcement mechanism or consumer action is required.

Technical details

The official module-manifest GUID reference, verified against Microsoft's immutable source, defines an optional declared identifier that distinguishes same-named modules. The introduction and GUID sections were read; no full-article review is claimed.

Before this correction, Dependencies grouped a module GUID with content hashes as a binding to immutable bytes. The identity/exact table also reported no change before re-pinning and reproducibility as Yes. Those are descriptive factual claims, not policy choices to preserve when false. The Task plan was extended before editing, with the source and a controlled counterexample.

Two locally generated, valid manifests both report module name Example, GUID 11111111-2222-4333-8444-555555555555, and version 1.0.0. They use different controlled description text. Test-ModuleManifest confirms the matching identity/version, while Get-FileHash returns different SHA-256 values: 95DA5C13989DF87D9E97D0176654FF5D7BC6E8128DA59563FF8F8B58D467F300 and 0E31D8A4833862CF4AB6459671D112F0246E736EF9F7710A05B9EE89B0F866BF. Matching metadata therefore does not fix manifest bytes. Both temporary fixtures and their empty directories were removed.

Commit 74bc8b9e634538cd7fb19ad0bcea694692f3ab67 changes only Dependencies, with 7 insertions and 5 deletions. It adds one official source link, distinguishes declared identity from content hashes, qualifies the identity/exact table, and corrects coupled reproducibility inferences. All existing examples, identifiers, links, and normative tokens remain intact.

The language-specific owner reports matching clarification in PowerShell Scripts.md, Requires-Modules.md, and Version-Constraints.md, in #260 at cd29fcb9d2fe3247aca71ae4f137279c0e8ed1cd. Optional checks, version constraints, exact examples, and pinning policy remain unchanged there. No enforcement mechanism is added. These are separately owned changes, not additional files read or edited in this PR.

Changed surface	Standards checked	Framework docs checked	Result
src\docs\Coding-Standards\Dependencies.md	Fixed writing criteria and the verified official GUID reference	Fixed Documentation Model	Fixed in this PR

Related references

• References Language standards state coding controls directly #260

[Copilot]

🟢 Approved

No active review issues are reported for the documentation-only update to the shared Markdown standard.

No open issues 🎉

What changed in this PR

This documentation-only change makes the shared Markdown standard more direct and consistent with en-US usage while preserving commands, examples, anchors, and technical requirements.

Changes:

• Replaces non-US spellings and simplifies rule explanations.
• Distinguishes formatting, local-link, and cross-repository validation scopes.
• Clarifies that successful local linting does not establish full CI or STE conformance.

File	Description
src/​docs/​Coding-Standards/​Markdown.md	Clarifies authoring rules and validation coverage using direct en-US guidance.

_{Review effort: Balanced}

[Copilot]

🟢 Approved

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

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues are reported for the coding-standards documentation rewrite.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues require changes to the coding-standards documentation updates.

No open issues 🎉

_{Review effort: Balanced}