scriptorium/docs/roadmap/implementation.md

# Policy Alignment Implementation Plan

## Status, Scope, And Authority

Planned on 2026-09-28 against Scriptorium
`8452b54809b99425a97940da485daaa48c77aeb8`. All stages below are pending.
Execute them in integer order; each is sized as a focused implementation task
for a gpt-5.6-terra coding agent.

The [feature roadmap](policy.md) owns the agreed end state, scope, and reasons
for local exceptions. This plan owns execution steps and acceptance checks.
This is documentation work, not application, dependency, or release-tool work.

The selected public upstream revision is
`d84a38ebab26f048cafbe59a2246700c35d29843`.
Start with its
[adoption guide](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md).
Retrieve source files at this revision, not whatever main contains when a
stage runs. A verified checkout of this exact revision is acceptable; no
sibling checkout is a prerequisite. If source retrieval fails, report that
blocker rather than inventing source content or provenance.

Read the current local agent policy and developer orientation before work,
then policies governing the stage. Once Stage 2 lands, use the new selective
reading guide. Reuse unchanged policy text already available in context.

## Historical Implementation Records

This filename previously held completed application plans. Preserve their
records through Git rather than carrying their implementation steps forward:

- ConfigKit adoption and release handoff:
  `git show 8452b54809b99425a97940da485daaa48c77aeb8:docs/roadmap/implementation.md`.
- Earlier PromptKit plans are referenced within that historical document.

Those stages must not be rerun. Existing release notes, including
[the v0.14.0 note](../releases/v0.14.0.md), record prior delivered features.
Do not infer a new release obligation from an old prospective handoff.
The new policy and licensing changes still need a concise summary in the next
release, including the already-selected GPL-3.0-or-later application grant and
the separately licensed policy material. Version selection and publication
are not part of this plan.

## Common Execution Rules

1. Inspect status and relevant diffs before each stage. Preserve unrelated
   changes; do not silently include them in the stage commit.
2. Read the selected upstream files completely before adopting them. Compare
   directly with local files; do not reconstruct historical adoption baselines.
3. Start from upstream text, remove the complete Base Policy Template section,
   and apply only the customizations selected below. Preserve shared language
   verbatim, including its meaning and strength. Do not retain old paraphrases
   merely because they are familiar or add prohibitions for hypothetical risks.
4. For each policy adopted in that stage, set the target Base Policy Version,
   the actual adoption date, and an Upstream Source link:
   `https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/FILE.md`.
   Substitute the actual filename. Do not stamp a source on a policy before
   incorporating it. Intermediate commits may legitimately have mixed versions.
5. Update the single policy-attribution entry as its copied/adapted scope grows.
   Do not claim later-stage material has already been adopted.
6. Validate affected text, links, notices, and diff; record concise completion
   evidence under the completed stage here. Commit each coherent stage with a
   short plain-English message under the agent policy. Do not push or publish.

Do not change Go code, module pins, tests, release scripts, CI, accepted ADR
decisions, or published release notes. Do not introduce recurring sync checks,
license approval rounds, release gates, or blanket source headers. Preserve
the application grant and dependency terms. Standard license text must remain
verbatim even if a generic whitespace check dislikes publisher formatting.

## Stage 1: Adopt OSS Rules And Establish Licensing Notices

**Status: Complete.** OSS language was compared with the pinned source after
the approved metadata and example changes. The CC-BY-SA text matches its pinned
source byte-for-byte; attribution and navigation were checked against the
specified format and local paths.

Files: `docs/policy/oss.md`, `docs/oss/attribution.md`,
`docs/oss/licenses/CC-BY-SA-4.0.txt`, `COPYRIGHT`, `README.md`,
and the footer portion of `docs/release.md`.

1. Read upstream OSS v1.8, COPYRIGHT, the canonical
   `examples/licensing/policy-attribution.md`, and referenced licensing
   examples at their pinned URLs. Adopt OSS v1.8 with metadata as above.
   Remove template-only content; retain upstream common wording and its
   existing commit-pinned example links. Customize the README example to
   Scriptorium and GPL v3 or later. No other OSS exception is selected.
2. Copy the complete CC-BY-SA-4.0 reference text from the selected revision
   into the named local license file and compare it byte-for-byte with that
   source. Do not copy the rest of the reference collection or add CC0 merely
   because example formatting is used.
3. Reformat the attribution document to the exact v1.8 House Format. Use
   `# Open Source Attribution Notices`, immediately followed by entries.
   Place Standard Repository Policies first, using the canonical entry,
   with its COPYRIGHT, LICENSE, and Source URLs pinned to the selected full
   commit. In this stage identify `docs/policy/oss.md` as the newly adapted
   material. Do not research or make claims about prior adoption provenance.
4. Preserve the eight existing dependency entries and their imported commits,
   copyright wording, SPDX expressions, and required notices. Optional module
   identification paragraphs may retain versions currently in source labels.
   Remove the introductory prose, missing-copyright filler, and editorial
   YAML license explanations. Preserve the factual MIT AND Apache-2.0
   expressions. Use actual upstream filename labels, local license names,
   terminal periods, and the exact `[Source](COMMIT_URL).` source form.
   Do not upgrade dependencies or relabel their grants.
