Plan the Promptkit upgrade implementation

docs/roadmap/upgrade-kit.md

@@ -5,15 +5,16 @@
 Accepted feature direction, recorded on 2026-09-26; implementation is pending.
 Upgrade directly from Promptkit v0.9.0 to v0.11.0, including the intervening
 v0.10.0 catalog transition. This document defines the desired end state and
-the changes from the current baseline, not a staged coding-agent plan.
+the changes from the current baseline. The [implementation plan](implementation.md)
+owns sequencing, concrete interface choices, verification steps, and unresolved
+implementation decisions.
 
 The target is complete definition compatibility, controllable transient
 retries, an optional whole-run deadline, and modest opt-in execution diagnostics.
 This is a focused adapter and configuration update, not another architecture
-migration. Optional diagnostics are included in the desired feature set but
-need not block the core compatibility upgrade; they remain separately tracked
-until delivered. “Optional” means callers opt in, not that they appear in
-default output.
+migration. Optional diagnostics are included in the desired feature set.
+“Optional” means callers opt in, not that diagnostics may be silently omitted
+from the completed adoption or appear in default output.
 
 [ADR 0004](../adr/0004-definition-boundary.md) and the
 [architecture policy](../policy/architecture.md) govern scope. Promptkit remains
@@ -77,24 +78,18 @@ catalog entries can change or disappear across upgrades; inheriting from one
 does not create a frozen copy. Complete application-owned profiles remain the
 appropriate choice when an application owns its model and settings.
 
-### Required Changes
+### Change From Baseline
 
-- Update `go.mod` and `go.sum`, retaining tagged upstream dependencies and no
-  committed workspace, replacement, vendor tree, or direct catalog imports.
-- Replace the obsolete built-in inspection test and add focused coverage for
-  the maintained names, prompt/default selection, inheritance, and overrides.
-  Preserve existing definition conformance coverage rather than rebuilding
-  Promptkit's parser tests in Scriptorium.
-- Review maintained prompts, profile references, examples, and fixtures for
-  removed catalog IDs. The selected upstream catalog removes `deepseek-3-2`,
-  `deepseek-4-flash`, and `deepseek-4-pro`. Newer DeepSeek names are not automatic
-  compatibility aliases, and Scriptorium must not silently invent aliases.
-- Explain migration options: choose an available catalog profile, choose a
-  maintained Promptkit name, or supply a complete application-owned definition.
-  Keep the existing application-owned example profiles where fixed settings
-  are the instructional intent.
-- Audit dependency-boundary tests for the `/v2` module paths without allowing
-  direct catalog imports or duplicating catalog contents.
+The module graph and active definition fixtures reflect the released v0.11
+catalogs rather than v0.9's catalogs. The selected catalog removes
+`deepseek-3-2`, `deepseek-4-flash`, and `deepseek-4-pro`; newer DeepSeek names
+are not compatibility aliases. Migration guidance offers an available catalog
+profile, a maintained Promptkit name, or a complete application-owned definition.
+Application-owned examples retain fixed settings where that is their purpose.
+
+Definition conformance and focused resolution coverage protect Scriptorium's
+adapter boundary without duplicating the upstream parser or catalog. Existing
+dependency boundaries also apply to the new `/v2` module paths.
 
 ## Controllable Transient Retries
 
@@ -121,23 +116,16 @@ loop. Transient retries and structural repairs have distinct budgets: each
 generation, including each repair generation, receives its transient budget.
 Retries do not imply exactly-once generation or complete billing knowledge.
 
-### Required Changes
+### Change From Baseline
 
