From 8d8cdbf3c5f3d2e4896ece27deefb21a6fa87242 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 31 Jul 2026 17:27:04 +0000 Subject: [PATCH] Finalize Promptkit migration documentation --- docs/roadmap/implementation.md | 55 +++++++++++++++------ docs/roadmap/promptkit.md | 87 +++++++++++++++++----------------- 2 files changed, 84 insertions(+), 58 deletions(-) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 21eac71..f27fa13 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,21 +1,19 @@ # Promptkit Migration Implementation Plan -Status: Stages 1–11 completed; audit remediation in Stages 12–19 remains. +Status: Completed; Stages 1–19 passed their exit gates. ## Purpose And Authority This document records the completed implementation of the -[Promptkit migration roadmap](promptkit.md) and defines the ordered follow-up -work required by the post-implementation audit. The feature roadmap remains -authoritative for scope, user intent, policy choices, and the desired end -state. This plan is authoritative for implementation sequence, tests, and -completion gates. +[Promptkit migration roadmap](promptkit.md) and its post-implementation audit +remediation. The feature roadmap records scope, user intent, policy choices, +and the implemented end state. This plan records implementation sequence, +tests, and completion gates. -Follow Stages 12–19 in order, using one implementation prompt per stage. A -stage may fix additional defects exposed by its required tests when those -defects are within the same stated contract. Do not expand a stage into new -product behavior or reinterpret a roadmap decision to accommodate the current -implementation. +Stages 12–19 were completed in order. They fixed additional defects exposed by +their required tests only when those defects were within the same stated +contract; they did not add new product behavior or reinterpret roadmap +decisions. This plan follows the repository's [architecture](../policy/architecture.md), @@ -71,11 +69,24 @@ The post-implementation audit confirmed the principal dependency and package boundaries, but found incorrect reached-path bookkeeping, incomplete execution artifact updates, insufficient artifact validation, extensive loss of behavioral tests during the final cutover, and roadmap lifecycle text that was -not finalized. The remaining stages address those findings without changing -the intended feature scope. +not finalized. The completed remediation addressed those findings without +changing the intended feature scope. + +| Stage | Completed outcome | +| --- | --- | +| 12 | Corrected reached-path bookkeeping across metadata, app results, batch items, and CLI summaries. | +| 13 | Hardened Promptkit-era durable state validation and restored v1/v2 state coverage. | +| 14 | Recorded every downstream path reached after completed prompt execution. | +| 15 | Restored assembled single-report behavioral and failure coverage. | +| 16 | Simplified prompt-generation orchestration while preserving behavior. | +| 17 | Restored assembled batch, planning, artifact, and notification coverage. | +| 18 | Restored supported CLI, summary, safety, and historical inspection coverage. | +| 19 | Reconciled canonical documentation and passed the complete repository verification gate. | ## Stage 12: Correct Reached-Artifact Bookkeeping +Status: Completed. + ### Goal Make metadata, app results, batch items, and CLI summaries truthful at every @@ -138,6 +149,8 @@ result. ## Stage 13: Harden Durable State Contracts And Restore State Coverage +Status: Completed. + ### Goal Make the v1/v2 wire boundary and Promptkit-era artifact validation explicit, @@ -206,6 +219,8 @@ offline coverage for its durable compatibility and filesystem contracts. ## Stage 14: Complete Execution-Artifact Path Tracking +Status: Completed. + ### Goal Make `PromptExecutionArtifact.Paths` accurately record every downstream @@ -267,6 +282,8 @@ when a later application stage fails. ## Stage 15: Restore Single-Report Behavioral Coverage +Status: Completed. + ### Goal Restore the risk-based application coverage removed during final cutover and @@ -325,6 +342,8 @@ debug isolation, output copying, and notification behavior. ## Stage 16: Refactor Prompt Generation Orchestration +Status: Completed. + ### Goal Reduce the complexity and duplicated persistence logic in @@ -374,6 +393,8 @@ and every Stage 12–15 behavioral test passes unchanged. ## Stage 17: Restore Batch Behavioral Coverage +Status: Completed. + ### Goal Re-establish confidence that morning and evening batches preserve their @@ -421,6 +442,8 @@ artifact, and notification contracts with one Promptkit executor. ## Stage 18: Restore CLI And Inspection Coverage +Status: Completed. + ### Goal Restore the user-facing command, summary, and historical inspection contracts @@ -464,6 +487,8 @@ composition, and v1/v2 inspection behavior have deterministic offline coverage. ## Stage 19: Finalize Documentation And Repository Verification +Status: Completed. + ### Goal Close the audit remediation, make roadmap lifecycle state truthful, and verify @@ -526,5 +551,5 @@ documents are marked complete. ## Open Questions -None. The roadmap and this follow-up plan contain the decisions required to -complete the audit remediation. +None. The roadmap and this completed plan record the decisions used for the +audit remediation. diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index ce28936..66a45b5 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -1,39 +1,40 @@ # Promptkit Migration Roadmap -Status: Accepted feature roadmap; the target state is unimplemented. +Status: Completed roadmap record. ## Purpose -This roadmap defines the scope and desired end state for replacing the -external Scriptorium CLI integration with Promptkit. Current implemented -behavior remains documented outside `docs/roadmap/` until the replacement is -complete. +This roadmap records the scope, decisions, and completed outcome of replacing +the external Scriptorium CLI integration with Promptkit. Canonical +documentation outside `docs/roadmap/` owns the implemented behavior. -## Current Baseline +## Pre-Migration Baseline -Status: Current migration input. +Status: Historical migration input. -Weatherreporter currently exposes seven report definitions, but only four have -complete prompt-backed report implementations: +Before the migration, Weatherreporter exposed seven report definitions, but +only four had complete prompt-backed report implementations: - Daily Report: `weather.daily_generated_text` - Today Report: `weather.today_generated_text` - Tomorrow Report: `weather.tomorrow_generated_text` - Hourly Report: `weather.hourly_generated_text` -The three-day, weekend, and storm commands and registry definitions have no +The three-day, weekend, and storm commands and registry definitions had no corresponding Scriptorium prompt or schema and never formed complete -operational report products. The `weather.daily_report` Scriptorium prompt is -legacy source material and is not selected by the current registry. +operational report products. The `weather.daily_report` Scriptorium prompt was +legacy source material and was not selected by the registry. -The available Scriptorium source corpus is retained temporarily under -`docs/roadmap/scriptorium/`. It contains the four operational generated-text -prompt definitions, their referenced content, their private response schemas, -shared instructions, and the unused legacy Daily Markdown prompt. +The Scriptorium source corpus was retained temporarily under +`docs/roadmap/scriptorium/` as migration input. It contained the four +operational generated-text prompt definitions, their referenced content, +private response schemas, shared instructions, and the unused legacy Daily +Markdown prompt. The temporary corpus was removed after the runtime assets +were reconciled and embedded. -## Desired End State +## Implemented End State -Status: Accepted target state; unimplemented. +Status: Completed. Weatherreporter pins `gitea.maximumdirect.net/eric/promptkit` at `v0.4.0` and uses it as the @@ -71,33 +72,33 @@ packages, CLI summaries, durable state contracts, or Distributor behavior. ## Goals -Status: Accepted migration scope; unimplemented. +Status: Completed migration outcomes. -- Remove the Scriptorium runtime dependency and subprocess boundary. -- Migrate the four operational report prompts to Promptkit `v0.4.0`. -- Use prepared execution to persist preparation provenance before provider work +- Removed the Scriptorium runtime dependency and subprocess boundary. +- Migrated the four operational report prompts to Promptkit `v0.4.0`. +- Used prepared execution to persist preparation provenance before provider work while executing the exact frozen snapshot. -- Validate report prompt and profile selections before weather collection when +- Validated report prompt and profile selections before weather collection when the required information is available. -- Preserve deterministic module snapshots and structured Recent Changes. -- Preserve generated-text domain validation and repository-owned Markdown +- Preserved deterministic module snapshots and structured Recent Changes. +- Preserved generated-text domain validation and repository-owned Markdown rendering. -- Preserve context cancellation, actionable errors, secret redaction, and +- Preserved context cancellation, actionable errors, secret redaction, and inspectable failures. -- Improve durable prompt provenance with prompt, input, profile, model, +- Improved durable prompt provenance with prompt, input, profile, model, validation, usage, and timing metadata. -- Keep content-rich prompt and response diagnostics separate from routine +- Kept content-rich prompt and response diagnostics separate from routine metadata and CLI output. -- Keep tests offline and deterministic through injected Promptkit model +- Kept tests offline and deterministic through injected Promptkit model clients and fixtures. -- Remove incomplete report declarations from the implemented product surface +- Removed incomplete report declarations from the implemented product surface rather than creating new report products during an integration migration. ## Non-Goals -Status: Accepted migration scope; unimplemented. +Status: Completed migration constraints. -The migration will not: +The completed migration did not: - create prompts, schemas, templates, or completed products for three-day, weekend, or storm reports; @@ -122,7 +123,7 @@ The migration will not: ## Locked Decisions -Status: Accepted decisions for the unimplemented migration. +Status: Implemented migration decisions. ### Dependency And Upgrade Boundary @@ -329,7 +330,7 @@ promptkit: ## Durable Artifacts And Observability -Status: Accepted design constraints; unimplemented. +Status: Implemented design constraints. Routine durable state retains useful non-secret provenance without persisting full rendered prompts. @@ -367,7 +368,7 @@ Rendered messages and other content-rich preparation or response diagnostics are available only when the operator supplies `--llm-debug-dir ` to a single-report or batch command. -- There is initially no persistent YAML setting for debug capture. +- There is no persistent YAML setting for debug capture. - The debug root is validated or created before weather collection or provider work. A requested destination that cannot be secured or written is an error. - Artifacts are grouped beneath @@ -411,7 +412,7 @@ dual-write deprecated aliases. CLI summary fields adopt `preparationPath` and ## Failure Contract -Status: Accepted design constraints; unimplemented. +Status: Implemented design constraints. - A preparation failure produces a redacted weatherreporter-owned failure receipt with report, RunID, prompt, stage, timing, and classified error @@ -441,7 +442,7 @@ Status: Accepted design constraints; unimplemented. ## Compatibility Requirements -Status: Accepted design constraints; unimplemented. +Status: Implemented design constraints. - Daily, Today, Tomorrow, and Hourly report IDs, prompt IDs, valid periods, artifact grouping, output names, and Distributor bundle behavior remain @@ -468,9 +469,9 @@ Status: Accepted design constraints; unimplemented. ## Verification And Completion Criteria -Status: Accepted completion criteria for the unimplemented migration. +Status: Completed and verified. -The migration is complete when: +Completion was verified by the following outcomes: - the four operational reports inspect, prepare, and execute through Promptkit `v0.4.0` using embedded report-owned assets; @@ -508,8 +509,8 @@ costly, and difficult to compare meaningfully. ## Decision Status -Status: Decision-complete. +Status: Completed. -The roadmap has no remaining open product or architecture questions. Any later -question that changes migration scope, policy, or the desired end state must be -resolved here rather than implicitly in code. +The roadmap has no remaining open product or architecture questions. Later +changes to this completed scope require new roadmap or decision-record scope +rather than implicit changes to this historical record.