Clarify downstream policy files and upstream references

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. |

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
+into another repository. This guide lives in the upstream repository; downstream
-[contributor guide](development.md).
+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
+   the [policy reading guide](#set-up-selective-policy-reading) below, which routes
-   [policy-update discovery section](#make-upstream-updates-discoverable) below.
+   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
+- Select policies using the task triggers above. Follow cross-references to
-  cross-reference. Read relevant sections of supporting references when needed
+  relevant sections when needed to resolve a concrete question.
-  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)

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
+- Select policies using the task triggers above. Follow cross-references to
-  cross-reference. Read relevant sections of supporting references when needed
+  relevant sections when needed to resolve a concrete question.
-  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.

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. |

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).