scriptorium/docs/roadmap/step9.md

Migration Step 9: Complete Release And Documentation Cutover

Status

Complete as of 2026-07-28. All steps of the migration roadmap are complete.

Completion Record

• Promptkit's annotated v0.1.0 tag remains published at commit 9e68a2bbf779545995270c47842048a3bc6c85dc; its independent documented validation and fresh remote module resolution passed.
• Scriptorium's annotated v0.12.0 tag object 734632371773bb7620ce9f18e79ae179a2a2b44b resolves to independently validated commit 2f42bdde3957563cb9b7a1e27fdd4ab2516f621a.
• The hosted release completed successfully with the checked-in release notes, exactly the Linux amd64 and arm64 binaries, and SHA256SUMS. Both checksums and binary architectures were verified.
• Fresh remote module queries resolved both release tags to their expected commits and confirmed that Scriptorium selects Promptkit v0.1.0, without a workspace, replacement, vendored sibling source, or local module cache.
• The downloaded Linux amd64 binary completed an offline render smoke test. Its existing command interface has no --help command, so that invocation returned the expected unknown-command usage response. The Linux arm64 binary was not executed on the amd64 validation host; its checksum, format, and target architecture were verified.
• Notarius at commit de046a8f13e227676d79c3aa3b685b049902038d remains migrated to Promptkit and passed its full test suite. No other downstream consumer of the former Scriptorium Go package was identified.
• Promptkit, Scriptorium, and Notarius were clean and synchronized with their remote main branches after validation.

Purpose

Finish the Promptkit split as a released, documented, and independently maintainable project boundary. Step 9 turns the already-implemented repository state into the supported public release state, gives former Scriptorium Go consumers a durable migration path, reconciles release guidance in both repositories, and retires the temporary migration records once their work is complete.

This roadmap defines the intended end state.

Release Baseline And Version Decisions

The coordinated release boundary is:

• Promptkit v0.1.0, already published from commit 9e68a2bbf779545995270c47842048a3bc6c85dc, is the framework version consumed by Scriptorium;
• Scriptorium v0.11.1 is the final published framework-bearing Scriptorium release; and
• Scriptorium v0.12.0 is the first slim application-only release.

The v0.12.0 version satisfies ADR 0002, which requires the first slim pre-v1 Scriptorium release to advance the minor version beyond the final framework-bearing release.

Promptkit does not need another tag merely to complete this migration. Promptkit documentation corrections that do not change the library contract may land on its main branch without changing Scriptorium's dependency. If Step 9 discovers that a Promptkit code or consumer-visible contract change is required, Promptkit must instead publish an appropriate later semantic version first, and Scriptorium must adopt and validate that tag before v0.12.0 is published.

No release may depend on a Go workspace, local module replacement, vendored sibling source, unpublished commit, or an unpushed tag.

Scriptorium Release Readiness

Scriptorium must have a durable, canonical release procedure appropriate to its hosted tag-triggered binary workflow. The procedure and contributor reading guide must collectively define:

• semantic-version selection and the clean-checkout preconditions;
• validation outside a Go workspace and without a module replacement;
• module identity, dependency resolution, module tidiness, tests, race tests, vet, formatting, link, example, and repository-hygiene checks;
• release-equivalent Linux amd64 and arm64 builds;
• annotated tag creation and publication;
• observation of the hosted release workflow;
• verification of published binaries and checksums; and
• post-publication smoke checks using downloaded release artifacts where the execution platform permits.

The documentation policy must assign the release procedure one canonical owner, and docs/development.md must route release work to it. Operations documentation should link to release material only when an operator task requires it; it must not become a second release procedure.

The tag workflow must accurately describe the current application. In particular, remove the obsolete linker assignment to the deleted internal/buildinfo.Version symbol. The release continues to use stripped, trimmed binaries unless a separate supported application-version interface is introduced. Adding a new --version command or other product behavior is not part of this migration.

