diff --git a/README.md b/README.md index ea262a0..a7d687a 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ updates are incorporated deliberately. | Policy | Purpose | | --- | --- | +| [Policy set provenance](docs/policy/meta.md) | Local policy authority and upstream adoption and update navigation. | | [Agents](docs/policy/agents.md) | Implementation discipline and local commit practices. | | [Testing](docs/policy/testing.md) | Meaningful behavioral coverage with proportionate maintenance cost. | | [Architecture](docs/policy/architecture.md) | A framework for application-specific boundaries and constraints. | diff --git a/docs/adoption.md b/docs/adoption.md index 233e540..dddb789 100644 --- a/docs/adoption.md +++ b/docs/adoption.md @@ -2,8 +2,20 @@ This guide is for agents and maintainers incorporating policies from [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy) -into another repository. To edit the upstream templates themselves, use the -[contributor guide](development.md). +into another repository. This guide lives in the upstream repository; downstream +projects link to it from their adopted `docs/policy/meta.md`. To edit the upstream +templates themselves, use the [contributor guide](development.md). + +## Downstream Files And Upstream References + +| Material | Downstream treatment | +| --- | --- | +| Applicable `docs/policy/*.md`, including `meta.md` | Copy and customize, retaining each document's upstream provenance. | +| `agents/AGENTS.md` | Adapt into the downstream root `AGENTS.md`. | +| Downstream `docs/development.md` | Create or update for that project using the reading guidance below. | +| This repository's README, root AGENTS.md, developer guide, and adoption guide | Keep upstream and consult through links as needed. | +| Licensing examples | Reference upstream and use them to create actual project notices. | +| Applicable standard license texts | Copy locally as specified below and in the OSS policy. | ## Select A Baseline @@ -19,7 +31,8 @@ restriction, or release gate mentioned in the templates. ## Copy And Customize -1. Copy applicable documents from `docs/policy/` to the same downstream location. +1. Copy `docs/policy/meta.md` and the applicable policy documents to the same + downstream locations. Follow each template's adoption instructions and remove its `Base Policy Template` section afterward. Create supporting documents when they have useful content for an existing responsibility, rather than filling an empty outline. @@ -30,8 +43,8 @@ restriction, or release gate mentioned in the templates. local adoption date. Add `Upstream Source` metadata linking to that specific document at the selected commit. Retain this provenance in future edits. 4. Create or update the downstream `docs/development.md` reading guide, including - the [policy reading guide](#set-up-selective-policy-reading) and - [policy-update discovery section](#make-upstream-updates-discoverable) below. + the [policy reading guide](#set-up-selective-policy-reading) below, which routes + adoption and update tasks to `policy/meta.md`. Use [agents/AGENTS.md](../agents/AGENTS.md) as the basis for the downstream root `AGENTS.md`, merging its orientation links with existing instructions. 5. Add the attribution and document-license scope described below. Review the @@ -55,6 +68,7 @@ there; the documentation policy remains the owner of the documentation topic map | Policy | Read before… | | --- | --- | +| [Policy set provenance](policy/meta.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. | | [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. | | [Architecture](policy/architecture.md) | Planning or changing application code or its structure. | | [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. | @@ -64,9 +78,8 @@ there; the documentation policy remains the owner of the documentation topic map - Read applicable policies before making decisions they govern; multiple policies may apply. -- Do not read the entire suite by default or recursively follow every - cross-reference. Read relevant sections of supporting references when needed - to resolve a concrete question. +- Select policies using the task triggers above. Follow cross-references to + relevant sections when needed to resolve a concrete question. - Reuse policies already available in context; reread when changed or no longer available. - Expand reading when the task's scope expands. @@ -74,26 +87,6 @@ there; the documentation policy remains the owner of the documentation topic map affected by the revision. ``` -## Make Upstream Updates Discoverable - -Include this section in the downstream `docs/development.md`, merging it with -existing update guidance where appropriate: - -```markdown -## Policy Updates - -These policies derive from -[Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy). -When asked to check for upstream revisions, follow its -[adoption and update guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md). -Each adopted policy records its baseline in `Upstream Source`. -``` - -The repository and current-guide links enable discovery of newer revisions. -Keep these discovery links pointed at the current upstream project; retain -commit-pinned links for adopted source baselines and reference examples. This -provides an on-request workflow, without automated polling or a release gate. - ## Attribute Copied Policies Use the [canonical attribution entry](../examples/licensing/policy-attribution.md) diff --git a/docs/development.md b/docs/development.md index 79f3ec5..dfd3cf6 100644 --- a/docs/development.md +++ b/docs/development.md @@ -16,6 +16,7 @@ application interfaces or infrastructure. | Policy | Read before… | | --- | --- | +| [Policy set provenance](policy/meta.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. | | [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. | | [Architecture](policy/architecture.md) | Planning or changing application code or its structure. | | [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. | @@ -25,9 +26,8 @@ application interfaces or infrastructure. - Read applicable policies before making decisions they govern; multiple policies may apply. -- Do not read the entire suite by default or recursively follow every - cross-reference. Read relevant sections of supporting references when needed - to resolve a concrete question. +- Select policies using the task triggers above. Follow cross-references to + relevant sections when needed to resolve a concrete question. - Reuse policies already available in context; reread when changed or no longer available. - Expand reading when the task's scope expands. diff --git a/docs/policy/documentation.md b/docs/policy/documentation.md index aabd56d..ac99ea5 100644 --- a/docs/policy/documentation.md +++ b/docs/policy/documentation.md @@ -1,6 +1,6 @@ # Documentation Policy -**Base Policy Version:** 1.7 +**Base Policy Version:** 1.8 **Last Updated**: 2026-09-27 @@ -76,6 +76,7 @@ secret values. | Product orientation and minimal end-to-end quickstart | `README.md` | What this application is, why it is useful, one shortest successful invocation, and links onward, including license and attribution navigation. | Complete command reference, configuration reference, operational procedures, implementation detail. | | Contributor entry point | `docs/development.md` | Task-oriented reading guide, minimal contributor orientation, baseline validation commands, and links to canonical docs. | Package inventory, architecture rules, subsystem behavior, detailed change recipes. | | Application architecture policy | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, architectural boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. | +| Policy-set provenance and upstream navigation | `docs/policy/meta.md` | Origin of the adopted policy set, local authority, meaning of adoption baselines, and links to upstream adoption and update guidance. | Task-specific reading triggers, detailed adoption procedures, and formal attribution notices. | | Agent policy | `docs/policy/agents.md` | Implementation discipline for coding agents, including proportionality, idiomatic simplicity, and rules against inventing requirements, restrictions, guarantees, or repository policy. | Application contracts, architecture, testing policy, and contributor procedures. | | Documentation policy | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. | | Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression-test policy, and criteria for adding, rewriting, or deleting tests. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. | diff --git a/docs/policy/meta.md b/docs/policy/meta.md new file mode 100644 index 0000000..04f2e84 --- /dev/null +++ b/docs/policy/meta.md @@ -0,0 +1,33 @@ +# Policy Set Provenance + +**Base Policy Version:** 1.0 + +**Last Updated**: 2026-09-27 + +## Base Policy Template + +Repositories adopting this policy should copy it alongside their selected +policies, retain its version, set `Last Updated` to the adoption date, and add +`Upstream Source` linking to this file at the adopted commit. Confirm the local +attribution link, then remove this section. The text below describes the +resulting downstream policy set. + +## Origin And Local Authority + +This repository's policy set is adapted from +[Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy). +The adopted local policies govern work in this repository. Upstream revisions +become local policy through deliberate adoption, preserving local decisions. +Each policy's `Upstream Source` identifies its adopted baseline. + +## Adoption And Updates + +For policy adoption, upstream revision reviews, and updates, consult the +[upstream adoption and update guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md). +That guide and the reference example collection are maintained upstream and +accessed through links. Keep discovery links pointed at the current upstream +project and guide; keep adopted-source and example links pinned to commits. + +The local [developer guide](../development.md) routes tasks to applicable +policies. Formal credit and licensing notices for the copied policy material +belong in the local [attribution document](../oss/attribution.md).