Skip to content

Keep documentation tooling tests focused on supported behavior - #240

Open
Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
mainfrom
functional-test-alignment
Open

Marius Storhaug (MariusStorhaug) wants to merge 6 commits into
mainfrom
functional-test-alignment

Conversation

@MariusStorhaug

@MariusStorhaug Marius Storhaug (MariusStorhaug) commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

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-case anchor 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

Field Verified identity
Initial live main and clean worktree 33ccfaae6d905150f104dd763e34bf36cb2de1f9
Refreshed default-branch baseline 1b0d4893c8fefabe604d04393068a8ff6f848082
Reviewed candidate ee3c17855cb282cdf236fc764df3f45502f4c057
Unchanged Testing policy blob fd153feef3ddac71c587eb2c547623a01379379f

Both complete recursive tree responses report truncated=false and the same six suite files. #237 merged into main during 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, and tests/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

Suite or group Disposition, real entry point, observed result, and policy reason
Marketplace uniqueness and source resolution Retain 2 existing static package-quality cases through Pester, the JSON reader, and filesystem checks. The current package and an anonymous positive fixture pass; duplicate identities fail. No specific plugin name or count is required.
Manifest identity/version/schema selector Retain the existing public package-profile check. The canonical selector is required by Agent Plugins; matching advertised identity/version follows the marketplace contract. This is static quality, not full-schema or installer coverage.
Agent Skills metadata Retain the required-file and metadata checks, and rename the group to state its limited scope. All 4 package-quality cases pass; no instruction phrase is checked.
Writing skill inventory Remove the count-of-one and fixed writing-skill directory assertions from the newly merged baseline. They do not invoke client discovery or an owned runtime.
Issue/PR/workflow skill inventory Remove the three hard-coded directory requirements and their unused enumeration setup. Do not replace them with another list, source search, snapshot, or validator.
Requires-Modules ranges, exact versions, GUIDs, and exits Retain all 11 real child-PowerShell cases: 3 range, 2 exact-version, 3 identity, and 3 process-exit checks. All pass.
Cross-link broken and resolving targets Retain 4 broken-target and 5 resolving-target command cases, including checkout resolution, branch/README anchors, and cache reuse. All pass against temporary repositories and a loopback service.
GitHub/site slug distinctions Retain all 3 real-command punctuation, wrong-site-slug, and duplicate-heading cases. All pass.
Internal slug cases Rewrite all 14 AST-extracted cases through the complete checker command, with the original expected anchors unchanged. Add 17 positive underscore/formatting/inline-code cases and 2 incorrect-anchor cases. All 33 pass; no source extraction remains.
Cross-link zero-work/scope and service/quota outcomes Retain all 3 scope/empty-work and 4 error/quota command cases. All pass. Request-count checks here measure documented cache/quota behavior, not an arbitrary call sequence.
Documentation link checker Retain all 6 real-command footnote, reference, and inline-link cases on controlled temporary pages. All pass.
Documentation index generator Retain 2 unchanged-byte, 2 stale-input rejection, and 2 LF/CRLF repair cases through the real generator and supported -Check mode. All pass. This does not enforce checked-in index drift.
Action pin updater Retain all 4 real-updater update/encoding/WhatIf/unchanged/error cases on temporary YAML and controlled release responses. All pass. Remove only the exact count of 6 REST calls.
Runner and CI Preserve Pester discovery and zero-work guards, named Test job, lint, local and cross-repository links, index generation, site build, pins, and security settings. Previously removed documentation-content suites and checked-in index-drift enforcement stay removed.

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

Command or control Actual result at the reviewed candidate
pwsh -NoLogo -NoProfile -File .\.github\scripts\Invoke-PesterSuite.ps1 83 passed, 0 failed, 0 skipped across 6 suites. PowerShell 7.6.9 on Windows; unchanged runner pin Pester 6.0.1.
Focused suite paths through the same runner Pin updater: 4 pass before/after. Marketplace: 6 pass before catalog cleanup, 4 after. Cross-link checker: 52 pass.
Independent anchor oracle Actual github-slugger 2.0.0 at 3461c4350868329c8530904d170358bca1d31448 verifies all 31 positive anchor expectations. Existing Node v26.12.1; no package installation or added dependency.
Independent heading rendering GitHub Markdown API mode=gfm confirms 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.
Anonymous package-quality controls Positive retained-field fixture: exit 0, 4 pass. Duplicate identity: exit 1, 1 expected failure. Empty catalog: exit 1 through both the runner and direct Pester.
Repository static and link checks 0 configured PSScriptAnalyzer diagnostics in all 4 changed files; git diff --check passes. All documentation links resolve across 130 files.
Docs CI Successful pull-request run at ee3c17855cb282cdf236fc764df3f45502f4c057: Lint, Build, Links, and Test succeed. The CI runner reports 83 passed, 0 failed, 0 skipped. Publish is intentionally skipped.
Cross-repository Links CI Same exact head: 7 in-scope links checked across 134 Markdown files; every link resolves.

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.

Full review read Exact head Summary and disposition
First review 9e19827aac3ca91ec3d44680c289324d6e196790 Changes recommended: 4 valid findings for adjacent formatting, nested underscore delimiters, unequal backtick runs, and unmatched backticks. All 7 examples first fail through the command, then pass after renderer reuse. All 4 threads have specific replies and are resolved.
Second review 617914a03a6318e3997800527903480befa5d828 Changes recommended: confirms the 4 earlier fixes; finds 1 valid generic-attribute regression. Correct-anchor acceptance and wrong-anchor rejection first fail (50 pass/2 fail), then pass with GitHub inline syntax (52 pass/0 fail). Its thread has a specific reply and is resolved.
Final review ee3c17855cb282cdf236fc764df3f45502f4c057 APPROVED. The complete summary states No active review issues and No 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

Changed surface Standards checked Framework or domain docs checked Result
tests/PluginMarketplace.Tests.ps1 Testing; PowerShell Testing; Code Layout; Natural Language Package profile, marketplace contract, Agent Plugins and Agent Skills formats Fixed in this PR
tests/Update-GitHubActionPin.Tests.ps1 Testing; PowerShell Testing; Code Layout Existing updater parameter and output contract Fixed in this PR
tests/Test-CrossRepositoryLink.Tests.ps1 Testing; PowerShell Testing; Naming; Error Handling Checker command help and independent GitHub heading/anchor evidence Fixed in this PR
.github/scripts/Test-CrossRepositoryLink.ps1 heading helper Functions and reuse-before-build; PowerShell; Documentation; Natural Language Existing heading contract, bundled renderer API provenance, GitHub Markdown, pinned slugger Fixed in this PR

The alignment pass re-read the process, testing, PowerShell, and applicable format guidance. .github/CONTRIBUTING.md and the generator's optional -Check guidance 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/.github main at 0c67251812ea306543f3a14ab473ae357cfb76ac and PSModule/.github main at 4e0092de8f208b11e0d4607ced93471607aa748e contain 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

This was referenced Nov 4, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The link checker strips heading attributes that GitHub preserves as literal text, causing it to reject valid anchors and accept nonexistent ones.

1 open issue
4 resolved since last review

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues are recorded for the documentation-tooling tests and heading-anchor changes.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@MariusStorhaug
Marius Storhaug (MariusStorhaug) marked this pull request as ready for review November 4, 2026 13:24
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>
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

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Preserve in-word underscores when checking GitHub heading anchors [functional-test-alignment] Test supported documentation tooling behavior

2 participants