From 416438d80d25cdc4d825d9b6808f33844acdff9f Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 28 Jul 2026 02:05:57 +0000 Subject: [PATCH] Record Promptkit validation and release decision --- ...ion-and-tag-only-releases-for-promptkit.md | 67 +++++++++++++++++++ docs/roadmap/migration.md | 19 ++++-- 2 files changed, 80 insertions(+), 6 deletions(-) create mode 100644 docs/adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md diff --git a/docs/adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md b/docs/adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md new file mode 100644 index 0000000..63f24c3 --- /dev/null +++ b/docs/adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md @@ -0,0 +1,67 @@ +# ADR 0003: Use Maintainer-Run Validation and Tag-Only Releases for Promptkit + +## Status + +Accepted + +## Date + +2026-07-28 + +## Context + +[ADR 0002](0002-split-promptkit-from-scriptorium.md) established Promptkit as +an independent Go library with its own repository, version history, validation, +and release coordination. It anticipated independent hosted CI for Promptkit +alongside Scriptorium's existing executable build and CI policy. + +Promptkit is presently a single-maintainer library. It does not produce a +runnable command, so executable packaging and binary-release automation do not +apply. Its validation and release model should be explicit before repository +guidance relies on it. + +## Decision + +Promptkit will use maintainer-run validation rather than hosted CI at this +stage. From a clean checkout, the maintainer will run the repository-documented +test, vet, build, formatting, documentation-link, and repository-hygiene checks +before changes are accepted and before a release tag is published. + +Promptkit releases consist of source commits and semantic Go module tags. The +project does not release runnable binaries or maintain binary-packaging +automation. + +Scriptorium's executable build, hosted CI, and binary-release policies are +unaffected. The repository boundary, independent version history, release +ordering, and other migration decisions accepted by ADR 0002 remain in force. +Where ADR 0002 anticipated independent hosted CI for Promptkit, this later ADR +controls Promptkit validation. + +## Alternatives Considered + +- Add hosted Promptkit CI now. This would provide automated remote enforcement, + but its setup and maintenance are not proportionate to the present + single-maintainer library and do not replace the maintainer's release + responsibility. +- Require local Git hooks. Hooks can provide fast feedback, but they are + machine-local, can be bypassed, and are not a durable substitute for the + documented clean-checkout validation procedure. + +## Rationale + +A documented maintainer-run procedure provides a clear acceptance and release +gate with little operational overhead for the project's current contribution +pattern. If maintenance load or contributor patterns change, a later ADR may +introduce hosted CI without changing Promptkit's library or tag-based release +model. + +## Consequences + +- Promptkit repository guidance must define the complete local validation + procedure and the checks required before accepting or tagging a change. +- Release evidence is the maintainer's successful clean-checkout validation, + not a hosted CI result. +- Promptkit releases contain source and semantic Go module tags only. +- A future move to hosted CI requires a later architectural decision. +- Scriptorium continues to validate, build, package, and release its executable + under its own policies. diff --git a/docs/roadmap/migration.md b/docs/roadmap/migration.md index ded5708..ad79a5f 100644 --- a/docs/roadmap/migration.md +++ b/docs/roadmap/migration.md @@ -190,7 +190,10 @@ Establish: - repository access, ownership, and branch protections; - the module path selected by the ADR; - baseline development, architecture, documentation, and release policies; -- CI for build, test, vet, and other agreed checks; +- documented maintainer-run test, vet, build, formatting, documentation-link, + and repository-hygiene validation; +- a tag-based release procedure for source commits and semantic Go module tags, + without runnable binaries or binary packaging; - an initial package layout centered on a small public facade with internal implementation packages; - a local development workflow for coordinated Promptkit and Scriptorium @@ -198,11 +201,14 @@ Establish: appropriate. Do not commit local filesystem `replace` directives to release branches. +[ADR 0003](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md) +records the controlling Promptkit validation and release decision. **Gate:** The Promptkit repository exists, is accessible to maintainers, has -working CI and policy scaffolding, and can receive the extracted framework. -Do not begin cross-repository extraction until this out-of-band work is -confirmed complete. +documented maintainer-run validation and tag-based release procedures, has the +required policy scaffolding, and can receive the extracted framework. Do not +begin cross-repository extraction until this out-of-band work is confirmed +complete. ### Step 6: Extract And Stabilize Promptkit @@ -225,8 +231,9 @@ Verify that Promptkit can be built, tested, and consumed independently of the Scriptorium repository. **Gate:** Promptkit independently provides the agreed framework contract, -passes its CI checks, and has a tagged version that Scriptorium and other -consumers can import. +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). ### Step 7: Slim Scriptorium And Adopt Promptkit