5. Add a scoped paragraph to COPYRIGHT stating that material adapted from
   Standard Repository Policies remains CC-BY-SA-4.0, with
   `docs/oss/attribution.md` identifying affected material and links. This
   covers the scoped material as stages add it; it does not relicense unrelated
   application code or documentation. Keep the existing GPL grant and LICENSE.
6. Correct the README ending to link GPL v3 or later to COPYRIGHT and keep
   the attribution link. Change the release-procedure footer to absolute
   immutable-tag COPYRIGHT, LICENSE, and ATTRIBUTION links, updating the
   references to the number of URLs. Change no publication commands.
   Do not retrofit published notes or create a release note/version now.

Acceptance: OSS text matches the pinned source except the approved project
example and metadata; attribution follows the prescribed format; the added
license text is faithful; project and dependency grants remain unchanged.
Check affected local paths and upstream notice/example destinations. Missing
copyright fields are omitted, not explained with agent-authored commentary.

## Stage 2: Adopt Provenance, Agent Guidance, And Documentation Ownership

**Status: Complete.** The three policies carry the selected versions, source
links, and local adoption date; shared text and the orientation template were
compared with the pinned source. The seven-link reading guide and local links
were checked, and attribution names only the incorporated material.

Files: new `docs/policy/meta.md`, `docs/policy/agents.md`,
`docs/policy/documentation.md`, root `AGENTS.md`,
`docs/development.md`, and the policy attribution entry.

1. Adopt meta v1.0 and agents v1.3 verbatim after template-section removal
   and metadata substitution. Keep meta's live project and main-branch
   adoption-guide discovery URLs; its own Upstream Source is commit-pinned.
   Retain local relative links to developer guidance and attribution.
2. Adopt documentation v1.11. Customize only applicable topic-map rows:
   configuration remains application configuration, framework formats belong
   to PromptKit, consumers cover executable use and migration rather than a
   Scriptorium public Go API, and integrations cover Scriptorium-owned
   executable/process contracts. Keep upstream rows for meta, COPYRIGHT,
   LICENSE, and attribution. Remove instructional “if applicable” qualifiers
   from selected rows. Preserve the rest of the shared language.
3. Use the upstream ADR lifecycle and examples guidance without retaining
   generic local expansions. This does not edit accepted ADRs or change their
   decisions. Metadata maintenance follows the adoption guide through meta,
   rather than a duplicate custom rule set.
4. Adapt upstream `agents/AGENTS.md` into root AGENTS.md. Preserve any actual
   repository-specific code-discovery instructions; do not copy environment-
   injected instructions into the file just because they appeared in a session.
   Do not copy upstream's own root AGENTS.md.
5. Add the adoption guide's Policy Reading Guide table and selection bullets
   verbatim to the developer guide with the seven local links. Replace its
   unconditional architecture-reading instruction and duplicated policy-reading
   prose with this selective guide. Retain project orientation, task-specific
   contract rows, dependency boundaries, and baseline validation commands.
   Avoid maintaining competing policy trigger rules in multiple places.
6. Expand the policy entry's Material sentence to identify the adopted OSS,
   meta, agents, and documentation policies plus adapted root AGENTS.md and
   the copied Policy Reading Guide section of docs/development.md. Mark them
   adapted for this repository; do not imply the whole developer guide or
   unrelated tooling instructions have changed license.

Acceptance: all stage policies have their own correct source link and version;
orientation selects policies by task, including meta for adoption work; local
links resolve; no upstream handbook or example collection was copied.
Generic language differences from upstream are eliminated, not rephrased.

## Stage 3: Adopt Architecture And Testing With Narrow Local Decisions

**Status: Complete.** The three shared architecture sections and the common
testing text match the pinned source. Local architecture decisions were checked
against the accepted ADRs and internal guides; focused test ownership and the
expanded attribution scope were reviewed without changing application code.

Files: `docs/policy/architecture.md`, `docs/policy/testing.md`,
policy attribution entry, and focused internal docs only if moving existing
implementation detail requires it.

1. Read the existing architecture, relevant accepted ADRs, source/adapter
   internal guides, and the pinned architecture v1.3 template. Retain upstream
   Purpose And Ownership, Architectural Approach, and Adopted Constraints And
   Implemented Structure text verbatim. Replace the Application-Specific
   Topics placeholder with Scriptorium's existing substantive decisions.
2. Preserve public PromptKit/ConfigKit responsibility boundaries, definition
   support, strict decoding, presence handling, HTTP artifact containment,
   request independence and concurrency-safe shared capacity, credential/error
   boundaries, dependency restrictions, and explicit workflow non-goals.
   Retain the existing lexical containment and privileged-host threat scope,
   not a stronger filesystem-sandbox promise. Customize the trust discussion
   to those decisions rather than retaining instructional example prose.
3. Correct system shape to include run, render, serve, inspect, and config.
   Link to internal documentation for concrete package inventory/mechanics.
   Where material moves, preserve it in its canonical internal owner without
   duplicating it. Do not introduce new wrappers, ports, orchestration, or
   package constraints merely to “implement” the architectural recommendation.
