Repository navigation
Community guidance is local only when repository-specific - #231
Open
Marius Storhaug (MariusStorhaug) wants to merge 4 commits into
Open
Marius Storhaug (MariusStorhaug) wants to merge 4 commits into
Marius Storhaug (MariusStorhaug) wants to merge 4 commits into
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
The design permits inherited contribution guidance, but the specification still requires the repository’s local CONTRIBUTING file, leaving inherited-only repositories unable to satisfy its success criteria.
1 open issue
What changed in this PR
This documentation-only PR makes local community files conditional on repository-specific needs or documented exceptions. It aligns repository standards, governance checks, and agent guidance with inherited organization defaults, without changing runtime behavior or removing existing contribution instructions.
Changes:
- Distinguishes required local files from discoverable shared contribution guidance.
- Updates governance and readiness guidance to verify effective guidance rather than require local copies.
- Aligns README guidance and agent-router examples with conditional contribution guides.
| File | Description |
|---|---|
src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md |
Allows pointers to local or inherited contribution guidance. |
src/docs/Ways-of-Working/Repository-Standard.md |
Defines the conditional local contribution-guide requirement. |
src/docs/Ways-of-Working/Readme-Driven-Context.md |
Aligns contribution links with the conditional rule. |
src/docs/Ways-of-Working/Organization-Standard.md |
Clarifies shared defaults, local content, and policy exceptions. |
src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md |
Adds verification of effective community guidance. |
src/docs/Capabilities/repository-governance/spec.md |
Separates required local files from discoverable contribution guidance. |
src/docs/Capabilities/repository-governance/design.md |
Updates reconciliation to check source defaults and effective guidance. |
src/docs/Capabilities/repository-governance/design-types.md |
Applies the conditional rule to Unmanaged repositories. |
src/docs/Capabilities/agentic-development/design.md |
Updates router guidance to support inherited contribution sources. |
src/docs/Capabilities/agentic-development/AGENTS.template.md |
Explains how to replace optional local entries with shared links. |
Review effort: Balanced
There was a problem hiding this comment.
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
October 31, 2026 22:40
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 1, 2026
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. <!-- ANNOUNCEMENT STOP --> ## 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. <details> <summary>Technical details</summary> | 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 | Aligned | | Record-format regression block | PowerShell/Pester, shared analyzer, testing baseline | 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. </details> ## 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. <details> <summary>Technical details</summary> | 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](PSModule/Template-PSModule#42) candidate as separately owned reconciliation. [PSModule/Process-PSModule#525](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 [#231](#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. </details> <details> <summary>Related references</summary> - Resolves [#226](#226) - References [#231](#231) - References [PSModule/Process-PSModule#525](PSModule/Process-PSModule#525) </details> ## 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. <details> <summary>Technical details</summary> | 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. **Final committed/pushed head:** `bc03a5992615f65d1d5346dc48e7506e80b8b6ca`. This ordinary commit refines the previous `be8c340...` authoring correspondence without amendment or history discard. Canonical anchors are [release-first analysis](https://github.com/MSXOrg/docs/blob/bc03a5992615f65d1d5346dc48e7506e80b8b6ca/src/docs/Ways-of-Working/PR-Format.md#resolve-release-coverage-first), [complete description example](https://github.com/MSXOrg/docs/blob/bc03a5992615f65d1d5346dc48e7506e80b8b6ca/src/docs/Ways-of-Working/PR-Format.md#complete-description-example), [repository file policy](https://github.com/MSXOrg/docs/blob/bc03a5992615f65d1d5346dc48e7506e80b8b6ca/src/docs/Ways-of-Working/Repository-Standard.md#no-pr-template-files), and [defaults source guidance](https://github.com/MSXOrg/docs/blob/bc03a5992615f65d1d5346dc48e7506e80b8b6ca/src/docs/Capabilities/repository-governance/design.md#organization-defaults-repository). 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](https://github.com/MSXOrg/docs/actions/runs/41243884162/job/124663205698), [Build](https://github.com/MSXOrg/docs/actions/runs/41243884162/job/124663205920), [Test](https://github.com/MSXOrg/docs/actions/runs/41243884162/job/124663205851), [Links](https://github.com/MSXOrg/docs/actions/runs/41243884162/job/124663205928), and [Cross-repository links](https://github.com/MSXOrg/docs/actions/runs/41243883939/job/124663204724). Both completed `pull_request` runs identify this source head. **Complete current-head review:** [5725019918](#209 (review)) 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 [#166](#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. </details> ## 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. <details> <summary>Technical details</summary> | 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. </details> <details> <summary>Related references</summary> - References [#196](#196) - References [#208](#208) - References [#230](#230) - References [#205](#205) - References [#166](#166) </details> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Ordinary repositories inherit organization community guidance without creating local files solely to repeat shared policy. Local contribution files remain only for genuine repository-specific instructions or a documented exception; organization
.githubrepositories remain the source homes for the other community defaults they supply.This is a standards correction, not a file cleanup or fleet rollout. This repository's genuine build, Pester, index, and link-check instructions are preserved. No other repository, released framework behavior, legal terms, ownership, labels, rulesets, permissions, or non-community configuration is changed.
Fixed: Contribution guidance can be inherited without local copies
The repository baseline and required-file matrix require discoverable contribution guidance rather than an unconditional local contribution file. Use the organization's default when supplied, or link to the shared contribution workflow when no default is provided. Keep a local guide when genuinely needed, describing repository-specific steps and linking to shared policy. Such steps are not automatically policy exceptions.
Organization and reconciliation guidance distinguish source-file validation from effective consumer guidance. README/readiness guidance and the agent specification, design, and router examples agree on that boundary, including that inherited defaults do not appear in clones. Actual PR-template-file policy is separately owned by the refreshed upstream Repository Standard; contribution inheritance must not restore its obsolete template requirements.
No repository file is deleted or copied by this PR. No consumer migration or change to released framework behavior is introduced. Actual PR-template removals, the central Feature intake-form follow-ups, and Task #228's nineteen-page issue-guidance delivery remain with their separate owners.
Technical details
Tracked draft head:
3ca4de0c508058950ed9d4592c47e24100874eee, oncommunity-guidance-inheritance, three ordinary commits, eleven modified documentation pages, 108 added and 55 removed lines against36da9154aa55d2052345fb2f28b812b29daf8bc9. The worktree is clean. Main has not advanced and this branch has not imported unlanded release changes.Superseding source: #209 is frozen at
bc03a5992615f65d1d5346dc48e7506e80b8b6ca, with its exact-head automated approval and all required checks verified. Repository Standard: No PR-template files owns file policy for every repository type and central default source, without exceptions. PR Format owns actual-record format and release-range analysis only; its complete description example replaces the old template anchor. The former template/scaffold correspondence is superseded and must not be used to land this draft unchanged.Preservation examples:
MSXOrg/Distributorat3beed03f64eeafdad1c5986a14845a2b7811f929has no local contribution guide and its GitHub community profile resolves toMSXOrg/.github. Historical source snapshots inMSXOrg/.githubandPSModule/.githubestablish the other shared community/default families, not current compliance with the subsequent no-PR-template policy. This repository's genuine local contribution instructions remain present. The refreshed source guide's PR-format links changed, so preservation uses its Making a change, Authoring conventions, and Building and previewing locally sections, verified byte-identical to original main, rather than the old whole-file blob.Read-only prospective composition: refreshed #209 and frozen #230 (
1c8f98cabe64b12aaa5fa9fb5f51b9d03f5de9de) compose at treec459e5ff243b354b8c7bdb0f24cdb11c19cb4a96. Applying this draft's frozen head yields five conflicts across three pages. The bounded resolved result is35c111d07698923a98602637ff57b16ca1e370e3:This is not an automatic clean merge or a reconciled branch. The result changes only this Task's eleven paths relative to the composed source, with 105 added and 53 removed lines. All eight non-overlap per-file deltas remain identical. The complete refreshed PR-default/no-file section, PR Format, source contribution guide, Task/Bug documents, and #228's current-documentation/no-unnecessary-churn evidence remain unchanged from their sources. The source guide's composed blob is
22f34aa90a1803bd55008f7775d366943fdd3074.Validation: The source-only snapshot fails eleven expected conditional-guidance checks and passes eight; applying #229 makes all nineteen pass while preserving all eighty upstream tests. In one pinned Pester run, 99 tests pass with no failures or skips. Prospective indexes, relative links (127 documentation files), cross-repository links (seven links in 131 files), all eleven changed pages' Markdown lint, and the actual Zensical build pass. Real built HTML exposes both new authority/example anchors. The complete bounded diff was self-reviewed. This prospective result does not simulate #196/#208's future reconciliation or supply review of a future committed head.
The unchanged tracked head's original validation remains distinct: 64 existing plus 19 original focused checks passed, all five required GitHub checks pass, and its final automated round is clean on
3ca4de0c508058950ed9d4592c47e24100874eee(COMMENTED, zero new inline comments), with the earlier specification thread resolved. That is not human approval.Standards and framework alignment:
Task progress and convergence: The original four Task #229 implementation steps are checked; its native type, acceptance criteria, technical decisions, and dependency edges are unchanged. Scoped open-issue searches were
communityandcontribution: #228 remains separately delivered by #230; #123 and #150 are not satisfied by this change. No additional issue converges. Only Task #229 is closed by this PR after merge. Artifact #1 on Task #229 now preserves the refreshed source/composition evidence instead of the obsolete scaffold result.Remaining blockers: #209, #196, #208, and #230 remain open. #196/#208 still have older correspondence and are not claimed byte-identical to refreshed #209. Keep the agreed human landing order #209, #196, #208, #230, then this PR. Reconcile each remaining branch against actual advanced main after each landing; for #229 preserve the no-file/record contract and conditional contribution rule through the known five ranges. Repeat CI, local validation, and full review after every landing/reconciliation/head change, then obtain the required human review. The current draft has not yet completed that future reconciliation.
No merge, auto-merge, retargeting, or actual template cleanup is performed or authorized. The Docs route publishes the site without invoking Release Management, so no Release decisions block or release labels are added.
Related references