Repository navigation
Community guidance is local only when repository-specific - #231
Merged
Marius Storhaug (MariusStorhaug) merged 6 commits intoNov 3, 2026
Merged
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>
There was a problem hiding this comment.
🔵 Needs a closer look
Four unmerged prerequisite PRs and unresolved cross-PR conflicts require human review of the final reconciled head to verify that conditional contribution inheritance and the upstream no-PR-template-file contract are preserved.
No open issues 🎉
Review effort: Balanced
Marius Storhaug (MariusStorhaug)
deleted the
community-guidance-inheritance
branch
November 3, 2026 17:20
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 3, 2026
Consumers gain one staged procedure for upgrading from the upstream source they actually use to a fixed target, with every applicable release accounted for. Use producer-owned discovery to establish the baseline, compose the required actions, preserve local intent, and verify the result; a version bump or the newest release note alone is not evidence of adoption. The shared `msx` plugin adds an optional discovery shortcut. Connected guidance explains qualification, automated-update gates, safe propagation, and completion ownership. This change delivers documentation and a thin skill pointer, not a consumer migration or an updater, publisher, or evidence-validator implementation. <!-- ANNOUNCEMENT STOP --> ## New: Consumers can compose a complete upgrade The [Consumer Upgrades procedure](https://github.com/MSXOrg/docs/blob/main/src/docs/Ways-of-Working/Consumer-Upgrades.md) gives humans and agents one method for dependencies, frameworks, Actions, reusable workflows, and other versioned products. It connects immutable provenance, complete release history, an applicability-aware action ledger, the compatible target template, existing validation, and an explicit completion outcome. Each consumer establishes its own baseline even when a fleet shares one target. Follow these stages when adopting an upstream change: 1. Inventory the consumed references and establish the exact upstream version and authoritative immutable identity that actually resolved or ran. Distinguish that identity from the consumer's own package version. Use full commits for Git-distributed sources and authoritative digests or equivalent immutable identities for artifact-only products; do not invent Git mappings. A floating alias's present destination does not prove its past destination. Unknown baseline provenance blocks the upgrade. 2. Resolve and record one target: latest stable by default under the producer's version ordering and stable lineage, or an explicit stable/prerelease target. Exhaust paginated discovery and inspect every applicable release in `(baseline, target]`, in semantic and lineage order rather than API order or timestamps. Include no-action records; exclude unrelated backports and prerelease streams. Older targets use immutable target-era source, documentation, release snapshots, and templates, not today's aliases or final PR body. 3. Compose the required actions and record each disposition: completed with evidence, not applicable with a reason, no action required, or blocked with an owner. Reconcile renames, reversals, and superseded steps without deleting their evidence. Preserve mandatory intermediate conversions, installations, or runs; reading the complete history does not require installing every intermediate version. Equivalent authoritative external evidence is accepted without requiring MSX headings or tables. 4. Compare the consumer with the target's recorded compatible immutable template, distinguishing required integration surfaces, optional scaffolding, and intentional local differences. Never copy a template wholesale. Preserve consumer-owned code, tests, configuration intent, secrets, documentation, and assets. Record secret names and provisioning obligations, never values. If no template applies, state why; missing compatibility evidence is not a no-template result. 5. Run the existing relevant consumer tests, builds, linting, and integration checks against the exact target identity. Reconcile every ledger entry with the final diff and observed results, including no-action ranges. Keep introduced and pre-existing failures distinct; missing or failed required validation blocks readiness. 6. Carry the proven range, identities, complete release links, reconciled actions, template comparison, validation outcomes, and remaining blockers into the upgrade PR. Keep the consumer's release decision separate from its upstream target. Record review, merge, publication, and completion as distinct milestones. An identical target is already current; a lower target is superseded, not permission to downgrade. Retain the proven baseline, target, comparison, and reason in the delivery issue. Close only an unneeded open leaf with no remaining local work as not planned, without an empty PR or a shipped-upgrade claim. Preserve existing closed records, and reconcile an existing PR or unmet local acceptance criteria with its owner before changing its disposition. <details> <summary>Technical details</summary> The implementation adds the common playbook and routes existing discovery and adoption guidance to it. Missing provenance, release/action evidence, applicable template compatibility, or required prerequisites remains a stop condition. Changed inputs invalidate affected downstream evidence; the target is not silently changed. | Evidence | Source or scope | | --- | --- | | Exact candidate | MSXOrg/docs at `a8cecfddaf1a80efd6d5758e159844572d2b1e66`, branch `consumer-upgrades`. | | Current target observed during metadata revision | `main` at `5f64e8253b7bc2838c8c2bfb90e8ccd0a9d0e08d`. | | Scoped implementation comparison | Merge base `180f78a0b75b59149edca07280eca055ea303d82` through the candidate; the actual PR delta contains 19 files. This is PR evidence, not a fabricated consumer-publication baseline. | | Actual publication route | The candidate and current target use the native `Docs` workflow to build and deploy Pages. No versioned immutable artifact publication or Release Management decision path is configured in these workflows. Pages publication alone does not establish a managed release. | | Integration template | Not applicable to this documentation and thin-pointer delivery. Authoring structures are standards, not a product integration template; no pilot consumer or producer/template repository is modified. | No managed release decision or predicted release coordinate is asserted. The existing release-label mismatch remains a format-finalization blocker because this revision is limited to title and description. The first five implementation-plan steps in #203 are recorded complete. Walkthrough reconciliation, alignment, and scoped convergence evidence is retained here; the final normal review/handoff item remains incomplete. This metadata revision does not complete it or claim that the candidate contains later changes from `main`. The earlier eighteen documentation walkthroughs are retained in the issue's [range cases](#203 (comment)), [review edge cases](#203 (comment)), [conditional flows](#203 (comment)), [evidence isolation](#203 (comment)), and [entry gates](#203 (comment)). They exercise the written procedure, not a real consumer, pilot, live delegation, or security evaluation. | Cases | Required outcome | | --- | --- | | No-action patch and skipped releases | Retain every applicable record, reconcile the range, and run relevant existing validation. | | Breaking transition and renamed/reversed actions | Preserve local values and mandatory intermediate operations; classification does not hide incompatible behavior, including before 1.0. | | Prerelease and non-latest targets | Use source-specific snapshots and target-era evidence without merging unrelated streams or substituting final-PR prose. | | Floating baselines and artifact-only sources | Require past-execution provenance; accept authoritative immutable artifact identities without invented Git mappings. | | Missing evidence/template and no-template applicability | Block unknown required facts; distinguish justified non-applicability from missing evidence. | | Equal/lower targets and changed inputs | Record no-upgrade outcomes without empty PRs or downgrades; invalidate stale evidence without silently retargeting. | | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Consumer Upgrades playbook | Natural Language, Markdown, orchestration-playbook structure, evidence trust boundaries | PR Format; Release Management; Dependencies; Contribution Workflow | Aligned | | Navigation and discovery indexes | Existing front matter, navigation, and generated-index conventions | Documentation Model | Aligned | Source-bound validation remains available in the [earlier verification record](#205 (comment)). For the exact candidate above, the [Docs run](https://github.com/MSXOrg/docs/actions/runs/41505041468) and [cross-repository-links run](https://github.com/MSXOrg/docs/actions/runs/41505041504) completed successfully; Pages publication was skipped for the PR event. Earlier local checks and review records describe their tested revisions, not a newly added documentation-content assertion or index-drift enforcement policy. The recorded convergence search covered consumer, template, and downstream work. #143 needs separate standard-to-artifact inventory/enforcement, #136 owns Gallery updater delivery, and #187 needs router/published-URL enforcement. No additional issue was fully delivered by this diff; only #203 is a closing reference. </details> <details> <summary>Related references</summary> - Resolves #203 - References #202 - References #204 - References #143 - References #136 - References #187 </details> ## New: A shared skill exposes the procedure without owning producer discovery `msx-ways-of-working-consumer-upgrades` adds a thin pointer to the common procedure. Once the candidate is available through the marketplace, plugin consumers can refresh `msx@msxorg` to discover the intent; humans and agents can also follow the procedure directly without installing anything. Existing skill names remain supported. Producer or initiative guidance still owns authoritative repositories and registries, version/source mapping, release lineages, target-era guidance, and compatible immutable template discovery. The shared skill contains neither initiative-specific authority nor version-specific migration instructions. Its version does not prove template compatibility or that any producer implements the documented controls. <details> <summary>Technical details</summary> The eight-line skill points to one canonical document. Plugin and marketplace-entry metadata both change from `0.1.2` to `0.2.0` in the scoped comparison. These are repository manifest values, not evidence that a package or GitHub Release has been published, and not a selected consumer upstream target. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Plugin README, skill, and manifests | Natural Language, Markdown, existing names/layout/version conventions | Plugin Marketplaces; Plugin Distribution; existing marketplace validation | Aligned | | Plugin Marketplaces and Plugin Distribution | Natural Language, Markdown, thin-pointer ownership | Agentic Development; Agent Plugins and Agent Skills | Aligned | Existing marketplace validation covers source resolution, synchronized versions, unique plugin names, and valid skill metadata. No new runtime or plugin installation is required by this PR. </details> ## Changed: Update and fleet guidance qualifies work before implementation Dependency and fleet guidance now routes each actual consumer through the complete procedure instead of treating a reference change or the newest note as adoption. For a fleet upgrade, establish the pre-upgrade baseline and fixed target before creating or adopting a branch/PR. Do not use an existing PR's proposed references as proof of what the consumer consumed, discard unmet local acceptance work, or copy another consumer's edits. When implementing automated dependency-update handling, create proposals as drafts or immediately convert them to draft if the native updater cannot do so. Keep them draft until the normal readiness gate holds. Before enabling automatic readiness, approval, or merge, bind adoption verification to an existing required PR check, or a separate required check when none owns it. Missing, stale, pending, or failed evidence must hold those actions even if builds pass; keep automation outside those actions until enforcement exists. The draft flag preserves the review signal but is not that independent enforcement mechanism. A proven no-upgrade outcome needs no reference-change campaign or empty PR. Campaign issues retain their prefix, PRs retain reader-facing titles and verified native Development links, and target-specific issue-linking/closure rules still apply. Advancing a controlled compatible owned-major alias alone does not require a consumer reference-change campaign; deliberate pinned upgrades and breaking-major adoption still need per-consumer evidence. <details> <summary>Technical details</summary> This PR specifies adoption and automation gates; it does not implement a required evidence validator, updater, receiving workflow, ruleset change, or consumer campaign. The documented green-build/incomplete-evidence case must remain blocked in a conforming implementation. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Dependency Updates spec/design | Natural Language, Markdown, existing spec/design structure | Consumer Upgrades; Release Management; Merge Automation; review readiness | Aligned | | Fleet Orchestration | Natural Language, Markdown, fleet and delivery-leaf conventions | Consumer Upgrades; controlled owned-major policy; native issue linking; completion ownership | Aligned | The fleet view distinguishes integration, an evidenced not-needed result, and delivery completion. A merged reference bump or automatically closed issue alone does not prove required publication, deployment, or template work. </details> ## Changed: Propagation guidance preserves stable targets and isolated evidence Downstream-propagation guidance qualifies the actual consumer before Build and uses one durable delivery identity for a producer version and dependent. Implementations must validate stable release kind at both release-triggered and manual-backfill entry points, before fan-out or issue creation: skip prerelease events and reject prerelease backfill requests with a clear error. Keep the event or explicit backfill target fixed; delayed notifications never authorize downgrades. Standalone consumer prerelease upgrades do not widen this stable-only capability. The notifier creates or reuses the Task or Bug before engaging an agent. If authoritative provenance already proves no upgrade is needed, record that outcome without delegation. Otherwise use the producer's configured mode. Issue-first uses issue pickup only after delegation is selected. Task-first starts a read-only qualification task with `create_pull_request: false`, then creates or reuses one correlated PR-delivery task with `create_pull_request: true` only for a verified needed upgrade. That task uses the same issue and qualified plan and produces the closing PR, which remains draft until readiness. For retries, serialize discovery and handoff for that producer version and dependent; verify the issue's immutable target and retain execution correlation there. Issue existence, request acceptance, and task completion alone are not successful handoff. Reuse active execution and any matching PR or verified no-upgrade outcome. Retain an `idle` task for designated-owner re-engagement; a `waiting_for_user` task needs an authorized answer in that same task. Neither permits replacement. Failed, timed-out, canceled, missing, or uncertain outcomes require reconciliation before a safe retry; preserve partial consumer work rather than creating duplicate issues, tasks, or PRs. Carry the complete source-bound release record and publication envelope losslessly as untrusted evidence, separate from application-owned task instructions. A runtime data/attachment boundary or collision-safe quotation must prevent embedded directives or delimiters from changing scope, permissions, secret handling, or validation/review gates. Extract proposed actions and validate them against the consumer's governing instructions. A summary cannot replace the complete record or the consumer's full crossed range; unsafe isolation blocks delegation rather than truncating content or trusting it as instructions. For implementations, keep `PROPAGATION_TOKEN` as the explicitly passed secret name, scoped only to necessary dependents, with `Issues: write`, `Pull requests: read`, and mode-specific permissions. Task-first also needs the Agent Tasks API's accepted user credential with `Agent tasks: write`; Issue-first uses its configured pickup mechanism instead of unconditional task creation. Keep least-privilege workflow permissions and do not use `secrets: inherit`. The notification credential does not itself push or open PRs; execution does that in its own session. This documentation change provisions no credential, permission, setting, or task. <details> <summary>Technical details</summary> The spec/design and capability indexes now describe both a needed-upgrade PR and an evidenced no-upgrade outcome. The issue is durable identity; live execution state and actual handoff are read from their platform, not maintained in a second status store. Missing provenance, required actions, template evidence, or validation remains blocking; genuinely independent work alone can move to a follow-up. The recorded conditional-flow, adversarial-record, backfill, and paused-task walkthroughs distinguish the notifier, qualification, PR delivery, retries, and final consumer completion. They are documentation reasoning, not proof of an implemented Agent Tasks integration or runtime security control. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Downstream Release Propagation spec/design/index and capability discovery | Natural Language, Markdown, evidence trust boundaries | Consumer Upgrades; qualification/idempotency; configured delegation; Continuous Practices | Aligned | </details> ## Changed: Completion guidance keeps evidence and publication separate Review readiness now explicitly requires complete consumer evidence; an upgrade also reconciles its full baseline-to-target range. Applicable producer/template work needs demonstrated compatibility with an immutable reviewed identity. Verified candidate or prerelease evidence can support review without inventing final coordinates, creating a circular pre-merge prerequisite, or waiving a native blocker. Before review, name the issue and responsible owner for the whole required outcome. If source integration and necessary template or other delivery work span separate leaves, use a PBI with required native children and keep it open until the combined criteria are verified; each PR closes only its own Task or Bug and references the PBI without closing it. For a single leaf awaiting its own publication/deployment without an aggregate owner, the owner reopens it if PR closure precedes that evidence, then closes it only after verification. Reconcile template compatibility with the actual published producer identity and deliver necessary linked template changes before claiming completion; rerun affected validation when that identity differs. The existing Implement alignment pass carries these obligations in its normal PR sections and evidence rows, without a second checklist. Keep resource documentation current and retain release-specific transitions, migration history, and delivery plans in their GitHub records. Decision records and research retain their distinct purposes. A normative contract is not proof of implementation or CI enforcement; consumers adopting older targets still need immutable historical source/docs and release records. <details> <summary>Technical details</summary> | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Definition of Ready and Done; Implement | Natural Language, Markdown, readiness and issue hierarchy | PR Format; Release Management; Consumer Upgrades; Task/PBI completion | Aligned | | Documentation Model | Natural Language, Markdown, artifact tiers | Spec-Driven Development; source-bound release evidence | Aligned | #203, assigned to MariusStorhaug, remains the completion owner for this single-leaf documentation delivery and its required Pages publication. If PR closure precedes publication evidence, the owner follows the reopen path. No applicable integration template or additional delivery leaf calls for a PBI here. The old governance exception is resolved: #166 is closed, and current effective `main` rules require Lint, Links, Test, Build, and Cross-repository links. Passing candidate runs do not establish publication, complete the Task's remaining handoff item, or authorize merging. The PR is currently non-draft; this title/body revision leaves that state, labels, source, and native maintenance settings unchanged. The existing release-label mismatch on the Pages-only route is still a format blocker, not a supported release decision. Current canonical PR Format and Release Management, including the accepted defaults, keyed routing, lifecycle, and producer-conformance boundaries, govern finalization instead of the Task's historical kickoff policy. The scoped candidate diff changes no release resolver, PR Format, issue-type or community-file policy, tests, validation script, or workflow. This metadata revision does not restore documentation-content assertions or index-drift enforcement, change producer behavior, or claim conformance from documentation or plugin version numbers. Out of scope remain PSModule pilot selection/execution, historical release or PR backfill, version-specific skills, updater/publisher/validator implementations, automatic template synchronization, and unrelated governance changes. </details> <details> <summary>Related references</summary> - References #166 - References #196 - References #208 - References #230 - References #231 </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
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.
Every initiative must provide
.github/CONTRIBUTING.mdin its public.githubcommunity 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.
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.
Technical details
Delivered head:
cdf10a47479406c80fbca742ed13b954cde2a095oncommunity-guidance-inheritance. The branch contains actual main at8c9d9353eb154d6072b3ed1d825a78d58a4665d3. 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 commitcdf10a47479406c80fbca742ed13b954cde2a095. 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/.githubandPSModule/.githubeach contain.github/CONTRIBUTING.md, at source blobs9ff70648eb1cc0a455f8362b5d1b81ba538b7f38andde229578ad918895b63b14331fb6eed7e6cc5711. 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 atbdb581f68fddd84bc129394a94388671d1d14356, #208 atadf98af340639f46f0a7aecf34720d6ef26f515b, and #230 at8c9d9353eb154d6072b3ed1d825a78d58a4665d3. 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:
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
communityandcontribution: #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.
Related references