scriptorium/docs/roadmap/step9.md

# Migration Step 9: Complete Release And Documentation Cutover

## Status

Proposed. Steps 1 through 8 of the
[migration roadmap](migration.md) are complete. This is the final migration
gate.

## 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](../adr/0002-split-promptkit-from-scriptorium.md), 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](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md):
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.