[Marius Storhaug (MariusStorhaug)]

Repository governance guidance uses clear en-US and present-tense statements across seven policy pages and four capability pages. It explains repository context, label ownership, code-owner review, type selection, and reconciliation without idioms.

Requirements and interfaces keep their meaning. The guidance distinguishes the governance contract from evidence of deployed enforcement. No adoption action is required.

Changed: Governance guidance states its contract directly

Contributors, maintainers, and agents can read the repository rules without interpreting navigation metaphors or delivery-status language. README guidance names the repository's capabilities and links to details. Repository boundaries follow ownership, lifecycle, and branch strategy. Code-owner guidance separates permission, review assignment, and required approval.

The distribution example states only what its source documentation describes. The defaults-repository table defines the required contract, not verified deployment. The Artifact rationale explains the chosen one-commit-per-change policy without claiming that Git cannot inspect merge history. Type values, required files, inheritance rules, local-guide conditions, API methods, commands, migration safeguards, and normative requirements do not change.

Technical details

Source and scope. The fixed expectations and scoped PR base are MSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082. The final candidate is MSXOrg/docs@e978a6c10675a175d640e663f5e91bdcbb7be219, read back from local HEAD, the remote branch, and this PR. Seven small commits are pushed. The worktree is clean. The PR remains draft, unmerged, and without auto-merge. No readiness, merge, or Agent merge action is performed.

The actual Docs.yml route builds and deploys a documentation site and does not invoke Release Management. This is a scoped documentation comparison, not a release-bound artifact comparison. No release-decision block or release:* label applies.

Pinned expectations. The review uses Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, and applicable specification, design, and standard templates. The STEMG overview, FAQ, and relevant Issue 9 rules/dictionary inform the manual review. The verified PDF and extract remain local. Mechanical checks do not establish full STE conformance.

Full read and before/after evidence

All 11 owned pages were read in full before edits and are changed. There is no owned no-change path. Each target is absent in the baseline and present in the final source and rendered page article.

Fully read and changed path	Before	After
src/docs/Ways-of-Working/Automation-Labels.md	"the cheapest control surface"	"Labels let contributors give instructions to repository automation."
src/docs/Ways-of-Working/Code-Ownership.md	"looks like an access control list and behaves like a mailing list"	"CODEOWNERS assigns reviewers to repository paths. It does not grant access or require approval before merge."
src/docs/Ways-of-Working/Organization-Standard.md	"PSModule currently explores this"	"Its documentation describes a managed-file distribution design for the PSModule initiative, not the MSX-wide design."
src/docs/Ways-of-Working/Repository-Segmentation.md	"that divergence is the seam to split on"	"When any of them differ, the parts belong in separate repositories."
src/docs/Ways-of-Working/Repository-Standard.md	"first useful mental model"; "bloating the start page"	"It introduces the repository, explains its main capabilities, and links to detailed documentation."; "while the start page stays short"
src/docs/Ways-of-Working/Repository-Type-Property.md	"Nothing falls out silently."	"No repository loses coverage without an explicit exclusion."
src/docs/Ways-of-Working/Readme-Driven-Context.md	"Use examples liberally"	"Use examples when they make an explanation shorter or clearer."
src/docs/Capabilities/repository-governance/index.md	"there is nothing per repository to drift"	"Reconciliation compares each repository with the controls its type requires."
src/docs/Capabilities/repository-governance/spec.md	"Governance MUST therefore be inverted"	"A repository MUST declare its kind. The organization defines one configuration per kind."
src/docs/Capabilities/repository-governance/design.md	"compares the live world"	"Delivery records provide evidence that an implementation and its enforcement satisfy this contract."
src/docs/Capabilities/repository-governance/design-types.md	"This orthogonality is the point."	"Documentation publication and environment promotion are independent."

Technical preservation and source-qualified corrections

Manual comparison preserves ownership/permission/enforcement distinctions, all Type and legacy inventory values, release-label meanings and route scope, migration ordering and verification gates, API methods/routes, commands, inherited defaults, conditional local guides, exceptions, and direct instructions.

Mechanical comparison confirms unchanged page titles, headings/anchors, fenced examples, uppercase normative-term sequence, existing inline-identifier set, existing link destinations, generated index blocks, the complete spec FR/NFR block, complete Type tables, the community-default section, and the local contribution rule. The sole added destination is the verified canonical Distributor repository. Historical inventories and safe migration procedures retain their roles. The content-location paragraph becomes five- and two-sentence paragraphs.

The PSModule/Distributor reference resolves to MSXOrg/Distributor. Its README at 3beed03f64eeafdad1c5986a14845a2b7811f929 describes managed-file distribution for PSModule. That evidence supports a documentation example, not deployed-service or conformance claims.

The defaults source trees are pinned at MSXOrg/.github@0c67251812ea306543f3a14ab473ae357cfb76ac and PSModule/.github@4e0092de8f208b11e0d4607ced93471607aa748e. The first contains a PR-template file despite the target policy. The design therefore states the contract rather than claiming that linked repositories prove compliance. External template cleanup is excluded.

An anonymous Git-object experiment joins five feature commits and an independent main-branch change. git bisect run finds feature 3 as the first bad commit; git log v0..v1 includes all five feature changes. Verified LF fixtures and a predicate that aborts on invalid input make the result reproducible. This disproves the absolute failure explanation, not the chosen Artifact history policy. The Git bisect manual supplies command semantics. No project code or credentials are used; the temporary experiment is removed.

