Skip to content

Epic and PBI guidance describes consumer expectations - #230

Merged
Marius Storhaug (MariusStorhaug) merged 4 commits into
mainfrom
express-epic-and-pbi-issues-as-consumer
Nov 3, 2026
Merged

Marius Storhaug (MariusStorhaug) merged 4 commits into
mainfrom
express-epic-and-pbi-issues-as-consumer

Conversation

@MariusStorhaug

@MariusStorhaug Marius Storhaug (MariusStorhaug) commented Oct 31, 2026 •

Copy link
Copy Markdown
Member

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.

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.
Technical details

The immutable delivery head 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 and PSModule/.github Feature form. 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.

Related references

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟢 Approved

No active review issues block the documentation-only update separating consumer expectations from implementation planning.

No open issues 🎉

What changed in this PR

This documentation-only PR addresses #228 by separating Epic/PBI consumer expectations from Task/Bug implementation planning across the shared authoring and delivery guidance.

Changes:

  • Defines consumer-focused acceptance scenarios for Epics and PBIs while preserving technical decisions and test-first plans in Tasks and Bugs.
  • Adds shared completion evidence requirements for current design, documentation, examples, links, and instructions, allowing justified no-change evidence.
  • Aligns workflow, template, README, and agent guidance while preserving native hierarchy and aggregate closure rules.
File Description
src/​docs/​Ways-of-Working/​Workflow.md Aligns planning, delivery, review, and closure with consumer expectations.
src/​docs/​Ways-of-Working/​Workflow-Stages/​Review.md Adds the shared documentation evidence check.
src/​docs/​Ways-of-Working/​Workflow-Stages/​Implement.md Reinforces test-first delivery and documentation verification.
src/​docs/​Ways-of-Working/​Workflow-Stages/​Define.md Separates aggregate expectations from delivery-leaf technical plans.
src/​docs/​Ways-of-Working/​Spec-Driven-Development-Templates.md Distinguishes durable artifact templates from issue plans.
src/​docs/​Ways-of-Working/​Readme-Driven-Context.md Requires README verification and updates only where needed.
src/​docs/​Ways-of-Working/​Issues/​Types/​Task.md Adds motivation and documentation verification while retaining technical plans.
src/​docs/​Ways-of-Working/​Issues/​Types/​PBI.md Adds consumer scenarios and combined-outcome completion evidence.
src/​docs/​Ways-of-Working/​Issues/​Types/​Epic.md Reframes strategic acceptance around observable consumer outcomes.
src/​docs/​Ways-of-Working/​Issues/​Types/​Bug.md Adds consumer context and documentation checks while preserving regression plans.
src/​docs/​Ways-of-Working/​Issues/​Process/​Planning.md Establishes canonical consumer-expectation and technical-planning boundaries.
src/​docs/​Ways-of-Working/​Issues/​Process/​Lifecycle.md Aligns planning, review, and shipping with the updated gates.
src/​docs/​Ways-of-Working/​Issues/​Process/​index.md Updates the planning page’s navigation description.
src/​docs/​Ways-of-Working/​Issues/​Process/​Format.md Routes issue bodies to type-appropriate content and evidence.
src/​docs/​Ways-of-Working/​Issues/​index.md Adds a direct entry point to canonical planning guidance.
src/​docs/​Ways-of-Working/​Documentation-Model.md Clarifies artifact ownership and completion evidence placement.
src/​docs/​Ways-of-Working/​Definition-of-Ready-and-Done.md Defines shared documentation and design evidence requirements.
src/​docs/​Coding-Standards/​Documentation.md Aligns README requirements with evidence-based verification.
src/​docs/​Capabilities/​agentic-development/​agent-interaction.md Clarifies that intent separation preserves Task/Bug delivery plans.

Review effort: Balanced

@MariusStorhaug
Marius Storhaug (MariusStorhaug) marked this pull request as ready for review October 31, 2026 15:55
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>
@MariusStorhaug
Marius Storhaug (MariusStorhaug) deleted the express-epic-and-pbi-issues-as-consumer branch November 3, 2026 16:48
Marius Storhaug (MariusStorhaug) added a commit that referenced this pull request Nov 3, 2026
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>
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>
Marius Storhaug (MariusStorhaug) added a commit to PSModule/.github that referenced this pull request Nov 11, 2026
<!-- Lead with one concise paragraph describing the user-facing outcome.
-->

