Skip to content

Commit 4ea45ec

Browse files
Migration skills state explicit template and upgrade conditions (#581)
Migration skill readers can distinguish the selected immutable template layout from the requested documentation layout. The v8 and Zensical framing uses explicit present-tense conditions instead of time-dependent or authoring-session statements. Consumer upgrade behavior does not change, and no consumer action is required. <!-- ANNOUNCEMENT STOP --> ## Fixed: Migration framing states its conditions The v8 anatomy tree applies only when the selected immutable template revision has that layout. The documentation framing states the selected-template condition and the requested-v8-upgrade condition directly. The Zensical starter configuration is conditional on the selected immutable template revision; a `docs/` tree remains possible or absent. All supported layouts, paths, migration actions, optional-versus-required distinctions, and preserve/report alternatives remain unchanged. Documentation moves only when the existing requested-migration condition applies. The Zensical procedure still requires a successful site build before removal of obsolete active configuration. This change does not perform or authorize a consumer upgrade. <details> <summary>Technical details</summary> ### Exact delivery and source evidence The scope is limited to the linguistic handback in #561. Both complete skills are reviewed. Before editing, exact source spans, expected replacements, and protected-content checks were recorded in the issue and in session-local JSON evidence. All three target statements were absent before editing and match their recorded replacements in the accepted source tree. | Released source | Before | After | | --- | --- | --- | | [v8 anatomy, source line 57](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/plugin/psmodule/skills/psmodule-v8-upgrade/SKILL.md#L57) | `The current template's default repository anatomy is:` | `If the selected immutable template revision has this layout, its default repository anatomy is:` | | [v8 framing, source lines 127-133](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/plugin/psmodule/skills/psmodule-v8-upgrade/SKILL.md#L127-L133) | `the current template uses` and `this v8 upgrade request uses` | `If the selected immutable template revision uses` the template configuration, and `If the requested v8 upgrade uses` the listed documentation paths. The optional asset distinction remains exact. | | [Zensical framing, source lines 79-83](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/plugin/psmodule/skills/psmodule-zensical-migration/SKILL.md#L79-L83) | `The current ... repository historically stores` | `If the selected immutable ... revision contains` the starter configuration. The requested-layout and build-before-removal conditions remain exact. | Scoped comparison: base `main` at `64ffb1d87f86bd5d487891fdb140b78385a00531`; accepted source head `21cc8b3c5f6f5bce6fe245ffd181fea5d0c496c4` on `migration-framing-prose`. The two source commits are `c43c36e1012859388d378a838c27e318893d933c` for the two v8 framing spans, then `21cc8b3c5f6f5bce6fe245ffd181fea5d0c496c4` for the two-line Zensical framing. This PR opened as a draft immediately after the first commit. Live issue ownership and unchanged main source blobs were rechecked before each source commit. The preparation head is `3b7f435d5db009740fb32686652fefb5663ddf06`. Its immediate parent is the accepted source head, and both full trees are `37516ee1cda57797e1de094ea8078a3cace927c6`. This one ordinary empty commit refreshes native PR evidence without a source change. Local, origin, remote commit, and live PR identities match; the worktree is clean. Only these two files differ from the base, with 11 insertions and 8 deletions: | File | Base blob | Head blob | | --- | --- | --- | | `.github/plugin/psmodule/skills/psmodule-v8-upgrade/SKILL.md` | `0c27e026a451cccb60196bee04e398486d86aa0d` | `be52d02d835f639786cff51122c3ecd873f98eb0` | | `.github/plugin/psmodule/skills/psmodule-zensical-migration/SKILL.md` | `b6e19feffb3afa6420b499f0166097c648d5ce2a` | `c0f49052a8b25dde9be6f3cf60e45ed30926ca11` | ### Protected content A one-off comparison reverses only the three recorded framing replacements and compares every other source text byte exactly, with CRLF normalized to LF. All ordered front matter, headings, fenced blocks, inline literals, and links also compare exactly. | Skill | Front matter | Headings | Fenced blocks | Inline literals | Links | | --- | --- | --- | --- | --- | --- | | v8 upgrade | 1 | 11 | 6 | 62 | 13 | | Zensical migration | 1 | 8 | 2 | 73 | 7 | This protects the exact caller YAML, triggers, permissions, concurrency, v8 reference, secrets, TestData examples, template/version selection, anatomy tree, layout alternatives, optional source directories and test phases, optional assets, migration actions, validation procedures, stop conditions, and normative force. No example becomes universal. All other skills, proposal branches, metadata, site design, runtime, repository tests, and dependencies remain unchanged. No migration command runs. Full-tree equality transfers this accepted source proof to the preparation head without another source audit or tool installation. ### Existing local checks and limits The source-delivery checks pass on both files: repository Markdown configuration with zero issues (`markdownlint-cli2` 0.24.0, `markdownlint` 0.42.0), repository spelling configuration, and `git diff --check`. The existing YAML parser accepts both unchanged front-matter maps; both unchanged plugin metadata JSON files parse. The one relative skill target resolves. All 20 links remain exact. No standalone plugin link/front-matter checker exists in this checkout; unchanged external URLs are not claimed as network-checked. The plain textlint CLI reports no rules before source edits and cannot resolve its configured rule packages on this host. After the actual missing-package failure during source delivery, those tools were restored only in the npm cache. The existing `textlint` 15.8.0, `terminology` 5.2.16, and `comments` 1.3.0 rules pass through their installed API with the unchanged repository options and Markdown plugin: zero messages on both immutable source files and both final files. An anonymous incorrect-term probe confirms rule execution, and a comment probe confirms the existing filter. No repository tooling or dependency is added. No tool was installed for the source-identical refresh. ### Fresh native review on 2026-11-11 Before the refresh, exact accepted-head inventories contain zero check runs, zero check suites, zero status contexts, and zero `pull_request` workflow runs. The November 4 checks are no longer retained. This confirmed absence permits the single normal empty trigger commit; no existing run or suite is available to rerun. No reset, rebase, amend, force push, workflow dispatch, or second trigger commit occurs. The one explicit native Copilot review request is sent at `2026-11-11T14:58:07.633Z` for `3b7f435d5db009740fb32686652fefb5663ddf06`. Timeline event `35811053045` records the request at `14:58:10Z`. Native review run `43043642020` has event `dynamic`, exact head/base association with PR 581, and a successful `copilot-pull-request-reviewer` job `130601746030`. Fresh [review `5860764388`](#581 (review)) approves that exact head at `14:59:40Z`; the author is `copilot-pull-request-reviewer[bot]` with association `CONTRIBUTOR`. Participant associations are read before feedback. Complete post-review thread pagination reports zero threads and zero unresolved threads. No finding or prose fix is required, and no second review is requested. Historical review `5769461963` is dismissed and retains its November 4 submission time, even though GitHub reports its commit association on the new head. It is not counted as fresh approval. The source-identical diagnostic retry below does not require another review. ### Actual PR CI and both Linter attempts | Actual native evidence | Event and source association | Result | | --- | --- | --- | | [Linter run `43043526453`, attempt 1, job `130601329239`](https://github.com/PSModule/Process-PSModule/actions/runs/43043526453/job/130601329239) | `pull_request`; PR 581; head `3b7f435d5db009740fb32686652fefb5663ddf06`; base `64ffb1d87f86bd5d487891fdb140b78385a00531` | Failure at `2026-11-11T15:01:30Z`; POWERSHELL validator process crash. | | [Same Linter run, attempt 2, job `130606199466`](https://github.com/PSModule/Process-PSModule/actions/runs/43043526453/job/130606199466) | Original `pull_request` event; same PR, head, base, and merge source; failed-job diagnostic retry only | Success at `15:09:31Z`; actual POWERSHELL validator success is verified below. | | [CodeQL run `43043522362`](https://github.com/PSModule/Process-PSModule/actions/runs/43043522362), job `130601319547` (`Analyze (actions)`) | Native `dynamic` CodeQL route; exact head; `refs/pull/581/head` | Success. `CodeQL` check `130601595792` also succeeds on the exact head. | | [Native review run `43043642020`](https://github.com/PSModule/Process-PSModule/actions/runs/43043642020), job `130601746030` | `dynamic/agents/copilot-pull-request-reviewer`; exact head/base and PR 581 | Success; fresh exact-head approval above. | The skill-only paths do not match Docs workflow path filters, so no Docs/Pages run is expected. No version, release, publication, consumer-upgrade, or dispatch-only check is required or manufactured by this refresh. ### Attempt 1: observed runtime failure and source boundary The failed job runs pinned Super-linter `4ce20838b8ab83717e78138c5b3a1407148e0918` / container `v8.7.0`, reporting PowerShell `7.6.2`. The POWERSHELL validator exits with `Unhandled exception. System.ArgumentException: String cannot have zero length.` The stack contains `System.Reflection.AssemblyNameParser..ctor`, `AssemblyNameParser.Parse`, and `AssemblyName.ParseAsAssemblySpec`. No PowerShell file/line lint defect is reported. The sole check annotation is the Ubuntu-latest migration notice, not this failure cause. The complete failure log, version, exception, job metadata, and source-boundary evidence are retained locally and in the leaf audit. The available log does not establish a lower-level cause. The actual PR merge ref is `ed067cb166fecee7058b7a296d04063dee28314c`, with base and preparation-head parents. Its full tree is also `37516ee1cda57797e1de094ea8078a3cace927c6`. The reviewed-parent-to-head delta is empty, and the base-to-head PowerShell/workflow/linter-configuration delta is empty. The only source changes remain the three released Markdown framing spans. On attempt 1, all 13 other Super-linter contexts succeed, including MARKDOWN, NATURAL_LANGUAGE, SPELL_CODESPELL, and YAML. Only `--> Linted: POWERSHELL`, status `58640569011`, is `error`. Those child passes do not make attempt 1 pass. No introduced or directly coupled three-span prose correction is demonstrated, and no source, workflow, runtime, dependency, tooling, or policy change is made to force green. ### One authorized diagnostic retry: same source, successful result The root coordinator explicitly authorizes one bounded same-event/head failed-job diagnostic retry despite unproven transience. The sole native `gh run rerun 43043526453 --failed` request is sent at `2026-11-11T15:05:52.347Z` and succeeds at `15:05:54.227Z`. It reruns only the failed job on the original PR event. No new trigger, dispatch, installation, suppression, source/configuration/runtime change, lifecycle change, or review re-request occurs. A bounded read-only observer completes within its six-minute limit. Attempt 2 runs job `130606199466` from `15:06:01Z` to `15:09:31Z`. Its checkout log identifies the same merge ref `ed067cb166fecee7058b7a296d04063dee28314c`. It reports the same `pwsh: 7.6.2` and `Successfully linted POWERSHELL` at `15:09:24Z`. New POWERSHELL status `58641300307` is `success`, and all 14 latest merge-ref status contexts are success. The four latest head checks are also success: Linter, native reviewer, CodeQL, and Analyze (actions). The runtime crash does not reproduce on this single diagnostic attempt. No source fix is made, and the successful retry is not proof of the original root cause. Attempt 1 remains recorded as failed; it is not rewritten or hidden. No further retry is requested. No preparation blocker remains in the current native gates; the root alone decides any later merge/publication. ### Standards and completion boundary The fixed [MSX writing source](https://github.com/MSXOrg/docs/tree/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs) supplies the Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, guide template, and Task/PR formats. The official STE overview and FAQ, relevant Issue 9 rules and dictionary entries, and en-US inform only the released wording. The [Issue 9](https://doi.org/10.5281/zenodo.23666006) manual stays local; its PDF checksum matches the official record. No certified or full STE conformance is claimed. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | Released v8 framing | Fixed MSX writing/documentation sources; relevant STE guidance; en-US | README, complete skill, plugin guide, and exact issue handback | Fixed in this PR | | Released Zensical framing | Same fixed writing sources and applicable guide format | Complete skill, plugin guide, and exact issue handback | Fixed in this PR | The README, plugin structure, shared guides, headings, anchors, and metadata need no change for this bounded framing correction. Independent content review accepts source head `21cc8b3c5f6f5bce6fe245ffd181fea5d0c496c4`; the preparation head has the identical full tree. Both skill diffs stay within the exact framing handback and preserve templates, paths, optional/required distinctions, scope, and procedure. The PR remains open and non-draft under the user's later lifecycle decision. Agent merge stays enabled for `address_reviews`, `fix_ci`, and `resolve_conflicts`, with `merge_pr=false`; GitHub `auto_merge` remains null. This preparation changes none of those settings, labels, or schedules. The root coordinator alone controls the later global merge/publication sequence. The issue stays open; no merge or publication is authorized here. Issue-convergence scope remains the exact handback and open migration-title issues. No additional issue is fully resolved by this two-file diff. Only #561 has a closing reference. </details> <details> <summary>Related references</summary> - Resolves #561 - References #525, #535, and #537 for unchanged template/caller/authoring ownership. </details> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 09107c4 commit 4ea45ec

2 files changed

Lines changed: 11 additions & 8 deletions

File tree

  • .github/plugin/psmodule/skills

‎.github/plugin/psmodule/skills/psmodule-v8-upgrade/SKILL.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,8 @@ the template's default files before adding, removing, or relocating anything.
5454
The template is a starting point, not a reason to overwrite module-specific
5555
content.
5656

57-
The current template's default repository anatomy is:
57+
If the selected immutable template revision has this layout, its default
58+
repository anatomy is:
5859

5960
```text
6061
<ModuleName>/
@@ -125,11 +126,13 @@ Treat files and directories as follows:
125126
Preserve the consumer's local onboarding contract while updating stale links.
126127

127128
If the template revision and the consumer's existing layout disagree, record
128-
the difference and migrate only the requested integration surface. In
129-
particular, the current template uses `.github/zensical.toml`, while this v8
130-
upgrade request uses `docs/zensical.toml`, `docs/content/`, and
131-
`docs/overrides/` (including `docs/overrides/assets/`) as its documentation
132-
contract; a separate `docs/assets/` directory is optional. When that requested
129+
the difference and migrate only the requested integration surface.
130+
131+
If the selected immutable template revision uses `.github/zensical.toml`,
132+
that file contains the template's Zensical settings. If the requested v8
133+
upgrade uses `docs/zensical.toml`, `docs/content/`, and `docs/overrides/`
134+
(including `docs/overrides/assets/`) as its documentation contract, a separate
135+
`docs/assets/` directory is optional. When that requested
133136
documentation migration is in scope, move the template's Zensical settings
134137
and custom assets into the `docs/` contract rather than maintaining both
135138
configurations. When it is not in scope, preserve the consumer's existing

‎.github/plugin/psmodule/skills/psmodule-zensical-migration/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,8 +76,8 @@ Keep existing content under `docs/content/`, custom templates under
7676
`docs/assets/` directory is optional for static content assets. Do not create a
7777
parallel MkDocs theme or leave two active site configurations.
7878

79-
The current `PSModule/Template-PSModule` repository historically stores a
80-
starter `.github/zensical.toml` and may not contain a `docs/` tree. When the
79+
If the selected immutable `PSModule/Template-PSModule` revision contains a
80+
starter `.github/zensical.toml`, it may not contain a `docs/` tree. When the
8181
consumer upgrade explicitly requires the Process-PSModule `docs/` contract,
8282
move the template settings and custom assets into `docs/` and remove the
8383
obsolete active configuration only after the site builds. When that contract

0 commit comments

Comments
 (0)