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](../../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.

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:

```markdown
# 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](../development.md) 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](../policy/documentation.md), 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](../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 [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.

## 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](../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.

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](../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.

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.