Feature contributors give the current situation first, then the user
benefit, the requested change, and an example of the expected result.
The inherited PSModule feature form uses direct instructions and
present-tense maintainer responsibilities. Its identity, declared
labels, single required response, and feedback routing remain unchanged.
No consumer-local edit or technical plan is necessary.

<!-- ANNOUNCEMENT STOP -->

<!-- Add user-facing sections for breaking, new, changed, or fixed
behavior when needed. -->

## Changed: Feature requests establish the current situation before the
desired change

The response remains **Current situation and desired change**. The
introduction removes the courtesy opening. The prompts give direct
instructions in the same order:

1. Tell us how things work today. Include what is not easy or is
missing.
2. Tell us who the change helps and why.
3. Tell us what you want to add or change.
4. Give a real example. Include the situation, your action, and the
result you expect.

Optional starters use ordinary language. Maintainers review and refine
feedback, then select the issue type. The form does not require literal
Gherkin syntax, architecture decisions, or a technical implementation
plan. Tasks and Bugs retain their technical delivery plans.

After merge, PSModule repositories that use inherited issue templates
receive the organization-owned form without local configuration or code
changes. Repositories with local overrides are unchanged. The chooser
metadata, title prefix, `feature`/`triage` declarations, `description`
field ID, single required textarea, field label, and blank-issue
fallback remain unchanged.

---
<details>
<summary>Technical details</summary>

<!-- Record the implementation approach, issue-plan progress, standards
alignment, and convergence sweep. -->

### Scope and source identity

Candidate: `7eedb8a44c00bfa0f38d541ea88a7d7d791eaa19` on
`psmodule-feature-intake`. The complete PR changes only
`.github\ISSUE_TEMPLATE\10-feature.yml`: 23 additions and 5 deletions
against `f424237c98b5b020f80e8c9563dbc37256fc1ec0`.

The prose revision is one ordinary commit after
`e7a14f7eb35eb77bff8b6ba7730c8870a660185d`. It changes only the
introduction, textarea description, and optional placeholder text. The
form's Git blob changes from `8fb4a887c15961430e78980ac695a8af83029fbc`
to `29b9a60ed7e77745fdcf7f0e22b66026c864036a`; the earlier
identical-blob claim applies only to the completed test-removal
correction, not this prose revision. Other campaign sessions own
README/AGENTS/profile and bug/patch/general forms; this branch does not
edit those paths.

### Prose acceptance evidence

| Concern | Before this prose revision | After | Preserved result |
| --- | --- | --- | --- |
| Opening | Courtesy thanks before the first instruction | Starts with
how things work today | Current situation first |
| User benefit and requested change | Questions and conditional wording
| Imperative Tell/Give prompts | User benefit precedes the requested
change |
| Expected result | A real-situation question | An example with
situation, action, and expected result | Observable scenario without
mandatory formal syntax |
| Maintainer responsibility | Will review and decide how to route |
Review and refine feedback, then select the issue type | Same
maintainers and native routing; present tense |
| Optional starters | Would help / would like | Change helps / I want |
Same ordinary-language hints, not prefilled answers |

A one-time read-only YAML comparison allowed changes only to
`body[0].attributes.value`, `body[1].attributes.description`, and
`body[1].attributes.placeholder`. The remaining keys and values matched
the preceding source. This includes form identity, routing declarations,
field ID, required flag, field label, and absence of an assigned native
type. The reference URLs and untouched blank-issue configuration retain
their roles. This comparison is maintenance evidence, not a retained
snapshot test or a test of GitHub behavior.

### Fixed writing sources and limits

The campaign uses MSXOrg/docs at
`1b0d4893c8fefabe604d04393068a8ff6f848082`: [Documentation
Model](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Documentation-Model.md),
[Natural
Language](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md),
[Writing
Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md),
Markdown, Documentation, and the applicable issue/Task/PR formats. All
required pages were available.