4. Adopt testing v1.3 common text verbatim. Add one clearly identified local
   test-ownership section for configuration, CLI, HTTP, formatting, architecture
   guards, and PromptKit/ConfigKit boundaries. Preserve the existing distinction
   between adoption/integration fixtures and upstream exhaustive tests.
   Retain a short application-specific note explaining HTTP containment and
   shared-state risks where useful; do not replace upstream risk-based coverage
   guidance or create percentage targets, quotas, or new test requirements.
5. Add accurate source/version/date metadata and extend the policy attribution
   scope to architecture and testing. Record any moved adapted prose in the
   Material scope if it is placed outside the already identified files.

Acceptance: direct comparison isolates only the roadmap's justified local
decisions; shared text matches upstream. Architecture describes existing
behavior accurately without implementation work. Testing preserves ownership
without duplicating upstream matrices or imposing new coverage gates.

## Stage 4: Adopt Release Policy Without Changing Publication Behavior

**Status: Complete.** The shared release language matches the pinned source;
the local selections match the existing script, hosted workflow, and runbook.
Commands, build targets, recovery behavior, and the three-link footer remain
unchanged. Attribution now names all seven adopted policies.

Files: `docs/policy/release.md`, `docs/release.md`, attribution entry.

1. Read the current release policy, procedure, script, and hosted workflow;
   inspect them read-only. Adopt upstream release v1.4 common wording.
2. Add a compact Scriptorium-specific section preserving the established
   selections: main/origin, branch-before-tag publication with exact remote
   candidate agreement, annotated tags derived from the checked-in note,
   stable releases only, asynchronous Linux binaries/checksums, one race-enabled
   offline test invocation, and source-boundary guards. Keep rationale for
   selected gates in policy and command/target details in the procedure.
3. Retain upstream's general alternatives verbatim but state which existing
   approach Scriptorium selects. Atomic push and source-only release remain
   template-supported alternatives, not newly supported Scriptorium workflows.
   Preserve successful tag publication as completion; no CI polling, artifact
   availability, or consumer installation gate is added.
4. Align the procedure with this allocation without changing its commands,
   required checks, supported platforms, or failure-recovery behavior. Confirm
   the Stage 1 three-link footer survives hosted-body reuse. Do not run the
   publication command or mutate remote state to validate documentation.
5. Add metadata and expand the policy attribution scope to all seven policies.
   The final Material description also identifies adapted AGENTS.md and the
   developer-guide reading section, plus any actually moved adapted text.

Acceptance: the existing release workflow still satisfies the resulting policy
with no script/CI changes. Source completion, delivery status, immutability,
tag type, and validation obligations are unchanged. All seven source links
identify their own file at the selected full commit.

## Stage 5: Verify Language Parity And Complete The Documentation Handoff

**Status: Pending.**

Files: this plan, the feature roadmap, and only affected documentation needing
correction within the preceding stages' scope.

1. Compare all seven adopted documents directly with their selected upstream
   counterparts. Account for metadata, removed template sections, approved
   substitutions, and the narrow local sections. Correct every remaining
   non-substantive wording difference. Do not turn this comparison into a
   permanent script, CI requirement, or release gate.
2. Check there are no adoption placeholders, copied template-only instructions,
   absent local example links, stale BSD descriptions of Scriptorium itself,
   or contradictory selective-reading directions. Legitimate BSD dependency
   attribution remains. Validate links using Markdown-aware handling so
   illustrative syntax in inline code is not treated as a broken real link.
3. Confirm per-document source metadata, the policy entry's exact scope,
   COPYRIGHT's scoped license treatment, existing dependency grants/notices,
   and the byte-for-byte new license text. Keep example/source links pinned
   and public discovery links current. Check footer paths in the candidate;
   unpublished release tags need not resolve online.
4. Review affected roadmap references to implementation.md. Where a link
   specifically means an old completed plan, replace it with a clear historical
   Git reference from this plan, not this new policy sequence. Preserve
   deferred application features and historical completion evidence.
   Current release directions link to the canonical procedure, not an old
   two-link footer. Do not rewrite published release notes.
5. Mark only actually delivered stages complete with concise evidence here.
   Update the feature roadmap's status to delivered and keep its end-state
   focus. Record the next-release summary described above without choosing a
   version, creating a tag, or claiming publication.
6. Run diff/whitespace and affected-document/link checks. Do not reformat
   verbatim license text to satisfy a style check. No Go test/build rerun is
   necessary for this documentation-only work; no executable example or
   publication command needs changing. Inspect status and staged diff, commit,
   and report the commit and remaining work under the agent policy.

Acceptance: policy language is standardized with only justified local
customization; notice/provenance arrangements describe reality; no runtime,
dependency, publication, or historical-release change slipped into the diff.

## Open Questions

None. The maintainer approved the public discovery URLs, the standard
CC-BY-SA arrangement for copied policy material, the selected upstream revision,
and the justified local variations. The existing application grant, dependency
grants, and release approach remain unchanged; do not reopen them merely to
perform this adoption.