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

Define the OSS attribution approach

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-26 15:12:09 +00:00
parent 604c1f1678
commit 5c3b0cf4f6
2 changed files with 213 additions and 311 deletions
Download Patch File Download Diff File Expand all files Collapse all files

401
docs/roadmap/policy.md
View File

@@ -1,289 +1,194 @@
# Policy Template Adoption
# OSS Attribution Policy Roadmap
## Status And Intent
## Status And Purpose
Completed and validated on 2026-09-26. This roadmap retains the accepted
adoption requirements and implementation record. The implemented documents
under `docs/policy/` own current policy; this roadmap does not authorize release
publication.
Proposed cross-project policy direction, based on the attribution and release
discoverability approach agreed for Scriptorium. This document replaces the
completed policy-template adoption roadmap, whose history remains in Git.
The existing documents under `docs/policy/` continue to govern the repository.
### Implementation Record
The target is a reusable OSS attribution policy template for the upstream policy
suite, with a locally adopted policy in each participating project. It should
standardize the location, content, discoverability, and maintenance of notices
without introducing a compliance platform or unnecessary release gates.
- Added agent and release policies and merged the architecture, documentation,
and testing updates. All five policies have the specified provenance headers.
- Updated repository entry points and the contributor reading guide, preserving
the local ADR lifecycle and executable-interface documentation ownership.
- Added [the publication command](../../scripts/release.sh) and
[local-repository regression tests](../../scripts/release_test.go), and
replaced the old release procedure with the [short runbook](../release.md).
- Retained the hosted workflow after checking its targets, flags, release-note
source, checksums, and non-overwrite settings. Recovery guidance explicitly
requires consistency with already-published manifests before adding assets.
- The complete `go test ./...` and `go test -race ./...` suites pass, including
the release-tool tests and existing CLI tests. Both declared Linux builds,
the native build, `go vet ./...`, shell syntax, changed-document links, and
whitespace checks pass. Validation used the installed Go 1.25.5 toolchain
and a temporary build cache, without provider credentials or inference calls.
- Initial sandbox restrictions on local listeners and Git metadata were
lifted before final verification. No tests were weakened or skipped to work
around them. No real tag or release was published during implementation.
This is a roadmap for that template, not an adopted policy or a claim that
every project or license has identical obligations. Scriptorium's concrete
Promptkit work is defined in [implementation Stage 9](implementation.md#stage-9-add-oss-attribution-and-release-links).
Creating the upstream template and adopting it across projects are future work,
not changes made by this document.
Use the templates in the sibling `../policy` repository at commit `45591a7` as
the adoption baseline. Customize them for Scriptorium rather than replacing
the existing policies verbatim. The sibling checkout is a review source, not a
new build, runtime, or contributor dependency.
## Intended Scope
The desired outcome is a complete, consistent policy set that preserves
Scriptorium's application boundaries, gives agents clear working rules, and
makes release preparation proportionate and repeatable.
The policy should cover attribution and license notices for OSS components
incorporated into or distributed with a project, including relevant transitive
dependencies and copied code or assets. A component's treatment follows its
actual license and how it is used or distributed, not merely whether it is
listed as a direct dependency.
## Policy Set And Provenance Headers
The baseline arrangement is an openly available project source repository,
dependency source references, and releases published alongside that repository.
The template must remain independent of programming language, forge, build
system, and particular dependency. Promptkit, Go, and Gitea are local examples,
not upstream policy requirements.
Every adopted policy document must place its base template version and local
last-updated date immediately below its title. For this adoption, use today's
date, **2026-09-26**, rather than the upstream template's last-updated date.
This policy should not automatically require attribution for every tool ever
used in development, create a full software bill of materials, approve license
compatibility, or replace applicable license terms. Distinct requirements
arising from a component or distribution channel remain relevant; the baseline
must neither erase them nor invent additional ones.
| Policy document | Adoption | Base Policy Version | Last Updated |
| --- | --- | --- | --- |
| `docs/policy/agents.md` | Add | 1.1 | 2026-09-26 |
| `docs/policy/architecture.md` | Merge with existing policy | 1.1 | 2026-09-26 |
| `docs/policy/documentation.md` | Merge with existing policy | 1.3 | 2026-09-26 |
| `docs/policy/release.md` | Add | 1.1 | 2026-09-26 |
| `docs/policy/testing.md` | Merge with existing policy | 1.1 | 2026-09-26 |
## Canonical Files And Ownership
Use this header shape, substituting the applicable title and base version:
The proposed convention is:
```markdown
# Architecture Policy
| Location | Responsibility |
| --- | --- |
| `LICENSE` | The project's own license; dependency attribution does not relicense the project. |
| `docs/oss/attribution.md` | Canonical component attributions, applicable license identifiers, and upstream source links. |
| `docs/oss/licenses/` | Complete, verbatim license texts referenced by attribution entries, including companion texts when applicable. |
| `docs/policy/oss.md` | The eventually adopted local OSS attribution policy, derived from the upstream template. |
| Release documents and hosted release pages | Discoverability through links to the release's license and attribution files, not duplicate notice inventories. |
**Base Policy Version:** 1.1
Use recognizable license filenames, such as `GPL-3.0.txt` and
`LGPL-3.0.txt`. A shared unmodified license text can serve multiple entries.
Distinct texts, exceptions, or component-specific required notices must not be
lost through deduplication. Keep license wording intact; explanations belong
in attribution or policy prose, not edits to license text.
**Last Updated:** 2026-09-26
```
A project's documentation policy owns the assignment of these canonical
locations. The OSS policy owns attribution conventions; the release policy
owns the footer requirement; the release procedure owns the concrete URL and
publication mechanics. Cross-references should avoid competing definitions.
The base version identifies the underlying upstream template, not a local
policy revision or Scriptorium release. Subsequent local revisions update the
date; the base version changes only when a newer template is adopted. Remove
upstream adoption instructions and template scaffolding from the finished
policies. All five documents must be substantive, repository-specific policy.
## Attribution Entry Convention
## Agent Guidance And Discoverability
Use a component heading or other clear identifier, followed by a concise entry:
Add `docs/policy/agents.md` as the canonical owner of coding-agent behavior.
Update `AGENTS.md` and the [development guide](../development.md) so agents read
it before recommending, planning, or implementing work, then follow the
task-specific reading guide. Preserve other applicable repository instructions.
1. The upstream copyright statement or statements, preserving the applicable
wording rather than substituting the application's copyright holder.
2. `SPDX-License-Identifier: <identifier or expression>`, with a link to the
corresponding local license text or texts.
3. A link to the component's source repository.
The policy should favor idiomatic Go, standard-library facilities where
appropriate, simple ownership, and machinery proportionate to the actual
problem. It must discourage speculative abstractions, invented requirements,
unsupported guarantees, and treating incidental implementation details as
permanent policy.
This is the standard compact form, not a three-line cap on notices that a
component actually requires. Preserve additional notices or exceptions where
applicable. Use the actual upstream license identification; do not invent an
SPDX identifier or silently choose between licensing alternatives when that
choice is unresolved. A nonstandard license should be identified accurately
and accompanied by its text.
Adopt the upstream local-commit default: complete and validate coherent units
of authorized work, review status and staged diffs, and commit those units with
plain English messages. Protect unrelated user changes and secrets, and do not
bypass hooks. An explicit request to leave work uncommitted overrides the
default. This rule does not authorize pushing, publishing releases, rewriting
history, or committing unrelated changes.
Prefer a source link to the revision or release used by the project where
practical, so the source corresponding to a distribution is easy to locate.
Dependency manifests remain useful version records; do not duplicate a
complete lockfile in the attribution document. A source link does not replace
a copyright notice or a license-text copy.
## Documentation Ownership
Make companion license texts reachable through concise document navigation.
For example, an LGPL entry may link its SPDX line to the local LGPL text while
the document also exposes the incorporated GPL text. Readers should not need
to infer where that companion document is stored.
Merge the updated documentation template into the existing
[documentation policy](../policy/documentation.md), preserving its useful
Scriptorium-specific decisions:
## Release Discoverability
- One canonical owner per contract, with short summaries and links elsewhere.
- Executable-interface consumer guidance, not a fictitious public Go API.
- Tested minimal orientation examples and complete copyable assets in
`examples/`.
- No irrelevant placeholder documents or template-only TODO sections.
- The existing ADR lifecycle, including proposed, accepted, rejected, and
superseded decisions; immutable accepted decision content; and reciprocal
supersession links.
Each new checked-in release document and its hosted download page should end
with two links whose visible text is:
Add ownership for agent policy and release policy. The release policy owns
versioning, compatibility, integrity, gate selection, publication controls,
immutability, and the definition of release completion. The
[release runbook](../release.md) owns concrete repository commands and recovery
procedures. Version-specific notes remain immutable release history.
`LICENSE | ATTRIBUTION`
Architecture policy owns deliberate constraints and normative boundaries;
the [internal overview](../internal/overview.md) owns implemented component
structure. Roadmaps own planned work and implementation status. Accepted ADRs
may precede implementation but must not imply that planned behavior exists.
Update reading-guide links and ownership descriptions together so old and new
documents do not prescribe competing workflows.
The first links to the project's own license; the second links to the
attribution document. Use absolute URLs to the files at that release's
immutable tag or corresponding immutable source revision, not a moving default
branch. The links should work both when viewing the release document in the
repository and when viewing its rendered body on the download page.
## Architecture Refinements
Where publication already derives the hosted release body from the checked-in
document, preserve that single source. Do not maintain a second notice list
or footer by hand. Where a platform uses a different mechanism, the local
release procedure specifies how the same links reach recipients.
Retain the existing adapter-oriented architecture and supported Promptkit root
package dependency. This policy refresh does not require new wrappers,
interfaces, packages, or another architecture migration.
The attribution document links onward to dependency sources and checked-in
license texts. Under this selected repository-hosted arrangement, the policy
does not additionally require separate downloadable license assets, a combined
source archive, or a new binary package format by default. Different channels,
such as offline distribution or a package registry without the repository's
release page, need treatment appropriate to that channel and its actual terms;
the footer convention is not a universal legal-sufficiency guarantee.
Explicitly connect the policy to
[ADR 0004](../adr/0004-definition-boundary.md): support valid prompt and profile
definitions for the selected Promptkit version, while considering library-only
features individually. Requests remain independent from the caller's
perspective; shared process-scoped engines, backend capacity accounting,
in-flight coordination, and lifecycle state remain permitted and, when needed
to enforce limits, required. Do not describe the application as internally
stateless or introduce conversation and durable workflow responsibilities.
Apply the convention prospectively. Do not rewrite published notes, tags,
binaries, or checksums to retrofit the footer. Follow the project's existing
release correction policy for an actual defect in published material.
Preserve strict application decoding, application-owned HTTP artifact limits,
and the separation between tagged upstream dependencies and Scriptorium's
executable adapters. Retain the existing guards against local replacements,
committed workspaces, vendored Promptkit implementation, and unsupported
imports.
## Source Availability And Proportionality
State architectural constraints deliberately rather than freezing every
current implementation choice. Explain the actual artifact threat boundary:
lexical containment does not prevent operating-system symlink following. Do
not invent a stronger filesystem-security guarantee or require defenses
against concurrent privileged filesystem modification as part of this update.
Keep operational mitigations and interface outcomes in their canonical owners.
The intended baseline makes the project's source and relevant dependency
sources available with permissions and existing build materials that enable
modification and combination. Attribution identifies where those sources can
be obtained.
## Risk-Based Testing
Do not automatically add a special modified-dependency rebuild tutorial,
verification exercise, relinking harness, source-bundle build, or dynamic-linking
migration when the existing sources, permissions, and build materials already
enable that work. If something actually needed is missing, address that gap
rather than assuming either that all source links suffice or that extra
machinery is always mandatory.
Merge the updated testing template into the
[testing policy](../policy/testing.md). Test sufficiency should follow the
established contract, realistic failure risk, and protections already supplied
by other layers, rather than a mandatory matrix of possible cases.
Common ownership of two projects may affect their particular licensing
position, but is not a prerequisite or blanket exception in the reusable
policy. Other dependencies and future contributors can have different owners
and terms. The upstream template should encode the attribution practice, not
depend on Scriptorium and Promptkit sharing a copyright holder.
Preserve existing coverage responsibilities for configuration precedence and
strict decoding; CLI streams, summaries, exits, and representative workflows;
HTTP DTOs, limits, statuses, and artifact restrictions; deterministic prepared
run and definition-inspection presentation; and architecture boundaries.
Promptkit remains responsible for framework semantics, while Scriptorium's
compatibility fixtures protect its adapter plumbing.
## Maintenance And Validation
Use real collaborators where practical, deterministic offline tests, and no
required provider credentials or paid API calls. Assert meaningful behavior
rather than helper structure or incidental wording. Concurrency tests must
follow the selected admission and queueing contract; an upstream example of
rejection is not a mandate to reject requests that should queue. Fuzzing,
matrices, and other techniques are options justified by risk, not universal
requirements. This adoption is not a blanket test rewrite or an excuse to
remove valuable compatibility coverage.
Maintain notices as part of the change that adds, removes, upgrades, copies,
or changes the distribution of a relevant component. Check its selected
source's notices and license, update affected entries/texts, and preserve useful
history through version control rather than retaining misleading current
entries. Do not assume that a dependency's license is unchanged across versions.
## Release Policy And Publication Workflow
Proportionate review covers:
The largest functional change in this adoption is release tooling and guidance,
not application behavior. Add `docs/policy/release.md` and shorten the existing
runbook around one repository-owned publication command, with its concrete
invocation documented there. Keep CI implementation details in the workflow.
- accurate component identification, notices, and license references;
- faithful copies of the required texts;
- working local links and source references appropriate to the selected version;
- release footer destinations matching the intended release's file layout; and
- preservation of the footer by the existing publication mechanism.
### Versioning And Release Identity
A future release tag need not be remotely resolvable before it is published.
Validate its intended paths against the candidate source. Do not turn link
checking into a publication-time network gate, CI polling loop, or recurring
manual legal signoff. Dedicated scanners, exhaustive dependency inventories,
and new compliance tooling are not required by this baseline; add machinery
only for a concrete unmet need.
Retain `origin` as the authoritative remote, `main` as the release branch,
annotated stable tags in `vMAJOR.MINOR.PATCH` form, and matching
`docs/releases/<version>.md` notes and titles. Reject invalid versions,
including leading-zero components, and tags already present locally or on the
authoritative remote. Do not add a prerelease channel in this adoption.
Resolve an actual uncertainty about rights, missing materials, or applicable
terms explicitly. Ordinary notice maintenance should not require repeated
approval of an already selected distribution approach. This policy supplements,
rather than replaces, normal dependency review and the project's release policy.
Before 1.0, minor releases may change documented contracts when release notes
explain the impact and required action; patch releases preserve the minor
line's compatibility. From 1.0 onward, use normal semantic-versioning
compatibility rules. Preserve cross-project tagged-release boundaries rather
than reviving migration-specific dependency audits.
## Upstream Template And Local Adoption Target
### A Single Validated Candidate
The eventual upstream template should contain the general conventions above,
with no Scriptorium-specific paths beyond the shared documentation convention,
no Promptkit version pin, and no assumptions about Gitea URL syntax. Its
adoption guidance should ask each project to identify its license location,
source/release host, distribution channels, and publication mechanism.
Publish the intended `main` commit before invoking the release command. The
command must establish a clean candidate on `main` that exactly matches
authoritative `origin/main`, validate its version and notes, run the required
checks, and bind publication to that exact commit. A changed candidate
invalidates validation. Check publication-sensitive state again where needed
without rerunning expensive tests on an unchanged candidate.
Follow the existing suite's provenance convention when the template is
versioned and adopted: the local policy has a Base Policy Version and a
Last Updated date immediately below its title. Record the real template version
and local adoption date; do not invent a base version for this proposal.
Template-only adoption instructions are removed from locally adopted policies.
Use one complete deterministic offline test-suite invocation for the final
candidate. The recommended invocation is `GOWORK=off go test -race ./...`:
it checks ordinary assertions and race behavior together, with race coverage
justified by the application's shared HTTP and backend operational state.
Keep dependency provisioning separate from offline test execution.
Coordinate the upstream documentation and release templates so they recognize
the OSS policy and its canonical files without duplicating its detailed rules.
Locally, connect the contributor reading guide to the OSS policy for dependency,
attribution, and release-document changes. These are documentation/policy
integration changes, not an application architecture migration.
Build both existing Linux targets, amd64 and arm64, using the release settings
(`CGO_ENABLED=0`, `-trimpath`, and `-ldflags "-s -w"`). Cross-building does not
imply requiring native test hardware for both architectures. Existing
architecture tests continue to enforce dependency boundaries.
Remove unconditional duplicate test runs, migration-era exact Promptkit
version audits, repeated example checks, broad documentation-link scans, and
other release gates without a distinct release-risk justification. Formatting,
vetting, affected examples, and documentation validation remain appropriate
change-development checks; they need not all be repeated as publication gates.
Do not introduce a persistent validation cache or a new platform matrix.
Ignored local build products are not inherently release blockers and do not
justify broad cleanup. Normal change review still protects against tracked
junk and secrets.
### Source Publication And Asynchronous Delivery
Create the annotated tag for the validated commit using its release notes and
push only that explicit tag ref. Do not force-push or publish all local tags.
A successful tag push completes source publication. Report binary delivery
separately as asynchronous and unverified unless actually checked.
Preserve the hosted workflow's Linux amd64/arm64 binaries, release-note body,
and `SHA256SUMS` delivery. Align the workflow only where needed to support the
policy. CI polling, artifact downloads, consumer installation checks, module
availability checks, and remote readback after an unequivocally successful
push are optional diagnostics, not completion gates. Failed or ambiguous
pushes require authoritative remote-state resolution before reporting success
or deciding whether to retry.
Published tags, source release notes, binaries, and checksums remain immutable.
Transient CI, authentication, or network failures do not automatically require
a new version: missing assets may be delivered later for the same tag without
overwriting existing assets or creating inconsistent checksum manifests.
Corrections that change published contents require a corrective commit and a
new version. Recovery guidance must distinguish these situations.
Version selection, release-note preparation, and retirement of completed
roadmaps are normal preparation work, not additional approval or signoff gates.
Preserve deferred work and useful references when retiring roadmap material.
## Adoption Sequence
The completed implementation covers these three adoption units:
1. **Working guidance:** add agent policy; merge documentation and testing
policies; add their provenance headers; update `AGENTS.md` and contributor
navigation. Preserve local ADR and application-consumer conventions.
2. **Architectural clarity:** merge architecture-template refinements, add its
header, and connect the policy to ADR 0004 and the actual threat scope
without changing runtime behavior or historical decisions.
3. **Release simplification:** add release policy and its header, implement and
validate the publication command, simplify the runbook, and align workflow
and documentation ownership references as necessary. Land the new release
procedure with its working tooling rather than documenting a command that
does not yet exist.
This sequence is an adoption outline, not an application-feature implementation
plan. Current policy is maintained in the adopted policy documents.
## Validation And Completion
The adoption is complete when:
- All five policies have the specified base-version and last-updated headers,
substantive local content, and no upstream adoption scaffolding.
- Repository entry points lead to the appropriate policy, links resolve, and
ownership is consistent across policy, runbook, ADRs, and internal docs.
- Existing product boundaries, compatibility protections, and security claims
are preserved without speculative guarantees or unrelated refactoring.
- The release command enforces the exact validated candidate and explicit tag
publication, and the runbook clearly distinguishes source completion from
optional delivery verification and recovery.
- Release-tool tests use temporary local Git repositories rather than real
publication. Cover meaningful failures such as invalid or reused versions,
dirty or staged changes, wrong branch or remote mismatch, missing or
mismatched notes, failed validation, a changed candidate, and ambiguous push
outcomes, as well as successful publication of a clean published candidate.
Keep this coverage proportionate; do not require external CI or providers.
- Published-content immutability and safe missing-artifact recovery remain
intact. No actual release is created merely to validate this adoption.
Application features, Promptkit upgrades, rewriting accepted ADR decisions,
editing historical published release notes, and release publication are outside
this roadmap's implementation scope.
Completion of this roadmap means a reusable template exists, the relevant suite
cross-references agree, and local adoption can produce clear notices and
release links without speculative guarantees or unnecessary machinery.
Scriptorium may implement its already-agreed Stage 9 before that upstream
template is created; the template's availability is not a release prerequisite.