Repository navigation
Standardize solution-owned settings filenames #232
Description
Context and request
Contributors and agents need one discoverable convention for solution-owned settings filenames: <name>.settings.yml, where <name> identifies the owning solution. The release solution uses .github/release.settings.yml. This extends the existing MSXOrg/docs#233 delivery rather than creating another naming standard or delivery issue.
The initial 17-reference release filename revision is committed at e65b9e0125d418852a993282e2b4cd5125f16d3a, based on accepted main aa9b5cecc69f4cbe6aa04a5dd70ff9cdadeeac3d. The confirmed extension establishes the common convention and its supported compatibility boundaries.
Acceptance criteria
-
One existing owning naming standard defines the canonical conventional filename for solution-owned settings. Repository, YAML, and release guidance link to that rule rather than restating it.
-
The rule does not rename tool-mandated manifests, lockfiles, workflow filenames, or arbitrary YAML files, and does not force a common directory for all solutions. The existing release convention keeps its
.githublocation. -
Supported explicit custom paths remain controlled by each reader's existing input contract; the convention does not become a blanket runtime path restriction.
-
Module repositories continue using
.github/PSModule.ymlthroughSettingsPath, including module release settings. This supported exception is documented with the PSModule initiative and linked from applicable guidance. No module settings migration or second settings file is required by this delivery. -
The release solution's canonical filename is
.github/release.settings.yml. Older conventional filenames appear only as migration/historical evidence, not current alternative authoring guidance. -
ConfigurationFileremains the existing Release-GHRepository input. Its separate conventional-default/migration revision in PSModule/Release-GHRepository#109 is not claimed as implemented or released by this documentation PR. -
Settings keys, schemas, shared defaults, precedence, omission behavior, applicability, required release-decision checks, caller controls, and the accepted PR-record/release-range/no-template contracts remain unchanged.
-
Remove the entire
tests/PR-Format.Tests.ps1file, including its PR-format, filename, naming, and repository-policy documentation assertions. Do not replace it with tests of documentation prose. Review the guidance and use the existing formatting, index, link, and site tooling instead. -
Existing tests of automation scripts, plugin metadata, and PowerShell behavior remain unchanged and pass. The PR stays scoped to the canonical documentation and the requested documentation-test removal. Native Agent merge remains maintenance-only; merging and GitHub auto-merge remain disabled.
-
Generated documentation-index drift MUST NOT block CI. The site build generates indexes in its checkout instead of invoking the stale-index verification gate. Functional tooling tests, linting, link validation, and site builds remain.
Technical decisions
-
src/docs/Coding-Standards/Naming.mdowns the convention in one solution-settings subsection.src/docs/Coding-Standards/YAML.mdandsrc/docs/Ways-of-Working/Repository-Standard.mdprovide discoverable links instead of duplicate rules. -
src/docs/Initiatives/PSModule.mdowns the initiative's supported naming exception and links to the actual Process-PSModule workflow-input/settings references. Released workflow source105e4dcefe1946782066aa50a5c7d3658319895aand the published workflow-input reference confirmSettingsPathdefaults to.github/PSModule.yml. -
Release Management design links the naming rule and module exception, and distinguishes the public settings-path input from a conventional filename. The release specification describes the release solution's path without implying all native producers or module repositories adopt it.
-
Delete
tests/PR-Format.Tests.ps1in full at the user's direction. Remove the dependent Naming sentence claiming documentation-contract test coverage. Preserve tests of the tooling itself, existing format/link/index/site validation, and all canonical settings/compatibility decisions; add no replacement documentation-content tests. -
No real
release.config.ymlorrelease.settings.ymlexists in this repository. No loader, module file, caller input, Build/metadata/runtime schema, publisher, label, pin, permission, ruleset, marketplace, consumer fleet, or historical record changes here. -
The separate Release-GHRepository owner verified its conventional runtime path is
.github/auto-release.yml, not arelease.config.ymlloader. Its pending revision changes the declared default and removed-conventional-path diagnostic to.github/release.settings.ymlwithout fallback, while preserving independent explicit custom paths, typed overrides, keys/precedence, and exports. This PR documents the target convention, not delivery of that reader. -
Keep exact module migration actions in separate future module work and exact released-reader migration actions in its own PR/release record. Canonical resource docs state the supported rule and exception, not a rollout timeline.
-
After pushing the new immutable naming source, coordinate it with the independent MSXOrg/docs#196, MSXOrg/docs#208, and Release-GHRepository owners. Do not import their unmerged scope or assume automatic composition.
-
The user selected removal of documentation drift enforcement while keeping functional tool tests. Replace the Docs build job's
Update-DocumentationIndex.ps1 -Checkstep with ordinary generation; retain optional manual-Checkdiagnostics and fixture-based tests of that script. Update contribution guidance and script help so neither claims CI enforces index freshness.
Implementation plan
- Delete the entire PR-format documentation test file and its dependent coverage claim, without adding replacement tests of documentation content.
- Establish the solution-settings naming rule once, wire its discovery links, and document the supported module exception without changing interfaces or settings semantics.
- Verify the release filename and producer/migration boundary, remove permanent old-path implications from the current Task/PR record, and preserve the original 17 substitutions and accepted contracts.
- Run the remaining existing Pester suites and relevant format/index/link/site checks; review the requested deletion and complete exact-head diff without documentation-content assertions.
- Reproduce and correct the VS Code guide's missing naming exception, preserving its documented vscode-extension.yml interface and keys without an unrequested file/reader/template migration.
- Push small ordinary commits, complete exact-head CI and the automated review round, and verify native maintenance-only Agent merge and disabled GitHub auto-merge.
- Publish the revised existing PR and hand off its actual immutable source, the user-directed documentation-test removal, and pending runtime/module-migration boundaries.
Documentation drift enforcement removal
- Replace the CI documentation-index freshness gate with build-time index generation; update directly related contribution and script-help guidance.
- Validate the retained functional tooling and site build, push the bounded change, and complete exact-head CI/review without adding tests of actual docs or workflow content.
- Publish the revised existing PR and report the removed enforcement plus retained functional-test/lint/link/build boundary.
Activity
MariusStorhaug commentedon Nov 1, 2026
Test-first evidence on main aa9b5ce: pinned Pester 6.0.1 ran 25 checks. All five new canonical-filename cases failed as intended; all 16 existing PR-record/repository-policy checks and four new unchanged-semantics checks passed. PSScriptAnalyzer reported no diagnostics. No documentation has changed yet.
MariusStorhaug commentedon Nov 1, 2026
All 17 canonical filename references are revised across the five owning pages. A baseline comparison proves each page equals main aa9b5ce with only release.config.yml replaced by release.settings.yml; every other setting, rule, and documentation shape is unchanged. The 25 focused checks now pass. Documentation indexes are current and relative links resolve across 127 pages. There is no real settings file or runtime loader to rename.
MariusStorhaug commentedon Nov 1, 2026
Draft MSXOrg/docs#233 is open at immutable head e65b9e0 with two ordinary commits. Native Agent merge is enabled only for address_reviews, fix_ci, and resolve_conflicts; merge_pr is false. REST read-back confirms draft=true, merged=false, and auto_merge=null. The complete Pester suite passes 89 tests, and the isolated repository-pinned Zensical 0.0.59 build succeeds. The automated review round is requested and running.
MariusStorhaug commentedon Nov 1, 2026
Exact-head validation is complete at e65b9e0 against unchanged current main aa9b5ce. All 89 local Pester tests, index/link/lint checks, and the pinned Zensical site build pass; the generated five HTML pages contain the same 17 requested references. All five required CI checks pass, and the exact-head automated review approves with zero comments. Both existing owners verified correspondence without importing this unmerged candidate: MSXOrg/docs#196 at ce9ca51 and MSXOrg/docs#208 at f68927e. Their retained default-bump/keyed-route and lifecycle schema/examples require sequential post-landing reconciliation, not automatic composition or restoration of older accepted content. No broader Task converges with this filename-only diff. Draft and merge-disabled holds remain.
MariusStorhaug commentedon Nov 1, 2026
The four new unchanged-semantics guards were also proven against isolated copies of the reviewed source and existing Pester suite: changing a release schema key, changing the shared patch default, making file absence opt a managed route out, and weakening required merge enforcement each produced exactly one intended assertion failure. Each baseline passed once and each restored fixture passed once. No reviewed source was modified, and all temporary fixtures, build output, and the isolated build environment were removed. Immutable head e65b9e0 remains clean and unchanged.
MariusStorhaug commentedon Nov 1, 2026
The verified Task and draft PR were published in the session and handed to the Project coordinator with immutable head e65b9e0, exact five-page correspondence, and remaining integration gates. All implementation-plan steps are complete. This Task remains open until human-reviewed integration; the PR remains draft, native maintenance remains non-merging, and GitHub auto-merge is disabled.
[-]Use release.settings.yml for canonical release settings[/-][+]Standardize solution-owned settings filenames[/+]MariusStorhaug commentedon Nov 1, 2026
The user extends this delivery from the release filename alone to the canonical solution-owned settings convention. Naming owns the single rule; YAML/repository/release docs link to it. The PSModule initiative records the supported PSModule.yml/SettingsPath exception, including module release settings, without a module migration. Release-GHRepository#109 separately changes its conventional default from auto-release.yml; ConfigurationFile and supported explicit custom paths are preserved. The existing PR is returned to draft while the new test-first scope is implemented. No runtime or blanket custom-path restriction is introduced here.
MariusStorhaug commentedon Nov 1, 2026
Regression-first proof for the confirmed extension: pinned Pester 6.0.1 ran 38 checks on unchanged documentation. All 13 new naming/discovery/tool-exclusion/location/custom-path/module-compatibility cases failed on the missing guidance; all 25 earlier filename, semantic, PR-record, and repository-policy cases passed. The new checks are formatter-clean and pass PSScriptAnalyzer. No documentation has been edited yet.
MariusStorhaug commentedon Nov 1, 2026
The owning Naming rule and its four linked guidance surfaces are implemented. The PSModule initiative records PSModule.yml/SettingsPath as the supported module settings default, including release settings, without a new module file or migration. Release guidance separates a conventional filename from reader implementation/public inputs and preserves supported explicit custom paths. All 38 focused checks pass; changed Markdown lint is clean, indexes are current, and checkout links resolve across 127 pages. The current Task/PR record now treats auto-release.yml only as the separate producer-migration source, not a permanent alternative convention.
MariusStorhaug commentedon Nov 1, 2026
Extended source f021418 passes all 102 tests in seven existing Pester suites, all 38 focused contract checks, Markdown/PowerShell lint, documentation index and relative/cross-repository links, and a Zensical 0.0.59 site build. The rendered site contains the single naming rule and unchanged module-default/release-settings exception. Nine isolated deliberate regressions were rejected and restored, including a duplicate rule owner, broken discovery link, unrequested shared directory, blanket custom-path restriction, forced module filename/second release file, and a false implemented-reader claim. The parameterized-link experiment was corrected to select all four cases and then verified one intended failure; no check over an empty selection was counted as a pass. The complete ten-file diff is reviewed against unchanged accepted main aa9b5ce.
MariusStorhaug commentedon Nov 1, 2026
Exact-head review found one consistency gap: the existing VS Code framework design prescribes vscode-extension.yml but did not record its naming exception. The bounded correction documents that interface in its owning guide and adds a regression case; it does not rename a file, change keys, or claim an implemented reader. All five required CI checks passed at f021418, but the extended delivery remains draft until the corrected head completes its own review.
MariusStorhaug commentedon Nov 1, 2026
The corrected candidate is 7341454. The new VS Code exception guard fails once on the missing owning-guide paragraph and passes after the correction; all 39 focused checks and all 103 Pester tests pass. The existing vscode-extension.yml interface and keys are retained, with a verified reader/template/caller migration required for any separate rename. Markdown/PowerShell lint, indexes, relative links, and the pinned site build pass. The original inline thread is replied to and resolved. The corrected head still requires its own final CI/review before handoff; f021418 and e65b9e0 are not the final source.
MariusStorhaug commentedon Nov 1, 2026
Final corrected source 7341454 passes all five live required CI checks and a clean exact-head automated review, with the original inline finding replied to and resolved and no new comments. All 103 local Pester tests, 39 focused contract checks, documentation/link/lint gates, and the pinned site build pass. The common Naming rule is defined once; PSModule.yml/SettingsPath and the documented VS Code template interface are supported owning-guide exceptions, not forced migrations. The separate Release-GHRepository#109 candidate remains 03e20b8293dd8dfb41bead3255930a5edbb2e9bb, draft and unmerged. Native maintenance is enabled with merge_pr=false; GitHub auto-merge is off, and this Task/PR remain unmerged under the human integration hold.
MariusStorhaug commentedon Nov 1, 2026
The materially revised draft and Task were published at immutable source 7341454. The naming rule, module compatibility boundary, retained VS Code interface exception, exact input/default boundary, and pending producer status were sent to the #196, #208, and Release-GHRepository#109 owners; the Project coordinator received the final handoff. All implementation-plan steps are complete. Native Task #232 stays open until reviewed integration, and the PR stays draft with native merge_pr=false and GitHub auto-merge disabled. No module migration, runtime change, merge, or live publication is part of this delivery.
MariusStorhaug commentedon Nov 1, 2026
PSModule/Release-GHRepository#109 verified the final Naming, module-settings, and release-guidance correspondence and updated its PR/Task references to documentation source 7341454. Live read-back confirms that immutable reference in its PR record and unchanged reader source 03e20b8293dd8dfb41bead3255930a5edbb2e9bb. The producer remains a development candidate; this correspondence does not import documentation code, expand custom-path restrictions, migrate PSModule.yml/SettingsPath, override readiness, or authorize production adoption. No source change or new validation run is required in this documentation delivery.
MariusStorhaug commentedon Nov 2, 2026
The user requests removal of the entire PR-format test file and no tests of documentation content. The current plan now deletes that suite, including the naming/settings and repository-policy assertions added during this delivery, and removes its dependent coverage claim. Existing tests of scripts, plugin metadata, and PowerShell behavior remain; no replacement prose assertions or new testing policy are introduced. Canonical filename, module compatibility, and merge-disabled boundaries are unchanged.
MariusStorhaug commentedon Nov 2, 2026
The entire 329-line tests/PR-Format.Tests.ps1 file is removed, including all 39 documentation-content and policy assertions. The Naming standard no longer claims test coverage for its prose. No replacement documentation tests were added. All 64 tests in the six retained tooling/runtime suites pass; documentation indexes, relative links across 127 pages, and the changed Markdown lint pass. The canonical settings naming and supported PSModule/VS Code interfaces are unchanged.
MariusStorhaug commentedon Nov 2, 2026
The user-directed deletion is committed and pushed at 3d7c58e. All 64 tests in the six retained tooling/runtime suites pass; all five exact-head required CI checks, including the site build, pass. The fresh automated review approves with zero new inline comments, and the previous review thread remains resolved. The entire PR-format test file is absent, its Naming coverage claim is removed, and no documentation-content tests replace it. The PR remains draft with GitHub auto-merge off and native merge_pr=false.
MariusStorhaug commentedon Nov 2, 2026
Audit of all six remaining suites found no other fixed-prose assertions against the live documentation and no assertions locking the real workflows. CI still invoked Update-DocumentationIndex -Check as a generated-documentation drift gate. The user selected removal of that enforcement while retaining functional tool tests, linting, link validation, and site builds. CI will generate indexes for the build instead; optional manual diagnostics and temporary-fixture tests remain. Plugin tests validate SKILL.md front matter and manifest structure, not prose snapshots, and remain within the retained tooling boundary.
MariusStorhaug commentedon Nov 2, 2026
Docs CI now runs normal Update-DocumentationIndex generation before the site build instead of its -Check freshness gate. Contribution guidance and script help describe that behavior. Optional local -Check diagnostics and all six functional test suites remain unchanged, as the user selected. The six index-generator fixture tests pass, including regeneration from stale sample content; the real generation-then-build path succeeds with pinned Zensical 0.0.59. No tests assert the content of checked-in docs or workflows, and no new tests were added. The audit's other matches are functional temporary-file tests and plugin metadata/schema checks, not prose snapshots.
MariusStorhaug commentedon Nov 2, 2026
The final user-selected drift-enforcement change is 8daf026. All 64 tests in the six retained functional suites pass in exact-head CI. All five required checks pass; the actual CI Build job successfully generates indexes and builds the site without a -Check drift gate. The fresh automated review approves with zero new inline comments. The functional index/link/action-pin tests and plugin metadata/PowerShell checks are unchanged; optional local index diagnostics remain. No actual-document or workflow-content tests were added, no source files are synchronized by CI, and no merge or live publication occurred.
Release guidance uses keyed release types (#196)