# Standard Policy Documentation Alignment

Status: accepted target; execution is defined in the [implementation plan](implementation.md).

## Intent and baseline

Align ConfigKit's adopted documentation with Standard Repository Policies while
preserving substantive local decisions. Prefer upstream wording verbatim wherever
differences are editorial; do not maintain a parallel local paraphrase of shared
rules. Customization must serve a locally significant requirement.

Local baseline: `0adb94f59e44827908eff401d4381a398fe17107` (v0.4.1).
The selected upstream revision is
`d84a38ebab26f048cafbe59a2246700c35d29843`. Its
[adoption guide](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md)
owns the standard adoption procedure. This roadmap covers the adopted policy set,
not just `docs/policy/documentation.md`.

ConfigKit currently has six policies, no `meta.md`, and no per-document
`Upstream Source` links. Its contributor guide routes tasks to documents but lacks
the upstream selective-reading guidance. Licensing documentation covers the
project and YAML dependency but not copied policy material. The release policy
has intentionally retained its established workflow.

Introduce accurate provenance going forward. Do not reconstruct old adoption
baselines or add historical-uncertainty narratives.

## Target policy set

Remove upstream template instructions after adoption. Retain shared substantive
wording unchanged except for necessary local adaptation and working references.

| Document | Target |
| --- | --- |
| `docs/policy/meta.md` | Adopt upstream v1.0: local authority, upstream origin, discovery links, and policy provenance. |
| `docs/policy/agents.md` | Adopt v1.3 wording, retaining local explanations of correctness constraints, protection of established contracts, and the rule that repeated agent-authored assertions are not evidence of approval. No change to standing commit authority. |
| `docs/policy/architecture.md` | Use v1.3 as the customized template while preserving the opinionated library model, root-owned facade, dependency direction, existing invariants, and explicit avoidance of an imposed hexagonal framework. No code restructuring or new threat guarantees. |
| `docs/policy/testing.md` | Adopt v1.3 shared wording. Retain ConfigKit-specific priorities and test ownership. Tests protect selected contracts; examples must not imply new rejection rules or mandatory inventories of techniques. |
| `docs/policy/documentation.md` | Adopt v1.11 wording with a library-specific ownership table, including policy provenance. Omit inapplicable interfaces and empty placeholder documents. |
| `docs/policy/oss.md` | Adopt v1.8 wording with necessary ConfigKit applicability and reference adjustments. Preserve the selected project grant and house interpretation of upstream notice links. |
| `docs/policy/release.md` | Adopt compatible wording and accurate source metadata, preserving current operational requirements as explicit local adaptations until the separate release-workflow task lands. Do not describe the future publication command as implemented. |

Each adopted document identifies its actual upstream template version, local
update date, and full commit-specific `Upstream Source` URL. A deliberate adoption
from the selected revision establishes the new baseline even where substantial
project-specific content remains. Metadata must not imply adoption of upstream
requirements deliberately replaced by local rules.

## Orientation and upstream navigation

Adapt upstream `agents/AGENTS.md` into the root orientation file. Keep the required
agent-policy reading rule and route other reading through `docs/development.md`.
The developer guide owns task triggers for all seven policies, including policy
reviews through `meta.md`. Readers select applicable policies, reuse unchanged
material already in context, follow relevant cross-references, and expand reading
when scope changes. Reading the entire suite is not the default.

Use live upstream project and adoption-guide URLs for discovery. Pin adopted-source
and licensing-example URLs to full commits. Keep the upstream README, root agent
instructions, contributor guide, adoption guide, and example collection upstream;
do not copy them into ConfigKit. Root orientation derives from the upstream
`agents/AGENTS.md` template, not its root AGENTS.md.

## Attribution and licensing target

Use the upstream canonical Standard Repository Policies entry in
`docs/oss/attribution.md`, identifying the actual adapted material and linking its
source, COPYRIGHT, and LICENSE at the selected commit. Include adapted orientation
material where applicable. Preserve notices and modification identification
without adding research or compliance narratives.

Copy the applicable CC-BY-SA-4.0 text verbatim into `docs/oss/licenses/` and identify
the separately licensed policy-document scope in root COPYRIGHT. ConfigKit code
retains LGPL-3.0-or-later; root LICENSE retains the project license texts. Original
upstream example formatting is CC0 and does not itself require an attribution
entry or copying the example collection.

Normalize the existing YAML entry to the current House Format: the prescribed
document title, factual component identification, actual notice filenames,
punctuation, and Source link. Remove editorial explanations while retaining
upstream notices, copyright statements, license expression, and exact source
revision. Keep MIT and Apache texts unchanged. Do not restore the author-owned
adaptation section that the maintainer expressly removed.

## Change surface and boundaries

Affected files are the policy documents, root `AGENTS.md`, `docs/development.md`,
COPYRIGHT, `docs/oss/attribution.md`, and the new CC license text. Repair affected
local links and any misleading licensing summaries. Shared rules belong in their
owning policies, not duplicated in the orientation guide or attribution entries.

The [release-workflow roadmap](release.md) owns publication automation and gate
selection. This work may align wording and references but does not alter release
scripts, existing gates, supported platforms, publication completion, or library
behavior. Coordinate edits to the release policy rather than maintaining two
competing definitions. Published tags and historical release notes remain intact.

## Completion criteria

The policy set uses upstream language except for justified local substance,
contains accurate forward-looking adoption metadata, and has working orientation
and attribution links. Existing local contracts and explicit maintainer decisions
remain intact. Documentation-link and whitespace checks, license-text comparisons,
and ordinary content review provide proportionate validation. No synchronization
service, scanner, legal sign-off, or new release gate is introduced.

This roadmap defines the desired end state and local policy choices. It
authorizes neither publication nor a release.