Repository navigation
Commit bc376d0
authored
Entry pages and workflow examples use direct prose (#579)
Entry pages describe the framework's reusable PowerShell modules, GitHub
Actions workflows, and task automation in direct, present-tense English.
The coverage example states its existing minimum of 80%, and the changed
descriptive text uses en-US spelling. No consumer action is needed for
these prose edits.
<!-- ANNOUNCEMENT STOP -->
## Changed: Entry guidance describes existing automation directly
The README and site index use direct descriptions instead of promotional
or time-relative wording. The coverage example says `at least 80%`
because the existing implementation rejects coverage only when it is
below the target. The release guide changes only two descriptive uses of
`labelled` to `labeled`.
The edits preserve the documented capabilities, supported scope,
destinations, examples, and obligations. They do not change the
framework, caller interface, configuration, release behavior, or site
design. The complete fixed-secret/TestData adoption section stays
intact. Its separate source-bound decision remains open in
#578.
<details>
<summary>Technical details</summary>
### Exact delivery source and plan
| Item | Identity |
| --- | --- |
| Repository | `PSModule/Process-PSModule` |
| Base | `main` at `64ffb1d87f86bd5d487891fdb140b78385a00531` |
| Head | `entry-guidance-prose` at
`79bac09b581e80b27bae5dad5d87adffac0ff219` |
| Comparison | Four files, 10 insertions, 10 deletions |
| First real commit | `93b95eb6935d43c3e350bcdd293e19c128dc7aa3`; this
draft opened immediately after that push |
| Final state | Five small commits pushed; draft; no auto-merge; no
labels |
This is a fresh main-based delivery, not an amendment to a proposal or
first-pass PR. The owner handback includes the explicit extension for
the two adjacent index statements at original lines 80-81. No other
paragraph-rewrite permission is inferred from the spelling allowance.
The issue plan covers the full ten-page read, pinned writing sources,
pre-edit expectations, protection baselines, existing checks, early
draft, small commits, live ownership checks before each commit, the
source-backed threshold clarification, and the final acceptance record.
All scoped implementation and verification work is complete. Merge and
issue closure remain separate, future review actions.
### Before/after acceptance evidence
[The original pre-edit
record](#560 (comment))
records the source, expected edits, protection baseline, and existing
checks before repository changes. [The threshold clarification
record](#560 (comment))
records the parent review request and the below/equal/above experiment
before that follow-up edit. All eight exact replacement expectations
pass at the final head. They cover nine matches, including the two
release-spelling matches.
| Region | Before, at the exact base | After, at the exact head |
| --- | --- | --- |
| README opening | [Line
3](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/README.md#L3):
`corner-stone` paragraph | [Line
3](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/README.md#L3):
a direct core-workflow description; end-to-end GitHub Actions, all five
lifecycle capabilities, and the Gallery destination remain. |
| Index spelling | [Line
18](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/index.md#L18):
`behaviour` | [Line
18](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/index.md#L18):
`behavior`; the rest of the paragraph and `.github/PSModule.yml` remain
unchanged. |
| Released adjacent index statements | [Lines
80-81](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/index.md#L80-L81):
`infuses GitHub ... fullest extent` and `DevOps functionality ...
missing` | [Lines
80-81](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/index.md#L80-L81):
reusable PowerShell modules, GitHub Actions workflows, and automated
module delivery. No shipping, exclusivity, completeness, or enforcement
claim is added. |
| Index task automation | [Line
83](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/index.md#L83):
`We empower ... effortlessly ... without distractions` | [Line
83](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/index.md#L83):
repeated-task automation lets developers write code for PowerShell
solutions; both consumers and contributors remain explicit. |
| Index goal-setting link | [Line
85](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/index.md#L85):
`Where we are headed ...` | [Line
85](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/index.md#L85):
a neutral imperative link to the same goal-setting model; link text and
destination remain unchanged. |
| Index canonical guidance | [Line
89](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/index.md#L89):
`are now canonical` | [Line
89](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/index.md#L89):
`are canonical`; authority and destination remain unchanged. |
| Coverage example | [Lines
17-23](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/guides/configuring-the-pipeline.md#L17-L23):
`will require that code coverage is 80% before passing` | [Lines
17-23](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/guides/configuring-the-pipeline.md#L17-L23):
`This example runs all steps and requires at least 80% code coverage to
pass.` The exact YAML is unchanged. |
| Release-guide spelling | [Lines 22 and
58](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/guides/versioning-and-releases.md#L22-L60):
`labelled` twice | [Lines 22 and
58](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/guides/versioning-and-releases.md#L22-L60):
`labeled` twice; all other release guidance is identical. |
The complete changed-file comparison permits only these declared
replacements. All other text in those four files remains unchanged,
including the index introduction, the development-framework
heading/anchor, and every configuration/release example.
### Ten-page review and no-change results
All ten pages were read in full. The four changed paths and exact
regions are listed above. The other six pages need no correction under
the narrow spelling allowance. Their complete file bytes and Git blobs
remain unchanged. This is a scoped no-change result, not a claim that
every paragraph received an unrestricted rewrite or full STE
certification.
| Reviewed no-change path | Before and after | Identical blob |
| --- | --- | --- |
| `docs/content/get-started/index.md` |
[Before](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/get-started/index.md)
/
[after](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/get-started/index.md);
procedure and outcomes unchanged |
`72cc182b8e790c4b5420277d69a61de934a02791` |
| `docs/content/get-started/repository-setup.md` |
[Before](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/get-started/repository-setup.md)
/
[after](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/get-started/repository-setup.md);
setup, permissions, secrets, and caller YAML unchanged |
`790cf5eafb2946cad7c61398e7f80c7fcf6cc8a5` |
| `docs/content/get-started/your-first-release.md` |
[Before](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/get-started/your-first-release.md)
/
[after](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/get-started/your-first-release.md);
triggers, labels, and release conditions unchanged |
`e8b00fb1c220108790517d151dc59b707d895928` |
| `docs/content/guides/calling-the-workflow.md` |
[Before](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/guides/calling-the-workflow.md)
/
[after](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/guides/calling-the-workflow.md);
whole file unchanged, including the protected complete TestData adoption
section | `8e18d7e18025b68a1abd318c115719607d3683c3` |
| `docs/content/guides/github-app-authentication.md` |
[Before](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/guides/github-app-authentication.md)
/
[after](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/guides/github-app-authentication.md);
secret mapping, token scope, and permission ceilings unchanged |
`cf35933a019eaf977a8ce39ad940ab809edfe9b5` |
| `docs/content/guides/structuring-your-module.md` |
[Before](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/guides/structuring-your-module.md)
/
[after](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/guides/structuring-your-module.md);
layout, help URLs, dependency rules, and source-tree examples unchanged
| `c4f36cf327b9e5f045a02b7d05bbb54e7bb39334` |
| Changed path | Base blob | Head blob |
| --- | --- | --- |
| `README.md` | `c2d2257e3948184ebb8db36268f1c7490e0abcbc` |
`924672d74ec5927a3bc4b0591b0311cbd9f4e038` |
| `docs/content/index.md` | `02cc155fc51c96deba28eaf9ae1f9e899baf2d97` |
`03a57bba4e97779ec2e35b9764f024fcb37ba454` |
| `docs/content/guides/configuring-the-pipeline.md` |
`b77d4cdf2272ad592234076eec0a48afd692a926` |
`ae643ebc87483b2154091fa98a681be35416ae40` |
| `docs/content/guides/versioning-and-releases.md` |
`fe226002f077d1e0e7a01a01514d8112b3303317` |
`7694d507ba5f6b0f1d47bb9f2cf04e23d68a9578` |
### Exact contract-preservation results
The session-local, one-off comparison passes against the source tree. No
comparison script, prose inventory, enforcement tool, test, or
dependency is added to the repository.
| Protected surface across the ten pages | Result |
| --- | --- |
| 25 complete fenced blocks | Byte-identical, including every YAML,
command, JSON, tree, and example block |
| 66 headings | Identical; no heading, anchor source, or navigation
destination changes |
| 234 inline-code spans | Identical technical names, paths, inputs,
defaults, secrets, permissions, versions, labels, and expressions |
| 79 extracted Markdown link/image targets and the HTML image target |
Identical; no destination changes |
| Nine front-matter blocks | Identical |
| 75 normative modal tokens, in sequence | Identical; the complete
replacement comparison also protects all other contract wording outside
the released spans |
| Other repository paths | No diff; workflows, implementation, tests,
site configuration, assets, and design remain unchanged |
The protected [fixed-secret/TestData section, lines
76-104](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/guides/calling-the-workflow.md#L76-L104),
including its heading, all seven old input names, mapping instructions,
and complete adoption example, is byte-identical. Its source-LF region
is 1,045 bytes with SHA-256
`96ac1034b74d2c76c8fc770d3f21a196b3d7cfd685210974d0a90d63bc61f54a` at
both base and head. The existing CRLF worktree region is 1,074 bytes
with SHA-256
`2a90ca000acc18720d4f281a8fb42e8b92206e9e968f9e70fc8dc3c39b37b05f`
before and after. The entire calling-guide blob is unchanged.
The coverage text retains this exact sample:
```yaml
Test:
CodeCoverage:
PercentTarget: 80
```
The [settings
reference](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/reference/settings.md#L53-L55)
still defines the separate default as `0`. The [existing workflow
mapping](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/workflows/Get-CodeCoverage.yml#L27-L35)
forwards that setting. The existing implementation [accepts coverage
greater than or equal to its
target](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/actions/Get-PesterCodeCoverage/src/main.ps1#L157)
and [fails only below
target](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/actions/Get-PesterCodeCoverage/src/main.ps1#L389-L396).
The pre-edit experiment executes those extracted comparisons with target
80: 79.99 fails, 80 passes, and 80.01 passes. `At least 80%` clarifies
this existing boundary; it does not change policy or behavior.
The built-site comparison passes 12 explicit checks. It confirms the new
prose, both reader roles, the existing development-framework anchor, the
goal-setting and canonical-guidance destinations, both `labeled`
sentences, the migration heading and all seven old input names, and the
exact decoded coverage YAML. Code text is read without inserting
whitespace between syntax-highlight spans.
### Existing checks and outcomes
The existing Markdown configuration passes on all ten pages before and
after the edits: markdownlint-cli2 0.24.0, markdownlint 0.42.0, 10
files, 0 issues. The existing codespell 2.4.2 CLI passes with the
repository configuration. The existing Zensical 0.0.50 build passes
before and after, reporting `No issues found`. The exact base-to-head
whitespace check passes.
These commands use the same ten-file set as the recorded runs:
```powershell
$pages = @(
'README.md',
'docs\content\index.md',
'docs\content\get-started\index.md',
'docs\content\get-started\repository-setup.md',
'docs\content\get-started\your-first-release.md',
'docs\content\guides\calling-the-workflow.md',
'docs\content\guides\configuring-the-pipeline.md',
'docs\content\guides\github-app-authentication.md',
'docs\content\guides\structuring-your-module.md',
'docs\content\guides\versioning-and-releases.md'
)
npx --no-install markdownlint-cli2 --config '.github\linters\.markdown-lint.yml' @pages
codespell --config '.github\linters\.codespellrc' @pages
Push-Location -LiteralPath 'docs'
zensical build --clean
Pop-Location
git --no-pager diff --check 64ffb1d 79bac09
```
No standalone link-check command exists in this repository. The existing
site build reports no issues; separate exact link/heading comparisons
and rendered destination checks confirm no link regression from these
edits. This is not a new internet-wide link-validation claim. An initial
`python -m codespell` invocation used the wrong entry point; the
existing `codespell` CLI passes. No repository dependency is changed.
Hosted snapshot at `2026-11-04T13:59:39Z`, for head
`79bac09b581e80b27bae5dad5d87adffac0ff219`:
| Hosted check | Result |
| --- | --- |
| [Docs
Build](https://github.com/PSModule/Process-PSModule/actions/runs/41842493106/job/126617424058)
| Success |
| [Docs
Lint](https://github.com/PSModule/Process-PSModule/actions/runs/41842493106/job/126617423266)
| Success |
| [Repository
lint](https://github.com/PSModule/Process-PSModule/actions/runs/41842493216/job/126617425457)
| Success |
|
[CodeQL](https://github.com/PSModule/Process-PSModule/runs/126617863969)
| Success |
| [Analyze
(actions)](https://github.com/PSModule/Process-PSModule/actions/runs/41842487969/job/126617413004)
| Success |
| [Fresh Copilot
review](#579 (review))
| Approved at the exact final head; no inline comments |
| [Docs
Publish](https://github.com/PSModule/Process-PSModule/actions/runs/41842493106/job/126617713362)
| Skipped for the pull-request event |
No hosted check or review remains pending at this snapshot. Earlier-head
approval is not used as final-head evidence. The parent current-head
content review also accepts `79bac09b581e80b27bae5dad5d87adffac0ff219`
after independently checking the complete four-file diff and the
protected structures across all ten pages. This content acceptance does
not change draft or merge state.
### Standards, ownership, and scope alignment
The fixed writing source is [MSXOrg/docs at
`1b0d4893c8fefabe604d04393068a8ff6f848082`](https://github.com/MSXOrg/docs/tree/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs).
The review covers Documentation Model; Natural Language; Writing Guide;
Markdown; Documentation; the guide/reference templates; and the Task,
PR, workflow, and commit formats. The official [STE
overview](https://www.asd-ste100.org/about_STE.html),
[FAQ](https://www.asd-ste100.org/STE_faq.html), and relevant Issue 9
rules/dictionary were consulted through the verified local manual. No
manual material is republished. These edits apply STE writing practices;
scans, counts, and lint do not establish full STE conformance.
| Changed surface | Standards checked | Framework/source docs checked |
Result |
| --- | --- | --- | --- |
| README opening | Pinned Natural Language, Writing Guide, Markdown,
Documentation, Documentation Model | Existing README and site-index
capabilities | Fixed in this PR |
| Released site-index spans and spelling | Same pinned writing standards
and artifact model | Source index and exact extended owner handback |
Fixed in this PR |
| Coverage-example description | Same pinned writing standards and guide
format | Settings reference, workflow input mapping, source coverage
comparison/failure boundary | Fixed in this PR |
| Release-guide descriptive spelling | Pinned en-US and Markdown rules |
Existing release paragraphs, examples, and settings references | Fixed
in this PR |
The source, issue scope, live owner heads, and intersecting paths are
rechecked before each of the five commits and at final handoff. The
source remains `64ffb1d87f86bd5d487891fdb140b78385a00531`. Active owner
heads are unchanged:
| Existing PR | Verified head |
| --- | --- |
| #524 |
`0fb4234056b3bd4574c58cd4edd6dff2544d70f6` |
| #525 |
`03e24f359265b7a4106f8f71f769cba1ba12bf3c` |
| #531 |
`50f16425797ec67375d47262c8c79d3507fb2b21` |
| #535 |
`7204e1eb418f99848c396f7e3597152a70e362ff` |
| #537 |
`af22c475873b21b8afa5ba7ecb87cb2bf8efabd2` |
| #548 |
`eb3eb0cb8fb6f0b7822c79ad9b2781d17127dcd4` |
| #549 |
`663d87b9c11e7d5662a986f662e4f7499e816f55` |
| #551 |
`7a00cbb9cd72baddf14d990019cf5da3c9c3600e`; no intersection with the
ten-page set |
#565 through #570
retain disjoint paths and unchanged heads. No existing owner branch is
awakened or edited. No new caller, release, compatibility, shipping, or
enforcement contract is imported from a proposal.
The issue-convergence search covers the open
`documentation-writing-alignment` issues and the active owners
intersecting this ten-page set. This diff resolves only
#560. It does not resolve the reserved
interface, source-contract, or TestData adoption work. No additional
closing reference is added.
No scoped wording decision remains. #578
retains the actual baseline/target, source-bound release-record,
compatibility, and exact #535 /
#537 owner decisions. This PR makes none of
those decisions.
The PR remains draft. No merge, ready transition, auto-merge, Agent
merge, release-label, or publication action is performed.
</details>
<details>
<summary>Related references</summary>
- Resolves #560
- References #578; protected source-bound
TestData adoption reconciliation remains separate and open.
</details>1 parent a40a9eb commit bc376d0
4 files changed
Lines changed: 10 additions & 10 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | | - | |
| 3 | + | |
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
14 | 14 | | |
15 | 15 | | |
16 | 16 | | |
17 | | - | |
| 17 | + | |
18 | 18 | | |
19 | 19 | | |
20 | 20 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
19 | 19 | | |
20 | 20 | | |
21 | 21 | | |
22 | | - | |
| 22 | + | |
23 | 23 | | |
24 | 24 | | |
25 | 25 | | |
| |||
55 | 55 | | |
56 | 56 | | |
57 | 57 | | |
58 | | - | |
| 58 | + | |
59 | 59 | | |
60 | 60 | | |
61 | 61 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
15 | 15 | | |
16 | 16 | | |
17 | 17 | | |
18 | | - | |
| 18 | + | |
19 | 19 | | |
20 | 20 | | |
21 | 21 | | |
| |||
77 | 77 | | |
78 | 78 | | |
79 | 79 | | |
80 | | - | |
81 | | - | |
| 80 | + | |
| 81 | + | |
82 | 82 | | |
83 | | - | |
| 83 | + | |
84 | 84 | | |
85 | | - | |
| 85 | + | |
86 | 86 | | |
87 | 87 | | |
88 | 88 | | |
89 | | - | |
| 89 | + | |
90 | 90 | | |
91 | 91 | | |
92 | 92 | | |
| |||
0 commit comments