diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 33cd388..f681e88 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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. diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md index 8a8b710..3a7baab 100644 --- a/docs/roadmap/policy.md +++ b/docs/roadmap/policy.md @@ -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: `, 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/.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.