Clarify policy reading and upstream update guidance

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.
 

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.
+Read and follow `docs/policy/agents.md` before recommending, planning, or
+implementing repository changes.

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.

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.