The official [STE overview](https://www.asd-ste100.org/about_STE.html),
[FAQ](https://www.asd-ste100.org/STE_faq.html), and [Issue 9
DOI](https://doi.org/10.5281/zenodo.23666006) were available. The PDF
was read in memory, and its MD5 matched the official record. The review
consulted active-voice rule 3.6, procedural rules 5.1-5.3, and relevant
dictionary entries for prompt wording, including Tell/Give and
alternatives to Explain/Describe. Reference content was not republished.

This is a scoped manual prose review, not a full word-by-word STE
certification. Domain terms retain their MSX meaning. A word count,
static lint result, or automated approval does not prove complete STE
conformance.

### Static checks and testing boundary

| Existing command or inspection | Result and limit |
| --- | --- |
| `yamllint --strict .github\ISSUE_TEMPLATE\10-feature.yml` | Passed,
exit 0. Existing static YAML lint only. |
| `git --no-pager diff f424237 HEAD
--check` | Passed. Whitespace inspection only. |
| Read-only comparison against
`e7a14f7eb35eb77bff8b6ba7730c8870a660185d` | Only permitted display
values differ; non-prose keys and values are unchanged. No comparison
script is committed. |
| `gh api repos/PSModule/.github/pulls/89/files --paginate` | Exactly
one changed file: the feature form, 23 additions/5 deletions. |

The 198-line Pester snapshot suite remains removed. Its historical 25
assertions did not test GitHub rendering, submission, or routing; the
earlier functional-coverage claim stays withdrawn. No replacement
content assertions, schema snapshots, runtime simulation, test
dependency, validator, workflow, hook, or test issue is added. No live
GitHub form test was executed or claimed. Static/manual inspection and
review do not establish that unexecuted coverage. Pre-commit alignment
remains deferred, and the separate testing-policy cleanup remains
independent.

### Plan, review, and lifecycle

[#88](#88)
records the new user-directed prose acceptance decision and the
preserved testing boundary. Its earlier test-removal identity is
historical evidence; current prose evidence uses the candidate above.

**Original delivery checkpoint (November 4):** The [exact-head
review](#89 (review))
approved the candidate at `2026-11-04T12:27:50Z`, with zero inline
comments and no active review issues. Previous-head approvals are not
reused. The November 4 review and static-check receipts above remain
historical evidence, not a new review or current hosted CI result.

**Original lifecycle-only pause:** At the November 4 checkpoint, this PR
stayed unmerged while the requested independent testing-cleanup
proposals were created. Agent merge and automatic landing were disabled.
This records the original delivery checkpoint; it is not an outstanding
requirement to adopt or merge those proposals.

**Current prerequisite record (November 11):** The creation request is
fulfilled by [MSXOrg/docs#240](MSXOrg/docs#240),
[PSModule/Process-PSModule#551](PSModule/Process-PSModule#551),
and the source-bound no-test audits of MSXOrg/.github and
PSModule/.github. No native dependency requires adoption or merge of
those unrelated proposals. No content question remains. The [fresh
prerequisite and exact-head
evidence](#88 (comment))
records those source identities, native relationships, fresh
existing-tool checks, and their limits.

The root has granted bounded operational acceptance of unchanged head
`7eedb8a44c00bfa0f38d541ea88a7d7d791eaa19` under the user's live
direction to review remaining changes and merge them when ready. The
root has not granted this PR the exclusive global merge slot; Process
owns it. A bounded exact-head squash is permitted only after that slot
is granted. No merge or automatic landing is authorized now.

The current native state remains open, not draft, and unmerged, with
GitHub `autoMergeRequest=null`. Agent merge remains disabled; actions
remain `address_reviews=true`, `fix_ci=true`, `resolve_conflicts=true`,
and `merge_pr=false`. Current hosted check-runs and commit statuses are
empty, not green CI. No changed coverage or organization rule is
claimed. The absent-CI, static/manual-only, and STE verification limits
remain in force.

| Changed surface | Standards checked | Framework/domain docs checked |
Result |
| --- | --- | --- | --- |
| Feature-form display prose | Fixed MSX writing baseline; relevant
official STE rules/dictionary; existing YAML guidance | GitHub
issue-form roles; native feedback refinement and Task/Bug planning
boundaries | Fixed in this PR |
| Removed-test state and evidence | MSX Testing: Test supported behavior
| None (no owned form runtime) | Aligned; live behavior unexecuted |

The exact feature-form-path issue sweep found this Task, the separate
writing campaign issues, and the broader YAML work. No additional issue
is fully delivered by this feature-only branch; this PR has only
[#88](#88) as
its closing delivery leaf. The Task remains open, and the PR is
unmerged. Retired validator/governance work is not reinstated. Issue
states/relationships, repository labels/protections, and other community
files remain unchanged.

</details>

<details>
<summary>Related references</summary>

<!-- Use fully qualified repository references for closing and related
work. -->

- Resolves
[#88](#88)

### Related work

- References
[MSXOrg/docs#228](MSXOrg/docs#228)
- References [MSXOrg/docs#230](MSXOrg/docs#230)

</details>
Marius Storhaug (MariusStorhaug) added a commit to MSXOrg/.github that referenced this pull request Nov 11, 2026
<!-- Lead with one concise paragraph describing the user-facing outcome.
-->

Feature requesters describe their need, motivation, and expected result
without choosing an implementation or learning a special scenario
format. The shared form keeps its feature identity, routing, and one
required free-text field.

<!-- ANNOUNCEMENT STOP -->

<!-- Add user-facing sections for breaking, new, changed, or fixed
behavior when needed. -->

## Changed: Consumer-focused feature intake

The **Describe the need** field requests who benefits, the problem or
opportunity, and a situation/action/result example. A failure or limit
example is conditional. The introduction uses direct requests and states
the feedback/internal-planning boundary as current fact. Technical
Task/Bug plans, existing labels, native-type selection, and minimum
submission requirements are unchanged.

## Adopting this release

After merge, repositories that use this organization-owned form receive
the prompts without consumer-local copies. No configuration, code, or
invocation change is required. Local issue forms retain precedence and
are not changed here. This public defaults repository does not publish a
versioned release.

## Release impact

This is a compatible, patch-level intake improvement. No versioned
publisher applies and no version is produced. No live labels, release
configuration, permissions, rulesets, or merge settings change.

---
<details>
<summary>Technical details</summary>

<!-- Record the implementation approach, issue-plan progress, standards
alignment, and convergence sweep. -->

### Consumer change record

| Surface | Before | After | Consumer action / verification |
| --- | --- | --- | --- |
| Organization feature form | Required Description asks for
implementation suggestions and alternatives. | The same `description`
field asks for consumer need, motivation, and observable examples. Name,
title, labels, native-type absence, and required-field contract remain.
| No consumer edit. One-time YAML/interface, native rendering, and
actual link checks are recorded below. |

### Template baseline

Head `9a4da3a0dacf7cfc68cad80270884886bcdc1ad9` targets `main` at
`0c67251812ea306543f3a14ab473ae357cfb76ac`. The final PR diff is **one
modified feature form: 17 additions, 7 deletions**. No added test or
validator remains.

The form is byte-for-byte equal to candidate
`589285cfb6c2ecc761c5308de4527d2dd2c54bd4`, with blob
`19d6abbbf5b1a4a5b48ce5710be9f7e79f0be742`. The latest commit removes
only the 119-line added test suite; it changes no form content or
behavior and no other source file.

The consumer guidance is published:
[MSXOrg/docs#230](MSXOrg/docs#230) merged on
2026-11-03 at `8c9d9353eb154d6072b3ed1d825a78d58a4665d3`. The fixed
[writing
baseline](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md)
and official STE guidance govern the unchanged prose. Shipped links use
the current canonical planning/routing pages, not an immutable review
snapshot.

### Maintainer evidence

**Test-policy correction.** The whole `FeatureIntake.Tests.ps1` file was
added by this PR. Its 12 cases froze checked-in YAML metadata, shape,
phrases, URLs, or blank configuration; built-in Markdown conversion
exercised no owned runtime. The [current Testing
rule](https://github.com/MSXOrg/docs/blob/f9b335d0b78a3eead0b7efa573936e86cb1e7265/src/docs/Coding-Standards/Testing.md#test-supported-behavior)
prohibits those source-string and snapshot assertions. The user-directed
review supersedes the earlier campaign limit on removing them. All 12
passed immediately before removal: this is conformance, not hiding a
failing test. No owned-runtime coverage or conflicting content decision
was found. There is no replacement test, validator, simulation, tooling,
or configuration. **No runtime suite remains and no current test pass is
claimed.** Earlier suite results and reviews are historical evidence for
their stated commits only.

**Fresh one-time checks.** Configuration/reference results stay outside
source. With `$configuration` naming the published default snapshot and
`$target.Path` each named input:

| Actual command / operation | Result |
| --- | --- |
| `python -` (inline PyYAML interface and raw-byte inspection) | 20
nodes, 6 mappings, 2 body elements, 1 required `description` textarea.
All non-prose keys/order/types/values and blank configuration match the
original base. The current form bytes exactly match `589285c`. |
| `yamllint --format parsable --config-file $configuration
$target.Path`; repeat with `--strict` | All 6 runs (original `0c6725`,
prior `589285c`, and current form; normal and strict) return exit 0 with
0 diagnostics. No baseline formatting change or weakened rule. |
| `gh api --method POST markdown --input -` with actual introduction,
`mode=gfm`, `context=MSXOrg/.github` | Native GitHub HTML renders
exactly 2 canonical links. |
| `python -` (inline unauthenticated HTTPS/actual HTML inspection) | 2
targets return HTTP 200:
[planning](https://msx.no/docs/Ways-of-Working/Issues/Process/Planning/)
contains `issue-planning`;
[routing](https://msx.no/docs/Ways-of-Working/Issues/Types/Hierarchy/)
contains `issue-hierarchy`. Neither form link has a fragment. |
| `git diff --name-status origin/main...HEAD`; `git diff --check` |
Exactly one modified feature form; whitespace check passes. |

YAML-default provenance: [current
Docs.yml](https://github.com/MSXOrg/docs/blob/f9b335d0b78a3eead0b7efa573936e86cb1e7265/.github/workflows/Docs.yml)
selects Super-Linter `4ce20838b8ab83717e78138c5b3a1407148e0918` without
a YAML override. Its [published
default](https://github.com/super-linter/super-linter/blob/4ce20838b8ab83717e78138c5b3a1407148e0918/TEMPLATES/.yaml-lint.yml),
blob `2aa49bd1867e24acdea4172191922df6135b69c6`, is used locally only.
It is not installed repository CI or a nonexistent MSX YAML override.
The configuration bytes match that source exactly. Its [yamllint
dependency
pin](https://github.com/super-linter/super-linter/blob/4ce20838b8ab83717e78138c5b3a1407148e0918/dependencies/python/yamllint.txt)
is `yamllint==1.38.0`, matching the local tool.

These observations establish static interface preservation, rendered
links, and actual page/anchor availability. They are **not owned-runtime
tests, GitHub form-submission end-to-end coverage, or hosted CI**.

| Changed surface | Guidance / result |
| --- | --- |
| Feature form | YAML, Natural Language, canonical planning/routing, and
GitHub form schema checked; consumer content and routing preserved. |
| Removed added suite | Current Testing prohibition applied by deletion;
no source-shape test or replacement remains. |

The existing Task plan and evidence are updated. Scoped convergence
finds no additional fully delivered issue: #10 concerns
community PR templates, #11/#12 hosted validation,
#13 hooks, and #16/#17/#18 other campaign
surfaces. Only #14 closes here. No new issue, CI/toolchain
work, rule, or label is introduced.

**Final review and native state.** The explicitly requested
[current-head Copilot
review](#15 (review))
is `APPROVED` at `9a4da3a0dacf7cfc68cad80270884886bcdc1ad9`, with no
active code issues or inline comments. All 5 submitted reviews were
read: 4 historical `COMMENTED` reviews and this approval. Complete
thread pagination reports 0 threads. GitHub now reports
`MERGEABLE/CLEAN` and review decision `APPROVED` for the exact head/base
above. The only check run is the successful
`copilot-pull-request-reviewer`; there are 0 commit statuses, and the
GraphQL rollup remains empty. No actually failing or named required
check is reported. **Organization defaults validation has not executed
at this head**: a successful reviewer check is not hosted form
validation. Separate
[#12](#12) remains
unmerged and is not revived here. Absent execution is not a pass.

Effective organization rules preserve squash-only integration,
stale-review dismissal, code-owner review, last-push approval, and
resolved threads. No named required-status-check rule is present. Those
review/approval prerequisites are not waived by local checks or a
Copilot run.

The PR remains open/non-draft. GitHub auto-merge and merge-queue entry
are null. Agent merge remains enabled for review/CI/conflict maintenance
with `merge_pr=false`; no settings changed. Root holds an exclusive
global merge slot elsewhere. **No merge is authorized in this session
until that slot is handed off.** No content decision is unresolved.

</details>

<details>
<summary>Relevant issues (or links)</summary>

<!-- Use fully qualified repository references for closing and related
work. -->

- Resolves #14

### Related work

- References
[MSXOrg/docs#228](MSXOrg/docs#228) and merged
[MSXOrg/docs#230](MSXOrg/docs#230) for canonical
consumer guidance.
- References
[#11](#11) and
[#12](#12) for
separate hosted validation.
- References
[#13](#13) for
separate local hooks.

</details>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Express Epic and PBI issues as consumer expectations

2 participants