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 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. 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, 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: Pending.

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: Pending.

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: Pending.

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: Pending.

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.