eric/scriptorium
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity

Revise the policy alignment roadmap

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 01:11:57 +00:00
parent d6aecf5c50
commit 8452b54809
1 changed files with 187 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files

306
docs/roadmap/policy.md
View File

@@ -1,148 +1,216 @@
# Project Licensing Policy Alignment
# Standard Repository Policy Alignment
## Status
## Status And Intent
Accepted feature direction, recorded on 2026-09-26; implementation is pending.
Align the policies and supporting documentation with the agreed licensing
conventions below. This roadmap defines the target state, not an implementation
sequence. The [OSS policy](../policy/oss.md) will own the ongoing rules.
Agreed on 2026-09-28; implementation is pending. This roadmap replaces the
earlier licensing-only proposal with alignment of the complete applicable
policy set and its supporting documentation. It defines the targeted end state
and required changes, not staged implementation instructions.
## Current Baseline
The goal is identical policy language across adopting projects except where a
substantive, locally significant requirement or decision warrants customization.
Adopt upstream wording verbatim for non-substantive differences. Existing local
phrasing is not, by itself, a reason to retain a variation.
The reviewed Scriptorium revision is `39d3508`. Its earlier policy adoption
is complete; that revision's `docs/roadmap/policy.md` preserves the previous
adoption record in Git. Current policy versions are:
## Review Revision And Current Baseline
- OSS policy base version 1.1;
- documentation policy base version 1.4; and
- release policy base version 1.2.
The fixed upstream review revision is
`d84a38ebab26f048cafbe59a2246700c35d29843`.
Use the [adoption and update guide at that revision](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md)
for this adoption. The review compared current local documents directly with
that revision; reconstruction or assessment of historical adoption baselines
is not required.
The maintainer has already changed the project grant to GPL-3.0-or-later.
[COPYRIGHT](../../COPYRIGHT) follows the agreed application convention,
including project identity, copyright holder and year, SPDX expression,
grant, disclaimer, and third-party statement. [LICENSE](../../LICENSE) contains
the complete GPLv3 text; its only byte-level difference from the standard
reference is a missing final newline. No substantive rewrite is needed.
The reviewed Scriptorium revision is
`d6aecf5c50269b7d130dbf19f416a67454cd9778`. It has six adopted policies,
without per-document Upstream Source metadata, and no `docs/policy/meta.md`.
The policy targets below supersede the earlier roadmap's narrower version
targets.
Remaining differences are documentation and policy alignment:
| Policy and proposed Upstream Source | Current base | Target base | Target treatment |
| --- | --- | --- | --- |
| [agents.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md) | 1.1 | 1.3 | Adopt shared rules verbatim, including commit discipline. |
| [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md) | 1.1 | 1.3 | Adopt common principles and customize for Scriptorium's established boundaries. |
| [documentation.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md) | 1.4 | 1.11 | Adopt shared language and tailor the canonical topic map. |
| [testing.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md) | 1.1 | 1.3 | Adopt shared guidance with focused local test ownership. |
| [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md) | 1.2 | 1.4 | Adopt common rules and retain justified release choices. |
| [oss.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/oss.md) | 1.1 | 1.8 | Adopt licensing, attribution, and reference-example conventions. |
| [meta.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/meta.md) | Not adopted | 1.0 | Add provenance, local authority, and upstream discovery. |
- The README and OSS policy's README example still say BSD 3-Clause.
- Documentation ownership does not yet recognize `COPYRIGHT`, and the
attribution introduction links only to `LICENSE` for the project's terms.
- The release procedure and remaining roadmap handoffs prescribe the old
`LICENSE | ATTRIBUTION` footer.
- The contributor reading guide routes dependency and attribution work to the
OSS policy but does not explicitly include project licensing.
Every existing policy needs language and provenance updates. No adopted policy
is entirely update-free, but established application decisions, dependency
licenses, and release mechanics need no substantive change.
Dependency entries already use imported-commit source and notice links and
applicable standard and companion texts. The hosted workflow already reuses
the checked-in release note unchanged as the hosted body.
Current supporting-document gaps include the README's obsolete BSD project
license statement, the release procedure's two-link footer, an attribution
document that does not follow the new exact House Format, and orientation
guidance that requires architecture reading even for unrelated work.
The architecture policy's command inventory also omits the implemented
`config` command family.
## Targeted End State
## Target Policy Language And Local Customizations
### Licensing Policy And Ownership
Remove every `Base Policy Template` section and its adoption instructions.
Replace instructional application-specific placeholders with actual decisions;
do not leave template examples describing nonexistent components.
Adopt OSS policy base version **1.2** and documentation policy base version
**1.5**, preserving Scriptorium-specific customizations. Agent, architecture,
testing, and release policies need no changes for this adoption; their versions
remain unchanged.
Use upstream common language verbatim. Keep necessary local requirements
clearly identifiable rather than paraphrasing entire shared sections.
The following customizations are justified:
| Canonical document | Target responsibility |
| --- | --- |
| `docs/policy/oss.md` | Project licensing conventions, author choices, upstream attribution, and discoverability. |
| `COPYRIGHT` | Project identity, holders and years, SPDX expression, grant, disclaimer, and third-party statement. |
| `LICENSE` | Complete project license text and incorporated companion text where applicable. |
| `docs/oss/attribution.md` | Component-specific upstream notices and imported-source references. |
| `docs/oss/licenses/` | Applicable complete standard dependency license texts. |
- **Architecture:** preserve PromptKit and ConfigKit ownership, full support
for valid PromptKit definitions, public dependency boundaries, HTTP artifact
containment, and simple predefined-prompt execution. Preserve caller-visible
request independence alongside shared engine and backend capacity state.
These are deliberate product and safety decisions, not generic template
choices. Adopt upstream architectural principles proportionately; they do
not require a wrapper or interface for every library. Correct the command
inventory and keep concrete package mechanics in internal documentation.
- **Documentation ownership:** tailor the topic map to the executable CLI and
HTTP application. Scriptorium does not offer a reusable public Go API;
consumer guidance covers executable use and migration to PromptKit.
PromptKit remains the owner of framework formats. Use upstream wording for
generic ownership, example, and ADR guidance instead of retaining redundant
local paraphrases. Preserve accepted ADR decisions and their history.
- **Testing:** retain a short project-specific ownership section distinguishing
Scriptorium's integration and adapter tests from upstream framework/parser
tests. This prevents duplication of PromptKit and ConfigKit test matrices.
HTTP containment and shared-capacity behavior justify focused adapter
coverage. Upstream observations about domain coverage are not quotas or a
hierarchy that displaces risk-based testing.
- **Release:** preserve branch-before-tag publication, annotated tags,
Linux amd64/arm64 binaries and checksums, and asynchronous artifact delivery.
Retain race testing because the server shares concurrent engine state and
source guards because local replacements, workspaces, or vendoring can hide
unpublished dependency substitutions. Keep gate rationale in policy and
concrete commands, targets, and publication choices in the release procedure.
Upstream's optional atomic-push approach does not require a new feature.
- **OSS:** use Scriptorium's actual GPL-3.0-or-later grant in the project
example. Preserve dependency grants and the settled House Format
interpretation for upstream notice links. The code grant does not extend
to separately licensed copied policy material.
The standard defaults are GPL-3.0-or-later for applications and
LGPL-3.0-or-later for libraries. An explicit author choice takes precedence
without exception rationale, extra approval, or compensating controls. These
defaults guide new selections: adoption does not relicense existing code,
override third-party terms, or imply different grants for individual packages.
No agent-policy exception is needed: upstream already preserves the local
commit authorization and safety boundaries. Stylistic preferences, alternate
wording, and generic elaboration do not justify additional exceptions.
Scriptorium's selected grant remains the one already recorded in `COPYRIGHT`.
Holder and year information is maintained accurately, not inferred from
maintainer identity or advanced automatically. No blanket per-file-header
requirement is introduced; applicable existing notices remain preserved.
## Provenance And Public Discovery
### Discoverability
When adoption lands, each of the seven policies records its target
`Base Policy Version`, actual local adoption date in `Last Updated`, and
`Upstream Source` pointing to the exact corresponding file linked in the
table above. Do not substitute a repository homepage, moving branch, another
policy's URL, or a historical source revision for that per-document link.
Retain accurate provenance in later local edits.
The README ends with a friendly GPL v3 or later statement linking to
`COPYRIGHT`, followed by the attribution link. The attribution introduction
links to both the project grant and complete license text without duplicating
the grant.
The new local `docs/policy/meta.md` follows upstream language after removing
its template section. It establishes that adopted local policies govern the
repository and that upstream changes require deliberate adoption. Its public
discovery links remain current:
New release notes and hosted download pages end with
`COPYRIGHT | LICENSE | ATTRIBUTION`. All three links use absolute URLs at the
release's immutable tag or source revision. Upstream component links continue
identifying imported commits, not Scriptorium release tags. The release
procedure owns concrete URLs; the hosted workflow reuses the note rather than
maintaining a separate footer.
- [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy).
- [Current adoption and update guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md).
## Recommended Changes From The Baseline
Adopted-source and example links remain commit-pinned. Preserve the valid
commit-pinned example links supplied in the selected OSS policy; their asset
revision need not be rewritten merely to match the policy review revision.
Public discovery and attribution in this agreed adoption supersede the earlier
instruction not to reference the policy repository.
- **[OSS policy](../policy/oss.md):** adopt the v1.2 scope, author-choice rules,
canonical locations, coordinated maintenance, and navigation conventions.
Use Scriptorium's actual grant in examples and link to local canonical files.
- **[Documentation policy](../policy/documentation.md):** adopt the v1.5
ownership entries and project-licensing boundary. Preserve local ownership,
minimal-example guidance, ADR lifecycle, and policy metadata conventions.
Both revised policies record their new base version and actual adoption date.
- **[README](../../README.md) and [attribution](../oss/attribution.md):** correct
the stale project-license description and provide the targeted navigation.
Preserve legitimate BSD dependency attribution and grants at imported
revisions; do not infer new terms from a dependency's latest checkout.
- **[Contributor guide](../development.md):** explicitly route project-license
changes to the OSS policy and relevant canonical documents.
- **[Release procedure](../release.md):** add the immutable `COPYRIGHT` link to
the footer example and update the references to two URLs. The release policy
already delegates footer conventions to the OSS policy; this adoption needs
no release-policy version bump or automation change.
- **Active roadmap handoffs:** update or supersede still-operative old-footer
directions in the [implementation record](implementation.md) with a link to
the canonical release procedure. Preserve historical completion evidence.
- **Licensing files:** preserve the already-aligned grant and text. Restoring
`LICENSE`'s final newline is optional mechanical alignment, not a substantive
correction or new release gate. Obtain any needed standard license texts
from their public publishers; no additional license collection is needed.
## Orientation And Selective Reading
## Preserved Scope
Adapt [the upstream agent orientation](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/agents/AGENTS.md)
into [root AGENTS.md](../../AGENTS.md), preserving applicable existing
code-discovery instructions. It points to the local contributor guide and
requires the agent policy before recommendations, planning, or implementation;
it does not require reading the entire suite by default.
This adoption documents an existing author-selected grant; it does not make a
new licensing decision. It changes no dependencies, application architecture,
runtime code, or release machinery. Preserve agent commit rules, the settled
House Format interpretation of upstream notice links, and existing
source-release completion and asynchronous delivery behavior.
The [contributor guide](../development.md) gains the upstream Policy Reading
Guide table and associated selection rules, including the new meta policy.
Retain Scriptorium's task-specific contract guide alongside it. Architecture
reading becomes task-triggered rather than unconditional. Relevant policies
are read before governed decisions, multiple policies may apply, material
already available in context may be reused, and expanded scope triggers
expanded reading. Policy-reading triggers live here, not in the documentation
topic map.
There is no new publication-time network check, approval gate, scanner, SBOM,
source bundle, downloadable license asset, or modified-dependency rebuild exercise.
Concrete exceptions continue to receive the treatment specified by the adopted
OSS policy; the house format is not a universal legal-sufficiency guarantee.
## Licensing And Attribution
## Release And Historical Treatment
Follow the [canonical copied-policy attribution entry](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/policy-attribution.md).
Insert it directly beneath the prescribed attribution title and replace all
three placeholder URLs with the full review commit. Identify the actual
copied/adapted scope, including agent-orientation material and copied reading
guidance where used, rather than describing only policy files if additional
material is incorporated. Preserve creator, copyright, license, disclaimer,
and modification information through the supplied notices and links.
Apply navigation changes prospectively. Do not rewrite published notes, tags,
binaries, checksums, or hosted release bodies to retrofit them. The next release
note should explain the maintainer-selected change to GPL-3.0-or-later and link
to the canonical grant. Policy adoption does not alter historical grants.
Version selection and publication remain separate preparation work under the
[release policy](../policy/release.md).
Required supporting changes:
## Completion Criteria
- Add the complete, unmodified `docs/oss/licenses/CC-BY-SA-4.0.txt` from the
selected revision.
- Extend [COPYRIGHT](../../COPYRIGHT) to identify the adapted policy material
as CC-BY-SA-4.0 and point to attribution for exact scope. Preserve
Scriptorium's GPL-3.0-or-later code grant and existing [LICENSE](../../LICENSE).
Unrelated application documentation is not automatically relicensed.
- Reformat [attribution](../oss/attribution.md) to the v1.8 House Format:
`# Open Source Attribution Notices`, followed directly by component entries;
factual optional identification; supplied copyrights; SPDX expressions;
license/notice links with actual filename labels and terminal periods;
and `[Source](COMMIT_URL).`.
- Remove its introductory policy prose, missing-copyright filler, and
agent-authored license-scope explanations. Omit an unavailable copyright
field instead of explaining that none was invented. Preserve actual
required upstream notices, applicable license expressions, and imported
dependency revisions.
- Correct [README](../../README.md) to link its GPL v3 or later statement to
`COPYRIGHT`, followed by the attribution link.
- Update [the release procedure](../release.md) to use the prospective
`COPYRIGHT | LICENSE | ATTRIBUTION` footer, with absolute immutable-release
URLs for all three destinations. The existing hosted workflow continues
copying the checked-in release note unchanged.
- The two updated policies identify the selected base versions and actual
adoption date, preserving local customizations and settled scope.
- Current project-license descriptions agree with `COPYRIGHT`; documentation
distinguishes the grant, complete text, and upstream attribution.
- The release procedure and active handoffs agree on the three-link footer,
with hosted-body reuse and publication behavior unchanged.
- Affected local links and candidate footer paths are verified against the
repository. Future release tags need not resolve online before publication;
this is ordinary documentation review, not a new release gate.
- The final diff contains only the agreed documentation changes and any chosen
newline normalization, not changes to published history or dependency grants.
Content, link, and diff checks suffice; runtime tests are unnecessary for
this documentation-only adoption.
The documented CC-BY-SA arrangement is agreed for this adoption. Original
licensing-example formatting has upstream's CC0 permission; using it alone
does not require a separate attribution entry. Reproduced license texts and
third-party notices retain their own terms.
## Local Materials And Upstream References
Keep applicable adopted policies, Scriptorium's adapted root orientation and
developer guide, actual project notices, attribution entries, and required
license texts locally.
Keep the upstream adoption guide, README, root AGENTS.md, developer guide, and
example collection upstream. Link to them as appropriate rather than copying
them into a parallel local handbook. The upstream `agents/AGENTS.md` is the
downstream orientation template, distinct from upstream's own root AGENTS.md.
Copy only needed standard license texts, not the entire reference collection.
## Scope And Completion Criteria
This work updates policy and supporting documentation. It does not change
application code, dependency versions or grants, release scripts, publication
mechanics, or accepted ADR decisions. No new scanner, recurring synchronization
check, license approval, publication-time network probe, or release gate is
introduced. Published releases, tags, notes, and assets remain unchanged.
Completion means:
- All seven policy files use the selected versions, accurate source links,
adoption dates, and upstream common wording, with template-only content
removed and local variations limited to the justified decisions above.
- Orientation and selective reading agree, and local links resolve without
depending on a sibling checkout.
- Policy attribution and document-license scope match the material actually
incorporated; required standard texts are complete and unmodified.
- README, attribution, release navigation, and still-operative roadmap
handoffs agree with the new conventions. Supersede stale instructions in
[the implementation record](implementation.md) without rewriting historical
completion evidence. Preserve the earlier author-selected license change
in the next release's preparation context; publication remains separate work.
- Review checks the resulting rules, source/example URLs, notice facts, local
links, license-text fidelity, and final diff. Runtime tests are unnecessary
for documentation-only changes. A Git adoption record is sufficient; no
additional provenance database or recurring audit is required.
There are no unresolved policy choices for this scope.