ConfigKit/docs/roadmap/implementation.md

# Policy Alignment Implementation Plan

Status: ready for implementation.

## Scope and selected decisions

Implement the [policy roadmap](policy.md), in the stages below, for a
gpt-5.6-terra coding agent. The roadmap owns intent and target state; this plan
owns execution. Local planning baseline is `6f372e0`. Use upstream commit
`d84a38ebab26f048cafbe59a2246700c35d29843` throughout, not whatever upstream main
contains when implementation starts. Read its
[adoption guide](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md)
and selected source files at that revision. The sibling `../policy` checkout is
a convenient source; use `git show` at the pinned commit rather than trusting its
working-tree contents. If unavailable, retrieve that exact revision outside this
repository. Do not update or modify the sibling checkout as part of this task.

The adopted shared wording is upstream wording, not a local paraphrase. Remove
template-adoption sections and customize only metadata, necessary references,
project-specific topics, and the substantive exceptions selected below. Preserve
unrelated work. Do not reconstruct older adoption baselines or write uncertainty
narratives. New source metadata records the deliberate adoption made here.

This is documentation work only. Do not change Go code, tests, dependencies,
scripts, existing release commands, gates, platforms, tags, historical release
notes, or accepted ADR decision text. The [release-workflow roadmap](release.md)
is a separate task and remains unchanged. Do not add policy synchronization,
scanners, mandatory legal reviews, per-file license headers, or new guarantees.

### Provenance convention

For each policy adopted in a stage, remove its old partial-adoption preamble,
set `Last Updated` to the actual local adoption date, and add:

```text
**Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/FILENAME.md)
```

Replace FILENAME with that document's filename. Use these actual upstream
template versions: meta 1.0; agents 1.3; architecture 1.3; testing 1.3;
documentation 1.11; OSS 1.8; release 1.4. Local adaptations remain explicit in
the document rather than being hidden by the version label. Do not claim that
all documents have already been updated while later stages remain outstanding.

### Validation and commit discipline

Before each stage, read AGENTS.md, the developer reading guide, the local policies
governing its work, the affected upstream documents, and the local documents being
revised. Reuse unchanged policy text already in context. Inspect Git status and
the diff before editing. For this cross-policy task, read all adopted policies
over the course of the work; this is not a new blanket-reading rule for other tasks.

After each coherent stage:

- Review the diff against the pinned upstream text. Account for every substantive
  local difference using the selected adaptations below, not incidental baseline
  wording. A review summary is sufficient; do not create a permanent diff ledger.
- Run `GOPROXY=off go test . -run '^TestLocalDocumentationLinks$'` and
  `git diff --check`; after staging, run `git diff --cached --check` as well.
  Acquire missing dependencies explicitly if necessary; do not weaken checks.
- Inspect new files, metadata URLs, anchors, and license scope manually. Compare
  copied standard license bytes with the pinned upstream source. Reuse results
  for unchanged content rather than repeating full suites.
- Update this plan with the stage's completion and validation evidence, review
  staged changes, and commit only that stage with a short plain-English message.
  No push, publication, or release is authorized.

The local link checker can encounter Markdown examples inside fenced blocks.
Keep examples meaningful and repair their destinations or link to the actual
upstream example when necessary. Do not add placeholder files, alter the checker,
or copy the upstream example collection to satisfy illustrative links.

## Stage 1 — Establish provenance, orientation, and licensing ownership

**Completed 2026-09-28.** Adopted pinned meta, OSS, and documentation policies,
selective orientation, policy attribution, document-license scope, and the
verbatim CC BY-SA 4.0 text. The local documentation-link check, whitespace
checks, pinned license-byte comparison, metadata/link review, and staged diff
review passed.

### Work

1. Create `docs/policy/meta.md` from the pinned template, retaining its live
   project and main-branch adoption-guide discovery URLs. Apply the provenance
   convention and preserve its distinction between local authority and optional
   future upstream adoption. Keep the adoption guide itself upstream.
2. Adopt upstream `docs/policy/oss.md` v1.8, including its copied-document scope,
   factual attribution format, and house interpretation of upstream notice links.
   Retain a concise ConfigKit applicability section identifying the selected
   LGPL-3.0-or-later grant and linking to COPYRIGHT, LICENSE, and the release
   procedure for the source-only Gitea channel. Do not require a hosted release
   object. Retarget upstream application/library COPYRIGHT examples, attribution
   examples, and retained reference-collection links to the selected full commit.
   Do not copy those examples. Preserve substantive upstream wording elsewhere.
   For the illustrative README link block, a link to the actual local README
   may replace the block if needed to avoid invalid example-relative links.
   Keep its two-statement requirement intact. Repair the release-correction link
   to the local `immutability-and-correction` anchor.
