Skip to content

📖 [Docs]: Release notes carry complete consumer adoption evidence - #204

Merged
Marius Storhaug (MariusStorhaug) merged 5 commits into
mainfrom
evergreen-upgrade-process
Sep 6, 2026
Merged

Marius Storhaug (MariusStorhaug) merged 5 commits into
mainfrom
evergreen-upgrade-process

Conversation

@MariusStorhaug

@MariusStorhaug Marius Storhaug (MariusStorhaug) commented Sep 6, 2026 •

Copy link
Copy Markdown
Member

Release-bound pull requests classify changes for their declared user/integrator audience and describe the incremental actions that audience needs to adopt them. Release levels come from an explicit decision or an opt-in repository default; missing decisions must block merge in CI. Published notes preserve the complete authored record and its source/template evidence.

Changed: Change type follows the target audience

Each initiative describes its audience and supported jobs; each repository README states its audience or explicitly adopts that definition and records any specialization. Users and integrators can be the same people: PSModule module users integrate commands into their work, and Process-PSModule users integrate the delivery workflow into their module repositories.

Change type follows the highest impact on supported uses, not file location, edit size, or the reviewer's perspective. An incompatible output, runtime requirement, or caller interface remains breaking even when an interactive command still works or only a manifest or .github/ file changes.

Changed: Repository defaults are explicit policy decisions

For PR-driven releases, an owned bump label overrides the optional DefaultBump in .github/release.config.yml. The setting accepts patch, minor, or major. If neither supplies a level and no valid release:skip is selected, the decision is missing: there is no implicit patch fallback. Prerelease mode can use an explicit or configured bump, but the mode alone is not a level. Invalid defaults and conflicting owned labels fail rather than selecting a convenient fallback.

The declared default is not evidence of compatibility: authors still assess the audience impact and override the default when needed. Release-label names, SemVer arithmetic, and pre-1.0 mapping remain unchanged. The optional ad hoc dispatch keeps its existing explicit-bump requirement.

Changed: Missing decisions block merge, not only publication

The release contract requires a named PR decision-validation check, enforced by the target branch's ruleset or protection. Missing, invalid, or conflicting decisions fail it before merge. The check re-evaluates source, release-label, and settings changes; a failed, pending, or absent required result prevents manual and automatic merge. A valid skip passes with a no-release outcome instead of skipping validation. Publication validates its actual inputs again.

This PR documents that contract; it does not implement producer CI workflows or change repository rulesets.

Changed: Consumer adoption and publication evidence are complete

PR descriptions include Adopting this release and Release impact sections, an applicability-aware consumer change record, and a verified immutable template baseline where applicable. Public interfaces belong in user-facing prose, and breaking behavior remains explicit independently of version classification.

The release-management contract preserves the release-bound title and complete description. Actual coordinates and provenance remain separate from authored prose, and version-computation and consumer-change baselines remain distinct. Bundled, optional ad hoc, and source-specific prerelease records retain equivalent evidence. Metadata corrections preserve an audit without changing artifacts or historical behavior. Release filters reflect product contracts, not directory names alone.

Adopting this release

  1. Initiative owners declare their audience and supported jobs. Repository maintainers state the audience, jobs, and interfaces in the README, or explicitly adopt the initiative definition and record any specialization. Detailed users and jobs stay in the linked capability specification.
  2. For each PR release decision, select an owned level or intentionally configure DefaultBump in the release settings. An explicit level wins; neither source is an error, not a patch default. Select release:skip for a no-release decision. Verify the resolved level against the audience impact.
  3. Use the PR Format structure: ordered adoption or an explicit no-action outcome, effective release impact and its source without predicting a final version, and each changed surface's before/after behavior, applicability, exact action, and verification. Include a verified immutable template baseline where applicable, or explain why none applies.
  4. Producer CI maintainers run the same decision resolver during PR validation, make its named check required in branch protection/rulesets, and cover relevant source and metadata changes. Missing, invalid, conflicting, pending, and absent results must not permit merge; a valid skip must produce an explicit successful result.
  5. Publisher maintainers preserve the complete source-bound record, resolve actual publication coordinates, audit metadata corrections, and keep consumer-facing interfaces in release filters. Implementation and governance changes remain separately scoped in their owning repositories.

