[Marius Storhaug (MariusStorhaug)]

Release guidance defines durable intent, phase-aware recovery, complete source-bound consumer records and settings-driven decisions using the canonical prerelease spelling. Its format/routing pages reuse the same complete canonical contract as the neighboring proposals, while preserving this PR's distinct lifecycle and target design.

This delivery changes guidance, not a producer runtime. No release, artifact, live caller setting or consumer installation changes because of it. Existing immutable-version consumers need no action. Authors and implementation owners adopt the protocol below; owned-tag recovery applies only when a trusted, permitted alias actually moves, not because these docs changed.

New: Owned moving-tag recovery keeps one explicit trust boundary

Use the procedure only for an intentionally moved MSX-owned major or minor alias that the consumer's artifact-specific pinning standard permits. Ownership alone does not authorize mutable references: the owned Action/reusable-workflow major-tag exception does not permit minor aliases. Exact version tags are immutable; their movement is an integrity incident, not routine recovery. SHA- or exact-version-pinned consumers require no action for this documentation delivery.

If the trusted alias is stale, verify the intended remote and back up needed local-only tags outside refs/tags/ before refreshing. Renaming a tag within that namespace does not preserve it from pruning. A verified git bundle create owned-tags-backup.bundle --tags followed by git bundle verify owned-tags-backup.bundle can retain original tag objects and reachable history; keep the backup private and outside checked-in paths.

The whole-namespace refresh is git fetch --tags --force --prune --prune-tags origin. Force replaces local tag values with that explicitly selected remote's values, and tag pruning removes local tags absent there. Accept that complete scope deliberately, review the output and do not normalize an altered exact version tag. Naming origin prevents a different upstream from choosing the source of this operation.