3. Adopt upstream `docs/policy/documentation.md` v1.11. Retain shared sections
   verbatim and adapt the ownership table for ConfigKit: retain the existing
   root Go declaration owner, configuration contract, consumer examples, internal
   documents, ADRs, deferred scope, and release-note history; add meta ownership.
   Omit CLI, HTTP API, operations, and integration-contract documents because
   ConfigKit has no such owned interfaces. Preserve local distinctions between
   `deferred.md` and execution plans, executable Go examples and complete example
   files, and retirement of completed roadmaps during release preparation.
   Do not create empty owners. Update licensing rows to the upstream scope.
4. Adapt root AGENTS.md from upstream `agents/AGENTS.md`, not upstream root
   AGENTS.md. Preserve any independent local tooling instructions encountered.
   Adopt its selective-reading orientation and mandatory agent-policy reference.
   Merge the adoption guide's seven-row Policy Reading Guide and its reading
   rules into `docs/development.md` verbatim except for necessary Go-library
   terminology. Keep the existing task-to-contract and task-to-test navigation,
   validation commands, and historical references. Remove duplicate policy
   trigger prose rather than maintain conflicting reading rules.
5. Create a Standard Repository Policies attribution entry using the pinned
   `examples/licensing/policy-attribution.md`. Preserve its copyright, SPDX,
   license/notice labels, and three commit-specific URLs after substitution.
   Copy `docs/oss/licenses/CC-BY-SA-4.0.txt` verbatim from upstream. At this stage,
   identify the newly adopted meta, OSS, and documentation policies, root agent
   orientation, and the Policy Reading Guide section of development.md as adapted
   material; expand the single entry as later stages adopt the other policies.
   Do not claim that unrelated parts of the developer guide were copied.
6. Add the guide's document-license scope statement to COPYRIGHT, extended to
   include the adapted orientation material identified by the attribution entry.
   Keep code LGPL-3.0-or-later, root LICENSE unchanged, and third-party terms intact.
   Do not convert the whole repository to CC-BY-SA or copy CC0 merely because
   upstream example formatting is used. The CC0 formatting alone needs no entry.
7. Normalize `docs/oss/attribution.md`: title `Open Source Attribution Notices`,
   then the policy entry and existing go-yaml entry, without introductory or
   concluding editorial prose. Use the current House Format for go-yaml: factual
   module/version identification, existing copyright statements and
   `Apache-2.0 AND MIT`, links labeled Apache 2.0, MIT, NOTICE, LICENSE, a period
   after the link list, and `[Source](COMMIT_URL).` Preserve its exact upstream
   hash and both local license texts. Remove the explanatory final paragraph.
   Do not restore author-owned adaptation notices.
8. Leave README's existing license/attribution navigation in place if accurate.
   If clarification is needed, state that the LGPL grant applies to ConfigKit
   code and let COPYRIGHT own the separately licensed-document scope; do not
   duplicate the attribution list or policy text in README.

### Acceptance

New documents and references are present, license-text comparison and link checks
pass, and metadata reflects only adoption actually performed. Standard policy
attribution identifies the adapted files/section accurately. No published note,
release behavior, root license text, or code changed.

## Stage 2 — Align agent, architecture, and testing policies

### Work

1. Adopt upstream agents v1.3 and its commit policy verbatim. Retain exactly the
   existing substantive local additions: the paragraph explaining why correctness
   constraints must follow requested behavior rather than implementation convenience;
   the qualification that existing explicit contracts remain authoritative and
   changing them needs a deliberate decision; and the paragraph rejecting
   repeated agent-authored artifacts as evidence of approval. Drop other local
   paraphrases or slogans where upstream already expresses the same rule.
2. Adopt architecture v1.3 as a customized template, not as a new architecture.
   Use upstream Purpose And Ownership and Adopted Constraints And Implemented
   Structure wording. Populate application-specific content with existing local
   purpose/success criteria, responsibility boundaries, public facade/dependency
   direction, configuration integrity, ownership/confidentiality, and scope rules.
   Preserve all their substantive requirements. The upstream hexagonal-framework
   recommendation is replaced by ConfigKit's existing proportionate separation
   and explicit no-imposed-framework decision. Retain explanatory ADR and contract
   links. Do not add a threat model, threat exclusions, hardening promises, or a
   required security document: the existing confidentiality/input boundaries remain
   the selected scope. Avoid duplicate normative descriptions across sections.