Release impact

Field Value
Effective decision release:skip, documentation only.
Semantic effect No versioned artifact release. The documented PR decision contract permits an opt-in default and requires a merge-blocking CI gate; it does not install that gate in producers.
Release/base coordinates No version is produced by this PR.

Technical details

Consumer change record

Identifier / surface Before After Applicability / prerequisites Consumer action Verification
AUDIENCE-CONTEXT / initiative docs and READMEs Audience context is not required as an input to classification. Explicit audience, jobs, and interfaces anchor classification; user/integrator roles may overlap. Initiative owners, maintainers, and PR authors. Adoption steps 1-2. Readers identify supported uses without inferring them from ownership or filenames.
RELEASE-DECISION / release settings and PR CI The spec forbids defaults while PR evidence permits configured policy; missing decisions lack an explicit required pre-merge check contract. An explicit bump overrides optional DefaultBump; neither source fails. Required CI validates the decision and blocks merge on missing/invalid/conflicting input. Producers implementing Release Management and consuming frameworks. Adoption steps 2 and 4. Explicit/default/override/skip/mode/error cases agree; the decision check is required, not merely advisory.
PR-EVIDENCE / release-bound PR bodies Adoption may be scattered and path/size heuristics can obscure impact. Ordered adoption, resolved release impact, consumer/template evidence, and highest-impact classification are required. Authors following MSX PR Format. Adoption steps 2-3. Every changed surface records applicability, action, and result; no-action and breaking cases stay explicit.
NOTE-PUBLICATION / publication contract Complete-body, source-snapshot, correction, and product-aware filter obligations are not explicit. Full authored records retain actual coordinates and source identity; corrections preserve artifacts; filters include shipped interfaces. Publisher maintainers. Adoption step 5. Published content matches its source-bound snapshot, and metadata corrections leave artifact/source identities intact.

Template baseline

Not applicable: this PR changes shared standards, not a versioned framework integration or its template. The PR-format skill remains an unchanged thin pointer; no plugin metadata or version change is needed.

Maintainer evidence

Changed surface Standards checked Framework docs checked Result
PR Format and related workflow/gate guidance Natural Language, Markdown, Documentation Model, standard template, issue/PR conventions Release Management; Merge Automation; audience contract Aligned
Release Management spec/design/index Natural Language, Markdown, Documentation Model, spec/design templates PR Format; Merge Automation Aligned
VS Code framework spec/design Natural Language, Markdown, Documentation Model, spec/design templates Shared Release Management contract Aligned
README/organization/repository standards and audience examples Natural Language, Markdown, README-Driven Context MSX documentation purpose; PSModule initiative boundary Aligned
Natural Language error examples Natural Language, Markdown Release-decision validation contract Aligned

The walkthroughs below assess the documentation contract, not a running producer or the PSModule pilot:

Case group Reconciled outcome
No-action patch; pre-1.0 break No-action is explicit; Minor mapping does not hide breaking behavior or required actions.
Skipped releases; prerelease; non-latest target Each applicable delta and source/template identity remains recoverable; latest metadata does not replace historical evidence.
Shared user/integrator roles; path/size; mixed changes; missing audience Supported audience impact controls classification; absent audience context is resolved rather than guessed.
Explicit level; configured default; override A valid explicit label wins; a configured default supplies a missing bump and is recorded as the source.
Missing/invalid/conflicting decisions The required PR check fails and merge is blocked. No built-in patch or conflict fallback is permitted.
Skip; prerelease; unowned labels Valid skip passes without a bump; a mode needs a resolved bump; unowned labels never supply a decision.
Changed labels/settings/source Validation re-evaluates the candidate inputs; publication revalidates its actual inputs too.
Relevant issues (or links)