-- Extend strict application configuration and engine settings, mapping the
-  optional value to `promptkit.Config.TransientRetries` in shared engine
-  construction, including the server engine.
-- Add presence-aware CLI and HTTP request mapping to
-  `promptkit.RunRequest.TransientRetries`. Keep this an execution setting, not
-  a copied prompt/profile schema field or provider model parameter.
-- Validate malformed and negative values at the appropriate configuration or
-  request boundary, using Promptkit for framework semantics.
-- Update CLI, HTTP, configuration, operations, and migration guidance to make
-  the default change, cost/latency implications, zero override, and independent
-  repair budget explicit.
-- Protect inheritance and explicit-zero mapping with focused tests; include a
-  representative built-in HTTP retry path and verify that cancellation and
-  shared backend limits remain effective. Do not duplicate the entire upstream
-  status/backoff test matrix.
+Application settings reach `promptkit.Config.TransientRetries`, including the
+shared server engine, and request overrides reach
+`promptkit.RunRequest.TransientRetries`. This adds execution controls, not
+prompt/profile schema fields or provider model parameters. Strict decoding and
+presence-aware mapping preserve inheritance and explicit zero. User and
+operations guidance makes the changed default, latency/cost implications, and
+independent repair budget visible. Cancellation and shared backend limits
+remain effective during retrying executions.
 
 ## Optional Whole-Run Deadline
 
@@ -155,21 +143,15 @@ context from the caller's existing context, so a caller cancellation or earlier
 deadline still wins. This is a cancellation boundary, not a guarantee of
 instantaneous interruption of arbitrary callback or filesystem code.
 
-### Required Changes
+### Change From Baseline
 
-- Replace the CLI's unconditional background-context execution with a
-  context carrying the selected whole-run deadline when requested.
-- Apply an HTTP execution deadline as a child of the incoming request context,
-  retaining disconnect cancellation and existing server lifecycle behavior.
-- Keep total-run duration handling separate from per-attempt timeout conversion;
-  do not reuse names or fields that would reinterpret existing requests.
-- Document that provider retry timing can exceed local backoff limits and that
-  per-attempt timeouts do not cap the complete run.
-- Test deadline/cancellation propagation through a representative retry wait
-  and capacity wait, without adding another admission queue or retry engine.
-
-Exact option names, units, and zero-value semantics belong in the subsequent
-implementation plan and must be settled before coding this interface.
+CLI execution can carry a selected deadline instead of always using an
+unbounded background context. HTTP execution can shorten the incoming context
+without losing parent cancellation or changing server lifecycle behavior.
+Total-run duration handling is separate from existing attempt-timeout conversion.
+The interval covers the engine invocation, not adapter parsing, engine creation,
+or output writing. Provider retry timing can exceed local backoff limits;
+per-attempt timeouts do not cap that complete invocation.
 
 ## Opt-In Execution Reports
 
@@ -193,26 +175,17 @@ Existing successful-result usage semantics remain unchanged. A terminal total
 is an aggregate, not another attempt to add to the bill; no report is a billing
 ledger.
 
-### Required Changes
+### Change From Baseline
 
-- Add an opt-in reporting interface and explicit application-owned report DTOs.
-- Collect per-request observations without shared mutable report state, durable
-  storage, or blocking work inside synchronous callbacks. Shared operational
-  infrastructure, if used, must remain concurrency-safe.
-- Format a concise terminal report rather than introducing event streaming,
-  an event archive, or a general telemetry framework.
-- Define success and failure response/report handling without manufacturing a
-  partial `RunResult` when Promptkit returns an operational error.
-- Exclude prompt and response bodies, credentials, headers, endpoint URLs,
-  provider diagnostic text, and raw errors. Treat selected identifiers as
-  potentially sensitive even when the upstream event is content-free.
-- Test omission by default, success/failure reporting, unknown versus known-zero
-  usage, incomplete totals, no aggregate double counting, and concurrent-request
-  isolation at the adapter/report boundary.
+Both adapters have opt-in reporting and explicit application-owned report DTOs.
+Per-request collection adds no shared mutable report state, durable storage,
+callback I/O, or event archive. Operational failures can carry reports without
+manufacturing partial `RunResult` values. Default output remains unchanged.
 
-The report destination, wire fields, report-write failure handling, and precise
-scope of reported metadata remain implementation-plan decisions. Full event
-streaming and durable history are explicitly outside this feature.
+Reports exclude prompt and response bodies, credentials, headers, endpoint URLs,
+provider diagnostic text, and raw errors. Selected identifiers remain potentially
+sensitive even when observations are content-free. Reports are concise terminal
+metadata, not a general telemetry framework, event stream, or durable history.
 
 ## Errors And Compatibility
 
