eric/scriptorium
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Add an implementation plan and roadmap for Step 9 of the migration plan

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-28 14:25:56 -05:00
parent 6f64947e42
commit f71d2bbb73
4 changed files with 767 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

525
docs/roadmap/implementation.md
View File

@@ -1,64 +1,493 @@
# Step 7 Implementation Completion
# Step 9 Implementation Plan
## Status
Complete as of 2026-07-28.
Ready for implementation.
## Result
This plan implements the target state and policy decisions in
[Step 9](step9.md). Execute the stages in order. A later stage may begin only
after the preceding stage's completion checks pass and any required
cross-repository commit is published.
Scriptorium now consumes
`gitea.maximumdirect.net/eric/promptkit v0.1.0` as an ordinary direct module
dependency. The published tag resolves to Promptkit commit
`9e68a2bbf779545995270c47842048a3bc6c85dc`; no workspace, replacement,
vendored dependency, or sibling-repository state is required.
## Fixed Decisions And Baseline
The Scriptorium module root no longer exposes a Go package. The remaining
production boundary consists of:
- Promptkit `v0.1.0` at commit
`9e68a2bbf779545995270c47842048a3bc6c85dc` is the published framework
baseline. Do not create a new Promptkit tag for documentation-only work.
- Scriptorium `v0.11.1` is the final framework-bearing release.
- Scriptorium `v0.12.0` is the intended first application-only release.
- Scriptorium will not restore a Go facade, compatibility package, alias, or
forwarding API.
- Promptkit retains maintainer-run validation and tag-only source releases. Do
not add hosted Promptkit CI or binary packaging.
- Scriptorium retains hosted, tag-triggered Linux `amd64` and `arm64` binary
releases with SHA-256 checksums.
- Versioned Scriptorium release notes live at
`docs/releases/<tag>.md`. The release workflow copies the file matching
`CI_COMMIT_TAG` into its build workspace and supplies that copy to the
Woodpecker release plugin's documented
[`note` setting](https://woodpecker-ci.org/plugins/release).
- The obsolete linker assignment to the removed
`internal/buildinfo.Version` symbol is deleted. Do not introduce a version
command or replacement build-information package.
- Temporary roadmaps remain present through tag and hosted-release
verification. They are removed only after completion is recorded in Git
history.
- `cmd/scriptorium`;
- `internal/adapter/cli`;
- `internal/adapter/http`;
- `internal/config`;
- `internal/defaults`; and
- `internal/format`.
Repository paths for this work are:
The CLI constructs and invokes Promptkit engines, the HTTP adapter maps its
transport contract to Promptkit public values, and the HTTP-specific restricted
artifact reader is injected through Promptkit's public extension point.
Scriptorium retains application configuration, presentation, transport,
containment, process, packaging, and executable-example responsibilities.
- Scriptorium: `/Users/eric/Code/scriptorium/scriptorium`
- Promptkit: `/Users/eric/Code/scriptorium/promptkit`
- Notarius verification checkout: `/Users/eric/Code/notarius`
The former root facade, duplicated framework packages, built-in profile copy,
framework tests and fixtures, Go-library example, and framework-owned
documentation were removed. Permanent Scriptorium documentation now describes
the CLI and HTTP application and links to the tagged Promptkit documentation
for framework contracts.
Do not commit `go.work`, `go.work.sum`, a `replace` directive, vendored
Promptkit source, generated binaries, downloaded release assets, credentials,
or temporary validation output. Use directories created with `mktemp -d` for
clones, caches, builds, and downloads, and remove or leave those directories
outside the repositories.
## Validation Evidence
## Stage 1: Correct Promptkit Release And Project Documentation
Scriptorium passed, outside a Go workspace and without a replacement:
Work only in the Promptkit repository during this stage.
- module identity, graph, tagged dependency, and `go mod tidy -diff` checks;
- ordinary and race-enabled tests, including retained HTTP decoding, limit,
restricted-file, error-mapping, and raw-output coverage;
- vet, formatting, whitespace, architecture, and tracked-tree hygiene checks;
- temporary native and release-equivalent Linux `amd64` and `arm64` builds;
- the maintained render script and both configuration examples without model
credentials; and
- all maintained local and tagged Promptkit documentation links.
### Changes
A fresh temporary module and build cache resolved Promptkit remotely, reported
the expected `v0.1.0` origin commit, and passed the Scriptorium test suite and
build without reading the sibling Promptkit checkout.
1. Rewrite `docs/release.md` as a current, reusable procedure:
- state that `v0.1.0` is the initial published release rather than a planned
tag;
- retain semantic `vMAJOR.MINOR.PATCH` tags, pre-`v1` compatibility notes,
maintainer-run validation, and source-only publication;
- require the maintainer to provide a not-yet-published
`RELEASE_VERSION`, validate it as a semantic version, and derive the
release commit from `HEAD`;
- retain clean-checkout, no-workspace, no-replacement, module identity,
tests, race tests, vet, build, maintained example, formatting, link,
whitespace, and repository-hygiene checks;
- use the annotated tag message as Promptkit's source-only release notes,
recording the version, validated commit, compatibility summary, public
API changes, and any required consumer action;
- retain annotated-tag creation, exact-ref publication, remote tag-object
comparison, source-commit verification, and ordinary Go module
resolution checks; and
- state the Promptkit-before-consumer release ordering without restating
Scriptorium's release procedure.
2. Use guarded shell examples. A missing or already-existing release version,
a dirty checkout, an active workspace, a replacement, an unpushed release
commit, or an existing local or remote tag must stop the procedure before
tag creation. Publish only the selected tag ref, never all local tags.
3. Add a short “Related project” entry to Promptkit's `README.md` linking to
the Scriptorium repository as the CLI and HTTP application built on
Promptkit. Do not copy Scriptorium invocation or transport contracts into
Promptkit.
4. Audit Promptkit README, consumer, architecture, development, and internal
documents for stale extraction or pre-release language. Change only claims
that are no longer true; exact public API and format contracts remain with
their existing canonical owners.
Promptkit was reconfirmed independently at the exact published tag. Its local
and remote tag targets agree, its working tree remains clean, and its
documented test, race, vet, build, example, formatting, module, link,
whitespace, and repository-hygiene checks pass.
### Validation
## Next Gate
- Follow every changed local and cross-project Markdown link.
- Check all changed shell fragments for valid POSIX shell syntax without
executing tag or push commands.
- Run `git diff --check`.
- Confirm no code, module, example, architecture boundary, or public contract
changed.
[Step 8](migration.md#step-8-migrate-downstream-consumers-to-promptkit) may
now inventory and migrate downstream Go consumers. Step 7 did not migrate
external consumers, publish a breaking Scriptorium release, or complete the
release and documentation cutover assigned to Step 9.
### Completion State
Commit the Promptkit documentation changes with a plain-English message and
push the commit to `origin/main`. Require a clean Promptkit working tree with
`main` synchronized to `origin/main` before Stage 2. Do not create a Promptkit
tag.
## Stage 2: Establish Scriptorium Release Ownership And Mechanics
Work only in the Scriptorium repository during this stage.
### Documentation Ownership
1. Add two canonical-owner rows to `docs/policy/documentation.md`:
- `docs/release.md` owns the Scriptorium release procedure, including
candidate validation, version and tag operations, hosted-workflow
observation, and artifact verification;
- `docs/releases/` owns immutable version-specific release notes and
migration announcements, not complete interface contracts.
2. Update the release-packaging row in `docs/development.md` to route
contributors to `docs/release.md`, `.woodpecker/release.yml`, and the
architecture policy.
3. Create `docs/release.md` with an end-to-end procedure for:
- selecting `v0.12.0` for this release and a semantic version for later
releases;
- requiring a clean, pushed release commit on `main`, outside a Go
workspace and without a module replacement or vendor tree;
- confirming module identity, Go version, direct Promptkit version, module
graph, module tidiness, and tag availability;
- running the complete application and release-equivalent validation
defined in Stage 4;
- requiring `docs/releases/<tag>.md`;
- creating and inspecting an annotated tag bound to the validated commit;
- pushing only that exact tag ref;
- monitoring the hosted workflow;
- comparing local and remote tag objects and commits;
- downloading and verifying release assets and checksums; and
- handling failures without moving or recreating a published tag.
The procedure must distinguish an unreleased candidate from a verified
published release and must not claim that `v0.12.0` exists before its tag
and hosted artifacts are confirmed.
4. Keep operator workflows in `docs/operations.md`; add a release-procedure
link there only if a concrete operator task needs it.
### Release Workflow
Update `.woodpecker/release.yml` as follows:
1. Keep tag-only execution, Go `1.25`, `CGO_ENABLED=0`, `-trimpath`, `-s -w`,
the existing Linux architectures, filenames, release plugin, and checksum
policy.
2. Remove only the stale
`-X gitea.maximumdirect.net/eric/scriptorium/internal/buildinfo.Version=...`
linker assignment.
3. Before building, require a release-notes source at
`docs/releases/$CI_COMMIT_TAG.md`. Fail with a clear diagnostic when it is
absent.
4. Copy that source to a stable path under the workflow's `dist` directory,
such as `dist/RELEASE_NOTES.md`.
5. Set the release plugin's `note` value to the copied file. Keep release-note
content out of the binary asset glob so only the two binaries are
checksummed and uploaded alongside `SHA256SUMS`.
6. Preserve `overwrite: false` and non-prerelease publication. Do not add
automatic tag generation or release mutation.
Do not add a Go test that parses or snapshots the workflow. The material risks
are protected by release-equivalent builds, missing-note failure behavior,
hosted execution, and artifact inspection.
### Validation
- Inspect the YAML and embedded shell for the exact intended paths and
dependency between build and publish steps.
- In a temporary directory, reproduce the build step with
`CI_COMMIT_TAG=v0.12.0` and a temporary output directory. Confirm both
release-equivalent binaries build and the release-note selection fails for
a nonexistent tag.
- Use `file` or an equivalent binary inspector to confirm Linux `amd64` and
Linux `arm64` targets.
- Run `git diff --check` and validate all new local documentation links.
### Completion State
The release contract and workflow are internally consistent, reusable after
`v0.12.0`, and contain no reference to a removed package. Do not tag or publish
Scriptorium in this stage.
## Stage 3: Publish Migration Guidance And Release Notes
Work only in the Scriptorium repository during this stage.
### Go Consumer Migration Guide
Create `docs/consumers/migrating-to-promptkit.md` as the canonical guide for
leaving the former Scriptorium Go package. It must:
1. Identify Scriptorium `v0.11.1` and
`gitea.maximumdirect.net/eric/scriptorium` as the source, Promptkit `v0.1.0`
and `gitea.maximumdirect.net/eric/promptkit` as the destination, and
Scriptorium `v0.12.0` as executable-only.
2. Give copyable commands that:
- add Promptkit `v0.1.0`;
- replace Go imports and package qualifiers;
- remove the old Scriptorium dependency through `go mod tidy`; and
- run the consumer's tests.
3. Explain at a high level that the established engine, requests, results,
profiles, source options, model-client boundary, artifacts, validation
values, and error identities were preserved where practical.
4. Identify the Promptkit additions relevant to migration:
`WithArtifactReader`, `ArtifactReader`, `ErrProfileRequired`, and
`ErrAPIKeyEnvMissing`. Link exact declarations and behavior to Promptkit's
tagged consumer guide and Go source rather than reproducing them.
5. Tell consumers to verify the behavior they actually rely upon, including
configuration sources, credentials, timeout layering, validation,
injected extensions, and `errors.Is` handling.
6. State that no compatibility facade exists. Consumers unable to migrate may
remain pinned to Scriptorium `v0.11.1`, but that line does not provide the
slim application release.
### Scriptorium Navigation
1. Add the migration guide to the documentation list in `README.md`.
2. Add a concise link from `docs/consumers/api.md` for readers arriving from
the former Go API.
3. Audit all Scriptorium Markdown and Go package comments:
- current product statements must describe a CLI and HTTP application;
- framework contracts must link to tagged Promptkit `v0.1.0` owners;
- no permanent document may imply that Scriptorium still exports a Go
package;
- no document may copy Promptkit's exact fields, defaults, or API
declarations merely to explain the split.
4. Keep general cross-project navigation pointed at project entry pages and
contract links pinned to the consumed Promptkit tag.
### Versioned Release Notes
Create `docs/releases/v0.12.0.md`. Write it so the same Markdown works both as
a checked-in document and as the hosted release body. It must:
- identify the executable-only boundary as a breaking change;
- direct former Go consumers to the migration guide and Promptkit `v0.1.0`;
- identify `v0.11.1` as the last framework-bearing Scriptorium release;
- summarize the retained CLI and HTTP application interfaces without
duplicating their contracts;
- state that all known downstream Go consumers were migrated;
- name Promptkit `v0.1.0` as the released binary's framework dependency; and
- link to canonical CLI, HTTP, configuration, operations, migration, and
Promptkit consumer documents.
Use absolute tag URLs for links that must work from the hosted release page.
Scriptorium `v0.12.0` tag URLs will not exist before publication; validate
their corresponding repository-relative targets locally before tagging and
the actual URLs in Stage 5. Promptkit `v0.1.0` links must already resolve.
### Validation
- Run every copyable non-destructive migration command against a temporary Go
module or a temporary copy of the maintained historical consumer shape.
Confirm it selects Promptkit `v0.1.0`, contains no Scriptorium import, and
compiles.
- Validate every local and currently published cross-project link.
- Confirm every prospective Scriptorium `v0.12.0` URL maps to an existing path
in the candidate tree.
- Run `git diff --check`.
- Re-audit for stale project identity, framework ownership, pre-cutover, and
planned-release claims.
### Completion State
Commit the combined Scriptorium release-workflow, release-procedure, migration,
release-note, policy, and navigation changes with one or more plain-English
messages. Push them to `origin/main`. Require a clean Scriptorium working tree
with `main` synchronized to `origin/main` before Stage 4. Do not tag the release
yet.
## Stage 4: Perform The Independent Pre-Release Acceptance Run
This is a validation and release-readiness stage. Do not modify product code,
move tags, or publish a release while running it.
### Promptkit Main And Published Tag
1. Confirm Promptkit's local `main`, `origin/main`, local annotated `v0.1.0`
tag, remote tag object, and resolved tag commit.
2. On Promptkit `main`, run:
- `go test ./...`;
- `go test -race ./...`;
- `go vet ./...`;
- `go build ./...`;
- `go run ./examples/go-library/prepare`;
- `gofmt -l` over tracked Go files;
- local and cross-project Markdown-link checks;
- `git diff --check`;
- module identity, no-workspace, no-replacement, no-vendor, and tracked-tree
hygiene checks.
3. Clone the remote Promptkit `v0.1.0` tag into a temporary directory with
fresh task-specific `GOMODCACHE` and `GOCACHE` directories and `GOWORK=off`.
Run the complete documented Promptkit validation there.
4. From a separate temporary consumer module, resolve
`gitea.maximumdirect.net/eric/promptkit@v0.1.0` through the ordinary remote
module path and confirm its origin metadata and expected source commit
without reading the sibling Promptkit checkout.
### Scriptorium Release Candidate
Clone the pushed Scriptorium release commit from `origin/main` into a temporary
directory. Use fresh task-specific module and build caches and `GOWORK=off`.
Perform all checks from that clone:
1. Confirm:
- module path and Go version;
- direct Promptkit requirement exactly `v0.1.0`;
- module graph selection of Promptkit `v0.1.0`;
- no `replace`, `go.work`, `go.work.sum`, vendor tree, root Go package,
former framework packages, Promptkit internal import, or sibling path;
- `go mod tidy -diff` produces no changes; and
- local and remote `v0.12.0` tags do not exist.
2. Run:
- `go test ./...`;
- `go test -race ./...`;
- `go vet ./...`;
- `gofmt -l` over tracked Go files;
- `git diff --check`;
- architecture and tracked-tree hygiene checks;
- the maintained render script;
- render smoke checks with both configuration examples; and
- every maintained local, Promptkit-tagged, and other existing external
documentation link.
3. Build a temporary native executable and exercise basic help and offline
render behavior.
4. Reproduce the release workflow with `CI_COMMIT_TAG=v0.12.0` into temporary
output:
- select and copy `docs/releases/v0.12.0.md`;
- build stripped, trimmed Linux `amd64` and `arm64` binaries;
- verify exact filenames, nonempty files, target operating systems and
architectures, and absence of the obsolete linker assignment;
- compute SHA-256 checksums in the same basename-only form expected from the
plugin; and
- confirm no extra file matches the upload glob.
5. Confirm repository-relative targets for the not-yet-live Scriptorium
`v0.12.0` release-note links.
### Downstream Confirmation
In the Notarius checkout:
- require a clean `main` synchronized with `origin/main`;
- confirm `go.mod` directly requires Promptkit and no tracked file imports the
former Scriptorium Go package; and
- run `go test ./...`.
If another downstream consumer is discovered, stop and disposition it under
the Step 8 gate before publication.
### Release Checkpoint
Record the exact Scriptorium release commit, Promptkit tag object and commit,
validation commands, and results. Confirm both source repositories remain
clean after validation.
Any failure returns work to the owning earlier stage. Repeat the complete
Stage 4 acceptance run after the fix is committed and pushed. Proceed only
when the validated Scriptorium commit is the exact clean `origin/main` commit
intended for `v0.12.0`.
## Stage 5: Publish And Verify Scriptorium `v0.12.0`
This stage performs external, tag-triggered publication. Do not start it
without confirmed repository access, the hosted release secret and workflow,
and the complete Stage 4 evidence.
### Tag Publication
1. Fetch `origin/main` and all tags without changing files.
2. Reconfirm that `v0.12.0` is absent locally and remotely and that the working
tree is clean at the validated release commit.
3. Create an annotated `v0.12.0` tag. Its message must identify Scriptorium
`v0.12.0`, the exact release commit, and that the documented release
validation passed.
4. Inspect the tag object and resolved commit.
5. Push only `refs/tags/v0.12.0`.
6. Compare the local and remote annotated tag object IDs and resolved commit
IDs.
Never move, delete, or recreate a published release tag. A transient hosted
workflow failure may be retried against the same tag. A source or workflow
defect discovered after tag publication requires a fix on `main` and an
explicit roadmap/version decision before a later patch release; do not silently
retag `v0.12.0` or mark Step 9 complete.
### Hosted Release Verification
1. Monitor the Woodpecker tag pipeline until it reaches a terminal state.
2. Require both the build and publish steps to succeed.
3. Inspect the Gitea release and require:
- a non-prerelease `v0.12.0` release;
- release body content sourced from `docs/releases/v0.12.0.md`;
- exactly the intended Linux `amd64` binary, Linux `arm64` binary, and
`SHA256SUMS` release assets; and
- no source-copy, Promptkit binary, release-note file, or stale artifact
uploaded by the workflow.
4. Download all three assets into a temporary directory.
5. Verify `SHA256SUMS` against both binaries, confirm file types and target
architectures, and inspect that neither file is empty or malformed.
6. Run basic `--help` and offline render smoke behavior on a downloaded binary
when the host or an available isolated Linux runtime supports its
architecture. When execution is unavailable, record that limitation and
rely on the matching pre-release binary smoke plus downloaded-artifact
format and checksum verification.
7. Verify every Scriptorium `v0.12.0` and Promptkit `v0.1.0` URL in the hosted
release notes.
8. Resolve Scriptorium `v0.12.0` and Promptkit `v0.1.0` through fresh remote Go
module queries and confirm their expected tag commits and dependency edge.
### Completion State
Retain the publication evidence needed for the final completion record. Remove
temporary downloads and confirm no release outputs entered either repository.
Do not retire the roadmaps until every hosted verification passes.
## Stage 6: Record Completion And Retire Migration Roadmaps
Work in Scriptorium only after Stage 5 is fully complete.
### Completion Record
1. Update `docs/roadmap/migration.md` to mark Step 9 and the overall Promptkit
migration complete.
2. Update `docs/roadmap/step9.md` and this implementation plan with a concise
completion summary containing:
- Promptkit tag and commit;
- Scriptorium tag and commit;
- hosted release and asset results;
- downstream status;
- independent validation results; and
- any explicitly accepted platform limitation in downloaded-binary
execution.
3. Commit and push that completion record with a plain-English message. This
commit provides the historical completion snapshot before temporary files
are removed.
### Roadmap Retirement
In a subsequent commit:
1. Move any still-useful current contract or procedure into its already
designated permanent owner.
2. Remove all completed Promptkit-migration roadmaps:
- `docs/roadmap/migration.md`;
- `docs/roadmap/step7.md`;
- `docs/roadmap/step9.md`; and
- `docs/roadmap/implementation.md`.
3. Remove the empty `docs/roadmap/` directory if no unrelated active roadmap
remains.
4. Search the full repository for incoming links or prose references to the
removed files and repair them by linking to ADRs, the release procedure,
versioned release notes, migration guide, or another canonical owner.
5. Do not change accepted ADR decision content. Git history, tags, hosted
release notes, permanent migration guidance, and the completion-record
commit retain the durable history.
### Final Validation
Run:
- all local Markdown-link checks;
- all maintained cross-project links;
- `git diff --check`;
- a stale-reference search for removed roadmap paths and pre-cutover claims;
- tracked-tree hygiene checks in both repositories; and
- `git status --short --branch` in Scriptorium, Promptkit, and Notarius.
The cleanup is documentation-only and does not require repeating unrelated Go
tests unless the cleanup changes a command, example, or behavior-bearing file.
Commit and push the retirement with a plain-English message.
## Final Completion State
The implementation is complete when:
- Promptkit main contains accurate reusable release guidance and still
publishes `v0.1.0` as an independently validated source-only Go module;
- Scriptorium main contains a canonical release procedure, permanent migration
guide, versioned `v0.12.0` release notes, and a release workflow matching the
current application;
- Scriptorium `v0.12.0` is published from the independently validated commit
with verified Linux `amd64` and `arm64` binaries and SHA-256 checksums;
- the hosted release body matches the checked-in versioned notes;
- Notarius remains migrated and no other downstream Go consumer remains;
- neither repository or release depends on local multi-repository state;
- both repositories are clean and synchronized with their remotes; and
- the completed temporary migration roadmaps have been removed after their
completion record was committed.
## Open Questions
None. The Step 9 feature roadmap, accepted ADRs, current release topology, and
repository policies determine the required implementation and release choices.

10
docs/roadmap/migration.md
View File

@@ -2,8 +2,8 @@
## Status
Accepted plan. Steps 1 through 7 are complete. Steps 8 and 9 remain proposed
and are not yet implemented.
Accepted plan. Steps 1 through 8 are complete. Step 9 remains proposed and is
not yet implemented.
## Objective
@@ -290,6 +290,12 @@ explicitly recorded as remaining on the previous Scriptorium version with an
owner and follow-up plan. Do not declare the ecosystem migration complete until
the required out-of-band consumer changes are confirmed.
**Gate status:** Complete as of 2026-07-28. The maintainer confirmed that
Notarius was the only downstream consumer of Scriptorium's former Go package.
Its clean, synchronized main branch now directly requires Promptkit `v0.1.0`,
all relevant Go imports use Promptkit rather than Scriptorium, and its full Go
test suite passes. No downstream consumer remains to migrate or disposition.
### Step 9: Complete Release And Documentation Cutover
Complete the coordinated project transition:

64
docs/roadmap/step7.md
View File

@@ -1,64 +0,0 @@
# Migration Step 7: Slim Scriptorium And Adopt Promptkit
## Status
Complete as of 2026-07-28.
## Result
Scriptorium is now an application-only consumer of the published
`gitea.maximumdirect.net/eric/promptkit v0.1.0` module. The command, CLI and
HTTP adapters, restricted artifact reader, and prepared-run formatter use
Promptkit's supported public API. The dependency resolves normally to
Promptkit commit `9e68a2bbf779545995270c47842048a3bc6c85dc` without a workspace,
replacement, vendored copy, or unpublished revision.
The Scriptorium module root no longer provides an importable Go package or
compatibility facade. The reusable framework packages, embedded built-in
profiles, framework contract tests and fixtures, and Go-library example were
removed. Architecture tests prevent production imports of the former root
facade, removed framework package families, and Promptkit internals.
## Retained Application Boundary
Scriptorium owns only its runnable process and application concerns:
- command and CLI parsing, assembly, streams, summaries, and exit behavior;
- HTTP routes, DTOs, strict decoding, limits, public error mapping, and
restricted artifact access;
- application configuration discovery, validation, precedence, and transport
defaults;
- prepared-run text and JSON presentation;
- executable examples, operations guidance, and binary packaging.
Promptkit owns prompt execution, framework sources and formats, validation,
model integration, built-in profiles, and ordinary artifact loading.
Scriptorium's permanent documentation reflects that boundary and links to the
tagged Promptkit contracts rather than duplicating them.
## Acceptance
The completed cutover passed:
- module graph and tidiness checks selecting exactly Promptkit `v0.1.0`;
- ordinary and race-enabled Scriptorium tests, vet, formatting, whitespace,
architecture, and repository-hygiene checks;
- temporary native and release-equivalent cross-builds;
- maintained offline render workflows with both application configurations;
- maintained local and tagged-documentation link checks;
- fresh-cache remote dependency resolution, tests, and build with the expected
Promptkit origin commit; and
- Promptkit's complete documented validation independently at its clean local
and remote `v0.1.0` tag.
These checks cover the retained CLI, HTTP, configuration, containment,
formatting, error-mapping, security, and representative executable behavior.
The working trees contain no generated binaries, temporary workspaces,
replacement directives, credentials, or migration residue.
## Handoff
The Step 7 gate is satisfied. [Step 8](migration.md#step-8-migrate-downstream-consumers-to-promptkit)
owns downstream consumer inventory and migration. Step 9 remains responsible
for the breaking Scriptorium release and final documentation cutover; neither
later gate is complete.

282
docs/roadmap/step9.md Normal file
View File

@@ -0,0 +1,282 @@
# 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.