163 lines
9.3 KiB
Markdown
163 lines
9.3 KiB
Markdown
# 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.
|