From f71d2bbb7371557637cf00c112c406336e26caae Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 28 Jul 2026 14:25:56 -0500 Subject: [PATCH] Add an implementation plan and roadmap for Step 9 of the migration plan --- docs/roadmap/implementation.md | 525 ++++++++++++++++++++++++++++++--- docs/roadmap/migration.md | 10 +- docs/roadmap/step7.md | 64 ---- docs/roadmap/step9.md | 282 ++++++++++++++++++ 4 files changed, 767 insertions(+), 114 deletions(-) delete mode 100644 docs/roadmap/step7.md create mode 100644 docs/roadmap/step9.md diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 0622742..48574fb 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,64 +1,493 @@ -# Step 7 Implementation Completion +# Step 9 Implementation Plan ## Status -Complete as of 2026-07-28. +Ready for implementation. -## Result +This plan implements the target state and policy decisions in +[Step 9](step9.md). Execute the stages in order. A later stage may begin only +after the preceding stage's completion checks pass and any required +cross-repository commit is published. -Scriptorium now consumes -`gitea.maximumdirect.net/eric/promptkit v0.1.0` as an ordinary direct module -dependency. The published tag resolves to Promptkit commit -`9e68a2bbf779545995270c47842048a3bc6c85dc`; no workspace, replacement, -vendored dependency, or sibling-repository state is required. +## Fixed Decisions And Baseline -The Scriptorium module root no longer exposes a Go package. The remaining -production boundary consists of: +- Promptkit `v0.1.0` at commit + `9e68a2bbf779545995270c47842048a3bc6c85dc` is the published framework + baseline. Do not create a new Promptkit tag for documentation-only work. +- Scriptorium `v0.11.1` is the final framework-bearing release. +- Scriptorium `v0.12.0` is the intended first application-only release. +- Scriptorium will not restore a Go facade, compatibility package, alias, or + forwarding API. +- Promptkit retains maintainer-run validation and tag-only source releases. Do + not add hosted Promptkit CI or binary packaging. +- Scriptorium retains hosted, tag-triggered Linux `amd64` and `arm64` binary + releases with SHA-256 checksums. +- Versioned Scriptorium release notes live at + `docs/releases/.md`. The release workflow copies the file matching + `CI_COMMIT_TAG` into its build workspace and supplies that copy to the + Woodpecker release plugin's documented + [`note` setting](https://woodpecker-ci.org/plugins/release). +- The obsolete linker assignment to the removed + `internal/buildinfo.Version` symbol is deleted. Do not introduce a version + command or replacement build-information package. +- Temporary roadmaps remain present through tag and hosted-release + verification. They are removed only after completion is recorded in Git + history. -- `cmd/scriptorium`; -- `internal/adapter/cli`; -- `internal/adapter/http`; -- `internal/config`; -- `internal/defaults`; and -- `internal/format`. +Repository paths for this work are: -The CLI constructs and invokes Promptkit engines, the HTTP adapter maps its -transport contract to Promptkit public values, and the HTTP-specific restricted -artifact reader is injected through Promptkit's public extension point. -Scriptorium retains application configuration, presentation, transport, -containment, process, packaging, and executable-example responsibilities. +- Scriptorium: `/Users/eric/Code/scriptorium/scriptorium` +- Promptkit: `/Users/eric/Code/scriptorium/promptkit` +- Notarius verification checkout: `/Users/eric/Code/notarius` -The former root facade, duplicated framework packages, built-in profile copy, -framework tests and fixtures, Go-library example, and framework-owned -documentation were removed. Permanent Scriptorium documentation now describes -the CLI and HTTP application and links to the tagged Promptkit documentation -for framework contracts. +Do not commit `go.work`, `go.work.sum`, a `replace` directive, vendored +Promptkit source, generated binaries, downloaded release assets, credentials, +or temporary validation output. Use directories created with `mktemp -d` for +clones, caches, builds, and downloads, and remove or leave those directories +outside the repositories. -## Validation Evidence +## Stage 1: Correct Promptkit Release And Project Documentation -Scriptorium passed, outside a Go workspace and without a replacement: +Work only in the Promptkit repository during this stage. -- module identity, graph, tagged dependency, and `go mod tidy -diff` checks; -- ordinary and race-enabled tests, including retained HTTP decoding, limit, - restricted-file, error-mapping, and raw-output coverage; -- vet, formatting, whitespace, architecture, and tracked-tree hygiene checks; -- temporary native and release-equivalent Linux `amd64` and `arm64` builds; -- the maintained render script and both configuration examples without model - credentials; and -- all maintained local and tagged Promptkit documentation links. +### Changes -A fresh temporary module and build cache resolved Promptkit remotely, reported -the expected `v0.1.0` origin commit, and passed the Scriptorium test suite and -build without reading the sibling Promptkit checkout. +1. Rewrite `docs/release.md` as a current, reusable procedure: + - state that `v0.1.0` is the initial published release rather than a planned + tag; + - retain semantic `vMAJOR.MINOR.PATCH` tags, pre-`v1` compatibility notes, + maintainer-run validation, and source-only publication; + - require the maintainer to provide a not-yet-published + `RELEASE_VERSION`, validate it as a semantic version, and derive the + release commit from `HEAD`; + - retain clean-checkout, no-workspace, no-replacement, module identity, + tests, race tests, vet, build, maintained example, formatting, link, + whitespace, and repository-hygiene checks; + - use the annotated tag message as Promptkit's source-only release notes, + recording the version, validated commit, compatibility summary, public + API changes, and any required consumer action; + - retain annotated-tag creation, exact-ref publication, remote tag-object + comparison, source-commit verification, and ordinary Go module + resolution checks; and + - state the Promptkit-before-consumer release ordering without restating + Scriptorium's release procedure. +2. Use guarded shell examples. A missing or already-existing release version, + a dirty checkout, an active workspace, a replacement, an unpushed release + commit, or an existing local or remote tag must stop the procedure before + tag creation. Publish only the selected tag ref, never all local tags. +3. Add a short “Related project” entry to Promptkit's `README.md` linking to + the Scriptorium repository as the CLI and HTTP application built on + Promptkit. Do not copy Scriptorium invocation or transport contracts into + Promptkit. +4. Audit Promptkit README, consumer, architecture, development, and internal + documents for stale extraction or pre-release language. Change only claims + that are no longer true; exact public API and format contracts remain with + their existing canonical owners. -Promptkit was reconfirmed independently at the exact published tag. Its local -and remote tag targets agree, its working tree remains clean, and its -documented test, race, vet, build, example, formatting, module, link, -whitespace, and repository-hygiene checks pass. +### Validation -## Next Gate +- Follow every changed local and cross-project Markdown link. +- Check all changed shell fragments for valid POSIX shell syntax without + executing tag or push commands. +- Run `git diff --check`. +- Confirm no code, module, example, architecture boundary, or public contract + changed. -[Step 8](migration.md#step-8-migrate-downstream-consumers-to-promptkit) may -now inventory and migrate downstream Go consumers. Step 7 did not migrate -external consumers, publish a breaking Scriptorium release, or complete the -release and documentation cutover assigned to Step 9. +### Completion State + +Commit the Promptkit documentation changes with a plain-English message and +push the commit to `origin/main`. Require a clean Promptkit working tree with +`main` synchronized to `origin/main` before Stage 2. Do not create a Promptkit +tag. + +## Stage 2: Establish Scriptorium Release Ownership And Mechanics + +Work only in the Scriptorium repository during this stage. + +### Documentation Ownership + +1. Add two canonical-owner rows to `docs/policy/documentation.md`: + - `docs/release.md` owns the Scriptorium release procedure, including + candidate validation, version and tag operations, hosted-workflow + observation, and artifact verification; + - `docs/releases/` owns immutable version-specific release notes and + migration announcements, not complete interface contracts. +2. Update the release-packaging row in `docs/development.md` to route + contributors to `docs/release.md`, `.woodpecker/release.yml`, and the + architecture policy. +3. Create `docs/release.md` with an end-to-end procedure for: + - selecting `v0.12.0` for this release and a semantic version for later + releases; + - requiring a clean, pushed release commit on `main`, outside a Go + workspace and without a module replacement or vendor tree; + - confirming module identity, Go version, direct Promptkit version, module + graph, module tidiness, and tag availability; + - running the complete application and release-equivalent validation + defined in Stage 4; + - requiring `docs/releases/.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. diff --git a/docs/roadmap/migration.md b/docs/roadmap/migration.md index 4b50dc7..e86ba90 100644 --- a/docs/roadmap/migration.md +++ b/docs/roadmap/migration.md @@ -2,8 +2,8 @@ ## Status -Accepted plan. Steps 1 through 7 are complete. Steps 8 and 9 remain proposed -and are not yet implemented. +Accepted plan. Steps 1 through 8 are complete. Step 9 remains proposed and is +not yet implemented. ## Objective @@ -290,6 +290,12 @@ explicitly recorded as remaining on the previous Scriptorium version with an owner and follow-up plan. Do not declare the ecosystem migration complete until the required out-of-band consumer changes are confirmed. +**Gate status:** Complete as of 2026-07-28. The maintainer confirmed that +Notarius was the only downstream consumer of Scriptorium's former Go package. +Its clean, synchronized main branch now directly requires Promptkit `v0.1.0`, +all relevant Go imports use Promptkit rather than Scriptorium, and its full Go +test suite passes. No downstream consumer remains to migrate or disposition. + ### Step 9: Complete Release And Documentation Cutover Complete the coordinated project transition: diff --git a/docs/roadmap/step7.md b/docs/roadmap/step7.md deleted file mode 100644 index c199d94..0000000 --- a/docs/roadmap/step7.md +++ /dev/null @@ -1,64 +0,0 @@ -# Migration Step 7: Slim Scriptorium And Adopt Promptkit - -## Status - -Complete as of 2026-07-28. - -## Result - -Scriptorium is now an application-only consumer of the published -`gitea.maximumdirect.net/eric/promptkit v0.1.0` module. The command, CLI and -HTTP adapters, restricted artifact reader, and prepared-run formatter use -Promptkit's supported public API. The dependency resolves normally to -Promptkit commit `9e68a2bbf779545995270c47842048a3bc6c85dc` without a workspace, -replacement, vendored copy, or unpublished revision. - -The Scriptorium module root no longer provides an importable Go package or -compatibility facade. The reusable framework packages, embedded built-in -profiles, framework contract tests and fixtures, and Go-library example were -removed. Architecture tests prevent production imports of the former root -facade, removed framework package families, and Promptkit internals. - -## Retained Application Boundary - -Scriptorium owns only its runnable process and application concerns: - -- command and CLI parsing, assembly, streams, summaries, and exit behavior; -- HTTP routes, DTOs, strict decoding, limits, public error mapping, and - restricted artifact access; -- application configuration discovery, validation, precedence, and transport - defaults; -- prepared-run text and JSON presentation; -- executable examples, operations guidance, and binary packaging. - -Promptkit owns prompt execution, framework sources and formats, validation, -model integration, built-in profiles, and ordinary artifact loading. -Scriptorium's permanent documentation reflects that boundary and links to the -tagged Promptkit contracts rather than duplicating them. - -## Acceptance - -The completed cutover passed: - -- module graph and tidiness checks selecting exactly Promptkit `v0.1.0`; -- ordinary and race-enabled Scriptorium tests, vet, formatting, whitespace, - architecture, and repository-hygiene checks; -- temporary native and release-equivalent cross-builds; -- maintained offline render workflows with both application configurations; -- maintained local and tagged-documentation link checks; -- fresh-cache remote dependency resolution, tests, and build with the expected - Promptkit origin commit; and -- Promptkit's complete documented validation independently at its clean local - and remote `v0.1.0` tag. - -These checks cover the retained CLI, HTTP, configuration, containment, -formatting, error-mapping, security, and representative executable behavior. -The working trees contain no generated binaries, temporary workspaces, -replacement directives, credentials, or migration residue. - -## Handoff - -The Step 7 gate is satisfied. [Step 8](migration.md#step-8-migrate-downstream-consumers-to-promptkit) -owns downstream consumer inventory and migration. Step 9 remains responsible -for the breaking Scriptorium release and final documentation cutover; neither -later gate is complete. diff --git a/docs/roadmap/step9.md b/docs/roadmap/step9.md new file mode 100644 index 0000000..c51afde --- /dev/null +++ b/docs/roadmap/step9.md @@ -0,0 +1,282 @@ +# Migration Step 9: Complete Release And Documentation Cutover + +## Status + +Proposed. Steps 1 through 8 of the +[migration roadmap](migration.md) are complete. This is the final migration +gate. + +## Purpose + +Finish the Promptkit split as a released, documented, and independently +maintainable project boundary. Step 9 turns the already-implemented repository +state into the supported public release state, gives former Scriptorium Go +consumers a durable migration path, reconciles release guidance in both +repositories, and retires the temporary migration records once their work is +complete. + +This roadmap defines the intended end state. + +## Release Baseline And Version Decisions + +The coordinated release boundary is: + +- Promptkit `v0.1.0`, already published from commit + `9e68a2bbf779545995270c47842048a3bc6c85dc`, is the framework version consumed + by Scriptorium; +- Scriptorium `v0.11.1` is the final published framework-bearing Scriptorium + release; and +- Scriptorium `v0.12.0` is the first slim application-only release. + +The `v0.12.0` version satisfies +[ADR 0002](../adr/0002-split-promptkit-from-scriptorium.md), which requires +the first slim pre-`v1` Scriptorium release to advance the minor version beyond +the final framework-bearing release. + +Promptkit does not need another tag merely to complete this migration. +Promptkit documentation corrections that do not change the library contract +may land on its main branch without changing Scriptorium's dependency. If Step +9 discovers that a Promptkit code or consumer-visible contract change is +required, Promptkit must instead publish an appropriate later semantic version +first, and Scriptorium must adopt and validate that tag before `v0.12.0` is +published. + +No release may depend on a Go workspace, local module replacement, vendored +sibling source, unpublished commit, or an unpushed tag. + +## Scriptorium Release Readiness + +Scriptorium must have a durable, canonical release procedure appropriate to +its hosted tag-triggered binary workflow. The procedure and contributor +reading guide must collectively define: + +- semantic-version selection and the clean-checkout preconditions; +- validation outside a Go workspace and without a module replacement; +- module identity, dependency resolution, module tidiness, tests, race tests, + vet, formatting, link, example, and repository-hygiene checks; +- release-equivalent Linux `amd64` and `arm64` builds; +- annotated tag creation and publication; +- observation of the hosted release workflow; +- verification of published binaries and checksums; and +- post-publication smoke checks using downloaded release artifacts where the + execution platform permits. + +The documentation policy must assign the release procedure one canonical +owner, and `docs/development.md` must route release work to it. Operations +documentation should link to release material only when an operator task +requires it; it must not become a second release procedure. + +The tag workflow must accurately describe the current application. In +particular, remove the obsolete linker assignment to the deleted +`internal/buildinfo.Version` symbol. The release continues to use stripped, +trimmed binaries unless a separate supported application-version interface is +introduced. Adding a new `--version` command or other product behavior is not +part of this migration. + +Release validation must exercise the same build commands and artifact names as +the hosted workflow. The resulting `v0.12.0` release must contain the supported +Linux `amd64` and `arm64` Scriptorium binaries and published SHA-256 checksums, +with no framework source or Promptkit binary artifact. + +## Promptkit Release Readiness + +Promptkit remains governed by +[ADR 0003](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md): +maintainer-run validation, semantic Go module tags, and no hosted CI or binary +release artifacts. + +Its release procedure must be corrected from pre-release language to current, +reusable guidance. It must no longer describe `v0.1.0` as an uncreated planned +release or instruct a maintainer to create an existing tag. It should: + +- acknowledge `v0.1.0` as the initial published release; +- use version-agnostic instructions for later releases; +- retain the clean-checkout, full-validation, tag-ordering, and remote-tag + verification requirements; and +- require pre-`v1` release notes to identify public API changes and consumer + migration requirements. + +Before Scriptorium `v0.12.0` is tagged, independently reconfirm that the local +and remote Promptkit `v0.1.0` tags resolve to the expected source commit, that +the tagged module is available through ordinary Go module resolution, and that +Promptkit passes its documented release validation without Scriptorium or +sibling-repository state. + +## Go Consumer Migration Guidance + +Scriptorium must publish a permanent migration guide under `docs/consumers/` +for consumers of the former Go package. Scriptorium owns this guide because it +describes departure from Scriptorium's removed API; Promptkit's declarations, +GoDoc, format reference, and consumer guide remain canonical for the +destination contract. + +The guide must identify the supported migration baseline: + +- source: Scriptorium `v0.11.1` and import path + `gitea.maximumdirect.net/eric/scriptorium`; +- destination: Promptkit `v0.1.0` and import path + `gitea.maximumdirect.net/eric/promptkit`; and +- Scriptorium `v0.12.0` and later: executable application only, with no root Go + package or compatibility facade. + +It must provide a minimal, copyable migration workflow: + +1. replace the Scriptorium module requirement and Go imports with Promptkit + `v0.1.0`; +2. update package qualifiers from `scriptorium` to `promptkit`; +3. run `go mod tidy`; +4. compile and test the consuming project; and +5. verify prompt, profile, schema, credential, timeout, validation, injected + client, and error-handling behavior relevant to that consumer. + +The guide should explain that the established engine, request, result, profile, +source-option, model-client, artifact, validation, and error shapes were +intentionally preserved where practical, while Promptkit also owns the +post-extraction public error identities and artifact-reader extension point. +It must direct exact API questions to Promptkit's tagged GoDoc and consumer +guide rather than duplicating the declaration reference. + +The guide must also state the deliberate compatibility policy: there are no +Scriptorium aliases, forwarding packages, or deprecated wrappers. A consumer +that cannot migrate may remain pinned to `v0.11.1`, but it will not receive the +application-only Scriptorium line through that package API. + +## Documentation And Project Identity Cutover + +Review both repositories as separate products and reconcile every maintained +link, example, package comment, and current-state statement with the released +boundary. + +Scriptorium documentation must: + +- present Scriptorium as a CLI and HTTP application, not a Go framework; +- link in-process Go consumers and framework contract questions to tagged + Promptkit `v0.1.0` documentation; +- link former Scriptorium Go consumers to the migration guide; +- keep CLI, HTTP, application configuration, operations, subprocess, and + executable examples under Scriptorium ownership; and +- avoid reproducing Promptkit fields, defaults, public declarations, or + integration contracts. + +Promptkit documentation must: + +- present Promptkit as the reusable Go framework and owner of its root API, + file formats, built-in profiles, validation, and outbound integration; +- retain Scriptorium only as a downstream application example or related + project, not as a framework owner or dependency; +- link to Scriptorium only for executable CLI and HTTP workflows when that + navigation is useful; and +- contain no stale extraction, planned-first-release, or pre-cutover claims. + +Cross-project links must point to the canonical owner. Scriptorium links that +define the framework version it consumes remain pinned to Promptkit `v0.1.0`; +general project-navigation links may point to the other repository's current +project entry point. Maintained examples must stay repository-local and must +not require a sibling checkout. + +## Release Notes And Public Communication + +The Scriptorium `v0.12.0` release notes must clearly identify the release as a +breaking project-boundary change. They must: + +- state that Scriptorium is now an executable-only CLI and HTTP application; +- state that the former Go framework moved to Promptkit; +- link the Scriptorium migration guide and Promptkit `v0.1.0` consumer + documentation; +- identify `v0.11.1` as the final framework-bearing Scriptorium release; +- summarize the retained Scriptorium interfaces and the removed root package; +- record that all known downstream Go consumers were migrated before release; + and +- identify the Promptkit version used by the released binary. + +Release notes must not serve as a duplicate CLI, HTTP, configuration, or +Promptkit API reference. They should route readers to the corresponding +canonical documents. + +## Independent Release And Artifact Verification + +The final acceptance run must treat the repositories as independent remote +projects: + +- validate Promptkit from its exact published tag without Scriptorium; +- validate Scriptorium from its intended release commit outside any workspace + and with a fresh module and build cache that cannot read the sibling + Promptkit checkout; +- confirm the Scriptorium module graph selects the intended published Promptkit + tag; +- verify both working trees contain no tracked workspace, replacement, vendored + cross-project source, generated binary, credential, or temporary release + residue; +- publish and verify the annotated Scriptorium `v0.12.0` tag; +- verify the hosted release completes and publishes the expected binaries and + checksums; +- download the published artifacts into a temporary location, verify their + checksums, file types, target architectures, and basic executable behavior; + and +- recheck maintained local and cross-project documentation links after + publication. + +Ordinary ignored developer files, including an ignored local Scriptorium +binary, do not fail repository hygiene. Acceptance concerns tracked content, +release inputs, generated files introduced by the release work, and published +artifacts. + +## Roadmap Retirement + +Roadmaps are temporary coordination documents. After every Step 9 completion +criterion is satisfied and durable release and migration records exist: + +- mark Step 9 and the overall migration complete before cleanup; +- preserve any still-useful current contract in its canonical permanent owner; +- rely on ADRs, Git history, tags, release notes, and the migration guide for + durable decision and release history; +- remove completed migration, step, and implementation roadmaps rather than + retaining them as a second current-state reference; and +- repair every incoming link affected by that removal. + +The roadmap files must remain until the out-of-band tag and hosted release have +been verified. Creating a release candidate or merging documentation is not +enough to declare the migration complete. + +## Non-Goals + +Step 9 does not: + +- redesign Promptkit's public API or Scriptorium's CLI or HTTP contracts; +- restore a Scriptorium Go facade or add compatibility shims; +- add hosted CI or binary artifacts to Promptkit; +- add new Scriptorium target platforms beyond the existing Linux `amd64` and + `arm64` release policy; +- introduce an application version command solely to preserve a stale linker + flag; +- redo the completed downstream migration inventory; or +- require a new Promptkit release when no Promptkit contract change is needed. + +## Completion Criteria + +Step 9 is complete only when all of the following are true: + +- Promptkit `v0.1.0` remains independently available, validated, and correctly + documented as the published framework dependency; +- Scriptorium has an accurate, canonical, and tested release procedure; +- the Scriptorium release workflow contains no reference to removed framework + or build-information packages and produces only the intended application + artifacts; +- the permanent Go-consumer migration guide is complete, copyable, and linked + from appropriate Scriptorium entry points; +- both repositories' permanent documentation, examples, package comments, and + cross-project links reflect distinct and canonical ownership; +- Scriptorium `v0.12.0` is published from a clean, independently validated + commit that directly requires a published Promptkit tag; +- the hosted Scriptorium release publishes verified Linux `amd64` and `arm64` + binaries and SHA-256 checksums; +- the `v0.12.0` release notes communicate the breaking package move and link to + the migration path; +- all known downstream Go consumers remain migrated or explicitly + dispositioned; +- neither release depends on local multi-repository state; and +- completed migration roadmaps are removed after their useful content and + completion evidence have durable owners. + +When these criteria are satisfied, the Promptkit split is complete and both +projects can evolve, validate, version, document, and release independently.