scriptorium/docs/roadmap/policy.md

Standard Repository Policy Alignment

Status And Intent

Agreed on 2026-09-28; implementation is pending. This roadmap replaces the earlier licensing-only proposal with alignment of the complete applicable policy set and its supporting documentation. It defines the targeted end state and required changes, not staged implementation instructions.

The goal is identical policy language across adopting projects except where a substantive, locally significant requirement or decision warrants customization. Adopt upstream wording verbatim for non-substantive differences. Existing local phrasing is not, by itself, a reason to retain a variation.

Review Revision And Current Baseline

The fixed upstream review revision is d84a38ebab26f048cafbe59a2246700c35d29843. Use the adoption and update guide at that revision for this adoption. The review compared current local documents directly with that revision; reconstruction or assessment of historical adoption baselines is not required.

The reviewed Scriptorium revision is d6aecf5c50269b7d130dbf19f416a67454cd9778. It has six adopted policies, without per-document Upstream Source metadata, and no docs/policy/meta.md. The policy targets below supersede the earlier roadmap's narrower version targets.

Policy and proposed Upstream Source	Current base	Target base	Target treatment
agents.md	1.1	1.3	Adopt shared rules verbatim, including commit discipline.
architecture.md	1.1	1.3	Adopt common principles and customize for Scriptorium's established boundaries.
documentation.md	1.4	1.11	Adopt shared language and tailor the canonical topic map.
testing.md	1.1	1.3	Adopt shared guidance with focused local test ownership.
release.md	1.2	1.4	Adopt common rules and retain justified release choices.
oss.md	1.1	1.8	Adopt licensing, attribution, and reference-example conventions.
meta.md	Not adopted	1.0	Add provenance, local authority, and upstream discovery.

Every existing policy needs language and provenance updates. No adopted policy is entirely update-free, but established application decisions, dependency licenses, and release mechanics need no substantive change.

Current supporting-document gaps include the README's obsolete BSD project license statement, the release procedure's two-link footer, an attribution document that does not follow the new exact House Format, and orientation guidance that requires architecture reading even for unrelated work. The architecture policy's command inventory also omits the implemented config command family.

Target Policy Language And Local Customizations

Remove every Base Policy Template section and its adoption instructions. Replace instructional application-specific placeholders with actual decisions; do not leave template examples describing nonexistent components.

Use upstream common language verbatim. Keep necessary local requirements clearly identifiable rather than paraphrasing entire shared sections. The following customizations are justified:

• Architecture: preserve PromptKit and ConfigKit ownership, full support for valid PromptKit definitions, public dependency boundaries, HTTP artifact containment, and simple predefined-prompt execution. Preserve caller-visible request independence alongside shared engine and backend capacity state. These are deliberate product and safety decisions, not generic template choices. Adopt upstream architectural principles proportionately; they do not require a wrapper or interface for every library. Correct the command inventory and keep concrete package mechanics in internal documentation.
• Documentation ownership: tailor the topic map to the executable CLI and HTTP application. Scriptorium does not offer a reusable public Go API; consumer guidance covers executable use and migration to PromptKit. PromptKit remains the owner of framework formats. Use upstream wording for generic ownership, example, and ADR guidance instead of retaining redundant local paraphrases. Preserve accepted ADR decisions and their history.
• Testing: retain a short project-specific ownership section distinguishing Scriptorium's integration and adapter tests from upstream framework/parser tests. This prevents duplication of PromptKit and ConfigKit test matrices. HTTP containment and shared-capacity behavior justify focused adapter coverage. Upstream observations about domain coverage are not quotas or a hierarchy that displaces risk-based testing.
• Release: preserve branch-before-tag publication, annotated tags, Linux amd64/arm64 binaries and checksums, and asynchronous artifact delivery. Retain race testing because the server shares concurrent engine state and source guards because local replacements, workspaces, or vendoring can hide unpublished dependency substitutions. Keep gate rationale in policy and concrete commands, targets, and publication choices in the release procedure. Upstream's optional atomic-push approach does not require a new feature.
• OSS: use Scriptorium's actual GPL-3.0-or-later grant in the project example. Preserve dependency grants and the settled House Format interpretation for upstream notice links. The code grant does not extend to separately licensed copied policy material.

No agent-policy exception is needed: upstream already preserves the local commit authorization and safety boundaries. Stylistic preferences, alternate wording, and generic elaboration do not justify additional exceptions.

Provenance And Public Discovery

When adoption lands, each of the seven policies records its target Base Policy Version, actual local adoption date in Last Updated, and Upstream Source pointing to the exact corresponding file linked in the table above. Do not substitute a repository homepage, moving branch, another policy's URL, or a historical source revision for that per-document link. Retain accurate provenance in later local edits.