Release validation must exercise the same build commands and artifact names as the hosted workflow. The resulting v0.12.0 release must contain the supported Linux amd64 and arm64 Scriptorium binaries and published SHA-256 checksums, with no framework source or Promptkit binary artifact.

Promptkit Release Readiness

Promptkit remains governed by ADR 0003: maintainer-run validation, semantic Go module tags, and no hosted CI or binary release artifacts.

Its release procedure must be corrected from pre-release language to current, reusable guidance. It must no longer describe v0.1.0 as an uncreated planned release or instruct a maintainer to create an existing tag. It should:

• acknowledge v0.1.0 as the initial published release;
• use version-agnostic instructions for later releases;
• retain the clean-checkout, full-validation, tag-ordering, and remote-tag verification requirements; and
• require pre-v1 release notes to identify public API changes and consumer migration requirements.

Before Scriptorium v0.12.0 is tagged, independently reconfirm that the local and remote Promptkit v0.1.0 tags resolve to the expected source commit, that the tagged module is available through ordinary Go module resolution, and that Promptkit passes its documented release validation without Scriptorium or sibling-repository state.

Go Consumer Migration Guidance

Scriptorium must publish a permanent migration guide under docs/consumers/ for consumers of the former Go package. Scriptorium owns this guide because it describes departure from Scriptorium's removed API; Promptkit's declarations, GoDoc, format reference, and consumer guide remain canonical for the destination contract.

The guide must identify the supported migration baseline:

• source: Scriptorium v0.11.1 and import path gitea.maximumdirect.net/eric/scriptorium;
• destination: Promptkit v0.1.0 and import path gitea.maximumdirect.net/eric/promptkit; and
• Scriptorium v0.12.0 and later: executable application only, with no root Go package or compatibility facade.

It must provide a minimal, copyable migration workflow:

1. replace the Scriptorium module requirement and Go imports with Promptkit v0.1.0;
2. update package qualifiers from scriptorium to promptkit;
3. run go mod tidy;
4. compile and test the consuming project; and
5. verify prompt, profile, schema, credential, timeout, validation, injected client, and error-handling behavior relevant to that consumer.

The guide should explain that the established engine, request, result, profile, source-option, model-client, artifact, validation, and error shapes were intentionally preserved where practical, while Promptkit also owns the post-extraction public error identities and artifact-reader extension point. It must direct exact API questions to Promptkit's tagged GoDoc and consumer guide rather than duplicating the declaration reference.

The guide must also state the deliberate compatibility policy: there are no Scriptorium aliases, forwarding packages, or deprecated wrappers. A consumer that cannot migrate may remain pinned to v0.11.1, but it will not receive the application-only Scriptorium line through that package API.

Documentation And Project Identity Cutover

Review both repositories as separate products and reconcile every maintained link, example, package comment, and current-state statement with the released boundary.

Scriptorium documentation must:

• present Scriptorium as a CLI and HTTP application, not a Go framework;
• link in-process Go consumers and framework contract questions to tagged Promptkit v0.1.0 documentation;
• link former Scriptorium Go consumers to the migration guide;
• keep CLI, HTTP, application configuration, operations, subprocess, and executable examples under Scriptorium ownership; and
• avoid reproducing Promptkit fields, defaults, public declarations, or integration contracts.

Promptkit documentation must:

• present Promptkit as the reusable Go framework and owner of its root API, file formats, built-in profiles, validation, and outbound integration;
• retain Scriptorium only as a downstream application example or related project, not as a framework owner or dependency;
• link to Scriptorium only for executable CLI and HTTP workflows when that navigation is useful; and
• contain no stale extraction, planned-first-release, or pre-cutover claims.

Cross-project links must point to the canonical owner. Scriptorium links that define the framework version it consumes remain pinned to Promptkit v0.1.0; general project-navigation links may point to the other repository's current project entry point. Maintained examples must stay repository-local and must not require a sibling checkout.

