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

123
docs/roadmap/implementation.md
View File

@@ -62,8 +62,10 @@ that built-in retry policy. Do not duplicate upstream's complete status,
backoff, parser, or repair test matrices.
Reports are included in this implementation sprint, not deferred by default.
Stage 9 has one explicit prerequisite in Open Questions. Stages 1–8 do not
depend on its answer, but the distribution work and release-readiness claim do.
The distribution decision is resolved: Stage 9 implements repository-hosted
attribution and license texts, made discoverable through release-note footers.
The [OSS attribution policy roadmap](policy.md) generalizes that approach for
future upstream template adoption; that separate adoption is not a prerequisite.
No stage authorizes a tag, push, publication, or changes to historical releases.
## Stage 1: Adopt The Released Dependency And Catalog Baseline
@@ -386,44 +388,62 @@ Acceptance: opt-in works for success and errors, reports participate in response
limits, defaults remain compatible, and concurrent runs do not share collectors.
Diagnostics include no disallowed content even when an upstream error contains it.
## Stage 9: Resolve And Implement Binary Distribution Materials
## Stage 9: Add OSS Attribution And Release Links
**Status: Pending; requires the decision in Open Questions.**
**Status: Pending; distribution approach settled.**
Do not turn the recommendation below into an assertion of legal sufficiency.
Once the maintainer resolves the distribution approach, record that decision
here before implementing its packaging mechanics.
Retain the existing static Linux binaries and source repositories. The selected
approach is repository-hosted license texts and attribution, with a
`LICENSE | ATTRIBUTION` footer in each new release document and hosted release
page. This is the maintainer's selected arrangement, not a general assertion
that repository co-location satisfies every license or distribution model.
1. Inventory licenses and notices for the selected module graph, including the
two catalog modules, against the actual tagged sources. Keep Scriptorium's
own license unchanged. Record dependency notices and license texts in a
maintained third-party location and link it from the appropriate user and
release documentation.
2. For the recommended static-binary/source-material approach, provide an
accompanying versioned source/material archive tied to the exact candidate:
Scriptorium sources, selected dependency sources and license texts,
go.mod/go.sum, and instructions/toolchain information for rebuilding with
a modified Promptkit. Include additional materials required by the resolved
approach. Build this as a release artifact, not a committed vendor tree
or runtime replacement.
3. Update the hosted workflow's asset selection/checksum generation to include
the chosen materials with the binaries. Preserve published-asset immutability
and consistent manifests on partial-upload recovery. Update the release
procedure's deliverable list and packaging instructions. Do not add CI
polling, consumer-installation checks, or routine human approval gates to
source publication.
4. Exercise archive construction and the documented rebuild procedure locally
using prepared dependencies and no paid calls. Verify included versions,
source availability, notices, and association with the binary source
revision. Record what was actually validated, not a blanket legal guarantee.
5. If the chosen approach differs, revise this stage's concrete packaging
steps before coding. A source-only approach must explicitly reconcile the
existing asynchronous-binary workflow; simply leaving automatic binary
publication enabled would not implement that decision.
1. Add verbatim GPLv3 and LGPLv3 texts under `docs/oss/licenses/`, using
`GPL-3.0.txt` and `LGPL-3.0.txt`. Obtain the texts from the selected
Promptkit release's COPYING and license text; retain the complete license
text without folding Promptkit's project-specific preamble into the generic
LGPL file. Keep Scriptorium's own LICENSE unchanged.
2. Add `docs/oss/attribution.md` with a Promptkit heading and three
attribution lines: `Copyright (C) 2026 Eric Rakestraw`;
`SPDX-License-Identifier: LGPL-3.0-or-later`, linked to the local LGPL
text; and a link to the Promptkit source repository. Link the corresponding
v0.11.0 tag as the source destination for this adoption. Make the companion
GPL text reachable from the document's general license-text navigation
without expanding the three-line Promptkit entry into a legal essay.
3. Preserve any additional notices required for other distributed components,
including catalog dependencies, based on their actual selected licenses.
The agreed Promptkit entry does not determine other components' terms.
Keep attribution concise; do not add a dependency audit framework.
4. Update the release policy and runbook to require the footer on future
release notes, with absolute URLs targeting that Scriptorium release tag's
root LICENSE and `docs/oss/attribution.md`. The visible text is
`LICENSE | ATTRIBUTION`. Update the last-updated date of any edited
policy, retaining its base template version. Do not edit published notes.
5. Keep the checked-in release document as the source of the hosted release
body. The existing workflow already uses it; no new asset packaging or
separately maintained hosted notice is needed. During the next release
preparation, add the footer with the selected version. Do not invent a
release version or create a release solely to exercise this stage.
6. Link the attribution document from README and assign ownership of
attribution/license files in the documentation policy. Check local license
links and the release-footer URL construction against the tagged-file
layout and existing note-to-hosted-body flow. A not-yet-published tag need
not resolve online before publication. Review the copied texts for fidelity.
No live publication or network-dependent release gate is required.
Acceptance: the adoption-specific distribution question is resolved and the
chosen materials/workflow exist and are tested. Do not publish upgraded
binaries while it is unresolved. This is not a new recurring release signoff.
The full Scriptorium and Promptkit sources, applicable permissions, and existing
build materials are the basis for modification and recombination in this
arrangement. Do not add a separate source/material archive, standalone license
download assets, special modified-library rebuild instructions or verification
exercise, dynamic linking, or a recurring legal-approval gate merely for this
adoption. This does not excuse addressing an actual missing source/build
material or a distinct dependency obligation if one is found.
Acceptance: attribution and both license texts exist and are linked; future
release preparation specifies the version-specific footer; the existing
workflow carries that footer to the hosted page. Binary packaging, checksum
behavior, source-publication completion, and historical releases stay intact.
The broader upstream policy template remains separate future work.
## Stage 10: Verify The Integrated End State And Prepare The Handoff
@@ -462,30 +482,7 @@ publication still follows the existing release policy and requires authorization
## Open Questions
### Which Distribution Approach Will Satisfy The Upgraded Dependency Licenses?
The runtime interfaces above are settled for implementation. The outstanding
decision is the applicable material/permission requirements for distributing
Scriptorium's statically linked binaries with LGPL-3.0-or-later Promptkit and
the other selected dependencies. The roadmap identified this as a prerequisite;
this plan cannot establish legal sufficiency from a dependency version alone.
**Recommended approach:** retain the current static Linux binary delivery and
add a version-matched source/license/rebuild-material archive as outlined in
Stage 9. Have the maintainer confirm the applicable requirements and whether
those materials and permissions are sufficient before finalizing packaging.
This preserves the established installation model and gives recipients an
auditable route to rebuild with a modified library. It is an adoption-specific
decision, not a proposal for a manual gate on every release.
**Viable alternative:** defer upgraded binary distribution and deliver source
only while the requirements are resolved. This avoids claiming that an
unreviewed binary package is ready, but reduces installation convenience and
requires an explicit change to the current binary-delivery workflow and its
documentation. Another possible route is obtaining suitable additional
distribution permission from the relevant rights holders; its availability
must be confirmed, not assumed.
**Impact:** settle this before Stage 9 and before any tag that would trigger
upgraded binary distribution. No runtime implementation stage needs to wait,
but the full distribution end state must remain incomplete until resolved.
None currently. The previously open distribution question is resolved by
Stage 9's repository-hosted attribution/license texts and release footer.
Its implementation remains pending; resolution of the decision does not imply
that the notices or footer already exist.

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.