scriptorium/docs/roadmap/policy.md

Policy Template Adoption

Status And Intent

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.

Implementation Record

• 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 and local-repository regression tests, and replaced the old release procedure with the short runbook.
• 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 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 Scriptorium's application boundaries, gives agents clear working rules, and makes release preparation proportionate and repeatable.

Policy Set And Provenance Headers

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.

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

Use this header shape, substituting the applicable title and base version:

# Architecture Policy

**Base Policy Version:** 1.1

**Last Updated:** 2026-09-26

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.

Agent Guidance And Discoverability

Add docs/policy/agents.md as the canonical owner of coding-agent behavior. Update AGENTS.md and the development guide so agents read it before recommending, planning, or implementing work, then follow the task-specific reading guide. Preserve other applicable repository instructions.

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.

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.

Documentation Ownership

Merge the updated documentation template into the existing documentation policy, preserving its useful Scriptorium-specific decisions:

• 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.

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 owns concrete repository commands and recovery procedures. Version-specific notes remain immutable release history.

Architecture policy owns deliberate constraints and normative boundaries; the internal overview 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.

Architecture Refinements

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.

Explicitly connect the policy to ADR 0004: 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.

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.

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.

Risk-Based Testing

Merge the updated testing template into the testing policy. 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.

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.

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.

Release Policy And Publication Workflow

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.

Versioning And Release Identity

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.

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.

A Single Validated Candidate

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.

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.

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.