Repository navigation
Keep documentation tooling tests focused on supported behavior - #240
Open
Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
Open
Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
Conversation
This was referenced Nov 4, 2026
This was referenced Nov 4, 2026
Closed
Closed
There was a problem hiding this comment.
🟡 Changes recommended
Markdown delimiter parsing mishandles adjacent formatting, nested emphasis, and backticks, causing the link checker to generate incorrect anchors and reject valid links.
4 open issues
What changed in this PR
This PR shifts documentation-tooling tests toward supported command behavior while retaining package-quality checks. It also updates heading normalization to preserve literal underscores in GitHub anchors.
Changes:
- Replace internal slug-function extraction with command-level anchor tests, including underscore and inline-code cases.
- Remove fixed skill-inventory assertions and the pin updater’s exact REST-call count.
- Refine underscore-emphasis handling in the cross-repository link checker.
| File | Description |
|---|---|
tests/Update-GitHubActionPin.Tests.ps1 |
Removes the exact REST-call-count assertion. |
tests/Test-CrossRepositoryLink.Tests.ps1 |
Moves slug coverage to checker commands and adds anchor regressions. |
tests/PluginMarketplace.Tests.ps1 |
Removes fixed skill inventories and clarifies metadata-check scope. |
.github/scripts/Test-CrossRepositoryLink.ps1 |
Preserves literal underscores while handling emphasis and code spans. |
Review effort: Balanced
13 tasks done
This was referenced Nov 4, 2026
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
November 4, 2026 13:24
3 tasks
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
Artifact and orchestration guidance uses direct en-US statements for documentation authors and agents. Fleet stage transitions remove the old label before adding its replacement, so the example and ordered instructions follow the existing one-stage-at-a-time rule. The five-page revision preserves artifact roles, native issue types, hierarchy, stage gates, requirement identifiers, and command strings. The Fleet example intentionally changes sequence only. No integration or runtime-tool change is required. <!-- ANNOUNCEMENT STOP --> ## Changed: Artifact guidance states its contracts and procedures directly Documentation Model distinguishes requirements, design mechanisms, implementation values, and delivery records. Spec-Driven Development and its templates use consistent en-US wording. Comparative and fleet playbooks use literal explanations for evidence, ownership, stages, and campaign state. The guidance keeps research findings historical, decision rationale immutable, template clarification markers unresolved until acceptance, and normative contracts separate from implementation or CI-enforcement evidence. It does not change policy, navigation, tooling, or dependencies. <details> <summary>Technical details</summary> The review baseline remains fixed at [`1b0d4893c8fefabe604d04393068a8ff6f848082`](https://github.com/MSXOrg/docs/tree/1b0d4893c8fefabe604d04393068a8ff6f848082). Source expectations come from that commit's Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and artifact templates. Editing an owned source page does not change the baseline or weaken its rules. The official [STEMG overview](https://www.asd-ste100.org/about_STE.html), [FAQ](https://www.asd-ste100.org/STE_faq.html), and verified local [Issue 9](https://doi.org/10.5281/zenodo.23666006) PDF/extract support the language review. The PDF MD5 is `9c720341c350ed77943b2c73d01c716f`. Copies and extracts remain local. Full STE conformance is not claimed. | Before | After | | --- | --- | | `this site is organised` | `The documentation on this site serves **humans and agents**.` | | `the behaviour, guarantees, and success criteria` | `behavior, guarantees, and success criteria` | | `implementation detail rots fastest` | `Implementation details change more often than requirements.` | | `A change moves down a ladder of artifacts.` | `Each artifact has a defined level of detail` | | `A spec fixes the smallest set of requirements` | `A spec fixes only the requirements needed for correctness and verification.` | | `this feature specialises` | `this feature specializes` | | `<One paragraph on how the spec is realised.>` | `<One paragraph on how the design meets the spec.>` | | `Some reviews are not` | `A comparative review compares a target with authoritative reference sources.` | | `Defining the classification vocabulary *before* looking at anything` | `Define the classification vocabulary **before** investigation.` | | `How a single change is applied across many repositories at once` | `A *campaign* applies one change across many repositories.` | | `every repository hitting the same wall` | `One shared fix unblocks every affected repository.` | | `the judgement of` | `The only human or agent judgment is` | All five owned files are fully read and changed, including all 11 artifact templates: - `src\docs\Ways-of-Working\Documentation-Model.md` - `src\docs\Ways-of-Working\Spec-Driven-Development.md` - `src\docs\Ways-of-Working\Spec-Driven-Development-Templates.md` - `src\docs\Ways-of-Working\Comparative-Review-Orchestration.md` - `src\docs\Ways-of-Working\Fleet-Orchestration.md` All 12 fixed prose examples pass after failing before editing. All 163 heading lines, including template/example headings, and all 118 link targets remain unchanged. FR/NFR anchors, normative keyword counts, fence structure, and contract tables retain their baseline meaning. Three comparative-review input descriptions change wording only. The 11 template skeletons retain their headings, syntax, placeholder delimiters, scenario examples, and clarification/supersession placeholders. All executable examples remain byte-for-byte unchanged except for the explicit Fleet sequence-only correction described below. The two existing command lines exchange positions without changes to either command string, its identifiers or API route, or the note command. This is the sole example-preservation exception. Manual review confirms required/optional tiers, the spec/design distinction, native issue types and hierarchy, stage gates, normative force, cross-cutting acceptance criteria, historical research, and decision immutability and supersession. No owned page has a no-change outcome. Shared indexes, other pages, code, tests, configuration, dependencies, and the files reserved by #240 remain unchanged. No cross-owned repair is required. Accepted differences retain stable heading text and anchors, technical nouns, native fields, exact commands and paths, imperative instructions, normative obligations, historical findings and decisions, and intentionally incomplete template examples. The normal ready/auto-merge handoff is not performed because this campaign explicitly requires draft PRs. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `Documentation-Model.md` | Fixed-baseline Natural Language, Technical Writing Guide, Markdown, Documentation | Fixed-baseline Documentation Model and artifact templates | Fixed in this PR | | `Spec-Driven-Development.md` and templates | Same fixed-baseline writing sources | Fixed-baseline artifact tiers, specification/design roles, and all templates | Fixed in this PR | | Comparative and fleet playbooks | Same writing sources; PowerShell shared conventions for exact native-command strings | Orchestration template, issue ownership, state rules, and stage gates | Fixed in this PR | The first complete Model improvement was pushed before this draft opened. Five focused commits are pushed: `b7c1648`, `6cf862a`, `ba77513`, `111cee3`, and `6e188db`. The scoped PR comparison is `1b0d4893c8fefabe604d04393068a8ff6f848082` to `6e188db9cb47563b9cd8ba6da37ecfab123b8a5e`. The issue-convergence sweep covers 16 open campaign issues and open `Spec-Driven-Development` and `Fleet-Orchestration` matches. #105 requests removal of the standalone acceptance-criteria section, while the fixed standard retains it for cross-cutting scenarios. That policy/migration question remains separate, open, and unresolved. #101 requests a defect-tracking capability, not a prose revision. No additional issue is fully convergent and no extra closing reference is added. `Docs.yml` builds and publishes the documentation site without invoking Release Management. The other workflow validates cross-repository links. No release decision block or `release:*` label applies. </details> ## Fixed: Fleet stage changes remove the old label first The Fleet example removes `stage:in-progress` before adding `stage:blocked`. The queued-to-in-progress, adopted-PR, and blocked transition instructions use the same remove-first order. The existing limit of one stage label holds during the transition, not only after it. This corrects the example and ordered documentation, not the policy or runtime tooling. Both existing command strings, identifiers, API routes, and the following note command are unchanged. No real GitHub labels are changed for the experiment. <details> <summary>Technical details</summary> Before editing, anonymous in-memory label sets reproduce the original transient failure. The original document-order assertion fails, as expected. The corrected test reads the actual example's command order and checks every intermediate state. | Sequence, including initial state | Stage-label counts | Result | | --- | --- | --- | | Add replacement, remove old stage, add note | `1, 2, 1, 1` | Fails the invariant after the add | | Remove old stage, add replacement, add note | `1, 0, 1, 1` | At most one stage after every operation | | Queued to in-progress | `1, 0, 1` | Remove-first instruction and model pass | | Delivery issue to adopted PR | `1, 0, 1` | Remove-first instruction and model pass | The initial example labels are anonymous: `stage:in-progress` and `topic:example`. Both command orders produce the same final labels, `stage:blocked` and `topic:example`. The unrelated label is preserved. The note command does not mutate labels. The experiment makes no network calls or real GitHub label changes. The Task's acceptance criteria and technical decisions record the intentional sequence-only exception. The original source baseline remains fixed. Normalizing only the approved adjacent-line reorder makes every other executable example match its prior content. Exact command-line multisets and the note command also match. All headings, links, FR/NFR anchors, normative keywords, and contract tables are preserved. Only Fleet changes after `111cee39bf9af79f04489d2eb5933e1999091e72`: seven insertions and five deletions. All implementation and verification steps for `6e188db9cb47563b9cd8ba6da37ecfab123b8a5e` are complete, with evidence in the closing Task. | Repeated final-head validation | Result | | --- | --- | | Test-first model and actual document order | Original `1, 2, 1, 1` failure reproduced before editing; corrected `1, 0, 1, 1` passes with the same final and unrelated labels | | Matching instructions | Queued, adopted-PR, and blocked transitions remove the old stage before adding the replacement | | Original prose and preservation | All 12 cases and full five-page checks pass with the explicit sequence-only exception | | Markdown lint | All five pages pass the shared configuration | | Relative links | All links resolve across 130 documentation files | | Cross-repository links | All seven links resolve across 134 Markdown files after the reported anonymous rate-limit reset | | Site | `zensical build --clean` completes with no issues; no generated index is edited in the worktree | | Repository tests | 66 tests in six suites pass at the final head with installed Pester 6.0.1 | | Scope and whitespace | Exactly five owned files differ from baseline, only Fleet changes in the correction commit, `git diff --check` passes, and the worktree is clean | | Final-head CI | [Lint](https://github.com/MSXOrg/docs/actions/runs/41833647833/job/126586882796), [Build](https://github.com/MSXOrg/docs/actions/runs/41833647833/job/126586882461), [Links](https://github.com/MSXOrg/docs/actions/runs/41833647833/job/126586882549), [Test](https://github.com/MSXOrg/docs/actions/runs/41833647833/job/126586882787), and [Cross-repository links](https://github.com/MSXOrg/docs/actions/runs/41833647533/job/126586879933) pass; Publish is skipped as configured | | Copilot review | [APPROVED for the final commit](#250 (review)), zero new inline comments; the review-wait script returns exit 0 | | Native delivery state | Remote and PR head match the final SHA; the PR is open/draft, targets `main`, and closes only the native Task; auto-merge is unset, Agent merge is disabled, and release labels are absent | The first repeated anonymous network-link run is rate-limited on five targets, which is not a broken-link result. The identical retry succeeds after the reported reset. No dependency, configuration, runtime-tool, or enforcement change is made to obtain the passing result. #105 remains separate and unresolved. The Fleet ordering contradiction is corrected in this PR rather than deferred. No blocker remains for this deliverable. This PR stays draft; do not merge it or enable auto-merge or Agent merge. </details> <details> <summary>Related references</summary> - Resolves #244 - References #105 - References #101 </details>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
Readers can find shared MSX guidance through direct, evergreen entry-point descriptions. Contributors can distinguish Markdown formatting checks from review against the Documentation Model. Commands, interfaces, and tooling do not change, and no adoption action is required. <!-- ANNOUNCEMENT STOP --> ## Changed: Entry points describe shared guidance directly The README, Home page, plugin README, and three section indexes use concrete descriptions and shorter sentences. They preserve the repository's purpose, reader groups, capability model, plugin ownership, and navigation. The vision and principles have one canonical source, and the documentation changes with the supported contract. The README identifies Zensical as the builder and GitHub Actions as the publisher. Direct task instructions remain imperative. Existing normative rules, the motto heading, the readability quotation, identifiers, and command examples retain their meaning and form. | Entry point | Before | After | | --- | --- | --- | | README | “Products change; the principles they express stay put.” | “The vision and principles have one canonical source in this repository.” | | README publication | “Published with Zensical to GitHub Pages” | “Zensical builds the documentation. GitHub Actions publishes the site to GitHub Pages.” | | Home | “The **why** lives in the Vision.” | “The **why**: the Vision defines the mission and principles.” | | Plugin README | “The shared writing entry point reaches the” | “The shared writing entry point links to the” | | Capabilities | “The independently versioned things the ecosystem builds and runs.” | “Capabilities are the independently versioned systems and tools that the ecosystem builds and operates.” | | Coding Standards | “understand the code cold” | “Write for the next person or agent without local context.” | | Ways of Working | “the answer is here” | “Use it to plan work, open issues, write commit messages, and review pull requests.” | <details> <summary>Technical details</summary> The immutable review and scoped PR base is `MSXOrg/docs@1b0d489`. The final candidate is [`MSXOrg/docs@97aa40a`](97aa40a). The complete scoped comparison contains only the seven owned documentation files, in five small pushed commits. The draft opened immediately after the first complete correction. The fixed-baseline Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and applicable artifact templates were read before editing. The official STEMG overview, FAQ, and relevant local Issue 9 rules informed the review. The supplied PDF's MD5 matches `9c720341c350ed77943b2c73d01c716f`. No reference manual is republished, and no scan or sentence count is treated as proof of full STE conformance. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `README.md` | Fixed-baseline Natural Language, Technical Writing Guide, Markdown, Documentation, and Documentation Model | Repository purpose, reader declaration, navigation, and actual Docs build/publication jobs | Fixed in this PR | | `src\docs\index.md` | The same writing baseline and navigation artifact purpose | Existing site navigation | Fixed in this PR | | `.github\plugin\README.md` | The same writing baseline and direct-instruction conventions | Existing plugin discovery and ownership contracts; identifiers and commands preserved | Fixed in this PR | | `src\docs\Capabilities\index.md` | The same writing baseline, spec/design responsibilities, and navigation artifact purpose | Documentation Model and applicable artifact templates | Fixed in this PR | | `src\docs\Coding-Standards\index.md` | The same writing baseline; existing rule force and suppression sequence preserved | Existing two-tier coding model | Fixed in this PR | | `src\docs\Ways-of-Working\index.md` | The same writing baseline and navigation artifact purpose | Existing shared process scope and audience | Fixed in this PR | **Test-first prose evidence:** the three original Task examples failed before editing, `0 passed / 3 failed`. Parent review then found an introduced actor error at candidate `e569c87f9404656efc2c478d4022e90ff7c6ba7c`: the README incorrectly said Zensical publishes the site. A fourth acceptance example failed before the narrow fix. The Docs workflow proves the separate build and publication actors. All four examples pass at the final candidate. Earlier-head results are not substituted for final-head verification. | Verification | Final-candidate evidence | | --- | --- | | Markdown lint | Existing shared configuration, all seven owned files, no issues. No package added. | | Preservation | All seven files retain headings, link destinations, all fenced examples, generated `INDEX` blocks, and non-description navigation metadata. The coding policy paragraph remains verbatim. | | Relative links | Existing checker passed across 130 documentation files. | | Cross-repository links | The final local attempt was inconclusive for five targets because the shared anonymous API quota was exhausted; no broken link was reported. All four remote target repositories were verified public. The [exact final-head CI check](https://github.com/MSXOrg/docs/actions/runs/41831112238/job/126578238584) passed with the workflow's scoped token. | | Pester | Existing Pester 6.0.1 runner: 66 passed, zero failed, zero skipped, six suites. | | Site | Restored the existing `zensical==0.0.59` requirement in an isolated session environment after the installed 0.0.50 failed the version prerequisite. Built an archive of the exact final candidate with `zensical build --clean`: no issues. No manifest changed. | | Generated output | The existing index generator ran only in the isolated candidate copy and updated only its Home table. No regenerated table entered the worktree or commits. Rendered checks passed for Home, Capabilities, Coding Standards, and Ways of Working, including the updated generated descriptions. | | Copilot review | [Clean review](#251 (review)) explicitly references final commit `97aa40a5910fdb43d69d5e883959ce1e510235b5`: APPROVED, no new inline comments. | | CI | [Final-head Docs workflow](https://github.com/MSXOrg/docs/actions/runs/41831112330): Lint, Build, Links, and Test passed. Publish is skipped for this pull request, as configured. Cross-repository links passed separately. | | Diff and persistence | Exactly seven owned paths changed. `git diff --check` passes, and the worktree is clean. All five commits are pushed. | The full read/changed/no-change inventory, source references, observed acceptance examples, technical decisions, test-first plan, and validation notes are retained in #246. All seven owned documents were read in full and changed; there is no owned file classified as unchanged. Other standards, configuration, and selected script help were read without edits. Test execution is not presented as a prose review of all test source. **Recorded contradiction:** the coding index says configuration derives from standards, “never the other way around.” The fixed-baseline Markdown standard says configuration is authoritative if they differ; Implement says repo-local config wins. This PR preserves the index policy paragraph and does not invent a precedence rule. Its enforcement language remains a normative contract, not implementation evidence. A separate standards PR can settle that conflict. **Scope and convergence:** the complete scoped diff was checked against the campaign issues, the exact entry-point title search, and the linter/enforcement search. Only #246 is fully delivered. #242 and #143 have broader asks and remain open. No other issue receives a closing reference. No source standard, executable file, test, configuration, plugin version, or generated table is changed. #240 remains excluded. The inspected Pages route does not invoke Release Management, so no release labels or release-decision block apply. No delivery blocker remains; the local quota limit is recorded with passing final-head CI evidence. The user requires draft-only handoff. The PR remains open and draft, auto-merge is absent, and Agent merge is disabled. Do not mark ready, merge, or enable either automation. </details> <details> <summary>Related references</summary> - Resolves #246 - References #242 and #143 for adjacent standards work that this entry-point change does not complete. - References #240 for excluded active code and test work. - [Fixed MSX source baseline](https://github.com/MSXOrg/docs/tree/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs) - [Official STEMG overview](https://www.asd-ste100.org/about_STE.html), [FAQ](https://www.asd-ste100.org/STE_faq.html), and [Issue 9](https://doi.org/10.5281/zenodo.23666006) </details> ## Fixed: Authoring guidance identifies formatting enforcement The contribution guide requires both the Markdown standard and the Documentation Model. It identifies the shared linter's formatting role and directs contributors to review page purpose and structure against the model. Its direct task steps and build commands retain their existing contract. No contributor setup change is required. | Before | After | | --- | --- | | “both are enforced by the shared linter configuration under `.github/linters/`.” | “The shared linter configuration under `.github/linters/` enforces Markdown formatting rules.” | | An unsupported semantic-enforcement claim. | “Review page purpose and structure against the Documentation Model.” | <details> <summary>Technical details</summary> The checked `.github\linters\.markdown-lint.yml` and `.github\workflows\Docs.yml` establish Markdown formatting checks. The contribution guide no longer claims that this configuration enforces the Documentation Model's semantic requirements. The existing relative-link and cross-repository workflows retain their documented scopes. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `.github\CONTRIBUTING.md` | Fixed-baseline Natural Language, Technical Writing Guide, Markdown, Documentation, Documentation Model, and guide/template conventions | Docs workflow, cross-repository workflow, shared Markdown configuration, and existing command contracts | Fixed in this PR | The exact contribution acceptance sentence and review instruction pass. The first complete correction passed its relevant checks before the early draft opened. The full final-candidate checks above were repeated after the source-backed README actor correction. The Task's prose implementation and validation steps are complete; the Task remains open for the requested draft review and later merge. </details>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
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. <!-- ANNOUNCEMENT STOP --> ## 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. <details> <summary>Technical details</summary> **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](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Documentation-Model.md), [Natural Language](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md), [Technical Writing Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md), [Markdown](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Markdown.md), [Documentation](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Documentation.md), and the applicable [standard template](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md#standard). Editing a source-owning page does not weaken the criteria. The official [STEMG overview](https://www.asd-ste100.org/about_STE.html) and [FAQ](https://www.asd-ste100.org/STE_faq.html) were read. The local [Issue 9](https://doi.org/10.5281/zenodo.23666006) 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](https://github.com/MSXOrg/docs/actions/runs/41833563676) | Pass: Build, Links, Lint, Test; Publish skipped for the PR | | [CI Build job](https://github.com/MSXOrg/docs/actions/runs/41833563676/job/126586592277) | Pass using the unchanged pinned `zensical==0.0.59` requirement | | [Cross-repository-link CI run 41833563852](https://github.com/MSXOrg/docs/actions/runs/41833563852) | Pass; immutable head matches this candidate | | [Final automated review](#258 (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. ```text 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](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/index.md) says configuration derives from standards. [Markdown](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Markdown.md#the-shared-configuration-is-the-source-of-truth) makes its configuration authoritative if they differ. [Implement](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Workflow-Stages/Implement.md#1-orient) 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. </details> <details> <summary>Related references</summary> - Resolves #242 - References #150 - References #186 - References #240; its scripts and tests are outside this PR </details> ## 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. <details> <summary>Technical details</summary> The official [module-manifest GUID reference](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_module_manifests?view=powershell-7.5#guid), verified against [Microsoft's immutable source](https://github.com/MicrosoftDocs/PowerShell-Docs/blob/364305cae1cd43135147df815661f0a1dddd9967/reference/7.5/Microsoft.PowerShell.Core/About/about_Module_Manifests.md#guid), 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 | </details> <details> <summary>Related references</summary> - References #260 </details>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
Repository governance guidance uses clear en-US and present-tense statements across seven policy pages and four capability pages. It explains repository context, label ownership, code-owner review, type selection, and reconciliation without idioms. Requirements and interfaces keep their meaning. The guidance distinguishes the governance contract from evidence of deployed enforcement. No adoption action is required. <!-- ANNOUNCEMENT STOP --> ## Changed: Governance guidance states its contract directly Contributors, maintainers, and agents can read the repository rules without interpreting navigation metaphors or delivery-status language. README guidance names the repository's capabilities and links to details. Repository boundaries follow ownership, lifecycle, and branch strategy. Code-owner guidance separates permission, review assignment, and required approval. The distribution example states only what its source documentation describes. The defaults-repository table defines the required contract, not verified deployment. The Artifact rationale explains the chosen one-commit-per-change policy without claiming that Git cannot inspect merge history. Type values, required files, inheritance rules, local-guide conditions, API methods, commands, migration safeguards, and normative requirements do not change. <details> <summary>Technical details</summary> **Source and scope.** The fixed expectations and scoped PR base are `MSXOrg/docs@1b0d489`. The final candidate is `MSXOrg/docs@e978a6c`, read back from local HEAD, the remote branch, and this PR. Seven small commits are pushed. The worktree is clean. The PR remains draft, unmerged, and without auto-merge. No readiness, merge, or Agent merge action is performed. The actual `Docs.yml` route builds and deploys a documentation site and does not invoke Release Management. This is a scoped documentation comparison, not a release-bound artifact comparison. No release-decision block or `release:*` label applies. **Pinned expectations.** The review uses [Documentation Model](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Documentation-Model.md), [Natural Language](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md), [Writing Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md), [Markdown](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Markdown.md), [Documentation](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Documentation.md), and applicable [specification, design, and standard templates](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md). The [STEMG overview](https://www.asd-ste100.org/about_STE.html), [FAQ](https://www.asd-ste100.org/STE_faq.html), and relevant Issue 9 rules/dictionary inform the manual review. The verified PDF and extract remain local. Mechanical checks do not establish full STE conformance. ### Full read and before/after evidence All 11 owned pages were read in full before edits and are changed. There is no owned no-change path. Each target is absent in the baseline and present in the final source and rendered page article. | Fully read and changed path | Before | After | | --- | --- | --- | | `src/docs/Ways-of-Working/Automation-Labels.md` | "the cheapest control surface" | "Labels let contributors give instructions to repository automation." | | `src/docs/Ways-of-Working/Code-Ownership.md` | "looks like an access control list and behaves like a mailing list" | "`CODEOWNERS` assigns reviewers to repository paths. It does not grant access or require approval before merge." | | `src/docs/Ways-of-Working/Organization-Standard.md` | "PSModule currently explores this" | "Its documentation describes a managed-file distribution design for the PSModule initiative, not the MSX-wide design." | | `src/docs/Ways-of-Working/Repository-Segmentation.md` | "that divergence is the seam to split on" | "When any of them differ, the parts belong in separate repositories." | | `src/docs/Ways-of-Working/Repository-Standard.md` | "first useful mental model"; "bloating the start page" | "It introduces the repository, explains its main capabilities, and links to detailed documentation."; "while the start page stays short" | | `src/docs/Ways-of-Working/Repository-Type-Property.md` | "Nothing falls out silently." | "No repository loses coverage without an explicit exclusion." | | `src/docs/Ways-of-Working/Readme-Driven-Context.md` | "Use examples liberally" | "Use examples when they make an explanation shorter or clearer." | | `src/docs/Capabilities/repository-governance/index.md` | "there is nothing per repository to drift" | "Reconciliation compares each repository with the controls its type requires." | | `src/docs/Capabilities/repository-governance/spec.md` | "Governance MUST therefore be inverted" | "A repository MUST declare its kind. The organization defines one configuration per kind." | | `src/docs/Capabilities/repository-governance/design.md` | "compares the live world" | "Delivery records provide evidence that an implementation and its enforcement satisfy this contract." | | `src/docs/Capabilities/repository-governance/design-types.md` | "This orthogonality is the point." | "Documentation publication and environment promotion are independent." | ### Technical preservation and source-qualified corrections Manual comparison preserves ownership/permission/enforcement distinctions, all Type and legacy inventory values, release-label meanings and route scope, migration ordering and verification gates, API methods/routes, commands, inherited defaults, conditional local guides, exceptions, and direct instructions. Mechanical comparison confirms unchanged page titles, headings/anchors, fenced examples, uppercase normative-term sequence, existing inline-identifier set, existing link destinations, generated index blocks, the complete spec FR/NFR block, complete Type tables, the community-default section, and the local contribution rule. The sole added destination is the verified canonical Distributor repository. Historical inventories and safe migration procedures retain their roles. The content-location paragraph becomes five- and two-sentence paragraphs. The `PSModule/Distributor` reference resolves to [MSXOrg/Distributor](https://github.com/MSXOrg/Distributor). Its [README at `3beed03f64eeafdad1c5986a14845a2b7811f929`](https://github.com/MSXOrg/Distributor/blob/3beed03f64eeafdad1c5986a14845a2b7811f929/README.md) describes managed-file distribution for PSModule. That evidence supports a documentation example, not deployed-service or conformance claims. The defaults source trees are pinned at [MSXOrg/.github@0c67251](https://github.com/MSXOrg/.github/tree/0c67251812ea306543f3a14ab473ae357cfb76ac) and [PSModule/.github@4e0092d](https://github.com/PSModule/.github/tree/4e0092de8f208b11e0d4607ced93471607aa748e). The first contains a PR-template file despite the target policy. The design therefore states the contract rather than claiming that linked repositories prove compliance. External template cleanup is excluded. An anonymous Git-object experiment joins five feature commits and an independent main-branch change. `git bisect run` finds feature 3 as the first bad commit; `git log v0..v1` includes all five feature changes. Verified LF fixtures and a predicate that aborts on invalid input make the result reproducible. This disproves the absolute failure explanation, not the chosen Artifact history policy. The [Git bisect manual](https://git-scm.com/docs/git-bisect) supplies command semantics. No project code or credentials are used; the temporary experiment is removed. ### Validation | Check | Result at the final source | | --- | --- | | Test-first prose examples | All 11 targets are absent before and present after; all 11 render in their page articles. | | Preservation and scoped diff | All 11 owned paths pass; no out-of-scope change. | | Markdown | `markdownlint-cli2` 0.24.0, shared configuration, all 11 explicit paths, zero issues. | | Relative links and anchors | Existing checker passes across 130 Markdown pages. | | Cross-repository links | Existing checker resolves eight links across 134 Markdown files. A shared anonymous API limit is resolved by a passing authenticated-rate-limit rerun, not a checker change. | | Pester | Existing runner, pinned Pester 6.0.1 and expected GUID; 66 passed in six suites; zero failed, skipped, inconclusive, or not-run. | | Site | Exact `zensical==0.0.59`; final-source archive; CI index generation in an isolated copy; no build issues; 131 HTML pages. All 11 owned pages, H1s, target text, generated descriptions, and Distributor link are verified. | | GitHub CI | [Lint](https://github.com/MSXOrg/docs/actions/runs/41832073152/job/126581632773), [Build](https://github.com/MSXOrg/docs/actions/runs/41832073152/job/126581633322), [Links](https://github.com/MSXOrg/docs/actions/runs/41832073152/job/126581633022), [Test](https://github.com/MSXOrg/docs/actions/runs/41832073152/job/126581632965), and [Cross-repository links](https://github.com/MSXOrg/docs/actions/runs/41832073331/job/126581482626) succeed. Publish is skipped for the PR as expected. | | Draft review | Existing review script exits 0: [APPROVED at the final head](#259 (review)), zero new inline comments, clean round. | The shared installed Zensical `0.0.50` is not used as a substitute. The exact existing requirement is restored in isolated session storage without changing the manifest or shared environment. Source index tables are not regenerated or committed; only the build copy receives generated tables. ### Standards and framework alignment | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Seven owned governance policy pages | Fixed-baseline Natural Language, Writing Guide, Markdown, Documentation, Documentation Model, standard template; official STEMG explanations and relevant Issue 9 rules/dictionary | Repository-governance spec/design/types and ownership, inheritance, contribution, and audience contracts | Fixed in this PR | | Governance index and spec | Same fixed-baseline writing/model standards; specification template | Type-property mechanism and the seven policy pages; FR/NFR text retained verbatim | Fixed in this PR | | Governance design and type catalog | Same fixed-baseline writing/model standards; design template | Governance spec, Type-property mechanism, repository/community-file rules, code-owner eligibility, and source-qualified examples | Fixed in this PR | | Retained normative conflicts | No new policy is inferred from a prose correction | Conflicting clauses remain recorded in the Task | Exception - #247 | ### Unresolved policy choices and exclusions These choices remain explicit and unchanged. They need a separate policy PR, not an inferred writing decision. | Sources | Unresolved choice | | --- | --- | | Organization Standard versus Repository Standard | Initiative specialization must not contradict this site, but initiative overrides govern their repositories. | | Repository Types versus Repository Standard | The Unmanaged discoverability minimum names a security policy in one place and contribution guidance in the other. | | Design selection table, exclusion-only rule, Type-property guidance, and NFR5 | Included-value layering selectors coexist with an exclusion-only/additive-extension contract. | | FR8 versus the automated-review design row | Every-PR automatic review versus default-branch scope. | The closing Task's prose, preservation, validation, and durable-evidence steps are complete. All shared indexes, other documentation parts, functional scripts/configuration/tests, dependencies, and paths reserved by #240 remain unchanged. No repository audit/planning files, new tooling, restructuring, or external enforcement cleanup is added. No complete STE certification or deployed-reconciliation claim is made. The scoped convergence query `repo:MSXOrg/docs is:issue is:open "repository governance" in:title,body` returns only the closing Task. No additional issue receives a closing link. There is no remaining blocker for this writing deliverable; this PR stays draft by request. </details> <details> <summary>Related references</summary> - Resolves #247 - References #240 for excluded code/test ownership </details>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
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. <!-- ANNOUNCEMENT STOP --> ## 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. <details> <summary>Technical details</summary> **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](#245 (comment)) 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. </details> <details> <summary>Related references</summary> - Resolves #245 - References #240 for the excluded active tooling work </details>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
Deployment guidance states the approved-effect contract in direct,
evergreen, en-US prose. Contributors, reviewers, operators, and their
agents get a clear explanation of one approval for the code and every
environment's resource effect, followed by deployment of exactly that
approved effect. No consumer action or deployment change is required.
<!-- ANNOUNCEMENT STOP -->
## Changed: Deployment guidance explains approval and resource effects
directly
The spec replaces vague and time-dependent explanations with concrete,
present-tense statements. The indexes distinguish the
technology-independent contract from each combination-specific design.
The Azure-from-GitHub design explains saved plans, state validity,
identity, emergency access, and audit records without idioms. Direct
procedures retain direct commands.
The approved-effect, reapproval, fail-closed, concurrency, emergency,
audit, environment, trust, and state contracts remain unchanged. This PR
changes guidance, not deployment behavior or enforcement. The DORA
statements describe intended outcomes, not measured implementation
results.
<details>
<summary>Technical details</summary>
**Immutable scope.** MSXOrg/docs
`1b0d4893c8fefabe604d04393068a8ff6f848082` to
`41fe0058730ba9fc759c211aac124ea135813176`. Four small commits change
only the four assigned Markdown pages: 218 insertions and 215 deletions.
The final head is pushed and the worktree is clean. This is a scoped
documentation-change record, not an artifact-release record. The
effective workflows validate and publish a Zensical site and do not
invoke Release Management.
**Full reads and changed paths.** Every owned page was read in full
before editing and the full baseline-to-head diff was reviewed after
editing. No whole owned page remains unchanged.
| Fully read and changed page | Change | Exact no-change content |
| --- | --- | --- |
| `src/docs/Capabilities/deployment/spec.md` | Premise, enduring
problem, outcomes, and requirement explanations | Front matter, Gherkin,
inline code, links, 14 FR/NFR IDs/anchors, and normative keyword force
per requirement |
| `src/docs/Capabilities/deployment/index.md` | Approval sequence and
spec/design relationship | Front matter, table rows, navigation, and
links |
| `src/docs/Capabilities/deployment/designs/index.md` | Design/spec
relationship | Front matter, generated INDEX table, and links |
| `src/docs/Capabilities/deployment/designs/azure-from-github.md` |
Mechanism explanations, en-US spelling, and direct operational steps |
Front matter, Mermaid, YAML, ordered inline identifiers/commands, links,
reference URLs, and headings |
**Concrete before/after evidence.**
| Before | After |
| --- | --- |
| `first-class, reviewable thing` | `Before deployment, the process
computes and shows the effect on every environment in the promotion
path.` |
| `Problem and why now` | `Problem {#problem-and-why-now}` |
| `from a proposal to live` | `The team approves the code change and all
these effects as one decision.` |
| `Entra rides the Azure identity context` | The design states that the
`azuread` provider uses the same federated token and Azure identity
context, with no separate Entra ID secret. |
| `native backstop` | `This state check is the native guard for FR5.`
The requirement remains linked. |
| `serialised`, `authorised`, `cancelled`, `serialisation`, `defence` in
prose | `serialized`/`serializes`, `authorized`, `canceled`,
`serialization`, `defense` |
**Technical-meaning review.** Each original FR/NFR and design mechanism
was compared with the edited text. NFR2 retains distinct read-only and
environment-scoped write **forms of access**; it does not add a
separate-principal policy to the spec. The design keeps its existing
two-identity mechanism. The complete review retains exact approved plans
and hashes, per-environment state serial/lineage, reapproval after
invalidation, no concurrent or interrupted applies, required tests,
restricted emergency access with reason/incident/follow-up, immutable
attribution, drift, OIDC, and trust boundaries.
**Preservation and anchor evidence.** A one-time baseline comparison
confirms three exact fenced blocks, one exact generated block, unchanged
front matter, ordered inline code, Markdown link targets, autolinks, and
all 14 requirement IDs/anchors. The MUST/MUST NOT/SHOULD sequence is
unchanged within every requirement. Only the Problem heading and FR6
spelling change. The old **published-site** `problem-and-why-now`
attr_list ID and all 14 FR/NFR IDs appear exactly once in the actual
final CI-built HTML. GitHub implicit-heading-anchor compatibility is not
claimed. No tracked links depended on the old implicit Problem or FR6
heading slug, so no cross-owned repair is needed.
**Validation.** Repeatable commands and full results are also retained
in the delivery Task.
| Check | Command or evidence | Result |
| --- | --- | --- |
| Markdown | Existing `markdownlint-cli2` with `--no-install`,
`.github/linters/.markdown-lint.yml`, and the four explicit owned paths
| Four files; zero issues |
| Relative links and anchors | `pwsh -NoLogo -NoProfile -File
.\.github\scripts\Test-DocumentationLink.ps1` | All links resolve across
130 files |
| Cross-repository links | `pwsh -NoLogo -NoProfile -File
.\.github\scripts\Test-CrossRepositoryLink.ps1` | Seven links resolve
across 134 files |
| Local site | `zensical build --clean --config-file
.\src\zensical.toml` | Existing local Zensical **0.0.50**; no issues;
not the repository's pinned version |
| Pinned site and anchors | Final CI installs **Zensical 0.0.59** from
`requirements.txt`; build succeeds; actual `github-pages` artifact
inspected | Old published Problem ID and all 14 requirement IDs appear
exactly once |
| Existing repository tests | `pwsh -NoLogo -NoProfile -File
.\.github\scripts\Invoke-PesterSuite.ps1` | Existing Pester 6.0.1; 66
tests in six suites pass; none skipped |
| Whitespace and ownership | `git diff
1b0d489
41fe005 --check` and changed-path
comparison | Clean; only the four owned pages change |
| Pre-edit prose review probe | Same scoped search outside fenced
examples, before and after | 12 observed phrase/spelling findings
before; zero after; not a full STE-conformance test |
| Draft review | Existing `Wait-CopilotReview.ps1` after each push |
Final round APPROVED on `41fe0058730ba9fc759c211aac124ea135813176` at
2026-11-04T12:46:42Z; zero new inline comments |
| Final-head GitHub checks | [Docs
run](https://github.com/MSXOrg/docs/actions/runs/41831680111) and
[cross-repository links
run](https://github.com/MSXOrg/docs/actions/runs/41831680125) | Lint,
Build, Links, Test, and Cross-repository links pass; Publish is skipped
for this PR |
The pinned-build anchor evidence comes from artifact ID `13321579755`,
name `github-pages`, from the successful final-head Docs run. The
inspected TAR member is `./Capabilities/deployment/spec/index.html`; its
SHA-256 is
`067e56568d4c80dcdc3f94b6893e4391f3c12c79ca8ec1bad91146091b597eec`. The
artifact TAR SHA-256 is
`5910dc357989b5fbeef7610a4bc07c594cf788fbcfe1f7292acd27334e26e69a`. This
verifies the actual pinned output instead of treating the older local
installation as equivalent. No local dependency upgrade or new tooling
is needed.
The final anonymous cross-link attempt hit the shared GitHub API quota
and reported five unresolvable links, not broken targets. A retry with
the existing GitHub CLI credential in process-local `GITHUB_TOKEN`
passes. A transient second-commit push rejection also resolves with an
ordinary fast-forward retry. No history rewrite, dependency
installation, or credential persistence is used.
**Standards and framework alignment.** Criteria were derived before
edits from the fixed-commit Documentation Model, Natural Language,
Writing Guide, Markdown, Documentation, and spec/design templates linked
in the Task. The official STEMG overview/FAQ and relevant Issue 9 rules
and dictionary entries were consulted. The local PDF hash matches the
verified reference; the PDF and extract remain local. These checks do
not certify full ASD-STE100 conformance.
| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| Deployment spec | Fixed-baseline documentation/writing standards and
specification template; relevant official STE guidance | Original
Deployment spec and Azure design | Fixed in this PR; normative meaning
retained |
| Both deployment indexes | Same writing standards and
navigation/generated-content rules | Deployment spec/design relationship
| Fixed in this PR; metadata and generated content retained |
| Azure-from-GitHub design | Same writing standards and design template;
direct procedural writing | Original deployment requirements and
mechanisms | Fixed in this PR; native contracts retained |
**Delivery plan and convergence.** The delivery Task's source review,
full reads, test-first prose-verification plan, spec/index/design steps,
final full-diff review, and checks are complete. The issue retains the
detailed source and before-text evidence. A narrow open-issue search for
`deployment in:title` finds only the delivery Task; no additional issue
is fully resolved by this diff.
**Exclusions and limitations.** No other capability, shared index,
process page, code, configuration, or test file changes. #240
remains outside scope. Frozen Gherkin spelling, Mermaid labels, YAML
comments, exact commands, technical terms, and generated content are
accepted differences. No live Azure or Terraform deployment was
attempted. Normative design intent is not proof of implementation or
enforcement. No remaining substantive contradiction was identified in
the owned pages, and there is no remaining blocker.
The PR remains **draft**. It is not marked ready or merged, and
auto-merge and Agent merge are not enabled.
</details>
<details>
<summary>Related references</summary>
- Resolves #249
- References [fixed-baseline criteria, initial observations, and
delivery evidence](#249)
</details>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
GitHub Actions guidance uses direct en-US instructions and present-tense explanations. It states the authoring rules separately from the checks that can detect violations. This guidance-only change preserves the extraction requirement, required CI, blocking criteria, security boundaries, compatibility, commands, and examples. No workflow behavior or consumer action changes. <!-- ANNOUNCEMENT STOP --> ## Fixed: Workflow authoring guidance states rules and lint coverage clearly The standard separates long explanations into direct statements and ordered instructions. The manual pin-audit section lists its use cases, prerequisites, exclusions, and explicit failure result. Job structure, action reuse, and diagnostics retain their existing contracts. The lint descriptions correct two factual coverage errors, not policy questions. actionlint can pass inline Bash/sh scripts to ShellCheck when the integration is enabled and the executable is available. That integration does not check PowerShell or Python; Python can have a separate optional Pyflakes integration. Standalone files provide native-language context for broader linting, formatting, type checks, security scanning, and editor features. Non-trivial scripts still require extraction into an action. Lint results do not prove compliance with every authoring rule. The page requires review alongside the existing CI checks and points to its skipped-dependency guidance. Required CI execution and blocking/severity rules are unchanged. Only the separate-versus-colocated workflow/action-library choice remains an unresolved policy question. <details> <summary>Technical details</summary> ### Scope and immutable sources Only `src/docs/Coding-Standards/GitHub-Actions.md` changes. The complete baseline page was read (1,265 lines), followed by the complete first writing result (1,364 lines). The narrow factual correction and surrounding sections were then read against the verified upstream sources. The resulting page has 1,372 lines. - Fixed criteria and scoped PR base: `1b0d4893c8fefabe604d04393068a8ff6f848082`. - Previous writing head: `0ba76283ef113db4eef91dda970f96486ee5a61d`. - Final reviewed and pushed candidate: `28947e5248f162cd358a0b1fc45c7587fe60aa20`. - Six logical commits are pushed. The draft opened after the first complete improvement, `6fa38a06c69261d31b314cac60976e4fb2f559a5`. - The coverage correction is one small commit: 16 added lines and eight removed lines in the owned page. The closing Task pins the Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and standard/guide templates at the fixed source. Official STEMG overview/FAQ and relevant local ASD-STE100 Issue 9 rules/dictionary were consulted. The PDF MD5 is `9c720341c350ed77943b2c73d01c716f`. Reference copies stay local. Automated observations and counts do not establish full STE conformance. ### Verified lint coverage and experiment limits Official actionlint evidence is fixed at `rhysd/actionlint@011a6d15e749bb3f2d771eed9c7aa0e7e3e10ee7`: - [ShellCheck integration](https://github.com/rhysd/actionlint/blob/011a6d15e749bb3f2d771eed9c7aa0e7e3e10ee7/docs/checks.md#check-shellcheck-integ) documents Bash/sh support, executable discovery, and explicit disabling. - [The dispatcher](https://github.com/rhysd/actionlint/blob/011a6d15e749bb3f2d771eed9c7aa0e7e3e10ee7/rule_shellcheck.go) sends supported scripts to ShellCheck and skips unsupported shells. - [The official inline-script fixture](https://github.com/rhysd/actionlint/blob/011a6d15e749bb3f2d771eed9c7aa0e7e3e10ee7/testdata/examples/shellcheck_integration.yaml) and [expected output](https://github.com/rhysd/actionlint/blob/011a6d15e749bb3f2d771eed9c7aa0e7e3e10ee7/testdata/examples/shellcheck_integration.out) show SC2086 at lines 6 and 14 for Bash, not the default Windows PowerShell step at line 12. - [Pyflakes is a separate integration](https://github.com/rhysd/actionlint/blob/011a6d15e749bb3f2d771eed9c7aa0e7e3e10ee7/docs/checks.md#check-pyflakes-integ). The ShellCheck limitation is not a claim that actionlint has no Python support. Eight source/fixture consistency observations pass. No local actionlint/ShellCheck execution is claimed: neither native executable is available, the Docker Linux engine is unavailable, and its WSL distribution is stopped. No tool was installed and no runtime was started. The official sources and independent expected diagnostics establish the correction. ### Concrete before and after cases | Concern | Before | After | | --- | --- | --- | | Opening | `held to the same bar as application code` | `Workflow authors apply the application-code standards and the supply-chain and least-privilege controls below.` | | Manual audit | One sentence combines the instruction and three cases. | A short instruction, three separate use cases, and separate prerequisites, exclusions, and failure handling. | | Inline lint capability | Tools `cannot process that script as code`. | `actionlint can send inline Bash and sh scripts to shellcheck` when enabled and available. ShellCheck does not lint PowerShell/Python. | | Standalone files | Tools can process code `only when it is in a file of its own language`. | Native-language/file context supports language-specific linters, formatters, type checkers, security scanners, and IDE features. | | ShellCheck scope | `the shell of every run: step through shellcheck` | Only inline Bash/sh scripts through that integration; no implied PowerShell/Python coverage. | | CI coverage | `A workflow that breaks this standard fails the build.` | `The linters do not detect every violation of this standard.` Review authoring rules and skipped dependencies as well as lint results. | | Diagnostics | `An action is a black box until it fails.` | `An action reports what it reads, decides, and produces on every run.` | ### Exact preservation and accepted differences All 31 fenced examples retain identical content and order after Git newline normalization. Their combined SHA-256 remains `f7d2fe9b4c16bd22690553fe56a833ab0c9b4ccc19d0e86077fb434531a59214`. All 38 headings/anchors, 270 inline-code spans, front matter, and uppercase normative terms (`MUST`, `MAY`, `MUST NOT`) remain unchanged from the fixed campaign baseline. All 42 original link destinations remain. Only two references are added: official ShellCheck integration documentation and the existing skipped-job section anchor, for 44 total destinations. No existing heading or anchor changes. The complete non-trivial-script extraction bullet, required push/PR CI execution statement, blocking/severity rules, and both repository-layout policy sections are exactly unchanged from `0ba76283ef113db4eef91dda970f96486ee5a61d`. Manual review preserves lower-case obligations, owned-major exceptions, external SHA requirements, compatibility, permissions/token scope, OIDC, untrusted-input controls, GHES exclusions, cancellation/result checks, and explicit failure behavior. Direct imperatives, technical terms, native YAML/PowerShell, placeholders, comments, historical example evidence, and stable headings remain accepted differences. This includes `behaviour` in a heading/anchor and the time-dependent concurrent-step title. Other standards, navigation, generated indexes, workflows, scripts/tests, configuration, dependencies, and #240 surfaces are untouched. ### Final-head validation The initial writing observations had seven expected failures. For this factual revision, six observations fail at the previous head before editing; all 24 final temporary assertions pass. No repository prose-policy tests or new tooling are added. | Check | Result at 28947e5 | | --- | --- | | Existing Markdown configuration | Pass: one owned page, zero issues | | Relative links and anchors | Pass: 130 files | | Scoped cross-repository links | Pass: one link in the owned page | | Existing Pester runner | Pass: 66 tests across six suites, zero failures or skips; existing installation only | | Exact examples/requirements comparison | Pass: all 24 observations, including extraction/CI/severity/layout-policy guards | | Docs CI | [Pass at the exact final head](https://github.com/MSXOrg/docs/actions/runs/41834436294) | | Cross-Repository Links CI | [Pass at the exact final head](https://github.com/MSXOrg/docs/actions/runs/41834436520) | | Pinned site build | [Build job passed](https://github.com/MSXOrg/docs/actions/runs/41834436294/job/126589598658); logs confirm installation of Zensical 0.0.59 and `No issues found` | | Actual CI site output | Artifact `13325290117` passes ten render observations: all 31 examples match source, corrected claims and extraction requirement render, both new references render, false descriptions are absent, and checked stable anchors remain | | New explicitly requested review | [Approved at the exact final head](#264 (review)), zero new inline comments; review-loop exit 0 | | Remote and worktree | Remote head matches the candidate; worktree is clean | Earlier local site checks at `0ba7628` remain historical evidence, not proof for this head. The existing final-head CI build and its downloaded artifact provide the new pinned-site evidence without local tooling or runtime changes. The temporary downloaded site artifact was removed after inspection. Source/fixture, comparison, render, build-log, and review evidence remain local and are summarized here and in the Task. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | GitHub Actions standard prose | Fixed documentation/writing standards and templates; official STE sources; immutable actionlint documentation/source/fixtures | None (no framework-specific docs) | Fixed in this PR | The two false coverage descriptions are corrected in this PR. They are no longer deferred as policy. The remaining layout question contrasts the separate-repositories/self-checkout-last-resort guidance with the colocated-action/self-checkout-required guidance. Those sections remain unchanged for an owner decision. All assigned writing, source verification, preservation comparisons, final-head validation, and automated review are complete. No writing or validation blocker remains. The live local ShellCheck experiment was unavailable and is not claimed. The prior scoped convergence search found this Task and #242, which excludes this page; no extra closing reference applies. **Delivery boundary:** Leave the PR DRAFT. No ready, merge, auto-merge, or Agent merge action was taken. The Task stays open for later review and merge. </details> <details> <summary>Related references</summary> - Resolves #243 - References #242 - References #240 for excluded code/test ownership </details>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
Agentic development guidance uses direct en-US and present-tense explanations for context ownership, runtime integration, shared tools, named intents, advisory work, and conformance. The supported contracts and executable examples remain intact. No runtime, configuration, or adoption change is required. <!-- ANNOUNCEMENT STOP --> ## Changed: Agentic development contracts have literal explanations Contributors, maintainers, integrators, and agents can identify which files own context, how index navigation works, and how runtime mechanics remain separate from process. The template commentary also distinguishes the `msx` plugin from the `msxorg` marketplace. This is changed guidance, not evidence that a runtime or enforcement mechanism was implemented. The specification retains its requirements, the design retains its mechanisms, focused pages retain their reference/addendum purpose, and the decisions index retains its historical-record semantics. Direct imperative instructions remain direct. Existing policy ambiguities are recorded rather than resolved by this prose change. <details> <summary>Technical details</summary> ### Immutable scope and review sources The complete scoped comparison is `MSXOrg/docs@1b0d489` to `MSXOrg/docs@ab46f17`. Five small logical commits are pushed, and the remote branch matches the candidate. The draft opened after the first complete design improvement. The final worktree is clean. Criteria were derived from the fixed baseline before editing: [Documentation Model](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Documentation-Model.md), [Natural Language](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md), [Technical Writing Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md), [Markdown](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Markdown.md), [Documentation](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Documentation.md), and the applicable [artifact templates](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md). These are the shared writing rules in the table below. The official [STEMG overview](https://www.asd-ste100.org/about_STE.html), [FAQ](https://www.asd-ste100.org/STE_faq.html), and verified local [Issue 9](https://doi.org/10.5281/zenodo.23666006) rules and dictionary were consulted. The local PDF MD5 is `9c720341c350ed77943b2c73d01c716f`, matching the campaign frame. Reference copies and extracted text remain local. Manual review and automated checks do not establish full STE conformance. ### Fully read paths and standards alignment All 12 owned pages were read fully. Eleven changed; the marketplace design is a justified no-change page. `Fixed in this PR` identifies changed prose, not a runtime implementation. | Fully read surface | Standards checked | Capability contract checked | Result | | --- | --- | --- | --- | | `src/docs/Capabilities/agentic-development/spec.md` | Shared writing rules; specification template | Organization boundary, requirement labels, freshness failures, normative force, success criteria, and nine-layer context order | Fixed in this PR | | `src/docs/Capabilities/agentic-development/design.md` | Shared writing rules; design template | Context ownership, reading/authority order, thin routes, client behavior, and freshness | Fixed in this PR | | `src/docs/Capabilities/agentic-development/design-plugin-marketplaces.md` | Shared writing rules; design template | Marketplace ownership, co-location, writing and upgrade discovery, layout, and versions | Aligned; complete file unchanged | | `src/docs/Capabilities/agentic-development/mcp-servers.md` | Shared writing rules; focused reference purpose | Shared server set, native declarations, credentials, authentication failure, and process ownership | Fixed in this PR | | `src/docs/Capabilities/agentic-development/runtime-integration.md` | Shared writing rules; focused reference purpose | Entry/lifecycle/tool/identity obligations, runtime shapes, setup failures, and permissions | Fixed in this PR | | `src/docs/Capabilities/agentic-development/plugin-distribution.md` | Shared writing rules; focused reference/addendum purpose | Pointer-only intents, portable package boundaries, marketplace discovery, commands, and manifests | Fixed in this PR | | `src/docs/Capabilities/agentic-development/agent-interaction.md` | Shared writing rules; focused reference purpose | Durable artifacts, Task/Bug technical plans, label ownership, agent-reviewing-agent scope, and human merge authority | Fixed in this PR | | `src/docs/Capabilities/agentic-development/advisory-agents.md` | Shared writing rules; focused reference/addendum purpose | Seed-once labels, final human overrides, idempotence, required-early-run scope, attribution, and independent advice | Fixed in this PR | | `src/docs/Capabilities/agentic-development/conformance.md` | Shared writing rules; focused reference purpose | Mandatory baseline, conformance levels, allowed additions, exemptions, and remedies | Fixed in this PR | | `src/docs/Capabilities/agentic-development/AGENTS.template.md` | Shared writing rules; template/instruction format | Router order, local configuration boundary, inherited contribution source, and client routes | Fixed in this PR; executable fence unchanged | | `src/docs/Capabilities/agentic-development/index.md` | Shared writing rules; documentation navigation model | Organization scope and context navigation | Fixed in this PR; generated INDEX block unchanged | | `src/docs/Capabilities/agentic-development/decisions/index.md` | Shared writing rules; decisions-register and decision-record semantics | Empty record inventory and immutable supersession history | Fixed in this PR; history semantics unchanged | ### Concrete before and after evidence | Page | Before | After | | --- | --- | --- | | `design.md` | "plugs into the same shape" | "An adopting organization uses the same model on a public or enterprise GitHub host." | | `design.md` | "the contract lives, it just lives in the file a human would read" | "Each repository-specific contract remains in the file that owns it." | | `design.md` | The agent "drills inward". | "The agent follows index links until it reaches the relevant page." | | `runtime-integration.md` | "integration work is plumbing" | "A runtime supplies capabilities and lifecycle points, not process rules." | | `mcp-servers.md` | "None of that is worth fighting." | "Each runtime uses its native configuration syntax for the same server contract." | | `plugin-distribution.md` | "drift with extra steps" | "A bundled procedure is a snapshot that can differ from its canonical source." | | `advisory-agents.md` | "This gives the agent exactly one turn to speak." | "The agent supplies an initial assessment only when no label from the set exists." | | `agent-interaction.md` | "The separation earns its keep at rejection." | "The issue preserves the request when reviewers reject a proposed implementation." | | `AGENTS.template.md` | "The shared `msxorg` Agent Plugin" | "The shared `msx` Agent Plugin from the `msxorg` marketplace provides skills that point to canonical documentation pages." | | `spec.md` | "Applies to any organization that wants a shared project knowledge base for agents across multiple repositories." | "The framework applies to organizations that share agent context across repositories." | | `conformance.md` | "A framework that cannot be checked is a preference." | "Conformance defines the required files, context resolution, and duplication limits for a repository." | | `decisions/index.md` | "There are currently no decisions recorded for this capability." | "No decision records are listed for this capability." | All 12 expected after-text examples were absent before editing and present in the immutable candidate. The final meaning review also defined two scope counterexamples before correction: the required early-run trigger and an agent reviewing another agent's work. Both explicit actor/trigger checks pass. The intent-copy check compares procedure content instead of treating every documentation change as evidence of copying. ### Validation and preserved behavior | Check | Final result | | --- | --- | | Existing Markdown lint | Passed for all 12 owned files with `markdownlint-cli2` 0.24.0 / `markdownlint` 0.42.0 and the repository configuration. `npx --no-install` used existing tooling. | | Relative links and anchors | Passed for 130 files in the checkout and again after index generation in the temporary immutable snapshot. No cross-owned link repair is needed. | | Cross-repository links | Repository-level check passed: 7 applicable targets across 134 files. The earlier owned-path run found zero applicable targets and exited 1; that run is not reported as a pass. | | Existing Pester suites | Final candidate: 66 passed, 0 failed, 0 skipped across 6 suites with the existing pinned Pester 6.0.1. No dependency was added or upgraded. | | CI-equivalent site build | Archived the exact candidate locally, ran the existing index generator and relative-link check, then `zensical build --clean`. Build reported no issues. Regenerated copies stayed in the temporary snapshot and were removed after verification. | | Rendered output | Verified the design adoption statement, template plugin/marketplace distinction, regenerated index en-US spelling, and preserved `indexes-as-the-mindmap` anchor. | | Source preservation | All 12 pages retain headings/anchors, full fenced content, generated INDEX bytes, link targets, normative-force sequence, requirement labels, navigation titles, and exact inline identifiers. Runtime/client/conformance/intent tables, spec success criteria, the complete context-order section, and the marketplace design are unchanged. `git diff --check` passes. | | Final-head CI | [Docs run](https://github.com/MSXOrg/docs/actions/runs/41831513197): Lint, Links, Test, and Build passed; Publish skipped as expected for a PR. [Cross-repository links run](https://github.com/MSXOrg/docs/actions/runs/41831513145) passed. Both apply to `ab46f17c8427780dd9c207087997b7838452560c`. | | Existing Copilot review loop | [Clean review](#265 (review)) on the exact final commit: APPROVED, zero new inline comments, helper exit 0. This remains advisory and does not change draft state. | The complete diff was reviewed for technical meaning in addition to the preservation checks. These results do not prove full ASD-STE100 conformance, runtime behavior, or semantic enforcement by CI. ### Accepted differences, contradictions, and exclusions Exact technical nouns, native syntax, identifiers, direct imperative template/procedure instructions, normative obligations, and historical decision semantics are retained. The `Indexes as the mindmap` heading remains to preserve its heading and anchor; its explanatory prose is literal. Existing artifact layouts remain intact instead of being restructured to recopy a template. Source INDEX tables remain unchanged; CI regenerates them from the edited front matter. Four baseline contract questions remain outside this prose change: - The spec prohibits restating host/org/repo coordinates in a router, while context-resolution step 3 says the router identifies host and organization. - Conformance requires a router precedence statement; the fenced template omits it, the design example includes it, and the spec limits router content. - The canonical-context freshness gate requires the fetched default-branch head, while the review-time table cites head-branch instructions. Their scopes need explicit clarification. - Runtime guidance says advisory-only work needs no write access, while advisory outputs can apply labels. Branch-content writes and artifact writes are not distinguished. The existing outside-contribution instruction-trust question remains in #123. None of these questions is converted into invented policy or implementation evidence. A separate contract-alignment change is the appropriate follow-up. Only `src/docs/Capabilities/agentic-development/**` changes. Shared plugin routers/manifests, actual root/client agent files, plugin README, shared index source pages, other capability parts, configuration, executable code, and tests are excluded. #240 retains its code/test ownership. No repository audit/planning file, enforcement tool, or dependency was added. The issue convergence pass searched open issues matching `agentic in:title,body` and `router in:title`, then checked the existing trust-boundary issue. No additional issue is fully resolved by this diff: #101 requires a defect-tracking contract; #187 requires router-link enforcement; #123 requires trust-boundary findings. The sibling capability-writing Task returned by the search belongs to another part. Only #248 has a closing reference. The Task's source review, test-first prose verification, five pushed increments, complete-diff meaning review, final checks, and durable evidence are complete. There is no blocker for the requested prose work. The app-managed branch name and continued draft state follow the explicit campaign instructions. The PR remains **draft**. GitHub auto-merge is null. Agent merge is disabled and `merge_pr` is false. No mark-ready or merge action was taken. The Docs route publishes a website and does not invoke Release Management; no release-decision block, release label, or versioned publication baseline is manufactured. </details> <details> <summary>Related references</summary> - Resolves #248 - References #123 for the existing instruction-trust boundary. - References #187 for router-link enforcement outside this prose scope. - References #101 for a separate defect-tracking contract. - References #240 as the excluded code/test workstream. </details>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
Release and downstream propagation guidance uses direct en-US statements for publication hazards, recovery, consumer qualification, and delegation. Contributors, operators, and consumers can read each condition separately. No release behavior, setting, permission, command, or consumer policy changes, and readers do not need to change configuration or references. <!-- ANNOUNCEMENT STOP --> ## Changed: Release and consumer handoff guidance is explicit The release spec separates partial publication, mutable pull-request metadata, and advancing source. It retains all three consequences of recomputing from current state: different bytes under a reserved version, omitted accumulated changes, and advertising an incomplete release. The lifecycle design separates reservation and consumer-change baselines without changing their version example or publication lineage. Publishing-target prose separates completion, retry, and withdrawal explanations. The moved-tag guide states the trusted-remote check and exact-version-tag safeguard directly. Propagation guidance describes outdated references without idioms and separates prompt context, qualification, paused execution, completion, and failure. Guide instructions remain imperative. These changes clarify the documented target-state contract; they do not prove that a producer implements or enforces it. <details> <summary>Technical details</summary> ### Scope and immutable evidence The fixed review baseline and scoped PR base are `1b0d4893c8fefabe604d04393068a8ff6f848082`. The completed prose head is `21c7794d00990954e059de2d7e82cbf48ebf2512`. The scoped comparison is `git diff 1b0d489 21c7794 -- src/docs/Capabilities/release-management src/docs/Capabilities/downstream-release-propagation`. All eight assigned pages were read in full and changed. There are no unchanged owned pages. Only these eight paths differ from the baseline. Front matter, shared indexes, scripts/tests, workflow/configuration, dependencies, and the paths owned by #240 are unchanged. Both generated INDEX blocks are byte-identical; only handwritten index prose changes. No restructure, new tooling, or enforcement is added. ### Concrete before/after evidence | Surface | Before | After | | --- | --- | --- | | Release spec Problem | “Publication can expose one destination before another fails, mutable pull-request metadata can change before a retry, and a later commit can reach the stable branch while an earlier artifact is still incomplete.” | “Publication can expose one destination before another fails.” “Mutable pull-request metadata can change before a retry.” “A later commit can reach the stable branch while an earlier artifact is still incomplete.” All three recomputation consequences remain immediately after these statements. | | Release announcements | “attempts and acknowledgements”; “If acknowledgement is missing, it may resend the same logical message; receivers therefore observe…” | “attempts and acknowledgments”; “If acknowledgment is missing, it may resend the same logical message. Receivers therefore observe…” At-least-once delivery and deduplication by release identity remain. | | Publishing targets | “Durable per-target progress keeps the release incomplete until all required targets succeed, then lets a retry resume safely.” | “Durable per-target progress keeps the release incomplete until all required targets succeed. A retry uses that progress to resume safely.” | | Moved-tag guide | “Confirm that `origin` is the intended trusted producer and that no exact-version-tag integrity incident is being normalized.” | “Confirm that `origin` is the intended trusted producer. Do not use this procedure to accept a moved exact version tag.” All backup, pruning, force-fetch, trust-boundary, and verification commands remain exact. | | Propagation spec | “A reference drifts the moment the producer cuts a release.” | “A producer release can make a reference outdated.” The surrounding prose retains the security-fix and runtime-failure risks and mandatory assessment of every dependent. | | Propagation design | “The notification runs in the **producer** when a release is cut.” | “The notification runs in the **producer** after a stable release.” Stable-only event/backfill gates and both delegation modes remain unchanged. | ### Preservation and semantic review A one-off read-only comparison against the fixed baseline confirms unchanged front matter, heading/anchor lines, links, inline-code sequence, all 40 fenced blocks, all 182 BCP 14 keyword occurrences in their original sequence, and both generated INDEX blocks. The complete release-spec requirements and scenarios, from `## Requirements` through the end of the page, are byte-identical. All eight test-first prose acceptance examples pass after reporting eight expected failures before editing. The five selected hazard/consequence sentences contain 8-16 whitespace-delimited words; that check is not a full STE-conformance claim. Manual comparison confirms that these contracts retain their meaning: durable intent and phase-aware recovery; permanent reservations and immutable source/artifact identity; approved source and provenance; labels, defaults, version/channel/target rules; publication lineage and source-bound notes; adoption and template evidence; bounded consumer policies and narrower pinning standards; moved-tag safeguards; fixed propagation targets, no-upgrade disposition, correlated execution, untrusted evidence boundaries, permissions, and human review. A normative requirement remains a contract, not implementation or CI-enforcement evidence. The existing `Failure behaviour` heading stays unchanged to preserve its anchor. Exact API states such as `cancelled`, technical nouns/verbs, identifiers, native syntax, examples, guide imperatives, and generated output are accepted differences. No policy contradiction or cross-owned repair is introduced or left unresolved by this diff. ### Validation and plan progress Local Markdown lint processed the exact eight assigned files and reported zero issues. The existing relative-link check passed for 130 documentation pages. The cross-repository check resolved all 7 links across 134 Markdown files. The existing pinned Pester 6.0.1 runner passed all 66 tests in 6 suites locally and again in final-head CI. No executable code or test changed. The final local build passed with existing Zensical 0.0.50; final-head CI also passed with the declared 0.0.59 requirement. No dependencies or tooling were added or changed. `git diff --check` passes, and the clean local/remote branch heads both equal the immutable head above. | Current-head verification | Result | Evidence | | --- | --- | --- | | Docs workflow | Success: Lint, Build, Links, and Test pass; Publish is skipped for this PR | [Run 41830087744](https://github.com/MSXOrg/docs/actions/runs/41830087744), bound to `21c7794d00990954e059de2d7e82cbf48ebf2512` | | Declared site toolchain | Zensical 0.0.59; “No issues found” | [Build job](https://github.com/MSXOrg/docs/actions/runs/41830087744/job/126574725326) logs the pinned requirement and successful build | | Pester | 66 passed, 0 failed, 6 suites; pinned 6.0.1 | [Test job](https://github.com/MSXOrg/docs/actions/runs/41830087744/job/126574725595) | | Cross-repository links | Success | [Run 41830087692](https://github.com/MSXOrg/docs/actions/runs/41830087692), bound to the same immutable head | | Automated review | Approved; 0 new inline comments; existing review script exits 0 | [Review](#266 (review)), bound to the same immutable head | The Task's source review, all-page reading, test-first examples, first complete improvement, early draft PR, producer prose, consumer prose, and final verification are complete. The Task body records the full path dispositions, before/after evidence, validation links, accepted differences, and immutable delivery record. The work is delivered in three small, pushed commits. No remaining blocker is identified. This PR remains open and draft, assigned to its author, by request. No ready transition or merge is requested. GitHub auto-merge is absent, Agent merge is disabled and has never run, and there are no `release:*` labels. The scoped convergence sweep searched open MSXOrg/docs issues for `"release-management" in:title,body` and `"downstream release propagation" in:title,body`. It found the closing Task and separate campaign Tasks #246, #247, #249, #253, and #255. Their separately owned deliverables are not closed by this eight-page diff. No additional issue converges. ### Standards and framework alignment The standard set is fixed at the review baseline: Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and the applicable specification/design/guide templates. The official STEMG overview and FAQ were read; relevant Issue 9 rules and dictionary entries were consulted from the verified local PDF/extract. The PDF MD5 is `9c720341c350ed77943b2c73d01c716f`. Reference copies remain local and are not republished. These checks do not claim full STE conformance. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `src/docs/Capabilities/release-management/spec.md` | Fixed standard set; specification template | Release requirements FR1-FR17 and NFR1-NFR4; release design | Fixed in this PR; normative requirements/scenarios unchanged | | `src/docs/Capabilities/release-management/design.md` | Fixed standard set; design template | Durable lifecycle, source-bound notes, publication lineage, consumer policies | Fixed in this PR; contracts and exact version example preserved | | `src/docs/Capabilities/release-management/design-publishing-targets.md` | Fixed standard set; design template | Seven-dimension target contract and all five target mappings | Fixed in this PR; mappings, constraints, and safeguards preserved | | `src/docs/Capabilities/release-management/accept-moved-release-tags.md` | Fixed standard set; guide template | Owned aliases, immutable exact tags, artifact-specific pinning | Fixed in this PR; commands and warnings preserved | | `src/docs/Capabilities/release-management/index.md` | Fixed standard set; navigation conventions | Release capability scope | Fixed in this PR; generated table unchanged | | `src/docs/Capabilities/downstream-release-propagation/spec.md` | Fixed standard set; specification template | Qualification, complete-range adoption, idempotency, human review | Fixed in this PR; obligations preserved | | `src/docs/Capabilities/downstream-release-propagation/design.md` | Fixed standard set; design template | Trigger, fixed target, evidence trust boundary, both delegation modes, retry states | Fixed in this PR; native states, gates, and stable anchors preserved | | `src/docs/Capabilities/downstream-release-propagation/index.md` | Fixed standard set; navigation conventions | Propagation and evidenced no-upgrade scope | Fixed in this PR; generated table unchanged | The effective repository route in `.github/workflows/Docs.yml` builds documentation and deploys Pages. The workflow set has no versioned release route. A Pages deployment alone does not invoke Release Management, so there is no release-decision block, publication-baseline claim, or `release:*` label. </details> <details> <summary>Related references</summary> - Resolves #252 </details>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
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. <!-- ANNOUNCEMENT STOP --> ## 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. <details> <summary>Technical details</summary> **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](https://github.com/MSXOrg/docs/actions/runs/41832344629) | Lint, Test, Links, and Build pass; PR publication correctly skipped | | [Pinned CI build](https://github.com/MSXOrg/docs/actions/runs/41832344629/job/126582402675) | Log confirms successful installation of `zensical-0.0.59` and `No issues found` | | [Corrected-head cross-repository CI](https://github.com/MSXOrg/docs/actions/runs/41832344619) | 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. </details> ## 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. <details> <summary>Technical details</summary> | 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](https://semver.org/#spec-item-9) 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](#268 (review)) completed with no new inline comments or changes requested. Its source is exactly `afe683b322ab9a19395bd98d1f89a1dda719f3fb`. No unresolved substantive contradiction remains in the changed explanations. </details> <details> <summary>Related references</summary> - Resolves #255 </details>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
Dependency and CI automation guidance states the update, merge, and PowerShell contracts in direct en-US prose. Readers can distinguish an update proposal from complete adoption, a required-check report from the verification it represents, and GitHub App permissions from code ownership. This documentation-only change requires no consumer configuration or runtime action. The PR remains draft for the documentation writing campaign. <!-- ANNOUNCEMENT STOP --> ## Changed: Automation guidance states precise, evergreen contracts The nine pages replace indirect explanations, idioms, British spelling, and delivery-plan prose. Specs retain their requirements, designs retain their mechanisms, and indexes retain their navigation role. The three-day cooldown, default-mapping omission, security bypass, release ownership, adoption evidence, merge holds, and PowerShell component boundaries remain intact. | Before | After | | --- | --- | | "Those pins age" | "A pinned version can contain a defect that a later upstream version corrects. It can also contain a known vulnerability." | | "native-support catalogue" / "prioritised" | "native-support catalog" / "prioritized" | | "Currency is the goal; being first is not." | "The cooldown delays a version update proposal after upstream publication." | | "a person to notice a green tick" | "For an eligible, routine change, a passing result SHOULD trigger automated merge without manual status inspection." | | "the check exists for free" | "Actions publishes a check run for each named job." | | "previously spread across initiative-local docs" | "MSXOrg/docs owns the canonical guidance." | | "Add a capability-level parity matrix with status per gap." | "A capability-level parity matrix records each gap's status and build or advocacy path." | The PowerShell design states its existing matrix, maturity, ownership, and review-cadence intent as target design responsibilities. It does not claim that those mechanisms have been implemented. Its renamed section retains the `planned-evolution` anchor. Required reviews remain independent of an app's review, and native auto-merge does not establish an unverified minimum permission set. <details> <summary>Technical details</summary> **Source identities.** The fixed review and scoped PR baseline is `1b0d4893c8fefabe604d04393068a8ff6f848082` in MSXOrg/docs. The final candidate is [`f81425c82c1938785720e758bed67f906e38f2ef`](f81425c). The comparison is baseline-to-candidate, not a publication-range claim. All five logical commits are pushed. The draft was opened after the first complete dependency edit, before the remaining capability edits. **Full-read and change record.** Every assigned page was read in full before editing and reviewed against its resulting contract. All nine changed; there are no unchanged owned pages. | Path | Read | Result | | --- | --- | --- | | `src/docs/Capabilities/dependency-updates/index.md` | Full | Revised | | `src/docs/Capabilities/dependency-updates/spec.md` | Full | Revised | | `src/docs/Capabilities/dependency-updates/design.md` | Full | Revised | | `src/docs/Capabilities/merge-automation/index.md` | Full | Revised | | `src/docs/Capabilities/merge-automation/spec.md` | Full | Revised | | `src/docs/Capabilities/merge-automation/design.md` | Full | Revised | | `src/docs/Capabilities/powershell-on-github/index.md` | Full | Revised | | `src/docs/Capabilities/powershell-on-github/spec.md` | Full | Revised | | `src/docs/Capabilities/powershell-on-github/design.md` | Full | Revised | **Preserved contracts and accepted differences.** Git-blob comparisons preserve all 17 FR/NFR labels, each requirement's normative force, three fenced YAML/Mermaid examples, and three generated INDEX blocks. Existing inline configuration and permission identifiers remain intact. PowerShell's original should/must sequence changes only to uppercase normative spelling. New code formatting for `Process-PSModule` and relative spec/design/reference links are intentional. The only heading rename retains its old HTML anchor; the local rendered page exposes both `planned-evolution` and `parity-gap-records`. No page moves or cross-owned link repairs are required. FR14 retains mechanism breadth: "A required PR check MUST report the evidence-verification result before the update is eligible for automatic readiness, approval, or merge." It does not require the check itself to perform verification. Missing, stale, pending, and failed results still hold the update. The three-day cooldown and exact `cooldown` omission/non-default semantics, schedule/timezone configuration, advisory bypass, central exceptions, complete-range evidence, independent release decision, and no-bypass merge gates retain their meaning. No PowerShell runtime requirement or execution behavior changes. **Source alignment and contradictions.** The review uses the fixed-baseline Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, and specification/design templates. The official STEMG overview and FAQ were read; relevant Issue 9 rules were consulted in the verified local reference. Copies and extracted text remain local. Selected-example checks and word counts are not full STE-conformance evidence. FR5's statement that generated configuration cannot drift conflicts with the design's explicit drift comparison. The explanation now states that generation uses supported manifests as its source; the existing SHOULD and reconciliation contract remain unchanged. The merge requirement now states its existing eligible-set restriction explicitly, consistent with the separate human-approval requirement. The original design also overstates platform facts. GitHub's [documented auto-merge workflow](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/automate-dependabot-with-actions#enabling-automerge-on-a-pull-request) grants both contents and pull-request write permissions. Its [GraphQL guidance](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app#choosing-permissions-for-graphql-api-access) requires testing selected app operations. The revised guidance does not infer a universal minimum from a user's write role or the REST merge endpoint. GitHub's [CODEOWNERS rules](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners#codeowners-syntax) identify users and teams with explicit write access; app installation permissions do not establish that ownership. The design therefore retains the required-review result as a separate gate. No API, permission, or runtime policy is changed. No live access experiment is run. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `src/docs/Capabilities/dependency-updates/**` | Fixed-baseline Natural Language, Writing Guide, Markdown, Documentation | Documentation Model, specification/design templates, and owned dependency contracts | Fixed in this PR | | `src/docs/Capabilities/merge-automation/**` | Fixed-baseline Natural Language, Writing Guide, Markdown, Documentation | Documentation Model, templates, owned merge contracts, and cited canonical GitHub facts | Fixed in this PR | | `src/docs/Capabilities/powershell-on-github/**` | Fixed-baseline Natural Language, Writing Guide, Markdown, Documentation | Documentation Model, templates, and owned PowerShell contracts | Fixed in this PR | **Verification.** The test-first check reproduced eight selected prose gaps before edits; all eight are absent from the committed candidate. The nine-file scope and preservation checks pass. The working tree is clean, and the remote branch matches the candidate. | Check | Result | | --- | --- | | Local Markdown | All nine pages inspected; no issues. markdownlint-cli2 0.24.0 / markdownlint 0.42.0. | | Relative links | Pass; 130 files scanned. | | Cross-repository links | Pass; seven links across 134 files. An anonymous attempt reached the shared GitHub rate limit; the rerun with existing process-local authentication passed. | | Existing Pester suites | 66 passed across six Pester 6.0.1 suites, with no skipped or inconclusive tests. Final CI also passes all 66. | | Local site and legacy anchor | Zensical 0.0.50 build passes; both design anchors render. This is supplementary, not the pinned-version result. | | Final Docs CI | [Success](https://github.com/MSXOrg/docs/actions/runs/41831835809) at the candidate. Lint, Links, Test, and Build pass; Publish is skipped for the PR. Build logs confirm pinned Zensical 0.0.59. MARKDOWN and NATURAL_LANGUAGE statuses are successful. | | Final cross-repository CI | [Success](https://github.com/MSXOrg/docs/actions/runs/41831835749) at the candidate. | | Automated review | [Approved](#269 (review)) at the candidate, with zero new inline comments. The standard review script exits 0. | An early CI run found one introduced terminology violation, "bug fix". The final defect/version sentence removes it. Cached local textlint 15.8.0 loads no rules, including for an anonymous counterexample, so that local attempt is not reported as a pass. The configured final CI NATURAL_LANGUAGE success provides the terminology result. No package or new tool is installed. **Scope and delivery.** The Task's prose, source-review, preservation, validation, and evidence steps are complete. Shared indexes, other capability owners, process pages, executable code, configuration, tooling, and tests are excluded. The reserved files owned by #240 are unchanged. Generated INDEX content is unchanged. No repository audit/planning files, dependencies, enforcement tooling, or structure changes are added. The issue-convergence search covers open campaign issues and the dependency/documentation, merge-automation, and PowerShell-on-GitHub terms. Only #254 is fully resolved by this focused diff; no additional closing reference applies. The effective Docs PR route does not invoke Release Management, so no release decision block or release labels apply. No delivery blocker remains. Exact app-operation permissions and implementation enforcement are not claimed as verified runtime behavior. The PR stays **draft** by explicit campaign instruction. No mark-ready, merge, auto-merge, or Agent merge action is taken. </details> <details> <summary>Related references</summary> - Resolves #254 - References [fixed source baseline](https://github.com/MSXOrg/docs/tree/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs) - References [official STEMG overview](https://www.asd-ste100.org/about_STE.html), [FAQ](https://www.asd-ste100.org/STE_faq.html), and [Issue 9](https://doi.org/10.5281/zenodo.23666006) </details>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
Workflow and issue guidance describes capture, planning, delivery, review, and operation in direct en-US prose. Contributors, maintainers, and agents can distinguish strategy, aggregate coordination, delivery work, and completion evidence without metaphor or temporary migration status. No reader action is required. This documentation-only change does not add policy, implementation, enforcement, tooling, or dependencies. <!-- ANNOUNCEMENT STOP --> ## Changed: Workflow and issue guidance states the continuing process directly The pages use concrete process descriptions and direct work steps. Epic and PBI guidance retains consumer expectations and native coordination; Task and Bug guidance retains technical decisions and test-first delivery plans. Merge remains distinct from publication, deployment, operation, and template completion. Exact recognized prompts, commands, examples, native types and relationships, normative force, headings, anchors, and complete readiness and evidence gates retain their meaning. The obsolete Feature migration sentence is replaced with the enduring classification rule, using the closed migration and current native-type configuration as evidence. <details> <summary>Technical details</summary> ### Immutable scope and delivery record - Review baseline: `1b0d4893c8fefabe604d04393068a8ff6f848082`. - Final head: `8527fa103940caa38e715daeaa5b678d9e31df5a`. - All 21 assigned Markdown pages were read fully after the criteria were derived. Thirteen pages change; eight require no prose change. - Five small commits were pushed individually. This draft opened after the first complete Workflow improvement, before the remaining scoped work. - No contribution, PR-format, governance, model, top-level index, functional code, test, configuration, or dependency file changes. The active #240 surfaces remain untouched. The criteria come from the fixed baseline's [Documentation Model](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Documentation-Model.md), [Natural Language](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md), [Technical Writing Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md), [Markdown](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Markdown.md), [Documentation](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Documentation.md), and applicable [standard, orchestration-playbook, and guide templates](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md). Existing artifact roles and sections remain; this is not a template restructure. The [official STEMG overview](https://www.asd-ste100.org/about_STE.html) and [FAQ](https://www.asd-ste100.org/STE_faq.html) were read. The verified local [Issue 9](https://doi.org/10.5281/zenodo.23666006) source, MD5 `9c720341c350ed77943b2c73d01c716f`, was consulted for terminology, approved meanings, active voice, short sentences, conditional instructions, and procedural/descriptive distinctions. The PDF and extract remain local and are not republished. ### Full read and disposition evidence Paths below are relative to `src\docs\Ways-of-Working`. | Path | Fully read | Disposition and evidence | | --- | --- | --- | | `Workflow.md` | Yes | Changed: concrete process, Capture record, local verification, review, Ship, and Operate prose. | | `Workflow-Stages\Define.md` | Yes | Changed: explicit capture/refinement actions and stage boundaries. | | `Workflow-Stages\Implement.md` | Yes | Changed: delivery responsibilities and alignment-pass wording; existing precedence contract retained. | | `Workflow-Stages\Review.md` | Yes | Changed: direct assessment instructions, en-US behavior spelling, evidence checks, and existing approval/check conditions. | | `Workflow-Stages\Security-Review.md` | Yes | Changed: shorter defensive-review and output descriptions; en-US labeled; all fields and constraints retained. | | `Workflow-Stages\Maintain-Guidance.md` | Yes | Changed: duplicated-process wording, source links, pointer responsibilities, and direct validation steps. | | `Workflow-Stages\index.md` | Yes | No change: existing routing, discovery path, and stage boundaries are direct; generated table preserved. | | `Issues\index.md` | Yes | No change: direct planning entry route and native type/process navigation; generated table preserved. | | `Issues\Process\Format.md` | Yes | No change: canonical title/body, metadata, audit, and formatting contracts remain clear. | | `Issues\Process\Lifecycle.md` | Yes | Changed: unblocked Build entry and explicit operational signal records. | | `Issues\Process\Planning.md` | Yes | Changed: independent child context and outcome-based decomposition wording; all normative consumer/technical boundaries retained. | | `Issues\Process\Relationships.md` | Yes | No change: concrete native containment, dependencies, parallelism, and no-duplicate-field rules. | | `Issues\Process\index.md` | Yes | No change: concise factual process navigation; generated table preserved. | | `Issues\Types\Epic.md` | Yes | Changed: direct Initiative strategy-boundary description; consumer scenarios and closure gates retained. | | `Issues\Types\PBI.md` | Yes | Changed: readiness explicitly coordinates delivery; scenarios, children, and closure gates retained. | | `Issues\Types\Hierarchy.md` | Yes | Changed: enduring Feature classification without obsolete migration status. | | `Issues\Types\Task.md` | Yes | No change: executable technical/test-first plan, repository path, and audited operational contracts remain clear. | | `Issues\Types\Bug.md` | Yes | No change: complete reproduction, regression-first, readiness, and closure evidence remains clear. | | `Issues\Types\index.md` | Yes | No change: concise native-type navigation; generated table preserved. | | `Goal-Setting.md` | Yes | Changed: direct strategy, Objective, Key Result, Initiative, and repository-Epic descriptions. | | `Definition-of-Ready-and-Done.md` | Yes | Changed: direct gate descriptions without weakening any readiness, release, documentation, or post-merge ownership condition. | ### Concrete before/after acceptance evidence The repeatable prose checks establish 15 desired results absent at the fixed baseline and all 15 present at the final head. The four observed Workflow defect strings are absent. Manual review compares the complete changed passages and their technical meaning, not only these strings. | Surface | Before | After | | --- | --- | --- | | Workflow process | `This is the heartbeat of the MSX ecosystem.` and `The loop never stops.` | `The workflow connects issue capture, planning, delivery, review, and operation.` Continuous activities and their signals are described directly. | | Capture | `so it exists for the world to see and "remember"` | `The issue gives contributors and agents a persistent record to refine.` | | Operate | `After merge, the system is live.` | `The delivery team operates the system and responds to signals.` | | Define | `Pain before solution - push back on implementation-framed requests.` | `Identify the problem before you select a solution.` The following sentence challenges requests without a stated problem. | | Implement | `plan from scratch` in the stage boundary | `Implement does not build an Epic or PBI, start without a delivery plan, or supply independent review.` | | Review | `tests that exercise behaviour` | `tests that exercise behavior` | | Security Review | `labelled` | `labeled`, with the exact native title and label syntax retained | | Maintain Guidance | `bloated agent file` | `duplicate process instructions`, replaced with a thin documentation pointer | | Goal Setting | `A concrete organization-level bet to move a Key Result` | `An organization-level effort to improve a Key Result` | | Readiness | `Ready gates starting, not scope` and `figured out on the fly` | `Readiness determines when work starts, not its scope.` | | Issue Planning | `to be picked up independently` | `for independent work`, retaining local Why and acceptance criteria | | Issue Lifecycle | `Feed production signals and learning back into the issue model.` | `Record operational signals and findings in the issue model.` | | Epic | `organization-level bet under an OKR` | `An Initiative is an organization-level effort under an OKR.` | | PBI | `A PBI is ready for delivery when:` | `A PBI is ready to coordinate delivery when:` | | Hierarchy | `Feature remains temporary live metadata while ... retires existing usage.` | `Feature describes a kind of work, not a planning altitude.` Its prohibition as a hierarchy node remains. | The exact before-text and immutable source links are also retained in #257. #90 is closed, and the organization API lists Task, Bug, Epic, and PBI, with no Feature type. Only the obsolete migration link is removed; every other link destination remains unchanged. Final meaning review removed an unintended per-push frequency from an intermediate draft. The final work step is `run relevant local checks. Do not push known failures to CI.` It preserves the existing obligation without adding policy. ### Validation at the final head | Check | Result | | --- | --- | | Manual source/meaning review | All 21 owned pages fully read; all changed passages compared against the pinned criteria and technical contracts. | | Repeatable prose cases | 15 expected baseline failures; 15 final result passes. | | Technical invariants | All 21 comparisons pass after LF/CRLF normalization: headings/anchors, fenced examples, exact inline syntax/prompts, MUST/SHOULD/MAY force, link targets except the documented removal, generated blocks, titles, front-matter keys, and quotations. | | Markdown | Existing repository configuration; 21 owned files; 0 issues; `markdownlint-cli2` 0.24.0, without installation. | | Relative links and anchors | Existing `Test-DocumentationLink.ps1`; 130 files scanned; all resolve. | | Cross-repository links | Existing `Test-CrossRepositoryLink.ps1`; 7 links across 134 files; all resolve. An anonymous retry hit the shared 60/hour quota; the authenticated retry passed. Authentication was process-local; no credential or persistent access was created. | | Repository tests | Existing Pester 6.0.1 runner; 66 passed in 6 suites; 0 failed, skipped, inconclusive, or not run. | | Pinned site build | Read-only existing Zensical 0.0.59 environment; archived final source; existing index generation; `zensical build --clean`; no issues, 2.29 seconds. Five rendered acceptance cases pass, including both regenerated descriptions. | | Git diff and scope | `git diff --check` passes; exactly 13 owned Markdown files change; working tree clean. | | Final-head Docs CI | [Lint, Links, Test, and Build pass](https://github.com/MSXOrg/docs/actions/runs/41832250410). Publish is intentionally skipped for the PR event. | | Final-head network CI | [Cross-repository links pass](https://github.com/MSXOrg/docs/actions/runs/41832250219). | | Final-head automated review | [Approved review](#270 (review)) is bound to `8527fa103940caa38e715daeaa5b678d9e31df5a`; no inline comments. The bounded three-minute helper elapsed before the review arrived; the completed GitHub receipt confirms the clean final round. | Reproducible site sequence: archive `8527fa103940caa38e715daeaa5b678d9e31df5a` into a session-only validation directory, run the archived `.github\scripts\Update-DocumentationIndex.ps1`, then run `& $PinnedPython -B -m zensical build --clean` from the archived `src` directory. The private interpreter's package version is verified as 0.0.59. Source configuration stays unchanged; output remains in session artifacts. The global 0.0.50 installation and the shared validation environment are not modified. ### Standards and framework alignment The shared writing set below is the fixed-baseline Natural Language, Technical Writing Guide, Markdown, Documentation, and Documentation Model guidance, plus the official sources cited above. Applicable standard/playbook/guide roles remain in their existing sections. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `Workflow.md` | Shared writing set; existing staged process | None (no framework-specific docs) | Fixed in this PR | | `Workflow-Stages\Define.md` | Shared writing set; guide/playbook; native planning altitude | None (no framework-specific docs) | Fixed in this PR | | `Workflow-Stages\Implement.md` | Shared writing set; guide/playbook; delivery and evidence gates | None (no framework-specific docs) | Fixed in this PR | | `Workflow-Stages\Review.md` | Shared writing set; guide/playbook; review identity and check gates | None (no framework-specific docs) | Fixed in this PR | | `Workflow-Stages\Security-Review.md` | Shared writing set; guide/playbook; defensive scope and output contract | None (no framework-specific docs) | Fixed in this PR | | `Workflow-Stages\Maintain-Guidance.md` | Shared writing set; guide/playbook; thin-pointer contract | None (no framework-specific docs) | Fixed in this PR | | `Issues\Process\Lifecycle.md` | Shared writing set; native lifecycle and relationship contracts | None (no framework-specific docs) | Fixed in this PR | | `Issues\Process\Planning.md` | Shared writing set; native consumer/technical altitude contract | None (no framework-specific docs) | Fixed in this PR | | `Issues\Types\Epic.md` | Shared writing set; aggregate strategy and acceptance contract | None (no framework-specific docs) | Fixed in this PR | | `Issues\Types\PBI.md` | Shared writing set; aggregate readiness contract | None (no framework-specific docs) | Fixed in this PR | | `Issues\Types\Hierarchy.md` | Shared writing set; verified native classification | None (no framework-specific docs) | Fixed in this PR | | `Goal-Setting.md` | Shared writing set; existing Mission/OKR/Initiative boundary | None (no framework-specific docs) | Fixed in this PR | | `Definition-of-Ready-and-Done.md` | Shared writing set; complete existing readiness/completion gates | None (no framework-specific docs) | Fixed in this PR | ### Accepted differences and exclusions Direct imperative work steps remain imperative. Exact recognized prompts, native issue types and relationships, commands, Gherkin and Mermaid examples, technical nouns, normative contracts, quotations, and the Now/Next/Later planning model keep their purpose. The retained quotation `You build it, you run it.` is not rewritten as authored process prose. Time is the subject of Current OKRs and planning horizons; these are not delivery-status narratives. No generated INDEX marker table is hand-edited or committed. Existing CI generation, also exercised in the isolated build, updates the shared Ways-of-Working index from the two changed descriptions. No heading, anchor, navigation key, requirement reference, or cross-owned link repair is needed. The app-managed branch name follows the explicit session naming instruction; the one-Task/one-branch/one-PR boundary remains. The campaign's explicit draft-only instruction stops this delivery before the general workflow's ready/auto-merge handoff. The source pages retain that general policy. These checks support the manual review. Counts, scans, and automated approval do not establish full STE conformance or prove policy implementation/enforcement. No integration-template change applies to this process-prose-only result. The site route does not invoke Release Management, so no release decision block or `release:*` label applies. ### Scoped issue convergence and remaining questions The finished-change sweep searched open issue titles for `workflow`, `issue`, and the campaign prefix. It found this delivery Task, #96, #154, and the other independently owned campaign parts. The complete bodies of #96 and #154 were read. Neither converges: the former proposes a different issue-planning policy, and the latter requests a new entry-side premise-verification gate. This prose change implements neither. Both stay open; no additional closing keyword is added. Three pre-existing policy questions remain recorded for separate resolution, not silently reconciled: - Security Review describes an issue per finding in its introduction but one issue containing finding blocks in Output. Reporting cardinality remains unresolved. - Security Review lists mutable action tags as findings, while Review recognizes the owned controlled-release major-tag exception. The exception boundary remains unresolved. - Implement's exact `Repo-local linter config wins where it disagrees with a published standard.` sentence remains. The Coding Standards index says configuration derives from standards, while Markdown says configuration is authoritative on disagreement. Precedence interpretation remains unresolved as directed by the coordinator. No implementation or validation blocker remains for the focused prose deliverable. These policy questions and the separate requests above remain outside it. The delivery Task stays open because this PR is not merged. **Delivery boundary:** This PR stays DRAFT. It is not merged; auto-merge is off; Agent merge is disabled with `merge_pr: false`. Human review and integration are not performed by this delivery. </details> <details> <summary>Related references</summary> - Resolves #257 - References #90 for the completed native-type migration evidence. - References #96 and #154 as non-convergent, still-open work. - References #240 only as an active code/test ownership exclusion. </details>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
Contribution guidance uses direct en-US explanations for branches, commits, worktrees, review duties, and session procedures. Commit guidance points change classification to canonical PR Format instead of asserting an unsupported metadata field. Commands, recognized phrases, and review/release gates are unchanged. Contributors and reviewers need no workflow change. This clarification changes guidance only, not automation or enforcement. The campaign keeps this pull request in draft. <!-- ANNOUNCEMENT STOP --> ## Changed: Contribution records state duties and session effects directly The contribution pages replace metaphorical explanations with explicit actors, actions, conditions, and results. Authors still complete automated review before requesting human review. Reviewers retain blocking-concern and independent-approval duties. Session procedures retain their existing recording, continuation, read-only status, and confirmation requirements. Commit Conventions states that classification belongs in the PR and links its canonical format. It adds no metadata field or unconditional label requirement. The no-conventional-prefix rule and every actual conditional release-label rule remain unchanged. No adoption action is required beyond reading the clarified explanations. PR Format remains unchanged, including its complete release-bound coverage and consumer-record requirements. <details> <summary>Technical details</summary> ### Immutable scope and complete reading The fixed criteria and scoped PR base are `1b0d4893c8fefabe604d04393068a8ff6f848082`. The final candidate is `5aa044a68db7f5bcf7927d1d1b48b2bbb1e701fd`. The remote PR head and all observed final-head CI checks name that exact candidate. Seven small commits change six prose-only files, with 272 additions and 223 deletions. The working tree is clean. The source-resolved follow-up compares prior verified head `4de8a3b1a933b76d50197af8303cb12f83bb1d5c` with the final candidate. It changes exactly one sentence in `Commit-Conventions.md`, with one insertion and one deletion. The other six assigned pages and every other sentence in Commit Conventions are exact to that prior head. The unsupported field reference is corrected, not deferred as policy. Every assigned page was read in full, including every example and all 745 lines of PR Format. | Fully read path | Final disposition | | --- | --- | | `src\docs\Ways-of-Working\Branching-and-Merging.md` | Changed: direct branch, check, promotion, and approval explanations. Stack ordering and release conditions are retained. | | `src\docs\Ways-of-Working\Commit-Conventions.md` | Changed: direct rationale and author responsibilities, with a canonical PR-format pointer instead of an unsupported field assertion. All prefix rules, good/bad messages, the body example, and the `git log` reference are retained. | | `src\docs\Ways-of-Working\Contribution-Workflow.md` | Changed: explicit author review steps, readiness, and required ruleset conditions. The script contract, example, and Mermaid are retained. | | `src\docs\Ways-of-Working\Git-Worktrees.md` | Changed: concrete working-directory isolation instead of a guarantee about all parallel work. Topology, remotes, and every command are retained. | | `src\docs\Ways-of-Working\PR-Format.md` | No change: all 745 lines are unchanged. Immutable publication/candidate identity, lineage, full-range coverage, partial/initial publication, conditional release decisions, and complete adoption/no-action records remain intact. | | `src\docs\Ways-of-Working\Review-Etiquette.md` | Changed: direct approval, evidence, response, and regression-coverage explanations. Blocking duties and the unresolved policy clauses are retained. | | `src\docs\Ways-of-Working\Session-Interactions.md` | Changed: direct procedure descriptions and en-US. All eight phrases, aliases, effects, normative force, and the unresolved confirmation clauses are retained. | No workflow, issue-guidance page, shared index, governance page, dependency, code, test, or configuration file changes are included. Active #240 code/tests remain outside scope. Front-matter descriptions are the owning inputs for CI-generated indexes; no generated index was edited or committed. ### Concrete before and after | Page | Before | After | | --- | --- | --- | | Contribution Workflow | "the cheap feedback is spent before a person's time is" | "The author addresses automated review feedback before requesting human review" | | Contribution Workflow | "survived an automated pass" | "the author completes the automated review loop and responds to its findings" | | Contribution Workflow | "so nothing lands early" | "Auto-merge waits for human approval and every required branch-protection condition before it merges the change." | | Branching and Merging | "A pull request is green before review begins." | "Automated checks pass before human review begins." | | Commit Conventions | "without the ceremony" | "Direct, descriptive messages explain the change without duplicate type prefixes." | | Commit Conventions, at the prior verified head | `MSX classifies changes at the PR level via labels and the change-type field.` | `MSX classifies changes in the PR according to [PR Format](PR-Format.md).` | | Git Worktrees | "so parallel work never collides" | "This keeps participants' uncommitted changes in separate directories." | | Review Etiquette | "the reviewer vouches for it" | "An approving review records the reviewer's acceptance of the change." | | Session Interactions | "The phrase matters because the alternative is ceremony." | "A defined procedure makes the expected result clear." | The independent source for the classification correction is the fixed [per-result classification contract](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/PR-Format.md#explain-each-reader-facing-result). Its [release decisions](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/PR-Format.md#resolve-release-decisions) remain conditional on the target route. This correction points to that owner rather than inventing a field or repeating its classification rules. ### Verification and its limits The editorial expectations and failing before-text examples were recorded in the native Task before editing. The classification correction also has a source-bound before/expected result recorded before its edit. An exact whole-file comparison proves that only the specified sentence changed against the prior verified head. The other six pages are unchanged from that head, including all actual conditional release-label rules and both unresolved policy choices. Final comparison against the fixed baseline retains all titles, 95 headings, 14 fenced blocks, 145 inline-code spans, 15 uppercase normative tokens, eight exact interaction phrases, and seven exact aliases/examples. All 72 existing link targets remain intact; the canonical PR-format pointer adds one relative target, for 73 total. PR Format remains wholly unchanged. Four selected policy clauses remain exact. The former field assertion is an explicitly verified descriptive correction, not a preserved policy choice. The complete before/after prose was reviewed for retained technical meaning, active voice, conditions, direct work steps, and the relevant Issue 9 rules and dictionary. Counts, syntax comparison, linter success, and automated approval do not prove full STE conformance. The ruleset requirements remain normative guidance, not evidence that repository enforcement was audited. The preserved setup/cleanup examples were not executed as real repository operations. | Existing check, repeated for the final candidate | Outcome | | --- | --- | | `git diff --check` against the fixed base | Passed. | | Cached `markdownlint-cli2` 0.24.0 with the shared configuration | Seven assigned pages examined; zero issues. No installation. | | `Test-DocumentationLink.ps1` | All relative links resolved; 130 files examined, including the added canonical pointer. | | `Test-CrossRepositoryLink.ps1` | Seven links in 134 files resolved. Existing GitHub authentication supplied rate-limit headroom; no credential was logged or persisted. An earlier head's anonymous-quota failure and successful retry remain in the Task audit record, not as evidence for this head. | | `Invoke-PesterSuite.ps1` with installed Pester 6.0.1 | 66 passed in six suites; zero failed, skipped, inconclusive, or not run. The log confirms the existing 6.0.1 import and GUID. | | `python -m zensical build --clean` from `src` | Passed; no issues. | | Final-head GitHub checks | Lint, Build, Test, Links, Cross-repository links, and automated review succeeded. Publish was skipped under the workflow's PR condition. All 15 reported linter statuses succeeded. | | Automated review | Four requested rounds completed cleanly. The repeated final review names `5aa044a68db7f5bcf7927d1d1b48b2bbb1e701fd`, reports approval, and adds zero inline comments. There are zero inline comments on the PR. Earlier clean rounds do not validate this new source. | Final external evidence: [Docs CI](https://github.com/MSXOrg/docs/actions/runs/41834882535), [cross-repository CI](https://github.com/MSXOrg/docs/actions/runs/41834882756), and [the final source-bound review](#271 (review)). ### Standards and scope alignment Criteria were derived before page review from the fixed Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, and applicable Standard/Guide/Reference templates. The official STEMG overview and FAQ and relevant local Issue 9 rules/dictionary were consulted. The source links and verified PDF MD5 are in #261. The PDF and extract remain local and are not republished. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `src\docs\Ways-of-Working\Branching-and-Merging.md` | Fixed writing criteria, Markdown, Standard/Guide roles; branch, stack, promotion, and approval contracts | None (no framework-specific docs) | Fixed in this PR | | `src\docs\Ways-of-Working\Commit-Conventions.md` | Fixed writing criteria, Markdown, Standard role; canonical PR classification ownership, no-prefix rules, and exact examples | None (no framework-specific docs) | Fixed in this PR | | `src\docs\Ways-of-Working\Contribution-Workflow.md` | Fixed writing criteria, Markdown, Guide/Standard roles; review, readiness, triage, and merge conditions | None (no framework-specific docs) | Fixed in this PR | | `src\docs\Ways-of-Working\Git-Worktrees.md` | Fixed writing criteria, Markdown, Guide/Reference roles; workspace, remotes, and exact commands | None (no framework-specific docs) | Fixed in this PR | | `src\docs\Ways-of-Working\Review-Etiquette.md` | Fixed writing criteria, Markdown, Standard role; blocking, reply, and independent-approval duties | None (no framework-specific docs) | Fixed in this PR | | `src\docs\Ways-of-Working\Session-Interactions.md` | Fixed writing criteria, Markdown, Standard/Reference roles; phrase bindings, effects, authority, and normative force | None (no framework-specific docs) | Fixed in this PR | These results cover the scoped prose, not a claim that every policy ambiguity is resolved. Accepted differences include direct imperatives, exact commands/examples, native issue types and technical terms, stable headings/anchors, recognized phrases, and release/history record semantics. The app-managed branch name and the draft-only handoff are explicit campaign exceptions to the general delivery procedure. The scoped convergence search covered this Task and open MSXOrg/docs issues with `contribution` in the title. It returned only #261. The narrow correction delivers the same Task, adds no other closing reference, and does not expand scope. All scoped implementation and repeated verification steps are complete; the Task remains open for review and merge. The inspected target workflows build and publish the Zensical site. They do not invoke Release Management or publish a versioned product artifact. No publication baseline, release decision block, or applied release label is appropriate for this PR. Its scoped source comparison is not release-note coverage evidence. ### Preserved policy questions and handoff Only two genuine policy tensions remain unresolved: Session Interactions calls Stop the only interaction that MUST confirm first, while Spin-off also requires confirmation; Review Etiquette sends self-review to the terminal but also describes a public `Comment` review. Their original source clauses remain unchanged. The unsupported change-type-field reference is resolved from canonical PR Format as a narrow descriptive correction, not left as a third policy question. There is no remaining implementation or validation blocker. This campaign stops at draft. The PR is open, draft, and unmerged; GitHub auto-merge is unset and Agent merge is disabled. Do not mark ready, merge, or enable either merge feature. </details> <details> <summary>Related references</summary> - Resolves #261 </details>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
Documentation command help uses direct en-US statements for supported results and controls. It distinguishes log/status strings, individual anchor strings, and structured results. The index command's synopsis, description, and `Check` help are visible through `Get-Help`. Changed output entries use the native format owner's full .NET type name, a blank line, and a description paragraph. Callers need no action. Executable statements, emitted values/shapes, parameters/defaults, existing examples, and exit behavior remain unchanged. <!-- ANNOUNCEMENT STOP --> ## Fixed: Native command help describes supported results The help replaces figurative wording with observable conditions: missing test files and zero tests cause failure; valid Markdown pages without links differ from missing Markdown files; planned pin updates differ from written updates. Review help states its selected start times, SkipRequest/WhatIf window, result properties, and exit codes. Cross-repository help explains owner/host scope, GitHub anchor rules, the three outcomes, retry/cache behavior, and anonymous-reader access. Output help describes existing emitted items, not internal List/HashSet containers or structured domain data that the commands do not return. Two commands gain missing native `.OUTPUTS` sections. A single required blank separator also fixes the index help's attachment defect. These corrections affect documentation and help visibility, not runtime behavior or caller contracts. <details> <summary>Technical details</summary> ### Final source and alignment The immutable PR base and writing-review baseline are MSXOrg/docs `1b0d4893c8fefabe604d04393068a8ff6f848082`. The delivered head is `1ba4dc5174399f859e4a0afee516bd007f13fe37`. Eight small commits are pushed; the draft opens after the first complete index-help improvement. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `.github/scripts/Invoke-PesterSuite.ps1`: native help/parameters and log-output description | Fixed Documentation Model, Natural Language, Technical Writing Guide, Markdown, Documentation, PowerShell Scripts/Functions, native help, relevant Issue 9 guidance | None (no framework-specific docs) | Fixed in this PR | | `.github/scripts/Test-DocumentationLink.ps1`: help/parameters, missing output section, emitted-anchor types | Same fixed sources; link/footnote/anchor contracts and actual output probes | None (no framework-specific docs) | Fixed in this PR | | `.github/scripts/Update-DocumentationIndex.ps1`: help/parameter, one separator, missing output section | Same fixed sources; native help placement, nav-array behavior, status/silence probes | None (no framework-specific docs) | Fixed in this PR | | `.github/scripts/Update-GitHubActionPin.ps1`: help/parameter and structured-output description | Same fixed sources; stable-release, authentication, ShouldProcess, actual structured result, and native output format | None (no framework-specific docs) | Fixed in this PR | | `.github/scripts/Wait-CopilotReview.ps1`: help/parameters and structured-output description | Same fixed sources; timing, result properties/exits, and native output format | Fixed Contribution Workflow | Fixed in this PR | | `.github/scripts/Test-CrossRepositoryLink.ps1`: released native help and parameter prose | Same fixed sources; scope, slug, checkout, retry/cache, actual output, and historical provenance | Matching replacement blocks in #240 at reviewed `ee3c17855cb282cdf236fc764df3f45502f4c057` | Released prose fixed here; two version-specific blocks covered by the existing matching effort, not baseline-aligned | No executable code, declaration/directive, actual output value/shape, exit, existing example/command, test, configuration, or Markdown page changes. No dependency, new tooling, repository audit/planning file, additional PR, or #240 lifecycle change is introduced. ### Final format-only receipt Commit `1ba4dc5174399f859e4a0afee516bd007f13fe37` changes only six output entries already modified by this campaign. Get-HeadingSlug, Get-CachedSlug, Get-MarkdownAnchor, and the cross-repository Write-WorkflowAnnotation use `System.String`. The previously edited action-pin and review-controller root entries use `System.Management.Automation.PSCustomObject`. Each full type is alone on its first line, followed by a blank line and its description paragraph. The four other changed root string entries already have that format. Earlier `[string]` directions identify the semantic type, not a prescribed help-field spelling. Before-format cases pass `0/6`; after-format cases pass `6/6`. All ten changed/added output entries pass the fixed native format owner's rule and render the full name through `Get-Help -Full`. Exact masked-file comparison permits only those six output-field text spans and proves every other byte unchanged, including unrelated legacy entries and both code-PR-covered blocks. Executable token text, AST parent topology, original examples, and every help keyword remain identical to the already-verified `3d7a740e8a04d2b95cc8edec1b102b55c6388d89` implementation head. Existing analyzer settings report zero diagnostics in the four corrected files. No whole-help audit or section restructure is added. ### Retained before/after and contract evidence “Glue across the ecosystem is PowerShell” becomes the actual quoted-path/nav-array operation. “Drives one round” becomes the exact review-cycle/timestamp contract. “Green and worthless” becomes explicit no-file/zero-test failure conditions. Released `honours`, `recognised`, and `Memoise` wording becomes direct en-US explanations. Eight factual output corrections describe existing emitted items; the final format pass does not change those meanings. Source-loaded and existing-fixture probes establish the actual contracts before the help corrections: annotation helper emits zero items outside Actions and one `System.String` inside; its caller emits two or three log/annotation strings with exit `1` for the no-link input; the pinned Pester empty-directory run emits five log strings with exit `1`; valid-link validation emits one status string with exit `0`; stale index check/update/current check emit three/two/zero items with exits `1`/`0`/`0`. Heading/cache helpers emit four individual strings for the existing README, and the anchor helper emits two strings for anonymous two-heading input. No output is changed to fit the help. Named anonymous fixtures are removed, and no dependency is installed. The fixed-baseline proof remains applicable: 8,591 original non-comment tokens plus the sole required index `NewLine`, all 7,284 AST nodes and parent relationships, 29 exact examples, six exact URL-shape rows, all 110 original help keywords plus only two authorized missing `.OUTPUTS` additions (112 total), unchanged protected bytes/non-owned comments/BOMs, six-path scope, and clean pushed source. No executable token is excluded or changed. The final formatting delta adds no keyword, layout outside an output entry, or code difference. At baseline, index `GetHelpContent()` is null and native `Get-Help` shows syntax only. Native help exposes synopsis, description, and `Check` after the one required separator. This is an intentional documentation-format correction, not a retained gap. ### Two-source coverage and deferred implementation metadata The baseline `Get-RenderedHeadingText` help and top-level `.NOTES` remain byte-exact here: 655 and 337 UTF-8/CRLF bytes, with fingerprints retained in #256. Their matching replacement blocks and renderer implementation are reviewed at #240 source `ee3c17855cb282cdf236fc764df3f45502f4c057`. Both the coordinator and this session read that persistent source. The helper uses bundled Markdig with GitHub inline autolinks/strikethrough, keeps generic attributes literal, and separates GitHub slug generation; NOTES distinguishes original slug provenance from the renderer. No additional prose correction is identified in those reviewed blocks. Those blocks are covered by the existing matching effort at that exact SHA, NOT baseline-aligned or permanent exceptions. This branch retains the old helper, so new-renderer claims/code are not copied here; edits to those version-specific blocks would wait until the code PR merges. No merge or extra future writing edit is needed to review the already-persistent matching source. #240 lifecycle remains untouched. Historical character-class facts retain their recorded comparison, named Unicode groups, 52 arrow/symbol differences, and 3 CJK differences. `Get-MarkdownAnchor` retains the exact executable attribute `[OutputType([System.Collections.Generic.HashSet[string]])]` despite emitting two `System.String` items in the anonymous probe. Help describes emitted items accurately; the pre-existing implementation-metadata mismatch is explicitly deferred to the #240 functional owner. It is not metadata conformance or verified no-change. No source warning/history paragraph or unauthorized runtime/declaration change is added. ### Validation and completed delivery The retained implementation verification passes 49/49 affected Pester 6.0.1 tests with expected GUID, zero analyzer diagnostics across six scripts, zero syntax errors, relative links across 130 Markdown files, index `-Check` exit `0` without writes, whitespace checks, and exact invariants. Its runtime/output probes and six-script executable/AST proof remain applicable because this follow-up changes comment format only. The narrow follow-up adds native-format assertions, native-help display checks, exact output-span-only comparison, and zero analyzer diagnostics in the four corrected scripts. All five new-head repository checks pass: [Build](https://github.com/MSXOrg/docs/actions/runs/41842992662/job/126619171453), [Lint](https://github.com/MSXOrg/docs/actions/runs/41842992662/job/126619171490), [Links](https://github.com/MSXOrg/docs/actions/runs/41842992662/job/126619171609), [Test](https://github.com/MSXOrg/docs/actions/runs/41842992662/job/126619171165), and [Cross-repository links](https://github.com/MSXOrg/docs/actions/runs/41842992607/job/126619170612). Publish is skipped for this PR, as configured. The one requested [source-bound review](#272 (review)) approves exact head `1ba4dc5174399f859e4a0afee516bd007f13fe37`. Its full summary reports no active review issues and no open issues. All review threads are resolved, with `hasNextPage=false`. The review arrives after the helper's three-minute wait; the result is verified directly through GitHub REST, without requesting a second review. That service timing is not a repository error or remaining blocker. #256 retains the complete read/changed/no-change inventory, source expectations, before/after/probe evidence, commit identities, two-source coverage, and deferred metadata finding. No full inventory repeat or whole-help audit is needed for this format-only delta. Counts and scans do not certify full STE conformance. The focused convergence sweep identifies no additional fully satisfied issue; #239 and #245 remain non-closing context. The missing parent `../AGENTS.md` source-path limitation is recorded; the existing root route is followed. The inspected workflows publish Pages and do not invoke Release Management for this route, so no release metadata is added. No in-scope blocker remains. This PR remains DRAFT with auto-merge unset; app Agent merge is disabled with merge_pr=false. No readiness or merge action is performed. The Task stays open for later review and merge. </details> <details> <summary>Related references</summary> - Resolves #256 - References #240 - References #239 - References #245 - [Matching reviewed heading-fix source](ee3c178) - [Fixed native output format owner](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/PowerShell/Functions.md#inputs-and-outputs) - [Fixed Documentation Model](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Documentation-Model.md) - [Fixed Natural Language](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md) - [Fixed Technical Writing Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md) - [Native PowerShell help conventions](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-7.5) - [Official STEMG overview](https://www.asd-ste100.org/about_STE.html) - [Official STEMG FAQ](https://www.asd-ste100.org/STE_faq.html) - [ASD-STE100 Issue 9](https://doi.org/10.5281/zenodo.23666006) </details>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 11, 2026
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. <!-- ANNOUNCEMENT STOP --> ## 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` | <details> <summary>Technical details</summary> ### Immutable delivery evidence - Native Task: [#263](#263), with canonical context, acceptance criteria, technical decisions, test-first plan, source links, and audit comments. - Fixed baseline: `1b0d4893c8fefabe604d04393068a8ff6f848082`. - Final head: `7f19e88045ee50d2e26a39387f44602961deaf90`. - [Scoped comparison](1b0d489...7f19e88): 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](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Capabilities/release-management/spec.md#fr1) and [PR Format](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/PR-Format.md#resolve-release-decisions) 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](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Dictionary/index.md#lts) 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](https://nodejs.org/en/about/previous-releases) explicitly uses long-term support. The official [PowerShell lifecycle page](https://learn.microsoft.com/en-us/powershell/scripting/install/powershell-support-lifecycle?view=powershell-7.5) 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](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_pwsh?view=powershell-7.5) and [immutable MicrosoftDocs source `9fc54e7fc4954f7b4af134def74ba8e8cac7e23c`](https://github.com/MicrosoftDocs/PowerShell-Docs/blob/9fc54e7fc4954f7b4af134def74ba8e8cac7e23c/reference/7.5/Microsoft.PowerShell.Core/About/about_Pwsh.md) 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](https://www.asd-ste100.org/about_STE.html), [FAQ](https://www.asd-ste100.org/STE_faq.html), and relevant local [Issue 9](https://doi.org/10.5281/zenodo.23666006) 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](https://githubnext.com/projects/continuous-ai/), the [Microsoft Learn Dojo path](https://learn.microsoft.com/en-us/training/paths/devops-dojo-white-belt-foundation/), [Dojo introduction](https://devblogs.microsoft.com/devops/intro-of-devops-dojo/), [ISE Playbook](https://microsoft.github.io/code-with-engineering-playbook/), [DORA guide](https://dora.dev/guides/dora-metrics/), [DORA history](https://dora.dev/insights/dora-metrics-history/), and [Thoughtworks Radar](https://www.thoughtworks.com/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](https://github.com/MSXOrg/docs/actions/runs/41840540743): Lint, Build, Links, and Test succeed; Publish is skipped. [Cross-repository links](https://github.com/MSXOrg/docs/actions/runs/41840540797) 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](#273 (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](#273 (comment)) 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. </details> <details> <summary>Related references</summary> - Resolves #263 - References #240 (excluded code/test ownership) </details>
This was referenced Nov 11, 2026
Marius Storhaug (MariusStorhaug)
added a commit
to PSModule/.github
that referenced
this pull request
Nov 11, 2026
<!-- Lead with one concise paragraph describing the user-facing outcome. --> Feature contributors give the current situation first, then the user benefit, the requested change, and an example of the expected result. The inherited PSModule feature form uses direct instructions and present-tense maintainer responsibilities. Its identity, declared labels, single required response, and feedback routing remain unchanged. No consumer-local edit or technical plan is necessary. <!-- ANNOUNCEMENT STOP --> <!-- Add user-facing sections for breaking, new, changed, or fixed behavior when needed. --> ## Changed: Feature requests establish the current situation before the desired change The response remains **Current situation and desired change**. The introduction removes the courtesy opening. The prompts give direct instructions in the same order: 1. Tell us how things work today. Include what is not easy or is missing. 2. Tell us who the change helps and why. 3. Tell us what you want to add or change. 4. Give a real example. Include the situation, your action, and the result you expect. Optional starters use ordinary language. Maintainers review and refine feedback, then select the issue type. The form does not require literal Gherkin syntax, architecture decisions, or a technical implementation plan. Tasks and Bugs retain their technical delivery plans. After merge, PSModule repositories that use inherited issue templates receive the organization-owned form without local configuration or code changes. Repositories with local overrides are unchanged. The chooser metadata, title prefix, `feature`/`triage` declarations, `description` field ID, single required textarea, field label, and blank-issue fallback remain unchanged. --- <details> <summary>Technical details</summary> <!-- Record the implementation approach, issue-plan progress, standards alignment, and convergence sweep. --> ### Scope and source identity Candidate: `7eedb8a44c00bfa0f38d541ea88a7d7d791eaa19` on `psmodule-feature-intake`. The complete PR changes only `.github\ISSUE_TEMPLATE\10-feature.yml`: 23 additions and 5 deletions against `f424237c98b5b020f80e8c9563dbc37256fc1ec0`. The prose revision is one ordinary commit after `e7a14f7eb35eb77bff8b6ba7730c8870a660185d`. It changes only the introduction, textarea description, and optional placeholder text. The form's Git blob changes from `8fb4a887c15961430e78980ac695a8af83029fbc` to `29b9a60ed7e77745fdcf7f0e22b66026c864036a`; the earlier identical-blob claim applies only to the completed test-removal correction, not this prose revision. Other campaign sessions own README/AGENTS/profile and bug/patch/general forms; this branch does not edit those paths. ### Prose acceptance evidence | Concern | Before this prose revision | After | Preserved result | | --- | --- | --- | --- | | Opening | Courtesy thanks before the first instruction | Starts with how things work today | Current situation first | | User benefit and requested change | Questions and conditional wording | Imperative Tell/Give prompts | User benefit precedes the requested change | | Expected result | A real-situation question | An example with situation, action, and expected result | Observable scenario without mandatory formal syntax | | Maintainer responsibility | Will review and decide how to route | Review and refine feedback, then select the issue type | Same maintainers and native routing; present tense | | Optional starters | Would help / would like | Change helps / I want | Same ordinary-language hints, not prefilled answers | A one-time read-only YAML comparison allowed changes only to `body[0].attributes.value`, `body[1].attributes.description`, and `body[1].attributes.placeholder`. The remaining keys and values matched the preceding source. This includes form identity, routing declarations, field ID, required flag, field label, and absence of an assigned native type. The reference URLs and untouched blank-issue configuration retain their roles. This comparison is maintenance evidence, not a retained snapshot test or a test of GitHub behavior. ### Fixed writing sources and limits The campaign uses MSXOrg/docs at `1b0d4893c8fefabe604d04393068a8ff6f848082`: [Documentation Model](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Documentation-Model.md), [Natural Language](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md), [Writing Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md), Markdown, Documentation, and the applicable issue/Task/PR formats. All required pages were available. The official [STE overview](https://www.asd-ste100.org/about_STE.html), [FAQ](https://www.asd-ste100.org/STE_faq.html), and [Issue 9 DOI](https://doi.org/10.5281/zenodo.23666006) were available. The PDF was read in memory, and its MD5 matched the official record. The review consulted active-voice rule 3.6, procedural rules 5.1-5.3, and relevant dictionary entries for prompt wording, including Tell/Give and alternatives to Explain/Describe. Reference content was not republished. This is a scoped manual prose review, not a full word-by-word STE certification. Domain terms retain their MSX meaning. A word count, static lint result, or automated approval does not prove complete STE conformance. ### Static checks and testing boundary | Existing command or inspection | Result and limit | | --- | --- | | `yamllint --strict .github\ISSUE_TEMPLATE\10-feature.yml` | Passed, exit 0. Existing static YAML lint only. | | `git --no-pager diff f424237 HEAD --check` | Passed. Whitespace inspection only. | | Read-only comparison against `e7a14f7eb35eb77bff8b6ba7730c8870a660185d` | Only permitted display values differ; non-prose keys and values are unchanged. No comparison script is committed. | | `gh api repos/PSModule/.github/pulls/89/files --paginate` | Exactly one changed file: the feature form, 23 additions/5 deletions. | The 198-line Pester snapshot suite remains removed. Its historical 25 assertions did not test GitHub rendering, submission, or routing; the earlier functional-coverage claim stays withdrawn. No replacement content assertions, schema snapshots, runtime simulation, test dependency, validator, workflow, hook, or test issue is added. No live GitHub form test was executed or claimed. Static/manual inspection and review do not establish that unexecuted coverage. Pre-commit alignment remains deferred, and the separate testing-policy cleanup remains independent. ### Plan, review, and lifecycle [#88](#88) records the new user-directed prose acceptance decision and the preserved testing boundary. Its earlier test-removal identity is historical evidence; current prose evidence uses the candidate above. **Original delivery checkpoint (November 4):** The [exact-head review](#89 (review)) approved the candidate at `2026-11-04T12:27:50Z`, with zero inline comments and no active review issues. Previous-head approvals are not reused. The November 4 review and static-check receipts above remain historical evidence, not a new review or current hosted CI result. **Original lifecycle-only pause:** At the November 4 checkpoint, this PR stayed unmerged while the requested independent testing-cleanup proposals were created. Agent merge and automatic landing were disabled. This records the original delivery checkpoint; it is not an outstanding requirement to adopt or merge those proposals. **Current prerequisite record (November 11):** The creation request is fulfilled by [MSXOrg/docs#240](MSXOrg/docs#240), [PSModule/Process-PSModule#551](PSModule/Process-PSModule#551), and the source-bound no-test audits of MSXOrg/.github and PSModule/.github. No native dependency requires adoption or merge of those unrelated proposals. No content question remains. The [fresh prerequisite and exact-head evidence](#88 (comment)) records those source identities, native relationships, fresh existing-tool checks, and their limits. The root has granted bounded operational acceptance of unchanged head `7eedb8a44c00bfa0f38d541ea88a7d7d791eaa19` under the user's live direction to review remaining changes and merge them when ready. The root has not granted this PR the exclusive global merge slot; Process owns it. A bounded exact-head squash is permitted only after that slot is granted. No merge or automatic landing is authorized now. The current native state remains open, not draft, and unmerged, with GitHub `autoMergeRequest=null`. Agent merge remains disabled; actions remain `address_reviews=true`, `fix_ci=true`, `resolve_conflicts=true`, and `merge_pr=false`. Current hosted check-runs and commit statuses are empty, not green CI. No changed coverage or organization rule is claimed. The absent-CI, static/manual-only, and STE verification limits remain in force. | Changed surface | Standards checked | Framework/domain docs checked | Result | | --- | --- | --- | --- | | Feature-form display prose | Fixed MSX writing baseline; relevant official STE rules/dictionary; existing YAML guidance | GitHub issue-form roles; native feedback refinement and Task/Bug planning boundaries | Fixed in this PR | | Removed-test state and evidence | MSX Testing: Test supported behavior | None (no owned form runtime) | Aligned; live behavior unexecuted | The exact feature-form-path issue sweep found this Task, the separate writing campaign issues, and the broader YAML work. No additional issue is fully delivered by this feature-only branch; this PR has only [#88](#88) as its closing delivery leaf. The Task remains open, and the PR is unmerged. Retired validator/governance work is not reinstated. Issue states/relationships, repository labels/protections, and other community files remain unchanged. </details> <details> <summary>Related references</summary> <!-- Use fully qualified repository references for closing and related work. --> - Resolves [#88](#88) ### Related work - References [MSXOrg/docs#228](MSXOrg/docs#228) - References [MSXOrg/docs#230](MSXOrg/docs#230) </details>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

Documentation tooling tests exercise real commands and retain package-quality gates without fixed skill inventories or transport call counts. The link-checker tests no longer extract an internal function from source.
The command-level tests found a real underscore-anchor defect. The user approved the narrow heading-helper fix, so valid GitHub anchors keep their literal underscores. No consumer action is required.
Fixed: GitHub heading links keep literal underscores
The cross-repository link checker accepts the correct
#snake_case-and-kebab-caseanchor and rejects the form that removes the underscore. It preserves literal underscores, code spans, and valid adjacent or nested formatting. GitHub-literal{#custom}text also remains part of the heading instead of becoming a site-specific attribute. Existing links and command inputs need no change.Technical details
Review-ready: implementation, source-bound audit, local validation, and exact-head CI are complete. All 5 findings from the first two full reviews have fixes, regression cases, replies, and resolved threads. The final exact-head review is APPROVED and states that there are no active/open issues. No merge was performed; GitHub auto-merge and app Agent merge remain off.
Source and scope
33ccfaae6d905150f104dd763e34bf36cb2de1f91b0d4893c8fefabe604d04393068a8ff6f848082ee3c17855cb282cdf236fc764df3f45502f4c057fd153feef3ddac71c587eb2c547623a01379379fBoth complete recursive tree responses report
truncated=falseand the same six suite files. #237 merged intomainduring the audit and added two fixed catalog assertions. This branch was refreshed from that merged default-branch commit, not an open PR branch. Its writing, skill, navigation, and manifest changes are baseline context, not this PR's delta.The scoped diff changes exactly four files:
.github/scripts/Test-CrossRepositoryLink.ps1,tests/PluginMarketplace.Tests.ps1,tests/Test-CrossRepositoryLink.Tests.ps1, andtests/Update-GitHubActionPin.Tests.ps1. The user approved only the demonstrated heading-helper defect as a runtime exception. No policy, workflow, pin, security setting, or unrelated production code changed. The draft opened immediately after the first focused commit; the authorized fix, catalog cleanup, and review corrections have separate focused commits.The helper reuses the Markdig.Signed assembly already bundled with PowerShell. It selects CommonMark plus GitHub's autolink and strikethrough inline extensions, not PowerShell's advanced/site-specific extensions. It does not enable generic attributes or use renderer-generated anchor IDs. The existing GitHub slug algorithm stays unchanged. No parser package, module, runtime, or framework was installed or added.
Compatibility evidence is source-bound: PowerShell v7.0.0 ships Markdig.Signed 0.18.1, and the selected public APIs exist at renderer source
dd6418d108c6cb66f2196ad04fad5d59a231e72e. The script's PowerShell 7.0 minimum is unchanged. Current Windows and Linux execution is verified below; no separate PowerShell 7.0 execution is claimed.Evidence inventory
-Checkmode. All pass. This does not enforce checked-in index drift.The repository owns no plugin installer or separate production manifest validator. The retained package cases are format-quality safeguards, not proof of client behavior. The required canonical selector follows the Agent Plugins manifest contract; a parsed file plus a fixed string is not presented as behavioral coverage. The package profile, marketplace contract, and Agent Skills specification support these limited checks. The Task holds the complete group-by-group inventory and source evidence.
Validation and full-review disposition
pwsh -NoLogo -NoProfile -File .\.github\scripts\Invoke-PesterSuite.ps13461c4350868329c8530904d170358bca1d31448verifies all 31 positive anchor expectations. Existing Node v26.12.1; no package installation or added dependency.mode=gfmconfirms the new headings' visible text, including the review examples and literal generic attributes. This response is not claimed as the automatic-slug oracle. Production renderer output is not used to compute expected anchors.git diff --checkpasses. All documentation links resolve across 130 files.ee3c17855cb282cdf236fc764df3f45502f4c057: Lint, Build, Links, and Test succeed. The CI runner reports 83 passed, 0 failed, 0 skipped. Publish is intentionally skipped.All 64 original tests passed, but the complete command rejected the valid underscore anchor. Test-first evidence remains in the Task and #241. Correct expected values were retained. An attempted name filter selected 0 cases and is excluded from evidence; counted runner results supply the actual red and green runs.
9e19827aac3ca91ec3d44680c289324d6e196790617914a03a6318e3997800527903480befa5d828ee3c17855cb282cdf236fc764df3f45502f4c057No active review issuesandNo open issues, and confirms the remaining issue is resolved. No new inline comments; all 5 threads are resolved, with complete thread pagination verified.The clean result is based on the full summary, exact source identity, and resolved threads, not only the runner exit or new-comment count. The native closing references were verified for the Task and its convergent user-approved Bug.
Simulated release responses make mutable latest-release data and invalid/unavailable responses deterministic without live quota use. The loopback service permits safe missing-target, quota-exhaustion, and HTTP-failure cases. These checks prove caller behavior, not live authentication or every vendor failure mode. The existing public read-only CI cross-link job is separate live evidence: Ubuntu 24.04, repository-scoped workflow token, public repository reads, no remote writes or resources to clean up. No live pin-updater API check or plugin-client installation/activation test was run. Metadata checks are not complete schema validation or trigger-reliability evidence. Scratch experiment files were removed after verification; durable evidence stays in GitHub.
Standards and convergence
tests/PluginMarketplace.Tests.ps1tests/Update-GitHubActionPin.Tests.ps1tests/Test-CrossRepositoryLink.Tests.ps1.github/scripts/Test-CrossRepositoryLink.ps1heading helperThe alignment pass re-read the process, testing, PowerShell, and applicable format guidance.
.github/CONTRIBUTING.mdand the generator's optional-Checkguidance already describe the retained commands correctly. Only help tied to the changed heading helper needed an update. No policy prose or repository notes were added. The route builds and deploys Pages; no Release Management block or labels apply.The scoped open-issue sweep covers tests, tooling, plugins, and anchors. It finds the closing Task and the fully delivered user-approved underscore defect, with no other convergent issue. The unrelated policy PBI #105 and published-URL, AGENTS-routing, navigation, and writing-campaign work remain outside this diff. All implementation, validation, and review plan steps are complete. No scoped blocker remains.
Campaign qualification supplied by the coordinator, not this PR's own audit: complete recursive trees (
truncated=false) for MSXOrg/.githubmainat0c67251812ea306543f3a14ab473ae357cfb76acand PSModule/.githubmainat4e0092de8f208b11e0d4607ced93471607aa748econtain no test code, runners, scripts, dependency manifests, hooks, or validation workflows. No empty PR is warranted for those snapshots. Open branches, including PSModule/.github#89, were not imported. PSModule/Process-PSModule has a separate scoped audit; this PR covers only MSXOrg/docs.Related references