[Marius Storhaug (MariusStorhaug)]

Dependency and CI automation guidance states the update, merge, and PowerShell contracts in direct en-US prose. Readers can distinguish an update proposal from complete adoption, a required-check report from the verification it represents, and GitHub App permissions from code ownership.

This documentation-only change requires no consumer configuration or runtime action. The PR remains draft for the documentation writing campaign.

Changed: Automation guidance states precise, evergreen contracts

The nine pages replace indirect explanations, idioms, British spelling, and delivery-plan prose. Specs retain their requirements, designs retain their mechanisms, and indexes retain their navigation role. The three-day cooldown, default-mapping omission, security bypass, release ownership, adoption evidence, merge holds, and PowerShell component boundaries remain intact.

Before	After
"Those pins age"	"A pinned version can contain a defect that a later upstream version corrects. It can also contain a known vulnerability."
"native-support catalogue" / "prioritised"	"native-support catalog" / "prioritized"
"Currency is the goal; being first is not."	"The cooldown delays a version update proposal after upstream publication."
"a person to notice a green tick"	"For an eligible, routine change, a passing result SHOULD trigger automated merge without manual status inspection."
"the check exists for free"	"Actions publishes a check run for each named job."
"previously spread across initiative-local docs"	"MSXOrg/docs owns the canonical guidance."
"Add a capability-level parity matrix with status per gap."	"A capability-level parity matrix records each gap's status and build or advocacy path."

The PowerShell design states its existing matrix, maturity, ownership, and review-cadence intent as target design responsibilities. It does not claim that those mechanisms have been implemented. Its renamed section retains the planned-evolution anchor. Required reviews remain independent of an app's review, and native auto-merge does not establish an unverified minimum permission set.

Technical details

Source identities. The fixed review and scoped PR baseline is 1b0d4893c8fefabe604d04393068a8ff6f848082 in MSXOrg/docs. The final candidate is f81425c82c1938785720e758bed67f906e38f2ef. The comparison is baseline-to-candidate, not a publication-range claim. All five logical commits are pushed. The draft was opened after the first complete dependency edit, before the remaining capability edits.

Full-read and change record. Every assigned page was read in full before editing and reviewed against its resulting contract. All nine changed; there are no unchanged owned pages.

Path	Read	Result
src/docs/Capabilities/dependency-updates/index.md	Full	Revised
src/docs/Capabilities/dependency-updates/spec.md	Full	Revised
src/docs/Capabilities/dependency-updates/design.md	Full	Revised
src/docs/Capabilities/merge-automation/index.md	Full	Revised
src/docs/Capabilities/merge-automation/spec.md	Full	Revised
src/docs/Capabilities/merge-automation/design.md	Full	Revised
src/docs/Capabilities/powershell-on-github/index.md	Full	Revised
src/docs/Capabilities/powershell-on-github/spec.md	Full	Revised
src/docs/Capabilities/powershell-on-github/design.md	Full	Revised

Preserved contracts and accepted differences. Git-blob comparisons preserve all 17 FR/NFR labels, each requirement's normative force, three fenced YAML/Mermaid examples, and three generated INDEX blocks. Existing inline configuration and permission identifiers remain intact. PowerShell's original should/must sequence changes only to uppercase normative spelling. New code formatting for Process-PSModule and relative spec/design/reference links are intentional. The only heading rename retains its old HTML anchor; the local rendered page exposes both planned-evolution and parity-gap-records. No page moves or cross-owned link repairs are required.

FR14 retains mechanism breadth: "A required PR check MUST report the evidence-verification result before the update is eligible for automatic readiness, approval, or merge." It does not require the check itself to perform verification. Missing, stale, pending, and failed results still hold the update. The three-day cooldown and exact cooldown omission/non-default semantics, schedule/timezone configuration, advisory bypass, central exceptions, complete-range evidence, independent release decision, and no-bypass merge gates retain their meaning. No PowerShell runtime requirement or execution behavior changes.

Source alignment and contradictions. The review uses the fixed-baseline Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, and specification/design templates. The official STEMG overview and FAQ were read; relevant Issue 9 rules were consulted in the verified local reference. Copies and extracted text remain local. Selected-example checks and word counts are not full STE-conformance evidence.

FR5's statement that generated configuration cannot drift conflicts with the design's explicit drift comparison. The explanation now states that generation uses supported manifests as its source; the existing SHOULD and reconciliation contract remain unchanged. The merge requirement now states its existing eligible-set restriction explicitly, consistent with the separate human-approval requirement.

The original design also overstates platform facts. GitHub's documented auto-merge workflow grants both contents and pull-request write permissions. Its GraphQL guidance requires testing selected app operations. The revised guidance does not infer a universal minimum from a user's write role or the REST merge endpoint. GitHub's CODEOWNERS rules identify users and teams with explicit write access; app installation permissions do not establish that ownership. The design therefore retains the required-review result as a separate gate. No API, permission, or runtime policy is changed. No live access experiment is run.

