Repository navigation
Commit 09107c4
authored
Framework contracts use direct en-US prose (#580)
Framework maintainers get shorter, direct en-US specification and
reference prose. The existing requirements, workflow interfaces,
examples, release policy, and publication guarantees stay unchanged.
Module authors do not need to change code, settings, or caller
workflows.
<!-- ANNOUNCEMENT STOP -->
## Changed: Framework guidance states existing contracts directly
The design uses `behavior` and removes the subjective phrase `sensible
defaults`. The principles describe linear version history and colocation
without first-person narration. Reference descriptions use clear
subjects and present tense. The patch-version description states
intended compatibility instead of the absolute `no risk` promise, under
the explicit handback in #562. This is a
wording change, not a SemVer policy change or evidence of new runtime
enforcement. Procedures stay imperative.
All eleven assigned pages were read in full before editing. Nine pages
change; the normative specification and scenario matrix are intentional
no-change reviews. No proposal-only artifact-root section is imported.
The protected fingerprint mechanism and its related automation claims
remain unchanged for #577. The mock-policy and
major-policy decisions remain separate.
<details>
<summary>Technical details</summary>
### Source and delivery identities
- Fresh-main PR base:
`PSModule/Process-PSModule@64ffb1d`.
- Pushed candidate:
`PSModule/Process-PSModule@b8a2e4f`,
branch `framework-contract-prose`, base branch `main`.
- [Complete scoped
comparison](64ffb1d...b8a2e4f):
nine Markdown files, 47 insertions and 51 deletions. No other repository
path changes.
- The draft opened after the first real slice,
`9ba4a606ca4a6aa2e460b8e994c9fdc9eff82631`. Small follow-ups are
`769fad09b875efec70c2fc6199f9a9c53297990f`,
`30d6bc69fcf8ff9c0673e8c055a3b35927f69276`, and
`b8a2e4ff2056409f89289a3209f5b08c3ad42031`. No old proposal or
first-pass PR is amended.
- Current source and issue-body ownership were rechecked before each
commit. Main remained at the released source. The separate
#541 head remains
`2001551566898e59efc764e68450c2238667d607` on
`complete-artifact-path-isolation`; its proposal and owner branch are
untouched. The recorded issue handback is the authority for existing
pipeline prose, not permission to import that proposal's additions.
### Writing sources
The fixed baseline is
`MSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs`:
[Documentation
Model](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Documentation-Model.md),
[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),
and the applicable specification/design/reference/standard
[templates](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md).
Their artifact distinctions remain intact; no template scaffolding is
added.
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](https://doi.org/10.5281/zenodo.23666006) rules were read. Issue 9
rules 3.2, 3.6, 4.1-4.2, and 6.1-6.6 informed tense, active voice, short
complete sentences, and descriptive paragraphs. The locally retained
official PDF MD5 is `9c720341c350ed77943b2c73d01c716f`, matching the
official record. No manual content is republished. The bounded review
and scans do not certify full ASD-STE100 conformance.
### Complete reviewed scope and before/after evidence
All paths below are under `docs/content/`. The before text comes from
the immutable PR base above; the after text is in the pushed candidate.
Natural Language supplies en-US and direct language, the Documentation
Model preserves normative contracts without implying implementation, and
STE guidance supplies short complete sentences and active descriptive
language.
| Page | Review | Concrete before to after | Preserved distinction |
| --- | --- | --- | --- |
| `specification/index.md` | Changed | `aimed at people maintaining
Process-PSModule itself` to `for maintainers of Process-PSModule` |
Maintainer/module-author roles, `normally`, and both reader links
remain. |
| `specification/spec.md` | No change, whole page exact | FR1 still says
`The pipeline MUST compile the PowerShell module source code into a
module artifact` | Every requirement, modality, FR/NFR ID, scenario, and
publication/quality guarantee stays exact. A requirement is not CI
evidence. |
| `specification/design.md` | Changed | `behaviour` to `behavior`;
`everything else uses sensible defaults` to `Other settings use
defaults` | Same reusable entry point, caller/settings contract, phase
roles, runtime enrichment, release decisions, and alternatives. |
| `specification/principles-and-practices.md` | Changed | `we only
maintain a single linear ancestry of versions` to `maintains one linear
version history` | Latest-only maintenance; the `2.1.3` security fix
does not go to 1.x. Dependency declarations and parameter descriptions
retain their colocation examples and exact code tokens. |
| `reference/pipeline-stages.md` | Changed | `report that is used by ...
evaluate the results` to `report that ... uses to evaluate the test
results` | Same report consumer, stage names/order, coverage, root-only
phases, runtime paths, publication/cleanup guarantees, and artifact
behavior. |
| `reference/powershell-module-standard.md` | Changed | `resource or
behaviour groups` to `resource or behavior groups`; `knobs` to `inputs`
| Layout rules, normative force, test IDs, discovery precedence,
examples, mock requirements, version resolution, and publication
sequence remain. |
| `reference/repository-standard.md` | Changed | `operates at the same
altitude as` to `complements`; `then points` to `then point` | Unchanged
MSX rules still apply. Module and non-module scope, both baseline
expectations, required files, ownership, examples, and attribution
requirements remain. |
| `reference/scenario-matrix.md` | No change, whole page exact | The
scenario table, conditional cells, and all four footnotes stay exact |
Important-change gates, SHA matching, manual Patch releases,
cleanup-only closed PRs, and stable cleanup retries remain. |
| `reference/settings.md` | Changed | `By default, it will look for` to
`The default path is` | Same JSON/YAML/PSD1 formats,
`.github/PSModule.yml` default, authorable/runtime boundary, and
complete settings/default tables and example. |
| `reference/versioning.md` | Changed with protected regions | `with no
risk of breaking functionality` to `intended to preserve compatibility`
| Same major/minor/patch/no-bump classifications, optional/required
parameter distinctions, examples, quoted sources, latest-only policy,
and protected automation text. |
| `reference/workflow-inputs.md` | Changed | `For how to wire it up` to
`For caller configuration` | Exact inputs/defaults, four declared
secrets, required flags, GitHub-token/App permission distinction, and
permission example remain. |
The two no-change Git blob identities are exact on base and head:
`specification/spec.md` is `5755abf2797a699e0ef0846ac2521cb1fb90b2bb`;
`reference/scenario-matrix.md` is
`d9c5490f5379fe94adf94df6ac349dfc0b82b8d1`.
### Preservation results
Pre-edit session evidence records concrete original text, its expected
wording property, and source-backed acceptance before repository edits.
Nine intended wording cases fail on the original source; all eleven
page-level cases pass on the pushed candidate, including the two
no-change cases. The session-only comparison reports zero preservation
failures.
| Checked surface | Result |
| --- | --- |
| Source structure | All 120 headings, 11 explicit anchors, eight
front-matter titles, and 11 requirement IDs preserved exactly and in
order. |
| Normative/interface tokens | All 144 requirement-modal tokens, 652
inline-code spans, 269 numeric literals, 233 table rows, and 148 bold
labels preserved exactly and in order. |
| Code and examples | All 22 fenced examples and every inline code
example preserved exactly. Another 43 example-bearing paragraphs remain
text-exact. The three narrative examples in principles use shorter prose
with the same scenarios and exact literals. No example is removed. |
| Source links and quotations | All 134 source link targets and seven
quoted spans preserved exactly. No external quotation, legal text, or
actual attribution is rewritten. |
| Rendered site | All 317 rendered anchor IDs and 1,055 rendered link
targets across the eleven built pages match the pre-edit site baseline.
This is preservation evidence, not an external-reachability audit. |
| Protected passages | All 13 selected policy/automation/contract
passages remain text-exact after line-ending normalization. |
| Supported behavior | Hunk review preserves supported roles,
compatibility classifications, inputs/defaults, publication/recovery
guarantees, dependency order, runner-only exceptions, and literal
identifiers. No wording claims new shipping or CI enforcement. |
The protected passages include the public-API major policy,
latest-version support policy, API-fingerprint section, both related
automation-claim paragraphs, mocked-environment requirement,
module-owned boundary-mock rule, linear maintenance policy, version
resolution/publication sequence, pipeline runtime contract, root-only
phase/discovery rules, framework-generated coverage guarantee, and
stable publication/cleanup section. The fingerprint source is blob
`ee2eafdd83405ab42da7a25aa5f6e9ff367e6d5e`, base lines 127-155; its
section SHA-256 remains
`fb098e0eea00a129b7f87f13806acc104de6ad47439769355d2d2c8fcf824e23`.
The selected main pipeline page contains neither a Consumer artifact
root section nor a `<WorkingDirectory>/.PSModule/` token. Both remain
absent. Existing paths are unchanged; no unmatched proposal content or
runner-only exception is added, removed, or reinterpreted.
### Existing checks and accepted review
The existing repository Markdown configuration passes on all eleven
explicit paths, before edits and on the completed source:
```powershell
npx --no-install markdownlint-cli2 --config .github\linters\.markdown-lint.yml docs\content\specification\index.md docs\content\specification\spec.md docs\content\specification\design.md docs\content\specification\principles-and-practices.md docs\content\reference\pipeline-stages.md docs\content\reference\powershell-module-standard.md docs\content\reference\repository-standard.md docs\content\reference\scenario-matrix.md docs\content\reference\settings.md docs\content\reference\versioning.md docs\content\reference\workflow-inputs.md
```
Result: 11 files, 0 issues. An initial Windows wildcard invocation
selected only seven files; it was corrected to the explicit eleven-file
command above, not treated as full-scope evidence.
The existing site command, `zensical build --clean` from `docs`, passes
before and after the changes with `No issues found`. `git diff --check`
passes for the complete base-to-head change. The session-only
preservation/wording command also passes at exact pushed head
`b8a2e4ff2056409f89289a3209f5b08c3ad42031`.
No standalone documentation-link checker is present in this main tree.
The link-check scripts named in the MSX Markdown standard belong to the
MSX docs repository, not this repository. No dependency was installed;
no enforcement tool, prose/inventory/implementation-shape snapshot test,
or repository audit document is added.
All six applicable hosted checks succeed at the exact candidate: Docs
Build and Lint, repository Lint code base, CodeQL, Actions analysis, and
Copilot review. Publication is skipped as expected on the draft. Copilot
review was explicitly requested with the CLI-supported `@copilot` value.
Its [completed
review](#580 (review))
is `APPROVED` at `b8a2e4ff2056409f89289a3209f5b08c3ad42031`, with no
inline comments or active issues. [Docs
run](https://github.com/PSModule/Process-PSModule/actions/runs/41842157105),
[repository lint
run](https://github.com/PSModule/Process-PSModule/actions/runs/41842157084),
and [hosted review
run](https://github.com/PSModule/Process-PSModule/actions/runs/41842463614)
retain the results.
The coordinating parent also accepted the content at this exact head
after independently reading all nine changed-page diffs and comparing
all eleven pages. Its comparison preserves headings, inline literals,
destinations, fences, table rows, modality sequences, the fingerprint
section and related automation text, and mocked-environment
requirements. This records content acceptance only; the PR remains draft
and no readiness or merge action is authorized.
### Alignment and residual decisions
| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| Specification index, design, and principles | Fixed MSX
writing/Markdown and specification/design templates; STE clarity
principles | Entire released spec/design/principles set | Aligned within
released linguistic scope; normative spec unchanged. |
| Pipeline, settings, and workflow-input references | Fixed MSX
writing/Markdown and reference template | Existing stage/runtime/caller
contracts and scenario matrix | Aligned; all contract tables/examples
and protected guarantees unchanged. |
| Module and repository standards | Fixed MSX writing/Markdown and
standard template | Layout, repository roles, test, version, and
publishing guidance | Aligned; mock-policy conflict remains
#563. |
| Versioning reference | Fixed MSX writing/Markdown and
reference/standard templates | SemVer classifications and released
no-risk wording exception | Aligned within handback; fingerprint truth
and core/major-policy conflicts remain #577 and
#573. |
The delivery issue's pre-edit read, expectations, baseline, small-commit
wording, ownership-recheck, and local current-head validation steps are
complete. The scoped convergence sweep covered open
`documentation-writing-alignment` issues, the protected follow-ups, the
eleven owned paths, and the disjoint first-pass PR paths. No additional
issue is closed by this bounded prose change.
Residual decisions are precise: #577 reconciles
the unsupported fingerprint mechanism and related claims with the real
resolver after
#359/#524 producer
decisions; #563 decides mock policy by test
category; #573 decides bootstrap-core versus
complete-public-API major policy. No runtime, framework upgrade, site
redesign, release-label, readiness, merge, or automation change is made.
This PR stays draft.
</details>
<details>
<summary>Related references</summary>
- Resolves #562.
- References #577, with
#359 and #524 as
producer context.
- References #563 and
#573 for the separate policy decisions.
- References #541 for the separate
pipeline-prose handback; its proposal and branch stay unchanged.
</details>1 parent bc376d0 commit 09107c4
9 files changed
Lines changed: 47 additions & 51 deletions
File tree
- docs/content
- reference
- specification
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
8 | | - | |
9 | | - | |
10 | | - | |
| 8 | + | |
11 | 9 | | |
12 | | - | |
| 10 | + | |
13 | 11 | | |
14 | 12 | | |
15 | 13 | | |
16 | 14 | | |
17 | 15 | | |
18 | | - | |
19 | | - | |
20 | | - | |
| 16 | + | |
| 17 | + | |
21 | 18 | | |
22 | 19 | | |
23 | 20 | | |
| |||
65 | 62 | | |
66 | 63 | | |
67 | 64 | | |
68 | | - | |
| 65 | + | |
69 | 66 | | |
70 | 67 | | |
71 | 68 | | |
| |||
75 | 72 | | |
76 | 73 | | |
77 | 74 | | |
78 | | - | |
| 75 | + | |
79 | 76 | | |
80 | 77 | | |
81 | 78 | | |
| |||
84 | 81 | | |
85 | 82 | | |
86 | 83 | | |
87 | | - | |
| 84 | + | |
88 | 85 | | |
89 | 86 | | |
90 | 87 | | |
| |||
106 | 103 | | |
107 | 104 | | |
108 | 105 | | |
109 | | - | |
| 106 | + | |
110 | 107 | | |
111 | 108 | | |
112 | 109 | | |
| |||
116 | 113 | | |
117 | 114 | | |
118 | 115 | | |
119 | | - | |
| 116 | + | |
120 | 117 | | |
121 | 118 | | |
122 | 119 | | |
| |||
126 | 123 | | |
127 | 124 | | |
128 | 125 | | |
129 | | - | |
| 126 | + | |
130 | 127 | | |
131 | 128 | | |
132 | 129 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
44 | 44 | | |
45 | 45 | | |
46 | 46 | | |
47 | | - | |
| 47 | + | |
48 | 48 | | |
49 | 49 | | |
50 | 50 | | |
| |||
65 | 65 | | |
66 | 66 | | |
67 | 67 | | |
68 | | - | |
| 68 | + | |
69 | 69 | | |
70 | 70 | | |
71 | 71 | | |
| |||
79 | 79 | | |
80 | 80 | | |
81 | 81 | | |
82 | | - | |
| 82 | + | |
83 | 83 | | |
84 | | - | |
| 84 | + | |
85 | 85 | | |
86 | 86 | | |
87 | 87 | | |
| |||
91 | 91 | | |
92 | 92 | | |
93 | 93 | | |
94 | | - | |
| 94 | + | |
95 | 95 | | |
96 | 96 | | |
97 | 97 | | |
| |||
| 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 | 9 | | |
10 | 10 | | |
| |||
17 | 17 | | |
18 | 18 | | |
19 | 19 | | |
20 | | - | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
21 | 23 | | |
22 | 24 | | |
23 | 25 | | |
| |||
306 | 308 | | |
307 | 309 | | |
308 | 310 | | |
309 | | - | |
| 311 | + | |
310 | 312 | | |
311 | 313 | | |
312 | 314 | | |
| |||
357 | 359 | | |
358 | 360 | | |
359 | 361 | | |
360 | | - | |
| 362 | + | |
361 | 363 | | |
362 | 364 | | |
363 | 365 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
8 | | - | |
9 | | - | |
| 8 | + | |
| 9 | + | |
10 | 10 | | |
11 | 11 | | |
12 | 12 | | |
| |||
0 commit comments