From 12a03dbb9adb47dff6548d514c1051f43f8f9e7c Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 28 Sep 2026 00:21:11 +0000 Subject: [PATCH] Plan staged policy documentation alignment --- docs/roadmap/implementation.md | 246 +++++++++++++++++++++++++++++++++ docs/roadmap/policy.md | 6 +- 2 files changed, 249 insertions(+), 3 deletions(-) create mode 100644 docs/roadmap/implementation.md diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md new file mode 100644 index 0000000..dbc5f1b --- /dev/null +++ b/docs/roadmap/implementation.md @@ -0,0 +1,246 @@ +# 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 + +### 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. diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md index 99e3e45..3346669 100644 --- a/docs/roadmap/policy.md +++ b/docs/roadmap/policy.md @@ -1,6 +1,6 @@ # Standard Policy Documentation Alignment -Status: accepted target; implementation planning remains separate. +Status: accepted target; execution is defined in the [implementation plan](implementation.md). ## Intent and baseline @@ -104,5 +104,5 @@ remain intact. Documentation-link and whitespace checks, license-text comparison and ordinary content review provide proportionate validation. No synchronization service, scanner, legal sign-off, or new release gate is introduced. -Detailed stages and executable implementation instructions belong in a later -implementation plan. This roadmap authorizes neither publication nor a release. +This roadmap defines the desired end state and local policy choices. It +authorizes neither publication nor a release.