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

Retire the completed migration roadmaps

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-28 20:04:24 +00:00
parent 1f08a1a94c
commit 27d7ad5057
3 changed files with 0 additions and 1171 deletions
Download Patch File Download Diff File Expand all files Collapse all files

514
docs/roadmap/implementation.md
View File

@@ -1,514 +0,0 @@
# Step 9 Implementation Plan
## Status
Complete as of 2026-07-28.
## Completion Summary
Promptkit's annotated `v0.1.0` tag remains published at commit
`9e68a2bbf779545995270c47842048a3bc6c85dc`. Scriptorium's annotated
`v0.12.0` tag object `734632371773bb7620ce9f18e79ae179a2a2b44b`
resolves to independently validated commit
`2f42bdde3957563cb9b7a1e27fdd4ab2516f621a`. The
[hosted release](https://gitea.maximumdirect.net/eric/scriptorium/releases/tag/v0.12.0)
succeeded with release notes matching the checked-in source, exactly the Linux
`amd64` and `arm64` binaries, and verified SHA-256 checksums.
Fresh remote module resolution and independent repository validation passed
without sibling-repository state. The downloaded `amd64` binary completed an
offline render; its existing command interface treated `--help` as an unknown
command and printed usage. The `arm64` binary could not be executed on the
`amd64` host, so its checksum, format, and target architecture were verified.
Notarius at commit `de046a8f13e227676d79c3aa3b685b049902038d`
remains migrated and verified, and no other downstream Go consumer was
identified. All three repositories were clean and synchronized after
validation.
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.
## Fixed Decisions And Baseline
- 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.
Repository paths for this work are:
- Scriptorium: `/Users/eric/Code/scriptorium/scriptorium`
- Promptkit: `/Users/eric/Code/scriptorium/promptkit`
- Notarius verification checkout: `/Users/eric/Code/notarius`
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.
## Stage 1: Correct Promptkit Release And Project Documentation
Work only in the Promptkit repository during this stage.
### Changes
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.
### Validation
- 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.
### 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.

349
docs/roadmap/migration.md
View File

@@ -1,349 +0,0 @@
# Promptkit Migration Roadmap
## Status
Complete as of 2026-07-28. All nine steps and the overall Promptkit migration
are complete. The final release and validation evidence is recorded in
[Step 9](step9.md).
## Objective
Split the current repository into two projects:
- **Promptkit**: the reusable Go framework, public Go facade, execution engine,
source and validation support, OpenAI-compatible client, extension
interfaces, and built-in execution-profile registry.
- **Scriptorium**: a slim runnable application that imports Promptkit and
provides the CLI and HTTP interfaces.
Scriptorium will become another downstream Promptkit consumer rather than the
owner of the framework.
## Compatibility And Migration Policy
This is an intentionally breaking change.
- New and migrated Go consumers must import Promptkit instead of Scriptorium.
- Scriptorium will not retain type aliases, forwarding packages, deprecated
facade APIs, or other source-compatibility shims.
- Existing consumers may continue using a previously tagged Scriptorium module
version until they are migrated.
- The migration does not need to preserve compatibility between intermediate
development states. Each completed phase must instead leave the affected
repository internally consistent and tested.
- Promptkit should initially preserve the useful shape and behavior of the
current public Go facade where doing so reduces extraction risk. Broader API
redesign should follow the split unless required to establish the new
boundary.
## Target Ownership
Promptkit should own application-neutral framework behavior:
- public engine, request, result, option, extension, and error APIs;
- prompt-definition loading and rendering;
- execution profiles, overlays, and the built-in profile registry;
- artifact-loading interfaces and general-purpose `file` and `inline` support;
- schema loading and output validation;
- LLM client boundaries and the OpenAI-compatible implementation;
- preparation and execution orchestration;
- framework and execution defaults.
Scriptorium should own executable and transport concerns:
- the `scriptorium` command and its `run`, `render`, and `serve` interfaces;
- CLI parsing, output formatting, exit codes, and process behavior;
- application-config discovery and CLI precedence;
- HTTP routing, request and response DTOs, limits, and error/status mapping;
- HTTP artifact-root and deployment security policy;
- server and adapter defaults;
- executable examples, operations guidance, and transport documentation.
The intended dependency direction is:
```text
Scriptorium CLI and HTTP adapters
|
v
Promptkit
|
v
consumer-supplied sources and clients
```
Scriptorium must use Promptkit's public API. It must not depend on Promptkit
implementation packages or reproduce framework orchestration.
## Migration Steps
### Step 1: Refresh And Synchronize Documentation
Perform a repository-wide documentation refresh before migration development.
At minimum:
- reconcile all current-behavior documentation with the code, tests, examples,
defaults, and current public contracts;
- introduce the planned documentation-policy updates;
- establish an architecture decision record policy and canonical ADR location;
- resolve stale, duplicated, or misplaced material;
- validate documentation links and maintained examples;
- leave future migration behavior in `docs/roadmap/` until implemented.
**Gate:** Do not begin architectural migration work until the documentation
refresh and policy updates are merged and the repository has an agreed,
accurate baseline.
**Gate status:** Complete as of 2026-07-26. The completed documentation
refresh, follow-up verification, and layered-timeout correction remain recorded
in repository history. Step 1 remains complete after that validation.
### Step 2: Record The Architectural Decision And Detailed Boundary
Create an ADR, under the policy established in Step 1, that records:
- the decision to split Promptkit from Scriptorium;
- the target ownership and dependency direction;
- the selected Promptkit repository and Go module paths;
- the breaking-change and versioning policy;
- ownership of configuration fields and defaults;
- artifact-reader and HTTP containment responsibilities;
- local multi-repository development and release coordination;
- documentation ownership after the split.
Use the ADR to resolve any remaining public-boundary decisions before code is
moved.
**Gate:** The ADR is accepted, and every existing package, public contract,
configuration category, and maintained asset has a target owner.
**Gate status:** Complete as of 2026-07-26.
[ADR 0002: Split Promptkit From Scriptorium](../adr/0002-split-promptkit-from-scriptorium.md)
is accepted and records the required ownership and coordination decisions.
### Step 3: Characterize Existing Framework Behavior
Strengthen or add contract-focused tests where needed so extraction can be
verified without relying on package placement.
The completed Step 3 gate records the accepted implementation scope and
intended completion state.
Preserve coverage of:
- `Prepare` and `Run` behavior;
- prompt, profile, execution-default, and request-override precedence;
- presence-aware numeric overrides;
- built-in profile fallback and custom-profile overlays;
- strict YAML and JSON decoding;
- prompt, profile, schema, and artifact source behavior;
- structured-output requests and output validation;
- validation failures versus validation runtime errors;
- secret handling and redaction;
- public error classification;
- HTTP artifact restrictions and transport mappings.
**Gate:** Current framework and adapter contracts are represented by passing
tests sufficient to detect behavioral regressions during the split.
**Gate status:** Complete as of 2026-07-27. The framework contract corpus,
public `Engine` characterization, ownership audit, full test and vet suites,
temporary executable build, and maintained offline examples passed.
### Step 4: Make Scriptorium Adapters Consume The Public Facade
Within the current repository, refactor the CLI and HTTP adapters to use the
public framework facade rather than constructing or importing internal runner
components directly.
Add only the minimum public capabilities needed to support this boundary. These
may include:
- a small `Run`/`Prepare` consumer interface;
- injectable artifact-reading behavior for Scriptorium's restricted HTTP
policy;
- source options currently available only through internal constructors;
- prepared-run formatting based on public types;
- stable public error classification required by CLI and HTTP mappings.
Do not broadly export internal repositories, domain types, or use-case
implementations.
**Gate:** The CLI and HTTP adapters use only the public framework API for
framework behavior, and all tests and documented smoke commands pass.
**Gate status:** Complete as of 2026-07-28. CLI `run`, `render`, and `serve`,
the HTTP handler, and prepared-run formatting use the public facade; the
restricted HTTP reader is injected through the public extension point. The
post-implementation public-error, deterministic MIME, and recursive
dependency-guard corrections passed full tests, vet, build, race checks,
maintained examples, and configuration smoke checks.
### Step 5: Create The Promptkit Repository
Promptkit was established as an independent repository and Go module through
the completed out-of-band workflow recorded in repository history. Its
foundation includes:
- confirmed repository access, governance, origin, and default-branch tracking;
- module `gitea.maximumdirect.net/eric/promptkit` at Go `1.25.5`;
- a minimal root `promptkit` public package boundary with no placeholder
framework packages;
- library-specific development, architecture, documentation, testing, and
release policies;
- documented maintainer-run test, vet, build, formatting, documentation-link,
and repository-hygiene validation;
- source-commit and semantic Go module tag releases without runnable binaries
or binary packaging; and
- temporary workspace and uncommitted replacement workflows for coordinated
development without committed repository coupling.
[ADR 0003](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md)
records the controlling Promptkit validation and release decision.
**Gate status:** Complete as of 2026-07-28. Promptkit passed its documented
validation independently, all maintained links and repository-hygiene checks
passed, and no workspace, replacement, CI configuration, binary, tag, command,
or placeholder package was added. The completed repository foundation
supported the Step 6 extraction.
### Step 6: Extract And Stabilize Promptkit
Move the application-neutral framework and built-in profile assets into
Promptkit. Preserve implementation packages as internal where practical.
The initial public API should remain focused on the established engine workflow
and the source and client extension points required by real consumers. Avoid
combining the extraction with unrelated API redesign.
Move or recreate the relevant:
- framework implementation;
- public package tests and framework contract tests;
- built-in profile assets and registry tests;
- Go consumer examples;
- framework, consumer, configuration-format, and integration documentation.
Verify that Promptkit can be built, tested, and consumed independently of the
Scriptorium repository.
**Gate:** Promptkit independently provides the agreed framework contract,
passes its documented validation, and has published its first versioned tag
before Scriptorium or another consumer adopts it, as required by
[ADR 0003](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md).
**Gate status:** Complete as of 2026-07-28. Repository history records source
Scriptorium commit `c7263ab2a8e58f7fb97280082d327a820c7cece7`,
accepted Promptkit commit
`9e68a2bbf779545995270c47842048a3bc6c85dc`, independently passing acceptance,
published annotated tag `v0.1.0`, and successful remote-consumer validation.
Scriptorium remains unchanged at its pre-cutover boundary. Step 7 adoption of
the tagged module and removal of the duplicated framework is the next gate.
### Step 7: Slim Scriptorium And Adopt Promptkit
Update Scriptorium to import the tagged Promptkit module and remove the
framework implementation and public Go facade that Promptkit replaces.
Retain only Scriptorium-owned executable and transport behavior. In particular:
- wire CLI and HTTP requests through Promptkit's public API;
- keep application config and transport defaults in Scriptorium;
- keep restricted HTTP artifact policy in Scriptorium while injecting it
through Promptkit's supported boundary;
- remove obsolete framework packages, tests, and documentation;
- update Scriptorium examples and docs to describe the CLI and HTTP application;
- direct Go framework consumers to Promptkit without providing compatibility
aliases or forwarding APIs.
**Gate:** Scriptorium builds and passes all tests using a tagged Promptkit
dependency, contains no duplicate framework implementation, and its current
documentation describes only the slimmed application.
**Gate status:** Complete as of 2026-07-28. Scriptorium directly resolves
Promptkit `v0.1.0`, no longer contains the framework copy or public Go facade,
and retains only its application, adapter, configuration, presentation,
transport, packaging, and executable-example responsibilities. Release-grade
Scriptorium validation passed with a fresh remote dependency cache, and the
published Promptkit tag passed its documented validation independently. The
application is ready for the downstream-consumer migrations in Step 8.
### Step 8: Migrate Downstream Consumers To Promptkit
Inventory downstream Go consumers and migrate each from the Scriptorium package
to Promptkit. This work may occur in external repositories and must be tracked
explicitly.
For each consumer:
- update module imports and dependencies;
- adapt to any intentionally changed public API;
- run its tests and relevant integration or smoke checks;
- confirm configuration, source, validation, and error behavior;
- release or deploy the migrated consumer through its normal process.
Consumers that cannot migrate immediately may remain pinned to the last
framework-bearing Scriptorium tag. No compatibility work is required in the new
Scriptorium project for those consumers.
**Gate:** All in-scope downstream consumers are either migrated and verified or
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:
- publish Promptkit before dependent Scriptorium releases;
- release the breaking Scriptorium version against the tagged Promptkit
dependency;
- publish migration guidance that maps the former Scriptorium Go API to
Promptkit;
- update cross-project links, examples, package documentation, and release
notes;
- verify that no release artifact depends on local workspaces or replacements;
- archive completed roadmap material according to the documentation policy in
effect at that time.
**Gate:** Promptkit and Scriptorium are independently releasable, their
documentation has distinct and accurate ownership, and the migration status of
all identified downstream consumers is recorded.
**Gate status:** Complete as of 2026-07-28. Promptkit `v0.1.0` remains
published from commit `9e68a2bbf779545995270c47842048a3bc6c85dc`.
Scriptorium `v0.12.0` was published from independently validated commit
`2f42bdde3957563cb9b7a1e27fdd4ab2516f621a` with the intended hosted release
notes, Linux `amd64` and `arm64` binaries, and SHA-256 checksums. Notarius, the
only identified downstream Go consumer, remains migrated and verified.
## Cross-Cutting Constraints
- Preserve the invariant that execution orchestration remains narrow and
application-neutral.
- Keep adapter-specific decisions out of Promptkit.
- Keep Scriptorium dependent only on Promptkit's supported public API.
- Preserve strict external decoding, error classification, validation
semantics, and secret redaction throughout the migration.
- Keep each repository buildable and testable at merged phase boundaries.
- Coordinate cross-repository changes through tagged dependencies and explicit
gates rather than assuming atomic commits across repositories.
- Document only implemented behavior outside roadmap files.
## Completion Criteria
The migration is complete when:
- Promptkit is the independent owner of the reusable framework and built-in
profiles;
- Scriptorium is a slim CLI and HTTP consumer of Promptkit;
- Scriptorium no longer exposes or maintains the former public Go framework;
- all required downstream migrations and external repository work have been
completed or explicitly dispositioned;
- both repositories build, test, document, version, and release independently.

308
docs/roadmap/step9.md
View File

@@ -1,308 +0,0 @@
# Migration Step 9: Complete Release And Documentation Cutover
## Status
Complete as of 2026-07-28. All steps of the
[migration roadmap](migration.md) 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](https://gitea.maximumdirect.net/eric/scriptorium/releases/tag/v0.12.0)
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](../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.