policy/docs/adoption.md

# Adopting And Updating The Policies

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

## Select A Baseline

Select an upstream commit and read the policies relevant to the requested work.
Use a revision containing the [project grant](../COPYRIGHT) and the reference
assets you intend to use. Record its full commit identifier; a moving branch
name is not an adoption baseline. No package manager or automatic update service
is required.

Preserve existing downstream decisions and unrelated changes. Adoption is a
local customization task, not authorization to add every capability, document,
restriction, or release gate mentioned in the templates.

## Copy And Customize

1. Copy applicable documents from `docs/policy/` to the same downstream location.
   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.
2. Tailor architecture to the actual project. Preserve the author's selected
   license and existing application contracts. Do not infer new product behavior
   from policy examples.
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, 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.

A source link has this shape; substitute the selected full commit and filename:

```text
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)
in the downstream `docs/oss/attribution.md`. It is an entry fragment to insert
beneath that document's existing title, not an additional document title.

- Replace `UPSTREAM_COMMIT` with the selected full commit in all three URLs.
- Adjust the `Material:` sentence to identify the files actually copied. Keep
  “adapted for this repository” for customized documents; use “copied without
  modification” for unchanged copies. For a mixture, identify which are adapted.
- Preserve supplied creator, copyright, license, and warranty-disclaimer notices,
  including the link to upstream `COPYRIGHT`. Retain indications of prior
  modifications as the documents evolve.
- Copy [CC-BY-SA-4.0.txt](oss/licenses/CC-BY-SA-4.0.txt) into the downstream
  `docs/oss/licenses/`. The entry's relative license link assumes that location.

This entry is the project's recommended attribution arrangement for copied or
adapted policies. Its short material statement identifies scope and modification
status; do not add research narratives or compliance commentary.

Keep customized policy documents under CC-BY-SA 4.0 in this standard adoption
workflow. Identify that scope in the downstream `COPYRIGHT`, for example:

```text
Policy documents adapted from Standard Repository Policies remain licensed
under CC-BY-SA-4.0. See docs/oss/attribution.md for the affected material,
upstream credit, and license links.
```

The application's own code retains its selected license. Copying a policy does
not select a new license for unrelated code or documentation. These instructions
implement the [project grant](../COPYRIGHT); they do not add a requirement to
publish private work or send modifications upstream. Other arrangements
permitted by the license remain available.

## Use Reference Assets

Create actual `COPYRIGHT` and attribution files using the upstream
[application](../examples/licensing/application/COPYRIGHT),
[library](../examples/licensing/library/COPYRIGHT), and
[attribution](../examples/licensing/attribution.md) examples. Read the
[OSS policy](policy/oss.md) for their format and placeholder substitution rules.
Original example formatting is available under CC0 as specified in
[COPYRIGHT](../COPYRIGHT); using that formatting alone does not require an
attribution entry for this project.

Keep links to these examples in the adopted policy pointed at upstream commits.
Do not populate the downstream `examples/` directory with this collection.
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.
Apply relevant changes while preserving local decisions; do not overwrite
customized documents wholesale or treat every upstream recommendation as a new
local requirement.

Update `Base Policy Version` when adopting a newer template version and update
`Upstream Source` to the revision actually incorporated. Change `Last Updated`
when revising the local document. Keep the material description, modification
status, and attribution links accurate. If documents use different upstream
revisions, retain each file's exact source metadata and include the necessary
commit-specific source and notice links in the single project attribution entry.
Do not change a source reference to a version that was merely reviewed.

Ordinary review should check the resulting rules, attribution facts, and affected
links. A commit-based adoption record is sufficient; no recurring synchronization
check, release gate, or separate license approval is required. Agents following
this documented arrangement need additional clarification only for a concrete
circumstance it does not cover. User instructions govern whether changes are
committed or published.