diff --git a/src/docs/Capabilities/agentic-development/AGENTS.template.md b/src/docs/Capabilities/agentic-development/AGENTS.template.md index 7ba9c74..0e9f097 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,14 @@ 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 initiative's required contribution +source in its public `.github` repository. If the source guide is blank, also +link to the shared +[Contribution Workflow](../../Ways-of-Working/Contribution-Workflow.md). +Report a missing required source file in the initiative's community repository. +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..2f6e315 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 initiative's required contribution source in its public `.github` repository. If the source guide is blank, also link to the shared [Contribution Workflow](../../Ways-of-Working/Contribution-Workflow.md). Report a missing required source file in the initiative's community repository; 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/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. 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 56ae0cf..6705c66 100644 --- a/src/docs/Capabilities/repository-governance/design.md +++ b/src/docs/Capabilities/repository-governance/design.md @@ -81,8 +81,10 @@ exception ([FR16](spec.md#bypass)). ## Organization defaults repository -Each organization carries one public repository named `.github`. It has three -distinct surfaces: community files that GitHub inherits into repositories, +Each organization carries one public repository named `.github`. This is the +initiative's community repository and the normal source for shared contribution +guidance. It has three distinct surfaces: community files that GitHub inherits +into repositories, content published on the organization's profile, and local context that governs the defaults repository itself. Treating those surfaces as one distributable file set would copy repository-specific configuration into places where it does @@ -97,17 +99,26 @@ the same structure: | `.github/CODE_OF_CONDUCT.md` | Required | Inherited by a repository that has no local code of conduct. | | `.github/SECURITY.md` | Required | Inherited by a repository that has no local security policy. | | `.github/SUPPORT.md` | Required | Inherited by a repository that has no local support policy. | -| `.github/CONTRIBUTING.md` | Optional | Provides an organization-wide fallback where local contribution guidance is absent. | +| `.github/CONTRIBUTING.md` | Required | Owns the initiative's shared contribution guidance. The source file must exist but may be blank; consumer-local guides remain conditional. | | `.github/ISSUE_TEMPLATE/` | Optional | Provides the organization's issue forms and template configuration where a repository defines no local issue-template set. | | `profile/README.md` | Optional | Publishes the public organization profile; it is not inherited by repositories. | | `media/` | Optional | Holds assets used by the profile or community files; it is not inherited by repositories. | | `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). +For the required contribution source, verify file presence, not a nonempty body. +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. There is no PR-template-file surface to inherit or distribute. Ordinary and defaults repositories follow the [Repository Standard's file @@ -140,8 +151,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. @@ -169,7 +182,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? | | PR authoring and file policy | Are PR-template files absent under the [Repository Standard](../../Ways-of-Working/Repository-Standard.md#no-pr-template-files), and do actual records meet [PR Format](../../Ways-of-Working/PR-Format.md#check-readiness) with verified source coverage and supporting evidence? | ### 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/Definition-of-Ready-and-Done.md b/src/docs/Ways-of-Working/Definition-of-Ready-and-Done.md index fe57d21..fde3eb0 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/Organization-Standard.md b/src/docs/Ways-of-Working/Organization-Standard.md index bf34393..791ebe6 100644 --- a/src/docs/Ways-of-Working/Organization-Standard.md +++ b/src/docs/Ways-of-Working/Organization-Standard.md @@ -32,7 +32,7 @@ Every initiative organization must define standards for these shared file famili | File family | Standard owns | | --- | --- | -| Community health files | Central code of conduct, support policy, and security policy defaults, plus contribution guidance where provided. | +| Community health files | Central code of conduct, support policy, security policy, and initiative contribution guidance. | | Issue intake | Central issue forms and issue-template configuration defaults, where the organization wants a shared intake model. | | Organization profile | The public organization introduction and any assets it uses. | | Repository context | README defaults, documentation ownership, and repository metadata expectations. | @@ -48,9 +48,10 @@ 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, and support policy as defaults in its -special `.github` repository. These defaults apply whenever a repository does -not need a documented local exception. +security policy, support policy, and shared contribution guide as defaults in +its public `.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: @@ -60,27 +61,35 @@ the special `.github` repository: | `.github/CODE_OF_CONDUCT.md` | Defines expected community behavior. | | `.github/SECURITY.md` | Defines supported versions and private vulnerability reporting. | | `.github/SUPPORT.md` | Defines where users ask for help. | +| `.github/CONTRIBUTING.md` | Owns the initiative's common contribution instructions. The file is required even when blank. | -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. +The contribution source file MAY be blank. Its absence is a missing required +organization default, not a reason to create placeholder copies in consumer +repositories. + +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). PR authoring follows the [Repository Standard's no-PR-template-file policy](Repository-Standard.md#no-pr-template-files) and canonical [PR Format](PR-Format.md). PR templates are not organization defaults or eligible local exceptions. -An organization MAY also provide optional defaults in the same repository: +An organization MAY also provide shared issue-intake 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/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. +When supplied, these defaults apply through GitHub's fallback. They are not +additional files for consumers to copy or subscribe to. 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 @@ -98,18 +107,18 @@ 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 -format is documented, without providing a PR-template file. 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. Contribution guidance links to canonical [PR Format](PR-Format.md). +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: @@ -135,9 +144,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/Readme-Driven-Context.md b/src/docs/Ways-of-Working/Readme-Driven-Context.md index e458d68..edf857b 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/Repository-Standard.md b/src/docs/Ways-of-Working/Repository-Standard.md index fbf53e4..5d44b8a 100644 --- a/src/docs/Ways-of-Working/Repository-Standard.md +++ b/src/docs/Ways-of-Working/Repository-Standard.md @@ -17,26 +17,29 @@ 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 repository-specific contribution steps and links to applicable organization defaults and canonical PR Format. | +| `.github/CONTRIBUTING.md` | Required locally only for repository-specific instructions or a documented exception; otherwise use shared guidance. See [Contribution guidance](#contribution-guidance) and [PR Format](PR-Format.md). | | `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. | | `.gitattributes` | Normalizes line endings and declares text/binary handling so the repository can be developed and built consistently on Linux, macOS, and Windows. | | `.gitignore` | Ignores files that must never be committed, tailored to the repository's ecosystem: operating-system files, editor and developer-tooling files, language and test-harness artifacts, and all local build outputs and files created during build and test. | -The organization provides `CODE_OF_CONDUCT.md`, `SECURITY.md`, and `SUPPORT.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 +The organization provides `CODE_OF_CONDUCT.md`, `SECURITY.md`, `SUPPORT.md`, and +`.github/CONTRIBUTING.md` as GitHub community defaults. Contribution guidance follows the +[initiative-level source below](#contribution-guidance). The organization MAY also +provide `.github/ISSUE_TEMPLATE/` as an optional default. 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 @@ -52,7 +55,8 @@ Solution-owned settings filenames follow the [Naming standard](../Coding-Standar ### 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 @@ -64,16 +68,27 @@ 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. The shared source is `.github/CONTRIBUTING.md` in its initiative organization's public `.github` repository. [Organization Standard](Organization-Standard.md#community-files-are-organization-defaults) requires that source file even when it is blank. + +When the source guide is blank, the shared [Contribution Workflow](Contribution-Workflow.md) still defines the process. A missing required guide is corrected in the initiative's community repository, not by creating consumer-local copies. + +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 back to the shared contribution guidance and 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. @@ -90,10 +105,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. @@ -111,7 +126,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. 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