Related work

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 Changes recommended

The updated guidance contains internal inconsistencies (notably release-impact “published coordinates” requirements and mismatched heading levels vs the example) that could mislead authors following the template.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Updates the MSX PR Format documentation to treat release-bound PR bodies as the authoritative, consumer-facing adoption record, and to require explicit adoption and release-impact evidence that publication preserves.

Changes:

  • Adds “source of truth” guidance connecting PR bodies to Release Management’s publication/provenance responsibilities.
  • Requires structured ## Adopting this release and ## Release impact sections, plus a consumer change record/template baseline/maintainer evidence split under Technical details.
  • Expands the example PR body to demonstrate the new required sections and evidence tables.
File summaries
File Description
src/docs/Ways-of-Working/PR-Format.md Clarifies PR bodies as authored release notes and adds explicit adoption, release-impact, and evidence-record requirements.
Review details

Suppressed comments (2)

src/docs/Ways-of-Working/PR-Format.md:166

  • The guidance section uses a #### Template baseline heading, but the Example block below uses ### Template baseline. Aligning these heading levels avoids ambiguity about the expected structure inside the Technical details block.
#### Template baseline

src/docs/Ways-of-Working/PR-Format.md:179

  • The guidance section uses a #### Maintainer evidence heading, but the Example block below uses ### Maintainer evidence. Using the same heading level in both places will make the template easier to follow.
#### Maintainer evidence
  • Files reviewed: 1/1 changed files
  • Comments generated: 2
  • Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread src/docs/Ways-of-Working/PR-Format.md Resolved
Comment thread src/docs/Ways-of-Working/PR-Format.md Resolved

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.

🟢 Approval recommended

The documentation updates are internally consistent, links/anchors resolve correctly, and the described authoring/publication contracts align across PR Format and Release Management spec/design.

Review details
  • Files reviewed: 3/3 changed files
  • Comments generated: 0 new
  • Review effort level: Lite

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 Changes recommended

Two documentation issues in changed lines (path-filter snippet copy/paste hazard and minor wording/grammar inconsistencies) should be corrected to avoid propagating incorrect guidance.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details
  • Files reviewed: 8/8 changed files
  • Comments generated: 3
  • Review effort level: Lite

Comment thread src/docs/Ways-of-Working/PR-Format.md Resolved

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.

🔵 Needs a closer look

There is at least one internal inconsistency in the updated documentation contract wording that could mislead authors about required release-decision evidence.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

src/docs/Ways-of-Working/PR-Format.md:130

  • The “Effective decision” row currently reads as if a configured policy could supply the release decision instead of an explicit owned release:* label. That conflicts with the Release Management spec’s requirement that a bump label is mandatory (no default) and risks confusing authors about what must appear in the PR body.
  • Files reviewed: 8/8 changed files
  • Comments generated: 0 new
  • Review effort level: Lite

@MariusStorhaug

Copy link
Copy Markdown
Member Author

Addressed the configured-default inconsistency from Copilot's review summary in fd32b41. The spec/design now require an explicit bump or an opt-in repository DefaultBump; there is no implicit patch fallback. Missing, invalid, or conflicting decisions must fail a required pre-merge CI check, while a valid release:skip reports a successful no-release decision. Related authoring and framework guidance is aligned. These are documentation requirements; producer CI and ruleset implementation remain separately scoped.

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

The changes are documentation-only, internally consistent across the touched standards/specs, and introduce no verified broken links or formatting defects in the modified sections.

Review details
  • Files reviewed: 17/17 changed files
  • Comments generated: 0 new
  • Review effort level: Lite

@MariusStorhaug
Marius Storhaug (MariusStorhaug) merged commit 702be0f into main Sep 6, 2026
22 checks passed
@MariusStorhaug
Marius Storhaug (MariusStorhaug) deleted the evergreen-upgrade-process branch September 6, 2026 12:16
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

release:skip Validate the change without publishing a release.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make release impact and user adoption explicit in PR release notes

2 participants