For ongoing controlled movement, inspect remote.origin.fetch and add +refs/tags/*:refs/tags/* once only when absent. Set clone-local remote.origin.prune and remote.origin.pruneTags to true, not clone-wide pruning defaults that can affect other remotes. Fetch explicitly from origin. Compare the local alias's tag-object hash with git ls-remote --refs origin refs/tags/<alias>, then resolve its exact release and immutable source before use. A stale or unverifiable result blocks use.

This is a general conditional operating procedure, not version-specific migration history. No real consumer tag, configuration or history is changed by this PR. The anonymous verification repositories contain only empty commits and test tags.

Technical details

Changed surface	Standards checked	Framework docs checked	Result
Accept Moved Release Tags guide	Guide structure, Natural Language, Markdown	Owned-alias trust, tag pruning and immutable-source verification	Aligned
GitHub Actions owned-tag link	Owning coding standard, Markdown	Allowed major-tag exception and consumer recovery	Aligned
Capability indexes and navigation	Front matter, generated indexes	Documentation Model	Aligned

An isolated anonymous Git experiment reproduced implicit upstream selection and pruning of a renamed local-only tag. Verification with complete 40-character identities confirmed that an independent bundle retains the pruned ref, explicit origin restores the intended alias, and origin-scoped pruning does not remove origin-owned tags when another remote is fetched. The experiment did not touch repository tags or create a release.

Changed: Durable lifecycle and native targets require verified conformance

The numbered specification retains fixed approved source/notes, permanent reservations after build or visibility, one retained artifact through verification/publication, destination progress, phase-aware retries, retirement/withdrawal, stable/candidate authority, current discovery, optional aliases and independent post-completion announcements. Records cover the complete accumulated source range, including skipped changes. Version computation uses permanent reservations and the aggregate minimum bump; consumer change discovery separately starts from the last completed release.

Implementation owners verify the invoked immutable producer and actual controls before relying on them. A normative requirement or configuration example is not proof that an older runtime implements recovery, manual release creation, candidate routing, alias reconciliation or announcement journaling. Exact producer adoption actions belong in its own PR/release record. Existing operators retain their released interface; an incomplete release is not repaired by rebuilding under an exposed version or re-resolving changed metadata. This documentation requires no runtime migration of its own and delivers no broad lifecycle engine, history backfill, downstream propagation or Discord sender.

A duplicate or phase-aware retry reuses its original logical intent, approved source, frozen version and retained artifact. A separately approved corrective release has a distinct immutable approved logical request identity, even when reviewed source is unchanged; it receives a new intent/version and preserves its relationship to the earlier attempt. Do not reuse a retry key to suppress that new approved request, supersede an exposed intent, or reuse a reserved version. Applicable producer/template adoption evidence records the template repository and immutable commit, compatibility with the selected producer source, and delivered integration changes or a justified no-change result. This docs-only delivery changes no released producer or integration template, so concrete runtime/template adoption values are not applicable here.

Publishing targets distinguish canonical and native identities. A PowerShell prerelease uses numeric ModuleVersion plus PrivateData.PSData.Prerelease; for example, 2.5.0-alpha is core 2.5.0 and label alpha, not a prerelease string in ModuleVersion. Validate the selected client's suffix syntax and reject or explicitly map unrepresentable forms without collisions or lost ordering.

Native bounded ranges, where supported, can express major/minor update policies without producer aliases. A field without a native range resolver can also receive immutable patch updates when permitted bounded update selection exists outside that field. A SHA-pinned Action or reusable workflow does not need or acquire permission to retain a minor alias for that policy. Git/container reference fields do not evaluate range-like strings. Require a permitted matching alias only when no other permitted resolver supplies the bound; if none can express it, fail without widening to latest or another boundary. Retain the exact version, full commit SHA or digest required by the artifact's pinning standard and trust policy.

The owning VS Code framework declares stable/prerelease native mappings together before enabling Marketplace publication. Numeric versions and the native channel do not imply a direct conversion from every canonical SemVer. An odd-minor convention is valid only with reserved stable space and proven series/counter allocation. Unsupported mappings or collisions fail before publication; an enabled required destination is not silently skipped. This PR specifies and verifies the conformance boundary, not a new version-allocation runtime.

Technical details

Changed surface	Standards checked	Framework docs checked	Result
Release Management spec/design and index	Specification/design separation, Natural Language, Markdown	Durable intent, immutable bounded selection, source authority and conformance	Aligned
Publishing-target contract	Owning target requirements, Markdown	Two-field module mapping, complete records, native coordinates and resolver fallback	Aligned
VS Code Extension Framework spec/design	Owning framework, Markdown	Coordinated native mapping and effective policy	Aligned
Parent/capability indexes and navigation	Generated-index conventions	Documentation Model	Aligned

The PowerShell native manifest tool verified numeric ModuleVersion and separate prerelease data; prerelease text does not parse as System.Version. Official Git, PowerShell and Marketplace documentation grounded the scope/mapping corrections. No Marketplace publication or invented allocator is claimed.

Written consumer-policy cases were checked across FR14, its design and native targets: omitted policy retains the strongest immutable reference; native minor bounds need no alias; permitted SHA-pinned bounded selection chooses a compatible patch without changing major/minor or retaining a minor alias; an owned Action's minor alias is not authorized by the major-tag exception; unavailable native/bounded/alias resolution fails without widening; an external latest result stays immutable; opaque range strings are not parsed; and patch-only pre-1.0 selection stays within its chosen minor rather than using a potentially breaking v0 alias. These verify the written contract, not a delivered resolver runtime. The positive SHA-pinned scenario and narrowed unsupported-policy preconditions cover the concrete review counterexample.

Current immutable candidate: 9f92fa1ad8f8f4d56e79f52a40acee09a3bdbad4. Local validation includes all 64 Pester tests in six suites, complete index/relative-link checks across 128 pages, seven cross-repository links, targeted lint for the final corrections, a clean pinned Zensical 0.0.59 build without missing anchors, patch checks, exact scaffold identity across candidates, and native/anonymous verification above.

All five required checks succeed on that exact head: Lint, Links, Test, Build, and Cross-repository links. Both runs are completed pull_request runs with the same source identity. The repository-only main rule requires those Actions checks; the existing approval/thread constraints remain. Native prerequisite #166 is closed/completed. No failed-check injection, merge attempt or bypass was used.

Complete review: 5723529327 approves that exact head. Its full summary, including resolved/suppressed feedback, records no active or open concerns; every concrete thread has a fix-linked reply and is resolved, with complete thread pagination. This is the automated author-side pass, not independent human approval or permission to merge.

All five existing implementation-plan items in the closing Task are fulfilled: inspection, contract cases, scoped reconciliation, native validation/full review, and final acceptance/handoff evidence. The scoped convergence sweep covered lifecycle, defaults, notes, tags, framework, workflow and consumer-upgrade work. Only the closing Task is fully delivered; producer implementation, consumer execution, date strategies and historical/governance cleanup remain outside scope.

Related references

• Resolves MSXOrg/docs#227
• References MSXOrg/docs#166

Changed: Canonical settings, full notes and authoring stay consistent

DefaultBump accepts patch, minor or major, with shared patch as the documented default. Repository settings and explicitly supplied supported caller overrides resolve before one owned bump-label override. Omitted caller inputs preserve repository policy; invalid supplied settings and conflicting signals fail even when another input supplies a valid level. A compatible effective default requires no per-PR bump label. The producer documents its actual supported caller surface; this PR does not approve an undecided runtime interface.

The owned set is exactly release:patch, release:minor, release:major, release:prerelease and release:skip. Prerelease uses the resolved bump; skip combines with no other signal. ReleaseType owns stable/prerelease/candidate branch keys, and candidate/announcement behavior uses supported settings rather than extra labels. Verify actual producer or adapter support before changing a live caller. Unmanaged routes omit both release metadata and every release label; this repository's Docs route only deploys Pages without a versioned artifact, so this PR retains only its documentation label.

Authors use the identical complete canonical scaffold: a reader-facing title, one boundary after the leading summary, ordered non-empty classifiers, exact actions or a justified no-action result in each result's prose, scoped supporting evidence/references and conditional release decisions. Internal-only work uses its summary/supporting-block exception. The complete captured title and body remain the note at applicable targets; announcements do not truncate publication. Consumers compose every applicable record from their actual baseline through the target, retaining required intermediate operations. Missing instructions block publication; PRs/diffs provide optional depth and resource docs show supported target-state usage.

Maintained scaffolds adopt those authoring rules without a software installation. Version-specific transition instructions stay in the affected PR/release record, not another migration guide or changelog. The legacy partial format is not retained as a competing contract.

Technical details

Changed surface	Standards checked	Framework docs checked	Result
Release Management setting/source/record scenarios	YAML examples, Natural Language, Markdown	Effective sources, complete notes and stable canonical anchors	Aligned
PR Format and Automation Labels	Canonical format, namespace ownership	Exactly five signals and verified actual-route mapping	Aligned
Contribution guide, workflow/contribution, Implement/Review, readiness, repository, README and branching pages	Ways of Working, PR Format	Shared finalization and routing	Aligned
Fleet, Documentation Model and generated Ways of Working index	Fleet/native linking, ownership, index conventions	Complete source-bound history	Aligned
Dependency coding/Actions guidance; Dependency Updates spec/design; Merge Automation design; Natural Language	Owning standards/capabilities	Conditional decisions and actionable errors	Aligned

The existing proposals remain separate on their main targets. Read-only paired composition identifies conflicts in the release spec, design and index in every pair, plus the VS Code framework design in the format/defaults and defaults/lifecycle pairs. The complete PR Format/Fleet content is identical. Eventual landing is one at a time, with remaining-branch reconciliation against actual advanced main and CI/full review repeated. No PR merge, retarget, replacement, amendment or auto-merge was performed.

The clarified issue-guidance follow-up is separate: Epic/PBI consumer/BDD authoring, retained Task/Bug technical plans and community-default inheritance are not independently rewritten here. The docs contribution guide retains genuine repository-specific validation instructions and inherits the organization PR template; no duplicate local template was introduced.

Related references

• References MSXOrg/docs#209
• References MSXOrg/docs#196
• References MSXOrg/docs#205

[Copilot]

🟡 Changes recommended

Unresolved documentation issues risk unintended tag deletion or replacement and leave release-range policies, prerelease version mappings, and PR-format requirements inconsistent.

7 open issues

• Require tag backups outside the pruned namespace · New
• Specify origin explicitly for fetch and verification · New
• Limit tag pruning to origin · New
• Document prerelease mapping across manifest fields · New
• Define collision-free stable and prerelease version mapping · New
• Align PR Format with FR10’s result-scoped evidence · New
• Allow native bounded ranges without requiring aliases · New

What changed in this PR

This documentation-only PR expands Release Management into a durable lifecycle contract and connects it to authoring standards, publishing targets, and consumer guidance. It distinguishes required controls from verified producer capabilities; no runtime, artifact, or consumer configuration changes are delivered.

Changes:

• Defines durable release intents, build-once recovery, publication completion, withdrawal, and consumer update policies.
• Revises settings precedence, canonical release labels, and complete source-bound release records.
• Adds owned moving-tag recovery guidance and updates navigation and related framework documentation.

File	Description
src/​zensical.toml	Adds navigation for the tag-recovery guide.
src/​docs/​Ways-of-Working/​PR-Format.md	Updates release applicability, defaults, and announcement boundary guidance.
src/​docs/​Ways-of-Working/​Automation-Labels.md	Defines the five owned release labels and verified producer mapping.
src/​docs/​Coding-Standards/​Natural-Language.md	Revises the release-decision error example.
src/​docs/​Coding-Standards/​GitHub-Actions.md	Links owned-tag consumers to recovery guidance.
src/​docs/​Capabilities/​vscode-extension-framework/​spec.md	Updates release defaults and canonical prerelease requirements.
src/​docs/​Capabilities/​vscode-extension-framework/​design.md	Revises input precedence and decision revalidation guidance.
src/​docs/​Capabilities/​release-management/​spec.md	Defines numbered lifecycle, evidence, recovery, and consumer requirements.
src/​docs/​Capabilities/​release-management/​index.md	Summarizes the expanded capability and indexes its pages.
src/​docs/​Capabilities/​release-management/​design.md	Describes durable state, lifecycle transitions, settings, and conformance.
src/​docs/​Capabilities/​release-management/​design-publishing-targets.md	Expands destination mapping, immutability, and publication contracts.
src/​docs/​Capabilities/​release-management/​accept-moved-release-tags.md	Adds conditional refresh, configuration, and verification instructions.
src/​docs/​Capabilities/​index.md	Updates the Release Management capability description.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The design still lacks a retirement path for exposed resolved intents and an explicit version-calculation baseline, while incorrectly freezing reservation state after Resolve.

3 open issues

• Separate frozen versions from reservation-state transitions · New
• Add a Resolved-to-Retired transition · New
• Record the version-computation baseline in the envelope · New

7 resolved since last review

• Allow native bounded ranges without requiring aliases
• Align PR Format with FR10’s result-scoped evidence
• Define collision-free stable and prerelease version mapping
• Document prerelease mapping across manifest fields
• Limit tag pruning to origin
• Specify origin explicitly for fetch and verification
• Require tag backups outside the pruned namespace

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The documentation conflicts with permanent version reservations and minimum-increment rules, while dashboard queries omit PR IDs required for joining and deduplicating results.

3 open issues

• Align the example with the pending minor increment · New
• Use the shared resolver instead of tags as the version base · New
• Include PR node IDs for joining result sets · New

3 resolved since last review

• Record the version-computation baseline in the envelope
• Add a Resolved-to-Retired transition
• Separate frozen versions from reservation-state transitions

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Human assessment is needed to weigh omitted template-evidence requirements and request-key reuse that can block a separately approved corrective release.

No open issues 🎉

3 resolved since last review

• Include PR node IDs for joining result sets
• Use the shared resolver instead of tags as the version base
• Align the example with the pending minor increment

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Human assessment is needed because the patch-only and minor-alias guidance may conflict with the stricter version-pinning standards for owned Actions and reusable workflows.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The conformance scenario can reject SHA-pinned consumers using bounded update selection explicitly permitted by FR14, so its preconditions need narrowing.

1 open issue

• Allow bounded updates for SHA-pinned references · New

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The publishing-target design still requires a producer alias for every Git boundary policy, conflicting with FR14’s allowance for bounded updates via immutable references and the Actions standard’s alias restrictions.

1 open issue

• Allow bounded updates without requiring a producer alias · New

1 resolved since last review

• Allow bounded updates for SHA-pinned references

_{Review effort: Balanced}

[Copilot]

🟢 Approved

No active review issues are recorded for the documentation-only changes aligning release lifecycle and workflow guidance.

No open issues 🎉

1 resolved since last review

• Allow bounded updates without requiring a producer alias

_{Review effort: Balanced}