[Marius Storhaug (MariusStorhaug)]

Release guidance defines durable intent, phase-aware recovery, complete source-bound consumer records, and settings-driven decisions. The documented optional file is .github/release.settings.yml; its directory, keys, defaults, caller precedence, and absence behavior are unchanged. The lifecycle proposal retains the canonical PR-record and release-range-first guidance already delivered on main.

This delivery changes documentation, not a producer runtime. It creates no settings file, legacy filename fallback, versioned release, live caller change, consumer installation, or governance change. Existing immutable-version consumers need no action. Implementation owners verify the invoked producer's actual interface and conformance before adopting any documented setting or lifecycle control.

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 a trusted, permitted 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 another 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 actual consumer tag, configuration, or history is changed by this PR.

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, 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

The earlier isolated anonymous Git experiment reproduced implicit upstream selection and pruning of a renamed local-only tag. 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 verification repositories contained only empty commits and test tags; no repository tags or releases were changed. This filename revision leaves that operating procedure intact.

Changed: Durable lifecycle and native targets require verified conformance

The numbered specification retains fixed approved source and notes, permanent reservations after a successful build or external visibility, one retained artifact through verification and publication, destination progress, phase-aware retries, retirement and withdrawal, stable/candidate authority, current discovery, optional aliases, and independent post-completion announcements. Version computation uses permanent reservations and the reviewed aggregate minimum bump. Consumer record coverage separately starts from the actual latest successful artifact publication for each product, target, and channel.

Authors resolve publication coverage before writing a release-bound record: verify the actual artifact and publication receipt, its immutable source provenance, and the exact candidate; compare those source trees and retain the scoped PR-base comparison separately. Include earlier merged, skipped, direct, and otherwise unshipped changes in the applicable consumer range. Successful Gallery publication advances module note coverage even if later GitHub completion fails. Completing that older GitHub record preserves its original snapshot and does not make its already-published module changes new again. These authoring baselines do not change aggregate approval, version reservations, or completed-state discovery.

Consumers compose every applicable source-bound record after their actual consumed baseline through the target in release order. Notes retain prerequisites, ordering, required intermediate operations, verification, or an explicit no-action result with its compatibility basis. Reading a record does not itself require installing that version. PRs and diffs provide optional depth; resource docs describe supported target-state usage, not another migration history. Missing publication provenance or required instructions blocks the affected publication rather than becoming a no-action result.

Implementation owners verify the invoked immutable producer and actual controls before relying on them. A requirement or configuration example does not prove 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 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 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 newly approved request, supersede an exposed intent, or reuse a reserved version. An affected product integration template requires its repository, compatible immutable commit, producer-source compatibility evidence, and delivered work or a justified no-change result. This docs-only delivery changes no producer or integration template, so concrete runtime/template adoption values do not apply here.

Native publishing identities remain explicit. A PowerShell prerelease uses numeric ModuleVersion plus PrivateData.PSData.Prerelease: canonical 2.5.0-alpha is core 2.5.0 and label alpha, not prerelease text in ModuleVersion. Validate the selected client's suffix syntax and reject or explicitly map unsupported forms without collisions or lost ordering.

Native bounded ranges, where supported, can express major/minor update policies without aliases. A field without a native range resolver can retain immutable patch updates when permitted bounded 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 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 a native channel do not imply direct conversion from every canonical SemVer. An odd-minor convention requires 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 the conformance boundary, not a new allocator or Marketplace publisher.

Technical details

Changed surface	Standards checked	Framework docs checked	Result
Release Management spec/design and index	Specification/design separation, Natural Language, Markdown	Durable intent, aggregate minima, distinct publication/version baselines, complete records, conformance	Aligned
Publishing-target contract	Owning target requirements, Markdown	Two-field module mapping, native coordinates, immutable bounded selection	Aligned
Parent/capability indexes and navigation	Generated-index conventions	Documentation Model	Aligned

The earlier native PowerShell manifest verification established numeric ModuleVersion and separate prerelease data; prerelease text does not parse as System.Version. Official Git, PowerShell, and Marketplace documentation grounded the mapping and trust corrections. No runtime publication or invented allocator is claimed.

Written consumer-policy cases cover omitted policy retaining the strongest immutable reference, native minor bounds without aliases, permitted SHA-pinned patch selection without changing major/minor or retaining a minor alias, the owned-major exception not authorizing minor aliases, unsupported resolution failing without widening, immutable external latest selection, opaque range strings, and patch-only pre-1.0 selection staying inside its chosen minor. These are written conformance cases, not evidence of a delivered resolver runtime.

Current immutable candidate: f68927e94a31520c4db482aa8f2359cc999b80aa. Scoped implementation base: delivered main aa9b5cecc69f4cbe6aa04a5dd70ff9cdadeeac3d, which contains merged #209. The complete actual base-to-head comparison contains 11 files and preserves the lifecycle proposal rather than reintroducing the already-delivered format/file-policy delta. This repository's Docs route is documentation validation and Pages deployment, not a versioned Release Management artifact route; no release-publication baseline or Release decisions block is fabricated for this PR.

