Identify v0.12.0 as the first published application-only release

Retire the completed migration roadmaps
Record completion of the Promptkit migration
2026-07-28 15:59:23 -05:00 · 2026-07-28 20:04:24 +00:00 · 2026-07-28 20:03:11 +00:00
4 changed files with 12 additions and 1125 deletions
--- a/docs/release.md
+++ b/docs/release.md
@@ -8,11 +8,11 @@ releases. The hosted
 executables, publishes their SHA-256 checksums, and uses the matching file
 under `docs/releases/` as the hosted release body.
-`v0.12.0` is the selected version for the pending first application-only
+`v0.12.0` is the first published application-only release. For each later
-release. It remains an unreleased candidate until its annotated tag is
+release, select a new `vMAJOR.MINOR.PATCH` version according to the intended
-published, the hosted workflow succeeds, and every published artifact is
+compatibility change. A selected version remains an unreleased candidate until
-verified. Later releases select a new `vMAJOR.MINOR.PATCH` version according to
+its annotated tag is published, the hosted workflow succeeds, and every
-the intended compatibility change.
+published artifact is verified.
 Run this procedure from the Scriptorium repository root. A release must not
 depend on a Go workspace, module replacement, vendor tree, sibling checkout,
@@ -20,14 +20,17 @@ unpublished dependency, or unpushed source commit.
 ## Establish The Candidate
-For the pending application-only release, start a POSIX shell and select:
+Start a POSIX shell, choose a semantic version that has not been published, and
 export it as `RELEASE_VERSION`. For example, if `v0.12.1` is the intended next
 version and remains unpublished, select:
 ```sh
-export RELEASE_VERSION=v0.12.0
+export RELEASE_VERSION=v0.12.1
 ```
-For a later release, export its not-yet-published semantic version instead.
+Use the version appropriate to the actual compatibility change rather than
-Then run the following guard in that same shell:
+assuming that the example is the next release. Then run the following guard in
 that same shell:
 ```sh
 set -eu
--- a/docs/roadmap/implementation.md
+++ b/docs/roadmap/implementation.md
@@ -1,493 +0,0 @@
 # Step 9 Implementation Plan
 ## Status
 Ready for implementation.
 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.
--- a/docs/roadmap/migration.md
+++ b/docs/roadmap/migration.md
@@ -1,341 +0,0 @@
 # Promptkit Migration Roadmap
 ## Status
 Accepted plan. Steps 1 through 8 are complete. Step 9 remains proposed and is
 not yet implemented.
 ## 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.
 ## 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.
--- a/docs/roadmap/step9.md
+++ b/docs/roadmap/step9.md
@@ -1,282 +0,0 @@
 # 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.
Author	SHA1	Message	Date
Eric Rakestraw	40f8a1c628	Identify v0.12.0 as the first published application-only release	2026-07-28 15:59:23 -05:00
Eric Rakestraw	27d7ad5057	Retire the completed migration roadmaps	2026-07-28 20:04:24 +00:00
Eric Rakestraw	1f08a1a94c	Record completion of the Promptkit migration	2026-07-28 20:03:11 +00:00