3. Adopt testing v1.3 shared text. Retain the local ConfigKit-specific priorities
   section and the short preference for real parsing/composition/decoding seams.
   Replace upstream generic test-layer ownership examples with ConfigKit's YAML,
   composition/overlay, decoding, metadata/rendering, filesystem, and lifecycle
   ownership list; preserve the distinction from required package layout.
   Retain local guidance preferring codes, paths, and locations at the public
   library boundary in place of the CLI-specific example. Use upstream conditional
   testing-technique wording, revised concurrency example, and explicit authority
   requirement for tested contracts. This changes guidance, not existing tests or
   established ConfigKit semantics. Do not turn example techniques into new gates.
4. Apply the source/version/date convention to all three documents. Expand the
   existing policy attribution entry's Material sentence to include them; do not
   create per-policy attribution entries or a second provenance registry.

### Acceptance

Shared rules match upstream text; preserved local differences have the specific
reasons above. Public API, configuration invariants, callback/ownership boundaries,
existing security contracts, and commit authority are neither narrowed nor
strengthened. No architectural refactor or test rewrite was performed.

## Stage 3 — Align release-policy wording without changing the workflow

### Work

1. Compare the current release policy with pinned upstream v1.4. Use upstream
   shared wording for purpose, compatibility principles, immutable publication,
   and successful-push/no-CI completion where semantically equivalent. Keep local
   operational sections and their headings where required by the current runbook
   and inbound links. This is a selected adoption with substantive local workflow
   adaptations, not a wholesale replacement of the body.
2. Set Base Policy Version to 1.4 and the exact upstream source/date metadata.
   Replace the old partial-v1.2 preamble with a concise ConfigKit adaptation note:
   the existing separately invoked checker and guarded runbook remain in force;
   the single-command workflow and gate review are future work. Link to the
   current runbook for operations, not to a future command. Record the following
   preserved local decisions in the owning policy sections, without duplication:
   - source-only Go module, main branch, annotated immutable tags, no prereleases;
   - minimum-line Linux validation, existing race/vet/module/format/whitespace
     checks and Linux amd64/arm64 builds; macOS best-effort;
   - current version-availability scope, note title and four required headings,
     licensing footer, and candidate commit recording/revalidation;
   - authorization and guards, sequential main-before-tag publication, remote-main
     match, and explicit intended refs;
   - no CI waiting, no required post-publication retrieval/read-back, and unchanged
     historical v0.1.1/v0.2.0 exceptions.
   These are preserved requirements, not a fresh endorsement of their permanent
   necessity. Their later review belongs to the release-workflow task.
3. Recast the old post-publication-verification exception as a normal local
   source-only completion choice supported by upstream v1.4. Preserve its actual
   safeguards; do not invent compensating controls. Keep current correction and
   recovery semantics; defer changes to push recovery, optional atomic publication,
   note structure, and tag-summary generation to the release-workflow task.
   Do not copy the upstream single-publication-command requirement into current
   binding policy. Do not modify release scripts, tests, or runbook command blocks.
4. Add release.md to the single policy attribution Material scope. At completion,
   it may identify all seven files under `docs/policy/`, root AGENTS.md, and only
   the adapted Policy Reading Guide in development.md. Keep all source and notice
   links accurate at the pinned revision; the text is identified as adapted.
5. Audit all seven policies against the roadmap and this plan. Check each template
   version, full source URL, date, live discovery link, pinned example reference,
   and absence of template scaffolding. Remove redundant local paraphrases but
   retain the explicit local substance. Repair documentation links without editing
   historical ADR decisions or releases. Confirm existing licensing navigation
   remains correct and that only the new CC license text was added to the asset set.
6. Mark this plan complete with evidence. Change the policy roadmap's status to
   implemented and replace future normative detail with a short completion summary
   pointing to current owners. Retain these completed records until normal release
   preparation retires them. Leave the separate release roadmap and its open
   decisions unchanged; do not create a release note or tag.

### Acceptance

Run the documentation validation described above and confirm the final change set
contains only the authorized documentation/notice/license files. The current
runbook still agrees with the adopted release policy, and no code, test, script,
dependency, gate, support commitment, or publication mechanism changed. Report
the stage commits and checks, and explicitly identify the release workflow as
remaining future work.

There are no open decisions required for this policy-alignment plan. Gate selection
and push strategy remain open only in the separate release-workflow roadmap.