From 7001658632820bfb319e615253ec9ebf0da9178c Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 31 Oct 2026 17:21:58 +0100 Subject: [PATCH 1/3] Make local community guidance conditional on repository needs --- .../repository-governance/design-types.md | 5 ++ .../repository-governance/design.md | 25 +++++++--- .../repository-governance/spec.md | 2 +- .../Ways-of-Working/Organization-Standard.md | 46 ++++++++++-------- .../Ways-of-Working/Repository-Standard.md | 47 ++++++++++++------- 5 files changed, 80 insertions(+), 45 deletions(-) diff --git a/src/docs/Capabilities/repository-governance/design-types.md b/src/docs/Capabilities/repository-governance/design-types.md index bbaa789..f939979 100644 --- a/src/docs/Capabilities/repository-governance/design-types.md +++ b/src/docs/Capabilities/repository-governance/design-types.md @@ -127,6 +127,11 @@ leave a repository unclassified, and an unclassified repository is indistinguishable from a forgotten one. With it, the exemptions are a list that can be reviewed, questioned, and shortened. +Contribution guidance follows the same +[conditional local-file rule](../../Ways-of-Working/Repository-Standard.md#contribution-guidance) +as governed repositories. Supported community guidance may be inherited; its +availability does not require a repository-local copy. + An archive, a scratch mirror, or a repository whose content is generated wholesale by another system are the shapes this fits. A repository people actively develop in is not. diff --git a/src/docs/Capabilities/repository-governance/design.md b/src/docs/Capabilities/repository-governance/design.md index 57fd91b..ca535f5 100644 --- a/src/docs/Capabilities/repository-governance/design.md +++ b/src/docs/Capabilities/repository-governance/design.md @@ -105,10 +105,18 @@ the same structure: | `README.md`, `AGENTS.md`, client routes, `.gitattributes`, and `.gitignore` | Required locally | Explain and govern the defaults repository; they are not organization defaults. | All inherited community files live under `.github/` in the defaults repository -so their scope is visible from their path. A local file in a target repository -takes precedence and therefore records a deliberate repository exception. If a -target defines any local issue-template set, it owns that complete set rather -than combining local and central forms. +so their scope is visible from their path. Validate required defaults in that +source repository, not by requiring consumer copies. A target retains a local +community file only for genuine repository-specific content or a documented +exception under [Organization Standard](../../Ways-of-Working/Organization-Standard.md#community-files-are-organization-defaults). +If a target defines any local issue-template set, it owns that complete set +rather than combining local and central forms. + +[GitHub's fallback](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file) +exposes supported defaults without placing them in consumer clones, packages, +or downloads. Consumer checks resolve the effective contribution guidance from +the local guide when needed or the shared source; absence of an unnecessary +local copy is not drift. The defaults repository does not centralize repository ownership, dependency updates, release configuration, license terms, or other repository-specific @@ -133,8 +141,10 @@ names. ## Required files by type The [Repository Standard](../../Ways-of-Working/Repository-Standard.md#required-files) -owns the file list and which type adds to it. This design owns only the -enforcement: presence is checked by reconciliation on the default branch, at +owns the file list, its conditional contribution rule, and which type adds to +it. This design owns only the enforcement: reconciliation checks required local +files on the default branch and resolves effective contribution guidance under +the [contribution rule](../../Ways-of-Working/Repository-Standard.md#contribution-guidance), at **Block** severity for the files that make a repository contributable and **Report** severity for the rest. @@ -162,7 +172,8 @@ the contract below, not the implementation that satisfies it. | Exemption is justified | Does an exempted repository carry a recorded reason? | | Rulesets apply | Do the rulesets the type implies actually evaluate against this repository? | | Branch shape matches | Do the protected branches, merge methods, and required checks match what the type declares? | -| Required files present | Does the default branch carry the governed baseline and the files its type adds, or the explicit Unmanaged discoverability minimum? | +| Required local files present | Does the default branch carry the locally required baseline and type-specific files, or the explicit Unmanaged discoverability minimum, including a local contribution guide only when needed? | +| Contribution guidance available | Does effective local or shared contribution guidance resolve, with required organization defaults validated in their source repository rather than copied into consumers? | ### Severity decides the response diff --git a/src/docs/Capabilities/repository-governance/spec.md b/src/docs/Capabilities/repository-governance/spec.md index 4d968c3..dda582a 100644 --- a/src/docs/Capabilities/repository-governance/spec.md +++ b/src/docs/Capabilities/repository-governance/spec.md @@ -63,7 +63,7 @@ subject to the same baseline, regardless of type: - **FR7 — Required checks gate the merge.** A pull request MUST NOT be mergeable until the checks its type declares have passed. - **FR8 — A review is requested automatically.** Every pull request MUST have a review requested without the author asking. Whether that review *gates* the merge is a separate rule ([the review gate](#the-review-gate)). - **FR9 — Merged branches are deleted.** The repository-level `delete_branch_on_merge` setting MUST delete the head branch of a merged pull request automatically. A protected branch MUST NOT be deleted by this setting. -- **FR10 — Contribution rules are present.** Every governed repository MUST carry the [required files](../../Ways-of-Working/Repository-Standard.md#required-files) its type declares, so a contributor arriving at the repository can act without leaving it. +- **FR10 — Contribution rules are present.** Every governed repository MUST carry the [required local files](../../Ways-of-Working/Repository-Standard.md#required-files) its type declares and expose discoverable [contribution guidance](../../Ways-of-Working/Repository-Standard.md#contribution-guidance), inherited or repository-specific under that rule. ### The review gate diff --git a/src/docs/Ways-of-Working/Organization-Standard.md b/src/docs/Ways-of-Working/Organization-Standard.md index fa63ff6..006d9b8 100644 --- a/src/docs/Ways-of-Working/Organization-Standard.md +++ b/src/docs/Ways-of-Working/Organization-Standard.md @@ -49,8 +49,9 @@ These standards must be written down before broad alignment work starts. File al Community policies are organization-wide commitments, not repository-specific configuration. Each initiative organization MUST provide its code of conduct, security policy, support policy, and pull request template as defaults in its -special `.github` repository. These defaults apply whenever a repository does -not need a documented local exception. +special `.github` repository. Ordinary repositories inherit these defaults +unless genuine repository-specific content or a documented exception requires +a local community file. Store every organization community default under the `.github/` directory of the special `.github` repository: @@ -62,22 +63,25 @@ the special `.github` repository: | `.github/SUPPORT.md` | Defines where users ask for help. | | `.github/pull_request_template.md` | Scaffolds pull requests in the organization's required format. | -A repository MAY carry a local copy only when it needs a material, -repository-specific exception. The local copy takes precedence, so the -exception and its owner MUST be documented in the initiative guidance. +A repository MAY retain a local community file only for genuine +repository-specific content or a documented policy exception. The local file +takes precedence. A policy exception and its owner MUST be documented in the +initiative guidance; repository-specific contribution instructions follow the +[conditional contribution rule](Repository-Standard.md#contribution-guidance). An organization MAY also provide optional defaults in the same repository: | File or directory | Purpose | | --- | --- | -| `.github/CONTRIBUTING.md` | Provides organization-wide contribution guidance that repositories can inherit or use as the source for their local contribution guide. | +| `.github/CONTRIBUTING.md` | Provides organization-wide contribution guidance inherited where no local contribution guide is needed. | | `.github/ISSUE_TEMPLATE/` | Provides shared issue forms and template configuration for consistent issue intake. | -These optional defaults are subscriptions, not additional repository baseline -files. A repository-local contribution guide remains required where the -[Repository Standard](Repository-Standard.md#required-files) calls for -repository-specific build, test, or contribution instructions. A repository MAY -provide local issue templates when it needs a documented local variation. +These defaults are optional for the organization to supply, not additional +files for consumers to copy or subscribe to. When supplied, they apply through +GitHub's fallback. Local contribution guidance follows +[Repository Standard](Repository-Standard.md#contribution-guidance). A repository +MAY provide local issue templates for genuine repository-specific intake or a +documented exception. The same repository MAY publish `profile/README.md` as the public organization profile and MAY keep its supporting assets under `media/`. Neither surface is @@ -95,17 +99,17 @@ owns the complete structure and distribution behavior. ## Repository-local context is the enforceable surface Every ordinary repository still carries the context that cannot be inferred -from an organization default: its `README.md`, `.github/CONTRIBUTING.md`, and -`AGENTS.md` with its client routes. The contribution guide tells humans and -agents how the organization defaults apply and where the central pull request -template lives. Automation configuration, ownership, and repository-specific -legal terms also remain repository-local where the +from an organization default: its `README.md` and `AGENTS.md` with its client +routes. A local contribution guide carries only needed repository-specific +instructions or a documented exception; inherited guidance does not require a +local file. Automation configuration, ownership, and repository-specific +legal terms remain repository-local where the [Repository Standard](Repository-Standard.md) requires them. The special `.github` repository uses the purpose-specific baseline above. ## Managed files -Shared files should be managed from a central source and delivered to repositories through pull requests. Direct pushes to repository default branches are not the standard path. +Centrally managed repository-local files are delivered through pull requests. Organization community defaults are reviewed in their source repository and inherited, not distributed as local copies. Direct pushes to repository default branches are not the standard path. A managed-file system must: @@ -131,9 +135,11 @@ Organizations must distinguish mandatory files from optional or type-specific fi | Repository-specific | Local files that are intentionally owned by one repository and not managed centrally. | Repository-local context, dependency updates, ownership, license terms, and -type-specific files are candidates for mandatory file sets. Organization -community defaults are mandatory at the organization level; repositories use -them through GitHub's fallback unless they have a documented exception. Linter +type-specific files are candidates for mandatory file sets. Contribution files +follow the conditional rule rather than an unconditional local-file requirement. +Required organization community defaults are mandatory in their source home; +repositories use supplied defaults through GitHub's fallback unless local content +is needed under the community-file rule above. Linter settings, agent instructions, and workflow defaults may be global or type-specific depending on the initiative. diff --git a/src/docs/Ways-of-Working/Repository-Standard.md b/src/docs/Ways-of-Working/Repository-Standard.md index 1bbc6b9..ca98155 100644 --- a/src/docs/Ways-of-Working/Repository-Standard.md +++ b/src/docs/Ways-of-Working/Repository-Standard.md @@ -17,15 +17,16 @@ Which natural language each repository artifact is written in follows [Natural L ## Required files -Every governed repository must carry the files that make it understandable and -governable on its own. An Unmanaged repository carries the explicit -discoverability minimum defined below instead. +Every governed repository must provide the local files and discoverable +contribution guidance below. Supported organization community defaults meet +their guidance requirements without repository-local copies. An Unmanaged +repository follows the explicit discoverability minimum defined below instead. | File | Requirement | | --- | --- | | `README.md` | Acts as the repository start page: purpose, target audience, value, access, first mental model, and where to go next. | | `LICENSE` | States the legal terms for reuse and redistribution. | -| `.github/CONTRIBUTING.md` | Explains how to contribute, including how the organization defaults and central pull request template apply. | +| `.github/CONTRIBUTING.md` | Required locally only for repository-specific instructions or a documented exception; otherwise use shared guidance. See [Contribution guidance](#contribution-guidance). | | `AGENTS.md` and its client routes | Route every agent runtime from this repository's own files outward to the initiative and central documentation. [Agentic Development](../Capabilities/agentic-development/design.md#client-behavior) names the files and the path each one sits at. | | `.github/dependabot.yml` | Configures platform-native dependency-update pull requests for supported ecosystems. The `github-actions` ecosystem is expected in virtually every repository; an unsupported ecosystem follows the centrally managed exception path rather than a repository-local updater. | | `.github/CODEOWNERS` | Routes reviews to responsible owners. | @@ -35,8 +36,9 @@ discoverability minimum defined below instead. The organization provides `CODE_OF_CONDUCT.md`, `SECURITY.md`, `SUPPORT.md`, and `.github/pull_request_template.md` as GitHub community defaults. It MAY also provide `.github/CONTRIBUTING.md` and `.github/ISSUE_TEMPLATE/` as -optional defaults. Do not copy any of these organization defaults into a -repository unless it needs a documented local exception; see +optional defaults. Retain local community files only for genuine +repository-specific content or a documented exception; do not copy shared +defaults solely to make them appear in the checkout. See [Organization Standard](Organization-Standard.md#community-files-are-organization-defaults). The special organization `.github` repository uses the purpose-specific file @@ -50,7 +52,8 @@ Repository types may require additional files. For example, a PowerShell module ### Required files by type -The table above is the mandatory set for every governed repository. A +The table above is the baseline for every governed repository, including the +conditional contribution-guide requirement. A [repository type](../Capabilities/repository-governance/design-types.md) adds to that set; no governed type subtracts from it. `Unmanaged` is the explicit full-governance exemption: it is audited only for the discoverability minimum @@ -62,16 +65,25 @@ stated below, not for the governed baseline. | **Artifact** | The artifact's own manifest or metadata file — whatever declares its identity to the ecosystem it publishes into — and a changelog where the ecosystem expects one rather than reading [GitHub Releases](../Capabilities/release-management/design-publishing-targets.md). | | **Infrastructure** | Documentation of each environment the repository deploys to and how a change reaches it, plus the promotion automation the [promotion flow](../Capabilities/repository-governance/design-types.md#infrastructure) requires. | | **Docs** | The documentation source root and the build configuration the documentation-build check runs. | -| **Unmanaged** | Nothing — but the exemption does not extend to discoverability: `README.md`, `.github/CONTRIBUTING.md`, and the agent router remain required, because a repository nobody governs is still a repository someone will open. | +| **Unmanaged** | Nothing — but the exemption does not extend to discoverability: `README.md`, discoverable [contribution guidance](#contribution-guidance), and the agent router remain required. A local contribution file follows the same conditional rule. | The set a governed repository is audited against is the mandatory set plus the additions of every type it declares; an Unmanaged repository is audited only -against its discoverability minimum. Presence is verified by +against its discoverability minimum. Required local files and effective +contribution guidance are verified by [reconciliation](../Capabilities/repository-governance/design.md#required-files-by-type), not by review. The agent-file row is the one entry this table does not spell out in full. [Agentic Development](../Capabilities/agentic-development/design.md#client-behavior) owns that set — one router at the repository root, plus a route for every client that reads a different filename — and the [agentic development spec](../Capabilities/agentic-development/spec.md) limits what a route may contain: a pointer to the router and, at most, genuinely runtime-specific configuration such as permission scopes, never a reading order, a workflow, or a standard. A repository is audited against that one list, so a second copy here would be a second list to keep in step. +### Contribution guidance + +Every repository MUST make its contribution process discoverable. Use the organization contribution default when supplied; otherwise link to the shared [Contribution Workflow](Contribution-Workflow.md). + +A local `.github/CONTRIBUTING.md` is required only for genuine repository-specific build, test, or contribution instructions, or a documented exception. The local guide describes those instructions and links to shared policy. Do not create a local file solely to repeat shared policy or point to it. + +Repository-specific instructions that follow shared policy are not a policy exception. A local policy exception follows the reason and owner requirements in [Organization Standard](Organization-Standard.md#community-files-are-organization-defaults). + ## README defaults The README is the repository start page. It brings a reader in, gives them the first useful mental model, and then points them to the right deeper surface. It must be short enough to stay current and specific enough that a human or agent can understand the repository before reading source code. @@ -88,10 +100,10 @@ A README answers these questions, in this order: | How do I get more info? | Point to the documentation surface that owns the details. | Do not use the README as a community-file index. Assume readers can find the -organization's standard community defaults and repository-local files such as -`LICENSE` and `.github/CONTRIBUTING.md` through GitHub's UI and repository -conventions. The README should mention them only when the repository has an -unusual rule that readers must know before using the product. +organization's standard community defaults, including inherited contribution +guidance, and repository-local files such as `LICENSE` through GitHub's UI and +repository conventions. The README should mention them only when the repository +has an unusual rule that readers must know before using the product. Do not repeat repository-sidebar information in prose. If GitHub already exposes the repository description, deployments, releases, or site URL, the README may rely on those surfaces unless the information is necessary to answer the start-page questions. @@ -109,7 +121,7 @@ Default expectations by repository type: | Libraries, services, CLIs, and applications | Product docs live under `docs/` and are published when the product needs more than a small README. | | GitHub Actions | The README is the main documentation surface because GitHub Actions users expect inputs, outputs, permissions, and examples next to `action.yml`. | | Reusable workflows | The README is the main documentation surface because callers need workflow interface, permissions, secrets, and examples in the repository. | -| Documentation repositories | The published site is the product. The repository README explains what the source repository is and how it is laid out, and points to `.github/CONTRIBUTING.md` for the authoring conventions and the local build. | +| Documentation repositories | The published site is the product. The repository README explains what the source repository is and how it is laid out, and points to repository-specific authoring and build guidance in a local contribution guide when needed. | Documentation content lives in one folder, never spread across the repository root. A repository whose product is content — a documentation site, a reference collection, an archive of external material — keeps that content under a single documentation root: `docs/` by default, or a generator's source root such as `src/docs/` when the site tooling needs one. The repository root stays reserved for the README, the tooling, and the governance files, so a reader can tell content from machinery without opening a folder. @@ -177,9 +189,10 @@ Default title pattern: Use [PR Format](PR-Format.md) for audience-based change classification and the complete description structure, including its required consumer evidence and ending blocks. A PR closes one scoped Task or Bug, with any additional closing links limited to issues the session-end convergence sweep shows are fully delivered by the same diff. The organization-level `.github` repository supplies the default template. -The repository-local contribution guide directs humans and agents to the -organization template and its required format. A repository carries a local -template only for a documented exception. +The contribution guidance, inherited or repository-specific, directs humans and +agents to the organization template and the canonical format. The inherited template is a +scaffold; PR Format remains authoritative. A repository carries a local template +only for a documented exception. ## Managed files From 3487d8e4cea92fbef1ae78ed162bbe22ed457ae4 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 31 Oct 2026 17:25:07 +0100 Subject: [PATCH 2/3] Route readers and agents to applicable contribution guidance --- .../agentic-development/AGENTS.template.md | 11 ++++++++++- src/docs/Capabilities/agentic-development/design.md | 12 +++++++----- .../Ways-of-Working/Definition-of-Ready-and-Done.md | 7 +++++++ src/docs/Ways-of-Working/Readme-Driven-Context.md | 2 +- .../Workflow-Stages/Maintain-Guidance.md | 2 +- 5 files changed, 26 insertions(+), 8 deletions(-) diff --git a/src/docs/Capabilities/agentic-development/AGENTS.template.md b/src/docs/Capabilities/agentic-development/AGENTS.template.md index 7ba9c74..4f8c651 100644 --- a/src/docs/Capabilities/agentic-development/AGENTS.template.md +++ b/src/docs/Capabilities/agentic-development/AGENTS.template.md @@ -30,7 +30,7 @@ pointers to canonical documentation pages. Read in this order: 1. `README.md` — what this repository is and how it builds. -2. `.github/CONTRIBUTING.md` — how a change is made and reviewed here. +2. `.github/CONTRIBUTING.md` — repository-specific contribution instructions, when present. 3. `docs/index.md` — this repository's own documentation. 4. [MSXOrg/docs](https://github.com/MSXOrg/docs/) — the organization standards. @@ -39,3 +39,12 @@ Clone each linked repository locally, keep its configuration local to that clone, and update it before reading it. ```` + +Tailor the entries to real destinations. Keep the local contribution entry only +[when a local guide is needed](../../Ways-of-Working/Repository-Standard.md#contribution-guidance); +otherwise replace it with a link to the organization default at its source. If +the organization supplies no contribution default, link to the shared +[Contribution Workflow](../../Ways-of-Working/Contribution-Workflow.md). +Inherited community files are not included in clones, so a router uses a source +link rather than a nonexistent local path. Do not create a local contribution +file solely to fill the template. diff --git a/src/docs/Capabilities/agentic-development/design.md b/src/docs/Capabilities/agentic-development/design.md index 322a338..2273c85 100644 --- a/src/docs/Capabilities/agentic-development/design.md +++ b/src/docs/Capabilities/agentic-development/design.md @@ -52,7 +52,7 @@ Product repositories carry local context and thin pointers: .claude/ CLAUDE.md # required: routes Claude Code — @../AGENTS.md .github/ - CONTRIBUTING.md # how a change is made here + CONTRIBUTING.md # conditional: repo-specific instructions or exception copilot-instructions.md # required: routes the Copilot surfaces that need it instructions/ .instructions.md # exceptional: a path-scoped local caveat @@ -60,7 +60,9 @@ Product repositories carry local context and thin pointers: docs/ # architecture and domain context ``` -The repository owns only repository-specific nuance, and each kind has a file that owns it: `README.md` for what the repository is and how it builds, `.github/CONTRIBUTING.md` for contribution mechanics, `docs/` for architecture and domain context, and path-scoped rule files for local caveats. `AGENTS.md` points at them and holds none of it. Cross-cutting standards remain in `docs`. Thin means "no duplicated reusable process," not "discard the local operating contract" — the contract lives, it just lives in the file a human would read. +The repository owns only repository-specific nuance, and each kind has a file that owns it: `README.md` for what the repository is and how it builds, `.github/CONTRIBUTING.md` for contribution mechanics [when a local guide is needed](../../Ways-of-Working/Repository-Standard.md#contribution-guidance), `docs/` for architecture and domain context, and path-scoped rule files for local caveats. `AGENTS.md` points at them and holds none of it. Cross-cutting standards remain in `docs`. Thin means "no duplicated reusable process," not "discard the local operating contract" — the contract lives, it just lives in the file a human would read. + +Inherited community files are not included in clones. When no local contribution guide is needed, the router links to the organization's contribution default at its source. If the organization supplies no contribution default, link to the shared [Contribution Workflow](../../Ways-of-Working/Contribution-Workflow.md). Do not create a local guide merely to fill a router entry. ## OKF page model @@ -112,7 +114,7 @@ flowchart TD msx --> refresh["Synchronize selected docs with Git
stop unless exactly synchronized"] psmodule --> refresh other --> refresh - refresh --> repo["Read README, CONTRIBUTING,
and local docs"] + refresh --> repo["Read README, contribution guidance,
and local docs"] repo --> path["Apply path-scoped local rules"] path --> orgdocs["Read organization
documentation"] orgdocs --> docs["Read inherited
ecosystem documentation"] @@ -142,7 +144,7 @@ mechanics, or standards. Read in this order: 1. `README.md` — what this repository is and how it builds. -2. `.github/CONTRIBUTING.md` — how a change is made and reviewed here. +2. `.github/CONTRIBUTING.md` — repository-specific contribution instructions, when present. 3. `docs/index.md` — this repository's own documentation. 4. [MSXOrg/docs](https://github.com/MSXOrg/docs/) — the organization standards. @@ -152,7 +154,7 @@ clone, and update it before reading it. Read nearest first. A local file never overrides a standard. ``` -A router lists the destinations that exist in that repository, written as the paths that repository actually uses — the ones above are an example, not a required layout. A repository with no documentation of its own drops that line; one that publishes the standards resolves steps 3 and 4 to the same tree and drops the duplicate. Writing a real path matters more than matching the example, because the router is read literally. +A router lists the destinations that actually exist — the ones above are an example, not a required layout. Replace the optional local contribution entry with a link to the inherited organization default when no local guide is needed. A repository with no documentation of its own drops that line; one that publishes the standards resolves steps 3 and 4 to the same tree and drops the duplicate. Writing a real path or source link matters more than matching the example, because the router is read literally. The index trail is the default. A clear prompt can shortcut stage discovery: `Review this PR ` enters Review, `Make this issue ` enters Define, and `Implement ` enters Implement. These phrases are routing hints interpreted by [Workflow](../../Ways-of-Working/Workflow.md#find-the-current-stage), not commands with independent procedures. diff --git a/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md b/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md index c68b48b..b39909a 100644 --- a/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md +++ b/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md @@ -39,6 +39,13 @@ Absent checks are not a pass. When a pull request reports no checks at all, the If any item is open, the pull request stays a draft. Marking it ready with known-open work shifts the author's unfinished job onto reviewers — the opposite of what the signal means. +When a change affects community or contribution guidance, verify +[effective contribution guidance](Repository-Standard.md#contribution-guidance): +shared files remain in their organization `.github` source home, inherited +guidance resolves without repository-local copies, and needed local instructions +or documented exceptions are preserved. Already-correct guidance does not +require a file edit. + Once every item holds, hand the change off: mark it ready for review and enable auto-merge so it lands the moment review approves and the required checks stay green. See [Branching and Merging](Branching-and-Merging.md#required-checks-and-auto-merge). Auto-merge gates only on what the ruleset declares. It waits for the required status checks and required approvals the branch ruleset names, and for nothing else — so where a ruleset declares no required status checks, an armed auto-merge lands on approval alone and never waits for CI, and "auto-merge is enabled" means considerably less than it appears to. That is a misconfiguration, not a local variation to work around: [Required checks and auto-merge](Branching-and-Merging.md#required-checks-and-auto-merge) already requires the ruleset to enforce required status checks, so a repository without them is in breach of it. The fix is to add the rule, not to compensate by watching the build by hand. diff --git a/src/docs/Ways-of-Working/Readme-Driven-Context.md b/src/docs/Ways-of-Working/Readme-Driven-Context.md index d495da8..4ce7546 100644 --- a/src/docs/Ways-of-Working/Readme-Driven-Context.md +++ b/src/docs/Ways-of-Working/Readme-Driven-Context.md @@ -27,7 +27,7 @@ Include what is relevant. Not every repository needs every section. | **Usage** | Examples and explanations of key functionality. Code samples where applicable. | | **Configuration** | Settings, environment variables, or options the user can control. | | **Architecture** | High-level overview — folders, components, data flow — for complex repos. | -| **Contributing** | How to contribute, or a link to the organization-level contributing guide. | +| **Contributing** | Applicable contribution guidance: the organization default, or a [local guide when needed](Repository-Standard.md#contribution-guidance). | | **License** | License type or a link to the LICENSE file. | For simple repositories (e.g., a single GitHub Action), a subset is fine — at minimum the title, description, and usage sections. diff --git a/src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md b/src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md index 4c820d9..22dccfe 100644 --- a/src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md +++ b/src/docs/Ways-of-Working/Workflow-Stages/Maintain-Guidance.md @@ -29,7 +29,7 @@ Write the stage as a page in this section, following the shape of its siblings: ### 3. Keep pointers thin -A repository never carries a copy of the workflow. Its `AGENTS.md` — with the client routes that reach it — lists these pages as a destination and nothing more. Repository-specific nuance lives in `README.md`, `.github/CONTRIBUTING.md`, and the repository's own `docs/`; the router points at those files rather than restating them. When a new runtime is adopted, add a route under the filename it reads; do not move process knowledge into it. See [Agentic Development](../../Capabilities/agentic-development/design.md#client-behavior). +A repository never carries a copy of the workflow. Its `AGENTS.md` — with the client routes that reach it — lists these pages as a destination and nothing more. Repository-specific nuance lives in `README.md`, a local contribution guide [when needed](../Repository-Standard.md#contribution-guidance), and the repository's own `docs/`; the router points at those destinations or inherited contribution guidance rather than restating them. When a new runtime is adopted, add a route under the filename it reads; do not move process knowledge into it. See [Agentic Development](../../Capabilities/agentic-development/design.md#client-behavior). ### 4. Validate From 3ca4de0c508058950ed9d4592c47e24100874eee Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 31 Oct 2026 17:38:27 +0100 Subject: [PATCH 3/3] Align agent context requirements with inherited contribution guidance --- src/docs/Capabilities/agentic-development/spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/docs/Capabilities/agentic-development/spec.md b/src/docs/Capabilities/agentic-development/spec.md index ef948e6..b278495 100644 --- a/src/docs/Capabilities/agentic-development/spec.md +++ b/src/docs/Capabilities/agentic-development/spec.md @@ -81,7 +81,7 @@ Applies to any organization that wants a shared project knowledge base for agent - An agent working in `github.com/MSXOrg/` resolves `github.com/MSXOrg/docs` as the canonical project context. - An agent working in `//` for any adopting organization resolves its designated documentation repository as the canonical project context, with no change to the framework. - A new product repository can adopt the framework by adding a router and the client routes that reach it, without copying standards pages. -- An agent reads the repository's own README and CONTRIBUTING before it reads an organization standard, and still applies the organization standard when the two disagree. +- An agent reads the repository's own README and [applicable contribution guidance](../../Ways-of-Working/Repository-Standard.md#contribution-guidance), local when needed and otherwise shared, before an organization standard, and still applies the organization standard when the two disagree. - A human or agent can follow the declared entry index to the applicable Workflow and current stage procedure. - A prompt such as `Review this PR ` reaches the Review procedure directly, while `Make this issue ` reaches Define, without a parallel process definition. - A missing, dirty, locally ahead, diverged, wrong-branch, or unreachable canonical context repository stops discovery before any context index is read. @@ -96,7 +96,7 @@ The framework uses this normative reading order: 2. **User-global preferences** — the human operator's baseline style and risk posture. 3. **Repository router** — `AGENTS.md` identifies the host, organization, and the context sources below, in the order they are read. 4. **Freshness gate** — fetch every canonical context repository and stop unless each clean default-branch checkout exactly matches its remote head. -5. **Repository context** — README, CONTRIBUTING, local docs, and narrow repository exceptions. +5. **Repository context** — README, applicable contribution guidance (local when needed, otherwise shared), local docs, and narrow repository exceptions. 6. **Path-scoped repository rules** — local rules that apply to the files being read, generated, reviewed, or edited. 7. **Organization documentation** — the designated documentation repository for the resolved organization: start at its entry index, resolve the current stage, then load the relevant standards, specs, and designs. 8. **Inherited ecosystem documentation** — where the organization inherits from a broader standard set, the layer it inherits from.