Plan standard policy alignment

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.