From 27d7ad50576b5329fa7cc6cc5021b9602c167d7b Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 28 Jul 2026 20:04:24 +0000 Subject: [PATCH] Retire the completed migration roadmaps --- docs/roadmap/implementation.md | 514 --------------------------------- docs/roadmap/migration.md | 349 ---------------------- docs/roadmap/step9.md | 308 -------------------- 3 files changed, 1171 deletions(-) delete mode 100644 docs/roadmap/implementation.md delete mode 100644 docs/roadmap/migration.md delete mode 100644 docs/roadmap/step9.md diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index 154da2c..0000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -1,514 +0,0 @@ -# Step 9 Implementation Plan - -## Status - -Complete as of 2026-07-28. - -## Completion Summary - -Promptkit's annotated `v0.1.0` tag remains published at commit -`9e68a2bbf779545995270c47842048a3bc6c85dc`. Scriptorium's annotated -`v0.12.0` tag object `734632371773bb7620ce9f18e79ae179a2a2b44b` -resolves to independently validated commit -`2f42bdde3957563cb9b7a1e27fdd4ab2516f621a`. The -[hosted release](https://gitea.maximumdirect.net/eric/scriptorium/releases/tag/v0.12.0) -succeeded with release notes matching the checked-in source, exactly the Linux -`amd64` and `arm64` binaries, and verified SHA-256 checksums. - -Fresh remote module resolution and independent repository validation passed -without sibling-repository state. The downloaded `amd64` binary completed an -offline render; its existing command interface treated `--help` as an unknown -command and printed usage. The `arm64` binary could not be executed on the -`amd64` host, so its checksum, format, and target architecture were verified. -Notarius at commit `de046a8f13e227676d79c3aa3b685b049902038d` -remains migrated and verified, and no other downstream Go consumer was -identified. All three repositories were clean and synchronized after -validation. - -This plan implements the target state and policy decisions in -[Step 9](step9.md). Execute the stages in order. A later stage may begin only -after the preceding stage's completion checks pass and any required -cross-repository commit is published. - -## Fixed Decisions And Baseline - -- Promptkit `v0.1.0` at commit - `9e68a2bbf779545995270c47842048a3bc6c85dc` is the published framework - baseline. Do not create a new Promptkit tag for documentation-only work. -- Scriptorium `v0.11.1` is the final framework-bearing release. -- Scriptorium `v0.12.0` is the intended first application-only release. -- Scriptorium will not restore a Go facade, compatibility package, alias, or - forwarding API. -- Promptkit retains maintainer-run validation and tag-only source releases. Do - not add hosted Promptkit CI or binary packaging. -- Scriptorium retains hosted, tag-triggered Linux `amd64` and `arm64` binary - releases with SHA-256 checksums. -- Versioned Scriptorium release notes live at - `docs/releases/.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/.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 deleted file mode 100644 index 58fa641..0000000 --- a/docs/roadmap/migration.md +++ /dev/null @@ -1,349 +0,0 @@ -# Promptkit Migration Roadmap - -## Status - -Complete as of 2026-07-28. All nine steps and the overall Promptkit migration -are complete. The final release and validation evidence is recorded in -[Step 9](step9.md). - -## Objective - -Split the current repository into two projects: - -- **Promptkit**: the reusable Go framework, public Go facade, execution engine, - source and validation support, OpenAI-compatible client, extension - interfaces, and built-in execution-profile registry. -- **Scriptorium**: a slim runnable application that imports Promptkit and - provides the CLI and HTTP interfaces. - -Scriptorium will become another downstream Promptkit consumer rather than the -owner of the framework. - -## Compatibility And Migration Policy - -This is an intentionally breaking change. - -- New and migrated Go consumers must import Promptkit instead of Scriptorium. -- Scriptorium will not retain type aliases, forwarding packages, deprecated - facade APIs, or other source-compatibility shims. -- Existing consumers may continue using a previously tagged Scriptorium module - version until they are migrated. -- The migration does not need to preserve compatibility between intermediate - development states. Each completed phase must instead leave the affected - repository internally consistent and tested. -- Promptkit should initially preserve the useful shape and behavior of the - current public Go facade where doing so reduces extraction risk. Broader API - redesign should follow the split unless required to establish the new - boundary. - -## Target Ownership - -Promptkit should own application-neutral framework behavior: - -- public engine, request, result, option, extension, and error APIs; -- prompt-definition loading and rendering; -- execution profiles, overlays, and the built-in profile registry; -- artifact-loading interfaces and general-purpose `file` and `inline` support; -- schema loading and output validation; -- LLM client boundaries and the OpenAI-compatible implementation; -- preparation and execution orchestration; -- framework and execution defaults. - -Scriptorium should own executable and transport concerns: - -- the `scriptorium` command and its `run`, `render`, and `serve` interfaces; -- CLI parsing, output formatting, exit codes, and process behavior; -- application-config discovery and CLI precedence; -- HTTP routing, request and response DTOs, limits, and error/status mapping; -- HTTP artifact-root and deployment security policy; -- server and adapter defaults; -- executable examples, operations guidance, and transport documentation. - -The intended dependency direction is: - -```text -Scriptorium CLI and HTTP adapters - | - v - Promptkit - | - v - consumer-supplied sources and clients -``` - -Scriptorium must use Promptkit's public API. It must not depend on Promptkit -implementation packages or reproduce framework orchestration. - -## Migration Steps - -### Step 1: Refresh And Synchronize Documentation - -Perform a repository-wide documentation refresh before migration development. - -At minimum: - -- reconcile all current-behavior documentation with the code, tests, examples, - defaults, and current public contracts; -- introduce the planned documentation-policy updates; -- establish an architecture decision record policy and canonical ADR location; -- resolve stale, duplicated, or misplaced material; -- validate documentation links and maintained examples; -- leave future migration behavior in `docs/roadmap/` until implemented. - -**Gate:** Do not begin architectural migration work until the documentation -refresh and policy updates are merged and the repository has an agreed, -accurate baseline. - -**Gate status:** Complete as of 2026-07-26. The completed documentation -refresh, follow-up verification, and layered-timeout correction remain recorded -in repository history. Step 1 remains complete after that validation. - -### Step 2: Record The Architectural Decision And Detailed Boundary - -Create an ADR, under the policy established in Step 1, that records: - -- the decision to split Promptkit from Scriptorium; -- the target ownership and dependency direction; -- the selected Promptkit repository and Go module paths; -- the breaking-change and versioning policy; -- ownership of configuration fields and defaults; -- artifact-reader and HTTP containment responsibilities; -- local multi-repository development and release coordination; -- documentation ownership after the split. - -Use the ADR to resolve any remaining public-boundary decisions before code is -moved. - -**Gate:** The ADR is accepted, and every existing package, public contract, -configuration category, and maintained asset has a target owner. - -**Gate status:** Complete as of 2026-07-26. -[ADR 0002: Split Promptkit From Scriptorium](../adr/0002-split-promptkit-from-scriptorium.md) -is accepted and records the required ownership and coordination decisions. - -### Step 3: Characterize Existing Framework Behavior - -Strengthen or add contract-focused tests where needed so extraction can be -verified without relying on package placement. - -The completed Step 3 gate records the accepted implementation scope and -intended completion state. - -Preserve coverage of: - -- `Prepare` and `Run` behavior; -- prompt, profile, execution-default, and request-override precedence; -- presence-aware numeric overrides; -- built-in profile fallback and custom-profile overlays; -- strict YAML and JSON decoding; -- prompt, profile, schema, and artifact source behavior; -- structured-output requests and output validation; -- validation failures versus validation runtime errors; -- secret handling and redaction; -- public error classification; -- HTTP artifact restrictions and transport mappings. - -**Gate:** Current framework and adapter contracts are represented by passing -tests sufficient to detect behavioral regressions during the split. - -**Gate status:** Complete as of 2026-07-27. The framework contract corpus, -public `Engine` characterization, ownership audit, full test and vet suites, -temporary executable build, and maintained offline examples passed. - -### Step 4: Make Scriptorium Adapters Consume The Public Facade - -Within the current repository, refactor the CLI and HTTP adapters to use the -public framework facade rather than constructing or importing internal runner -components directly. - -Add only the minimum public capabilities needed to support this boundary. These -may include: - -- a small `Run`/`Prepare` consumer interface; -- injectable artifact-reading behavior for Scriptorium's restricted HTTP - policy; -- source options currently available only through internal constructors; -- prepared-run formatting based on public types; -- stable public error classification required by CLI and HTTP mappings. - -Do not broadly export internal repositories, domain types, or use-case -implementations. - -**Gate:** The CLI and HTTP adapters use only the public framework API for -framework behavior, and all tests and documented smoke commands pass. - -**Gate status:** Complete as of 2026-07-28. CLI `run`, `render`, and `serve`, -the HTTP handler, and prepared-run formatting use the public facade; the -restricted HTTP reader is injected through the public extension point. The -post-implementation public-error, deterministic MIME, and recursive -dependency-guard corrections passed full tests, vet, build, race checks, -maintained examples, and configuration smoke checks. - -### Step 5: Create The Promptkit Repository - -Promptkit was established as an independent repository and Go module through -the completed out-of-band workflow recorded in repository history. Its -foundation includes: - -- confirmed repository access, governance, origin, and default-branch tracking; -- module `gitea.maximumdirect.net/eric/promptkit` at Go `1.25.5`; -- a minimal root `promptkit` public package boundary with no placeholder - framework packages; -- library-specific development, architecture, documentation, testing, and - release policies; -- documented maintainer-run test, vet, build, formatting, documentation-link, - and repository-hygiene validation; -- source-commit and semantic Go module tag releases without runnable binaries - or binary packaging; and -- temporary workspace and uncommitted replacement workflows for coordinated - development without committed repository coupling. - -[ADR 0003](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md) -records the controlling Promptkit validation and release decision. - -**Gate status:** Complete as of 2026-07-28. Promptkit passed its documented -validation independently, all maintained links and repository-hygiene checks -passed, and no workspace, replacement, CI configuration, binary, tag, command, -or placeholder package was added. The completed repository foundation -supported the Step 6 extraction. - -### Step 6: Extract And Stabilize Promptkit - -Move the application-neutral framework and built-in profile assets into -Promptkit. Preserve implementation packages as internal where practical. - -The initial public API should remain focused on the established engine workflow -and the source and client extension points required by real consumers. Avoid -combining the extraction with unrelated API redesign. - -Move or recreate the relevant: - -- framework implementation; -- public package tests and framework contract tests; -- built-in profile assets and registry tests; -- Go consumer examples; -- framework, consumer, configuration-format, and integration documentation. - -Verify that Promptkit can be built, tested, and consumed independently of the -Scriptorium repository. - -**Gate:** Promptkit independently provides the agreed framework contract, -passes its documented validation, and has published its first versioned tag -before Scriptorium or another consumer adopts it, as required by -[ADR 0003](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md). - -**Gate status:** Complete as of 2026-07-28. Repository history records source -Scriptorium commit `c7263ab2a8e58f7fb97280082d327a820c7cece7`, -accepted Promptkit commit -`9e68a2bbf779545995270c47842048a3bc6c85dc`, independently passing acceptance, -published annotated tag `v0.1.0`, and successful remote-consumer validation. -Scriptorium remains unchanged at its pre-cutover boundary. Step 7 adoption of -the tagged module and removal of the duplicated framework is the next gate. - -### Step 7: Slim Scriptorium And Adopt Promptkit - -Update Scriptorium to import the tagged Promptkit module and remove the -framework implementation and public Go facade that Promptkit replaces. - -Retain only Scriptorium-owned executable and transport behavior. In particular: - -- wire CLI and HTTP requests through Promptkit's public API; -- keep application config and transport defaults in Scriptorium; -- keep restricted HTTP artifact policy in Scriptorium while injecting it - through Promptkit's supported boundary; -- remove obsolete framework packages, tests, and documentation; -- update Scriptorium examples and docs to describe the CLI and HTTP application; -- direct Go framework consumers to Promptkit without providing compatibility - aliases or forwarding APIs. - -**Gate:** Scriptorium builds and passes all tests using a tagged Promptkit -dependency, contains no duplicate framework implementation, and its current -documentation describes only the slimmed application. - -**Gate status:** Complete as of 2026-07-28. Scriptorium directly resolves -Promptkit `v0.1.0`, no longer contains the framework copy or public Go facade, -and retains only its application, adapter, configuration, presentation, -transport, packaging, and executable-example responsibilities. Release-grade -Scriptorium validation passed with a fresh remote dependency cache, and the -published Promptkit tag passed its documented validation independently. The -application is ready for the downstream-consumer migrations in Step 8. - -### Step 8: Migrate Downstream Consumers To Promptkit - -Inventory downstream Go consumers and migrate each from the Scriptorium package -to Promptkit. This work may occur in external repositories and must be tracked -explicitly. - -For each consumer: - -- update module imports and dependencies; -- adapt to any intentionally changed public API; -- run its tests and relevant integration or smoke checks; -- confirm configuration, source, validation, and error behavior; -- release or deploy the migrated consumer through its normal process. - -Consumers that cannot migrate immediately may remain pinned to the last -framework-bearing Scriptorium tag. No compatibility work is required in the new -Scriptorium project for those consumers. - -**Gate:** All in-scope downstream consumers are either migrated and verified or -explicitly recorded as remaining on the previous Scriptorium version with an -owner and follow-up plan. Do not declare the ecosystem migration complete until -the required out-of-band consumer changes are confirmed. - -**Gate status:** Complete as of 2026-07-28. The maintainer confirmed that -Notarius was the only downstream consumer of Scriptorium's former Go package. -Its clean, synchronized main branch now directly requires Promptkit `v0.1.0`, -all relevant Go imports use Promptkit rather than Scriptorium, and its full Go -test suite passes. No downstream consumer remains to migrate or disposition. - -### Step 9: Complete Release And Documentation Cutover - -Complete the coordinated project transition: - -- publish Promptkit before dependent Scriptorium releases; -- release the breaking Scriptorium version against the tagged Promptkit - dependency; -- publish migration guidance that maps the former Scriptorium Go API to - Promptkit; -- update cross-project links, examples, package documentation, and release - notes; -- verify that no release artifact depends on local workspaces or replacements; -- archive completed roadmap material according to the documentation policy in - effect at that time. - -**Gate:** Promptkit and Scriptorium are independently releasable, their -documentation has distinct and accurate ownership, and the migration status of -all identified downstream consumers is recorded. - -**Gate status:** Complete as of 2026-07-28. Promptkit `v0.1.0` remains -published from commit `9e68a2bbf779545995270c47842048a3bc6c85dc`. -Scriptorium `v0.12.0` was published from independently validated commit -`2f42bdde3957563cb9b7a1e27fdd4ab2516f621a` with the intended hosted release -notes, Linux `amd64` and `arm64` binaries, and SHA-256 checksums. Notarius, the -only identified downstream Go consumer, remains migrated and verified. - -## Cross-Cutting Constraints - -- Preserve the invariant that execution orchestration remains narrow and - application-neutral. -- Keep adapter-specific decisions out of Promptkit. -- Keep Scriptorium dependent only on Promptkit's supported public API. -- Preserve strict external decoding, error classification, validation - semantics, and secret redaction throughout the migration. -- Keep each repository buildable and testable at merged phase boundaries. -- Coordinate cross-repository changes through tagged dependencies and explicit - gates rather than assuming atomic commits across repositories. -- Document only implemented behavior outside roadmap files. - -## Completion Criteria - -The migration is complete when: - -- Promptkit is the independent owner of the reusable framework and built-in - profiles; -- Scriptorium is a slim CLI and HTTP consumer of Promptkit; -- Scriptorium no longer exposes or maintains the former public Go framework; -- all required downstream migrations and external repository work have been - completed or explicitly dispositioned; -- both repositories build, test, document, version, and release independently. diff --git a/docs/roadmap/step9.md b/docs/roadmap/step9.md deleted file mode 100644 index 903b694..0000000 --- a/docs/roadmap/step9.md +++ /dev/null @@ -1,308 +0,0 @@ -# Migration Step 9: Complete Release And Documentation Cutover - -## Status - -Complete as of 2026-07-28. All steps of the -[migration roadmap](migration.md) are complete. - -## Completion Record - -- Promptkit's annotated `v0.1.0` tag remains published at commit - `9e68a2bbf779545995270c47842048a3bc6c85dc`; its independent documented - validation and fresh remote module resolution passed. -- Scriptorium's annotated `v0.12.0` tag object - `734632371773bb7620ce9f18e79ae179a2a2b44b` resolves to independently - validated commit `2f42bdde3957563cb9b7a1e27fdd4ab2516f621a`. -- The - [hosted release](https://gitea.maximumdirect.net/eric/scriptorium/releases/tag/v0.12.0) - completed successfully with the checked-in release notes, exactly the Linux - `amd64` and `arm64` binaries, and `SHA256SUMS`. Both checksums and binary - architectures were verified. -- Fresh remote module queries resolved both release tags to their expected - commits and confirmed that Scriptorium selects Promptkit `v0.1.0`, without a - workspace, replacement, vendored sibling source, or local module cache. -- The downloaded Linux `amd64` binary completed an offline render smoke test. - Its existing command interface has no `--help` command, so that invocation - returned the expected unknown-command usage response. The Linux `arm64` - binary was not executed on the `amd64` validation host; its checksum, format, - and target architecture were verified. -- Notarius at commit `de046a8f13e227676d79c3aa3b685b049902038d` - remains migrated to Promptkit and passed its full test suite. No other - downstream consumer of the former Scriptorium Go package was identified. -- Promptkit, Scriptorium, and Notarius were clean and synchronized with their - remote main branches after validation. - -## Purpose - -Finish the Promptkit split as a released, documented, and independently -maintainable project boundary. Step 9 turns the already-implemented repository -state into the supported public release state, gives former Scriptorium Go -consumers a durable migration path, reconciles release guidance in both -repositories, and retires the temporary migration records once their work is -complete. - -This roadmap defines the intended end state. - -## Release Baseline And Version Decisions - -The coordinated release boundary is: - -- Promptkit `v0.1.0`, already published from commit - `9e68a2bbf779545995270c47842048a3bc6c85dc`, is the framework version consumed - by Scriptorium; -- Scriptorium `v0.11.1` is the final published framework-bearing Scriptorium - release; and -- Scriptorium `v0.12.0` is the first slim application-only release. - -The `v0.12.0` version satisfies -[ADR 0002](../adr/0002-split-promptkit-from-scriptorium.md), which requires -the first slim pre-`v1` Scriptorium release to advance the minor version beyond -the final framework-bearing release. - -Promptkit does not need another tag merely to complete this migration. -Promptkit documentation corrections that do not change the library contract -may land on its main branch without changing Scriptorium's dependency. If Step -9 discovers that a Promptkit code or consumer-visible contract change is -required, Promptkit must instead publish an appropriate later semantic version -first, and Scriptorium must adopt and validate that tag before `v0.12.0` is -published. - -No release may depend on a Go workspace, local module replacement, vendored -sibling source, unpublished commit, or an unpushed tag. - -## Scriptorium Release Readiness - -Scriptorium must have a durable, canonical release procedure appropriate to -its hosted tag-triggered binary workflow. The procedure and contributor -reading guide must collectively define: - -- semantic-version selection and the clean-checkout preconditions; -- validation outside a Go workspace and without a module replacement; -- module identity, dependency resolution, module tidiness, tests, race tests, - vet, formatting, link, example, and repository-hygiene checks; -- release-equivalent Linux `amd64` and `arm64` builds; -- annotated tag creation and publication; -- observation of the hosted release workflow; -- verification of published binaries and checksums; and -- post-publication smoke checks using downloaded release artifacts where the - execution platform permits. - -The documentation policy must assign the release procedure one canonical -owner, and `docs/development.md` must route release work to it. Operations -documentation should link to release material only when an operator task -requires it; it must not become a second release procedure. - -The tag workflow must accurately describe the current application. In -particular, remove the obsolete linker assignment to the deleted -`internal/buildinfo.Version` symbol. The release continues to use stripped, -trimmed binaries unless a separate supported application-version interface is -introduced. Adding a new `--version` command or other product behavior is not -part of this migration. - -Release validation must exercise the same build commands and artifact names as -the hosted workflow. The resulting `v0.12.0` release must contain the supported -Linux `amd64` and `arm64` Scriptorium binaries and published SHA-256 checksums, -with no framework source or Promptkit binary artifact. - -## Promptkit Release Readiness - -Promptkit remains governed by -[ADR 0003](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md): -maintainer-run validation, semantic Go module tags, and no hosted CI or binary -release artifacts. - -Its release procedure must be corrected from pre-release language to current, -reusable guidance. It must no longer describe `v0.1.0` as an uncreated planned -release or instruct a maintainer to create an existing tag. It should: - -- acknowledge `v0.1.0` as the initial published release; -- use version-agnostic instructions for later releases; -- retain the clean-checkout, full-validation, tag-ordering, and remote-tag - verification requirements; and -- require pre-`v1` release notes to identify public API changes and consumer - migration requirements. - -Before Scriptorium `v0.12.0` is tagged, independently reconfirm that the local -and remote Promptkit `v0.1.0` tags resolve to the expected source commit, that -the tagged module is available through ordinary Go module resolution, and that -Promptkit passes its documented release validation without Scriptorium or -sibling-repository state. - -## Go Consumer Migration Guidance - -Scriptorium must publish a permanent migration guide under `docs/consumers/` -for consumers of the former Go package. Scriptorium owns this guide because it -describes departure from Scriptorium's removed API; Promptkit's declarations, -GoDoc, format reference, and consumer guide remain canonical for the -destination contract. - -The guide must identify the supported migration baseline: - -- source: Scriptorium `v0.11.1` and import path - `gitea.maximumdirect.net/eric/scriptorium`; -- destination: Promptkit `v0.1.0` and import path - `gitea.maximumdirect.net/eric/promptkit`; and -- Scriptorium `v0.12.0` and later: executable application only, with no root Go - package or compatibility facade. - -It must provide a minimal, copyable migration workflow: - -1. replace the Scriptorium module requirement and Go imports with Promptkit - `v0.1.0`; -2. update package qualifiers from `scriptorium` to `promptkit`; -3. run `go mod tidy`; -4. compile and test the consuming project; and -5. verify prompt, profile, schema, credential, timeout, validation, injected - client, and error-handling behavior relevant to that consumer. - -The guide should explain that the established engine, request, result, profile, -source-option, model-client, artifact, validation, and error shapes were -intentionally preserved where practical, while Promptkit also owns the -post-extraction public error identities and artifact-reader extension point. -It must direct exact API questions to Promptkit's tagged GoDoc and consumer -guide rather than duplicating the declaration reference. - -The guide must also state the deliberate compatibility policy: there are no -Scriptorium aliases, forwarding packages, or deprecated wrappers. A consumer -that cannot migrate may remain pinned to `v0.11.1`, but it will not receive the -application-only Scriptorium line through that package API. - -## Documentation And Project Identity Cutover - -Review both repositories as separate products and reconcile every maintained -link, example, package comment, and current-state statement with the released -boundary. - -Scriptorium documentation must: - -- present Scriptorium as a CLI and HTTP application, not a Go framework; -- link in-process Go consumers and framework contract questions to tagged - Promptkit `v0.1.0` documentation; -- link former Scriptorium Go consumers to the migration guide; -- keep CLI, HTTP, application configuration, operations, subprocess, and - executable examples under Scriptorium ownership; and -- avoid reproducing Promptkit fields, defaults, public declarations, or - integration contracts. - -Promptkit documentation must: - -- present Promptkit as the reusable Go framework and owner of its root API, - file formats, built-in profiles, validation, and outbound integration; -- retain Scriptorium only as a downstream application example or related - project, not as a framework owner or dependency; -- link to Scriptorium only for executable CLI and HTTP workflows when that - navigation is useful; and -- contain no stale extraction, planned-first-release, or pre-cutover claims. - -Cross-project links must point to the canonical owner. Scriptorium links that -define the framework version it consumes remain pinned to Promptkit `v0.1.0`; -general project-navigation links may point to the other repository's current -project entry point. Maintained examples must stay repository-local and must -not require a sibling checkout. - -## Release Notes And Public Communication - -The Scriptorium `v0.12.0` release notes must clearly identify the release as a -breaking project-boundary change. They must: - -- state that Scriptorium is now an executable-only CLI and HTTP application; -- state that the former Go framework moved to Promptkit; -- link the Scriptorium migration guide and Promptkit `v0.1.0` consumer - documentation; -- identify `v0.11.1` as the final framework-bearing Scriptorium release; -- summarize the retained Scriptorium interfaces and the removed root package; -- record that all known downstream Go consumers were migrated before release; - and -- identify the Promptkit version used by the released binary. - -Release notes must not serve as a duplicate CLI, HTTP, configuration, or -Promptkit API reference. They should route readers to the corresponding -canonical documents. - -## Independent Release And Artifact Verification - -The final acceptance run must treat the repositories as independent remote -projects: - -- validate Promptkit from its exact published tag without Scriptorium; -- validate Scriptorium from its intended release commit outside any workspace - and with a fresh module and build cache that cannot read the sibling - Promptkit checkout; -- confirm the Scriptorium module graph selects the intended published Promptkit - tag; -- verify both working trees contain no tracked workspace, replacement, vendored - cross-project source, generated binary, credential, or temporary release - residue; -- publish and verify the annotated Scriptorium `v0.12.0` tag; -- verify the hosted release completes and publishes the expected binaries and - checksums; -- download the published artifacts into a temporary location, verify their - checksums, file types, target architectures, and basic executable behavior; - and -- recheck maintained local and cross-project documentation links after - publication. - -Ordinary ignored developer files, including an ignored local Scriptorium -binary, do not fail repository hygiene. Acceptance concerns tracked content, -release inputs, generated files introduced by the release work, and published -artifacts. - -## Roadmap Retirement - -Roadmaps are temporary coordination documents. After every Step 9 completion -criterion is satisfied and durable release and migration records exist: - -- mark Step 9 and the overall migration complete before cleanup; -- preserve any still-useful current contract in its canonical permanent owner; -- rely on ADRs, Git history, tags, release notes, and the migration guide for - durable decision and release history; -- remove completed migration, step, and implementation roadmaps rather than - retaining them as a second current-state reference; and -- repair every incoming link affected by that removal. - -The roadmap files must remain until the out-of-band tag and hosted release have -been verified. Creating a release candidate or merging documentation is not -enough to declare the migration complete. - -## Non-Goals - -Step 9 does not: - -- redesign Promptkit's public API or Scriptorium's CLI or HTTP contracts; -- restore a Scriptorium Go facade or add compatibility shims; -- add hosted CI or binary artifacts to Promptkit; -- add new Scriptorium target platforms beyond the existing Linux `amd64` and - `arm64` release policy; -- introduce an application version command solely to preserve a stale linker - flag; -- redo the completed downstream migration inventory; or -- require a new Promptkit release when no Promptkit contract change is needed. - -## Completion Criteria - -Step 9 is complete only when all of the following are true: - -- Promptkit `v0.1.0` remains independently available, validated, and correctly - documented as the published framework dependency; -- Scriptorium has an accurate, canonical, and tested release procedure; -- the Scriptorium release workflow contains no reference to removed framework - or build-information packages and produces only the intended application - artifacts; -- the permanent Go-consumer migration guide is complete, copyable, and linked - from appropriate Scriptorium entry points; -- both repositories' permanent documentation, examples, package comments, and - cross-project links reflect distinct and canonical ownership; -- Scriptorium `v0.12.0` is published from a clean, independently validated - commit that directly requires a published Promptkit tag; -- the hosted Scriptorium release publishes verified Linux `amd64` and `arm64` - binaries and SHA-256 checksums; -- the `v0.12.0` release notes communicate the breaking package move and link to - the migration path; -- all known downstream Go consumers remain migrated or explicitly - dispositioned; -- neither release depends on local multi-repository state; and -- completed migration roadmaps are removed after their useful content and - completion evidence have durable owners. - -When these criteria are satisfied, the Promptkit split is complete and both -projects can evolve, validate, version, document, and release independently.