Changed surface	Standards checked	Framework docs checked	Result
src/docs/Capabilities/dependency-updates/**	Fixed-baseline Natural Language, Writing Guide, Markdown, Documentation	Documentation Model, specification/design templates, and owned dependency contracts	Fixed in this PR
src/docs/Capabilities/merge-automation/**	Fixed-baseline Natural Language, Writing Guide, Markdown, Documentation	Documentation Model, templates, owned merge contracts, and cited canonical GitHub facts	Fixed in this PR
src/docs/Capabilities/powershell-on-github/**	Fixed-baseline Natural Language, Writing Guide, Markdown, Documentation	Documentation Model, templates, and owned PowerShell contracts	Fixed in this PR

Verification. The test-first check reproduced eight selected prose gaps before edits; all eight are absent from the committed candidate. The nine-file scope and preservation checks pass. The working tree is clean, and the remote branch matches the candidate.

Check	Result
Local Markdown	All nine pages inspected; no issues. markdownlint-cli2 0.24.0 / markdownlint 0.42.0.
Relative links	Pass; 130 files scanned.
Cross-repository links	Pass; seven links across 134 files. An anonymous attempt reached the shared GitHub rate limit; the rerun with existing process-local authentication passed.
Existing Pester suites	66 passed across six Pester 6.0.1 suites, with no skipped or inconclusive tests. Final CI also passes all 66.
Local site and legacy anchor	Zensical 0.0.50 build passes; both design anchors render. This is supplementary, not the pinned-version result.
Final Docs CI	Success at the candidate. Lint, Links, Test, and Build pass; Publish is skipped for the PR. Build logs confirm pinned Zensical 0.0.59. MARKDOWN and NATURAL_LANGUAGE statuses are successful.
Final cross-repository CI	Success at the candidate.
Automated review	Approved at the candidate, with zero new inline comments. The standard review script exits 0.

An early CI run found one introduced terminology violation, "bug fix". The final defect/version sentence removes it. Cached local textlint 15.8.0 loads no rules, including for an anonymous counterexample, so that local attempt is not reported as a pass. The configured final CI NATURAL_LANGUAGE success provides the terminology result. No package or new tool is installed.

Scope and delivery. The Task's prose, source-review, preservation, validation, and evidence steps are complete. Shared indexes, other capability owners, process pages, executable code, configuration, tooling, and tests are excluded. The reserved files owned by #240 are unchanged. Generated INDEX content is unchanged. No repository audit/planning files, dependencies, enforcement tooling, or structure changes are added.

The issue-convergence search covers open campaign issues and the dependency/documentation, merge-automation, and PowerShell-on-GitHub terms. Only #254 is fully resolved by this focused diff; no additional closing reference applies. The effective Docs PR route does not invoke Release Management, so no release decision block or release labels apply.

No delivery blocker remains. Exact app-operation permissions and implementation enforcement are not claimed as verified runtime behavior. The PR stays draft by explicit campaign instruction. No mark-ready, merge, auto-merge, or Agent merge action is taken.

Related references

• Resolves [documentation-writing-alignment] Clarify dependency and CI automation capability guidance #254
• References fixed source baseline
• References official STEMG overview, FAQ, and Issue 9

[Copilot]

🟢 Approved

No active review issues block the documentation-only clarifications to the capability contracts.

No open issues 🎉

What changed in this PR

This documentation-only PR clarifies the dependency-update, merge-automation, and PowerShell-on-GitHub capability contracts in direct, evergreen en-US prose. It changes no executable code or consumer configuration.

Changes:

• Clarifies dependency proposals, complete consumer adoption, review gates, and independent release decisions.
• Makes merge eligibility and required-check behavior explicit, and corrects guidance on auto-merge permissions and code-owner approval.
• Refines PowerShell capability requirements, architecture descriptions, and build-versus-advocacy guidance.

File	Description
src/​docs/​Capabilities/​powershell-on-github/​spec.md	Clarifies requirements and success criteria.
src/​docs/​Capabilities/​powershell-on-github/​index.md	States capability scope and canonical documentation ownership.
src/​docs/​Capabilities/​powershell-on-github/​design.md	Refines architecture, reference links, and parity-gap records.
src/​docs/​Capabilities/​merge-automation/​spec.md	Clarifies eligibility, required checks, and human-review boundaries.
src/​docs/​Capabilities/​merge-automation/​index.md	Summarizes automated merge and hold conditions.
src/​docs/​Capabilities/​merge-automation/​design.md	Clarifies check handling, permissions, and code-owner approval.
src/​docs/​Capabilities/​dependency-updates/​spec.md	Refines coverage, cooldown, adoption, and release contracts.
src/​docs/​Capabilities/​dependency-updates/​index.md	Clarifies update scope and applicable review and release paths.
src/​docs/​Capabilities/​dependency-updates/​design.md	Clarifies updater behavior, adoption evidence, and configuration ownership.

_{Review effort: Balanced}