diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 2c6af34..1f6e864 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,422 +1,63 @@ -# Step 5 Implementation Plan +# Step 5 Implementation Record ## Status -Proposed. - -This plan implements -[Migration Step 5: Promptkit Repository Foundation](step5.md). The feature -roadmap is the canonical source for the intended end state and policy choices; -this document owns implementation order, concrete changes, and validation. - -## Scope and Repository Boundaries - -Step 5 changes two sibling repositories: - -- `scriptorium` remains the controlling repository for the migration roadmap - and architectural decision records. -- `promptkit` becomes a self-contained Go library repository with its own - policies, contributor guidance, release procedure, module metadata, and - validation baseline. - -Paths in this plan are relative to the named repository unless otherwise -stated. Run commands from the root of the repository named by the stage. - -The implementation agent must preserve these boundaries: - -- Do not move framework implementation or public APIs from Scriptorium. That is - Step 6 work. -- Do not add placeholder packages or empty directory scaffolding for future - framework components. -- Do not add hosted CI configuration, release binaries, or binary-packaging - automation to Promptkit. -- Do not create or publish a Promptkit version tag. The first `v0.1.0` tag - belongs to Step 6 after framework extraction. -- Do not add a committed `go.work` file or a committed local `replace` - directive to either repository. -- Keep Scriptorium and Promptkit changes in their respective Git histories. - Never create a cross-repository commit. - -## Stage 1: Reconcile the Durable Validation and Release Decision - -### Objective - -Record the approved Promptkit validation and release model in a permanent ADR, -then make the controlling migration roadmap consistent with that decision -before relying on it in Promptkit documentation. - -### Scriptorium Changes - -Create the next sequential ADR under `docs/adr/` with an Accepted status. Use -the repository's current ADR format and the actual implementation date. Give it -a title that describes the decision, such as -`Use Maintainer-Run Validation and Tag-Only Releases for Promptkit`. - -The ADR must make the following points decision content: - -- Promptkit is a Go library and does not release runnable binaries. -- Promptkit does not use hosted CI at this stage. -- Its required checks are run by the maintainer from a clean checkout before - changes are accepted and before a release tag is published. -- Promptkit releases consist of source commits and semantic Go module tags. -- The required local checks are the repository-documented test, vet, build, - formatting, documentation-link, and repository-hygiene checks. -- Scriptorium's own executable build and CI policy are unaffected. -- The repository boundary, independent version history, and migration ordering - accepted by - [ADR 0002](../adr/0002-split-promptkit-from-scriptorium.md) remain in force. -- Where ADR 0002 anticipated independent hosted CI for Promptkit, the new ADR - is the later, controlling decision for Promptkit validation. - -Document at least hosted Promptkit CI and required local hooks as alternatives. -Explain why maintainer-run validation is proportionate for the present -single-maintainer library while making clear that a later ADR may introduce -hosted CI if maintenance or contribution patterns change. - -Do not mark ADR 0002 Rejected or Superseded. The new decision refines only its -validation assumption and does not replace the accepted repository split. Link -the new ADR to ADR 0002 from the new record; do not rewrite ADR 0002's -historical decision content. - -Update `docs/roadmap/migration.md` so that: - -- Step 5 requires Promptkit's documented maintainer-run validation and - tag-based release procedure instead of hosted CI or binary packaging; -- Step 6 requires the extracted library to pass Promptkit's documented - validation rather than “CI checks”; -- the release-order gate continues to require Promptkit's first versioned tag - before Scriptorium consumes it; and -- the new ADR is linked wherever the later validation decision is material. - -Do not mark Step 5 complete in this stage. - -### Stage 1 Validation - -From the Scriptorium repository: - -1. Confirm the new ADR contains a title, date, Accepted status, context, - decision, alternatives, and consequences. -2. Confirm ADR 0002 remains Accepted and its decision content is unchanged. -3. Search `docs/roadmap/migration.md` for Promptkit CI and binary-release - requirements and confirm no obsolete requirement remains. -4. Check every changed Markdown link. -5. Run `git diff --check`. - -### Stage 1 Completion Gate - -Proceed only when the permanent decision record and controlling migration -roadmap consistently describe maintainer-run validation, tag-only library -releases, and no Promptkit release binaries. - -## Stage 2: Establish the Promptkit Go Module and License Baseline - -### Objective - -Make Promptkit a valid, independently buildable Go module with an accurate root -package and project-specific GPLv3 example notices. - -### Promptkit Module Files - -Create `go.mod` with exactly this module identity and Go baseline: - -```go -module gitea.maximumdirect.net/eric/promptkit - -go 1.25.5 -``` - -Do not add dependencies solely to populate the module. A `go.sum` file is not -expected while the module has no external dependencies. - -Create a root `doc.go` that: - -- declares `package promptkit`; -- contains a package comment beginning with `Package promptkit`; -- describes the package only as the public package boundary for the Promptkit - Go module; and -- does not claim that framework behavior or APIs have already been migrated. - -Do not add exported symbols, placeholder implementations, empty internal -packages, or speculative package trees. The root package alone is the correct -foundation state. - -### Promptkit License Hygiene - -Preserve `LICENSE` as GPLv3 and preserve its existing copyright attribution and -license text. Replace the template project name in both GPL example notices -with `Promptkit`. Do not use this stage to relicense Promptkit, add a second -license, or alter GPLv3 wording outside those project-name examples. - -Review `.gitignore` and retain coverage for Go build and test output, editor and -operating-system files, `.env`, `go.work`, and `go.work.sum`. Change it only if -one of those required rules is missing; do not add broad rules that could hide -source or documentation. - -### Stage 2 Validation - -From the Promptkit repository: - -1. Run `go mod tidy` and confirm it does not introduce unnecessary - dependencies or a spurious `go.sum`. -2. Run: - - ```sh - go test ./... - go vet ./... - go build ./... - ``` - -3. Confirm module metadata: - - ```sh - go list -m -f '{{.Path}} {{.GoVersion}}' - go list -f '{{.Name}} {{.ImportPath}}' . - ``` - - The results must identify module - `gitea.maximumdirect.net/eric/promptkit`, Go `1.25.5`, package `promptkit`, - and the matching root import path. -4. Run `gofmt -l` over all tracked Go files and confirm it produces no output. -5. Search `LICENSE` for `go-application-template` and confirm no matches. -6. Confirm `.gitignore` covers every required repository-local artifact without - hiding maintained source. -7. Confirm no `go.work`, local `replace` directive, CI configuration, command - package, or placeholder package was added. -8. Run `git diff --check`. - -### Stage 2 Completion Gate - -Proceed only when Promptkit builds as an independent, dependency-free root Go -package and its retained GPLv3 license notices identify the correct project. - -## Stage 3: Replace Promptkit's Template Policies and Architecture Guide - -### Objective - -Replace inherited application-template guidance with durable policies that -accurately govern a reusable Go library and its manual validation model. - -### Documentation Policy - -Rewrite `docs/policy/documentation.md` for Promptkit while retaining the useful -principles established in the Scriptorium documentation policy. It must: - -- identify Promptkit as a reusable Go library, not an application; -- preserve the distinction between current-state documentation, accepted ADRs, - and temporary roadmaps; -- preserve the one-canonical-owner rule and require other documents to link to - the owner rather than duplicate exact contracts; -- assign canonical ownership for project orientation, contributor workflow, - architecture, testing, release procedure, public Go contracts, integrations, - internal subsystem detail, ADRs, and temporary feature roadmaps; -- state that Go declarations and GoDoc own exact exported API contracts once - APIs exist; -- use the ADR statuses Proposed, Accepted, Rejected, and Superseded; -- require a later ADR for changed accepted decisions rather than rewriting - accepted decision content; -- retain link, example, code-fence, and document-lifecycle expectations; and -- avoid claiming that absent consumer, integration, or subsystem documents - already exist. - -State ownership rules for future document categories conditionally rather than -creating placeholder documents. - -### Architecture Policy - -Rewrite `docs/policy/architecture.md` as Promptkit's canonical current-state -architecture policy. It must define: - -- Promptkit as an importable Go library with no runnable command or HTTP - service; -- the root `promptkit` package as the public facade and only implemented package - at the Step 5 foundation state; -- the intended dependency direction: public facade to internal framework - components, with internal components depending on narrow abstractions rather - than on consumers or Scriptorium; -- Scriptorium as a downstream application boundary, not an internal Promptkit - package; -- package ownership, exported-API discipline, error-boundary expectations, and - dependency-injection principles that future extraction work must preserve; -- the rule that implementation packages remain internal unless a stable public - contract requires otherwise; -- no committed workspace coupling or local module replacement; -- no binary, CLI, HTTP-server, deployment, or application-configuration - ownership in Promptkit; and -- the relationship between this high-level policy and - `docs/internal/overview.md`. - -Describe future package boundaries as constraints on Step 6, not as current -implemented components. - -### Testing Policy - -Revise `docs/policy/testing.md` only as needed to make it accurate for -Promptkit. Preserve its deterministic, offline, behavior-focused standards. -Specifically: - -- describe the subject as a library or project rather than an application; -- make required maintainer-run checks the active validation model; -- remove language that represents hosted CI as an existing workflow; -- retain requirements that tests be deterministic, parallel-safe, and free of - live network dependencies; -- retain appropriate guidance for unit, integration, contract, fixture, - golden-file, and failure-path tests; and -- phrase golden-file safeguards in terms of validation runs rather than a CI - system that does not exist. - -The policy may permit future hosted CI, but must not require or document it as -current state. - -### Internal Architecture Inventory - -Create `docs/internal/overview.md` as the current component inventory. It must: - -- identify the root `promptkit` package as the sole implemented Go package; -- describe its present role without claiming migrated framework behavior; -- state that no internal framework packages exist yet; -- link to the architecture policy for durable boundary rules; -- link to `docs/development.md` for contributor workflow; and -- state that the inventory must be updated as Step 6 introduces components. - -Do not include aspirational packages in the implemented-component table. - -### Stage 3 Validation - -From the Promptkit repository: - -1. Check every Markdown link added or changed in this stage. -2. Search policy and internal documentation for stale template terms, - misspellings, Scriptorium application commands, and unsupported current - claims. At minimum inspect matches from: - - ```sh - rg -n -i 'go-application-template|cmd/scriptorium|thsi|thos|todo|hosted ci|application' docs - ``` - - Review legitimate contextual uses rather than deleting them mechanically. -3. Confirm the documentation policy names all four permitted ADR statuses. -4. Confirm the architecture policy and internal overview agree that the root - package is the only implemented component. -5. Confirm no roadmap detail or future API specification was copied into a - permanent current-state document. -6. Run `git diff --check`. - -### Stage 3 Completion Gate - -Proceed only when Promptkit's permanent policy and architecture documents are -self-consistent, library-specific, accurate for the foundation state, and free -of claims that hosted CI or migrated framework packages already exist. - -## Stage 4: Complete Promptkit Orientation, Development, and Release Guidance - -### Objective - -Give maintainers and prospective consumers an accurate repository entry point, -a usable local workflow, and a complete manual release procedure. - -### Repository README - -Rewrite `README.md` as a concise Promptkit orientation document. It must: - -- identify Promptkit as the reusable Go framework being separated from - Scriptorium; -- show module path `gitea.maximumdirect.net/eric/promptkit`; -- state that Step 5 establishes the repository foundation and framework APIs - have not yet been extracted; -- avoid speculative install or usage examples; -- link to `docs/development.md` and `docs/policy/architecture.md`; and -- identify GPLv3 as the current license. - -Do not make the README depend on a temporary Scriptorium roadmap for basic -orientation. - -### Contributor Guide - -Rewrite `docs/development.md` as Promptkit's contributor entry point. It must: - -- direct all contributors to read `docs/policy/architecture.md`; -- retain a task-specific reading guide for documentation, tests, public API, - internal packages, integrations, and releases; -- link only to documents that exist, using conditional instructions for - subsystem documents introduced later; -- list the default validation sequence: - - ```sh - go test ./... - go vet ./... - go build ./... - ``` - -- require tracked-Go-file formatting checks, Markdown-link validation, and - `git diff --check`; -- describe test filtering and targeted package validation without referring to - nonexistent packages; -- explain that Promptkit has no hosted CI and maintainers run the checks; -- explain temporary sibling integration through a local Go workspace or an - uncommitted `replace` directive; and -- prohibit committing `go.work`, `go.work.sum`, or local `replace` directives. - -The workspace example must use repository-relative or clearly illustrative -paths, explain its working directory and cleanup, and avoid the maintainer's -absolute filesystem path. - -Keep `AGENTS.md` as the short route to `docs/development.md`; update it only if -its link or wording is inaccurate. - -### Release Procedure - -Create `docs/release.md` as the canonical Promptkit release procedure. It must: - -- state that Promptkit publishes a Go library through source commits and - semantic version tags; -- state that it publishes no binaries and currently uses no hosted CI; -- require a clean checkout and working tree; -- require the complete documented local validation suite before tagging; -- include review of module path, Go version, links, formatting, repository - hygiene, and absence of committed workspace overrides; -- describe annotated semantic-version tag creation and publication without a - hosting-provider-specific release UI; -- require the annotated tag message to identify the release and record that the - documented validation suite passed for the tagged commit; -- require post-push verification that the tag resolves to the intended commit; -- explain that the first `v0.1.0` tag is created only after Step 6 extraction - and validation; and -- require documentation before future changes to hosted automation, binary - artifacts, or release governance. - -Do not create a release tag while implementing Step 5. - -### Stage 4 Validation - -From the Promptkit repository: - -1. Follow every internal link in `README.md`, `AGENTS.md`, - `docs/development.md`, and `docs/release.md`. -2. Confirm documented commands work from their stated directories. -3. Confirm development and release guides use the same validation commands. -4. Search maintained documentation for stale template and Scriptorium - application commands, hosted-CI or binary claims, claims that framework APIs - exist, and absolute maintainer-specific paths. -5. Confirm no temporary workspace or replacement file was created or staged. -6. Run `git diff --check`. - -### Stage 4 Completion Gate - -Proceed only when a new contributor can orient, validate, and understand the -future release process using Promptkit's own maintained documentation, with no -dependency on hidden CI or unpublished framework APIs. - -## Stage 5: Perform Cross-Repository Acceptance and Close Step 5 - -### Objective - -Validate the foundation independently, verify both repositories tell the same -migration story, and update planning status only after all checks succeed. - -### Promptkit Acceptance Validation - -Start from Promptkit with no active parent or repository-local Go workspace and -no local module replacement. Run: +Complete as of 2026-07-28. + +This record summarizes the completed implementation of +[Migration Step 5: Promptkit Repository Foundation](step5.md). The +[main migration roadmap](migration.md) owns the continuing cross-repository +sequence. + +## Completed Work + +### Validation And Release Decision + +- Added accepted + [ADR 0003](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md) + for maintainer-run Promptkit validation and source-and-tag releases. +- Preserved accepted + [ADR 0002](../adr/0002-split-promptkit-from-scriptorium.md) and its repository + split, ownership, independent versioning, and release-order decisions. +- Reconciled the migration roadmap so Promptkit validation no longer depends on + hosted CI or binary packaging. + +### Promptkit Module And License + +- Created module `gitea.maximumdirect.net/eric/promptkit` at Go `1.25.5`. +- Added the root `promptkit` package as the only implemented Go package. +- Kept the module dependency-free and added no placeholder implementation. +- Preserved GPLv3 wording and attribution while changing the two template + example-notice project names to `Promptkit`. +- Confirmed the existing ignore rules cover Go output, editor and operating + system artifacts, `.env`, `go.work`, and `go.work.sum`. + +### Policies And Architecture + +- Replaced template documentation and architecture material with durable + library-specific policies. +- Assigned canonical documentation ownership, including conditional ownership + for public contracts, integrations, internal subsystems, ADRs, roadmaps, and + examples that may exist later. +- Defined the root facade, internal-package direction, consumer boundary, + exported-API discipline, error boundary, dependency injection, and repository + independence constraints for future extraction. +- Updated testing policy for deterministic, offline, parallel-safe, + behavior-focused, maintainer-run validation. +- Recorded the root package as the sole implemented component. + +### Orientation, Development, And Releases + +- Rewrote the Promptkit README without claiming unimplemented APIs. +- Replaced the contributor guide with task routing, complete local validation, + focused checks, and safe sibling-repository workflows. +- Added the canonical release procedure for annotated semantic Go module tags, + validation evidence, publication verification, and consumer release ordering. +- Added no hosted CI, binary packaging, executable command, or release tag. + +### Cross-Repository Acceptance + +Promptkit passed, without an active workspace or local replacement: ```sh go test ./... @@ -426,71 +67,24 @@ gofmt -l $(git ls-files '*.go') git diff --check ``` -The formatting command must produce no output. Also: +Acceptance also verified exact module and package metadata, all maintained +Markdown links, clean repository hygiene, the Promptkit origin and tracked +default branch, the absence of dependencies and prohibited artifacts, and the +retained GPLv3 license. -1. Use `go list -m -f '{{.Path}} {{.GoVersion}}'` to confirm the exact module - path and Go version. -2. Use `go list -f '{{.Name}} {{.ImportPath}}' .` to confirm the root package. -3. Confirm `go.mod` has no `replace` and no unnecessary dependency. -4. Confirm no `go.work`, `go.work.sum`, CI configuration, command, release - artifact, version tag, or placeholder package was added. -5. Use `git remote get-url origin` to confirm the origin belongs to Promptkit, - not Scriptorium. -6. Use `git branch -vv` and - `git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}'` to confirm - the current default branch tracks the intended Promptkit remote branch. -7. Check every maintained Markdown link. -8. Search the repository for stale template naming and investigate each match. -9. Confirm `LICENSE` remains GPLv3 with Promptkit-specific notices and unchanged - attribution. +Scriptorium acceptance confirmed that ADR 0003 and the migration roadmap +distinguish Scriptorium's executable CI policy from Promptkit's maintainer-run +checks, preserve the first-tag release gate, and introduce no production code, +module dependency, workspace, or replacement change. -If a check fails, correct the owning stage and repeat the complete suite. +## Repository Boundaries -### Scriptorium Acceptance Validation +Promptkit foundation changes remain in Promptkit's Git history. Scriptorium +contains only the durable cross-project ADR and migration-roadmap records. No +tag was created and neither repository was pushed as part of this work. -From Scriptorium: +## Next Work -1. Confirm the new ADR and `docs/roadmap/migration.md` distinguish - Scriptorium's CI from Promptkit's maintainer-run checks. -2. Confirm Step 6 still requires Promptkit validation and its first release tag - before Scriptorium changes its dependency. -3. Check every changed Markdown link. -4. Run `git diff --check`. -5. Confirm no Scriptorium production code, module dependency, workspace file, - or local replacement changed during Step 5. - -### Planning-State Updates - -Only after both acceptance suites pass: - -- change `docs/roadmap/step5.md` from Accepted scope to Complete and replace its - future-oriented lifecycle text with a concise completion record; -- update `docs/roadmap/migration.md` to mark Step 5 complete, record successful - maintainer-run validation, and identify Step 6 as the next gate; and -- revise this file so completed stages appear as a concise `Completed Work` - summary rather than an active execution checklist. - -Do not delete the Step 5 roadmap while its completion record remains useful, -and do not create a Step 6 roadmap incidentally. - -### Repository and Publication Boundaries - -Before handoff: - -- keep Promptkit changes in the Promptkit repository only; -- keep the ADR and migration-roadmap changes in Scriptorium only; -- review each repository's diff independently; and -- do not publish a Promptkit tag or push either repository unless separately - requested. - -### Stage 5 Completion Gate - -Step 5 is complete only when every feature-roadmap criterion is satisfied, both -repositories are internally coherent, all checks pass without workspace -overrides, and the Scriptorium roadmap records Step 6 as the next authorized -work. - -## Open Questions - -None. The Step 5 roadmap and confirmed governance, validation, and licensing -choices are sufficient to implement this plan without further design decisions. +Migration Step 6 may now extract and stabilize the application-neutral +framework. It must not update Scriptorium to consume Promptkit until Promptkit +passes its documented validation and publishes its first versioned tag. diff --git a/docs/roadmap/migration.md b/docs/roadmap/migration.md index ad79a5f..3e877ee 100644 --- a/docs/roadmap/migration.md +++ b/docs/roadmap/migration.md @@ -2,7 +2,7 @@ ## Status -Accepted plan. Steps 1 through 4 are complete. Steps 5 through 9 remain +Accepted plan. Steps 1 through 5 are complete. Steps 6 through 9 remain proposed and are not yet implemented. ## Objective @@ -182,33 +182,31 @@ creation is next. ### Step 5: Create The Promptkit Repository -Create the Promptkit repository and Go module as an explicit out-of-band -operation. +Promptkit was established as an independent repository and Go module through +the out-of-band workflow recorded in the +[Step 5 completion record](step5.md). Its foundation includes: -Establish: - -- repository access, ownership, and branch protections; -- the module path selected by the ADR; -- baseline development, architecture, documentation, and release policies; +- 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; -- 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 - changes, using a workspace or temporary uncommitted module replacement where - appropriate. +- 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. -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 -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. +**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. Framework extraction and stabilization in +Step 6 is the next gate. ### Step 6: Extract And Stabilize Promptkit diff --git a/docs/roadmap/step5.md b/docs/roadmap/step5.md index 3dc1e1f..d389ddf 100644 --- a/docs/roadmap/step5.md +++ b/docs/roadmap/step5.md @@ -2,252 +2,63 @@ ## Status -Accepted scope. The Promptkit repository exists and its governance has been -confirmed, but the repository foundation is not complete until the target state -and completion criteria below are satisfied. +Complete as of 2026-07-28. ## Purpose -Establish Promptkit as an independent, maintainable Go library repository that -is ready to receive the framework extraction in Migration Step 6. +Establish Promptkit as an independent, maintainable Go library repository ready +to receive framework extraction in Migration Step 6 without moving framework +behavior prematurely. -This step creates the repository and its durable project scaffolding; it does -not extract framework behavior. The -[main migration roadmap](migration.md) owns the overall sequence, and -[ADR 0002](../adr/0002-split-promptkit-from-scriptorium.md) owns the selected -project boundary, module path, versioning direction, and cross-repository -ownership decisions. +The [main migration roadmap](migration.md) owns the overall sequence. +[ADR 0002](../adr/0002-split-promptkit-from-scriptorium.md) owns the repository +boundary, module path, versioning direction, and cross-repository ordering. +[ADR 0003](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md) +owns the maintainer-run validation and tag-only release decision. -## Confirmed Decisions +## Completed Work -- The repository is named `promptkit`, is accessible at its configured origin, - and has the intended maintainer governance and branch protections. No further - governance work is required for Step 5. -- Promptkit is a Go library and will not publish executable binaries. -- Promptkit will not use a hosted CI integration at this stage. Maintainers will - run and record the repository's required validation before merging and - tagging. -- Promptkit will remain licensed under GPLv3 for now. A future license change is - a separate legal and project decision. -- The first Promptkit release remains planned as `v0.1.0`, but creating that tag - belongs to Step 6 after the framework is extracted and validated. +### Repository And Module Foundation -## Target Repository State +- Confirmed the Promptkit repository, maintainer governance, configured origin, + and `main` tracking of `origin/main`. +- Created dependency-free module + `gitea.maximumdirect.net/eric/promptkit` with Go `1.25.5`. +- Added the root `promptkit` package as the sole implemented Go package and + public package boundary. +- Added no framework implementation, exported API, internal package, + speculative package tree, command, workspace file, or local replacement. +- Retained GPLv3 and changed only the two template project names in its example + notices to `Promptkit`. -Promptkit is a valid standalone Go module with a minimal public package and -project-specific repository guidance. A fresh checkout can be understood, -validated, and used for coordinated local extraction work without relying on -undocumented Scriptorium knowledge or committed machine-local configuration. +### Durable Repository Guidance -The repository remains intentionally small: +- Replaced application-template architecture, documentation, and testing + policies with library-specific policies. +- Recorded the root package as the only implemented component and kept future + framework boundaries explicitly unimplemented. +- Rewrote repository orientation and contributor workflow for the Promptkit + module. +- Documented deterministic, offline, parallel-safe, maintainer-run validation. +- Documented temporary sibling workspace and uncommitted replacement workflows + without committing machine-local coupling. +- Added a semantic Go module tag release procedure with no runnable binaries or + hosted CI. -```text -promptkit/ -├── go.mod -├── doc.go -├── README.md -├── LICENSE -├── AGENTS.md -└── docs/ - ├── development.md - ├── release.md - ├── internal/ - │ └── overview.md - └── policy/ - ├── architecture.md - ├── documentation.md - └── testing.md -``` +### Decision Reconciliation -Additional files are appropriate only when they describe or validate the -implemented repository foundation. Do not create empty `internal/`, `examples/`, -consumer, integration, or ADR directories merely to reserve future structure. +- Accepted ADR 0003 as the later controlling decision for Promptkit validation + while leaving ADR 0002 Accepted and its repository-split decision unchanged. +- Reconciled the main migration roadmap with maintainer-run validation, + tag-only releases, and the requirement that Promptkit publish its first + versioned tag before Scriptorium adopts it. -## Go Module And Package Foundation +## Acceptance Record -The repository will define: +From a clean Promptkit checkout with no active Go workspace or local +replacement, the maintainer successfully ran: -- module path `gitea.maximumdirect.net/eric/promptkit`; -- Go version `1.25.5`, matching Scriptorium during the extraction; -- a root package named `promptkit`; and -- no external dependencies until implemented code requires them. - -The root `doc.go` will contain an accurate package comment and package -declaration. It establishes the public package boundary but must not claim that -the future engine, profiles, loaders, clients, or validation features have -already been extracted. - -Promptkit implementation will live under `internal/` once Step 6 moves real -implementation packages. No placeholder public subpackages or empty internal -packages are needed in Step 5. The supported public facade will remain centered -at the module root as required by ADR 0002. - -The foundation must support: - -```bash -go test ./... -go vet ./... -go build ./... -``` - -These commands validate packages only; they do not build or package a binary. - -## Architecture And Dependency Policy - -Promptkit's architecture policy will describe the implemented Step 5 shape and -the boundaries that later extraction must preserve: - -- the module root is the supported public facade; -- implementation packages belong under `internal/`; -- consumer extension points become public only when a demonstrated consumer - requires them; -- Promptkit owns application-neutral prompt-execution behavior; -- CLI, HTTP, process, deployment, and executable-release concerns do not belong - in Promptkit; and -- future package movement must follow the ownership recorded by ADR 0002. - -The architecture document must distinguish the implemented empty foundation -from the accepted future extraction. Detailed future package and feature claims -remain in Scriptorium's migration roadmap until they are implemented. - -The internal overview will inventory only implemented components. At Step 5 -completion it will identify the root package and repository guidance; it will -not contain template tables or describe uncreated framework packages. - -## Documentation And Contributor Foundation - -Promptkit's repository documentation will be rewritten for a reusable Go -library rather than copied from an executable application template. - -### README - -The README will: - -- identify Promptkit and its module path; -- explain that the repository foundation exists but framework extraction is - still pending; -- avoid presenting unimplemented APIs as available; -- point contributors to `docs/development.md`; and -- state the GPLv3 license without providing legal interpretation. - -A consumer quickstart is not required until Step 6 provides a usable public -API. - -### Contributor Guide - -`docs/development.md` will: - -- describe Promptkit as a library; -- provide a task-specific reading guide for the current repository; -- use `go test ./...`, `go vet ./...`, and `go build ./...` as the baseline; -- remove Scriptorium command and executable references; and -- document coordinated local work with Scriptorium. - -The coordinated workflow will permit either: - -- a temporary Go workspace containing the sibling Promptkit and Scriptorium - modules; or -- an uncommitted local `replace` directive in the consuming module. - -The guide must not hard-code a maintainer's absolute filesystem path. -`go.work`, `go.work.sum`, and local filesystem `replace` directives must not be -committed. Each repository must remain independently valid outside the shared -workspace. - -### Documentation Policy - -The documentation policy will be tailored to a library: - -- remove template typos and executable-only ownership categories that do not - apply; -- assign canonical ownership for the README, public Go consumer contract, - contributor guide, architecture, testing, releases, internal components, - integrations, ADRs, roadmaps, and maintained examples when those materials - exist; -- retain the current-versus-future behavior rule; -- retain the security, privacy, example, and canonical-owner rules; and -- use the same enumerated ADR statuses and immutable accepted-decision policy - established in Scriptorium. - -Promptkit does not need repository-local ADRs at Step 5. Remove links to a -nonexistent ADR directory; create that directory only when Promptkit has a -repository-local architectural decision to record. Cross-project migration -decisions remain owned by Scriptorium. - -### Testing Policy - -The existing risk-based testing philosophy may remain, but it must consistently -refer to Promptkit as a library or project rather than a generic application. -Its default suite must be offline, deterministic, credential-free, and runnable -manually from a fresh checkout. - -## Manual Validation And Release Policy - -Promptkit will use maintainer-run validation instead of hosted CI. This is an -intentional policy choice, not a temporary missing integration. - -`docs/release.md` will be the canonical Promptkit release guide. It will state: - -- releases are Go module tags and do not contain binary artifacts; -- semantic-versioning begins with the planned `v0.1.0`; -- the release maintainer must run the documented full test, vet, build, - formatting, link, and whitespace checks before tagging; -- the repository and module must be clean and independently valid without a - local workspace or replacement; -- Promptkit must be tagged before Scriptorium or another consumer publishes a - release depending on that version; -- released consumer modules must use a tagged Promptkit version rather than a - local replacement or unpublished revision; and -- release notes should identify intentional public API changes while Promptkit - remains pre-`v1`. - -Step 5 establishes this policy but does not create `v0.1.0`. Step 6 owns the -first releasable framework version and its tag. - -No CI configuration, CI badge, executable packaging, or binary release -workflow is required. - -## Decision-Record Reconciliation - -The no-CI decision changes the automation assumption recorded in accepted ADR -0002 and in the main migration roadmap. Accepted ADR decision text remains -unchanged. - -At completion, the controlling records have this state: - -- A later accepted Scriptorium ADR records maintainer-run Promptkit validation - and tag-only library releases in place of hosted Promptkit CI and binary - packaging. -- That decision links to ADR 0002 as a refinement of its validation and - release-coordination provisions without changing the accepted project split. -- The Step 5 and later affected gates in `migration.md` require the documented - manual validation rather than CI. -- The repository boundary, module path, ownership, versioning, tagging order, - and no-committed-replacement decisions from ADR 0002 remain unchanged. - -The new ADR records the durable policy decision. This roadmap continues to own -implementation status and completion. - -## License And Repository Hygiene - -Promptkit retains the existing GPLv3 license text. The example notices at the -end of `LICENSE` name `Promptkit` rather than `go-application-template`. The -license version and existing copyright attribution remain unchanged. - -Repository hygiene will retain: - -- ignore rules for Go build/test outputs, editor and operating-system files, - `.env`, `go.work`, and `go.work.sum`; -- no committed credentials, private data, generated binaries, coverage output, - workspace files, or local replacements; -- no dependency changes unsupported by implemented code; and -- clean Markdown links and whitespace. - -## Required Validation Outcome - -From a clean Promptkit checkout, maintainers must successfully run: - -```bash +```sh go test ./... go vet ./... go build ./... @@ -255,72 +66,29 @@ gofmt -l $(git ls-files '*.go') git diff --check ``` -The `gofmt` command must produce no Go source paths. Maintainers must also: +The formatting command produced no paths. Acceptance also confirmed: -- validate all local Markdown links; -- confirm the module path, root package name, and Go version; -- confirm the repository contains no `go.work`, `go.work.sum`, or local - `replace` directive; -- confirm the origin and tracked default branch are correct; -- inspect the final file inventory for template residue and unsupported future - claims; and -- record the successful manual validation in the Step 5 completion update. +- module path `gitea.maximumdirect.net/eric/promptkit`, Go `1.25.5`, root + package `promptkit`, and matching import path; +- no external dependency, `go.sum`, `go.work`, `go.work.sum`, or `replace` + directive; +- no hosted CI configuration, command package, release artifact, version tag, + or placeholder framework package; +- every maintained Markdown link resolves; +- repository orientation, policies, inventory, contributor workflow, and + release procedure are internally consistent and free of template residue; +- the configured origin belongs to Promptkit and `main` tracks `origin/main`; +- GPLv3 wording and attribution remain unchanged apart from the two approved + Promptkit example-notice names; and +- Scriptorium contains only the decision and roadmap documentation required for + this foundation work, with no production code or module dependency change. -The Scriptorium repository requires documentation validation for the new ADR, -this feature roadmap, and the reconciled main migration roadmap. No Scriptorium -code change or full executable test suite is required solely for the Promptkit -foundation, unless implementation work unexpectedly changes Scriptorium code -or maintained examples. +## Scope Boundary And Next Gate -## Out Of Scope +No framework implementation or public framework API was extracted, no consumer +was migrated, and no `v0.1.0` tag was created. Promptkit remains an independently +valid repository foundation. -Step 5 does not: - -- extract or copy framework implementation from Scriptorium; -- add Promptkit engine, request, result, profile, source, validation, artifact, - or model-client APIs; -- create placeholder internal packages or consumer examples; -- tag or publish `v0.1.0`; -- update Scriptorium to import Promptkit; -- migrate downstream consumers; -- add CI integration or release binaries; -- reconsider GPLv3 beyond removing the template project name; or -- change the accepted Promptkit/Scriptorium ownership boundary. - -Those changes belong to Steps 6 through 8 or to a separately accepted decision. - -## Completion Criteria - -Step 5 is complete when: - -- the confirmed Promptkit governance remains in place and its origin and - tracked default branch are correct; -- Promptkit is a standalone module at - `gitea.maximumdirect.net/eric/promptkit` with Go `1.25.5` and a minimal root - `promptkit` package; -- repository documentation and policies are Promptkit-specific, internally - consistent, free of template residue, and accurate for the implemented - foundation; -- architecture and internal inventory clearly distinguish the current - foundation from the future framework extraction; -- contributor guidance documents the manual validation and safe - cross-repository development workflow; -- the tag-only, no-binary release policy and pre-`v1` coordination rules are - documented; -- the no-CI decision is recorded in a new accepted ADR and reconciled with the - main migration roadmap; -- GPLv3 remains in place with corrected Promptkit example notices; -- Promptkit passes every required manual validation check independently of - Scriptorium and without a workspace or local replacement; -- no framework extraction, consumer migration, tag, compatibility layer, or - unrelated work is included; and -- `migration.md` records Step 5 as complete and identifies framework extraction - and stabilization in Step 6 as the next gate. - -Migration Step 6 must not begin until these criteria are satisfied. - -## Lifecycle - -This feature roadmap is a temporary migration artifact. It may be removed after -Step 5 is complete and no longer needs to guide active work; repository history -will retain the accepted scope and completion record. +Migration Step 6 is now authorized to extract and stabilize the framework. It +must pass Promptkit's documented validation and publish the first versioned tag +before Scriptorium or another consumer adopts the module.