Repository navigation
Commit 1ae6c11
authored
Module authors have direct development and validation procedures (#565)
Module authors get direct, evergreen procedures for bootstrap,
coordinated development, framework-test exceptions, validation, module
tests, and plugin-skill authoring. Descriptions state supported facts;
procedures use active instructions and explicit conditions.
This change revises guidance only. It requires no module, workflow,
configuration, or dependency migration. Executable examples and
runtime/version constraints remain unchanged.
<!-- ANNOUNCEMENT STOP -->
## Changed: Module guides state direct procedures and supported facts
The six guides replace conversational, vague, and future-delivery
wording with present-state descriptions and verifiable actions. The test
guide names the v5.1.1 action contract that the workflow uses and states
its unsupported optional-control limitation without a future
implementation promise. Its Pester declaration keeps the exact minimum
and maximum from the existing code block, without the misleading `6.1.x`
prose label.
The bootstrap version-policy conflict and OS-qualified shared-resource
example conflict remain explicit follow-ups. This prose delivery does
not choose a new version policy or change executable examples.
<details>
<summary>Technical details</summary>
**Source comparison and delivery.** Base
`64ffb1d87f86bd5d487891fdb140b78385a00531`; final pushed head
`d33a7e1773f9bde2527ae94fea7a8ed2c22a4acf`. Six small commits are
pushed. This draft opened immediately after the first coherent commit,
`5f5062cca628831bc4f3de8864c84bb2759ed6f7`. It stays in draft by
request. No merge, auto-merge, Agent merge, or additional child session
is used.
**Manual review and before/after evidence.** Every assigned file is read
in full before edits and in the final review, including unchanged
passages and examples. All six files change; no assigned guide is
omitted or given an unverified no-change result.
| Exact changed path | Before | After |
| --- | --- | --- |
| `docs/content/get-started/module-bootstrap.md` | "the piece(s) every
other function will depend on"; "first real release" | "contains the
components that all other module functions require"; "first release
(`v1.0.0`)". |
| `docs/content/guides/module-development-orchestration.md` | "a second
place where the implementation is silently changed" | "The orchestrator
does not change a child's implementation without a recorded scope
decision." |
| `docs/content/guides/skipping-framework-tests.md` | "will cause the
framework to skip"; "will log a warning" | "The framework skips only the
identified test for that file. It writes the supplied reason as a
warning in the build output." |
| `docs/content/guides/validating-before-review.md` | "current enough
that generated documentation will stay accurate" | "public-function
links resolve and usage examples match the implemented parameters and
outputs". |
| `docs/content/guides/writing-module-tests.md` | "will expose them
after"; "current v5.1.0"; a `6.1.x` label for a broader declaration |
The pinned v5.1.1 contract does not accept the optional controls; the
reusable workflow does not expose them. The declaration is introduced as
"this Pester requirement". |
| `docs/content/guides/writing-plugin-skills.md` | "an operational entry
point for an agent; shared process and policy belongs" | "A skill is an
agent's entry point. Shared process and policy belong in the
documentation". |
**Meaning and protected content.** The immutable source comparison
verifies 10 byte-identical fenced examples, 54 headings unchanged except
sentence case, and all 85 distinct per-file inline technical tokens
retained. Manual comparison preserves public inputs/defaults, paths,
framework-test IDs, warning semantics, discovery precedence, bootstrap
rules, caller-provided `TestData`, and normative requirement strength.
No normative requirement is presented as proof of CI enforcement. No
link repair requires another owner's file.
**Writing sources.** The fixed writing baseline is
`MSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082`: [Natural
Language](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md),
[Writing
Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md),
[Markdown](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Markdown.md),
[Documentation](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Documentation.md),
[Documentation
Model](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Documentation-Model.md),
and the [guide
template](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md#guide).
The review also uses the [STEMG
description](https://www.asd-ste100.org/about_STE.html), [STEMG
FAQ](https://www.asd-ste100.org/STE_faq.html), and [ASD-STE100 Issue
9](https://doi.org/10.5281/zenodo.23666006), including relevant writing
rules and dictionary entries. The reference PDF and extraction stay
local; the verified PDF MD5 is `9c720341c350ed77943b2c73d01c716f`. No
required writing source is unavailable. Automated checks do not prove
full STE conformance.
| Changed surface | Standards checked | Framework/source evidence
checked | Result |
| --- | --- | --- | --- |
| `module-bootstrap.md` | Fixed writing baseline and guide template |
Existing bootstrap branch/release contract; versioning reference |
Exception - #573 preserves the policy conflict.
|
| `module-development-orchestration.md` | Fixed writing baseline and
guide template | Existing child scope, handoff, integration, and
release-readiness contract | Fixed in this PR. |
| `skipping-framework-tests.md` | Fixed writing baseline and guide
template | Source-code `FunctionCount` skip handling and warning output
| Fixed in this PR. |
| `validating-before-review.md` | Fixed writing baseline and guide
template | Module structure, native-help, and test reference
requirements | Fixed in this PR. |
| `writing-module-tests.md` | Fixed writing baseline and guide template
| Discovery/settings source, test/setup/teardown workflows, and pinned
action interface | Exception - #571 preserves
the executable sample conflict. |
| `writing-plugin-skills.md` | Fixed writing baseline and guide template
| Existing plugin README, directory structure, plugin metadata, and
marketplace registration | Fixed in this PR. |
**Read-only inspections and justified no-change results.** Supporting
files/sections: `README.md`; `AGENTS.md`; `.gitignore`;
`.github/actions/Get-PSModuleSettings/src/main.ps1`;
`.github/actions/Test-PSModule/src/tests/SourceCode/PSModule/PSModule.Tests.ps1`;
`.github/workflows/workflow.yml`;
`.github/workflows/Test-ModuleLocal.yml`;
`.github/workflows/BeforeAll-ModuleLocal.yml`;
`.github/workflows/AfterAll-ModuleLocal.yml`;
`.github/workflows/Docs.yml`; `.github/workflows/Linter.yml`;
`.github/workflows/Release.yml`; `.github/linters/.markdown-lint.yml`;
`.github/linters/.textlintrc`; `.github/plugin/README.md`;
`.github/plugin/psmodule/plugin.json`;
`.github/plugin/marketplace.json`; `docs/zensical.toml`; and the
relevant sections of
`docs/content/reference/{versioning,powershell-module-standard,test-specification}.md`.
They need no edit because this delivery changes guide prose, not their
contracts, implementation, native help, tests, metadata, or
configuration.
The remote [Invoke-Pester action
contract](https://github.com/PSModule/Invoke-Pester/blob/c5494aba3c07d7bfd81bdbbc9f301e8fa4a729fb/action.yml)
is read at exact SHA `c5494aba3c07d7bfd81bdbbc9f301e8fa4a729fb`. The
v5.1.1 tag independently resolves to that commit. Its interface lacks
`Run.Shuffle`, `Run.ShuffleSeed`, `Run.Parallel`,
`Run.ParallelThrottleLimit`, and `Debug.ShowStartMarkers`. Neither
workflow action references nor Pester/runtime constraints change.
**Exclusions.** Every other repository path is excluded: other
getting-started and guide pages, reference pages, indexes,
specifications, dictionary pages, assets/site design, plugin
skills/metadata, code, tests/assertions, and configuration. Reserved
release/workflow/structure/configuration surfaces remain with
#524, #525,
#531, #535,
#537, #541,
#548, and #549.
#551 changes no documentation or native help.
Live open-PR path ownership is checked before every commit; no other PR
owns an assigned path.
**Checks on the final head.**
| Command or review | Result |
| --- | --- |
| `git diff --check 64ffb1d` | Pass. |
| `npx --no-install markdownlint-cli2 --config
.github\linters\.markdown-lint.yml` with the six exact assigned paths |
Pass: 6 files, 0 issues. |
| `zensical build --clean` from `docs` | Pass: "No issues found", exit
0. |
| Existing `rules.terminology` through `TextlintKernel.lintText` | Pass:
6 final guides, 0 issues; an intentional `Powershell` positive control
reports the `PowerShell` correction. |
| Standard-library scoped Markdown/generated-HTML link review | Pass: 33
relative links, 9 rendered fragments, 0 issues. |
| Exact committed `git show` source comparisons | Pass: 10
byte-identical fences, 54 stable headings, 85 retained per-file inline
technical tokens, exact six-file scope. |
| Six original wording cases | Each fails on the original baseline and
passes at the final head. The additional misleading Pester-range label
is absent. |
| `ConvertFrom-Json` on plugin and marketplace metadata | Pass; both
files are unchanged. |
The direct terminology CLI is absent; the cache-only attempt confirms
missing packages before a session-local restore. Its Windows CLI loader
does not load the configured rule. The successful kernel invocation
loads the existing Markdown parser and exact `rules.terminology` options
from `.github/linters/.textlintrc`, with an active positive control. No
repository dependency, linter, or configuration is added. No standalone
link-check script exists in this snapshot; the scoped check uses
Python's standard library and actual generated HTML. It does not claim
exhaustive external-site validation. Generated site output and the
temporary checker restore are removed after verification; the worktree
is clean and local/remote commit counts are `0 0`.
**Hosted status on the final head.** `gh pr checks 565 --repo
PSModule/Process-PSModule --json name,state,link` reports 22 successful
checks, one skipped Publish check, and no pending or failed checks.
Copilot approves `d33a7e1773f9bde2527ae94fea7a8ed2c22a4acf` with "No
open issues" and no inline comments. Final-head Build, Lint, Lint code
base, CodeQL, and Analyze (actions) pass. No new local failure or scope
blocker remains. The PR stays in draft for the requested acceptance
review; these results do not authorize readiness or merge.
**Plan and convergence.** #559 contains the
current Task plan, pre-edit evidence, final acceptance evidence, and
check results. Its author-side implementation steps are complete; the
issue stays open until the normal review/merge path completes. The
scoped sweep examines campaign issue titles and declared paths, plus
bootstrap/major, version-policy, and `RUNNER_OS` searches. Only
#559 is fully covered.
#571 and #573 remain
non-closing follow-ups; other campaign issues name excluded surfaces.
The docs-only path set does not invoke the release workflow, so no
release-decision block or `release:*` label applies.
</details>
<details>
<summary>Related references</summary>
- Resolves #559
- References #571
- References #573
</details>1 parent 64ffb1d commit 1ae6c11
6 files changed
Lines changed: 218 additions & 205 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | | - | |
| 3 | + | |
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
8 | | - | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
9 | 11 | | |
10 | 12 | | |
11 | 13 | | |
12 | | - | |
| 14 | + | |
13 | 15 | | |
14 | | - | |
15 | | - | |
| 16 | + | |
| 17 | + | |
16 | 18 | | |
17 | | - | |
| 19 | + | |
18 | 20 | | |
19 | 21 | | |
20 | 22 | | |
21 | | - | |
22 | | - | |
23 | | - | |
24 | | - | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
25 | 27 | | |
26 | 28 | | |
27 | 29 | | |
28 | | - | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
29 | 33 | | |
30 | 34 | | |
31 | 35 | | |
| |||
46 | 50 | | |
47 | 51 | | |
48 | 52 | | |
49 | | - | |
| 53 | + | |
50 | 54 | | |
51 | 55 | | |
52 | 56 | | |
53 | | - | |
| 57 | + | |
54 | 58 | | |
55 | 59 | | |
56 | 60 | | |
57 | | - | |
58 | | - | |
| 61 | + | |
| 62 | + | |
59 | 63 | | |
60 | 64 | | |
61 | 65 | | |
62 | | - | |
63 | | - | |
| 66 | + | |
| 67 | + | |
64 | 68 | | |
65 | 69 | | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | | - | |
| 3 | + | |
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
8 | | - | |
9 | | - | |
10 | | - | |
11 | | - | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
12 | 11 | | |
13 | | - | |
14 | | - | |
15 | | - | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
16 | 15 | | |
17 | 16 | | |
18 | 17 | | |
| |||
27 | 26 | | |
28 | 27 | | |
29 | 28 | | |
30 | | - | |
| 29 | + | |
31 | 30 | | |
32 | 31 | | |
33 | 32 | | |
34 | 33 | | |
35 | | - | |
36 | | - | |
37 | | - | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
38 | 37 | | |
39 | 38 | | |
40 | 39 | | |
41 | | - | |
42 | | - | |
43 | | - | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
44 | 43 | | |
45 | | - | |
| 44 | + | |
46 | 45 | | |
47 | | - | |
48 | | - | |
49 | | - | |
50 | | - | |
51 | | - | |
52 | | - | |
53 | | - | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
54 | 51 | | |
55 | | - | |
| 52 | + | |
56 | 53 | | |
57 | | - | |
58 | | - | |
59 | | - | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
60 | 57 | | |
61 | 58 | | |
62 | 59 | | |
| |||
73 | 70 | | |
74 | 71 | | |
75 | 72 | | |
76 | | - | |
77 | | - | |
78 | | - | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
79 | 76 | | |
80 | 77 | | |
81 | 78 | | |
| |||
88 | 85 | | |
89 | 86 | | |
90 | 87 | | |
91 | | - | |
92 | | - | |
93 | | - | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
94 | 91 | | |
95 | | - | |
| 92 | + | |
96 | 93 | | |
97 | 94 | | |
98 | 95 | | |
99 | | - | |
100 | | - | |
101 | | - | |
102 | | - | |
103 | | - | |
104 | | - | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
105 | 100 | | |
106 | | - | |
107 | | - | |
108 | | - | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
109 | 107 | | |
110 | 108 | | |
111 | 109 | | |
112 | | - | |
113 | | - | |
114 | | - | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
115 | 115 | | |
116 | 116 | | |
117 | 117 | | |
118 | 118 | | |
119 | 119 | | |
120 | | - | |
| 120 | + | |
121 | 121 | | |
122 | 122 | | |
123 | 123 | | |
124 | 124 | | |
125 | 125 | | |
126 | | - | |
127 | | - | |
| 126 | + | |
| 127 | + | |
128 | 128 | | |
129 | 129 | | |
130 | 130 | | |
131 | 131 | | |
132 | | - | |
133 | | - | |
134 | | - | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
135 | 135 | | |
136 | 136 | | |
137 | 137 | | |
| |||
140 | 140 | | |
141 | 141 | | |
142 | 142 | | |
143 | | - | |
144 | | - | |
| 143 | + | |
| 144 | + | |
145 | 145 | | |
0 commit comments