Repository navigation
Solution settings use canonical filenames - #233
Merged
Merged
Conversation
There was a problem hiding this comment.
🟢 Approved
There are no active review issues blocking the documentation filename standardization.
No open issues 🎉
What changed in this PR
Standardizes the optional Release Management settings filename as .github/release.settings.yml across canonical guidance. This is a documentation change; released producers’ inputs and runtime loading behavior remain unchanged.
Changes:
- Updates 17 filename references across five documentation pages.
- Adds five filename checks and four semantic guards covering existing settings and release-decision requirements.
| File | Description |
|---|---|
tests/PR-Format.Tests.ps1 |
Adds canonical filename checks and guards for unchanged release semantics. |
src/docs/Ways-of-Working/PR-Format.md |
Updates settings references in PR authoring guidance. |
src/docs/Ways-of-Working/Automation-Labels.md |
Updates the optional settings path in release-label guidance. |
src/docs/Capabilities/vscode-extension-framework/design.md |
Updates configuration and template-layout references. |
src/docs/Capabilities/release-management/spec.md |
Updates settings references without changing applicability requirements. |
src/docs/Capabilities/release-management/design.md |
Updates settings paths in examples, precedence guidance, and configuration tables. |
Review effort: Balanced
This was referenced Nov 1, 2026
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
November 1, 2026 13:28
Marius Storhaug (MariusStorhaug)
marked this pull request as draft
November 1, 2026 21:49
Marius Storhaug (MariusStorhaug)
changed the title
Marius Storhaug (MariusStorhaug)
dismissed
Copilot’s stale review
via
November 1, 2026 22:01
f021418
16 tasks done
Marius Storhaug (MariusStorhaug)
dismissed
Copilot’s stale review
via
November 2, 2026 17:50
3d7c58e
Marius Storhaug (MariusStorhaug)
dismissed
Copilot’s stale review
via
November 2, 2026 18:06
8daf026
This was referenced Nov 2, 2026
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 2, 2026
Testing guidance prioritizes observable supported behavior, real implementations, and safe actual APIs instead of assertions that merely detect implementation edits. A fast credential-free local loop remains available; protected live checks carry explicit prerequisites, authorization, isolation, cleanup, and honest coverage evidence. The shared plugin adds a thin testing-skill pointer. This is a standards/plugin-source delivery, not a test-suite migration or consumer rollout: existing installations are unchanged, and the focused skill requires updating the shared `msx` plugin after this source is merged and available. <!-- ANNOUNCEMENT STOP --> ## New: A focused skill routes test work to the canonical policy `msx-coding-testing` routes test design, authoring, and review to the single [Testing standard](https://github.com/MSXOrg/docs/blob/main/src/docs/Coding-Standards/Testing.md). The skill copies no policy. Consumers can continue using their existing general coding route; to gain the focused trigger, update their shared `msx` plugin after the source is available. This PR does not install it for them. <details> <summary>Technical details</summary> The actual plugin and marketplace entry advance together from `0.1.1` to `0.1.2`. The independently managed marketplace metadata stays `0.1.0`. Existing plugin tests pass (4 tests, 49 skill directories), both changed plugin Markdown files lint cleanly, and the new pointer resolves when explicitly passed to the existing link tool (1 target in 1 file). | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `.github/plugin/msx/skills/msx-coding-testing/SKILL.md` | Documentation Model, Natural Language, Markdown | Agent Plugin Marketplaces design; sibling thin-skill pattern | Aligned | | `.github/plugin/msx/plugin.json` and `.github/plugin/marketplace.json` | Manifest identity and synchronized versions | Agent Plugin Marketplaces design; plugin README | Aligned | | `.github/plugin/README.md` | Documentation Model, Natural Language, Markdown | Agent Plugin Marketplaces design | Aligned | </details> ## Changed: Testing policy distinguishes functional evidence from edit detection Contributors and agents choose tests around supported functions, commands, and APIs without an arbitrary mocked-unit-test ratio or unnecessary remote calls for pure logic. Mocks and fakes are justified exceptions with explicit limits; a fake or an unexecuted live check does not prove that an external API works. A behavior-preserving refactor must not fail tests solely because implementation text changed. The engineering principle links to the owning policy instead of requiring a cloud-free full suite. Independent expected results, meaningful examined-unit counts, regression intent, linting, formatting, static analysis, link checks, builds, and temporary-fixture tooling checks remain valid. Production writes and unsafe, destructive, or paid calls gain no authorization from this standard. No runtime, CI, or existing-suite migration is included. <details> <summary>Technical details</summary> Scoped comparison: `MSXOrg/docs` base `aa9b5cecc69f4cbe6aa04a5dd70ff9cdadeeac3d` to immutable candidate `607cca0010fa08b9fee43c6f5b07c17c5a051253`, in two focused ordinary commits. The complete diff contains seven files; no tests, scripts, workflows, runtime dependencies, or settings-delivery changes are imported. The worktree is clean. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `src/docs/Coding-Standards/Testing.md` | Existing standard shape, Documentation Model, Natural Language, Markdown | None (no framework-specific docs) | Fixed in this PR | | `src/docs/Ways-of-Working/Principles/Engineering-Practices.md` | Documentation Model, Natural Language, Markdown | Owning Testing policy | Fixed in this PR | | `src/docs/Coding-Standards/index.md` | Generated index and recursive-navigation conventions | Repository README and contribution instructions | Aligned | Validation on the committed tree: - Existing Pester runner: 80 passed in 7 suites; zero failed, skipped, inconclusive, or unexecuted. - Markdown lint: all 5 changed Markdown files, zero issues. - Internal links: 127 documentation files scanned, all resolve. - Cross-repository links: 7 targets in 131 files, all resolve; the new skill pointer was checked separately as recorded above. - Generated index verification and diff whitespace checks pass. - Clean site build: repository-pinned Zensical `0.0.59`, restored in an isolated environment, no issues. The global `0.0.50` mismatch was detected and is not the pinned build evidence; no repository dependency or shared tool was changed. - Exact-head [Docs CI](https://github.com/MSXOrg/docs/actions/runs/41501467382): Test, Lint, Build, and Links passed; Publish skipped for the PR. Exact-head [cross-repository CI](https://github.com/MSXOrg/docs/actions/runs/41501467414) passed. - Exact-head [Copilot review](#235 (review)): approved at `2026-11-02T18:38:24Z`, covering all seven changed files. The explicit review loop returned clean with zero new comments; complete review-thread pagination returned no threads. The scoped Task records baseline/scenario reasoning, both commits, local checks, CI/review evidence, and completed standards/convergence review. Every implementation-plan item is complete; the Task remains open for its normal reviewed-merge completion path. Targeted open issue/PR searches for testing, mocks, and functional tests found no additional fully convergent issue; the settings and release deliveries remain separate. No policy-wording or structural-content tests were added, and no existing suites were changed or deleted. Native Agent merge was verified before enabling and read back afterward: `enabled=true`, `address_reviews=true`, `fix_ci=true`, `resolve_conflicts=true`, `merge_pr=false`. This is maintenance-only authorization. The PR remains draft by request with GitHub auto-merge unset; advancing readiness and any later merge require the appropriate user/owner decision. No merge, enqueue, service publication, permission/rule/label change, or consumer rollout was performed or authorized. No protected live-API experiment campaign was run or claimed. The inspected Docs route only publishes Pages on non-PR events and does not invoke Release Management; no release-decision block or labels are applied. </details> <details> <summary>Related references</summary> - Resolves #234 - References #233 (separate settings delivery; unchanged) </details>
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
November 2, 2026 19:52
Marius Storhaug (MariusStorhaug)
deleted the
release-settings-filename
branch
November 2, 2026 19:59
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 3, 2026
Release guidance maps configured branches through `ReleaseType.Stable`,
`ReleaseType.Prerelease`, and `ReleaseType.ReleaseCandidate`. The stable
route defaults to the repository default branch; the other routes are
optional. Each branch has one effective routing assignment.
This changes documentation, not a released producer, settings loader,
caller input, branch configuration, or publication. Authors implementing
the canonical protocol use the keyed shape below. Existing consumers
keep their producer's declared interface until a compatible
implementation and its exact adoption instructions are released.
<!-- ANNOUNCEMENT STOP -->
## Changed: Release branches are keyed by the type they publish
The guidance replaces the `release-branches` list example with one
`ReleaseType` object whose only supported keys are `Stable`,
`Prerelease`, and `ReleaseCandidate`. Each key has at most one `Branch`.
Unknown keys fail. Branch-assignment validation resolves inherited
defaults first and then rejects any branch assigned to several routing
types, whether the assignments are explicit or inherited.
`Stable.Branch` is the only stable-production authority. An omitted
stable route inherits the repository default branch, and that assignment
still participates in duplicate validation: an explicit prerelease or
candidate assignment to the same branch is invalid. A configured
candidate route publishes its own `-rc.N` series without stable
publication or promotion to latest. `Prerelease` and `ReleaseCandidate`
are routing types that both publish prereleases, not a third
semantic-version mode or another owned release label. The VS Code
framework points to the same shared routing contract.
```yaml
# .github/release.settings.yml
DefaultBump: patch
ReleaseType:
Stable:
Branch: main
Prerelease:
Branch: dev
ReleaseCandidate:
Branch: rc
```
The existing effective-default contract remains: `DefaultBump` accepts
`patch`, `minor`, or `major`; the shared default is `patch`; repository
settings and explicitly supplied supported caller overrides refine it;
one owned bump label overrides the valid effective default. Invalid
supplied values and conflicting owned signals fail rather than fall
back. Skip alone validates without publication, and prerelease mode uses
the resolved explicit or default bump.
The canonical `.github/release.settings.yml` filename and its
naming/input boundaries are already on main. This remaining diff does
not rename another file or grant an older producer support for a
different path. `ConfigurationFile`, supported explicit custom paths,
the `.github/PSModule.yml` / `SettingsPath` exception, and the existing
`.github/vscode-extension.yml` template interface remain governed by
their owning producer or solution. No executable consumer migration is
performed here.
<details>
<summary>Technical details</summary>
**Current source:** `3f48c8b391d8af9952b9d4e851e8c56afd36b03b` on
`default-release-bump`, compared with actual main
`9453587dbf34e888d057848a867c48778c62b4e7`. The remaining delivery
contains four documentation pages, with 72 insertions and 51 deletions.
The branch includes that main source and has no unresolved conflicts.
Earlier `ce9ca513`, `105d53f`, `d9d35ab`, and `99fd558` records are
historical, not final-head review evidence.
| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| Release Management design | Documentation Model, Natural Language,
Markdown | Effective defaults, keyed routing, inherited validation,
stable authority | Aligned |
| Release Management spec | Specification/design separation, Natural
Language, Markdown | Closed routing-key contract, applicability, owned
decisions, required validation | Aligned |
| Release Management index | Documentation Model, generated navigation |
Current spec/design descriptions | Aligned |
| VS Code framework design | Documentation Model, Natural Language,
Markdown | Shared release resolver and configuration surface | Aligned |
| User-directed test-policy fix | Testing, PowerShell test discovery |
Functional validation versus prose-edit assertions | Fixed in this PR |
**Test-policy correction:** `d9d35ab` removes only the added
`ReleaseSettingsDocumentation.Tests.ps1` suite. Its five cases searched
documentation strings rather than executing a supported runtime
interface, contrary to the functional-testing policy now on main. All
functional suites, assertions, required checks, linters, link
validation, and build configuration are unchanged and match the accepted
base. No replacement phrase, heading, or source-shape guard is added.
**Concrete review corrections:** the complete review
[5743140913](#196 (review))
on `d9d35ab` identified inherited stable-assignment and
candidate-publication ambiguities. `99fd558` corrected both, with
fix-linked resolved replies for [inherited stable
validation](#196 (comment))
and [candidate publication
mode](#196 (comment)).
The complete review
[5743210606](#196 (review))
confirmed those fixes and requested the existing fixed-key/inheritance
guarantees in the normative spec. `3f48c8b` adds those guarantees and
has a [fix-linked resolved
reply](#196 (comment)).
These clarify the existing intended routing constraints; they do not
implement a reader or change the settings/input/runtime scope.
**Final-head validation:** all five required contexts succeed on
`3f48c8b391d8af9952b9d4e851e8c56afd36b03b`: [Lint, Build, Test, and
Links](https://github.com/MSXOrg/docs/actions/runs/41524011349), plus
[Cross-repository
links](https://github.com/MSXOrg/docs/actions/runs/41524011453). The run
identity was verified as a pull-request run for this exact source. Its
[Ubuntu Test
job](https://github.com/MSXOrg/docs/actions/runs/41524011349/job/125546962864)
passes all 64 functional tests in six suites using pinned Pester 6.0.1,
with none skipped. The site build and Markdown/static checks pass; the
PR-only Publish job is skipped as intended. Local functional suites,
Markdown lint, patch checks, relative links across 127 pages, and all
seven cross-repository links also pass. No older green run is counted
for this head.
**Final complete review disposition:** the explicitly requested round
[5743289293](#196 (review))
is COMMENTED on `3f48c8b391d8af9952b9d4e851e8c56afd36b03b`, with no new
inline comments, no requested changes, and no open issues. Its complete
summary was read, not reduced to the script's successful exit code: it
still says **Needs a closer look** and asks for human verification
because this normative cross-document routing proposal has no compatible
producer, executable resolver, or consumer migration delivered with it.
That is the intentionally retained documentation-only boundary, not
runtime validation or an approving review. The keyed/inherited-default
runtime behavior remains unexecuted coverage. A complete paginated
thread read-back confirms no unresolved threads. An independent reviewer
must assess and accept the contract; the last-push approval gate remains
unsatisfied and is not self-granted or bypassed.
**Preserved canonical composition and holds:** landed #209
supplied the complete PR-record, release-range-first,
sufficient-upgrade-history, and no-PR-template-file contracts. Landed
#233 supplied the single settings-name convention, supported
custom-path boundary, and PSModule/VS Code exceptions. This branch
retains those accepted sources while keeping its keyed-route proposal.
No unmerged producer or documentation delivery is copied into the
branch. Native prerequisite #166 is closed; #208
remains a separate overlapping delivery. If main advances again,
reconcile the surviving branch against the actual landed source and
repeat exact-head validation/review before readiness.
The older review
[5723060562](#196 (review))
also retained a generic human-assessment caution about default/skip
paths. Nineteen anonymous written-contract cases were checked on that
older source, not a runtime resolver; the decision table and ordering
survived the reconciliations. That caution is not an approval or a
governance waiver. The later Windows-path allegation in review
[5728271684](#196 (review))
was disproven by its exact-head Ubuntu run and received an
[evidence-linked resolved
reply](#196 (comment)).
The now-removed prose suite and older reviews do not establish
final-head runtime coverage.
**Task plan and convergence:** the original default/override, label,
framework, and conflict-reconciliation steps in #225 are
complete. The user-directed author-side readiness revision is complete:
prose-only assertions removed, functional validation retained,
current-source PR record refreshed, concrete review findings corrected,
and final-head CI/full automated review disposition recorded.
Independent contract assessment and last-push approval remain external
gates, not completed author work. The scoped convergence sweep covered
release/default/filename issues: only #225 is closed by this
delivery. #232 is the separate canonical filename Task;
#203 remains the broader consumer-upgrade procedure/gate
work. No additional closing links, producer migration, date-based
versioning, or historical/fleet cleanup are included.
This repository's target route builds and deploys an unversioned
documentation site. It does not publish a versioned immutable consumer
artifact, so no artifact-publication baseline is invented and no
`Release decisions` block or `release:*` label applies. The scoped
main-to-candidate comparison above is implementation/reviewer evidence,
not a fabricated release range.
Existing human/source/lineage/prerequisite holds are not waived. Agent
merge remains maintenance-only with `merge_pr=false`, and GitHub
auto-merge remains off. The PR target and existing draft state are
unchanged. This fix authorizes no merge, enqueue, publication, package,
live producer, label, pin, or governance mutation.
</details>
<details>
<summary>Related references</summary>
- Resolves [#225](#225)
- References [#209](#209)
- References [#233](#233)
- References [#208](#208)
- References
[#166](#166)
</details>
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Nov 3, 2026
…rds (#208) Release guidance defines durable intent, phase-aware recovery, complete source-bound consumer records, and settings-driven decisions. It preserves the accepted keyed release routing, `.github/release.settings.yml` convention, solution-specific path exceptions, and release-range-first PR records while defining the lifecycle contract. 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. <!-- ANNOUNCEMENT STOP --> ## 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. <details> <summary>Technical details</summary> | 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. The accepted-main reconciliation leaves that operating procedure intact. </details> ## 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. <details> <summary>Technical details</summary> | 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:** `a37884419c6c5ec4da56222be27238ee192b4cd1`. **Scoped implementation base:** accepted main `bdb581f68fddd84bc129394a94388671d1d14356`, containing delivered #209, #235, #233, and #196. The complete base-to-head comparison contains eight existing lifecycle, target, guide, and navigation files. Current canonical format, naming, testing, solution-specific exceptions, repository policy, CI configuration, and VS Code framework guidance match accepted main without an additional PR 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 of the composed candidate passes all **64 functional/tooling Pester tests in six suites**, normal index regeneration, relative links across 128 pages, seven cross-repository links, exact-file Markdown lint across eight relevant pages, patch checks, and a clean build with manifest-pinned Zensical **0.0.59**. The unavailable pinned build version was restored only in an isolated temporary environment, which was removed afterward. No dependency manifest was changed. The accepted testing policy is preserved; no prose-drift tests were added or restored. The inherited-routing scenario documents the requirement but does not claim an implemented resolver test. **New-head required CI was running at handoff:** [Lint](https://github.com/MSXOrg/docs/actions/runs/41675815774/job/126055996866), [Links](https://github.com/MSXOrg/docs/actions/runs/41675815774/job/126055996479), [Test](https://github.com/MSXOrg/docs/actions/runs/41675815774/job/126055996962), [Build](https://github.com/MSXOrg/docs/actions/runs/41675815774/job/126055996918), and [Cross-repository links](https://github.com/MSXOrg/docs/actions/runs/41675815839/job/126055998868). All five checks identify `a37884419c6c5ec4da56222be27238ee192b4cd1`. Earlier green checks are not represented as a result for this new head; current status is shown by the PR checks. The previous full automated review [5728246486](#208 (review)) approved `f68927e94a31520c4db482aa8f2359cc999b80aa` with no active concerns. It is an earlier checkpoint, not a review of this candidate. This tick began with all review threads resolved and no changes-requested review, but with approval blocked. No reviewer was requested or approval manufactured during conflict maintenance. The exact resolution review preserves lifecycle authority, reservations, immutable artifact recovery, source-bound records, and consumer policy while integrating the accepted keyed-routing rules. The closing Task's original implementation-plan evidence remains in the prior delivery history. This maintenance resolves the accepted-main composition gate and leaves new-head required CI and GitHub's remaining approval/protection requirements as acceptance gates. Producer implementation, consumer execution, date strategies, historical correction, and live governance remain outside this Task. No PR merge, merge enqueue, retarget, release, or artifact promotion was performed; automatic landing remains off. </details> <details> <summary>Related references</summary> - Resolves [#227](#227) - References [#166](#166) - References [#209](#209) </details> ## Changed: Keyed routing and settings retain their accepted boundaries The lifecycle retains `ReleaseType.Stable`, `ReleaseType.Prerelease`, and `ReleaseType.ReleaseCandidate`, each with at most one branch. The stable route inherits the default branch when the routing object or stable key is omitted. Validate the effective mapping after inheritance: unknown keys and duplicate branch assignments fail, including a candidate or prerelease route assigned to the inherited stable branch. Prerelease and release-candidate routes publish only their assigned prerelease series, not stable releases or stable discovery/aliases. Configured branches retain their push-driven series, and open PRs retain `release:prerelease` using one explicit owned bump label or the valid effective `DefaultBump`. Candidate versions retain `rc` and increasing counters; promotion to stable uses the stable version resolver without carrying either prerelease counter over. An unreviewed direct push to the stable line still validates without publishing. The release solution's optional path remains `.github/release.settings.yml` under the accepted Naming standard. The convention does not implement a reader, rename a public input, require a shared directory, or restrict otherwise supported explicit custom paths. Verify the immutable producer revision's declared settings input and default before adoption. `ConfigurationFile`, where exposed, remains that producer's settings-path input. PSModule retains `.github/PSModule.yml` through `SettingsPath`, including module release settings; module repositories do not need a separate release-solution settings file. The VS Code template retains `.github/vscode-extension.yml` and its settings keys. Both owning exceptions are preserved from accepted main. This documentation does not authorize a reader, template, or live-caller migration, and creates no legacy fallback. `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. Skip and out-of-scope work validate without publication. 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. Candidate and announcement behavior uses supported settings rather than extra labels. A route without versioned release behavior carries neither release metadata nor any release label. Authors retain the finalized PR record, release-range-first procedure, complete source-bound notes, and scoped supporting evidence already delivered on main. The 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. Existing runtime consumers do not rename live files or install software because this guidance changed. Producer support and any required adoption actions must be verified and delivered by the relevant implementation owner. <details> <summary>Technical details</summary> | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Lifecycle routing requirements and design | Specification/design separation, Natural Language, Markdown | Accepted fixed routing keys, inherited defaults, branch collisions, prerelease sources and stable-only authority | Aligned | | Lifecycle settings and configuration sections | Natural Language, Markdown, Naming | Optional release-solution file, verified reader/input boundary, unchanged defaults and typed overrides | Aligned | | Accepted-base composition | Current PR Format, Testing, Repository Standard | Release-range-first records, no-template ownership, preserved PSModule and VS Code exceptions | Aligned | Conflict maintenance merges only accepted main `bdb581f68fddd84bc129394a94388671d1d14356` into the existing branch. It resolves conflicts in release spec/design/index without importing an unmerged delivery or restoring the older `release-branches` schema. The lifecycle's artifact, aggregate-approval, recovery, discovery, announcement, version-reservation, settings-precedence, and optional-file contracts remain intact. Accepted keyed-routing requirements are expressed within the existing numbered specification and design; the inherited-default collision scenario makes the effective-mapping rule explicit. Shared canonical pages and the VS Code framework match accepted main exactly. The #233 and #196 sequential-composition gates are resolved against their delivered merges, not their superseded development candidates. No other branch, historical record, live label, consumer pin, governance setting, or producer runtime was changed. New-head CI and remaining GitHub acceptance gates are still required; Agent merge maintenance does not authorize automatic landing. </details> <details> <summary>Related references</summary> - References [#196](#196) - References [#233](#233) - References [#235](#235) </details> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Solution-owned settings use the conventional filename
<name>.settings.yml. The release solution uses.github/release.settings.yml; module repositories retain.github/PSModule.ymlthroughSettingsPath, including module release settings.The documentation-content test file and CI documentation-index drift gate are removed. Functional tooling tests, linting, link validation, and site builds remain; no module migration or runtime loader is implemented here.
Removed: Tests that lock documentation content
tests/PR-Format.Tests.ps1is deleted in full at the user's request, including its PR-format, filename, naming, and repository-policy assertions. No replacement tests of checked-in documentation or workflow content are added. The Naming standard no longer claims test coverage for its prose.The follow-up audit covers all six remaining suites and both workflows. The remaining suites exercise scripts on temporary fixtures, PowerShell engine behavior, and plugin metadata/schema validity. They do not lock the actual documentation's wording or assert the actual workflows' contents. The user explicitly chose to retain these functional tool tests, together with linting, link validation, and site builds.
Technical details
The entire 329-line documentation suite is absent, including all 39 assertions it contained. Historical audit comments and earlier test totals describe preceding iterations, not tests present in this candidate. No replacement prose or workflow-content tests were introduced.
The complete scoped comparison is accepted main
aa9b5cecc69f4cbe6aa04a5dd70ff9cdadeeac3dto candidate8daf026a14036dee04786d371883e8871b5ec2f4. The latest bounded change removes drift enforcement without changing any test suite or index-generator logic.tests/PR-Format.Tests.ps1(deleted)All 64 tests in the six retained functional suites pass on the current head, verified from the completed CI job. The six index-tool fixture cases also pass locally; these exercise optional diagnostics, regeneration, and line endings on temporary files, not drift in this repository's actual docs. No suite is rewritten to inspect the checked-in documentation or workflows.
The fresh exact-head review approves
8daf026a14036dee04786d371883e8871b5ec2f4with zero new inline comments. All five required checks pass: Lint, Build, Links, Test, and Cross-repository links. The earlier consistency thread remains resolved. Publishing is intentionally skipped for this PR.Related references
New: Solution-owned settings filenames identify their owner
Use the owning solution's name for its conventional settings filename. The Naming standard defines this once; repository, YAML, and release guidance link to it. The rule does not rename tool-mandated manifests, lockfiles, workflow filenames, or arbitrary YAML files, and it does not impose one directory on every solution. Supported explicit custom paths remain governed by each reader's existing input contract.
Module repositories keep
.github/PSModule.ymlthroughSettingsPath, including module release settings. The PSModule initiative records this supported exception and links to the framework's actual input and settings references. No module filename migration, second release settings file, or caller-input change is required here.The VS Code framework design retains
.github/vscode-extension.ymlas an explicit supported naming exception. Its settings keys and interface are unchanged; a filename change requires a verified reader and separate template/caller migration.Technical details
src/docs/Coding-Standards/Naming.mdsrc/docs/Coding-Standards/YAML.mdsrc/docs/Ways-of-Working/Repository-Standard.mdsrc/docs/Initiatives/PSModule.mdNaming.md#solution-settings-filesowns the rule;PSModule.md#module-settingsand the VS Code configuration surface own the supported exceptions. Related guidance links to those owners rather than defining another rule. The directly related obsolete framework overview link is corrected to its actual canonical site route.The module default was verified from Process-PSModule source
105e4dcefe1946782066aa50a5c7d3658319895aand the published workflow-input reference. The settings reference owns module keys and defaults. Neither the workflow, its input, schema, nor enriched runtime settings object changes here.The earlier VS Code consistency finding remains addressed by its owning-guide exception, independently of the deleted assertion. The scoped issue-convergence search finds no additional complete ask satisfied by this naming slice; broader default-bump/keyed-route and lifecycle work stays separate.
Changed: Release settings use the release solution's canonical filename
The optional release-solution file is
.github/release.settings.yml, replacing the documentedrelease.config.ymlconvention. Its.githublocation, settings keys, schema, defaults, precedence, omission behavior, applicability, and required decision validation are unchanged. All 17 original current-guidance substitutions remain. This repository has no settings file or runtime loader to rename.The former
.github/auto-release.ymlis migration evidence for the separately owned Release-GHRepository reader change, not a current alternative convention.ConfigurationFileremains the public input, distinct from its conventional default filename. This documentation PR does not deliver or release that reader. Consumers verify their producer revision and its migration record before adopting a changed default; module release settings remain under the supportedPSModule.ymlinterface.Technical details
The accepted release-range-first analysis, complete description example with one summary boundary, conditional release/default rules, Task/Bug planning, and repository-owned no-PR-template policy are preserved without tests of their prose. Runtime default/migration work belongs to PSModule/Release-GHRepository#109, not this source. No module file, loader, public input, Build/metadata/runtime schema, publisher, pin, permission, ruleset, marketplace, or consumer fleet change is included.
Related references
Changed: Documentation builds regenerate indexes without a drift gate
CI generates documentation indexes before building the site instead of rejecting an out-of-date generated table. A documentation edit no longer needs to satisfy an index-drift gate. The generator updates only the build checkout; this change adds no bot commit or source synchronization.
Optional local
-Checkdiagnostics and functional tests of the generator remain available. Linting, link validation, and site builds still run. The contribution guide and script help describe this distinction; no tests inspect the actual workflow to enforce its contents.Technical details
.github/workflows/Docs.yml.github/scripts/Update-DocumentationIndex.ps1(help only).github/CONTRIBUTING.mdThe index step runs normal generation with no
-Checkflag. The index-generator implementation and all functional test suites are unchanged. The local generation-then-build path succeeds with repository-pinned Zensical 0.0.59; the changed contribution guidance is lint-clean and the scoped diff has no whitespace errors. The exact-head CI Build job also successfully executesGenerate documentation indexesfollowed by the site build. Temporary build environments and output are cleaned without changing shared dependencies.The Task records the audit, the user's selected boundary, and the completed verification. Its implementation and review gates are complete; the Task remains open for reviewed integration. This PR remains draft; native maintenance has
merge_pr=false, GitHub auto-merge is off, and no live publication or merge is authorized. A later main change requires a refreshed comparison and exact-head validation.