diff --git a/AGENTS.md b/AGENTS.md index 69fa169..da3e774 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,6 @@ For work on this repository, start with [docs/development.md](docs/development.md) -and follow its task-specific reading guide. Read and follow the +and use its policy reading guide to select the policies applicable to the task. +Do not read the entire suite by default. Read and follow the [agent policy](docs/policy/agents.md) before recommending, planning, or implementing changes. diff --git a/agents/AGENTS.md b/agents/AGENTS.md index aeeff31..8b791c3 100644 --- a/agents/AGENTS.md +++ b/agents/AGENTS.md @@ -1,4 +1,6 @@ -Please review `docs/development.md` for initial orientation in this repository -and follow its task-specific reading guide. +Start with `docs/development.md` for orientation and use its policy reading guide +to select the policies applicable to the task. Do not read the entire suite by +default. -Review and follow `docs/policy/agents.md` before recommending, planning, or implementing any changes to this repository. \ No newline at end of file +Read and follow `docs/policy/agents.md` before recommending, planning, or +implementing repository changes. diff --git a/docs/adoption.md b/docs/adoption.md index 25bfe87..233e540 100644 --- a/docs/adoption.md +++ b/docs/adoption.md @@ -29,8 +29,10 @@ restriction, or release gate mentioned in the templates. 3. Retain each document's `Base Policy Version` and set `Last Updated` to the 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. Use - [agents/AGENTS.md](../agents/AGENTS.md) as the basis for the downstream root +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. + 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 resulting local rules for consistency with the project's actual workflows. @@ -41,6 +43,57 @@ A source link has this shape; substitute the selected full commit and filename: https://gitea.maximumdirect.net/eric/policy/src/commit/UPSTREAM_COMMIT/docs/policy/testing.md ``` +## Set Up Selective Policy Reading + +Include the following in the downstream `docs/development.md`, merging it with +existing reading guidance and retaining rows for the policies adopted locally. +The links are relative to that downstream document. Keep policy reading triggers +there; the documentation policy remains the owner of the documentation topic map. + +```markdown +## Policy Reading Guide + +| Policy | Read before… | +| --- | --- | +| [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. | +| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. | +| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. | +| [Release](policy/release.md) | Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions. | + +- 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. +- Reuse policies already available in context; reread when changed or no longer + available. +- Expand reading when the task's scope expands. +- When revising a policy itself, read that policy and any provisions elsewhere + 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) @@ -93,6 +146,32 @@ Copy the applicable standard license texts into the actual local license files; retain their wording and their own terms. Those copies remain necessary under the House Format even though example documents stay upstream. +## Check For Upstream Revisions + +When asked to check the policy set and recommend updates: + +1. Read the local policies and identify each document's `Upstream Source` commit, + `Base Policy Version`, and local customizations. Different documents may have + different adoption baselines. +2. Inspect upstream `main` and record its full commit identifier. Use that fixed + revision for the review so later upstream changes do not shift the comparison. +3. Compare each recorded upstream file with its counterpart at the review + revision, then assess the upstream changes against the locally customized + policy. Version labels help orientation; inspect the actual differences. + Note new, renamed, or removed upstream policies where relevant to the project. +4. Recommend applicable changes with their reasons, identify conflicts with + deliberate local choices, and name policies that need no update. Include the + baseline and review revisions so the comparison can be reproduced. Do not + recommend wholesale replacement merely because upstream differs. +5. If a baseline is missing or unavailable, report the uncertainty. You may + compare available content, but do not assume the local policy is an unchanged + upstream copy or invent an adoption revision. If upstream cannot be reached, + report that limitation rather than claiming the policies are current. + +For a recommendation-only request, leave files and adoption metadata unchanged. +A completed review does not mean a newer policy has been adopted. Apply the +following procedure when implementation is requested. + ## Update Deliberately Compare the previously recorded upstream files with a selected newer revision. diff --git a/docs/development.md b/docs/development.md index fed152e..79f3ec5 100644 --- a/docs/development.md +++ b/docs/development.md @@ -12,12 +12,27 @@ their template adoption sections because they are distributed as templates. Application-specific template examples do not require this repository to acquire application interfaces or infrastructure. -| Task | Read | +## Policy Reading Guide + +| Policy | Read before… | | --- | --- | -| Change a policy | The affected policy, its related policies, and the [documentation policy](policy/documentation.md). | -| Change adoption or provenance guidance | The [adoption guide](adoption.md), [OSS policy](policy/oss.md), and root [COPYRIGHT](../COPYRIGHT). | -| Change licensing examples | The [OSS policy](policy/oss.md), [COPYRIGHT](../COPYRIGHT), and affected examples. | -| Add or update reference license texts | The [reference collection README](oss/licenses/README.md) and the selected publisher or recorded upstream source. | +| [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. | +| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. | +| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. | +| [Release](policy/release.md) | Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions. | + +- 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. +- Reuse policies already available in context; reread when changed or no longer + available. +- Expand reading when the task's scope expands. +- When revising a policy itself, read that policy and any provisions elsewhere + affected by the revision. ## Editing And Validation @@ -37,8 +52,10 @@ URLs or missing local dependencies. No application build or new test suite is needed for prose-only changes. Retain upstream formatting in verbatim license texts even where it would trigger whitespace warnings. -Pin upstream reference links to commits that contain the referenced files. New -assets can use local links within this repository until a containing commit is -available; do not invent a future hash or publish changes merely to obtain one. +Pin adopted-source and example links to commits that contain the referenced +files. Discovery links to the upstream project and current adoption guide may +track `main` so downstream agents can find updates. New assets can use local +links within this repository until a containing commit is available; do not +invent a future hash or publish changes merely to obtain one. Before publication, confirm that public reference links are accessible. This is change validation, not a recurring downstream release gate.