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. backoff, parser, or repair test matrices.
Reports are included in this implementation sprint, not deferred by default. 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 The distribution decision is resolved: Stage 9 implements repository-hosted
depend on its answer, but the distribution work and release-readiness claim do. 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. No stage authorizes a tag, push, publication, or changes to historical releases.
## Stage 1: Adopt The Released Dependency And Catalog Baseline ## 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. limits, defaults remain compatible, and concurrent runs do not share collectors.
Diagnostics include no disallowed content even when an upstream error contains it. 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. Retain the existing static Linux binaries and source repositories. The selected
Once the maintainer resolves the distribution approach, record that decision approach is repository-hosted license texts and attribution, with a
here before implementing its packaging mechanics. `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 1. Add verbatim GPLv3 and LGPLv3 texts under `docs/oss/licenses/`, using
two catalog modules, against the actual tagged sources. Keep Scriptorium's `GPL-3.0.txt` and `LGPL-3.0.txt`. Obtain the texts from the selected
own license unchanged. Record dependency notices and license texts in a Promptkit release's COPYING and license text; retain the complete license
maintained third-party location and link it from the appropriate user and text without folding Promptkit's project-specific preamble into the generic
release documentation. LGPL file. Keep Scriptorium's own LICENSE unchanged.
2. For the recommended static-binary/source-material approach, provide an 2. Add `docs/oss/attribution.md` with a Promptkit heading and three
accompanying versioned source/material archive tied to the exact candidate: attribution lines: `Copyright (C) 2026 Eric Rakestraw`;
Scriptorium sources, selected dependency sources and license texts, `SPDX-License-Identifier: LGPL-3.0-or-later`, linked to the local LGPL
go.mod/go.sum, and instructions/toolchain information for rebuilding with text; and a link to the Promptkit source repository. Link the corresponding
a modified Promptkit. Include additional materials required by the resolved v0.11.0 tag as the source destination for this adoption. Make the companion
approach. Build this as a release artifact, not a committed vendor tree GPL text reachable from the document's general license-text navigation
or runtime replacement. without expanding the three-line Promptkit entry into a legal essay.
3. Update the hosted workflow's asset selection/checksum generation to include 3. Preserve any additional notices required for other distributed components,
the chosen materials with the binaries. Preserve published-asset immutability including catalog dependencies, based on their actual selected licenses.
and consistent manifests on partial-upload recovery. Update the release The agreed Promptkit entry does not determine other components' terms.
procedure's deliverable list and packaging instructions. Do not add CI Keep attribution concise; do not add a dependency audit framework.
polling, consumer-installation checks, or routine human approval gates to 4. Update the release policy and runbook to require the footer on future
source publication. release notes, with absolute URLs targeting that Scriptorium release tag's
4. Exercise archive construction and the documented rebuild procedure locally root LICENSE and `docs/oss/attribution.md`. The visible text is
using prepared dependencies and no paid calls. Verify included versions, `LICENSE | ATTRIBUTION`. Update the last-updated date of any edited
source availability, notices, and association with the binary source policy, retaining its base template version. Do not edit published notes.
revision. Record what was actually validated, not a blanket legal guarantee. 5. Keep the checked-in release document as the source of the hosted release
5. If the chosen approach differs, revise this stage's concrete packaging body. The existing workflow already uses it; no new asset packaging or
steps before coding. A source-only approach must explicitly reconcile the separately maintained hosted notice is needed. During the next release
existing asynchronous-binary workflow; simply leaving automatic binary preparation, add the footer with the selected version. Do not invent a
publication enabled would not implement that decision. 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 The full Scriptorium and Promptkit sources, applicable permissions, and existing
chosen materials/workflow exist and are tested. Do not publish upgraded build materials are the basis for modification and recombination in this
binaries while it is unresolved. This is not a new recurring release signoff. 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 ## 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 ## Open Questions
### Which Distribution Approach Will Satisfy The Upgraded Dependency Licenses? None currently. The previously open distribution question is resolved by
Stage 9's repository-hosted attribution/license texts and release footer.
The runtime interfaces above are settled for implementation. The outstanding Its implementation remains pending; resolution of the decision does not imply
decision is the applicable material/permission requirements for distributing that the notices or footer already exist.
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.

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 Proposed cross-project policy direction, based on the attribution and release
adoption requirements and implementation record. The implemented documents discoverability approach agreed for Scriptorium. This document replaces the
under `docs/policy/` own current policy; this roadmap does not authorize release completed policy-template adoption roadmap, whose history remains in Git.
publication. 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, This is a roadmap for that template, not an adopted policy or a claim that
and testing updates. All five policies have the specified provenance headers. every project or license has identical obligations. Scriptorium's concrete
- Updated repository entry points and the contributor reading guide, preserving Promptkit work is defined in [implementation Stage 9](implementation.md#stage-9-add-oss-attribution-and-release-links).
the local ADR lifecycle and executable-interface documentation ownership. Creating the upstream template and adopting it across projects are future work,
- Added [the publication command](../../scripts/release.sh) and not changes made by this document.
[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.
Use the templates in the sibling `../policy` repository at commit `45591a7` as ## Intended Scope
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.
The desired outcome is a complete, consistent policy set that preserves The policy should cover attribution and license notices for OSS components
Scriptorium's application boundaries, gives agents clear working rules, and incorporated into or distributed with a project, including relevant transitive
makes release preparation proportionate and repeatable. 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 This policy should not automatically require attribution for every tool ever
last-updated date immediately below its title. For this adoption, use today's used in development, create a full software bill of materials, approve license
date, **2026-09-26**, rather than the upstream template's last-updated date. 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 | ## Canonical Files And Ownership
| --- | --- | --- | --- |
| `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 |
Use this header shape, substituting the applicable title and base version: The proposed convention is:
```markdown | Location | Responsibility |
# Architecture Policy | --- | --- |
| `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 ## Attribution Entry Convention
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.
## 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. 1. The upstream copyright statement or statements, preserving the applicable
Update `AGENTS.md` and the [development guide](../development.md) so agents read wording rather than substituting the application's copyright holder.
it before recommending, planning, or implementing work, then follow the 2. `SPDX-License-Identifier: <identifier or expression>`, with a link to the
task-specific reading guide. Preserve other applicable repository instructions. 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 This is the standard compact form, not a three-line cap on notices that a
appropriate, simple ownership, and machinery proportionate to the actual component actually requires. Preserve additional notices or exceptions where
problem. It must discourage speculative abstractions, invented requirements, applicable. Use the actual upstream license identification; do not invent an
unsupported guarantees, and treating incidental implementation details as SPDX identifier or silently choose between licensing alternatives when that
permanent policy. 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 Prefer a source link to the revision or release used by the project where
of authorized work, review status and staged diffs, and commit those units with practical, so the source corresponding to a distribution is easy to locate.
plain English messages. Protect unrelated user changes and secrets, and do not Dependency manifests remain useful version records; do not duplicate a
bypass hooks. An explicit request to leave work uncommitted overrides the complete lockfile in the attribution document. A source link does not replace
default. This rule does not authorize pushing, publishing releases, rewriting a copyright notice or a license-text copy.
history, or committing unrelated changes.
## 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 ## Release Discoverability
[documentation policy](../policy/documentation.md), preserving its useful
Scriptorium-specific decisions:
- One canonical owner per contract, with short summaries and links elsewhere. Each new checked-in release document and its hosted download page should end
- Executable-interface consumer guidance, not a fictitious public Go API. with two links whose visible text is:
- 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.
Add ownership for agent policy and release policy. The release policy owns `LICENSE | ATTRIBUTION`
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.
Architecture policy owns deliberate constraints and normative boundaries; The first links to the project's own license; the second links to the
the [internal overview](../internal/overview.md) owns implemented component attribution document. Use absolute URLs to the files at that release's
structure. Roadmaps own planned work and implementation status. Accepted ADRs immutable tag or corresponding immutable source revision, not a moving default
may precede implementation but must not imply that planned behavior exists. branch. The links should work both when viewing the release document in the
Update reading-guide links and ownership descriptions together so old and new repository and when viewing its rendered body on the download page.
documents do not prescribe competing workflows.
## 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 The attribution document links onward to dependency sources and checked-in
package dependency. This policy refresh does not require new wrappers, license texts. Under this selected repository-hosted arrangement, the policy
interfaces, packages, or another architecture migration. 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 Apply the convention prospectively. Do not rewrite published notes, tags,
[ADR 0004](../adr/0004-definition-boundary.md): support valid prompt and profile binaries, or checksums to retrofit the footer. Follow the project's existing
definitions for the selected Promptkit version, while considering library-only release correction policy for an actual defect in published material.
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.
Preserve strict application decoding, application-owned HTTP artifact limits, ## Source Availability And Proportionality
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.
State architectural constraints deliberately rather than freezing every The intended baseline makes the project's source and relevant dependency
current implementation choice. Explain the actual artifact threat boundary: sources available with permissions and existing build materials that enable
lexical containment does not prevent operating-system symlink following. Do modification and combination. Attribution identifies where those sources can
not invent a stronger filesystem-security guarantee or require defenses be obtained.
against concurrent privileged filesystem modification as part of this update.
Keep operational mitigations and interface outcomes in their canonical owners.
## 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 Common ownership of two projects may affect their particular licensing
[testing policy](../policy/testing.md). Test sufficiency should follow the position, but is not a prerequisite or blanket exception in the reusable
established contract, realistic failure risk, and protections already supplied policy. Other dependencies and future contributors can have different owners
by other layers, rather than a mandatory matrix of possible cases. 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 ## Maintenance And Validation
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.
Use real collaborators where practical, deterministic offline tests, and no Maintain notices as part of the change that adds, removes, upgrades, copies,
required provider credentials or paid API calls. Assert meaningful behavior or changes the distribution of a relevant component. Check its selected
rather than helper structure or incidental wording. Concurrency tests must source's notices and license, update affected entries/texts, and preserve useful
follow the selected admission and queueing contract; an upstream example of history through version control rather than retaining misleading current
rejection is not a mandate to reject requests that should queue. Fuzzing, entries. Do not assume that a dependency's license is unchanged across versions.
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.
## Release Policy And Publication Workflow Proportionate review covers:
The largest functional change in this adoption is release tooling and guidance, - accurate component identification, notices, and license references;
not application behavior. Add `docs/policy/release.md` and shorten the existing - faithful copies of the required texts;
runbook around one repository-owned publication command, with its concrete - working local links and source references appropriate to the selected version;
invocation documented there. Keep CI implementation details in the workflow. - 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, Resolve an actual uncertainty about rights, missing materials, or applicable
annotated stable tags in `vMAJOR.MINOR.PATCH` form, and matching terms explicitly. Ordinary notice maintenance should not require repeated
`docs/releases/<version>.md` notes and titles. Reject invalid versions, approval of an already selected distribution approach. This policy supplements,
including leading-zero components, and tags already present locally or on the rather than replaces, normal dependency review and the project's release policy.
authoritative remote. Do not add a prerelease channel in this adoption.
Before 1.0, minor releases may change documented contracts when release notes ## Upstream Template And Local Adoption Target
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.
### 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 Follow the existing suite's provenance convention when the template is
command must establish a clean candidate on `main` that exactly matches versioned and adopted: the local policy has a Base Policy Version and a
authoritative `origin/main`, validate its version and notes, run the required Last Updated date immediately below its title. Record the real template version
checks, and bind publication to that exact commit. A changed candidate and local adoption date; do not invent a base version for this proposal.
invalidates validation. Check publication-sensitive state again where needed Template-only adoption instructions are removed from locally adopted policies.
without rerunning expensive tests on an unchanged candidate.
Use one complete deterministic offline test-suite invocation for the final Coordinate the upstream documentation and release templates so they recognize
candidate. The recommended invocation is `GOWORK=off go test -race ./...`: the OSS policy and its canonical files without duplicating its detailed rules.
it checks ordinary assertions and race behavior together, with race coverage Locally, connect the contributor reading guide to the OSS policy for dependency,
justified by the application's shared HTTP and backend operational state. attribution, and release-document changes. These are documentation/policy
Keep dependency provisioning separate from offline test execution. integration changes, not an application architecture migration.
Build both existing Linux targets, amd64 and arm64, using the release settings Completion of this roadmap means a reusable template exists, the relevant suite
(`CGO_ENABLED=0`, `-trimpath`, and `-ldflags "-s -w"`). Cross-building does not cross-references agree, and local adoption can produce clear notices and
imply requiring native test hardware for both architectures. Existing release links without speculative guarantees or unnecessary machinery.
architecture tests continue to enforce dependency boundaries. Scriptorium may implement its already-agreed Stage 9 before that upstream
template is created; the template's availability is not a release prerequisite.
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.