promptkit/docs/roadmap/policy.md

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 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'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.