Release Notes And Public Communication

The Scriptorium v0.12.0 release notes must clearly identify the release as a breaking project-boundary change. They must:

• state that Scriptorium is now an executable-only CLI and HTTP application;
• state that the former Go framework moved to Promptkit;
• link the Scriptorium migration guide and Promptkit v0.1.0 consumer documentation;
• identify v0.11.1 as the final framework-bearing Scriptorium release;
• summarize the retained Scriptorium interfaces and the removed root package;
• record that all known downstream Go consumers were migrated before release; and
• identify the Promptkit version used by the released binary.

Release notes must not serve as a duplicate CLI, HTTP, configuration, or Promptkit API reference. They should route readers to the corresponding canonical documents.

Independent Release And Artifact Verification

The final acceptance run must treat the repositories as independent remote projects:

• validate Promptkit from its exact published tag without Scriptorium;
• validate Scriptorium from its intended release commit outside any workspace and with a fresh module and build cache that cannot read the sibling Promptkit checkout;
• confirm the Scriptorium module graph selects the intended published Promptkit tag;
• verify both working trees contain no tracked workspace, replacement, vendored cross-project source, generated binary, credential, or temporary release residue;
• publish and verify the annotated Scriptorium v0.12.0 tag;
• verify the hosted release completes and publishes the expected binaries and checksums;
• download the published artifacts into a temporary location, verify their checksums, file types, target architectures, and basic executable behavior; and
• recheck maintained local and cross-project documentation links after publication.

Ordinary ignored developer files, including an ignored local Scriptorium binary, do not fail repository hygiene. Acceptance concerns tracked content, release inputs, generated files introduced by the release work, and published artifacts.

Roadmap Retirement

Roadmaps are temporary coordination documents. After every Step 9 completion criterion is satisfied and durable release and migration records exist:

• mark Step 9 and the overall migration complete before cleanup;
• preserve any still-useful current contract in its canonical permanent owner;
• rely on ADRs, Git history, tags, release notes, and the migration guide for durable decision and release history;
• remove completed migration, step, and implementation roadmaps rather than retaining them as a second current-state reference; and
• repair every incoming link affected by that removal.

The roadmap files must remain until the out-of-band tag and hosted release have been verified. Creating a release candidate or merging documentation is not enough to declare the migration complete.

Non-Goals

Step 9 does not:

• redesign Promptkit's public API or Scriptorium's CLI or HTTP contracts;
• restore a Scriptorium Go facade or add compatibility shims;
• add hosted CI or binary artifacts to Promptkit;
• add new Scriptorium target platforms beyond the existing Linux amd64 and arm64 release policy;
• introduce an application version command solely to preserve a stale linker flag;
• redo the completed downstream migration inventory; or
• require a new Promptkit release when no Promptkit contract change is needed.

Completion Criteria

Step 9 is complete only when all of the following are true:

• Promptkit v0.1.0 remains independently available, validated, and correctly documented as the published framework dependency;
• Scriptorium has an accurate, canonical, and tested release procedure;
• the Scriptorium release workflow contains no reference to removed framework or build-information packages and produces only the intended application artifacts;
• the permanent Go-consumer migration guide is complete, copyable, and linked from appropriate Scriptorium entry points;
• both repositories' permanent documentation, examples, package comments, and cross-project links reflect distinct and canonical ownership;
• Scriptorium v0.12.0 is published from a clean, independently validated commit that directly requires a published Promptkit tag;
• the hosted Scriptorium release publishes verified Linux amd64 and arm64 binaries and SHA-256 checksums;
• the v0.12.0 release notes communicate the breaking package move and link to the migration path;
• all known downstream Go consumers remain migrated or explicitly dispositioned;
• neither release depends on local multi-repository state; and
• completed migration roadmaps are removed after their useful content and completion evidence have durable owners.

When these criteria are satisfied, the Promptkit split is complete and both projects can evolve, validate, version, document, and release independently.