@@ -226,11 +199,11 @@ failure details in execution diagnostics, including actual attempts where
 available. Retry exhaustion and the final cause are distinct facts; do not lose
 the underlying failure category by flattening them into one label.
 
-Review mapping precedence and add representative wrapped-error tests while
-retaining existing capacity and validation behavior. Specify total-deadline
-outcomes in the implementation plan rather than accidentally treating every
-context error as an unclassified failure. No breaking replacement of existing
-error codes is required by this upgrade.
+Capacity and validation behavior remains intact. Whole-run deadline and caller
+cancellation outcomes are deliberate adapter classifications, distinct from a
+provider-attempt timeout while the caller context is still live. The implementation
+plan owns the exact presentation choices. Existing generation-error codes do
+not need a breaking replacement for this upgrade.
 
 ## Licensing And Distribution Review
 
@@ -253,18 +226,16 @@ approval gate for every future release.
 
 ## Documentation And Delivery
 
-Update current documentation to link to the selected v0.11.0 contracts when
-the implementation lands. CLI, HTTP, configuration, and operations documents
-own their respective new behavior; internal docs explain adapter mapping;
-release notes summarize compatibility impact. Preserve historical release notes
-and ADR decision content. Revise current examples and migration guidance where
-needed rather than globally replacing version strings in historical material.
+Current documentation links to the selected v0.11.0 contracts once implemented.
+CLI, HTTP, configuration, and operations documents own their respective new
+behavior; internal docs explain adapter mapping; release notes summarize
+compatibility impact. Historical release notes and ADR decision content remain
+unchanged. Current examples and migration guidance reflect the selected version.
 
-Deliver the upgrade as a minor Scriptorium release, not a compatibility patch.
-Prominently explain removed catalog profiles, changed retry behavior, the
-explicit single-attempt option, and timeout layering. Optional diagnostics may
-follow in a separate feature release without representing unfinished reports
-as already available.
+The upgrade merits a minor Scriptorium release, not a compatibility patch,
+with prominent migration guidance for removed profiles, changed retry behavior,
+the explicit single-attempt option, and timeout layering. Any later decision to
+defer part of the target leaves that feature visibly incomplete until delivered.
 
 Use the existing [release policy](../policy/release.md) and
 [runbook](../release.md). This roadmap authorizes no publication. No new ADR is
@@ -283,7 +254,7 @@ boundaries.
   per-attempt timeouts or disabling parent cancellation.
 - Opt-in terminal reports provide safe, isolated, presence-aware execution
   metadata without changing default output or creating durable workflow state.
-  If deferred to a follow-up release, this item remains visibly incomplete.
+  Any deferred reporting work remains visibly incomplete.
 - Existing error classifications remain compatible, with deliberate handling
   of the new public identities and context outcomes.
 - The licensing/distribution approach is resolved before upgraded binary
@@ -292,17 +263,7 @@ boundaries.
   implemented behavior. Relevant tests remain offline and credential-free,
   and normal development and release validation pass.
 
-## Decisions To Resolve In The Implementation Plan
-
-- Exact placement/naming of retry overrides and which preparation-only CLI
-  options should accept them for consistency without implying execution.
-- Whole-run deadline option names, units, zero handling, and external deadline
-  error presentation; omission must impose no new deadline.
-- Report destinations and opt-in request shape, report DTO fields, failure
-  reporting, and report-output error behavior; defaults must remain unchanged.
-- Whether reports ship with the core upgrade or in a clearly tracked follow-up.
-- The concrete licensing/distribution approach and any resulting packaging work.
-
-These are bounded interface and delivery decisions, not permission to expand
+Concrete interface decisions and the remaining distribution question are recorded
+in the [implementation plan](implementation.md). They do not expand the product
 into conversations, follow-up messages, application-owned semantic retry loops,
 prepared-handle coordination, or multi-step workflows.