The new local docs/policy/meta.md follows upstream language after removing its template section. It establishes that adopted local policies govern the repository and that upstream changes require deliberate adoption. Its public discovery links remain current:

• Standard Repository Policies.
• Current adoption and update guide.

Adopted-source and example links remain commit-pinned. Preserve the valid commit-pinned example links supplied in the selected OSS policy; their asset revision need not be rewritten merely to match the policy review revision. Public discovery and attribution in this agreed adoption supersede the earlier instruction not to reference the policy repository.

Orientation And Selective Reading

Adapt the upstream agent orientation into root AGENTS.md, preserving applicable existing code-discovery instructions. It points to the local contributor guide and requires the agent policy before recommendations, planning, or implementation; it does not require reading the entire suite by default.

The contributor guide gains the upstream Policy Reading Guide table and associated selection rules, including the new meta policy. Retain Scriptorium's task-specific contract guide alongside it. Architecture reading becomes task-triggered rather than unconditional. Relevant policies are read before governed decisions, multiple policies may apply, material already available in context may be reused, and expanded scope triggers expanded reading. Policy-reading triggers live here, not in the documentation topic map.

Licensing And Attribution

Follow the canonical copied-policy attribution entry. Insert it directly beneath the prescribed attribution title and replace all three placeholder URLs with the full review commit. Identify the actual copied/adapted scope, including agent-orientation material and copied reading guidance where used, rather than describing only policy files if additional material is incorporated. Preserve creator, copyright, license, disclaimer, and modification information through the supplied notices and links.

Required supporting changes:

• Add the complete, unmodified docs/oss/licenses/CC-BY-SA-4.0.txt from the selected revision.
• Extend COPYRIGHT to identify the adapted policy material as CC-BY-SA-4.0 and point to attribution for exact scope. Preserve Scriptorium's GPL-3.0-or-later code grant and existing LICENSE. Unrelated application documentation is not automatically relicensed.
• Reformat attribution to the v1.8 House Format: # Open Source Attribution Notices, followed directly by component entries; factual optional identification; supplied copyrights; SPDX expressions; license/notice links with actual filename labels and terminal periods; and [Source](COMMIT_URL)..
• Remove its introductory policy prose, missing-copyright filler, and agent-authored license-scope explanations. Omit an unavailable copyright field instead of explaining that none was invented. Preserve actual required upstream notices, applicable license expressions, and imported dependency revisions.
• Correct README to link its GPL v3 or later statement to COPYRIGHT, followed by the attribution link.
• Update the release procedure to use the prospective COPYRIGHT | LICENSE | ATTRIBUTION footer, with absolute immutable-release URLs for all three destinations. The existing hosted workflow continues copying the checked-in release note unchanged.

The documented CC-BY-SA arrangement is agreed for this adoption. Original licensing-example formatting has upstream's CC0 permission; using it alone does not require a separate attribution entry. Reproduced license texts and third-party notices retain their own terms.

Local Materials And Upstream References

Keep applicable adopted policies, Scriptorium's adapted root orientation and developer guide, actual project notices, attribution entries, and required license texts locally.

Keep the upstream adoption guide, README, root AGENTS.md, developer guide, and example collection upstream. Link to them as appropriate rather than copying them into a parallel local handbook. The upstream agents/AGENTS.md is the downstream orientation template, distinct from upstream's own root AGENTS.md. Copy only needed standard license texts, not the entire reference collection.

Scope And Completion Criteria

This work updates policy and supporting documentation. It does not change application code, dependency versions or grants, release scripts, publication mechanics, or accepted ADR decisions. No new scanner, recurring synchronization check, license approval, publication-time network probe, or release gate is introduced. Published releases, tags, notes, and assets remain unchanged.

Completion means:

• All seven policy files use the selected versions, accurate source links, adoption dates, and upstream common wording, with template-only content removed and local variations limited to the justified decisions above.
• Orientation and selective reading agree, and local links resolve without depending on a sibling checkout.
• Policy attribution and document-license scope match the material actually incorporated; required standard texts are complete and unmodified.
• README, attribution, release navigation, and still-operative roadmap handoffs agree with the new conventions. Supersede stale instructions in the implementation record without rewriting historical completion evidence. Preserve the earlier author-selected license change in the next release's preparation context; publication remains separate work.
• Review checks the resulting rules, source/example URLs, notice facts, local links, license-text fidelity, and final diff. Runtime tests are unnecessary for documentation-only changes. A Git adoption record is sufficient; no additional provenance database or recurring audit is required.

There are no unresolved policy choices for this scope.