From 843d07b63642afa5f2f3faedb83f280676e044c1 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 27 Sep 2026 21:10:12 +0000 Subject: [PATCH] Plan standard policy alignment --- docs/roadmap/policy.md | 162 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 docs/roadmap/policy.md diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md new file mode 100644 index 0000000..be7874f --- /dev/null +++ b/docs/roadmap/policy.md @@ -0,0 +1,162 @@ +# Standard Policy Alignment + +**Status:** Accepted scope; not yet implemented. + +## Purpose + +Align Promptkit's adopted policies with Standard Repository Policies, establish +reproducible adoption provenance, and make future updates straightforward. +Use upstream language verbatim wherever differences are non-substantive. +Retain local differences only for a substantive project-specific reason. + +This roadmap defines the target and required changes. A separate implementation +plan may divide the work into stages; this document does not implement policy. + +## Comparison Baselines + +The reviewed Promptkit baseline is +`dc6fd2752dfa3f4e49e97af26681e5f2ee8fc2e2`, including the maintainer's factual +attribution cleanup. + +The selected upstream revision is +`d84a38ebab26f048cafbe59a2246700c35d29843`. +Use its [adoption and update guide](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md) +and policy documents as the fixed implementation reference. Do not silently +switch to a newer upstream revision during this work. + +No current local policy has `Upstream Source` metadata. Historical roadmap +evidence in Promptkit commit `5843cee` identifies upstream +`dafa823981004d4d58a5eb1b59a84ffebbd979da` as the comparison baseline for the +last OSS, documentation, and release-policy alignment. Exact original adoption +baselines for agents, architecture, and testing cannot be established from the +reviewed records. Version labels are not proof of an exact source revision. + +The new adoption records must identify the revision actually incorporated by +this update, not claim to reconstruct uncertain historical provenance. + +## Target End State + +### Common Wording And Local Authority + +Adopt applicable upstream text verbatim, removing template instructions and +substituting required project metadata. Do not retain local paraphrases, +formatting preferences, or redundant explanations merely because they already +exist. This applies to agent and release policies even where their substantive +requirements need no change. + +Preserve deliberate local decisions and project-specific requirements. Keep +necessary customizations localized and their reasons identifiable in the +relevant policy; no separate exception registry or approval mechanism is needed. +Architecture requires substantial customization for Promptkit's actual library +boundaries. A shorter upstream formulation is not permission to weaken an +established local contract, nor is existing wording alone proof of a deliberate +exception. + +Local adopted policies remain authoritative. Future upstream revisions become +local policy only through deliberate adoption. + +### Policy Inventory And Changes + +| File under `docs/policy/` | Current → selected base version | Target | +| --- | --- | --- | +| `meta.md` | Absent → 1.0 | Add upstream origin, local authority, adoption provenance, and discovery links. Keep detailed adoption procedure upstream. | +| `agents.md` | 1.1 → 1.3 | Use upstream wording for equivalent rules. Preserve substantive local safeguards concerning established contracts, authority for restrictions, and unrelated work only where the upstream text does not already express them. | +| `architecture.md` | 1.0 → 1.3 | Incorporate the distinction between adopted constraints and implemented structure, proportionate boundaries, and requirement-grounded threat scope. Retain the public facade, internal dependency direction, and consumer/library separation. | +| `testing.md` | 1.0 → 1.3 | Adopt risk-based selection, contract-grounded tests, and the clarified concurrency example. Preserve Promptkit's offline suite, public/internal test ownership, and established validation workflow. | +| `documentation.md` | 1.5 → 1.11 | Add meta-policy ownership and factual attribution scope. Preserve GoDoc ownership of exact exported contracts and the library's format, integration, consumer, and internal-document owners. | +| `oss.md` | 1.2 → 1.8 | Adopt the precise House Format, copied-document treatment, upstream reference links, and separate document-license scope. Remove obsolete private-repository treatment and stale attribution instructions. | +| `release.md` | 1.2 → 1.4 | Normalize equivalent language and add provenance while preserving the existing source-only process and compatibility decisions. No release-mechanics change is required. | + +Every adopted policy, including `meta.md`, records its actual Base Policy +Version, local adoption date as Last Updated, and an Upstream Source link to +that exact upstream document at the selected full commit. + +Agent and release policies require no new substantive restrictions. Retain +Promptkit's successful-tag-push completion point, no CI or module-availability +wait, selected automated checks, fixed release-note structure, immutable +published records, and catalog-profile compatibility exception. Do not replace +these decisions with upstream options intended for other projects. + +### Orientation And Selective Reading + +Adapt upstream `agents/AGENTS.md` into the root `AGENTS.md`, preserving any +unrelated repository instructions. Route orientation through +`docs/development.md` and require agent-policy reading before recommendations, +planning, or implementation. + +Merge the adoption guide's Policy Reading Guide into `docs/development.md`. +Include the meta-policy trigger for adoption and update work, and retain useful +project-specific task routing. Remove the blanket requirement to read +architecture before every change. Read policies by task, reuse unchanged +material already in context, follow relevant cross-references, and expand +reading when scope expands. The documentation policy owns topic ownership, +not a duplicate reading-trigger table. + +### Discovery And Provenance Links + +In `meta.md`, retain the upstream project URL and the current +`docs/adoption.md` URL as discovery links. Keep per-document adopted-source +links, formal attribution links, and reference-example links pinned to commits. +Existing example links may identify an earlier upstream commit that contains +the referenced asset; discovery and imported-source links have different roles. + +The reviewed adoption guide is publicly accessible. This approved update +supersedes the earlier local prohibition on policy-repository links. Do not +require publishing another repository or introduce a network-availability gate. + +### Attribution And Document Licensing + +Preserve the existing factual dependency entries in +`docs/oss/attribution.md`. Add the selected upstream revision's canonical +`examples/licensing/policy-attribution.md` entry beneath the title, substituting +the full commit in its URLs and accurately identifying copied/adapted material. +Include the adapted root agent instructions if used; do not label all unrelated +documentation as copied policy material. + +Retain the supplied creator, copyright, license, and notice links, including +upstream COPYRIGHT, and identify adaptation in the concise Material statement. +Do not restore research narratives, compliance commentary, or an introductory +essay. Merely consulting upstream guidance is distinct from copying or adapting +its documents. + +Add a scoped statement to Promptkit's root `COPYRIGHT` that policy documents +adapted from Standard Repository Policies remain CC-BY-SA-4.0, pointing to the +attribution entry for affected material and license information. Keep the +library's LGPL-3.0-or-later grant unchanged. Retain the existing +`docs/oss/licenses/CC-BY-SA-4.0.txt`, which matches the selected upstream text. +The project `LICENSE` requires no change. + +Original licensing-example formatting is CC0 under the selected upstream grant. +Using that formatting alone does not require a policy attribution entry or a +new local example collection. Standard license texts retain their own terms. + +### Local Materials And Upstream References + +Keep customized policies, project orientation, actual COPYRIGHT and attribution +notices, and applicable standard license texts locally. Keep the upstream +README, root AGENTS, contributor guide, adoption guide, and example collection +upstream. Adapt `agents/AGENTS.md`, not the upstream repository's own root +agent instructions. Link to reference examples from the adopted OSS policy; +do not copy their collection into Promptkit's runnable `examples/`. + +## Scope And Completion + +This is documentation work only. No runtime, API, dependency, test-suite, release +script, publication-channel, or library-license changes are needed. Do not add +scanners, recurring synchronization, approval gates, or new threat guarantees. +Do not rewrite published releases to retrofit adoption metadata. + +The [future roadmap](future.md)'s remaining standard-policy-alignment idea is +covered by this scope. Remove that entry when implementation is complete, +preserving unrelated future and deferred work. + +Completion means the selected upstream wording is used wherever applicable, +substantive Promptkit exceptions are preserved and identifiable, all adopted +policies have accurate provenance, reading guidance is selective, and copied +policy licensing and attribution follow the selected guide. Validate affected +local links and anchors, source/example destinations, license-text fidelity, +metadata, and whitespace proportionately. No full code audit or new permanent +validation gate is required. + +Retire this roadmap after completion, leaving durable rules and provenance in +their canonical owners. No significant design decisions remain open.