Local validation passes all 80 repository Pester tests in seven suites, 22 focused composition/lifecycle-invariant checks, generated-index validation, relative links across 128 pages, seven cross-repository links, exact-file Markdown lint across 12 relevant pages, patch checks, and a clean build with the manifest-pinned Zensical 0.0.59. A stale global 0.0.50 executable was rejected as insufficient evidence; the required version was restored only in an isolated session environment. Dependencies and repository configuration were not changed.

All five required checks succeed on that exact head: Lint, Links, Test, Build, and Cross-repository links. Both runs are completed successful pull_request runs bound to the exact source head; the publication job is skipped.

Fresh full review: 5728246486 approves that exact head. The entire submitted summary reports no active or open concerns; the explicitly requested round added zero inline comments. All 15 existing native threads are resolved, with complete thread and comment pagination. This is the automated author-side pass, not independent human review or permission to merge.

The closing Task's inspection, contract checks, scoped reconciliation, validation/full-review, and acceptance-evidence items remain fulfilled. The filename amendment and delivered-main reconciliation are pushed separately. Producer implementation, consumer execution, date strategies, history correction, and live governance remain outside this Task. No PR merge, merge enqueue, retarget, release, or artifact promotion was performed; Agent merge's landing action and GitHub auto-merge remain off.

Related references

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

Changed: Optional release settings use one filename without changing behavior

The optional documented path is .github/release.settings.yml in Release Management's spec/design, the VS Code framework example, Automation Labels, and PR Format. All eight active filename references in this authored lifecycle shape use that name. No matching file exists in this repository, so no actual settings file was renamed or created. Settings keys, typed overrides, shared defaults, branch/applicability rules, and omitted-file behavior are unchanged. No runtime loader, ConfigurationFile/auto-release.yml surface, SettingsPath/PSModule.yml surface, or legacy filename fallback was added or renamed.

DefaultBump still 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 needs no per-PR bump label.

The owned set remains exactly release:patch, release:minor, release:major, release:prerelease, and release:skip. Prerelease uses the resolved bump; skip combines with no other signal. ReleaseType retains stable/prerelease/candidate branch keys, and candidate/announcement behavior uses supported settings rather than extra labels. Verify the actual producer or adapter interface before changing a live caller. A route without versioned release behavior carries neither release metadata nor any release label; this repository's Docs route remains unmanaged by the versioned-release contract.

Authors use the current finalized PR record: a reader-facing title, one announcement boundary after the summary, ordered non-empty classifiers, exact applicable actions or a justified no-action result, and scoped supporting evidence. Release coverage is resolved first, and the complete captured title/body remains the note. Format adherence is verified from that actual record, not an inherited scaffold or template-file copy. The current no-PR-template-file policy remains in Repository Standard and its owning governance guidance, not PR Format. Product integration template evidence and genuine repository-specific contribution instructions remain separate and intact.

This is a documentation filename revision. Existing runtime consumers do not rename live files or install software merely because the guidance changed; producer support and any required adoption actions must be verified and delivered by the relevant implementation owner.

Technical details

Changed surface	Standards checked	Framework docs checked	Result
Release spec/design filename and VS Code examples	Natural Language, Markdown	Optional settings, typed schema, defaults, caller precedence, applicability	Aligned
PR Format and Automation Labels filename references	Canonical record procedure, namespace ownership	Unmanaged-route absence behavior	Aligned
Delivered canonical composition	Current PR Format and Repository Standard	Release-range-first records, no-template-file ownership, unchanged lifecycle contracts	Aligned

The test-first filename-only revision failed on the old references, then passed all 12 focused checks. Its commit 995dbab9a1115c768249f467e37ebd6b8686d7ac contains exactly eight filename substitutions across five pages; normalized comparison proves every other character was unchanged at that boundary. The separate reconciliation commit f68927e94a31520c4db482aa8f2359cc999b80aa integrates only delivered main and preserves the lifecycle's artifact, setting, approval, recovery, discovery, and announcement contracts. Twenty-two focused checks verify that preservation and the reconciled publication-record rules.

The canonical filename-only candidate is #233 at e65b9e0125d418852a993282e2b4cd5125f16d3a, based on the same landed main. Read-only comparison confirms exact PR Format, Automation Labels, and VS Code design correspondence. Its 17 references differ from this lifecycle shape's eight because the spec/design structures are intentionally distinct; no unmerged source or tests were imported.

Remaining sequential-composition gate: read-only paired composition with #233 reports intentional conflicts in release spec/design. Its new example checks are tied to main's release-branches and minor-default examples, while this proposal retains its authored keyed ReleaseType and patch example. After whichever delivery lands first, reconcile the remaining branch against actual advanced main, preserve the applicable schema/record contract, and repeat exact-head checks and full review. Independent human review and explicit landing authorization remain separate; automatic landing is off.

Related references

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

[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}

[Copilot]

🟢 Approved

The documentation-only release-management updates have no active review issues.

No open issues 🎉

_{Review effort: Balanced}