Validation

Check	Result at the final source
Test-first prose examples	All 11 targets are absent before and present after; all 11 render in their page articles.
Preservation and scoped diff	All 11 owned paths pass; no out-of-scope change.
Markdown	markdownlint-cli2 0.24.0, shared configuration, all 11 explicit paths, zero issues.
Relative links and anchors	Existing checker passes across 130 Markdown pages.
Cross-repository links	Existing checker resolves eight links across 134 Markdown files. A shared anonymous API limit is resolved by a passing authenticated-rate-limit rerun, not a checker change.
Pester	Existing runner, pinned Pester 6.0.1 and expected GUID; 66 passed in six suites; zero failed, skipped, inconclusive, or not-run.
Site	Exact zensical==0.0.59; final-source archive; CI index generation in an isolated copy; no build issues; 131 HTML pages. All 11 owned pages, H1s, target text, generated descriptions, and Distributor link are verified.
GitHub CI	Lint, Build, Links, Test, and Cross-repository links succeed. Publish is skipped for the PR as expected.
Draft review	Existing review script exits 0: APPROVED at the final head, zero new inline comments, clean round.

The shared installed Zensical 0.0.50 is not used as a substitute. The exact existing requirement is restored in isolated session storage without changing the manifest or shared environment. Source index tables are not regenerated or committed; only the build copy receives generated tables.

Standards and framework alignment

Changed surface	Standards checked	Framework docs checked	Result
Seven owned governance policy pages	Fixed-baseline Natural Language, Writing Guide, Markdown, Documentation, Documentation Model, standard template; official STEMG explanations and relevant Issue 9 rules/dictionary	Repository-governance spec/design/types and ownership, inheritance, contribution, and audience contracts	Fixed in this PR
Governance index and spec	Same fixed-baseline writing/model standards; specification template	Type-property mechanism and the seven policy pages; FR/NFR text retained verbatim	Fixed in this PR
Governance design and type catalog	Same fixed-baseline writing/model standards; design template	Governance spec, Type-property mechanism, repository/community-file rules, code-owner eligibility, and source-qualified examples	Fixed in this PR
Retained normative conflicts	No new policy is inferred from a prose correction	Conflicting clauses remain recorded in the Task	Exception - #247

Unresolved policy choices and exclusions

These choices remain explicit and unchanged. They need a separate policy PR, not an inferred writing decision.

Sources	Unresolved choice
Organization Standard versus Repository Standard	Initiative specialization must not contradict this site, but initiative overrides govern their repositories.
Repository Types versus Repository Standard	The Unmanaged discoverability minimum names a security policy in one place and contribution guidance in the other.
Design selection table, exclusion-only rule, Type-property guidance, and NFR5	Included-value layering selectors coexist with an exclusion-only/additive-extension contract.
FR8 versus the automated-review design row	Every-PR automatic review versus default-branch scope.

The closing Task's prose, preservation, validation, and durable-evidence steps are complete. All shared indexes, other documentation parts, functional scripts/configuration/tests, dependencies, and paths reserved by #240 remain unchanged. No repository audit/planning files, new tooling, restructuring, or external enforcement cleanup is added. No complete STE certification or deployed-reconciliation claim is made.

The scoped convergence query repo:MSXOrg/docs is:issue is:open "repository governance" in:title,body returns only the closing Task. No additional issue receives a closing link. There is no remaining blocker for this writing deliverable; this PR stays draft by request.

Related references

• Resolves [documentation-writing-alignment] Clarify repository governance contracts #247
• References Keep documentation tooling tests focused on supported behavior #240 for excluded code/test ownership

[Copilot]

🟢 Approved

No active review issues block the documentation changes clarifying repository-governance guidance.

No open issues 🎉

What changed in this PR

This documentation-only PR rewrites repository-governance guidance in direct English, clarifying existing contracts without changing live enforcement.

Changes:

• Clarifies the README’s role as a short introduction that links to detailed product documentation.
• Simplifies guidance on repository boundaries, classification, ownership, and automation labels.
• Clarifies shared controls and reconciliation requirements, distinguishing design contracts from implementation evidence.

File	Description
src/​docs/​Ways-of-Working/​Repository-Type-Property.md	Simplifies classification, migration, and ruleset coverage guidance.
src/​docs/​Ways-of-Working/​Repository-Standard.md	Clarifies README scope and documentation layout.
src/​docs/​Ways-of-Working/​Repository-Segmentation.md	States repository boundary and lifecycle criteria directly.
src/​docs/​Ways-of-Working/​Readme-Driven-Context.md	Clarifies README context, maintenance, and audience guidance.
src/​docs/​Ways-of-Working/​Organization-Standard.md	Simplifies shared governance guidance and links the Distributor example.
src/​docs/​Ways-of-Working/​Code-Ownership.md	Clarifies permissions, review assignment, and merge enforcement.
src/​docs/​Ways-of-Working/​Automation-Labels.md	Simplifies label ownership and namespace rules.
src/​docs/​Capabilities/​repository-governance/​spec.md	Restates classification requirements and success criteria directly.
src/​docs/​Capabilities/​repository-governance/​index.md	Summarizes classification, shared controls, and reconciliation.
src/​docs/​Capabilities/​repository-governance/​design.md	Clarifies control design and the reconciliation contract.
src/​docs/​Capabilities/​repository-governance/​design-types.md	Simplifies type definitions, composition, and validation guidance.

_{Review effort: Balanced}