You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Pull request guidance describes complete source-bound records - #209
PR Format describes the actual title and complete body: audience-first results, release-range-first analysis, complete adoption/compatibility evidence, one announcement boundary and conditional release decisions. Repository file policy is owned separately by Repository/Organization/Governance guidance, not by the PR Format page.
Authors use canonical guidance for the resulting record. Repository standards exclude GitHub PR-template files from ordinary and central-default sources, while retaining other community defaults, genuine repository-specific contribution instructions and supported product-integration contracts. This delivery changes guidance and checks in MSXOrg/docs; separate owners remove their actual source/consumer files. No publisher, live caller, artifact, tag, governance setting or release history is changed here.
Changed: PR Format focuses on the complete authored record
Use one short reader-facing title and an audience-first summary, then ordered non-empty Breaking, Removed, New, Changed and Fixed results. Explain what changed, why, affected supported uses, compatibility and complete adoption actions or a justified no-action result in each result's prose. Keep prerequisites, ordering, verification and mandatory intermediate operations in the record itself, with supporting evidence and references scoped to the result they verify.
The complete in-document example is named Complete description example. Its anchor is now #complete-description-example, replacing #copy-the-complete-template. The single announcement boundary and full body remain unchanged in purpose; announcements do not truncate the published note. Maintained links adopt the new anchor. Existing skills still route to the same canonical PR Format page and its release-coverage analysis; no additional skill, file distributor or plugin installation is required for this correction.
PR Format contains no repository PR-template-file discussion: no file locations, copying/inheritance, local exceptions, presence/absence policy or deletion history. Those rules belong to the repository standards below. Product integration-template compatibility evidence remains distinct and required where a delivered result affects a supported integration.
Technical details
Changed surface
Standards checked
Framework docs checked
Result
PR Format complete example, record evidence and anchors
Natural Language, Markdown, Documentation Model, PR Format
Complete consumer record and source-range authoring
Aligned
Release Management result evidence
Specification/design separation, Markdown
Actual title/body/source coverage, retained product-integration compatibility
Aligned
Repository-specific contribution PR-format links
Markdown, canonical ownership
Full description example; existing local build/index/link instructions
Required structure, one boundary, five classifiers/evidence prompts and release-first order
Aligned
The tests separate record quality from repository file policy. Record tests verify the complete example and ordered classifiers, marker count, publication/candidate identity fields, five scoped release-evidence prompts, release-first analysis, and five affected-product integration prompts. They also reject GitHub PR-template-file discussion on this page without rejecting legitimate product integration contracts. File-policy tests inspect the owning repository/organization/governance pages, not PR Format. Five ownership/naming cases failed before the refinement and pass after it.
The old example link is a documentation-anchor transition, not a runtime migration. Required old-to-new consumer actions still belong in the relevant release record; product docs retain supported target-state usage rather than a migration hierarchy or changelog.
Changed: Repository standards require canonical adherence without PR-template files
Repository Standard owns the no-file rule for every MSX repository type and the special MSXOrg/.github and PSModule/.github sources. GitHub PR-template files, multiple-template directories, generated copies and local exceptions are not part of this contract. Organization Standard and Repository Governance reference that one owner; their former mandatory default-file rows and local PR-template exception are removed.
Authors and validators verify the actual title, complete body, source coverage, compatibility/adoption evidence and normal review gates. An inherited scaffold, file-presence check or similarity to a central copy does not prove adherence. The complete canonical record example remains in the docs. Other code-of-conduct/security/support/contribution/issue-intake defaults and genuine repository-specific contribution instructions are unaffected; this is not an organization-wide community-file cleanup.
Separate source and consumer owners remove existing PR-template files and revise their source docs/check expectations. This PR introduces no distributor, physically edits none of their workspaces and claims no pending deletion is merged. A missing file never substitutes for Markdown/source/head/containment validation or complete PR record quality.
Technical details
Changed surface
Standards checked
Framework docs checked
Result
Repository Standard no-file policy and PR/contribution guidance
Standard ownership, Markdown, Natural Language
One policy owner; canonical actual-record verification
Aligned
Organization Standard community/review/default rows
Standard ownership, Markdown
Other community defaults preserved; PR-file requirements/exceptions removed
Aligned
Repository Governance defaults and reconciliation evidence
Design ownership, Markdown
Required-source row removed without changing live controls
Aligned
Markdown linter comment
YAML/Markdown standards
Only obsolete PR-template commentary changed; parsed configuration values are identical
Aligned
Repository-policy regression block
PowerShell/Pester, source inventory
Own-policy links, no tracked PR file, case/extension/directory detection, unaffected issue forms
Aligned
The corrected regression checks were run against exported frozen guidance with no commits: five actual policy cases failed while eleven preservation/path cases passed. Current source checks recognize uppercase/lowercase PR file names, alternate extensions and multiple-template directories, while leaving issue forms and canonical PR Format docs unaffected. MSXOrg/docs contains no tracked GitHub PR-template file.
Independent full, non-truncated default-source reads confirmed these still-present files at the measured immutable sources:
Repository
Source
File
MSXOrg/.github
0c67251812ea306543f3a14ab473ae357cfb76ac
.github/pull_request_template.md
PSModule/.github
f424237c98b5b020f80e8c9563dbc37256fc1ec0
.github/pull_request_template.md
PSModule/Yml
93d2656563a719d99416b9e13a05e65f6f815498
.github/pull_request_template.md
PSModule/PSSemVer
1a621b14286331569f4d1ffd4643999c2a2a6ca8
.github/pull_request_template.md
These are measured source/consumer counterexamples with separate removal owners, not evidence that the new no-file state has already landed. The Project's complete 71-repository inventory additionally identified the stale PSModule/Template-PSModule#42 candidate as separately owned reconciliation. PSModule/Process-PSModule#525 tracks the bounded producer anatomy/audit requirement reconciliation; central/default validators have separate owners. Their publisher/Build/runtime behavior remains outside this documentation revision.
The MSXOrg/docs#231 owner confirmed its clean frozen branch and no pending overlapping edits. The exact community composition boundary is the PR-template rows/paragraphs only: preserve its conditional local-contribution rule and all other inherited defaults while adopting the new no-file policy links. No #196/#208/#230/#231 tracked branch was edited here.
Changed: Release-bound authoring starts from actual artifact publication
Before drafting the title, results, adoption actions or compatibility decision, resolve the actual latest successful artifact publication for the same product, target and channel and verify its immutable source. Pin that artifact/source and the exact candidate PR source, verify intended lineage and compare those source trees. The complete delivered range includes earlier merged, skipped or unshipped changes; the ordinary PR-base diff remains separate implementation/reviewer evidence, not the note boundary.
A GitHub Latest hint, moving tag, assumed highest version or overall failed run is not publication-baseline proof. Module publication to Gallery counts even when later GitHub completion fails: the next module record starts from its already-published source. Completing that older GitHub record does not make module changes new again. Multiple artifact targets/channels have independently pinned consumer baselines and applicability.
Resolve missing/unverifiable evidence, ambiguous scope and diverged lineage explicitly. A verified initial publication has reviewed whole-candidate coverage and initial adoption instructions, not a fabricated predecessor or no-action/patch assumption. Re-read publication and candidate identities before readiness/snapshot capture and refresh comparison, actions and compatibility when either changes. This is the preserved authoring procedure, not a new publisher/version resolver or Build/artifact-promotion design.
Technical details
Changed surface
Standards checked
Framework docs checked
Result
Publication-baseline-first procedure, five result prompts and readiness
PR Format, Markdown
Exact publication/candidate identities, complete range and scoped PR diff
Aligned
Release Management source binding and note evidence
Specification/design ownership
Actual artifact publication versus version/completion baselines
Aligned
Thin PR-format skill and paired plugin metadata
Plugin granularity/versioning, manifest tests
Prior 0.1.1 canonical entrypoint retained
Aligned
The anonymous Git experiment remains exact source-tree evidence: published A-to-candidate C includes earlier unshipped B and current C, while scoped B-to-C includes only the current PR. Simulated Gallery-success/GitHub-failure evidence for B keeps module coverage at B-to-C even after older GitHub completion. Changed candidate/publication pairs change coverage, and unrelated lineage is rejected. Receipts were simulated inputs, not a live publish or historical repair.
Local validation passes: all 80 Pester tests in seven suites, 127 documentation pages plus contribution-guide lint, indexes/relative anchors, seven cross-repository links, actual pinned Zensical 0.0.59 build and rendered new-anchor checks, zero PowerShell analyzer diagnostics, existing plugin-manifest validation, and patch checks. The parsed linter configuration remains unchanged. All five required hosted checks succeed on this exact head: Lint, Build, Test, Links, and Cross-repository links. Both completed pull_request runs identify this source head.
Complete current-head review:5725019918 is APPROVED on bc03a5992615f65d1d5346dc48e7506e80b8b6ca. The full summary records no active/open or suppressed concerns; all review threads are resolved and thread pagination is complete. The prior be8c340 approval was not used as approval of this correction. This is the automated author-side pass, not independent human approval or permission to merge.
All five existing Task #226 plan items are fulfilled: verified state/cases, bounded canonical authoring, directly coupled policy/evidence/link reconciliation, native checks/current-head full review, and final acceptance/immutable handoff. The scoped sweep covered PR authoring, source/default validation, release/consumer and community guidance; only Task #226 is the closing delivery leaf. The existing native prerequisite MSXOrg/docs#166 is completed. Its five-context required-check rule and the existing approval/thread constraints remain unchanged; no live merge attempt, injected failure or bypass was used.
Changed: Effective decisions and release-history ownership are preserved
DefaultBump still accepts patch/minor/major with documented shared patch, repository settings, explicitly supplied supported caller overrides and one explicit owned bump override in that order. Omitted inputs inherit valid policy; invalid supplied settings and conflicting owned signals fail even when another source supplies a level. An effective default removes the need for a per-PR bump label, not the need for compatibility evidence. The exact owned set remains release:patch, release:minor, release:major, release:prerelease and release:skip.
Verify actual native/shared producer controls or a supported adapter before using signals. Prerelease uses the resolved bump; skip combines with no other owned signal. Unmanaged routes omit all release metadata/labels; this repository deploys Pages without a versioned release artifact, so this PR retains neither a Release decisions block nor a release label. No undecided caller-override interface, allocator, publisher or live input is approved or implemented here.
Complete PR/release records remain the sufficient version-specific upgrade history; resource docs describe supported target-state usage. Mandatory intermediate operations and superseded actions remain explicit. Campaign/native associations and completion-aware issue links retain their established ownership. No migration-guide/changelog duplication, date strategy, native dependency mutation, publication, historical backfill, label/permission/rules edit, merge or auto-merge is performed.
Technical details
Changed surface
Standards checked
Framework docs checked
Result
Automation Labels, settings/decision rules, VS Code and continuous-delivery guidance
Owning standards/capabilities
Accepted default/signal, source validation and native mapping retained
Aligned
Documentation Model, Fleet, workflow/readiness and Task/Bug planning
Ways of Working, issue hierarchy, PR Format
Actual scoped implementation evidence and sufficient consumer record preserved
Aligned
The existing PRs stay separate on main. Eventual landing is one at a time with every remaining overlapping branch reconciled against advanced main and CI/full review repeated. Other owners must consume the refreshed immutable correspondence; their prior frozen example/file expectations are not claimed current. This PR does not edit their tracked candidates or waive their independent prerequisites.
Replace the icon-and-type schema with audience-first titles, evidence-based descriptions, and route-conditional MSX release decisions. Document the inherited organization template and refresh navigation and anchor references.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Keep workflow mechanics in their owning pages, make release decisions conditional on route invocation, and preserve campaign identity without polluting reader-facing pull request titles.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Replace the channel-specific Slack boundary with the approved announcement marker while preserving exact once-only placement.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This documentation-only PR establishes audience-first pull request guidance across MSX and makes release records the authoritative source of consumer upgrade instructions.
Changes:
Replaces prefixed titles and global evidence blocks with reader-facing results, ordered classifiers, and section-scoped evidence.
Defines conditional release metadata, release defaults, and native-producer applicability.
Aligns workflow, fleet, dependency, and documentation guidance with the canonical PR format.
File
Description
src/docs/Ways-of-Working/Workflow.md
Clarifies PR descriptions as durable, release-ready records.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
The promotion guidance conflicts with caller-override precedence and could cause authors to record a bump that differs from the resolver’s effective DefaultBump.
This restricts promotion bumps to a label or the repository default, conflicting with the caller-override precedence in release-management/design.md:108–117. For example, repository DefaultBump: major with a supported explicit caller override of patch and no bump label resolves to patch, but this instruction tells the promotion author to record major. Refer to the valid effective DefaultBump, including shared defaults and supported caller overrides, so promotion records agree with the resolver.
Marius Storhaug (MariusStorhaug)
changed the title
Pull request guidance starts from the published artifact source
Pull request guidance describes complete source-bound records
Oct 31, 2026
Solution-owned settings use the conventional filename
`<name>.settings.yml`. The release solution uses
`.github/release.settings.yml`; module repositories retain
`.github/PSModule.yml` through `SettingsPath`, including module release
settings.
The documentation-content test file and CI documentation-index drift
gate are removed. Functional tooling tests, linting, link validation,
and site builds remain; no module migration or runtime loader is
implemented here.
<!-- ANNOUNCEMENT STOP -->
## Removed: Tests that lock documentation content
`tests/PR-Format.Tests.ps1` is deleted in full at the user's request,
including its PR-format, filename, naming, and repository-policy
assertions. No replacement tests of checked-in documentation or workflow
content are added. The Naming standard no longer claims test coverage
for its prose.
The follow-up audit covers all six remaining suites and both workflows.
The remaining suites exercise scripts on temporary fixtures, PowerShell
engine behavior, and plugin metadata/schema validity. They do not lock
the actual documentation's wording or assert the actual workflows'
contents. The user explicitly chose to retain these functional tool
tests, together with linting, link validation, and site builds.
<details>
<summary>Technical details</summary>
The entire 329-line documentation suite is absent, including all 39
assertions it contained. Historical audit comments and earlier test
totals describe preceding iterations, not tests present in this
candidate. No replacement prose or workflow-content tests were
introduced.
The complete scoped comparison is accepted main
`aa9b5cecc69f4cbe6aa04a5dd70ff9cdadeeac3d` to candidate
`8daf026a14036dee04786d371883e8871b5ec2f4`. The [latest bounded
change](3d7c58e...8daf026)
removes drift enforcement without changing any test suite or
index-generator logic.
| Changed surface | Standards checked | Framework or domain docs checked
| Result |
| --- | --- | --- | --- |
| `tests/PR-Format.Tests.ps1` (deleted) | User-directed removal and test
discovery | Existing Pester suite discovery | Aligned |
| Naming enforcement statement | Naming, Natural Language, Markdown |
None (no framework-specific docs) | Aligned |
All 64 tests in the six retained functional suites pass on the current
head, verified from the completed CI job. The six index-tool fixture
cases also pass locally; these exercise optional diagnostics,
regeneration, and line endings on temporary files, not drift in this
repository's actual docs. No suite is rewritten to inspect the
checked-in documentation or workflows.
The [fresh exact-head
review](#233 (review))
approves `8daf026a14036dee04786d371883e8871b5ec2f4` with zero new inline
comments. All five required checks pass:
[Lint](https://github.com/MSXOrg/docs/actions/runs/41497449037/job/125456000472),
[Build](https://github.com/MSXOrg/docs/actions/runs/41497449037/job/125456000462),
[Links](https://github.com/MSXOrg/docs/actions/runs/41497449037/job/125456000312),
[Test](https://github.com/MSXOrg/docs/actions/runs/41497449037/job/125455999512),
and [Cross-repository
links](https://github.com/MSXOrg/docs/actions/runs/41497448823/job/125455993357).
The earlier consistency thread remains resolved. Publishing is
intentionally skipped for this PR.
</details>
<details>
<summary>Related references</summary>
- Resolves#232
</details>
## New: Solution-owned settings filenames identify their owner
Use the owning solution's name for its conventional settings filename.
The Naming standard defines this once; repository, YAML, and release
guidance link to it. The rule does not rename tool-mandated manifests,
lockfiles, workflow filenames, or arbitrary YAML files, and it does not
impose one directory on every solution. Supported explicit custom paths
remain governed by each reader's existing input contract.
Module repositories keep `.github/PSModule.yml` through `SettingsPath`,
including module release settings. The PSModule initiative records this
supported exception and links to the framework's actual input and
settings references. No module filename migration, second release
settings file, or caller-input change is required here.
The VS Code framework design retains `.github/vscode-extension.yml` as
an explicit supported naming exception. Its settings keys and interface
are unchanged; a filename change requires a verified reader and separate
template/caller migration.
<details>
<summary>Technical details</summary>
| Changed surface | Standards checked | Framework or domain docs checked
| Result |
| --- | --- | --- | --- |
| `src/docs/Coding-Standards/Naming.md` | Naming, Natural Language,
Markdown, standard template | None (no framework-specific docs) |
Aligned |
| `src/docs/Coding-Standards/YAML.md` | YAML, Naming, Markdown | None
(no framework-specific docs) | Aligned |
| `src/docs/Ways-of-Working/Repository-Standard.md` | Repository
Standard, Naming, Markdown | Repository Governance required-files model
| Aligned |
| `src/docs/Initiatives/PSModule.md` | Documentation Model, Natural
Language, Markdown | Process-PSModule workflow inputs and settings |
Aligned |
`Naming.md#solution-settings-files` owns the rule;
`PSModule.md#module-settings` and the VS Code configuration surface own
the supported exceptions. Related guidance links to those owners rather
than defining another rule. The directly related obsolete framework
overview link is corrected to its actual canonical site route.
The module default was verified from Process-PSModule source
`105e4dcefe1946782066aa50a5c7d3658319895a` and the [published
workflow-input
reference](https://psmodule.io/Process-PSModule/reference/workflow-inputs/).
The [settings
reference](https://psmodule.io/Process-PSModule/reference/settings/)
owns module keys and defaults. Neither the workflow, its input, schema,
nor enriched runtime settings object changes here.
The earlier VS Code consistency finding remains addressed by its
owning-guide exception, independently of the deleted assertion. The
scoped issue-convergence search finds no additional complete ask
satisfied by this naming slice; broader default-bump/keyed-route and
lifecycle work stays separate.
</details>
## Changed: Release settings use the release solution's canonical
filename
The optional release-solution file is `.github/release.settings.yml`,
replacing the documented `release.config.yml` convention. Its `.github`
location, settings keys, schema, defaults, precedence, omission
behavior, applicability, and required decision validation are unchanged.
All 17 original current-guidance substitutions remain. This repository
has no settings file or runtime loader to rename.
The former `.github/auto-release.yml` is migration evidence for the
separately owned Release-GHRepository reader change, not a current
alternative convention. `ConfigurationFile` remains the public input,
distinct from its conventional default filename. This documentation PR
does not deliver or release that reader. Consumers verify their producer
revision and its migration record before adopting a changed default;
module release settings remain under the supported `PSModule.yml`
interface.
<details>
<summary>Technical details</summary>
| Changed surface | Standards checked | Framework or domain docs checked
| Result |
| --- | --- | --- | --- |
| Release Management spec and design | Documentation Model, Naming,
Markdown | Applicability, defaults, overrides, and decision validation |
Aligned |
| VS Code framework design | Documentation Model, Naming, Markdown |
Existing extension interface and release configuration | Aligned |
| Automation Labels and PR Format | Natural Language, Markdown, owning
standards | Release-route applicability and complete-record ownership |
Aligned |
The accepted release-range-first analysis, complete description example
with one summary boundary, conditional release/default rules, Task/Bug
planning, and repository-owned no-PR-template policy are preserved
without tests of their prose. Runtime default/migration work belongs to
PSModule/Release-GHRepository#109, not this source. No module file,
loader, public input, Build/metadata/runtime schema, publisher, pin,
permission, ruleset, marketplace, or consumer fleet change is included.
</details>
<details>
<summary>Related references</summary>
- References PSModule/Release-GHRepository#109
- References #196
- References #208
- References #209
</details>
## Changed: Documentation builds regenerate indexes without a drift gate
CI generates documentation indexes before building the site instead of
rejecting an out-of-date generated table. A documentation edit no longer
needs to satisfy an index-drift gate. The generator updates only the
build checkout; this change adds no bot commit or source
synchronization.
Optional local `-Check` diagnostics and functional tests of the
generator remain available. Linting, link validation, and site builds
still run. The contribution guide and script help describe this
distinction; no tests inspect the actual workflow to enforce its
contents.
<details>
<summary>Technical details</summary>
| Changed surface | Standards checked | Framework or domain docs checked
| Result |
| --- | --- | --- | --- |
| `.github/workflows/Docs.yml` | GitHub Actions, YAML | Existing
documentation build pipeline | Aligned |
| `.github/scripts/Update-DocumentationIndex.ps1` (help only) |
PowerShell, Natural Language | Existing index generator interface |
Aligned |
| `.github/CONTRIBUTING.md` | Markdown, contribution guidance |
Documentation authoring and build flow | Aligned |
The index step runs normal generation with no `-Check` flag. The
index-generator implementation and all functional test suites are
unchanged. The local generation-then-build path succeeds with
repository-pinned Zensical 0.0.59; the changed contribution guidance is
lint-clean and the scoped diff has no whitespace errors. The exact-head
CI Build job also successfully executes `Generate documentation indexes`
followed by the site build. Temporary build environments and output are
cleaned without changing shared dependencies.
The Task records the audit, the user's selected boundary, and the
completed verification. Its implementation and review gates are
complete; the Task remains open for reviewed integration. This PR
remains draft; native maintenance has `merge_pr=false`, GitHub
auto-merge is off, and no live publication or merge is authorized. A
later main change requires a refreshed comparison and exact-head
validation.
</details>
Release guidance maps configured branches through `ReleaseType.Stable`,
`ReleaseType.Prerelease`, and `ReleaseType.ReleaseCandidate`. The stable
route defaults to the repository default branch; the other routes are
optional. Each branch has one effective routing assignment.
This changes documentation, not a released producer, settings loader,
caller input, branch configuration, or publication. Authors implementing
the canonical protocol use the keyed shape below. Existing consumers
keep their producer's declared interface until a compatible
implementation and its exact adoption instructions are released.
<!-- ANNOUNCEMENT STOP -->
## Changed: Release branches are keyed by the type they publish
The guidance replaces the `release-branches` list example with one
`ReleaseType` object whose only supported keys are `Stable`,
`Prerelease`, and `ReleaseCandidate`. Each key has at most one `Branch`.
Unknown keys fail. Branch-assignment validation resolves inherited
defaults first and then rejects any branch assigned to several routing
types, whether the assignments are explicit or inherited.
`Stable.Branch` is the only stable-production authority. An omitted
stable route inherits the repository default branch, and that assignment
still participates in duplicate validation: an explicit prerelease or
candidate assignment to the same branch is invalid. A configured
candidate route publishes its own `-rc.N` series without stable
publication or promotion to latest. `Prerelease` and `ReleaseCandidate`
are routing types that both publish prereleases, not a third
semantic-version mode or another owned release label. The VS Code
framework points to the same shared routing contract.
```yaml
# .github/release.settings.yml
DefaultBump: patch
ReleaseType:
Stable:
Branch: main
Prerelease:
Branch: dev
ReleaseCandidate:
Branch: rc
```
The existing effective-default contract remains: `DefaultBump` accepts
`patch`, `minor`, or `major`; the shared default is `patch`; repository
settings and explicitly supplied supported caller overrides refine it;
one owned bump label overrides the valid effective default. Invalid
supplied values and conflicting owned signals fail rather than fall
back. Skip alone validates without publication, and prerelease mode uses
the resolved explicit or default bump.
The canonical `.github/release.settings.yml` filename and its
naming/input boundaries are already on main. This remaining diff does
not rename another file or grant an older producer support for a
different path. `ConfigurationFile`, supported explicit custom paths,
the `.github/PSModule.yml` / `SettingsPath` exception, and the existing
`.github/vscode-extension.yml` template interface remain governed by
their owning producer or solution. No executable consumer migration is
performed here.
<details>
<summary>Technical details</summary>
**Current source:** `3f48c8b391d8af9952b9d4e851e8c56afd36b03b` on
`default-release-bump`, compared with actual main
`9453587dbf34e888d057848a867c48778c62b4e7`. The remaining delivery
contains four documentation pages, with 72 insertions and 51 deletions.
The branch includes that main source and has no unresolved conflicts.
Earlier `ce9ca513`, `105d53f`, `d9d35ab`, and `99fd558` records are
historical, not final-head review evidence.
| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| Release Management design | Documentation Model, Natural Language,
Markdown | Effective defaults, keyed routing, inherited validation,
stable authority | Aligned |
| Release Management spec | Specification/design separation, Natural
Language, Markdown | Closed routing-key contract, applicability, owned
decisions, required validation | Aligned |
| Release Management index | Documentation Model, generated navigation |
Current spec/design descriptions | Aligned |
| VS Code framework design | Documentation Model, Natural Language,
Markdown | Shared release resolver and configuration surface | Aligned |
| User-directed test-policy fix | Testing, PowerShell test discovery |
Functional validation versus prose-edit assertions | Fixed in this PR |
**Test-policy correction:** `d9d35ab` removes only the added
`ReleaseSettingsDocumentation.Tests.ps1` suite. Its five cases searched
documentation strings rather than executing a supported runtime
interface, contrary to the functional-testing policy now on main. All
functional suites, assertions, required checks, linters, link
validation, and build configuration are unchanged and match the accepted
base. No replacement phrase, heading, or source-shape guard is added.
**Concrete review corrections:** the complete review
[5743140913](#196 (review))
on `d9d35ab` identified inherited stable-assignment and
candidate-publication ambiguities. `99fd558` corrected both, with
fix-linked resolved replies for [inherited stable
validation](#196 (comment))
and [candidate publication
mode](#196 (comment)).
The complete review
[5743210606](#196 (review))
confirmed those fixes and requested the existing fixed-key/inheritance
guarantees in the normative spec. `3f48c8b` adds those guarantees and
has a [fix-linked resolved
reply](#196 (comment)).
These clarify the existing intended routing constraints; they do not
implement a reader or change the settings/input/runtime scope.
**Final-head validation:** all five required contexts succeed on
`3f48c8b391d8af9952b9d4e851e8c56afd36b03b`: [Lint, Build, Test, and
Links](https://github.com/MSXOrg/docs/actions/runs/41524011349), plus
[Cross-repository
links](https://github.com/MSXOrg/docs/actions/runs/41524011453). The run
identity was verified as a pull-request run for this exact source. Its
[Ubuntu Test
job](https://github.com/MSXOrg/docs/actions/runs/41524011349/job/125546962864)
passes all 64 functional tests in six suites using pinned Pester 6.0.1,
with none skipped. The site build and Markdown/static checks pass; the
PR-only Publish job is skipped as intended. Local functional suites,
Markdown lint, patch checks, relative links across 127 pages, and all
seven cross-repository links also pass. No older green run is counted
for this head.
**Final complete review disposition:** the explicitly requested round
[5743289293](#196 (review))
is COMMENTED on `3f48c8b391d8af9952b9d4e851e8c56afd36b03b`, with no new
inline comments, no requested changes, and no open issues. Its complete
summary was read, not reduced to the script's successful exit code: it
still says **Needs a closer look** and asks for human verification
because this normative cross-document routing proposal has no compatible
producer, executable resolver, or consumer migration delivered with it.
That is the intentionally retained documentation-only boundary, not
runtime validation or an approving review. The keyed/inherited-default
runtime behavior remains unexecuted coverage. A complete paginated
thread read-back confirms no unresolved threads. An independent reviewer
must assess and accept the contract; the last-push approval gate remains
unsatisfied and is not self-granted or bypassed.
**Preserved canonical composition and holds:** landed #209
supplied the complete PR-record, release-range-first,
sufficient-upgrade-history, and no-PR-template-file contracts. Landed
#233 supplied the single settings-name convention, supported
custom-path boundary, and PSModule/VS Code exceptions. This branch
retains those accepted sources while keeping its keyed-route proposal.
No unmerged producer or documentation delivery is copied into the
branch. Native prerequisite #166 is closed; #208
remains a separate overlapping delivery. If main advances again,
reconcile the surviving branch against the actual landed source and
repeat exact-head validation/review before readiness.
The older review
[5723060562](#196 (review))
also retained a generic human-assessment caution about default/skip
paths. Nineteen anonymous written-contract cases were checked on that
older source, not a runtime resolver; the decision table and ordering
survived the reconciliations. That caution is not an approval or a
governance waiver. The later Windows-path allegation in review
[5728271684](#196 (review))
was disproven by its exact-head Ubuntu run and received an
[evidence-linked resolved
reply](#196 (comment)).
The now-removed prose suite and older reviews do not establish
final-head runtime coverage.
**Task plan and convergence:** the original default/override, label,
framework, and conflict-reconciliation steps in #225 are
complete. The user-directed author-side readiness revision is complete:
prose-only assertions removed, functional validation retained,
current-source PR record refreshed, concrete review findings corrected,
and final-head CI/full automated review disposition recorded.
Independent contract assessment and last-push approval remain external
gates, not completed author work. The scoped convergence sweep covered
release/default/filename issues: only #225 is closed by this
delivery. #232 is the separate canonical filename Task;
#203 remains the broader consumer-upgrade procedure/gate
work. No additional closing links, producer migration, date-based
versioning, or historical/fleet cleanup are included.
This repository's target route builds and deploys an unversioned
documentation site. It does not publish a versioned immutable consumer
artifact, so no artifact-publication baseline is invented and no
`Release decisions` block or `release:*` label applies. The scoped
main-to-candidate comparison above is implementation/reviewer evidence,
not a fabricated release range.
Existing human/source/lineage/prerequisite holds are not waived. Agent
merge remains maintenance-only with `merge_pr=false`, and GitHub
auto-merge remains off. The PR target and existing draft state are
unchanged. This fix authorizes no merge, enqueue, publication, package,
live producer, label, pin, or governance mutation.
</details>
<details>
<summary>Related references</summary>
- Resolves [#225](#225)
- References [#209](#209)
- References [#233](#233)
- References [#208](#208)
- References
[#166](#166)
</details>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
…rds (#208)
Release guidance defines durable intent, phase-aware recovery, complete
source-bound consumer records, and settings-driven decisions. It
preserves the accepted keyed release routing,
`.github/release.settings.yml` convention, solution-specific path
exceptions, and release-range-first PR records while defining the
lifecycle contract.
This delivery changes documentation, not a producer runtime. It creates
no settings file, legacy filename fallback, versioned release, live
caller change, consumer installation, or governance change. Existing
immutable-version consumers need no action. Implementation owners verify
the invoked producer's actual interface and conformance before adopting
any documented setting or lifecycle control.
<!-- ANNOUNCEMENT STOP -->
## New: Owned moving-tag recovery keeps one explicit trust boundary
Use the procedure only for an intentionally moved MSX-owned major or
minor alias that the consumer's artifact-specific pinning standard
permits. Ownership alone does not authorize mutable references: the
owned Action/reusable-workflow major-tag exception does not permit minor
aliases. Exact version tags are immutable; their movement is an
integrity incident, not routine recovery. SHA- or exact-version-pinned
consumers require no action for this documentation delivery.
If a trusted, permitted alias is stale, verify the intended remote and
back up needed local-only tags outside `refs/tags/` before refreshing.
Renaming a tag within that namespace does not preserve it from pruning.
A verified `git bundle create owned-tags-backup.bundle --tags` followed
by `git bundle verify owned-tags-backup.bundle` can retain original tag
objects and reachable history; keep the backup private and outside
checked-in paths.
The whole-namespace refresh is `git fetch --tags --force --prune
--prune-tags origin`. Force replaces local tag values with that
explicitly selected remote's values, and tag pruning removes local tags
absent there. Accept that complete scope deliberately, review the
output, and do not normalize an altered exact version tag. Naming
`origin` prevents another upstream from choosing the source of this
operation.
For ongoing controlled movement, inspect `remote.origin.fetch` and add
`+refs/tags/*:refs/tags/*` once only when absent. Set clone-local
`remote.origin.prune` and `remote.origin.pruneTags` to true, not
clone-wide pruning defaults that can affect other remotes. Fetch
explicitly from origin. Compare the local alias's tag-object hash with
`git ls-remote --refs origin refs/tags/<alias>`, then resolve its exact
release and immutable source before use. A stale or unverifiable result
blocks use.
This is a general conditional operating procedure, not version-specific
migration history. No actual consumer tag, configuration, or history is
changed by this PR.
<details>
<summary>Technical details</summary>
| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| Accept Moved Release Tags guide | Guide structure, Natural Language,
Markdown | Owned-alias trust, tag pruning, immutable-source verification
| Aligned |
| GitHub Actions owned-tag link | Owning coding standard, Markdown |
Allowed major-tag exception and consumer recovery | Aligned |
| Capability indexes and navigation | Front matter, generated indexes |
Documentation Model | Aligned |
The earlier isolated anonymous Git experiment reproduced implicit
upstream selection and pruning of a renamed local-only tag. Complete
40-character identities confirmed that an independent bundle retains the
pruned ref, explicit origin restores the intended alias, and
origin-scoped pruning does not remove origin-owned tags when another
remote is fetched. The verification repositories contained only empty
commits and test tags; no repository tags or releases were changed. The
accepted-main reconciliation leaves that operating procedure intact.
</details>
## Changed: Durable lifecycle and native targets require verified
conformance
The numbered specification retains fixed approved source and notes,
permanent reservations after a successful build or external visibility,
one retained artifact through verification and publication, destination
progress, phase-aware retries, retirement and withdrawal,
stable/candidate authority, current discovery, optional aliases, and
independent post-completion announcements. Version computation uses
permanent reservations and the reviewed aggregate minimum bump. Consumer
record coverage separately starts from the actual latest successful
artifact publication for each product, target, and channel.
Authors resolve publication coverage before writing a release-bound
record: verify the actual artifact and publication receipt, its
immutable source provenance, and the exact candidate; compare those
source trees and retain the scoped PR-base comparison separately.
Include earlier merged, skipped, direct, and otherwise unshipped changes
in the applicable consumer range. Successful Gallery publication
advances module note coverage even if later GitHub completion fails.
Completing that older GitHub record preserves its original snapshot and
does not make its already-published module changes new again. These
authoring baselines do not change aggregate approval, version
reservations, or completed-state discovery.
Consumers compose every applicable source-bound record after their
actual consumed baseline through the target in release order. Notes
retain prerequisites, ordering, required intermediate operations,
verification, or an explicit no-action result with its compatibility
basis. Reading a record does not itself require installing that version.
PRs and diffs provide optional depth; resource docs describe supported
target-state usage, not another migration history. Missing publication
provenance or required instructions blocks the affected publication
rather than becoming a no-action result.
Implementation owners verify the invoked immutable producer and actual
controls before relying on them. A requirement or configuration example
does not prove that an older runtime implements recovery, manual release
creation, candidate routing, alias reconciliation, or announcement
journaling. Exact producer adoption actions belong in its own PR/release
record. Existing operators retain their released interface; an
incomplete release is not repaired by rebuilding under an exposed
version or re-resolving changed metadata. This documentation delivers no
broad lifecycle engine, history backfill, downstream propagation, or
Discord sender.
A duplicate or phase-aware retry reuses its original logical intent,
approved source, frozen version, and retained artifact. A separately
approved corrective release has a distinct immutable approved request
identity, even when reviewed source is unchanged; it receives a new
intent/version and preserves its relationship to the earlier attempt. Do
not reuse a retry key to suppress that newly approved request, supersede
an exposed intent, or reuse a reserved version. An affected product
integration template requires its repository, compatible immutable
commit, producer-source compatibility evidence, and delivered work or a
justified no-change result. This docs-only delivery changes no producer
or integration template, so concrete runtime/template adoption values do
not apply here.
Native publishing identities remain explicit. A PowerShell prerelease
uses numeric `ModuleVersion` plus `PrivateData.PSData.Prerelease`:
canonical `2.5.0-alpha` is core `2.5.0` and label `alpha`, not
prerelease text in `ModuleVersion`. Validate the selected client's
suffix syntax and reject or explicitly map unsupported forms without
collisions or lost ordering.
Native bounded ranges, where supported, can express major/minor update
policies without aliases. A field without a native range resolver can
retain immutable patch updates when permitted bounded selection exists
outside that field. A SHA-pinned Action or reusable workflow does not
need or acquire permission to retain a minor alias for that policy.
Git/container reference fields do not evaluate range-like strings.
Require a permitted matching alias only when no other permitted resolver
supplies the bound; if none can express it, fail without widening to
latest or another boundary. Retain the exact version, full SHA, or
digest required by the artifact's pinning standard and trust policy.
The owning VS Code framework declares stable/prerelease native mappings
together before enabling Marketplace publication. Numeric versions and a
native channel do not imply direct conversion from every canonical
SemVer. An odd-minor convention requires reserved stable space and
proven series/counter allocation. Unsupported mappings or collisions
fail before publication; an enabled required destination is not silently
skipped. This PR specifies the conformance boundary, not a new allocator
or Marketplace publisher.
<details>
<summary>Technical details</summary>
| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| Release Management spec/design and index | Specification/design
separation, Natural Language, Markdown | Durable intent, aggregate
minima, distinct publication/version baselines, complete records,
conformance | Aligned |
| Publishing-target contract | Owning target requirements, Markdown |
Two-field module mapping, native coordinates, immutable bounded
selection | Aligned |
| Parent/capability indexes and navigation | Generated-index conventions
| Documentation Model | Aligned |
The earlier native PowerShell manifest verification established numeric
`ModuleVersion` and separate prerelease data; prerelease text does not
parse as `System.Version`. Official Git, PowerShell, and Marketplace
documentation grounded the mapping and trust corrections. No runtime
publication or invented allocator is claimed.
Written consumer-policy cases cover omitted policy retaining the
strongest immutable reference, native minor bounds without aliases,
permitted SHA-pinned patch selection without changing major/minor or
retaining a minor alias, the owned-major exception not authorizing minor
aliases, unsupported resolution failing without widening, immutable
external latest selection, opaque range strings, and patch-only pre-1.0
selection staying inside its chosen minor. These are written conformance
cases, not evidence of a delivered resolver runtime.
**Current immutable candidate:**
`a37884419c6c5ec4da56222be27238ee192b4cd1`. **Scoped implementation
base:** accepted main `bdb581f68fddd84bc129394a94388671d1d14356`,
containing delivered #209, #235, #233,
and #196. The complete base-to-head comparison contains eight
existing lifecycle, target, guide, and navigation files. Current
canonical format, naming, testing, solution-specific exceptions,
repository policy, CI configuration, and VS Code framework guidance
match accepted main without an additional PR delta. This repository's
Docs route is documentation validation and Pages deployment, not a
versioned Release Management artifact route; no release-publication
baseline or `Release decisions` block is fabricated for this PR.
Local validation of the composed candidate passes all **64
functional/tooling Pester tests in six suites**, normal index
regeneration, relative links across 128 pages, seven cross-repository
links, exact-file Markdown lint across eight relevant pages, patch
checks, and a clean build with manifest-pinned Zensical **0.0.59**. The
unavailable pinned build version was restored only in an isolated
temporary environment, which was removed afterward. No dependency
manifest was changed. The accepted testing policy is preserved; no
prose-drift tests were added or restored. The inherited-routing scenario
documents the requirement but does not claim an implemented resolver
test.
**New-head required CI was running at handoff:**
[Lint](https://github.com/MSXOrg/docs/actions/runs/41675815774/job/126055996866),
[Links](https://github.com/MSXOrg/docs/actions/runs/41675815774/job/126055996479),
[Test](https://github.com/MSXOrg/docs/actions/runs/41675815774/job/126055996962),
[Build](https://github.com/MSXOrg/docs/actions/runs/41675815774/job/126055996918),
and [Cross-repository
links](https://github.com/MSXOrg/docs/actions/runs/41675815839/job/126055998868).
All five checks identify `a37884419c6c5ec4da56222be27238ee192b4cd1`.
Earlier green checks are not represented as a result for this new head;
current status is shown by the PR checks.
The previous full automated review
[5728246486](#208 (review))
approved `f68927e94a31520c4db482aa8f2359cc999b80aa` with no active
concerns. It is an earlier checkpoint, not a review of this candidate.
This tick began with all review threads resolved and no
changes-requested review, but with approval blocked. No reviewer was
requested or approval manufactured during conflict maintenance. The
exact resolution review preserves lifecycle authority, reservations,
immutable artifact recovery, source-bound records, and consumer policy
while integrating the accepted keyed-routing rules.
The closing Task's original implementation-plan evidence remains in the
prior delivery history. This maintenance resolves the accepted-main
composition gate and leaves new-head required CI and GitHub's remaining
approval/protection requirements as acceptance gates. Producer
implementation, consumer execution, date strategies, historical
correction, and live governance remain outside this Task. No PR merge,
merge enqueue, retarget, release, or artifact promotion was performed;
automatic landing remains off.
</details>
<details>
<summary>Related references</summary>
- Resolves [#227](#227)
- References
[#166](#166)
- References [#209](#209)
</details>
## Changed: Keyed routing and settings retain their accepted boundaries
The lifecycle retains `ReleaseType.Stable`, `ReleaseType.Prerelease`,
and `ReleaseType.ReleaseCandidate`, each with at most one branch. The
stable route inherits the default branch when the routing object or
stable key is omitted. Validate the effective mapping after inheritance:
unknown keys and duplicate branch assignments fail, including a
candidate or prerelease route assigned to the inherited stable branch.
Prerelease and release-candidate routes publish only their assigned
prerelease series, not stable releases or stable discovery/aliases.
Configured branches retain their push-driven series, and open PRs retain
`release:prerelease` using one explicit owned bump label or the valid
effective `DefaultBump`. Candidate versions retain `rc` and increasing
counters; promotion to stable uses the stable version resolver without
carrying either prerelease counter over. An unreviewed direct push to
the stable line still validates without publishing.
The release solution's optional path remains
`.github/release.settings.yml` under the accepted Naming standard. The
convention does not implement a reader, rename a public input, require a
shared directory, or restrict otherwise supported explicit custom paths.
Verify the immutable producer revision's declared settings input and
default before adoption. `ConfigurationFile`, where exposed, remains
that producer's settings-path input.
PSModule retains `.github/PSModule.yml` through `SettingsPath`,
including module release settings; module repositories do not need a
separate release-solution settings file. The VS Code template retains
`.github/vscode-extension.yml` and its settings keys. Both owning
exceptions are preserved from accepted main. This documentation does not
authorize a reader, template, or live-caller migration, and creates no
legacy fallback.
`DefaultBump` still accepts `patch`, `minor`, or `major`, with shared
`patch` as the documented default. Repository settings and explicitly
supplied supported caller overrides resolve before one owned bump-label
override. Omitted caller inputs preserve repository policy; invalid
supplied settings and conflicting signals fail even when another input
supplies a valid level. A compatible effective default needs no per-PR
bump label. Skip and out-of-scope work validate without publication.
The owned set remains exactly `release:patch`, `release:minor`,
`release:major`, `release:prerelease`, and `release:skip`. Prerelease
uses the resolved bump; skip combines with no other signal. Candidate
and announcement behavior uses supported settings rather than extra
labels. A route without versioned release behavior carries neither
release metadata nor any release label.
Authors retain the finalized PR record, release-range-first procedure,
complete source-bound notes, and scoped supporting evidence already
delivered on main. The no-PR-template-file policy remains in Repository
Standard and its owning governance guidance, not PR Format. Product
integration template evidence and genuine repository-specific
contribution instructions remain separate and intact.
Existing runtime consumers do not rename live files or install software
because this guidance changed. Producer support and any required
adoption actions must be verified and delivered by the relevant
implementation owner.
<details>
<summary>Technical details</summary>
| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| Lifecycle routing requirements and design | Specification/design
separation, Natural Language, Markdown | Accepted fixed routing keys,
inherited defaults, branch collisions, prerelease sources and
stable-only authority | Aligned |
| Lifecycle settings and configuration sections | Natural Language,
Markdown, Naming | Optional release-solution file, verified reader/input
boundary, unchanged defaults and typed overrides | Aligned |
| Accepted-base composition | Current PR Format, Testing, Repository
Standard | Release-range-first records, no-template ownership, preserved
PSModule and VS Code exceptions | Aligned |
Conflict maintenance merges only accepted main
`bdb581f68fddd84bc129394a94388671d1d14356` into the existing branch. It
resolves conflicts in release spec/design/index without importing an
unmerged delivery or restoring the older `release-branches` schema. The
lifecycle's artifact, aggregate-approval, recovery, discovery,
announcement, version-reservation, settings-precedence, and
optional-file contracts remain intact. Accepted keyed-routing
requirements are expressed within the existing numbered specification
and design; the inherited-default collision scenario makes the
effective-mapping rule explicit. Shared canonical pages and the VS Code
framework match accepted main exactly.
The #233 and #196 sequential-composition gates are
resolved against their delivered merges, not their superseded
development candidates. No other branch, historical record, live label,
consumer pin, governance setting, or producer runtime was changed.
New-head CI and remaining GitHub acceptance gates are still required;
Agent merge maintenance does not authorize automatic landing.
</details>
<details>
<summary>Related references</summary>
- References [#196](#196)
- References [#233](#233)
- References [#235](#235)
</details>
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Epic and PBI authors describe the consumer's need, motivation,
expectation, and observable behavior instead of prescribing an
implementation. Task and Bug authors retain technical decisions and
test-first delivery plans. Completion verifies current design and
documentation, updating affected content and recording evidence when it
already matches the delivered result.
This changes guidance, not repository-inventory functionality, existing
issue bodies, community files, or release automation. No new BDD tool,
plugin reinstall, or configuration change is required.
<!-- ANNOUNCEMENT STOP -->
## Changed: Consumer expectations survive planning and completion
When authoring or deliberately refining an Epic or PBI, identify the
consumer and motivation, then state observable acceptance examples using
Given / When / Then or an equally clear scenario. Keep architecture
choices, component inventories, file/function lists, and implementation
checklists in the current design and Task/Bug delivery leaves. The issue
skill and agent instruction route still reach one canonical
issue-planning rule; they do not acquire a duplicate BDD process.
Completion verifies relevant current specifications, designs,
documentation, examples, links, and instruction routes against delivered
behavior. Update the owning artifacts where the change requires it. When
an artifact already describes the result correctly, link it and record
why no update is needed rather than editing it to satisfy a checkbox.
Missing required documentation remains unfinished work. Native children
still own aggregate progress, native dependencies still gate genuine
prerequisites, and a delivery PR cannot close a PBI or Epic.
| Issue altitude | Representative expectation or plan |
| --- | --- |
| Epic | Given maintainers assess fleet health across organizations,
every repository in the agreed scope is accounted for and coverage gaps
are explicit before they act. |
| PBI | Given a caller can access 137 repositories, an unlimited
inventory returns all 137 exactly once; unreadable coverage is not
presented as a complete success. |
| Task/Bug | Keep local consumer context, repository paths,
implementation/root-cause decisions, and executable
verification-before-implementation plans in the delivery leaf. |
<details>
<summary>Technical details</summary>
The [immutable delivery
head](1c8f98c)
contains three ordinary commits on a main-based topic branch. The
complete diff changes 19 documentation pages and no plugin, workflow
configuration, community file, legal/ownership file, or release record.
The existing single issue-index skill pointer is unchanged, so the
plugin version is not bumped.
**Implementation-plan progress:** all five #228 steps are
complete: current-guidance comparison, representative scenarios and leaf
counterexamples, canonical altitude/completion ownership, affected
routes, and existing documentation checks plus complete-diff/summary
review. The Task remains open until its reviewed PR is merged.
**Validation and review:** 64 existing Pester tests and 10 focused
session checks pass. The focused checks detected the
aggregate-authoring/completion contradictions before the edits and the
missing README/agent routes before their correction. Generated indexes
are current; documentation links resolve across 127 scanned files; all
seven cross-repository links resolve; Markdown lint passes for all 19
changed pages; the actual Zensical site builds with no reported issues.
Rendered HTML contains the new anchors and three Gherkin scenarios. All
five live required checks—Build, Links, Test, Cross-repository links,
and Lint—are successful at the immutable head. The explicitly requested
Copilot round approved that exact head with zero new inline comments and
no open review issues; complete diff, summary, and supporting evidence
have been self-reviewed. No auto-merge is enabled.
**Standards and framework alignment:**
| Changed surface | Standards checked | Framework/domain documentation |
Result |
| --- | --- | --- | --- |
| Issues/Process/Planning | Consumer altitude, test-first delivery,
native decomposition | Documentation Model and Spec-Driven Development |
Fixed in this PR |
| Issues/Process/Format and Lifecycle | Body ownership, audit trail,
type-specific readiness and closure | Issue Planning and Definition of
Ready and Done | Fixed in this PR |
| Issues/Process/index and Issues/index | Generated navigation,
thin-pointer discovery | Documentation Model and existing issue skill |
Fixed in this PR |
| Epic and PBI types | Consumer context/scenarios, aggregate acceptance
| Issue Planning and native hierarchy/relationships | Fixed in this PR |
| Task and Bug types | Consumer context, technical decisions,
test-first/regression plans | Issue Planning and completion evidence |
Aligned; technical plans preserved |
| Definition of Ready and Done | Type-specific gates and
combined-outcome evidence | Documentation Model | Fixed in this PR |
| Documentation Model | Artifact ownership and evergreen evidence |
Spec-Driven Development | Fixed in this PR |
| Coding-Standards/Documentation and README-Driven Context | Current
README evidence without forced edits | Completion evidence and existing
repository README | Fixed in this PR |
| Workflow and Define | Correct issue altitude and delivery-leaf handoff
| Issue Planning and native relationships | Fixed in this PR |
| Implement and Review | Executable leaf plans and documentation
verification | Completion evidence and Contribution Workflow | Fixed in
this PR |
| Spec-Driven Development Templates | Durable artifact templates, not
issue plans | Issue Planning and completion evidence | Fixed in this PR
|
| Agent Interaction | Intent/implementation separation without removing
leaf plans | Canonical issue planning and existing agentic-development
spec/design | Fixed in this PR |
| All changed Markdown | Markdown, Natural Language, front matter,
index/link/site checks | Documentation Model | Aligned |
The existing repository README and thin client/skill routes remain
correct for this change and are verified rather than churned.
Spec-Driven Development already owns implementation-free durable
requirements and technical designs; no second specification or BDD skill
is added.
**Composition and ownership:** the release owner handed off the shared
guidance pages. Read-only three-way compositions against complete
#209 at `27ffab8ad89cf41147dc25ba2f6bd300b01b938f`,
#196 at `e2e4b7d428badfce35e6511afd6aaedb77280613`, and
#208 at `9f92fa1ad8f8f4d56e79f52a40acee09a3bdbad4` all
succeed. Each composition preserves exactly the same 19 changed paths
and added/removed guidance lines; the complete PR Format scaffold
remains byte-identical to its release candidate. Composed trees are
`435eb4220addb34c0c308318054cf48e09085507`,
`40456e7f0d04707125ecc28e7fa6a0f045515858`, and
`dc6888519fe271b0e36fce6e22b5561f4d6a17fb`, respectively. No release
changes are copied into this PR.
The agreed human landing order is #209, #196,
#208, this PR, then #229. Remaining branches need
reconciliation and repeated CI/full review when main advances. Complete
release-record/scaffold/conditional-decision and Task/Bug plan-progress
contracts are preserved. No merge, retarget, native-dependency edit, or
auto-merge action is performed.
**Issue convergence:** searches scoped to Epic/PBI, issue planning, and
community/contribution identify #96, #154, and
#229 as related but not fully delivered. #96 asks
for broader removal of technical issue plans, contrary to this clarified
Epic/PBI-only scope; #154 adds a separate
premise-verification procedure; community inheritance stays in
#229. Only #228 is closed by this PR; historical
issues are not rewritten.
**External intake follow-up:** the Project will give separate narrow
delivery surfaces to the inherited [MSXOrg/.github Feature
form](https://github.com/MSXOrg/.github/blob/main/.github/ISSUE_TEMPLATE/10-feature.yml)
and [PSModule/.github Feature
form](https://github.com/PSModule/.github/blob/main/.github/ISSUE_TEMPLATE/10-feature.yml).
Their descriptions should ask for consumer need, motivation, and
observable scenarios and link canonical issue planning and native-type
routing instead of soliciting implementation framing. These source-owned
intake forms are not copied or edited here; Bug forms, Task/Bug
technical plans, and unrelated YAML/CI policy are preserved.
#229 will use a separate coordinator-created issue session;
this tracked workspace and PR remain scoped to #228.
The main documentation route builds and publishes the Zensical site; its
two workflows do not invoke Release Management. Release-decision blocks
and all `release:*` labels are therefore absent. The title/description
follows the complete handed-off #209 audience-first scaffold
without changing that PR.
</details>
<details>
<summary>Related references</summary>
- Resolves#228
- Followed by #229
- References #96
- References #154
- References #209
- References #196
- References #208
</details>
Every initiative must provide `.github/CONTRIBUTING.md` in its public
`.github` community repository, even if the file is blank. Ordinary
repositories inherit that shared guidance and keep a local contribution
guide only for genuine repository-specific instructions or a documented
exception.
This corrects the standards, not repository files across the fleet.
Initiative maintainers must ensure the central source file exists; blank
content is allowed. Consumers do not need generic local copies. This
repository's build, Pester, index-generation, and link-check
instructions remain intact.
<!-- ANNOUNCEMENT STOP -->
## Fixed: Required initiative sources do not require local consumer
copies
Organization Standard now requires a contribution source in every
initiative community repository. Repository Standard, the governance
source matrix, README/readiness guidance, and agent
specification/design/router examples consistently distinguish that
source requirement from a conditional consumer-local guide. Missing
source files are corrected in the initiative community repository, not
by manufacturing consumer placeholders. When a source guide is blank,
the shared Contribution Workflow still defines the process and agent
routes also link there.
Source validation checks file presence, not a nonempty body. Local
guides describe repository-specific steps and link back to shared
guidance; such steps are not automatically policy exceptions. Other
community defaults and the landed prohibition on PR-template files
retain their separate rules.
No files are deleted, copied, or distributed in other repositories.
Legal terms, CODEOWNERS, actual agent/client routes, live governance
settings, labels, permissions, non-community configuration, and released
framework behavior are unchanged. The central Feature intake-form
follow-ups remain separate.
<details>
<summary>Technical details</summary>
**Delivered head:** `cdf10a47479406c80fbca742ed13b954cde2a095` on
`community-guidance-inheritance`. The branch contains actual main at
`8c9d9353eb154d6072b3ed1d825a78d58a4665d3`. Its complete diff is eleven
modified documentation pages, 127 added lines and 62 removed lines. The
tracked worktree is clean.
The main refresh is separate merge commit
`daa9dec0379eb1a04b6d65c518ff7a2dd62ba12d`. The required-even-blank
source rule is the small commit
`cdf10a47479406c80fbca742ed13b954cde2a095`. No history rewrite or PR
retargeting was used.
**User-directed clarification:** "All initiatives should supply one,
even if it's blank. The requirement is that initiatives have this." The
central rule is therefore MUST/Required, not SHOULD/Recommended or
optional. The ordinary-repository local-guide rule remains conditional.
**Source verification:** live GitHub API reads confirm public
`MSXOrg/.github` and `PSModule/.github` each contain
`.github/CONTRIBUTING.md`, at source blobs
`9ff70648eb1cc0a455f8362b5d1b81ba538b7f38` and
`de229578ad918895b63b14331fb6eed7e6cc5711`. The previously verified
Distributor example established a consumer without a local contribution
guide whose community profile resolves to the organization source. Blank
content is explicitly permitted by the clarified contract; no live
blank-file inheritance experiment is claimed.
**Actual landed composition:** all agreed prerequisites are merged: #209
at `aa9b5cecc69f4cbe6aa04a5dd70ff9cdadeeac3d`, #196 at
`bdb581f68fddd84bc129394a94388671d1d14356`, #208 at
`adf98af340639f46f0a7aecf34720d6ef26f515b`, and #230 at
`8c9d9353eb154d6072b3ed1d825a78d58a4665d3`. The real current main was
integrated cleanly. The earlier prospective-only correspondence and
unlanded-prerequisite blockers are superseded.
Current main's actual contribution guide, PR Format, and Task/Bug
documents are unchanged by this PR. Repository-specific commands, the
no-PR-template-file policy, actual-record/release-range ownership, and
#228's current-documentation/no-unnecessary-churn evidence remain
intact. No obsolete scaffold requirement is restored.
**Validation:** all 64 current native Pester tests pass, with zero
failed or skipped. The native index generator, relative-link checker
(128 documentation files), cross-repository checker (seven links in 132
Markdown files), all eleven changed pages' Markdown lint, and the actual
Zensical build pass. All five required GitHub checks pass at
`cdf10a47479406c80fbca742ed13b954cde2a095`. The explicitly requested
automated review round is clean on that head (`COMMENTED`, zero new
inline comments), and no review thread remains unresolved. The complete
scoped diff and source contracts were self-reviewed. No source-string or
prose-snapshot tests were added; current validation uses functional
suites and real documentation tooling.
**Standards and framework alignment:**
| Changed surface | Standards checked | Framework/domain docs checked |
Result |
| --- | --- | --- | --- |
| Repository and Organization Standards (2 pages) | Documentation Model,
Markdown, Natural Language | Required initiative source, conditional
consumer-local rule, blank versus missing boundary | Fixed in this PR |
| Repository Governance spec, design, and types (3 pages) |
Specification/design ownership | Required source-file presence and
effective consumer guidance | Fixed in this PR |
| README-Driven Context and Ready/Done (2 pages) | README ownership,
readiness, no-unnecessary-churn evidence | Conditional contribution rule
and landed #230 evidence gate | Fixed in this PR |
| Agentic Development spec, design, and router template (3 pages) | Thin
pointers, real destinations, canonical process | Required initiative
contribution source; blank-guide process link; missing-source reporting
| Fixed in this PR |
| Maintain Workflow Guidance (1 page) | Link-not-inline workflow
maintenance | Agentic Development pointer model | Fixed in this PR |
**Task progress and convergence:** all Task #229 implementation steps
are complete, including the user-directed mandatory source clarification
and final validation. The native Task remains open until merge;
technical planning and native dependency edges are unchanged. The scoped
convergence sweep covered `community` and `contribution`: #228 is
separately delivered by #230, and #123/#150 are not delivered by this
diff. Only Task #229 is closed here. Its existing artifact #1 now holds
current source and landed-composition evidence.
**Remaining readiness:** no agreed prerequisite remains unlanded.
Exact-head checks and automated review are complete; the automated round
is not human approval. Human review remains. No merge or auto-merge is
performed or enabled. The Docs route publishes the site without invoking
Release Management, so no Release decisions block or release labels are
added.
</details>
<details>
<summary>Related references</summary>
- Resolves#229
- References #228 and #230
- References the landed neighboring contracts in #209,
#196, and #208
- [GitHub default community-file
behavior](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file)
</details>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
documentationImprovements or additions to documentation
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Marius Storhaug (MariusStorhaug)
added
the
documentation
PR Format describes the actual title and complete body: audience-first results, release-range-first analysis, complete adoption/compatibility evidence, one announcement boundary and conditional release decisions. Repository file policy is owned separately by Repository/Organization/Governance guidance, not by the PR Format page.
Authors use canonical guidance for the resulting record. Repository standards exclude GitHub PR-template files from ordinary and central-default sources, while retaining other community defaults, genuine repository-specific contribution instructions and supported product-integration contracts. This delivery changes guidance and checks in MSXOrg/docs; separate owners remove their actual source/consumer files. No publisher, live caller, artifact, tag, governance setting or release history is changed here.
Changed: PR Format focuses on the complete authored record
Use one short reader-facing title and an audience-first summary, then ordered non-empty Breaking, Removed, New, Changed and Fixed results. Explain what changed, why, affected supported uses, compatibility and complete adoption actions or a justified no-action result in each result's prose. Keep prerequisites, ordering, verification and mandatory intermediate operations in the record itself, with supporting evidence and references scoped to the result they verify.
The complete in-document example is named Complete description example. Its anchor is now
#complete-description-example, replacing#copy-the-complete-template. The single announcement boundary and full body remain unchanged in purpose; announcements do not truncate the published note. Maintained links adopt the new anchor. Existing skills still route to the same canonical PR Format page and its release-coverage analysis; no additional skill, file distributor or plugin installation is required for this correction.PR Format contains no repository PR-template-file discussion: no file locations, copying/inheritance, local exceptions, presence/absence policy or deletion history. Those rules belong to the repository standards below. Product integration-template compatibility evidence remains distinct and required where a delivered result affects a supported integration.
Technical details
The tests separate record quality from repository file policy. Record tests verify the complete example and ordered classifiers, marker count, publication/candidate identity fields, five scoped release-evidence prompts, release-first analysis, and five affected-product integration prompts. They also reject GitHub PR-template-file discussion on this page without rejecting legitimate product integration contracts. File-policy tests inspect the owning repository/organization/governance pages, not PR Format. Five ownership/naming cases failed before the refinement and pass after it.
The old example link is a documentation-anchor transition, not a runtime migration. Required old-to-new consumer actions still belong in the relevant release record; product docs retain supported target-state usage rather than a migration hierarchy or changelog.
Changed: Repository standards require canonical adherence without PR-template files
Repository Standard owns the no-file rule for every MSX repository type and the special
MSXOrg/.githubandPSModule/.githubsources. GitHub PR-template files, multiple-template directories, generated copies and local exceptions are not part of this contract. Organization Standard and Repository Governance reference that one owner; their former mandatory default-file rows and local PR-template exception are removed.Authors and validators verify the actual title, complete body, source coverage, compatibility/adoption evidence and normal review gates. An inherited scaffold, file-presence check or similarity to a central copy does not prove adherence. The complete canonical record example remains in the docs. Other code-of-conduct/security/support/contribution/issue-intake defaults and genuine repository-specific contribution instructions are unaffected; this is not an organization-wide community-file cleanup.
Separate source and consumer owners remove existing PR-template files and revise their source docs/check expectations. This PR introduces no distributor, physically edits none of their workspaces and claims no pending deletion is merged. A missing file never substitutes for Markdown/source/head/containment validation or complete PR record quality.
Technical details
The corrected regression checks were run against exported frozen guidance with no commits: five actual policy cases failed while eleven preservation/path cases passed. Current source checks recognize uppercase/lowercase PR file names, alternate extensions and multiple-template directories, while leaving issue forms and canonical PR Format docs unaffected. MSXOrg/docs contains no tracked GitHub PR-template file.
Independent full, non-truncated default-source reads confirmed these still-present files at the measured immutable sources:
0c67251812ea306543f3a14ab473ae357cfb76ac.github/pull_request_template.mdf424237c98b5b020f80e8c9563dbc37256fc1ec0.github/pull_request_template.md93d2656563a719d99416b9e13a05e65f6f815498.github/pull_request_template.md1a621b14286331569f4d1ffd4643999c2a2a6ca8.github/pull_request_template.mdThese are measured source/consumer counterexamples with separate removal owners, not evidence that the new no-file state has already landed. The Project's complete 71-repository inventory additionally identified the stale PSModule/Template-PSModule#42 candidate as separately owned reconciliation. PSModule/Process-PSModule#525 tracks the bounded producer anatomy/audit requirement reconciliation; central/default validators have separate owners. Their publisher/Build/runtime behavior remains outside this documentation revision.
The MSXOrg/docs#231 owner confirmed its clean frozen branch and no pending overlapping edits. The exact community composition boundary is the PR-template rows/paragraphs only: preserve its conditional local-contribution rule and all other inherited defaults while adopting the new no-file policy links. No #196/#208/#230/#231 tracked branch was edited here.
Related references
Changed: Release-bound authoring starts from actual artifact publication
Before drafting the title, results, adoption actions or compatibility decision, resolve the actual latest successful artifact publication for the same product, target and channel and verify its immutable source. Pin that artifact/source and the exact candidate PR source, verify intended lineage and compare those source trees. The complete delivered range includes earlier merged, skipped or unshipped changes; the ordinary PR-base diff remains separate implementation/reviewer evidence, not the note boundary.
A GitHub Latest hint, moving tag, assumed highest version or overall failed run is not publication-baseline proof. Module publication to Gallery counts even when later GitHub completion fails: the next module record starts from its already-published source. Completing that older GitHub record does not make module changes new again. Multiple artifact targets/channels have independently pinned consumer baselines and applicability.
Resolve missing/unverifiable evidence, ambiguous scope and diverged lineage explicitly. A verified initial publication has reviewed whole-candidate coverage and initial adoption instructions, not a fabricated predecessor or no-action/patch assumption. Re-read publication and candidate identities before readiness/snapshot capture and refresh comparison, actions and compatibility when either changes. This is the preserved authoring procedure, not a new publisher/version resolver or Build/artifact-promotion design.
Technical details
The anonymous Git experiment remains exact source-tree evidence: published A-to-candidate C includes earlier unshipped B and current C, while scoped B-to-C includes only the current PR. Simulated Gallery-success/GitHub-failure evidence for B keeps module coverage at B-to-C even after older GitHub completion. Changed candidate/publication pairs change coverage, and unrelated lineage is rejected. Receipts were simulated inputs, not a live publish or historical repair.
Final committed/pushed head:
bc03a5992615f65d1d5346dc48e7506e80b8b6ca. This ordinary commit refines the previousbe8c340...authoring correspondence without amendment or history discard. Canonical anchors are release-first analysis, complete description example, repository file policy, and defaults source guidance.Local validation passes: all 80 Pester tests in seven suites, 127 documentation pages plus contribution-guide lint, indexes/relative anchors, seven cross-repository links, actual pinned Zensical 0.0.59 build and rendered new-anchor checks, zero PowerShell analyzer diagnostics, existing plugin-manifest validation, and patch checks. The parsed linter configuration remains unchanged. All five required hosted checks succeed on this exact head: Lint, Build, Test, Links, and Cross-repository links. Both completed
pull_requestruns identify this source head.Complete current-head review: 5725019918 is APPROVED on
bc03a5992615f65d1d5346dc48e7506e80b8b6ca. The full summary records no active/open or suppressed concerns; all review threads are resolved and thread pagination is complete. The prior be8c340 approval was not used as approval of this correction. This is the automated author-side pass, not independent human approval or permission to merge.All five existing Task #226 plan items are fulfilled: verified state/cases, bounded canonical authoring, directly coupled policy/evidence/link reconciliation, native checks/current-head full review, and final acceptance/immutable handoff. The scoped sweep covered PR authoring, source/default validation, release/consumer and community guidance; only Task #226 is the closing delivery leaf. The existing native prerequisite MSXOrg/docs#166 is completed. Its five-context required-check rule and the existing approval/thread constraints remain unchanged; no live merge attempt, injected failure or bypass was used.
Changed: Effective decisions and release-history ownership are preserved
DefaultBumpstill accepts patch/minor/major with documented shared patch, repository settings, explicitly supplied supported caller overrides and one explicit owned bump override in that order. Omitted inputs inherit valid policy; invalid supplied settings and conflicting owned signals fail even when another source supplies a level. An effective default removes the need for a per-PR bump label, not the need for compatibility evidence. The exact owned set remainsrelease:patch,release:minor,release:major,release:prereleaseandrelease:skip.Verify actual native/shared producer controls or a supported adapter before using signals. Prerelease uses the resolved bump; skip combines with no other owned signal. Unmanaged routes omit all release metadata/labels; this repository deploys Pages without a versioned release artifact, so this PR retains neither a Release decisions block nor a release label. No undecided caller-override interface, allocator, publisher or live input is approved or implemented here.
Complete PR/release records remain the sufficient version-specific upgrade history; resource docs describe supported target-state usage. Mandatory intermediate operations and superseded actions remain explicit. Campaign/native associations and completion-aware issue links retain their established ownership. No migration-guide/changelog duplication, date strategy, native dependency mutation, publication, historical backfill, label/permission/rules edit, merge or auto-merge is performed.
Technical details
The existing PRs stay separate on main. Eventual landing is one at a time with every remaining overlapping branch reconciled against advanced main and CI/full review repeated. Other owners must consume the refreshed immutable correspondence; their prior frozen example/file expectations are not claimed current. This PR does not edit their tracked candidates or waive their independent prerequisites.
Related references