eric/policy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Clarify downstream policy files and upstream references

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-27 19:14:00 +00:00
parent 027604e974
commit 04e20af744
5 changed files with 60 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
README.md
View File

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

49
docs/adoption.md
View File

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

6
docs/development.md
View File

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

3
docs/policy/documentation.md
View File

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

33
docs/policy/meta.md Normal file
View File

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